@godxjp/ui 28.6.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/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/navigation/app-setting-picker.js

@@ -186,10 +186,27 @@ const AppSettingPicker = React.forwardRef(
                   )
                 ) : (
                   // Labeled: sized to a per-kind width from `sm` up; below `sm` it hugs its content and
-                  // A form field that wants a full-width control passes
-                  // `className="w-full"`, which wins over `w-auto`.
                   // `compact` drops the per-kind width entirely so the trigger hugs its value.
-                  cn("w-auto max-w-full", !isCompact && "ui-app-setting-picker-trigger")
+                  //
+                  // The width is a UTILITY READING A TOKEN, for the third time in this file's
+                  // history and for the same reason (gh#366 icon, gh#375 Select, gh#819 here):
+                  // @layer utilities is ordered after @layer components, so the `w-auto` that
+                  // stood here outranked `.ui-app-setting-picker-trigger[data-kind]`'s
+                  // `inline-size` and every one of the eight per-kind tokens was inert — a
+                  // consumer who retuned --app-setting-picker-density-width saw nothing move.
+                  // `--app-setting-picker-trigger-width` is what `data-kind` resolves in
+                  // navigation-layout.css (a custom property, which no utility competes with);
+                  // it defaults to `auto`, so below the breakpoint and under `compact` this is
+                  // byte-for-byte the old `w-auto` behaviour.
+                  //
+                  // It stays a SINGLE unprefixed `w-*` (not `sm:w-[…]` per kind): `cn` is
+                  // tailwind-merge, so a form field that wants a full-width control still passes
+                  // `className="w-full"` and REPLACES this one. A `sm:`-variant utility would
+                  // survive that merge and quietly ignore the consumer above 40rem.
+                  cn(
+                    "w-[length:var(--app-setting-picker-trigger-width)] max-w-full",
+                    !isCompact && "ui-app-setting-picker-trigger"
+                  )
                 ),
                 // Compact re-tiers the box through tokens (--app-setting-picker-compact-*); the height
                 // still comes from the official --control-height-sm tier, never a literal. The gap is a

package/dist/components/ui/table.js

@@ -1 +1,2 @@
+"use client";
 export * from "../data-display/table.js";

package/dist/contracts/measurement.json

@@ -1,6 +1,6 @@
 {
   "$comment": "AUTO-GENERATED by scripts/gen-measurement-contract.mjs — do not edit. Read this instead of guessing: docs/MEASUREMENT-CONTRACT.md.",
-  "version": "28.6.0",
+  "version": "28.7.0",
   "targetSize": {
     "standard": "WCAG 2.2 SC 2.5.8 Target Size (Minimum), level AA — 24×24 CSS px",
     "min": 24,

package/dist/i18n/messages/en.json

@@ -325,6 +325,9 @@
       "ariaLabel": "Progress",
       "breakdownSeparator": ", "
     },
+    "scrollArea": {
+      "region": "Scrollable region"
+    },
     "tree": {
       "expand": "Expand",
       "collapse": "Collapse",
@@ -537,7 +540,8 @@
     "sortAscending": "Sort ascending",
     "sortDescending": "Sort descending",
     "sortCancel": "Cancel sort",
-    "selectColumn": "Select"
+    "selectColumn": "Select",
+    "scrollRegion": "Scrollable table"
   },
   "dataGrid": {
     "search": "Search",

package/dist/i18n/messages/ja.json

@@ -318,6 +318,9 @@
       "ariaLabel": "進捗",
       "breakdownSeparator": "、"
     },
+    "scrollArea": {
+      "region": "スクロール可能な領域"
+    },
     "tree": {
       "expand": "展開",
       "collapse": "折りたたむ",
@@ -524,7 +527,8 @@
     "sortAscending": "昇順に並べ替え",
     "sortDescending": "降順に並べ替え",
     "sortCancel": "並べ替えを解除",
-    "selectColumn": "選択"
+    "selectColumn": "選択",
+    "scrollRegion": "スクロール可能な表"
   },
   "dataGrid": {
     "search": "検索",

package/dist/i18n/messages/vi.json

@@ -319,6 +319,9 @@
       "ariaLabel": "Tiến độ",
       "breakdownSeparator": ", "
     },
+    "scrollArea": {
+      "region": "Vùng có thể cuộn"
+    },
     "tree": {
       "expand": "Mở rộng",
       "collapse": "Thu gọn",
@@ -525,7 +528,8 @@
     "sortAscending": "Sắp xếp tăng dần",
     "sortDescending": "Sắp xếp giảm dần",
     "sortCancel": "Bỏ sắp xếp",
-    "selectColumn": "Chọn"
+    "selectColumn": "Chọn",
+    "scrollRegion": "Bảng có thể cuộn"
   },
   "dataGrid": {
     "search": "Tìm kiếm",

package/dist/lib/hooks.d.ts

@@ -1,3 +1,4 @@
+import { type RefObject } from "react";
 /**
  * Returns a debounced view of `value`, updated only after `delay` ms of no
  * change. Use for search inputs to avoid querying on every keystroke.
@@ -37,3 +38,25 @@ export declare function useIsMobile(): boolean;
  * @param element the scroll container itself (state, not a ref, so the effect re-runs when it mounts)
  */
 export declare function useScrollableRegionTabIndex(element: HTMLElement | null): void;
+/**
+ * Does this scroll box actually have somewhere to scroll, on the axes it is allowed to scroll on?
+ *
+ * Drives BOTH halves of a scroll region: the `tabindex="0"` a keyboard user needs to reach the
+ * overflow (WCAG 2.1.1 / axe `scrollable-region-focusable`) AND the `role`/name that stop needs in
+ * order not to be an anonymous one (gh#817 for the table, gh#821 for `ScrollArea`). A stop that
+ * scrolls nothing is pure noise, and a name on it is noise too, so both are withheld until there is
+ * overflow to reach.
+ *
+ * The measurement may only ever REMOVE the stop, never withhold it on a guess: a box that has not
+ * been laid out reports 0 for `clientWidth`/`clientHeight` (the server render, jsdom, a
+ * `display:none` ancestor, the frame before first layout), and that is not evidence that nothing
+ * overflows. Reading it as "no overflow" would strand the overflow from every keyboard user — a
+ * worse failure than an extra tab stop — so an unmeasured box counts as scrolling.
+ *
+ * `axis` is the box's OWN `overflow`, not a preference: an axis it does not scroll on is `hidden`
+ * there, so overflow on that axis is CLIPPED rather than reachable, and measuring it would keep a
+ * tab stop that scrolls nothing. `ScrollArea`'s `orientation` is exactly this union.
+ */
+export declare function useScrollsOnAxis(ref: RefObject<HTMLElement | null>, enabled: boolean, axis: "horizontal" | "vertical" | "both"): boolean;
+/** A table's wrapper scrolls on one axis only, so it asks the one question it has (gh#817). */
+export declare function useScrollsHorizontally(ref: RefObject<HTMLElement | null>, enabled: boolean): boolean;

package/dist/lib/hooks.js

@@ -104,11 +104,38 @@ function useScrollableRegionTabIndex(element) {
     };
   }, [element]);
 }
+function useScrollsOnAxis(ref, enabled, axis) {
+  const [scrolls, setScrolls] = useState(true);
+  useEffect(() => {
+    const el = ref.current;
+    if (!enabled || !el) return void 0;
+    const overflows = (client, scroll) => client === 0 || scroll - client > 1;
+    const update = () => {
+      setScrolls(
+        axis !== "vertical" && overflows(el.clientWidth, el.scrollWidth) || axis !== "horizontal" && overflows(el.clientHeight, el.scrollHeight)
+      );
+    };
+    update();
+    if (typeof ResizeObserver === "undefined") return void 0;
+    const observer = new ResizeObserver(update);
+    observer.observe(el);
+    if (el.firstElementChild) observer.observe(el.firstElementChild);
+    return () => {
+      observer.disconnect();
+    };
+  }, [ref, enabled, axis]);
+  return enabled && scrolls;
+}
+function useScrollsHorizontally(ref, enabled) {
+  return useScrollsOnAxis(ref, enabled, "horizontal");
+}
 export {
   useControlledLatch,
   useDebouncedValue,
   useIsMobile,
   useMediaQuery,
   useScrollableRegionTabIndex,
+  useScrollsHorizontally,
+  useScrollsOnAxis,
   useTimeoutFlag
 };