@xleddyl/443-components-vue 0.10.2 → 0.12.0

package/README.md

@@ -136,7 +136,7 @@ A few component tokens are unset by default and only exist to be overridden on a
 | Fields         | `--k-field-padding-x`                                                                                                                                                                                                                                                                                                                                         |
 | Overlays       | `--k-modal-radius`, `--k-modal-shadow`, `--k-drawer-radius`, `--k-drawer-shadow`, `--k-popover-radius`, `--k-popover-shadow`, `--k-toast-radius`, `--k-toast-shadow`, `--k-scrim-blur` (3px)                                                                                                                                                                  |
 | Tooltip        | `--k-tooltip-background`, `--k-tooltip-text`, `--k-tooltip-border`, `--k-tooltip-radius`, `--k-tooltip-shadow`, `--k-tooltip-padding`                                                                                                                                                                                                                         |
-| Shell          | `--k-sidebar-width` (15rem), `--k-sidebar-rail-width`, `--k-topbar-height` (3rem), `--k-shell-inset`, `--k-shell-padding`, `--k-shell-content`                                                                                                                                                                                                                |
+| Shell          | `--k-sidebar-width` (16.5rem), `--k-sidebar-rail-width`, `--k-topbar-height` (3rem), `--k-shell-inset`, `--k-shell-padding`, `--k-shell-content`                                                                                                                                                                                                              |
 | Switch         | `--k-switch-track-width`, `--k-switch-track-height`, `--k-switch-thumb-size` (md size)                                                                                                                                                                                                                                                                        |
 | Separator      | `--k-separator-heading-font-size` (0.9375rem), `--k-separator-heading-color` (`--k-text`), `--k-separator-label-font-size` (0.75rem)                                                                                                                                                                                                                          |
 | Calendar       | `--k-calendar-day-radius`, `--k-calendar-unavailable-color`, `--k-calendar-unavailable-decoration` (line-through), `--k-calendar-unavailable-opacity` (0.6), `--k-calendar-out-of-range-color`, `--k-calendar-out-of-range-decoration`, `--k-calendar-out-of-range-opacity` (each defaults to its unavailable token)                                          |
@@ -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`, `useRouteState`, `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.
@@ -450,9 +475,47 @@ const confirmDiscard = () => !dirty.value || confirm({ title: 'Discard changes?'
 ```
 
 - `#title-trailing` puts badges or a status next to the title without replacing `#header`.
+- `#actions` (`{ close }`) puts buttons in the header, on the right before the close button (an edit or a more menu), without replacing `#header`.
 - `size="fullscreen"` on a Modal fills the viewport edge to edge (no radius, no outer padding, safe area insets inside the panel) and never turns into a bottom sheet.
 - Overlays reset the field context: controls inside a Modal, Drawer, CommandPalette, menu, Popover or HoverCard panel do not inherit the id, description or invalid state of a `FormField` that contains the trigger. Call `provideFieldBoundary()` in your own overlay components to do the same.
 
+### Deep links
+
+`useRouteState(key, options?)` binds a ref to one query parameter of the current URL, so any Drawer or Modal can be opened from a link, survives a reload and closes with the browser back button. It reads the router through `$router` (vue-router or Nuxt, no import of either); without a router it is a plain ref.
+
+```ts
+const familyId = useRouteState('family')
+```
+
+```vue
+<KButton icon="plus" @click="familyId = 'new'">New family</KButton>
+<KDrawer
+   :open="!!familyId"
+   :title="familyId === 'new' ? 'New family' : family?.name"
+   @update:open="familyId = undefined"
+>
+   <FamilyForm :id="familyId === 'new' ? undefined : familyId" />
+</KDrawer>
+```
+
+- Reading: the initial value comes from the URL (on the server too, so SSR renders the same state), and the ref follows every later route change (back, forward, links).
+- Writing: setting the ref navigates with `router.push` (default) or `router.replace` (`history: 'replace'`, for filters or tabs that should not add history entries). The path and the other query parameters stay. `undefined`, `null` and `''` remove the parameter. Several refs changed in the same tick make one navigation. A push that returns to the previous history entry goes back instead (`router.back()`), so opening then closing a drawer leaves the history as it was, and the browser back button and the in-app close button agree.
+- Types: `parse(value)` and `serialize(value)` convert the string (`parse` returning `undefined` means no value). `default` gives the value when the parameter is missing, and setting the default removes the parameter:
+
+```ts
+const page = useRouteState('page', { parse: Number, default: 1, history: 'replace' })
+const archived = useRouteState('archived', {
+   parse: (value) => value === '1',
+   serialize: (value) => (value ? '1' : undefined),
+   default: false,
+})
+```
+
+- Create forms: use a reserved value (`?family=new`) and branch on it, like above.
+- Nested views inside one overlay: keep the path in one parameter (`?settings=users/usr_123`, `?family=fam_1/variants`) and split it on `/` in a computed. One parameter keeps every step in one history entry and avoids two refs racing. Encode ids that may contain `/` with `encodeURIComponent` per segment.
+- Pages that set `definePageMeta({ key: (route) => route.fullPath })` remount on every query change; keep the default page key for pages with deep links.
+- To leave the page from inside an overlay, navigate (a link or `router.push`): the new route has no parameter, so the overlay closes. Do not set the ref to `undefined` and navigate in the same tick: the later navigation cancels the earlier one.
+
 `CommandPalette`: items take typed `data` (`CommandItem<T>`, `CommandGroup<T>`), which reaches the `#item` slot and the `select` event typed; `emptyText` also takes `(query) => string`. Groups take a `description` (shown after the label), the `#group-label` slot (`{ group, label, description, recent }`) replaces the label, and `notice` or the `#after-results` slot (`{ query, count }`) adds a line under the results, for example "Showing the first results".
 
 - `Brand`: `logo` takes an image URL, trusted inline SVG markup (`'<svg ...>'`) or a component; the `#logo` slot replaces the boxed mark; `show-name` keeps the name visible next to a logo.
@@ -480,23 +543,25 @@ 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. `brandAlign` (`'start'` or `'center'`) centers the brand in the expanded sidebar, with the collapse button on the right. The collapse button uses the icons `sidebar-collapse` and `sidebar-expand` (chevrons by default), so `k.icons.aliases: { 'sidebar-collapse': 'lucide:panel-left-close', 'sidebar-expand': 'lucide:panel-left-open' }` changes only that button.                                                                                                                                                                                                                                                                                                             |
+| `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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `settingsRoute`, `settingsResolvePage`                                             | `false`                         | Sync the settings modal with the URL (`?settings=users/usr_123`): `true` uses the key `settings`, a string sets the key. `settingsResolvePage(section, id, parents)` gives the label of a subpage restored from the URL. See SettingsModal.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `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`.
 
@@ -533,7 +598,9 @@ A large dialog (60rem) with a section nav on the left and the content on the rig
 - Built-in sections, used when no `#section-<id>` slot fills them: `account` (profile card, your `#account-fields`, a sign out button) and `appearance` (`AppearanceSettings`: theme cards light, dark, system and preset cards; `presets` limits or hides them).
 - `@sign-out` adds a Sign out item at the bottom of the nav and in the account section.
 - Labels: `title` (accessible name of the dialog, default `Settings`), `closeLabel`, `navLabel`, `signOutLabel`, `accountLabel`, `accountText`, `appearanceLabel`, `appearanceText`, `sessionLabel`, `sessionText`, `themeLabel`, `themeText`, `presetLabel`, `presetText`.
+- Header actions: `#actions-<id>` renders buttons on the right of the section header row (an "Add user" button), next to the title instead of on a row of its own in the body. It stays there when a subpage is open, so render different actions per page from its `page` prop. When the content is too narrow, the actions wrap under the title. On `DashboardLayout` the slot is `#settings-actions-<id>`.
 - Subpages: `#section-<id>` and `#actions-<id>` get `page`, `pages`, `openPage({ id, label })` and `back()`. With a page open, the header title becomes the path (`Members > Grace Hopper`, same size, only the last part in the text color, earlier parts are buttons that go back to them), the section description stays, and a Back button (`backLabel`, default `common.back`) shows on the right before `#actions-<id>`. `v-model:pages` binds the stack (it also works unbound). Changing section clears it. Render the detail when `page` is set, the list otherwise.
+- Deep links: `route` (`true` for the key `settings`, or your own query key, default `false`) syncs the open state, the section and the subpage stack with the URL: `?settings=users` for a section, `?settings=users/usr_123` for a subpage, deeper pages add segments. Opening, switching section, opening a subpage, Back and the crumbs push history entries, so the browser back button steps back through them and finally closes the dialog; closing removes the parameter. Loading a URL with the parameter opens the dialog at that section and subpage after mount. A section id that is not selectable falls back to the first section and the URL is corrected with `replace`. The URL holds only page ids, so `resolvePage(section, id, parents)` returns the label of a page restored from the URL: a string, `undefined` (the page and the ones after it are dropped, the URL is corrected) or a promise of either (the page opens at once with an empty label, then the label fills in). Without `resolvePage` the label is the id. Pages opened with `openPage` keep their own label. Link sections (`to`) do not close the dialog themselves when the route is synced: the navigation drops the parameter and closes it. On `DashboardLayout` the props are `settingsRoute` and `settingsResolvePage`; in the `k-dashboard` layout `settings.route` in `app.config`.
 - `hide-session` hides the Session group (sign out) in the account section; the Sign out item in the nav stays. `beforeClose` works as on Modal.
 - Accessibility: native modal `<dialog>` (focus trap, Escape, focus returns to the trigger), the nav is a labelled `nav` of buttons with `aria-current` and `aria-controls`, the content is a `section` labelled by its heading.
 
@@ -635,7 +702,7 @@ export default defineAppConfig({
 })
 ```
 
-The account row opens the SettingsModal (`account.action: 'menu'` with `account.menu` for a dropdown instead). Sections from `app.config` can be built-ins or links (`to`); `settings.presets` limits the preset cards, `settings.signOutTo` adds Sign out.
+The account row opens the SettingsModal (`account.action: 'menu'` with `account.menu` for a dropdown instead). Sections from `app.config` can be built-ins or links (`to`); `settings.presets` limits the preset cards, `settings.signOutTo` adds Sign out, `settings.route` (`true` or a query key) syncs the modal with the URL (see SettingsModal, deep links).
 
 Pages pick them with `definePageMeta({ layout: 'k-dashboard', title: 'Items' })` or `layout: 'k-auth'` (the auth card shows `title` and `description` from the page meta). Both layouts set the document title from `meta.title` and the brand name (`Items · Acme`; a page's own `useHead({ title })` wins) and announce route changes through a polite live region, unless the app already renders `<NuxtRouteAnnouncer />`. Breadcrumbs come from `meta.breadcrumbs`, otherwise from the matching navigation item (plus `meta.title` on deeper pages). At runtime `useDashboard().value = { account, breadcrumbs, badges: { '/items': 12 } }` overrides the account, the breadcrumbs and the badges. Set it in route middleware (`definePageMeta({ middleware })`) or a plugin, not in the page `setup`: the layout renders the sidebar and breadcrumbs before the page, so a value set during the page render would differ between the server HTML and hydration.
 
@@ -682,6 +749,23 @@ Accessibility related props and defaults:
 - `DataGrid` sort is a model: `v-model:sort` (`{ column, direction } | null`) sets the sorted column from outside (server side sort, a sort restored from the URL) and follows header clicks. Leave it unset for an uncontrolled grid. `sortChange` still fires with `serverSort`.
 - `DataGrid` takes `rowHeight` and `headerHeight` (pixels) for an exact row size on top of `density`, and `headerText: (field, column) => string | undefined` to name every column that has a `field` and no `headerName` (from your i18n).
 - `DataGrid` `filterable` registers the AG Grid text, number and date filters (`registerGridFilterModules()` does it without the prop) and turns `filter` on for every column. `filterChange(model, event)` fires with `api.getFilterModel()` whenever a column filter changes, also when the filters come from `gridOptions` or your own registered modules.
+- `DataGrid` `#filters` slot: put your own filter controls (Select, Combobox, DateInput bound with `v-model`) in it and the toolbar shows a square funnel button right after the search input (at the start with `:searchable="false"`), before the `actions`. The button opens a `Modal` titled "Filters" that hosts the slot, so the filters still apply live; its footer has "Reset filters" (emits `filtersReset`, disabled while `filterCount` is 0) and "Show results" (closes it). `filterCount` shows the number of active filters as a badge on the button and in its accessible name ("Filters, 2 active", `grid.filtersActive`). Slot props: `{ close, count }`. Focus returns to the button on close, and the modal becomes a bottom sheet on small screens. `GridToolbar` takes the same slot, prop and event.
+
+```vue
+<KDataGrid
+   :rows="rows"
+   :columns="columns"
+   toolbar
+   :filter-count="[status, owner].filter(Boolean).length"
+   @filters-reset="status = owner = null"
+>
+   <template #filters>
+      <KFormField label="Status"><KSelect v-model="status" :options="statuses" /></KFormField>
+      <KFormField label="Owner"><KSelect v-model="owner" :options="owners" /></KFormField>
+   </template>
+</KDataGrid>
+```
+
 - `DateCell` takes `relative: true` (or `Intl.RelativeTimeFormatOptions`) in `cellRendererParams` for "3 days ago"; the absolute date stays in the `title`. `relativeWithin` (milliseconds, default unset: always relative) shows the absolute date instead once the value is further than that from now, in the past or the future (`relativeWithin: 7 * 86_400_000` keeps "3 days ago" and prints older dates in full).
 - `DataGrid` takes `gridOptions` for any AG Grid option it does not wrap (`rowHeight`, `onCellEditingStopped`, `onFilterChanged`, ...). A prop of `DataGrid` wins only when it is set: `getRowId`, `rowSelection` (when `selectable` is off), `autoSizeStrategy` (also `undefined` to turn it off), `tooltipShowDelay`, `overlayNoRowsTemplate` and `overlayLoadingTemplate` from `gridOptions` are used otherwise; `defaultColDef` and `localeText` are merged over the component defaults, and `context` is merged under the cell context. Handlers from both run.
 - `DataGrid` row ids: `getRowId: (params) => string` (wins), `rowIdKey` (a field of the row), or `gridOptions.getRowId`.
@@ -689,7 +773,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>