@xleddyl/443-components-vue 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,436 @@
-# Temporary Holding Version
+# @xleddyl/443-components-vue
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Compact, scoped dashboard components for Vue 3.5 and Nuxt 4. Plain Vue and CSS, no runtime dependency besides `vue`. Every style lives under `.k-root` and inside cascade layers, so the host page is never touched.
+
+## Install
+
+```sh
+pnpm add @xleddyl/443-components-vue
+```
+
+Optional integrations need their own peer dependencies, install only what you use:
+
+| Subpath           | Peer dependencies                                                                                                          |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `@xleddyl/443-components-vue/grid`   | `ag-grid-community`, `ag-grid-vue3`                                                                                        |
+| `@xleddyl/443-components-vue/editor` | `@tiptap/vue-3`, `@tiptap/starter-kit`, `@tiptap/pm`, `@tiptap/extension-placeholder`, `@tiptap/extension-character-count` |
+| `@xleddyl/443-components-vue/chart`  | `chart.js`, `vue-chartjs`                                                                                                  |
+
+## Nuxt
+
+```ts
+export default defineNuxtConfig({
+   modules: ['@xleddyl/443-components-vue/nuxt'],
+   k: {
+      prefix: 'K',
+      icons: { dir: '~/assets/icons' },
+      chart: true,
+   },
+})
+```
+
+```vue
+<template>
+   <KRoot class="is-canvas">
+      <KButton icon="plus" @click="toast.success('Created')">New entry</KButton>
+      <KOverlayHost />
+   </KRoot>
+</template>
+```
+
+Every component is registered with the prefix (`Button.vue` becomes `<KButton>`) and every `use*` composable plus `toast` and `withLoading` is auto-imported.
+
+| Option           | Default         | Effect                                                                                                                                                                                                       |
+| ---------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `prefix`         | `'K'`           | Component name prefix.                                                                                                                                                                                       |
+| `css`            | `true`          | Injects `@xleddyl/443-components-vue/style.css` (and the CSS of enabled optional groups).                                                                                                                                       |
+| `composables`    | `true`          | Auto-imports the composables.                                                                                                                                                                                |
+| `global`         | `false`         | Puts `k-root` and `data-theme` on `<html>` for apps that are dashboard only.                                                                                                                                 |
+| `theme.cookie`   | `'k-theme'`     | Cookie that stores the theme preference (SSR safe, no flash).                                                                                                                                                |
+| `theme.default`  | `'system'`      | `'light'`, `'dark'` or `'system'`.                                                                                                                                                                           |
+| `preset.default` | `'default'`     | Built-in preset: `'default'`, `'suedtirol'` or `'spotfish'`.                                                                                                                                                 |
+| `preset.cookie`  | `'k-preset'`    | Cookie that stores the preset preference (SSR safe, no flash).                                                                                                                                               |
+| `fonts`          | `true`          | Injects the self-hosted fonts of `preset.default` (`true`), of a list of presets (`['default', 'suedtirol']`) or none (`false`). Install the `@fontsource-variable/*` packages they need.                    |
+| `icons.dir`      | none            | Folder of `.svg` files registered as icons by file name (watched in dev).                                                                                                                                    |
+| `grid`           | `false`         | Registers `KDataGrid` and `KGridToolbar` and injects their CSS.                                                                                                                                              |
+| `editor`         | `false`         | Registers `KRichTextEditor` and injects its CSS.                                                                                                                                                             |
+| `chart`          | `false`         | Registers `KChartPanel`, `KChartLegend`, `KLineChart`, `KBarChart`, `KDoughnutChart` and injects their CSS.                                                                                                  |
+| `layouts`        | `false`         | Registers the ready Nuxt layouts `k-dashboard` and `k-auth` (configured from `app.config.ts`, see [Layouts](#layouts-and-page-templates)). Pass `{ dashboard: 'admin', auth: false }` to rename or skip one. |
+| `cssTarget`      | modern browsers | Sets `vite.build.cssTarget` when the host did not, so Lightning CSS keeps `light-dark()`. Pass `false` to leave the build target alone.                                                                      |
+
+The module also adds the optional peer dependencies that are installed in the host to `vite.optimizeDeps.include`, so the first visit to a page with a grid, editor or chart does not trigger a dependency reload.
+
+## Plain Vue
+
+```ts
+import { createApp } from 'vue'
+import { createIcons } from '@xleddyl/443-components-vue'
+import '@xleddyl/443-components-vue/style.css'
+import App from './App.vue'
+
+createApp(App)
+   .use(createIcons({ logo: '<svg ...>' }))
+   .mount('#app')
+```
+
+```vue
+<script setup lang="ts">
+import { Button, OverlayHost, Root, toast } from '@xleddyl/443-components-vue'
+</script>
+
+<template>
+   <Root>
+      <Button @click="toast('Saved')">Save</Button>
+      <OverlayHost />
+   </Root>
+</template>
+```
+
+Without Nuxt the theme and preset preferences are kept in `localStorage`; pass your own stores with `app.use(createTheme(ref('dark')))` and `app.use(createPreset(ref('suedtirol')))`. Import the fonts of the presets you use yourself (see [Presets](#presets)). Optional groups: `import { DataGrid } from '@xleddyl/443-components-vue/grid'` plus `import '@xleddyl/443-components-vue/grid/style.css'` (same for `editor` and `chart`). With a router, provide the link component once: `app.use(createLinkComponent(RouterLink))`.
+
+Vite 8 minifies CSS with Lightning CSS. Set `build.cssTarget` to browsers that support `light-dark()` (for example `['chrome123', 'edge123', 'firefox128', 'safari17.5']`) to keep the native function. See the theming notes below for what changes when it is transpiled.
+
+## Theming
+
+Tokens live on `.k-root`, never on `:root`. Override them on a root element: Root props, inline style or host CSS.
+
+```vue
+<KRoot accent="#ff4d00" font-sans="'Inter', sans-serif" :radius-scale="0.75" theme="dark">
+```
+
+Input tokens, declared only on the outermost root so nested roots inherit them: `--k-accent`, `--k-accent-contrast`, `--k-font-sans`, `--k-font-mono`, `--k-font-size`, `--k-font-features`, `--k-line-height`, `--k-radius-scale`. Every other token (surfaces, text, lines, accent shades, status colors, radii, shadows, motion) is derived per root, so a nested root with its own `theme` or `accent` re-themes a region. The full list is in [CONVENTIONS.md](./CONVENTIONS.md#tokens).
+
+Themes: `data-theme="light"` or `"dark"` forces the scheme, `system` (or no attribute) follows the OS. `useTheme()` returns `preference`, `set()` and `cycle()`; `KThemeSwitch` is a ready control.
+
+Titles (headings, `k-title`, `k-display`, PageHeader, Card, Modal and Drawer titles, Brand, Stat values, auth and error titles) use `--k-font-display`, which falls back to `--k-font-sans`. Set it (or the `fontDisplay` prop of `Root`) for a separate display face.
+
+### Presets
+
+Three built-in presets, each designed for light and dark (all colors use `light-dark()`, so `data-theme` keeps working with every preset):
+
+| Preset      | Look                                                                                                                                     | Fonts                                            |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| `default`   | The nuxt-cms look: neutral greys, indigo accent, radius scale 1.                                                                         | Geist, Geist Mono                                |
+| `suedtirol` | Südtirol: forest green `#0d4631` with lime `#bde68f`, blue grey surfaces, rounder. Dark: lime on deep forest.                            | Funnel Sans, Funnel Display (titles), Geist Mono |
+| `spotfish`  | Spotfish: signal yellow `#ffbd00` fills with black text, a readable dark yellow `--k-accent-text` on light surfaces, graphite dark mode. | Funnel Sans, Unbounded (titles), Geist Mono      |
+
+A preset is the `data-preset` attribute on a root. `Root` renders it from the stored preference, or from its `preset` prop:
+
+```vue
+<KRoot preset="suedtirol">...</KRoot>
+<KRoot preset="spotfish" theme="dark">...</KRoot>
+```
+
+`usePreset()` returns `preset` (a ref), `options` (`presetOptions`: value, label, description) and `set(value)` (with a view transition). `AppearanceSettings` renders theme and preset cards, and `SettingsModal` shows them in its Appearance section. Under Nuxt the preference lives in the `k-preset` cookie, so the server renders the right preset with no flash; `k.global: true` also puts `data-preset` on `<html>`. Nested roots inherit the preset of the closest root that sets one, and a nested root can set its own.
+
+Fonts are self-hosted variable fonts from Fontsource, declared as optional peer dependencies:
+
+```sh
+pnpm add @fontsource-variable/geist @fontsource-variable/geist-mono
+pnpm add @fontsource-variable/funnel-sans @fontsource-variable/funnel-display
+pnpm add @fontsource-variable/unbounded
+```
+
+The Nuxt module injects the CSS of the packages needed by the presets in `k.fonts` (default: only `preset.default`) and warns about missing packages. `@font-face` rules only download a file when a glyph is rendered with it, so listing several presets costs little. In plain Vue import them yourself, `PRESET_FONTS` lists the packages per preset:
+
+```ts
+import '@fontsource-variable/funnel-sans'
+import '@fontsource-variable/funnel-display'
+import '@fontsource-variable/geist-mono'
+```
+
+Presets set the input tokens (accent, accent contrast and accent text, fonts, font features, radius scale) and the surface, line and text tokens. Root props, inline style and unlayered host CSS still win, so a custom brand is a few lines:
+
+```vue
+<KRoot accent="#ff4d00" accent-contrast="#ffffff" :radius-scale="0.5" theme="dark">...</KRoot>
+```
+
+```css
+.k-root.brand-secret {
+   --k-accent: #ff4d00;
+   --k-radius-scale: 0.5;
+}
+```
+
+Semantic color props are always called `tone` and accept `'neutral' | 'accent' | 'info' | 'success' | 'warning' | 'danger'` (type `Tone`).
+
+## Scoping
+
+- The reset only matches `.k-root` and its descendants, wrapped in `:where()` (zero specificity). Markup outside a root keeps browser defaults.
+- All classes and keyframes are `k-` prefixed.
+- Everything sits in `@layer k.tokens, k.base, k.components, k.utilities`. Any unlayered host CSS wins, so overrides need no `!important`. The flip side: unlayered host element selectors (`button { ... }`) also reach library elements. Put global element styles in a layer or scope them.
+- The one exception is the dashboard frame: while an `AppShell` (`.k-shell`) is on the page, or with `k.global`, `html` and `body` get `overscroll-behavior: none` and `overflow-x: clip`, so the page never rubber bands or scrolls sideways. Only the content panel and the sidebar list scroll, with `overscroll-behavior: contain`.
+- Overlays stay inside the root in the DOM (native top layer through `<dialog>` and `popover`), so they inherit tokens.
+
+## Components
+
+| Group     | Components                                                                                                                                                                                                                      |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| core      | Root, Icon, Button, Spinner, Input, Textarea, FormField, Form, 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, FilterPills, Pagination, Stat, Table, Tag, Timeline, Tree                                                                                                                          |
+| layout    | Accordion, AppShell, Breadcrumbs, Card, CopyButton, Grid, NavLink, PageHeader, Separator, Sidebar, SidebarNav, SidebarSection, Stack, 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, 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`, `usePasswordStrength`, `useTableSort`, `useAppShell`, `useScrollLock`, `useDirtyGuard`, `useIcons` helpers and `useLinkComponent`. With the Nuxt module also `useDashboard()` (runtime account, breadcrumbs and badges for the `k-dashboard` layout).
+
+## Imperative hooks
+
+Mount `<KOverlayHost />` once (the ready Nuxt layouts already do). It renders the Toaster, the dialog host for confirm, alert and prompt, the programmatic modal stack and the global loading indicators. Every part can be turned off or configured: `<KOverlayHost :toaster="{ position: 'top-center', max: 4, gap: 8, expand: false, progress: false }" :confirm="true" :modals="true" :loading="{ bar: true, delay: 150, label: 'Loading' }" />`. Each part renders only once even when several hosts are mounted (the first one wins), so a page can add a host safely. All hooks are SSR safe: on the server they do nothing and resolve to the cancelled value.
+
+```ts
+toast('Draft saved')
+toast.success('Entry published', { description: 'It is now live.' })
+toast.error('Import failed', { description: ['Row 4: missing email', 'Row 9: invalid date'] })
+toast('Entry deleted', { action: { label: 'Undo', onClick: restore } })
+toast.promise(save(), { loading: 'Saving', success: 'Saved', error: (e) => String(e) })
+const id = toast.loading('Uploading')
+toast.update(id, { title: 'Almost there' })
+toast.dismiss(id)
+
+const confirm = useConfirm()
+const ok = await confirm({ title: 'Delete project?', tone: 'danger', confirmLabel: 'Delete' })
+
+const alert = useAlert()
+await alert({ title: 'Payment failed', description: 'Update your card.', tone: 'danger' })
+
+const prompt = usePrompt()
+const name = await prompt({ title: 'Rename', label: 'Name', value: 'Acme', required: true })
+
+const modal = useModal()
+const result = await modal.open<Profile>(
+   ProfileForm,
+   { profile },
+   { title: 'Edit profile', size: 'sm' }
+)
+useDrawer().open(ProfileForm, { profile }, { title: 'Edit profile', side: 'right' })
+
+const loading = useLoading()
+await loading.wrap(fetchAll())
+await loading.wrap(publish(), { blocking: true, label: 'Publishing' })
+const reload = withLoading(fetchAll)
+
+const { loading: saving, run } = useLoadingState()
+await run(() => api.save(form))
+```
+
+- 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`. 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.
+- `useLoading()` is ref counted: `start()` returns a stop function, `wrap(promise | fn, options?)` and `withLoading(fn)` stop when settled, `active`, `count` and `blocking` are refs. The host shows a top progress bar after `delay`, and a blocking screen (a modal dialog, so the page is inert) for tasks started with `blocking: true`. `useLoadingState({ global? })` returns a scoped `{ loading, error, run }` for buttons and forms.
+
+## Layouts and page templates
+
+Ready defaults to start a dashboard project: an app frame, an auth frame and page templates with loading, empty and error states. The default look is the nuxt-cms one: the sidebar sits on the canvas and the content is an inset raised panel.
+
+### DashboardLayout
+
+```vue
+<KDashboardLayout
+   :navigation="navigation"
+   :account="{ name: 'Ada Lovelace', email: 'ada@acme.dev', menu: accountMenu }"
+   :breadcrumbs="[{ label: 'Orders', to: '/orders' }, { label: '#1047' }]"
+   brand-name="Acme"
+   brand-subtitle="Production"
+   brand-icon="cube"
+   search
+>
+   <template #actions><KButton icon="plus">New order</KButton></template>
+   <NuxtPage />
+</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`, `brandTo` | `brandTo: '/'`                  | 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. `#search` replaces it.                                                                                                                                                       |
+| `themeSwitch`                                                     | `'sidebar'`                     | `'sidebar'`, `'topbar'` or `false`.                                                                                                                                                                                                                                          |
+| `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.                                                                                                                                                                    |
+
+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`.
+
+### SettingsModal
+
+A large dialog (60rem) with a section nav on the left and the content on the right, the nuxt-cms settings look. Below 640px the nav turns into a scrolling row above the content.
+
+```vue
+<KSettingsModal
+   v-model:open="open"
+   v-model:section="section"
+   :account="{ name: 'Ada Lovelace', email: 'ada@acme.dev', role: 'Owner' }"
+   :sections="[
+      { id: 'general', label: 'General', icon: 'building-office' },
+      { id: 'members', label: 'Members', icon: 'users', badge: 3 },
+      { id: 'account', label: 'Account', icon: 'user-circle', group: 'You' },
+      { id: 'appearance', label: 'Appearance', icon: 'sun', group: 'You' },
+      { id: 'docs', label: 'Documentation', icon: 'document', group: 'Help', to: '/docs' },
+   ]"
+   @sign-out="signOut"
+>
+   <template #section-general>
+      <KSettingsGroup label="Workspace name" description="Shown on invoices.">
+         <KInput v-model="name" aria-label="Workspace name" />
+      </KSettingsGroup>
+   </template>
+   <template #actions-members><KButton size="sm" icon="plus">Invite</KButton></template>
+   <template #section-members>...</template>
+   <template #account-fields>...</template>
+</KSettingsModal>
+```
+
+- `sections`: `{ id, label, icon?, group?, description?, badge?, disabled?, to? }`. Consecutive items with the same `group` form a labelled block. `to` renders a link that closes the dialog. Without `sections` you get `account` (when `account` is set) and `appearance`.
+- 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`.
+- 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.
+
+`SettingsGroup` (`label`, `description`, `row`, `#actions`) lays out a block inside a section; `AppearanceSettings` works on its own too, for example inside a `SettingsPage`.
+
+### AuthLayout
+
+Centered card on the canvas (`variant="centered"`) or form plus an accent aside panel (`variant="split"`, the aside hides below 960px). Props: `title`, `description`, `footer`, `brandName`, `brandIcon`, `brandLogo`, `brandTo`, `asideTitle`, `asideDescription`, `themeSwitch`. Slots: default (card content), `links` (under the card), `footer`, `brand`, `aside`, `corner`.
+
+### Page templates
+
+| Component                                    | What it gives you                                                                                                                                                                                                                                                                                                                                                                                                        |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `DashboardPage`                              | PageHeader (`title`, `eyebrow`, `description`, `#actions`), a Stat grid from `stats` (or `#stats`), a content grid (`columns`, default 1 then 3 columns).                                                                                                                                                                                                                                                                |
+| `ListPage`                                   | Header, toolbar (search with `searchable`, FilterPills from `filters`, `#toolbar`, `#bulk` when rows are selected), Table from `columns`/`rows`, Pagination. Client mode filters (`searchKeys`, `filterKey`), sorts and paginates; pass `total` for server mode. States: `loading` skeleton rows, first run `#empty`, no results with a clear button, `error` with retry. `cell-*` and `header-*` slots go to the Table. |
+| `DetailPage`                                 | Back link (`backTo`), title, `status` badge, `#actions`, optional `tabs` (`#panel-<value>`), main column plus an aside with DescriptionList cards from `sections` (or `#aside`). `loading` and `error` states.                                                                                                                                                                                                           |
+| `FormPage`                                   | Header, your cards inside `Form` (`form` from `useForm`, or a plain `form` emitting `submit`), sticky footer with cancel and submit, unsaved state, dirty guard (`guard`, on by default) through `useDirtyGuard`.                                                                                                                                                                                                        |
+| `SettingsPage`, `SettingsSection`, `SaveBar` | Section nav (sticky on the left, a scrolling row on narrow screens; items with `to` become route links), `#section-<value>` panels, section cards with a save footer, and a floating save bar while `dirty`.                                                                                                                                                                                                             |
+| `ErrorPage`, `NotFoundPage`                  | Status code, title, message (defaults per status code, reads a Nuxt `error`), home, retry (`@retry`) and back actions. `@home` replaces the home link, handy for `clearError`.                                                                                                                                                                                                                                           |
+| `EmptyPage`                                  | First run screen: illustration, title, description, primary and secondary actions, onboarding `steps`.                                                                                                                                                                                                                                                                                                                   |
+
+`useDirtyGuard(dirty, options?)` asks before leaving (router navigation through `ConfirmHost`, or the native confirm) and on tab close. Returns `confirmLeave()` and `allowNext()`.
+
+### Nuxt: your own layout
+
+`app/layouts/default.vue`:
+
+```vue
+<template>
+   <KRoot class="is-canvas">
+      <KDashboardLayout :navigation="navigation" :account="account" brand-name="Acme" search>
+         <slot />
+      </KDashboardLayout>
+      <KOverlayHost />
+   </KRoot>
+</template>
+
+<script setup lang="ts">
+import type { NavSection } from '@xleddyl/443-components-vue'
+
+const account = { name: 'Ada Lovelace', email: 'ada@acme.dev' }
+const navigation: NavSection[] = [
+   {
+      items: [
+         { label: 'Dashboard', to: '/', icon: 'home' },
+         { label: 'Orders', to: '/orders', icon: 'truck' },
+      ],
+   },
+]
+</script>
+```
+
+`app/error.vue` (it replaces the whole app, so it needs its own root):
+
+```vue
+<template>
+   <KRoot class="is-canvas">
+      <KErrorPage :error="error" brand-name="Acme" @home="clearError({ redirect: '/' })" />
+   </KRoot>
+</template>
+
+<script setup lang="ts">
+import type { NuxtError } from '#app'
+
+defineProps<{ error: NuxtError }>()
+</script>
+```
+
+### Nuxt: ready layouts
+
+With `k: { layouts: true }` the module registers `k-dashboard` and `k-auth`. Each wraps itself in `KRoot` with a `KOverlayHost` (`k.toaster: false` to skip it) and reads `app.config.ts`:
+
+```ts
+export default defineAppConfig({
+   k: {
+      brand: { name: 'Acme', subtitle: 'Production', icon: 'cube', to: '/' },
+      navigation: [
+         { items: [{ label: 'Dashboard', to: '/', icon: 'home', exact: true }] },
+         { label: 'Catalog', items: [{ label: 'Items', to: '/items', icon: 'cube' }] },
+      ],
+      account: { name: 'Ada Lovelace', email: 'ada@acme.dev', role: 'Owner' },
+      settings: {
+         sections: [
+            { id: 'account', label: 'Account', icon: 'user-circle' },
+            { id: 'appearance', label: 'Appearance', icon: 'sun' },
+            {
+               id: 'workspace',
+               label: 'Workspace',
+               icon: 'cog-6-tooth',
+               group: 'Admin',
+               to: '/settings',
+            },
+         ],
+         signOutTo: '/logout',
+      },
+      dashboard: { variant: 'inset', search: true, themeSwitch: 'sidebar' },
+      auth: { variant: 'split', footer: 'Acme Inc.', asideTitle: 'Run the store.' },
+   },
+})
+```
+
+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.
+
+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). 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.
+
+### Starter
+
+The playground ships a small app built only from these pieces, typechecked and built with it: [`playground/nuxt/app/pages/starter`](../../playground/nuxt/app/pages/starter) (`index.vue` dashboard, `login.vue` auth, `settings.vue`, `items/index.vue`, `items/[id].vue`, `items/new.vue`, `projects.vue` first run), [`app.config.ts`](../../playground/nuxt/app/app.config.ts) and [`error.vue`](../../playground/nuxt/app/error.vue). To start a project copy those files and set:
+
+```ts
+export default defineNuxtConfig({
+   modules: ['@xleddyl/443-components-vue/nuxt'],
+   k: { layouts: true },
+})
+```
+
+`app.vue` stays `<NuxtLayout><NuxtPage /></NuxtLayout>`.
+
+## TypeScript
+
+Components are typed for `strictTemplates`: native attributes and listeners of the element that receives the fallthrough attributes are part of the props (`<KButton aria-label="Close" @click="close" />`, `<KInput min="1" step="0.5" />`). `popover`, `popovertarget`, `popovertargetaction` and `closedby` are added to Vue's DOM types. For `data-*` attributes under `strictTemplates`, add `"dataAttributes": ["data-*"]` to `vueCompilerOptions`. When you consume the sources directly (a monorepo workspace) also enable `"fallthroughAttributes": true`; the published declarations already contain the attribute types.
+
+## Accessibility
+
+- Native elements first (`button`, `a`, `input`, `select`, `dialog`, `table`), full ARIA patterns where none fits (combobox, listbox, menu, tabs, tree, radio group, grid calendar).
+- Labels, descriptions and errors are wired through `FormField` (`for`/`id`, `aria-describedby`, `aria-invalid`, required state). Every form control works inside it.
+- Keyboard: arrows inside composite widgets, Escape closes overlays, focus moves into overlays on open and returns to the trigger on close, modals trap focus natively. Tag supports Delete and Backspace on its remove button.
+- Icon-only buttons need an `aria-label` (Button warns in development). Decorative icons are hidden from assistive technology.
+- Toasts are announced through polite or assertive live regions. While a modal dialog is open the toast stack and the live regions move inside that dialog, so they stay reachable and announced (the rest of the page is inert).
+- `prefers-reduced-motion` disables animations inside every root. Colors are never the only signal.
+
+## Browser support
+
+- Required: native `popover`, `<dialog>`, `:where()`, cascade layers, `color-mix()`, `light-dark()` (Chrome and Edge 123, Firefox 128, Safari 17.5).
+- Anchor positioning: used when supported (Chromium). Other browsers get a measured fallback that flips at the viewport edge and follows scroll and resize.
+- `@starting-style` and `transition-behavior: allow-discrete` animate overlays in and out where supported; elsewhere they simply appear.
+- `popover="hint"` is used for tooltips and hover cards when supported, `manual` otherwise.
+- `appearance: base-select` is progressive: Select gets the custom picker in browsers that support it and the native picker elsewhere.
+- `field-sizing: content` drives Textarea autoresize, with a script fallback.

package/dist/chart/BarChart.vue

@@ -0,0 +1,77 @@
+<template>
+   <div ref="root" class="k-chart" :class="`k-chart-legend-${legendPosition}`">
+      <div class="k-chart-canvas" :style="{ height }" role="img" :aria-label="label">
+         <Bar v-if="ready" :data="chartData" :options="chartOptions" />
+         <div v-else class="k-chart-placeholder" aria-hidden="true" />
+      </div>
+      <ChartLegend
+         v-if="legend && legendItems.length > 1"
+         :items="legendItems"
+         :position="legendPosition"
+         @toggle="toggle"
+      />
+      <ChartSummary :caption="label" :labels="labels" :rows="series" />
+   </div>
+</template>
+
+<script setup>
+import { computed, useTemplateRef } from "vue";
+import { Bar } from "vue-chartjs";
+import ChartLegend from "./ChartLegend.vue";
+import ChartSummary from "./ChartSummary.vue";
+import { buildCartesianOptions } from "./options";
+import { registerChartModules } from "./register";
+import { useChartSurface } from "./useChartSurface";
+registerChartModules();
+const props = defineProps({
+  labels: { type: Array, required: true },
+  series: { type: Array, required: true },
+  label: { type: String, required: true },
+  height: { type: String, required: false, default: "16rem" },
+  legend: { type: Boolean, required: false, default: true },
+  legendPosition: { type: String, required: false, default: "bottom" },
+  stacked: { type: Boolean, required: false },
+  horizontal: { type: Boolean, required: false },
+  formatValue: { type: Function, required: false },
+  options: { type: null, required: false }
+});
+const { colors, reducedMotion, ready, colorAt, isHidden, toggle } = useChartSurface(
+  useTemplateRef("root"),
+  {
+    color: (index) => props.series[index]?.color,
+    key: (index) => props.series[index]?.label
+  }
+);
+const legendItems = computed(
+  () => props.series.map((entry, index) => ({
+    label: entry.label,
+    color: colorAt(index),
+    hidden: isHidden(index)
+  }))
+);
+const chartData = computed(() => ({
+  labels: props.labels,
+  datasets: props.series.map((entry, index) => ({
+    label: entry.label,
+    data: entry.data,
+    hidden: isHidden(index),
+    backgroundColor: colorAt(index),
+    hoverBackgroundColor: colorAt(index),
+    borderRadius: 4,
+    borderSkipped: false,
+    maxBarThickness: 36
+  }))
+}));
+const chartOptions = computed(
+  () => buildCartesianOptions(
+    {
+      colors: colors.value,
+      reducedMotion: reducedMotion.value,
+      formatValue: props.formatValue,
+      stacked: props.stacked,
+      horizontal: props.horizontal
+    },
+    { indexAxis: props.horizontal ? "y" : "x", ...props.options }
+  )
+);
+</script>