@godxjp/ui 19.3.1 → 19.4.1

package/dist/components/general/inert-background.js

@@ -0,0 +1,48 @@
+"use client";
+import * as React from "react";
+const TABBABLE = 'a[href], area[href], button, input, select, textarea, iframe, object, embed, details, audio[controls], video[controls], [contenteditable="true"], [tabindex]:not([tabindex^="-"])';
+const owned = /* @__PURE__ */ new Set();
+let observer = null;
+let mounted = 0;
+function sync() {
+  for (const el of document.querySelectorAll("[data-aria-hidden]")) {
+    if (owned.has(el) || el.hasAttribute("inert")) continue;
+    if (el.querySelector(TABBABLE)) {
+      el.setAttribute("inert", "");
+      owned.add(el);
+    }
+  }
+  for (const el of [...owned]) {
+    if (el.isConnected && el.hasAttribute("data-aria-hidden")) continue;
+    el.removeAttribute("inert");
+    owned.delete(el);
+  }
+}
+function release() {
+  for (const el of owned) el.removeAttribute("inert");
+  owned.clear();
+}
+function useInertHiddenBackground() {
+  React.useEffect(() => {
+    mounted += 1;
+    if (!observer) {
+      observer = new MutationObserver(sync);
+      observer.observe(document.body, {
+        subtree: true,
+        attributes: true,
+        attributeFilter: ["data-aria-hidden"]
+      });
+    }
+    sync();
+    return () => {
+      mounted -= 1;
+      if (mounted > 0) return;
+      observer?.disconnect();
+      observer = null;
+      release();
+    };
+  }, []);
+}
+export {
+  useInertHiddenBackground
+};

package/dist/components/layout/auth-shell.d.ts

@@ -3,6 +3,8 @@ export type { AuthShellProp, AuthShellProp as AuthShellProps, } from "../../prop
 /**
  * AuthShell — centred auth/login page shell (login · mfa · passkey · device · reset). A top brand
  * bar (banner), a centred `main` that holds the auth `Card`, and an optional footer (contentinfo),
- * over a `min-h-dvh` surface.
+ * over a `min-h-dvh` surface. The banner also carries page-level `actions` at its inline end (a
+ * locale picker, a theme toggle), and `measure="wide"` opens the content slot to the split login
+ * (a brand panel beside the card) that used to have no shell of its own.
  */
-export declare function AuthShell({ brand, footer, children, variant, preset, density, className, }: AuthShellProp): import("react").JSX.Element;
+export declare function AuthShell({ brand, actions, footer, children, variant, preset, measure, density, className, }: AuthShellProp): import("react").JSX.Element;

package/dist/components/layout/auth-shell.js

@@ -4,10 +4,12 @@ import { useTranslation } from "../../i18n/use-translation.js";
 import { cn } from "../../lib/utils.js";
 function AuthShell({
   brand,
+  actions,
   footer,
   children,
   variant = "default",
   preset = "default",
+  measure = "default",
   density,
   className
 }) {
@@ -19,10 +21,14 @@ function AuthShell({
       "data-slot": "auth-shell",
       "data-variant": variant,
       "data-preset": preset === "default" ? void 0 : preset,
+      "data-measure": measure === "default" ? void 0 : measure,
       "data-density": resolvedDensity,
       className: cn("ui-auth-shell", className),
       children: [
-        brand !== void 0 && /* @__PURE__ */ jsx("header", { className: "ui-auth-shell-bar", "aria-label": t("layout.authShell.brandLabel"), children: brand }),
+        (brand !== void 0 || actions !== void 0) && /* @__PURE__ */ jsxs("header", { className: "ui-auth-shell-bar", "aria-label": t("layout.authShell.brandLabel"), children: [
+          brand,
+          actions !== void 0 && /* @__PURE__ */ jsx("div", { className: "ui-auth-shell-bar-actions", children: actions })
+        ] }),
         /* @__PURE__ */ jsx("main", { className: "ui-auth-shell-main", "aria-label": t("layout.authShell.mainLabel"), children: /* @__PURE__ */ jsx("div", { className: "ui-auth-shell-card", children }) }),
         footer !== void 0 && /* @__PURE__ */ jsx("footer", { className: "ui-auth-shell-footer", "aria-label": t("layout.authShell.footerLabel"), children: footer })
       ]

package/dist/components/layout/centered-shell.d.ts

@@ -5,7 +5,7 @@ export type { CenteredShellProp, CenteredShellProp as CenteredShellProps, } from
  * account / self-service, and standalone-settings shape. It fills the gap between the two existing
  * shells: - `AppShell` REQUIRES a sidebar — its padded topbar chrome (`.app-topbar`) is a grid
  * area beside the nav rail, so you cannot get a padded top bar without a rail. - `AuthShell` is
- * the UNAUTHENTICATED root (login/mfa/reset); it centres a narrow ~24rem card VERTICALLY and has
- * no top-right actions slot.
+ * the UNAUTHENTICATED root (login/mfa/reset); it centres its card VERTICALLY, so a page that
+ * scrolls its own content belongs here instead.
  */
 export declare function CenteredShell({ topbar, footer, children, width, align, preset, className, }: CenteredShellProp): import("react").JSX.Element;

package/dist/components/layout/flex.d.ts

@@ -1,3 +1,3 @@
 import type { FlexProp } from "../../props/components/layout.prop.js";
 export type { FlexAlignProp, FlexDirectionProp, FlexJustifyProp, FlexProp, FlexProp as FlexProps, } from "../../props/components/layout.prop.js";
-export declare function Flex({ direction, gap, align, justify, wrap, hideBelow, hideFrom, className, children, ...props }: FlexProp): import("react").JSX.Element;
+export declare function Flex({ as: Element, direction, gap, align, justify, wrap, hideBelow, hideFrom, className, children, ...props }: FlexProp): import("react").JSX.Element;

package/dist/components/layout/flex.js

@@ -4,6 +4,7 @@ import { mergeAriaIds } from "../../lib/field-a11y.js";
 import { cn } from "../../lib/utils.js";
 import { flexGapClass } from "../../lib/variants.js";
 function Flex({
+  as: Element = "div",
   direction = "row",
   gap = "md",
   align,
@@ -30,7 +31,7 @@ function Flex({
     };
   }
   return /* @__PURE__ */ jsx(
-    "div",
+    Element,
     {
       "data-direction": direction,
       "data-align": align,

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

@@ -22,6 +22,9 @@ export { AuthFooter } from "./auth-footer.js";
 export type { AuthFooterProp, AuthFooterProps } from "./auth-footer.js";
 export { AuthStack } from "./auth-stack.js";
 export type { AuthStackProps } from "./auth-stack.js";
+export { MobileShell } from "./mobile-shell.js";
+export type { MobileShellProp, MobileShellProps } from "./mobile-shell.js";
+export type { MobileShellHeightProp } from "../../props/vocabulary/index.js";
 export { CenteredShell } from "./centered-shell.js";
 export type { CenteredShellProp, CenteredShellProps } from "./centered-shell.js";
 export type { CenteredShellWidthProp, CenteredShellAlignProp } from "../../props/vocabulary/index.js";

package/dist/components/layout/index.js

@@ -10,6 +10,7 @@ import { AccountChip } from "./account-chip.js";
 import { AuthAccountSummary } from "./auth-account-summary.js";
 import { AuthFooter } from "./auth-footer.js";
 import { AuthStack } from "./auth-stack.js";
+import { MobileShell } from "./mobile-shell.js";
 import { CenteredShell } from "./centered-shell.js";
 import { ErrorSurface } from "./error-surface.js";
 import { Breadcrumb } from "./breadcrumb.js";
@@ -38,6 +39,7 @@ export {
   Flex,
   LegalDocumentShell,
   MasterDetail,
+  MobileShell,
   OrgSwitcher,
   PageContainer,
   ResizableHandle,

package/dist/components/layout/mobile-shell.d.ts

@@ -0,0 +1,21 @@
+import type { MobileShellProp } from "../../props/components/layout.prop.js";
+export type { MobileShellProp, MobileShellProp as MobileShellProps, } from "../../props/components/layout.prop.js";
+/**
+ * MobileShell — the HANDHELD app shell: a status band, an app bar, ONE scroll region,
+ * a sticky action bar and a bottom tab bar, in that fixed order.
+ *
+ * The fourth root shell. The other three cannot express a phone app: `AppShell` REQUIRES a sidebar
+ * (its bar is a grid area beside the nav rail), `AuthShell` is the UNAUTHENTICATED root and centres
+ * a ~24rem card, and `CenteredShell` is a scrolling DOCUMENT — its `main` scrolls the page, which
+ * is precisely what a handheld app must not do.
+ *
+ * SOURCE ORDER IS THE LAYOUT. The bands are a flex column and nothing repositions them, so the DOM
+ * order and the reading order are the same order — the accessibility property AppShell has to buy
+ * back with grid areas. `actions` therefore comes before `tabBar` in the DOM as well as on screen.
+ *
+ * i18n: the three landmarks reuse the SHARED shell labels (`layout.appShell.headerLabel` /
+ * `.mainLabel` for the bar and the scroll region, `layout.sidebar.ariaLabel` for the tab bar, which
+ * IS the app's primary navigation). They are the same strings in all three locales, and a fourth
+ * identical copy under `layout.mobileShell.*` would be three files of duplication to keep in sync.
+ */
+export declare function MobileShell({ statusBar, header, children, actions, tabBar, height, className, }: MobileShellProp): import("react").JSX.Element;

package/dist/components/layout/mobile-shell.js

@@ -0,0 +1,43 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useTranslation } from "../../i18n/use-translation.js";
+import { cn } from "../../lib/utils.js";
+function MobileShell({
+  statusBar,
+  header,
+  children,
+  actions,
+  tabBar,
+  height = "viewport",
+  className
+}) {
+  const { t } = useTranslation();
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      "data-slot": "mobile-shell",
+      "data-height": height === "viewport" ? void 0 : height,
+      className: cn("ui-mobile-shell", className),
+      children: [
+        (statusBar !== void 0 || header !== void 0) && /* @__PURE__ */ jsxs("header", { className: "ui-mobile-shell-chrome", "aria-label": t("layout.appShell.headerLabel"), children: [
+          statusBar !== void 0 && /* @__PURE__ */ jsx("div", { className: "ui-mobile-shell-status", children: statusBar }),
+          header !== void 0 && /* @__PURE__ */ jsx("div", { className: "ui-mobile-shell-header", children: header })
+        ] }),
+        /* @__PURE__ */ jsx(
+          "main",
+          {
+            className: "ui-mobile-shell-main",
+            "aria-label": t("layout.appShell.mainLabel"),
+            tabIndex: 0,
+            children
+          }
+        ),
+        actions !== void 0 && /* @__PURE__ */ jsx("footer", { className: "ui-mobile-shell-actions", children: actions }),
+        tabBar !== void 0 && /* @__PURE__ */ jsx("nav", { className: "ui-mobile-shell-tabbar", "aria-label": t("layout.sidebar.ariaLabel"), children: tabBar })
+      ]
+    }
+  );
+}
+export {
+  MobileShell
+};

package/dist/components/layout/sidebar-link.d.ts

@@ -1,7 +1,7 @@
 import * as React from "react";
 import type { SidebarLinkComponentProp } from "../../props/components/layout.prop.js";
 /**
- * Adapt a framework router `Link` to {@link SidebarLinkComponentProp} (gh#213) — a dependency-free
+ * Adapt a framework router `Link` to {@link SidebarLinkComponentProp} — a dependency-free
  * factory, so `@godxjp/ui` still ships ZERO router/framework dependencies.
  *
  * It lives in its own module (imports only React + the prop types) so `@godxjp/ui/inertia` can build

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

@@ -4,20 +4,24 @@ import * as React from "react";
 import * as ContextMenuPrimitive from "@radix-ui/react-context-menu";
 import { Check, ChevronRight, Circle } from "lucide-react";
 import { cn } from "../../lib/utils.js";
+import { useInertHiddenBackground } from "../general/inert-background.js";
 const ContextMenu = ContextMenuPrimitive.Root;
 function ContextMenuTrigger(props) {
   return /* @__PURE__ */ jsx(ContextMenuPrimitive.Trigger, { "data-slot": "context-menu-trigger", ...props });
 }
 const ContextMenuPortal = ContextMenuPrimitive.Portal;
-const ContextMenuContent = React.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx(ContextMenuPrimitive.Portal, { children: /* @__PURE__ */ jsx(
-  ContextMenuPrimitive.Content,
-  {
-    ref,
-    "data-slot": "context-menu-content",
-    className: cn("ui-context-menu-content", className),
-    ...props
-  }
-) }));
+const ContextMenuContent = React.forwardRef(({ className, ...props }, ref) => {
+  useInertHiddenBackground();
+  return /* @__PURE__ */ jsx(ContextMenuPrimitive.Portal, { children: /* @__PURE__ */ jsx(
+    ContextMenuPrimitive.Content,
+    {
+      ref,
+      "data-slot": "context-menu-content",
+      className: cn("ui-context-menu-content", className),
+      ...props
+    }
+  ) });
+});
 ContextMenuContent.displayName = ContextMenuPrimitive.Content.displayName;
 const ContextMenuItem = React.forwardRef(({ className, inset, variant = "default", ...props }, ref) => /* @__PURE__ */ jsx(
   ContextMenuPrimitive.Item,

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

@@ -4,6 +4,7 @@ import * as React from "react";
 import * as DropdownMenuPrimitive from "@radix-ui/react-dropdown-menu";
 import { Check, ChevronRight } from "lucide-react";
 import { cn } from "../../lib/utils.js";
+import { useInertHiddenBackground } from "../general/inert-background.js";
 function DropdownMenu(props) {
   return /* @__PURE__ */ jsx(DropdownMenuPrimitive.Root, { "data-slot": "dropdown-menu", ...props });
 }
@@ -22,19 +23,22 @@ function DropdownMenuRadioGroup(props) {
 function DropdownMenuSub(props) {
   return /* @__PURE__ */ jsx(DropdownMenuPrimitive.Sub, { "data-slot": "dropdown-menu-sub", ...props });
 }
-const DropdownMenuContent = React.forwardRef(({ className, sideOffset = 4, ...props }, ref) => /* @__PURE__ */ jsx(DropdownMenuPortal, { children: /* @__PURE__ */ jsx(
-  DropdownMenuPrimitive.Content,
-  {
-    ref,
-    "data-slot": "dropdown-menu-content",
-    sideOffset,
-    className: cn(
-      "ui-dropdown-menu-content data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 origin-[var(--radix-dropdown-menu-content-transform-origin)]",
-      className
-    ),
-    ...props
-  }
-) }));
+const DropdownMenuContent = React.forwardRef(({ className, sideOffset = 4, ...props }, ref) => {
+  useInertHiddenBackground();
+  return /* @__PURE__ */ jsx(DropdownMenuPortal, { children: /* @__PURE__ */ jsx(
+    DropdownMenuPrimitive.Content,
+    {
+      ref,
+      "data-slot": "dropdown-menu-content",
+      sideOffset,
+      className: cn(
+        "ui-dropdown-menu-content data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 origin-[var(--radix-dropdown-menu-content-transform-origin)]",
+        className
+      ),
+      ...props
+    }
+  ) });
+});
 DropdownMenuContent.displayName = DropdownMenuPrimitive.Content.displayName;
 const DropdownMenuItem = React.forwardRef(({ className, inset, variant = "default", ...props }, ref) => /* @__PURE__ */ jsx(
   DropdownMenuPrimitive.Item,

package/dist/inertia/index.d.ts

@@ -68,7 +68,7 @@ export interface InertiaLinkLike {
     children?: ReactNode;
 }
 /**
- * Bind Inertia's `<Link>` as the Sidebar's row element (gh#213).
+ * Bind Inertia's `<Link>` as the Sidebar's row element.
  *
  * The LIBRARY still composes every row — the 16px icon slot, the label, the badge, `data-active` /
  * `aria-current`, the icon-only collapsed rail and its tooltip name — and hands it to the link as

package/dist/lib/variants.d.ts

@@ -3,10 +3,10 @@ import type { GapProp, PageContainerVariantProp, PageDensityProp } from "../prop
 export type Density = PageDensityProp;
 export type StackGap = GapProp;
 export type FlexGap = GapProp;
-export type InlineGap = Exclude<GapProp, "xl">;
+export type InlineGap = Exclude<GapProp, "xl" | "none">;
 export type PageContainerVariant = PageContainerVariantProp;
 export declare const densityClass: Record<PageDensityProp, string>;
 export declare const pageContainerVariantClass: Record<PageContainerVariantProp, string | undefined>;
-export declare const stackGapClass: Record<GapProp, string>;
-export declare const inlineGapClass: Record<Exclude<GapProp, "xl">, string>;
+export declare const stackGapClass: Record<Exclude<GapProp, "none">, string>;
+export declare const inlineGapClass: Record<InlineGap, string>;
 export declare const flexGapClass: Record<GapProp, string>;

package/dist/lib/variants.js

@@ -23,6 +23,7 @@ const inlineGapClass = {
   lg: "ui-inline-lg"
 };
 const flexGapClass = {
+  none: "ui-flex-gap-none",
   xs: "ui-flex-gap-xs",
   sm: "ui-flex-gap-sm",
   md: "ui-flex-gap-md",

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

@@ -137,6 +137,12 @@ export type AvatarPresenceProp = "online" | "away" | "busy" | "offline";
 export type AvatarAppearanceProp = "default" | "tinted";
 /** @see Badge */
 export type BadgeProp = {
+    /**
+     * Render element — `div` (default) or `span` when the chip sits in a phrasing context where a
+     * `<div>` is invalid HTML (inside a `<button>` rendered by TabsTrigger/PopoverTrigger/Button,
+     * a `<label>`, a `<p>`). Swaps the tag only.
+     */
+    as?: "div" | "span";
     variant?: "default" | "secondary" | "outline";
     /** Status tones plus a brand `primary` tone (soft brand pill); solid brand = `variant="default"`. */
     tone?: ToneProp | "primary";
@@ -360,3 +366,62 @@ export type ScrollAreaProp = {
      */
     onAnchoredChange?: (anchored: boolean) => void;
 };
+/**
+ * @see TimelineGrid — one COLUMN of the grid (a day, a room, a machine). The label names the
+ * column visually AND names the column's event list for assistive technology.
+ */
+export type TimelineGridColumnProp = {
+    /** Stable column id — the `columnId` an event points at. */
+    id: string;
+    /** Column head. Also the accessible name of that column's event list, so keep it text. */
+    label: LabelProp;
+    /** Secondary line under the head (a date, a capacity, a room number). */
+    description?: DescriptionProp;
+    /** Marks the column as "now" (today's column): it carries the tint and hosts the `now` marker. */
+    current?: boolean;
+};
+/**
+ * @see TimelineGrid — one event BLOCK. `start`/`end` are clock times in the column's own day,
+ * `"HH:MM"` 24-hour (`"24:00"` = end of day). An `end` at or before `start` continues into the
+ * next day (22:00–06:00), and the block is drawn to the end of the window and marked clipped.
+ */
+export type TimelineGridEventProp = {
+    /** Stable event id — the React key, and the `data-event-id` on the block. */
+    id: string;
+    /** Id of the column this event belongs to. An event pointing at no column is not drawn. */
+    columnId: string;
+    /** Start clock time, `"HH:MM"`. */
+    start: string;
+    /** End clock time, `"HH:MM"`. At or before `start` = continues into the next day. */
+    end: string;
+    /** Block title. The block also renders the time range as text, so the range is never colour or position alone. */
+    title: TitleProp;
+    /** Secondary line inside the block (who is on the shift, a room, a customer). */
+    description?: DescriptionProp;
+    /** The record's own colour, washed exactly like `Badge color` — decorative, never the only signal. */
+    color?: string;
+};
+/** @see TimelineGrid */
+export type TimelineGridProp = {
+    /**
+     * Accessible name of the grid. Required, and a plain `string`: the grid is a focusable scroll
+     * region, so its name has to survive as an `aria-label`.
+     */
+    label: Extract<LabelProp, string>;
+    /** Columns in render order. */
+    columns: readonly TimelineGridColumnProp[];
+    /** Events in any order; the grid sorts each column by start time and lays overlaps out side by side. */
+    events: readonly TimelineGridEventProp[];
+    /** First clock time on the axis, `"HH:MM"`. Defaults to the earliest event, on the hour. */
+    start?: string;
+    /** Last clock time on the axis, `"HH:MM"`. Defaults to the latest event, on the hour. */
+    end?: string;
+    /** Hours between hour rules and axis labels. Default `1`. */
+    interval?: number;
+    /** Current clock time, `"HH:MM"`. Draws the now marker in the columns marked `current`. */
+    now?: string;
+    /** Block click handler. Its PRESENCE turns every block into a real `button`. */
+    onEventSelect?: (event: TimelineGridEventProp) => void;
+    className?: ClassNameProp;
+    id?: IdProp;
+};

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

@@ -106,7 +106,7 @@ export type FormProp = React.FormHTMLAttributes<HTMLFormElement> & {
     className?: ClassNameProp;
 };
 /**
- * @see FormField — exactly one of `children` (an interactive control) or `staticText` (gh#294):
+ * @see FormField — exactly one of `children` (an interactive control) or `staticText`:
  * a read-only VALUE row inside the same Form, styled to match `Descriptions.Item`'s value
  * typography (`text-sm break-all`) byte-for-byte. This is the "mixed read-only + editable fields
  * on one form" case (an immutable name/email row above an editable role Select, for example) —

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, 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, ClassNameProp, ChildrenProp, IdProp, DisabledProp, DescriptionProp, ActionProp, IconProp, HeadingLevelProp, ToneProp } 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.
@@ -102,6 +102,14 @@ 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> & {
+    /**
+     * 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
+     * render a `<button>`, whose content model is phrasing content only), inside a `<label>`, or
+     * 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;
     gap?: GapProp;
     align?: FlexAlignProp;
@@ -226,6 +234,13 @@ export type AuthShellProp = {
     children: ReactNode;
     /** Brand bar slot pinned to the top (e.g. a `<Logo>` / product mark). */
     brand?: ReactNode;
+    /**
+     * Page-level controls pinned to the TOP-RIGHT of the same banner row as `brand` — a locale
+     * picker, a theme toggle, a "need help?" link. These belong to the PAGE, not to the auth form,
+     * which is why they sit in the bar rather than inside the card. The banner renders as soon as
+     * `brand` OR `actions` is present, so an actions-only bar is a legal shape.
+     */
+    actions?: ActionProp;
     /** Footer slot pinned to the bottom (legal links, locale switch, support). */
     footer?: ReactNode;
     /**
@@ -242,6 +257,16 @@ export type AuthShellProp = {
      * canonical 1440x900, 1024x900 and 390x844 viewports.
      */
     preset?: AuthShellPresetProp;
+    /**
+     * Inline MEASURE of the shell's content slot. `"default"` keeps the single auth card (24rem, or
+     * the canonical variant's 22.5rem). `"wide"` opens the slot to
+     * `--auth-shell-wide-card-max-width` so a SPLIT login fits — a brand/marketing panel beside the
+     * auth card, the shape that previously had no shell and reached for `CenteredShell`. The wide
+     * slot centres itself with auto margins, so a tall two-column layout starts at the top instead
+     * of overflowing above the scroll origin. Ignored under a `preset`: a preset already owns its
+     * flow geometry.
+     */
+    measure?: "default" | "wide";
     /**
      * Vertical density scoped to auth-card descendants. The canonical variant defaults to
      * `"compact"`; the default variant defaults to `"comfortable"`.
@@ -249,6 +274,68 @@ export type AuthShellProp = {
     density?: "comfortable" | "compact";
     className?: ClassNameProp;
 };
+/**
+ * @see MobileShell — the HANDHELD app shell: a status band, an app bar, ONE scroll region, a
+ * sticky action bar and a bottom tab bar, in that fixed order.
+ *
+ * It is the fourth root shell, and it exists because the other three cannot express a phone app:
+ * `AppShell` REQUIRES a sidebar (its bar is a grid area beside the nav rail), `AuthShell` is the
+ * UNAUTHENTICATED root and centres a ~24rem card, and `CenteredShell` is a scrolling DOCUMENT —
+ * its `main` scrolls the page, which is exactly what a handheld app must not do. Composing one out
+ * of `Card` + `ui-card-inset*` (what docs/showcase/case6 once did) reproduces the look
+ * and none of the two behaviours that matter on a real device:
+ *
+ *  1. The shell is the only scroll container. The root is exactly one screen tall, so the DOCUMENT
+ *     never scrolls and the tab bar never slides away under a collapsing URL bar.
+ *  2. Every band pads itself out of `env(safe-area-inset-*)`, so the notch never covers the app
+ *     bar and the home indicator never covers the primary verb.
+ *
+ * Layout-only, like the other shells: it paints chrome and owns geometry, and delegates motion to
+ * `Reveal`. Never nest it inside another shell — it is a ROOT.
+ */
+export type MobileShellProp = {
+    /**
+     * The scrolling screen body — the ONLY scroll container in the shell, and the only elastic band.
+     * Everything else is fixed chrome, so a long list scrolls under a stationary app bar and tab bar.
+     */
+    children: ReactNode;
+    /**
+     * App bar (banner) pinned to the top: the screen title plus its inline actions. When there is no
+     * `statusBar` this band absorbs the top safe-area inset itself. Omit → no banner.
+     *
+     * On a screen with a MODE (multi-select, search, edit) swap the whole node rather than stacking a
+     * second strip under it — replacing the bar's contents is the platform pattern on both iOS and
+     * Android, and it keeps one bar to read instead of two.
+     */
+    header?: ReactNode;
+    /**
+     * The band that sits IN the OS status-bar strip above the app bar — the carrier/clock row of a
+     * `display-mode: standalone` PWA, or the simulated one in a device-frame preview. It absorbs the
+     * top safe-area inset when present. Omit it in an ordinary browser tab, where the OS already owns
+     * that strip: the header then takes the inset.
+     */
+    statusBar?: ReactNode;
+    /**
+     * The sticky action bar pinned above the tab bar — the screen's primary verb (Scan, Save, Hand
+     * over) and at most one secondary. It sits OUTSIDE the scroll region, so it is always reachable
+     * without `position: sticky` and without a scroll-padding hack, and it takes the home-indicator
+     * inset whenever no tab bar follows it.
+     */
+    actions?: ActionProp;
+    /**
+     * Bottom tab bar (navigation) — the app's top-level destinations. Its children TILE: equal width,
+     * no seam, no page gutter, so the consumer never hand-rolls a grid with a column count. Always
+     * the last band, so it owns the home-indicator inset.
+     */
+    tabBar?: ReactNode;
+    /**
+     * Where the shell's one-screen height comes from. `"viewport"` (default) is the real app —
+     * exactly `100dvh`, document never scrolls. `"fill"` fills a BOUNDED parent instead (a
+     * device-frame preview, a phone view embedded in a wider page).
+     */
+    height?: MobileShellHeightProp;
+    className?: ClassNameProp;
+};
 /**
  * @see Separator — the tokenized rule, optionally INTERRUPTED by a localized label.
  *
@@ -256,7 +343,7 @@ export type AuthShellProp = {
  * what they have always been: an inert Radix rule, `decorative` by default, nothing announced.
  * With a `label` the root becomes the three-cell grid `rule · label · rule` and, because
  * "new messages" is CONTENT rather than decoration, a real `role="separator"` carrying the label
- * as its accessible name (gh#308). Every constant — rule weight, label gap, label inset, label
+ * as its accessible name. Every constant — rule weight, label gap, label inset, label
  * type ramp, rule and label colour per tone — is a `--separator-*` component token (rules #44/#45),
  * so a service retunes a day divider or an unread watermark from its theme and never forks CSS.
  */
@@ -284,7 +371,7 @@ export type SeparatorProp = Omit<React.HTMLAttributes<HTMLDivElement>, "children
     decorative?: boolean;
     className?: ClassNameProp;
 };
-/** @see AuthDivider — the auth-scoped preset over `Separator label` (gh#308). */
+/** @see AuthDivider — the auth-scoped preset over `Separator label`. */
 export type AuthDividerProp = {
     /** Short localized conjunction rendered between the two separator rules (for example, "or"). */
     label: string;
@@ -577,7 +664,7 @@ export type SidebarLinkComponentProp = ComponentType<SidebarLinkProp>;
  * @deprecated Prefer `Sidebar.linkComponent` (or `SidebarItem asChild`), where the library composes
  * the row and the consumer supplies only the element. `renderItem` leaves row CONTENT to the
  * consumer, which is how a `<Link>{item.label}</Link>` silently dropped every icon and badge
- * (gh#213). Spreading `rowProps` — including its `children` — now yields the canonical row.
+ *. Spreading `rowProps` — including its `children` — now yields the canonical row.
  */
 export type SidebarRenderItemProp = {
     className: string;
@@ -662,7 +749,7 @@ export type SidebarProp = {
     collapsed?: boolean;
     children?: ChildrenProp;
     /**
-     * THE framework-router contract (gh#213). Supply only the LINK ELEMENT TYPE; the Sidebar still
+     * THE framework-router contract. Supply only the LINK ELEMENT TYPE; the Sidebar still
      * composes the row — icon slot, label, badge, `data-active`/`aria-current`, the icon-only
      * collapsed rail and its tooltip name — and passes it as {@link SidebarLinkProp} `children`.
      * Used for every row that carries an `href`: top-level leaves, submenu children, collapsed-rail
@@ -690,7 +777,7 @@ export type SidebarProp = {
      *
      * Legacy escape hatch: return a SINGLE interactive element and the Sidebar merges the row styling
      * + active state onto it via Slot. Because row CONTENT stayed consumer-authored, a
-     * `<Link>{item.label}</Link>` silently dropped every icon and badge (the gh#213 production
+     * `<Link>{item.label}</Link>` silently dropped every icon and badge (the production
      * regression). `rowProps` now also carries the composed `children`, so spreading it restores the
      * canonical row.
      */