@godxjp/ui 20.0.0 → 20.2.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;
@@ -73,6 +89,19 @@ export type ButtonProp = React.ButtonHTMLAttributes<HTMLButtonElement> & {
     /** Corner shape — `default` (control radius) · `pill` (fully rounded) · `sharp` (square). */
     shape?: ShapeProp;
     fullWidth?: boolean;
+    /**
+     * Take the space the siblings leave, and let a long label ELLIPSE instead of widening the row —
+     * the same axis `Flex` calls `fill`, for the same reason.
+     *
+     * Button ships `flex-shrink: 0`, right almost everywhere and wrong in a constrained bar: an
+     * account menu holding an avatar plus a person's name keeps its full width while the cluster
+     * clips it, so a keyboard user tabs to a control they cannot see (SC 2.4.7). Until this axis
+     * existed the only move was `className="min-w-0 flex-1"`, which ui-audit blocks — and which this
+     * package's own Topbar guidance recommended, so the docs prescribed the utility the audit forbids.
+     *
+     * Sets `flex: 1 1 auto` and `min-inline-size: 0`; pair it with a `<Text truncate>` label.
+     */
+    fill?: boolean;
     /** Allow a text button to grow vertically for multi-line labels. */
     wrap?: boolean;
     /** Logical content alignment, especially for full-width collection actions. */

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;
@@ -324,6 +336,30 @@ export type AppShellProp = {
      * 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.
      */
+    /**
+     * WHICH EDGE the rail sits on. `start` (default) and `end` are the INLINE edges — logical, so an
+     * RTL document mirrors them without a `[dir]` rule; `top` and `bottom` are the block edges, where
+     * the rail becomes a full-measure horizontal strip and the shell grows a ROW instead of a column.
+     *
+     * The scope contract does not move with it: wherever it sits, the rail is PLATFORM scope. The
+     * edge is a presentation choice — a docked column reads as permanent chrome (Slack), a bottom
+     * strip reads as the phone/tab-bar shape, a top strip as a platform band above the app's own bar.
+     * Thickness follows the orientation: `--app-shell-nav-rail-width` as a column,
+     * `--app-shell-nav-rail-height` as a strip.
+     *
+     * Collapsing the sidebar folds the sidebar track only, at every position.
+     */
+    navRailPosition?: "start" | "end" | "top" | "bottom";
+    /**
+     * Rail content pinned to its FAR end — the counterpart of `Sidebar`'s `footer`, and the tray end
+     * of a taskbar: settings, appearance, the account glyph. It follows the orientation, so it is the
+     * bottom of a column and the inline-end of a strip, and it stays put while `navRail` scrolls.
+     *
+     * A slot rather than "whatever you put last", because pinning it needs an auto margin on the
+     * right axis — geometry that would otherwise land in consumer CSS, which this library does not
+     * accept. Ignored when `navRail` is not passed: there is no rail to pin anything to.
+     */
+    navRailEnd?: ReactNode;
     navRailLabel?: string;
     /**
      * Navigation shown in the mobile drawer at the DXS 900px breakpoint, where the docked sidebar is
@@ -386,6 +422,22 @@ export type AuthShellProp = {
      * flow geometry.
      */
     measure?: "default" | "wide";
+    /**
+     * Block-axis placement of the auth column, ORTHOGONAL to `preset` the way `variant` is: a preset
+     * owns the page MEASURE (card width, inline gutters, section rhythm), `align` owns where that
+     * column sits vertically.
+     *
+     * Omit it to keep the preset's own choice — `"login"` and `"registration"` anchor so a
+     * requester/identity line that wraps to two lines cannot move the card, every other preset
+     * centres. Pass `"center"` for a vertically centred column (the block-start inset collapses to
+     * the preset's block-end one, desktop and mobile, so the padding is symmetric) or `"anchored"`
+     * for a top-anchored one. This replaces re-declaring a preset's offset tokens from consumer CSS.
+     *
+     * HAZARD on a tall flow: a vertically centred tall card overflows ABOVE the scroll origin on a
+     * short viewport, putting its first field out of reach. That is why `"registration"` anchors by
+     * default; `"center"` is legal there but is the caller's judgement.
+     */
+    align?: "anchored" | "center";
     /**
      * Vertical density scoped to auth-card descendants. The canonical variant defaults to
      * `"compact"`; the default variant defaults to `"comfortable"`.
@@ -467,6 +519,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,14 +925,170 @@ 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.
+     *
+     * `responsive="fullscreen"` steps that DEFAULT up with the surface — 3 · 4 · 5 · 6 on the house
+     * container ladder — because a fixed three columns on a full viewport is three columns of tiles
+     * and a screen of nothing. Passing `columns` still wins everywhere: an inline custom property
+     * beats every stylesheet rule, so a stated count is a stated count on both surfaces.
+     */
+    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.
+     *
+     * `"fullscreen"` is the LAUNCHPAD: one full-viewport surface, the page behind it blurred, the
+     * grid floating on that ground at tile size — the macOS Launchpad / Windows Start shape. It is
+     * pinned at every width, because a start surface that becomes a popover on a wide screen is two
+     * different products.
+     *
+     * WHEN IT IS RIGHT, AND WHEN IT IS NOT. This prop used to say a modal was always wrong here:
+     * "a launcher grid is a jump table, and a modal that takes over the screen to offer nine links
+     * is heavier than the errand." That reasoning is sound for a launcher in ONE application's
+     * topbar, where the grid is a shortcut away from the work on screen and the work should stay
+     * visible. It does not hold for a PLATFORM start bar — a strip that is present in every service,
+     * whose launcher is the primary way to move between products rather than a shortcut. There the
+     * grid IS the errand, the page behind it is the thing being left, and the interruption is the
+     * point. Keep `"auto"` for a topbar launcher; reach for `"fullscreen"` for a dock.
+     */
+    responsive?: "auto" | "popover" | "sheet" | "fullscreen";
+    /**
+     * The BOX the trigger takes — the same split `AppSettingToggle` draws, and for the same reason.
+     * `bar` (default) is a `TopbarItem`: a cell as tall as the bar, whose hover is the bar's own
+     * surface. `icon` is a square ghost `Button`, for chrome that is NOT a bar — a nav rail, a card
+     * header, a toolbar. A `TopbarItem` outside a bar has nothing to bleed to: it stretches to a
+     * container that never set a band height, and its squared corners and full-bleed hover read as a
+     * broken cell. The panel, the grid and the responsive contract are identical either way.
+     */
+    appearance?: "bar" | "icon";
+    /**
+     * Which side of the trigger the panel opens on, and how it aligns to it. Both default from
+     * `appearance` — a bar drops the grid below and aligns to the bar's end; anything else opens to
+     * the inline-end aligned to the trigger's start.
+     *
+     * State them when the chrome can be RE-DOCKED. `appearance` says the trigger is not in a bar; it
+     * cannot say which way is out, and a rail pinned to the top edge still opens downward. Measured
+     * without this: a launcher in a top strip opened sideways and left the panel 440px from the
+     * trigger it belonged to.
      */
-    responsive?: "auto" | "popover" | "sheet";
+    side?: "top" | "right" | "bottom" | "left";
+    align?: "start" | "center" | "end";
     open?: boolean;
     onOpenChange?: (open: boolean) => void;
     className?: ClassNameProp;
@@ -890,7 +1102,21 @@ export type SidebarProp = {
     sections?: SidebarSectionProp[];
     product?: SidebarProductProp;
     onProductClick?: () => void;
-    brand?: ReactNode;
+    /**
+     * Header slot ABOVE the navigation, replacing `product`.
+     *
+     * Pass a FUNCTION to follow the EFFECTIVE collapsed state. A plain node cannot: `AppShell` hands
+     * the same Sidebar to the drawer and the drawer un-collapses the rows (see `NavSurface`), so a
+     * node built from the consumer's own `collapsed` boolean renders a glyph-only lockup inside a
+     * full-width drawer. The escape hatch consumers reach for is a SECOND hand-built `Sidebar` in
+     * `AppShell.mobileNav` — and that override is precisely what switches off `railInDrawer`, so the
+     * `navRail` silently stops reaching mobile. The function is called with the surface-effective
+     * value, which removes the reason to build the second node at all.
+     *
+     * SCOPE: this is the APP's brand lockup. A PLATFORM switch (which organization, which app) does
+     * not belong here — see AppShell's `navRail` for where it goes and why.
+     */
+    brand?: ReactNode | ((collapsed: boolean) => ReactNode);
     collapsed?: boolean;
     children?: ChildrenProp;
     /**
@@ -939,6 +1165,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 +1192,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;