@godxjp/ui 20.0.0 → 20.1.0

package/dist/components/ui/rating.js

@@ -9,7 +9,12 @@ const Rating = React.forwardRef(
     value,
     defaultValue = 0,
     onValueChange,
-    max = 5,
+    max,
+    count,
+    allowHalf = false,
+    allowClear = false,
+    character,
+    tooltips,
     readOnly,
     disabled,
     name,
@@ -17,68 +22,103 @@ const Rating = React.forwardRef(
     ...rest
   }, ref) => {
     const { t } = useTranslation();
+    const symbols = count ?? max ?? 5;
     const [internal, setInternal] = React.useState(defaultValue);
     const current = value ?? internal;
     const [hover, setHover] = React.useState(null);
     const display = hover ?? current;
     const interactive = !readOnly && !disabled;
+    const stepSize = allowHalf ? 0.5 : 1;
     const select = (next) => {
       if (!interactive) return;
-      if (value === void 0) setInternal(next);
-      onValueChange?.(next);
+      const resolved = allowClear && next === current ? 0 : next;
+      if (value === void 0) setInternal(resolved);
+      onValueChange?.(resolved);
     };
-    const focusableStar = current > 0 ? current : 1;
+    const focusableStar = current > 0 ? Math.ceil(current) : 1;
     const onKeyDown = (e, star) => {
       if (!interactive) return;
       let next;
       switch (e.key) {
         case "ArrowRight":
         case "ArrowUp":
-          next = Math.min(max, star + 1);
+          next = Math.min(symbols, star + stepSize);
           break;
         case "ArrowLeft":
         case "ArrowDown":
-          next = Math.max(1, star - 1);
+          next = Math.max(stepSize, star - stepSize);
           break;
         case "Home":
-          next = 1;
+          next = stepSize;
           break;
         case "End":
-          next = max;
+          next = symbols;
           break;
         default:
           return;
       }
       e.preventDefault();
-      select(next);
+      if (value === void 0) setInternal(next);
+      onValueChange?.(next);
+    };
+    const stepLabel = (star) => {
+      const tooltip = tooltips?.[star - 1];
+      const base = t("ui.rating.starLabel", { star, max: symbols });
+      return tooltip ? `${base}, ${tooltip}` : base;
     };
+    const glyph = (star) => typeof character === "function" ? character(star) : character ?? /* @__PURE__ */ jsx(Star, { "aria-hidden": "true" });
     return /* @__PURE__ */ jsxs(
       "div",
       {
         ref,
         role: "radiogroup",
         "data-slot": "rating",
+        "data-allow-half": allowHalf ? "true" : void 0,
         className: cn("ui-rating", className),
         "aria-label": rest["aria-label"] ?? t("ui.rating.ariaLabel"),
         children: [
-          Array.from({ length: max }, (_, i) => i + 1).map((star) => /* @__PURE__ */ jsx(
-            "button",
-            {
-              type: "button",
-              role: "radio",
-              "aria-checked": current === star,
-              "aria-label": t("ui.rating.starLabel", { star, max }),
-              disabled: disabled || readOnly,
-              tabIndex: interactive && star === focusableStar ? 0 : -1,
-              className: cn("ui-rating-star", star <= display && "ui-rating-star-filled"),
-              onMouseEnter: () => interactive && setHover(star),
-              onMouseLeave: () => setHover(null),
-              onClick: () => select(star),
-              onKeyDown: (e) => onKeyDown(e, star),
-              children: /* @__PURE__ */ jsx(Star, { "aria-hidden": "true" })
-            },
-            star
-          )),
+          Array.from({ length: symbols }, (_, i) => i + 1).map((star) => {
+            const symbol = /* @__PURE__ */ jsx(
+              "button",
+              {
+                type: "button",
+                role: "radio",
+                "aria-checked": current === star,
+                "aria-label": stepLabel(star),
+                disabled: disabled || readOnly,
+                tabIndex: interactive && star === focusableStar ? 0 : -1,
+                className: cn(
+                  "ui-rating-star",
+                  star <= display && "ui-rating-star-filled",
+                  allowHalf && star - 0.5 === display && "ui-rating-star-half-filled"
+                ),
+                onMouseEnter: () => interactive && setHover(star),
+                onMouseLeave: () => setHover(null),
+                onClick: () => select(star),
+                onKeyDown: (e) => onKeyDown(e, star),
+                children: glyph(star)
+              },
+              star
+            );
+            if (!allowHalf) return symbol;
+            return /* @__PURE__ */ jsxs("span", { "data-slot": "rating-symbol", className: "ui-rating-symbol", children: [
+              /* @__PURE__ */ jsx(
+                "button",
+                {
+                  type: "button",
+                  tabIndex: -1,
+                  "aria-hidden": "true",
+                  disabled: disabled || readOnly,
+                  "data-slot": "rating-half",
+                  className: "ui-rating-star-half",
+                  onMouseEnter: () => interactive && setHover(star - 0.5),
+                  onMouseLeave: () => setHover(null),
+                  onClick: () => select(star - 0.5)
+                }
+              ),
+              symbol
+            ] }, star);
+          }),
           name ? /* @__PURE__ */ jsx("input", { type: "hidden", name, value: current }) : null
         ]
       }

package/dist/components/ui/segmented.d.ts

@@ -18,6 +18,15 @@ export type SegmentedProp = {
     /** Uncontrolled initial selection. */
     defaultValue?: string;
     onValueChange?: (value: string) => void;
+    /**
+     * antd `block` — stretch the bar to its container and share the width EQUALLY between the
+     * choices, so the selected pill does not resize as the label changes length.
+     */
+    block?: boolean;
+    /** antd `vertical` — stack the choices in a column. Arrow keys follow the axis. */
+    vertical?: boolean;
+    /** Control height tier: `md` (default), `sm` or `lg` — the same tiers as every other control. */
+    size?: "sm" | "md" | "lg";
     /** Disable the whole group. */
     disabled?: boolean;
     /** Form field name — submits the selected value with the form. */

package/dist/components/ui/segmented.js

@@ -3,15 +3,30 @@ import { jsx, jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import * as RadioGroupPrimitive from "@radix-ui/react-radio-group";
 import { cn } from "../../lib/utils.js";
-const Segmented = React.forwardRef(function Segmented2({ options, value, defaultValue, onValueChange, disabled, name, id, className, ...props }, ref) {
+const Segmented = React.forwardRef(function Segmented2({
+  options,
+  value,
+  defaultValue,
+  onValueChange,
+  disabled,
+  block = false,
+  vertical = false,
+  size,
+  name,
+  id,
+  className,
+  ...props
+}, ref) {
   return /* @__PURE__ */ jsx(
     RadioGroupPrimitive.Root,
     {
       ref,
       id,
       "data-slot": "segmented",
+      "data-block": block ? "true" : void 0,
+      "data-size": size,
       className: cn("ui-segmented", className),
-      orientation: "horizontal",
+      orientation: vertical ? "vertical" : "horizontal",
       value,
       defaultValue,
       onValueChange,

package/dist/components/ui/separator.d.ts

@@ -12,6 +12,10 @@ export type { SeparatorProp, SeparatorProp as SeparatorProps, } from "../../prop
  * the ref, and we decide what element carries them.
  */
 export declare const Separator: React.ForwardRefExoticComponent<Omit<React.HTMLAttributes<HTMLDivElement>, "children"> & {
+    labelSize?: "2xs" | "xs" | "sm" | "md";
+    space?: import("../../props/index.js").GapProp;
+    hideBelow?: import("../../props/index.js").BreakpointProp;
+    hideFrom?: import("../../props/index.js").BreakpointProp;
     orientation?: import("../../props/index.js").OrientationProp;
     label?: string;
     labelAlign?: import("../../props/index.js").TextAlignProp;

package/dist/components/ui/separator.js

@@ -1,10 +1,16 @@
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { Separator as AriaSeparator } from "react-aria-components";
+import { padStepToken } from "../../lib/variants.js";
 import { cn } from "../../lib/utils.js";
 const Separator = React.forwardRef(
   ({
     className,
+    labelSize,
+    space,
+    hideBelow,
+    hideFrom,
+    style,
     orientation = "horizontal",
     decorative,
     label,
@@ -28,6 +34,13 @@ const Separator = React.forwardRef(
         ref,
         elementType: "div",
         "data-slot": "separator",
+        "data-label-size": labelSize,
+        "data-hide-below": hideBelow,
+        "data-hide-from": hideFrom,
+        style: {
+          ...style,
+          ...space === void 0 ? void 0 : { marginBlock: padStepToken(space) }
+        },
         "data-orientation": orientation,
         "data-tone": tone,
         "data-labelled": labelled ? "" : void 0,

package/dist/components/ui/tag-input.d.ts

@@ -1,13 +1,58 @@
 import * as React from "react";
+import type { AllowClearProp, ControlStatusProp, ControlVariantProp, MaxTagCountProp, MaxTagPlaceholderProp, SizeProp } from "../../props/vocabulary/index.js";
+/**
+ * TagInput is this library's answer to antd's `Select mode="tags"` — a free-text token field — so
+ * it takes the same token-level props antd puts on that mode.
+ */
 export type TagInputProps = {
     value?: string[];
     defaultValue?: string[];
     onValueChange?: (tags: string[]) => void;
     placeholder?: string;
     disabled?: boolean;
+    /**
+     * Read-only: the tags stay visible, selectable and submitted, but nothing can be added or
+     * removed — the draft field is read-only, the chip removers and the clear ✕ are withdrawn, and
+     * the container reports `aria-readonly`. Mirrors Select's readOnly contract (still focusable and
+     * still in the tab order, unlike `disabled`).
+     */
+    readOnly?: boolean;
     name?: string;
     className?: string;
     id?: string;
     "aria-label"?: string;
+    /** Control height tier (antd `size`) — the shared `--control-height` ladder. */
+    size?: SizeProp;
+    /** Validation status (antd `status`). `error` also sets `aria-invalid`; `warning` recolours only. */
+    status?: ControlStatusProp;
+    /** Control surface (antd `variant`). Default `outlined`. */
+    variant?: ControlVariantProp;
+    /** Hard ceiling on how many tags may be held (antd `maxCount`). Further input is refused. */
+    maxCount?: number;
+    /**
+     * antd `allowClear` — a single ✕ that drops EVERY tag at once. Off by default (antd's own
+     * default for a tags field). The object form replaces the icon and/or the accessible label.
+     */
+    allowClear?: AllowClearProp;
+    /** Fired after every tag is dropped through the ✕ (antd `onClear`). */
+    onClear?: () => void;
+    /** How many chips render before the rest collapse into the overflow node (antd `maxTagCount`). */
+    maxTagCount?: MaxTagCountProp;
+    /** The node standing in for what `maxTagCount` hid (antd `maxTagPlaceholder`). */
+    maxTagPlaceholder?: MaxTagPlaceholderProp;
+    /** Render one chip yourself (antd `tagRender`) — receives the value and an `onClose` remover. */
+    tagRender?: (props: {
+        value: string;
+        label: React.ReactNode;
+        onClose: () => void;
+        index: number;
+        disabled: boolean;
+    }) => React.ReactNode;
+    /**
+     * Characters that commit the draft into a tag (antd `tokenSeparators`). Default `[","]`; Enter
+     * always commits and is not a separator. Pasting a run containing a separator splits it into
+     * several tags, which is antd's behaviour and the reason the prop exists.
+     */
+    tokenSeparators?: string[];
 };
 export declare const TagInput: React.ForwardRefExoticComponent<TagInputProps & React.RefAttributes<HTMLInputElement>>;

package/dist/components/ui/tag-input.js

@@ -1,9 +1,17 @@
 "use client";
-import { jsx, jsxs } from "react/jsx-runtime";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { X } from "lucide-react";
 import { useTranslation } from "../../i18n/use-translation.js";
 import { cn } from "../../lib/utils.js";
+import {
+  applyMaxTagCount,
+  controlSurfaceAttrs,
+  resolveAllowClear
+} from "../data-entry/control-surface.js";
+function escapeForCharClass(character) {
+  return character.replace(/[\\\]^-]/g, "\\$&");
+}
 const TagInput = React.forwardRef(
   ({
     value,
@@ -11,10 +19,21 @@ const TagInput = React.forwardRef(
     onValueChange,
     placeholder,
     disabled,
+    readOnly,
     name,
     className,
     id,
-    "aria-label": ariaLabel
+    "aria-label": ariaLabel,
+    size,
+    status,
+    variant,
+    maxCount,
+    allowClear,
+    onClear,
+    maxTagCount,
+    maxTagPlaceholder,
+    tagRender,
+    tokenSeparators = [","]
   }, ref) => {
     const { t } = useTranslation();
     const [internal, setInternal] = React.useState(defaultValue);
@@ -27,11 +46,25 @@ const TagInput = React.forwardRef(
     const add = (raw) => {
       const tag = raw.trim();
       if (!tag || tags.includes(tag)) return;
+      if (maxCount !== void 0 && tags.length >= maxCount) return;
       commit([...tags, tag]);
     };
+    const addAll = (raw) => {
+      let next = [...tags];
+      const pieces = tokenSeparators.length ? raw.split(new RegExp(`[${tokenSeparators.map(escapeForCharClass).join("")}]`)) : [raw];
+      for (const piece of pieces) {
+        const tag = piece.trim();
+        if (!tag || next.includes(tag)) continue;
+        if (maxCount !== void 0 && next.length >= maxCount) break;
+        next = [...next, tag];
+      }
+      if (next.length !== tags.length) commit(next);
+    };
     const removeAt = (i) => commit(tags.filter((_, idx) => idx !== i));
     const onKeyDown = (e) => {
-      if (e.key === "Enter" || e.key === ",") {
+      if (readOnly) return;
+      if (e.nativeEvent.isComposing) return;
+      if (e.key === "Enter" || tokenSeparators.includes(e.key)) {
         e.preventDefault();
         add(draft);
         setDraft("");
@@ -39,35 +72,63 @@ const TagInput = React.forwardRef(
         removeAt(tags.length - 1);
       }
     };
+    const clearControl = resolveAllowClear(allowClear, false, t("common.clear"));
+    const showClear = clearControl.enabled && tags.length > 0 && !disabled && !readOnly;
+    const clearAll = () => {
+      commit([]);
+      onClear?.();
+    };
+    const chips = tags.map((tag, index) => ({ value: tag, label: tag, index }));
+    const {
+      visible: visibleChips,
+      omitted: omittedChips,
+      overflow
+    } = applyMaxTagCount(chips, maxTagCount, maxTagPlaceholder);
     return /* @__PURE__ */ jsxs(
       "div",
       {
         "data-slot": "tag-input",
         "aria-disabled": disabled || void 0,
-        className: cn("ui-tag-input", disabled && "ui-tag-input-disabled", className),
+        "aria-readonly": readOnly || void 0,
+        ...controlSurfaceAttrs({ variant, status, size }),
+        "aria-invalid": status === "error" ? true : void 0,
+        className: cn(
+          "ui-tag-input ui-control-surface",
+          disabled && "ui-tag-input-disabled",
+          className
+        ),
         children: [
-          tags.length > 0 ? /* @__PURE__ */ jsx("ul", { role: "list", className: "ui-tag-input-list", "data-slot": "tag-input-list", children: tags.map((tag, i) => /* @__PURE__ */ jsxs(
-            "li",
-            {
-              role: "listitem",
-              className: "ui-tag-input-chip",
-              "data-slot": "tag-input-chip",
-              children: [
-                tag,
-                !disabled ? /* @__PURE__ */ jsx(
-                  "button",
-                  {
-                    type: "button",
-                    className: "ui-tag-input-remove",
-                    "aria-label": t("ui.tagInput.removeTag", { tag }),
-                    onClick: () => removeAt(i),
-                    children: /* @__PURE__ */ jsx(X, { "aria-hidden": "true" })
-                  }
-                ) : null
-              ]
-            },
-            tag
-          )) }) : null,
+          tags.length > 0 ? /* @__PURE__ */ jsxs("ul", { role: "list", className: "ui-tag-input-list", "data-slot": "tag-input-list", children: [
+            visibleChips.map((chip) => /* @__PURE__ */ jsx(
+              "li",
+              {
+                role: "listitem",
+                className: "ui-tag-input-chip",
+                "data-slot": "tag-input-chip",
+                children: tagRender ? tagRender({
+                  value: chip.value,
+                  label: chip.label,
+                  index: chip.index,
+                  disabled: Boolean(disabled) || Boolean(readOnly),
+                  onClose: () => removeAt(chip.index)
+                }) : /* @__PURE__ */ jsxs(Fragment, { children: [
+                  chip.value,
+                  !disabled && !readOnly ? /* @__PURE__ */ jsx(
+                    "button",
+                    {
+                      type: "button",
+                      className: "ui-tag-input-remove",
+                      "aria-label": t("ui.tagInput.removeTag", { tag: chip.value }),
+                      onClick: () => removeAt(chip.index),
+                      children: /* @__PURE__ */ jsx(X, { "aria-hidden": "true" })
+                    }
+                  ) : null
+                ] })
+              },
+              chip.value
+            )),
+            omittedChips.length > 0 ? /* @__PURE__ */ jsx("li", { role: "listitem", className: "ui-tag-input-chip", "data-slot": "tag-input-overflow", children: overflow ?? t("dataEntry.selection.overflow", { count: omittedChips.length }) }) : null
+          ] }) : null,
           /* @__PURE__ */ jsx(
             "input",
             {
@@ -76,12 +137,21 @@ const TagInput = React.forwardRef(
               type: "text",
               className: "ui-tag-input-field",
               value: draft,
-              placeholder: tags.length === 0 ? placeholder : void 0,
+              placeholder: tags.length === 0 && !readOnly ? placeholder : void 0,
               disabled,
+              readOnly,
               "aria-label": ariaLabel ?? t("ui.tagInput.inputLabel"),
               onChange: (e) => setDraft(e.target.value),
               onKeyDown,
+              onPaste: (e) => {
+                const text = e.clipboardData.getData("text");
+                if (!tokenSeparators.some((separator) => text.includes(separator))) return;
+                e.preventDefault();
+                addAll(text);
+                setDraft("");
+              },
               onBlur: () => {
+                if (readOnly) return;
                 if (draft.trim()) {
                   add(draft);
                   setDraft("");
@@ -89,6 +159,18 @@ const TagInput = React.forwardRef(
               }
             }
           ),
+          showClear ? /* @__PURE__ */ jsx(
+            "button",
+            {
+              type: "button",
+              tabIndex: -1,
+              "aria-label": clearControl.label,
+              "data-slot": "tag-input-clear",
+              className: "ui-control-inline-affix-action ui-tag-input-clear",
+              onClick: clearAll,
+              children: clearControl.clearIcon ?? /* @__PURE__ */ jsx(X, { className: "ui-control-inline-affix-icon", "aria-hidden": "true" })
+            }
+          ) : null,
           /* @__PURE__ */ jsx("span", { "aria-live": "polite", className: "sr-only", "data-slot": "tag-input-status", children: t("ui.tagInput.tagCount", { count: tags.length }) }),
           name ? /* @__PURE__ */ jsx("input", { type: "hidden", name, value: tags.join(",") }) : null
         ]

package/dist/form/form-context.d.ts

@@ -1,3 +1,4 @@
+import { type Control, type FieldPath, type FieldValues, type UseFormReturn } from "react-hook-form";
 import type { FormStateAdapter } from "../props/components/form.prop.js";
 /**
  * Context carrying a framework-agnostic {@link FormStateAdapter}. `FormRoot` provides it on the
@@ -7,11 +8,39 @@ import type { FormStateAdapter } from "../props/components/form.prop.js";
 export declare const FormAdapterContext: import("react").Context<FormStateAdapter | null>;
 /** Read the active form-state adapter, or `null` when `FormRoot` runs the react-hook-form path. */
 export declare function useFormAdapter(): FormStateAdapter | null;
+/** Form-wide options shared by BOTH paths — currently the antd-style form-level `disabled`. */
+export interface FormOptionsContextValue {
+    disabled: boolean;
+    submitting?: boolean;
+}
+/** Defaults to enabled so a `FormField`/`FormFieldControl` outside a `FormRoot` keeps working. */
+export declare const FormOptionsContext: import("react").Context<FormOptionsContextValue>;
+/**
+ * Whether the surrounding `FormRoot` disables its fields (`FormRoot disabled`). Read it for the
+ * action buttons, which are NOT fields and so are never disabled automatically.
+ */
+export declare function useFormDisabled(): boolean;
 /**
  * Whether the surrounding `FormRoot` is currently submitting — works for BOTH paths: the adapter's
  * `isSubmitting` (e.g. Inertia's `processing`) or react-hook-form's `formState.isSubmitting`.
  */
 export declare function useFormSubmitting(): boolean;
+/**
+ * The react-hook-form instance of the surrounding `FormRoot` (antd `Form.useFormInstance`) — for
+ * `setValue`/`trigger`/`getValues` deep inside a form without prop-drilling `form`. Throws on the
+ * adapter path, which has no RHF instance; use {@link useFormAdapter} there.
+ */
+export declare function useFormInstance<TFieldValues extends FieldValues = FieldValues>(): UseFormReturn<TFieldValues>;
+export declare function getFallbackFormControl(): Control<FieldValues>;
+/**
+ * Subscribe to a field's value (antd `Form.useWatch`) — the "show this section only when `plan`
+ * is `enterprise`" case, WITHOUT re-rendering the whole form. Omit `name` for every value.
+ * Works on both paths: react-hook-form's `useWatch`, or the adapter's `getValue`/`getValues`.
+ *
+ * Returns `unknown` — the same contract as `FormFieldControl`'s render-prop `value`. Narrow at the
+ * call site (`String(v ?? "")`, a Zod parse, a type guard).
+ */
+export declare function useFormWatch<TFieldValues extends FieldValues = FieldValues>(name?: FieldPath<TFieldValues>): unknown;
 /**
  * Normalise a control's change payload to a bare value. The `FormFieldControl` render-prop spreads
  * `onChange` onto a control that may call it with a DOM `ChangeEvent` (native `<Input>`) OR a raw

package/dist/form/form-context.js

@@ -1,15 +1,50 @@
 "use client";
 import { createContext, useContext } from "react";
-import { useFormContext } from "react-hook-form";
+import {
+  createFormControl,
+  useFormContext,
+  useWatch
+} from "react-hook-form";
 const FormAdapterContext = createContext(null);
 function useFormAdapter() {
   return useContext(FormAdapterContext);
 }
+const FormOptionsContext = createContext({ disabled: false });
+function useFormDisabled() {
+  return useContext(FormOptionsContext).disabled;
+}
 function useFormSubmitting() {
+  const { submitting } = useContext(FormOptionsContext);
+  const adapter = useContext(FormAdapterContext);
+  const rhf = useFormContext();
+  if (adapter) return Boolean(submitting || adapter.isSubmitting);
+  return Boolean(submitting || rhf?.formState?.isSubmitting);
+}
+function useFormInstance() {
+  const rhf = useFormContext();
+  if (!rhf) {
+    throw new Error(
+      "useFormInstance must be rendered inside <FormRoot form={\u2026}> (react-hook-form path). On the adapter path use useFormAdapter()."
+    );
+  }
+  return rhf;
+}
+let fallbackControl;
+function getFallbackFormControl() {
+  fallbackControl ??= createFormControl().control;
+  return fallbackControl;
+}
+function useFormWatch(name) {
   const adapter = useContext(FormAdapterContext);
   const rhf = useFormContext();
-  if (adapter) return adapter.isSubmitting;
-  return rhf?.formState?.isSubmitting ?? false;
+  const control = rhf?.control ?? getFallbackFormControl();
+  const watched = useWatch({
+    control,
+    name,
+    disabled: !rhf
+  });
+  if (adapter) return name === void 0 ? adapter.getValues?.() : adapter.getValue(name);
+  return watched;
 }
 function extractControlValue(arg) {
   if (arg && typeof arg === "object" && "target" in arg) {
@@ -23,7 +58,12 @@ function extractControlValue(arg) {
 }
 export {
   FormAdapterContext,
+  FormOptionsContext,
   extractControlValue,
+  getFallbackFormControl,
   useFormAdapter,
-  useFormSubmitting
+  useFormDisabled,
+  useFormInstance,
+  useFormSubmitting,
+  useFormWatch
 };

package/dist/form/form-field-array.d.ts

@@ -0,0 +1,22 @@
+import * as React from "react";
+import { type FieldArrayPath, type FieldValues } from "react-hook-form";
+import type { FormFieldArrayProp } from "../props/components/form.prop.js";
+export type { FormFieldArrayProp } from "../props/components/form.prop.js";
+/**
+ * FormFieldArray — repeating fields (antd `Form.List`) on react-hook-form's `useFieldArray`, so
+ * rows keep their identity across insert/remove/move instead of being re-keyed by index.
+ *
+ * Each row hands back its dotted path prefix; build the child field name from it, which is what
+ * makes nested validation messages land on the right row:
+ *
+ * ```tsx
+ * <FormFieldArray<Values, "contacts"> name="contacts">
+ *   {({ fields, append, remove }) => (…
+ *     <FormFieldControl name={`${row.name}.email`} label={t("contact.email")}>…
+ *   )}
+ * </FormFieldArray>
+ * ```
+ *
+ * react-hook-form path only — a server-driven `adapter` owns its own collection state.
+ */
+export declare function FormFieldArray<TFieldValues extends FieldValues, TName extends FieldArrayPath<TFieldValues> = FieldArrayPath<TFieldValues>>({ name, children }: FormFieldArrayProp<TFieldValues, TName>): React.JSX.Element;