@godxjp/ui 28.5.0 → 28.7.0

package/dist/components/data-display/data-table.d.ts

@@ -1,6 +1,6 @@
 import * as React from "react";
 import { flexRender, type ColumnVisibilityState, type OnChangeFn, type PaginationState } from "@tanstack/react-table";
-import type { BreakpointProp, ColumnDefProp, DensityProp, OnColumnFilterChangeProp, OnRowProp, RowToneProp, SortDirectionProp, SortStateProp, TableExpandableProp, TablePaginationProp, TablePresetProp, TableRowSelectionProp, TableScrollProp, TableStickyProp, TableSummaryProp } from "../../props/vocabulary/index.js";
+import type { BreakpointProp, ColumnDefProp, DensityProp, LabelProp, OnColumnFilterChangeProp, OnRowProp, RowToneProp, SortDirectionProp, SortStateProp, TableExpandableProp, TablePaginationProp, TablePresetProp, TableRowSelectionProp, TableScrollProp, TableStickyProp, TableSummaryProp } from "../../props/vocabulary/index.js";
 export type Density = DensityProp;
 /**
  * Lean column definition — the simple, common-case column API. `render` shapes a cell; `sortable`
@@ -93,6 +93,14 @@ interface DataTableProps<T> {
     preset?: TablePresetProp;
     /** Default `"sm"`. Ignored while `preset` is `"default"`. */
     collapseBelow?: BreakpointProp;
+    /**
+     * Accessible name for the horizontal-scroll REGION (the `tabindex="0"` wrapper a keyboard user
+     * lands on), not for the `<table>`. Optional: left out, the region takes the localized
+     * `dataTable.scrollRegion` default, so no consumer has to invent a name for every list. The
+     * region is announced only while it HAS overflow to reach. Same contract as `Table label`.
+     * (gh#817)
+     */
+    label?: LabelProp;
     /**
      * Per-row className for state-based row tinting (e.g. flag an invalid or empty record). Returned
      * classes are appended last, so they win over the built-in hover/selected fills.
@@ -146,7 +154,7 @@ interface DataTableProps<T> {
     className?: string;
     children?: React.ReactNode;
 }
-export declare function DataTable<T>({ data, columns, getRowId, getRowLabel, selectable, selected: controlledSelected, onSelectChange, onRowClick, density: controlledDensity, onDensityChange, sort, onSortChange, globalFilter: controlledGlobalFilter, onGlobalFilterChange, pagination: paginationProp, onPaginationChange, rowCount, columnVisibility: controlledVisibility, onColumnVisibilityChange, manualSorting, manualFiltering, manualPagination, loading, empty, error, denied, onRetry, striped, hoverable, stickyHeader, preset, collapseBelow, rowClassName, rowTone, rowSelection, expandable, summary, scroll, sticky, onRow, bordered, showSorterTooltip, sortDirections, onFilterChange, className, children, }: DataTableProps<T>): React.JSX.Element;
+export declare function DataTable<T>({ data, columns, getRowId, getRowLabel, selectable, selected: controlledSelected, onSelectChange, onRowClick, density: controlledDensity, onDensityChange, sort, onSortChange, globalFilter: controlledGlobalFilter, onGlobalFilterChange, pagination: paginationProp, onPaginationChange, rowCount, columnVisibility: controlledVisibility, onColumnVisibilityChange, manualSorting, manualFiltering, manualPagination, loading, empty, error, denied, onRetry, striped, hoverable, stickyHeader, preset, collapseBelow, label, rowClassName, rowTone, rowSelection, expandable, summary, scroll, sticky, onRow, bordered, showSorterTooltip, sortDirections, onFilterChange, className, children, }: DataTableProps<T>): React.JSX.Element;
 export declare namespace DataTable {
     export var Toolbar: ({ children, className, }: {
         children?: React.ReactNode;

package/dist/components/data-display/data-table.js

@@ -65,9 +65,11 @@ import {
   TableCell,
   TableHead,
   TableHeader,
-  TableRow
+  TableRow,
+  scrollRegionLabel
 } from "../data-display/table.js";
 import { cn } from "../../lib/utils.js";
+import { useScrollsHorizontally } from "../../lib/hooks.js";
 import { densityClass } from "../../lib/variants.js";
 import {
   controlIconSmClass,
@@ -230,6 +232,7 @@ function DataTable({
   stickyHeader = true,
   preset = "default",
   collapseBelow = "sm",
+  label,
   rowClassName,
   rowTone,
   rowSelection,
@@ -450,6 +453,7 @@ function DataTable({
     stickyHeader: sticky === void 0 ? stickyHeader : sticky !== false,
     preset,
     collapseBelow,
+    label,
     rowClassName,
     rowTone,
     bordered,
@@ -774,6 +778,7 @@ DataTable.Content = function DataTableContent() {
     stickyHeader,
     preset,
     collapseBelow,
+    label,
     rowClassName,
     rowTone,
     bordered,
@@ -816,6 +821,7 @@ DataTable.Content = function DataTableContent() {
   }, [missingHeaderNames]);
   const selectLabelColumn = visibleColumns.find((col) => col.priority === "primary") ?? visibleColumns[0];
   const scrollRef = React.useRef(null);
+  const scrolls = useScrollsHorizontally(scrollRef, !presetAttr);
   const [hasOverflowEnd, setHasOverflowEnd] = React.useState(false);
   React.useEffect(() => {
     const el = scrollRef.current;
@@ -923,7 +929,7 @@ DataTable.Content = function DataTableContent() {
       "data-scroll-x": scroll?.x !== void 0 ? "" : void 0,
       "data-scroll-y": scroll?.y !== void 0 ? "" : void 0,
       "aria-busy": loading,
-      tabIndex: presetAttr ? void 0 : 0,
+      ...scrolls ? { role: "group", "aria-label": scrollRegionLabel(label, t), tabIndex: 0 } : {},
       children: /* @__PURE__ */ jsx(
         "div",
         {
@@ -936,6 +942,7 @@ DataTable.Content = function DataTableContent() {
             Table,
             {
               scrollable: preset !== "default",
+              label,
               preset,
               collapseBelow,
               bordered,
@@ -982,7 +989,7 @@ DataTable.Content = function DataTableContent() {
                         ) : null;
                         const headerEmpty = isEmptyHeader(col.header);
                         const headerContent = headerEmpty && col.ariaLabel ? /* @__PURE__ */ jsx("span", { className: "sr-only", children: col.ariaLabel }) : col.header;
-                        const label = /* @__PURE__ */ jsxs("span", { className: "ui-data-table-sort-label", children: [
+                        const label2 = /* @__PURE__ */ jsxs("span", { className: "ui-data-table-sort-label", children: [
                           headerContent,
                           sortIndicator
                         ] });
@@ -1000,7 +1007,7 @@ DataTable.Content = function DataTableContent() {
                             onClick: () => {
                               onHeaderClick(col);
                             },
-                            children: label
+                            children: label2
                           }
                         );
                         return /* @__PURE__ */ jsxs(
@@ -1027,7 +1034,7 @@ DataTable.Content = function DataTableContent() {
                               isSortable ? tooltipOn ? /* @__PURE__ */ jsxs(Tooltip, { children: [
                                 /* @__PURE__ */ jsx(TooltipTrigger, { asChild: true, children: sortButton }),
                                 /* @__PURE__ */ jsx(TooltipContent, { children: sortHint })
-                              ] }) : sortButton : label,
+                              ] }) : sortButton : label2,
                               col.filters ? /* @__PURE__ */ jsx(ColumnFilterMenu, { column: col }) : null
                             ]
                           },

package/dist/components/data-display/scroll-area.js

@@ -1,6 +1,8 @@
 "use client";
 import { jsx } from "react/jsx-runtime";
 import * as React from "react";
+import { useTranslation } from "../../i18n/use-translation.js";
+import { useScrollsOnAxis } from "../../lib/hooks.js";
 import { cn } from "../../lib/utils.js";
 const ANCHOR_OFFSET_TOKEN = "--scroll-area-anchor-offset";
 const ANCHOR_OFFSET_FALLBACK_PX = 48;
@@ -121,12 +123,16 @@ const ScrollArea = React.forwardRef(
     onAnchoredChange,
     orientation = "vertical",
     scrollbar = "auto",
+    label,
     ...props
   }, ref) => {
+    const { t } = useTranslation();
     const [viewport, setViewport] = React.useState(null);
+    const viewportHandle = React.useRef(null);
     const attachViewport = React.useCallback(
       (node) => {
         setViewport(node);
+        viewportHandle.current = node;
         for (const target of [ref, viewportRef]) {
           if (typeof target === "function") target(node);
           else if (target) target.current = node;
@@ -135,9 +141,17 @@ const ScrollArea = React.forwardRef(
       [ref, viewportRef]
     );
     useBottomAnchor(viewport, anchor === "bottom", anchorOffset, onAnchoredChange);
+    const scrolls = useScrollsOnAxis(viewportHandle, true, orientation);
+    const regionLabel = typeof label === "string" && label.trim() !== "" ? label : t("dataDisplay.scrollArea.region");
     return (
       // `tabIndex={0}` keeps the scroll viewport keyboard-reachable so overflowing content can be
-      // scrolled without a pointer (WCAG 2.1.1 / axe scrollable-region-focusable).
+      // scrolled without a pointer (WCAG 2.1.1 / axe scrollable-region-focusable). That stop must
+      // not be ANONYMOUS: unroled and unnamed it announces nothing, so it carries `role="group"`
+      // plus an accessible name (gh#821, the same defect gh#817 fixed in Table). `group`, not
+      // `region`: a named `region` IS a landmark, and a page with several scroll areas would ship
+      // several identically-named landmarks (axe `landmark-unique`). All three attributes come and
+      // go together with the overflow, because a focus stop that scrolls nothing is noise — and
+      // they precede `{...props}`, so a consumer's own `role`/`aria-label`/`tabIndex` still wins.
       //
       // NO `dir` IS STAMPED HERE, deliberately. Radix's Root called `useDirection(dir)`, which
       // falls back to the literal "ltr" and writes it onto the element — and a `dir` attribute is
@@ -150,12 +164,12 @@ const ScrollArea = React.forwardRef(
         "div",
         {
           ref: attachViewport,
-          tabIndex: 0,
           "data-slot": "scroll-area-viewport",
           "data-anchor": anchor,
           "data-orientation": orientation,
           "data-scrollbar": scrollbar,
           className: cn("ui-scroll-area", className),
+          ...scrolls ? { role: "group", "aria-label": regionLabel, tabIndex: 0 } : {},
           ...props,
           children: /* @__PURE__ */ jsx("div", { "data-slot": "scroll-area-content", className: "ui-scroll-area-content", children })
         }

package/dist/components/data-display/service-launcher-card.d.ts

@@ -1,3 +1,28 @@
+/**
+ * RECORDED EXCEPTION to the Framework-Component Test (gh#814).
+ *
+ * `docs/COMPOSITION-VS-COMPONENT.md` §2 says all seven criteria must PASS and any FAIL makes a
+ * thing a composition pattern. This file FAILS two of them, and stays anyway:
+ *
+ *   C2 (encapsulates reusable BEHAVIOR) — FAIL. It owns no state, no keyboard handling and no
+ *      focus management; its only ARIA is three static attributes. §2 calls this "pure static
+ *      layout/visual arrangement".
+ *   C3 (not expressible by composing primitives) — FAIL. Its own imports are the answer: this is
+ *      `Card` + `CardContent` + `Badge` + one Lucide glyph, and §2's heuristic — "could I build
+ *      this right now from existing primitives + token overrides?" — is answered yes.
+ *
+ * It is RETAINED because `src/components/layout/app-launcher.tsx` consumes it: it is an internal
+ * building block of a component that does pass the test, so deleting it is not on the table, and
+ * removing a public export is breaking. Keeping it public was the cheaper call.
+ *
+ * SO: a consumer reaching for a service tile should compose `Card` + `CardContent` + `Badge`
+ * themselves, which is what C3 says. Reach for `ServiceLauncherCard` only to match `AppLauncher`'s
+ * own tiles. Do not cite it as precedent for adding another static tile to `src/components/` —
+ * the test still means what it says, and this is the exception that was argued and written down
+ * rather than the rule.
+ *
+ * Ledger, options considered and the decision: gh#814.
+ */
 import * as React from "react";
 import type { LucideIcon } from "lucide-react";
 import type { HeadingLevelProp, ToneProp } from "../../props/vocabulary/index.js";

package/dist/components/data-display/table.d.ts

@@ -1,5 +1,5 @@
 import * as React from "react";
-import type { BreakpointProp, FlushProp, TableCellIndentProp, TableColumnPriorityProp, TablePresetProp, WidthProp } from "../../props/vocabulary/index.js";
+import type { BreakpointProp, FlushProp, LabelProp, TableCellIndentProp, TableColumnPriorityProp, TablePresetProp, WidthProp } from "../../props/vocabulary/index.js";
 export type TableProps = React.HTMLAttributes<HTMLTableElement> & {
     /**
      * Whether the Table owns its own horizontal-scroll region (default `true`). When `true` a table
@@ -58,7 +58,29 @@ export type TableProps = React.HTMLAttributes<HTMLTableElement> & {
     };
     /** Defaults to `"sm"` (40rem). Ignored while `preset` is `"default"`. */
     collapseBelow?: BreakpointProp;
+    /**
+     * Accessible name for the horizontal-scroll REGION — the `tabindex="0"` wrapper a keyboard user
+     * lands on to scroll a table wider than its container, NOT the `<table>` itself (pass `aria-label`
+     * for that; it reaches the table element as it always has).
+     *
+     * Optional on purpose. A consumer is never forced to invent a name for every table: left out, the
+     * region takes the localized `dataTable.scrollRegion` default ("Scrollable table"), which is what
+     * a screen-reader user needs to hear anyway — that the arrow keys now scroll something. Pass a
+     * plain string when the page can say WHICH table ("Pending approvals"); a non-string node cannot
+     * be an `aria-label`, so it falls back to the default (the PermissionMatrix `label` contract).
+     *
+     * The region is only announced while it HAS overflow to reach: no overflow, no tab stop, no role
+     * and no name, because a focus stop that scrolls nothing is noise. (gh#817)
+     */
+    label?: LabelProp;
 };
+/**
+ * The scroll region's accessible name. A `label` is only usable as an `aria-label` when it is a
+ * plain string, and no consumer is obliged to supply one at all — so anything else takes the
+ * localized default, which still tells the user what the stop is for. Shared with `DataTable`, so
+ * both tables name their region the same way.
+ */
+export declare function scrollRegionLabel(label: LabelProp | undefined, t: (key: string) => string): string;
 export declare const Table: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLTableElement> & {
     /**
      * Whether the Table owns its own horizontal-scroll region (default `true`). When `true` a table
@@ -117,6 +139,21 @@ export declare const Table: React.ForwardRefExoticComponent<React.HTMLAttributes
     };
     /** Defaults to `"sm"` (40rem). Ignored while `preset` is `"default"`. */
     collapseBelow?: BreakpointProp;
+    /**
+     * Accessible name for the horizontal-scroll REGION — the `tabindex="0"` wrapper a keyboard user
+     * lands on to scroll a table wider than its container, NOT the `<table>` itself (pass `aria-label`
+     * for that; it reaches the table element as it always has).
+     *
+     * Optional on purpose. A consumer is never forced to invent a name for every table: left out, the
+     * region takes the localized `dataTable.scrollRegion` default ("Scrollable table"), which is what
+     * a screen-reader user needs to hear anyway — that the arrow keys now scroll something. Pass a
+     * plain string when the page can say WHICH table ("Pending approvals"); a non-string node cannot
+     * be an `aria-label`, so it falls back to the default (the PermissionMatrix `label` contract).
+     *
+     * The region is only announced while it HAS overflow to reach: no overflow, no tab stop, no role
+     * and no name, because a focus stop that scrolls nothing is noise. (gh#817)
+     */
+    label?: LabelProp;
 } & React.RefAttributes<HTMLTableElement>>;
 export declare const TableHeader: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLTableSectionElement> & React.RefAttributes<HTMLTableSectionElement>>;
 export declare const TableBody: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLTableSectionElement> & React.RefAttributes<HTMLTableSectionElement>>;

package/dist/components/data-display/table.js

@@ -1,7 +1,13 @@
+"use client";
 import { jsx, jsxs } from "react/jsx-runtime";
 import * as React from "react";
+import { useTranslation } from "../../i18n/use-translation.js";
 import { tableHeadHeightClass } from "../../lib/control-styles.js";
+import { useScrollsHorizontally } from "../../lib/hooks.js";
 import { cn } from "../../lib/utils.js";
+function scrollRegionLabel(label, t) {
+  return typeof label === "string" && label.trim() !== "" ? label : t("dataTable.scrollRegion");
+}
 const Table = React.forwardRef(
   ({
     className,
@@ -11,45 +17,56 @@ const Table = React.forwardRef(
     preset = "default",
     collapseBelow = "sm",
     columnWidths,
+    label,
     ...props
-  }, ref) => (
-    // A table wider than its container scrolls horizontally in this wrapper; keep it
-    // keyboard-reachable so it can be scrolled without a pointer (WCAG 2.1.1 / axe
-    // scrollable-region-focusable). No landmark role — avoids landmark-unique collisions.
-    // When `scrollable` is false an ancestor owns the scroll region, so this is a bare
-    // positioning box (no `overflow`, no tab stop) to avoid a redundant nested scroller.
-    // step attribute; with `preset="default"` neither is emitted, so the box is byte-identical.
-    /* @__PURE__ */ jsx(
-      "div",
-      {
-        className: cn(
-          scrollable ? "relative w-full overflow-auto" : "relative w-full",
-          preset === "action-collection" && "ui-table-collection",
-          preset === "stacked-record-collection" && "ui-table-stacked-collection"
-        ),
-        "data-preset": preset === "default" ? void 0 : preset,
-        "data-collapse-below": preset === "default" ? void 0 : collapseBelow,
-        "data-column-widths": columnWidths ? "" : void 0,
-        style: columnWidths ? {
-          "--table-action-collection-actions-width": columnWidths.actions,
-          "--table-action-collection-actions-width-compact": columnWidths.actionsCompact,
-          "--table-action-collection-meta-width-compact": columnWidths.metaCompact,
-          "--table-action-collection-min-inline-size-compact": columnWidths.minInlineSizeCompact
-        } : void 0,
-        ...scrollable ? { tabIndex: 0 } : {},
-        children: /* @__PURE__ */ jsx(
-          "table",
-          {
-            ref,
-            "data-slot": "table",
-            "data-striped": striped === void 0 ? void 0 : striped ? "" : "false",
-            className: cn("w-full caption-bottom", bordered && "ui-table-bordered", className),
-            ...props
-          }
-        )
-      }
-    )
-  )
+  }, ref) => {
+    const { t } = useTranslation();
+    const scrollRef = React.useRef(null);
+    const scrolls = useScrollsHorizontally(scrollRef, scrollable);
+    return (
+      // A table wider than its container scrolls horizontally in this wrapper; keep it
+      // keyboard-reachable so it can be scrolled without a pointer (WCAG 2.1.1 / axe
+      // scrollable-region-focusable). That stop must not be ANONYMOUS: an unnamed, unroled focus
+      // stop announces nothing at all, so it carries `role="group"` + an accessible name (gh#817).
+      // `group`, not `region`: a named `region` IS a landmark, and a page with three tables would
+      // then ship three same-named landmarks (axe `landmark-unique`) — the reason the role was left
+      // off in the first place. `group` is announced, takes a name, and is not a landmark.
+      // When `scrollable` is false an ancestor owns the scroll region, so this is a bare
+      // positioning box (no `overflow`, no tab stop) to avoid a redundant nested scroller.
+      // step attribute; with `preset="default"` neither is emitted, so the box is byte-identical.
+      /* @__PURE__ */ jsx(
+        "div",
+        {
+          ref: scrollRef,
+          className: cn(
+            scrollable ? "relative w-full overflow-auto" : "relative w-full",
+            preset === "action-collection" && "ui-table-collection",
+            preset === "stacked-record-collection" && "ui-table-stacked-collection"
+          ),
+          "data-preset": preset === "default" ? void 0 : preset,
+          "data-collapse-below": preset === "default" ? void 0 : collapseBelow,
+          "data-column-widths": columnWidths ? "" : void 0,
+          style: columnWidths ? {
+            "--table-action-collection-actions-width": columnWidths.actions,
+            "--table-action-collection-actions-width-compact": columnWidths.actionsCompact,
+            "--table-action-collection-meta-width-compact": columnWidths.metaCompact,
+            "--table-action-collection-min-inline-size-compact": columnWidths.minInlineSizeCompact
+          } : void 0,
+          ...scrolls ? { role: "group", "aria-label": scrollRegionLabel(label, t), tabIndex: 0 } : {},
+          children: /* @__PURE__ */ jsx(
+            "table",
+            {
+              ref,
+              "data-slot": "table",
+              "data-striped": striped === void 0 ? void 0 : striped ? "" : "false",
+              className: cn("w-full caption-bottom", bordered && "ui-table-bordered", className),
+              ...props
+            }
+          )
+        }
+      )
+    );
+  }
 );
 Table.displayName = "Table";
 const TableHeader = React.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx("thead", { ref, className: cn("[&_tr]:border-b", className), ...props }));
@@ -140,5 +157,6 @@ export {
   TableCell,
   TableHead,
   TableHeader,
-  TableRow
+  TableRow,
+  scrollRegionLabel
 };

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

@@ -2,4 +2,4 @@ import * as React from "react";
 import type { FieldProp } from "../../props/components/data-entry.prop.js";
 export type { FieldProp, FieldProp as FieldProps } from "../../props/components/data-entry.prop.js";
 /** Label + optional description beside a checkbox/radio/switch control. */
-export declare function Field({ id, label, description, className, children }: FieldProp): React.JSX.Element;
+export declare function Field({ id, label, labelAddon, description, error, className, children, }: FieldProp): React.JSX.Element;

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

@@ -1,12 +1,43 @@
+"use client";
 import { jsx, jsxs } from "react/jsx-runtime";
+import * as React from "react";
 import { cn } from "../../lib/utils.js";
+import { mergeAriaIds } from "../../lib/field-a11y.js";
 import { Label } from "./label.js";
-function Field({ id, label, description, className, children }) {
+function Field({
+  id,
+  label,
+  labelAddon,
+  description,
+  error,
+  className,
+  children
+}) {
+  const descriptionId = description ? `${id}-description` : void 0;
+  const errorId = error ? `${id}-error` : void 0;
+  const childProps = React.isValidElement(children) ? children.props : void 0;
+  const control = React.isValidElement(children) ? React.cloneElement(children, {
+    "aria-describedby": mergeAriaIds(
+      childProps?.["aria-describedby"],
+      descriptionId,
+      errorId
+    ),
+    "aria-errormessage": mergeAriaIds(
+      childProps?.["aria-errormessage"],
+      errorId
+    ),
+    "aria-invalid": error ? true : childProps?.["aria-invalid"]
+  }) : children;
+  const labelNode = /* @__PURE__ */ jsx(Label, { htmlFor: id, className: "ui-choice-label", children: label });
   return /* @__PURE__ */ jsxs("div", { className: cn("ui-choice-field", className), children: [
-    /* @__PURE__ */ jsx("div", { className: "ui-choice-control", children }),
+    /* @__PURE__ */ jsx("div", { className: "ui-choice-control", children: control }),
     /* @__PURE__ */ jsxs("div", { className: "ui-choice-content", children: [
-      /* @__PURE__ */ jsx(Label, { htmlFor: id, className: "ui-choice-label", children: label }),
-      description ? /* @__PURE__ */ jsx("p", { className: "ui-choice-description", children: description }) : null
+      labelAddon != null ? /* @__PURE__ */ jsxs("div", { className: "ui-choice-label-row", children: [
+        labelNode,
+        labelAddon
+      ] }) : labelNode,
+      description ? /* @__PURE__ */ jsx("p", { id: descriptionId, className: "ui-choice-description", children: description }) : null,
+      error ? /* @__PURE__ */ jsx("p", { id: errorId, role: "alert", className: "ui-choice-error", children: error }) : null
     ] })
   ] });
 }

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

@@ -4,7 +4,6 @@ import * as React from "react";
 import { CheckCircle, CircleAlert, LoaderCircle, TriangleAlert } from "lucide-react";
 import { useTranslation } from "../../i18n/use-translation.js";
 import { Label } from "../data-entry/label.js";
-import { controlIconClass } from "../../lib/control-styles.js";
 import { cn } from "../../lib/utils.js";
 import { FieldIdentityContext, FieldNameContext, mergeAriaIds } from "../../lib/field-a11y.js";
 import { useOptionalAppContext } from "../../app/app-provider.js";
@@ -107,7 +106,16 @@ function FormField({
       errorId
     ),
     "aria-required": required ? true : childProps?.["aria-required"],
-    "aria-invalid": validationStatus === "error" ? true : childProps?.["aria-invalid"]
+    "aria-invalid": validationStatus === "error" ? true : childProps?.["aria-invalid"],
+    /* THE BOX SHOWS ITS OWN STATE, not just the line under it. `error` already reached the
+     * control through `aria-invalid`, but `warning` reached nothing — so a warned field drew an
+     * ordinary border and the only signal was a sentence below it. `.ui-control[data-status]`
+     * has painted both edges for a long time; FormField simply never passed the value down.
+     *
+     * Only `error` and `warning` are sent: `ControlStatusProp` is exactly those two, and
+     * `success` / `validating` have no control-level representation today. A child that sets its
+     * own `status` keeps it. */
+    ...validationStatus === "error" || validationStatus === "warning" ? { status: childProps?.status ?? validationStatus } : {}
   }) : children;
   const style = {};
   if (labelWidth != null)
@@ -166,16 +174,25 @@ function FormField({
               children: childWithA11y
             }
           ) }) }),
-          hasFeedback && validationStatus ? /* @__PURE__ */ jsxs("span", { id: feedbackId, role: "status", className: "ui-inline-xs text-xs", children: [
-            feedback ?? /* @__PURE__ */ jsx(
-              FeedbackIcon,
-              {
-                "aria-hidden": "true",
-                className: validationStatus === "validating" ? `${controlIconClass} motion-safe:animate-spin` : controlIconClass
-              }
-            ),
-            t(`dataEntry.form.${validationStatus}`)
-          ] }) : null,
+          hasFeedback && validationStatus ? /* @__PURE__ */ jsxs(
+            "span",
+            {
+              id: feedbackId,
+              role: "status",
+              "data-status": validationStatus,
+              className: "ui-form-feedback ui-inline-xs text-xs",
+              children: [
+                feedback ?? /* @__PURE__ */ jsx(
+                  FeedbackIcon,
+                  {
+                    "aria-hidden": "true",
+                    className: validationStatus === "validating" ? "motion-safe:animate-spin" : void 0
+                  }
+                ),
+                t(`dataEntry.form.${validationStatus}`)
+              ]
+            }
+          ) : null,
           helperPlacement === "after" ? helperNode : null,
           error ? /* @__PURE__ */ jsx("p", { id: errorId, role: "alert", className: "ui-form-field-note text-error-strong text-xs", children: error }) : null
         ] })

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

@@ -2,7 +2,7 @@ import * as React from "react";
 export type { InputProp, InputProp as InputProps } from "../../props/components/data-entry.prop.js";
 export declare const Input: React.ForwardRefExoticComponent<Omit<React.InputHTMLAttributes<HTMLInputElement>, "prefix" | "size"> & {
     onValueChange?: (value: string) => void;
-    size?: "sm" | "md" | "lg";
+    size?: "xs" | "sm" | "md" | "lg";
     status?: import("../../props/index.js").ControlStatusProp;
     variant?: import("../../props/index.js").ControlVariantProp;
     allowClear?: import("../../props/index.js").AllowClearProp;

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

@@ -38,7 +38,7 @@ export type { ErrorSurfaceModeProp, ErrorSurfaceStatusProp } from "../../props/v
 export { Breadcrumb } from "./breadcrumb.js";
 export type { BreadcrumbProps } from "./breadcrumb.js";
 export { createSidebarLink, Sidebar, SidebarHeader, SidebarItem, SidebarSection } from "./sidebar.js";
-export type { SidebarItemData, SidebarLinkComponentProp, SidebarLinkProp, SidebarProductProp as SidebarProduct, SidebarProp, SidebarProp as SidebarProps, SidebarRenderItemProp, SidebarSectionProp, } from "../../props/components/layout.prop.js";
+export type { SidebarItemData, SidebarItemProp, SidebarLinkComponentProp, SidebarLinkProp, SidebarProductProp as SidebarProduct, SidebarProp, SidebarProp as SidebarProps, SidebarRenderItemProp, SidebarSectionProp, } from "../../props/components/layout.prop.js";
 export { Topbar } from "./topbar.js";
 export type { TopbarProp, TopbarProps } from "./topbar.js";
 export { TopbarItem } from "./topbar-item.js";

package/dist/components/layout/nav-list.d.ts

@@ -16,9 +16,17 @@ export type NavListProps = NavListProp;
  * consumer that already learnt `SidebarItemProp` / `linkComponent` for the rail knows this too.
  * Only the container differs — a `<nav>` landmark instead of the shell's grid area, and no
  * collapsed rail (a page-level nav has no rail to collapse into).
+ *
+ * `item.children` is part of that shared row shape, and it is rendered through the rail's OWN
+ * `NavGroup` (gh#815). It used to be dropped: `items` mapped straight to `SidebarItem`, so a
+ * nested group type-checked, rendered as a single flat row, and its children vanished with no
+ * error and no warning. A grouped settings nav — アカウント / セキュリティ / 通知 / 請求 — is the
+ * canonical use of this component, and it took one `NavList` per group wrapped in
+ * `SidebarSection`, i.e. N `<nav>` landmarks where the page has one navigation. Now it is one
+ * `NavList`, one landmark, and the group opens itself whenever the route lands on a descendant.
  */
 export declare const NavList: React.ForwardRefExoticComponent<Omit<React.HTMLAttributes<HTMLElement>, "onSelect"> & {
-    items: import("../../props/index.js").SidebarItemProp[];
+    items: import("./sidebar.js").SidebarItemProp[];
     activeId?: string;
     label: string;
     linkComponent?: import("./sidebar.js").SidebarLinkComponentProp;

package/dist/components/layout/nav-list.js

@@ -2,18 +2,29 @@
 import { jsx } from "react/jsx-runtime";
 import * as React from "react";
 import { cn } from "../../lib/utils.js";
-import { SidebarItem } from "./sidebar.js";
+import { NavGroup, SidebarItem } from "./sidebar.js";
 const NavList = React.forwardRef(
-  ({ items, activeId, label, linkComponent, onSelect, className, ...props }, ref) => /* @__PURE__ */ jsx("nav", { ref, "aria-label": label, className: cn("ui-nav-list", className), ...props, children: items.map((item) => /* @__PURE__ */ jsx(
-    SidebarItem,
-    {
-      item,
-      active: item.id === activeId,
-      linkComponent,
-      onActivate: onSelect
-    },
-    item.id
-  )) })
+  ({ items, activeId, label, linkComponent, onSelect, className, ...props }, ref) => /* @__PURE__ */ jsx("nav", { ref, "aria-label": label, className: cn("ui-nav-list", className), ...props, children: items.map(
+    (item) => item.children && item.children.length > 0 ? /* @__PURE__ */ jsx(
+      NavGroup,
+      {
+        item,
+        activeId: activeId ?? "",
+        linkComponent,
+        onSelect
+      },
+      item.id
+    ) : /* @__PURE__ */ jsx(
+      SidebarItem,
+      {
+        item,
+        active: item.id === activeId,
+        linkComponent,
+        onActivate: onSelect
+      },
+      item.id
+    )
+  ) })
 );
 NavList.displayName = "NavList";
 export {

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

@@ -1,6 +1,6 @@
 import * as React from "react";
-import type { SidebarItemData, SidebarLinkComponentProp, SidebarProp, SidebarRenderItemProp } from "../../props/components/layout.prop.js";
-export type { SidebarItemData, SidebarLinkComponentProp, SidebarLinkProp, SidebarProductProp as SidebarProduct, SidebarProp, SidebarProp as SidebarProps, SidebarRenderItemProp, } from "../../props/components/layout.prop.js";
+import type { SidebarItemData, SidebarItemProp, SidebarLinkComponentProp, SidebarProp, SidebarRenderItemProp } from "../../props/components/layout.prop.js";
+export type { SidebarItemData, SidebarItemProp, SidebarLinkComponentProp, SidebarLinkProp, SidebarProductProp as SidebarProduct, SidebarProp, SidebarProp as SidebarProps, SidebarRenderItemProp, } from "../../props/components/layout.prop.js";
 type RenderItem = (item: SidebarItemData, rowProps: SidebarRenderItemProp) => React.ReactNode;
 type SidebarHeaderProps = React.HTMLAttributes<HTMLDivElement>;
 type SidebarSectionProps = {
@@ -28,6 +28,20 @@ type SidebarItemProps = {
 export declare function SidebarHeader({ children, className, ...props }: SidebarHeaderProps): React.JSX.Element;
 export declare function SidebarSection({ label, collapsed, children, className, ...props }: SidebarSectionProps & React.HTMLAttributes<HTMLDivElement>): React.JSX.Element;
 export declare function SidebarItem({ item, active, sub, onActivate, linkComponent: LinkComponent, asChild, renderItem, children, ...props }: SidebarItemProps & Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "onClick">): React.JSX.Element;
+type RowProps = {
+    item: SidebarItemProp;
+    activeId: string;
+    onSelect?: (id: string) => void;
+    sub?: boolean;
+    linkComponent?: SidebarLinkComponentProp;
+    renderItem?: RenderItem;
+};
+/**
+ * The collapsible submenu group of a nested `SidebarItemProp`. Exported (not from the package —
+ * only within `src/components/layout`) so `NavList` renders nested items through the SAME group as
+ * the rail instead of dropping `item.children` on the floor (gh#815).
+ */
+export declare function NavGroup({ item, activeId, onSelect, linkComponent, renderItem }: RowProps): React.JSX.Element;
 export { createSidebarLink } from "./sidebar-link.js";
 /**
  * Sidebar — data-driven vertical nav rail. Use {@link createSidebarLink} to adapt a router `Link`,

package/dist/components/layout/sidebar.js

@@ -396,6 +396,7 @@ function Sidebar({
   ] });
 }
 export {
+  NavGroup,
   Sidebar,
   SidebarHeader,
   SidebarItem,