@godxjp/ui 18.15.4 → 19.1.0

package/dist/components/ui/separator.js

@@ -1,21 +1,52 @@
 "use client";
-import { jsx } from "react/jsx-runtime";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import * as SeparatorPrimitive from "@radix-ui/react-separator";
 import { cn } from "../../lib/utils.js";
-const Separator = React.forwardRef(({ className, orientation = "horizontal", decorative = true, ...props }, ref) => /* @__PURE__ */ jsx(
-  SeparatorPrimitive.Root,
-  {
-    ref,
-    "data-slot": "separator",
-    "data-orientation": orientation,
-    orientation,
+const Separator = React.forwardRef(
+  ({
+    className,
+    orientation = "horizontal",
     decorative,
-    className: cn("ui-separator", className),
+    label,
+    labelAlign = "center",
+    tone = "default",
     ...props
+  }, ref) => {
+    const hasLabel = typeof label === "string" && label.trim() !== "";
+    const labelled = hasLabel && orientation === "horizontal";
+    if (typeof process !== "undefined" && process.env?.NODE_ENV !== "production") {
+      if (hasLabel && orientation === "vertical") {
+        console.warn(
+          'Separator: `label` is rendered on orientation="horizontal" only; it was ignored. Use a horizontal rule for a day divider / unread watermark.'
+        );
+      }
+    }
+    const isDecorative = decorative ?? !labelled;
+    return /* @__PURE__ */ jsx(
+      SeparatorPrimitive.Root,
+      {
+        ref,
+        "data-slot": "separator",
+        "data-orientation": orientation,
+        "data-tone": tone,
+        "data-labelled": labelled ? "" : void 0,
+        "data-label-align": labelled ? labelAlign : void 0,
+        orientation,
+        decorative: isDecorative,
+        "aria-label": labelled && !isDecorative ? label : void 0,
+        className: cn("ui-separator", className),
+        ...props,
+        children: labelled ? /* @__PURE__ */ jsxs(Fragment, { children: [
+          /* @__PURE__ */ jsx("span", { className: "ui-separator-rule", "aria-hidden": "true" }),
+          /* @__PURE__ */ jsx("span", { className: "ui-separator-label", "aria-hidden": isDecorative ? void 0 : true, children: label }),
+          /* @__PURE__ */ jsx("span", { className: "ui-separator-rule", "aria-hidden": "true" })
+        ] }) : null
+      }
+    );
   }
-));
-Separator.displayName = SeparatorPrimitive.Root.displayName;
+);
+Separator.displayName = "Separator";
 export {
   Separator
 };

package/dist/components/ui/toggle-group.d.ts

@@ -1,13 +1,23 @@
 import * as React from "react";
 import * as ToggleGroupPrimitive from "@radix-ui/react-toggle-group";
-import { type ToggleProps } from "./toggle.js";
-type ToggleGroupVariant = ToggleProps["variant"];
-type ToggleGroupSize = ToggleProps["size"];
-export declare const ToggleGroup: React.ForwardRefExoticComponent<((Omit<ToggleGroupPrimitive.ToggleGroupSingleProps & React.RefAttributes<HTMLDivElement>, "ref"> | Omit<ToggleGroupPrimitive.ToggleGroupMultipleProps & React.RefAttributes<HTMLDivElement>, "ref">) & {
+import { type ToggleCountFields, type ToggleProp } from "./toggle.js";
+type ToggleGroupVariant = ToggleProp["variant"];
+type ToggleGroupSize = ToggleProp["size"];
+export declare const ToggleGroup: React.ForwardRefExoticComponent<((Omit<ToggleGroupPrimitive.ToggleGroupMultipleProps & React.RefAttributes<HTMLDivElement>, "ref"> | Omit<ToggleGroupPrimitive.ToggleGroupSingleProps & React.RefAttributes<HTMLDivElement>, "ref">) & {
     variant?: ToggleGroupVariant;
     size?: ToggleGroupSize;
 }) & React.RefAttributes<HTMLDivElement>>;
-export declare const ToggleGroupItem: React.ForwardRefExoticComponent<Omit<ToggleGroupPrimitive.ToggleGroupItemProps & React.RefAttributes<HTMLButtonElement>, "ref"> & {
+/**
+ * `variant`/`size` come from the group through context; the COUNT stays per item, because the
+ * number is per-item data (gh#312). Same vocabulary as `Toggle` and `Button` — one counter pill
+ * for the whole library.
+ */
+export type ToggleGroupItemProp = React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Item> & ToggleCountFields & {
+    variant?: ToggleGroupVariant;
+    size?: ToggleGroupSize;
+};
+export type ToggleGroupItemProps = ToggleGroupItemProp;
+export declare const ToggleGroupItem: React.ForwardRefExoticComponent<Omit<ToggleGroupPrimitive.ToggleGroupItemProps & React.RefAttributes<HTMLButtonElement>, "ref"> & ToggleCountFields & {
     variant?: ToggleGroupVariant;
     size?: ToggleGroupSize;
 } & React.RefAttributes<HTMLButtonElement>>;

package/dist/components/ui/toggle-group.js

@@ -1,9 +1,9 @@
 "use client";
-import { jsx } from "react/jsx-runtime";
+import { jsx, jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import * as ToggleGroupPrimitive from "@radix-ui/react-toggle-group";
 import { cn } from "../../lib/utils.js";
-import { toggleVariants } from "./toggle.js";
+import { toggleVariants, useCounterPill } from "./toggle.js";
 const ToggleGroupContext = React.createContext({});
 const ToggleGroup = React.forwardRef(({ className, variant, size, children, ...props }, ref) => {
   const context = React.useMemo(() => ({ variant, size }), [variant, size]);
@@ -21,22 +21,47 @@ const ToggleGroup = React.forwardRef(({ className, variant, size, children, ...p
   );
 });
 ToggleGroup.displayName = ToggleGroupPrimitive.Root.displayName;
-const ToggleGroupItem = React.forwardRef(({ className, variant, size, ...props }, ref) => {
-  const context = React.useContext(ToggleGroupContext);
-  const resolvedVariant = variant ?? context.variant;
-  const resolvedSize = size ?? context.size;
-  return /* @__PURE__ */ jsx(
-    ToggleGroupPrimitive.Item,
-    {
-      ref,
-      "data-slot": "toggle-group-item",
-      "data-variant": resolvedVariant,
-      "data-size": resolvedSize,
-      className: cn(toggleVariants({ variant: resolvedVariant, size: resolvedSize }), className),
-      ...props
-    }
-  );
-});
+const ToggleGroupItem = React.forwardRef(
+  ({
+    className,
+    variant,
+    size,
+    count,
+    overflowCount,
+    showZero,
+    countLabel,
+    children,
+    "aria-label": ariaLabel,
+    ...props
+  }, ref) => {
+    const context = React.useContext(ToggleGroupContext);
+    const resolvedVariant = variant ?? context.variant;
+    const resolvedSize = size ?? context.size;
+    const { pill, resolvedAriaLabel } = useCounterPill({
+      count,
+      overflowCount,
+      showZero,
+      countLabel,
+      ariaLabel
+    });
+    return /* @__PURE__ */ jsxs(
+      ToggleGroupPrimitive.Item,
+      {
+        ref,
+        "data-slot": "toggle-group-item",
+        "data-variant": resolvedVariant,
+        "data-size": resolvedSize,
+        "aria-label": resolvedAriaLabel,
+        className: cn(toggleVariants({ variant: resolvedVariant, size: resolvedSize }), className),
+        ...props,
+        children: [
+          children,
+          pill
+        ]
+      }
+    );
+  }
+);
 ToggleGroupItem.displayName = ToggleGroupPrimitive.Item.displayName;
 export {
   ToggleGroup,

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

@@ -3,11 +3,72 @@ import * as TogglePrimitive from "@radix-ui/react-toggle";
 import { type VariantProps } from "class-variance-authority";
 declare const toggleVariants: (props?: ({
     variant?: "default" | "outline" | null | undefined;
-    size?: "sm" | "md" | "lg" | null | undefined;
+    size?: "lg" | "md" | "sm" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
-export type ToggleProps = React.ComponentPropsWithoutRef<typeof TogglePrimitive.Root> & VariantProps<typeof toggleVariants>;
+/**
+ * The counter-pill vocabulary, lifted VERBATIM from `Button` (`count` / `overflowCount` /
+ * `showZero`) so a counted filter tab and a counted, pressed filter chip are one vocabulary rather
+ * than two that drift (gh#312). Not exported on its own — it is folded into `ToggleProp` and
+ * `ToggleGroupItemProp` so there is one public name per component.
+ */
+type ToggleCountFields = {
+    /**
+     * Optional numeric count rendered as a borderless counter pill after the label — the SAME
+     * vocabulary `Button` already defines, so a counted segmented toggle and a counted filter tab
+     * read identically. Formatted with `Intl.NumberFormat` in the active locale (never `String(n)`,
+     * never a hand-rolled thousands separator). Never nest a `Badge` inside a Toggle for this: a
+     * Badge is a status chip with its own surface, so it double-borders the chip and puts two boxes
+     * where there is one control. The pill takes its colour from the toggle's OWN pressed state, so
+     * pressed and unpressed chips differ without reading the number.
+     */
+    count?: number;
+    /** Cap for `count` — beyond it the pill shows `{overflowCount}+` (e.g. `99+`). Default `99`. */
+    overflowCount?: number;
+    /** Render the pill when `count` is 0. Default `true`, matching Button. */
+    showZero?: boolean;
+    /**
+     * Localized description of what the count MEANS, folded into the accessible name so the control
+     * never announces as a bare number ("👍 3" → "thumbs up, 3 reactions"). Supply it whenever the
+     * visible label is an icon or an emoji; with a text label the label itself already carries the
+     * meaning. Pass a `t()`-resolved string — the library does not own this wording.
+     */
+    countLabel?: string;
+};
+/**
+ * Counter pill shared by `Toggle` and `ToggleGroupItem`.
+ *
+ * ACCESSIBLE NAME. The digits live INSIDE the same `button[aria-pressed]` — one tab stop, one
+ * focus ring, one name. The name always comes out as "<label>, <count> <unit>" ("Unread, 12",
+ * "Thích, 3 lượt"), by one of two routes:
+ *
+ *   • Name from CONTENTS (the usual text chip). The visible digits are `aria-hidden`, and an
+ *     `sr-only` sibling carries ", 12 unit". The separator is explicit on purpose: the accessible
+ *     name is a CONCATENATION of descendant text, and whether a browser inserts a space between
+ *     two inline boxes is a layout detail no test can rely on — without it the control can
+ *     announce "Unread12".
+ *   • Name from `aria-label` (an icon or emoji chip). Contents are ignored for the name, so the
+ *     same ", 12 unit" tail is folded into the label instead.
+ *
+ * Either way the count is announced exactly ONCE — the visible digits are hidden from the a11y
+ * tree precisely so they cannot be counted twice — and there is deliberately no `aria-live`: a
+ * count that ticks up as other people react is not this control's status, and a live region here
+ * would fire on every socket message. A product that wants the change announced owns its own
+ * live region.
+ */
+declare function useCounterPill({ count, overflowCount, showZero, countLabel, ariaLabel, }: ToggleCountFields & {
+    ariaLabel?: string;
+}): {
+    pill: null;
+    resolvedAriaLabel: string | undefined;
+} | {
+    pill: React.JSX.Element;
+    resolvedAriaLabel: string | undefined;
+};
+export type ToggleProp = React.ComponentPropsWithoutRef<typeof TogglePrimitive.Root> & VariantProps<typeof toggleVariants> & ToggleCountFields;
+export type ToggleProps = ToggleProp;
 export declare const Toggle: React.ForwardRefExoticComponent<Omit<TogglePrimitive.ToggleProps & React.RefAttributes<HTMLButtonElement>, "ref"> & VariantProps<(props?: ({
     variant?: "default" | "outline" | null | undefined;
-    size?: "sm" | "md" | "lg" | null | undefined;
-} & import("class-variance-authority/types").ClassProp) | undefined) => string> & React.RefAttributes<HTMLButtonElement>>;
-export { toggleVariants };
+    size?: "lg" | "md" | "sm" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string> & ToggleCountFields & React.RefAttributes<HTMLButtonElement>>;
+export { toggleVariants, useCounterPill };
+export type { ToggleCountFields };

package/dist/components/ui/toggle.js

@@ -1,9 +1,10 @@
 "use client";
-import { jsx } from "react/jsx-runtime";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import * as TogglePrimitive from "@radix-ui/react-toggle";
 import { cva } from "class-variance-authority";
 import { cn } from "../../lib/utils.js";
+import { useTranslation } from "../../i18n/use-translation.js";
 const toggleVariants = cva("ui-toggle", {
   variants: {
     variant: {
@@ -21,17 +22,71 @@ const toggleVariants = cva("ui-toggle", {
     size: "md"
   }
 });
-const Toggle = React.forwardRef(({ className, variant, size, ...props }, ref) => /* @__PURE__ */ jsx(
-  TogglePrimitive.Root,
-  {
-    ref,
-    "data-slot": "toggle",
-    className: cn(toggleVariants({ variant, size }), className),
+function useCounterPill({
+  count,
+  overflowCount = 99,
+  showZero = true,
+  countLabel,
+  ariaLabel
+}) {
+  const { locale } = useTranslation();
+  const visible = count != null && (count !== 0 || showZero);
+  const formatted = React.useMemo(() => {
+    if (count == null) return "";
+    const format = new Intl.NumberFormat(locale);
+    return count > overflowCount ? `${format.format(overflowCount)}+` : format.format(count);
+  }, [count, locale, overflowCount]);
+  if (!visible) {
+    return { pill: null, resolvedAriaLabel: ariaLabel };
+  }
+  const spoken = countLabel ? `${formatted} ${countLabel}` : formatted;
+  return {
+    pill: /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsx("span", { "data-slot": "toggle-count", className: "ui-toggle-count", "aria-hidden": "true", children: formatted }),
+      /* @__PURE__ */ jsx("span", { className: "sr-only", children: `, ${spoken}` })
+    ] }),
+    resolvedAriaLabel: ariaLabel == null ? ariaLabel : `${ariaLabel}, ${spoken}`
+  };
+}
+const Toggle = React.forwardRef(
+  ({
+    className,
+    variant,
+    size,
+    count,
+    overflowCount,
+    showZero,
+    countLabel,
+    children,
+    "aria-label": ariaLabel,
     ...props
+  }, ref) => {
+    const { pill, resolvedAriaLabel } = useCounterPill({
+      count,
+      overflowCount,
+      showZero,
+      countLabel,
+      ariaLabel
+    });
+    return /* @__PURE__ */ jsxs(
+      TogglePrimitive.Root,
+      {
+        ref,
+        "data-slot": "toggle",
+        "aria-label": resolvedAriaLabel,
+        className: cn(toggleVariants({ variant, size }), className),
+        ...props,
+        children: [
+          children,
+          pill
+        ]
+      }
+    );
   }
-));
+);
 Toggle.displayName = TogglePrimitive.Root.displayName;
 export {
   Toggle,
-  toggleVariants
+  toggleVariants,
+  useCounterPill
 };

package/dist/i18n/messages/en.json

@@ -213,6 +213,14 @@
     }
   },
   "dataDisplay": {
+    "avatar": {
+      "presence": {
+        "online": "Online",
+        "away": "Away",
+        "busy": "Busy",
+        "offline": "Offline"
+      }
+    },
     "carousel": {
       "roleDescription": "carousel",
       "ariaLabel": "Carousel",

package/dist/i18n/messages/ja.json

@@ -207,6 +207,14 @@
     }
   },
   "dataDisplay": {
+    "avatar": {
+      "presence": {
+        "online": "オンライン",
+        "away": "離席中",
+        "busy": "取り込み中",
+        "offline": "オフライン"
+      }
+    },
     "carousel": {
       "roleDescription": "カルーセル",
       "ariaLabel": "カルーセル",

package/dist/i18n/messages/vi.json

@@ -207,6 +207,14 @@
     }
   },
   "dataDisplay": {
+    "avatar": {
+      "presence": {
+        "online": "Trực tuyến",
+        "away": "Vắng mặt",
+        "busy": "Bận",
+        "offline": "Ngoại tuyến"
+      }
+    },
     "carousel": {
       "roleDescription": "băng chuyền",
       "ariaLabel": "Băng chuyền",

package/dist/lib/control-styles.d.ts

@@ -1,6 +1,20 @@
 /** Shared control sizing — reads `--control-height`, `--font-size-*` from density / theme. */
 export declare const controlFieldClass = "ui-control w-full rounded-[var(--control-radius)] border border-input bg-background ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-[3px] focus-visible:ring-ring/25 disabled:cursor-not-allowed disabled:opacity-50";
 export declare const controlMultilineClass = "ui-control-multiline w-full rounded-[var(--control-radius)] border border-input bg-background ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-[3px] focus-visible:ring-ring/25 disabled:cursor-not-allowed disabled:opacity-50";
+/**
+ * Multiline control with its own chrome removed, for a textarea EMBEDDED in a surface that
+ * already draws the box — a chat composer inside a Card, an inline edit cell, a comment box in
+ * a panel. Two nested rounded borders is the tell that this was missing.
+ *
+ * These are utilities, not tokens, ON PURPOSE. `.ui-control-multiline` reads
+ * `--control-border-width` / `--control-shadow` from `@layer components`, but the default class
+ * ALSO carries Tailwind's `border` in `@layer utilities`, which wins whatever the token says —
+ * the same structural inertness gh#260 found on Badge's font size. So the variant cannot be a
+ * token override by a consumer; it has to drop the utilities here.
+ *
+ * The focus ring goes with them: the surface owns focus, via `focus-within` on the wrapper.
+ */
+export declare const controlMultilineGhostClass = "ui-control-multiline w-full min-h-0 border-0 bg-transparent shadow-none placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-0 disabled:cursor-not-allowed disabled:opacity-50";
 /**
  * Open-state ring for popup-style triggers (Select / Cascader / TreeSelect / SearchSelect).
  * Radix moves focus INTO the popup on open, so the trigger loses `:focus-visible` and — without

package/dist/lib/control-styles.js

@@ -1,5 +1,6 @@
 const controlFieldClass = "ui-control w-full rounded-[var(--control-radius)] border border-input bg-background ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-[3px] focus-visible:ring-ring/25 disabled:cursor-not-allowed disabled:opacity-50";
 const controlMultilineClass = "ui-control-multiline w-full rounded-[var(--control-radius)] border border-input bg-background ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-[3px] focus-visible:ring-ring/25 disabled:cursor-not-allowed disabled:opacity-50";
+const controlMultilineGhostClass = "ui-control-multiline w-full min-h-0 border-0 bg-transparent shadow-none placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-0 disabled:cursor-not-allowed disabled:opacity-50";
 const controlOpenRingClass = "data-[state=open]:border-ring data-[state=open]:ring-ring/50 data-[state=open]:ring-[3px]";
 const controlTriggerClass = "ui-control flex w-full items-center justify-between gap-2 whitespace-nowrap rounded-[var(--control-radius)] border border-input bg-background shadow-sm transition-[color,box-shadow] focus-visible:outline-none focus-visible:ring-[3px] focus-visible:ring-ring/25 data-[state=open]:border-ring data-[state=open]:ring-ring/50 data-[state=open]:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50 [&>span]:line-clamp-1";
 const controlIconClass = "size-[length:var(--control-height)] shrink-0";
@@ -21,6 +22,7 @@ export {
   controlIconLeadingClass,
   controlIconSmClass,
   controlMultilineClass,
+  controlMultilineGhostClass,
   controlOpenRingClass,
   controlTriggerClass,
   tableCellPaddingClass,

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

@@ -13,6 +13,12 @@ import * as React from "react";
  * - `aria-errormessage` + `aria-invalid` — the validation message, announced when invalid.
  * - `aria-required` — required-field semantics.
  * - `aria-label` — a name supplied directly (used when there is no visible label element).
+ *
+ * `data-field` travels the SAME route (gh#337) and is therefore part of this bag even though it is
+ * not an ARIA attribute. It is the field's stable machine key — the `data-testid` role, standardised
+ * on one attribute so a control never has to be found by a generated id or by its visible Japanese
+ * label. It is inert (read-only metadata) and must land on the same semantic focus target the aria
+ * relationships do; routing it through a second, parallel mechanism is how a control gets missed.
  */
 export interface FieldA11yProps {
     "aria-label"?: string;
@@ -21,6 +27,8 @@ export interface FieldA11yProps {
     "aria-errormessage"?: string;
     "aria-invalid"?: React.AriaAttributes["aria-invalid"];
     "aria-required"?: React.AriaAttributes["aria-required"];
+    /** Stable machine key of the field (gh#337) — see the interface doc above. */
+    "data-field"?: string;
 }
 /**
  * Merge one or more space-separated id-reference lists (`aria-describedby`, `aria-labelledby`,
@@ -81,6 +89,49 @@ export declare const FieldNameContext: React.Context<FieldNameContextValue | nul
  * 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 enclosing `FormField`, made reachable by NESTED controls (gh#337).
+ *
+ * `cloneElement` reaches FormField's single DIRECT child only. In the real screens this library
+ * serves, 322 of 1,410 controls (23%) sit one level deeper — the direct child is a `Flex` holding a
+ * from/to pair, a 年/月 combo, or a value + 「不明」 checkbox — so the machine key stopped on the
+ * wrapper `div` and the controls inside stayed anonymous. The customer's acceptance condition is
+ * 「画面に見えている入力欄の100%に付与されていること」; 77% does not pass.
+ *
+ * The key for such a control is its OWN `id`, and that is a finding, not a convention invented
+ * here: of those 322, **250 already carry a static id** and the ambiguous case the wrapper creates
+ * — two controls under one field — is already distinguished at the call site
+ * (`search_billing_date_from` / `..._to`, `fax` / `fax_unknown`). So a nested control names itself
+ * and no two controls can ever end up sharing a key. The remaining 72 (48 computed ids, 24 with no
+ * id at all) get NOTHING: a fabricated key is worse than a missing one, because automation would
+ * bind to it and break silently on the next render.
+ */
+export interface FieldIdentityContextValue {
+    /** Whether the app opted into a native `name` (@see AppProviderProp.emitFieldNames). */
+    emitName: boolean;
+}
+export declare const FieldIdentityContext: React.Context<FieldIdentityContextValue | null>;
+/**
+ * Resolve `data-field` / `name` for a control nested under a `FormField` (see
+ * {@link FieldIdentityContext}). Returns `{}` — adding nothing — in every case but the one it
+ * exists for, which is what keeps it safe to call from every control:
+ *
+ * - **outside a FormField** → `{}`. A control elsewhere on the page is untouched.
+ * - **`data-field` already present** → `{}`. Either `FormField` cloned it onto its direct child, or
+ *   a composite (DatePicker, Select) already resolved this field and is passing it down. Whoever
+ *   owns the field owns BOTH attributes, so `name` is not second-guessed here either — that is what
+ *   keeps DatePicker's ISO mirror (`name` belongs to the hidden `yyyy-MM-dd` input, not the visible
+ *   `yyyy/MM/dd` one) and Select's native `<select>` intact.
+ * - **no `id` of its own** → `{}`. Nothing to derive a stable key from; see the interface doc.
+ */
+export declare function useFieldIdentity(own: {
+    id?: string;
+    name?: string;
+    "data-field"?: string;
+}): {
+    "data-field"?: string;
+    name?: string;
+};
 /**
  * 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
@@ -98,4 +149,5 @@ export declare function useFieldNameFallback(name: Pick<FieldA11yProps, "aria-la
 export declare function pickGroupFieldA11y(props: FieldA11yProps): {
     "aria-labelledby"?: string;
     "aria-describedby"?: string;
+    "data-field"?: string;
 };

package/dist/lib/field-a11y.js

@@ -6,7 +6,8 @@ const FIELD_A11Y_KEYS = [
   "aria-describedby",
   "aria-errormessage",
   "aria-invalid",
-  "aria-required"
+  "aria-required",
+  "data-field"
 ];
 function mergeAriaIds(...values) {
   return Array.from(new Set(values.flatMap((value) => value?.split(/\s+/).filter(Boolean) ?? []))).join(
@@ -47,19 +48,33 @@ function useFieldNameFallback(name) {
     ...field.label !== void 0 ? { "aria-label": field.label } : {}
   };
 }
+const FieldIdentityContext = React.createContext(null);
+function useFieldIdentity(own) {
+  const ctx = React.useContext(FieldIdentityContext);
+  if (!ctx || own["data-field"] !== void 0 || own.id === void 0) return {};
+  return {
+    "data-field": own.id,
+    ...ctx.emitName && own.name === void 0 ? { name: own.id } : {}
+  };
+}
 function pickGroupFieldA11y(props) {
   const describedBy = mergeAriaIds(props["aria-describedby"], props["aria-errormessage"]);
   return {
     ...props["aria-labelledby"] !== void 0 ? { "aria-labelledby": props["aria-labelledby"] } : {},
-    ...describedBy !== void 0 ? { "aria-describedby": describedBy } : {}
+    ...describedBy !== void 0 ? { "aria-describedby": describedBy } : {},
+    // Not an ARIA attribute and so not subject to the role="group" restriction above — a group
+    // still has to be findable by its field key (gh#337).
+    ...props["data-field"] !== void 0 ? { "data-field": props["data-field"] } : {}
   };
 }
 export {
+  FieldIdentityContext,
   FieldNameContext,
   mergeAriaIds,
   omitFieldA11y,
   pickFieldA11y,
   pickGroupFieldA11y,
   resolveFieldA11y,
+  useFieldIdentity,
   useFieldNameFallback
 };

package/dist/props/components/app.prop.d.ts

@@ -49,6 +49,19 @@ export type AppProviderProp = {
      * number (e.g. `0.95`) overrides it. Type is a separate axis — not scaled.
      */
     scaling?: number | null;
+    /**
+     * Emit a native `name` on every control a `FormField` wraps, taken from the field's key
+     * (`field` → `name` → `id`). Default `false`, and deliberately opt-in (gh#337).
+     *
+     * `data-field` is inert metadata and is always emitted; `name` is NOT — it changes what a
+     * native `<form>` submit sends. An app whose controls have never carried a `name` would start
+     * posting extra keys to its backend the moment it upgraded the library. That is a behaviour
+     * change no shared package may make by default, so the app that WANTS it (a screen-automation /
+     * RPA contract, native form posts) turns it on here, once, and every FormField in it obeys.
+     *
+     * A `name` written on the control itself always wins over the injected one.
+     */
+    emitFieldNames?: boolean;
     onLocaleChange?: (locale: AppLocale) => void;
     onTimezoneChange?: (timezone: AppTimezone) => void;
     onTimeFormatChange?: (timeFormat: AppTimeFormat) => void;
@@ -117,6 +130,8 @@ export type AppContextValue = {
     density: AppDensity;
     fontSize: AppFontSize;
     scaling: number | null;
+    /** Whether `FormField` injects a native `name` onto its control (gh#337). Default `false`. */
+    emitFieldNames: boolean;
     setLocale: (locale: AppLocale) => void;
     setTimezone: (timezone: AppTimezone) => void;
     setTimeFormat: (timeFormat: AppTimeFormat) => void;