From 0c39506dcb87260ae4d40ee525645ccc155adc7c Mon Sep 17 00:00:00 2001 From: metonym Date: Wed, 4 May 2022 07:31:51 -0700 Subject: [PATCH] fix(types): strongly type `translateWithId` parameters (#1284) --- COMPONENT_INDEX.md | 130 +++++++++++----------- docs/src/COMPONENT_API.json | 18 +-- src/ComboBox/ComboBox.svelte | 13 ++- src/MultiSelect/MultiSelect.svelte | 10 +- tests/ComboBox.test.svelte | 2 + tests/MultiSelect.test.svelte | 2 + types/ComboBox/ComboBox.svelte.d.ts | 15 ++- types/MultiSelect/MultiSelect.svelte.d.ts | 14 ++- 8 files changed, 112 insertions(+), 92 deletions(-) diff --git a/COMPONENT_INDEX.md b/COMPONENT_INDEX.md index 48e60054..cdbcdad0 100644 --- a/COMPONENT_INDEX.md +++ b/COMPONENT_INDEX.md @@ -649,33 +649,33 @@ export interface ComboBoxItem { ### Props -| Prop name | Kind | Reactive | Type | Default value | Description | -| :------------------- | :-------------------- | :------- | :---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | -| listRef | let | Yes | null | HTMLDivElement | null | Obtain a reference to the list HTML element | -| ref | let | Yes | null | HTMLInputElement | null | Obtain a reference to the input HTML element | -| open | let | Yes | boolean | false | Set to `true` to open the combobox menu dropdown | -| value | let | Yes | string | "" | Specify the selected combobox value | -| selectedId | let | Yes | ComboBoxItemId | undefined | Set the selected item by value id | -| items | let | No | ComboBoxItem[] | [] | Set the combobox items | -| itemToString | let | No | (item: ComboBoxItem) => string | (item) => item.text || item.id | Override the display of a combobox item | -| direction | let | No | "bottom" | "top" | "bottom" | Specify the direction of the combobox dropdown menu | -| size | let | No | "sm" | "xl" | undefined | Set the size of the combobox | -| disabled | let | No | boolean | false | Set to `true` to disable the combobox | -| titleText | let | No | string | "" | Specify the title text of the combobox | -| placeholder | let | No | string | "" | Specify the placeholder text | -| helperText | let | No | string | "" | Specify the helper text | -| invalidText | let | No | string | "" | Specify the invalid state text | -| invalid | let | No | boolean | false | Set to `true` to indicate an invalid state | -| warn | let | No | boolean | false | Set to `true` to indicate an warning state | -| warnText | let | No | string | "" | Specify the warning state text | -| light | let | No | boolean | false | Set to `true` to enable the light variant | -| shouldFilterItem | let | No | (item: ComboBoxItem, value: string) => boolean | () => true | Determine if an item should be filtered given the current combobox value | -| translateWithId | let | No | (id: any) => string | undefined | Override the default translation ids | -| translateWithIdMenu | let | No | (id: any) => string | undefined | Override the default translation ids for the menu | -| translateWithIdInput | let | No | (id: any) => string | undefined | Override the default translation ids for the input | -| id | let | No | string | "ccs-" + Math.random().toString(36) | Set an id for the list box component | -| name | let | No | string | undefined | Specify a name attribute for the input | -| clear | function | No | (options?: { focus?: boolean; }) => void | () => { prevSelectedId = null; highlightedIndex = -1; highlightedId = undefined; selectedId = undefined; selectedItem = undefined; open = false; inputValue = ""; if (options?.focus !== false) ref?.focus(); } | Clear the combo box programmatically | +| Prop name | Kind | Reactive | Type | Default value | Description | +| :------------------- | :-------------------- | :------- | :---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | +| listRef | let | Yes | null | HTMLDivElement | null | Obtain a reference to the list HTML element | +| ref | let | Yes | null | HTMLInputElement | null | Obtain a reference to the input HTML element | +| open | let | Yes | boolean | false | Set to `true` to open the combobox menu dropdown | +| value | let | Yes | string | "" | Specify the selected combobox value | +| selectedId | let | Yes | ComboBoxItemId | undefined | Set the selected item by value id | +| items | let | No | ComboBoxItem[] | [] | Set the combobox items | +| itemToString | let | No | (item: ComboBoxItem) => string | (item) => item.text || item.id | Override the display of a combobox item | +| direction | let | No | "bottom" | "top" | "bottom" | Specify the direction of the combobox dropdown menu | +| size | let | No | "sm" | "xl" | undefined | Set the size of the combobox | +| disabled | let | No | boolean | false | Set to `true` to disable the combobox | +| titleText | let | No | string | "" | Specify the title text of the combobox | +| placeholder | let | No | string | "" | Specify the placeholder text | +| helperText | let | No | string | "" | Specify the helper text | +| invalidText | let | No | string | "" | Specify the invalid state text | +| invalid | let | No | boolean | false | Set to `true` to indicate an invalid state | +| warn | let | No | boolean | false | Set to `true` to indicate an warning state | +| warnText | let | No | string | "" | Specify the warning state text | +| light | let | No | boolean | false | Set to `true` to enable the light variant | +| shouldFilterItem | let | No | (item: ComboBoxItem, value: string) => boolean | () => true | Determine if an item should be filtered given the current combobox value | +| translateWithId | let | No | (id: import("../ListBox/ListBoxMenuIcon.svelte").ListBoxMenuIconTranslationId) => string | undefined | Override the chevron icon label based on the open state.
Defaults to "Open menu" when closed and "Close menu" when open | +| translateWithIdMenu | let | No | (id: any) => string | undefined | Override the menu label based on the open state.
Defaults to "Open menu" and "Close menu" | +| translateWithIdInput | let | No | (id: "clearSelection") => string | undefined | Override the label of the clear button when the input has a selection.
Defaults to "Clear selected item" | +| id | let | No | string | "ccs-" + Math.random().toString(36) | Set an id for the list box component | +| name | let | No | string | undefined | Specify a name attribute for the input | +| clear | function | No | (options?: { focus?: boolean; }) => void | () => { prevSelectedId = null; highlightedIndex = -1; highlightedId = undefined; selectedId = undefined; selectedItem = undefined; open = false; inputValue = ""; if (options?.focus !== false) ref?.focus(); } | Clear the combo box programmatically | ### Slots @@ -2327,44 +2327,44 @@ export interface MultiSelectItem { ### Props -| Prop name | Kind | Reactive | Type | Default value | Description | -| :------------------- | :--------------- | :------- | :--------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- | -| highlightedId | let | Yes | null | MultiSelectItemId | null | Id of the highlighted ListBoxMenuItem | -| selectionRef | let | Yes | null | HTMLDivElement | null | Obtain a reference to the selection element | -| fieldRef | let | Yes | null | HTMLDivElement | null | Obtain a reference to the field box element | -| multiSelectRef | let | Yes | null | HTMLDivElement | null | Obtain a reference to the outer div element | -| inputRef | let | Yes | null | HTMLInputElement | null | Obtain a reference to the input HTML element | -| open | let | Yes | boolean | false | Set to `true` to open the dropdown | -| value | let | Yes | string | "" | Specify the multiselect value | -| selectedIds | let | Yes | MultiSelectItemId[] | [] | Set the selected ids | -| items | let | Yes | MultiSelectItem[] | [] | Set the multiselect items | -| itemToString | let | No | (item: MultiSelectItem) => any | (item) => item.text || item.id | Override the display of a multiselect item | -| itemToInput | let | No | (item: MultiSelectItem) => { name?: string; labelText?: any; title?: string; } | (item) => {} | Override the item name, title, labelText passed to the checkbox input | -| size | let | No | "sm" | "lg" | "xl" | undefined | Set the size of the combobox | -| type | let | No | "default" | "inline" | "default" | Specify the type of multiselect | -| direction | let | No | "bottom" | "top" | "bottom" | Specify the direction of the multiselect dropdown menu | -| selectionFeedback | let | No | "top" | "fixed" | "top-after-reopen" | "top-after-reopen" | Specify the selection feedback after selecting items | -| disabled | let | No | boolean | false | Set to `true` to disable the dropdown | -| filterable | let | No | boolean | false | Set to `true` to filter items | -| filterItem | let | No | (item: MultiSelectItem, value: string) => string | (item, value) => item.text.toLowerCase().includes(value.trim().toLowerCase()) | Override the filtering logic
The default filtering is an exact string comparison | -| light | let | No | boolean | false | Set to `true` to enable the light variant | -| locale | let | No | string | "en" | Specify the locale | -| placeholder | let | No | string | "" | Specify the placeholder text | -| sortItem | let | No | ((a: MultiSelectItem, b: MultiSelectItem) => MultiSelectItem) | (() => void) | (a, b) => a.text.localeCompare(b.text, locale, { numeric: true }) | Override the sorting logic
The default sorting compare the item text value | -| translateWithId | let | No | (id: any) => string | undefined | Override the default translation ids | -| translateWithIdMenu | let | No | (id: any) => string | undefined | Override the default translation ids for the menu | -| translateWithIdInput | let | No | (id: any) => string | undefined | Override the default translation ids for the input | -| titleText | let | No | string | "" | Specify the title text | -| useTitleInItem | let | No | boolean | false | Set to `true` to pass the item to `itemToString` in the checkbox | -| invalid | let | No | boolean | false | Set to `true` to indicate an invalid state | -| invalidText | let | No | string | "" | Specify the invalid state text | -| warn | let | No | boolean | false | Set to `true` to indicate an warning state | -| warnText | let | No | string | "" | Specify the warning state text | -| helperText | let | No | string | "" | Specify the helper text | -| label | let | No | string | "" | Specify the list box label | -| hideLabel | let | No | boolean | false | Set to `true` to visually hide the label text | -| id | let | No | string | "ccs-" + Math.random().toString(36) | Set an id for the list box component | -| name | let | No | string | undefined | Specify a name attribute for the select | +| Prop name | Kind | Reactive | Type | Default value | Description | +| :------------------- | :--------------- | :------- | :------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | +| highlightedId | let | Yes | null | MultiSelectItemId | null | Id of the highlighted ListBoxMenuItem | +| selectionRef | let | Yes | null | HTMLDivElement | null | Obtain a reference to the selection element | +| fieldRef | let | Yes | null | HTMLDivElement | null | Obtain a reference to the field box element | +| multiSelectRef | let | Yes | null | HTMLDivElement | null | Obtain a reference to the outer div element | +| inputRef | let | Yes | null | HTMLInputElement | null | Obtain a reference to the input HTML element | +| open | let | Yes | boolean | false | Set to `true` to open the dropdown | +| value | let | Yes | string | "" | Specify the multiselect value | +| selectedIds | let | Yes | MultiSelectItemId[] | [] | Set the selected ids | +| items | let | Yes | MultiSelectItem[] | [] | Set the multiselect items | +| itemToString | let | No | (item: MultiSelectItem) => any | (item) => item.text || item.id | Override the display of a multiselect item | +| itemToInput | let | No | (item: MultiSelectItem) => { name?: string; labelText?: any; title?: string; } | (item) => {} | Override the item name, title, labelText passed to the checkbox input | +| size | let | No | "sm" | "lg" | "xl" | undefined | Set the size of the combobox | +| type | let | No | "default" | "inline" | "default" | Specify the type of multiselect | +| direction | let | No | "bottom" | "top" | "bottom" | Specify the direction of the multiselect dropdown menu | +| selectionFeedback | let | No | "top" | "fixed" | "top-after-reopen" | "top-after-reopen" | Specify the selection feedback after selecting items | +| disabled | let | No | boolean | false | Set to `true` to disable the dropdown | +| filterable | let | No | boolean | false | Set to `true` to filter items | +| filterItem | let | No | (item: MultiSelectItem, value: string) => string | (item, value) => item.text.toLowerCase().includes(value.trim().toLowerCase()) | Override the filtering logic
The default filtering is an exact string comparison | +| light | let | No | boolean | false | Set to `true` to enable the light variant | +| locale | let | No | string | "en" | Specify the locale | +| placeholder | let | No | string | "" | Specify the placeholder text | +| sortItem | let | No | ((a: MultiSelectItem, b: MultiSelectItem) => MultiSelectItem) | (() => void) | (a, b) => a.text.localeCompare(b.text, locale, { numeric: true }) | Override the sorting logic
The default sorting compare the item text value | +| translateWithId | let | No | (id: import("../ListBox/ListBoxMenuIcon.svelte").ListBoxMenuIconTranslationId) => string | undefined | Override the chevron icon label based on the open state.
Defaults to "Open menu" when closed and "Close menu" when open | +| translateWithIdMenu | let | No | (id: any) => string | undefined | Override the default translation ids for the menu | +| translateWithIdInput | let | No | (id: import("../ListBox/ListBoxSelection.svelte").ListBoxSelectionTranslationId) => string | undefined | Override the label of the clear button when the input has a selection.
Defaults to "Clear selected item" and "Clear all items" | +| titleText | let | No | string | "" | Specify the title text | +| useTitleInItem | let | No | boolean | false | Set to `true` to pass the item to `itemToString` in the checkbox | +| invalid | let | No | boolean | false | Set to `true` to indicate an invalid state | +| invalidText | let | No | string | "" | Specify the invalid state text | +| warn | let | No | boolean | false | Set to `true` to indicate an warning state | +| warnText | let | No | string | "" | Specify the warning state text | +| helperText | let | No | string | "" | Specify the helper text | +| label | let | No | string | "" | Specify the list box label | +| hideLabel | let | No | boolean | false | Set to `true` to visually hide the label text | +| id | let | No | string | "ccs-" + Math.random().toString(36) | Set an id for the list box component | +| name | let | No | string | undefined | Specify a name attribute for the select | ### Slots diff --git a/docs/src/COMPONENT_API.json b/docs/src/COMPONENT_API.json index 20b43b0b..f4f2d149 100644 --- a/docs/src/COMPONENT_API.json +++ b/docs/src/COMPONENT_API.json @@ -1555,8 +1555,8 @@ { "name": "translateWithId", "kind": "let", - "description": "Override the default translation ids", - "type": "(id: any) => string", + "description": "Override the chevron icon label based on the open state.\nDefaults to \"Open menu\" when closed and \"Close menu\" when open", + "type": "(id: import(\"../ListBox/ListBoxMenuIcon.svelte\").ListBoxMenuIconTranslationId) => string", "isFunction": false, "isFunctionDeclaration": false, "constant": false, @@ -1565,7 +1565,7 @@ { "name": "translateWithIdMenu", "kind": "let", - "description": "Override the default translation ids for the menu", + "description": "Override the menu label based on the open state.\nDefaults to \"Open menu\" and \"Close menu\"", "type": "(id: any) => string", "isFunction": false, "isFunctionDeclaration": false, @@ -1575,8 +1575,8 @@ { "name": "translateWithIdInput", "kind": "let", - "description": "Override the default translation ids for the input", - "type": "(id: any) => string", + "description": "Override the label of the clear button when the input has a selection.\nDefaults to \"Clear selected item\"", + "type": "(id: \"clearSelection\") => string", "isFunction": false, "isFunctionDeclaration": false, "constant": false, @@ -6603,8 +6603,8 @@ { "name": "translateWithId", "kind": "let", - "description": "Override the default translation ids", - "type": "(id: any) => string", + "description": "Override the chevron icon label based on the open state.\nDefaults to \"Open menu\" when closed and \"Close menu\" when open", + "type": "(id: import(\"../ListBox/ListBoxMenuIcon.svelte\").ListBoxMenuIconTranslationId) => string", "isFunction": false, "isFunctionDeclaration": false, "constant": false, @@ -6623,8 +6623,8 @@ { "name": "translateWithIdInput", "kind": "let", - "description": "Override the default translation ids for the input", - "type": "(id: any) => string", + "description": "Override the label of the clear button when the input has a selection.\nDefaults to \"Clear selected item\" and \"Clear all items\"", + "type": "(id: import(\"../ListBox/ListBoxSelection.svelte\").ListBoxSelectionTranslationId) => string", "isFunction": false, "isFunctionDeclaration": false, "constant": false, diff --git a/src/ComboBox/ComboBox.svelte b/src/ComboBox/ComboBox.svelte index 0e34eeaa..52fbacbf 100644 --- a/src/ComboBox/ComboBox.svelte +++ b/src/ComboBox/ComboBox.svelte @@ -76,20 +76,23 @@ export let shouldFilterItem = () => true; /** - * Override the default translation ids - * @type {(id: any) => string} + * Override the chevron icon label based on the open state. + * Defaults to "Open menu" when closed and "Close menu" when open + * @type {(id: import("../ListBox/ListBoxMenuIcon.svelte").ListBoxMenuIconTranslationId) => string} */ export let translateWithId = undefined; /** - * Override the default translation ids for the menu + * Override the menu label based on the open state. + * Defaults to "Open menu" and "Close menu" * @type {(id: any) => string} */ export let translateWithIdMenu = undefined; /** - * Override the default translation ids for the input - * @type {(id: any) => string} + * Override the label of the clear button when the input has a selection. + * Defaults to "Clear selected item" since a combo box can only have on selection. + * @type {(id: "clearSelection") => string} */ export let translateWithIdInput = undefined; diff --git a/src/MultiSelect/MultiSelect.svelte b/src/MultiSelect/MultiSelect.svelte index c7d369de..b9ce6d57 100644 --- a/src/MultiSelect/MultiSelect.svelte +++ b/src/MultiSelect/MultiSelect.svelte @@ -95,8 +95,9 @@ a.text.localeCompare(b.text, locale, { numeric: true }); /** - * Override the default translation ids - * @type {(id: any) => string} + * Override the chevron icon label based on the open state. + * Defaults to "Open menu" when closed and "Close menu" when open + * @type {(id: import("../ListBox/ListBoxMenuIcon.svelte").ListBoxMenuIconTranslationId) => string} */ export let translateWithId = undefined; @@ -107,8 +108,9 @@ export let translateWithIdMenu = undefined; /** - * Override the default translation ids for the input - * @type {(id: any) => string} + * Override the label of the clear button when the input has a selection. + * Defaults to "Clear selected item" and "Clear all items" + * @type {(id: import("../ListBox/ListBoxSelection.svelte").ListBoxSelectionTranslationId) => string} */ export let translateWithIdInput = undefined; diff --git a/tests/ComboBox.test.svelte b/tests/ComboBox.test.svelte index d7e2e8f1..337a3f82 100644 --- a/tests/ComboBox.test.svelte +++ b/tests/ComboBox.test.svelte @@ -24,12 +24,14 @@ console.log(e.detail.selectedId); }}" translateWithId="{(id) => { + console.log(id); // "open" | "close" return id; }}" translateWithIdMenu="{(id) => { return id; }}" translateWithIdInput="{(id) => { + console.log(id); // "clearSelection" return id; }}" let:item diff --git a/tests/MultiSelect.test.svelte b/tests/MultiSelect.test.svelte index 7102f59a..d5faf0fa 100644 --- a/tests/MultiSelect.test.svelte +++ b/tests/MultiSelect.test.svelte @@ -21,12 +21,14 @@ e.detail; // number | FocusEvent }}" translateWithId="{(id) => { + console.log(id); // "open" | "close" return id; }}" translateWithIdMenu="{(id) => { return id; }}" translateWithIdInput="{(id) => { + console.log(id); // "clearAll" | "clearSelection" return id; }}" let:item diff --git a/types/ComboBox/ComboBox.svelte.d.ts b/types/ComboBox/ComboBox.svelte.d.ts index 1d804fed..c0e87c63 100644 --- a/types/ComboBox/ComboBox.svelte.d.ts +++ b/types/ComboBox/ComboBox.svelte.d.ts @@ -113,22 +113,27 @@ export interface ComboBoxProps shouldFilterItem?: (item: ComboBoxItem, value: string) => boolean; /** - * Override the default translation ids + * Override the chevron icon label based on the open state. + * Defaults to "Open menu" when closed and "Close menu" when open * @default undefined */ - translateWithId?: (id: any) => string; + translateWithId?: ( + id: import("../ListBox/ListBoxMenuIcon.svelte").ListBoxMenuIconTranslationId + ) => string; /** - * Override the default translation ids for the menu + * Override the menu label based on the open state. + * Defaults to "Open menu" and "Close menu" * @default undefined */ translateWithIdMenu?: (id: any) => string; /** - * Override the default translation ids for the input + * Override the label of the clear button when the input has a selection. + * Defaults to "Clear selected item" * @default undefined */ - translateWithIdInput?: (id: any) => string; + translateWithIdInput?: (id: "clearSelection") => string; /** * Set an id for the list box component diff --git a/types/MultiSelect/MultiSelect.svelte.d.ts b/types/MultiSelect/MultiSelect.svelte.d.ts index ee9f3bf1..46eef893 100644 --- a/types/MultiSelect/MultiSelect.svelte.d.ts +++ b/types/MultiSelect/MultiSelect.svelte.d.ts @@ -123,10 +123,13 @@ export interface MultiSelectProps | (() => void); /** - * Override the default translation ids + * Override the chevron icon label based on the open state. + * Defaults to "Open menu" when closed and "Close menu" when open * @default undefined */ - translateWithId?: (id: any) => string; + translateWithId?: ( + id: import("../ListBox/ListBoxMenuIcon.svelte").ListBoxMenuIconTranslationId + ) => string; /** * Override the default translation ids for the menu @@ -135,10 +138,13 @@ export interface MultiSelectProps translateWithIdMenu?: (id: any) => string; /** - * Override the default translation ids for the input + * Override the label of the clear button when the input has a selection. + * Defaults to "Clear selected item" and "Clear all items" * @default undefined */ - translateWithIdInput?: (id: any) => string; + translateWithIdInput?: ( + id: import("../ListBox/ListBoxSelection.svelte").ListBoxSelectionTranslationId + ) => string; /** * Specify the title text