@godxjp/ui 17.0.0 → 18.0.0

package/dist/components/navigation/tabs.js

@@ -3,6 +3,14 @@ import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import * as TabsPrimitive from "@radix-ui/react-tabs";
 import { cn } from "../../lib/utils.js";
+function resolveFallbackTabValue(items, requested) {
+  if (!items || items.length === 0) return requested;
+  if (requested !== void 0) {
+    const requestedItem = items.find((item) => item.value === requested);
+    if (requestedItem && !requestedItem.disabled) return requested;
+  }
+  return items.find((item) => !item.disabled)?.value;
+}
 function Tabs({
   className,
   orientation = "horizontal",
@@ -14,8 +22,7 @@ function Tabs({
   contentClassName,
   ...props
 }) {
-  const firstValue = items?.[0]?.value;
-  const resolvedDefault = defaultValue ?? firstValue;
+  const resolvedDefault = resolveFallbackTabValue(items, defaultValue);
   return /* @__PURE__ */ jsx(
     TabsPrimitive.Root,
     {
@@ -24,7 +31,10 @@ function Tabs({
       orientation,
       value,
       defaultValue: value === void 0 ? resolvedDefault : void 0,
-      className: cn("group/tabs flex gap-2 data-[orientation=horizontal]:flex-col", className),
+      className: cn(
+        "group/tabs flex min-w-0 gap-2 data-[orientation=horizontal]:flex-col",
+        className
+      ),
       ...props,
       children: items ? /* @__PURE__ */ jsxs(Fragment, { children: [
         /* @__PURE__ */ jsx(
@@ -72,7 +82,14 @@ const TabsList = React.forwardRef(({ className, variant = "default", ...props },
     "data-slot": "tabs-list",
     "data-variant": variant,
     className: cn(
-      "group/tabs-list text-muted-foreground data-[variant=default]:bg-muted inline-flex w-fit items-center justify-center rounded-lg p-1 group-data-[orientation=vertical]/tabs:flex-col data-[variant=line]:gap-1 data-[variant=line]:rounded-none data-[variant=line]:bg-transparent",
+      // `min-w-0 max-w-full` let the list shrink to (and never exceed) whatever width its
+      // ancestors actually give it instead of forcing them wider; horizontal orientation then
+      // scrolls its own overflow rather than clipping/hiding long localized labels in a narrow
+      // container (gh#175). Hidden scrollbar keeps the strip visually clean while staying
+      // swipeable on touch and reachable via keyboard (arrow-key roving focus still scrolls the
+      // newly-focused trigger into view natively). Vertical orientation is untouched — it already
+      // stacks in a column and is sized by its own `h-*`/`w-*` overrides.
+      "group/tabs-list text-muted-foreground data-[variant=default]:bg-muted inline-flex w-fit max-w-full min-w-0 items-center justify-center rounded-lg p-1 group-data-[orientation=vertical]/tabs:flex-col data-[orientation=horizontal]:[scrollbar-width:none] data-[orientation=horizontal]:overflow-x-auto data-[orientation=horizontal]:overflow-y-hidden data-[variant=line]:gap-1 data-[variant=line]:rounded-none data-[variant=line]:bg-transparent [&[data-orientation=horizontal]::-webkit-scrollbar]:hidden",
       className
     ),
     ...props

package/dist/i18n/messages/en.json

@@ -129,7 +129,9 @@
       "sidebarLabel": "Sidebar",
       "headerLabel": "Header",
       "mainLabel": "Main content",
-      "footerLabel": "Footer"
+      "footerLabel": "Footer",
+      "openNav": "Open navigation menu",
+      "navLabel": "Menu"
     },
     "authShell": {
       "brandLabel": "Brand",

package/dist/i18n/messages/ja.json

@@ -129,7 +129,9 @@
       "sidebarLabel": "サイドバー",
       "headerLabel": "ヘッダー",
       "mainLabel": "メインコンテンツ",
-      "footerLabel": "フッター"
+      "footerLabel": "フッター",
+      "openNav": "ナビゲーションメニューを開く",
+      "navLabel": "メニュー"
     },
     "authShell": {
       "brandLabel": "ブランド",

package/dist/i18n/messages/vi.json

@@ -129,7 +129,9 @@
       "sidebarLabel": "Thanh bên",
       "headerLabel": "Đầu trang",
       "mainLabel": "Nội dung chính",
-      "footerLabel": "Chân trang"
+      "footerLabel": "Chân trang",
+      "openNav": "Mở menu điều hướng",
+      "navLabel": "Menu"
     },
     "authShell": {
       "brandLabel": "Thương hiệu",

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

@@ -0,0 +1,66 @@
+import type * as React from "react";
+/**
+ * The accessible-name / description / validation contract that {@link FormField} injects onto its
+ * single control child (via `cloneElement`). EVERY form-capable `@godxjp/ui` component accepts
+ * these props and forwards them to its **semantic focus target** — the real `<input>` / combobox /
+ * trigger the user tabs to, never a presentational wrapper `<div>`. Without this forwarding the
+ * visible label / helper / error rendered by FormField is silently disconnected from the control
+ * for assistive technology (issue #164).
+ *
+ * These are the standard WAI-ARIA field relationships:
+ * - `aria-labelledby` — points at the FormField label → the control's accessible **name**.
+ * - `aria-describedby` — points at helper text → the control's **description**.
+ * - `aria-errormessage` + `aria-invalid` — the validation message, announced when invalid.
+ * - `aria-required` — required-field semantics.
+ * - `aria-label` — a name supplied directly (used when there is no visible label element).
+ */
+export interface FieldA11yProps {
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    "aria-describedby"?: string;
+    "aria-errormessage"?: string;
+    "aria-invalid"?: React.AriaAttributes["aria-invalid"];
+    "aria-required"?: React.AriaAttributes["aria-required"];
+}
+/**
+ * Merge one or more space-separated id-reference lists (`aria-describedby`, `aria-labelledby`,
+ * `aria-errormessage`) into a single deduplicated token list. Returns `undefined` when empty so the
+ * attribute is omitted rather than rendered as `""`.
+ */
+export declare function mergeAriaIds(...values: Array<string | undefined>): string | undefined;
+/**
+ * Extract ONLY the defined field-a11y attributes from a props bag, ready to spread onto a
+ * component's semantic focus target. Undefined entries are dropped so a forwarded contract never
+ * clobbers a control's own intrinsic `aria-label` / `aria-invalid`.
+ *
+ * ```tsx
+ * const fieldA11y = pickFieldA11y(props);
+ * return <input {...fieldA11y} />; // the real focus target owns the relationship
+ * ```
+ */
+export declare function pickFieldA11y(props: FieldA11yProps): FieldA11yProps;
+/**
+ * As {@link pickFieldA11y}, but resolves the accessible **name** for a control that also has an
+ * intrinsic `aria-label` (e.g. SearchInput's built-in "Search"): when the FormField supplies an
+ * `aria-labelledby`, it wins and the intrinsic `aria-label` is dropped (a control must not carry
+ * both — `aria-labelledby` takes precedence and the redundant `aria-label` only adds noise).
+ */
+export declare function resolveFieldA11y(props: FieldA11yProps, intrinsicAriaLabel?: string): FieldA11yProps;
+/**
+ * The field-a11y attributes valid on a **group container** (`role="group"`), used by composite
+ * controls that have no single labelable focus target — CheckboxGroup, and the two-input range
+ * pickers / Transfer shuttle.
+ *
+ * Per WAI-ARIA 1.2 only `aria-labelledby` and `aria-describedby` are globally allowed on
+ * `role="group"`; `aria-invalid` / `aria-errormessage` / `aria-required` are widget-only and would
+ * be an invalid-ARIA violation on a group. So the validation message id (`aria-errormessage`) is
+ * **folded into `aria-describedby`** — the error text is still announced as part of the group's
+ * description, and FormField's `role="alert"` error node announces it live regardless.
+ *
+ * `role="radiogroup"` IS a widget and supports the full validation set — those groups use
+ * {@link pickFieldA11y} directly, not this helper.
+ */
+export declare function pickGroupFieldA11y(props: FieldA11yProps): {
+    "aria-labelledby"?: string;
+    "aria-describedby"?: string;
+};

package/dist/lib/field-a11y.js

@@ -0,0 +1,44 @@
+const FIELD_A11Y_KEYS = [
+  "aria-label",
+  "aria-labelledby",
+  "aria-describedby",
+  "aria-errormessage",
+  "aria-invalid",
+  "aria-required"
+];
+function mergeAriaIds(...values) {
+  return Array.from(new Set(values.flatMap((value) => value?.split(/\s+/).filter(Boolean) ?? []))).join(
+    " "
+  ) || void 0;
+}
+function pickFieldA11y(props) {
+  const out = {};
+  for (const key of FIELD_A11Y_KEYS) {
+    const value = props[key];
+    if (value !== void 0) out[key] = value;
+  }
+  return out;
+}
+function resolveFieldA11y(props, intrinsicAriaLabel) {
+  const picked = pickFieldA11y(props);
+  if (picked["aria-labelledby"]) {
+    return picked;
+  }
+  if (picked["aria-label"] === void 0 && intrinsicAriaLabel !== void 0) {
+    picked["aria-label"] = intrinsicAriaLabel;
+  }
+  return picked;
+}
+function pickGroupFieldA11y(props) {
+  const describedBy = mergeAriaIds(props["aria-describedby"], props["aria-errormessage"]);
+  return {
+    ...props["aria-labelledby"] !== void 0 ? { "aria-labelledby": props["aria-labelledby"] } : {},
+    ...describedBy !== void 0 ? { "aria-describedby": describedBy } : {}
+  };
+}
+export {
+  mergeAriaIds,
+  pickFieldA11y,
+  pickGroupFieldA11y,
+  resolveFieldA11y
+};

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

@@ -1,6 +1,6 @@
 /** Data Display component prop types — @see docs/COMPONENTS.md#data-display */
 import type * as React from "react";
-import type { ActionProp, ClassNameProp, DescriptionProp, IconProp, TitleProp, ColumnDefProp, GetRowIdProp, OnRowClickProp, OnSelectChangeProp, OnSortChangeProp, OnTableDensityChangeProp, SelectedIdsProp, SortStateProp, TableDensityProp, ChildrenProp, ToneProp } from "../vocabulary/index.js";
+import type { ActionProp, ClassNameProp, DescriptionProp, IconProp, TitleProp, ColumnDefProp, GetRowIdProp, OnRowClickProp, OnSelectChangeProp, OnSortChangeProp, OnTableDensityChangeProp, SelectedIdsProp, SortStateProp, TableDensityProp, ChildrenProp, ToneProp, HeadingLevelProp } from "../vocabulary/index.js";
 /** @see EmptyState */
 /**
  * Semantic intent of the EmptyState icon medallion — a subset of the shared `ToneProp` vocabulary
@@ -22,6 +22,21 @@ export type EmptyStateProp = {
      * consumer never hand-rolls a `.ui-success-state` class to recolour it.
      */
     tone?: EmptyStateToneProp;
+    /**
+     * Semantic heading level (`h1`–`h4`) for the title. Default `3`. Choose it to
+     * keep the page outline valid (`h1 → h2 → h3`, no skipped levels), NOT for
+     * visual size — the title size is fixed by `--empty-state` styles regardless
+     * of level. A page/onboarding empty state directly under a page `h1` uses
+     * `titleLevel={2}`; an empty state nested in an already-`h2` section uses `3`.
+     */
+    titleLevel?: HeadingLevelProp;
+    /**
+     * Render the title as a non-heading element (`p` / `div`) instead of a
+     * heading. Use for a `compact`/`section` empty state placed inside a section
+     * that already owns its heading, so the zero-state message is not announced as
+     * a heading and cannot skip an outline level. Overrides `titleLevel`.
+     */
+    titleAs?: "h1" | "h2" | "h3" | "h4" | "p" | "div";
     className?: ClassNameProp;
 };
 /** @see Descriptions */

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

@@ -7,7 +7,8 @@ import type { DayPickerProps } from "react-day-picker";
 import type { DateRange } from "react-day-picker";
 import type * as React from "react";
 import type { UploadFileItem } from "../../components/data-entry/upload-types.js";
-import type { ClassNameProp, DisabledProp, EmptyMessageProp, ErrorProp, HelperProp, IdProp, LabelProp, NameProp, OnChangeProp, OnValueChangeProp, OnSearchChangeProp, PlaceholderProp, RequiredProp, ValueProp, DefaultValueProp, FormLayoutProp, WidthProp, BreakpointProp, DensityProp, SizeProp } from "../vocabulary/index.js";
+import type { FieldA11yProps } from "../../lib/field-a11y.js";
+import type { ClassNameProp, DisabledProp, EmptyMessageProp, ErrorProp, HelperProp, IdProp, LabelProp, NameProp, OnChangeProp, OnValueChangeProp, OnSearchChangeProp, OpenProp, OnOpenChangeProp, PlaceholderProp, RequiredProp, ValueProp, DefaultValueProp, FormLayoutProp, WidthProp, BreakpointProp, DensityProp, SizeProp } from "../vocabulary/index.js";
 import type { ResponsiveGridColumnsProp } from "./layout.prop.js";
 /** @see Input */
 export type InputProp = React.InputHTMLAttributes<HTMLInputElement> & {
@@ -33,7 +34,7 @@ export type TextareaProp = React.TextareaHTMLAttributes<HTMLTextAreaElement> & {
  * the stepper buttons and ArrowUp/ArrowDown (Shift = ×10); `precision` sets the committed decimal
  * places (inferred from `step` when omitted). Value commits clamped to `min`/`max` on blur/Enter.
  */
-export type NumberInputProp = {
+export type NumberInputProp = FieldA11yProps & {
     value?: ValueProp<number | null>;
     defaultValue?: DefaultValueProp<number | null>;
     onValueChange?: OnValueChangeProp<number | null>;
@@ -58,9 +59,6 @@ export type NumberInputProp = {
     name?: NameProp;
     id?: IdProp;
     className?: ClassNameProp;
-    "aria-label"?: string;
-    "aria-labelledby"?: string;
-    "aria-describedby"?: string;
     "data-testid"?: string;
 };
 /**
@@ -101,7 +99,7 @@ export type FormFieldProp = {
     children: React.ReactNode;
 };
 /** @see SearchInput */
-export type SearchInputProp = {
+export type SearchInputProp = FieldA11yProps & {
     id?: IdProp;
     label?: LabelProp;
     placeholder?: PlaceholderProp;
@@ -121,7 +119,7 @@ export type ChoiceOptionProp = {
     description?: React.ReactNode;
 };
 /** @see Checkbox.Group */
-export type CheckboxGroupProp = {
+export type CheckboxGroupProp = FieldA11yProps & {
     value?: ValueProp<string[]>;
     defaultValue?: DefaultValueProp<string[]>;
     onValueChange?: OnValueChangeProp<string[]>;
@@ -129,11 +127,13 @@ export type CheckboxGroupProp = {
     orientation?: "horizontal" | "vertical";
     disabled?: DisabledProp;
     name?: NameProp;
+    /** Injected by FormField (or set directly) — applied to the `role="group"` container. */
+    id?: IdProp;
     className?: ClassNameProp;
     children?: React.ReactNode;
 };
 /** @see Radio.Group */
-export type RadioGroupProp = {
+export type RadioGroupProp = FieldA11yProps & {
     value?: ValueProp;
     defaultValue?: DefaultValueProp;
     onValueChange?: OnValueChangeProp;
@@ -141,6 +141,8 @@ export type RadioGroupProp = {
     orientation?: "horizontal" | "vertical";
     disabled?: DisabledProp;
     name?: NameProp;
+    /** Injected by FormField (or set directly) — applied to the `role="radiogroup"` container. */
+    id?: IdProp;
     className?: ClassNameProp;
     children?: React.ReactNode;
 };
@@ -163,7 +165,7 @@ export type SliderProp = React.ComponentPropsWithoutRef<typeof SliderPrimitive.R
 /** @see Calendar — react-day-picker DayPicker. */
 export type CalendarProp = DayPickerProps;
 /** @see DatePicker */
-export type DatePickerProp = {
+export type DatePickerProp = FieldA11yProps & {
     value?: ValueProp<Date>;
     defaultValue?: DefaultValueProp<Date | undefined>;
     onValueChange?: OnValueChangeProp<Date | undefined>;
@@ -180,7 +182,7 @@ export type DatePickerProp = {
     allowClear?: boolean;
 };
 /** @see MonthPicker */
-export type MonthPickerProp = {
+export type MonthPickerProp = FieldA11yProps & {
     value?: ValueProp<Date>;
     defaultValue?: DefaultValueProp<Date | undefined>;
     onValueChange?: OnValueChangeProp<Date | undefined>;
@@ -200,7 +202,7 @@ export type MonthPickerProp = {
  * @see MonthRangePicker — both edges are normalized to the FIRST day of their month
  * (the `DateRange` shape is shared with DateRangePicker so ranges interop).
  */
-export type MonthRangePickerProp = {
+export type MonthRangePickerProp = FieldA11yProps & {
     value?: ValueProp<DateRange>;
     defaultValue?: DefaultValueProp<DateRange | undefined>;
     onValueChange?: OnValueChangeProp<DateRange | undefined>;
@@ -217,7 +219,7 @@ export type MonthRangePickerProp = {
     allowClear?: boolean;
 };
 /** @see DateRangePicker */
-export type DateRangePickerProp = {
+export type DateRangePickerProp = FieldA11yProps & {
     value?: ValueProp<DateRange>;
     defaultValue?: DefaultValueProp<DateRange | undefined>;
     onValueChange?: OnValueChangeProp<DateRange | undefined>;
@@ -234,7 +236,7 @@ export type DateRangePickerProp = {
     allowClear?: boolean;
 };
 /** @see TimePicker — popover HH:mm picker (canonical 24h storage). */
-export type TimePickerProp = {
+export type TimePickerProp = FieldA11yProps & {
     value?: ValueProp;
     defaultValue?: DefaultValueProp;
     onValueChange?: OnValueChangeProp;
@@ -250,7 +252,7 @@ export type TimePickerProp = {
     allowClear?: boolean;
 };
 /** @see ColorPicker */
-export type ColorPickerProp = {
+export type ColorPickerProp = FieldA11yProps & {
     value?: ValueProp;
     onValueChange?: OnValueChangeProp;
     disabled?: DisabledProp;
@@ -320,12 +322,51 @@ export type SearchSelectProp = {
     searchPlaceholder?: PlaceholderProp;
     emptyMessage?: EmptyMessageProp;
     loadingMessage?: string;
-    /** Message shown when an async `loadOptions` rejects — a distinct state from empty/loading. */
+    /** Message shown when an async `loadOptions` rejects — a distinct state from empty/loading. Used
+     *  as-is unless `renderError` is provided. */
     errorMessage?: string;
     clearLabel?: string;
     /** Show a "clear" row when a value is selected (default true). */
     clearable?: boolean;
     disabled?: DisabledProp;
+    /**
+     * Read-only: the current value is shown (and the clear affordance hidden) but the popover cannot
+     * be opened — no new pick, no search. Mirrors the Input/NumberInput readOnly contract (stays
+     * focusable + submits its value, unlike `disabled`). Default false.
+     */
+    readOnly?: boolean;
+    /** Trigger height tier — forwarded to the underlying Button. Default matches Button's own default. */
+    size?: SizeProp;
+    /** Controlled open state for the popover (uncontrolled by default). */
+    open?: OpenProp;
+    onOpenChange?: OnOpenChangeProp;
+    /** Controlled search-box query (uncontrolled by default). Pairs with `onSearchChange`. */
+    search?: string;
+    onSearchChange?: OnSearchChangeProp;
+    /**
+     * Override the default client-side filter (`options` mode only — ignored with `loadOptions`,
+     * which is responsible for its own server-side filtering). Receives the option and the trimmed
+     * query; return true to keep the row. Only consulted while the query is non-empty.
+     */
+    filterOption?: (option: SearchSelectOptionProp, query: string) => boolean;
+    /**
+     * Custom error slot — receives the resolved message and a `retry` callback that reloads from the
+     * first page (a predictable recovery, not a resume of a failed page-N append). Overrides the
+     * default `errorMessage` row.
+     */
+    renderError?: (params: {
+        message: string;
+        retry: () => void;
+    }) => React.ReactNode;
+    /**
+     * Custom "load more" affordance appended below the list while another page is available — pairs
+     * with (does not replace) the built-in scroll-triggered pagination.
+     */
+    renderLoadMore?: (params: {
+        hasMore: boolean;
+        loading: boolean;
+        loadMore: () => void;
+    }) => React.ReactNode;
     /** Form field name — submits the selected value via a hidden input. */
     name?: NameProp;
     id?: IdProp;
@@ -342,6 +383,11 @@ export type SearchSelectProp = {
  * Data-driven (Ant-style) form of {@link Select} — one component covering static `options` or
  * async `loadOptions`, with `showSearch` toggling the searchable combobox vs a plain listbox.
  * Passing `options`/`loadOptions` to `<Select>` switches it from the compound API to this one.
+ *
+ * `readOnly`/`size`/`open`/`onOpenChange`/`search`/`onSearchChange`/`filterOption`/`renderError`/
+ * `renderLoadMore` (inherited from {@link SearchSelectProp}) take effect ONLY in searchable mode
+ * (`showSearch` or `loadOptions`) — they configure the `SearchSelect` engine that mode delegates
+ * to. The plain listbox (no search) is a native Radix listbox and ignores them.
  */
 export type SelectDataProp = SearchSelectProp & {
     /** Show the search box (combobox). Defaults to true when `loadOptions` is set, otherwise false. */
@@ -352,7 +398,7 @@ export type UploadFileItemProp = UploadFileItem;
 /** @see Upload */
 export type UploadVariantProp = "dropzone" | "button" | "picture-card" | "picture" | "avatar" | "avatar-crop";
 /** @see Upload — presentational; wire `onUpload` to media-service in app api.ts */
-export type UploadProp = {
+export type UploadProp = FieldA11yProps & {
     variant?: UploadVariantProp;
     value?: ValueProp<UploadFileItemProp[]>;
     defaultValue?: DefaultValueProp<UploadFileItemProp[]>;
@@ -368,6 +414,8 @@ export type UploadProp = {
         mediaId: string;
         previewUrl?: string;
     }>;
+    /** Injected by FormField (or set directly) — applied to the native `<input type="file">`. */
+    id?: IdProp;
     className?: ClassNameProp;
     children?: React.ReactNode;
 };
@@ -386,7 +434,7 @@ export type TreeFieldNamesProp = {
     children?: string;
 };
 /** @see Cascader — cascade picker (Popover + multi-column). */
-export type CascaderProp = {
+export type CascaderProp = FieldA11yProps & {
     options: TreeOptionProp[];
     value?: ValueProp<string[] | string[][]>;
     defaultValue?: DefaultValueProp<string[] | string[][]>;
@@ -404,7 +452,7 @@ export type CascaderProp = {
 };
 export type ShowCheckedStrategyProp = "SHOW_CHILD" | "SHOW_PARENT" | "SHOW_ALL";
 /** @see TreeSelect — tree in Popover (cmdk search + expand/collapse). */
-export type TreeSelectProp = {
+export type TreeSelectProp = FieldA11yProps & {
     treeData: TreeOptionProp[];
     value?: ValueProp<string | string[]>;
     defaultValue?: DefaultValueProp<string | string[]>;
@@ -430,7 +478,7 @@ export type TransferItemProp = {
     disabled?: boolean;
 };
 /** @see Transfer — dual-list shuttle (Checkbox + SearchInput). */
-export type TransferProp = {
+export type TransferProp = FieldA11yProps & {
     dataSource: TransferItemProp[];
     targetKeys: string[];
     onValueChange?: (targetKeys: string[], direction: "left" | "right", moveKeys: string[]) => void;
@@ -438,6 +486,8 @@ export type TransferProp = {
     showSearch?: boolean;
     oneWay?: boolean;
     disabled?: DisabledProp;
+    /** Injected by FormField (or set directly) — applied to the `role="group"` shuttle container. */
+    id?: IdProp;
     className?: ClassNameProp;
     selectedKeys?: [string[], string[]];
     onSelectChange?: (sourceSelectedKeys: string[], targetSelectedKeys: string[]) => void;

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

@@ -9,6 +9,13 @@ export type PageContainerProp = {
     extra?: ExtraProp;
     footer?: FooterProp;
     breadcrumb?: BreadcrumbProp;
+    /**
+     * Override the breadcrumb `<nav>` landmark's accessible name. Defaults to a localized
+     * "Breadcrumb". Needed when more than one `PageContainer` (each with its own `breadcrumb`)
+     * renders on the same page/view — two `<nav>` landmarks sharing one name/role fail axe's
+     * `landmark-unique` (WCAG 2.4.1 / 1.3.1).
+     */
+    breadcrumbAriaLabel?: string;
     linkComponent?: React.ElementType;
     density?: PageDensityProp;
     variant?: PageContainerVariantProp;
@@ -66,6 +73,21 @@ export type AppShellProp = {
     breadcrumb?: ReactNode;
     footer?: ReactNode;
     sidebarCollapsed?: boolean;
+    /**
+     * Navigation shown in the mobile drawer below the `lg` breakpoint, where the docked sidebar is
+     * hidden. AppShell OWNS the drawer: it renders a hamburger trigger in the topbar and a focus-
+     * trapped Sheet (Esc + overlay close, focus returns to the trigger) — hiding the sidebar without
+     * a reachable alternative is invalid (gh#165). Defaults to `sidebar`, so the same nav is
+     * available on mobile with no extra wiring; pass a distinct node for a mobile-tailored menu, or
+     * `null` to opt out (only when navigation lives elsewhere, e.g. a bottom bar).
+     */
+    mobileNav?: ReactNode;
+    /** Accessible title for the mobile navigation drawer. Defaults to the localized "Menu". */
+    mobileNavLabel?: string;
+    /** Controlled open state of the mobile drawer. Omit for AppShell-owned (uncontrolled) state. */
+    mobileNavOpen?: boolean;
+    /** Change handler for the mobile drawer open state (pairs with `mobileNavOpen`). */
+    onMobileNavOpenChange?: (open: boolean) => void;
 };
 /**
  * @see AuthShell — centred auth/login page shell (login · mfa · passkey · device · reset). A
@@ -97,6 +119,13 @@ export type SidebarItemProp = {
     icon: ComponentType<SVGProps<SVGSVGElement>>;
     badge?: ReactNode;
     disabled?: boolean;
+    /**
+     * Render the row as a real anchor (`<a href>`) — the link is the SOLE interactive element (no
+     * nested `<button>`). Use for MPA links / right-click-open-in-new-tab. Omit for SPA rows that
+     * report selection via `onSelect(id)`. For a framework router `<Link>`, use `renderItem` instead
+     * (its returned element is merged as the row via Slot, so there is still no nested interactive).
+     */
+    href?: string;
     /** Nested rows — renders a collapsible submenu group (the parent reads active when any child is). */
     children?: SidebarItemProp[];
 };
@@ -117,8 +146,21 @@ export type SidebarProp = {
     brand?: ReactNode;
     collapsed?: boolean;
     children?: ChildrenProp;
+    /**
+     * Escape hatch to render a leaf row as a custom element — typically a framework router `<Link>`.
+     * Return a SINGLE interactive element; the Sidebar merges the row styling + active state onto it
+     * via Slot (so it is the row and the sole interactive element — no nested `<button>`). Any
+     * secondary affix (a star, a count) must be a non-interactive descendant of that element.
+     */
     renderItem?: (item: SidebarItemData) => ReactNode;
     footer?: ReactNode;
+    /**
+     * Override the nav landmark's accessible name. Defaults to a localized "Main navigation".
+     * Needed when more than one Sidebar renders on the same page/view (e.g. a docked sidebar +
+     * its mobile-drawer twin, both mounted at once) — two `<nav>` landmarks sharing one name/role
+     * fail axe's `landmark-unique` (WCAG 2.4.1 / 1.3.1).
+     */
+    "aria-label"?: string;
 };
 /**
  * @see Topbar — a PURE SLOT bar (no baked chrome). The library only positions three clusters; the

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

@@ -22,10 +22,26 @@ export type PaginationProp = {
     pageSizeOptions?: number[];
     showSizeChanger?: boolean;
     showTotal?: boolean | ((total: number, range: [number, number]) => React.ReactNode);
+    /**
+     * Hide the whole control when there is nothing to page through — zero items OR exactly one page.
+     * `true` (default) keeps table footers clean: pagination is navigation between multiple result
+     * pages, so a lone disabled `1 / 1` bar is noise. Set `false` for the explicit opt-in when a
+     * consumer still wants the bar on a single page (e.g. to keep `showTotal` visible). A control
+     * with `total === 0` is ALWAYS hidden — there is no data to navigate. (gh#153)
+     */
+    hideOnSinglePage?: boolean;
     simple?: boolean;
     disabled?: DisabledProp;
     className?: ClassNameProp;
     onValueChange?: (page: number, pageSize: number) => void;
+    /**
+     * Override the `<nav>` landmark's accessible name. Defaults to a localized "Pagination".
+     * Multiple Pagination instances on one page/view (e.g. two independent result lists) need a
+     * DISTINCT name each — two `<nav>` landmarks sharing one name/role fail axe's `landmark-unique`
+     * (WCAG 2.4.1 / 1.3.1). Pass something that names what is being paged, e.g. `"注文一覧の
+     * ページネーション"` vs `"請求書一覧のページネーション"`.
+     */
+    "aria-label"?: string;
 };
 export type StepStatusProp = "wait" | "process" | "finish" | "error";
 /** @see StepItem */

package/dist/props/registry.d.ts

@@ -610,13 +610,13 @@ export declare const COMPONENT_PROP_REGISTRY: {
     readonly SearchSelectProp: {
         readonly group: "data-entry";
         readonly file: "components/data-entry.prop.ts";
-        readonly vocabulary: readonly ["ValueProp", "OnValueChangeProp", "PlaceholderProp", "EmptyMessageProp", "DisabledProp", "NameProp", "IdProp", "ClassNameProp"];
+        readonly vocabulary: readonly ["ValueProp", "OnValueChangeProp", "PlaceholderProp", "EmptyMessageProp", "DisabledProp", "NameProp", "IdProp", "ClassNameProp", "OpenProp", "OnOpenChangeProp", "SizeProp"];
         readonly note: "Internal — the searchable engine behind `<Select options showSearch>` (not public API); use Select.";
     };
     readonly SelectDataProp: {
         readonly group: "data-entry";
         readonly file: "components/data-entry.prop.ts";
-        readonly vocabulary: readonly ["ValueProp", "OnValueChangeProp", "PlaceholderProp", "EmptyMessageProp", "DisabledProp", "NameProp", "IdProp", "ClassNameProp"];
+        readonly vocabulary: readonly ["ValueProp", "OnValueChangeProp", "PlaceholderProp", "EmptyMessageProp", "DisabledProp", "NameProp", "IdProp", "ClassNameProp", "OpenProp", "OnOpenChangeProp", "SizeProp"];
         readonly note: "Ant-style data-driven form of Select (options|loadOptions + showSearch). One Select for all single-selects.";
     };
     readonly SearchSelectOptionProp: {
@@ -687,7 +687,7 @@ export declare const COMPONENT_PROP_REGISTRY: {
     readonly EmptyStateProp: {
         readonly group: "data-display";
         readonly file: "components/data-display.prop.ts";
-        readonly vocabulary: readonly ["IconProp", "TitleProp", "DescriptionProp", "ActionProp", "ToneProp"];
+        readonly vocabulary: readonly ["IconProp", "TitleProp", "DescriptionProp", "ActionProp", "ToneProp", "HeadingLevelProp"];
     };
     readonly EmptyStateToneProp: {
         readonly group: "data-display";
@@ -1097,6 +1097,11 @@ export declare const COMPONENT_PROP_REGISTRY: {
         readonly file: "components/data-display/card.tsx";
         readonly vocabulary: readonly ["TitleProp", "DescriptionProp", "ClassNameProp", "ChildrenProp"];
     };
+    readonly CardTitleProp: {
+        readonly group: "data-display";
+        readonly file: "components/data-display/card.tsx";
+        readonly vocabulary: readonly ["HeadingLevelProp", "ClassNameProp", "ChildrenProp"];
+    };
     readonly CardContentProp: {
         readonly group: "data-display";
         readonly file: "components/data-display/card.tsx";

package/dist/props/registry.js

@@ -637,7 +637,10 @@ const COMPONENT_PROP_REGISTRY = {
       "DisabledProp",
       "NameProp",
       "IdProp",
-      "ClassNameProp"
+      "ClassNameProp",
+      "OpenProp",
+      "OnOpenChangeProp",
+      "SizeProp"
     ],
     note: "Internal \u2014 the searchable engine behind `<Select options showSearch>` (not public API); use Select."
   },
@@ -652,7 +655,10 @@ const COMPONENT_PROP_REGISTRY = {
       "DisabledProp",
       "NameProp",
       "IdProp",
-      "ClassNameProp"
+      "ClassNameProp",
+      "OpenProp",
+      "OnOpenChangeProp",
+      "SizeProp"
     ],
     note: "Ant-style data-driven form of Select (options|loadOptions + showSearch). One Select for all single-selects."
   },
@@ -742,7 +748,14 @@ const COMPONENT_PROP_REGISTRY = {
   EmptyStateProp: {
     group: "data-display",
     file: "components/data-display.prop.ts",
-    vocabulary: ["IconProp", "TitleProp", "DescriptionProp", "ActionProp", "ToneProp"]
+    vocabulary: [
+      "IconProp",
+      "TitleProp",
+      "DescriptionProp",
+      "ActionProp",
+      "ToneProp",
+      "HeadingLevelProp"
+    ]
   },
   EmptyStateToneProp: {
     group: "data-display",
@@ -1104,6 +1117,11 @@ const COMPONENT_PROP_REGISTRY = {
     file: "components/data-display/card.tsx",
     vocabulary: ["TitleProp", "DescriptionProp", "ClassNameProp", "ChildrenProp"]
   },
+  CardTitleProp: {
+    group: "data-display",
+    file: "components/data-display/card.tsx",
+    vocabulary: ["HeadingLevelProp", "ClassNameProp", "ChildrenProp"]
+  },
   CardContentProp: {
     group: "data-display",
     file: "components/data-display/card.tsx",