@xleddyl/443-components-vue 0.3.0 → 0.4.0

package/README.md

@@ -244,11 +244,38 @@ const form = useForm({
 
 A control can report its own error (a JSON field that fails to parse) through the surrounding `FormField`: `const control = useFieldControl()` then `control.setControlError(message | undefined)`. The form error wins over it, and it clears when the control unmounts. `FieldMessage` renders the same inline error, warning or hint line outside a `FormField` (`tone="danger" | "warning" | "neutral"`, `icon`, `id` for `aria-describedby`).
 
+`validate()` is async. When every rule, `validate` function and Standard Schema is synchronous, `validateSync()` answers immediately and fills `form.errors` in the same tick, so a caller can reveal the first error without parsing again (it throws when it meets a Promise):
+
+```ts
+if (!form.validateSync()) revealField(Object.keys(form.errors).find((key) => form.errors[key]))
+```
+
+Nested forms. Overlays stay in the DOM, so a `Form` inside a Modal opened from another `Form` would nest `<form>` elements. Render the inner one with `as="div"`: it submits on Enter in its inputs and through its own submit and reset buttons, and keeps those events from reaching the outer form. An outer `Form` also ignores submit events whose target is not its own form element. A component that renders fields without `Form` gives them the form with `provideForm(form)` and shows the root alerts with `<KFormAlerts />` (it reads `rootErrors` and `rootWarnings` from the provided form, or takes `errors` and `warnings` props). `Form` exposes `submit()`, `reset()` and `el`.
+
+```vue
+<KForm :form="entry">
+   <KModal v-model:open="open" title="New tag">
+      <KForm as="div" :form="tag">...</KForm>
+   </KModal>
+</KForm>
+```
+
+Several controls in one `FormField`. Only the primary control takes the field id, name, description and invalid state. Wrap secondary controls (a search input above a Tree) in `<KFieldBoundary auxiliary>`, or call `useFieldControl({ role: 'auxiliary' })` in your own control: they keep their own id and only follow `disabled`. `<KFieldBoundary>` without `auxiliary` cuts the field context completely, like the overlays do. A primary control that is not labelable (a tree, a group, a contenteditable editor) passes `useFieldControl({ labelable: false })`; `FormField` then drops `for` from its label and the control uses `aria-labelledby` with `field.labelId` instead. `Tree`, `CheckboxGroup`, `RadioGroup`, `SegmentedControl` and `RichTextEditor` already do.
+
+```vue
+<KFormField label="Folder">
+   <KFieldBoundary auxiliary>
+      <KInput v-model="query" aria-label="Find a folder" />
+   </KFieldBoundary>
+   <KTree v-model:selected="folder" :nodes="nodes" />
+</KFormField>
+```
+
 ## Components
 
 | Group     | Components                                                                                                                                                                                                                      |
 | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| core      | Root, Icon, Button, Spinner, Input, Textarea, FormField, FieldMessage, Form, Kbd, VisuallyHidden                                                                                                                                |
+| core      | Root, Icon, Button, Spinner, Input, Textarea, FormField, FieldMessage, FieldBoundary, Form, FormAlerts, Kbd, VisuallyHidden                                                                                                     |
 | forms     | Calendar, Checkbox, CheckboxGroup, ColorInput, Combobox, DateInput, DatePicker, FileInput, InputAddon, InputGroup, NumberInput, PasswordInput, PinInput, Radio, RadioGroup, SegmentedControl, Select, Slider, Switch, TimeInput |
 | overlays  | CommandPalette, ConfirmDialog, ConfirmHost, ContextMenu, Drawer, DropdownMenu, HoverCard, Modal, OverlayHost, Popover, Toaster, Tooltip                                                                                         |
 | data      | Avatar, AvatarGroup, Badge, DescriptionList, FilterPill, FilterPills, Pagination, SelectionBar, Stat, Table, Tag, Timeline, Tree                                                                                                |
@@ -259,17 +286,17 @@ A control can report its own error (a JSON field that fails to parse) through th
 | editor    | RichTextEditor                                                                                                                                                                                                                  |
 | chart     | ChartPanel, ChartLegend, LineChart, BarChart, DoughnutChart                                                                                                                                                                     |
 
-Composables: `useTheme`, `usePreset`, `useForm`, `useField`, `useFieldControl`, `useToast` (and `toast`), `useConfirm`, `useAlert`, `usePrompt`, `useModal`, `useDrawer`, `useOverlay`, `useModalContext`, `useLoading` (and `withLoading`), `useLoadingState`, `useHotkey`, `useCopy`, `useFileDrop` (with `readDroppedFiles`), `usePasswordStrength`, `useTableSort`, `useAppShell`, `useScrollLock`, `useDirtyGuard`, `useIcons` helpers and `useLinkComponent`, `provideFieldBoundary`, `useLocale`. With the Nuxt module also `useDashboard()` (runtime account, breadcrumbs and badges for the `k-dashboard` layout).
+Composables: `useTheme`, `usePreset`, `useForm`, `useField`, `useFieldControl`, `useToast` (and `toast`), `useConfirm`, `useAlert`, `usePrompt`, `useModal`, `useDrawer`, `useOverlay`, `useModalContext`, `useLoading` (and `withLoading`), `useLoadingState`, `useHotkey`, `useCopy`, `useFileDrop` (with `readDroppedFiles`), `usePasswordStrength`, `useTableSort`, `useAppShell`, `useScrollLock`, `useDirtyGuard`, `useIcons` helpers and `useLinkComponent`, `provideFieldBoundary`, `provideAuxiliaryControls`, `provideForm`, `useLocale`. With the Nuxt module also `useDashboard()` (runtime account, breadcrumbs and badges for the `k-dashboard` layout).
 
 ### Lists, trees and uploads
 
-- `Tree` takes `size="sm"` for dense rows, `checkmark`, `emptyText` (or `#empty`) and works inside a `FormField` (labelled and described by the field). With `reorderable` rows get a drag handle and Alt with the up and down arrows moves them; `nestable` also lets rows change level (drop in the middle of a row, Alt with left and right). The `move` event carries `{ node, target, position, from: { parent, index }, to: { parent, index } }`, `to.index` being the final index, and `applyTreeMove(nodes, move)` returns the updated tree. `canDrop(move)` vetoes a move. Moves are announced to screen readers.
-- `SelectionBar` shows a plural aware selected count (announced in a live region), select all (`total` plus `@select-all`) and clear (`@clear`) actions, an `#actions` slot and `placement` `inline`, `sticky` or `floating`. `ListPage` renders it for `#bulk`.
-- `FilterPills` takes `required` (single select cannot be cleared) and options with `menu` items (a dropdown trigger showing `valueLabel`). The `#pill` slot renders any trigger; `FilterPill` is exported so popover triggers match the other pills.
+- `Tree` takes `size="sm"` for dense rows, `checkmark`, `descriptionVariant` (`mono`, the default for paths and slugs, or `text`; a node can override it with its own `descriptionVariant`), `emptyText` (or `#empty`) and works inside a `FormField` (labelled and described by the field). With `reorderable` rows get a drag handle and Alt with the up and down arrows moves them; `nestable` also lets rows change level (drop in the middle of a row, Alt with left and right). The `move` event carries `{ node, target, position, from: { parent, index }, to: { parent, index } }`, `to.index` being the final index, and `applyTreeMove(nodes, move)` returns the updated tree. `canDrop(move)` vetoes a move. Moves are announced to screen readers.
+- `SelectionBar` shows a plural aware selected count (announced in a live region), select all (`total` plus `@select-all`) and clear (`@clear`) actions, an `#actions` slot and `placement` `inline`, `sticky` or `floating`. With `count` 0 it renders no box (only its live region), so it can sit in a flex toolbar without adding a gap; the first count after mount is announced too. `ListPage` renders it for `#bulk`.
+- `FilterPills` is generic: the value type comes from the options, `multiple` makes the model an array and `required` drops `null` from it (like `SegmentedControl`). Options take `menu` items (a dropdown trigger showing `valueLabel`) or `panel: true`, which opens a popover with the `#panel-<value>` slot (`{ option, active, toggle, close }`, `panelLabel` names it). The `#pill` slot renders any trigger and its scope has `defaultPill`, a component that renders the built-in pill for that option, so one custom pill does not mean rewriting the others: `<component :is="defaultPill" v-else />`. `FilterPill` is exported so custom triggers match the other pills.
 - `SegmentedControl` with `required` narrows `v-model` to a non null value. Options take `title` (tooltip and description) and `muted`, and the `#option` slot replaces the content of each option.
-- `FileInput` takes `directory` (folder picker; dropped folders are walked, every file keeps its relative path), `list: false` (no file list: picks and drops only emit `add`) and `loading`. `add` receives `(files, { entries: [{ file, path }], source, event, dataTransfer })`.
-- `useFileDrop` returns `{ over, reset }` and takes `ignore(event)`. A drop handled by a nested drop zone is skipped by the outer ones, and the state resets after any drop, even when a child stops propagation. `readDroppedFiles(dataTransfer)` walks dropped folders (call it synchronously in the drop handler).
-- `Tabs` items take `badgeTone` and `badgeLabel` (the accessible name of the badge); the `#panel="{ item }"` slot renders a single panel for the active tab. `Breadcrumbs` items take `attrs` and `onClick` (an item without a link renders a button, handy for drop targets), `#item` customizes the content, and `ancestors` links every item and ends with a separator (`breadcrumbsAncestors` on `PageHeader`). `Accordion` items take `description`, and `contentVariant="neutral"` drops the content padding and text styling.
+- `FileInput` takes `directory` (folder picker; dropped folders are walked, every file keeps its relative path) or `directory="drop"` (the click opens a file picker, dropped folders are still walked), `directoryAction` (an "Upload a folder" button under the dropzone, `directoryActionLabel` renames it) or the `#actions` slot (`{ browse, browseDirectory, disabled }`), `skipHidden` (ignores dot files and dot folders), `list: false` (no file list: picks and drops only emit `add`), `loading` and the `#hint` slot. `add` receives `(files, { entries: [{ file, path }], directories, source, event, dataTransfer })`; `directories` lists every folder path of a folder pick or drop, empty folders included, and `add` also fires for a drop of empty folders. `invalid` fires per file and `reject` once with every rejected file (`(events, detail)`). `acceptMode="hint"` only passes `accept` to the picker and leaves filtering to the host. The component exposes `browse()`, `browseDirectory()`, `addFiles()` and `focus()`.
+- `useFileDrop` returns `{ over, reset }` and takes `ignore(event)`. A drop handled by a nested drop zone is skipped by the outer ones, and the state resets after any drop, even when a child stops propagation. `readDroppedFiles(dataTransfer)` walks dropped folders (call it synchronously in the drop handler) and resolves to `[{ file, path }]`; `readDroppedFiles(dataTransfer, { directories: true })` resolves to `{ files, directories }` with every folder path, empty ones included, and `skipHidden: true` leaves out dot entries.
+- `Tabs` items take `badgeTone` and `badgeLabel` (the accessible name of the badge); the `#panel="{ item }"` slot renders a single panel for the active tab. `stretch` makes the tabs fill the remaining height of a flex column and the active panel grow with it (`flex: 1; min-height: 0`), and `inset` spaces the tab list from the container edges with the panel flush below it, for inspectors and side panes. `Breadcrumbs` items take `attrs` and `onClick` (an item without a link renders a button, handy for drop targets), `#item` customizes the content, and `ancestors` links every item and ends with a separator (`breadcrumbsAncestors` on `PageHeader`). `Accordion` takes `variant` `card` (default), `outline` (the same card without a shadow), `separated` or `plain`; items take `description`, and `contentVariant="neutral"` drops the content padding and text styling.
 - `RichTextEditor` labels heading buttons by their real level (`headingLabel="relative"` numbers them from 1) and `toolbar` picks and orders the buttons: `['headings', '|', 'bold', 'italic', 'link']`.
 
 ## Imperative hooks
@@ -337,7 +364,7 @@ const confirmDiscard = () => !dirty.value || confirm({ title: 'Discard changes?'
 - `size="fullscreen"` on a Modal fills the viewport edge to edge (no radius, no outer padding, safe area insets inside the panel) and never turns into a bottom sheet.
 - Overlays reset the field context: controls inside a Modal, Drawer, CommandPalette, menu, Popover or HoverCard panel do not inherit the id, description or invalid state of a `FormField` that contains the trigger. Call `provideFieldBoundary()` in your own overlay components to do the same.
 
-`CommandPalette`: groups take a `description` (shown after the label), the `#group-label` slot (`{ group, label, description, recent }`) replaces the label, and `notice` or the `#after-results` slot (`{ query, count }`) adds a line under the results, for example "Showing the first results".
+`CommandPalette`: items take typed `data` (`CommandItem<T>`, `CommandGroup<T>`), which reaches the `#item` slot and the `select` event typed; `emptyText` also takes `(query) => string`. Groups take a `description` (shown after the label), the `#group-label` slot (`{ group, label, description, recent }`) replaces the label, and `notice` or the `#after-results` slot (`{ query, count }`) adds a line under the results, for example "Showing the first results".
 
 - `Brand`: `logo` takes an image URL, trusted inline SVG markup (`'<svg ...>'`) or a component; the `#logo` slot replaces the boxed mark; `show-name` keeps the name visible next to a logo.
 - `Card`: `selected` gives a pressed look (`aria-pressed` on `as="button"`, `aria-selected` with `role="option"` and similar roles); `:animated="false"` turns off the entrance animation.
@@ -364,22 +391,22 @@ Ready defaults to start a dashboard project: an app frame, an auth frame and pag
 </KDashboardLayout>
 ```
 
-| Prop                                                                               | Default                         | Notes                                                                                                                                                                                                                                                                                                                    |
-| ---------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `variant`                                                                          | `'inset'`                       | `inset` (canvas sidebar, inset content panel), `sidebar` (bordered sidebar, full bleed content), `floating` (raised sidebar card on the canvas).                                                                                                                                                                         |
-| `navigation`                                                                       |                                 | `NavItem[]` or `NavSection[]` (`{ label?, items }`). Items: `label`, `to`/`href`, `icon`, `badge`, `exact`, `active`, `external`, `disabled`, `children`.                                                                                                                                                                |
-| `currentPath`                                                                      | router path                     | Active state is computed from the router (`$route`) with prefix matching (`/` and `exact` items match exactly).                                                                                                                                                                                                          |
-| `brandName`, `brandSubtitle`, `brandIcon`, `brandLogo`, `brandShowName`, `brandTo` | `brandTo: '/'`                  | `brandLogo` takes an image URL, inline SVG markup or a component; the name is hidden next to a logo unless `brandShowName`. Or the `#brand` slot.                                                                                                                                                                        |
-| `account`                                                                          |                                 | `{ name, email?, avatar?, role?, menu? }`. Shown as a row (avatar, name, email, chevron) at the bottom of the sidebar.                                                                                                                                                                                                   |
-| `accountAction`                                                                    | `'settings'`                    | `settings`: the row opens a `SettingsModal` (`settingsSections`, `settingsPresets`, `v-model:settings-open`, `v-model:settings-section`, `@sign-out`). `menu`: a DropdownMenu with `account.menu`, selections emit `account-select`. Or replace it with the `#account` slot.                                             |
-| `breadcrumbs`                                                                      |                                 | Rendered in the desktop topbar. `#topbar` replaces them, `#actions` adds buttons on the right.                                                                                                                                                                                                                           |
-| `search`                                                                           | `false`                         | `true` adds a CommandPalette with every navigation item, an array adds your own command groups, an async function `(query, signal) => CommandGroup[]` searches on your server (matching navigation items come first unless `searchNavigation` is `false`). `#search` replaces it.                                        |
-| `searchProps`                                                                      |                                 | Options for the built-in CommandPalette: `minQueryLength`, `debounce`, `placeholder`, `label`, `emptyText`, `minQueryText`, `errorText`, `loadingText`, `resultsText`, `notice`, `recentKey`, footer labels. Slots `#search-item`, `#search-empty`, `#search-group-label` and `#search-after-results` reach the palette. |
-| `themeSwitch`                                                                      | `'sidebar'`                     | `'sidebar'`, `'topbar'` or `false`.                                                                                                                                                                                                                                                                                      |
-| `collapsible`, `v-model:collapsed`, `storageKey`                                   | `true`, `'k-sidebar-collapsed'` | Icon rail on desktop. Persisted in a cookie under Nuxt (rendered on the server, no flash) or `localStorage` elsewhere. `false` disables persistence.                                                                                                                                                                     |
-| `shortcut`                                                                         | `'mod+b'`                       | Toggles the rail on desktop and the drawer on mobile. `searchShortcut` defaults to `mod+k`.                                                                                                                                                                                                                              |
-| `v-model:open`                                                                     | `false`                         | Mobile drawer (below 768px of shell width): scrim, focus moves into the drawer, the content is `inert`, Escape and the scrim close it and focus returns to the burger.                                                                                                                                                   |
-| `fluid`, `viewTransition`                                                          | `false`, `true`                 | Full width content; `view-transition-name` on sidebar and panel so page transitions keep the frame still.                                                                                                                                                                                                                |
+| Prop                                                                               | Default                         | Notes                                                                                                                                                                                                                                                                                                                                                      |
+| ---------------------------------------------------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `variant`                                                                          | `'inset'`                       | `inset` (canvas sidebar, inset content panel), `sidebar` (bordered sidebar, full bleed content), `floating` (raised sidebar card on the canvas).                                                                                                                                                                                                           |
+| `navigation`                                                                       |                                 | `NavItem[]` or `NavSection[]` (`{ label?, items }`). Items: `label`, `to`/`href`, `icon`, `badge`, `exact`, `active`, `external`, `disabled`, `children`.                                                                                                                                                                                                  |
+| `currentPath`                                                                      | router path                     | Active state is computed from the router (`$route`) with prefix matching (`/` and `exact` items match exactly).                                                                                                                                                                                                                                            |
+| `brandName`, `brandSubtitle`, `brandIcon`, `brandLogo`, `brandShowName`, `brandTo` | `brandTo: '/'`                  | `brandLogo` takes an image URL, inline SVG markup or a component; the name is hidden next to a logo unless `brandShowName`. Or the `#brand` slot.                                                                                                                                                                                                          |
+| `account`                                                                          |                                 | `{ name, email?, avatar?, role?, menu? }`. Shown as a row (avatar, name, email, chevron) at the bottom of the sidebar.                                                                                                                                                                                                                                     |
+| `accountAction`                                                                    | `'settings'`                    | `settings`: the row opens a `SettingsModal` (`settingsSections`, `settingsPresets`, `v-model:settings-open`, `v-model:settings-section`, `@sign-out`). `menu`: a DropdownMenu with `account.menu`, selections emit `account-select`. Or replace it with the `#account` slot.                                                                               |
+| `breadcrumbs`                                                                      |                                 | Rendered in the desktop topbar. `#topbar` replaces them, `#actions` adds buttons on the right.                                                                                                                                                                                                                                                             |
+| `search`                                                                           | `false`                         | `true` adds a CommandPalette with every navigation item, an array adds your own command groups, an async function `(query, signal) => CommandGroup<T>[]` searches on your server (item `data` reaches `#search-item` typed) (matching navigation items come first unless `searchNavigation` is `false`). `#search` replaces it.                            |
+| `searchProps`                                                                      |                                 | Options for the built-in CommandPalette: `minQueryLength`, `debounce`, `placeholder`, `label`, `emptyText` (a string or `(query) => string`), `minQueryText`, `errorText`, `loadingText`, `resultsText`, `notice`, `recentKey`, footer labels. Slots `#search-item`, `#search-empty`, `#search-group-label` and `#search-after-results` reach the palette. |
+| `themeSwitch`                                                                      | `'sidebar'`                     | `'sidebar'`, `'topbar'` or `false`.                                                                                                                                                                                                                                                                                                                        |
+| `collapsible`, `v-model:collapsed`, `storageKey`                                   | `true`, `'k-sidebar-collapsed'` | Icon rail on desktop. Persisted in a cookie under Nuxt (rendered on the server, no flash) or `localStorage` elsewhere. `false` disables persistence.                                                                                                                                                                                                       |
+| `shortcut`                                                                         | `'mod+b'`                       | Toggles the rail on desktop and the drawer on mobile. `searchShortcut` defaults to `mod+k`.                                                                                                                                                                                                                                                                |
+| `v-model:open`                                                                     | `false`                         | Mobile drawer (below 768px of shell width): scrim, focus moves into the drawer, the content is `inert`, Escape and the scrim close it and focus returns to the burger.                                                                                                                                                                                     |
+| `fluid`, `viewTransition`                                                          | `false`, `true`                 | Full width content; `view-transition-name` on sidebar and panel so page transitions keep the frame still.                                                                                                                                                                                                                                                  |
 
 Slots: `brand`, `search`, `sidebar` (replaces the navigation), `sidebar-footer`, `account`, `topbar-brand`, `topbar`, `actions`, default, plus `settings-section-<id>`, `settings-actions-<id>` and `settings-account-fields`, forwarded to the SettingsModal. The exposed `openSettings(id?)` opens it on a section. Landmarks: skip link, `aside` and `nav` with labels, `main` with an id, `aria-current="page"` on the active link. `SidebarNav` (layout group) renders the same navigation data inside your own `Sidebar`.
 

package/dist/components/core/FieldBoundary.vue

@@ -0,0 +1,14 @@
+<template>
+   <slot />
+</template>
+
+<script setup>
+import { provideAuxiliaryControls, provideFieldBoundary } from "../../composables/useFieldBoundary";
+defineOptions({ inheritAttrs: false });
+const props = defineProps({
+  auxiliary: { type: Boolean, required: false }
+});
+if (props.auxiliary) provideAuxiliaryControls();
+else provideFieldBoundary();
+defineSlots();
+</script>

package/dist/components/core/FieldBoundary.vue.d.ts

@@ -0,0 +1,15 @@
+type __VLS_Props = {
+    auxiliary?: boolean;
+};
+type __VLS_Slots = {
+    default?: () => unknown;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/core/Form.vue

@@ -1,11 +1,12 @@
 <template>
    <form
+      v-if="as === 'form'"
       ref="formRef"
       class="k-form"
       novalidate
       :aria-busy="form.submitting.value ? 'true' : void 0"
-      @submit.prevent="onSubmit"
-      @reset.prevent="onReset"
+      @submit="onSubmitEvent"
+      @reset="onResetEvent"
    >
       <template v-if="alerts === 'start'">
          <slot name="alerts" :errors="rootErrors" :warnings="rootWarnings">
@@ -27,37 +28,115 @@
          </slot>
       </template>
    </form>
+   <div
+      v-else
+      ref="divRef"
+      class="k-form"
+      :aria-busy="form.submitting.value ? 'true' : void 0"
+      @keydown="onKeydown"
+      @click="onClick"
+   >
+      <template v-if="alerts === 'start'">
+         <slot name="alerts" :errors="rootErrors" :warnings="rootWarnings">
+            <FormAlerts :errors="rootErrors" :warnings="rootWarnings" />
+         </slot>
+      </template>
+      <slot
+         :values="form.values"
+         :errors="form.errors"
+         :warnings="form.warnings"
+         :root-errors="rootErrors"
+         :root-warnings="rootWarnings"
+         :dirty="form.dirty.value"
+         :submitting="form.submitting.value"
+      />
+      <template v-if="alerts === 'end'">
+         <slot name="alerts" :errors="rootErrors" :warnings="rootWarnings">
+            <FormAlerts :errors="rootErrors" :warnings="rootWarnings" />
+         </slot>
+      </template>
+   </div>
 </template>
 
 <script setup>
-import { computed, nextTick, provide, useTemplateRef } from "vue";
-import { FORM_KEY } from "../../internal/keys";
-import FormAlerts from "../../internal/forms/FormAlerts.vue";
+import { computed, nextTick, useTemplateRef } from "vue";
+import { provideForm } from "../../composables/useForm";
+import FormAlerts from "./FormAlerts.vue";
 const props = defineProps({
   form: { type: Object, required: true },
+  as: { type: String, required: false, default: "form" },
   focusOnError: { type: Boolean, required: false, default: true },
   alerts: { type: [String, Boolean], required: false, default: "start" }
 });
 const emit = defineEmits(["submitted", "invalid", "reset"]);
 const formRef = useTemplateRef("formRef");
+const divRef = useTemplateRef("divRef");
+const rootRef = computed(() => formRef.value ?? divRef.value);
 const rootErrors = computed(() => props.form.rootErrors?.value ?? []);
 const rootWarnings = computed(() => props.form.rootWarnings?.value ?? []);
-provide(FORM_KEY, props.form);
-async function onSubmit() {
+provideForm(props.form);
+const IMPLICIT_SUBMIT_SKIP = /* @__PURE__ */ new Set([
+  "button",
+  "submit",
+  "reset",
+  "image",
+  "checkbox",
+  "radio",
+  "file",
+  "color",
+  "range",
+  "hidden"
+]);
+function ownsTarget(target) {
+  if (!(target instanceof Element)) return false;
+  return target.closest("form, .k-form") === rootRef.value;
+}
+async function submit() {
   const ok = await props.form.submit();
   if (ok) {
     emit("submitted");
-    return;
+    return true;
   }
   emit("invalid");
-  if (!props.focusOnError) return;
+  if (!props.focusOnError) return false;
   await nextTick();
-  const control = formRef.value?.querySelector('[aria-invalid="true"]');
+  const control = rootRef.value?.querySelector('[aria-invalid="true"]');
   if (control) control.focus();
-  else formRef.value?.querySelector(".k-form-alerts")?.focus();
+  else rootRef.value?.querySelector(".k-form-alerts")?.focus();
+  return false;
 }
-function onReset() {
+function reset() {
   props.form.reset();
   emit("reset");
 }
+function onSubmitEvent(event) {
+  if (event.target !== formRef.value) return;
+  event.preventDefault();
+  void submit();
+}
+function onResetEvent(event) {
+  if (event.target !== formRef.value) return;
+  event.preventDefault();
+  reset();
+}
+function onKeydown(event) {
+  if (event.key !== "Enter" || event.defaultPrevented) return;
+  if (event.isComposing || event.shiftKey || event.altKey) return;
+  const target = event.target;
+  if (!(target instanceof HTMLInputElement) || IMPLICIT_SUBMIT_SKIP.has(target.type)) return;
+  if (!ownsTarget(target)) return;
+  event.preventDefault();
+  void submit();
+}
+function onClick(event) {
+  if (event.defaultPrevented || !(event.target instanceof Element)) return;
+  const button = event.target.closest(
+    'button[type="submit"], button:not([type]), input[type="submit"], button[type="reset"], input[type="reset"]'
+  );
+  if (!button || button.disabled || !ownsTarget(button)) return;
+  event.preventDefault();
+  if (button.type === "reset") reset();
+  else void submit();
+}
+defineExpose({ submit, reset, el: rootRef });
 </script>

package/dist/components/core/Form.vue.d.ts

@@ -2,16 +2,21 @@ import type { FormSchema, UseFormReturn } from '../../composables/useForm';
 declare const __VLS_export: <S extends FormSchema, V extends object>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
     props: import("vue").PublicProps & __VLS_PrettifyLocal<{
         form: UseFormReturn<S, V>;
+        as?: "form" | "div";
         focusOnError?: boolean;
         alerts?: "start" | "end" | false;
     } & {
         onInvalid?: (() => any) | undefined;
         onReset?: (() => any) | undefined;
         onSubmitted?: (() => any) | undefined;
-    } & Partial<import("vue").FormHTMLAttributes & import("vue").ReservedProps>> & (typeof globalThis extends {
+    } & Partial<import("vue").FormHTMLAttributes & import("vue").ReservedProps & import("vue").HTMLAttributes>> & (typeof globalThis extends {
         __VLS_PROPS_FALLBACK: infer P;
     } ? P : {});
-    expose: (exposed: {}) => void;
+    expose: (exposed: import("vue").ShallowUnwrapRef<{
+        submit: () => Promise<boolean>;
+        reset: () => void;
+        el: import("vue").ComputedRef<HTMLElement | null>;
+    }>) => void;
     attrs: any;
     slots: {
         alerts?: (props: {
@@ -33,6 +38,26 @@ declare const __VLS_export: <S extends FormSchema, V extends object>(__VLS_props
             errors: readonly string[];
             warnings: readonly string[];
         }) => any;
+    } & {
+        alerts?: (props: {
+            errors: readonly string[];
+            warnings: readonly string[];
+        }) => any;
+    } & {
+        default?: (props: {
+            values: import("vue").UnwrapRef<V>;
+            errors: import("../../index.ts").FormErrors<S>;
+            warnings: Readonly<import("../../index.ts").FormMessageMap>;
+            rootErrors: readonly string[];
+            rootWarnings: readonly string[];
+            dirty: boolean;
+            submitting: boolean;
+        }) => any;
+    } & {
+        alerts?: (props: {
+            errors: readonly string[];
+            warnings: readonly string[];
+        }) => any;
     };
     emit: ((evt: "invalid") => void) & ((evt: "reset") => void) & ((evt: "submitted") => void);
 }>) => import("vue").VNode & {

package/dist/components/core/FormAlerts.vue

@@ -0,0 +1,30 @@
+<template>
+   <div v-if="errorList.length || warningList.length" class="k-form-alerts" tabindex="-1">
+      <Alert
+         v-for="message in errorList"
+         :key="`error:${message}`"
+         tone="danger"
+         :description="message"
+      />
+      <Alert
+         v-for="message in warningList"
+         :key="`warning:${message}`"
+         tone="warning"
+         role="status"
+         :description="message"
+      />
+   </div>
+</template>
+
+<script setup>
+import { computed } from "vue";
+import { useFormContext } from "../../composables/useForm";
+import Alert from "../feedback/Alert.vue";
+const props = defineProps({
+  errors: { type: Array, required: false },
+  warnings: { type: Array, required: false }
+});
+const form = useFormContext();
+const errorList = computed(() => props.errors ?? form?.rootErrors?.value ?? []);
+const warningList = computed(() => props.warnings ?? form?.rootWarnings?.value ?? []);
+</script>

package/dist/{internal/forms → components/core}/FormAlerts.vue.d.ts

@@ -1,6 +1,6 @@
 declare const __VLS_export: import("vue").DefineComponent<{
-    errors: readonly string[];
-    warnings: readonly string[];
+    errors?: readonly string[];
+    warnings?: readonly string[];
     innerHTML?: string | undefined | undefined;
     class?: import("vue").ClassValue;
     style?: import("vue").StyleValue;
@@ -194,8 +194,8 @@ declare const __VLS_export: import("vue").DefineComponent<{
     ref_for?: boolean | undefined | undefined;
     ref_key?: string | undefined | undefined;
 }, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{
-    errors: readonly string[];
-    warnings: readonly string[];
+    errors?: readonly string[];
+    warnings?: readonly string[];
     innerHTML?: string | undefined | undefined;
     class?: import("vue").ClassValue;
     style?: import("vue").StyleValue;

package/dist/components/core/FormField.vue

@@ -11,7 +11,12 @@
       @animationend="onAnimationEnd"
    >
       <div v-if="hasLabelRow" class="k-form-field-label-row">
-         <label v-if="label || $slots.label" :id="labelId" :for="id" class="k-form-field-label">
+         <label
+            v-if="label || $slots.label"
+            :id="labelId"
+            :for="labelFor"
+            class="k-form-field-label"
+         >
             <Icon v-if="icon" :name="icon" class="k-form-field-label-icon" />
             <span
                ><slot name="label">{{ label }}</slot></span
@@ -53,7 +58,7 @@
 <script setup>
 import { computed, provide, ref, shallowReactive, useId, useSlots, watch } from "vue";
 import { useFormContext } from "../../composables/useForm";
-import { FIELD_KEY } from "../../internal/keys";
+import { FIELD_KEY, FIELD_ROLE_KEY } from "../../internal/keys";
 import FieldMessage from "./FieldMessage.vue";
 import Icon from "./Icon.vue";
 const props = defineProps({
@@ -83,6 +88,14 @@ function setControlError(message, source = fieldSource) {
   else controlErrors.delete(source);
 }
 const controlError = computed(() => controlErrors.values().next().value);
+const labelables = shallowReactive(/* @__PURE__ */ new Map());
+function setLabelable(labelable, source) {
+  if (labelable === void 0) labelables.delete(source);
+  else labelables.set(source, labelable);
+}
+const labelFor = computed(
+  () => [...labelables.values()].some((labelable) => !labelable) ? void 0 : id.value
+);
 const errorMessage = computed(() => {
   if (props.error) return props.error;
   const formError = props.error !== false && props.name ? form?.errors[props.name] : void 0;
@@ -116,9 +129,11 @@ const context = {
   invalid: computed(() => Boolean(errorMessage.value)),
   required: isRequired,
   disabled: computed(() => Boolean(props.disabled)),
-  setControlError
+  setControlError,
+  setLabelable
 };
 provide(FIELD_KEY, context);
+provide(FIELD_ROLE_KEY, "primary");
 const shaking = ref(false);
 watch(
   () => [errorMessage.value, form?.submitCount.value],

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

@@ -1,6 +1,8 @@
 export { default as Button } from './Button.vue';
+export { default as FieldBoundary } from './FieldBoundary.vue';
 export { default as FieldMessage } from './FieldMessage.vue';
 export { default as Form } from './Form.vue';
+export { default as FormAlerts } from './FormAlerts.vue';
 export { default as FormField } from './FormField.vue';
 export { default as Icon } from './Icon.vue';
 export { default as Input } from './Input.vue';

package/dist/components/core/index.mjs

@@ -1,6 +1,8 @@
 export { default as Button } from "./Button.vue";
+export { default as FieldBoundary } from "./FieldBoundary.vue";
 export { default as FieldMessage } from "./FieldMessage.vue";
 export { default as Form } from "./Form.vue";
+export { default as FormAlerts } from "./FormAlerts.vue";
 export { default as FormField } from "./FormField.vue";
 export { default as Icon } from "./Icon.vue";
 export { default as Input } from "./Input.vue";