@godxjp/ui 19.6.0 → 20.0.0

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

@@ -27,6 +27,23 @@ export type ProseProp = {
     children?: ChildrenProp;
 };
 import type { ActionProp, ClassNameProp, DescriptionProp, IconProp, TitleProp, ColumnDefProp, GetRowIdProp, OnRowClickProp, OnSelectChangeProp, OnSortChangeProp, OnTableDensityChangeProp, SelectedIdsProp, SortStateProp, TableDensityProp, TablePresetProp, BreakpointProp, DensityProp, ChildrenProp, ToneProp, AvatarShapeProp, HeadingLevelProp, HandlerProp, SizeProp, LabelProp, IdProp, DescriptionsLayoutProp } from "../vocabulary/index.js";
+/**
+ * One key in a `Legend`: a tone, and the words that tone stands for.
+ *
+ * `label` is required and there is no way to omit it. That is the point of a key — colour alone
+ * never carries meaning (WCAG 1.4.1), and a legend whose entries could be wordless would be a
+ * component that lets a caller build the exact failure it exists to prevent.
+ */
+export type LegendItemProp = {
+    /** The tone this key explains — the SAME tone the marks it stands for are drawn in. */
+    tone: ToneProp;
+    label: LabelProp;
+};
+/** @see Legend — the key for a colour-coded surface: a breakdown bar, a chart, a status column. */
+export type LegendProp = Omit<React.HTMLAttributes<HTMLUListElement>, "children"> & {
+    items: LegendItemProp[];
+    className?: ClassNameProp;
+};
 /** @see EmptyState */
 /**
  * Semantic intent of the EmptyState icon medallion — a subset of the shared `ToneProp` vocabulary

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

@@ -8,7 +8,7 @@ import type { DateRange } from "react-day-picker";
 import type * as React from "react";
 import type { UploadFileItem } from "../../components/data-entry/upload-types.js";
 import type { FieldA11yProps } from "../../lib/field-a11y.js";
-import type { ClassNameProp, DisabledProp, EmptyMessageProp, ErrorBagProp, ErrorProp, HelperProp, IdProp, LabelProp, NameProp, OnValueChangeProp, OnSearchChangeProp, OpenProp, OnOpenChangeProp, PlaceholderProp, RequiredProp, ValueProp, DefaultValueProp, FormLayoutProp, WidthProp, BreakpointProp, DensityProp, SizeProp, TitleProp } from "../vocabulary/index.js";
+import type { ClassNameProp, ControlWidthProp, DisabledProp, EmptyMessageProp, ErrorBagProp, ErrorProp, HelperProp, IdProp, LabelProp, NameProp, OnValueChangeProp, OnSearchChangeProp, OpenProp, OnOpenChangeProp, PlaceholderProp, RequiredProp, ValueProp, DefaultValueProp, FormLayoutProp, WidthProp, BreakpointProp, DensityProp, SizeProp, TitleProp } from "../vocabulary/index.js";
 import type { ResponsiveGridColumnsProp } from "./layout.prop.js";
 /** One-outline-per-group appearance for the compound InputOTP control. */
 export type InputOTPGroupAppearanceProp = "slots" | "grouped";
@@ -228,7 +228,7 @@ export type SearchInputProp = FieldA11yProps & {
 };
 /** @see Checkbox — extends Radix checkbox root props. */
 export type CheckboxProp = React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>;
-/** Shared option row — Ant Design `CheckboxOptionType`. */
+/** Shared option row — the conventional `CheckboxOptionType` shape. */
 export type ChoiceOptionProp = {
     label: React.ReactNode;
     value: string;
@@ -283,6 +283,34 @@ export type SliderProp = React.ComponentPropsWithoutRef<typeof SliderPrimitive.R
 export type CalendarProp = DayPickerProps & CalendarFooterProp & {
     /** Replaces the built-in footer actions. */
     footer?: React.ReactNode;
+    /**
+     * How the grid claims horizontal space. Default `auto` shrink-wraps to seven fixed day
+     * columns — the shape a picker popover needs, because the panel is shrink-to-fit and takes
+     * ITS width from the calendar inside it.
+     *
+     * `full` is for an EMBEDDED calendar — a shift board, a booking month — where the calendar is
+     * the content of a card rather than a dropdown. It stacks the months, lets each one grow, and
+     * lets the day cells share the row.
+     *
+     * Opt-in on purpose, and the default is load-bearing: making the calendar fluid globally was
+     * measured to collapse the DatePicker popover from 250px to 157.8px with 18.8px day cells.
+     * `Calendar` and `DatePicker` want opposite answers here, which is why the enterprise
+     * libraries split them too
+     * (`Calendar fullscreen` is 100% of its container; the DatePicker dropdown is a fixed 288px).
+     */
+    width?: Extract<ControlWidthProp, "auto" | "full">;
+    /**
+     * Rule the grid: one border per day cell, weekday header included.
+     *
+     * NOT a box around the calendar — that is what `Card` is for, and nesting one inside a section
+     * card was measured on a real page as two rounded edges 16px apart with both paddings stacked.
+     * What a month grid needs is the ruling BETWEEN days, so a week reads as a row of cells the
+     * eye can track across.
+     *
+     * Default `false`, because a picker popover wants the opposite: floating day buttons with no
+     * ruling, so the selected day is the only shape in the panel.
+     */
+    bordered?: boolean;
 };
 /** Footer actions shared by Calendar and the pickers that embed it. Both default to off. */
 export type CalendarFooterProp = {
@@ -430,10 +458,10 @@ export type SearchSelectProp = {
     /** Remote fetcher — debounced search + infinite-scroll pagination call into this. Provide this
      *  OR `options`. */
     loadOptions?: (params: SearchSelectLoadParamsProp) => Promise<SearchSelectLoadResultProp>;
-    /** Custom per-option renderer (Ant-Design style). Defaults to label + optional sublabel. */
+    /** Custom per-option renderer. Defaults to label + optional sublabel. */
     renderOption?: (option: SearchSelectOptionProp) => React.ReactNode;
     /**
-     * Custom renderer for the SELECTED value shown on the trigger (Ant Design `labelRender`).
+     * Custom renderer for the SELECTED value shown on the trigger (the conventional `labelRender`).
      * Receives the value, the resolved label, and the full option when it is loaded (undefined for
      * an async preset whose page hasn't arrived).
      */

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

@@ -6,5 +6,5 @@ export type { ChartDatum, ChartSeriesProp, LineChartProp, BarChartProp, AreaChar
 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 { 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.
@@ -112,6 +112,55 @@ export type FlexProp = React.HTMLAttributes<HTMLDivElement> & {
     as?: "div" | "span";
     direction?: FlexDirectionProp;
     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 +175,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 | {
@@ -213,11 +287,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". */
@@ -842,7 +955,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.
  */

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

@@ -168,7 +168,7 @@ export type StepsProp = {
 };
 /** @see Steps — inline separator glyph. */
 export type StepsSeparatorProp = "chevron" | "arrow";
-/** Tab pane — Ant Design `items` entry. */
+/** Tab pane — the conventional `items` entry. */
 export type TabItemProp = {
     value: string;
     label: React.ReactNode;

package/dist/props/registry.d.ts

@@ -289,6 +289,11 @@ export declare const VOCABULARY_REGISTRY: {
         readonly category: "interaction";
         readonly description: "AppSettingPicker trigger presentation: labeled (icon + value) | icon (square icon-only topbar trigger) | inline (compact text footer trigger)";
     };
+    readonly AppSettingToggleAppearanceProp: {
+        readonly file: "vocabulary/interaction.prop.ts";
+        readonly category: "interaction";
+        readonly description: "AppSettingToggle box: bar (default — a full-height CELL of the bar, TopbarItem shape) | icon (square --control-height ghost button for anywhere that is not a bar)";
+    };
     readonly ShapeProp: {
         readonly file: "vocabulary/interaction.prop.ts";
         readonly category: "interaction";
@@ -491,6 +496,11 @@ export declare const COMPONENT_PROP_REGISTRY: {
             readonly reason: "Trigger DENSITY for the picker only (sm control tier + content-hugging width) — orthogonal to `appearance`, and not the page-level DensityProp scope.";
         }];
     };
+    readonly AppSettingToggleProp: {
+        readonly group: "app";
+        readonly file: "components/app.prop.ts";
+        readonly vocabulary: readonly ["ValueProp", "OnValueChangeProp", "DisabledProp", "IdProp", "ClassNameProp", "AppSettingToggleAppearanceProp"];
+    };
     readonly PageContainerHeaderLayoutProp: {
         readonly group: "layout";
         readonly file: "components/layout.prop.ts";
@@ -1057,7 +1067,7 @@ export declare const COMPONENT_PROP_REGISTRY: {
     readonly CalendarProp: {
         readonly group: "data-entry";
         readonly file: "components/data-entry.prop.ts";
-        readonly vocabulary: readonly [];
+        readonly vocabulary: readonly ["ControlWidthProp"];
     };
     readonly CalendarFooterProp: {
         readonly group: "data-entry";
@@ -1771,7 +1781,17 @@ export declare const COMPONENT_PROP_REGISTRY: {
     readonly ProgressProp: {
         readonly group: "data-display";
         readonly file: "components/data-display/progress.tsx";
-        readonly vocabulary: readonly ["ValueProp", "LabelProp", "ClassNameProp"];
+        readonly vocabulary: readonly ["ValueProp", "LabelProp", "ToneProp", "ClassNameProp"];
+    };
+    readonly LegendItemProp: {
+        readonly group: "data-display";
+        readonly file: "components/data-display.prop.ts";
+        readonly vocabulary: readonly ["ToneProp", "LabelProp"];
+    };
+    readonly LegendProp: {
+        readonly group: "data-display";
+        readonly file: "components/data-display.prop.ts";
+        readonly vocabulary: readonly ["ClassNameProp"];
     };
     readonly CodeBlockProp: {
         readonly group: "data-display";

package/dist/props/registry.js

@@ -288,6 +288,11 @@ const VOCABULARY_REGISTRY = {
     category: "interaction",
     description: "AppSettingPicker trigger presentation: labeled (icon + value) | icon (square icon-only topbar trigger) | inline (compact text footer trigger)"
   },
+  AppSettingToggleAppearanceProp: {
+    file: "vocabulary/interaction.prop.ts",
+    category: "interaction",
+    description: "AppSettingToggle box: bar (default \u2014 a full-height CELL of the bar, TopbarItem shape) | icon (square --control-height ghost button for anywhere that is not a bar)"
+  },
   ShapeProp: {
     file: "vocabulary/interaction.prop.ts",
     category: "interaction",
@@ -495,6 +500,18 @@ const COMPONENT_PROP_REGISTRY = {
       }
     ]
   },
+  AppSettingToggleProp: {
+    group: "app",
+    file: "components/app.prop.ts",
+    vocabulary: [
+      "ValueProp",
+      "OnValueChangeProp",
+      "DisabledProp",
+      "IdProp",
+      "ClassNameProp",
+      "AppSettingToggleAppearanceProp"
+    ]
+  },
   PageContainerHeaderLayoutProp: {
     group: "layout",
     file: "components/layout.prop.ts",
@@ -1204,7 +1221,11 @@ const COMPONENT_PROP_REGISTRY = {
     file: "components/data-entry.prop.ts",
     vocabulary: ["DisabledProp"]
   },
-  CalendarProp: { group: "data-entry", file: "components/data-entry.prop.ts", vocabulary: [] },
+  CalendarProp: {
+    group: "data-entry",
+    file: "components/data-entry.prop.ts",
+    vocabulary: ["ControlWidthProp"]
+  },
   CalendarFooterProp: {
     group: "data-entry",
     file: "components/data-entry.prop.ts",
@@ -1983,7 +2004,17 @@ const COMPONENT_PROP_REGISTRY = {
   ProgressProp: {
     group: "data-display",
     file: "components/data-display/progress.tsx",
-    vocabulary: ["ValueProp", "LabelProp", "ClassNameProp"]
+    vocabulary: ["ValueProp", "LabelProp", "ToneProp", "ClassNameProp"]
+  },
+  LegendItemProp: {
+    group: "data-display",
+    file: "components/data-display.prop.ts",
+    vocabulary: ["ToneProp", "LabelProp"]
+  },
+  LegendProp: {
+    group: "data-display",
+    file: "components/data-display.prop.ts",
+    vocabulary: ["ClassNameProp"]
   },
   CodeBlockProp: {
     group: "data-display",

package/dist/props/vocabulary/content.prop.d.ts

@@ -14,7 +14,7 @@ export type DescriptionProp = React.ReactNode;
  * Owned by the canonical page-header contract so consumers never hand-lay a badge row.
  */
 export type StatusProp = React.ReactNode;
-/** Top-right action slot on pages (Ant Design `extra`). */
+/** Top-right action slot on pages (the conventional `extra` slot). */
 export type ExtraProp = React.ReactNode;
 /** Bottom action bar on pages — save/cancel, pagination controls. */
 export type FooterProp = React.ReactNode;

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

@@ -1,7 +1,7 @@
 /** Barrel — all vocabulary prop types. */
 export type { ClassNameProp, ChildrenProp, IdProp, OpenProp, DefaultOpenProp, OnOpenChangeProp, HandlerProp, PendingProp, RequiredProp, DisabledProp, LabelProp, HelperProp, ErrorProp, ErrorBagProp, PlaceholderProp, NameProp, ValueProp, DefaultValueProp, OnValueChangeProp, OnChangeProp, OnClickProp, AsChildProp, FlushProp, WidthProp, ControlWidthProp, } from "./shared.prop.js";
 export type { TitleProp, SubtitleProp, StatusProp, DescriptionProp, ExtraProp, FooterProp, ActionProp, IconProp, ConfirmLabelProp, CancelLabelProp, ActionsProp, EmptyMessageProp, } from "./content.prop.js";
-export type { PageDensityProp, PageContainerVariantProp, CenteredShellWidthProp, CenteredShellAlignProp, CenteredShellPresetProp, ErrorSurfaceModeProp, ErrorSurfaceStatusProp, AuthShellPresetProp, MobileShellHeightProp, OrientationProp, TableDensityProp, DensityProp, GapProp, } from "./layout.prop.js";
-export type { ButtonVariantProp, ButtonSizeProp, BadgeVariantProp, AppSettingPickerAppearanceProp, ShapeProp, AvatarShapeProp, TextSizeProp, TextToneProp, FontWeightProp, HeadingLevelProp, TextAlignProp, SizeProp, FormLayoutProp, DescriptionsLayoutProp, BreakpointProp, ConfirmVariantProp, ToneProp, AlertVariantProp, SortDirectionProp, ColumnAlignProp, SortStateProp, RevealDelayProp, ActivityVariantProp, ActivityAnnounceProp, } from "./interaction.prop.js";
+export type { PageDensityProp, PageContainerVariantProp, CenteredShellWidthProp, CenteredShellAlignProp, CenteredShellPresetProp, ErrorSurfaceModeProp, ErrorSurfaceStatusProp, AuthShellPresetProp, MobileShellHeightProp, OrientationProp, TableDensityProp, DensityProp, GapNameProp, PadProp, PadRawProp, PadSides, GapProp, GapStepProp, } from "./layout.prop.js";
+export type { ButtonVariantProp, ButtonSizeProp, BadgeVariantProp, AppSettingPickerAppearanceProp, AppSettingToggleAppearanceProp, ShapeProp, AvatarShapeProp, TextSizeProp, TextToneProp, FontWeightProp, HeadingLevelProp, TextAlignProp, SizeProp, FormLayoutProp, DescriptionsLayoutProp, BreakpointProp, ConfirmVariantProp, ToneProp, AlertVariantProp, SortDirectionProp, ColumnAlignProp, SortStateProp, RevealDelayProp, ActivityVariantProp, ActivityAnnounceProp, } from "./interaction.prop.js";
 export type { BreadcrumbItemProp, BreadcrumbProp } from "./navigation.prop.js";
 export type { GetRowIdProp, OnRowClickProp, ColumnDefProp, TablePresetProp, TableColumnPriorityProp, TableCellIndentProp, SelectedIdsProp, OnSelectChangeProp, OnTableDensityChangeProp, OnSortChangeProp, OnSearchChangeProp, OnClearFiltersProp, HasActiveFiltersProp, StickyProp, } from "./data.prop.js";

package/dist/props/vocabulary/interaction.prop.d.ts

@@ -39,8 +39,24 @@ export type BadgeVariantProp = "default" | "secondary" | "outline" | "dashed";
  *   STRUCTURALLY drops the value text and the picker's owned trigger width, keeping the localized
  *   `aria-label`, focus ring, keyboard behaviour and a `--control-height` tap target (which is
  *   ≥44px on coarse/touch pointers per Rule #24) — so consumers never hide internal nodes via CSS.
+ * - `bar` — the same structural drops as `icon`, re-shaped as a CELL OF THE BAR rather than a
+ *   control dropped into it: it fills the bar's height and squares its corners, so the hover
+ *   surface paints the whole strip. Reach for it in a `Topbar` slot or AppShell's own bar, where
+ *   `icon` leaves a --control-height pill floating in a taller strip and reads as a different
+ *   control family from the bar's own chrome (`TopbarItem`).
  */
-export type AppSettingPickerAppearanceProp = "labeled" | "icon" | "inline";
+export type AppSettingPickerAppearanceProp = "labeled" | "icon" | "bar" | "inline";
+/**
+ * AppSettingToggle presentation. The toggle has no menu, so it has no `labeled`/`inline` form —
+ * the two members here are the two BOXES a one-tap cycler can take.
+ * - `bar` (default) — a CELL of the bar (`TopbarItem`): full bar height, the bar's own hover
+ *   surface, square corners (`--topbar-item-radius`). This is the canonical placement, which is
+ *   why it is the default: a toggle exists for a top bar.
+ * - `icon` — a square `--control-height` ghost button for everywhere that is NOT a bar (a
+ *   settings row, a card header). In a taller bar this leaves a pill floating mid-strip, which is
+ *   the defect `bar` exists to avoid.
+ */
+export type AppSettingToggleAppearanceProp = "bar" | "icon";
 /** Button size preset. */
 export type SizeProp = "xs" | "sm" | "md" | "lg";
 /** Button size preset; icon-only sizes are a documented Button subset. */

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

@@ -59,7 +59,63 @@ export type AuthShellPresetProp = "default" | "login" | "registration" | "device
  * Without it those stacks had to carry `gap="xs"`, which is a visual change forced by a missing
  * step rather than by design.
  */
-export type GapProp = "none" | "xs" | "sm" | "md" | "lg" | "xl";
+export type GapNameProp = "none" | "xs" | "sm" | "md" | "lg" | "xl";
+/**
+ * Bậc SỐ, ánh xạ thẳng vào `--space-{n}` của thang gốc.
+ *
+ * Vì sao cần, dù đã có sáu tên ở trên: thang gốc có MƯỜI bậc
+ * (0·4·8·12·16·20·24·32·40·48px) nhưng lớp tên chỉ với tới năm trong số đó.
+ * `md` là 16px, `lg` là 24px — và `--space-5` (20px) tồn tại mà không có đường
+ * nào gọi tới. Người viết mã gặp một thiết kế 20px thì không còn nước đi hợp
+ * lệ nào: làm tròn thì lệch, viết literal thì `no-arbitrary-spacing` chặn.
+ *
+ * Bậc số KHÔNG theo trục — `gap={3}` là 12px ở cả hàng lẫn cột. Đó là chủ ý:
+ * tên mang ý ĐỊNH ("cách nhau vừa phải, tuỳ trục"), số mang GIÁ TRỊ ("đúng
+ * 12px"). Trộn hai nghĩa vào một thang là lý do thang cũ vừa thô vừa khó đoán.
+ */
+export type GapStepProp = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | 12;
+export type GapProp = GapNameProp | GapStepProp;
+/**
+ * Đệm TRONG của một primitive bố cục.
+ *
+ * ## Vì sao tồn tại
+ *
+ * Chạy `ui-audit` trên consumer thật (godx-chat, 08/09/2026): **42 trong 51
+ * lỗi** là `no-utility-spacing`, và gần như toàn bộ chúng xin cùng một thứ —
+ * padding. `<Flex className="p-3">` không phải người viết 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, và mỗi lỗi ấy trước nay chỉ có hai đường: để đỏ, hoặc mở issue rồi chờ.
+ *
+ * ## Vì sao ba tầng chứ không phải một
+ *
+ * Đo trên chính 51 lỗi ấy: có `p-3` (bốn cạnh), có `px-4`/`py-1` (theo trục),
+ * và **16 dòng cần cạnh riêng** (`pt-2.5` khác `pb-2.5` trên cùng phần tử).
+ * Một prop chỉ nhận một số sẽ không phủ nổi, và ép người ta quay lại class.
+ *
+ * Tên cạnh là LOGIC (`inlineStart`, `blockEnd`), không phải vật lý (`left`,
+ * `top`) — cùng luật với `ms-`/`me-` mà audit đang bắt, và là thứ giữ cho giao
+ * diện RTL không phải viết lại.
+ */
+export type PadSides<T> = T | {
+    /** Hai cạnh theo trục viết (trái+phải ở LTR). */
+    inline?: T;
+    /** Hai cạnh theo trục khối (trên+dưới). */
+    block?: T;
+    inlineStart?: T;
+    inlineEnd?: T;
+    blockStart?: T;
+    blockEnd?: T;
+};
+/** Đệm theo thang token — bậc tên hoặc bậc số, cùng thang với `gap`. */
+export type PadProp = PadSides<GapProp>;
+/**
+ * Đệm bằng pixel THÔ, cho giá trị ngoài thang.
+ *
+ * Cùng lý do với `gapRaw`, và cùng cái giá: nó để lại `data-pad-raw` trên DOM
+ * nên mỗi lần thoát đều đếm được. Thiết kế thật cần 2px, 6px, 10px, 14px, 44px
+ * — thang không có bậc nào như thế, và bịt lại không làm chúng biến mất.
+ */
+export type PadRawProp = PadSides<number>;
 /** DataTable row density subset. */
 export type TableDensityProp = Exclude<DensityProp, "default">;
 /**