@godxjp/ui 19.4.2 → 19.5.0

package/dist/components/layout/index.js

@@ -1,6 +1,7 @@
 import { PageContainer } from "./page-container.js";
 import { Flex } from "./flex.js";
 import { ResizablePanel, ResizablePanelGroup, ResizableHandle } from "./resizable.js";
+import { NavList } from "./nav-list.js";
 import { AppShell } from "./app-shell.js";
 import { OrgSwitcher } from "./org-switcher.js";
 import { AuthShell } from "./auth-shell.js";
@@ -16,6 +17,7 @@ import { ErrorSurface } from "./error-surface.js";
 import { Breadcrumb } from "./breadcrumb.js";
 import { createSidebarLink, Sidebar, SidebarHeader, SidebarItem, SidebarSection } from "./sidebar.js";
 import { Topbar } from "./topbar.js";
+import { TopbarItem } from "./topbar-item.js";
 import { ResponsiveGrid } from "./responsive-grid.js";
 import { MasterDetail } from "./master-detail.js";
 import { SplitPane } from "./split-pane.js";
@@ -40,6 +42,7 @@ export {
   LegalDocumentShell,
   MasterDetail,
   MobileShell,
+  NavList,
   OrgSwitcher,
   PageContainer,
   ResizableHandle,
@@ -54,5 +57,6 @@ export {
   SidebarSection,
   SplitPane,
   Topbar,
+  TopbarItem,
   createSidebarLink
 };

package/dist/components/layout/nav-list.d.ts

@@ -0,0 +1,26 @@
+import * as React from "react";
+import type { NavListProp } from "../../props/components/layout.prop.js";
+export type { NavListProp };
+export type NavListProps = NavListProp;
+/**
+ * NavList — a vertical route navigation that is NOT shell furniture (gh#374).
+ *
+ * `Sidebar` owns the app's primary rail and renders into `AppShell`'s grid, so it cannot be nested
+ * in a page. The settings-nav shape — a column of links beside the pane they drive, one of them
+ * current — had no primitive, which left every consumer hand-rolling rows out of `Button`s with the
+ * current one encoded as a variant swap: no `aria-current`, no icon column, a different invention
+ * per app.
+ *
+ * This is the SAME row as the rail, deliberately: it composes `SidebarItem`, so icon slot, label,
+ * badge, active tokens and `aria-current="page"` are one implementation shared by both, and a
+ * consumer that already learnt `SidebarItemProp` / `linkComponent` for the rail knows this too.
+ * Only the container differs — a `<nav>` landmark instead of the shell's grid area, and no
+ * collapsed rail (a page-level nav has no rail to collapse into).
+ */
+export declare const NavList: React.ForwardRefExoticComponent<Omit<React.HTMLAttributes<HTMLElement>, "onSelect"> & {
+    items: import("../../props/index.js").SidebarItemProp[];
+    activeId?: string;
+    label: string;
+    linkComponent?: import("./sidebar.js").SidebarLinkComponentProp;
+    onSelect?: (id: string) => void;
+} & React.RefAttributes<HTMLElement>>;

package/dist/components/layout/nav-list.js

@@ -0,0 +1,21 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../../lib/utils.js";
+import { SidebarItem } from "./sidebar.js";
+const NavList = React.forwardRef(
+  ({ items, activeId, label, linkComponent, onSelect, className, ...props }, ref) => /* @__PURE__ */ jsx("nav", { ref, "aria-label": label, className: cn("ui-nav-list", className), ...props, children: items.map((item) => /* @__PURE__ */ jsx(
+    SidebarItem,
+    {
+      item,
+      active: item.id === activeId,
+      linkComponent,
+      onActivate: onSelect
+    },
+    item.id
+  )) })
+);
+NavList.displayName = "NavList";
+export {
+  NavList
+};

package/dist/components/layout/topbar-item.d.ts

@@ -0,0 +1,17 @@
+import * as React from "react";
+export type { TopbarItemProp, TopbarItemProp as TopbarItemProps, } from "../../props/components/layout.prop.js";
+/**
+ * TopbarItem — one interactive cell of a {@link Topbar} slot, shaped like part of the bar.
+ *
+ * Full bar height, the bar's own hover surface, and the focus mark hosted INSIDE the cell (a
+ * full-bleed cell has nothing outside itself to ring, and the bar clips its own overflow). All of
+ * that lives in `.ui-topbar-item`; this component only picks the element and the classes.
+ *
+ * `ui-focus-ring` is the ONE focus source (styles/focus-ring.css) — the cell hosts whatever that
+ * file resolves, including nothing at all while the `--focus-outline` switch ships off.
+ */
+export declare const TopbarItem: React.ForwardRefExoticComponent<Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children"> & {
+    asChild?: boolean;
+    children?: React.ReactNode;
+    className?: import("../../props/index.js").ClassNameProp;
+} & React.RefAttributes<HTMLButtonElement>>;

package/dist/components/layout/topbar-item.js

@@ -0,0 +1,21 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { cn } from "../../lib/utils.js";
+const TopbarItem = React.forwardRef(function TopbarItem2({ asChild = false, className, type, ...props }, ref) {
+  const Comp = asChild ? Slot : "button";
+  return /* @__PURE__ */ jsx(
+    Comp,
+    {
+      ref,
+      "data-slot": "topbar-item",
+      className: cn("ui-topbar-item ui-focus-ring", className),
+      type: asChild ? void 0 : type ?? "button",
+      ...props
+    }
+  );
+});
+export {
+  TopbarItem
+};

package/dist/components/navigation/app-setting-picker.js

@@ -135,19 +135,36 @@ const AppSettingPicker = React.forwardRef(
                   // sits among ghost icon buttons (the topbar's sidebar-toggle/notifications/account
                   // triggers), so it drops controlTriggerClass's form-input chrome (border/bg/shadow)
                   // at rest and adopts the same ghost hover — a resting border here read as visually
-                  // inconsistent next to its borderless topbar siblings. The open-state ring
-                  // (`data-[state=open]:border-ring`, from controlTriggerClass) and the
-                  // focus-visible ring are untouched, so keyboard and "is this open" affordance
-                  // still hold.
+                  // inconsistent next to its borderless topbar siblings. The open-state and
+                  // focus-visible rings are untouched, so keyboard and "is this open" affordance
+                  // still hold: both come from styles/focus-ring.css, which also excludes this
+                  // variant from the bordered-field rebind precisely BECAUSE it has no resting
+                  // border to recolour, so it keeps the opaque ring form.
                   // Bề ngang phải là UTILITY, không phải luật class. SelectTrigger phát `w-full`,
                   // mà utility nằm sau components trong thứ tự layer nên `inline-size` khai trong
                   // .ui-app-setting-picker-icon luôn thua. Trong một khe co theo nội dung của
                   // topbar, `width: 100%` co lại bằng chính nội dung, tức 18px thay vì ô vuông
                   // --control-height. Nhánh có nhãn ngay dưới đã phải tự vệ đúng như vậy bằng
                   // `w-auto`. Giá trị vẫn đọc token chứ không phải một con số.
+                  // `justify-content` đi cùng lý do đó: SelectTrigger phát `justify-between`,
+                  // với một con duy nhất thì nó dồn glyph sát viền trái (khe 1px/15px trong ô
+                  // 32px). `justify-content: center` khai trong .ui-app-setting-picker-icon
+                  // cũng nằm ở @layer components nên cũng thua. Cả hai trục của cái hộp này
+                  // phải do lớp utility sở hữu, không được để sót nửa nào lại trong luật class.
+                  // `shrink-0` là NỬA CÒN LẠI của trục ngang, không phải trang trí. `w-*` chỉ khai
+                  // kích thước MONG MUỐN; trong một flex row chật, `flex-shrink: 1` mặc định vẫn
+                  // ép nó nhỏ hơn. Đo thật trong Chromium ở chính frame tài liệu của component:
+                  // `.ui-topbar-end` rộng 82px, gap 8px, hai trigger cùng co → ô vuông ra
+                  // 21,28 × 32px thay vì 32 × 32. Đây không phải gh#366 quay lại: `inline-size`
+                  // vẫn giải đúng --control-height; cái hỏng là co giãn. Một tap target vuông
+                  // biến thành hình chữ nhật 21px mỗi khi topbar chật là lỗi thật, và nó kéo
+                  // theo cả vùng chạm. Nhánh CÓ NHÃN cố tình KHÔNG nhận `shrink-0`: nó rộng theo
+                  // nội dung và mang sẵn `max-w-full` để được phép thu lại.
+                  // Vẫn phải là utility vì cùng lý do với `w-*`: luật trong @layer components
+                  // thua lớp utilities mà SelectTrigger phát ra.
                   cn(
                     "ui-app-setting-picker-icon hover:bg-accent hover:text-accent-foreground",
-                    "w-[length:var(--control-height)]"
+                    "w-[length:var(--control-height)] shrink-0 justify-center"
                   )
                 ) : (
                   // Labeled: sized to a per-kind width from `sm` up; below `sm` it hugs its content and

package/dist/components/navigation/context-menu.js

@@ -11,11 +11,11 @@ function ContextMenuTrigger(props) {
 }
 const ContextMenuPortal = ContextMenuPrimitive.Portal;
 const ContextMenuContent = React.forwardRef(({ className, ...props }, ref) => {
-  useInertHiddenBackground();
+  const contentRef = useInertHiddenBackground(ref);
   return /* @__PURE__ */ jsx(ContextMenuPrimitive.Portal, { children: /* @__PURE__ */ jsx(
     ContextMenuPrimitive.Content,
     {
-      ref,
+      ref: contentRef,
       "data-slot": "context-menu-content",
       className: cn("ui-context-menu-content", className),
       ...props

package/dist/components/navigation/dropdown-menu.js

@@ -24,11 +24,11 @@ function DropdownMenuSub(props) {
   return /* @__PURE__ */ jsx(DropdownMenuPrimitive.Sub, { "data-slot": "dropdown-menu-sub", ...props });
 }
 const DropdownMenuContent = React.forwardRef(({ className, sideOffset = 4, ...props }, ref) => {
-  useInertHiddenBackground();
+  const contentRef = useInertHiddenBackground(ref);
   return /* @__PURE__ */ jsx(DropdownMenuPortal, { children: /* @__PURE__ */ jsx(
     DropdownMenuPrimitive.Content,
     {
-      ref,
+      ref: contentRef,
       "data-slot": "dropdown-menu-content",
       sideOffset,
       className: cn(

package/dist/components/navigation/tabs.js

@@ -47,9 +47,28 @@ function Tabs({
             "data-slot": "tabs-list",
             variant: variant === "line" ? "line" : "default",
             className: cn(
-              // The padding override is an arbitrary value reading the knob (never `p-0`): it must
-              // stay a UTILITY so tailwind-merge still drops the strip's own padding step, and a
-              variant === "line" && "h-auto w-full justify-start border-b p-[var(--tabs-list-line-space-inset)]",
+              // The inset override is an arbitrary value reading the knob (never `p-0`): it must
+              // stay a UTILITY so tailwind-merge still drops the strip's own padding step.
+              //
+              // IT IS SPLIT INTO `px-`/`py-` FOR THE FOCUS RING (gh#376). The strip clips its
+              // block axis (`overflow-y: hidden` beside `overflow-x: auto`), and this variant's
+              // inset is 0px, so a focused trigger had NO block headroom at all — measured in
+              // Chromium, 0px top and bottom, i.e. the entire ring was shaved. The headroom has to
+              // come from layout: `overflow-y: visible` next to `overflow-x: auto` computes back
+              // to `auto` per spec (a second scroll container, not a ring), and Chromium honours
+              // `overflow-clip-margin` only when BOTH axes are `clip`. So the block padding carries
+              // the ring's outer reach and an equal negative block margin hands it straight back —
+              // the ring paints inside the scrollport and the strip's OUTER box is unchanged
+              // (measured: 38px before and after). Both values read the same token the ring is
+              // sized from, so the two can never drift apart.
+              //
+              // The cost, recorded rather than hidden: the rail hairline (`border-b`, drawn at the
+              // border box) now sits the ring's reach below the triggers instead of flush. That is
+              // where a hand-composed <TabsList variant="line"> already put it — its `p-1` gives
+              // the same block inset — so the two construction paths now agree. A service that
+              // wants the active bar parked back on the hairline raises `--tabs-indicator-offset`,
+              // which exists for exactly that.
+              variant === "line" && "my-[calc(-1_*_var(--tabs-list-focus-ring-space-inset,calc(var(--focus-ring-width)_+_var(--focus-ring-glow-width))))] h-auto w-full justify-start border-b px-[var(--tabs-list-line-space-inset)] py-[calc(var(--tabs-list-line-space-inset)_+_var(--tabs-list-focus-ring-space-inset,calc(var(--focus-ring-width)_+_var(--focus-ring-glow-width))))]",
               variant === "card" && "w-full justify-start",
               listClassName
             ),
@@ -134,12 +153,25 @@ const TabsTrigger = React.forwardRef(({ className, ...props }, ref) => /* @__PUR
     ref,
     "data-slot": "tabs-trigger",
     className: cn(
-      // The SELECTED-state ring (`ring-1 ring-primary/25`) is scoped to the default/card lists —
-      // it competes with (and at equal specificity overrides) the `:focus-visible` ring. The
-      // focus-visible ring/outline below is deliberately left unscoped: every variant keeps a
-      // visible keyboard focus indicator (WCAG 2.4.7). The line indicator itself lives in
-      // src/styles/navigation-layout.css so it reads the --tabs-indicator-* tokens.
-      "text-muted-foreground ring-offset-background hover:text-foreground ui-focus-ring data-[state=active]:bg-background data-[state=active]:text-foreground group-data-[variant=default]/tabs-list:data-[state=active]:ring-primary/25 relative inline-flex flex-1 items-center justify-center gap-1.5 rounded-md border border-transparent px-3 py-1 text-sm font-medium whitespace-nowrap transition-all group-data-[orientation=vertical]/tabs:w-full group-data-[orientation=vertical]/tabs:justify-start group-data-[variant=line]/tabs-list:border-e-0 group-data-[variant=line]/tabs-list:border-b-0 focus-visible:outline-1 disabled:pointer-events-none disabled:opacity-50 group-data-[variant=default]/tabs-list:data-[state=active]:shadow-sm group-data-[variant=default]/tabs-list:data-[state=active]:ring-1 group-data-[variant=line]/tabs-list:data-[state=active]:bg-transparent group-data-[variant=line]/tabs-list:data-[state=active]:shadow-none",
+      // SELECTED IS A BORDER TINT, NOT A RING — and that is a WCAG fix, not a style preference.
+      // It used to be `ring-1 ring-primary/25`, which writes `--tw-ring-shadow` in the UTILITIES
+      // layer and therefore overwrote the focus ring that focus-ring.css feeds from `components`.
+      // Measured: a focused ACTIVE tab painted `oklab(… / 0.25) 0 0 0 1px` and nothing else — a
+      // 1px indicator at 25% alpha, failing both clauses of SC 2.4.13 (2px perimeter, ≥3:1),
+      // while every other control in the library carried a full 2px ring. The trigger already
+      // owns `border border-transparent`, so tinting that border reproduces the selected hairline
+      // at the same colour and width with no layout change, and leaves `--tw-ring-shadow` free for
+      // the focus ring. `shadow-sm` stays: its composite READS `--tw-ring-shadow`, so the lift and
+      // the ring coexist.
+      //
+      // No `focus-visible:outline-1` either. It was the fallback that survived the clobber — a 1px
+      // currentColor line squeezed between the border and the ring once both paint. The ring is
+      // the indicator now; two marks for one state is what this pass exists to remove.
+      //
+      // The line indicator lives in src/styles/navigation-layout.css so it reads --tabs-indicator-*.
+      // Selected and focused stay visually distinct (WCAG 2.4.7): selected is a 1px hairline in the
+      // border, focused is the 2px ring plus its halo outside it.
+      "text-muted-foreground ring-offset-background hover:text-foreground ui-focus-ring data-[state=active]:bg-background data-[state=active]:text-foreground group-data-[variant=default]/tabs-list:data-[state=active]:border-primary/25 relative inline-flex flex-1 items-center justify-center gap-1.5 rounded-md border border-transparent px-3 py-1 text-sm font-medium whitespace-nowrap transition-all group-data-[orientation=vertical]/tabs:w-full group-data-[orientation=vertical]/tabs:justify-start group-data-[variant=line]/tabs-list:border-e-0 group-data-[variant=line]/tabs-list:border-b-0 disabled:pointer-events-none disabled:opacity-50 group-data-[variant=default]/tabs-list:data-[state=active]:shadow-sm group-data-[variant=line]/tabs-list:data-[state=active]:bg-transparent group-data-[variant=line]/tabs-list:data-[state=active]:shadow-none",
       className
     ),
     ...props
@@ -151,7 +183,7 @@ const TabsContent = React.forwardRef(({ className, ...props }, ref) => /* @__PUR
   {
     ref,
     "data-slot": "tabs-content",
-    className: cn("focus-visible:ring-ring flex-1 outline-none focus-visible:ring-2", className),
+    className: cn("ui-focus-ring flex-1 outline-none", className),
     ...props
   }
 ));

package/dist/components/ui/segmented.d.ts

@@ -0,0 +1,48 @@
+import * as React from "react";
+/** One choice in a {@link Segmented}. */
+export type SegmentedOption = {
+    /** Wire value — what `onValueChange` reports and what a form submits. */
+    value: string;
+    /** Visible label. It is also the item's accessible name, so it is required. */
+    label: React.ReactNode;
+    /** Optional leading glyph, rendered `aria-hidden` beside the label. */
+    icon?: React.ReactNode;
+    /** Disable this one choice; the rest of the group stays operable. */
+    disabled?: boolean;
+};
+export type SegmentedProp = {
+    /** The closed set of choices, in reading order. */
+    options: readonly SegmentedOption[];
+    /** Controlled selection. */
+    value?: string;
+    /** Uncontrolled initial selection. */
+    defaultValue?: string;
+    onValueChange?: (value: string) => void;
+    /** Disable the whole group. */
+    disabled?: boolean;
+    /** Form field name — submits the selected value with the form. */
+    name?: string;
+    id?: string;
+    className?: string;
+    /** Accessible name of the group. Required unless a visible label points at `id`. */
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+};
+export type SegmentedProps = SegmentedProp;
+/**
+ * Segmented — one-of-N from a small, closed, always-visible set. antd's `Segmented`
+ * (docs/DESIGN-AUTHORITY.md names Ant Design the taxonomy authority) drawn on Radix's RadioGroup,
+ * which is this repo's authority for behaviour primitives.
+ *
+ * WHY NOT `ToggleGroup`. A ToggleGroup is a row of PRESSED buttons: `aria-pressed`, independently
+ * togglable, and — even at `type="single"` — deselectable, so "no theme at all" is a state the
+ * markup permits. A segmented control is a radio group: exactly one member is always chosen, the
+ * arrow keys move between members rather than Tab, and a screen reader must say "Light, radio
+ * button, 1 of 3, selected" and not "Light, toggle button, pressed". WAI-ARIA APG owns that
+ * distinction and it is not a skin.
+ *
+ * The primitive gives roving tabindex, arrow-key traversal (RTL-aware), the radiogroup/radio roles
+ * and the hidden input a native form submit needs. This file adds the antd geometry and nothing
+ * else — the focus mark comes from `ui-focus-ring`, the ONE source in styles/focus-ring.css.
+ */
+export declare const Segmented: React.ForwardRefExoticComponent<SegmentedProp & React.RefAttributes<HTMLDivElement>>;

package/dist/components/ui/segmented.js

@@ -0,0 +1,48 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import * as RadioGroupPrimitive from "@radix-ui/react-radio-group";
+import { cn } from "../../lib/utils.js";
+const Segmented = React.forwardRef(function Segmented2({ options, value, defaultValue, onValueChange, disabled, name, id, className, ...props }, ref) {
+  return /* @__PURE__ */ jsx(
+    RadioGroupPrimitive.Root,
+    {
+      ref,
+      id,
+      "data-slot": "segmented",
+      className: cn("ui-segmented", className),
+      orientation: "horizontal",
+      value,
+      defaultValue,
+      onValueChange,
+      disabled,
+      name,
+      ...props,
+      children: options.map((option) => /* @__PURE__ */ jsxs(
+        RadioGroupPrimitive.Item,
+        {
+          value: option.value,
+          disabled: option.disabled,
+          "data-slot": "segmented-item",
+          className: "ui-segmented-item ui-focus-ring",
+          children: [
+            option.icon == null ? null : /* @__PURE__ */ jsx(
+              "span",
+              {
+                "data-slot": "segmented-item-icon",
+                className: "ui-segmented-item-icon",
+                "aria-hidden": "true",
+                children: option.icon
+              }
+            ),
+            /* @__PURE__ */ jsx("span", { "data-slot": "segmented-item-label", className: "ui-segmented-item-label", children: option.label })
+          ]
+        },
+        option.value
+      ))
+    }
+  );
+});
+export {
+  Segmented
+};

package/dist/email/tokens.generated.d.ts

@@ -44,8 +44,8 @@ export declare const EMAIL_COLOR_SOURCE: {
         readonly hsl: "60 33% 99%";
     };
     readonly focus: {
-        readonly cssVar: "--ring";
-        readonly hsl: "204 100% 39%";
+        readonly cssVar: "--primary";
+        readonly hsl: "204 100% 37%";
     };
     readonly brand: {
         readonly cssVar: "--brand";
@@ -103,7 +103,7 @@ export declare const EMAIL_COLOR_SOURCE_DARK: {
         readonly hsl: "48 9% 9%";
     };
     readonly focus: {
-        readonly cssVar: "--ring";
+        readonly cssVar: "--primary";
         readonly hsl: "204 90% 60%";
     };
     readonly brand: {

package/dist/email/tokens.generated.js

@@ -36,8 +36,8 @@ const EMAIL_COLOR_SOURCE = {
     "hsl": "60 33% 99%"
   },
   "focus": {
-    "cssVar": "--ring",
-    "hsl": "204 100% 39%"
+    "cssVar": "--primary",
+    "hsl": "204 100% 37%"
   },
   "brand": {
     "cssVar": "--brand",
@@ -94,7 +94,7 @@ const EMAIL_COLOR_SOURCE_DARK = {
     "hsl": "48 9% 9%"
   },
   "focus": {
-    "cssVar": "--ring",
+    "cssVar": "--primary",
     "hsl": "204 90% 60%"
   },
   "brand": {

package/dist/i18n/messages/en.json

@@ -336,7 +336,8 @@
     "themePicker": {
       "ariaLabel": "Theme",
       "light": "Light",
-      "dark": "Dark"
+      "dark": "Dark",
+      "system": "System"
     },
     "densityPicker": {
       "ariaLabel": "Density",

package/dist/i18n/messages/ja.json

@@ -324,7 +324,8 @@
     "themePicker": {
       "ariaLabel": "テーマ",
       "light": "ライト",
-      "dark": "ダーク"
+      "dark": "ダーク",
+      "system": "システム"
     },
     "densityPicker": {
       "ariaLabel": "密度",

package/dist/i18n/messages/vi.json

@@ -324,7 +324,8 @@
     "themePicker": {
       "ariaLabel": "Giao diện",
       "light": "Sáng",
-      "dark": "Tối"
+      "dark": "Tối",
+      "system": "Hệ thống"
     },
     "densityPicker": {
       "ariaLabel": "Mật độ",

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

@@ -28,7 +28,11 @@ export type AppProviderProp = {
     storageKey?: string;
     /** Persist user choices. Default: true. */
     persist?: boolean;
-    /** Initial light/dark theme — written to `<html data-theme>`. Default: `"light"`. */
+    /**
+     * Initial theme choice. `"light"` / `"dark"` are written straight to `<html data-theme>`;
+     * `"system"` defers to `prefers-color-scheme` and is re-resolved whenever the OS changes.
+     * Default: `"light"`.
+     */
     theme?: AppTheme;
     /**
      * Initial brand palette preset — written to `<html data-brand>`. OPT-IN: omit
@@ -101,7 +105,10 @@ export type AppContextValue = {
     requestHeaders: AppRequestHeaders;
     /** Configured timezone list; `undefined` → full IANA in the timezone-picker recipe. */
     timezoneOptions?: readonly AppTimezone[];
-    /** Current theme axes (mirror `<html data-*>` / inline `--scaling`). */
+    /**
+     * Current theme axes (mirror `<html data-*>` / inline `--scaling`). `theme` is the user's
+     * CHOICE — it can be `"system"`, which `<html data-theme>` never is.
+     */
     theme: AppTheme;
     brand: AppBrand | null;
     density: AppDensity;

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

@@ -631,6 +631,25 @@ export type SidebarItemProp = {
     /** Nested rows — renders a collapsible submenu group (the parent reads active when any child is). */
     children?: SidebarItemProp[];
 };
+/**
+ * A vertical route navigation that lives INSIDE a page, not in the shell (gh#374).
+ *
+ * Reuses `SidebarItemProp` and `SidebarLinkComponentProp` verbatim rather than minting a parallel
+ * vocabulary: the row is the same row, so a service that learnt the rail's item shape does not
+ * learn a second one, and a fix to the row reaches both.
+ */
+export type NavListProp = Omit<React.HTMLAttributes<HTMLElement>, "onSelect"> & {
+    /** Rows, in reading order. `icon` is required by `SidebarItemProp` — the label aligns to it. */
+    items: SidebarItemProp[];
+    /** `SidebarItemProp.id` of the current route; that row gets `aria-current="page"`. */
+    activeId?: string;
+    /** Accessible name for the `<nav>` landmark. Required: a page may hold more than one. */
+    label: string;
+    /** Router link component — same contract as `Sidebar.linkComponent`. */
+    linkComponent?: SidebarLinkComponentProp;
+    /** Reports the activated row's id, for consumers driving navigation themselves. */
+    onSelect?: (id: string) => void;
+};
 /** @see Sidebar */
 export type SidebarItemData = SidebarItemProp;
 /**
@@ -654,8 +673,15 @@ export type SidebarLinkProp = {
     "aria-label"?: string;
     /** `"menuitem"` inside the collapsed rail's portaled flyout menu; absent for ordinary rows. */
     role?: "menuitem";
-    /** Reports selection to `Sidebar.onSelect` after the router link runs its own handler. */
-    onClick?: (event: React.MouseEvent<HTMLElement>) => void;
+    /**
+     * Reports selection to `Sidebar.onSelect` after the router link runs its own handler.
+     *
+     * Typed on `Element`, NOT `HTMLElement`. Handler parameters are contravariant, so a link
+     * component that accepts the wider `MouseEvent<Element>` — Inertia's `<Link>`, react-router's,
+     * TanStack's — cannot receive a prop narrowed to `HTMLElement`, and the anchor-safe contract
+     * this type promises would only hold behind a cast at every call site.
+     */
+    onClick?: React.MouseEventHandler<Element>;
 };
 /**
  * A framework router link component driven by {@link SidebarLinkProp} — Inertia's `<Link href>`,
@@ -809,6 +835,26 @@ export type TopbarProp = Omit<React.HTMLAttributes<HTMLDivElement>, "children">
     /** Escape hatch — render fully custom bar content instead of the three slots. */
     children?: ReactNode;
 };
+/**
+ * @see TopbarItem — ONE interactive cell of a {@link TopbarProp} slot: the account button, a
+ * settings trigger, a notifications bell.
+ *
+ * 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
+ * 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.
+ */
+export type TopbarItemProp = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children"> & {
+    /**
+     * 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.
+     */
+    asChild?: boolean;
+    children?: ReactNode;
+    className?: ClassNameProp;
+};
 /**
  * @see LegalDocumentShell — one entry of the table of contents + the matching document section.
  * `id` is the REAL anchor target (`href="#{id}"`, `<section id>`), so it must be unique on the page

package/dist/props/registry.d.ts

@@ -927,6 +927,20 @@ export declare const COMPONENT_PROP_REGISTRY: {
         readonly file: "components/layout.prop.ts";
         readonly vocabulary: readonly ["ChildrenProp"];
     };
+    readonly TopbarItemProp: {
+        readonly group: "layout";
+        readonly file: "components/layout.prop.ts";
+        readonly vocabulary: readonly ["ChildrenProp", "ClassNameProp", {
+            readonly field: "asChild";
+            readonly local: true;
+            readonly reason: "Radix Slot passthrough — merges onto the child";
+        }];
+    };
+    readonly NavListProp: {
+        readonly group: "layout";
+        readonly file: "components/layout.prop.ts";
+        readonly vocabulary: readonly ["IdProp", "ClassNameProp"];
+    };
     readonly ButtonProp: {
         readonly group: "general";
         readonly file: "components/general.prop.ts";
@@ -1734,6 +1748,11 @@ export declare const COMPONENT_PROP_REGISTRY: {
         readonly file: "components/ui/rating.tsx";
         readonly vocabulary: readonly ["ValueProp", "OnValueChangeProp", "DisabledProp", "ClassNameProp"];
     };
+    readonly SegmentedProp: {
+        readonly group: "data-entry";
+        readonly file: "components/ui/segmented.tsx";
+        readonly vocabulary: readonly ["ValueProp", "DefaultValueProp", "OnValueChangeProp", "DisabledProp", "NameProp", "IdProp", "ClassNameProp"];
+    };
     readonly TagInputProp: {
         readonly group: "data-entry";
         readonly file: "components/ui/tag-input.tsx";

package/dist/props/registry.js

@@ -1020,6 +1020,20 @@ const COMPONENT_PROP_REGISTRY = {
     file: "components/layout.prop.ts",
     vocabulary: ["ChildrenProp"]
   },
+  TopbarItemProp: {
+    group: "layout",
+    file: "components/layout.prop.ts",
+    vocabulary: [
+      "ChildrenProp",
+      "ClassNameProp",
+      { field: "asChild", local: true, reason: "Radix Slot passthrough \u2014 merges onto the child" }
+    ]
+  },
+  NavListProp: {
+    group: "layout",
+    file: "components/layout.prop.ts",
+    vocabulary: ["IdProp", "ClassNameProp"]
+  },
   ButtonProp: {
     group: "general",
     file: "components/general.prop.ts",
@@ -1938,6 +1952,19 @@ const COMPONENT_PROP_REGISTRY = {
     file: "components/ui/rating.tsx",
     vocabulary: ["ValueProp", "OnValueChangeProp", "DisabledProp", "ClassNameProp"]
   },
+  SegmentedProp: {
+    group: "data-entry",
+    file: "components/ui/segmented.tsx",
+    vocabulary: [
+      "ValueProp",
+      "DefaultValueProp",
+      "OnValueChangeProp",
+      "DisabledProp",
+      "NameProp",
+      "IdProp",
+      "ClassNameProp"
+    ]
+  },
   TagInputProp: {
     group: "data-entry",
     file: "components/ui/tag-input.tsx",

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

@@ -62,5 +62,14 @@ export type FlushProp = boolean;
  * px; a `string` is any CSS length (`"32rem"`, `"90vw"`, `"50%"`).
  */
 export type WidthProp = number | string;
-/** How a control sizes on the inline axis: fill its column, or hug its label. */
-export type ControlWidthProp = "full" | "auto";
+/**
+ * How a control sizes on the inline axis: fill its column, hug its label, or sit at a bounded
+ * width the theme owns.
+ *
+ * `bounded` exists because neither of the other two is right for a control whose VALUE varies in
+ * length — an organization switcher in a shell top bar is the canonical case. `full` swallows the
+ * bar; `auto` makes the bar reflow every time the selected value changes length. `bounded` reads
+ * `--control-bounded-width`, so the width is a knob rather than geometry hand-written at the call
+ * site (gh#375).
+ */
+export type ControlWidthProp = "full" | "auto" | "bounded";