@raydenui/ui 0.9.7 → 0.10.1

package/README.md

@@ -6,91 +6,166 @@
 
 # Rayden UI
 
-A modern, accessible React component library built with Tailwind CSS v4.
-Pixel-perfect components from the [Rayna UI](https://www.raynaui.com/) design system.
+React components, page blocks, icons, and design tokens for building product interfaces. Rayden's default **Citrionus** flavor is built with Tailwind CSS v4 and includes TypeScript definitions, light and dark themes, and opt-in motion.
 
 [![npm version](https://img.shields.io/npm/v/@raydenui/ui.svg)](https://www.npmjs.com/package/@raydenui/ui)
 [![npm downloads](https://img.shields.io/npm/dm/@raydenui/ui.svg)](https://www.npmjs.com/package/@raydenui/ui)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Documentation](https://img.shields.io/badge/docs-rayden--docs.vercel.app-F56630)](https://rayden-docs.vercel.app)
-[![Storybook](https://img.shields.io/badge/Storybook-FF4785?logo=storybook&logoColor=white)](https://69b6d5e6cb6bbc778afec0ee-tcxvxzrkrt.chromatic.com/)
 
-## Quick Start
+[Documentation](https://rayden-docs.vercel.app) · [Storybook](https://main--69b6d5d8527b4eddb882e0a7.chromatic.com) · [Source](https://github.com/playbookTV/Rayden)
 
-The fastest way to get started is with `create-rayden-app`:
+## Quick start
+
+In an existing React application:
 
 ```bash
-npx create-rayden-app my-app
+npm install @raydenui/ui
+```
+
+React and React DOM 18 or later are required. Import the component stylesheet once in your app entry point or root layout. The optional font stylesheet serves bundled Hanken Grotesk and Manrope webfonts from your app.
+
+```tsx
+import "@raydenui/ui/styles.css";
+import "@raydenui/ui/fonts.css";
+import { Badge, Button, Input, ThemeProvider } from "@raydenui/ui";
+
+export default function App() {
+  return (
+    <ThemeProvider defaultTheme="system">
+      <main style={{ display: "grid", gap: 16, maxWidth: 400, padding: 24 }}>
+        <Input label="Email" type="email" placeholder="you@example.com" />
+        <Button variant="primary" size="lg">Subscribe</Button>
+        <Badge color="success">Active</Badge>
+      </main>
+    </ThemeProvider>
+  );
+}
+```
+
+The package includes compiled component CSS. Configure Tailwind CSS v4 in your own app if you also want to generate utility classes for your layouts. In Next.js App Router, put interactive examples and providers in a client component with `"use client"`; import global styles from the root layout.
+
+### Start a new project
+
+```bash
+npx create-rayden-app@latest my-app
+```
+
+Choose Vite or Next.js, TypeScript or JavaScript, and one of six starter templates: `blank`, `minimal`, `landing`, `dashboard`, `ecommerce`, or `blog`. Follow the CLI's printed next steps; it can install dependencies during setup.
+
+For an explicit setup with npm:
+
+```bash
+npx create-rayden-app@latest my-app -f vite -t minimal --ts --pm npm --install
 cd my-app
-npm install
 npm run dev
 ```
 
-### Templates
+## Package imports
 
-| Template | Description |
-|----------|-------------|
-| `blank` | Empty project, Rayden UI configured |
-| `minimal` | Demo of core components |
-| `landing` | Hero, features, pricing, CTA |
-| `dashboard` | Sidebar, tables, metrics |
-| `ecommerce` | Products, cart, checkout |
-| `blog` | Articles, categories, posts |
+| Import | What it provides |
+| --- | --- |
+| `@raydenui/ui` | Components, theme providers and hooks, icon discovery, and utilities |
+| `@raydenui/ui/blocks` | Ready-made application, account, marketing, and commerce blocks |
+| `@raydenui/ui/icons` | Named static icon data such as `heartIcon` |
+| `@raydenui/ui/chart` | `RaydenChart` and chart helpers |
+| `@raydenui/ui/motion` | Motion primitives, presets, and recipes |
+| `@raydenui/ui/preset` | Programmatic design tokens and the Tailwind preset |
+| `@raydenui/ui/styles.css` | Compiled component styles and theme variables |
+| `@raydenui/ui/fonts.css` | Optional bundled webfonts |
 
-### CLI Options
+Charts require the optional `chart.js` and `react-chartjs-2` peers. The `useRaydenInput`, `useRaydenSelect`, and other form integration hooks require `react-hook-form`. Install these only when using the corresponding features:
 
 ```bash
-npx create-rayden-app my-app -f vite -t landing --ts --pm pnpm
+npm install chart.js react-chartjs-2
+# For React Hook Form integration:
+npm install react-hook-form
 ```
 
-| Flag | Options |
-|------|---------|
-| `-f, --framework` | `vite` (recommended), `nextjs` |
-| `-t, --template` | `blank`, `minimal`, `landing`, `dashboard`, `ecommerce`, `blog` |
-| `--ts` / `--js` | TypeScript (default) or JavaScript |
-| `--pm` | `npm`, `pnpm`, `yarn` |
+## Components and blocks
 
-### Manual Installation
+- **Forms:** Button, ButtonGroup, Input, Select, Checkbox, Radio, Toggle, Chip, FileUpload, Counter, Slider, and DatePicker.
+- **Navigation:** Tabs, Breadcrumb, Pagination, SidebarMenu, DropdownMenu, and Stepper.
+- **Display and feedback:** Card, Table, Avatar, ActivityItem, ActivityContent, MetricsCard, Icon, EmptyStateIllustration, Alert, Badge, Banner, ProgressBar, ProgressCircle, Spinner, and Tooltip.
+- **Layout:** Accordion, Divider, and Modal. Charts are available as `RaydenChart` from the chart subpath.
 
-```bash
-npm install @raydenui/ui
+Import page blocks separately:
+
+```tsx
+import { PageHeaderBlock } from "@raydenui/ui/blocks";
+
+export function OverviewHeader() {
+  return (
+    <PageHeaderBlock
+      title="Overview"
+      description="A snapshot of your workspace activity."
+    />
+  );
+}
 ```
 
-## Usage
+The block library includes application shells, page headers, workspace switching, command palettes, login and account creation, profile settings, KPI overviews, task lists, tables, notifications, marketing sections, product browsing, carts, and checkout review. Blocks provide UI; connect their props and callbacks to your own data and services.
+
+## Icons
+
+Use a static data import for immediate rendering, including server rendering:
 
 ```tsx
-import "@raydenui/ui/styles.css";
-import { Button, Input, Badge } from "@raydenui/ui";
+import { Button, Icon } from "@raydenui/ui";
+import { heartIcon } from "@raydenui/ui/icons";
+
+export function FavoriteButton() {
+  return <Button icon={heartIcon} iconPosition="leading">Favorite</Button>;
+}
+
+export function FavoriteIcon() {
+  return <Icon icon={heartIcon} variant="solid" size={24} />;
+}
+```
 
-function App() {
+`<Icon name="heart" />` supports dynamic name lookup and loads the icon registry after mounting. Pass either `name` or `icon`. Both `outline` and `solid` variants are available. The `iconCatalog` export lists exact registry names and static export names without SVG artwork.
+
+Icons are decorative by default. Label icon-only controls on the control itself; a meaningful standalone icon needs `aria-hidden={false}`, `role="img"`, and an `aria-label`.
+
+## Theme and motion
+
+`ThemeProvider` supports `light`, `dark`, and `system`. Use `useTheme()` to read or change the selected theme.
+
+```tsx
+import { MotionProvider, Pressable } from "@raydenui/ui/motion";
+
+export function MotionExample() {
   return (
-    <div className="flex flex-col gap-4 p-8">
-      <Input label="Email" placeholder="you@example.com" />
-      <Button variant="primary" size="lg">Subscribe</Button>
-      <Badge color="success">Active</Badge>
-    </div>
+    <MotionProvider preset="snappy">
+      <Pressable>Continue</Pressable>
+    </MotionProvider>
   );
 }
 ```
 
-## Components (33+)
+Motion presets are `calm`, `snappy`, `playful`, and `reduced`. `Reveal`, `Collapse`, and `SharedLayout` provide additional primitives. Tabs and Modal require an explicit `motion` prop to animate. System reduced-motion preferences take precedence.
 
-**Forms & Inputs**: Button, ButtonGroup, Input, Select, FormControl, Chip, FileUpload, Counter, Slider, DatePicker
+## AI and MCP
 
-**Navigation**: Tabs, Breadcrumb, Pagination, SidebarMenu, DropdownMenu, Stepper
+[`@raydenui/ai`](https://www.npmjs.com/package/@raydenui/ai) supplies component contracts, token references, icon discovery, usage validation, and the Rayden MCP server. The MCP server ships in that package; it does not require a separate MCP package.
 
-**Data Display**: Table, Avatar, ActivityFeed, MetricsCard, Icon, EmptyStateIllustration, Chart
+For an MCP client that launches stdio servers, use command `npx` with arguments `-y` and `@raydenui/ai@latest`. To inspect the server from a terminal:
 
-**Feedback**: Alert, Badge, Banner, ProgressBar, ProgressCircle, Spinner, Tooltip
+```bash
+npx -y @raydenui/ai@latest --help
+```
+
+See the [AI package README](https://github.com/playbookTV/Rayden/tree/main/packages/rayden-ai#readme) for configuration and programmatic usage. The AI catalog identifies its reference UI version and supported components; it does not inspect your installed project automatically.
 
-**Layout**: Accordion, Divider, Modal
+## Development
 
-## Resources
+From a checkout with Node.js and pnpm installed:
+
+```bash
+pnpm install
+pnpm storybook
+```
 
-- [Documentation](https://rayden-docs.vercel.app) — Full component API and guides
-- [Storybook](https://main--69b6d5d8527b4eddb882e0a7.chromatic.com) — Interactive component explorer
-- [create-rayden-app](https://www.npmjs.com/package/create-rayden-app) — CLI scaffolding with 6 templates
-- [@raydenui/ai](https://www.npmjs.com/package/@raydenui/ai) — MCP server for AI-assisted development
+Use `pnpm typecheck`, `pnpm exec vitest run`, and `pnpm build` to check the UI. `pnpm check:pilots` validates the matching AI/MCP package and generated guidance after the UI build. Browser tests require a Playwright Chromium installation. See [CONTRIBUTING.md](https://github.com/playbookTV/Rayden/blob/main/CONTRIBUTING.md) for contributor setup.
 
 ## Contributors
 
@@ -105,4 +180,4 @@ function App() {
 
 ## License
 
-MIT
+MIT

package/dist/Table-DCNSxua1.d.cts

@@ -0,0 +1,31 @@
+import * as react from 'react';
+import { HTMLAttributes, TdHTMLAttributes, ThHTMLAttributes } from 'react';
+
+declare const illustrationNames: readonly ["calendar", "chat", "contacts", "dashboard", "favorites", "file-manager", "forms", "gallery", "inbox", "invoice", "notifications", "product-catalog", "project-list", "search", "shopping-cart", "subscriptions", "survey", "task-templates", "team"];
+type IllustrationName = (typeof illustrationNames)[number];
+
+type TableProps = HTMLAttributes<HTMLTableElement>;
+declare const Table: react.ForwardRefExoticComponent<TableProps & react.RefAttributes<HTMLTableElement>>;
+type TableHeaderProps = HTMLAttributes<HTMLTableSectionElement>;
+declare const TableHeader: react.ForwardRefExoticComponent<TableHeaderProps & react.RefAttributes<HTMLTableSectionElement>>;
+type TableBodyProps = HTMLAttributes<HTMLTableSectionElement>;
+declare const TableBody: react.ForwardRefExoticComponent<TableBodyProps & react.RefAttributes<HTMLTableSectionElement>>;
+interface TableRowProps extends HTMLAttributes<HTMLTableRowElement> {
+    /** Whether this row is selected */
+    selected?: boolean;
+}
+declare const TableRow: react.ForwardRefExoticComponent<TableRowProps & react.RefAttributes<HTMLTableRowElement>>;
+type SortDirection = "asc" | "desc" | null;
+interface TableHeadProps extends ThHTMLAttributes<HTMLTableCellElement> {
+    /** Enable sort indicator and click-to-sort behavior */
+    sortable?: boolean;
+    /** Current sort direction for this column */
+    sortDirection?: SortDirection;
+    /** Called when the sort indicator is clicked */
+    onSort?: () => void;
+}
+declare const TableHead: react.ForwardRefExoticComponent<TableHeadProps & react.RefAttributes<HTMLTableCellElement>>;
+type TableCellProps = TdHTMLAttributes<HTMLTableCellElement>;
+declare const TableCell: react.ForwardRefExoticComponent<TableCellProps & react.RefAttributes<HTMLTableCellElement>>;
+
+export { type IllustrationName as I, type SortDirection as S, Table as T, TableBody as a, type TableBodyProps as b, TableCell as c, type TableCellProps as d, TableHead as e, type TableHeadProps as f, TableHeader as g, type TableHeaderProps as h, type TableProps as i, TableRow as j, type TableRowProps as k, illustrationNames as l };

package/dist/Table-DCNSxua1.d.ts

@@ -0,0 +1,31 @@
+import * as react from 'react';
+import { HTMLAttributes, TdHTMLAttributes, ThHTMLAttributes } from 'react';
+
+declare const illustrationNames: readonly ["calendar", "chat", "contacts", "dashboard", "favorites", "file-manager", "forms", "gallery", "inbox", "invoice", "notifications", "product-catalog", "project-list", "search", "shopping-cart", "subscriptions", "survey", "task-templates", "team"];
+type IllustrationName = (typeof illustrationNames)[number];
+
+type TableProps = HTMLAttributes<HTMLTableElement>;
+declare const Table: react.ForwardRefExoticComponent<TableProps & react.RefAttributes<HTMLTableElement>>;
+type TableHeaderProps = HTMLAttributes<HTMLTableSectionElement>;
+declare const TableHeader: react.ForwardRefExoticComponent<TableHeaderProps & react.RefAttributes<HTMLTableSectionElement>>;
+type TableBodyProps = HTMLAttributes<HTMLTableSectionElement>;
+declare const TableBody: react.ForwardRefExoticComponent<TableBodyProps & react.RefAttributes<HTMLTableSectionElement>>;
+interface TableRowProps extends HTMLAttributes<HTMLTableRowElement> {
+    /** Whether this row is selected */
+    selected?: boolean;
+}
+declare const TableRow: react.ForwardRefExoticComponent<TableRowProps & react.RefAttributes<HTMLTableRowElement>>;
+type SortDirection = "asc" | "desc" | null;
+interface TableHeadProps extends ThHTMLAttributes<HTMLTableCellElement> {
+    /** Enable sort indicator and click-to-sort behavior */
+    sortable?: boolean;
+    /** Current sort direction for this column */
+    sortDirection?: SortDirection;
+    /** Called when the sort indicator is clicked */
+    onSort?: () => void;
+}
+declare const TableHead: react.ForwardRefExoticComponent<TableHeadProps & react.RefAttributes<HTMLTableCellElement>>;
+type TableCellProps = TdHTMLAttributes<HTMLTableCellElement>;
+declare const TableCell: react.ForwardRefExoticComponent<TableCellProps & react.RefAttributes<HTMLTableCellElement>>;
+
+export { type IllustrationName as I, type SortDirection as S, Table as T, TableBody as a, type TableBodyProps as b, TableCell as c, type TableCellProps as d, TableHead as e, type TableHeadProps as f, TableHeader as g, type TableHeaderProps as h, type TableProps as i, TableRow as j, type TableRowProps as k, illustrationNames as l };

package/dist/blocks/ApplicationShellBlock.cjs

@@ -0,0 +1,157 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApplicationShellBlock = ApplicationShellBlock;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const cn_1 = require("../utils/cn.cjs");
+const Icon_1 = require("../components/Icon/index.cjs");
+const Spinner_1 = require("../components/Spinner/index.cjs");
+const TIER = {
+    sm: {
+        expandedFlex: "hidden @min-[720px]:flex",
+        collapsed: "@min-[720px]:hidden",
+        row: "@min-[720px]:flex-row",
+        sidebarWidth: "@min-[720px]:w-[248px]",
+        pad: "@min-[720px]:px-6",
+    },
+    md: {
+        expandedFlex: "hidden @min-[900px]:flex",
+        collapsed: "@min-[900px]:hidden",
+        row: "@min-[900px]:flex-row",
+        sidebarWidth: "@min-[900px]:w-[264px]",
+        pad: "@min-[900px]:px-6",
+    },
+    lg: {
+        expandedFlex: "hidden @min-[1080px]:flex",
+        collapsed: "@min-[1080px]:hidden",
+        row: "@min-[1080px]:flex-row",
+        sidebarWidth: "@min-[1080px]:w-[280px]",
+        pad: "@min-[1080px]:px-6",
+    },
+};
+/* ─── Shared recipes ─────────────────────────────────────────────────── */
+const FOCUS_RING = "focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-action-primary-text";
+const NAV_ITEM_BASE = (0, cn_1.cn)("group flex min-h-11 w-full min-w-0 items-start gap-3 rounded-lg px-3 py-2 text-left text-body-sm font-medium transition-colors", FOCUS_RING);
+/* ─── Navigation item ────────────────────────────────────────────────── */
+function NavBadge({ badge, badgeDescription, }) {
+    return ((0, jsx_runtime_1.jsxs)("span", { className: "ml-auto inline-flex shrink-0 items-center rounded-full bg-grey-100 px-2 py-0.5 text-body-xs font-semibold text-grey-700", children: [(0, jsx_runtime_1.jsx)("span", { "aria-hidden": badgeDescription ? true : undefined, children: badge }), badgeDescription && (0, jsx_runtime_1.jsx)("span", { className: "sr-only", children: badgeDescription })] }));
+}
+/**
+ * One element for both arrangements. The collapsed panel used to rebuild
+ * destinations as buttons, which dropped the href and sent them nowhere
+ * (audit B01); rendering an anchor whenever there is an href makes that
+ * impossible to reintroduce.
+ */
+function ShellNavItem({ item, showDescription, onNavigate, reasonIdPrefix, }) {
+    const unavailable = "unavailableReason" in item ? item.unavailableReason : undefined;
+    const reasonId = `${reasonIdPrefix}-${item.id}-reason`;
+    const body = ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [item.icon && ((0, jsx_runtime_1.jsx)(Icon_1.Icon, { name: item.icon, size: "md", className: (0, cn_1.cn)("mt-0.5 shrink-0", item.current ? "text-action-primary-text" : "text-grey-500") })), (0, jsx_runtime_1.jsxs)("span", { className: "flex min-w-0 flex-1 flex-col gap-0.5", children: [(0, jsx_runtime_1.jsx)("span", { className: "break-words", children: item.label }), showDescription && item.description && ((0, jsx_runtime_1.jsx)("span", { className: "text-body-xs font-normal break-words text-grey-500", children: item.description }))] }), item.badge && (0, jsx_runtime_1.jsx)(NavBadge, { badge: item.badge, badgeDescription: item.badgeDescription })] }));
+    if (unavailable) {
+        return ((0, jsx_runtime_1.jsxs)("li", { children: [(0, jsx_runtime_1.jsxs)("button", { type: "button", disabled: true, "aria-describedby": reasonId, className: (0, cn_1.cn)(NAV_ITEM_BASE, "cursor-not-allowed text-grey-500"), children: [(0, jsx_runtime_1.jsx)(Icon_1.Icon, { name: "lock", size: "md", className: "mt-0.5 shrink-0 text-grey-500", "aria-hidden": "true" }), (0, jsx_runtime_1.jsx)("span", { className: "flex min-w-0 flex-1 flex-col gap-0.5", children: (0, jsx_runtime_1.jsx)("span", { className: "break-words", children: item.label }) })] }), (0, jsx_runtime_1.jsx)("p", { id: reasonId, className: "px-3 pb-1 text-body-xs break-words text-grey-500", children: unavailable })] }));
+    }
+    const tone = item.current
+        ? "bg-primary-50 text-grey-900"
+        : "text-grey-700 hover:bg-surface-muted hover:text-grey-900";
+    if (item.href) {
+        return ((0, jsx_runtime_1.jsx)("li", { children: (0, jsx_runtime_1.jsx)("a", { href: item.href, "aria-current": item.current ? "page" : undefined, onClick: () => {
+                    item.onClick?.();
+                    onNavigate?.();
+                }, ...(item.external ? { target: "_blank", rel: "noreferrer" } : {}), className: (0, cn_1.cn)(NAV_ITEM_BASE, tone), children: body }) }));
+    }
+    return ((0, jsx_runtime_1.jsx)("li", { children: (0, jsx_runtime_1.jsx)("button", { type: "button", "aria-current": item.current ? "page" : undefined, onClick: () => {
+                item.onClick?.();
+                onNavigate?.();
+            }, className: (0, cn_1.cn)(NAV_ITEM_BASE, "cursor-pointer", tone), children: body }) }));
+}
+/* ─── Component ──────────────────────────────────────────────────────── */
+function ApplicationShellBlock({ brand, brandHref, onBrandClick, navSections = [], navLabel = "Main", sectionHeadingLevel = "h2", navStatus = "idle", navErrorMessage = "Navigation could not be loaded.", onRetryNav, navLoadingMessage = "Loading navigation", navEmptyMessage, search, switcher, actions = [], actionsLabel = "Account and tools", sidebarFooter, openMenuLabel = "Open navigation", closeMenuLabel = "Close navigation", skipLinkLabel = "Skip to main content", skipNavLabel = "Skip links", expandAt = "md", mainScroll = "page", stickyTopBar = true, mainLabel = "Workspace", children, className, }) {
+    const uid = (0, react_1.useId)();
+    const mainId = `${uid}-main`;
+    const panelId = `${uid}-nav-panel`;
+    const [menuOpen, setMenuOpen] = (0, react_1.useState)(false);
+    const toggleRef = (0, react_1.useRef)(null);
+    const tier = TIER[expandAt];
+    const SectionHeading = sectionHeadingLevel;
+    const itemCount = navSections.reduce((total, section) => total + section.items.length, 0);
+    /**
+     * A shell with nothing to navigate to renders no rail and no toggle, rather
+     * than an empty rail and a control that opens nothing. Supplying
+     * `navEmptyMessage` is how a consumer asks for the empty rail instead.
+     */
+    const hasNav = navStatus !== "idle" || itemCount > 0 || Boolean(navEmptyMessage);
+    const regionScroll = mainScroll === "region";
+    function closeMenu() {
+        setMenuOpen(false);
+    }
+    function handleKeyDown(event) {
+        if (event.defaultPrevented || event.key !== "Escape" || !menuOpen)
+            return;
+        setMenuOpen(false);
+        toggleRef.current?.focus();
+    }
+    /* ── Navigation body, rendered in the sidebar and in the collapsed panel ── */
+    function renderNav(placement) {
+        if (navStatus === "loading") {
+            return ((0, jsx_runtime_1.jsxs)("div", { role: "status", className: "flex items-center gap-2 px-3 py-4 text-body-sm text-grey-500", children: [(0, jsx_runtime_1.jsx)(Spinner_1.Spinner, { size: "sm" }), (0, jsx_runtime_1.jsx)("span", { children: navLoadingMessage })] }));
+        }
+        if (navStatus === "error") {
+            return ((0, jsx_runtime_1.jsxs)("div", { role: "alert", className: "mx-1 rounded-lg border border-error-200 bg-error-50 px-3 py-3 text-body-sm text-error-700", children: [(0, jsx_runtime_1.jsx)("p", { className: "break-words", children: navErrorMessage }), onRetryNav && ((0, jsx_runtime_1.jsxs)("button", { type: "button", onClick: onRetryNav, className: (0, cn_1.cn)("mt-2 inline-flex min-h-9 cursor-pointer items-center gap-2 rounded-lg border-[1.5px] border-current px-3 py-1.5 font-semibold", FOCUS_RING), children: [(0, jsx_runtime_1.jsx)(Icon_1.Icon, { name: "refresh", size: "sm", "aria-hidden": "true" }), "Try again"] }))] }));
+        }
+        if (itemCount === 0) {
+            return navEmptyMessage ? ((0, jsx_runtime_1.jsx)("p", { className: "px-3 py-4 text-body-sm break-words text-grey-500", children: navEmptyMessage })) : null;
+        }
+        return ((0, jsx_runtime_1.jsx)("div", { className: "flex flex-col gap-5", children: navSections.map((section) => {
+                const headingId = `${uid}-${placement}-${section.id}`;
+                return ((0, jsx_runtime_1.jsxs)("div", { className: "flex flex-col gap-1", children: [section.label && ((0, jsx_runtime_1.jsx)(SectionHeading, { id: headingId, className: "px-3 pb-1 text-caption-sm font-semibold break-words text-grey-500 uppercase", children: section.label })), (0, jsx_runtime_1.jsx)("ul", { className: "flex list-none flex-col gap-0.5", ...(section.label ? { "aria-labelledby": headingId } : {}), children: section.items.map((item) => ((0, jsx_runtime_1.jsx)(ShellNavItem, { item: item, showDescription: placement === "panel", onNavigate: placement === "panel" ? closeMenu : undefined, reasonIdPrefix: `${uid}-${placement}` }, item.id))) })] }, section.id));
+            }) }));
+    }
+    /* ── Brand ── */
+    function renderBrand(extraClassName) {
+        if (!brand)
+            return null;
+        const content = (0, jsx_runtime_1.jsx)("span", { className: "flex min-w-0 items-center gap-2 break-words", children: brand });
+        if (brandHref) {
+            return ((0, jsx_runtime_1.jsx)("a", { href: brandHref, onClick: onBrandClick, className: (0, cn_1.cn)("rounded", FOCUS_RING, extraClassName), children: content }));
+        }
+        if (onBrandClick) {
+            return ((0, jsx_runtime_1.jsx)("button", { type: "button", onClick: onBrandClick, className: (0, cn_1.cn)("cursor-pointer rounded text-left", FOCUS_RING, extraClassName), children: content }));
+        }
+        return (0, jsx_runtime_1.jsx)("div", { className: (0, cn_1.cn)("min-w-0", extraClassName), children: content });
+    }
+    /* ── Top-bar actions ── */
+    function renderAction(action) {
+        const iconOnly = Boolean(action.icon);
+        const inner = ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [action.icon ? ((0, jsx_runtime_1.jsx)(Icon_1.Icon, { name: action.icon, size: "md", "aria-hidden": "true" })) : ((0, jsx_runtime_1.jsx)("span", { className: "break-words", children: action.label })), iconOnly && (0, jsx_runtime_1.jsx)("span", { className: "sr-only", children: action.label }), action.badge && ((0, jsx_runtime_1.jsxs)("span", { className: "absolute top-0.5 right-0.5 inline-flex min-w-4 items-center justify-center rounded-full bg-action-primary px-1 text-[10px] leading-4 font-semibold text-white", children: [(0, jsx_runtime_1.jsx)("span", { "aria-hidden": action.badgeDescription ? true : undefined, children: action.badge }), action.badgeDescription && (0, jsx_runtime_1.jsx)("span", { className: "sr-only", children: action.badgeDescription })] }))] }));
+        const classes = (0, cn_1.cn)("relative inline-flex min-h-11 min-w-11 items-center justify-center gap-2 rounded-lg px-2 text-body-sm font-medium text-grey-700 transition-colors hover:bg-surface-muted hover:text-grey-900", FOCUS_RING);
+        if (action.href) {
+            return ((0, jsx_runtime_1.jsx)("a", { href: action.href, onClick: action.onClick, ...(action.external ? { target: "_blank", rel: "noreferrer" } : {}), className: classes, children: inner }, action.id));
+        }
+        return ((0, jsx_runtime_1.jsx)("button", { type: "button", onClick: action.onClick, className: (0, cn_1.cn)(classes, "cursor-pointer"), children: inner }, action.id));
+    }
+    const sidebarInner = ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [brand && (0, jsx_runtime_1.jsx)("div", { className: "px-3 pb-4", children: renderBrand("inline-flex min-h-10 items-center") }), (0, jsx_runtime_1.jsx)("div", { className: (0, cn_1.cn)("flex-1", regionScroll && "min-h-0 overflow-y-auto"), children: renderNav("sidebar") }), sidebarFooter && ((0, jsx_runtime_1.jsx)("div", { className: "mt-4 border-t border-surface-border px-3 pt-4", children: sidebarFooter }))] }));
+    return ((0, jsx_runtime_1.jsxs)("div", { onKeyDown: handleKeyDown, className: (0, cn_1.cn)(
+        // `@container` sits on the outermost element, outside the padded
+        // surfaces, so `@min-[…]` padding inside resolves against the shell's
+        // real width. `relative` keeps the skip link's positioned box inside
+        // the shell instead of widening the document (audit B03).
+        "@container relative flex w-full flex-col bg-surface-muted", regionScroll && "h-full max-h-full overflow-hidden", className), children: [(0, jsx_runtime_1.jsx)("nav", { "aria-label": skipNavLabel, children: (0, jsx_runtime_1.jsx)("a", { href: `#${mainId}`, className: (0, cn_1.cn)("sr-only rounded-lg bg-surface px-4 py-2 text-body-sm font-semibold text-action-primary-text shadow-soft-sm", "focus:not-sr-only focus:absolute focus:top-3 focus:left-3 focus:z-40", FOCUS_RING), children: skipLinkLabel }) }), (0, jsx_runtime_1.jsxs)("div", { className: (0, cn_1.cn)("flex min-h-0 w-full flex-1 flex-col", tier.row), children: [hasNav && (
+                    // The landmark wraps the brand, the destinations, and the sidebar
+                    // footer. With the landmark on an inner element the brand and footer
+                    // were page content outside every landmark, which axe's `region` rule
+                    // reported and a screen-reader user would meet as stray text.
+                    (0, jsx_runtime_1.jsx)("nav", { "aria-label": navLabel, className: (0, cn_1.cn)("w-full shrink-0 flex-col border-r border-surface-border bg-surface px-3 py-5", tier.sidebarWidth, regionScroll && "min-h-0", tier.expandedFlex), children: sidebarInner })), (0, jsx_runtime_1.jsxs)("div", { className: (0, cn_1.cn)("flex min-w-0 min-h-0 flex-1 flex-col"), children: [(0, jsx_runtime_1.jsxs)("header", { className: (0, cn_1.cn)("flex w-full flex-wrap items-center gap-2 border-b border-surface-border bg-surface px-4 py-2", tier.pad, stickyTopBar && !regionScroll && "sticky top-0 z-20"), children: [hasNav && ((0, jsx_runtime_1.jsxs)("button", { ref: toggleRef, type: "button", onClick: () => setMenuOpen((open) => !open), "aria-expanded": menuOpen, "aria-controls": panelId, className: (0, cn_1.cn)("inline-flex min-h-11 min-w-11 shrink-0 cursor-pointer items-center justify-center rounded-lg text-grey-700 hover:bg-surface-muted hover:text-grey-900", FOCUS_RING, tier.collapsed), children: [(0, jsx_runtime_1.jsx)(Icon_1.Icon, { name: menuOpen ? "multiply" : "list", size: "md", "aria-hidden": "true" }), (0, jsx_runtime_1.jsx)("span", { className: "sr-only", children: menuOpen ? closeMenuLabel : openMenuLabel })] })), brand && !(hasNav && switcher) && ((0, jsx_runtime_1.jsx)("div", { className: (0, cn_1.cn)("min-w-0", hasNav ? tier.collapsed : undefined), children: renderBrand("inline-flex min-h-10 items-center") })), switcher && (
+                                    // A floor, not a fixed width: the switcher is a feature, and a
+                                    // feature squeezed to nothing has been dropped. It wraps onto the
+                                    // next row before it shrinks below this.
+                                    (0, jsx_runtime_1.jsx)("div", { className: "flex min-w-0 flex-1 @min-[640px]:min-w-[168px] @min-[640px]:flex-none", children: switcher })), search && ((0, jsx_runtime_1.jsx)("div", { className: (0, cn_1.cn)(
+                                        // Wraps onto its own row while the shell is narrow rather
+                                        // than being removed. One instance, so its state is stable.
+                                        "order-last w-full min-w-0 basis-full", "@min-[640px]:order-none @min-[640px]:w-auto @min-[640px]:max-w-[420px] @min-[640px]:flex-1 @min-[640px]:basis-auto"), children: search })), actions.length > 0 && ((0, jsx_runtime_1.jsx)("div", { role: "group", "aria-label": actionsLabel, className: "ml-auto flex shrink-0 items-center gap-1", children: actions.map((action) => renderAction(action)) }))] }), hasNav && ((0, jsx_runtime_1.jsxs)("nav", { id: panelId, "aria-label": navLabel, className: (0, cn_1.cn)("border-b border-surface-border bg-surface px-3 py-4", tier.collapsed, !menuOpen && "hidden"), children: [brand && switcher && ((0, jsx_runtime_1.jsx)("div", { className: "px-3 pb-4", children: renderBrand("inline-flex min-h-11 items-center") })), renderNav("panel"), sidebarFooter && ((0, jsx_runtime_1.jsx)("div", { className: "mt-4 border-t border-surface-border px-3 pt-4", children: sidebarFooter }))] })), (0, jsx_runtime_1.jsx)("main", { id: mainId, 
+                                /**
+                                 * In `region` mode the workspace is its own scroll container, so it
+                                 * has to be reachable from the keyboard even when the content it
+                                 * holds is not focusable (WCAG 2.1.1). In `page` mode it is only a
+                                 * skip-link target and should not be a tab stop.
+                                 */
+                                tabIndex: regionScroll ? 0 : -1, "aria-label": mainLabel, className: (0, cn_1.cn)("min-w-0 flex-1 px-4 py-6", tier.pad, regionScroll && "min-h-0 overflow-y-auto"), children: children })] })] })] }));
+}

package/dist/blocks/ApplicationShellBlock.js

@@ -0,0 +1,154 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useId, useRef, useState, } from "react";
+import { cn } from "../utils/cn.js";
+import { Icon } from "../components/Icon/index.js";
+import { Spinner } from "../components/Spinner/index.js";
+const TIER = {
+    sm: {
+        expandedFlex: "hidden @min-[720px]:flex",
+        collapsed: "@min-[720px]:hidden",
+        row: "@min-[720px]:flex-row",
+        sidebarWidth: "@min-[720px]:w-[248px]",
+        pad: "@min-[720px]:px-6",
+    },
+    md: {
+        expandedFlex: "hidden @min-[900px]:flex",
+        collapsed: "@min-[900px]:hidden",
+        row: "@min-[900px]:flex-row",
+        sidebarWidth: "@min-[900px]:w-[264px]",
+        pad: "@min-[900px]:px-6",
+    },
+    lg: {
+        expandedFlex: "hidden @min-[1080px]:flex",
+        collapsed: "@min-[1080px]:hidden",
+        row: "@min-[1080px]:flex-row",
+        sidebarWidth: "@min-[1080px]:w-[280px]",
+        pad: "@min-[1080px]:px-6",
+    },
+};
+/* ─── Shared recipes ─────────────────────────────────────────────────── */
+const FOCUS_RING = "focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-action-primary-text";
+const NAV_ITEM_BASE = cn("group flex min-h-11 w-full min-w-0 items-start gap-3 rounded-lg px-3 py-2 text-left text-body-sm font-medium transition-colors", FOCUS_RING);
+/* ─── Navigation item ────────────────────────────────────────────────── */
+function NavBadge({ badge, badgeDescription, }) {
+    return (_jsxs("span", { className: "ml-auto inline-flex shrink-0 items-center rounded-full bg-grey-100 px-2 py-0.5 text-body-xs font-semibold text-grey-700", children: [_jsx("span", { "aria-hidden": badgeDescription ? true : undefined, children: badge }), badgeDescription && _jsx("span", { className: "sr-only", children: badgeDescription })] }));
+}
+/**
+ * One element for both arrangements. The collapsed panel used to rebuild
+ * destinations as buttons, which dropped the href and sent them nowhere
+ * (audit B01); rendering an anchor whenever there is an href makes that
+ * impossible to reintroduce.
+ */
+function ShellNavItem({ item, showDescription, onNavigate, reasonIdPrefix, }) {
+    const unavailable = "unavailableReason" in item ? item.unavailableReason : undefined;
+    const reasonId = `${reasonIdPrefix}-${item.id}-reason`;
+    const body = (_jsxs(_Fragment, { children: [item.icon && (_jsx(Icon, { name: item.icon, size: "md", className: cn("mt-0.5 shrink-0", item.current ? "text-action-primary-text" : "text-grey-500") })), _jsxs("span", { className: "flex min-w-0 flex-1 flex-col gap-0.5", children: [_jsx("span", { className: "break-words", children: item.label }), showDescription && item.description && (_jsx("span", { className: "text-body-xs font-normal break-words text-grey-500", children: item.description }))] }), item.badge && _jsx(NavBadge, { badge: item.badge, badgeDescription: item.badgeDescription })] }));
+    if (unavailable) {
+        return (_jsxs("li", { children: [_jsxs("button", { type: "button", disabled: true, "aria-describedby": reasonId, className: cn(NAV_ITEM_BASE, "cursor-not-allowed text-grey-500"), children: [_jsx(Icon, { name: "lock", size: "md", className: "mt-0.5 shrink-0 text-grey-500", "aria-hidden": "true" }), _jsx("span", { className: "flex min-w-0 flex-1 flex-col gap-0.5", children: _jsx("span", { className: "break-words", children: item.label }) })] }), _jsx("p", { id: reasonId, className: "px-3 pb-1 text-body-xs break-words text-grey-500", children: unavailable })] }));
+    }
+    const tone = item.current
+        ? "bg-primary-50 text-grey-900"
+        : "text-grey-700 hover:bg-surface-muted hover:text-grey-900";
+    if (item.href) {
+        return (_jsx("li", { children: _jsx("a", { href: item.href, "aria-current": item.current ? "page" : undefined, onClick: () => {
+                    item.onClick?.();
+                    onNavigate?.();
+                }, ...(item.external ? { target: "_blank", rel: "noreferrer" } : {}), className: cn(NAV_ITEM_BASE, tone), children: body }) }));
+    }
+    return (_jsx("li", { children: _jsx("button", { type: "button", "aria-current": item.current ? "page" : undefined, onClick: () => {
+                item.onClick?.();
+                onNavigate?.();
+            }, className: cn(NAV_ITEM_BASE, "cursor-pointer", tone), children: body }) }));
+}
+/* ─── Component ──────────────────────────────────────────────────────── */
+export function ApplicationShellBlock({ brand, brandHref, onBrandClick, navSections = [], navLabel = "Main", sectionHeadingLevel = "h2", navStatus = "idle", navErrorMessage = "Navigation could not be loaded.", onRetryNav, navLoadingMessage = "Loading navigation", navEmptyMessage, search, switcher, actions = [], actionsLabel = "Account and tools", sidebarFooter, openMenuLabel = "Open navigation", closeMenuLabel = "Close navigation", skipLinkLabel = "Skip to main content", skipNavLabel = "Skip links", expandAt = "md", mainScroll = "page", stickyTopBar = true, mainLabel = "Workspace", children, className, }) {
+    const uid = useId();
+    const mainId = `${uid}-main`;
+    const panelId = `${uid}-nav-panel`;
+    const [menuOpen, setMenuOpen] = useState(false);
+    const toggleRef = useRef(null);
+    const tier = TIER[expandAt];
+    const SectionHeading = sectionHeadingLevel;
+    const itemCount = navSections.reduce((total, section) => total + section.items.length, 0);
+    /**
+     * A shell with nothing to navigate to renders no rail and no toggle, rather
+     * than an empty rail and a control that opens nothing. Supplying
+     * `navEmptyMessage` is how a consumer asks for the empty rail instead.
+     */
+    const hasNav = navStatus !== "idle" || itemCount > 0 || Boolean(navEmptyMessage);
+    const regionScroll = mainScroll === "region";
+    function closeMenu() {
+        setMenuOpen(false);
+    }
+    function handleKeyDown(event) {
+        if (event.defaultPrevented || event.key !== "Escape" || !menuOpen)
+            return;
+        setMenuOpen(false);
+        toggleRef.current?.focus();
+    }
+    /* ── Navigation body, rendered in the sidebar and in the collapsed panel ── */
+    function renderNav(placement) {
+        if (navStatus === "loading") {
+            return (_jsxs("div", { role: "status", className: "flex items-center gap-2 px-3 py-4 text-body-sm text-grey-500", children: [_jsx(Spinner, { size: "sm" }), _jsx("span", { children: navLoadingMessage })] }));
+        }
+        if (navStatus === "error") {
+            return (_jsxs("div", { role: "alert", className: "mx-1 rounded-lg border border-error-200 bg-error-50 px-3 py-3 text-body-sm text-error-700", children: [_jsx("p", { className: "break-words", children: navErrorMessage }), onRetryNav && (_jsxs("button", { type: "button", onClick: onRetryNav, className: cn("mt-2 inline-flex min-h-9 cursor-pointer items-center gap-2 rounded-lg border-[1.5px] border-current px-3 py-1.5 font-semibold", FOCUS_RING), children: [_jsx(Icon, { name: "refresh", size: "sm", "aria-hidden": "true" }), "Try again"] }))] }));
+        }
+        if (itemCount === 0) {
+            return navEmptyMessage ? (_jsx("p", { className: "px-3 py-4 text-body-sm break-words text-grey-500", children: navEmptyMessage })) : null;
+        }
+        return (_jsx("div", { className: "flex flex-col gap-5", children: navSections.map((section) => {
+                const headingId = `${uid}-${placement}-${section.id}`;
+                return (_jsxs("div", { className: "flex flex-col gap-1", children: [section.label && (_jsx(SectionHeading, { id: headingId, className: "px-3 pb-1 text-caption-sm font-semibold break-words text-grey-500 uppercase", children: section.label })), _jsx("ul", { className: "flex list-none flex-col gap-0.5", ...(section.label ? { "aria-labelledby": headingId } : {}), children: section.items.map((item) => (_jsx(ShellNavItem, { item: item, showDescription: placement === "panel", onNavigate: placement === "panel" ? closeMenu : undefined, reasonIdPrefix: `${uid}-${placement}` }, item.id))) })] }, section.id));
+            }) }));
+    }
+    /* ── Brand ── */
+    function renderBrand(extraClassName) {
+        if (!brand)
+            return null;
+        const content = _jsx("span", { className: "flex min-w-0 items-center gap-2 break-words", children: brand });
+        if (brandHref) {
+            return (_jsx("a", { href: brandHref, onClick: onBrandClick, className: cn("rounded", FOCUS_RING, extraClassName), children: content }));
+        }
+        if (onBrandClick) {
+            return (_jsx("button", { type: "button", onClick: onBrandClick, className: cn("cursor-pointer rounded text-left", FOCUS_RING, extraClassName), children: content }));
+        }
+        return _jsx("div", { className: cn("min-w-0", extraClassName), children: content });
+    }
+    /* ── Top-bar actions ── */
+    function renderAction(action) {
+        const iconOnly = Boolean(action.icon);
+        const inner = (_jsxs(_Fragment, { children: [action.icon ? (_jsx(Icon, { name: action.icon, size: "md", "aria-hidden": "true" })) : (_jsx("span", { className: "break-words", children: action.label })), iconOnly && _jsx("span", { className: "sr-only", children: action.label }), action.badge && (_jsxs("span", { className: "absolute top-0.5 right-0.5 inline-flex min-w-4 items-center justify-center rounded-full bg-action-primary px-1 text-[10px] leading-4 font-semibold text-white", children: [_jsx("span", { "aria-hidden": action.badgeDescription ? true : undefined, children: action.badge }), action.badgeDescription && _jsx("span", { className: "sr-only", children: action.badgeDescription })] }))] }));
+        const classes = cn("relative inline-flex min-h-11 min-w-11 items-center justify-center gap-2 rounded-lg px-2 text-body-sm font-medium text-grey-700 transition-colors hover:bg-surface-muted hover:text-grey-900", FOCUS_RING);
+        if (action.href) {
+            return (_jsx("a", { href: action.href, onClick: action.onClick, ...(action.external ? { target: "_blank", rel: "noreferrer" } : {}), className: classes, children: inner }, action.id));
+        }
+        return (_jsx("button", { type: "button", onClick: action.onClick, className: cn(classes, "cursor-pointer"), children: inner }, action.id));
+    }
+    const sidebarInner = (_jsxs(_Fragment, { children: [brand && _jsx("div", { className: "px-3 pb-4", children: renderBrand("inline-flex min-h-10 items-center") }), _jsx("div", { className: cn("flex-1", regionScroll && "min-h-0 overflow-y-auto"), children: renderNav("sidebar") }), sidebarFooter && (_jsx("div", { className: "mt-4 border-t border-surface-border px-3 pt-4", children: sidebarFooter }))] }));
+    return (_jsxs("div", { onKeyDown: handleKeyDown, className: cn(
+        // `@container` sits on the outermost element, outside the padded
+        // surfaces, so `@min-[…]` padding inside resolves against the shell's
+        // real width. `relative` keeps the skip link's positioned box inside
+        // the shell instead of widening the document (audit B03).
+        "@container relative flex w-full flex-col bg-surface-muted", regionScroll && "h-full max-h-full overflow-hidden", className), children: [_jsx("nav", { "aria-label": skipNavLabel, children: _jsx("a", { href: `#${mainId}`, className: cn("sr-only rounded-lg bg-surface px-4 py-2 text-body-sm font-semibold text-action-primary-text shadow-soft-sm", "focus:not-sr-only focus:absolute focus:top-3 focus:left-3 focus:z-40", FOCUS_RING), children: skipLinkLabel }) }), _jsxs("div", { className: cn("flex min-h-0 w-full flex-1 flex-col", tier.row), children: [hasNav && (
+                    // The landmark wraps the brand, the destinations, and the sidebar
+                    // footer. With the landmark on an inner element the brand and footer
+                    // were page content outside every landmark, which axe's `region` rule
+                    // reported and a screen-reader user would meet as stray text.
+                    _jsx("nav", { "aria-label": navLabel, className: cn("w-full shrink-0 flex-col border-r border-surface-border bg-surface px-3 py-5", tier.sidebarWidth, regionScroll && "min-h-0", tier.expandedFlex), children: sidebarInner })), _jsxs("div", { className: cn("flex min-w-0 min-h-0 flex-1 flex-col"), children: [_jsxs("header", { className: cn("flex w-full flex-wrap items-center gap-2 border-b border-surface-border bg-surface px-4 py-2", tier.pad, stickyTopBar && !regionScroll && "sticky top-0 z-20"), children: [hasNav && (_jsxs("button", { ref: toggleRef, type: "button", onClick: () => setMenuOpen((open) => !open), "aria-expanded": menuOpen, "aria-controls": panelId, className: cn("inline-flex min-h-11 min-w-11 shrink-0 cursor-pointer items-center justify-center rounded-lg text-grey-700 hover:bg-surface-muted hover:text-grey-900", FOCUS_RING, tier.collapsed), children: [_jsx(Icon, { name: menuOpen ? "multiply" : "list", size: "md", "aria-hidden": "true" }), _jsx("span", { className: "sr-only", children: menuOpen ? closeMenuLabel : openMenuLabel })] })), brand && !(hasNav && switcher) && (_jsx("div", { className: cn("min-w-0", hasNav ? tier.collapsed : undefined), children: renderBrand("inline-flex min-h-10 items-center") })), switcher && (
+                                    // A floor, not a fixed width: the switcher is a feature, and a
+                                    // feature squeezed to nothing has been dropped. It wraps onto the
+                                    // next row before it shrinks below this.
+                                    _jsx("div", { className: "flex min-w-0 flex-1 @min-[640px]:min-w-[168px] @min-[640px]:flex-none", children: switcher })), search && (_jsx("div", { className: cn(
+                                        // Wraps onto its own row while the shell is narrow rather
+                                        // than being removed. One instance, so its state is stable.
+                                        "order-last w-full min-w-0 basis-full", "@min-[640px]:order-none @min-[640px]:w-auto @min-[640px]:max-w-[420px] @min-[640px]:flex-1 @min-[640px]:basis-auto"), children: search })), actions.length > 0 && (_jsx("div", { role: "group", "aria-label": actionsLabel, className: "ml-auto flex shrink-0 items-center gap-1", children: actions.map((action) => renderAction(action)) }))] }), hasNav && (_jsxs("nav", { id: panelId, "aria-label": navLabel, className: cn("border-b border-surface-border bg-surface px-3 py-4", tier.collapsed, !menuOpen && "hidden"), children: [brand && switcher && (_jsx("div", { className: "px-3 pb-4", children: renderBrand("inline-flex min-h-11 items-center") })), renderNav("panel"), sidebarFooter && (_jsx("div", { className: "mt-4 border-t border-surface-border px-3 pt-4", children: sidebarFooter }))] })), _jsx("main", { id: mainId, 
+                                /**
+                                 * In `region` mode the workspace is its own scroll container, so it
+                                 * has to be reachable from the keyboard even when the content it
+                                 * holds is not focusable (WCAG 2.1.1). In `page` mode it is only a
+                                 * skip-link target and should not be a tab stop.
+                                 */
+                                tabIndex: regionScroll ? 0 : -1, "aria-label": mainLabel, className: cn("min-w-0 flex-1 px-4 py-6", tier.pad, regionScroll && "min-h-0 overflow-y-auto"), children: children })] })] })] }));
+}