@central-design-system/skills 4.0.0-alpha.6

package/skills/cds-builder/references/components/cds-select/api.md

@@ -0,0 +1,155 @@
+# CdsSelect — API
+
+> Generated from meta.json by `bun run generate:skill`. Do not edit manually.
+> Examples: [examples.md](examples.md) · Guidelines: [guidelines.md](guidelines.md) · Tokens: [tokens.md](tokens.md)
+
+A select opens a dropdown list and lets you pick one or several values from a known set: a country, a status, a category. The field is built on [CdsTextInput](../cds-text-input/api.md), so the label, the description, the messages, validation and the states work exactly as in a text field.
+
+## CdsSelect
+
+**Props**
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `active` | `boolean \| undefined` | — | no | Active state of the field |
+| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
+| `appendIcon` | `IconValue \| undefined` | — | no | Icon in the append slot, after the content |
+| `appendInnerIcon` | `IconValue \| undefined` | — | no | Icon in the inner append slot, after the content of the field |
+| `autocomplete` | `string \| undefined` | — | no | Helps to influence browser suggestions. The `suppress` value changes the name attribute of the fields, and `off` relies on the browser to stop suggesting values on its own. Any other value is passed to the built-in autocomplete of the corresponding element. |
+| `autofocus` | `boolean \| undefined` | — | no | Enables autofocus |
+| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
+| `bgColor` | `string \| undefined` | — | no | Background color of the component |
+| `centerAffix` | `boolean \| undefined` | — | no | Vertically center the appendInner, prependInner, clearIcon and label elements. |
+| `chips` | `boolean \| undefined` | — | no | Shows the selected values as removable chips (CdsTag). |
+| `clearable` | `boolean \| undefined` | — | no | Shows the clear button |
+| `clearIcon` | `IconValue \| undefined` | `'remove'` | no | Icon of the clear button |
+| `closableChips` | `boolean \| undefined` | — | no | Adds a remove button to the chips (relevant together with `chips`). |
+| `closeText` | `string \| undefined` | `'$cds.close'` | no | Text for screen readers describing the close action of the menu. |
+| `color` | `string \| undefined` | — | no | Component color |
+| `counter` | `string \| number \| boolean \| undefined` | — | no | Character counter. Accepts a boolean, a number or a string |
+| `counterValue` | `number \| ((value: any) => number) \| undefined` | — | no | Custom counter value. Either a number or a function computing it from the current value |
+| `customFilter` | `FilterFunction \| undefined` | — | no | Your own value filtering function. Receives the value, the search query and the item, returns a match or `-1` |
+| `customKeyFilter` | `FilterKeyFunctions \| undefined` | — | no | Separate filtering functions for specific item keys — an object of the form `{ key: function }` |
+| `description` | `string \| undefined` | — | no | Description of the component, shown under the label |
+| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
+| `eager` | `boolean \| undefined` | — | no | Renders the menu content upfront, without waiting for the first opening. |
+| `ellipsis` | `boolean \| undefined` | — | no | In multiple mode keeps the selected values on a single line with an ellipsis |
+| `error` | `boolean \| undefined` | — | no | Error state |
+| `errorMessages` | `string \| readonly string[] \| null \| undefined` | `[]` | no | Puts the component into the error state and passes custom error messages. They are merged with any checks defined in the `rules` prop. This field does not trigger validation. |
+| `filterKeys` | `FilterKeys \| undefined` | — | no | Item keys the search runs over. By default filtering goes by the item title |
+| `filterMode` | `FilterMode \| undefined` | `'intersection'` | no | How the results of `customKeyFilter` and of the general filtering are combined: by intersection, by union or by replacement |
+| `focused` | `boolean \| undefined` | — | no | Controls the focus state of the component. When `true`, the component is considered focused and may apply the corresponding styles or behavior. |
+| `hideDetails` | `boolean \| "auto" \| undefined` | — | no | Hides the details block (messages and hints). With the 'auto' value the block is hidden when there are no messages |
+| `hideMessages` | `boolean \| undefined` | — | no | Hide the messages under the input |
+| `hideNoData` | `boolean \| undefined` | — | no | Hides the menu and the "no data" placeholder when the item list is empty. |
+| `hideSelected` | `boolean \| undefined` | — | no | Hides the already selected items from the menu list. |
+| `hint` | `string \| undefined` | — | no | Hint text shown under the input |
+| `iconColor` | `string \| boolean \| undefined` | — | no | Icon color. Accepts a boolean or a color string |
+| `id` | `string \| undefined` | — | no | Unique identifier of the component |
+| `isSelectAll` | `string \| boolean \| undefined` | `false` | no | Adds a "select all" entry as the first item of the list (for `multiple` only). `true` uses the default `$cds.selectAll` caption, a string sets your own caption. |
+| `itemChildren` | `SelectItemKey` | `false` | no | Object field that holds the child items, or a function that returns them |
+| `itemColor` | `string \| undefined` | — | no | Color of the selected items in the menu list. `color` is used by default. |
+| `itemProps` | `SelectItemKey` | `'props'` | no | Object field that holds the props of the item, or a function that returns them |
+| `items` | `any[] \| undefined` | `[]` | no | Array of items to display |
+| `itemTitle` | `SelectItemKey` | `'title'` | no | Object field used as the item title, or a function that returns it |
+| `itemType` | `SelectItemKey` | `'type'` | no | Object field that defines the item type (`item`, `divider`, `subheader`), or a function that returns it |
+| `itemValue` | `SelectItemKey` | `'value'` | no | Object field used as the item value, or a function that returns it |
+| `label` | `string \| undefined` | — | no | Label text of the component |
+| `listProps` | `CdsListProps \| undefined` | — | no | Props passed through to the inner CdsList component. |
+| `loading` | `string \| boolean \| undefined` | — | no | Loading indicator for the component |
+| `maxErrors` | `string \| number \| undefined` | `1` | no | Maximum number of validation errors shown |
+| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
+| `menu` | `boolean \| undefined` | — | no | Controls the open state of the dropdown menu (v-model:menu). |
+| `menuHeight` | `string \| number \| undefined` | `178` | no | Maximum height of the dropdown menu. |
+| `menuIcon` | `IconValue \| undefined` | `'chevron-down'` | no | Icon indicating that the menu can be expanded. |
+| `menuProps` | `CdsMenuProps \| undefined` | — | no | Props passed through to the inner CdsMenu component. |
+| `messages` | `string \| readonly string[] \| undefined` | `[]` | no | Messages shown under the input |
+| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
+| `modelModifiers` | `Record<string, boolean> \| undefined` | — | no | v-model modifiers passed by Vue to process the field value |
+| `modelValue` | `any` | `null` | no | Value of the component in v-model. If the component supports the multiple prop, an empty array is used by default. |
+| `multiple` | `boolean \| undefined` | — | no | Allows selecting several values. The selected items are shown as chips or as a list. |
+| `name` | `string \| undefined` | — | no | Name of the input |
+| `nativeSelect` | `boolean \| undefined` | — | no | Renders a native HTML select instead of the custom dropdown menu (CdsMenu) |
+| `noAutoScroll` | `boolean \| undefined` | — | no | Turns off the automatic scrolling of the menu to the selected item on opening. |
+| `noDataText` | `string \| undefined` | `'$cds.noDataText'` | no | Text shown in the menu when the item list is empty. |
+| `noFilter` | `boolean \| undefined` | — | no | Turns off the built-in filtering — the list is shown as is, the search is handled outside |
+| `openOnClear` | `boolean \| undefined` | — | no | Opens the menu after the value is cleared. |
+| `openText` | `string \| undefined` | `'$cds.open'` | no | Text for screen readers describing the open action of the menu. |
+| `persistentClearable` | `boolean \| undefined` | — | no | Always show the clear button, not only on hover or focus |
+| `persistentCounter` | `boolean \| undefined` | — | no | Always show the counter, not only while the field is in use |
+| `persistentHint` | `boolean \| undefined` | — | no | Always show the hint, not only on focus |
+| `persistentPlaceholder` | `boolean \| undefined` | — | no | Always show the placeholder instead of hiding it while the field is in use |
+| `placeholder` | `string \| undefined` | — | no | Placeholder text shown in an empty field |
+| `prefix` | `string \| undefined` | — | no | Text prefix shown before the field value |
+| `prependIcon` | `IconValue \| undefined` | — | no | Icon in the prepend slot, before the content |
+| `prependInnerIcon` | `IconValue \| undefined` | — | no | Icon in the inner prepend slot, before the content of the field |
+| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
+| `returnObject` | `boolean \| undefined` | — | no | Return an object in the model value instead of an array |
+| `reverse` | `boolean \| undefined` | — | no | Reverses the order of the elements inside the field |
+| `role` | `string \| undefined` | `'combobox'` | no | ARIA role for the native input element |
+| `rules` | `readonly ValidationRule[] \| undefined` | `[]` | no | Accepts an array of items of different types: functions, booleans and strings. Functions take the input value as an argument and must return either true / false, or a string with an error message. The input goes into the error state if a function returns false (or any value in the array is false) or is a string. |
+| `search` | `string \| undefined` | — | no | Current value of the search query used to filter the items (v-model:search). |
+| `size` | `number \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined` | `'md'` | no | Size of the component |
+| `suffix` | `string \| undefined` | — | no | Text suffix shown after the field value |
+| `textColor` | `string \| undefined` | — | no | Text color of the component |
+| `theme` | `string \| undefined` | — | no | Component theme |
+| `transition` | `string \| boolean \| (TransitionProps & { component?: Component \| undefined; }) \| { component: Component; } \| null \| undefined` | `{ component: CdsModalTransition }` | no | Transition animation |
+| `type` | `string \| undefined` | `'text'` | no | Type of the native input |
+| `validateOn` | `ValidateOn \| undefined` | — | no | Changes the type of the event that triggers validation |
+| `valueComparator` | `ValueComparator \| undefined` | — | no | Function that compares item values to determine the selected state |
+| `width` | `string \| number \| undefined` | — | no | Component width |
+
+**Events**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `update:focused` | `[focused: boolean]` | The focus state of the component changed (v-model:focused). |
+| `update:menu` | `[ue: boolean]` | The open state of the dropdown menu changed (v-model:menu). |
+| `update:modelValue` | `[value: any]` | The selected value changed (v-model). |
+| `update:search` | `[value: string]` | The search query changed (v-model:search). |
+| `update:selectedAll` | `[value: boolean]` | The "all selected" state changed (for `multiple` + `isSelectAll` only). |
+
+**Slots**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `append` | `CdsInputSlot` | Adds an element after the input |
+| `append-inner` | `CdsInputDefaultSlot` | Slot added at the end of the input |
+| `append-item` | `any` | Content after the item list in the menu. |
+| `chip` | `{ item: any; internalItem: ListItem<any>; index: number; props: Record<string, unknown>; }` | Custom rendering of the chip of a selected value (relevant together with `chips`). |
+| `clear` | `CdsInputDefaultSlot & { props: Record<string, any>; }` | Slot for a custom clear icon (shown when the clearable prop is true). |
+| `description` | `{ description: string \| undefined; props: Record<string, any>; }` | Default slot of the CdsDescription component |
+| `details` | `CdsInputSlot` | Slot for custom content that lets you customize how the messages are displayed |
+| `divider` | `{ props: Record<string, unknown>; index: number; }` | Custom rendering of a divider in the menu list. |
+| `item` | `{ item: any; internalItem: ListItem<any>; index: number; props: Record<string, unknown>; }` | Custom rendering of an item of the menu list. |
+| `label` | `{ label: string \| undefined; props: Record<string, any>; }` | Default slot of the CdsLabel component |
+| `loader` | `LoaderSlotProps` | Slot for a custom loader (shown when the loading prop is true). |
+| `menu-footer` | `{ search: Ref<string \| undefined, string \| undefined>; filteredItems: ListItem<any>[]; }` | Content of the menu footer. Receives the current search query and the filtered items. |
+| `menu-header` | `{ search: Ref<string \| undefined, string \| undefined>; filteredItems: ListItem<any>[]; }` | Content of the menu header. Receives the current search query and the filtered items. |
+| `message` | `CdsMessagesSlots` | Slot for customizing the content of a message |
+| `messages` | `CdsInputSlot` | Slot for custom content that lets you customize how the messages are displayed |
+| `no-data` | `any` | Content shown in the menu when the item list is empty. |
+| `prepend` | `CdsInputSlot` | Adds an element before the input |
+| `prepend-inner` | `CdsInputDefaultSlot` | Slot added at the start of the input |
+| `prepend-item` | `any` | Content before the item list in the menu. |
+| `selection` | `{ item: any; internalItem: ListItem<any>; index: number; }` | Custom rendering of the selected value inside the field. |
+| `subheader` | `{ props: Record<string, unknown>; index: number; }` | Custom rendering of a group subheader in the menu list. |
+
+**Exposed**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `controlRef` | `HTMLElement \| undefined` | Ref to the control of the input |
+| `fieldIconColor` | `string \| undefined` | Icon color |
+| `filteredItems` | `ListItem<any>[]` | Items filtered by the current search query. |
+| `isDirty` | `boolean` | Whether the input is dirty |
+| `isDisabled` | `boolean` | Whether the input is disabled |
+| `isFocused` | `boolean` | Whether the component is focused. |
+| `isPure` | `boolean` | Whether the input is pure |
+| `isReadonly` | `boolean` | Whether the input is read-only |
+| `isValid` | `boolean \| null` | Whether the input is valid |
+| `isValidating` | `boolean` | Whether the input is being validated |
+| `reset` | `() => Promise<void>` | Resets the input to its initial state |
+| `resetValidation` | `() => Promise<void>` | Resets the validation of the input |
+| `selectAll` | `() => void` | Toggle the selection of all available items (for `multiple` + `isSelectAll` only). |
+| `validate` | `(silent?: boolean) => Promise<string[]>` | Validates the input |