@godxjp/ui 19.0.0 → 19.2.0

package/dist/email/geometry.d.ts

@@ -35,10 +35,7 @@ export interface EmailShellTokens {
     /** Tight rhythm (heading ↔ lede). */
     readonly gapSm: string;
     readonly gapSmPx: number;
-    /**
-     * Height the canonical invitation reference card measures at this geometry (480×407). A
-     * visual-regression target, NOT a layout input — never set a fixed height on an email card.
-     */
+    /** Height the canonical invitation reference card measures at this geometry (480×407). */
     readonly referenceHeight: string;
     readonly referenceHeightPx: number;
 }
@@ -47,11 +44,10 @@ export declare const EMAIL_SHELL: EmailShellTokens;
 export interface EmailTypographyTokens {
     /**
      * The canonical DXS stack, Noto Sans JP first (product override, direct instruction). Web-font
-     * `@font-face` is unavailable in most clients, so this NAMES the face and degrades: a client with
-     * Noto Sans JP installed (or a webmail that already loaded it) renders the canonical face;
+     * `@font-face` is unavailable in most clients, so this NAMES the face and degrades: a client
+     * with Noto Sans JP installed (or a webmail that already loaded it) renders the canonical face;
      * everything else falls to Hiragino (macOS/iOS) → Yu Gothic (Windows) → M PLUS 2 → Meiryo → the
-     * system UI face → Arial → `sans-serif`. Family names are SINGLE-quoted so the value drops
-     * straight into a double-quoted `style="…"` attribute.
+     * system UI face → Arial → `sans-serif`.
      */
     readonly fontFamily: string;
     /** Mono stack for invoice ids, masked card numbers, ISO dates and amounts. */

package/dist/email/index.d.ts

@@ -1,53 +1,9 @@
 /**
- * `@godxjp/ui/email` — the email-safe design-token contract for transactional templates (issue #227).
- *
- * ## Why this exists
- *
- * A transactional email is rendered by Blade/Twig/MJML, not React, and by clients that strip
- * `<style>`, ignore CSS custom properties, refuse relative units and block remote images. So the
- * two things a template usually reaches for — the component library and the CSS token file — are
- * both unavailable, and templates end up hand-copying hex and hand-drawing the logo. That is
+ * So the two things a template usually reaches for — the component library and the CSS token file
+ * — are both unavailable, and templates end up hand-copying hex and hand-drawing the logo. That is
  * exactly the drift this module removes: it is a FRAMEWORK-NEUTRAL, zero-dependency, React-free
- * data export of literal `#rrggbb` / `px` values plus the canonical brand-mark markup.
- *
- * ## The no-drift guarantee
- *
- * Nothing here is hand-typed. `src/tokens/foundation.css` (colour roles) and
- * `src/tokens/components/email.css` (geometry/typography) are read by
- * `scripts/gen-email-tokens.mjs` into `tokens.generated.ts`, and the HSL→hex conversion runs at
- * module load. There is no hex literal anywhere in `src/email/`, so an email palette that diverges
- * from the web palette is not something a maintainer can accidentally write.
- * `src/email/__tests__/email-tokens.test.ts` re-derives every value straight from the CSS and
- * asserts equality, and `pnpm check:email-token-sync` fails CI if the generated file goes stale.
- *
- * ## Usage
- *
- * ```ts
- * import { EMAIL_COLORS, EMAIL_URGENCY, EMAIL_SHELL, EMAIL_CTA, EMAIL_BRAND_MARK, emailInlineStyle } from "@godxjp/ui/email";
- *
- * const card = emailInlineStyle({
- *   width: EMAIL_SHELL.width,
- *   padding: EMAIL_SHELL.padding,
- *   backgroundColor: EMAIL_COLORS.surface,
- *   border: `${EMAIL_SHELL.borderWidth} solid ${EMAIL_COLORS.border}`,
- *   borderTopColor: EMAIL_URGENCY.accent,
- *   borderRadius: EMAIL_SHELL.radius,
- * });
- * ```
- *
- * A non-JS template engine (Blade, Twig, Liquid) consumes the same values through
- * `EMAIL_TOKENS_JSON` — dump it once in the build step and read the JSON from PHP:
- *
- * ```sh
- * node --input-type=module -e \
- *   'import("@godxjp/ui/email").then(m => process.stdout.write(m.EMAIL_TOKENS_JSON))' \
- *   > resources/design/email-tokens.json
- * ```
- *
- * ## Scope
- *
- * Tokens, geometry and brand markup only. Copy, recipients, links, locale, triggers and queue
- * behaviour belong to the sending application — this module knows nothing about them.
+ * data export of literal `#rrggbb` / `px` values plus the canonical brand-mark markup. ## The
+ * no-drift guarantee Nothing here is hand-typed.
  */
 export { hslToHex, EMAIL_COLORS, EMAIL_COLORS_DARK, type EmailColorToken, type EmailHex, } from "./color.js";
 export { EMAIL_SHELL, EMAIL_TYPOGRAPHY, EMAIL_CTA, EMAIL_FOOTER, EMAIL_FOCUS, EMAIL_MOBILE, type EmailTokenName, type EmailShellTokens, type EmailTypographyTokens, type EmailCtaTokens, type EmailFooterTokens, type EmailFocusTokens, type EmailMobileTokens, } from "./geometry.js";

package/dist/email/inline-style.d.ts

@@ -1,13 +1,7 @@
 /**
- * Inline-style serialisation for HTML email.
- *
- * Email clients do not run the cascade: Gmail strips `<style>`, Outlook resolves no custom
- * property, and only the `style=""` attribute on the painting element is universally honoured.
- * `emailInlineStyle` turns a declaration map into that attribute value AND enforces the three rules
- * that silently break templates — no `var()` (nothing resolves it), no `calc()` (Outlook's Word
- * renderer drops the whole declaration) and no `"` (it closes the `style="…"` attribute mid-value,
- * which is how a double-quoted font family corrupts a whole tag). Failing loudly at template-build
- * time beats a broken layout discovered in Mailpit.
+ * Inline-style serialisation for HTML email. Email clients do not run the cascade: Gmail strips
+ * `<style>`, Outlook resolves no custom property, and only the `style=""` attribute on the
+ * painting element is universally honoured.
  */
 /** A declaration map. Numbers are emitted verbatim (already-unitless values like `font-weight`). */
 export type EmailStyleDeclarations = Record<string, string | number | null | undefined>;

package/dist/email/urgency.d.ts

@@ -1,12 +1,7 @@
 import { type EmailHex } from "./color.js";
 /**
- * Semantic action-required styling for transactional email.
- *
- * `accent` is the non-text rail/border color painted on the normal email surface. The solid pair
- * is safe for icons and large or bold labels that satisfy the 3:1 contrast floor; it is not a
- * replacement for normal body copy, which remains `EMAIL_COLORS.foreground` on
- * `EMAIL_COLORS.surface`. This deliberately narrow contract prevents urgency from becoming an
- * undocumented second CTA or a component-local palette.
+ * Semantic action-required styling for transactional email. `accent` is the non-text rail/border
+ * color painted on the normal email surface.
  */
 export interface EmailUrgencyTokens {
     /** Non-text action-required rail or border on the standard email surface. */

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

@@ -9,15 +9,12 @@ export declare const FormAdapterContext: import("react").Context<FormStateAdapte
 export declare function useFormAdapter(): FormStateAdapter | null;
 /**
  * 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`. Spread
- * onto a submit button so `processing` drives its loading state automatically:
- * `<Button type="submit" loading={useFormSubmitting()}>`.
+ * `isSubmitting` (e.g. Inertia's `processing`) or react-hook-form's `formState.isSubmitting`.
  */
 export declare function useFormSubmitting(): boolean;
 /**
  * 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
- * value (a `Select`'s `onValueChange`). Mirror react-hook-form's own event unwrapping so the adapter
- * path binds identically for every control kind.
+ * value (a `Select`'s `onValueChange`).
  */
 export declare function extractControlValue(arg: unknown): unknown;

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

@@ -4,7 +4,6 @@ export type { FormRootProp } from "../props/components/form.prop.js";
 /**
  * FormRoot — the form shell. Provide EITHER `form` (built-in react-hook-form + Zod, client-side
  * validation) OR `adapter` (a framework-agnostic {@link FormStateAdapter} for a server-driven form
- * library — Inertia's `useForm` via `@godxjp/ui/inertia`, formik, TanStack Form). Both drive the same
- * `FormFieldControl` auto-binding; the core keeps ZERO dependency on any non-RHF form library.
+ * library — Inertia's `useForm` via `@godxjp/ui/inertia`, formik, TanStack Form).
  */
 export declare function FormRoot<TFieldValues extends FieldValues>({ form, adapter, onSubmit, children, className, id, }: FormRootProp<TFieldValues>): import("react").JSX.Element;

package/dist/i18n/messages/en.json

@@ -17,6 +17,10 @@
     "typeToConfirm": "Type {phrase} to confirm"
   },
   "dataEntry": {
+    "calendar": {
+      "today": "Today",
+      "close": "Close"
+    },
     "datePicker": {
       "placeholder": "Select date",
       "openCalendar": "Open calendar"

package/dist/i18n/messages/ja.json

@@ -17,6 +17,10 @@
     "typeToConfirm": "確認のため {phrase} と入力"
   },
   "dataEntry": {
+    "calendar": {
+      "today": "今日",
+      "close": "閉じる"
+    },
     "datePicker": {
       "placeholder": "日付を選択",
       "openCalendar": "カレンダーを開く"

package/dist/i18n/messages/vi.json

@@ -17,6 +17,10 @@
     "typeToConfirm": "Nhập {phrase} để xác nhận"
   },
   "dataEntry": {
+    "calendar": {
+      "today": "Hôm nay",
+      "close": "Đóng"
+    },
     "datePicker": {
       "placeholder": "Chọn ngày",
       "openCalendar": "Mở lịch"

package/dist/inertia/index.d.ts

@@ -1,11 +1,7 @@
 import type { ComponentType, ReactNode } from "react";
 import type { FormStateAdapter } from "../props/components/form.prop.js";
 import type { SidebarLinkComponentProp } from "../props/components/layout.prop.js";
-/**
- * Structural shape of Inertia's `useForm` return that the adapter needs. Duck-typed on purpose —
- * `@godxjp/ui` keeps ZERO dependency on `@inertiajs/react`; the real `useForm()` object satisfies
- * this shape, so a consumer passes it directly with no import from this package.
- */
+/** Structural shape of Inertia's `useForm` return that the adapter needs. */
 export interface InertiaFormLike<TData extends Record<string, unknown> = Record<string, unknown>> {
     /** Current form values (server-driven state). */
     data: TData;
@@ -65,11 +61,7 @@ export declare function useInertiaField<TData extends Record<string, unknown>>(f
         };
     }) => void;
 };
-/**
- * Structural shape of Inertia's `<Link>` that the Sidebar adapter needs. Duck-typed on purpose —
- * `@godxjp/ui` keeps ZERO dependency on `@inertiajs/react`; the real `Link` satisfies this shape,
- * so a consumer passes it directly with no import from this package.
- */
+/** Structural shape of Inertia's `<Link>` that the Sidebar adapter needs. */
 export interface InertiaLinkLike {
     href: string;
     className?: string;

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

@@ -1,29 +1,18 @@
 /** 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";
+export declare const controlMultilineClass = "ui-control-multiline aria-invalid:border-destructive w-full rounded-[var(--control-radius)] border-input bg-background ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none";
 /**
- * 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.
+ * 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.
  */
-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";
+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";
 /**
- * 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
- * this — an open popover shows only a border change (no ring), inconsistent with a focused Input.
- * Opacity `/50` matches the real focus ring used by Button / Input / Select. Apply alongside
- * `focus-visible:ring-*` on any trigger that toggles `data-state="open"`.
+ * 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 this —
+ * an open popover shows only a border change (no ring), inconsistent with a focused Input.
  */
-export declare const controlOpenRingClass = "data-[state=open]:border-ring data-[state=open]:ring-ring/50 data-[state=open]:ring-[3px]";
-export declare 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";
+export declare const controlOpenRingClass = "ui-control-trigger";
+export declare const controlTriggerClass = "ui-control ui-control-trigger flex items-center justify-between gap-2 whitespace-nowrap rounded-[var(--control-radius)] border-input bg-background transition-[color,box-shadow] focus-visible:outline-none [&>span]:line-clamp-1";
 export declare const controlIconClass = "size-[length:var(--control-height)] shrink-0";
 export declare const controlIconSmClass = "size-[calc(var(--control-height)-0.5rem)] shrink-0";
 /** Leading/affix icon inside an input row (search, command) — sized to `--control-icon-size`. */

package/dist/lib/control-styles.js

@@ -1,8 +1,7 @@
-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 controlMultilineClass = "ui-control-multiline aria-invalid:border-destructive w-full rounded-[var(--control-radius)] border-input bg-background ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none";
+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";
+const controlOpenRingClass = "ui-control-trigger";
+const controlTriggerClass = "ui-control ui-control-trigger flex items-center justify-between gap-2 whitespace-nowrap rounded-[var(--control-radius)] border-input bg-background transition-[color,box-shadow] focus-visible:outline-none [&>span]:line-clamp-1";
 const controlIconClass = "size-[length:var(--control-height)] shrink-0";
 const controlIconSmClass = "size-[calc(var(--control-height)-0.5rem)] shrink-0";
 const controlIconLeadingClass = "size-[length:var(--control-icon-size)] shrink-0";
@@ -17,7 +16,6 @@ const toneDestructiveClass = "border-destructive/30 bg-destructive/10 text-error
 const toneMutedClass = "border-border bg-muted text-muted-foreground";
 const toneNeutralClass = "border-border bg-muted text-muted-foreground";
 export {
-  controlFieldClass,
   controlIconClass,
   controlIconLeadingClass,
   controlIconSmClass,

package/dist/lib/datetime/format-date.d.ts

@@ -1,10 +1,7 @@
 import { type FormatDatetimeOptions } from "./format.js";
 import { type FormatDateKind } from "./detect.js";
 export type FormatDateOptions = FormatDatetimeOptions & {
-    /**
-     * Output preset. Default `auto` detects ISO date / HH:mm / instant.
-     * Locale, timezone, and 12h|24h fall back to AppProvider when omitted.
-     */
+    /** Output preset. Default `auto` detects ISO date / HH:mm / instant. */
     kind?: FormatDateKind;
     /** Treat `Date` as calendar pick (react-day-picker) — not an instant. */
     calendar?: boolean;

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

@@ -3,16 +3,7 @@ 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
  * these props and forwards them to its **semantic focus target** — the real `<input>` / combobox /
- * trigger the user tabs to, never a presentational wrapper `<div>`. Without this forwarding the
- * visible label / helper / error rendered by FormField is silently disconnected from the control
- * for assistive technology (issue #164).
- *
- * These are the standard WAI-ARIA field relationships:
- * - `aria-labelledby` — points at the FormField label → the control's accessible **name**.
- * - `aria-describedby` — points at helper text → the control's **description**.
- * - `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).
+ * trigger the user tabs to, never a presentational wrapper `<div>`.
  */
 export interface FieldA11yProps {
     "aria-label"?: string;
@@ -21,6 +12,7 @@ export interface FieldA11yProps {
     "aria-errormessage"?: string;
     "aria-invalid"?: React.AriaAttributes["aria-invalid"];
     "aria-required"?: React.AriaAttributes["aria-required"];
+    "data-field"?: string;
 }
 /**
  * Merge one or more space-separated id-reference lists (`aria-describedby`, `aria-labelledby`,
@@ -32,18 +24,12 @@ export declare function mergeAriaIds(...values: Array<string | undefined>): stri
  * Extract ONLY the defined field-a11y attributes from a props bag, ready to spread onto a
  * component's semantic focus target. Undefined entries are dropped so a forwarded contract never
  * clobbers a control's own intrinsic `aria-label` / `aria-invalid`.
- *
- * ```tsx
- * const fieldA11y = pickFieldA11y(props);
- * return <input {...fieldA11y} />; // the real focus target owns the relationship
- * ```
  */
 export declare function pickFieldA11y(props: FieldA11yProps): FieldA11yProps;
 /**
  * The inverse of {@link pickFieldA11y}: everything EXCEPT the field-a11y attributes. Use it when a
  * component must route the contract somewhere other than the element the remaining props land on —
- * e.g. `Select`'s compound API, where the props bag belongs to `SelectPrimitive.Root` (a
- * context-only component that renders no DOM) while the accessible name has to reach the trigger.
+ * e.g.
  */
 export declare function omitFieldA11y<T extends FieldA11yProps>(props: T): Omit<T, keyof FieldA11yProps>;
 /**
@@ -54,19 +40,10 @@ export declare function omitFieldA11y<T extends FieldA11yProps>(props: T): Omit<
  */
 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). */
@@ -81,21 +58,39 @@ 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">;
+/**
+ * `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.
+ */
+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** → `{}`.
+ */
+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
- * pickers / Transfer shuttle.
- *
- * Per WAI-ARIA 1.2 only `aria-labelledby` and `aria-describedby` are globally allowed on
- * `role="group"`; `aria-invalid` / `aria-errormessage` / `aria-required` are widget-only and would
- * be an invalid-ARIA violation on a group. So the validation message id (`aria-errormessage`) is
- * **folded into `aria-describedby`** — the error text is still announced as part of the group's
- * description, and FormField's `role="alert"` error node announces it live regardless.
- *
- * `role="radiogroup"` IS a widget and supports the full validation set — those groups use
- * {@link pickFieldA11y} directly, not this helper.
+ * pickers / Transfer shuttle. Per WAI-ARIA 1.2 only `aria-labelledby` and `aria-describedby` are
+ * globally allowed on `role="group"`; `aria-invalid` / `aria-errormessage` / `aria-required` are
+ * widget-only and would be an invalid-ARIA violation on a group.
  */
 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,32 @@ 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
+    ...props["data-field"] !== void 0 ? { "data-field": props["data-field"] } : {}
   };
 }
 export {
+  FieldIdentityContext,
   FieldNameContext,
   mergeAriaIds,
   omitFieldA11y,
   pickFieldA11y,
   pickGroupFieldA11y,
   resolveFieldA11y,
+  useFieldIdentity,
   useFieldNameFallback
 };

package/dist/lib/format.d.ts

@@ -1,15 +1,11 @@
 /**
- * Bytes → size with conventional binary units (B/KB/MB/GB) and a locale-correct number,
- * e.g. "2.0 KB" (en) / "2,0 KB" (vi). The numeric part is formatted via `Intl.NumberFormat`
- * (locale decimal/grouping separators — no hardcoded "."); an optional `locale` overrides the
- * module-synced active locale.
+ * Bytes → size with conventional binary units (B/KB/MB/GB) and a locale-correct number, e.g. "2.0
+ * KB" (en) / "2,0 KB" (vi).
  */
 export declare function formatBytes(n: number | null | undefined, locale?: string): string;
 /**
- * ISO 4217 minor units → locale-formatted currency, e.g. (1995, "USD") → "$19.95" (en) /
- * "19,95 $" (vi). The active locale (or an explicit `locale`) drives grouping/symbol placement;
- * the currency's minor-unit scale comes from CLDR via `resolvedOptions().maximumFractionDigits`
- * — no hand-maintained zero-decimal list.
+ * ISO 4217 minor units → locale-formatted currency, e.g. (1995, "USD") → "$19.95" (en) / "19,95 $"
+ * (vi).
  */
 export declare function formatCurrency(amountMinor: number | null | undefined, currency: string, locale?: string): string;
 /** UUIDv7 / UUIDv4 → first 8 chars + ellipsis. Pair with a Tooltip showing full. */

package/dist/lib/hooks.d.ts

@@ -12,18 +12,12 @@ export declare function useDebouncedValue<T>(value: T, delay?: number): T;
  */
 export declare function useTimeoutFlag(signal: unknown, ms?: number): boolean;
 /**
- * Controlled-ness latch for `value`/`defaultValue`/`onValueChange` controls
- * whose empty state is `undefined` (pickers carrying `Date`/`DateRange`).
- *
- * A control counts as controlled once a DEFINED `value` has EVER been passed:
- * - mounted with a defined `value` → controlled, and a later `value={undefined}`
- *   stays controlled-EMPTY (not mistaken for uncontrolled);
- * - mounted with `value={undefined}` (an empty form that later restores a
- *   saved value) → uncontrolled until the first defined value arrives, then
- *   PROMOTES to controlled for good.
- *
- * Fixing controlled-ness at mount (the previous behaviour) silently ignored
- * every later controlled value in the second case.
+ * Controlled-ness latch for `value`/`defaultValue`/`onValueChange` controls whose empty state is
+ * `undefined` (pickers carrying `Date`/`DateRange`). A control counts as controlled once a DEFINED
+ * `value` has EVER been passed: - mounted with a defined `value` → controlled, and a later
+ * `value={undefined}` stays controlled-EMPTY (not mistaken for uncontrolled); - mounted with
+ * `value={undefined}` (an empty form that later restores a saved value) → uncontrolled until the
+ * first defined value arrives, then PROMOTES to controlled for good.
  */
 export declare function useControlledLatch(valueIsDefined: boolean): boolean;
 export declare function useMediaQuery(query: string): boolean;

package/dist/lib/permission-grid.d.ts

@@ -1,22 +1,7 @@
 /**
- * permission-grid — pure, render-neutral helpers for RBAC role × permission
- * matrices.
- *
- * A permission matrix maps a set of PERMISSION rows against a set of ROLE
- * columns; each (role, permission) pair is either granted or not. A "permission
- * matrix" is NOT a framework component — it is a COMPOSITION of `Table`/
- * `DataTable` + `Badge` + tokens (see `docs/COMPOSITION-VS-COMPONENT.md`, Gate 0:
- * fails C2/C3/C7). What it DOES need is a single, tested source of truth for the
- * non-trivial data logic every consumer would otherwise re-derive: grant lookup,
- * the per-permission diff between two roles (compare mode), and the row set that
- * survives a "differences only" (差分のみ) filter.
- *
- * These functions are framework-neutral (no React) and locale-neutral (no
- * strings) so the showcase — and any RBAC admin — composes UI on top of them.
- *
- * Grants are modelled as a flat `Set` of composite keys for O(1) membership,
- * which mirrors how an authz decision cache (`role:permission` tuples) is
- * typically held in memory.
+ * permission-grid — pure, render-neutral helpers for RBAC role × permission matrices. A permission
+ * matrix maps a set of PERMISSION rows against a set of ROLE columns; each (role, permission) pair
+ * is either granted or not.
  */
 /** Any object addressable by a stable string `id` (a role or a permission). */
 export interface GridEntity {

package/dist/lib/query-error.d.ts

@@ -8,9 +8,9 @@ export type QueryErrorInfo = {
     retryable: boolean;
 };
 /**
- * Classify a query/API error into a recovery-relevant category. Status codes win; message
- * keywords are the fallback for transport layers that only surface a string (e.g. an SDK that
- * throws `new Error("Access token invalid")` with no status). Never exposes the raw message.
+ * Classify a query/API error into a recovery-relevant category. Status codes win; message keywords
+ * are the fallback for transport layers that only surface a string (e.g. an SDK that throws `new
+ * Error("Access token invalid")` with no status).
  */
 export declare function classifyQueryError(error: unknown): QueryErrorInfo;
 /** `true` when repeating the same request can plausibly resolve the error. */

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

@@ -15,23 +15,20 @@ export type AppProviderProp = {
     defaultTimezone?: AppTimezoneDefault;
     /** Backend/system timezone when `defaultTimezone` is `system`. */
     systemTimezone?: AppTimezone;
-    /** Initial clock format. `"locale"` derives from `defaultLocale`. Default: `"locale"`. */
+    /** Initial clock format. `"locale"` derives from `defaultLocale`. */
     defaultTimeFormat?: AppTimeFormat | "locale";
-    /** Initial date display format. `"locale"` derives from `defaultLocale`. Default: `"locale"`. */
+    /** Initial date display format. `"locale"` derives from `defaultLocale`. */
     defaultDateFormat?: AppDateFormat | "locale";
     /**
-     * IANA ids offered by the timezone-picker recipe (`useAppContext().timezoneOptions`).
-     * Omit for the full IANA list; set to restrict (e.g. `APP_TIMEZONE_PRESET`).
+     * IANA ids offered by the timezone-picker recipe (`useAppContext().timezoneOptions`). Omit for
+     * the full IANA list; set to restrict (e.g.
      */
     timezoneOptions?: readonly AppTimezone[];
     /** localStorage key. Default: `godxjp.app`. */
     storageKey?: string;
     /** Persist user choices. Default: true. */
     persist?: boolean;
-    /**
-     * Initial light/dark theme — written to `<html data-theme>`. Default: `"light"`.
-     * (The legacy `.dark` class still works as an equal alias.)
-     */
+    /** Initial light/dark theme — written to `<html data-theme>`. Default: `"light"`. */
     theme?: AppTheme;
     /**
      * Initial brand palette preset — written to `<html data-brand>`. OPT-IN: omit
@@ -43,12 +40,16 @@ export type AppProviderProp = {
     /** Initial base type size — written to `<html data-font-size>`. Default: `"default"`. */
     fontSize?: AppFontSize;
     /**
-     * Continuous global size multiplier — sets inline `--scaling` on `<html>`. Every
-     * size token (spacing, control/table/checkbox/switch heights, radius) rescales in
-     * proportion (Radix-style). `null` (default) defers to the `density` preset; a
-     * number (e.g. `0.95`) overrides it. Type is a separate axis — not scaled.
+     * Continuous global size multiplier — sets inline `--scaling` on `<html>`. Every size token
+     * (spacing, control/table/checkbox/switch heights, radius) rescales in proportion (Radix-style).
      */
     scaling?: number | null;
+    /**
+     * Emit a native `name` on every control a `FormField` wraps, taken from the field's key (`field`
+     * → `name` → `id`). `data-field` is inert metadata and is always emitted; `name` is NOT — it
+     * changes what a native `<form>` submit sends.
+     */
+    emitFieldNames?: boolean;
     onLocaleChange?: (locale: AppLocale) => void;
     onTimezoneChange?: (timezone: AppTimezone) => void;
     onTimeFormatChange?: (timeFormat: AppTimeFormat) => void;
@@ -70,24 +71,13 @@ export type AppSettingPickerProp = {
     kind: AppSettingKind;
     /**
      * Trigger presentation. `"labeled"` shows the leading icon + the selected value in a control
-     * sized to the setting. `"icon"` renders a supported square, icon-only topbar trigger (e.g. a
-     * globe language switcher): it structurally drops the value text and the picker's owned width —
-     * no descendant-selector CSS overrides needed — while always keeping the localized `aria-label`,
-     * so an icon-only trigger can never ship without an accessible name. `"inline"` renders the
-     * selected value as a compact text trigger for legal/auth footers without a field-like box.
-     *
-     * Default is kind-dependent: `kind="locale"` defaults to `"icon"` (its product contract is the
-     * compact language switcher); every other kind defaults to `"labeled"`. Override explicitly for
-     * e.g. a labeled locale row inside a settings form (`appearance="labeled"`).
+     * sized to the setting.
      */
     appearance?: AppSettingPickerAppearanceProp;
     /**
-     * Compact presentation (gh#217) — re-tiers the trigger box to `--control-height-sm` and drops the
-     * picker's owned per-kind width so a LABELLED trigger hugs its value. Use it for an auth/legal
-     * footer locale switch (`kind="locale" appearance="labeled" compact`), where the square icon-only
-     * default reads as a stray button and the full labelled trigger is too tall. All geometry is
-     * tokenized (`--app-setting-picker-compact-*`). No effect on `appearance="inline"`, which is
-     * already chrome-less. Default `false`.
+     * Use it for an auth/legal footer locale switch (`kind="locale" appearance="labeled" compact`),
+     * where the square icon-only default reads as a stray button and the full labelled trigger is
+     * too tall. All geometry is tokenized (`--app-setting-picker-compact-*`).
      */
     compact?: boolean;
     className?: ClassNameProp;
@@ -117,6 +107,8 @@ export type AppContextValue = {
     density: AppDensity;
     fontSize: AppFontSize;
     scaling: number | null;
+    /** Default `false`. */
+    emitFieldNames: boolean;
     setLocale: (locale: AppLocale) => void;
     setTimezone: (timezone: AppTimezone) => void;
     setTimeFormat: (timeFormat: AppTimeFormat) => void;