basalt-ui 1.26.0 → 1.28.0

package/dist/forms/form-layout.d.ts

@@ -0,0 +1,142 @@
+import type { ReactNode } from 'react';
+import type { BasaltProps, SlotStylesProps } from '../common/props.js';
+import type { SlotActions } from '../controls/actions.js';
+import type { WidgetHeaderTitleProps } from '../widget-header/index.js';
+/** The three boxes `FormSection` paints (`common/props.ts`). */
+export type FormSectionSlot = 'root' | 'header' | 'body';
+/**
+ * Composed from the named `WidgetHeaderTitleProps` slice, the same way `SettingsSection` is — so
+ * `icon` and `info` reach the header for free and the four composers cannot drift into four
+ * different title subsets (audit B #2). `value`/`delta` are deliberately not taken: a form section
+ * groups fields, it states no metric.
+ */
+export type FormSectionProps = BasaltProps & SlotStylesProps<FormSectionSlot> & WidgetHeaderTitleProps & {
+    /** The section body — typically a stack of `FormRow`s. */
+    children: ReactNode;
+};
+/**
+ * A titled grouping of form rows: a `WidgetHeader tier="section"` above a stack.
+ *
+ * **Not `Section`, and deliberately not a card.** `Section` is a collapsible, persistable page
+ * widget with its own surface; a form is usually already inside one, and nesting a second card per
+ * fieldset is the "two cards deep" a settings page reads as. This paints no background, no border
+ * and no shadow — only the heading and the rhythm.
+ *
+ * @example
+ * <FormSection title="Billing" subtitle="Where the invoice goes.">
+ *   <FormRow label="Company">
+ *     <TextInput key={fieldKey(form, 'company')} {...inputProps(form, 'company')} />
+ *   </FormRow>
+ *   <FormRow label="VAT ID">
+ *     <TextInput key={fieldKey(form, 'vat')} {...inputProps(form, 'vat')} />
+ *   </FormRow>
+ * </FormSection>
+ */
+export declare function FormSection(props: FormSectionProps): import("react").JSX.Element;
+/** The three boxes `FormRow` paints (`common/props.ts`). */
+export type FormRowSlot = 'root' | 'label' | 'control';
+export type FormRowProps = BasaltProps & SlotStylesProps<FormRowSlot> & {
+    /** The field's label. Ink, `--vx-text-md` — the same weight `SettingsRow` gives its own. */
+    label: string;
+    /** Muted line under the label: the rule, the unit, the example. Never the error. */
+    hint?: string;
+    /**
+     * The field's error, rendered under the control. Falsy renders nothing. For a Mantine input
+     * wired through `inputProps(form, path)`, Mantine's own `Input.Wrapper` already renders
+     * `form.errors[path]` — passing it here too would render it twice. Reserve this prop for
+     * children that render no error of their own: a raw input, a custom control.
+     */
+    error?: ReactNode;
+    /** Marks the field required: an accent `*` for sighted readers, `(required)` for assistive tech. */
+    required?: boolean;
+    /**
+     * Associates the `<label>` with the control's id. Mantine generates one per input, so pass the
+     * SAME `id` to both. Without it the row's label is a caption, not a label — which is why a
+     * control carrying its OWN `label` prop should not also sit under a `FormRow` label.
+     */
+    htmlFor?: string;
+    /** The control. Anything: a Mantine input, a segmented control, a consumer's own widget. */
+    children: ReactNode;
+};
+/**
+ * One labelled field: label left / control right on desktop, label above the control below `sm`.
+ * The swap is CSS (law C9) — no `useMediaQuery`, so it is correct in SSR markup and it costs no
+ * render.
+ *
+ * The control region is a `<fieldset>` that goes `disabled` whenever the enclosing
+ * `FormStateProvider` says the form is busy, which is the whole disabled-propagation story: no
+ * `disabled` prop to thread, no `cloneElement`, real `:disabled` styling from Mantine.
+ *
+ * @example
+ * // A Mantine input wired through inputProps already renders its own error via Input.Wrapper —
+ * // omit `error` here, or it renders twice.
+ * <FormRow label="Email" hint="We only use it for receipts." required>
+ *   <TextInput key={fieldKey(form, 'email')} {...inputProps(form, 'email')} />
+ * </FormRow>
+ *
+ * @example
+ * // A raw control renders no error of its own — pass it explicitly.
+ * <FormRow label="Email" required error={form.errors['email']}>
+ *   <input value={form.values.email} onChange={(e) => form.setFieldValue('email', e.target.value)} />
+ * </FormRow>
+ */
+export declare function FormRow(props: FormRowProps): import("react").JSX.Element;
+export type FormGroupProps = BasaltProps & {
+    /** The group's label, rendered as the fieldset's `<legend>` — the accessible name of the cluster. */
+    label: string;
+    /** Muted line under the legend. */
+    hint?: string;
+    /** The group-level error, rendered under the controls. */
+    error?: ReactNode;
+    /** Marks the group required — same two-channel treatment as `FormRow`. */
+    required?: boolean;
+    /** `column` stacks the options; `row` lays them out inline and wraps. @default 'column' */
+    direction?: 'row' | 'column';
+    /** The cluster — checkboxes, radios, chips. */
+    children: ReactNode;
+};
+/**
+ * A labelled cluster of related controls: a checkbox group, a radio group, a set of chips.
+ *
+ * **The label is ALWAYS above**, never beside — a `FormRow`'s side-by-side geometry breaks the
+ * moment the right column holds four stacked checkboxes rather than one input. That is the whole
+ * reason this is a second primitive and not a `FormRow` variant.
+ *
+ * It renders a real `<fieldset>` + `<legend>`, which is the correct grouping semantic for a set of
+ * inputs sharing one question — and, as with `FormRow`, is what makes the `FormStateProvider`
+ * disable propagate natively.
+ *
+ * @example
+ * <FormGroup label="Notify me about" direction="row">
+ *   <Checkbox key={fieldKey(form, 'onDeploy')} {...inputProps(form, 'onDeploy')} label="Deploys" />
+ *   <Checkbox key={fieldKey(form, 'onError')} {...inputProps(form, 'onError')} label="Errors" />
+ * </FormGroup>
+ */
+export declare function FormGroup(props: FormGroupProps): import("react").JSX.Element;
+export type FormActionsProps = BasaltProps & {
+    /**
+     * The submit/cancel row, in either form law C15 accepts: typed `BarAction[]` DATA — which basalt
+     * projects, budgets and folds into a `More` menu past three — or an opaque `ReactNode` the caller
+     * drew itself. Rendered through the SAME `BarActionSlot` every other home uses, so a form's
+     * actions and a page bar's cannot look like two different vocabularies.
+     *
+     * A `BarAction` renders a `type="button"`, so a typed submit is `onClick: submit`; a native
+     * `<Button type="submit">` goes through the node arm.
+     */
+    actions: SlotActions;
+};
+/**
+ * The row a form ends on. Trailing-aligned, wrapping, and `disabled` as a unit while the enclosing
+ * `FormStateProvider` reports a submit in flight — which is what stops the double-submit that
+ * a per-button `loading` prop only hides.
+ *
+ * @example
+ * <FormActions
+ *   actions={[
+ *     { key: 'cancel', label: 'Cancel', onClick: close },
+ *     { key: 'save', label: 'Save', onClick: submit },
+ *   ]}
+ * />
+ */
+export declare function FormActions(props: FormActionsProps): import("react").JSX.Element;
+//# sourceMappingURL=form-layout.d.ts.map

package/dist/forms/form-layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-layout.d.ts","sourceRoot":"","sources":["../../src/forms/form-layout.tsx"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAGnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAEtD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAA;AAyC9D,gEAAgE;AAChE,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAA;AAExD;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,WAAW,GACxC,eAAe,CAAC,eAAe,CAAC,GAChC,sBAAsB,GAAG;IACvB,0DAA0D;IAC1D,QAAQ,EAAE,SAAS,CAAA;CACpB,CAAA;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,+BAoBlD;AAID,4DAA4D;AAC5D,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAA;AAEtD,MAAM,MAAM,YAAY,GAAG,WAAW,GACpC,eAAe,CAAC,WAAW,CAAC,GAAG;IAC7B,4FAA4F;IAC5F,KAAK,EAAE,MAAM,CAAA;IACb,oFAAoF;IACpF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;OAKG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,oGAAoG;IACpG,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4FAA4F;IAC5F,QAAQ,EAAE,SAAS,CAAA;CACpB,CAAA;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,YAAY,+BAwB1C;AAID,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG;IACzC,qGAAqG;IACrG,KAAK,EAAE,MAAM,CAAA;IACb,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,0DAA0D;IAC1D,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,2FAA2F;IAC3F,SAAS,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAA;IAC5B,+CAA+C;IAC/C,QAAQ,EAAE,SAAS,CAAA;CACpB,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,+BAsB9C;AAID,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG;IAC3C;;;;;;;;OAQG;IACH,OAAO,EAAE,WAAW,CAAA;CACrB,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,+BAgBlD"}

package/dist/forms/form-layout.js

@@ -0,0 +1,110 @@
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { VisuallyHidden } from "@mantine/core";
+import { cx } from "../common/props.js";
+import { assertRequiredProps } from "../common/validate.js";
+import { BarActionSlot } from "../controls/actions.js";
+import { WidgetHeader } from "../widget-header/index.js";
+import { useFormState } from "./form-state.js";
+import classes from "./form-layout.module.css";
+function RequiredMark({ required }) {
+  if (required !== true) return null;
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx("span", { "aria-hidden": "true", className: classes.required, children: "*" }),
+    /* @__PURE__ */ jsx(VisuallyHidden, { children: "(required)" })
+  ] });
+}
+function FieldError({ error }) {
+  if (error === void 0 || error === null || error === false) return null;
+  return /* @__PURE__ */ jsx("span", { className: classes.error, children: error });
+}
+function FormSection(props) {
+  assertRequiredProps("FormSection", props, ["title"]);
+  const { title, icon, subtitle, info, children, className, style, classNames } = props;
+  return /* @__PURE__ */ jsxs(
+    "section",
+    {
+      className: cx(classes.section, classNames?.root, className),
+      ...style !== void 0 && { style },
+      children: [
+        /* @__PURE__ */ jsx(
+          WidgetHeader,
+          {
+            tier: "section",
+            title,
+            ...icon !== void 0 && { icon },
+            ...subtitle !== void 0 && { subtitle },
+            ...info !== void 0 && { info },
+            ...classNames?.header !== void 0 && { className: classNames.header }
+          }
+        ),
+        /* @__PURE__ */ jsx("div", { className: cx(classes.sectionBody, classNames?.body), children })
+      ]
+    }
+  );
+}
+function FormRow(props) {
+  assertRequiredProps("FormRow", props, ["label"]);
+  const { label, hint, error, required, htmlFor, children, className, style, classNames } = props;
+  const { disabled } = useFormState();
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: cx(classes.row, classNames?.root, className),
+      ...style !== void 0 && { style },
+      children: [
+        /* @__PURE__ */ jsxs("div", { className: cx(classes.rowLabel, classNames?.label), children: [
+          /* @__PURE__ */ jsxs("label", { className: classes.label, ...htmlFor !== void 0 && { htmlFor }, children: [
+            label,
+            /* @__PURE__ */ jsx(RequiredMark, { required })
+          ] }),
+          hint !== void 0 && /* @__PURE__ */ jsx("span", { className: classes.hint, children: hint })
+        ] }),
+        /* @__PURE__ */ jsxs("fieldset", { className: cx(classes.control, classNames?.control), disabled, children: [
+          children,
+          /* @__PURE__ */ jsx(FieldError, { error })
+        ] })
+      ]
+    }
+  );
+}
+function FormGroup(props) {
+  assertRequiredProps("FormGroup", props, ["label"]);
+  const { label, hint, error, required, direction = "column", children, className, style } = props;
+  const { disabled } = useFormState();
+  return /* @__PURE__ */ jsxs(
+    "fieldset",
+    {
+      className: cx(classes.group, className),
+      disabled,
+      ...style !== void 0 && { style },
+      children: [
+        /* @__PURE__ */ jsxs("legend", { className: classes.legend, children: [
+          label,
+          /* @__PURE__ */ jsx(RequiredMark, { required })
+        ] }),
+        hint !== void 0 && /* @__PURE__ */ jsx("span", { className: classes.hint, children: hint }),
+        /* @__PURE__ */ jsx("div", { className: classes.groupControls, "data-direction": direction, children }),
+        /* @__PURE__ */ jsx(FieldError, { error })
+      ]
+    }
+  );
+}
+function FormActions(props) {
+  const { actions, className, style } = props;
+  const { disabled } = useFormState();
+  return /* @__PURE__ */ jsx(
+    "fieldset",
+    {
+      className: cx(classes.actions, className),
+      disabled,
+      ...style !== void 0 && { style },
+      children: /* @__PURE__ */ jsx(BarActionSlot, { actions })
+    }
+  );
+}
+export {
+  FormActions,
+  FormGroup,
+  FormRow,
+  FormSection
+};

package/dist/forms/form-layout.module.css

@@ -0,0 +1,145 @@
+/*
+ * The form layout law (law C1's THIRD home — the form row), in CSS.
+ *
+ * Every gap here is a density-tracking `--vx-space-*` token, so `createBasaltTheme({ density })`
+ * moves a form the same way it moves a settings page. The two settings tokens are reused
+ * deliberately rather than forked: a form row and a `SettingsRow` are the same shape at the same
+ * rhythm, and a second pair of numbers is how the two drift apart.
+ *
+ * The `47.99375em` literal is the `sm` breakpoint (law C9 — the responsive swap is CSS, never a JS
+ * media query). A `@media` condition cannot read a custom property, so the number is written.
+ */
+
+/* ── FormSection ─────────────────────────────────────────────────────────────────────────────── */
+
+.section {
+  display: flex;
+  flex-direction: column;
+  gap: var(--vx-space-stack-sm);
+}
+
+.sectionBody {
+  display: flex;
+  flex-direction: column;
+  gap: var(--vx-space-stack-md);
+}
+
+/* ── FormRow ─────────────────────────────────────────────────────────────────────────────────── */
+
+/*
+ * Label left, control right. The control column is the wider one: a label is a phrase, a control is
+ * an input that has to hold real content. `align-items: start` so a two-line label does not centre
+ * itself against a one-line input.
+ */
+.row {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) minmax(0, 1.4fr);
+  align-items: start;
+  gap: var(--vx-space-settings-row-gap);
+}
+
+.rowLabel {
+  display: flex;
+  flex-direction: column;
+  gap: var(--vx-space-stack-xs);
+  min-inline-size: 0;
+}
+
+.label {
+  font-size: var(--vx-text-md);
+  color: var(--vx-ink);
+}
+
+.hint {
+  font-size: var(--vx-text-sm);
+  color: var(--vx-muted);
+}
+
+.required {
+  color: var(--vx-status-bad);
+  margin-inline-start: var(--vx-space-stack-xs);
+}
+
+/*
+ * The control cell is a `fieldset` — see `form-state.tsx` for why. Every one of these five
+ * declarations is undoing a UA default (border, padding, margin, min-inline-size: min-content),
+ * not styling: a fieldset that keeps them draws a box around every row and refuses to shrink.
+ */
+.control {
+  display: flex;
+  flex-direction: column;
+  gap: var(--vx-space-stack-xs);
+  min-inline-size: 0;
+  border: 0;
+  margin: 0;
+  padding: 0;
+}
+
+.error {
+  font-size: var(--vx-text-sm);
+  color: var(--vx-status-bad);
+}
+
+/* The phone twin: the control needs the full width, so the label goes above it. */
+@media (max-width: 47.99375em) {
+  .row {
+    grid-template-columns: minmax(0, 1fr);
+    gap: var(--vx-space-stack-xs);
+  }
+}
+
+/* ── FormGroup ───────────────────────────────────────────────────────────────────────────────── */
+
+/* Same UA reset as `.control`, same reason. */
+.group {
+  display: flex;
+  flex-direction: column;
+  gap: var(--vx-space-stack-xs);
+  min-inline-size: 0;
+  border: 0;
+  margin: 0;
+  padding: 0;
+}
+
+/*
+ * A `<legend>` is absolutely positioned into the fieldset's border by the UA. With no border to sit
+ * in, `float: left` + `width: 100%` is the one portable way to put it back in normal flow.
+ */
+.legend {
+  float: left;
+  width: 100%;
+  padding: 0;
+  font-size: var(--vx-text-md);
+  color: var(--vx-ink);
+}
+
+.groupControls {
+  display: flex;
+  clear: both;
+}
+
+.groupControls[data-direction='column'] {
+  flex-direction: column;
+  gap: var(--vx-space-stack-xs);
+}
+
+.groupControls[data-direction='row'] {
+  flex-direction: row;
+  flex-wrap: wrap;
+  gap: var(--vx-space-control-gap);
+}
+
+/* ── FormActions ─────────────────────────────────────────────────────────────────────────────── */
+
+/* Same UA reset again. Trailing-aligned: the confirming action is where the eye leaves the form. */
+.actions {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: flex-end;
+  align-items: center;
+  gap: var(--vx-space-control-gap);
+  min-inline-size: 0;
+  border: 0;
+  margin: 0;
+  padding: 0;
+}

package/dist/forms/form-layout.module.css.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Typed CSS-module declaration (the S4 CSS-modules path). Named string props — not an index
+ * signature — so dot access stays verbatim under the package's strict flags.
+ */
+declare const classes: {
+  readonly section: string
+  readonly sectionBody: string
+  readonly row: string
+  readonly rowLabel: string
+  readonly label: string
+  readonly hint: string
+  readonly required: string
+  readonly control: string
+  readonly error: string
+  readonly group: string
+  readonly legend: string
+  readonly groupControls: string
+  readonly actions: string
+}
+export default classes

package/dist/forms/form-state.d.ts

@@ -0,0 +1,42 @@
+import type { ReactNode } from 'react';
+/**
+ * What a control in this subtree needs to know. Two fields on purpose:
+ *
+ * - `disabled` is the RESOLVED verdict — bind a control's `disabled` to it and nothing else. It is
+ *   already true while `submitting` is, so a call site never writes `disabled || submitting` and
+ *   never gets that `||` backwards.
+ * - `submitting` is the REASON, for a control that renders differently for it (a button showing a
+ *   loader) rather than merely inertly.
+ */
+export type FormState = {
+    readonly disabled: boolean;
+    readonly submitting: boolean;
+};
+export type FormStateProviderProps = {
+    /** Disable every control below, for a reason of the caller's own (no permission, read-only view). */
+    disabled?: boolean;
+    /** A submit is in flight — pair with `useFormSubmit`'s `isSubmitting`. Implies `disabled`. */
+    submitting?: boolean;
+    children: ReactNode;
+};
+/**
+ * Publishes the form's busy/disabled state to every layout primitive below it.
+ *
+ * **Nesting ORs, it never resets**: an inner `<FormStateProvider>` can disable a subsection of an
+ * enabled form, but cannot re-enable a subsection of a disabled one. A form that is submitting is
+ * submitting everywhere, and a provider that could unset that is a double-submit waiting for the
+ * one call site that used it.
+ */
+export declare function FormStateProvider({ disabled, submitting, children, }: FormStateProviderProps): import("react").JSX.Element;
+/**
+ * The form state a custom (non-native) control has to honour itself. Outside any provider it reads
+ * `{ disabled: false, submitting: false }` — a control is never disabled by accident of placement.
+ *
+ * @example
+ * function ColorSwatches() {
+ *   const { disabled } = useFormState()
+ *   return <div aria-disabled={disabled}>…</div>
+ * }
+ */
+export declare function useFormState(): FormState;
+//# sourceMappingURL=form-state.d.ts.map

package/dist/forms/form-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-state.d.ts","sourceRoot":"","sources":["../../src/forms/form-state.tsx"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;CAC7B,CAAA;AAMD,MAAM,MAAM,sBAAsB,GAAG;IACnC,qGAAqG;IACrG,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,8FAA8F;IAC9F,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,QAAQ,EAAE,SAAS,CAAA;CACpB,CAAA;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,QAAgB,EAChB,UAAkB,EAClB,QAAQ,GACT,EAAE,sBAAsB,+BAUxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,IAAI,SAAS,CAExC"}

package/dist/forms/form-state.js

@@ -0,0 +1,26 @@
+import { jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from "react";
+const DEFAULT_FORM_STATE = { disabled: false, submitting: false };
+const FormStateContext = createContext(DEFAULT_FORM_STATE);
+function FormStateProvider({
+  disabled = false,
+  submitting = false,
+  children
+}) {
+  const parent = useContext(FormStateContext);
+  const value = useMemo(
+    () => ({
+      disabled: parent.disabled || disabled || submitting,
+      submitting: parent.submitting || submitting
+    }),
+    [parent.disabled, parent.submitting, disabled, submitting]
+  );
+  return /* @__PURE__ */ jsx(FormStateContext.Provider, { value, children });
+}
+function useFormState() {
+  return useContext(FormStateContext);
+}
+export {
+  FormStateProvider,
+  useFormState
+};

package/dist/forms/index.d.ts

@@ -1,16 +1,32 @@
 /**
- * ./forms — Mantine form adapter battery.
- * Provides useBasaltForm, field, FormErrorSummary, and useFormDraft on top of @mantine/form.
- * Optional peer: @mantine/form ^9.3.0.
+ * ./forms — the Mantine form layer.
  *
- * Install with: bun add @mantine/form
+ * Subpath-ONLY, deliberately: the root barrel re-exports nothing from here (`src/index.ts`), so a
+ * consumer without `@mantine/form` installed never pulls an unresolvable import in by importing
+ * `basalt-ui`. Same reason `./charts` and `./tokens` stay off the root barrel, one optional peer
+ * over. Import everything below from `basalt-ui/forms`.
+ *
+ * Five pieces: the form (`useBasaltForm` + `inputProps`/`fieldKey`), the layout
+ * (`FormSection` / `FormRow` / `FormGroup` / `FormActions`), the submit lifecycle
+ * (`useFormSubmit` + `FormStateProvider`), the list field (`useFieldArray`) and the draft
+ * (`useFormDraft`).
+ *
+ * Optional peer: @mantine/form ^9.3.0 — install with: bun add @mantine/form
  */
 export { useBasaltForm } from './create-form.js';
 export type { UseBasaltFormOptions } from './create-form.js';
-export { field } from './field.js';
+export { inputProps, fieldKey, field } from './field.js';
+export { FormSection, FormRow, FormGroup, FormActions } from './form-layout.js';
+export type { FormSectionProps, FormSectionSlot, FormRowProps, FormRowSlot, FormGroupProps, FormActionsProps, } from './form-layout.js';
+export { useFormSubmit, isFieldErrorEnvelope } from './use-form-submit.js';
+export type { FormFieldErrors, UseFormSubmitOptions, UseFormSubmitReturn } from './use-form-submit.js';
+export { FormStateProvider, useFormState } from './form-state.js';
+export type { FormState, FormStateProviderProps } from './form-state.js';
+export { useFieldArray } from './use-field-array.js';
+export type { UseFieldArrayReturn } from './use-field-array.js';
 export { FormErrorSummary } from './FormErrorSummary.js';
 export type { FormErrorSummaryProps } from './FormErrorSummary.js';
-export { useFormDraft } from './use-form-draft.js';
+export { useFormDraft, DEFAULT_AUTOSAVE_DEBOUNCE_MS } from './use-form-draft.js';
 export type { UseFormDraftOptions, UseFormDraftReturn } from './use-form-draft.js';
 export { useForm, schemaResolver } from '@mantine/form';
 export type { UseFormReturnType, UseFormInput } from '@mantine/form';

package/dist/forms/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/forms/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAC7C,YAAY,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA;AAGzD,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAG/B,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AACrD,YAAY,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AAG/D,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,YAAY,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAG/E,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AACvD,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/forms/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAC7C,YAAY,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA;AAKzD,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAGrD,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC5E,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,WAAW,EACX,cAAc,EACd,gBAAgB,GACjB,MAAM,eAAe,CAAA;AAGtB,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AACvE,YAAY,EAAE,eAAe,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AACnG,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAC9D,YAAY,EAAE,SAAS,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAA;AAGrE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACjD,YAAY,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AAG5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AACrD,YAAY,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AAG/D,OAAO,EAAE,YAAY,EAAE,4BAA4B,EAAE,MAAM,kBAAkB,CAAA;AAC7E,YAAY,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAG/E,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AACvD,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA"}

package/dist/forms/index.js

@@ -1,13 +1,29 @@
 import { useBasaltForm } from "./create-form.js";
-import { field } from "./field.js";
+import { inputProps, fieldKey, field } from "./field.js";
+import { FormSection, FormRow, FormGroup, FormActions } from "./form-layout.js";
+import { useFormSubmit, isFieldErrorEnvelope } from "./use-form-submit.js";
+import { FormStateProvider, useFormState } from "./form-state.js";
+import { useFieldArray } from "./use-field-array.js";
 import { FormErrorSummary } from "./FormErrorSummary.js";
-import { useFormDraft } from "./use-form-draft.js";
+import { useFormDraft, DEFAULT_AUTOSAVE_DEBOUNCE_MS } from "./use-form-draft.js";
 import { useForm, schemaResolver } from "@mantine/form";
 export {
+  DEFAULT_AUTOSAVE_DEBOUNCE_MS,
+  FormActions,
   FormErrorSummary,
+  FormGroup,
+  FormRow,
+  FormSection,
+  FormStateProvider,
   field,
+  fieldKey,
+  inputProps,
+  isFieldErrorEnvelope,
   schemaResolver,
   useBasaltForm,
+  useFieldArray,
   useForm,
-  useFormDraft
+  useFormDraft,
+  useFormState,
+  useFormSubmit
 };

package/dist/forms/use-field-array.d.ts

@@ -0,0 +1,60 @@
+/**
+ * ./forms — useFieldArray: the list-field surface over Mantine's four list actions.
+ * Mantine-coupled. Optional peer: @mantine/form.
+ *
+ * The gap (audit B §4): `insertListItem` / `removeListItem` / `reorderListItem` are all reachable
+ * off the raw form object, but they are unexported by name, undocumented in the forms doctrine, and
+ * each takes a different argument shape (`(path, item, index?)`, `(path, index)`,
+ * `(path, { from, to })`). The list ALSO has to be read back out of the values by dotted path, and
+ * every row needs `form.key(\`${path}.${i}\`)` or the uncontrolled reconciler reuses the wrong DOM
+ * node when a row is removed from the middle — which is the defect this hook exists to make
+ * unwritable.
+ */
+import type { FormArrayElement, LooseKeys, UseFormReturnType } from '@mantine/form';
+export type UseFieldArrayReturn<Item> = {
+    /** The live list. `[]` when the path holds nothing, so a call site never guards before mapping. */
+    items: Item[];
+    /** Push one item onto the end. */
+    append: (value: Item) => void;
+    /** Drop the item at `index`. Mantine re-indexes the field errors with it. */
+    remove: (index: number) => void;
+    /** Move one item, e.g. from a drag handle or a pair of arrow buttons. */
+    move: (from: number, to: number) => void;
+    /**
+     * Mantine's reconciler key for row `index` (`form.key('<path>.<index>')`) — pass it as the row's
+     * JSX `key`, never spread it.
+     *
+     * **Positional, and that is a real limit worth stating**: it identifies the SLOT, not the item.
+     * Mantine's list actions write values through `$values` directly and never bump the form-level
+     * key generation (verified in 9.3.2's use-form-list), so removing row 0 does not change row 0's
+     * key — it changes which item sits there. That is correct for an append/remove list, where the
+     * uncontrolled inputs below re-read their `defaultValue` from the new values anyway. A list the
+     * USER reorders wants an identity key instead: put a `randomId()` on the item and key the row on
+     * that.
+     */
+    key: (index: number) => string;
+};
+/**
+ * Reads and edits a list field as one object.
+ *
+ * **`items` is read from `form.getValues()`, not from `form.values`**, so it is correct under the
+ * `mode: 'uncontrolled'` default `useBasaltForm` sets: the list actions all re-render the form
+ * (they call `setValues` with `updateState: true`), so the snapshot this returns is the one the
+ * caller just produced.
+ *
+ * @example
+ * const items = useFieldArray(form, 'contacts')
+ *
+ * {items.items.map((_, index) => (
+ *   <FormRow key={items.key(index)} label={`Contact ${index + 1}`}>
+ *     <TextInput
+ *       key={fieldKey(form, `contacts.${index}.email`)}
+ *       {...inputProps(form, `contacts.${index}.email`)}
+ *     />
+ *     <Button onClick={() => items.remove(index)}>Remove</Button>
+ *   </FormRow>
+ * ))}
+ * <Button onClick={() => items.append({ email: '' })}>Add contact</Button>
+ */
+export declare function useFieldArray<Values extends Record<string, unknown>, Path extends LooseKeys<Values>>(form: UseFormReturnType<Values>, path: Path): UseFieldArrayReturn<FormArrayElement<Values, Path & string>>;
+//# sourceMappingURL=use-field-array.d.ts.map

package/dist/forms/use-field-array.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-field-array.d.ts","sourceRoot":"","sources":["../../src/forms/use-field-array.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAEnF,MAAM,MAAM,mBAAmB,CAAC,IAAI,IAAI;IACtC,mGAAmG;IACnG,KAAK,EAAE,IAAI,EAAE,CAAA;IACb,kCAAkC;IAClC,MAAM,EAAE,CAAC,KAAK,EAAE,IAAI,KAAK,IAAI,CAAA;IAC7B,6EAA6E;IAC7E,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IAC/B,yEAAyE;IACzE,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;IACxC;;;;;;;;;;;OAWG;IACH,GAAG,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;CAC/B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAC3B,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACtC,IAAI,SAAS,SAAS,CAAC,MAAM,CAAC,EAE9B,IAAI,EAAE,iBAAiB,CAAC,MAAM,CAAC,EAC/B,IAAI,EAAE,IAAI,GACT,mBAAmB,CAAC,gBAAgB,CAAC,MAAM,EAAE,IAAI,GAAG,MAAM,CAAC,CAAC,CAU9D"}

package/dist/forms/use-field-array.js

@@ -0,0 +1,20 @@
+function useFieldArray(form, path) {
+  return {
+    items: readList(form.getValues(), String(path)),
+    append: (value) => form.insertListItem(path, value),
+    remove: (index) => form.removeListItem(path, index),
+    move: (from, to) => form.reorderListItem(path, { from, to }),
+    key: (index) => form.key(`${String(path)}.${index}`)
+  };
+}
+function readList(values, path) {
+  let current = values;
+  for (const segment of path.split(".")) {
+    if (current === null || typeof current !== "object") return [];
+    current = current[segment];
+  }
+  return Array.isArray(current) ? current : [];
+}
+export {
+  useFieldArray
+};