@godxjp/ui 19.2.0 → 19.4.0

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

@@ -5,8 +5,7 @@ import { ChevronDown, ChevronRight, ChevronsUpDown, X } from "lucide-react";
 import { useTranslation } from "../../i18n/use-translation.js";
 import { cn } from "../../lib/utils.js";
 import { pickFieldA11y, useFieldIdentity } from "../../lib/field-a11y.js";
-import { controlOpenRingClass } from "../../lib/control-styles.js";
-import { Button } from "../general/button.js";
+import { controlTriggerClass } from "../../lib/control-styles.js";
 import { Popover, PopoverContent, PopoverTrigger } from "../data-display/popover.js";
 import { ScrollArea } from "../data-display/scroll-area.js";
 import { Checkbox } from "./checkbox.js";
@@ -177,12 +176,11 @@ function TreeSelectRoot({
   return /* @__PURE__ */ jsxs(Popover, { open, onOpenChange: setOpen, children: [
     /* @__PURE__ */ jsxs("div", { className: "relative", children: [
       /* @__PURE__ */ jsx(PopoverTrigger, { asChild: true, children: /* @__PURE__ */ jsxs(
-        Button,
+        "button",
         {
           id,
           "data-field": fieldA11y["data-field"] ?? identity["data-field"],
           type: "button",
-          variant: "outline",
           role: "combobox",
           "aria-expanded": open,
           "aria-haspopup": "tree",
@@ -190,9 +188,9 @@ function TreeSelectRoot({
           ...fieldA11y,
           disabled,
           className: cn(
-            "w-full justify-between font-normal",
+            controlTriggerClass,
+            "w-full justify-between",
             allowClear && displayKeys.length > 0 && !disabled && "ui-tree-select-trigger-affixed",
-            controlOpenRingClass,
             !displayKeys.length && "text-muted-foreground",
             className
           ),

package/dist/components/general/inert-background.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Call from an overlay's content wrapper (the always-mounted portal wrapper, not the portalled
+ * content itself). Idempotent and refcounted: one observer serves every overlay on the page.
+ */
+export declare function useInertHiddenBackground(): void;

package/dist/components/general/inert-background.js

@@ -0,0 +1,48 @@
+"use client";
+import * as React from "react";
+const TABBABLE = 'a[href], area[href], button, input, select, textarea, iframe, object, embed, details, audio[controls], video[controls], [contenteditable="true"], [tabindex]:not([tabindex^="-"])';
+const owned = /* @__PURE__ */ new Set();
+let observer = null;
+let mounted = 0;
+function sync() {
+  for (const el of document.querySelectorAll("[data-aria-hidden]")) {
+    if (owned.has(el) || el.hasAttribute("inert")) continue;
+    if (el.querySelector(TABBABLE)) {
+      el.setAttribute("inert", "");
+      owned.add(el);
+    }
+  }
+  for (const el of [...owned]) {
+    if (el.isConnected && el.hasAttribute("data-aria-hidden")) continue;
+    el.removeAttribute("inert");
+    owned.delete(el);
+  }
+}
+function release() {
+  for (const el of owned) el.removeAttribute("inert");
+  owned.clear();
+}
+function useInertHiddenBackground() {
+  React.useEffect(() => {
+    mounted += 1;
+    if (!observer) {
+      observer = new MutationObserver(sync);
+      observer.observe(document.body, {
+        subtree: true,
+        attributes: true,
+        attributeFilter: ["data-aria-hidden"]
+      });
+    }
+    sync();
+    return () => {
+      mounted -= 1;
+      if (mounted > 0) return;
+      observer?.disconnect();
+      observer = null;
+      release();
+    };
+  }, []);
+}
+export {
+  useInertHiddenBackground
+};

package/dist/components/layout/auth-shell.d.ts

@@ -3,6 +3,8 @@ export type { AuthShellProp, AuthShellProp as AuthShellProps, } from "../../prop
 /**
  * AuthShell — centred auth/login page shell (login · mfa · passkey · device · reset). A top brand
  * bar (banner), a centred `main` that holds the auth `Card`, and an optional footer (contentinfo),
- * over a `min-h-dvh` surface.
+ * over a `min-h-dvh` surface. The banner also carries page-level `actions` at its inline end (a
+ * locale picker, a theme toggle), and `measure="wide"` opens the content slot to the split login
+ * (a brand panel beside the card) that used to have no shell of its own.
  */
-export declare function AuthShell({ brand, footer, children, variant, preset, density, className, }: AuthShellProp): import("react").JSX.Element;
+export declare function AuthShell({ brand, actions, footer, children, variant, preset, measure, density, className, }: AuthShellProp): import("react").JSX.Element;

package/dist/components/layout/auth-shell.js

@@ -4,10 +4,12 @@ import { useTranslation } from "../../i18n/use-translation.js";
 import { cn } from "../../lib/utils.js";
 function AuthShell({
   brand,
+  actions,
   footer,
   children,
   variant = "default",
   preset = "default",
+  measure = "default",
   density,
   className
 }) {
@@ -19,10 +21,14 @@ function AuthShell({
       "data-slot": "auth-shell",
       "data-variant": variant,
       "data-preset": preset === "default" ? void 0 : preset,
+      "data-measure": measure === "default" ? void 0 : measure,
       "data-density": resolvedDensity,
       className: cn("ui-auth-shell", className),
       children: [
-        brand !== void 0 && /* @__PURE__ */ jsx("header", { className: "ui-auth-shell-bar", "aria-label": t("layout.authShell.brandLabel"), children: brand }),
+        (brand !== void 0 || actions !== void 0) && /* @__PURE__ */ jsxs("header", { className: "ui-auth-shell-bar", "aria-label": t("layout.authShell.brandLabel"), children: [
+          brand,
+          actions !== void 0 && /* @__PURE__ */ jsx("div", { className: "ui-auth-shell-bar-actions", children: actions })
+        ] }),
         /* @__PURE__ */ jsx("main", { className: "ui-auth-shell-main", "aria-label": t("layout.authShell.mainLabel"), children: /* @__PURE__ */ jsx("div", { className: "ui-auth-shell-card", children }) }),
         footer !== void 0 && /* @__PURE__ */ jsx("footer", { className: "ui-auth-shell-footer", "aria-label": t("layout.authShell.footerLabel"), children: footer })
       ]

package/dist/components/layout/centered-shell.d.ts

@@ -5,7 +5,7 @@ export type { CenteredShellProp, CenteredShellProp as CenteredShellProps, } from
  * account / self-service, and standalone-settings shape. It fills the gap between the two existing
  * shells: - `AppShell` REQUIRES a sidebar — its padded topbar chrome (`.app-topbar`) is a grid
  * area beside the nav rail, so you cannot get a padded top bar without a rail. - `AuthShell` is
- * the UNAUTHENTICATED root (login/mfa/reset); it centres a narrow ~24rem card VERTICALLY and has
- * no top-right actions slot.
+ * the UNAUTHENTICATED root (login/mfa/reset); it centres its card VERTICALLY, so a page that
+ * scrolls its own content belongs here instead.
  */
 export declare function CenteredShell({ topbar, footer, children, width, align, preset, className, }: CenteredShellProp): import("react").JSX.Element;

package/dist/components/layout/flex.d.ts

@@ -1,3 +1,3 @@
 import type { FlexProp } from "../../props/components/layout.prop.js";
 export type { FlexAlignProp, FlexDirectionProp, FlexJustifyProp, FlexProp, FlexProp as FlexProps, } from "../../props/components/layout.prop.js";
-export declare function Flex({ direction, gap, align, justify, wrap, hideBelow, hideFrom, className, children, ...props }: FlexProp): import("react").JSX.Element;
+export declare function Flex({ as: Element, direction, gap, align, justify, wrap, hideBelow, hideFrom, className, children, ...props }: FlexProp): import("react").JSX.Element;

package/dist/components/layout/flex.js

@@ -4,6 +4,7 @@ import { mergeAriaIds } from "../../lib/field-a11y.js";
 import { cn } from "../../lib/utils.js";
 import { flexGapClass } from "../../lib/variants.js";
 function Flex({
+  as: Element = "div",
   direction = "row",
   gap = "md",
   align,
@@ -30,7 +31,7 @@ function Flex({
     };
   }
   return /* @__PURE__ */ jsx(
-    "div",
+    Element,
     {
       "data-direction": direction,
       "data-align": align,

package/dist/components/layout/index.d.ts

@@ -22,6 +22,9 @@ export { AuthFooter } from "./auth-footer.js";
 export type { AuthFooterProp, AuthFooterProps } from "./auth-footer.js";
 export { AuthStack } from "./auth-stack.js";
 export type { AuthStackProps } from "./auth-stack.js";
+export { MobileShell } from "./mobile-shell.js";
+export type { MobileShellProp, MobileShellProps } from "./mobile-shell.js";
+export type { MobileShellHeightProp } from "../../props/vocabulary/index.js";
 export { CenteredShell } from "./centered-shell.js";
 export type { CenteredShellProp, CenteredShellProps } from "./centered-shell.js";
 export type { CenteredShellWidthProp, CenteredShellAlignProp } from "../../props/vocabulary/index.js";

package/dist/components/layout/index.js

@@ -10,6 +10,7 @@ import { AccountChip } from "./account-chip.js";
 import { AuthAccountSummary } from "./auth-account-summary.js";
 import { AuthFooter } from "./auth-footer.js";
 import { AuthStack } from "./auth-stack.js";
+import { MobileShell } from "./mobile-shell.js";
 import { CenteredShell } from "./centered-shell.js";
 import { ErrorSurface } from "./error-surface.js";
 import { Breadcrumb } from "./breadcrumb.js";
@@ -38,6 +39,7 @@ export {
   Flex,
   LegalDocumentShell,
   MasterDetail,
+  MobileShell,
   OrgSwitcher,
   PageContainer,
   ResizableHandle,

package/dist/components/layout/mobile-shell.d.ts

@@ -0,0 +1,21 @@
+import type { MobileShellProp } from "../../props/components/layout.prop.js";
+export type { MobileShellProp, MobileShellProp as MobileShellProps, } from "../../props/components/layout.prop.js";
+/**
+ * MobileShell — the HANDHELD app shell (gh#354 §6): a status band, an app bar, ONE scroll region,
+ * a sticky action bar and a bottom tab bar, in that fixed order.
+ *
+ * The fourth root shell. The other three cannot express a phone app: `AppShell` REQUIRES a sidebar
+ * (its bar is a grid area beside the nav rail), `AuthShell` is the UNAUTHENTICATED root and centres
+ * a ~24rem card, and `CenteredShell` is a scrolling DOCUMENT — its `main` scrolls the page, which
+ * is precisely what a handheld app must not do.
+ *
+ * SOURCE ORDER IS THE LAYOUT. The bands are a flex column and nothing repositions them, so the DOM
+ * order and the reading order are the same order — the accessibility property AppShell has to buy
+ * back with grid areas. `actions` therefore comes before `tabBar` in the DOM as well as on screen.
+ *
+ * i18n: the three landmarks reuse the SHARED shell labels (`layout.appShell.headerLabel` /
+ * `.mainLabel` for the bar and the scroll region, `layout.sidebar.ariaLabel` for the tab bar, which
+ * IS the app's primary navigation). They are the same strings in all three locales, and a fourth
+ * identical copy under `layout.mobileShell.*` would be three files of duplication to keep in sync.
+ */
+export declare function MobileShell({ statusBar, header, children, actions, tabBar, height, className, }: MobileShellProp): import("react").JSX.Element;

package/dist/components/layout/mobile-shell.js

@@ -0,0 +1,43 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useTranslation } from "../../i18n/use-translation.js";
+import { cn } from "../../lib/utils.js";
+function MobileShell({
+  statusBar,
+  header,
+  children,
+  actions,
+  tabBar,
+  height = "viewport",
+  className
+}) {
+  const { t } = useTranslation();
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      "data-slot": "mobile-shell",
+      "data-height": height === "viewport" ? void 0 : height,
+      className: cn("ui-mobile-shell", className),
+      children: [
+        (statusBar !== void 0 || header !== void 0) && /* @__PURE__ */ jsxs("header", { className: "ui-mobile-shell-chrome", "aria-label": t("layout.appShell.headerLabel"), children: [
+          statusBar !== void 0 && /* @__PURE__ */ jsx("div", { className: "ui-mobile-shell-status", children: statusBar }),
+          header !== void 0 && /* @__PURE__ */ jsx("div", { className: "ui-mobile-shell-header", children: header })
+        ] }),
+        /* @__PURE__ */ jsx(
+          "main",
+          {
+            className: "ui-mobile-shell-main",
+            "aria-label": t("layout.appShell.mainLabel"),
+            tabIndex: 0,
+            children
+          }
+        ),
+        actions !== void 0 && /* @__PURE__ */ jsx("footer", { className: "ui-mobile-shell-actions", children: actions }),
+        tabBar !== void 0 && /* @__PURE__ */ jsx("nav", { className: "ui-mobile-shell-tabbar", "aria-label": t("layout.sidebar.ariaLabel"), children: tabBar })
+      ]
+    }
+  );
+}
+export {
+  MobileShell
+};

package/dist/components/layout/sidebar-link.d.ts

@@ -1,7 +1,7 @@
 import * as React from "react";
 import type { SidebarLinkComponentProp } from "../../props/components/layout.prop.js";
 /**
- * Adapt a framework router `Link` to {@link SidebarLinkComponentProp} (gh#213) — a dependency-free
+ * Adapt a framework router `Link` to {@link SidebarLinkComponentProp} — a dependency-free
  * factory, so `@godxjp/ui` still ships ZERO router/framework dependencies.
  *
  * It lives in its own module (imports only React + the prop types) so `@godxjp/ui/inertia` can build

package/dist/components/navigation/context-menu.js

@@ -4,20 +4,24 @@ import * as React from "react";
 import * as ContextMenuPrimitive from "@radix-ui/react-context-menu";
 import { Check, ChevronRight, Circle } from "lucide-react";
 import { cn } from "../../lib/utils.js";
+import { useInertHiddenBackground } from "../general/inert-background.js";
 const ContextMenu = ContextMenuPrimitive.Root;
 function ContextMenuTrigger(props) {
   return /* @__PURE__ */ jsx(ContextMenuPrimitive.Trigger, { "data-slot": "context-menu-trigger", ...props });
 }
 const ContextMenuPortal = ContextMenuPrimitive.Portal;
-const ContextMenuContent = React.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx(ContextMenuPrimitive.Portal, { children: /* @__PURE__ */ jsx(
-  ContextMenuPrimitive.Content,
-  {
-    ref,
-    "data-slot": "context-menu-content",
-    className: cn("ui-context-menu-content", className),
-    ...props
-  }
-) }));
+const ContextMenuContent = React.forwardRef(({ className, ...props }, ref) => {
+  useInertHiddenBackground();
+  return /* @__PURE__ */ jsx(ContextMenuPrimitive.Portal, { children: /* @__PURE__ */ jsx(
+    ContextMenuPrimitive.Content,
+    {
+      ref,
+      "data-slot": "context-menu-content",
+      className: cn("ui-context-menu-content", className),
+      ...props
+    }
+  ) });
+});
 ContextMenuContent.displayName = ContextMenuPrimitive.Content.displayName;
 const ContextMenuItem = React.forwardRef(({ className, inset, variant = "default", ...props }, ref) => /* @__PURE__ */ jsx(
   ContextMenuPrimitive.Item,

package/dist/components/navigation/dropdown-menu.js

@@ -4,6 +4,7 @@ import * as React from "react";
 import * as DropdownMenuPrimitive from "@radix-ui/react-dropdown-menu";
 import { Check, ChevronRight } from "lucide-react";
 import { cn } from "../../lib/utils.js";
+import { useInertHiddenBackground } from "../general/inert-background.js";
 function DropdownMenu(props) {
   return /* @__PURE__ */ jsx(DropdownMenuPrimitive.Root, { "data-slot": "dropdown-menu", ...props });
 }
@@ -22,19 +23,22 @@ function DropdownMenuRadioGroup(props) {
 function DropdownMenuSub(props) {
   return /* @__PURE__ */ jsx(DropdownMenuPrimitive.Sub, { "data-slot": "dropdown-menu-sub", ...props });
 }
-const DropdownMenuContent = React.forwardRef(({ className, sideOffset = 4, ...props }, ref) => /* @__PURE__ */ jsx(DropdownMenuPortal, { children: /* @__PURE__ */ jsx(
-  DropdownMenuPrimitive.Content,
-  {
-    ref,
-    "data-slot": "dropdown-menu-content",
-    sideOffset,
-    className: cn(
-      "ui-dropdown-menu-content data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 origin-[var(--radix-dropdown-menu-content-transform-origin)]",
-      className
-    ),
-    ...props
-  }
-) }));
+const DropdownMenuContent = React.forwardRef(({ className, sideOffset = 4, ...props }, ref) => {
+  useInertHiddenBackground();
+  return /* @__PURE__ */ jsx(DropdownMenuPortal, { children: /* @__PURE__ */ jsx(
+    DropdownMenuPrimitive.Content,
+    {
+      ref,
+      "data-slot": "dropdown-menu-content",
+      sideOffset,
+      className: cn(
+        "ui-dropdown-menu-content data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 origin-[var(--radix-dropdown-menu-content-transform-origin)]",
+        className
+      ),
+      ...props
+    }
+  ) });
+});
 DropdownMenuContent.displayName = DropdownMenuPrimitive.Content.displayName;
 const DropdownMenuItem = React.forwardRef(({ className, inset, variant = "default", ...props }, ref) => /* @__PURE__ */ jsx(
   DropdownMenuPrimitive.Item,

package/dist/inertia/index.d.ts

@@ -68,7 +68,7 @@ export interface InertiaLinkLike {
     children?: ReactNode;
 }
 /**
- * Bind Inertia's `<Link>` as the Sidebar's row element (gh#213).
+ * Bind Inertia's `<Link>` as the Sidebar's row element.
  *
  * The LIBRARY still composes every row — the 16px icon slot, the label, the badge, `data-active` /
  * `aria-current`, the icon-only collapsed rail and its tooltip name — and hands it to the link as

package/dist/lib/variants.d.ts

@@ -3,10 +3,10 @@ import type { GapProp, PageContainerVariantProp, PageDensityProp } from "../prop
 export type Density = PageDensityProp;
 export type StackGap = GapProp;
 export type FlexGap = GapProp;
-export type InlineGap = Exclude<GapProp, "xl">;
+export type InlineGap = Exclude<GapProp, "xl" | "none">;
 export type PageContainerVariant = PageContainerVariantProp;
 export declare const densityClass: Record<PageDensityProp, string>;
 export declare const pageContainerVariantClass: Record<PageContainerVariantProp, string | undefined>;
-export declare const stackGapClass: Record<GapProp, string>;
-export declare const inlineGapClass: Record<Exclude<GapProp, "xl">, string>;
+export declare const stackGapClass: Record<Exclude<GapProp, "none">, string>;
+export declare const inlineGapClass: Record<InlineGap, string>;
 export declare const flexGapClass: Record<GapProp, string>;

package/dist/lib/variants.js

@@ -23,6 +23,7 @@ const inlineGapClass = {
   lg: "ui-inline-lg"
 };
 const flexGapClass = {
+  none: "ui-flex-gap-none",
   xs: "ui-flex-gap-xs",
   sm: "ui-flex-gap-sm",
   md: "ui-flex-gap-md",

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

@@ -137,9 +137,22 @@ export type AvatarPresenceProp = "online" | "away" | "busy" | "offline";
 export type AvatarAppearanceProp = "default" | "tinted";
 /** @see Badge */
 export type BadgeProp = {
+    /**
+     * Render element — `div` (default) or `span` when the chip sits in a phrasing context where a
+     * `<div>` is invalid HTML (inside a `<button>` rendered by TabsTrigger/PopoverTrigger/Button,
+     * a `<label>`, a `<p>`). Swaps the tag only (gh#354).
+     */
+    as?: "div" | "span";
     variant?: "default" | "secondary" | "outline";
     /** Status tones plus a brand `primary` tone (soft brand pill); solid brand = `variant="default"`. */
     tone?: ToneProp | "primary";
+    /**
+     * The entity's OWN colour (a status, an issue type, a tag) as a CSS colour —
+     * DATA, not a semantic tone. Washed into `--badge-tint-surface` rather than
+     * filled, because no foreground clears WCAG AA against every colour a picker
+     * can produce. Wins over `tone` and over `variant`'s fill.
+     */
+    color?: string;
     status?: string;
     icon?: React.ComponentType<{
         className?: string;
@@ -353,3 +366,62 @@ export type ScrollAreaProp = {
      */
     onAnchoredChange?: (anchored: boolean) => void;
 };
+/**
+ * @see TimelineGrid — one COLUMN of the grid (a day, a room, a machine). The label names the
+ * column visually AND names the column's event list for assistive technology.
+ */
+export type TimelineGridColumnProp = {
+    /** Stable column id — the `columnId` an event points at. */
+    id: string;
+    /** Column head. Also the accessible name of that column's event list, so keep it text. */
+    label: LabelProp;
+    /** Secondary line under the head (a date, a capacity, a room number). */
+    description?: DescriptionProp;
+    /** Marks the column as "now" (today's column): it carries the tint and hosts the `now` marker. */
+    current?: boolean;
+};
+/**
+ * @see TimelineGrid — one event BLOCK. `start`/`end` are clock times in the column's own day,
+ * `"HH:MM"` 24-hour (`"24:00"` = end of day). An `end` at or before `start` continues into the
+ * next day (22:00–06:00), and the block is drawn to the end of the window and marked clipped.
+ */
+export type TimelineGridEventProp = {
+    /** Stable event id — the React key, and the `data-event-id` on the block. */
+    id: string;
+    /** Id of the column this event belongs to. An event pointing at no column is not drawn. */
+    columnId: string;
+    /** Start clock time, `"HH:MM"`. */
+    start: string;
+    /** End clock time, `"HH:MM"`. At or before `start` = continues into the next day. */
+    end: string;
+    /** Block title. The block also renders the time range as text, so the range is never colour or position alone. */
+    title: TitleProp;
+    /** Secondary line inside the block (who is on the shift, a room, a customer). */
+    description?: DescriptionProp;
+    /** The record's own colour, washed exactly like `Badge color` — decorative, never the only signal. */
+    color?: string;
+};
+/** @see TimelineGrid */
+export type TimelineGridProp = {
+    /**
+     * Accessible name of the grid. Required, and a plain `string`: the grid is a focusable scroll
+     * region, so its name has to survive as an `aria-label`.
+     */
+    label: Extract<LabelProp, string>;
+    /** Columns in render order. */
+    columns: readonly TimelineGridColumnProp[];
+    /** Events in any order; the grid sorts each column by start time and lays overlaps out side by side. */
+    events: readonly TimelineGridEventProp[];
+    /** First clock time on the axis, `"HH:MM"`. Defaults to the earliest event, on the hour. */
+    start?: string;
+    /** Last clock time on the axis, `"HH:MM"`. Defaults to the latest event, on the hour. */
+    end?: string;
+    /** Hours between hour rules and axis labels. Default `1`. */
+    interval?: number;
+    /** Current clock time, `"HH:MM"`. Draws the now marker in the columns marked `current`. */
+    now?: string;
+    /** Block click handler. Its PRESENCE turns every block into a real `button`. */
+    onEventSelect?: (event: TimelineGridEventProp) => void;
+    className?: ClassNameProp;
+    id?: IdProp;
+};

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

@@ -106,7 +106,7 @@ export type FormProp = React.FormHTMLAttributes<HTMLFormElement> & {
     className?: ClassNameProp;
 };
 /**
- * @see FormField — exactly one of `children` (an interactive control) or `staticText` (gh#294):
+ * @see FormField — exactly one of `children` (an interactive control) or `staticText`:
  * a read-only VALUE row inside the same Form, styled to match `Descriptions.Item`'s value
  * typography (`text-sm break-all`) byte-for-byte. This is the "mixed read-only + editable fields
  * on one form" case (an immutable name/email row above an editable role Select, for example) —