@godxjp/ui 20.0.0 → 20.1.0

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

@@ -1,8 +1,8 @@
 /** Form module prop types — react-hook-form + Zod 4 only. */
 import type * as React from "react";
-import type { FieldPath, FieldValues, UseFormProps, UseFormReturn } from "react-hook-form";
+import type { FieldArray, FieldArrayPath, FieldErrors, FieldPath, FieldValues, UseFormProps, UseFormReturn } from "react-hook-form";
 import type { z } from "zod";
-import type { ErrorProp, HelperProp, IdProp, LabelProp, RequiredProp } from "../vocabulary/index.js";
+import type { BreakpointProp, DensityProp, DisabledProp, ErrorBagProp, ErrorProp, FormLayoutProp, HelperProp, IdProp, LabelProp, RequiredProp, WidthProp } from "../vocabulary/index.js";
 /** Schema passed to useZodForm — must be Zod 4 object schema. */
 export type ZodSchemaProp<T extends z.ZodType = z.ZodType> = T;
 /** Options for useZodForm (resolver injected automatically). */
@@ -27,6 +27,11 @@ export interface FormStateAdapter {
     /** Optional blur handler (e.g. touch-tracking); called with the field name. */
     onBlur?(name: string): void;
     getValues?(): unknown;
+    /**
+     * Restore the store's initial values (e.g. Inertia's `form.reset()`). `FormRoot` calls it for a
+     * native `<Button type="reset">`, so the reset button behaves identically on both paths.
+     */
+    reset?(): void;
 }
 /** @see FormRoot */
 export type FormRootProp<TFieldValues extends FieldValues> = {
@@ -39,26 +44,159 @@ export type FormRootProp<TFieldValues extends FieldValues> = {
      * Framework-agnostic form-state adapter (e.g. `inertiaAdapter(form)` from `@godxjp/ui/inertia`).
      */
     adapter?: FormStateAdapter;
-    /** Submit handler. */
+    /** Submit handler — runs only after validation passes (antd `onFinish`). */
     onSubmit: (values: TFieldValues) => void | Promise<void>;
+    /**
+     * Validation FAILED (antd `onFinishFailed`) — receives react-hook-form's error tree. Use it to
+     * announce a summary; the first invalid field is focused (and scrolled to) regardless.
+     * react-hook-form path only: on the adapter path the server owns validation.
+     */
+    onSubmitFailed?: (errors: FieldErrors<TFieldValues>) => void;
+    /**
+     * `onSubmit` REJECTED (the network call failed). Without this the rejection escapes as an
+     * unhandled promise rejection, which is what an async `onSubmit` does today — pass a handler to
+     * render a form-level error instead.
+     */
+    onSubmitError?: (error: unknown) => void;
+    /**
+     * A native `<Button type="reset">` inside the form restores `defaultValues` (adapter path:
+     * `adapter.reset()`); this runs afterwards for any extra app state (a status banner, a step).
+     */
+    onReset?: () => void;
+    /**
+     * Scroll the first invalid field into view after a failed submit (antd `scrollToFirstError`).
+     * Honours `prefers-reduced-motion`. Default `true`.
+     */
+    scrollToFirstError?: boolean;
+    /**
+     * Disable EVERY field under this form (antd Form `disabled`) — read by `FormFieldControl`
+     * (which hands `disabled` to its render prop) and by `useFormDisabled()` for the action buttons.
+     * Values are NOT dropped from the submitted payload.
+     */
+    disabled?: DisabledProp;
+    /**
+     * Field layout for every `FormFieldControl` below (antd `layout`). Setting ANY layout prop makes
+     * `FormRoot` render the `Form` layout shell, whose `--form-block-gap` spacing replaces the plain
+     * `ui-stack-md` stack used by a bare `FormRoot`.
+     */
+    layout?: FormLayoutProp;
+    /** Label column width in the `horizontal` layout (antd `labelCol`). */
+    labelWidth?: WidthProp;
+    /** Control column width (antd `wrapperCol`). */
+    controlWidth?: WidthProp;
+    /** Label text alignment in the `horizontal` layout (antd `labelAlign`). */
+    labelAlign?: "start" | "end";
+    /** Viewport below which a `horizontal`/`inline` layout stacks; `false` never stacks. */
+    collapseBelow?: BreakpointProp | false;
+    /** Control density for the fields below (antd Form `size`). */
+    density?: DensityProp;
+    columns?: import("./data-entry.prop.js").FormProp["columns"];
+    /** How required/optional fields are marked in their labels (antd `requiredMark`). */
+    requiredMark?: boolean | "optional";
+    /**
+     * Server validation error bag. Fields claim their own key and `<FormErrors />` renders the
+     * unclaimed remainder — the same mechanism as `Form errors`, without a second `Form` wrapper.
+     */
+    errors?: ErrorBagProp;
     children: React.ReactNode;
     className?: string;
     id?: IdProp;
 };
 /** @see FormFieldControl */
-export type FormFieldControlProp<TFieldValues extends FieldValues> = {
+export type FormFieldControlProp<TFieldValues extends FieldValues> = Pick<import("./data-entry.prop.js").FormFieldProp, "id" | "field" | "labelAddon" | "layout" | "labelWidth" | "controlWidth" | "colSpan"> & {
     name: FieldPath<TFieldValues>;
     label: LabelProp;
     required?: RequiredProp;
     helper?: HelperProp;
+    /**
+     * Disable this field only. Defaults to the surrounding `FormRoot disabled`. The resolved state
+     * reaches the control through the render prop's `disabled`; the field's value is still submitted
+     * (antd semantics), unlike react-hook-form's own `disabled`.
+     */
+    disabled?: DisabledProp;
+    /**
+     * Re-validate this field whenever one of these fields changes (antd `dependencies`) — the
+     * confirm-password / date-range case, where the schema's cross-field `.superRefine()` reports on
+     * THIS field but only re-runs when the OTHER one is edited. Runs only once the form has been
+     * submitted, so a dependency edit never flags a field the user has not reached yet.
+     */
+    dependencies?: FieldPath<TFieldValues>[];
+    /**
+     * Read the value out of the control's change payload (antd `getValueFromEvent`). Replaces the
+     * built-in DOM-event/raw-value detection — needed by a control that reports `(value, option)`.
+     */
+    getValueFromEvent?: (...args: unknown[]) => unknown;
+    /**
+     * Transform the extracted value before it is stored (antd `normalize`) — trim, upper-case,
+     * digits-only. Receives the previous value so a normaliser can reject a change.
+     */
+    normalize?: (value: unknown, previousValue: unknown) => unknown;
+    /**
+     * Message shown in the error slot INSTEAD of the resolved validation error (antd `help`) — for a
+     * server error the schema cannot know about.
+     */
+    help?: ErrorProp;
+    /**
+     * Force the validation state shown by the field (antd `validateStatus`) — `"validating"` for a
+     * remote check in flight, `"success"` for a confirmed-unique value. A real validation error
+     * always wins; mirrors `FormField validateStatus`.
+     */
+    validateStatus?: "success" | "warning" | "error" | "validating";
+    /** Render the status icon + localized status text for `validateStatus` (antd `hasFeedback`). */
+    hasFeedback?: boolean;
+    /** Replace the default feedback text next to the `hasFeedback` icon. */
+    feedback?: React.ReactNode;
+    /**
+     * Keep the value in the form state after the field unmounts (antd `preserve`, default `true`).
+     * `false` unregisters it — a conditional branch that must not submit a stale value.
+     */
+    preserve?: boolean;
     className?: string;
     children: (field: {
         id: string;
         name: string;
         value: unknown;
         onChange: (...args: unknown[]) => void;
+        onValueChange: (...args: unknown[]) => void;
         onBlur: () => void;
         ref: React.Ref<HTMLInputElement>;
+        /** Present (and `true`) only when the field is disabled, so `{...field}` never re-enables a control. */
+        disabled?: DisabledProp;
+    }) => React.ReactNode;
+};
+/**
+ * @see FormFieldArray — dynamic repeating fields (antd `Form.List`) on react-hook-form's
+ * `useFieldArray`. `name` is the array field; each row hands back the dotted path prefix to build
+ * the child `FormFieldControl name`.
+ */
+export type FormFieldArrayProp<TFieldValues extends FieldValues, TName extends FieldArrayPath<TFieldValues> = FieldArrayPath<TFieldValues>> = {
+    /** Path of the array in the schema (`"contacts"`, `"invoice.lines"`). */
+    name: TName;
+    children: (list: {
+        /** One entry per row, in order. `key` is react-hook-form's stable row id — use it as the React key. */
+        fields: Array<{
+            key: string;
+            name: `${TName}.${number}`;
+            index: number;
+        }>;
+        /** Append one row (or several) at the end. */
+        append: (value: FieldArray<TFieldValues, TName> | FieldArray<TFieldValues, TName>[]) => void;
+        /** Insert one row (or several) at the front. */
+        prepend: (value: FieldArray<TFieldValues, TName> | FieldArray<TFieldValues, TName>[]) => void;
+        /** Insert at `index`. */
+        insert: (index: number, value: FieldArray<TFieldValues, TName> | FieldArray<TFieldValues, TName>[]) => void;
+        /** Remove `index` (or several); omit to clear every row. */
+        remove: (index?: number | number[]) => void;
+        /** Move a row, keeping its state (drag-reorder). */
+        move: (from: number, to: number) => void;
+        /** Exchange two rows. */
+        swap: (indexA: number, indexB: number) => void;
+        /** Replace every row at once. */
+        replace: (values: FieldArray<TFieldValues, TName>[]) => void;
+        /** Array-LEVEL validation message (a `.min(1)` on the array itself), not a row's. */
+        error?: string;
+        /** Resolved `FormRoot disabled` — gate the add/remove buttons on it. */
+        disabled: DisabledProp;
     }) => React.ReactNode;
 };
 /** Mapped field error from RHF — displayed via FormField error slot. */

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

@@ -1,6 +1,6 @@
 /** Foundation component prop types — @see docs/COMPONENTS.md#foundation */
 import type * as React from "react";
-import type { ActivityAnnounceProp, ActivityVariantProp, AsChildProp, ButtonSizeProp, ButtonVariantProp, ChildrenProp, ClassNameProp, DisabledProp, FontWeightProp, HeadingLevelProp, LabelProp, OnClickProp, PendingProp, RevealDelayProp, ShapeProp, SizeProp, TextAlignProp, TextSizeProp, TextToneProp } from "../vocabulary/index.js";
+import type { ActivityAnnounceProp, ActivityVariantProp, AsChildProp, ButtonSizeProp, ButtonVariantProp, ChildrenProp, ClassNameProp, DisabledProp, FontWeightProp, HeadingLevelProp, LabelProp, OnClickProp, PendingProp, RevealDelayProp, ShapeProp, SizeProp, TextAlignProp, TextSizeProp, TextToneProp, TextWhitespaceProp } from "../vocabulary/index.js";
 /** @see Text — typographic primitive; replaces hand-rolled `<span className="text-[13px] …">`. */
 export type TextProp = Omit<React.HTMLAttributes<HTMLElement>, "color"> & {
     /** Render element. Default `span`. */
@@ -37,8 +37,24 @@ export type TextProp = Omit<React.HTMLAttributes<HTMLElement>, "color"> & {
      * line-clamp styling (never write the `line-clamp-N` utility page-side).
      */
     clamp?: number;
+    /**
+     * Whitespace handling. Default `normal` (CSS's own: newlines and space runs collapse).
+     *
+     * `pre-wrap` is for text a PERSON typed — a plain-text note, an issue description, a pasted log
+     * — where the line breaks and the indentation are CONTENT, not formatting. It preserves both and
+     * still wraps long lines at the container edge, and it breaks an over-long unbroken token (a URL,
+     * an id) rather than letting it overflow.
+     *
+     * Precedence is explicit and resolved in the component, not by CSS ordering: `truncate` is a
+     * single-line contract and WINS (dev builds warn, and `data-whitespace` is not emitted), while
+     * `clamp` composes with it — a clamped pre-wrap block shows its first N real lines.
+     */
+    whitespace?: TextWhitespaceProp;
     /** Tabular figures for aligned numbers. */
     tabular?: boolean;
+    decoration?: "none" | "underline" | "line-through";
+    /** Inline code chip; use with as="code". */
+    chip?: boolean;
     /** Monospace family (codes, ids). */
     mono?: boolean;
     htmlFor?: string;

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

@@ -1,10 +1,10 @@
-export type { AppShellProp, AuthFooterProp, AuthIdentityProp, OrgSwitcherLabels, OrgSwitcherOrganization, OrgSwitcherProp, PageContainerProp, PageInsetProp, SidebarItemProp, SidebarProductProp, SidebarProp, SidebarSectionProp, TopbarProp, } from "./layout.prop.js";
+export type { AppLauncherApp, AppLauncherGroup, AppLauncherLabels, AppLauncherProp, AppShellProp, AuthFooterProp, AuthIdentityProp, OrgSwitcherLabels, OrgSwitcherOrganization, OrgSwitcherProp, PageContainerProp, PageInsetProp, SidebarItemProp, SidebarProductProp, SidebarProp, SidebarSectionProp, TopbarProp, } from "./layout.prop.js";
 export type { ButtonProp } from "./general.prop.js";
 export type { InputProp, TextareaProp, FormFieldProp, SearchInputProp, CheckboxProp, CheckboxGroupProp, ChoiceOptionProp, RadioProp, RadioGroupProp, SwitchProp, SliderProp, CalendarProp, DatePickerProp, DateRangePickerProp, TimePickerProp, ColorPickerProp, UploadProp, UploadFileItemProp, UploadVariantProp, TreeOptionProp, TreeFieldNamesProp, CascaderProp, TreeSelectProp, ShowCheckedStrategyProp, TransferProp, TransferItemProp, } from "./data-entry.prop.js";
 export type { AvatarProp, EmptyStateProp, DescriptionsProp, DescriptionsItemProp, BadgeProp, DataTableProp, QrCodeProp, } from "./data-display.prop.js";
 export type { ChartDatum, ChartSeriesProp, LineChartProp, BarChartProp, AreaChartProp, PieChartProp, } from "./charts.prop.js";
 export type { AlertQueryErrorProp, AlertProp, AlertTitleProp, AlertContentProp, AlertDescriptionProp, AlertActionsProp, SheetResponsiveProp, SkeletonRowsProp, } from "./feedback.prop.js";
 export type { DataStateProp, InfiniteQueryStateProp, InfiniteQueryHelpers, PrefetchLinkProp, } from "./query.prop.js";
-export type { PaginationProp, StepsProp, StepItemProp, StepStatusProp, TabsProp, TabItemProp, } from "./navigation.prop.js";
+export type { DropdownMenuPlacementProp, PaginationProp, PaginationSizeProp, PaginationAlignProp, StepsProp, StepItemProp, StepStatusProp, StepsTypeProp, TabsProp, TabItemProp, TabsVariantProp, TabsPlacementProp, TabsExtraProp, TabsOnEditProp, } from "./navigation.prop.js";
 export type { AppProviderProp, AppContextValue, AppSettingKind, AppSettingPickerProp, AppSettingToggleKind, AppSettingToggleProp, } from "./app.prop.js";
 export type { ZodSchemaProp, UseZodFormOptionsProp, UseZodFormReturnProp, FormRootProp, FormFieldControlProp, FieldErrorMessageProp, } from "./form.prop.js";

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

@@ -24,6 +24,8 @@ export type PageContainerMeasureProp = "default" | "narrow" | "medium";
 export type PageContainerHeaderScaleProp = "document" | "chrome";
 /** @see PageContainer */
 export type PageContainerProp = {
+    toolbarPad?: PadProp;
+    footerPad?: PadProp;
     title: TitleProp;
     subtitle?: SubtitleProp;
     /**
@@ -101,7 +103,7 @@ export type FlexDirectionProp = "row" | "col";
 export type FlexAlignProp = "start" | "center" | "end" | "stretch" | "baseline";
 export type FlexJustifyProp = "start" | "center" | "end" | "between" | "around" | "evenly";
 /** @see Flex */
-export type FlexProp = React.HTMLAttributes<HTMLDivElement> & {
+export type FlexProp = React.HTMLAttributes<HTMLElement> & {
     /**
      * Render element — `div` (default) or `span` when the Flex sits in a PHRASING context and a
      * `<div>` would be invalid HTML: inside a `TabsTrigger`/`PopoverTrigger`/`Button` (all of which
@@ -109,8 +111,16 @@ export type FlexProp = React.HTMLAttributes<HTMLDivElement> & {
      * inside a `<p>`. Same closed shape as `ListRow`'s `as` — it swaps the TAG, nothing else: the
      * `.ui-flex` rules carry `display: flex`, so the box is identical either way.
      */
-    as?: "div" | "span";
-    direction?: FlexDirectionProp;
+    as?: "div" | "span" | "ul" | "ol" | "li";
+    /** Lightweight surfaces for rows and notices; no Card elevation by default. */
+    surface?: "muted" | "popover" | "warning";
+    /** Negative inline inset, using the same spacing scale as pad. */
+    bleed?: GapProp;
+    /** Floating row actions: show on parent hover, focus-within, and touch. */
+    reveal?: "hover";
+    direction?: FlexDirectionProp | Partial<Record<"base" | BreakpointProp, FlexDirectionProp>>;
+    grow?: boolean;
+    shrink?: boolean;
     gap?: GapProp;
     /**
      * CỬA THOÁT: một khoảng cách tính bằng pixel, ngoài mọi bậc của thang.
@@ -213,8 +223,9 @@ export type ResponsiveGridColumnsProp = number | {
  * `pricing-plans` — the canonical billing/pricing-plan collection: 1 column until the `lg` step
  * (container ≥ 64rem), then 3 columns from `lg` upward.
  */
+export type ResponsiveGridFlowProp = "rows" | "columns";
 export type ResponsiveGridPresetProp = "pricing-plans";
-export type MasterDetailRailWidthProp = "compact" | "standard";
+export type MasterDetailRailWidthProp = "narrow" | "compact" | "standard" | "wide";
 export type MasterDetailRailProp = "master" | "detail";
 /**
  * Bounded viewport preset for the master collection. `auto` (default) never bounds it — the region
@@ -262,7 +273,8 @@ export type PageInsetProp = React.HTMLAttributes<HTMLDivElement> & {
 };
 /** @see AppShell */
 export type AppShellProp = {
-    sidebar: ReactNode;
+    /** Omit or pass null/false for a shell without the sidebar landmark or grid track. */
+    sidebar?: ReactNode;
     children: ReactNode;
     topbar?: ReactNode;
     topbarLeft?: ReactNode;
@@ -467,6 +479,10 @@ export type MobileShellProp = {
  * so a service retunes a day divider or an unread watermark from its theme and never forks CSS.
  */
 export type SeparatorProp = Omit<React.HTMLAttributes<HTMLDivElement>, "children"> & {
+    labelSize?: "2xs" | "xs" | "sm" | "md";
+    space?: GapProp;
+    hideBelow?: BreakpointProp;
+    hideFrom?: BreakpointProp;
     /** Rule axis. Default `"horizontal"`. */
     orientation?: OrientationProp;
     /**
@@ -869,12 +885,132 @@ export type OrgSwitcherProp = {
     error?: ReactNode;
     onRetry?: () => void;
     labels: OrgSwitcherLabels;
+    /**
+     * WHICH SURFACE the panel opens on.
+     *
+     * - `"auto"` (default) — popover above `--sheet-responsive-breakpoint-width`, focus-trapped
+     *   bottom Sheet at or below it.
+     * - `"dialog"` — a centred modal above that breakpoint, the same bottom Sheet below it. Reach for
+     *   this once the panel carries more than a name per row — a role, a plan, a member count, a
+     *   "create organization" action. A popover is anchored to its trigger, clipped by the viewport
+     *   and sized by `--org-switcher-menu-width`; a dialog has a real title, a scrolling body and a
+     *   footer, and takes the reader's full attention, which is the right trade when switching
+     *   organization re-scopes everything on screen.
+     * - `"popover"` / `"sheet"` — pinned to one surface at every width. Useful for a deterministic
+     *   embedded surface or a component test, rarely in a product.
+     *
+     * `auto` and `dialog` are the two RESPONSIVE pairs and differ only in their desktop half; the
+     * mobile half is the same Sheet, because a centred modal on a phone is a Sheet with worse
+     * ergonomics. All four resolve the breakpoint through the shared `useSheetResponsiveMode()`
+     * hook, so a service moves the line once for every overlay.
+     */
+    responsive?: "auto" | "popover" | "sheet" | "dialog";
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    className?: ClassNameProp;
+};
+/**
+ * One app tile in the public {@link AppLauncher} contract.
+ *
+ * A tile is a REAL LINK, always. There is no `onClick`-only entry and no `disabled` entry: an app
+ * the viewer may not open is an app the consumer does not pass. A launcher that renders inert tiles
+ * is a launcher that teaches its users to stop trusting the grid.
+ */
+export type AppLauncherApp = {
+    /** Stable app identifier — the React key, and the `data-app` hook an end-to-end test holds. */
+    id: string;
+    /** Visible app name. It is also the tile's accessible name — the mark is presentational. */
+    name: string;
+    /** The destination. Required, because the tile IS an `<a href>` (WCAG 2.2 / APG: link, not button). */
+    href: string;
+    /**
+     * Owned mark — a Lucide icon, a `<Logo>`, an `<img>`, an `<Avatar>`. Rendered `aria-hidden`;
+     * when omitted the launcher falls back to the first character of `name`, exactly as
+     * `OrgSwitcher` does for an organization with no avatar.
+     */
+    icon?: ReactNode;
+    /** The app the viewer is currently inside. That tile carries `aria-current="page"`. */
+    current?: boolean;
+    /**
+     * The destination leaves this SPA. Such a tile renders a plain `<a target="_blank" rel="noreferrer
+     * noopener">` and DELIBERATELY bypasses `linkComponent`: a client-side router link to another
+     * origin is a router asked to route somewhere it does not own, which is how a launcher entry
+     * turns into a blank screen. Pair it with `labels.externalHint` (WCAG 3.2.5).
+     */
+    external?: boolean;
+};
+/** A labelled section of the launcher grid — the "more from …" band of the Google-style panel. */
+export type AppLauncherGroup = {
+    /** Section heading. Rendered as a real heading and used to name the section's own grid. */
+    label: string;
+    apps: readonly AppLauncherApp[];
+};
+/** Localized copy owned by the consuming product, never hard-coded by the component. */
+export type AppLauncherLabels = {
+    /**
+     * Accessible name of the nine-dot trigger ("Apps" / "アプリ"). A plain string, NOT a function of
+     * the current app the way `OrgSwitcherLabels.trigger` is a function of the organization: the
+     * launcher's trigger shows no current value, so naming one in the trigger would announce a
+     * destination the button does not go to.
+     */
+    trigger: string;
+    /** Panel name — the popover's accessible name and the bottom Sheet's header title. */
+    title: string;
+    empty: string;
+    loading: string;
+    retry?: string;
+    /** Screen-reader suffix for an `external` tile, e.g. "(opens in a new tab)" (WCAG 3.2.5). */
+    externalHint?: string;
+};
+/**
+ * @see AppLauncher — the PLATFORM-scope app switcher that lives in the topbar.
+ *
+ * Related, and repeatedly confused with it:
+ *
+ * - `ServiceLauncherCard` (data-display) is also a launcher tile, but a PAGE-SIZED one: status,
+ *   hostname, plan, an action button, a reason it is locked. It belongs on a service-catalogue
+ *   page, where choosing is a considered act. `AppLauncher`'s tile is bar-sized — mark plus name,
+ *   the whole tile a link — because switching app is a reflex, not a decision. Neither is built
+ *   out of the other; a grid of `ServiceLauncherCard`s inside a popover is the wrong component.
+ * - `AppShellProp.navRail` expresses the SAME platform scope as a docked column. These are the two
+ *   ways to say it, and a product picks ONE: the launcher suits a platform with MANY apps where
+ *   switching is occasional (the Google Workspace shape), the rail suits a single product where
+ *   switching workspace is a constant action worth permanent screen width (the Slack shape).
+ *   Shipping both puts one scope in two places and makes neither authoritative.
+ */
+export type AppLauncherProp = {
+    /** Ungrouped apps, rendered first, with no heading above them. */
+    apps: readonly AppLauncherApp[];
+    /** Labelled sections rendered after `apps`, in order. */
+    groups?: readonly AppLauncherGroup[];
+    labels: AppLauncherLabels;
+    /**
+     * Grid column count. Omit it and the panel keeps the stylesheet's own `--app-launcher-columns`
+     * (3, the Google-launcher shape, declared on `.ui-app-launcher-panel`): the default is where a
+     * theme can reach it, and this prop is the per-instance override written inline on top.
+     */
+    columns?: number;
+    /**
+     * THE framework-router contract, reusing `SidebarLinkComponentProp` VERBATIM — the same type
+     * `Sidebar` and `NavList` take, so a service that already wrote `inertiaSidebarLink(Link)` or
+     * `createSidebarLink(Link, "to")` for its rail hands the same value here. The launcher still
+     * composes the tile (mark, name, `aria-current`, the external hint); the consumer supplies only
+     * the element type. `external` apps bypass it — see {@link AppLauncherApp.external}.
+     */
+    linkComponent?: SidebarLinkComponentProp;
+    loading?: boolean;
+    /** Error content replaces the grid while preserving the trigger and the retry affordance. */
+    error?: ReactNode;
+    onRetry?: () => void;
     /**
      * `"auto"` (default) uses the desktop popover above `--sheet-responsive-breakpoint-width` and a
      * focus-trapped bottom Sheet at/below it — the SAME token that drives `SheetContent
      * responsive="auto"`, resolved through the shared `useSheetResponsiveMode()` hook, so a service
      * moves the drawer line once for every overlay instead of per component.
-     * Explicit modes are useful for deterministic embedded surfaces and component tests.
+     *
+     * No `"dialog"` here, unlike `OrgSwitcher`: a launcher grid is a jump table, and a modal that
+     * takes over the screen to offer nine links is heavier than the errand. Switching ORGANIZATION
+     * re-scopes everything on screen and earns the interruption; opening an app does not.
      */
     responsive?: "auto" | "popover" | "sheet";
     open?: boolean;
@@ -939,6 +1075,8 @@ export type SidebarProp = {
  * configured via THEIR own props and dropped into a slot.
  */
 export type TopbarProp = Omit<React.HTMLAttributes<HTMLDivElement>, "children"> & {
+    height?: "bar" | "auto";
+    pad?: PadProp;
     /** Inline-start cluster — typically the sidebar toggle + a brand mark (`Avatar`) + primary nav. */
     start?: ReactNode;
     /** Center cluster — optional (e.g. a search trigger or a page/entity switcher). */
@@ -964,6 +1102,25 @@ export type TopbarItemProp = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>,
      * Render the bar-cell shape ONTO the child instead of emitting a `<button>` — for a router link,
      * or for a menu/popover trigger that needs to own the element itself.
      */
+    /** Hide below a shared responsive breakpoint, without changing cell height. */
+    hideBelow?: BreakpointProp;
+    /**
+     * Unread count OVERLAID on the cell's glyph — the notification-bell affordance the cell's own use
+     * cases name (gh#398). Pass the CONTENT ONLY, exactly like `SidebarItemProp.badge`: a number, a
+     * string, `"99+"`. Position, size and colour come from `--topbar-item-badge-*`, so the count does
+     * NOT widen the cell (an inline chip pushes the end cluster's shrink budget around every time the
+     * count crosses a digit boundary) and a theme can retune the overlay once.
+     *
+     * The count is not an accessible name: give the cell an `aria-label` that says what the number
+     * means (`aria-label={t("topbar.notifications.unread", { count })}`).
+     */
+    badge?: ReactNode;
+    /**
+     * Emphasis of `badge`. Vocabulary shared VERBATIM with `SidebarItemProp.badgeTone` so one count
+     * pill reads the same in the rail and in the bar: `destructive` when the count is addressed to
+     * the user rather than merely unread.
+     */
+    badgeTone?: SidebarBadgeToneProp;
     asChild?: boolean;
     children?: ReactNode;
     className?: ClassNameProp;

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

@@ -130,10 +130,48 @@ export type PaginationProp = {
      */
     hideOnSinglePage?: boolean;
     simple?: boolean;
+    /**
+     * Ant Design `showQuickJumper`. Adds a "go to page" number field at the inline end of the bar;
+     * committing it (Enter, or the optional Go button) clamps into `[1, pageCount]` and fires
+     * `onValueChange`. Pass an object to supply the confirm button's content.
+     */
+    showQuickJumper?: boolean | {
+        goButton?: React.ReactNode;
+    };
+    /**
+     * Control tier of every button in the bar. `md` (default) is the library's standard control
+     * height; `sm` is Ant Design's `size="small"` pager for a dense table footer.
+     */
+    size?: PaginationSizeProp;
+    /**
+     * Ant Design `align`. Where the pager sits on its own inline axis — `end` (default) keeps the
+     * long-standing table-footer alignment.
+     */
+    align?: PaginationAlignProp;
+    /**
+     * Ant Design `responsive`. `true` (the default) collapses the bar to its `simple` form below the
+     * library's single mobile breakpoint (`useIsMobile`, max-width 767px) instead of leaving a number
+     * strip wider than the phone to scroll — measured at 390px: 224px wide, zero page buttons, no
+     * horizontal overflow. `simple` always wins; `responsive={false}` pins the full pager at every
+     * width.
+     */
+    responsive?: boolean;
     disabled?: DisabledProp;
     className?: ClassNameProp;
     onValueChange?: (page: number, pageSize: number) => void;
 };
+/** @see Pagination — control tier (Ant Design `size`: `small` → `sm`, `middle` → `md`). */
+export type PaginationSizeProp = "sm" | "md";
+/** @see Pagination — inline-axis alignment of the bar (Ant Design `align`, RTL-logical). */
+export type PaginationAlignProp = "start" | "center" | "end";
+/**
+ * @see DropdownMenuContent — Ant Design `placement`, spelled on the LOGICAL inline axis.
+ * antd's names are physical (`bottomLeft`, `topRight`); the same six anchors are `bottomStart`,
+ * `topEnd` and so on here, so an Arabic or Hebrew app anchors on the correct edge with no second
+ * value. Only the block-axis set is offered — see the note on the `placement` prop for why the
+ * inline-side ones (antd `left*` / `right*`) stay on Radix's own physical `side`.
+ */
+export type DropdownMenuPlacementProp = "top" | "topStart" | "topEnd" | "bottom" | "bottomStart" | "bottomEnd";
 export type StepStatusProp = "wait" | "process" | "finish" | "error";
 /** @see StepItem */
 export type StepItemProp = {
@@ -144,6 +182,13 @@ export type StepItemProp = {
     status?: StepStatusProp;
     disabled?: boolean;
 };
+/**
+ * @see Steps — marker/rail appearance.
+ * `dot` IS Ant Design's `progressDot` (antd 6.6.2 deprecates that prop in favour of exactly this
+ * value). `inline` is the compact numbered auth/device progress row. `navigation` is antd's
+ * chevron-sectioned bar: each step becomes a full-width slab pointing at the next one.
+ */
+export type StepsTypeProp = "default" | "dot" | "inline" | "navigation";
 /** @see Steps */
 export type StepsProp = {
     items?: StepItemProp[];
@@ -153,11 +198,18 @@ export type StepsProp = {
     orientation?: "horizontal" | "vertical";
     /**
      * Marker appearance. `inline` renders the compact numbered auth/device progress row without the
-     * icon rail while preserving the same status and current-step semantics.
+     * icon rail while preserving the same status and current-step semantics; `navigation` renders
+     * Ant Design's chevron-sectioned bar.
      */
-    type?: "default" | "dot" | "inline";
+    type?: StepsTypeProp;
     size?: "md" | "sm";
     titlePlacement?: "horizontal" | "vertical";
+    /**
+     * Ant Design `percent` — completion of the CURRENT (`process`) step only, 0–100. Draws a
+     * determinate arc around that step's marker and exposes it to assistive tech as a
+     * `progressbar`. Ignored by `inline`, which has no marker to draw into.
+     */
+    percent?: number;
     /**
      * The glyph between inline steps (`type="inline"` only). `chevron` (default, `›`) is the
      * breadcrumb-flavoured original.
@@ -174,14 +226,72 @@ export type TabItemProp = {
     label: React.ReactNode;
     content: React.ReactNode;
     disabled?: boolean;
+    /** Leading glyph inside the trigger (Ant Design `Tab.icon`). */
+    icon?: React.ReactNode;
+    /**
+     * Ant Design `Tab.closable`. Honoured only by `variant="editable-card"`, where it puts a remove
+     * button in the trigger that calls `onEdit(value, "remove")`. Defaults to `true` there.
+     */
+    closable?: boolean;
+    /** Ant Design `Tab.closeIcon` — replaces the default × on this item's remove button. */
+    closeIcon?: React.ReactNode;
+};
+/**
+ * @see Tabs — trigger-strip appearance. This is Ant Design's `type` spelled in the library's own
+ * `variant` vocabulary: `line`, `card` and `editable-card` are antd's values, `default` is the
+ * library's pill strip (antd has no equivalent).
+ */
+export type TabsVariantProp = "default" | "line" | "card" | "editable-card";
+/**
+ * @see Tabs — which edge the trigger strip parks on. This is Ant Design 6.6.2's `tabPlacement`
+ * (its `tabPosition` is deprecated there), so the inline values are already RTL-logical —
+ * `start`/`end`, never `left`/`right`. Both inline values also flip the tablist to vertical
+ * roving focus (WAI-ARIA APG), which is what `orientation="vertical"` did on its own before.
+ */
+export type TabsPlacementProp = "top" | "bottom" | "start" | "end";
+/**
+ * @see Tabs — Ant Design `tabBarExtraContent`, held to the library's `extra` slot name and to its
+ * logical inline axis: antd's `left`/`right` keys are `start`/`end` here, so an Arabic or Hebrew
+ * app gets the slot on the correct edge with no second code path.
+ */
+export type TabsExtraProp = React.ReactNode | {
+    start?: React.ReactNode;
+    end?: React.ReactNode;
 };
+/**
+ * @see Tabs — Ant Design `onEdit`. It is a NAMED alias rather than an inline signature so the
+ * field reads as one prop everywhere: the catalog-sync guard splits an object type on top-level
+ * commas, and an inline `(target, action) => void` leaks its second PARAMETER as a phantom prop.
+ */
+export type TabsOnEditProp = (target: string | React.MouseEvent<HTMLButtonElement>, action: "add" | "remove") => void;
 /** @see Tabs — high-level tabs with optional `items` array. */
 export type TabsProp = {
     items?: TabItemProp[];
     value?: string;
     defaultValue?: string;
     onValueChange?: (value: string) => void;
-    variant?: "default" | "line" | "card";
+    variant?: TabsVariantProp;
+    /** Ant Design `tabPlacement`. Default `top`. */
+    tabPlacement?: TabsPlacementProp;
+    /** Control tier of the triggers. Default `md`. Ant Design `size` (`small`/`middle`/`large`). */
+    size?: "sm" | "md" | "lg";
+    /** Ant Design `centered` — centre the trigger strip on its own inline axis. */
+    centered?: boolean;
+    /** Ant Design `tabBarExtraContent`, renamed and made logical. @see TabsExtraProp */
+    extra?: TabsExtraProp;
+    /**
+     * Ant Design `destroyOnHidden`. `true` (the default here, and Radix's own behaviour) unmounts a
+     * panel the moment it stops being selected. `false` keeps EVERY panel mounted and only hides the
+     * inactive ones, so a live chart, a scroll position or an unsent form draft survives a tab
+     * switch. The default is deliberately the opposite of antd's, which keeps panels mounted.
+     */
+    destroyOnHidden?: boolean;
+    /** Ant Design `onEdit`. `remove` passes the item's `value`; `add` passes the click event. */
+    onEdit?: TabsOnEditProp;
+    /** Ant Design `addIcon` — replaces the default + on the `editable-card` add button. */
+    addIcon?: React.ReactNode;
+    /** Ant Design `hideAdd` — keep `editable-card`'s remove buttons but drop the add button. */
+    hideAdd?: boolean;
     className?: ClassNameProp;
     listClassName?: ClassNameProp;
     contentClassName?: ClassNameProp;