From ce0b13a9b88ec01410fa725c1f2e3483319f979c Mon Sep 17 00:00:00 2001 From: Davide Mininni Date: Mon, 4 Dec 2023 10:46:46 +0100 Subject: [PATCH] docs: remove references to methods --- .../datepicker/datepicker/datepicker.ts | 31 +++++++------ .../datepicker/datepicker/readme.md | 24 +++++----- src/components/time-input/readme.md | 14 +++--- src/components/time-input/time-input.ts | 46 +++++++++++-------- 4 files changed, 62 insertions(+), 53 deletions(-) diff --git a/src/components/datepicker/datepicker/datepicker.ts b/src/components/datepicker/datepicker/datepicker.ts index 570b07f2055..f0177b1c03f 100644 --- a/src/components/datepicker/datepicker/datepicker.ts +++ b/src/components/datepicker/datepicker/datepicker.ts @@ -201,6 +201,23 @@ export class SbbDatepicker extends LitElement { /** Reference of the native input connected to the datepicker. */ @property() public input?: string | HTMLElement; + /** + * Formats the current input's value as date. + * TODO: in the readme.md, the `attribute: false` options is not evaluated. + * This will be fixed in issue #2246. + */ + @property({ attribute: false }) + public set valueAsDate(date: SbbDateLike) { + const parsedDate = date instanceof Date ? date : new Date(date); + this._formatAndUpdateValue(this._inputElement.value, parsedDate); + /* Emit blur event when value is changed programmatically to notify + frameworks that rely on that event to update form status. */ + this._inputElement.dispatchEvent(new Event('blur', { composed: true })); + } + public get valueAsDate(): Date | undefined { + return this._parse(this._inputElement?.value); + } + /** * @deprecated only used for React. Will probably be removed once React 19 is available. */ @@ -297,20 +314,6 @@ export class SbbDatepicker extends LitElement { } } - /** Gets the input value with the correct date format. */ - public get valueAsDate(): Date | undefined { - return this._parse(this._inputElement?.value); - } - - /** Set the input value to the correctly formatted value. */ - public set valueAsDate(date: SbbDateLike) { - const parsedDate = date instanceof Date ? date : new Date(date); - this._formatAndUpdateValue(this._inputElement.value, parsedDate); - /* Emit blur event when value is changed programmatically to notify - frameworks that rely on that event to update form status. */ - this._inputElement.dispatchEvent(new Event('blur', { composed: true })); - } - private _onInputPropertiesChange(mutationsList?: MutationRecord[]): void { this._inputUpdated.emit({ disabled: this._inputElement?.disabled, diff --git a/src/components/datepicker/datepicker/readme.md b/src/components/datepicker/datepicker/readme.md index 0756174e474..6b3ae3506ec 100644 --- a/src/components/datepicker/datepicker/readme.md +++ b/src/components/datepicker/datepicker/readme.md @@ -3,7 +3,7 @@ to display the typed value as a formatted date (default: `dd.MM.yyyy`). The component allows the insertion of up to 10 numbers, possibly with separators like `.`, `-`, ` `, `,` or `/`, then automatically formats the value as date and displays it. -It also exposes methods to get / set the value formatted as Date. +It also allows to get / set the value formatted as Date. The component and the native `input` can be connected using the `input` property, which accepts the id of the native input, or directly its reference. @@ -48,9 +48,9 @@ If the input's value changes, it is formatted then a `change` event is emitted w If it's an invalid date, the `data-sbb-invalid` attribute is added to the input. The component also listens for changes in its two properties, `wide` and `dateFilter`, and emits a `datePickerUpdated` event when changed. -Consumers can listen to the native `change` and `input` events on the `sbb-datepicker` component to intercept date changes, -the current value can be read from the async method `event.target.getValueAsDate()`. -To set the value programmatically, it's recommended to use the `setValueAsDate()` method of the `sbb-datepicker`. +Consumers can listen to the native `change` and `input` events on the `sbb-datepicker` component to intercept date changes. +The `valueAsDate` property on the `sbb-datepicker` can be used to read the current value +(e.g. from `event.target.valueAsDate`) or to set the value programmatically. Each time the user changes the date by using the calendar, or the next and previous day arrow, or by using the `setValueAsDate()` method, a `blur` event is fired on the input to ensure compatibility with any framework that relies on that event to update the current state. @@ -104,14 +104,14 @@ This is helpful if you need a specific state of the component. ## Properties -| Name | Attribute | Privacy | Type | Default | Description | -| ------------- | --------------- | ------- | --------------------------------------------------- | ------- | ----------------------------------------------------------------- | -| `wide` | `wide` | public | `boolean` | `false` | If set to true, two months are displayed. | -| `dateFilter` | `date-filter` | public | `(date: Date \| null) => boolean` | | A function used to filter out dates. | -| `dateParser` | `date-parser` | public | `(value: string) => Date \| undefined \| undefined` | | A function used to parse string value into dates. | -| `format` | `format` | public | `(date: Date) => string \| undefined` | | A function used to format dates into the preferred string format. | -| `input` | `input` | public | `string \| HTMLElement \| undefined` | | Reference of the native input connected to the datepicker. | -| `valueAsDate` | `value-as-date` | public | `Date \| undefined` | | Set the input value to the correctly formatted value. | +| Name | Attribute | Privacy | Type | Default | Description | +| ------------- | --------------- | ------- | --------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `wide` | `wide` | public | `boolean` | `false` | If set to true, two months are displayed. | +| `dateFilter` | `date-filter` | public | `(date: Date \| null) => boolean` | | A function used to filter out dates. | +| `dateParser` | `date-parser` | public | `(value: string) => Date \| undefined \| undefined` | | A function used to parse string value into dates. | +| `format` | `format` | public | `(date: Date) => string \| undefined` | | A function used to format dates into the preferred string format. | +| `input` | `input` | public | `string \| HTMLElement \| undefined` | | Reference of the native input connected to the datepicker. | +| `valueAsDate` | `value-as-date` | public | `Date \| undefined` | | Formats the current input's value as date. TODO: in the readme.md, the `attribute: false` options is not evaluated. This will be fixed in issue #2246. | ## Events diff --git a/src/components/time-input/readme.md b/src/components/time-input/readme.md index 62bf43b23cd..165d1f046b9 100644 --- a/src/components/time-input/readme.md +++ b/src/components/time-input/readme.md @@ -25,12 +25,12 @@ The initial value can be set using the `value` property (string) of the `input`o When the input changes, if it is valid, the component updates the `value` of the `input`. -To get the value as a `Date` object, the `getValueAsDate()` method of the `sbb-time-input` can be called. +To get the value as a `Date` object, the `valueAsDate` property can be used. The date is constructed like following: the start date is set to 01.01.1970, 00:00:00 UTC, then the typed hours and minuted are added, -e.g.: with a value of `12:34`, the `getValueAsDate()` will be 01.01.1970, 12:34:00 UTC. +e.g.: with a value of `12:34`, the `valueAsDate` will be 01.01.1970, 12:34:00 UTC. If the value is invalid because not real (e.g. 12:61 or 25:30), the component does not format the `value`, -and will return `null` if `getValueAsDate()` was called. +and `valueAsDate` will return `null`. ## Format example @@ -59,10 +59,10 @@ Whenever the validation state changes (e.g., a valid value becomes invalid or vi ## Properties -| Name | Attribute | Privacy | Type | Default | Description | -| ------------- | --------------- | ------- | ----------------------- | ------- | ---------------------------------------------------------- | -| `input` | `input` | public | `string \| HTMLElement` | | Reference of the native input connected to the datepicker. | -| `valueAsDate` | `value-as-date` | public | `Date \| null` | | | +| Name | Attribute | Privacy | Type | Default | Description | +| ------------- | --------------- | ------- | ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `input` | `input` | public | `string \| HTMLElement` | | Reference of the native input connected to the datepicker. | +| `valueAsDate` | `value-as-date` | public | `Date \| null` | | Formats the current input's value as date. TODO: in the readme.md, the `attribute: false` options is not evaluated. This will be fixed in issue #2246. | ## Events diff --git a/src/components/time-input/time-input.ts b/src/components/time-input/time-input.ts index 43d3b88b1cc..5bb2d8c4e0b 100644 --- a/src/components/time-input/time-input.ts +++ b/src/components/time-input/time-input.ts @@ -49,6 +49,31 @@ export class SbbTimeInput extends LitElement { } private _input: string | HTMLElement; + /** + * Formats the current input's value as date. + * TODO: in the readme.md, the `attribute: false` options is not evaluated. + * This will be fixed in issue #2246. + */ + @property({ attribute: false }) + public set valueAsDate(date: SbbDateLike) { + if (!date || !this._inputElement) { + return; + } + const dateObj = date instanceof Date ? date : new Date(date); + + this._inputElement.value = this._formatValue({ + hours: dateObj.getHours(), + minutes: dateObj.getMinutes(), + }); + + // Emit blur event when value is changed programmatically to notify + // frameworks that rely on that event to update form status. + this._inputElement.dispatchEvent(new FocusEvent('blur', { composed: true })); + } + public get valueAsDate(): Date | null { + return this._formatValueAsDate(this._parseInput(this._inputElement?.value)); + } + @state() private _inputElement: HTMLInputElement | null; /** @@ -92,25 +117,6 @@ export class SbbTimeInput extends LitElement { this._abortController?.abort(); this._handlerRepository.disconnect(); } - public get valueAsDate(): Date | null { - return this._formatValueAsDate(this._parseInput(this._inputElement?.value)); - } - - public set valueAsDate(date: SbbDateLike) { - if (!date || !this._inputElement) { - return; - } - const dateObj = date instanceof Date ? date : new Date(date); - - this._inputElement.value = this._formatValue({ - hours: dateObj.getHours(), - minutes: dateObj.getMinutes(), - }); - - // Emit blur event when value is changed programmatically to notify - // frameworks that rely on that event to update form status. - this._inputElement.dispatchEvent(new FocusEvent('blur', { composed: true })); - } private _findInputElement(): void { const oldInput = this._inputElement; @@ -224,7 +230,7 @@ export class SbbTimeInput extends LitElement { /** Validate input against the defined RegExps. */ private _parseInput(value: string): Time { - const trimmedValue = value.trim(); + const trimmedValue = value?.trim(); if (!trimmedValue) { return null; }