@godxjp/ui 18.13.0 → 18.14.0

package/dist/components/data-entry/form-errors.d.ts

@@ -0,0 +1,45 @@
+import * as React from "react";
+import type { FormErrorsProp, FormErrorsProviderProp } from "../../props/components/data-entry.prop.js";
+import type { ErrorBagProp } from "../../props/vocabulary/index.js";
+export type { FormErrorsProp, FormErrorsProp as FormErrorsProps, FormErrorsProviderProp, FormErrorsProviderProp as FormErrorsProviderProps, } from "../../props/components/data-entry.prop.js";
+/**
+ * Registry shared by a `Form` with its FormFields and `<FormErrors />`. Each mounted
+ * `FormField name="…"` CLAIMS its error-bag key (it is the visible owner of that message);
+ * `<FormErrors />` renders only the unclaimed remainder. Claims are reference-counted so
+ * duplicate names and unmount order stay correct.
+ */
+interface FormErrorsRegistryValue {
+    errors: ErrorBagProp;
+    claimed: ReadonlyMap<string, number>;
+    /** Claim `key`; returns the release function (stable identity — safe as an effect dep). */
+    claim: (key: string) => () => void;
+}
+/** Read the nearest Form's error registry (null when used outside a Form). */
+export declare function useFormErrorsRegistry(): FormErrorsRegistryValue | null;
+/** First message of a bag entry — Laravel arrays surface their first message on the field. */
+export declare function firstBagMessage(entry: string | string[] | undefined): string | undefined;
+/**
+ * FormErrorsProvider — one shared error registry (error bag + claim set) over a region.
+ * 兄弟 Form 群で 1 つのエラーバッグを共有するための公開プロバイダ。Two ways to get one:
+ *
+ * 1. `Form errors={…}` renders this provider itself (both `<form>` and `asChild` modes) —
+ *    the single-form case needs nothing else.
+ * 2. An edit screen split into several sibling Card+Form sections (the standard exseli shape)
+ *    wraps the REGION in `<FormErrorsProvider errors={…}>` instead: Forms **without** their own
+ *    `errors` join the surrounding registry, every `FormField name="…"` inside claims into it,
+ *    and one `<FormErrors />` anywhere in the region renders the unclaimed remainder.
+ *
+ * A nested Form WITH its own `errors` starts a new registry that shadows this one — its claims
+ * and messages stay inside it.
+ */
+export declare function FormErrorsProvider({ errors, children }: FormErrorsProviderProp): React.JSX.Element;
+/** FormField calls this to claim its error-bag key while mounted (no-op outside a Form). */
+export declare function useClaimErrorKey(name: string | undefined): void;
+/**
+ * FormErrors — renders the error-bag entries no mounted `FormField name="…"` displays: server
+ * validation errors attached to hidden/derived fields (an `action_mode`, a `page`, a source-record
+ * id) that would otherwise fail silently. Place it inside a `Form errors={…}` — typically above
+ * the fields; it renders nothing while every entry is claimed or the bag is empty. Composed on
+ * `Alert tone="destructive"` (role="alert"), so appearing messages are announced assertively.
+ */
+export declare function FormErrors({ errors: errorsProp, title, className }: FormErrorsProp): React.JSX.Element | null;

package/dist/components/data-entry/form-errors.js

@@ -0,0 +1,71 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { useTranslation } from "../../i18n/use-translation.js";
+import { Alert, AlertContent, AlertDescription, AlertTitle } from "../feedback/alert.js";
+const useIsomorphicLayoutEffect = typeof window === "undefined" ? React.useEffect : React.useLayoutEffect;
+const FormErrorsRegistryContext = React.createContext(null);
+function useFormErrorsRegistry() {
+  return React.useContext(FormErrorsRegistryContext);
+}
+function firstBagMessage(entry) {
+  const message = Array.isArray(entry) ? entry[0] : entry;
+  return message ? message : void 0;
+}
+function FormErrorsProvider({ errors, children }) {
+  const [claimed, setClaimed] = React.useState(/* @__PURE__ */ new Map());
+  const claim = React.useCallback((key) => {
+    setClaimed((prev) => {
+      const next = new Map(prev);
+      next.set(key, (next.get(key) ?? 0) + 1);
+      return next;
+    });
+    return () => {
+      setClaimed((prev) => {
+        const next = new Map(prev);
+        const count = (next.get(key) ?? 0) - 1;
+        if (count <= 0) next.delete(key);
+        else next.set(key, count);
+        return next;
+      });
+    };
+  }, []);
+  const value = React.useMemo(
+    () => ({ errors: errors ?? {}, claimed, claim }),
+    [errors, claimed, claim]
+  );
+  return /* @__PURE__ */ jsx(FormErrorsRegistryContext.Provider, { value, children });
+}
+function useClaimErrorKey(name) {
+  const registry = useFormErrorsRegistry();
+  const claim = registry?.claim;
+  useIsomorphicLayoutEffect(() => {
+    if (!name || !claim) return;
+    return claim(name);
+  }, [name, claim]);
+}
+function FormErrors({ errors: errorsProp, title, className }) {
+  const { t } = useTranslation();
+  const registry = useFormErrorsRegistry();
+  const errors = errorsProp ?? registry?.errors;
+  const claimed = registry?.claimed;
+  const messages = [];
+  for (const [key, entry] of Object.entries(errors ?? {})) {
+    if (entry == null || (claimed?.get(key) ?? 0) > 0) continue;
+    for (const message of Array.isArray(entry) ? entry : [entry]) {
+      if (message) messages.push({ key, message });
+    }
+  }
+  if (!messages.length) return null;
+  return /* @__PURE__ */ jsx(Alert, { tone: "destructive", className, children: /* @__PURE__ */ jsxs(AlertContent, { children: [
+    /* @__PURE__ */ jsx(AlertTitle, { children: title ?? t("dataEntry.formErrors.title") }),
+    messages.map(({ key, message }, index) => /* @__PURE__ */ jsx(AlertDescription, { children: message }, `${key}-${index}`))
+  ] }) });
+}
+export {
+  FormErrors,
+  FormErrorsProvider,
+  firstBagMessage,
+  useClaimErrorKey,
+  useFormErrorsRegistry
+};

package/dist/components/data-entry/form-field.d.ts

@@ -1,4 +1,4 @@
 import * as React from "react";
 import type { FormFieldProp } from "../../props/components/data-entry.prop.js";
 export type { FormFieldProp, FormFieldProp as FormFieldProps, } from "../../props/components/data-entry.prop.js";
-export declare function FormField({ id, label, required, helper, error, labelAddon, layout: layoutProp, labelWidth: labelWidthProp, controlWidth: controlWidthProp, colSpan, className, children, staticText, }: FormFieldProp): React.JSX.Element;
+export declare function FormField({ id, name, label, required, helper, error: errorProp, labelAddon, layout: layoutProp, labelWidth: labelWidthProp, controlWidth: controlWidthProp, colSpan, className, children, staticText, }: FormFieldProp): React.JSX.Element;

package/dist/components/data-entry/form-field.js

@@ -3,16 +3,18 @@ import { jsx, jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { Label } from "../data-entry/label.js";
 import { cn } from "../../lib/utils.js";
-import { mergeAriaIds } from "../../lib/field-a11y.js";
+import { FieldNameContext, mergeAriaIds } from "../../lib/field-a11y.js";
 import { useFormLayout } from "./form.js";
+import { firstBagMessage, useClaimErrorKey, useFormErrorsRegistry } from "./form-errors.js";
 const toCssLength = (v) => typeof v === "number" ? `${v}px` : v;
 const FOCUSABLE_SELECTOR = 'input:not([type="hidden"]), select, textarea, button, [tabindex]:not([tabindex="-1"])';
 function FormField({
   id,
+  name,
   label,
   required,
   helper,
-  error,
+  error: errorProp,
   labelAddon,
   layout: layoutProp,
   labelWidth: labelWidthProp,
@@ -28,6 +30,9 @@ function FormField({
   const controlWidth = controlWidthProp ?? form?.controlWidth;
   const labelAlign = form?.labelAlign ?? "end";
   const collapseBelow = form?.collapseBelow ?? "md";
+  const errorsRegistry = useFormErrorsRegistry();
+  useClaimErrorKey(name);
+  const error = errorProp ?? (name && errorsRegistry ? firstBagMessage(errorsRegistry.errors[name]) : void 0);
   const autoId = React.useId();
   const resolvedId = id ?? autoId;
   const labelId = `${resolvedId}-label`;
@@ -39,6 +44,10 @@ function FormField({
       "FormField expects a single React element child to receive aria-describedby/aria-errormessage; the helper text and error message will not be associated with the control. Pass plain text via `staticText` instead of `children` for a read-only value row."
     );
   }
+  const fieldNameContext = React.useMemo(
+    () => ({ labelId, label: typeof label === "string" ? label : void 0 }),
+    [labelId, label]
+  );
   const childProps = React.isValidElement(children) ? children.props : void 0;
   const mergeIds = mergeAriaIds;
   const childWithA11y = isStatic ? (
@@ -112,7 +121,7 @@ function FormField({
           labelAddon
         ] }),
         /* @__PURE__ */ jsxs("div", { "data-slot": "form-field-control", className: "ui-form-field-control", children: [
-          childWithA11y,
+          isStatic ? childWithA11y : /* @__PURE__ */ jsx(FieldNameContext.Provider, { value: fieldNameContext, children: childWithA11y }),
           helper ? /* @__PURE__ */ jsx("p", { id: helperId, className: "text-muted-foreground text-xs", children: helper }) : null,
           error ? /* @__PURE__ */ jsx("p", { id: errorId, role: "alert", className: "text-destructive text-xs", children: error }) : null
         ] })

package/dist/components/data-entry/form.d.ts

@@ -32,6 +32,7 @@ export declare const Form: React.ForwardRefExoticComponent<React.FormHTMLAttribu
     collapseBelow?: BreakpointProp | false;
     columns?: import("../../props/components/layout.prop.js").ResponsiveGridColumnsProp;
     density?: import("../../props/index.js").DensityProp;
+    errors?: import("../../props/index.js").ErrorBagProp;
     asChild?: boolean;
     className?: import("../../props/index.js").ClassNameProp;
 } & React.RefAttributes<HTMLFormElement>>;

package/dist/components/data-entry/form.js

@@ -3,6 +3,7 @@ import { jsx } from "react/jsx-runtime";
 import { Slot } from "@radix-ui/react-slot";
 import * as React from "react";
 import { cn } from "../../lib/utils.js";
+import { FormErrorsProvider } from "./form-errors.js";
 import { ResponsiveGrid } from "../layout/responsive-grid.js";
 const FormLayoutContext = React.createContext(null);
 function useFormLayout() {
@@ -16,6 +17,7 @@ const Form = React.forwardRef(function Form2({
   collapseBelow = "md",
   columns,
   density,
+  errors,
   asChild = false,
   className,
   children,
@@ -26,17 +28,20 @@ const Form = React.forwardRef(function Form2({
     [layout, labelWidth, controlWidth, labelAlign, collapseBelow]
   );
   const content = columns != null ? /* @__PURE__ */ jsx(ResponsiveGrid, { columns, children }) : children;
+  const withRegistry = (node) => errors !== void 0 ? /* @__PURE__ */ jsx(FormErrorsProvider, { errors, children: node }) : node;
   if (asChild) {
-    return /* @__PURE__ */ jsx(FormLayoutContext.Provider, { value: ctx, children: /* @__PURE__ */ jsx(
-      Slot,
-      {
-        ref,
-        "data-slot": "form",
-        "data-layout": layout,
-        className: cn("ui-form", density && `ui-density-${density}`, className),
-        ...props,
-        children
-      }
+    return /* @__PURE__ */ jsx(FormLayoutContext.Provider, { value: ctx, children: withRegistry(
+      /* @__PURE__ */ jsx(
+        Slot,
+        {
+          ref,
+          "data-slot": "form",
+          "data-layout": layout,
+          className: cn("ui-form", density && `ui-density-${density}`, className),
+          ...props,
+          children
+        }
+      )
     ) });
   }
   return /* @__PURE__ */ jsx(
@@ -47,7 +52,7 @@ const Form = React.forwardRef(function Form2({
       "data-layout": layout,
       className: cn("ui-form", density && `ui-density-${density}`, className),
       ...props,
-      children: /* @__PURE__ */ jsx(FormLayoutContext.Provider, { value: ctx, children: content })
+      children: /* @__PURE__ */ jsx(FormLayoutContext.Provider, { value: ctx, children: withRegistry(content) })
     }
   );
 });

package/dist/components/data-entry/index.d.ts

@@ -13,6 +13,8 @@ export { Form, useFormLayout, type FormLayoutContextValue } from "./form.js";
 export type { FormProp, FormProps } from "./form.js";
 export { FormField } from "./form-field.js";
 export type { FormFieldProp, FormFieldProps } from "./form-field.js";
+export { FormErrors, FormErrorsProvider } from "./form-errors.js";
+export type { FormErrorsProp, FormErrorsProps, FormErrorsProviderProp, FormErrorsProviderProps, } from "./form-errors.js";
 export { Field } from "./field.js";
 export type { FieldProps } from "./field.js";
 export { SearchInput } from "./search-input.js";

package/dist/components/data-entry/index.js

@@ -19,6 +19,7 @@ import { Radio, RadioGroup, RadioItem, RadioGroupRoot } from "./radio.js";
 import { Textarea } from "./textarea.js";
 import { Form, useFormLayout } from "./form.js";
 import { FormField } from "./form-field.js";
+import { FormErrors, FormErrorsProvider } from "./form-errors.js";
 import { Field } from "./field.js";
 import { SearchInput } from "./search-input.js";
 import { Switch } from "./switch.js";
@@ -69,6 +70,8 @@ export {
   DateRangePicker,
   Field,
   Form,
+  FormErrors,
+  FormErrorsProvider,
   FormField,
   Input,
   InputOTP,

package/dist/components/data-entry/input.js

@@ -3,6 +3,7 @@ import { jsx, jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { X } from "lucide-react";
 import { useTranslation } from "../../i18n/use-translation.js";
+import { useFieldNameFallback } from "../../lib/field-a11y.js";
 import { cn } from "../../lib/utils.js";
 const inputBaseClass = [
   "ui-control border-input bg-background w-full min-w-0 rounded-[var(--control-radius)] transition-[color,box-shadow] outline-none",
@@ -27,6 +28,10 @@ const Input = React.forwardRef(
     ...props
   }, ref) => {
     const { t } = useTranslation();
+    const nameFallback = useFieldNameFallback({
+      "aria-label": props["aria-label"],
+      "aria-labelledby": props["aria-labelledby"]
+    });
     const innerRef = React.useRef(null);
     const setRefs = React.useCallback(
       (node) => {
@@ -71,7 +76,8 @@ const Input = React.forwardRef(
           defaultValue,
           onChange,
           className: cn(inputBaseClass, className),
-          ...props
+          ...props,
+          ...nameFallback
         }
       );
     }
@@ -112,7 +118,8 @@ const Input = React.forwardRef(
             (showClear || trailingIcon != null) && "pe-9",
             className
           ),
-          ...props
+          ...props,
+          ...nameFallback
         }
       ),
       trailing != null ? /* @__PURE__ */ jsx("span", { className: "absolute inset-y-0 end-2 inline-flex items-center", children: trailing }) : null

package/dist/components/data-entry/search-select.js

@@ -3,6 +3,7 @@ import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { ChevronsUpDown, Loader2, X } from "lucide-react";
 import { useTranslation } from "../../i18n/use-translation.js";
+import { useFieldNameFallback } from "../../lib/field-a11y.js";
 import { cn } from "../../lib/utils.js";
 import { controlOpenRingClass } from "../../lib/control-styles.js";
 import { Button } from "../general/button.js";
@@ -49,6 +50,12 @@ function SearchSelect({
   "aria-required": ariaRequired
 }) {
   const { t } = useTranslation();
+  const nameFallback = useFieldNameFallback({
+    "aria-label": ariaLabel,
+    "aria-labelledby": ariaLabelledby
+  });
+  const triggerAriaLabel = ariaLabel ?? nameFallback["aria-label"];
+  const triggerAriaLabelledby = ariaLabelledby ?? nameFallback["aria-labelledby"];
   const reactId = React.useId();
   const listId = `${reactId}-listbox`;
   const optionDomId = (optionValue) => `${reactId}-opt-${optionValue}`;
@@ -238,8 +245,8 @@ function SearchSelect({
               size,
               "aria-expanded": open,
               "aria-controls": open ? listId : void 0,
-              "aria-label": ariaLabel,
-              "aria-labelledby": ariaLabelledby,
+              "aria-label": triggerAriaLabel,
+              "aria-labelledby": triggerAriaLabelledby,
               "aria-describedby": ariaDescribedby,
               "aria-errormessage": ariaErrorMessage,
               "aria-invalid": ariaInvalid,
@@ -272,8 +279,8 @@ function SearchSelect({
           /* @__PURE__ */ jsx(
             PopoverContent,
             {
-              "aria-label": ariaLabelledby ? void 0 : ariaLabel ?? resolvedPlaceholder,
-              "aria-labelledby": ariaLabelledby,
+              "aria-label": triggerAriaLabelledby ? void 0 : triggerAriaLabel ?? resolvedPlaceholder,
+              "aria-labelledby": triggerAriaLabelledby,
               align: "start",
               sideOffset: 4,
               collisionPadding: 12,

package/dist/components/data-entry/select.js

@@ -5,7 +5,12 @@ import * as SelectPrimitive from "@radix-ui/react-select";
 import { ChevronDown, ChevronUp, X } from "lucide-react";
 import { cn } from "../../lib/utils.js";
 import { controlTriggerClass } from "../../lib/control-styles.js";
-import { mergeAriaIds, omitFieldA11y, pickFieldA11y } from "../../lib/field-a11y.js";
+import {
+  mergeAriaIds,
+  omitFieldA11y,
+  pickFieldA11y,
+  useFieldNameFallback
+} from "../../lib/field-a11y.js";
 import { SearchSelect } from "./search-select.js";
 import { useTranslation } from "../../i18n/use-translation.js";
 function isDataSelect(props) {
@@ -32,13 +37,24 @@ function SelectValue(props) {
 const SelectTrigger = React.forwardRef(({ className, children, size = "md", showIndicator = true, ...props }, ref) => {
   const field = React.useContext(SelectFieldA11yContext);
   const ownsName = props["aria-label"] !== void 0 || props["aria-labelledby"] !== void 0;
-  const fieldA11y = field ? {
-    id: props.id ?? field.id,
-    ...ownsName ? {} : { "aria-label": field["aria-label"], "aria-labelledby": field["aria-labelledby"] },
-    "aria-describedby": mergeAriaIds(props["aria-describedby"], field["aria-describedby"]),
-    "aria-errormessage": mergeAriaIds(props["aria-errormessage"], field["aria-errormessage"]),
-    "aria-required": props["aria-required"] ?? field["aria-required"],
-    "aria-invalid": props["aria-invalid"] ?? field["aria-invalid"]
+  const fieldOwnsName = field?.["aria-label"] !== void 0 || field?.["aria-labelledby"] !== void 0;
+  const nameFallback = useFieldNameFallback({
+    "aria-label": ownsName ? props["aria-label"] : field?.["aria-label"],
+    "aria-labelledby": ownsName ? props["aria-labelledby"] : field?.["aria-labelledby"]
+  });
+  const fieldA11y = field || nameFallback["aria-labelledby"] !== void 0 ? {
+    id: props.id ?? field?.id,
+    ...ownsName ? {} : fieldOwnsName ? {
+      "aria-label": field?.["aria-label"],
+      "aria-labelledby": field?.["aria-labelledby"]
+    } : nameFallback,
+    "aria-describedby": mergeAriaIds(props["aria-describedby"], field?.["aria-describedby"]),
+    "aria-errormessage": mergeAriaIds(
+      props["aria-errormessage"],
+      field?.["aria-errormessage"]
+    ),
+    "aria-required": props["aria-required"] ?? field?.["aria-required"],
+    "aria-invalid": props["aria-invalid"] ?? field?.["aria-invalid"]
   } : void 0;
   return /* @__PURE__ */ jsxs(
     SelectPrimitive.Trigger,

package/dist/components/layout/flex.js

@@ -1,4 +1,6 @@
+"use client";
 import { jsx } from "react/jsx-runtime";
+import { mergeAriaIds } from "../../lib/field-a11y.js";
 import { cn } from "../../lib/utils.js";
 import { flexGapClass } from "../../lib/variants.js";
 function Flex({
@@ -13,6 +15,20 @@ function Flex({
   children,
   ...props
 }) {
+  let domProps = props;
+  if (props.role === void 0 && (props["aria-label"] !== void 0 || props["aria-labelledby"] !== void 0)) {
+    const {
+      "aria-required": _ariaRequired,
+      "aria-invalid": _ariaInvalid,
+      "aria-errormessage": ariaErrorMessage,
+      ...allowed
+    } = props;
+    domProps = {
+      ...allowed,
+      role: "group",
+      "aria-describedby": mergeAriaIds(props["aria-describedby"], ariaErrorMessage)
+    };
+  }
   return /* @__PURE__ */ jsx(
     "div",
     {
@@ -23,7 +39,7 @@ function Flex({
       "data-hide-below": hideBelow,
       "data-hide-from": hideFrom,
       className: cn("ui-flex", flexGapClass[gap], className),
-      ...props,
+      ...domProps,
       children
     }
   );

package/dist/form/form-field-control.js

@@ -21,6 +21,7 @@ function FormFieldControl({
       FormField,
       {
         id: fieldName,
+        name: fieldName,
         label,
         required,
         helper,
@@ -46,6 +47,7 @@ function FormFieldControl({
         FormField,
         {
           id: String(name),
+          name: String(name),
           label,
           required,
           helper,

package/dist/i18n/messages/en.json

@@ -128,6 +128,9 @@
       "denied": "You do not have permission to view branches",
       "loading": "Loading branches…",
       "noMatches": "No branches match your search"
+    },
+    "formErrors": {
+      "title": "Please review the following errors"
     }
   },
   "feedback": {

package/dist/i18n/messages/ja.json

@@ -125,6 +125,9 @@
       "denied": "ブランチを表示する権限がありません",
       "loading": "ブランチを読み込み中…",
       "noMatches": "検索に一致するブランチがありません"
+    },
+    "formErrors": {
+      "title": "入力内容にエラーがあります"
     }
   },
   "feedback": {

package/dist/i18n/messages/vi.json

@@ -125,6 +125,9 @@
       "denied": "Bạn không có quyền xem chi nhánh",
       "loading": "Đang tải chi nhánh…",
       "noMatches": "Không có chi nhánh khớp với tìm kiếm"
+    },
+    "formErrors": {
+      "title": "Dữ liệu nhập có lỗi, vui lòng kiểm tra"
     }
   },
   "feedback": {

package/dist/lib/field-a11y.d.ts

@@ -1,4 +1,4 @@
-import type * as React from "react";
+import * as React from "react";
 /**
  * The accessible-name / description / validation contract that {@link FormField} injects onto its
  * single control child (via `cloneElement`). EVERY form-capable `@godxjp/ui` component accepts
@@ -53,6 +53,34 @@ export declare function omitFieldA11y<T extends FieldA11yProps>(props: T): Omit<
  * both — `aria-labelledby` takes precedence and the redundant `aria-label` only adds noise).
  */
 export declare function resolveFieldA11y(props: FieldA11yProps, intrinsicAriaLabel?: string): FieldA11yProps;
+/**
+ * The FormField label made reachable by NESTED controls (gh#303).
+ *
+ * `cloneElement` can only wire the field-a11y contract onto FormField's single direct child. When
+ * that child is a layout wrapper (a `Flex` holding a range from/to pair, a 年/月 input+select
+ * combo), the naming attributes stop on the wrapper `div` and every control inside is left with no
+ * accessible name at all (axe: `label` on the inputs, `button-name` on select/combobox triggers).
+ *
+ * FormField therefore also publishes its label through this context, and each control's semantic
+ * focus target picks it up as a LAST-RESORT name via {@link useFieldNameFallback}: a control that
+ * already has a name — its own `aria-label`/`aria-labelledby`, or the one FormField cloned onto it
+ * as the direct child — keeps it untouched. Multiple nested controls then all announce the field's
+ * label; a consumer wanting distinct names (e.g. "開始日" / "終了日") sets `aria-label` per
+ * control, which always wins.
+ */
+export interface FieldNameContextValue {
+    /** DOM id of FormField's visible label element (the `aria-labelledby` target). */
+    labelId: string;
+    /** The label's plain-text content, when it is a string (belt-and-suspenders `aria-label`). */
+    label?: string;
+}
+export declare const FieldNameContext: React.Context<FieldNameContextValue | null>;
+/**
+ * Resolve the last-resort accessible name for a control's semantic focus target (see
+ * {@link FieldNameContext}). Returns `{}` — never clobbering anything — unless the control is
+ * inside a FormField AND still nameless after its own props and the cloned contract are applied.
+ */
+export declare function useFieldNameFallback(name: Pick<FieldA11yProps, "aria-label" | "aria-labelledby">): Pick<FieldA11yProps, "aria-label" | "aria-labelledby">;
 /**
  * The field-a11y attributes valid on a **group container** (`role="group"`), used by composite
  * controls that have no single labelable focus target — CheckboxGroup, and the two-input range

package/dist/lib/field-a11y.js

@@ -1,3 +1,5 @@
+"use client";
+import * as React from "react";
 const FIELD_A11Y_KEYS = [
   "aria-label",
   "aria-labelledby",
@@ -34,6 +36,17 @@ function resolveFieldA11y(props, intrinsicAriaLabel) {
   }
   return picked;
 }
+const FieldNameContext = React.createContext(null);
+function useFieldNameFallback(name) {
+  const field = React.useContext(FieldNameContext);
+  if (!field || name["aria-label"] !== void 0 || name["aria-labelledby"] !== void 0) {
+    return {};
+  }
+  return {
+    "aria-labelledby": field.labelId,
+    ...field.label !== void 0 ? { "aria-label": field.label } : {}
+  };
+}
 function pickGroupFieldA11y(props) {
   const describedBy = mergeAriaIds(props["aria-describedby"], props["aria-errormessage"]);
   return {
@@ -42,9 +55,11 @@ function pickGroupFieldA11y(props) {
   };
 }
 export {
+  FieldNameContext,
   mergeAriaIds,
   omitFieldA11y,
   pickFieldA11y,
   pickGroupFieldA11y,
-  resolveFieldA11y
+  resolveFieldA11y,
+  useFieldNameFallback
 };

package/dist/props/components/data-entry.prop.d.ts

@@ -8,7 +8,7 @@ import type { DateRange } from "react-day-picker";
 import type * as React from "react";
 import type { UploadFileItem } from "../../components/data-entry/upload-types.js";
 import type { FieldA11yProps } from "../../lib/field-a11y.js";
-import type { ClassNameProp, DisabledProp, EmptyMessageProp, ErrorProp, HelperProp, IdProp, LabelProp, NameProp, OnChangeProp, OnValueChangeProp, OnSearchChangeProp, OpenProp, OnOpenChangeProp, PlaceholderProp, RequiredProp, ValueProp, DefaultValueProp, FormLayoutProp, WidthProp, BreakpointProp, DensityProp, SizeProp } from "../vocabulary/index.js";
+import type { ClassNameProp, DisabledProp, EmptyMessageProp, ErrorBagProp, ErrorProp, HelperProp, IdProp, LabelProp, NameProp, OnChangeProp, OnValueChangeProp, OnSearchChangeProp, OpenProp, OnOpenChangeProp, PlaceholderProp, RequiredProp, ValueProp, DefaultValueProp, FormLayoutProp, WidthProp, BreakpointProp, DensityProp, SizeProp, TitleProp } from "../vocabulary/index.js";
 import type { ResponsiveGridColumnsProp } from "./layout.prop.js";
 /** One-outline-per-group appearance for the compound InputOTP control. */
 export type InputOTPGroupAppearanceProp = "slots" | "grouped";
@@ -88,6 +88,15 @@ export type FormProp = React.FormHTMLAttributes<HTMLFormElement> & {
     collapseBelow?: BreakpointProp | false;
     columns?: ResponsiveGridColumnsProp;
     density?: DensityProp;
+    /**
+     * Server validation error bag (e.g. Inertia's `form.errors`). Each `FormField name="…"` inside
+     * resolves its own message from the bag automatically and CLAIMS its key; `<FormErrors />`
+     * renders the remaining, unclaimed entries — errors attached to hidden/derived fields that no
+     * visible field displays. Works in both the `<form>` and `asChild` modes. A Form WITHOUT this
+     * prop joins a surrounding `FormErrorsProvider` instead (sibling Card+Form sections sharing one
+     * bag); a Form WITH it starts its own (shadowing) registry.
+     */
+    errors?: ErrorBagProp;
     /**
      * Render the caller's own element instead of a `<form>`, keeping only the layout context.
      * For routing libraries that own the form element (Inertia, TanStack Form) — two `<form>`
@@ -110,6 +119,13 @@ export type FormProp = React.FormHTMLAttributes<HTMLFormElement> & {
 export type FormFieldProp = {
     /** Optional — auto-generated and injected into the child control when omitted. */
     id?: IdProp;
+    /**
+     * Error-bag key of this field. When the surrounding `Form` carries `errors`, the field
+     * resolves its message from `errors[name]` automatically (an explicit `error` prop wins)
+     * and CLAIMS the key so `<FormErrors />` does not repeat it. Not injected into the child —
+     * pass `name` on the control itself for native form submission.
+     */
+    name?: NameProp;
     label: LabelProp;
     required?: RequiredProp;
     helper?: HelperProp;
@@ -130,6 +146,12 @@ export type FormFieldProp = {
 } | {
     /** Optional — auto-generated and injected into the child control when omitted. */
     id?: IdProp;
+    /**
+     * Error-bag key of this field. When the surrounding `Form` carries `errors`, the field
+     * resolves its message from `errors[name]` automatically (an explicit `error` prop wins)
+     * and CLAIMS the key so `<FormErrors />` does not repeat it.
+     */
+    name?: NameProp;
     label: LabelProp;
     required?: RequiredProp;
     helper?: HelperProp;
@@ -149,6 +171,37 @@ export type FormFieldProp = {
     /** Read-only value — renders as `Descriptions.Item`-matched text instead of a control. */
     staticText: React.ReactNode;
 };
+/**
+ * @see FormErrors — the "no field to stand on" error summary. Renders the entries of the
+ * surrounding `Form`'s error bag that no mounted `FormField name="…"` has claimed — validation
+ * errors attached to hidden/derived fields (`action_mode`, `page`, a source-record id…) that
+ * would otherwise fail silently. Renders nothing while every error is claimed or the bag is empty.
+ */
+export type FormErrorsProp = {
+    /**
+     * Explicit error bag — overrides the surrounding `Form errors`. Use it when the component sits
+     * outside a `Form` (e.g. inside `FormRoot`); field claiming still applies when a `Form` provides
+     * the registry.
+     */
+    errors?: ErrorBagProp;
+    /** Heading above the messages. Defaults to the localized "please review your input" title. */
+    title?: TitleProp;
+    className?: ClassNameProp;
+};
+/**
+ * @see FormErrorsProvider — one shared error registry over a REGION of sibling Forms. An edit
+ * screen split into several Card+Form sections shares a single server bag: wrap the sections in
+ * this provider instead of passing `errors` to each Form, and every `FormField name="…"` inside
+ * (Forms without their own `errors` join the surrounding registry) claims into the same registry,
+ * so one `<FormErrors />` anywhere in the region renders exactly the unclaimed remainder.
+ * `Form errors={…}` renders this provider itself — a Form WITH its own `errors` starts a new
+ * (shadowing) registry.
+ */
+export type FormErrorsProviderProp = {
+    /** Server validation error bag shared by every Form/FormField in the region. */
+    errors?: ErrorBagProp;
+    children?: React.ReactNode;
+};
 /** @see SearchInput */
 export type SearchInputProp = FieldA11yProps & {
     id?: IdProp;

package/dist/props/registry.d.ts

@@ -69,6 +69,11 @@ export declare const VOCABULARY_REGISTRY: {
         readonly category: "shared";
         readonly description: "Validation error message";
     };
+    readonly ErrorBagProp: {
+        readonly file: "vocabulary/shared.prop.ts";
+        readonly category: "shared";
+        readonly description: "Server validation error bag keyed by field name (Laravel/Inertia errors)";
+    };
     readonly PlaceholderProp: {
         readonly file: "vocabulary/shared.prop.ts";
         readonly category: "shared";
@@ -863,12 +868,22 @@ export declare const COMPONENT_PROP_REGISTRY: {
     readonly FormProp: {
         readonly group: "data-entry";
         readonly file: "components/data-entry.prop.ts";
-        readonly vocabulary: readonly ["FormLayoutProp", "WidthProp", "BreakpointProp", "DensityProp"];
+        readonly vocabulary: readonly ["FormLayoutProp", "WidthProp", "BreakpointProp", "DensityProp", "ErrorBagProp"];
     };
     readonly FormFieldProp: {
         readonly group: "data-entry";
         readonly file: "components/data-entry.prop.ts";
-        readonly vocabulary: readonly ["IdProp", "LabelProp", "RequiredProp", "HelperProp", "ErrorProp", "FormLayoutProp", "WidthProp"];
+        readonly vocabulary: readonly ["IdProp", "NameProp", "LabelProp", "RequiredProp", "HelperProp", "ErrorProp", "FormLayoutProp", "WidthProp"];
+    };
+    readonly FormErrorsProp: {
+        readonly group: "data-entry";
+        readonly file: "components/data-entry.prop.ts";
+        readonly vocabulary: readonly ["ErrorBagProp", "TitleProp", "ClassNameProp"];
+    };
+    readonly FormErrorsProviderProp: {
+        readonly group: "data-entry";
+        readonly file: "components/data-entry.prop.ts";
+        readonly vocabulary: readonly ["ErrorBagProp"];
     };
     readonly SearchInputProp: {
         readonly group: "data-entry";

package/dist/props/registry.js

@@ -65,6 +65,11 @@ const VOCABULARY_REGISTRY = {
     category: "shared",
     description: "Validation error message"
   },
+  ErrorBagProp: {
+    file: "vocabulary/shared.prop.ts",
+    category: "shared",
+    description: "Server validation error bag keyed by field name (Laravel/Inertia errors)"
+  },
   PlaceholderProp: {
     file: "vocabulary/shared.prop.ts",
     category: "shared",
@@ -959,13 +964,14 @@ const COMPONENT_PROP_REGISTRY = {
   FormProp: {
     group: "data-entry",
     file: "components/data-entry.prop.ts",
-    vocabulary: ["FormLayoutProp", "WidthProp", "BreakpointProp", "DensityProp"]
+    vocabulary: ["FormLayoutProp", "WidthProp", "BreakpointProp", "DensityProp", "ErrorBagProp"]
   },
   FormFieldProp: {
     group: "data-entry",
     file: "components/data-entry.prop.ts",
     vocabulary: [
       "IdProp",
+      "NameProp",
       "LabelProp",
       "RequiredProp",
       "HelperProp",
@@ -974,6 +980,16 @@ const COMPONENT_PROP_REGISTRY = {
       "WidthProp"
     ]
   },
+  FormErrorsProp: {
+    group: "data-entry",
+    file: "components/data-entry.prop.ts",
+    vocabulary: ["ErrorBagProp", "TitleProp", "ClassNameProp"]
+  },
+  FormErrorsProviderProp: {
+    group: "data-entry",
+    file: "components/data-entry.prop.ts",
+    vocabulary: ["ErrorBagProp"]
+  },
   SearchInputProp: {
     group: "data-entry",
     file: "components/data-entry.prop.ts",

package/dist/props/vocabulary/index.d.ts

@@ -1,5 +1,5 @@
 /** Barrel — all vocabulary prop types. */
-export type { ClassNameProp, ChildrenProp, IdProp, OpenProp, DefaultOpenProp, OnOpenChangeProp, HandlerProp, PendingProp, RequiredProp, DisabledProp, LabelProp, HelperProp, ErrorProp, PlaceholderProp, NameProp, ValueProp, DefaultValueProp, OnValueChangeProp, OnChangeProp, OnClickProp, AsChildProp, WidthProp, } from "./shared.prop.js";
+export type { ClassNameProp, ChildrenProp, IdProp, OpenProp, DefaultOpenProp, OnOpenChangeProp, HandlerProp, PendingProp, RequiredProp, DisabledProp, LabelProp, HelperProp, ErrorProp, ErrorBagProp, PlaceholderProp, NameProp, ValueProp, DefaultValueProp, OnValueChangeProp, OnChangeProp, OnClickProp, AsChildProp, WidthProp, } from "./shared.prop.js";
 export type { TitleProp, SubtitleProp, StatusProp, DescriptionProp, ExtraProp, FooterProp, ActionProp, IconProp, ConfirmLabelProp, CancelLabelProp, ActionsProp, EmptyMessageProp, } from "./content.prop.js";
 export type { PageDensityProp, PageContainerVariantProp, CenteredShellWidthProp, CenteredShellAlignProp, CenteredShellPresetProp, ErrorSurfaceModeProp, ErrorSurfaceStatusProp, AuthShellPresetProp, TableDensityProp, DensityProp, GapProp, } from "./layout.prop.js";
 export type { ButtonVariantProp, ButtonSizeProp, BadgeVariantProp, AppSettingPickerAppearanceProp, ShapeProp, AvatarShapeProp, TextSizeProp, TextToneProp, FontWeightProp, HeadingLevelProp, TextAlignProp, SizeProp, FormLayoutProp, BreakpointProp, ConfirmVariantProp, ToneProp, AlertVariantProp, SortDirectionProp, ColumnAlignProp, SortStateProp, RevealDelayProp, } from "./interaction.prop.js";

package/dist/props/vocabulary/shared.prop.d.ts

@@ -29,6 +29,11 @@ export type LabelProp = React.ReactNode;
 export type HelperProp = React.ReactNode;
 /** Validation error message. */
 export type ErrorProp = React.ReactNode;
+/**
+ * Server validation error bag, keyed by field name — the shape Laravel hands Inertia
+ * (`errors: { field: "message" }`) or a JSON API returns (`{ field: ["m1", "m2"] }`).
+ */
+export type ErrorBagProp = Partial<Record<string, string | string[]>>;
 /** Placeholder text for inputs. */
 export type PlaceholderProp = string;
 /** HTML input `name` attribute. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@godxjp/ui",
-  "version": "18.13.0",
-  "godxUiMcp": "18.13.0",
+  "version": "18.14.0",
+  "godxUiMcp": "18.14.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",