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

package/skills/cds-builder/references/components/cds-file-upload/api.md

@@ -0,0 +1,296 @@
+# CdsFileUpload — 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 file upload zone: it accepts files by dragging, by pasting from the clipboard and through the system dialog, and shows the selection as a list with image previews. Around the zone the component gathers everything a form needs: a label, a description, messages and validation.
+
+Family: [CdsFileUpload](#cdsfileupload) + subcomponents: [CdsFileUploadDropzone](#cdsfileuploaddropzone), [CdsFileUploadItem](#cdsfileuploaditem), [CdsFileUploadList](#cdsfileuploadlist).
+
+## CdsFileUpload
+
+**Props**
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
+| `appendIcon` | `IconValue \| undefined` | — | no | Icon in the append slot, after the content |
+| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
+| `bgColor` | `string \| undefined` | — | no | Background color of the component |
+| `browseText` | `string \| undefined` | `'$cds.fileUpload.browse'` | no | Text of the file browse button. Supports localization keys (`$cds.fileUpload.browse`). |
+| `centerAffix` | `boolean \| undefined` | `true` | no | Vertically center the appendInner, prependInner, clearIcon and label elements. |
+| `clearable` | `boolean \| undefined` | — | no | Allows removing the chosen files from the list. |
+| `color` | `string \| undefined` | — | no | Component color |
+| `description` | `string \| undefined` | — | no | Description of the component, shown under the label |
+| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
+| `dividerText` | `string \| undefined` | `'$cds.fileUpload.divider'` | no | Text of the divider between the icon and the file browse button. |
+| `error` | `boolean \| undefined` | — | no | Puts the component into the 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. |
+| `filterByType` | `string \| undefined` | — | no | Filtering of files by MIME type or extension (`image/*,.pdf`, for example). The rejected files do not get into the model. |
+| `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. |
+| `hideBrowse` | `boolean \| undefined` | — | no | Hides the file browse button — the whole upload zone becomes clickable. |
+| `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 |
+| `hint` | `string \| undefined` | — | no | Hint text shown under the input |
+| `icon` | `IconValue \| undefined` | `'upload'` | no | Icon in the center of the upload zone. |
+| `iconColor` | `string \| boolean \| undefined` | — | no | Icon color. Accepts a boolean or a color string |
+| `id` | `string \| undefined` | — | no | Unique identifier of the component |
+| `insetFileList` | `boolean \| undefined` | — | no | Shows the list of the chosen files inside the upload zone instead of under it. |
+| `label` | `string \| undefined` | — | no | Label text of the 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 |
+| `messages` | `string \| readonly string[] \| undefined` | `[]` | no | Messages shown under the input |
+| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
+| `modelValue` | `File \| File[] \| null \| undefined` | `null` | no | The chosen files. An array with `multiple`, a single `File` otherwise. |
+| `multiple` | `boolean \| undefined` | — | no | Allows choosing several files. |
+| `name` | `string \| undefined` | — | no | Name of the input |
+| `persistentHint` | `boolean \| undefined` | — | no | Always show the hint, not only on focus |
+| `prependIcon` | `IconValue \| undefined` | — | no | Icon in the prepend slot, before the content |
+| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
+| `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. |
+| `scrim` | `string \| boolean \| undefined` | `true` | no | Dimming of the upload zone while files are being dragged over it. |
+| `showSize` | `ShowSize \| undefined` | `false` | no | Shows the size of the file. A number sets the base for the human-readable conversion. |
+| `size` | `"sm" \| "md" \| "lg" \| undefined` | `'md'` | no | Size of the upload zone. With `sm` the zone is shown as a compact row without the browse button and the divider. |
+| `subtitle` | `string \| undefined` | — | no | Subtitle under the file browse button. Shown with `size` `md` and `lg` only. |
+| `textColor` | `string \| undefined` | — | no | Text color of the component |
+| `theme` | `string \| undefined` | — | no | Component theme |
+| `title` | `string \| undefined` | `'$cds.fileUpload.title'` | no | Title of the upload zone. |
+| `validateOn` | `ValidateOn \| undefined` | — | no | Changes the type of the event that triggers validation |
+| `validationValue` | `any` | — | no | Value used when applying the validation rules |
+| `width` | `string \| number \| undefined` | — | no | Component width |
+
+**Events**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `rejected` | `[files: File[]]` | The files did not pass the `filterByType` filtering. |
+| `update:focused` | `[focused: boolean]` | The focus state changed. |
+| `update:modelValue` | `[files: File[]]` | The list of the chosen files changed. |
+
+**Slots**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `append` | `CdsInputSlot` | Adds an element after the input |
+| `browse` | `CdsFileUploadBrowseSlot` | The file browse button. |
+| `default` | `any` | Fully replaces the upload zone with your own markup. |
+| `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` | `any` | Divider between the title and the file browse button. |
+| `icon` | `any` | Icon in the center of the upload zone. |
+| `input` | `{ inputNode: VNode<RendererNode, RendererElement, { [key: string]: any; }>; }` | The native `input[type=file]`, given out for manual placement in the markup. |
+| `item` | `CdsFileUploadFileSlot` | An item of the list of the chosen files. |
+| `label` | `{ label: string \| undefined; props: Record<string, any>; }` | Default slot of the CdsLabel component |
+| `loader` | `LoaderSlotProps` | The loading indicator. |
+| `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 |
+| `prepend` | `CdsInputSlot` | Adds an element before the input |
+| `single` | `CdsFileUploadFileSlot` | The only chosen file with `insetFileList` and without `multiple`. |
+| `title` | `any` | Title of the upload zone. |
+
+**Exposed**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `controlRef` | `HTMLInputElement \| undefined` | Ref to the native `input[type=file]` element — for opening the file dialog programmatically. |
+| `isDirty` | `boolean` | Whether the input is dirty |
+| `isDisabled` | `boolean` | Whether the input is disabled |
+| `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 |
+| `validate` | `(silent?: boolean) => Promise<string[]>` | Validates the input |
+
+---
+
+## CdsFileUploadDropzone
+
+**Props**
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `browseText` | `string \| undefined` | `'$cds.fileUpload.browse'` | no | Text of the file browse button. Supports localization keys (`$cds.fileUpload.browse`). |
+| `clearable` | `boolean \| undefined` | — | no | Allows removing the chosen files from the list. |
+| `color` | `string \| undefined` | — | no | Background color of the surface |
+| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
+| `dividerText` | `string \| undefined` | `'$cds.fileUpload.divider'` | no | Text of the divider between the icon and the file browse button. |
+| `error` | `boolean \| undefined` | — | no | Shows the upload zone in the error state. |
+| `height` | `string \| number \| undefined` | — | no | Component height |
+| `hideBrowse` | `boolean \| undefined` | — | no | Hides the file browse button — the whole upload zone becomes clickable. |
+| `icon` | `IconValue \| undefined` | `'upload'` | no | Icon in the center of the upload zone. |
+| `insetFileList` | `boolean \| undefined` | — | no | Shows the list of the chosen files inside the upload zone instead of under it. |
+| `length` | `string \| number \| undefined` | `150` | no | Length of the divider. Defaults to pixels. |
+| `location` | `Anchor \| null \| undefined` | — | no | Position of the element relative to its container, for example "top left", "center", "bottom right". |
+| `maxHeight` | `string \| number \| undefined` | — | no | Maximum component height |
+| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
+| `minHeight` | `string \| number \| undefined` | — | no | Minimum component height |
+| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
+| `modelValue` | `File[] \| undefined` | `[]` | no | The list of the chosen files. Used when `CdsFileUploadDropzone` is applied on its own. |
+| `multiple` | `boolean \| undefined` | — | no | Allows choosing several files. |
+| `opacity` | `string \| number \| undefined` | — | no | Opacity of the divider. |
+| `position` | `"absolute" \| "static" \| "fixed" \| "relative" \| "sticky" \| undefined` | — | no | CSS positioning of the component — the value of the `position` property |
+| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
+| `scrim` | `string \| boolean \| undefined` | `true` | no | Dimming of the upload zone while files are being dragged over it. |
+| `showSize` | `ShowSize \| undefined` | `false` | no | Shows the size of the file. A number sets the base for the human-readable conversion. |
+| `size` | `"sm" \| "md" \| "lg" \| undefined` | `'md'` | no | Size of the upload zone. With `sm` the zone is shown as a compact row without the browse button and the divider. |
+| `subtitle` | `string \| undefined` | — | no | Subtitle under the file browse button. Shown with `size` `md` and `lg` only. |
+| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
+| `theme` | `string \| undefined` | — | no | Component theme |
+| `thickness` | `string \| number \| undefined` | — | no | Thickness of the divider. Defaults to pixels. |
+| `title` | `string \| undefined` | `'$cds.fileUpload.title'` | no | Title of the upload zone. |
+| `width` | `string \| number \| undefined` | — | no | Component width |
+
+**Events**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `click:browse` | `[]` | The file browse button was pressed. |
+| `click:remove` | `[index: number]` | Removal of a file by its index was requested. |
+| `drop` | `[files: File[]]` | Files were dropped into the upload zone. |
+
+**Slots**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `browse` | `CdsFileUploadBrowseSlot` | The file browse button. |
+| `default` | `{ isDragging: boolean; hasFiles: boolean; files: readonly File[]; props: { onClick: () => void; }; }` | Fully replaces the content of the upload zone. |
+| `divider` | `any` | Divider between the title and the file browse button. |
+| `icon` | `any` | Icon in the center of the upload zone. |
+| `input` | `any` | The native `input[type=file]`. |
+| `item` | `CdsFileUploadFileSlot` | An item of the list of the chosen files inside the upload zone. |
+| `loader` | `any` | The loading indicator. |
+| `single` | `CdsFileUploadFileSlot` | The only chosen file with `insetFileList` and without `multiple`. |
+| `title` | `any` | Title of the upload zone. |
+
+---
+
+## CdsFileUploadItem
+
+**Props**
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `active` | `boolean \| undefined` | — | no | Forces the active state of the item |
+| `activeClass` | `string \| undefined` | — | no | Class applied to list items when they are in the active state |
+| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
+| `appendAvatar` | `string \| undefined` | — | no | Avatar (image URL) shown after the item content |
+| `appendIcon` | `IconValue \| undefined` | — | no | Icon shown after the item content |
+| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
+| `bgColor` | `string \| undefined` | — | no | Background color of the component |
+| `clearable` | `boolean \| undefined` | — | no | Allows removing the file from the list. |
+| `color` | `string \| undefined` | — | no | Component color |
+| `description` | `string \| number \| boolean \| undefined` | — | no | Description of the list item shown below the title and the subtitle |
+| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
+| `exact` | `boolean \| undefined` | — | no | If true, the active state applies only on an exact route match |
+| `file` | `File \| undefined` | `null` | no | The file shown by the list item. |
+| `fileIcon` | `IconValue \| undefined` | `'doc'` | no | Fallback icon for the files that have no preview. |
+| `height` | `string \| number \| undefined` | — | no | Component height |
+| `href` | `string \| undefined` | — | no | The `href` attribute of the link. When set, the component behaves as a regular link |
+| `index` | `number \| undefined` | — | no | Index of the item; used for keyboard navigation |
+| `lines` | `false \| "one" \| "two" \| "three" \| undefined` | `'two'` | no | Number of lines in the list items; affects their height. `false` turns off the fixed height |
+| `link` | `boolean \| undefined` | — | no | Turns the item into a clickable link. Detected automatically when `href` or `to` is set |
+| `maxHeight` | `string \| number \| undefined` | — | no | Maximum component height |
+| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
+| `minHeight` | `string \| number \| undefined` | — | no | Minimum component height |
+| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
+| `nav` | `boolean \| undefined` | — | no | Applies navigation list styles (rounded active items) |
+| `prependAvatar` | `string \| undefined` | — | no | Avatar (image URL) shown before the item content |
+| `prependGap` | `string \| number \| undefined` | — | no | Indent before the item content (reserves space for the prepend icon or avatar) |
+| `prependIcon` | `IconValue \| undefined` | — | no | Icon shown before the item content |
+| `replace` | `boolean \| undefined` | — | no | If true, navigation replaces the current history entry instead of pushing a new one |
+| `showSize` | `ShowSize \| undefined` | `false` | no | Shows the size of the file instead of its MIME type. |
+| `slim` | `boolean \| undefined` | — | no | Removes the inner paddings of the list and of the menu container: the list fills the available area completely |
+| `subtitle` | `string \| number \| boolean \| undefined` | — | no | Subtitle of the item shown below the title |
+| `tabindex` | `string \| number \| undefined` | — | no | Value of the element `tabindex` attribute |
+| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
+| `textColor` | `string \| undefined` | — | no | Text color of the component |
+| `theme` | `string \| undefined` | — | no | Component theme |
+| `title` | `string \| number \| boolean \| undefined` | — | no | Title of the item shown in the component |
+| `to` | `LinkTo \| undefined` | — | no | Target route or route location object for RouterLink. When set, the component behaves as a RouterLink |
+| `value` | `any` | — | no | Value of the item used for selection and activation in the list |
+| `width` | `string \| number \| undefined` | — | no | Component width |
+
+**Events**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `click` | `[event: MouseEvent \| KeyboardEvent]` | A click on the list item. |
+| `click:remove` | `[]` | Removal of the file was requested. |
+
+**Slots**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `append` | `ListItemSlot` | Content after the item text (in place of the append icon or avatar) |
+| `clear` | `{ props: { onClick: () => void; }; }` | The file removal button. |
+| `default` | `ListItemSlot` | Default content inside the item |
+| `description` | `ListItemDescriptionSlot` | Content of the item description (shown below the title and the subtitle) |
+| `prepend` | `ListItemSlot` | Content before the item text (in place of the prepend icon or avatar) |
+| `subtitle` | `ListItemSubtitleSlot` | Content of the item subtitle |
+| `title` | `ListItemTitleSlot` | Content of the item title |
+
+---
+
+## CdsFileUploadList
+
+**Props**
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `activatable` | `boolean \| undefined` | — | no | Allows items to be activated (highlighting the current item without selection mode) |
+| `activated` | `any` | — | no | Identifiers of the active items (supports v-model through `update:activated`) |
+| `activeClass` | `string \| undefined` | — | no | Class applied to list items when they are in the active state |
+| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
+| `activeStrategy` | `ActiveStrategyProp \| undefined` | — | no | Activation strategy for items (single, multiple, and so on) |
+| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
+| `bgColor` | `string \| undefined` | — | no | Background color of the component |
+| `clearable` | `boolean \| undefined` | — | no | Allows removing files from the list. |
+| `collapseIcon` | `IconValue \| undefined` | — | no | Icon shown on a collapsed group |
+| `color` | `string \| undefined` | — | no | Component color |
+| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
+| `expandIcon` | `IconValue \| undefined` | — | no | Icon shown on an expanded group |
+| `files` | `File[] \| undefined` | — | no | The list of files. Taken from the `CdsFileUpload` context by default. |
+| `filterable` | `boolean \| undefined` | — | no | **FOR INTERNAL USE ONLY** Turns on filtering mode: the space key does not select an item but is used for typing. Applies to the CdsCombobox and CdsAutocomplete components |
+| `height` | `string \| number \| undefined` | — | no | Component height |
+| `indent` | `string \| number \| undefined` | — | no | Indent size for nested item groups |
+| `itemChildren` | `SelectItemKey` | `'children'` | no | Object field that holds the child items, or a function that returns them |
+| `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 |
+| `itemsRegistration` | `ItemsRegistrationType \| undefined` | `'render'` | no | Item registration strategy: `render` — as they are rendered, otherwise all at once |
+| `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 |
+| `lines` | `false \| "one" \| "two" \| "three" \| undefined` | `false` | no | Number of lines in the list items; affects their height. `false` turns off the fixed height |
+| `mandatory` | `boolean \| undefined` | — | no | Makes the selection mandatory: forbids clearing the selection of the last item |
+| `maxHeight` | `string \| number \| undefined` | — | no | Maximum component height |
+| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
+| `minHeight` | `string \| number \| undefined` | — | no | Minimum component height |
+| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
+| `nav` | `boolean \| undefined` | — | no | Applies navigation list styles (rounded active items) |
+| `navigationIndex` | `number \| undefined` | — | no | Index of the current item during keyboard navigation (supports v-model) |
+| `navigationStrategy` | `"focus" \| "track" \| undefined` | `'focus'` | no | Keyboard navigation strategy: `focus` — moves the focus, `track` — a virtual cursor |
+| `opened` | `any` | — | no | Identifiers of the expanded groups (supports v-model through `update:opened`) |
+| `openStrategy` | `OpenStrategyProp \| undefined` | `'list'` | no | Expansion strategy for groups (`list`, `single`, `multiple`) |
+| `prependGap` | `string \| number \| undefined` | — | no | Indent before the item content (reserves space for the prepend icon or avatar) |
+| `required` | `boolean \| undefined` | — | no | Makes the selection mandatory: forbids clearing the selection of the last item |
+| `returnObject` | `boolean \| undefined` | — | no | Return an object in the model value instead of an array |
+| `selectable` | `boolean \| undefined` | — | no | Allows items to be selected |
+| `selected` | `any` | — | no | Identifiers of the selected items (supports v-model through `update:selected`) |
+| `selectStrategy` | `SelectStrategyProp \| undefined` | `'single-leaf'` | no | Selection strategy for items (`single-leaf`, `leaf`, `independent`, `classic`, and so on) |
+| `showSize` | `ShowSize \| undefined` | `false` | no | Shows the size of every file. |
+| `slim` | `boolean \| undefined` | — | no | Removes the inner paddings of the list and of the menu container: the list fills the available area completely |
+| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
+| `textColor` | `string \| undefined` | — | no | Text color of the component |
+| `theme` | `string \| undefined` | — | no | Component theme |
+| `valueComparator` | `ValueComparator \| undefined` | — | no | Function that compares item values to determine the selected state |
+| `width` | `string \| number \| undefined` | — | no | Component width |
+
+**Slots**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `default` | `{ files: readonly File[]; onClickRemove: (index: number) => void; }` | Fully replaces the content of the list. |
+| `item` | `CdsFileUploadFileSlot` | An item of the list. |