@xleddyl/443-components-vue 0.10.2 → 0.11.0

package/README.md

@@ -350,15 +350,15 @@ Several controls in one `FormField`. Only the primary control takes the field id
 | core      | Root, Icon, Button, Spinner, Input, Textarea, FormField, FieldMessage, FieldBoundary, Form, FormAlerts, Kbd, VisuallyHidden                                                                                                     |
 | forms     | Calendar, Checkbox, CheckboxGroup, ColorInput, Combobox, DateInput, DatePicker, FileInput, InputAddon, InputGroup, NumberInput, PasswordInput, PinInput, Radio, RadioGroup, SegmentedControl, Select, Slider, Switch, TimeInput |
 | overlays  | CommandPalette, ConfirmDialog, ConfirmHost, ContextMenu, Drawer, DropdownMenu, HoverCard, Modal, OverlayHost, Popover, Toaster, Tooltip                                                                                         |
-| data      | Avatar, AvatarGroup, Badge, DescriptionList, FilterPill, FilterPills, Pagination, SelectionBar, Stat, Table, Tag, Timeline, Tree                                                                                                |
-| layout    | Accordion, AppShell, Breadcrumbs, Card, CopyButton, Grid, NavLink, PageHeader, Separator, Sidebar, SidebarNav, SidebarSection, Stack, Tabs, ThemeSwitch, Toolbar                                                                |
+| data      | Avatar, AvatarGroup, Badge, DescriptionList, FilterPill, FilterPills, Pagination, SelectionBar, Stat, Table, Tag, TagList, Timeline, Tree                                                                                       |
+| layout    | Accordion, AppShell, Breadcrumbs, Card, CopyButton, Grid, NavLink, PageHeader, Separator, Sidebar, SidebarNav, SidebarSection, Stack, Stepper, Tabs, ThemeSwitch, Toolbar                                                       |
 | templates | DashboardLayout, AuthLayout, DashboardPage, ListPage, DetailPage, FormPage, SettingsPage, SettingsSection, SettingsModal, SettingsGroup, AppearanceSettings, SaveBar, ErrorPage, NotFoundPage, EmptyPage, Brand, AccountMenu    |
 | feedback  | Alert, EmptyState, LoadingOverlay, Meter, Progress, ProgressRing, Skeleton                                                                                                                                                      |
 | grid      | DataGrid, GridToolbar, cell renderers (BadgeCell, BooleanCell, DateCell, EmptyCell, ImageCell, LinkCell)                                                                                                                        |
 | editor    | RichTextEditor                                                                                                                                                                                                                  |
 | chart     | ChartPanel, ChartLegend, LineChart, BarChart, DoughnutChart                                                                                                                                                                     |
 
-Composables: `useTheme`, `usePreset`, `useForm`, `useField`, `useFieldControl`, `useToast` (and `toast`), `useConfirm`, `useAlert`, `usePrompt`, `useModal`, `useDrawer`, `useOverlay`, `useModalContext`, `useLoading` (and `withLoading`), `useLoadingState`, `useHotkey`, `useCopy`, `useFileDrop` (with `readDroppedFiles`), `usePasswordStrength`, `useTableSort`, `useAppShell`, `useScrollLock`, `useDirtyGuard`, `useIcons` helpers and `useLinkComponent`, `provideFieldBoundary`, `provideAuxiliaryControls`, `provideForm`, `useLocale`. With the Nuxt module also `useDashboard()` (runtime account, breadcrumbs and badges for the `k-dashboard` layout).
+Composables: `useTheme`, `usePreset`, `useForm`, `useField`, `useFieldControl`, `useToast` (and `toast`), `useConfirm`, `useAlert`, `usePrompt`, `useModal`, `useDrawer`, `useOverlay`, `useModalContext`, `useLoading` (and `withLoading`), `useLoadingState`, `useHotkey`, `useCopy`, `useFileDrop` (with `readDroppedFiles`), `useSortable`, `usePasswordStrength`, `useTableSort`, `useAppShell`, `useScrollLock`, `useDirtyGuard`, `useIcons` helpers and `useLinkComponent`, `provideFieldBoundary`, `provideAuxiliaryControls`, `provideForm`, `useLocale`. With the Nuxt module also `useDashboard()` (runtime account, breadcrumbs and badges for the `k-dashboard` layout).
 
 ### Lists, trees and uploads
 
@@ -368,12 +368,19 @@ Composables: `useTheme`, `usePreset`, `useForm`, `useField`, `useFieldControl`,
 - `Input` takes `transform: (value: string) => string`, applied to the typed text before it reaches the model (the caret keeps its place; IME composition is transformed when it ends). `:transform="(value) => value.toUpperCase()"` enforces uppercase codes. Values set from outside are not transformed.
 - `FormField` takes `optional`, a muted localized "Optional" marker in the label row (`form.optional`, `optionalText` overrides it), the counterpart of the required asterisk. It is hidden when the field is required.
 - `CheckboxGroup` takes `columns` (a number): the options are laid out in a grid with that many equal columns. Unset keeps the `orientation` layout. `variant="filled"` (`CheckboxGroupVariant`, `'default' | 'filled'`, default `'default'`) puts the options in a subtle filled panel, styled by `--k-checkbox-group-background` (`--k-subtle`), `--k-checkbox-group-padding` (0.75rem), `--k-checkbox-group-radius` (`--k-radius-md`) and `--k-checkbox-group-border` (none).
+- `Combobox` with `creatable` takes `createTransform` (`ComboboxCreateTransform`, `(input) => string | null | undefined`) and `createValidate` (`ComboboxCreateValidate`, `(input) => string | true | undefined`). The transform runs on the typed text first: the "Create" option shows its result, and an empty result (or `null`) shows no create option. The validator gets the transformed text when the user picks the create option: a returned string is the error, shown inline through the surrounding `FormField` (`useFieldControl().setControlError`, or a `FieldMessage` under the control and an announcement without a field) with `aria-invalid` on the input, and nothing is created; `true` or nothing accepts it. The error clears when the query changes. Both work with `multiple`, where created values become tags: `<KCombobox v-model="tags" multiple creatable :create-transform="(input) => input.toLowerCase()" :create-validate="(input) => input.length >= 3 || 'Too short'" />`.
 - `Combobox` with `multiple` takes `hideTags`: the selected values are not rendered as tags inside the control (the host shows them elsewhere), the placeholder stays visible and Backspace no longer removes the last value. Selection is still announced through the options.
 - `Pagination` takes `showEdges` (first and last page buttons, `firstLabel`, `lastLabel`) and `showJump` (a typed page number, `jumpLabel`). Both are off by default. `page` is clamped to the page count only when `total` is known: while `total` is `0` or `loading` is set (it also sets `aria-busy`), the page is kept, so a server reload does not reset it.
 - `FilterPills` can list active filters: options with `removable: true` render as active pills with a remove button (`removeLabel`, a `'Remove {label}'` template). Clicking the pill emits `select(value)`, the button emits `remove(value)` (and drops the value from the model when it is selected); focus moves to the next pill when the removed one disappears.
 - `Calendar` takes `dayText: (iso) => string | undefined`, a short line under each day number that is also added to the day's accessible name (availability, prices). The `#day` slot (`{ date, number, text, selected, unavailable, outOfRange, inMonth }`) replaces the cell content; it is decorative, so announced text still comes from `dayText`. Days before `min` or after `max` get the `is-out-of-range` class (and `is-unavailable`, like days rejected by `isDateDisabled`), so the `--k-calendar-out-of-range-*` tokens style them apart from disabled days.
 - `Separator` takes `description` (or `#description`) under its label, and an `#actions` slot rendered next to them (a small add or edit button). `variant="heading"` (`SeparatorVariant`, `'label' | 'heading'`, default `'label'`) shows the label as a section title on its own (an `h3`, `level` changes it) with the description below and the actions at the end, under one line above instead of the small muted label between two lines. `:lines="false"` (default `true`) hides the lines of either variant. `align` (`SeparatorAlign`, `'start' | 'center'`, default `'start'`) centers the heading title and description. `--k-separator-heading-font-size` (0.9375rem) sizes the heading, `--k-separator-heading-color` (default `--k-text`) colors it, and `--k-separator-label-font-size` (0.75rem) sizes the small label of `variant="label"`, with or without lines.
 - `Modal` takes `width` (any CSS length, overrides `size`) and `minHeight` (keeps the height steady while tabs or steps change). The size widths are tokens: `--k-modal-width-sm` (26rem), `--k-modal-width-md` (32rem), `--k-modal-width-lg` (50rem), `--k-modal-width-xl` (64rem).
+- `Stepper` shows the steps of a wizard: `steps` (`StepperStep[]`: `value`, `label`, `description`, `icon`, `disabled`, `state` `'complete' | 'error'`) and `v-model` for the current value. It renders a `nav` (named by `label`, default "Progress") around an ordered list; the current step has `aria-current="step"`, every step carries a hidden "Step 2 of 4" (`stepper.position`, `positionLabel` overrides it) and its state ("completed", "has errors"). Clickable steps are buttons with one tab stop and arrow keys, Home and End between them. `linear` makes only completed steps (`state: 'complete'` or before the current one) and the current step clickable; `readonly` renders no buttons. `orientation="vertical"` stacks the steps; `size="sm"` is denser. `compact` is `'auto'` by default: below 36rem of container width the labels are visually hidden (still read) and a "Step 2 of 4 Columns" line shows the current step; `true` forces it, `false` turns it off. `select(step)` fires on a click before the model changes.
+
+```vue
+<KStepper v-model="step" :steps="steps" linear label="Import" />
+```
+
 - `Tabs` items take `dot: true` for a small indicator without a number (`dotTone`, default `danger`; `dotLabel` is the hidden text, default "Needs attention").
 - `DropdownMenu` takes `matchTriggerWidth` (the menu is at least as wide as its trigger) and `minWidth` (a CSS length).
 - `PageHeader` takes `align` (`'end'` by default, `'start'` or `'center'`) for the title block and the actions, and `truncate` to keep the title on one line with an ellipsis (the full title is in its `title` attribute).
@@ -384,6 +391,23 @@ Composables: `useTheme`, `usePreset`, `useForm`, `useField`, `useFieldControl`,
 - `FilterPills` is generic: the value type comes from the options, `multiple` makes the model an array and `required` drops `null` from it (like `SegmentedControl`). Options take `menu` items (a dropdown trigger showing `valueLabel`) or `panel: true`, which opens a popover with the `#panel-<value>` slot (`{ option, active, toggle, close }`, `panelLabel` names it). The `#pill` slot renders any trigger and its scope has `defaultPill`, a component that renders the built-in pill for that option, so one custom pill does not mean rewriting the others: `<component :is="defaultPill" v-else />`. `FilterPill` is exported so custom triggers match the other pills.
 - `SegmentedControl` with `required` narrows `v-model` to a non null value. Options take `title` (tooltip and description) and `muted`, and the `#option` slot replaces the content of each option.
 - `FileInput` takes `directory` (folder picker; dropped folders are walked, every file keeps its relative path) or `directory="drop"` (the click opens a file picker, dropped folders are still walked), `directoryAction` (an "Upload a folder" button under the dropzone, `directoryActionLabel` renames it) or the `#actions` slot (`{ browse, browseDirectory, disabled }`), `skipHidden` (ignores dot files and dot folders), `list: false` (no file list: picks and drops only emit `add`), `loading` and the `#hint` slot. `add` receives `(files, { entries: [{ file, path }], directories, source, event, dataTransfer })`; `directories` lists every folder path of a folder pick or drop, empty folders included, and `add` also fires for a drop of empty folders. `invalid` fires per file and `reject` once with every rejected file (`(events, detail)`). `acceptMode="hint"` only passes `accept` to the picker and leaves filtering to the host. The component exposes `browse()`, `browseDirectory()`, `addFiles()` and `focus()`.
+- `TagList` renders `v-model` (`TagListItem[]`: `value`, `label`, `tone`, `icon`, `removable`, `disabled`) as `Tag` chips in a labelled list (`label`, default "Items"). `removable` (or `removable` per item) adds the remove button; the chip is dropped from the model, `remove(item, index)` fires, focus moves to the neighbor and "Label removed" is announced. `sortable` reorders by pointer drag (the list updates live while dragging, Escape cancels), and the chips become one tab stop: the arrow keys, Home and End move between chips, Alt with an arrow key (or Alt with Home and End) moves the focused chip, Delete removes it, and every move is announced ("Name moved to position 2 of 4", `sortable.moved`). `moveButtons` adds "Move earlier" and "Move later" buttons to every chip, a single pointer alternative to dragging. A disabled item cannot move or be removed. `move({ item, from, to })` fires after each move. `accept` (a MIME type, a list of them, or `(event) => boolean`) makes the list a drop target for native drags from outside: an insertion marker follows the pointer and `itemDrop({ index, dataTransfer, event })` (`@item-drop`, named apart from the native `drop` event) gives the insertion index, so the host inserts the item (`dropEffect`, default `copy`, must match the `effectAllowed` of the source). The `#item` slot (`{ item, index }`) replaces the chip label.
+
+```vue
+<KTagList
+   v-model="columns"
+   label="Export columns"
+   sortable
+   removable
+   accept="application/x-column"
+   @item-drop="
+      ({ index, dataTransfer }) => insert(dataTransfer?.getData('application/x-column'), index)
+   "
+/>
+```
+
+- `useSortable(container, options)` is the reorder logic of `TagList` for any list. Options: `items` (a ref or getter), `onMove(items, move)` (`SortableMove`: `{ item, from, to, items, source }`, write `items` back to your state), `orientation` (`'vertical'` by default, `'horizontal'` for wrapping rows), `disabled`, `handle` (a selector: only a pointer down on it starts a drag; without it any pointer down outside buttons, links and inputs does), `canMove(item, index)`, `label(item)` and `movedText(move)` for the announcement. Bind `itemProps(index)` on each item element (the attribute marks it, plus pointer and Alt with arrow key handlers) and render `announcement` in a polite live region. `move(from, to, { announce })` moves from your own buttons, `dragging` is the index being dragged (for a lifted style), `canMove(index)` reports locked items. Pointer drags reorder live and follow the pointer, Escape or a cancelled pointer puts the item back, and the click after a drag is swallowed.
+
 - `useFileDrop` returns `{ over, reset }` and takes `ignore(event)`. A drop handled by a nested drop zone is skipped by the outer ones, and the state resets after any drop, even when a child stops propagation. `readDroppedFiles(dataTransfer)` walks dropped folders (call it synchronously in the drop handler) and resolves to `[{ file, path }]`; `readDroppedFiles(dataTransfer, { directories: true })` resolves to `{ files, directories }` with every folder path, empty ones included, and `skipHidden: true` leaves out dot entries.
 - `Tabs` items take `badgeTone` and `badgeLabel` (the accessible name of the badge); the `#panel="{ item }"` slot renders a single panel for the active tab. `stretch` makes the tabs fill the remaining height of a flex column and the active panel grow with it (`flex: 1; min-height: 0`), and `inset` spaces the tab list from the container edges with the panel flush below it, for inspectors and side panes. `Breadcrumbs` items take `attrs` and `onClick` (an item without a link renders a button, handy for drop targets), `#item` customizes the content, and `ancestors` links every item and ends with a separator (`breadcrumbsAncestors` on `PageHeader`). `Accordion` takes `variant` `card` (default), `outline` (the same card without a shadow), `separated` or `plain`; items take `description`, and `contentVariant="neutral"` drops the content padding and text styling.
 - `RichTextEditor` labels heading buttons by their real level (`headingLabel="relative"` numbers them from 1) and `toolbar` picks and orders the buttons: `['headings', '|', 'bold', 'italic', 'link']`.
@@ -428,6 +452,7 @@ const { loading: saving, run } = useLoadingState()
 await run(() => api.save(form))
 ```
 
+- Toasts stay clear of an open Drawer: next to a left or right drawer the stack moves beside the panel (by its width) when there is room for it, otherwise it moves above the drawer footer (or below the header for top positions), so the drawer actions stay visible and the toasts stay clickable. The same footer rule applies to a Modal whose footer sits under the toasts (a sheet or a fullscreen modal).
 - Toasts stack behind the newest one (up to `max`, default 4) and expand on hover or focus, which also pauses their timers. Each tone has its own icon; `description` takes a string or a list of lines. `dismissible: false` hides the close button, `duration: Infinity` keeps a toast open, `progress` on the toaster shows a timer bar.
 - `useConfirm()` resolves `true` or `false`, `useAlert()` resolves when closed, `usePrompt()` resolves the string or `null`. `useConfirm()` and `useAlert()` also take `body`, a component rendered under the description (for example a list of the pages that use a file). The body can emit `close` to dismiss the dialog as cancelled, for example when one of its links is clicked. Prompt options: `label`, `placeholder`, `value`, `type`, `required`, `requiredText`, `validate(value)` (return an error message to keep the dialog open), `onConfirm(value)`. Without a host they fall back to the native browser dialogs.
 - `modal.open(Component, props, options)` returns a promise for the result plus `id`, `close(result)` and `update(props)`. Options: `title`, `description`, `size`, `side` (drawers), `sheet`, `flush`, `dismissible`, `hideClose`, `closeLabel`, `as: 'modal' | 'drawer'`. Inside the component, `useModalContext<R>()` gives `close(result?)` and `setLoading(boolean)`. A component can open another modal on top; Escape and the backdrop resolve `undefined`. `modal.close(id?, result?)` and `modal.closeAll()` close from outside.
@@ -480,23 +505,24 @@ Ready defaults to start a dashboard project: an app frame, an auth frame and pag
 </KDashboardLayout>
 ```
 
-| Prop                                                                               | Default                         | Notes                                                                                                                                                                                                                                                                                                                                                      |
-| ---------------------------------------------------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `variant`                                                                          | `'inset'`                       | `inset` (canvas sidebar, inset content panel), `sidebar` (bordered sidebar, full bleed content), `floating` (raised sidebar card on the canvas).                                                                                                                                                                                                           |
-| `navigation`                                                                       |                                 | `NavItem[]` or `NavSection[]` (`{ label?, items }`). Items: `label`, `to`/`href`, `icon`, `badge`, `exact`, `active`, `external`, `disabled`, `children`.                                                                                                                                                                                                  |
-| `currentPath`                                                                      | router path                     | Active state is computed from the router (`$route`) with prefix matching (`/` and `exact` items match exactly).                                                                                                                                                                                                                                            |
-| `brandName`, `brandSubtitle`, `brandIcon`, `brandLogo`, `brandShowName`, `brandTo` | `brandTo: '/'`                  | `brandLogo` takes an image URL, inline SVG markup or a component; the name is hidden next to a logo unless `brandShowName`. Or the `#brand` slot.                                                                                                                                                                                                          |
-| `account`                                                                          |                                 | `{ name, email?, avatar?, role?, menu? }`. Shown as a row (avatar, name, email, chevron) at the bottom of the sidebar.                                                                                                                                                                                                                                     |
-| `accountAction`                                                                    | `'settings'`                    | `settings`: the row opens a `SettingsModal` (`settingsSections`, `settingsPresets`, `v-model:settings-open`, `v-model:settings-section`, `@sign-out`). `menu`: a DropdownMenu with `account.menu`, selections emit `account-select`. Or replace it with the `#account` slot.                                                                               |
-| `breadcrumbs`                                                                      |                                 | Rendered in the desktop topbar. `#topbar` replaces them, `#actions` adds buttons on the right.                                                                                                                                                                                                                                                             |
-| `search`                                                                           | `false`                         | `true` adds a CommandPalette with every navigation item, an array adds your own command groups, an async function `(query, signal) => CommandGroup<T>[]` searches on your server (item `data` reaches `#search-item` typed) (matching navigation items come first unless `searchNavigation` is `false`). `#search` replaces it.                            |
-| `searchProps`                                                                      |                                 | Options for the built-in CommandPalette: `minQueryLength`, `debounce`, `placeholder`, `label`, `emptyText` (a string or `(query) => string`), `minQueryText`, `errorText`, `loadingText`, `resultsText`, `notice`, `recentKey`, footer labels. Slots `#search-item`, `#search-empty`, `#search-group-label` and `#search-after-results` reach the palette. |
-| `themeSwitch`                                                                      | `false`                         | `'sidebar'`, `'topbar'` or `false`. The default keeps the theme choice only in the Appearance section of the settings modal. With `accountAction="menu"` there is no settings modal, so set `'sidebar'` or `'topbar'`.                                                                                                                                     |
-| `collapsible`, `v-model:collapsed`, `storageKey`                                   | `true`, `'k-sidebar-collapsed'` | Icon rail on desktop. Persisted in a cookie under Nuxt (rendered on the server, no flash) or `localStorage` elsewhere. `false` disables persistence.                                                                                                                                                                                                       |
-| `shortcut`                                                                         | `'mod+b'`                       | Toggles the rail on desktop and the drawer on mobile. `searchShortcut` defaults to `mod+k`.                                                                                                                                                                                                                                                                |
-| `v-model:open`                                                                     | `false`                         | Mobile drawer (below 768px of shell width): scrim, focus moves into the drawer, the content is `inert`, Escape and the scrim close it and focus returns to the burger.                                                                                                                                                                                     |
-| `fluid`, `viewTransition`                                                          | `false`, `true`                 | Full width content; `view-transition-name` on sidebar and panel so page transitions keep the frame still.                                                                                                                                                                                                                                                  |
-| `fill`                                                                             | `false`                         | Full height, full bleed content: no padding, gap or max width, and the content fills the panel (a page that is one DataGrid with `height="100%"`). Also on `AppShell`; in the `k-dashboard` layout per page with `definePageMeta({ fill: true })` or for every page with `dashboard.fill`.                                                                 |
+| Prop                                                                               | Default                         | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ---------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `variant`                                                                          | `'inset'`                       | `inset` (canvas sidebar, inset content panel), `sidebar` (bordered sidebar, full bleed content), `floating` (raised sidebar card on the canvas).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `navigation`                                                                       |                                 | `NavItem[]` or `NavSection[]` (`{ label?, items }`). Items: `label`, `to`/`href`, `icon`, `badge`, `exact`, `active`, `external`, `disabled`, `children`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `currentPath`                                                                      | router path                     | Active state is computed from the router (`$route`) with prefix matching (`/` and `exact` items match exactly).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `brandName`, `brandSubtitle`, `brandIcon`, `brandLogo`, `brandShowName`, `brandTo` | `brandTo: '/'`                  | `brandLogo` takes an image URL, inline SVG markup or a component; the name is hidden next to a logo unless `brandShowName`. Or the `#brand` slot.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `account`                                                                          |                                 | `{ name, email?, avatar?, role?, menu? }`. Shown as a row (avatar, name, email, chevron) at the bottom of the sidebar.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `accountAction`                                                                    | `'settings'`                    | `settings`: the row opens a `SettingsModal` (`settingsSections`, `settingsPresets`, `v-model:settings-open`, `v-model:settings-section`, `@sign-out`). `menu`: a DropdownMenu with `account.menu`, selections emit `account-select`. Or replace it with the `#account` slot.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `breadcrumbs`                                                                      |                                 | Rendered in the desktop topbar. `#topbar` replaces them, `#actions` adds buttons on the right.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `search`                                                                           | `false`                         | `true` adds a CommandPalette with every navigation item, an array adds your own command groups, an async function `(query, signal) => CommandGroup<T>[]` searches on your server (item `data` reaches `#search-item` typed) (matching navigation items come first unless `searchNavigation` is `false`). `#search` replaces it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `searchProps`                                                                      |                                 | Options for the built-in CommandPalette: `minQueryLength`, `debounce`, `placeholder`, `label`, `emptyText` (a string or `(query) => string`), `minQueryText`, `errorText`, `loadingText`, `resultsText`, `notice`, `recentKey`, footer labels. Slots `#search-item`, `#search-empty`, `#search-group-label` and `#search-after-results` reach the palette.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `themeSwitch`                                                                      | `false`                         | `'sidebar'`, `'topbar'` or `false`. The default keeps the theme choice only in the Appearance section of the settings modal. With `accountAction="menu"` there is no settings modal, so set `'sidebar'` or `'topbar'`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `collapsible`, `v-model:collapsed`, `storageKey`                                   | `true`, `'k-sidebar-collapsed'` | Icon rail on desktop. Persisted in a cookie under Nuxt (rendered on the server, no flash) or `localStorage` elsewhere. `false` disables persistence.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `shortcut`                                                                         | `'mod+b'`                       | Toggles the rail on desktop and the drawer on mobile. `searchShortcut` defaults to `mod+k`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `v-model:open`                                                                     | `false`                         | Mobile drawer (below 768px of shell width): scrim, focus moves into the drawer, the content is `inert`, Escape and the scrim close it and focus returns to the burger.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `fluid`, `viewTransition`                                                          | `false`, `true`                 | Full width content; `view-transition-name` on sidebar and panel so page transitions keep the frame still.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `fill`                                                                             | `false`                         | Full height, full bleed content (the same as `content="bleed"`): no padding, gap or max width, and the content fills the panel (a page that is one DataGrid with `height="100%"`). Also on `AppShell`; in the `k-dashboard` layout per page with `definePageMeta({ fill: true })` or for every page with `dashboard.fill`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `content`                                                                          | `'page'`                        | Content layout (`ShellContent`). `page`: max width (`--k-shell-content`, 72rem), padding, the panel scrolls. `fill`: full width and full height with the normal padding and gap; the panel never scrolls and the content is a flex column with `min-height: 0`, so a child with `flex: 1` (a `DataGrid` with `fill`, `Tabs` with `stretch`, a `.k-page` root) takes the rest of the height. `centered`: the same full height, with the width kept at `--k-shell-content` and centered. `bleed`: full width and height without padding or gap. `fill` (boolean) is an alias of `bleed` and `fluid` removes the max width of `page`; `content` wins over both. Also on `AppShell`; in the `k-dashboard` layout per page with `definePageMeta({ content: 'fill' })` (typed) or for every page with `dashboard.content` in the app config. |
 
 Slots: `brand`, `search`, `sidebar` (replaces the navigation), `sidebar-footer`, `account`, `topbar-brand`, `topbar`, `actions`, default, plus `settings-section-<id>`, `settings-actions-<id>` and `settings-account-fields`, forwarded to the SettingsModal. The exposed `openSettings(id?)` opens it on a section. Landmarks: skip link, `aside` and `nav` with labels, `main` with an id, `aria-current="page"` on the active link. `SidebarNav` (layout group) renders the same navigation data inside your own `Sidebar`.
 
@@ -689,7 +715,7 @@ Accessibility related props and defaults:
 - `DataGrid` `showEdges` and `showJump` reach the footer pager (first and last page buttons, page number input). `loading` also keeps the pager from resetting the page while a server total is unknown.
 - `DataGrid` registers the AG Grid cell editors (text, large text, number, date, checkbox, select, custom and undo/redo) when `editable` is set or when a column or `gridOptions.defaultColDef` has `editable` at mount. `registerGridEditorModules()` from `/grid` does it by hand, before the first grid mounts, for columns that become editable later.
 - `ImageCell` takes `fit` (`'cover'` default, or `'contain'` for logos) and `size` (any CSS length, default `1.75rem`) in `cellRendererParams`. `EmptyCell` (the hidden "Empty" dash) is exported from `/grid` for custom renderers.
-- `BadgeCell` takes `variant` (`BadgeVariant`, `'soft' | 'solid' | 'outline'`) in `cellRendererParams`: set, the cell renders a `KBadge` with that variant and the resolved tone (`size`, `BadgeSize`, default `'sm'`); unset keeps the compact grid pill. `badgeClass` (`string | ((value, data) => string | undefined)`) adds host classes to the badge, to set the per instance badge tokens (`--k-badge-background`, `--k-badge-color`, `--k-badge-border-color`, which the grid pill also reads) for values outside `Tone`. `BadgeCellParams<T>` types the row of `data`.
+- `BadgeCell` takes `variant` (`BadgeVariant`, `'soft' | 'solid' | 'outline'`) in `cellRendererParams`: set, the cell renders a `KBadge` with that variant and the resolved tone (`size`, `BadgeSize`, default `'sm'`); unset keeps the compact grid pill. `badgeClass` (`string | ((value, data) => string | undefined)`) adds host classes to the badge, to set the per instance badge tokens (`--k-badge-background`, `--k-badge-color`, `--k-badge-border-color`, which the grid pill also reads) for values outside `Tone`. `BadgeCellParams<T>` types the row of `data`. When the value is an array, the cell renders one badge per item (each item resolves its own `tones`, `labels` and `badgeClass`), on one line clipped to the cell, with the full list in the `title` attribute. `max` (a number) shows the first items and a `+N` badge for the rest (announced as "N more", `grid.moreValues`); `wrap: true` lets the badges wrap onto more lines (pair it with `autoHeight` on the column). Give an array column a `valueFormatter` (`(params) => params.value.join(', ')`): AG Grid infers an object type for arrays and uses the formatter for export, copy and the quick filter. Single values render as before.
 - `DataGrid` `spreadsheet` turns on Excel like editing on AG Grid Community (no Enterprise modules): it registers the editor modules and the AG Grid `ScrollApiModule` (`registerGridSpreadsheetModules()` from `/grid` does it by hand) and leaves the normal grid unchanged when it is off. Set `rowIdKey` or `getRowId`: changes, dirty cells and undo refer to row ids, never to indexes.
    - Selection: click selects a cell; drag, Shift+click and Shift+arrows extend a rectangular range (Shift+Cmd/Ctrl+arrow to the edge); Cmd/Ctrl+A selects every cell. The range follows the displayed row order (after sort, filter and quick search) and the displayed column order; the row selection checkbox column is not part of it. Escape collapses the range to the active cell.
    - Keyboard: arrows and Tab move the active cell, Enter, F2 or typing start the AG Grid editor, Escape cancels it. While an editor (or any input) has focus no shortcut fires.

package/dist/components/data/Tag.vue

@@ -19,6 +19,7 @@
          :aria-label="removeText"
          :title="removeText"
          :disabled="disabled"
+         :tabindex="removeTabindex"
          @click="onRemove"
          @keydown="onKeydown"
       >
@@ -40,6 +41,7 @@ const props = defineProps({
   icon: { type: null, required: false },
   removable: { type: Boolean, required: false },
   removeLabel: { type: String, required: false },
+  removeTabindex: { type: Number, required: false },
   disabled: { type: Boolean, required: false }
 });
 const { t, locale } = useLocale();

package/dist/components/data/Tag.vue.d.ts

@@ -12,6 +12,7 @@ declare const __VLS_base: import("vue").DefineComponent<{
     icon?: IconName;
     removable?: boolean;
     removeLabel?: string;
+    removeTabindex?: number;
     disabled?: boolean;
     key?: PropertyKey | undefined;
     prefix?: string | undefined | undefined;
@@ -214,6 +215,7 @@ declare const __VLS_base: import("vue").DefineComponent<{
     icon?: IconName;
     removable?: boolean;
     removeLabel?: string;
+    removeTabindex?: number;
     disabled?: boolean;
     key?: PropertyKey | undefined;
     prefix?: string | undefined | undefined;

package/dist/components/data/TagList.vue

@@ -0,0 +1,239 @@
+<template>
+   <div
+      ref="root"
+      class="k-tag-list"
+      :class="{
+  'is-sortable': canSort,
+  'is-dragging': sorter.dragging.value !== null,
+  'is-drop-target': dropIndex !== null,
+  'is-empty': !items.length,
+  'is-disabled': disabled
+}"
+      @dragenter="onDragEnter"
+      @dragover="onDragOver"
+      @dragleave="onDragLeave"
+      @drop="onDrop"
+   >
+      <ul
+         v-if="items.length"
+         ref="list"
+         class="k-tag-list-items"
+         :aria-label="labelText"
+         :aria-describedby="hintText ? hintId : void 0"
+      >
+         <li
+            v-for="(item, index) in items"
+            :key="item.value"
+            class="k-tag-list-item"
+            :class="{
+  'is-moving': sorter.dragging.value === index,
+  'is-locked': canSort && !sorter.canMove(index)
+}"
+            :data-drop="dropIndex === index ? 'before' : void 0"
+            :tabindex="canSort ? index === focusIndex ? 0 : -1 : void 0"
+            v-bind="canSort ? sorter.itemProps(index) : void 0"
+            @focus="focusIndex = index"
+            @keydown="onItemKeydown($event, index)"
+         >
+            <Tag
+               :label="item.label"
+               :tone="item.tone ?? tone"
+               :icon="item.icon"
+               :size="size"
+               :removable="isRemovable(item)"
+               :remove-label="removeLabel"
+               :remove-tabindex="canSort ? -1 : void 0"
+               :disabled="disabled || item.disabled"
+               @remove="remove(index)"
+            >
+               <slot name="item" :item="item" :index="index">{{ item.label }}</slot>
+            </Tag>
+            <span v-if="canSort && moveButtons" class="k-tag-list-move">
+               <Button
+                  variant="ghost"
+                  tone="neutral"
+                  size="xs"
+                  icon="chevron-left"
+                  tabindex="-1"
+                  :aria-label="t('tagList.moveEarlier', { label: item.label })"
+                  :title="t('tagList.moveEarlier', { label: item.label })"
+                  :disabled="index === 0 || !sorter.canMove(index)"
+                  @click="moveBy(index, -1)"
+               />
+               <Button
+                  variant="ghost"
+                  tone="neutral"
+                  size="xs"
+                  icon="chevron-right"
+                  tabindex="-1"
+                  :aria-label="t('tagList.moveLater', { label: item.label })"
+                  :title="t('tagList.moveLater', { label: item.label })"
+                  :disabled="index === items.length - 1 || !sorter.canMove(index)"
+                  @click="moveBy(index, 1)"
+               />
+            </span>
+         </li>
+         <li
+            v-if="dropIndex !== null && dropIndex >= items.length"
+            class="k-tag-list-end"
+            data-drop="before"
+            aria-hidden="true"
+         />
+      </ul>
+      <p v-else class="k-tag-list-empty">
+         <slot name="empty">{{ emptyLabel }}</slot>
+      </p>
+      <span v-if="hintText" :id="hintId" class="k-visually-hidden">{{ hintText }}</span>
+      <LiveRegion :message="liveText" />
+   </div>
+</template>
+
+<script setup>
+import { computed, nextTick, ref, useId, useTemplateRef, watch } from "vue";
+import { useLocale } from "../../composables/useLocale";
+import { useSortable } from "../../composables/useSortable";
+import LiveRegion from "../../internal/core/LiveRegion.vue";
+import { useLiveMessage } from "../../internal/core/live";
+import { focusStable } from "../../internal/core/focus";
+import { rovingIndex } from "../../internal/core/roving";
+import { insertionIndex, isRtl, sortableElements } from "../../internal/data/sortable";
+import Button from "../core/Button.vue";
+import Tag from "./Tag.vue";
+const props = defineProps({
+  label: { type: String, required: false },
+  sortable: { type: Boolean, required: false },
+  removable: { type: Boolean, required: false },
+  moveButtons: { type: Boolean, required: false },
+  accept: { type: [String, Array, Function], required: false },
+  dropEffect: { type: String, required: false, default: "copy" },
+  tone: { type: String, required: false, default: "neutral" },
+  size: { type: String, required: false, default: "md" },
+  disabled: { type: Boolean, required: false },
+  emptyText: { type: String, required: false },
+  removeLabel: { type: String, required: false }
+});
+const model = defineModel({ type: Array, ...{ default: () => [] } });
+const emit = defineEmits(["remove", "move", "itemDrop"]);
+defineSlots();
+const { t } = useLocale();
+const hintId = `${useId()}-hint`;
+const root = useTemplateRef("root");
+const list = useTemplateRef("list");
+const focusIndex = ref(0);
+const dropIndex = ref(null);
+const removal = useLiveMessage();
+const items = computed(() => model.value);
+const canSort = computed(() => props.sortable && !props.disabled);
+const labelText = computed(() => props.label ?? t("tagList.label"));
+const emptyLabel = computed(() => props.emptyText ?? t("tagList.empty"));
+const hintText = computed(() => {
+  const parts = [];
+  if (canSort.value) parts.push(t("tagList.sortHint"));
+  if (canSort.value && items.value.some(isRemovable)) parts.push(t("tagList.removeHint"));
+  return parts.join(". ");
+});
+function isRemovable(item) {
+  return !props.disabled && !item.disabled && (item.removable ?? props.removable ?? false);
+}
+const sorter = useSortable(list, {
+  items,
+  orientation: "horizontal",
+  disabled: () => !canSort.value,
+  canMove: (item) => !item.disabled,
+  label: (item) => item.label,
+  onMove: (next, move) => {
+    model.value = next;
+    focusIndex.value = move.to;
+    emit("move", { item: move.item, from: move.from, to: move.to });
+  }
+});
+const liveText = computed(() => removal.message.value || sorter.announcement.value);
+watch(
+  () => items.value.length,
+  (length) => {
+    if (focusIndex.value >= length) focusIndex.value = Math.max(0, length - 1);
+  }
+);
+function itemElement(index) {
+  return list.value?.querySelectorAll(":scope > .k-tag-list-item")[index] ?? null;
+}
+function moveBy(index, delta) {
+  sorter.move(index, index + delta, { announce: true, source: "api" });
+}
+function remove(index) {
+  const item = items.value[index];
+  if (!item || !isRemovable(item)) return;
+  const hadFocus = Boolean(root.value?.contains(document.activeElement));
+  const next = items.value.filter((_, position) => position !== index);
+  model.value = next;
+  emit("remove", item, index);
+  removal.announce(t("tagList.removed", { label: item.label }));
+  if (!hadFocus) return;
+  const target = Math.min(index, next.length - 1);
+  focusIndex.value = Math.max(0, target);
+  nextTick(() => {
+    const element = target >= 0 ? itemElement(target) : null;
+    const focusable = canSort.value ? element : element?.querySelector(".k-tag-remove:not(:disabled)");
+    if (focusable) focusable.focus({ preventScroll: true });
+    else if (root.value) focusStable(root.value);
+  });
+}
+function onItemKeydown(event, index) {
+  if (!canSort.value || event.target !== event.currentTarget) return;
+  if (event.altKey) return;
+  if (event.key === "Delete" || event.key === "Backspace") {
+    event.preventDefault();
+    remove(index);
+    return;
+  }
+  const rtl = isRtl(root.value);
+  const key = rtl && event.key === "ArrowLeft" ? "ArrowRight" : rtl && event.key === "ArrowRight" ? "ArrowLeft" : event.key;
+  const target = rovingIndex(key, index, items.value.length, "both");
+  if (target === null) return;
+  event.preventDefault();
+  focusIndex.value = target;
+  itemElement(target)?.focus();
+}
+function accepts(event) {
+  const accept = props.accept;
+  if (!accept || props.disabled) return false;
+  if (typeof accept === "function") return accept(event);
+  const types = Array.from(event.dataTransfer?.types ?? []);
+  return (Array.isArray(accept) ? accept : [accept]).some((type) => types.includes(type));
+}
+function dropTarget(event) {
+  if (!items.value.length) return 0;
+  const elements = sortableElements(list.value);
+  const targets = elements.length ? elements : Array.from(list.value?.querySelectorAll(":scope > .k-tag-list-item") ?? []);
+  return insertionIndex(targets, event.clientX, event.clientY, "horizontal", isRtl(root.value));
+}
+let dragDepth = 0;
+function resetDrop() {
+  dragDepth = 0;
+  dropIndex.value = null;
+}
+function onDragEnter(event) {
+  if (!accepts(event)) return;
+  event.preventDefault();
+  dragDepth++;
+}
+function onDragOver(event) {
+  if (!accepts(event)) return;
+  event.preventDefault();
+  if (event.dataTransfer) event.dataTransfer.dropEffect = props.dropEffect;
+  const index = dropTarget(event);
+  if (dropIndex.value !== index) dropIndex.value = index;
+}
+function onDragLeave(event) {
+  if (!accepts(event)) return;
+  dragDepth = Math.max(0, dragDepth - 1);
+  if (!dragDepth) dropIndex.value = null;
+}
+function onDrop(event) {
+  if (!accepts(event)) return;
+  event.preventDefault();
+  const index = dropIndex.value ?? dropTarget(event);
+  resetDrop();
+  emit("itemDrop", { index, dataTransfer: event.dataTransfer, event });
+}
+</script>

package/dist/components/data/TagList.vue.d.ts

@@ -0,0 +1,53 @@
+import type { Tone } from '../core/types';
+import type { BadgeSize, TagListAccept, TagListDrop, TagListItem } from './types';
+declare const __VLS_export: <T extends TagListItem>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+    props: import("vue").PublicProps & __VLS_PrettifyLocal<({
+        label?: string;
+        sortable?: boolean;
+        removable?: boolean;
+        moveButtons?: boolean;
+        accept?: TagListAccept;
+        dropEffect?: "copy" | "move" | "link";
+        tone?: Tone;
+        size?: BadgeSize;
+        disabled?: boolean;
+        emptyText?: string;
+        removeLabel?: string;
+    } & {
+        modelValue?: T[];
+    }) & {
+        onRemove?: ((item: T, index: number) => any) | undefined;
+        onMove?: ((move: {
+            item: T;
+            from: number;
+            to: number;
+        }) => any) | undefined;
+        "onUpdate:modelValue"?: ((value: T[]) => any) | undefined;
+        onItemDrop?: ((drop: TagListDrop) => any) | undefined;
+    } & Partial<import("vue").HTMLAttributes & import("vue").ReservedProps>> & (typeof globalThis extends {
+        __VLS_PROPS_FALLBACK: infer P;
+    } ? P : {});
+    expose: (exposed: {}) => void;
+    attrs: any;
+    slots: {
+        item?: (props: {
+            item: T;
+            index: number;
+        }) => unknown;
+        empty?: () => unknown;
+    };
+    emit: (((evt: "remove", item: T, index: number) => void) & ((evt: "move", move: {
+        item: T;
+        from: number;
+        to: number;
+    }) => void) & ((evt: "itemDrop", drop: TagListDrop) => void)) & ((event: "update:modelValue", value: T[]) => void);
+}>) => import("vue").VNode & {
+    __ctx?: NonNullable<Awaited<typeof __VLS_setup>>;
+};
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_PrettifyLocal<T> = (T extends any ? {
+    [K in keyof T]: T[K];
+} : {
+    [K in keyof T as K]: T[K];
+}) & {};

package/dist/components/data/index.d.ts

@@ -9,6 +9,7 @@ export { default as SelectionBar } from './SelectionBar.vue';
 export { default as Stat } from './Stat.vue';
 export { default as Table } from './Table.vue';
 export { default as Tag } from './Tag.vue';
+export { default as TagList } from './TagList.vue';
 export { default as Timeline } from './Timeline.vue';
 export { default as Tree } from './Tree.vue';
 export type * from './types';

package/dist/components/data/index.mjs

@@ -9,6 +9,7 @@ export { default as SelectionBar } from "./SelectionBar.vue";
 export { default as Stat } from "./Stat.vue";
 export { default as Table } from "./Table.vue";
 export { default as Tag } from "./Tag.vue";
+export { default as TagList } from "./TagList.vue";
 export { default as Timeline } from "./Timeline.vue";
 export { default as Tree } from "./Tree.vue";
 export { applyTreeMove } from "../../internal/data/tree.mjs";

package/dist/components/data/types.d.ts

@@ -1,4 +1,5 @@
 import type { Tone } from '../core/types';
+import type { IconName } from '../../composables/useIcons';
 import type { MenuItems } from '../overlays/types';
 export type BadgeVariant = 'soft' | 'solid' | 'outline';
 export type BadgeSize = 'sm' | 'md';
@@ -94,3 +95,17 @@ export interface FilterPillOption<T extends FilterPillValue = FilterPillValue> {
     removable?: boolean;
 }
 export type SelectionBarPlacement = 'inline' | 'sticky' | 'floating';
+export interface TagListItem {
+    value: string | number;
+    label: string;
+    tone?: Tone;
+    icon?: IconName;
+    removable?: boolean;
+    disabled?: boolean;
+}
+export interface TagListDrop {
+    index: number;
+    dataTransfer: DataTransfer | null;
+    event: DragEvent;
+}
+export type TagListAccept = string | string[] | ((event: DragEvent) => boolean);