@godxjp/ui 19.6.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 { AppProviderProp, AppContextValue, AppSettingKind, AppSettingPickerProp, } from "./app.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

@@ -1,7 +1,7 @@
 /** Layout component prop types — @see docs/COMPONENTS.md#layout */
 import type * as React from "react";
 import type { ComponentType, ReactNode, SVGProps } from "react";
-import type { BreadcrumbProp, TitleProp, SubtitleProp, StatusProp, ExtraProp, FooterProp, PageDensityProp, PageContainerVariantProp, CenteredShellWidthProp, CenteredShellAlignProp, CenteredShellPresetProp, ErrorSurfaceModeProp, ErrorSurfaceStatusProp, AuthShellPresetProp, MobileShellHeightProp, OrientationProp, TextAlignProp, TextToneProp, BreakpointProp, GapProp, ClassNameProp, ChildrenProp, IdProp, DisabledProp, DescriptionProp, ActionProp, IconProp, HeadingLevelProp, ToneProp } from "../vocabulary/index.js";
+import type { BreadcrumbProp, TitleProp, SubtitleProp, StatusProp, ExtraProp, FooterProp, PageDensityProp, PageContainerVariantProp, CenteredShellWidthProp, CenteredShellAlignProp, CenteredShellPresetProp, ErrorSurfaceModeProp, ErrorSurfaceStatusProp, AuthShellPresetProp, MobileShellHeightProp, OrientationProp, TextAlignProp, TextToneProp, BreakpointProp, GapProp, PadProp, PadRawProp, ClassNameProp, ChildrenProp, IdProp, DisabledProp, DescriptionProp, ActionProp, IconProp, HeadingLevelProp, ToneProp, WidthProp } from "../vocabulary/index.js";
 import type { EmptyStateToneProp } from "./data-display.prop.js";
 /**
  * Arrangement of the page header's title band and its `extra` slot below the 640px step.
@@ -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,9 +111,66 @@ 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.
+     *
+     * ## Vì sao một design system lại mở cửa thoát
+     *
+     * Vì bịt nó lại không làm thiết kế biến mất — nó chỉ làm cách làm ĐÚNG trở
+     * thành bất hợp pháp. Một bản thiết kế thật dùng 2px, 5px, 6px, 10px; thang
+     * gốc không có bậc nào như thế. Người viết mã khi ấy có ba nước, và cả ba
+     * đều tệ: làm tròn xuống bậc gần nhất (lệch bố cục, và "gần nhất" giữa hai
+     * số cách đều vốn đã là một phép đoán), viết literal (audit chặn), hoặc mở
+     * issue ngược lên rồi CHỜ. Đó là lý do mọi dự án đều lệch design — không
+     * phải người viết cẩu thả.
+     *
+     * ## Cái giá của nó
+     *
+     * Nó phát ra `data-gap-raw` lên DOM. Đó không phải trang trí: nó làm mỗi lần
+     * thoát trở nên ĐẾM ĐƯỢC — grep mã nguồn hoặc quét DOM đều ra, nên một kho
+     * đang trôi dần khỏi thang sẽ tự lộ ra bằng con số thay vì bằng cảm giác.
+     *
+     * ## Khi nào ĐỪNG dùng
+     *
+     * Khi giá trị bạn cần có trong thang. `gap={3}` là 12px và nó đọc theo
+     * `--scaling` của người dùng; `gapRaw={12}` thì không, nó đứng yên khi người
+     * ta phóng to giao diện. Thang có mười bậc — hãy tiêu hết chúng trước.
+     *
+     * Khi có mặt, nó THẮNG `gap`, và `gap` không phát lớp nào nữa để hai bên
+     * không tranh độ đặc hiệu.
+     */
+    gapRaw?: number;
+    /**
+     * Đệm TRONG, theo thang token. Nhận một bậc cho cả bốn cạnh, hoặc một object
+     * theo cạnh LOGIC (`inline`, `block`, `inlineStart`, `blockEnd`…).
+     *
+     * Vì sao có: chạy `ui-audit` trên consumer thật (godx-chat, 08/09/2026) ra
+     * **42 trong 51 lỗi** là `no-utility-spacing`, và gần như tất cả xin cùng
+     * một thứ — padding. `<Flex className="p-3">` không phải cẩu thả; đó là nước
+     * đi duy nhất còn lại khi primitive không có prop đệm. Một prop thiếu đẻ ra
+     * 42 lỗi (gh#408).
+     */
+    pad?: PadProp;
+    /**
+     * Đệm bằng pixel THÔ, cho giá trị ngoài thang — cùng lý do và cùng cái giá
+     * với `gapRaw`: nó để lại `data-pad-raw` trên DOM nên mỗi lần thoát đều đếm
+     * được. Đo trên 51 lỗi ấy: thiết kế cần 2px, 6px, 10px, 14px, 44px, không
+     * bậc nào có.
+     *
+     * Ghi đè `pad` ở TỪNG CẠNH, không phải cả cụm.
+     */
+    padRaw?: PadRawProp;
     align?: FlexAlignProp;
     justify?: FlexJustifyProp;
     wrap?: boolean;
@@ -126,6 +185,31 @@ export type FlexProp = React.HTMLAttributes<HTMLDivElement> & {
      * only on the narrow side (a compact-only affordance). Omit for no attribute and no rule.
      */
     hideFrom?: BreakpointProp;
+    /**
+     * Take the space the siblings leave — the Flex becomes the row's ELASTIC column.
+     *
+     * ## Vì sao là một trục, không phải một tiện ích
+     *
+     * Một hàng thật gần như luôn có hình `cố định | co giãn | cố định`: tên bên trái, thước đo ở
+     * giữa, con số bên phải. Không có trục này thì nước đi duy nhất là `className="flex-1 min-w-0"`
+     * — mà `ui-audit` chặn `no-utility-spacing`, nên cách làm ĐÚNG lại là cách bất hợp pháp.
+     * `PageContainer` đã có `fill` với đúng nghĩa ấy; `Flex` không có là bất đối xứng, không phải
+     * quyết định (gh#405 §2).
+     *
+     * Nó kèm luôn `min-inline-size: 0`. Đó không phải chi tiết thừa: một flex item mặc định không
+     * co nhỏ hơn nội dung, nên một `Text truncate` bên trong sẽ ĐẨY hàng rộng ra thay vì cắt bớt.
+     */
+    fill?: boolean;
+    /**
+     * Bề rộng CỐ ĐỊNH của một cột trong hàng — số là px, chuỗi là mọi CSS length (`"12rem"`, `"40%"`).
+     *
+     * Đi kèm `flex: none`. Một `inline-size` mà sibling vẫn bóp được thì không phải cột, nó chỉ là
+     * một đề nghị — và sáu thanh xếp dọc dưới nhau sẽ bắt đầu ở sáu toạ độ x khác nhau.
+     *
+     * Nó để lại `data-width-raw` trên DOM, cùng lý do với `gapRaw`/`padRaw`: mỗi số đo cứng viết ở
+     * call site đều ĐẾM ĐƯỢC, nên một kho đang trôi khỏi thang tự lộ ra bằng con số.
+     */
+    width?: WidthProp;
 };
 /** Container column counts; omitted steps inherit from the previous step. Base defaults to 1. */
 export type ResponsiveGridColumnsProp = number | {
@@ -139,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
@@ -188,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;
@@ -213,11 +299,50 @@ export type AppShellProp = {
      * belonging to it.
      */
     topbarSpan?: "content" | "full";
+    /**
+     * A SECOND navigation column, narrower than `sidebar` and placed before it — the
+     * workspace/organization switcher shape (Slack, Teams, Discord). Passing a node adds the track;
+     * omitting it leaves the two-column shell exactly as it was. Width is
+     * `--app-shell-nav-rail-width` (3.5rem — deliberately NOT the collapsed sidebar's 4rem: at equal
+     * widths the two navigation tracks fuse into one block the moment the sidebar collapses).
+     *
+     * THE THREE COLUMNS ARE THREE SCOPES, and the scope — not the free space — is what decides where
+     * a control goes. The rail is PLATFORM scope: whatever is true across every app in the
+     * organization (which organization, which app, notifications, messages, events, organization
+     * settings, cross-app shortcuts). The sidebar is APP scope: this app's own sections. The topbar
+     * is PAGE scope: where you are and what you can do here.
+     *
+     * So app navigation never goes in the rail, a platform switch never goes in the sidebar, and a
+     * destination that would fit both belongs to the rail — because it survives changing apps. A
+     * rail that repeats the sidebar's own entries is a second chrome band carrying the first one's
+     * rank, just vertical instead of horizontal.
+     *
+     * Orthogonal to `topbarSpan`: the rail says how many navigation COLUMNS there are, `topbarSpan`
+     * says how far the BAR reaches, and every combination of the two is a real shape, so they never
+     * need to be reconciled. `sidebarCollapsed` folds the sidebar track only — the rail keeps its
+     * width, which is what keeps its destinations reachable while collapsed.
+     *
+     * Building this by hand inside the single `sidebar` slot is the trap it replaces: `Sidebar`
+     * renders `.sb-root { display: contents }`, so two of them dropped side by side dissolve into
+     * one flex row and both collapse to zero unless each is separately wrapped — and sizing the one
+     * available track for two columns means overriding `--app-shell-sidebar-width`, which is how a
+     * shipped consumer moved its content edge by 64px between routes.
+     */
+    navRail?: ReactNode;
+    /**
+     * Accessible name for the `navRail` landmark. Defaults to the localized "Workspaces".
+     *
+     * The rail and the sidebar are two `complementary` landmarks on one page, so ARIA requires them
+     * to be tellable apart by name; the shell always supplies both defaults rather than requiring
+     * this prop, so the two columns of equal rank behave the same way.
+     */
+    navRailLabel?: string;
     /**
      * Navigation shown in the mobile drawer at the DXS 900px breakpoint, where the docked sidebar is
-     * hidden. 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).
+     * hidden. Defaults to `navRail` followed by `sidebar` — both docked columns are hidden at that
+     * width, so a default of `sidebar` alone would silently strip every app-level destination the
+     * rail carries. 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". */
@@ -354,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;
     /**
@@ -756,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;
@@ -826,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). */
@@ -842,7 +1093,7 @@ export type TopbarProp = Omit<React.HTMLAttributes<HTMLDivElement>, "children">
  * It exists because the alternative is a `Button`, and a Button in a bar is a control that landed
  * in the bar rather than a part of it — a pill of its own height floating in a taller strip, with
  * its own hover surface and its own focus ring drawn around that pill. Fluent, SLDS, Atlassian and
- * antd's ProLayout all draw a top-bar trigger the other way: the cell is as tall as the bar, its
+ * and enterprise pro-layouts all draw a top-bar trigger the other way: the cell is as tall as the bar, its
  * hover is the bar's own surface, and the focus mark is hosted INSIDE the cell because a
  * full-bleed cell has nothing outside itself to ring.
  */
@@ -851,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;