@xleddyl/443-components-vue 0.9.3 → 0.10.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CATALOG.md +331 -0
- package/README.md +72 -15
- package/dist/composables/useForm.d.ts +10 -0
- package/dist/composables/useForm.mjs +63 -2
- package/dist/grid/DataGrid.vue +90 -13
- package/dist/grid/DataGrid.vue.d.ts +44 -2
- package/dist/grid/cells/LinkCell.vue +8 -7
- package/dist/grid/cells/LinkCell.vue.d.ts +1 -417
- package/dist/grid/data-grid.css +113 -0
- package/dist/grid/index.d.ts +2 -1
- package/dist/grid/index.mjs +3 -1
- package/dist/grid/modules.d.ts +1 -0
- package/dist/grid/modules.mjs +8 -0
- package/dist/grid/spreadsheet.d.ts +52 -0
- package/dist/grid/spreadsheet.mjs +938 -0
- package/dist/grid/tsv.d.ts +3 -0
- package/dist/grid/tsv.mjs +88 -0
- package/dist/grid/types.d.ts +82 -0
- package/dist/locale/de.mjs +10 -1
- package/dist/locale/en.mjs +10 -1
- package/dist/locale/it.mjs +10 -1
- package/dist/locale/types.d.ts +9 -0
- package/package.json +3 -2
package/CATALOG.md
ADDED
|
@@ -0,0 +1,331 @@
|
|
|
1
|
+
# Component catalog: @xleddyl/443-components-vue
|
|
2
|
+
|
|
3
|
+
Read this file before you write UI code. It lists every component and composable of the package, says what each one does, and tells you which one to pick for a task. Reuse what exists. Do not write your own version.
|
|
4
|
+
|
|
5
|
+
This file is a map, not the full reference. For all props, tokens, theming and accessibility notes, read [README.md](./README.md).
|
|
6
|
+
|
|
7
|
+
## How to use the names
|
|
8
|
+
|
|
9
|
+
- In Nuxt, every component has the prefix `K` (set by `k.prefix`). `Button.vue` is `<KButton>`. This catalog uses the short name (`Button`).
|
|
10
|
+
- Every `use*` composable, `toast` and `withLoading` are auto-imported in Nuxt. Without Nuxt, import them from `@xleddyl/443-components-vue`.
|
|
11
|
+
- Mount `<KOverlayHost />` once (the ready Nuxt layouts do it). It is needed for `toast`, `useConfirm`, `useAlert`, `usePrompt`, `useModal`, `useDrawer` and `useLoading`.
|
|
12
|
+
- Wrap the app in `<KRoot>` (it holds the theme, preset and scoping). The ready layouts do it.
|
|
13
|
+
- Icons are passed as names (`icon="plus"`). The type is `IconName`.
|
|
14
|
+
- Tones are always `neutral`, `accent`, `info`, `success`, `warning`, `danger` (type `Tone`).
|
|
15
|
+
- Field sizes are `sm`, `md`, `lg`. Button sizes are `xs`, `sm`, `md`, `lg`.
|
|
16
|
+
|
|
17
|
+
### Optional groups
|
|
18
|
+
|
|
19
|
+
Install the peer dependencies only for the groups you use. Turn the group on in `nuxt.config.ts` (`k: { grid: true }`, `editor: true`, `chart: true`). Without Nuxt, import from the subpath and import its `style.css`.
|
|
20
|
+
|
|
21
|
+
| Group | Subpath | Peer dependencies |
|
|
22
|
+
| ------ | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
|
|
23
|
+
| grid | `@xleddyl/443-components-vue/grid` | `ag-grid-community`, `ag-grid-vue3` |
|
|
24
|
+
| editor | `@xleddyl/443-components-vue/editor` | `@tiptap/vue-3`, `@tiptap/starter-kit`, `@tiptap/pm`, `@tiptap/extension-placeholder`, `@tiptap/extension-character-count` |
|
|
25
|
+
| chart | `@xleddyl/443-components-vue/chart` | `chart.js`, `vue-chartjs` |
|
|
26
|
+
|
|
27
|
+
Playground paths in this file are relative to `playground/nuxt/app/pages/components/` in the `443-components` repository. A dash means no page for that component alone (the page of a related component shows it).
|
|
28
|
+
|
|
29
|
+
## Which component for which task
|
|
30
|
+
|
|
31
|
+
| Task | Use |
|
|
32
|
+
| ------------------------------------------------------------ | ------------------------------------------------------------------------- |
|
|
33
|
+
| Form with validation, dirty state and server errors | `useForm` + `Form` + `FormField` + field components |
|
|
34
|
+
| One labelled field with error, hint and required marker | `FormField` |
|
|
35
|
+
| Map a server error (409, 422) to fields | `useForm` option `submitError`, `form.setErrors`, `form.setIssues` |
|
|
36
|
+
| Form as a full page with sticky save footer | `FormPage` |
|
|
37
|
+
| Warn before the user leaves with unsaved changes | `useDirtyGuard` (or `FormPage`, it has `guard`) |
|
|
38
|
+
| Floating "unsaved changes" bar | `SaveBar` |
|
|
39
|
+
| Single line text | `Input` |
|
|
40
|
+
| Multi line text | `Textarea` |
|
|
41
|
+
| Rich text (bold, lists, links) | `RichTextEditor` (group `editor`) |
|
|
42
|
+
| Password with strength meter and generator | `PasswordInput` |
|
|
43
|
+
| Number with stepper, locale format | `NumberInput` |
|
|
44
|
+
| Money or unit prefix and suffix around an input | `InputGroup` + `InputAddon` |
|
|
45
|
+
| One choice from a short list (5 or fewer) | `RadioGroup` or `SegmentedControl` |
|
|
46
|
+
| One choice from a longer list, no search | `Select` |
|
|
47
|
+
| Searchable select, async search, multi select, create option | `Combobox` |
|
|
48
|
+
| Several choices as checkboxes | `CheckboxGroup` |
|
|
49
|
+
| One yes or no | `Switch` (instant setting) or `Checkbox` (part of a form) |
|
|
50
|
+
| Date, date and time, month | `DateInput` (native) or `DatePicker` (popover calendar, ranges) |
|
|
51
|
+
| Inline calendar | `Calendar` |
|
|
52
|
+
| Time of day | `TimeInput` |
|
|
53
|
+
| Color | `ColorInput` |
|
|
54
|
+
| Number in a range | `Slider` |
|
|
55
|
+
| One time code, OTP | `PinInput` |
|
|
56
|
+
| File or folder upload with drop zone | `FileInput` |
|
|
57
|
+
| Drop files on any element | `useFileDrop` |
|
|
58
|
+
| Confirm a destructive action | `useConfirm` |
|
|
59
|
+
| Show a message the user must acknowledge | `useAlert` |
|
|
60
|
+
| Ask for one text value | `usePrompt` |
|
|
61
|
+
| Short message after an action | `toast` |
|
|
62
|
+
| Toast for a promise (loading, success, error) | `toast.promise` |
|
|
63
|
+
| Detail or edit panel from the side | `Drawer` (or `useDrawer().open`) |
|
|
64
|
+
| Dialog with a form or content | `Modal` (or `useModal().open` to get the result as a promise) |
|
|
65
|
+
| Menu opened by a button | `DropdownMenu` |
|
|
66
|
+
| Right click menu | `ContextMenu` |
|
|
67
|
+
| Small floating panel with content or a form | `Popover` |
|
|
68
|
+
| Preview on hover (user card) | `HoverCard` |
|
|
69
|
+
| Short label on hover or focus | `Tooltip` |
|
|
70
|
+
| Global search, command menu (Cmd+K) | `CommandPalette` (the `DashboardLayout` has it with `search`) |
|
|
71
|
+
| Small table, simple sort | `Table` (+ `useTableSort` for client sort) |
|
|
72
|
+
| Big table, many rows, editing, Excel-like | `DataGrid` (+ `spreadsheet` prop for Excel-like editing) |
|
|
73
|
+
| Whole list page: search, filters, table, pagination | `ListPage` |
|
|
74
|
+
| Page numbers and page size | `Pagination` |
|
|
75
|
+
| Bulk actions bar for selected rows | `SelectionBar` |
|
|
76
|
+
| Filter chips, active filters | `FilterPills` |
|
|
77
|
+
| Tags, chips, removable labels | `Tag` |
|
|
78
|
+
| Status label, counter, dot | `Badge` |
|
|
79
|
+
| User picture or initials; stack of users | `Avatar`; `AvatarGroup` |
|
|
80
|
+
| Key figure with delta and trend (KPI) | `Stat` |
|
|
81
|
+
| Label and value pairs (details) | `DescriptionList` |
|
|
82
|
+
| Event history, activity feed | `Timeline` |
|
|
83
|
+
| Hierarchy, folders, drag to reorder | `Tree` |
|
|
84
|
+
| Charts (line, bar, doughnut) | `ChartPanel` + `LineChart` / `BarChart` / `DoughnutChart` (group `chart`) |
|
|
85
|
+
| Tabs | `Tabs` |
|
|
86
|
+
| Collapsible sections, FAQ | `Accordion` |
|
|
87
|
+
| Container with title and actions | `Card` |
|
|
88
|
+
| Page title, description, breadcrumbs, actions | `PageHeader` (or a page template) |
|
|
89
|
+
| Breadcrumbs only | `Breadcrumbs` |
|
|
90
|
+
| Dashboard layout with sidebar, search, account and settings | `DashboardLayout` (or the Nuxt layout `k-dashboard`) |
|
|
91
|
+
| Custom app frame with your own sidebar | `AppShell` + `Sidebar` + `SidebarNav` |
|
|
92
|
+
| Login, sign up, reset password page | `AuthLayout` (or the Nuxt layout `k-auth`) |
|
|
93
|
+
| Settings in a modal (account, appearance, your sections) | `SettingsModal` (the `DashboardLayout` embeds it) |
|
|
94
|
+
| Settings as a page with sections | `SettingsPage` + `SettingsSection` + `SettingsGroup` |
|
|
95
|
+
| Theme and preset choice | `AppearanceSettings`, `ThemeSwitch`, `useTheme`, `usePreset` |
|
|
96
|
+
| Detail page of one record with tabs and aside | `DetailPage` |
|
|
97
|
+
| Overview page with stats | `DashboardPage` |
|
|
98
|
+
| First run screen with steps | `EmptyPage` |
|
|
99
|
+
| Error page, 404 page | `ErrorPage`, `NotFoundPage` |
|
|
100
|
+
| Empty state inside a card or list | `EmptyState` |
|
|
101
|
+
| Loading placeholder for content | `Skeleton` |
|
|
102
|
+
| Spinner; spinner that fills its container | `Spinner`; `Spinner block` |
|
|
103
|
+
| Cover an area while it loads | `LoadingOverlay` |
|
|
104
|
+
| Global loading bar or blocking screen | `useLoading` / `withLoading` (needs `OverlayHost`) |
|
|
105
|
+
| Loading flag for one button or form | `useLoadingState`, or `loading` prop of `Button` |
|
|
106
|
+
| Progress of a task | `Progress` (bar) or `ProgressRing` |
|
|
107
|
+
| Value in a known range (quota, score) | `Meter` |
|
|
108
|
+
| Inline message (info, warning, error) | `Alert` |
|
|
109
|
+
| Copy text to the clipboard | `CopyButton` or `useCopy` |
|
|
110
|
+
| Keyboard shortcut handler; show a shortcut | `useHotkey`; `Kbd` |
|
|
111
|
+
| Row or column layout with gap; responsive grid | `Stack`; `Grid` |
|
|
112
|
+
| Line or labelled divider; section heading with actions | `Separator` |
|
|
113
|
+
| Group of buttons or tools with arrow key navigation | `Toolbar` |
|
|
114
|
+
| Text for screen readers only | `VisuallyHidden` |
|
|
115
|
+
| Translations of the component texts | `useLocale` (languages: en, it, de) |
|
|
116
|
+
| Custom icons | `createIcons`, `provideIcons`, Nuxt option `k.icons` |
|
|
117
|
+
|
|
118
|
+
## Core
|
|
119
|
+
|
|
120
|
+
| Component | Purpose and when to use it | Main props, models, slots, events | Playground |
|
|
121
|
+
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
|
|
122
|
+
| `Root` | App root. Scopes all styles under `.k-root` and sets theme, preset and tokens. Mount once. Add `is-canvas` for the page background. | Props: `theme` (system, light, dark), `preset`, `accent`, `accentContrast`, `fontSans`, `fontMono`, `fontDisplay`, `radiusScale`, `as`. Slot: default. | `core/root.vue` |
|
|
123
|
+
| `Button` | Every button and button-like link. Use `CopyButton` to copy text, `DropdownMenu` for a menu. | Props: `label`, `variant` (solid, soft, subtle, outline, ghost, link), `tone`, `size`, `icon`, `trailingIcon`, `to`, `href`, `target`, `external`, `type`, `disabled`, `loading`, `block`, `square` (icon only). Slot: default. A `to` or `href` makes it a link. | `core/button.vue` |
|
|
124
|
+
| `Icon` | Show an icon by name. | Props: `name` (required), `label` (makes it non decorative), `size`. | `core/icon.vue` |
|
|
125
|
+
| `Spinner` | Loading indicator. Use `block` for a centered loading state that fills its container. | Props: `size` (xs to lg), `label`, `decorative`, `block`. | `core/spinner.vue` |
|
|
126
|
+
| `Input` | Single line text field. Use `NumberInput` for numbers, `PasswordInput` for passwords. | Model: `v-model` (string, number or null; modifiers `.number`, `.trim`). Props: `type`, `size`, `icon`, `clearable`, `counter` (needs `maxlength`), `transform`, `numeric`, `invalid`, `disabled`, `readonly`, `required`, `noAutofill`. Slots: `leading`, `trailing`. Event: `clear`. | `core/input.vue` |
|
|
127
|
+
| `Textarea` | Multi line text field. | Model: `v-model`. Props: `rows`, `maxRows`, `autoresize`, `counter`, `size`, `invalid`, `disabled`, `readonly`, `required`. Slot: `trailing`. | `core/textarea.vue` |
|
|
128
|
+
| `FormField` | Label, description, hint, error and required marker around one control. It links ids and ARIA for the control inside. | Props: `label`, `name` (reads error and warning from the surrounding `Form`), `description`, `hint`, `error`, `warning`, `required`, `optional`, `disabled`, `icon`. Slots: default, `label`, `label-actions`, `description`, `hint`. | `core/form-field.vue` |
|
|
129
|
+
| `FieldMessage` | One error, warning or hint line outside a `FormField`. | Props: `message`, `tone` (danger, warning, neutral), `icon`. Slot: default. | `core/field-message.vue` |
|
|
130
|
+
| `FieldBoundary` | Cut the field context for controls inside a `FormField` that are not the main control (a search box above a `Tree`). | Prop: `auxiliary` (keeps own id, follows only `disabled`). Without it the context is fully cut. | `core/form-field.vue` |
|
|
131
|
+
| `Form` | Connects a `useForm` result to a `<form>`. Provides errors to `FormField`, handles submit, reset, focus on first error. | Props: `form` (required), `as` (form or div; use `div` for a form nested in a modal), `focusOnError`, `alerts` (start, end, false). Slot: default, `alerts`. Events: `submitted`, `invalid`, `reset`. | `core/form.vue` |
|
|
132
|
+
| `FormAlerts` | Render root errors and warnings as alerts. `Form` already does it. Use it only for a custom placement. | Props: `errors`, `warnings`. | `core/form.vue` |
|
|
133
|
+
| `Kbd` | Show a keyboard key or shortcut. | Props: `value` (for example `mod+k`, shown per platform), `size`. Slot: default. | `core/kbd.vue` |
|
|
134
|
+
| `VisuallyHidden` | Text for screen readers only. | Props: `as`, `focusable`. | `core/visually-hidden.vue` |
|
|
135
|
+
|
|
136
|
+
## Forms
|
|
137
|
+
|
|
138
|
+
All field components work inside `FormField` and take `invalid`, `disabled`, `readonly`, `required` and `size`. They use `v-model`.
|
|
139
|
+
|
|
140
|
+
| Component | Purpose and when to use it | Main props, models, slots, events | Playground |
|
|
141
|
+
| ------------------ | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
|
|
142
|
+
| `Checkbox` | One boolean, or one value in an array model. Use `Switch` for an instant setting. | Model: boolean or array. Props: `label`, `description`, `value`, `indeterminate`. Slots: default, `description`. | `forms/checkbox.vue` |
|
|
143
|
+
| `CheckboxGroup` | Several choices as checkboxes from `options`. | Model: `T[]`. Props: `options` (`label`, `value`, `description`, `disabled`, `icon`), `legend`, `orientation`, `columns`, `variant` (default, filled), `name`. | `forms/checkbox-group.vue` |
|
|
144
|
+
| `Radio` | One radio option, used inside `RadioGroup`. | Props: `value`, `label`, `description`, `icon`. Slots: default, `description`. | `forms/radio-group.vue` |
|
|
145
|
+
| `RadioGroup` | One choice from a short list. Use `Select` for long lists, `SegmentedControl` for a compact toggle. | Model: value or null. Props: `options`, `legend`, `orientation`, `variant` (default, card), `name`. | `forms/radio-group.vue` |
|
|
146
|
+
| `SegmentedControl` | Compact toggle between 2 to 5 options (view mode, period). | Model: value (with `required` it is never null). Props: `options` (`label`, `value`, `icon`, `title`, `muted`), `iconOnly`, `block`, `label`. Slot: `option`. | `forms/segmented-control.vue` |
|
|
147
|
+
| `Select` | Native styled select. Use `Combobox` when search or async options are needed. | Model: `T or null`. Props: `options` (items or groups with `label`, `value`, `disabled`), `placeholder`, `icon`. Option values can be string, number or boolean. | `forms/select.vue` |
|
|
148
|
+
| `Combobox` | Searchable select. Local filter, async `search`, `multiple` with tags, `creatable`. | Models: `v-model`, `v-model:query`. Props: `options` (`label`, `value`, `description`, `icon`, `keywords`), `search(query, signal)`, `filter`, `multiple`, `hideTags`, `creatable`, `debounce`, `minQueryLength`, `maxSelected`, `clearable`, `loading`, `placeholder`, `emptyText`. Slots: `option`, `empty`. Events: `create`, `open`, `close`. | `forms/combobox.vue` |
|
|
149
|
+
| `Switch` | On or off setting that applies at once. | Model: boolean. Props: `label`, `description`, `labelPosition`, `checkedIcon`, `uncheckedIcon`, `name`. Slots: default, `description`. | `forms/switch.vue` |
|
|
150
|
+
| `NumberInput` | Locale aware number with stepper, min, max, step. | Model: number or null. Props: `min`, `max`, `step`, `largeStep`, `locale`, `formatOptions` (currency, percent), `stepper`, `wheel`, `align`, `icon`, `placeholder`. | `forms/number-input.vue` |
|
|
151
|
+
| `PasswordInput` | Password with show or hide, optional generator, copy and strength meter. | Model: string. Props: `generate` (true or a function), `copy`, `strength`, `minLength`, `autocomplete`. Event: `generate`. | `forms/password-input.vue` |
|
|
152
|
+
| `PinInput` | One time code or PIN in separate cells. | Model: string. Props: `length`, `mode` (numeric, alphanumeric, alphabetic), `mask`, `uppercase`, `separatorAfter`, `autocomplete`. Event: `complete(value)`. | `forms/pin-input.vue` |
|
|
153
|
+
| `InputGroup` | Join an input with addons or buttons on its sides. | Props: `label`, `size`, `block`. Slot: default (inputs, `InputAddon`, `Button`). | `forms/input-group.vue` |
|
|
154
|
+
| `InputAddon` | Static text or icon (currency, domain, unit) inside an `InputGroup`. | Props: `label`, `icon`, `size`. Slot: default. | `forms/input-group.vue` |
|
|
155
|
+
| `DateInput` | Native date, datetime-local, month or week input. Use `DatePicker` for a calendar popover or ranges. | Model: ISO string or null. Props: `type`, `min`, `max`, `step`, `clearable`. | `forms/date-input.vue` |
|
|
156
|
+
| `DatePicker` | Input with a calendar popover. Single date or `range`. | Model: ISO string, range object (`start`, `end`) or null. Props: `range`, `min`, `max`, `isDateDisabled`, `locale`, `weekStartsOn`, `format`, `closeOnSelect`, `clearable`. Slot: `footer`. | `forms/date-picker.vue` |
|
|
157
|
+
| `Calendar` | Inline calendar. Use it for availability views, or as a building block. | Models: `v-model` (date or range), `v-model:month`. Props: `range`, `min`, `max`, `isDateDisabled`, `locale`, `weekStartsOn`, `dayText(iso)`. Slots: `day`, `footer`. Event: `select`. | `forms/calendar.vue` |
|
|
158
|
+
| `TimeInput` | Time of day (HH:MM, optional seconds). | Model: string or null. Props: `min`, `max`, `step`, `seconds`, `clearable`. | `forms/time-input.vue` |
|
|
159
|
+
| `ColorInput` | Color text field with picker and swatches. | Model: hex string or null. Props: `swatches` (strings or `{ value, label }`), `placeholder`, `invalidText`. | `forms/color-input.vue` |
|
|
160
|
+
| `Slider` | Number in a range with drag handle. | Model: number. Props: `min`, `max`, `step`, `bubble` (true, always), `marks`, `format(value)`, `label`. Event: `change` (on release). | `forms/slider.vue` |
|
|
161
|
+
| `FileInput` | Drop zone and file picker. Validates type, size and count. Supports folders and previews. | Model: `File`, `File[]` or null. Props: `accept`, `acceptMode`, `maxSize`, `maxFiles`, `multiple`, `directory`, `directoryAction`, `previews`, `list`, `loading`, `capture`, `title`, `dropText`, `hint`. Slots: `title`, `hint`, `actions`. Events: `add`, `remove`, `invalid`, `reject`. | `forms/file-input.vue` |
|
|
162
|
+
|
|
163
|
+
## Overlays
|
|
164
|
+
|
|
165
|
+
Mount `OverlayHost` once for the imperative hooks (see [Composables](#composables)).
|
|
166
|
+
|
|
167
|
+
| Component | Purpose and when to use it | Main props, models, slots, events | Playground |
|
|
168
|
+
| ---------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
|
|
169
|
+
| `Modal` | Centered dialog for forms and content. Use `Drawer` for a side panel, `useConfirm` for a yes or no question. | Model: `v-model:open`. Props: `title`, `description`, `size` (sm to xl, full, fit, fullscreen), `width`, `minHeight`, `dismissible`, `hideClose`, `sheet`, `flush`, `loading`, `beforeClose(reason)`. Slots: default, `header`, `footer`, `title-trailing`. Events: `open`, `close`, `afterLeave`. | `overlays/modal.vue` |
|
|
170
|
+
| `Drawer` | Panel from the side or bottom for details and edit forms. Use `Modal` for short focused dialogs. | Model: `v-model:open`. Props: `title`, `description`, `side` (left, right, bottom), `size` (sm to xl, full), `dismissible`, `hideClose`, `flush`, `loading`, `beforeClose(reason)`. Slots like `Modal`. Events: `open`, `close`, `afterLeave`. | `overlays/drawer.vue` |
|
|
171
|
+
| `ConfirmDialog` | Declarative confirm dialog. Prefer `useConfirm()`. Use this one only when the dialog state lives in the template. | Model: `v-model:open`. Props: `title`, `description`, `confirmLabel`, `cancelLabel`, `tone`, `icon`, `hideCancel`, `onConfirm`. Events: `resolve(confirmed)`, `cancel`, `afterLeave`. | `overlays/confirm-dialog.vue` |
|
|
172
|
+
| `ConfirmHost` | Renders the dialogs of `useConfirm`, `useAlert`, `usePrompt`. `OverlayHost` includes it. Do not mount it alone. | None. | - |
|
|
173
|
+
| `OverlayHost` | One mount point for toasts, confirm dialogs, programmatic modals and loading indicators. | Props: `toaster` (true or options), `confirm`, `modals`, `loading` (true or `{ bar, delay, label }`). | `overlays/hooks.vue` |
|
|
174
|
+
| `Toaster` | Renders toasts. `OverlayHost` includes it. Use it directly only for custom options. | Props: `position`, `max`, `duration`, `gap`, `expand`, `progress`, `hotkey`. | `overlays/toast.vue` |
|
|
175
|
+
| `DropdownMenu` | Menu opened by its trigger. Items can have icons, shortcuts, checkboxes, radios, sub menus and links. | Model: `v-model:open`. Props: `items` (`label`, `icon`, `to`, `href`, `tone: danger`, `shortcut`, `disabled`, `children`, `onSelect`; also `type`: checkbox, radio, label, separator), `placement`, `offset`, `matchTriggerWidth`, `minWidth`. Slot: default (the trigger). Event: `select`. | `overlays/dropdown-menu.vue` |
|
|
176
|
+
| `ContextMenu` | Menu on right click of the wrapped area. | Model: `v-model:open`. Props: `items` (same as `DropdownMenu`), `disabled`. Slot: default (the area). Event: `select`. | `overlays/context-menu.vue` |
|
|
177
|
+
| `Popover` | Floating panel with any content (a form, filters) opened by its trigger. Use `DropdownMenu` for a list of actions. | Model: `v-model:open`. Props: `placement`, `offset`, `arrow`, `label`, `initialFocus`. Slots: default (the trigger), `content`. | `overlays/popover.vue` |
|
|
178
|
+
| `HoverCard` | Rich preview on hover or focus (user card, link preview). Use `Tooltip` for plain text. | Model: `v-model:open`. Props: `placement`, `openDelay`, `closeDelay`, `arrow`, `disabled`. Slots: default (trigger), `content`. | `overlays/hover-card.vue` |
|
|
179
|
+
| `Tooltip` | Short text on hover or focus. Optional shortcut. | Props: `text`, `placement`, `openDelay`, `closeDelay`, `arrow`, `shortcut`, `disabled`. Slots: default (trigger), `content`. | `overlays/tooltip.vue` |
|
|
180
|
+
| `CommandPalette` | Search and command dialog (Cmd+K) with groups, recent items, async search and typed item data. | Models: `v-model:open`, `v-model:query`. Props: `groups` (items with `id`, `label`, `description`, `icon`, `shortcut`, `keywords`, `to`, `data`, `onSelect`), `search(query, signal)`, `shortcut`, `trigger`, `recentKey`, `emptyText`, `notice`. Slots: `item`, `empty`, `group-label`, `after-results`. Events: `select`, `open`, `close`. | `overlays/command-palette.vue` |
|
|
181
|
+
|
|
182
|
+
## Data
|
|
183
|
+
|
|
184
|
+
| Component | Purpose and when to use it | Main props, models, slots, events | Playground |
|
|
185
|
+
| ----------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
|
|
186
|
+
| `Table` | Small to medium table with sort, selection, links and loading rows. For thousands of rows or editing use `DataGrid`. | Models: `v-model:sort` (`{ key, direction }`), `v-model:selected` (row keys). Props: `rows`, `columns` (`key`, `label`, `align`, `width`, `numeric`, `sortable`, `value`, `format`), `rowKey`, `selectable`, `rowTo`, `loading`, `emptyText`, `density`, `stickyHeader`, `maxHeight`, `bordered`, `caption`. Slots: `cell-<key>`, `header-<key>`, `empty`. Event: `rowClick`. | `data/table.vue` |
|
|
187
|
+
| `Pagination` | Page buttons, page size select and summary. Client or server paging. | Models: `v-model:page`, `v-model:pageSize`. Props: `total`, `pageSizes`, `showEdges`, `showJump`, `compact`, `loading`, `showSummary`. Slot: `summary`. | `data/pagination.vue` |
|
|
188
|
+
| `SelectionBar` | Shows the selected count and bulk actions for a list or table. | Props: `count`, `total`, `placement` (inline, sticky, floating), `onSelectAll`, `onClear`. Slots: `actions`, `count`. With `count` 0 it renders nothing visible. | `data/selection-bar.vue` |
|
|
189
|
+
| `FilterPills` | Quick filters as pills: single, multiple, menu or panel pills, removable active filters. | Model: value, array (`multiple`) or null. Props: `options` (`value`, `label`, `valueLabel`, `count`, `icon`, `menu`, `panel`, `removable`), `multiple`, `required`, `clearable`, `size`. Slots: `pill`, `panel-<value>`. Events: `select`, `remove`. | `data/filter-pills.vue` |
|
|
190
|
+
| `FilterPill` | One pill button. Use it alone for a custom filter trigger. `FilterPills` uses it. | Props: `label`, `valueLabel`, `icon`, `count`, `active`, `pressed`, `caret`, `size`, `disabled`. Slot: default. | `data/filter-pills.vue` |
|
|
191
|
+
| `Tag` | Chip or label, optionally removable. Use `Badge` for a status. | Props: `label`, `tone`, `size`, `icon`, `removable`, `removeLabel`, `disabled`. Slot: default. Event: `remove`. | `data/tag.vue` |
|
|
192
|
+
| `Badge` | Status label, counter or dot. Not interactive. | Props: `label` (string or number), `tone`, `variant` (soft, solid, outline), `size`, `dot`, `pulse`, `icon`. Slot: default. | `data/badge.vue` |
|
|
193
|
+
| `Avatar` | User picture with initials fallback and status dot. | Props: `src`, `name`, `alt`, `size` (xs to xl), `shape` (circle, square), `status` (online, away, busy, offline), `decorative`. Slot: `fallback`. | `data/avatar.vue` |
|
|
194
|
+
| `AvatarGroup` | Overlapping stack of avatars with "+N". | Props: `items` (`src`, `name`, `alt`), `max`, `size`, `shape`, `moreLabel`. | `data/avatar.vue` |
|
|
195
|
+
| `Stat` | Key figure (KPI) with unit, delta, trend, hint and optional sparkline. Can be a link. | Props: `label`, `value`, `unit`, `delta`, `trend` (up, down, flat), `invert` (down is good), `hint`, `icon`, `loading`, `to`, `href`, `plain`. Slots: `label`, `value`, `icon`, `sparkline`, `footer`. | `data/stat.vue` |
|
|
196
|
+
| `DescriptionList` | Label and value pairs for a record. Use it on detail views. | Props: `items` (`key`, `label`, `value`, `hint`), `layout` (stacked, inline, grid), `columns`, `divided`, `emptyText`. Slots: `term`, `value`, `value-<key>`. | `data/description-list.vue` |
|
|
197
|
+
| `Timeline` | Vertical list of events or activity. | Props: `items` (`title`, `description`, `time`, `datetime`, `icon`, `tone`), `compact`. Slot: `item`. | `data/timeline.vue` |
|
|
198
|
+
| `Tree` | Expandable hierarchy with selection, drag to reorder and nesting. | Models: `v-model:expanded`, `v-model:selected`. Props: `nodes` (`id`, `label`, `description`, `meta`, `icon`, `children`, `disabled`), `selectable`, `reorderable`, `nestable`, `canDrop`, `size`, `checkmark`, `emptyText`. Slots: `label`, `meta`, `empty`. Events: `select`, `move`. | `data/tree.vue` |
|
|
199
|
+
|
|
200
|
+
## Layout
|
|
201
|
+
|
|
202
|
+
| Component | Purpose and when to use it | Main props, models, slots, events | Playground |
|
|
203
|
+
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
|
|
204
|
+
| `Card` | Container with optional title, description, icon, actions and footer. Can be a link or a selectable button. | Props: `title`, `description`, `icon`, `variant` (raised, outline, subtle), `padding`, `as`, `to`, `href`, `selected`, `disabled`, `animated`. Slots: default, `header`, `title`, `description`, `icon`, `actions`, `footer`. | `layout/card.vue` |
|
|
205
|
+
| `PageHeader` | Page title with description, breadcrumbs, badge and actions. The page templates include it. | Props: `title`, `description`, `icon`, `breadcrumbs`, `level`, `bordered`, `align`, `truncate`. Slots: `actions`, `badge`, `description`, `title`, `icon`, `breadcrumbs`. | `layout/page-header.vue` |
|
|
206
|
+
| `Breadcrumbs` | Path navigation. | Props: `items` (`label`, `to`, `href`, `icon`), `separator`, `linkLast`, `ancestors`. Slot: `item`. | `layout/breadcrumbs.vue` |
|
|
207
|
+
| `Tabs` | Tabs with panels, badges and dots. Segmented or underline. | Model: `v-model` (active value). Props: `items` (`value`, `label`, `icon`, `badge`, `badgeTone`, `dot`, `disabled`), `variant`, `size`, `lazy`, `fill`, `stretch`, `inset`. Slots: `panel-<value>`, `panel`. | `layout/tabs.vue` |
|
|
208
|
+
| `Accordion` | Collapsible sections. | Model: `v-model` (open value or values). Props: `items` (`value`, `title`, `description`, `content`, `icon`), `multiple`, `collapsible`, `variant`. Slots: default, `title`. | `layout/accordion.vue` |
|
|
209
|
+
| `Separator` | Divider, labelled divider, or section heading with description and actions. | Props: `orientation`, `variant` (label, heading), `label`, `description`, `align`, `level`. Slots: default, `description`, `actions`. | `layout/separator.vue` |
|
|
210
|
+
| `Stack` | Flex row or column with gap. | Props: `direction`, `gap` (none to xl), `align`, `justify`, `wrap`, `responsive`, `as`. | `layout/stack.vue` |
|
|
211
|
+
| `Grid` | Responsive CSS grid. | Props: `columns` (number or breakpoints), `minItemWidth` (auto fit), `gap`, `as`. | `layout/grid.vue` |
|
|
212
|
+
| `Toolbar` | Group of controls with arrow key navigation (ARIA toolbar). | Props: `label`, `orientation`, `roving`, `bordered`. | `layout/toolbar.vue` |
|
|
213
|
+
| `CopyButton` | Button that copies a value and shows "copied". | Props: `value`, `label`, `copiedLabel`, `showLabel`, `size`, `variant`, `tone`, `resetAfter`. Event: `copy(success)`. | `layout/copy-button.vue` |
|
|
214
|
+
| `ThemeSwitch` | Light, dark and system switch. | Props: `variant` (segmented, icon), `size`, `showLabels`. | `layout/theme-switch.vue` |
|
|
215
|
+
| `NavLink` | One navigation link with icon, badge and active state. | Props: `label`, `to`, `href`, `icon`, `badge`, `active`, `match` (exact, prefix), `external`, `disabled`. Slots: default, `icon`. | `layout/nav-link.vue` |
|
|
216
|
+
| `AppShell` | App frame: sidebar, topbar, mobile menu, collapse, skip link. Use it for a custom frame. Use `DashboardLayout` for the ready one. | Models: `v-model:collapsed`, `v-model:open`. Props: `variant` (inset, sidebar, floating), `fluid`, `fill`, `topbar`, `storageKey`, `shortcut`. Slots: default, `sidebar`, `topbar`, `overlays`. | `layout/app-shell.vue` |
|
|
217
|
+
| `Sidebar` | Sidebar content with header, collapse button and footer. Goes in the `sidebar` slot of `AppShell`. | Props: `label`, `collapsible`. Slots: default, `header`, `top`, `footer`. | `layout/app-shell.vue` |
|
|
218
|
+
| `SidebarNav` | Navigation list from data, with groups and children. | Props: `items` (`NavItem[]` or `NavSection[]`: `label`, `to`, `icon`, `badge`, `children`), `currentPath`. | `layout/app-shell.vue` |
|
|
219
|
+
| `SidebarSection` | Labelled block inside a sidebar for hand written links. | Prop: `label`. Slot: default. | `layout/app-shell.vue` |
|
|
220
|
+
|
|
221
|
+
## Feedback
|
|
222
|
+
|
|
223
|
+
| Component | Purpose and when to use it | Main props, models, slots, events | Playground |
|
|
224
|
+
| ---------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
|
|
225
|
+
| `Alert` | Inline message with tone, title, description and actions. Use `toast` for short lived messages. | Model: `v-model:open`. Props: `tone`, `variant`, `title`, `description`, `icon` (or false), `dismissible`, `role`. Slots: default, `title`, `icon`, `actions`. Event: `dismiss`. | `feedback/alert.vue` |
|
|
226
|
+
| `EmptyState` | "Nothing here" block with icon, text and actions. For a full first run screen use `EmptyPage`. | Props: `title`, `description`, `icon`, `size`, `variant` (card, plain), `fill`. Slots: default, `title`, `description`, `icon`, `actions`. | `feedback/empty-state.vue` |
|
|
227
|
+
| `Skeleton` | Placeholder shape while content loads. | Props: `shape`, `width`, `height`, `lines`, `lastLineWidth`, `radius`, `animation`. | `feedback/skeleton.vue` |
|
|
228
|
+
| `LoadingOverlay` | Cover its content with a spinner while `loading`. | Props: `loading`, `label`, `showLabel`, `blur`, `spinnerSize`. Slot: default. | `feedback/loading-overlay.vue` |
|
|
229
|
+
| `Progress` | Linear progress, determinate or indeterminate (`value` null). | Props: `value`, `max`, `label`, `showLabel`, `showValue`, `valueText`, `tone`, `size`. Slot: `label`. | `feedback/progress.vue` |
|
|
230
|
+
| `ProgressRing` | Circular progress with optional center content. | Props: `value`, `max`, `label`, `size`, `thickness`, `showValue`, `tone`. Slot: default. | `feedback/progress.vue` |
|
|
231
|
+
| `Meter` | A value inside a known range with low, high and optimum zones (quota, score). Not a task progress. | Props: `value`, `min`, `max`, `low`, `high`, `optimum`, `label`, `hideLabel`, `showValue`, `valueText`, `size`. | `feedback/meter.vue` |
|
|
232
|
+
|
|
233
|
+
## Templates
|
|
234
|
+
|
|
235
|
+
Templates combine core parts into whole pages and layouts. Start from them for new pages.
|
|
236
|
+
|
|
237
|
+
| Component | Purpose and when to use it | Main props, models, slots, events | Playground |
|
|
238
|
+
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
|
|
239
|
+
| `DashboardLayout` | Ready app frame: brand, navigation, command search, account menu, settings modal, breadcrumbs, theme switch. Put it in `layouts/default.vue`. | Models: `v-model:collapsed`, `v-model:open`, `v-model:settingsOpen`, `v-model:settingsSection`. Props: `navigation` (`NavItem[]` or `NavSection[]`), `account` (`name`, `email`, `avatar`, `role`, `menu`), `brandName`, `brandIcon`, `brandLogo`, `breadcrumbs`, `search` (true, groups or function), `settingsSections`, `variant`, `fluid`, `fill`, `onSignOut`. Slots: default, `actions`, `brand`, `sidebar`, `sidebar-footer`, `account`, `topbar`, `search-item`, `settings-account-fields`. Event: `accountSelect`. | `templates/dashboard-layout.vue` |
|
|
240
|
+
| `AuthLayout` | Login, sign up and reset password frame. Centered card or split with aside. | Props: `variant` (centered, split), `title`, `description`, `footer`, `brandName`, `brandIcon`, `brandLogo`, `asideTitle`, `asideDescription`, `themeSwitch`. Slots: default, `links`, `footer`, `brand`, `aside`, `corner`. | `templates/auth-layout.vue` |
|
|
241
|
+
| `ListPage` | Whole list page: header, search, filters, table, pagination, bulk actions, loading, empty, no results and error states. Client or server mode (`total`). | Models: `page`, `pageSize`, `search`, `filter`, `sort`, `selected`. Props: `title`, `rows`, `columns`, `rowKey`, `rowTo`, `selectable`, `loading`, `error`, `total`, `paginate`, `searchable`, `searchKeys`, `filters`, `filterKey`, `filterMultiple`, `emptyTitle`. Slots: `actions`, `toolbar`, `toolbar-end`, `bulk`, `empty`, `empty-actions`, `no-results`, `error`, `cell-<key>`, `table`. Events: `retry`, `clear`, `rowClick`. | `templates/list-page.vue` |
|
|
242
|
+
| `DetailPage` | Record page: back link, title, status, actions, tabs, main column and aside with description lists. | Model: `v-model:tab`. Props: `title`, `backTo`, `backLabel`, `status` (`label`, `tone`, `dot`), `tabs`, `sections` (`title`, `items`), `loading`, `error`. Slots: default, `actions`, `badge`, `meta`, `aside`, `aside-before`, `panel-<value>`. | `templates/detail-page.vue` |
|
|
243
|
+
| `FormPage` | Form page: header, cards in a `Form`, sticky submit and cancel footer, dirty guard. | Props: `title`, `backTo`, `form` (from `useForm`), `dirty`, `saving`, `guard`, `requireDirty`, `submitLabel`, `cancelLabel`, `cancelTo`, `width`, `sticky`. Slots: default, `actions`, `footer`, `status`. Events: `submit`, `submitted`, `invalid`, `reset`, `cancel`. | `templates/form-page.vue` |
|
|
244
|
+
| `DashboardPage` | Overview page: header, stat grid, content grid. | Props: `title`, `eyebrow`, `description`, `stats` (`PageStat[]`), `statsColumns`, `columns`, `loading`. Slots: default, `actions`, `stats`, `sparkline`, `before`, `after`, `eyebrow`. | `templates/dashboard-page.vue` |
|
|
245
|
+
| `SettingsPage` | Settings as a page: section nav, panels, floating save bar when `dirty`. | Model: `v-model:section`. Props: `title`, `sections` (`value`, `label`, `icon`, `to`), `dirty`, `saving`, `saveBar`, `form`. Slots: `section-<value>`, `actions`, `nav-footer`. Events: `save`, `discard`. | `templates/settings-page.vue` |
|
|
246
|
+
| `SettingsSection` | Card of one settings section with a save footer. | Props: `title`, `description`, `icon`, `hint`, `saveable`, `saving`, `saveDisabled`, `saveLabel`, `form`. Slots: default, `actions`, `footer`, `hint`. Event: `save`. | `templates/settings-page.vue` |
|
|
247
|
+
| `SettingsGroup` | Block with label, description and actions inside a settings section. | Props: `label`, `description`, `level`, `row`. Slots: default, `label`, `description`, `actions`. | `templates/settings-modal.vue` |
|
|
248
|
+
| `SettingsModal` | Settings dialog with nav, built-in account and appearance sections, your own sections and subpages. | Models: `v-model:open`, `v-model:section`, `v-model:pages`. Props: `sections` (`id`, `label`, `icon`, `group`, `badge`, `to`), `account`, `presets`, `title`, `onSignOut`, `hideSession`, `beforeClose`. Slots: `section-<id>`, `actions-<id>`, `account-fields`. | `templates/settings-modal.vue` |
|
|
249
|
+
| `AppearanceSettings` | Theme (light, dark, system) and preset cards. Used by `SettingsModal`. Use alone in a settings page. | Props: `presets` (list or false), `themes`, `level`. | `presets.vue` (pages root) |
|
|
250
|
+
| `SaveBar` | Floating bar with save and discard for unsaved changes. | Props: `visible`, `saving`, `message`, `saveLabel`, `discardLabel`, `form`. Slots: default, `actions`. Events: `save`, `discard`. | `templates/settings-page.vue` |
|
|
251
|
+
| `EmptyPage` | First run screen with illustration, actions and onboarding steps. | Props: `title`, `description`, `icon`, `actionLabel`, `actionTo`, `onAction`, `secondaryLabel`, `steps` (`title`, `description`, `done`, `to`), `fill`. Slots: default, `illustration`, `title`, `description`, `actions`. | `templates/empty-page.vue` |
|
|
252
|
+
| `ErrorPage` | Error screen. Reads a Nuxt `error`. Use it in `app/error.vue`. | Props: `error`, `statusCode`, `title`, `message`, `homeTo`, `homeLabel`, `retryLabel`, `brandName`, `fill`, `onHome`, `onRetry`. Slots: default, `title`, `message`, `actions`, `brand`. | `templates/error-page.vue` |
|
|
253
|
+
| `NotFoundPage` | 404 screen. | Props: `title`, `message`, `homeTo`, `homeLabel`, `backLabel`, `brandName`, `fill`, `onHome`. Slots: default, `actions`, `brand`. | `templates/error-page.vue` |
|
|
254
|
+
| `Brand` | Logo and name block (image URL, inline SVG or component). | Props: `name`, `subtitle`, `icon`, `logo`, `to`, `size`, `accent`, `hideText`, `showName`. Slots: default, `logo`, `mark`, `subtitle`. | `templates/dashboard-layout.vue` |
|
|
255
|
+
| `AccountMenu` | Account button with avatar, name and a dropdown menu. Used by `DashboardLayout`. | Props: `name`, `email`, `avatar`, `menu` (menu items), `placement`, `icon`. Event: `select`. | `templates/dashboard-layout.vue` |
|
|
256
|
+
|
|
257
|
+
Nuxt ready layouts: with `k: { layouts: true }` the module registers the layouts `k-dashboard` and `k-auth`. They read brand, navigation, account and settings from `app.config.ts` (`k` key). `useDashboard()` gives the runtime account, breadcrumbs and badges for `k-dashboard`. See README, section "Nuxt: ready layouts".
|
|
258
|
+
|
|
259
|
+
## Grid (group `grid`)
|
|
260
|
+
|
|
261
|
+
Import from `@xleddyl/443-components-vue/grid`. It wraps AG Grid Community.
|
|
262
|
+
|
|
263
|
+
| Component | Purpose and when to use it | Main props, models, slots, events | Playground |
|
|
264
|
+
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- |
|
|
265
|
+
| `DataGrid` | Big table: virtual scroll, column menu, search, CSV export, selection, server sort and paging, inline editing. For small tables use `Table`. | Models: `v-model:query`, `v-model:page`, `v-model:pageSize`, `v-model:sort` (`{ column, direction }`). Props: `rows`, `columns` (AG Grid `ColDef`), `rowIdKey` or `getRowId`, `storageKey`, `density`, `selectable`, `loading`, `height`, `fill`, `autoHeight`, `toolbar`, `searchable`, `columnMenu`, `exportable`, `serverSort`, `pagination`, `serverPagination`, `total`, `filterable`, `editable`, `spreadsheet`, `gridOptions`, `messages`. Slot: `actions`. Events: `rowClick`, `selectionChange`, `sortChange`, `filterChange`, `cellsChange`, `cellsInvalid`, `dirtyChange`, `rangeChange`, `copy`. | `grid/data-grid.vue` |
|
|
266
|
+
| `DataGrid` with `spreadsheet` | Excel-like editing: cell range selection, copy and paste (TSV), fill down and right, clear, undo and redo, dirty cell tracking. Set `rowIdKey` or `getRowId`. | Template ref methods (`GridSpreadsheetMethods`): `getRange`, `getSelectedCells`, `selectRange`, `selectAll`, `setRangeValue`, `copyRange`, `paste`, `fillDown`, `fillRight`, `clearCells`, `undo`, `redo`, `getDirtyCells`, `clearDirty`. The `actions` slot gets the same methods plus `range`, `selectedCellCount`, `dirtyCount`, `canUndo`, `canRedo`. Use `cellsChange` to save edits, `cellsInvalid` for rejected input. | `grid/spreadsheet.vue` |
|
|
267
|
+
| `GridToolbar` | Toolbar of `DataGrid` (search, column menu, export). `DataGrid` already renders it. Use it alone only for a custom grid setup. | Props: `api`, `searchable`, `columnMenu`, `exportable`, `exportFileName`, `debounce`. Model: `v-model` (query). Event: `resetColumns`. | - |
|
|
268
|
+
| Cell renderers | Use as `cellRenderer` in a column definition, with `cellRendererParams`. | `BadgeCell` (`tones`, `labels`, `defaultTone`, `variant`), `BooleanCell` (`trueLabel`, `falseLabel`), `DateCell` (`locale`, `options`, `relative`), `EmptyCell` (placeholder for empty values), `ImageCell` (`alt`, `rounded`, `fit`, `size`), `LinkCell` (`href`, `label`, `target`). | `grid/data-grid.vue` |
|
|
269
|
+
|
|
270
|
+
Grid helpers: `registerGridModules`, `registerGridEditorModules`, `registerGridFilterModules`, `registerGridSpreadsheetModules` (register AG Grid modules by hand), `createGridTheme`, `parseTsv`, `formatTsv`.
|
|
271
|
+
|
|
272
|
+
## Editor (group `editor`)
|
|
273
|
+
|
|
274
|
+
| Component | Purpose and when to use it | Main props, models, slots, events | Playground |
|
|
275
|
+
| ---------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
|
|
276
|
+
| `RichTextEditor` | Rich text field (Tiptap): headings, bold, italic, lists, quote, code, links. Use `Textarea` for plain text. | Model: `v-model` (HTML string or JSON, per `format`). Props: `format` (html, json), `placeholder`, `readonly`, `disabled`, `invalid`, `required`, `maxLength`, `showCount`, `minHeight`, `maxHeight`, `toolbar` (items and `'\|'` separators), `headings`, `headingLabel`, `linkTypes` (url, email, phone), `extensions`, `messages`. Works inside `FormField`. | `editor/rich-text-editor.vue` |
|
|
277
|
+
|
|
278
|
+
## Chart (group `chart`)
|
|
279
|
+
|
|
280
|
+
Import from `@xleddyl/443-components-vue/chart`. It wraps Chart.js. Colors come from `--k-chart-1` to `--k-chart-8`.
|
|
281
|
+
|
|
282
|
+
| Component | Purpose and when to use it | Main props, models, slots, events | Playground |
|
|
283
|
+
| --------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
|
|
284
|
+
| `ChartPanel` | Card around a chart with title, description, loading, empty state and legend. Wrap every chart in it. | Props: `title`, `description`, `loading`, `empty`, `emptyText`, `height`. Slots: default, `actions`, `legend`, `empty`, `footer`. | `chart/charts.vue` |
|
|
285
|
+
| `LineChart` | Trends over time. Series with labels. | Props: `labels`, `series` (`label`, `data`, `color`), `label` (accessible name, required), `height`, `legend`, `legendPosition`, `smooth`, `fill`, `points`, `stacked`, `patterns`, `formatValue`, `options`. | `chart/charts.vue` |
|
|
286
|
+
| `BarChart` | Compare categories. Stacked, horizontal, one color per bar. | Props: `labels`, `series`, `label`, `height`, `legend`, `stacked`, `horizontal`, `colorByPoint`, `colors`, `patterns`, `formatValue`, `options`. | `chart/charts.vue` |
|
|
287
|
+
| `DoughnutChart` | Share of a whole. Use for 5 or fewer parts. | Props: `labels`, `values`, `label`, `colors`, `cutout`, `height`, `legend`, `formatValue`, `options`. Slot: default (center content). | `chart/charts.vue` |
|
|
288
|
+
| `ChartLegend` | Clickable legend. The charts include it. Use it alone for a custom layout. | Props: `items` (`label`, `color`, `hidden`, `value`), `position`, `label`. Event: `toggle(index)`. | `chart/charts.vue` |
|
|
289
|
+
|
|
290
|
+
Chart helpers: `useChartColors`, `readChartColors`, `withAlpha`, `registerChartModules`.
|
|
291
|
+
|
|
292
|
+
## Composables
|
|
293
|
+
|
|
294
|
+
All are exported from `@xleddyl/443-components-vue` and auto-imported in Nuxt.
|
|
295
|
+
|
|
296
|
+
| Composable | Purpose and when to use it | Signature and notes | Playground |
|
|
297
|
+
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
|
|
298
|
+
| `useForm` | State of a form: values, errors, warnings, touched, dirty, submit, server errors. Use it for every form with more than one field. | `useForm({ schema, values, validator, warnings, validateOn, onSubmit, onInvalid, submitError, messages, translateMessage })`. Schema fields: `initial`, `required`, `min`, `max`, `minLength`, `maxLength`, `pattern`, `validate`. `validator` takes any Standard Schema (Zod 4, Valibot, ArkType). Returns `values`, `errors`, `dirty`, `dirtyFields`, `valid`, `submitting`, `validate`, `validateSync`, `setError`, `setErrors`, `setIssues`, `reset(next?)`, `submit`, `touch`, `isRequired`. Pass it to `Form`. | `core/form.vue` |
|
|
299
|
+
| `useField`, `useFieldControl` | Build your own field control that reads the surrounding `FormField` (id, invalid, described by). | `useFieldControl({ role: 'auxiliary' })` for a secondary control. `control.setControlError(message)` reports a control level error. | `core/form-field.vue` |
|
|
300
|
+
| `provideFieldBoundary`, `provideAuxiliaryControls` | In your own overlay component, stop controls from inheriting the field context of the trigger. | Call in `setup`. | - |
|
|
301
|
+
| `toast` / `useToast` | Toasts. | `toast(title, opts)`, `toast.success`, `.error`, `.warning`, `.info`, `.loading`, `.promise(promise, { loading, success, error })`, `.update(id, opts)`, `.dismiss(id)`. Options: `description` (string or list), `action` (`label`, `onClick`), `duration`, `dismissible`. | `overlays/toast.vue` |
|
|
302
|
+
| `useConfirm` | Ask yes or no. Returns a promise of `true` or `false`. | `await useConfirm()({ title, description, tone, confirmLabel, cancelLabel, body })`. | `overlays/hooks.vue` |
|
|
303
|
+
| `useAlert` | Show a message and wait until the user closes it. | `await useAlert()({ title, description, tone })`. | `overlays/hooks.vue` |
|
|
304
|
+
| `usePrompt` | Ask for one text value. Returns the string or `null`. | `await usePrompt()({ title, label, value, placeholder, type, required, validate(value), onConfirm(value) })`. | `overlays/hooks.vue` |
|
|
305
|
+
| `useModal`, `useDrawer`, `useOverlay` | Open a component as a modal or drawer and await its result. Use it when the content is a component with its own logic. | `const result = await useModal().open(Component, props, { title, size, beforeClose })`. The handle has `id`, `close(result)`, `update(props)`. `useModal().close(id?)`, `closeAll()`. `useOverlay` is the base (option `as`). | `overlays/hooks.vue` |
|
|
306
|
+
| `useModalContext` | Inside a component opened by `useModal` or `useDrawer`: close with a result and set the loading state. | `const { close, setLoading } = useModalContext<R>()`. | `overlays/hooks.vue` |
|
|
307
|
+
| `useLoading`, `withLoading` | Global loading: top bar after a delay, or a blocking screen. Ref counted. | `useLoading().wrap(promise, { blocking, label })`, `start()` returns a stop function. `withLoading(fn)` wraps a function. Needs `OverlayHost`. | `overlays/hooks.vue` |
|
|
308
|
+
| `useLoadingState` | Local loading and error flag for a button or form. | `const { loading, error, run } = useLoadingState()`; `await run(() => api.save())`. | `overlays/hooks.vue` |
|
|
309
|
+
| `useDirtyGuard` | Ask before leaving a page or closing the tab with unsaved changes. | `useDirtyGuard(dirty, options?)`. Returns `confirmLeave()` and `allowNext()`. `FormPage` already uses it. | `templates/form-page.vue` |
|
|
310
|
+
| `useFileDrop` | Make any element a drop zone. Use `FileInput` when you need the full control. | `useFileDrop(targetRef, { onDrop(files, event), disabled, ignore })` returns `{ over, reset }`. `readDroppedFiles(dataTransfer)` walks dropped folders. | `forms/file-input.vue` |
|
|
311
|
+
| `useHotkey` | Keyboard shortcut for a page or component. | `useHotkey('mod+k', handler, { enabled, preventDefault, allowInInputs, target })`. `formatHotkey` and `ariaKeyShortcuts` are exported. | `overlays/command-palette.vue` |
|
|
312
|
+
| `useCopy` | Copy text with a `copied` flag. | `const { copy, copied, error } = useCopy({ resetAfter })`. | `layout/copy-button.vue` |
|
|
313
|
+
| `useTableSort` | Client side sort for `Table`. | `const { sort, sorted } = useTableSort(rows, { columns, initial, locale })`. Bind `sort` to `v-model:sort` and render `sorted`. | `data/table.vue` |
|
|
314
|
+
| `usePasswordStrength` | Score a password. Also `scorePassword` and `generatePassword`. | Returns the level 0 to 4. `PasswordInput` already uses it. | `forms/password-input.vue` |
|
|
315
|
+
| `useTheme` | Read or set the theme preference (system, light, dark). | `const { preference, resolved, set } = useTheme()`. Nuxt module stores it in a cookie. | `layout/theme-switch.vue` |
|
|
316
|
+
| `usePreset` | Read or set the visual preset. | `presetOptions` lists the presets. | `presets.vue` (pages root) |
|
|
317
|
+
| `useAppShell` | Read the `AppShell` state (collapsed, open) from a child component. | Returns the shell context or `null` outside a shell. | `layout/app-shell.vue` |
|
|
318
|
+
| `useScrollLock` | Lock the page scroll while something is open. | `useScrollLock(activeRef)`. | - |
|
|
319
|
+
| `useLocale` | Translate component texts and read the active locale (en, it, de). | `const { locale, t } = useLocale()`. `provideLocale` and `createLocale` set it. Nuxt follows `k.locale`. | `languages.vue` (pages root) |
|
|
320
|
+
| `useIcons` helpers, `createIcons`, `provideIcons` | Register your own icons by name. | Nuxt: option `k.icons: { dir: '~/assets/icons' }`. | `components/core/icon.vue` |
|
|
321
|
+
| `useLinkComponent`, `createLinkComponent` | Use the router link (for example `NuxtLink`) for every `to` prop. | The Nuxt module does it for you. | - |
|
|
322
|
+
| `useDashboard` (Nuxt only) | Runtime account, breadcrumbs and badges for the `k-dashboard` layout. | Auto-imported by the module. | `layouts/` of the playground |
|
|
323
|
+
|
|
324
|
+
## Before you build your own
|
|
325
|
+
|
|
326
|
+
1. Search this file for the task. Check the table "Which component for which task" first.
|
|
327
|
+
2. Read the section of the component in `README.md`. Many needs are a prop or a slot that exists (for example `Tabs` `badge`, `Combobox` `multiple`, `Modal` `beforeClose`, `Input` `counter`).
|
|
328
|
+
3. Open the playground page of the component and copy its pattern.
|
|
329
|
+
4. Use the page templates (`ListPage`, `DetailPage`, `FormPage`, `SettingsPage`) before you compose a page from parts.
|
|
330
|
+
5. If something is missing, change the package. Do it only when the change helps every project: a general feature, a fix, a missing prop or slot, a better default. Never add a project specific special case, a local override, a wrapper hack or a CSS patch on internals. If the only possible change is project specific, keep it in the project and write down why.
|
|
331
|
+
6. Release the package, then update the version in the project. Do not use a `link:` dependency.
|