@xleddyl/443-components-vue 0.9.2 → 0.10.0

package/README.md

@@ -2,6 +2,8 @@
 
 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.
 
+Looking for the right component for a task? Read [CATALOG.md](./CATALOG.md) first: it lists every component and composable with what it is for and when to use it.
+
 ## Install
 
 ```sh
@@ -127,21 +129,21 @@ Input tokens, declared only on the outermost root so nested roots inherit them:
 
 A few component tokens are unset by default and only exist to be overridden on a root (or any ancestor). Unset, every one keeps the library look. The full list with defaults is in [CONVENTIONS.md](./CONVENTIONS.md#tokens):
 
-| Area           | Tokens                                                                                                                                                                                                                                                                                                               |
-| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Type           | `--k-font-weight` (400), `--k-font-weight-medium` (500), `--k-font-weight-strong` (600), `--k-font-weight-display` (650)                                                                                                                                                                                             |
-| Buttons        | `--k-btn-highlight`, `--k-btn-shadow` (`0 0 #0000` for a flat button), `--k-btn-border`, `--k-btn-hover-background`, `--k-btn-active-background`, `--k-btn-padding-x`, `--k-btn-font-size`, `--k-btn-icon-size`, `--k-press-scale` (0.97)                                                                            |
-| Fields         | `--k-field-padding-x`                                                                                                                                                                                                                                                                                                |
-| Overlays       | `--k-modal-radius`, `--k-modal-shadow`, `--k-drawer-radius`, `--k-drawer-shadow`, `--k-popover-radius`, `--k-popover-shadow`, `--k-toast-radius`, `--k-toast-shadow`, `--k-scrim-blur` (3px)                                                                                                                         |
-| Tooltip        | `--k-tooltip-background`, `--k-tooltip-text`, `--k-tooltip-border`, `--k-tooltip-radius`, `--k-tooltip-shadow`, `--k-tooltip-padding`                                                                                                                                                                                |
-| Shell          | `--k-sidebar-width` (15rem), `--k-sidebar-rail-width`, `--k-topbar-height` (3rem), `--k-shell-inset`, `--k-shell-padding`, `--k-shell-content`                                                                                                                                                                       |
-| Switch         | `--k-switch-track-width`, `--k-switch-track-height`, `--k-switch-thumb-size` (md size)                                                                                                                                                                                                                               |
-| Separator      | `--k-separator-heading-font-size` (0.9375rem), `--k-separator-heading-color` (`--k-text`), `--k-separator-label-font-size` (0.75rem)                                                                                                                                                                                 |
-| Calendar       | `--k-calendar-day-radius`, `--k-calendar-unavailable-color`, `--k-calendar-unavailable-decoration` (line-through), `--k-calendar-unavailable-opacity` (0.6), `--k-calendar-out-of-range-color`, `--k-calendar-out-of-range-decoration`, `--k-calendar-out-of-range-opacity` (each defaults to its unavailable token) |
-| Checkbox group | `--k-checkbox-group-background`, `--k-checkbox-group-padding` (0.75rem), `--k-checkbox-group-radius`, `--k-checkbox-group-border` (`variant="filled"`)                                                                                                                                                               |
-| Badge          | `--k-badge-radius`, `--k-badge-font`, `--k-badge-font-size`, `--k-badge-font-weight`, `--k-badge-text-transform`, `--k-badge-letter-spacing`                                                                                                                                                                         |
-| DataGrid       | `--k-grid-header-background`, `--k-grid-header-text`, `--k-grid-header-font`, `--k-grid-header-font-weight`, `--k-grid-header-font-size` (12px), `--k-grid-font-size` (13px), `--k-grid-radius`, `--k-grid-selected-background`                                                                                      |
-| Charts         | `--k-chart-1` to `--k-chart-8` (series palette)                                                                                                                                                                                                                                                                      |
+| Area           | Tokens                                                                                                                                                                                                                                                                                                                                                        |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Type           | `--k-font-weight` (400), `--k-font-weight-medium` (500), `--k-font-weight-strong` (600), `--k-font-weight-display` (650)                                                                                                                                                                                                                                      |
+| Buttons        | `--k-btn-highlight`, `--k-btn-shadow` (`0 0 #0000` for a flat button), `--k-btn-border`, `--k-btn-hover-background`, `--k-btn-active-background`, `--k-btn-padding-x`, `--k-btn-font-size`, `--k-btn-icon-size`, `--k-press-scale` (0.97)                                                                                                                     |
+| Fields         | `--k-field-padding-x`                                                                                                                                                                                                                                                                                                                                         |
+| Overlays       | `--k-modal-radius`, `--k-modal-shadow`, `--k-drawer-radius`, `--k-drawer-shadow`, `--k-popover-radius`, `--k-popover-shadow`, `--k-toast-radius`, `--k-toast-shadow`, `--k-scrim-blur` (3px)                                                                                                                                                                  |
+| Tooltip        | `--k-tooltip-background`, `--k-tooltip-text`, `--k-tooltip-border`, `--k-tooltip-radius`, `--k-tooltip-shadow`, `--k-tooltip-padding`                                                                                                                                                                                                                         |
+| Shell          | `--k-sidebar-width` (15rem), `--k-sidebar-rail-width`, `--k-topbar-height` (3rem), `--k-shell-inset`, `--k-shell-padding`, `--k-shell-content`                                                                                                                                                                                                                |
+| Switch         | `--k-switch-track-width`, `--k-switch-track-height`, `--k-switch-thumb-size` (md size)                                                                                                                                                                                                                                                                        |
+| Separator      | `--k-separator-heading-font-size` (0.9375rem), `--k-separator-heading-color` (`--k-text`), `--k-separator-label-font-size` (0.75rem)                                                                                                                                                                                                                          |
+| Calendar       | `--k-calendar-day-radius`, `--k-calendar-unavailable-color`, `--k-calendar-unavailable-decoration` (line-through), `--k-calendar-unavailable-opacity` (0.6), `--k-calendar-out-of-range-color`, `--k-calendar-out-of-range-decoration`, `--k-calendar-out-of-range-opacity` (each defaults to its unavailable token)                                          |
+| Checkbox group | `--k-checkbox-group-background`, `--k-checkbox-group-padding` (0.75rem), `--k-checkbox-group-radius`, `--k-checkbox-group-border` (`variant="filled"`)                                                                                                                                                                                                        |
+| Badge          | `--k-badge-radius`, `--k-badge-font`, `--k-badge-font-size`, `--k-badge-font-weight`, `--k-badge-text-transform`, `--k-badge-letter-spacing`                                                                                                                                                                                                                  |
+| DataGrid       | `--k-grid-header-background`, `--k-grid-header-text`, `--k-grid-header-font`, `--k-grid-header-font-weight`, `--k-grid-header-font-size` (12px), `--k-grid-font-size` (13px), `--k-grid-radius`, `--k-grid-selected-background`, spreadsheet mode: `--k-grid-range-background`, `--k-grid-range-border`, `--k-grid-dirty-background`, `--k-grid-dirty-marker` |
+| Charts         | `--k-chart-1` to `--k-chart-8` (series palette)                                                                                                                                                                                                                                                                                                               |
 
 Some tokens are meant for one element: set `--k-btn-tone`, `--k-btn-on-tone` and `--k-btn-tone-text` on a button for a brand tone outside `Tone` (a lime fill with green text), and `--k-badge-background`, `--k-badge-color` and `--k-badge-border-color` on a badge for a custom pill color. `variant="subtle"` is a borderless tinted fill (`--k-fill` for the neutral tone). For solid buttons without hover darkening, declare the fill tokens on the button so `var(--k-btn-tone)` resolves per tone: `.k-btn-solid { --k-btn-hover-background: var(--k-btn-tone); --k-btn-active-background: var(--k-btn-tone) }` (the neutral solid button rests on `--k-text`).
 
@@ -263,6 +265,28 @@ const form = useForm({
 
 Issues are keyed by their first path segment and by their full dotted path (`blocks.0.title`), so a nested `FormField name="blocks.0.title"` shows its own error. Pass `issueKey: (path) => string | string[]` to choose the keys yourself. Issues with an empty path become `rootErrors`, which `Form` renders as alerts above the content (`alerts="end"` moves them below, `alerts="false"` hides them, the `#alerts` slot replaces them). `setError('', message)` adds a root error, for example from the server.
 
+Server errors. `form.setIssues(issues)` takes Standard Schema shaped issues (`FormIssueInput`, `{ message, path? }`), keys them like validator issues (first segment and dotted path) and shows them on their fields; an empty path becomes a root error. Messages go through `translateMessage` (`kind: 'error'`). When `onSubmit` throws, a `submitError` resolver (`FormSubmitErrorResolver`, `(error) => FormSubmitError | null | undefined`, with `FormSubmitError` `{ message?, issues? }`) turns the error into issues: `submit()` then resolves `false` instead of throwing, `Form` focuses the first invalid field (or the alerts), `form.submitError` holds the mapped result, and `message` becomes a root error when no issue landed on a field. Set the resolver once in `createFormConfig` / `provideFormConfig`, or per form in `useForm({ submitError })`, which wins. Without a resolver, or when it returns nothing (or neither a message nor issues), the error is thrown as before. Server errors are stale once the user edits: changing a field drops the server errors of that field and its nested paths, and the next submit drops the rest. `setError` keeps its behavior: its errors stay until the field validates again (after the first submit every edit validates the field, so they clear on edit too; before it they stay).
+
+```ts
+app.use(
+   createFormConfig({
+      submitError: (error) => {
+         const data = (
+            error as { data?: { message?: string; data?: { issues?: FormIssueInput[] } } }
+         ).data
+         return data ? { message: data.message, issues: data.data?.issues } : null
+      },
+   })
+)
+
+const form = useForm({
+   values: product,
+   onSubmit: (values) => $fetch('/api/products', { method: 'POST', body: values }),
+})
+```
+
+The server answers `422` with `{ message: 'Invalid product', data: { issues: [{ message: 'Taken', path: ['sku'] }] } }` (`createError({ statusCode: 422, message, data: { issues } })` in Nitro), and `$fetch` puts that body on `error.data`.
+
 Built-in messages follow the active language. `messages` overrides them for one form.
 
 `schema` also accepts a ref or getter (`MaybeRefOrGetter<FormSchema>`), for one form component reused with different fields, labels or rules per open, mode or language: `schema: () => (mode.value === 'edit' ? editSchema : createSchema)`. Field definitions, labels, `required` and rules follow the source (after the first submit the form validates again when they change). A field that appears starts from its `initial` and is clean; a field that disappears loses its value, error and touched state. With `values` the host owns the values, so only rules and labels change. `form.schema` always returns the current definitions.
@@ -509,7 +533,7 @@ A large dialog (60rem) with a section nav on the left and the content on the rig
 - Built-in sections, used when no `#section-<id>` slot fills them: `account` (profile card, your `#account-fields`, a sign out button) and `appearance` (`AppearanceSettings`: theme cards light, dark, system and preset cards; `presets` limits or hides them).
 - `@sign-out` adds a Sign out item at the bottom of the nav and in the account section.
 - Labels: `title` (accessible name of the dialog, default `Settings`), `closeLabel`, `navLabel`, `signOutLabel`, `accountLabel`, `accountText`, `appearanceLabel`, `appearanceText`, `sessionLabel`, `sessionText`, `themeLabel`, `themeText`, `presetLabel`, `presetText`.
-- Subpages: `#section-<id>` and `#actions-<id>` get `page`, `pages`, `openPage({ id, label })` and `back()`. With a page open, a breadcrumb from the section to the page shows below the header (the header keeps the section title and description); a click on a breadcrumb goes back to it. `v-model:pages` binds the stack (it also works unbound). Changing section clears it. Render the detail when `page` is set, the list otherwise.
+- Subpages: `#section-<id>` and `#actions-<id>` get `page`, `pages`, `openPage({ id, label })` and `back()`. With a page open, the header title becomes the path (`Members > Grace Hopper`, same size, only the last part in the text color, earlier parts are buttons that go back to them), the section description stays, and a Back button (`backLabel`, default `common.back`) shows on the right before `#actions-<id>`. `v-model:pages` binds the stack (it also works unbound). Changing section clears it. Render the detail when `page` is set, the list otherwise.
 - `hide-session` hides the Session group (sign out) in the account section; the Sign out item in the nav stays. `beforeClose` works as on Modal.
 - Accessibility: native modal `<dialog>` (focus trap, Escape, focus returns to the trigger), the nav is a labelled `nav` of buttons with `aria-current` and `aria-controls`, the content is a `section` labelled by its heading.
 
@@ -666,6 +690,39 @@ Accessibility related props and defaults:
 - `DataGrid` registers the AG Grid cell editors (text, large text, number, date, checkbox, select, custom and undo/redo) when `editable` is set or when a column or `gridOptions.defaultColDef` has `editable` at mount. `registerGridEditorModules()` from `/grid` does it by hand, before the first grid mounts, for columns that become editable later.
 - `ImageCell` takes `fit` (`'cover'` default, or `'contain'` for logos) and `size` (any CSS length, default `1.75rem`) in `cellRendererParams`. `EmptyCell` (the hidden "Empty" dash) is exported from `/grid` for custom renderers.
 - `BadgeCell` takes `variant` (`BadgeVariant`, `'soft' | 'solid' | 'outline'`) in `cellRendererParams`: set, the cell renders a `KBadge` with that variant and the resolved tone (`size`, `BadgeSize`, default `'sm'`); unset keeps the compact grid pill. `badgeClass` (`string | ((value, data) => string | undefined)`) adds host classes to the badge, to set the per instance badge tokens (`--k-badge-background`, `--k-badge-color`, `--k-badge-border-color`, which the grid pill also reads) for values outside `Tone`. `BadgeCellParams<T>` types the row of `data`.
+- `DataGrid` `spreadsheet` turns on Excel like editing on AG Grid Community (no Enterprise modules): it registers the editor modules and the AG Grid `ScrollApiModule` (`registerGridSpreadsheetModules()` from `/grid` does it by hand) and leaves the normal grid unchanged when it is off. Set `rowIdKey` or `getRowId`: changes, dirty cells and undo refer to row ids, never to indexes.
+   - Selection: click selects a cell; drag, Shift+click and Shift+arrows extend a rectangular range (Shift+Cmd/Ctrl+arrow to the edge); Cmd/Ctrl+A selects every cell. The range follows the displayed row order (after sort, filter and quick search) and the displayed column order; the row selection checkbox column is not part of it. Escape collapses the range to the active cell.
+   - Keyboard: arrows and Tab move the active cell, Enter, F2 or typing start the AG Grid editor, Escape cancels it. While an editor (or any input) has focus no shortcut fires.
+   - Copy: Cmd/Ctrl+C copies the range as TSV (tabs between cells, newlines between rows, cells with a tab, a newline or a leading quote are quoted like Excel). Cells copy their raw value as text (`true`/`false`, dates as `YYYY-MM-DD`); `gridOptions.processCellForClipboard` changes it (it gets `formatValue` and `parseValue` helpers). Right click inside a range copies the range.
+   - Paste: Cmd/Ctrl+V reads TSV from Excel, Google Sheets or text (quoted multi line cells, CRLF, trailing newline) and starts at the top left cell of the range. One value fills the whole range; a smaller block that divides the range evenly is tiled; otherwise the block keeps its size and the pasted area becomes the range. Read only cells (`editable` false or a function that returns false) are skipped. Text goes through the column `valueParser` (also the one of `cellDataType`) and then `valueSetter` or `field`; `gridOptions.processCellFromClipboard` replaces the parser. A non empty text that parses to `null`, `undefined`, `NaN` or an invalid date, or a value missing from `cellEditorParams.values` of a select editor, is not written: it is listed in `cellsInvalid` and counted in the toast.
+   - Fill: Cmd/Ctrl+D copies the first row of the range down, Cmd/Ctrl+R the first column to the right (a one row or one column range copies from the row above or the column on the left). Drag the small square on the range corner down to repeat the range rows below it. Delete or Backspace clears the editable cells (`null`, or what the column `valueParser` returns for an empty string).
+   - Changes: every edit, paste, fill, clear, bulk set, undo and redo is one batch, emitted as `cellsChange` with `{ changes: GridCellChange[], source }` (`GridCellChange` is `{ rowId, colId, field, oldValue, newValue }`, `source` is `'edit' | 'paste' | 'fill' | 'clear' | 'bulk' | 'undo' | 'redo'`). Cmd/Ctrl+Z undoes a batch, Shift+Cmd/Ctrl+Z and Ctrl+Y redo it (100 batches; AG Grid `undoRedoCellEditing` is turned off). The grid writes into the row objects like AG Grid editing does; persist the batch yourself.
+   - Dirty cells: a changed cell gets a tint and a corner marker until you clear it; a cell edited back to its first value is clean again. `dirtyChange(count)` fires when the count changes; `getDirtyCells()` returns `{ rowId, colId, field, originalValue }[]` and `clearDirty(rowIds?)` clears all of them or the given rows (after a save).
+   - Events: `cellsChange`, `cellsInvalid` (`{ cells: { rowId, colId, field, text }[], source }`), `dirtyChange`, `rangeChange` (`GridCellRange | null`, `{ startRowIndex, endRowIndex, columns, active: { rowIndex, colId } }`), and `copy(text)` for a copied range.
+   - Methods (template ref, typed as `GridSpreadsheetMethods<T>`): `getRange()`, `getSelectedCells()` (`{ rowId, rowIndex, colId, field, value, data, editable }[]`), `selectRange({ startRowIndex, endRowIndex?, startColumn, endColumn? })`, `selectAll()`, `clearRange()`, `setRangeValue(value, { parse? })` (writes the value in every editable cell of the range; `parse: true` runs a string through the paste pipeline), `copyRange()`, `paste(text)`, `fillDown()`, `fillRight()`, `clearCells()`, `undo()`, `redo()`, `clearHistory()`, `getDirtyCells()`, `clearDirty(rowIds?)`. Write methods return the number of changed cells.
+   - The `actions` slot also gets every method plus `range`, `selectedCellCount`, `dirtyCount`, `canUndo` and `canRedo` (`GridSpreadsheetSlotProps<T>`), for a "set this value on the selected cells" action:
+
+```vue
+<KDataGrid
+   ref="grid"
+   :rows="products"
+   :columns="columns"
+   row-id-key="id"
+   spreadsheet
+   toolbar
+   @cells-change="({ changes }) => queue(changes)"
+   @dirty-change="(count) => (dirty = count)"
+>
+   <template #actions="{ selectedCellCount, setRangeValue, canUndo, undo }">
+      <KButton label="Undo" :disabled="!canUndo" @click="undo()" />
+      <KButton :label="`Set to Shoes (${selectedCellCount})`" @click="setRangeValue('Shoes')" />
+   </template>
+</KDataGrid>
+```
+
+- Rendering stays virtual: the range, active cell and dirty marks are `cellClassRules` (merged with your own) and only the rendered cells of the affected rows refresh. The range tint is `--k-grid-range-background`, its border and the fill handle `--k-grid-range-border`, dirty cells `--k-grid-dirty-background` and `--k-grid-dirty-marker`. `parseTsv` and `formatTsv` are exported from `/grid`.
+- `DataGrid` row classes: `gridOptions.rowClass`, `gridOptions.rowClassRules` (`{ 'is-archived': (params) => params.data?.archived }`) and `gridOptions.getRowClass` reach AG Grid unchanged. Style the classes in host CSS under `.k-data-grid .ag-row.<class>`.
+- `LinkCell` renders internal hrefs (starting with `/`) with the configured link component (`NuxtLink` in Nuxt, `createLinkComponent(RouterLink)` in plain Vue), so they navigate without a reload; other hrefs stay a plain `<a>`.
 - `DataGrid` translates the AG Grid ARIA strings through the catalog (`grid.*`; your own `localeText` still wins) and announces row count changes.
 
 ## Browser support

package/dist/components/templates/SettingsModal.vue

@@ -99,21 +99,44 @@
                <header class="k-settings-modal-header">
                   <div class="k-settings-modal-heading">
                      <h2 :id="`${baseId}-title`" class="k-settings-modal-title">
-                        {{ active.label }}
+                        <template v-if="currentPage">
+                           <template v-for="(crumb, index) in trail" :key="index">
+                              <button
+                                 type="button"
+                                 class="k-settings-modal-crumb"
+                                 @click="goTo(index)"
+                              >
+                                 {{ crumb }}
+                              </button>
+                              <Icon name="chevron-right" class="k-settings-modal-crumb-separator" />
+                           </template>
+                           <span class="k-settings-modal-crumb is-current">
+                              {{ currentPage.label }}
+                           </span>
+                        </template>
+                        <template v-else>{{ active.label }}</template>
                      </h2>
                      <p v-if="active.description" class="k-settings-modal-description">
                         {{ active.description }}
                      </p>
                   </div>
-                  <div v-if="$slots[`actions-${active.id}`]" class="k-settings-modal-actions">
+                  <div
+                     v-if="currentPage || $slots[`actions-${active.id}`]"
+                     class="k-settings-modal-actions"
+                  >
+                     <Button
+                        v-if="currentPage"
+                        variant="ghost"
+                        tone="neutral"
+                        size="sm"
+                        icon="arrow-left"
+                        @click="back"
+                     >
+                        {{ backText }}
+                     </Button>
                      <slot :name="`actions-${active.id}`" v-bind="slotProps(active, close)" />
                   </div>
                </header>
-               <Breadcrumbs
-                  v-if="currentPage"
-                  class="k-settings-modal-breadcrumbs"
-                  :items="breadcrumbItems"
-               />
                <div
                   ref="contentBody"
                   class="k-settings-modal-body"
@@ -186,7 +209,6 @@ import Icon from "../core/Icon.vue";
 import Avatar from "../data/Avatar.vue";
 import Badge from "../data/Badge.vue";
 import Modal from "../overlays/Modal.vue";
-import Breadcrumbs from "../layout/Breadcrumbs.vue";
 import AppearanceSettings from "./AppearanceSettings.vue";
 import SettingsGroup from "./SettingsGroup.vue";
 const props = defineProps({
@@ -195,6 +217,7 @@ const props = defineProps({
   presets: { type: [Array, Boolean], required: false, default: () => THEME_PRESETS },
   title: { type: String, required: false },
   closeLabel: { type: String, required: false },
+  backLabel: { type: String, required: false },
   navLabel: { type: String, required: false },
   signOutLabel: { type: String, required: false },
   sessionLabel: { type: String, required: false },
@@ -219,6 +242,7 @@ const pages = defineModel("pages", { type: Array, ...{ default: () => [] } });
 const { t } = useLocale();
 const titleText = computed(() => props.title ?? t("settings.title"));
 const closeText = computed(() => props.closeLabel ?? t("settings.close"));
+const backText = computed(() => props.backLabel ?? t("common.back"));
 const navText = computed(() => props.navLabel ?? t("settings.sections"));
 const signOutText = computed(() => props.signOutLabel ?? t("settings.signOut"));
 const sessionLabelText = computed(() => props.sessionLabel ?? t("settings.session"));
@@ -276,12 +300,9 @@ function openPage(page) {
 function back() {
   goTo(pages.value.length - 1);
 }
-const breadcrumbItems = computed(() => [
-  { label: active.value?.label ?? "", onClick: () => goTo(0) },
-  ...pages.value.map((page, index) => ({
-    label: page.label,
-    onClick: index < pages.value.length - 1 ? () => goTo(index + 1) : void 0
-  }))
+const trail = computed(() => [
+  active.value?.label ?? "",
+  ...pages.value.slice(0, -1).map((page) => page.label)
 ]);
 function slotProps(item, close) {
   return { section: item, close, page: currentPage.value, pages: pages.value, openPage, back };

package/dist/components/templates/SettingsModal.vue.d.ts

@@ -16,6 +16,7 @@ declare const __VLS_base: import("vue").DefineComponent<{
     presets?: readonly ThemePreset[] | false;
     title?: string | undefined;
     closeLabel?: string;
+    backLabel?: string;
     navLabel?: string;
     signOutLabel?: string;
     sessionLabel?: string;
@@ -257,6 +258,7 @@ declare const __VLS_base: import("vue").DefineComponent<{
     presets?: readonly ThemePreset[] | false;
     title?: string | undefined;
     closeLabel?: string;
+    backLabel?: string;
     navLabel?: string;
     signOutLabel?: string;
     sessionLabel?: string;

package/dist/composables/useForm.d.ts

@@ -50,9 +50,16 @@ export interface FormTranslateContext {
     params?: MessageParams;
 }
 export type FormTranslateMessage = (message: string, context: FormTranslateContext) => string;
+export type FormIssueInput = StandardSchemaIssue;
+export interface FormSubmitError {
+    message?: string;
+    issues?: ReadonlyArray<FormIssueInput>;
+}
+export type FormSubmitErrorResolver = (error: unknown) => FormSubmitError | undefined | null;
 export interface FormConfig {
     messages?: Partial<FormMessages>;
     translateMessage?: FormTranslateMessage;
+    submitError?: FormSubmitErrorResolver;
 }
 export type FormValidationTrigger = 'submit' | 'blur' | 'input';
 export type FormIssueKey = IssueKeyResolver;
@@ -72,6 +79,7 @@ export interface UseFormOptions<S extends FormSchema = FormSchema, V extends obj
     validateOn?: FormValidationTrigger;
     onSubmit?: (values: V) => unknown;
     onInvalid?: (errors: FormErrors<S>) => unknown;
+    submitError?: FormSubmitErrorResolver;
 }
 export type FormErrors<S extends FormSchema = FormSchema> = Partial<Record<keyof S & string, string>> & FormMessageMap;
 export interface FormContext {
@@ -105,6 +113,8 @@ export interface UseFormReturn<S extends FormSchema = FormSchema, V extends obje
     validateField: (name: keyof V & string) => Promise<boolean>;
     setError: (name: FormPath<V>, message: string | undefined) => void;
     setErrors: (errors: FormErrors<S>) => void;
+    setIssues: (issues: ReadonlyArray<FormIssueInput>) => void;
+    submitError: Readonly<Ref<FormSubmitError | null>>;
     clearErrors: () => void;
     touch: (name: string) => void;
     reset: (values?: Partial<V>) => void;

package/dist/composables/useForm.mjs

@@ -146,11 +146,14 @@ export function useForm(options) {
   const touched = reactive({});
   const submitCount = ref(0);
   const submitting = ref(false);
+  const submitError = shallowRef(null);
   const ruleErrors = {};
   const manualErrors = {};
   let issueErrors = {};
   let issueRoot = [];
   let manualRoot = [];
+  const serverKeys = /* @__PURE__ */ new Set();
+  let serverRoot = [];
   const readValue = (name) => target()[name];
   const dirtyFields = computed(() => {
     void baselineVersion.value;
@@ -172,7 +175,46 @@ export function useForm(options) {
   }
   function syncErrors(inScope) {
     replaceEntries(errors, composeErrors(), inScope);
-    if (!inScope) rootErrors.value = uniqueMessages(manualRoot, issueRoot);
+    if (!inScope) syncRootErrors();
+  }
+  function syncRootErrors() {
+    rootErrors.value = uniqueMessages(manualRoot, serverRoot, issueRoot);
+  }
+  function dropServerErrors(inScope = () => true) {
+    let dropped = false;
+    for (const key of serverKeys) {
+      if (!inScope(key)) continue;
+      delete manualErrors[key];
+      serverKeys.delete(key);
+      dropped = true;
+    }
+    return dropped;
+  }
+  function applyIssues(issues) {
+    dropServerErrors();
+    const grouped = groupIssues(translateIssues(schemaIssues(issues), "error"), issueKey);
+    for (const [key, message] of Object.entries(grouped.fields)) {
+      manualErrors[key] = message;
+      serverKeys.add(key);
+    }
+    serverRoot = grouped.root;
+    return grouped;
+  }
+  function setIssues(issues) {
+    applyIssues(issues);
+    syncErrors();
+  }
+  function resolveSubmitError(error) {
+    const resolver = options.submitError ?? config?.submitError;
+    const result = resolver?.(error);
+    return result && (result.message || result.issues?.length) ? result : null;
+  }
+  function applySubmitError(result) {
+    const grouped = applyIssues(result.issues ?? []);
+    if (result.message && !Object.keys(grouped.fields).length)
+      serverRoot = uniqueMessages(serverRoot, [translate(result.message, { kind: "error" })]);
+    submitError.value = result;
+    syncErrors();
   }
   function evaluateValidator() {
     const validator = toValue(options.validator);
@@ -274,6 +316,8 @@ export function useForm(options) {
     fields.forEach((name, index) => ruleErrors[name] = results[index]);
     for (const key of Object.keys(manualErrors)) delete manualErrors[key];
     manualRoot = [];
+    serverKeys.clear();
+    serverRoot = [];
     syncErrors();
   }
   function isValidResult(issues, results) {
@@ -309,9 +353,10 @@ export function useForm(options) {
   function setError(name, message) {
     if (name === "") {
       manualRoot = message ? [message] : [];
-      rootErrors.value = uniqueMessages(manualRoot, issueRoot);
+      syncRootErrors();
       return;
     }
+    serverKeys.delete(name);
     manualErrors[name] = message;
     if (!message) {
       delete ruleErrors[name];
@@ -323,6 +368,8 @@ export function useForm(options) {
     for (const key of Object.keys(manualErrors)) delete manualErrors[key];
     for (const key of Object.keys(ruleErrors)) delete ruleErrors[key];
     issueErrors = {};
+    serverKeys.clear();
+    serverRoot = [];
     for (const [key, message] of Object.entries(next)) {
       if (key === "") manualRoot = message ? [message] : [];
       else manualErrors[key] = message;
@@ -335,6 +382,9 @@ export function useForm(options) {
     issueErrors = {};
     issueRoot = [];
     manualRoot = [];
+    serverKeys.clear();
+    serverRoot = [];
+    submitError.value = null;
     syncErrors();
   }
   function touch(name) {
@@ -374,6 +424,7 @@ export function useForm(options) {
   async function submit() {
     if (submitting.value) return false;
     submitCount.value++;
+    submitError.value = null;
     const ok = await validate();
     if (!ok) {
       await options.onInvalid?.({ ...errors });
@@ -382,6 +433,11 @@ export function useForm(options) {
     submitting.value = true;
     try {
       await options.onSubmit?.(cloneValue(target()));
+    } catch (error) {
+      const result = resolveSubmitError(error);
+      if (!result) throw error;
+      applySubmitError(result);
+      return false;
     } finally {
       submitting.value = false;
     }
@@ -394,6 +450,8 @@ export function useForm(options) {
         const current = readValue(name);
         if (snapshots.has(name) && isEqualValue(current, snapshots.get(name))) continue;
         snapshots.set(name, cloneValue(current));
+        const inField = (key) => isWithin(key, name);
+        if (dropServerErrors(inField)) syncErrors(inField);
         if (validateOn === "input" || submitCount.value > 0 || validateOn === "blur" && touched[name])
           void validateField(name);
       }
@@ -406,6 +464,7 @@ export function useForm(options) {
         if (isWithin(key, name)) delete source[key];
       }
     }
+    dropServerErrors((key) => isWithin(key, name));
   }
   watch(
     schemaNames,
@@ -500,6 +559,8 @@ export function useForm(options) {
     validateField,
     setError,
     setErrors,
+    setIssues,
+    submitError: readonly(submitError),
     clearErrors,
     touch,
     isRequired: isFieldRequired,

package/dist/grid/DataGrid.vue

@@ -3,7 +3,13 @@
       class="k-data-grid"
       :class="[
   `k-data-grid-${density}`,
-  { 'is-loading': loading, 'is-auto-height': autoHeight, 'is-fill': fill && !autoHeight }
+  {
+    'is-loading': loading,
+    'is-auto-height': autoHeight,
+    'is-fill': fill && !autoHeight,
+    'is-spreadsheet': spreadsheet,
+    'is-filling': spreadsheet && sheetFilling
+  }
 ]"
    >
       <GridToolbar
@@ -18,15 +24,20 @@
          :debounce="searchDebounce"
          @reset-columns="clearStoredState"
       >
-         <slot name="actions" :api="api" />
+         <slot name="actions" :api="api" v-bind="sheetSlot" />
       </GridToolbar>
 
       <div
+         ref="bodyElement"
          class="k-data-grid-body"
          role="region"
          :aria-label="label ?? text.label"
          :aria-busy="loading ? 'true' : void 0"
          :style="autoHeight || fill ? void 0 : { height }"
+         @keydown.capture="sheet.onKeyDown"
+         @pointerdown.capture="sheet.onPointerDown"
+         @mousedown.capture="sheet.onMouseDown"
+         @pointerover="sheet.onPointerOver"
       >
          <AgGridVue
             v-if="mounted"
@@ -54,12 +65,15 @@
             :header-height="headerHeight ?? gridOptions?.headerHeight"
             :tooltip-show-delay="gridOptions?.tooltipShowDelay ?? 600"
             :suppress-cell-focus="false"
+            :undo-redo-cell-editing="spreadsheet ? false : gridOptions?.undoRedoCellEditing"
             v-on="gridEvents"
          />
          <div v-else class="k-data-grid-placeholder" aria-hidden="true">
             <Spinner decorative />
          </div>
-         <p v-if="copied" class="k-data-grid-toast" aria-hidden="true">{{ text.copied }}</p>
+         <p v-if="notice || copied" class="k-data-grid-toast" aria-hidden="true">
+            {{ notice || text.copied }}
+         </p>
          <LiveRegion :message="loading || !mounted ? text.loading : live.message.value" />
       </div>
 
@@ -99,7 +113,7 @@
 
 <script setup>
 import { AgGridVue } from "ag-grid-vue3";
-import { computed, nextTick, onMounted, ref, shallowRef, watch } from "vue";
+import { computed, nextTick, onBeforeUnmount, onMounted, ref, shallowRef, watch } from "vue";
 import Pagination from "../components/data/Pagination.vue";
 import Spinner from "../components/core/Spinner.vue";
 import { useCopy } from "../composables/useCopy";
@@ -113,8 +127,10 @@ import { escapeHtml } from "../internal/core/text";
 import {
   registerGridEditorModules,
   registerGridFilterModules,
-  registerGridModules
+  registerGridModules,
+  registerGridSpreadsheetModules
 } from "./modules";
+import { createGridSpreadsheet } from "./spreadsheet";
 import { getGridTheme } from "./theme";
 registerGridModules();
 const props = defineProps({
@@ -150,25 +166,34 @@ const props = defineProps({
   headerHeight: { type: Number, required: false },
   headerText: { type: Function, required: false },
   filterable: { type: Boolean, required: false },
-  editable: { type: Boolean, required: false }
+  editable: { type: Boolean, required: false },
+  spreadsheet: { type: Boolean, required: false }
 });
-const emit = defineEmits(["rowClick", "selectionChange", "sortChange", "filterChange", "copy"]);
+const emit = defineEmits(["rowClick", "selectionChange", "sortChange", "filterChange", "copy", "cellsChange", "cellsInvalid", "dirtyChange", "rangeChange"]);
 const query = defineModel("query", { type: String, ...{ default: "" } });
 const page = defineModel("page", { type: Number, ...{ default: 1 } });
 const pageSize = defineModel("pageSize", { type: Number, ...{ default: 25 } });
 const sort = defineModel("sort", { type: null, ...{ default: void 0 } });
 if (props.filterable) registerGridFilterModules();
 function hasEditableColumn() {
-  return props.editable || Boolean(props.gridOptions?.defaultColDef?.editable) || props.columns.some((column) => Boolean(column.editable));
+  return props.editable || props.spreadsheet || Boolean(props.gridOptions?.defaultColDef?.editable) || props.columns.some((column) => Boolean(column.editable));
 }
-if (hasEditableColumn()) registerGridEditorModules();
+if (props.spreadsheet) registerGridSpreadsheetModules();
+else if (hasEditableColumn()) registerGridEditorModules();
 const columnDefs = computed(() => {
   const headerText = props.headerText;
-  if (!headerText) return props.columns;
+  const rules = props.spreadsheet ? sheet.classRules : void 0;
+  if (!headerText && !rules) return props.columns;
+  const defaultRules = props.gridOptions?.defaultColDef?.cellClassRules;
   return props.columns.map((column) => {
-    if (column.headerName !== void 0 || !column.field) return column;
-    const headerName = headerText(String(column.field), column);
-    return headerName === void 0 ? column : { ...column, headerName };
+    let next = column;
+    if (headerText && column.headerName === void 0 && column.field) {
+      const headerName = headerText(String(column.field), column);
+      if (headerName !== void 0) next = { ...next, headerName };
+    }
+    if (rules)
+      next = { ...next, cellClassRules: { ...defaultRules, ...column.cellClassRules, ...rules } };
+    return next;
   });
 });
 const { locale, t } = useLocale();
@@ -212,6 +237,52 @@ const selectedCount = ref(0);
 const clientTotal = ref(0);
 const clientPageCount = ref(1);
 const { copied, copy } = useCopy();
+const bodyElement = ref(null);
+const notice = ref("");
+let noticeTimer;
+const noticeMessages = {
+  copied: "cellsCopied",
+  pasted: "cellsPasted",
+  filled: "cellsFilled",
+  cleared: "cellsCleared",
+  updated: "cellsUpdated",
+  undone: "changesUndone",
+  redone: "changesRedone"
+};
+function formatCount(template, count) {
+  return formatLocaleMessage(locale.value.code, template, { count });
+}
+function showNotice(kind, count, invalid) {
+  if (!count && !invalid) return;
+  const message = formatCount(text.value[noticeMessages[kind]], count);
+  notice.value = invalid ? `${message}, ${formatCount(text.value.invalidValues, invalid)}` : message;
+  live.announce(notice.value);
+  clearTimeout(noticeTimer);
+  noticeTimer = setTimeout(() => notice.value = "", 1600);
+}
+const sheet = createGridSpreadsheet({
+  enabled: () => Boolean(props.spreadsheet),
+  body: () => bodyElement.value,
+  gridOptions: () => props.gridOptions,
+  onChange: (event) => emit("cellsChange", event),
+  onInvalid: (event) => emit("cellsInvalid", event),
+  onDirty: (count) => emit("dirtyChange", count),
+  onRange: (range) => emit("rangeChange", range),
+  onCopy: (copiedText) => emit("copy", copiedText),
+  onSelect: (count) => live.announce(formatCount(text.value.cellsSelected, count)),
+  notify: showNotice
+});
+const { filling: sheetFilling, slotProps: sheetSlot } = sheet;
+watch(
+  () => props.spreadsheet,
+  (enabled) => {
+    if (!enabled) sheet.disable();
+  }
+);
+onBeforeUnmount(() => {
+  clearTimeout(noticeTimer);
+  sheet.detach();
+});
 const paginationEnabled = computed(() => props.pagination || props.serverPagination);
 const paginated = computed(() => Boolean(props.pagination) && !props.serverPagination);
 const showFooter = computed(() => paginationEnabled.value || Boolean(props.selectable));
@@ -293,6 +364,7 @@ function persistState(event) {
 }
 function onGridReady(event) {
   api.value = event.api;
+  sheet.attach(event.api);
   const stored = readStoredState();
   if (stored?.length) event.api.applyColumnState({ state: stored, applyOrder: true });
   applySort();
@@ -369,6 +441,10 @@ function onFilterChanged(event) {
 async function onCellContextMenu(event) {
   if (!event.node || !event.column) return;
   event.event?.preventDefault();
+  if (props.spreadsheet && sheet.containsCell(event.node.rowIndex, event.column.getColId())) {
+    await sheet.copyRange();
+    return;
+  }
   const value = event.api.getCellValue({
     rowNode: event.node,
     colKey: event.column,
@@ -399,6 +475,7 @@ onMounted(() => {
   mounted.value = true;
 });
 defineExpose({
+  ...sheet.methods,
   api,
   getSelectedRows: () => api.value?.getSelectedRows() ?? [],
   deselectAll: () => api.value?.deselectAll(),