Skip to content

Commit

Permalink
docs: remove references to methods
Browse files Browse the repository at this point in the history
  • Loading branch information
@DavideMininni-Fincons
DavideMininni-Fincons committed Dec 4, 2023
1 parent 9cdc9c5 commit ce0b13a
Show file tree
Hide file tree
Showing 4 changed files with 62 additions and 53 deletions.
31 changes: 17 additions & 14 deletions src/components/datepicker/datepicker/datepicker.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*/
Expand Down Expand Up @@ -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,
Expand Down
24 changes: 12 additions & 12 deletions src/components/datepicker/datepicker/readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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

Expand Down
14 changes: 7 additions & 7 deletions src/components/time-input/readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down
46 changes: 26 additions & 20 deletions src/components/time-input/time-input.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;

/**
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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;
}
Expand Down

0 comments on commit ce0b13a

Please sign in to comment.