@godxjp/ui 17.0.1 → 18.0.1

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

@@ -1,6 +1,7 @@
 import * as React from "react";
 import { type VariantProps } from "class-variance-authority";
 import type { LucideIcon } from "lucide-react";
+import type { HeadingLevelProp } from "../../props/vocabulary/index.js";
 type CardSize = "md" | "compact";
 /** Semantic leading-edge accent stripe (border-inline-start; width via the
  *  --card-accent-rail-width token, default 6px). */
@@ -37,7 +38,42 @@ export declare const CardHeader: React.ForwardRefExoticComponent<React.HTMLAttri
     /** Muted background + border-bottom — section band (mirror footer `separated`). */
     banded?: boolean;
 } & React.RefAttributes<HTMLDivElement>>;
-export declare const CardTitle: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLHeadingElement> & React.RefAttributes<HTMLHeadingElement>>;
+export type CardTitleProps = React.HTMLAttributes<HTMLHeadingElement> & {
+    /**
+     * Semantic heading level (`h1`–`h4`). Default `3`. Choose it to keep the
+     * document outline valid (`h1 → h2 → h3`, no skipped levels) for the page the
+     * card sits on — NOT for visual size: the title's size is fixed by the
+     * `--card-title-*` tokens and does not change with `level`. A section card
+     * directly under a page `h1` uses `level={2}`; a card nested inside an
+     * already-`h2` section uses `level={3}` (the default).
+     */
+    level?: HeadingLevelProp;
+    /**
+     * Render a different element than the `level` heading. Use `"p"` / `"div"`
+     * when the card title is a styled label rather than a section heading in the
+     * outline (so it is not announced as a heading and cannot skip a level).
+     * Overrides `level`.
+     */
+    as?: "h1" | "h2" | "h3" | "h4" | "p" | "div";
+};
+export declare const CardTitle: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLHeadingElement> & {
+    /**
+     * Semantic heading level (`h1`–`h4`). Default `3`. Choose it to keep the
+     * document outline valid (`h1 → h2 → h3`, no skipped levels) for the page the
+     * card sits on — NOT for visual size: the title's size is fixed by the
+     * `--card-title-*` tokens and does not change with `level`. A section card
+     * directly under a page `h1` uses `level={2}`; a card nested inside an
+     * already-`h2` section uses `level={3}` (the default).
+     */
+    level?: HeadingLevelProp;
+    /**
+     * Render a different element than the `level` heading. Use `"p"` / `"div"`
+     * when the card title is a styled label rather than a section heading in the
+     * outline (so it is not announced as a heading and cannot skip a level).
+     * Overrides `level`.
+     */
+    as?: "h1" | "h2" | "h3" | "h4" | "p" | "div";
+} & React.RefAttributes<HTMLHeadingElement>>;
 export declare const CardDescription: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLParagraphElement> & React.RefAttributes<HTMLParagraphElement>>;
 export type CardContentProps = React.HTMLAttributes<HTMLDivElement> & {
     /** Edge-to-edge body (tables, tabs list). Horizontal padding removed. */

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

@@ -44,7 +44,13 @@ const CardHeader = React.forwardRef(
   )
 );
 CardHeader.displayName = "CardHeader";
-const CardTitle = React.forwardRef(({ className, children, ...props }, ref) => /* @__PURE__ */ jsx("h3", { ref, "data-slot": "card-title", className, ...props, children }));
+const CardTitle = React.forwardRef(
+  ({ className, children, level = 3, as, ...props }, ref) => React.createElement(
+    as ?? `h${level}`,
+    { ref, "data-slot": "card-title", className, ...props },
+    children
+  )
+);
 CardTitle.displayName = "CardTitle";
 const CardDescription = React.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx("p", { ref, "data-slot": "card-description", className, ...props }));
 CardDescription.displayName = "CardDescription";

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

@@ -284,6 +284,9 @@ DataTable.ViewOptions = function DataTableViewOptions({ className }) {
   ] });
 };
 DataTable.ViewOptions.displayName = "DataTable.ViewOptions";
+function isEmptyHeader(header) {
+  return header == null || header === "" || header === false;
+}
 function columnLabel(column) {
   const header = column.columnDef.meta?.lean?.header;
   if (typeof header === "string" && header.length > 0) return header;
@@ -386,6 +389,15 @@ DataTable.Content = function DataTableContent() {
   const visibleColumns = table.getVisibleLeafColumns().map((c) => c.columnDef.meta?.lean).filter((c) => !!c);
   const emptyColSpan = visibleColumns.length + (selectable ? 1 : 0);
   const hasPinEnd = visibleColumns.some((col) => col.pin === "end");
+  const missingHeaderNames = visibleColumns.filter((col) => isEmptyHeader(col.header) && !col.ariaLabel).map((col) => col.key).join("|");
+  React.useEffect(() => {
+    if (process.env.NODE_ENV === "production" || !missingHeaderNames) return;
+    for (const key of missingHeaderNames.split("|")) {
+      console.warn(
+        `[DataTable] Column "${key}" renders a <th> with no visible or accessible text. Give it a visible \`header\`, or set \`ariaLabel\` (e.g. "Actions"/"Select") so screen readers can announce the column and axe reports no empty-table-header violation.`
+      );
+    }
+  }, [missingHeaderNames]);
   const activeSort = sort ?? sortingStateToSort(table.getState().sorting);
   const isControlledSort = sort !== void 0 || !!onSortChange;
   const onHeaderClick = (col) => {
@@ -409,27 +421,30 @@ DataTable.Content = function DataTableContent() {
     {
       className: cn("ui-data-table-scroll", hasPinEnd && "ui-data-table-has-pin-end"),
       "aria-busy": loading,
+      tabIndex: 0,
       children: /* @__PURE__ */ jsx(
         "div",
         {
           className: "ui-data-table-surface min-w-[640px] sm:min-w-0",
           "data-striped": striped ? "" : void 0,
           "data-hoverable": hoverable ? "" : void 0,
-          children: /* @__PURE__ */ jsxs(Table, { children: [
+          children: /* @__PURE__ */ jsxs(Table, { scrollable: false, children: [
             /* @__PURE__ */ jsx(TableHeader, { className: cn("bg-secondary", stickyHeader && "sticky top-0 z-10"), children: /* @__PURE__ */ jsxs(TableRow, { children: [
               selectable && /* @__PURE__ */ jsx(TableHead, { className: "w-10", children: /* @__PURE__ */ jsx(DataTable.SelectAll, {}) }),
               visibleColumns.map((col) => {
                 const isSortable = !!col.sortable;
                 const isActiveSort = isSortable && activeSort?.key === col.key;
                 const sortIndicator = isSortable ? isActiveSort ? activeSort?.direction === "asc" ? /* @__PURE__ */ jsx(ArrowUp, { className: "size-3", "aria-hidden": "true" }) : /* @__PURE__ */ jsx(ArrowDown, { className: "size-3", "aria-hidden": "true" }) : /* @__PURE__ */ jsx(ChevronsUpDown, { className: "text-muted-foreground size-3", "aria-hidden": "true" }) : 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: [
-                  col.header,
+                  headerContent,
                   sortIndicator
                 ] });
                 return /* @__PURE__ */ jsx(
                   TableHead,
                   {
-                    "data-empty": !col.header || void 0,
+                    "data-empty": headerEmpty || void 0,
                     "aria-sort": isSortable ? isActiveSort ? activeSort?.direction === "asc" ? "ascending" : "descending" : "none" : void 0,
                     className: cn(
                       col.width,
@@ -494,7 +509,7 @@ DataTable.Content = function DataTableContent() {
                 colSpan: emptyColSpan,
                 className: "ui-data-table-empty",
                 "aria-live": "polite",
-                children: empty ?? /* @__PURE__ */ jsx(EmptyState, { title: t("dataTable.empty") })
+                children: empty ?? /* @__PURE__ */ jsx(EmptyState, { title: t("dataTable.empty"), titleAs: "p" })
               }
             ) }) : dataRows.map((row) => {
               const original = row.original;

package/dist/components/data-display/empty-state.d.ts

@@ -1,3 +1,3 @@
 import type { EmptyStateProp } from "../../props/components/data-display.prop.js";
 export type { EmptyStateProp, EmptyStateProp as EmptyStateProps, } from "../../props/components/data-display.prop.js";
-export declare function EmptyState({ icon: Icon, title, description, action, variant, tone, className, }: EmptyStateProp): import("react/jsx-runtime").JSX.Element;
+export declare function EmptyState({ icon: Icon, title, description, action, variant, tone, titleLevel, titleAs, className, }: EmptyStateProp): import("react/jsx-runtime").JSX.Element;

package/dist/components/data-display/empty-state.js

@@ -1,4 +1,5 @@
 import { jsx, jsxs } from "react/jsx-runtime";
+import { createElement } from "react";
 import { cn } from "../../lib/utils.js";
 function EmptyState({
   icon: Icon,
@@ -7,8 +8,11 @@ function EmptyState({
   action,
   variant = "page",
   tone = "muted",
+  titleLevel = 3,
+  titleAs,
   className
 }) {
+  const TitleTag = titleAs ?? `h${titleLevel}`;
   return /* @__PURE__ */ jsxs(
     "div",
     {
@@ -19,7 +23,7 @@ function EmptyState({
       className: cn("ui-empty-state", className),
       children: [
         Icon && variant !== "compact" && /* @__PURE__ */ jsx("div", { className: "ui-empty-state-icon", children: /* @__PURE__ */ jsx(Icon, { className: "text-muted-foreground size-6", "aria-hidden": "true" }) }),
-        /* @__PURE__ */ jsx("h3", { className: "ui-empty-state-title", children: title }),
+        createElement(TitleTag, { className: "ui-empty-state-title" }, title),
         description && /* @__PURE__ */ jsx("p", { className: "ui-empty-state-description", children: description }),
         action && /* @__PURE__ */ jsx("div", { children: action })
       ]

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

@@ -10,7 +10,7 @@ const ScrollArea = React.forwardRef(({ className, children, ...props }, ref) =>
     className: cn("relative overflow-hidden", className),
     ...props,
     children: [
-      /* @__PURE__ */ jsx(ScrollAreaPrimitive.Viewport, { className: "size-full rounded-[inherit]", children }),
+      /* @__PURE__ */ jsx(ScrollAreaPrimitive.Viewport, { tabIndex: 0, className: "size-full rounded-[inherit]", children }),
       /* @__PURE__ */ jsx(ScrollBar, {}),
       /* @__PURE__ */ jsx(ScrollAreaPrimitive.Corner, {})
     ]

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

@@ -1,5 +1,24 @@
 import * as React from "react";
-export declare const Table: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLTableElement> & React.RefAttributes<HTMLTableElement>>;
+export type TableProps = React.HTMLAttributes<HTMLTableElement> & {
+    /**
+     * Whether the Table owns its own horizontal-scroll region (default `true`). When `true` a
+     * table wider than its container scrolls inside a keyboard-reachable wrapper (WCAG 2.1.1 / axe
+     * `scrollable-region-focusable`). Set `false` when an ancestor already provides the scroll
+     * region (e.g. `DataTable`, whose `.ui-data-table-scroll` owns the overflow + tab stop) — this
+     * avoids a redundant NESTED scroll container and a duplicate keyboard focus stop for one table.
+     */
+    scrollable?: boolean;
+};
+export declare const Table: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLTableElement> & {
+    /**
+     * Whether the Table owns its own horizontal-scroll region (default `true`). When `true` a
+     * table wider than its container scrolls inside a keyboard-reachable wrapper (WCAG 2.1.1 / axe
+     * `scrollable-region-focusable`). Set `false` when an ancestor already provides the scroll
+     * region (e.g. `DataTable`, whose `.ui-data-table-scroll` owns the overflow + tab stop) — this
+     * avoids a redundant NESTED scroll container and a duplicate keyboard focus stop for one table.
+     */
+    scrollable?: boolean;
+} & 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>>;
 export declare const TableRow: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLTableRowElement> & React.RefAttributes<HTMLTableRowElement>>;

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

@@ -3,15 +3,29 @@ import * as React from "react";
 import { tableHeadHeightClass } from "../../lib/control-styles.js";
 import { cn } from "../../lib/utils.js";
 const Table = React.forwardRef(
-  ({ className, ...props }, ref) => /* @__PURE__ */ jsx("div", { className: "relative w-full overflow-auto", children: /* @__PURE__ */ jsx(
-    "table",
-    {
-      ref,
-      "data-slot": "table",
-      className: cn("w-full caption-bottom text-sm", className),
-      ...props
-    }
-  ) })
+  ({ className, scrollable = true, ...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.
+    /* @__PURE__ */ jsx(
+      "div",
+      {
+        className: scrollable ? "relative w-full overflow-auto" : "relative w-full",
+        ...scrollable ? { tabIndex: 0 } : {},
+        children: /* @__PURE__ */ jsx(
+          "table",
+          {
+            ref,
+            "data-slot": "table",
+            className: cn("w-full caption-bottom text-sm", className),
+            ...props
+          }
+        )
+      }
+    )
+  )
 );
 Table.displayName = "Table";
 const TableHeader = React.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx("thead", { ref, className: cn("[&_tr]:border-b", className), ...props }));

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

@@ -70,6 +70,10 @@ function Calendar({
         ),
         selected: cn(
           "bg-primary text-primary-foreground hover:bg-primary hover:text-primary-foreground focus:bg-primary focus:text-primary-foreground",
+          // The day is a ghost <button> that sets its OWN (dark --foreground) text colour, which
+          // overrides the cell's text-primary-foreground and fails contrast on the blue fill
+          // (axe color-contrast). Force the button label to primary-foreground through hover/focus.
+          "[&>button]:text-primary-foreground [&>button:hover]:bg-primary [&>button:hover]:text-primary-foreground [&>button:focus]:text-primary-foreground",
           classNames?.selected
         ),
         today: cn("bg-accent text-accent-foreground", classNames?.today),

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

@@ -1,4 +1,4 @@
 import type { CascaderProp } from "../../props/components/data-entry.prop.js";
 export type { CascaderProp, CascaderProp as CascaderProps, } from "../../props/components/data-entry.prop.js";
 export type { TreeOption, TreeFieldNames } from "./tree-utils.js";
-export declare function Cascader({ options: optionsProp, value, defaultValue, onValueChange, multiple, changeOnSelect, showSearch, placeholder, disabled, className, id, expandTrigger, fieldNames, allowClear, }: CascaderProp): import("react/jsx-runtime").JSX.Element;
+export declare function Cascader({ options: optionsProp, value, defaultValue, onValueChange, multiple, changeOnSelect, showSearch, placeholder, disabled, className, id, expandTrigger, fieldNames, allowClear, ...ariaProps }: CascaderProp): import("react/jsx-runtime").JSX.Element;

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

@@ -4,6 +4,7 @@ import * as React from "react";
 import { Check, ChevronRight, ChevronsUpDown, Minus, X } from "lucide-react";
 import { useTranslation } from "../../i18n/use-translation.js";
 import { cn } from "../../lib/utils.js";
+import { pickFieldA11y } from "../../lib/field-a11y.js";
 import { controlOpenRingClass } from "../../lib/control-styles.js";
 import { Button } from "../general/button.js";
 import { Popover, PopoverContent, PopoverTrigger } from "../data-display/popover.js";
@@ -80,9 +81,13 @@ function Cascader({
   id,
   expandTrigger = "click",
   fieldNames,
-  allowClear = true
+  allowClear = true,
+  ...ariaProps
 }) {
   const { t } = useTranslation();
+  const fieldA11y = pickFieldA11y(ariaProps);
+  const reactId = React.useId();
+  const panelId = `${id ?? reactId}-panel`;
   const options = React.useMemo(
     () => normalizeTreeOptions(optionsProp, fieldNames),
     [optionsProp, fieldNames]
@@ -239,6 +244,9 @@ function Cascader({
           variant: "outline",
           role: "combobox",
           "aria-expanded": open,
+          "aria-haspopup": "listbox",
+          "aria-controls": open ? panelId : void 0,
+          ...fieldA11y,
           disabled,
           className: cn(
             "w-full justify-start font-normal",
@@ -253,6 +261,7 @@ function Cascader({
       /* @__PURE__ */ jsxs(
         PopoverContent,
         {
+          id: panelId,
           className: "w-auto min-w-[var(--radix-popover-trigger-width)] p-0",
           align: "start",
           children: [

package/dist/components/data-entry/checkbox-group.d.ts

@@ -1,3 +1,3 @@
 import type { CheckboxGroupProp } from "../../props/components/data-entry.prop.js";
 export type { CheckboxGroupProp, CheckboxGroupProp as CheckboxGroupProps, } from "../../props/components/data-entry.prop.js";
-export declare function CheckboxGroup({ value: controlledValue, defaultValue, onValueChange, options, orientation, disabled, name, className, children, }: CheckboxGroupProp): import("react/jsx-runtime").JSX.Element;
+export declare function CheckboxGroup({ value: controlledValue, defaultValue, onValueChange, options, orientation, disabled, name, id, className, children, ...ariaProps }: CheckboxGroupProp): import("react/jsx-runtime").JSX.Element;

package/dist/components/data-entry/checkbox-group.js

@@ -2,6 +2,7 @@
 import { jsx } from "react/jsx-runtime";
 import * as React from "react";
 import { cn } from "../../lib/utils.js";
+import { pickGroupFieldA11y } from "../../lib/field-a11y.js";
 import { Checkbox } from "./checkbox.js";
 import { Field } from "./field.js";
 import { choiceGroupClassName } from "./choice-option.js";
@@ -24,11 +25,14 @@ function CheckboxGroup({
   orientation = "vertical",
   disabled,
   name,
+  id,
   className,
-  children
+  children,
+  ...ariaProps
 }) {
   const reactId = React.useId();
   const [value, setValue] = useControllableArray(controlledValue, defaultValue);
+  const groupA11y = pickGroupFieldA11y(ariaProps);
   const toggle = (optionValue) => {
     const next = value.includes(optionValue) ? value.filter((v) => v !== optionValue) : [...value, optionValue];
     setValue(next);
@@ -39,16 +43,18 @@ function CheckboxGroup({
       "div",
       {
         role: "group",
+        id,
+        ...groupA11y,
         "aria-disabled": disabled ? true : void 0,
         "data-orientation": orientation,
         className: choiceGroupClassName(orientation, className),
         children: options.map((opt, index) => {
-          const id = `${reactId}-${opt.value}-${index}`;
+          const id2 = `${reactId}-${opt.value}-${index}`;
           const checked = value.includes(opt.value);
-          return /* @__PURE__ */ jsx(Field, { id, label: opt.label, description: opt.description, children: /* @__PURE__ */ jsx(
+          return /* @__PURE__ */ jsx(Field, { id: id2, label: opt.label, description: opt.description, children: /* @__PURE__ */ jsx(
             Checkbox,
             {
-              id,
+              id: id2,
               name,
               value: opt.value,
               checked,
@@ -66,6 +72,9 @@ function CheckboxGroup({
     "div",
     {
       role: "group",
+      id,
+      ...groupA11y,
+      "aria-disabled": disabled ? true : void 0,
       "data-orientation": orientation,
       className: cn(choiceGroupClassName(orientation), className),
       children

package/dist/components/data-entry/color-picker.d.ts

@@ -1,3 +1,3 @@
 import type { ColorPickerProp } from "../../props/components/data-entry.prop.js";
 export type { ColorPickerProp, ColorPickerProp as ColorPickerProps, } from "../../props/components/data-entry.prop.js";
-export declare function ColorPicker({ value, onValueChange, disabled, className, id, showHexInput, }: ColorPickerProp): import("react/jsx-runtime").JSX.Element;
+export declare function ColorPicker({ value, onValueChange, disabled, className, id, showHexInput, ...ariaProps }: ColorPickerProp): import("react/jsx-runtime").JSX.Element;

package/dist/components/data-entry/color-picker.js

@@ -3,6 +3,7 @@ import { jsx, jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { useTranslation } from "../../i18n/use-translation.js";
 import { cn } from "../../lib/utils.js";
+import { resolveFieldA11y } from "../../lib/field-a11y.js";
 import { controlIconClass } from "../../lib/control-styles.js";
 import { Input } from "./input.js";
 const HEX_PATTERN = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
@@ -16,11 +17,13 @@ function ColorPicker({
   disabled,
   className,
   id,
-  showHexInput = true
+  showHexInput = true,
+  ...ariaProps
 }) {
   const { t } = useTranslation();
   const [draft, setDraft] = React.useState(null);
   const display = draft ?? value;
+  const swatchA11y = resolveFieldA11y(ariaProps, t("dataEntry.colorPicker.ariaLabel"));
   const commit = (next) => {
     const normalized = normalizeHex(next);
     if (!HEX_PATTERN.test(normalized)) {
@@ -49,7 +52,7 @@ function ColorPicker({
           disabled,
           onChange: (event) => commit(event.target.value),
           className: "ui-color-picker-input",
-          "aria-label": t("dataEntry.colorPicker.ariaLabel")
+          ...swatchA11y
         }
       )
     ] }),

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

@@ -46,7 +46,7 @@ export declare const CommandGroup: React.ForwardRefExoticComponent<Omit<{
     ref?: React.Ref<HTMLDivElement>;
 } & {
     asChild?: boolean;
-}, keyof React.HTMLAttributes<HTMLDivElement> | "key" | "asChild">, "heading" | "value"> & {
+}, keyof React.HTMLAttributes<HTMLDivElement> | "key" | "asChild">, "value" | "heading"> & {
     heading?: React.ReactNode;
     value?: string;
     forceMount?: boolean;
@@ -57,7 +57,7 @@ export declare const CommandItem: React.ForwardRefExoticComponent<Omit<{
     ref?: React.Ref<HTMLDivElement>;
 } & {
     asChild?: boolean;
-}, keyof React.HTMLAttributes<HTMLDivElement> | "key" | "asChild">, "onSelect" | "disabled" | "value"> & {
+}, keyof React.HTMLAttributes<HTMLDivElement> | "key" | "asChild">, "onSelect" | "value" | "disabled"> & {
     disabled?: boolean;
     onSelect?: (value: string) => void;
     value?: string;

package/dist/components/data-entry/date-picker.d.ts

@@ -6,4 +6,4 @@ export type { DatePickerProp, DatePickerProp as DatePickerProps, } from "../../p
  * `name`), screen-reader friendly, and e2e-testable by simply filling the input. The calendar
  * popover is the visual affordance; typing and the calendar stay in sync.
  */
-export declare function DatePicker({ value: valueProp, defaultValue, onValueChange, placeholder, disabled, className, id, name, locale: localeProp, fromDate, toDate, allowClear, }: DatePickerProp): import("react/jsx-runtime").JSX.Element;
+export declare function DatePicker({ value: valueProp, defaultValue, onValueChange, placeholder, disabled, className, id, name, locale: localeProp, fromDate, toDate, allowClear, ...ariaProps }: DatePickerProp): import("react/jsx-runtime").JSX.Element;

package/dist/components/data-entry/date-picker.js

@@ -5,6 +5,7 @@ import { CalendarIcon } from "lucide-react";
 import { usePickerLocales, useTranslation } from "../../i18n/use-translation.js";
 import { parseDateInput, toIsoDate } from "../../lib/datetime/parse.js";
 import { useControlledLatch } from "../../lib/hooks.js";
+import { pickFieldA11y } from "../../lib/field-a11y.js";
 import { cn } from "../../lib/utils.js";
 import { Input } from "./input.js";
 import { Popover, PopoverAnchor, PopoverContent, PopoverTrigger } from "../data-display/popover.js";
@@ -22,11 +23,15 @@ function DatePicker({
   locale: localeProp,
   fromDate,
   toDate,
-  allowClear = true
+  allowClear = true,
+  ...ariaProps
 }) {
   const { t } = useTranslation();
   const { dayPickerLocale } = usePickerLocales(localeProp);
   const [open, setOpen] = React.useState(false);
+  const fieldA11y = pickFieldA11y(ariaProps);
+  const reactId = React.useId();
+  const dialogId = `${id ?? reactId}-dialog`;
   const isControlled = useControlledLatch(valueProp !== void 0);
   const [internalValue, setInternalValue] = React.useState(defaultValue);
   const value = isControlled ? valueProp : internalValue;
@@ -69,6 +74,8 @@ function DatePicker({
         role: "combobox",
         "aria-expanded": open,
         "aria-haspopup": "dialog",
+        "aria-controls": open ? dialogId : void 0,
+        ...fieldA11y,
         allowClear,
         onClear: clear,
         trailingIcon: /* @__PURE__ */ jsx(PopoverTrigger, { asChild: true, children: /* @__PURE__ */ jsx(
@@ -106,6 +113,9 @@ function DatePicker({
     /* @__PURE__ */ jsx(
       PopoverContent,
       {
+        id: dialogId,
+        role: "dialog",
+        "aria-label": t("dataEntry.datePicker.openCalendar") ?? "Calendar",
         className: "w-auto p-0",
         align: "start",
         onOpenAutoFocus: (event) => event.preventDefault(),

package/dist/components/data-entry/date-range-picker.d.ts

@@ -7,4 +7,4 @@ export type { DateRangePickerProp, DateRangePickerProp as DateRangePickerProps,
  * `${name}_to`, screen-reader friendly, e2e-testable by filling either input); the
  * range calendar is the visual affordance.
  */
-export declare function DateRangePicker({ value: valueProp, defaultValue, onValueChange, placeholder, disabled, className, id, name, locale: localeProp, fromDate, toDate, allowClear, }: DateRangePickerProp): import("react/jsx-runtime").JSX.Element;
+export declare function DateRangePicker({ value: valueProp, defaultValue, onValueChange, placeholder, disabled, className, id, name, locale: localeProp, fromDate, toDate, allowClear, ...ariaProps }: DateRangePickerProp): import("react/jsx-runtime").JSX.Element;

package/dist/components/data-entry/date-range-picker.js

@@ -5,6 +5,7 @@ import { ArrowRight, CalendarIcon, X } from "lucide-react";
 import { usePickerLocales, useTranslation } from "../../i18n/use-translation.js";
 import { parseDateInput, toIsoDate } from "../../lib/datetime/index.js";
 import { useControlledLatch } from "../../lib/hooks.js";
+import { pickGroupFieldA11y } from "../../lib/field-a11y.js";
 import { cn } from "../../lib/utils.js";
 import { Popover, PopoverAnchor, PopoverContent, PopoverTrigger } from "../data-display/popover.js";
 import { Calendar } from "./calendar.js";
@@ -21,14 +22,17 @@ function DateRangePicker({
   locale: localeProp,
   fromDate,
   toDate,
-  allowClear = true
+  allowClear = true,
+  ...ariaProps
 }) {
   const { t } = useTranslation();
   const { dayPickerLocale } = usePickerLocales(localeProp);
   const [open, setOpen] = React.useState(false);
+  const groupA11y = pickGroupFieldA11y(ariaProps);
   const autoId = React.useId();
-  const fromId = id ?? autoId;
-  const toId = `${fromId}-to`;
+  const groupId = id ?? autoId;
+  const fromId = `${groupId}-from`;
+  const toId = `${groupId}-to`;
   const isControlled = useControlledLatch(valueProp !== void 0);
   const [internalValue, setInternalValue] = React.useState(defaultValue);
   const value = isControlled ? valueProp : internalValue;
@@ -70,6 +74,10 @@ function DateRangePicker({
   return /* @__PURE__ */ jsx(Popover, { open, onOpenChange: setOpen, children: /* @__PURE__ */ jsx(PopoverAnchor, { asChild: true, children: /* @__PURE__ */ jsxs(
     "div",
     {
+      role: "group",
+      id: groupId,
+      ...groupA11y,
+      "aria-disabled": disabled ? true : void 0,
       className: cn(
         // One input-styled shell for the whole range — mirrors Input's control
         // tokens (border/radius/ring) so it reads as a single form field.

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

@@ -3,6 +3,7 @@ import { jsx, jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { Label } from "../data-entry/label.js";
 import { cn } from "../../lib/utils.js";
+import { mergeAriaIds } from "../../lib/field-a11y.js";
 import { useFormLayout } from "./form.js";
 const toCssLength = (v) => typeof v === "number" ? `${v}px` : v;
 const FOCUSABLE_SELECTOR = 'input:not([type="hidden"]), select, textarea, button, [tabindex]:not([tabindex="-1"])';
@@ -37,15 +38,18 @@ function FormField({
     );
   }
   const childProps = React.isValidElement(children) ? children.props : void 0;
-  const mergeIds = (...values) => Array.from(new Set(values.flatMap((value) => value?.split(/\s+/).filter(Boolean) ?? []))).join(
-    " "
-  ) || void 0;
+  const mergeIds = mergeAriaIds;
   const childWithA11y = React.isValidElement(children) ? React.cloneElement(children, {
     // The label is associated via aria-labelledby (not <label for>): composite
     // controls (Radio.Group, checkbox lists, range pairs) have no labelable root,
     // and a dangling `for` triggers Chrome's "Incorrect use of <label>" issue.
     id: childProps?.id ?? resolvedId,
     "aria-labelledby": childProps?.["aria-labelledby"] ?? labelId,
+    // Redundant `aria-label` fallback (belt-and-suspenders): the accessible name is the
+    // SAME string as the visible label, just reachable even if an aria-labelledby lookup
+    // ever comes back empty (id-ref timing, AT quirks). Only when `label` is plain text and
+    // the child hasn't already set its own aria-label.
+    "aria-label": childProps?.["aria-label"] ?? (typeof label === "string" ? label : void 0),
     // Helper and error can coexist: helper stays on aria-describedby, the error on
     // aria-errormessage (surfaced when aria-invalid is true).
     "aria-describedby": mergeIds(

package/dist/components/data-entry/month-picker.d.ts

@@ -6,4 +6,4 @@ export type { MonthPickerProp, MonthPickerProp as MonthPickerProps, } from "../.
  * The field stays a real, typeable input (form-submittable via `name` as
  * `yyyy-MM`); the grid is the visual affordance.
  */
-export declare function MonthPicker({ value: valueProp, defaultValue, onValueChange, placeholder, disabled, className, id, name, fromYear, toYear, allowClear, }: MonthPickerProp): import("react/jsx-runtime").JSX.Element;
+export declare function MonthPicker({ value: valueProp, defaultValue, onValueChange, placeholder, disabled, className, id, name, fromYear, toYear, allowClear, ...ariaProps }: MonthPickerProp): import("react/jsx-runtime").JSX.Element;

package/dist/components/data-entry/month-picker.js

@@ -4,6 +4,7 @@ import * as React from "react";
 import { CalendarIcon, ChevronLeft, ChevronRight, X } from "lucide-react";
 import { usePickerLocales, useTranslation } from "../../i18n/use-translation.js";
 import { useControlledLatch } from "../../lib/hooks.js";
+import { pickFieldA11y } from "../../lib/field-a11y.js";
 import { cn } from "../../lib/utils.js";
 import { Button } from "../general/button.js";
 import { Popover, PopoverAnchor, PopoverContent, PopoverTrigger } from "../data-display/popover.js";
@@ -27,13 +28,16 @@ function MonthPicker({
   name,
   fromYear,
   toYear,
-  allowClear = true
+  allowClear = true,
+  ...ariaProps
 }) {
   const { t } = useTranslation();
   const { locale } = usePickerLocales();
   const [open, setOpen] = React.useState(false);
   const autoId = React.useId();
   const inputId = id ?? autoId;
+  const dialogId = `${inputId}-dialog`;
+  const fieldA11y = pickFieldA11y(ariaProps);
   const isControlled = useControlledLatch(valueProp !== void 0);
   const [internalValue, setInternalValue] = React.useState(defaultValue);
   const value = isControlled ? valueProp : internalValue;
@@ -78,6 +82,11 @@ function MonthPicker({
             placeholder: placeholder ?? t("dataEntry.monthPicker.placeholder") ?? YM_HINT,
             inputMode: "numeric",
             autoComplete: "off",
+            role: "combobox",
+            "aria-expanded": open,
+            "aria-haspopup": "dialog",
+            "aria-controls": open ? dialogId : void 0,
+            ...fieldA11y,
             className: "placeholder:text-muted-foreground min-w-0 flex-1 bg-transparent tabular-nums outline-none disabled:cursor-not-allowed",
             onKeyDown: (event) => {
               if (event.key === "ArrowDown") {
@@ -124,6 +133,9 @@ function MonthPicker({
         /* @__PURE__ */ jsxs(
           PopoverContent,
           {
+            id: dialogId,
+            role: "dialog",
+            "aria-label": t("dataEntry.monthPicker.openGrid") ?? "Month grid",
             className: "w-auto p-3",
             align: "start",
             onOpenAutoFocus: (event) => event.preventDefault(),

package/dist/components/data-entry/month-range-picker.d.ts

@@ -8,4 +8,4 @@ export type { MonthRangePickerProp, MonthRangePickerProp as MonthRangePickerProp
  * affordance. Grid picks are two-step (from, then to — swapped when picked
  * backwards) and a pick on a COMPLETE range starts a new one (reset-on-complete).
  */
-export declare function MonthRangePicker({ value: valueProp, defaultValue, onValueChange, placeholder, disabled, className, id, name, fromYear, toYear, allowClear, }: MonthRangePickerProp): import("react/jsx-runtime").JSX.Element;
+export declare function MonthRangePicker({ value: valueProp, defaultValue, onValueChange, placeholder, disabled, className, id, name, fromYear, toYear, allowClear, ...ariaProps }: MonthRangePickerProp): import("react/jsx-runtime").JSX.Element;