@scalewing/react 1.46.0 → 1.47.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @scalewing/react
 
+## 1.47.0
+
+### Minor Changes
+
+- 26fe8e5: `AppShell`: a web workspace's frame with a pinned side navigation of grouped destinations beside the page in `main`, which scrolls with the document. From 75rem a full sidebar (header, groups with optional captions, footer; glyph, label and count per destination, the current one on a quiet fill), sticky at the viewport's height with only its nav scrolling; from `lg` to 75rem an icon rail whose labels stay in each link's name and show in a Tooltip, the count a pill on the glyph, with `railHeader`/`railFooter`; below `lg` a sticky AppHeader `bar` whose menu button opens the same navigation in a modal drawer from the inline start (Escape, a press outside, its close button or choosing a destination close it, focus returning to the menu button). Items follow `SectionNav`'s rules plus a required `icon`; `onNavigate` takes a plain press for a client router; invalid groups, items or words throw a `RangeError`. New classes `sw-app-shell*` (the count joins the shared count pill as `sw-app-shell-count`); the 75rem width is internal, not a public breakpoint. `SectionNav` and `AppShell` now share one item validation (`nav-items.ts`); `SectionNav`'s behaviour and messages are unchanged. No new tokens or dependencies. Request: `docs/requests/futmas-app-shell.md`.
+- 26fe8e5: `NavCount` `tone="warning"`: an amber count for work that needs the person but is not urgent, the warning tint with the warning ink (a warning Notice's, 4.5:1 in every palette) inside a warning edge; `navCountTones` is now `['danger', 'accent', 'warning']`. `AppShell` items take `countTone` (NavCount's tones, `danger` by default; needs a `count`). New classes `sw-nav-count-warning`, `sw-app-shell-count-accent` and `sw-app-shell-count-warning`. The default stays danger. No new tokens or dependencies. Request: `docs/requests/futmas-nav-count-warning.md`.
+
 ## 1.46.0
 
 ### Minor Changes

package/README.md

@@ -9,6 +9,7 @@ import {
   Accordion,
   ActionBar,
   ActionMenu,
+  AppShell,
   BarChart,
   ChartLegend,
   ColumnChart,
@@ -110,7 +111,7 @@ Import the CSS once at the application entry. Do not copy it into your source tr
 </Field>
 ```
 
-Every press control and link takes an explicit `tabindex="0"`: `Button` (and the controls built on it, `CalendarButton` and `InfoTip`), `Box as="a"` with an `href`, `SectionNav` links, the `Select`, `MultiSelect` and `ActionMenu` triggers, `SegmentedControl` items (every item, as outside Safari: its arrow keys change the value, not the focus, so it is not a roving group), `DateField`'s calendar button and month steps, a search `Field`'s clear button, a `Table`'s sort and `TableCell onPress` buttons, `Checkbox`, `Switch`, and the checked radio of a `RadioGroup` or `FilterChips` (the first enabled one while none is; the others keep no `tabindex`, so each browser's arrow-key group rule stands). Safari's default (its "Press Tab to highlight each item" setting off) leaves a button, a link, a checkbox and a radio out of the Tab order unless it carries one, so a Safari user would Tab past them; the explicit `0` gives them the order every other browser already does. A `tabIndex` you pass wins, and controls that are deliberately no tab stop keep their `-1`: a `Stepper`'s − and +, and a roving item (a `Tabs` tab, a menu item, a calendar day) other than the current one. A `<summary>` is already in Safari's order and takes none.
+Every press control and link takes an explicit `tabindex="0"`: `Button` (and the controls built on it, `CalendarButton` and `InfoTip`), `Box as="a"` with an `href`, `SectionNav` links, `AppShell` links and its menu and close buttons, the `Select`, `MultiSelect` and `ActionMenu` triggers, `SegmentedControl` items (every item, as outside Safari: its arrow keys change the value, not the focus, so it is not a roving group), `DateField`'s calendar button and month steps, a search `Field`'s clear button, a `Table`'s sort and `TableCell onPress` buttons, `Checkbox`, `Switch`, and the checked radio of a `RadioGroup` or `FilterChips` (the first enabled one while none is; the others keep no `tabindex`, so each browser's arrow-key group rule stands). Safari's default (its "Press Tab to highlight each item" setting off) leaves a button, a link, a checkbox and a radio out of the Tab order unless it carries one, so a Safari user would Tab past them; the explicit `0` gives them the order every other browser already does. A `tabIndex` you pass wins, and controls that are deliberately no tab stop keep their `-1`: a `Stepper`'s − and +, and a roving item (a `Tabs` tab, a menu item, a calendar day) other than the current one. A `<summary>` is already in Safari's order and takes none.
 
 An element a script focuses, such as a notice or a card announced after a save, takes the same accent focus ring as the canvas's links and native controls, 2 px past its edge (`--sw-focus-ring-width` and `--sw-focus-ring-offset`), instead of the browser's outline. Give it `tabIndex={-1}`, so it takes focus from a script but is no tab stop, and put the focus on the whole card rather than its text, so the ring goes round it clear of the words; a `Box` round the card with the card's `radius` makes the ring follow its corners. As with the browser's own outline, the ring shows only when focus is visible (`:focus-visible`): after a keyboard press, not after a mouse press. The rule has zero specificity, so a component's own ring always wins.
 
@@ -517,7 +518,7 @@ An option's optional `description` (a `ReactNode`) is secondary text for that op
 
 `appearance="words"` (opt-in; default `"default"`, `navAppearances`) draws every destination, a link or a `Button` of any variant, as plain words: no fill, border or underline, label type, the others in the muted color at medium weight and the current one (`aria-current`, not `"false"`) in the text color at label weight. A Button keeps its size, padding, touch target and focus ring; hover lifts a destination to the text color where the pointer can hover, never a disabled one. The current mark is color and weight, so each destination's words must be visible: a glyph-only destination has no weight to change (keep `default` for a glyph rail). Forced colors draw the current one's border in Highlight and underline its words. An unknown value throws a `RangeError`.
 
-`NavCount` puts a count after a destination's words, such as the tasks waiting in an area: place it inside the link or `Button`, after its words (`<a href="/tasks">Tasks<NavCount count={8} /></a>`). It is the pill `SectionNav`'s item `count` draws (the danger color with its on-color figures, an edge in forced colors), a space-2 after the words in a link or a Button, the link keeping its siblings' height, and it is read as part of the destination's name ("Tasks 8"). `count` is a whole number; 0 shows nothing. `countLabel` says what it means in your words ("8 tasks to do"): it is read in place of the bare number ("Tasks 8 tasks to do") and the pill is hidden from assistive technology. `tone="accent"` (default `"danger"`, `navCountTones`) draws the pill in the accent color with its on-color figures, for a count that is news rather than work waiting, such as what was added since the person last looked; its size, spacing and name are the same. Give an accent count a `countLabel` ("3 new") so its words, not its color, say it is news, and place either tone on a neutral or ghost destination, never a filled one of the same color. A count that is not a whole number from 0, a blank `countLabel` or an unknown `tone` throws a `RangeError`.
+`NavCount` puts a count after a destination's words, such as the tasks waiting in an area: place it inside the link or `Button`, after its words (`<a href="/tasks">Tasks<NavCount count={8} /></a>`). It is the pill `SectionNav`'s item `count` draws (the danger color with its on-color figures, an edge in forced colors), a space-2 after the words in a link or a Button, the link keeping its siblings' height, and it is read as part of the destination's name ("Tasks 8"). `count` is a whole number; 0 shows nothing. `countLabel` says what it means in your words ("8 tasks to do"): it is read in place of the bare number ("Tasks 8 tasks to do") and the pill is hidden from assistive technology. `tone="accent"` (default `"danger"`, `navCountTones`) draws the pill in the accent color with its on-color figures, for a count that is news rather than work waiting, such as what was added since the person last looked; its size, spacing and name are the same. `tone="warning"` draws it in amber, for work that needs the person but is not urgent ("needs you"): the warning tint with the warning ink (a warning `Notice`'s, 4.5:1 in every palette) inside a warning edge. Give an accent or warning count a `countLabel` ("3 new", "2 to confirm") so its words, not its color, say what it is, and place either tone on a neutral or ghost destination, never a filled one of the same color. A count that is not a whole number from 0, a blank `countLabel` or an unknown `tone` throws a `RangeError`.
 
 ```tsx
 <Nav appearance="words" aria-label="Areas">
@@ -549,6 +550,62 @@ An option's optional `description` (a `ReactNode`) is secondary text for that op
 />
 ```
 
+`AppShell` is a web workspace's frame: a pinned side navigation of grouped destinations beside the page, which it renders in `main` and which scrolls with the document (`main` is never its own scroll box). `groups` is a list of `{ id, label?, items }`; each item is `{ id, label, href, icon, count?, countLabel?, countTone?, current? }` with `SectionNav`'s rules for `current`, `count` and `countLabel` (the same shared count pill, read in the link's name), `countTone` one of `NavCount`'s tones (`danger` by default, `warning` for amber, `accent`; it needs a `count`), and `icon`, the consumer's decorative glyph, is required because the rail shows nothing else. `navLabel` names the navigation (and the drawer). `onNavigate` takes a plain press for a client router, as `SectionNav`'s does: the item, after the browser's navigation is prevented; a modifier or middle press keeps the browser's behaviour.
+
+The layout follows the window, with generated media queries only. From 75rem (1200 px, an internal width of the component, not a public breakpoint) the sidebar is 15rem on the solid surface with a hairline at its end, sticky at the top at the viewport's height: `header` (a workspace switcher such as an `ActionMenu`), the groups (a group's `label` is a small muted caption naming its list), `footer` (the account menu) under a hairline; only the nav scrolls, and only when it is taller than the window. Each destination shows its glyph, label and count; the current one takes `SectionNav filled`'s quiet fill at the label weight; a coarse pointer gets 44 px rows. From `lg` (64rem) to 75rem it is a rail of glyphs, the 44 px target wide: labels are visually hidden but stay in each link's name and show in a `Tooltip` on hover or keyboard focus, a count is the pill on the glyph's corner, group captions become hairlines, and `railHeader`/`railFooter` replace `header`/`footer` (none is drawn without them). Below `lg` there is no sidebar: a sticky `AppHeader appearance="bar"` holds an icon-only ghost menu button (`menuIcon`, named `labels.openMenu`), `barTitle` and `barEnd`. The menu opens a modal drawer on the top layer from the inline start (the end in right-to-left), sliding in unless reduced motion is asked for, with a close button named `labels.closeMenu` where the menu button was, then `header`, the nav and `footer`. Escape, a press outside, the close button or a plain press on a destination close it; after the first three focus returns to the menu button, while a chosen destination leaves focus to the page it moves to. A window widened past `lg` closes it too. `header` and `footer` render in the sidebar and again in the open drawer (and `railHeader`/`railFooter` beside them in the hidden sidebar), so a slot's content can be mounted twice at once with separate state: give it no fixed DOM `id` (use `useId`), and keep state that must survive opening the menu, such as a selection, in your own component. Forced colours draw the links as `LinkText`, the current one with a `Highlight` edge. A blank `navLabel` or menu label, no groups, an empty or duplicate group id, a blank group label, an empty group, an empty or duplicate item id (across groups), an empty label, a missing icon (or one that draws nothing: a boolean, `''` or `0`), a `count` that is not a whole number from 0, a blank `countLabel` or one without a `count`, and an unknown `countTone` or one without a `count` throw a `RangeError`.
+
+```tsx
+<AppShell
+  navLabel="Field station"
+  groups={[
+    {
+      id: 'field',
+      items: [
+        {
+          id: 'today',
+          label: 'Today',
+          href: '/today',
+          icon: <CalendarDays />,
+          current: 'page',
+        },
+      ],
+    },
+    {
+      id: 'reserves',
+      label: 'Reserves',
+      items: [
+        {
+          id: 'wetlands',
+          label: 'Wetlands',
+          href: '/wetlands',
+          icon: <Waves />,
+          count: 3,
+          countLabel: '3 sightings to check',
+        },
+        {
+          id: 'forests',
+          label: 'Forests',
+          href: '/forests',
+          icon: <Trees />,
+          count: 2,
+          countLabel: '2 to confirm',
+          countTone: 'warning',
+        },
+      ],
+    },
+  ]}
+  onNavigate={(item) => navigate(item.href)}
+  header={<StationMenu />}
+  railHeader={<StationTile />}
+  footer={<AccountMenu />}
+  barTitle={<Text variant="label">Heron Marsh</Text>}
+  menuIcon={<Menu />}
+  labels={{ openMenu: 'Open menu', closeMenu: 'Close menu' }}
+>
+  <Box padding={5}>{page}</Box>
+</AppShell>
+```
+
 ```tsx
 <Stack gap={3}>
   <Box paddingX={4}>

package/dist/app-shell.test-support.d.ts

@@ -0,0 +1,5 @@
+import { type AppShellNavGroup, type AppShellProps } from './components/AppShell.js';
+/** A field station's destinations: one bare group and one labelled. */
+export declare const habitats: AppShellNavGroup[];
+/** The shell with its required words, a page, and any prop overridden. */
+export declare function renderShell(props?: Partial<AppShellProps>): import("@testing-library/react").RenderResult<typeof import("@testing-library/dom/types/queries.js"), HTMLElement, HTMLElement>;

package/dist/app-shell.test-support.js

@@ -0,0 +1,45 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { render } from '@testing-library/react';
+import { AppShell, } from './components/AppShell.js';
+/** A field station's destinations: one bare group and one labelled. */
+export const habitats = [
+    {
+        id: 'field',
+        items: [
+            {
+                id: 'today',
+                label: 'Today',
+                href: '/today',
+                icon: _jsx("svg", { "data-glyph": "today" }),
+                current: 'page',
+            },
+        ],
+    },
+    {
+        id: 'reserves',
+        label: 'Reserves',
+        items: [
+            {
+                id: 'wetlands',
+                label: 'Wetlands',
+                href: '/wetlands',
+                icon: _jsx("svg", {}),
+                count: 3,
+                countLabel: '3 sightings to check',
+            },
+            {
+                id: 'forests',
+                label: 'Forests',
+                href: '/forests',
+                icon: _jsx("svg", {}),
+                count: 2,
+                countTone: 'warning',
+            },
+            { id: 'dunes', label: 'Dunes', href: '/dunes', icon: _jsx("svg", {}), count: 0 },
+        ],
+    },
+];
+/** The shell with its required words, a page, and any prop overridden. */
+export function renderShell(props = {}) {
+    return render(_jsx(AppShell, { barTitle: "Heron Marsh", groups: habitats, labels: { openMenu: 'Open menu', closeMenu: 'Close menu' }, menuIcon: _jsx("svg", { "data-glyph": "menu" }), navLabel: "Field station", ...props, children: _jsx("p", { children: "Otters seen at dawn." }) }));
+}

package/dist/components/AppShell.d.ts

@@ -0,0 +1,12 @@
+import { type AppShellProps } from './app-shell/types.js';
+export type { AppShellLabels, AppShellNavGroup, AppShellNavItem, AppShellProps, } from './app-shell/types.js';
+/**
+ * A web workspace's frame: a pinned side navigation of grouped
+ * destinations beside the page (`main`), which scrolls with the document.
+ * From 75rem the sidebar is full (glyphs, labels, counts and group
+ * captions); from `lg` to 75rem it is a rail of glyphs with tooltips; below
+ * `lg` a sticky top bar's menu button opens the same navigation in a modal
+ * drawer from the inline start. Invalid groups, items or words throw a
+ * `RangeError`.
+ */
+export declare function AppShell({ barEnd, barTitle, children, footer, groups, header, labels, menuIcon, navLabel, onNavigate, railFooter, railHeader, }: AppShellProps): import("react").JSX.Element;

package/dist/components/AppShell.js

@@ -0,0 +1,48 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { breakpointQuery } from '../css/breakpoints.js';
+import { appShellWideQuery } from '../css/css-app-shell.js';
+import { AppHeader } from './AppHeader.js';
+import { AppShellDrawer } from './app-shell/AppShellDrawer.js';
+import { AppShellSidebar } from './app-shell/AppShellSidebar.js';
+import { assertAppShellProps } from './app-shell/validate.js';
+import { Button } from './Button.js';
+import { useMediaQuery } from './use-media-query.js';
+const fromLg = breakpointQuery('from', 'lg');
+/**
+ * A web workspace's frame: a pinned side navigation of grouped
+ * destinations beside the page (`main`), which scrolls with the document.
+ * From 75rem the sidebar is full (glyphs, labels, counts and group
+ * captions); from `lg` to 75rem it is a rail of glyphs with tooltips; below
+ * `lg` a sticky top bar's menu button opens the same navigation in a modal
+ * drawer from the inline start. Invalid groups, items or words throw a
+ * `RangeError`.
+ */
+export function AppShell({ barEnd, barTitle, children, footer, groups, header, labels, menuIcon, navLabel, onNavigate, railFooter, railHeader, }) {
+    assertAppShellProps({ groups, labels, navLabel });
+    const [menuOpen, setMenuOpen] = useState(false);
+    const menuRef = useRef(null);
+    // Set by a dismissal (Escape, a press outside, the close button): only
+    // that hands focus back to the menu button.
+    const refocusRef = useRef(false);
+    const sidebarShown = useMediaQuery(fromLg, false);
+    const wide = useMediaQuery(appShellWideQuery, false);
+    // The drawer belongs to the bar, which is gone from `lg` up: a window
+    // widened while it is open closes it.
+    if (sidebarShown && menuOpen)
+        setMenuOpen(false);
+    // After a dismissal (the drawer's own effect closes it first), focus
+    // returns to the menu button. A chosen destination leaves focus to the
+    // page it moves to, and a widened window has no menu button to focus.
+    useEffect(() => {
+        if (menuOpen || !refocusRef.current)
+            return;
+        refocusRef.current = false;
+        menuRef.current?.focus();
+    }, [menuOpen]);
+    return (_jsxs("div", { className: "sw-app-shell", children: [_jsxs(AppHeader, { appearance: "bar", className: "sw-app-shell-bar", padding: 2, children: [_jsx(Button, { ref: menuRef, "aria-expanded": menuOpen, "aria-haspopup": "dialog", "aria-label": labels.openMenu, className: "sw-app-shell-menu", onPress: () => setMenuOpen(true), size: "sm", variant: "ghost", children: _jsx("span", { "aria-hidden": "true", className: "sw-app-shell-icon", children: menuIcon }) }), _jsx("div", { className: "sw-app-shell-bar-title", children: barTitle }), barEnd ? _jsx("div", { className: "sw-app-shell-bar-end", children: barEnd }) : null] }), _jsx(AppShellSidebar, { footer: footer, groups: groups, header: header, navLabel: navLabel, onNavigate: onNavigate, rail: sidebarShown && !wide, railFooter: railFooter, railHeader: railHeader }), _jsx("main", { className: "sw-app-shell-main", children: children }), _jsx(AppShellDrawer, { closeLabel: labels.closeMenu, footer: footer, groups: groups, header: header, navLabel: navLabel, onChoose: () => setMenuOpen(false), onClose: () => {
+                    refocusRef.current = true;
+                    setMenuOpen(false);
+                }, onNavigate: onNavigate, open: menuOpen })] }));
+}

package/dist/components/NavCount.d.ts

@@ -1,5 +1,8 @@
-/** The pill's colours: `danger` for work waiting, `accent` for news. */
-export declare const navCountTones: readonly ["danger", "accent"];
+/**
+ * The pill's colours: `danger` for work waiting, `accent` for news,
+ * `warning` for work that needs the person but is not urgent.
+ */
+export declare const navCountTones: readonly ["danger", "accent", "warning"];
 export type NavCountTone = (typeof navCountTones)[number];
 export type NavCountProps = {
     /**
@@ -17,8 +20,11 @@ export type NavCountProps = {
     /**
      * The pill's colour. `danger` (the default) is work waiting there, such
      * as tasks to do; `accent` is news, such as what was added since the
-     * person last looked, where nothing is overdue. Give an accent count a
-     * `countLabel` ("3 new"), so its words, not its colour, say it is news.
+     * person last looked, where nothing is overdue; `warning` is amber, work
+     * that needs the person but is not urgent ("needs you"): the warning
+     * tint with the warning ink (4.5:1 in every palette) inside a warning
+     * edge. Give an accent or warning count a `countLabel` ("3 new", "2 to
+     * confirm"), so its words, not its colour, say what it is.
      * Place either tone on a neutral or ghost destination: a filled one of
      * the same colour would hide it.
      */
@@ -29,6 +35,7 @@ export type NavCountProps = {
  * Button: `<a href="/tasks">Tasks<NavCount count={8} /></a>`. It is the
  * pill SectionNav's item count draws, and it is part of the destination's
  * accessible name, as there. `tone="accent"` draws it in the accent colour,
- * for news rather than work.
+ * for news rather than work; `tone="warning"` in amber, for work that needs
+ * the person but is not urgent.
  */
 export declare function NavCount({ count, countLabel, tone, }: NavCountProps): import("react").JSX.Element | null;

package/dist/components/NavCount.js

@@ -1,8 +1,12 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { cx } from '../class-names.js';
+import { countToneClass } from '../css/css-count-pill.js';
 import { isOneOf } from '../is-one-of.js';
-/** The pill's colours: `danger` for work waiting, `accent` for news. */
-export const navCountTones = ['danger', 'accent'];
+/**
+ * The pill's colours: `danger` for work waiting, `accent` for news,
+ * `warning` for work that needs the person but is not urgent.
+ */
+export const navCountTones = ['danger', 'accent', 'warning'];
 /**
  * Fails closed on a count that is not a whole number, an empty label or an
  * unknown tone.
@@ -21,7 +25,8 @@ function assertNavCount({ count, countLabel, tone }) {
  * Button: `<a href="/tasks">Tasks<NavCount count={8} /></a>`. It is the
  * pill SectionNav's item count draws, and it is part of the destination's
  * accessible name, as there. `tone="accent"` draws it in the accent colour,
- * for news rather than work.
+ * for news rather than work; `tone="warning"` in amber, for work that needs
+ * the person but is not urgent.
  */
 export function NavCount({ count, countLabel, tone = 'danger', }) {
     assertNavCount({ count, countLabel, tone });
@@ -29,5 +34,5 @@ export function NavCount({ count, countLabel, tone = 'danger', }) {
         return null;
     // The space is its own text node, so every browser and the name's
     // computation keep it between the words and the count.
-    return (_jsxs(_Fragment, { children: [' ', countLabel ? _jsx("span", { className: "sw-sr-only", children: countLabel }) : null, _jsx("span", { "aria-hidden": countLabel ? true : undefined, className: cx('sw-nav-count', tone === 'accent' && 'sw-nav-count-accent'), children: count })] }));
+    return (_jsxs(_Fragment, { children: [' ', countLabel ? _jsx("span", { className: "sw-sr-only", children: countLabel }) : null, _jsx("span", { "aria-hidden": countLabel ? true : undefined, className: cx('sw-nav-count', tone !== 'danger' && countToneClass('sw-nav-count', tone)), children: count })] }));
 }

package/dist/components/SectionNav.d.ts

@@ -2,6 +2,7 @@ import { type ReactNode } from 'react';
 import { type AccessibleName } from '../accessible-name.js';
 import { type Breakpoint } from '../css/breakpoints.js';
 import { type SectionNavAppearance } from '../css/css-section-nav-filled.js';
+import { type NavItemCurrent } from './nav-items.js';
 export type { SectionNavAppearance };
 export { sectionNavAppearances } from '../css/css-section-nav-filled.js';
 export type SectionNavItem = {
@@ -12,7 +13,7 @@ export type SectionNavItem = {
      * `page` when the item is this page, `location` (or `true`) when the page
      * is inside the item's section, such as a detail page under its list.
      */
-    current?: 'page' | 'location' | boolean;
+    current?: NavItemCurrent;
     /** A decorative glyph before the label. */
     icon?: ReactNode;
     /**

package/dist/components/SectionNav.js

@@ -5,24 +5,8 @@ import { sectionNavVerticalClass } from '../css/css-section-nav.js';
 import { assertSectionNavAppearance, } from '../css/css-section-nav-filled.js';
 import { tabStop } from '../tab-stop.js';
 import { plainPress } from './link-press.js';
+import { assertNavItems, navItemAriaCurrent, } from './nav-items.js';
 export { sectionNavAppearances } from '../css/css-section-nav-filled.js';
-function ariaCurrent(current) {
-    if (current === true)
-        return 'true';
-    return current || undefined;
-}
-function assertItems(items) {
-    if (items.some((item) => !item.id.trim() || !item.label.trim()))
-        throw new RangeError('SectionNav items need nonempty ids and labels');
-    if (new Set(items.map((item) => item.id)).size !== items.length)
-        throw new RangeError('SectionNav items need unique ids');
-    if (items.some((item) => item.count !== undefined &&
-        (!Number.isInteger(item.count) || item.count < 0)))
-        throw new RangeError('SectionNav item counts are whole numbers from 0');
-    if (items.some((item) => item.countLabel !== undefined &&
-        (!item.countLabel.trim() || item.count === undefined)))
-        throw new RangeError('SectionNav item countLabel is nonempty and comes with a count');
-}
 function assertBreakpoint(verticalFrom) {
     if (verticalFrom !== undefined && !breakpoints.includes(verticalFrom))
         throw new RangeError(`SectionNav verticalFrom must be one of ${breakpoints.join(', ')}`);
@@ -34,10 +18,10 @@ function assertBreakpoint(verticalFrom) {
  * a side list. The current item carries `aria-current`.
  */
 export function SectionNav({ appearance = 'underline', items, onNavigate, verticalFrom, ...label }) {
-    assertItems(items);
+    assertNavItems('SectionNav', items);
     assertBreakpoint(verticalFrom);
     assertSectionNavAppearance(appearance);
-    return (_jsx("nav", { className: cx('sw-section-nav', verticalFrom && sectionNavVerticalClass(verticalFrom), appearance === 'filled' && 'sw-section-nav-filled'), ...label, children: _jsx("ul", { className: "sw-section-nav-list", children: items.map((item) => (_jsx("li", { children: _jsxs("a", { "aria-current": ariaCurrent(item.current), className: "sw-section-nav-link", href: item.href, tabIndex: tabStop, 
+    return (_jsx("nav", { className: cx('sw-section-nav', verticalFrom && sectionNavVerticalClass(verticalFrom), appearance === 'filled' && 'sw-section-nav-filled'), ...label, children: _jsx("ul", { className: "sw-section-nav-list", children: items.map((item) => (_jsx("li", { children: _jsxs("a", { "aria-current": navItemAriaCurrent(item.current), className: "sw-section-nav-link", href: item.href, tabIndex: tabStop, 
                     // Only a given onNavigate attaches a handler, so the links
                     // render from a server component without one.
                     onClick: onNavigate

package/dist/components/app-shell/AppShellDrawer.d.ts

@@ -0,0 +1,24 @@
+import { type ReactNode } from 'react';
+import { type AppShellNavGroup, type AppShellNavItem } from './types.js';
+export type AppShellDrawerProps = {
+    open: boolean;
+    /** Asked on every close request: Escape, a press outside, the close button. */
+    onClose: () => void;
+    /** Asked after a plain press on a destination, which also closes it. */
+    onChoose: () => void;
+    closeLabel: string;
+    navLabel: string;
+    groups: readonly AppShellNavGroup[];
+    onNavigate?: (item: AppShellNavItem) => void;
+    header?: ReactNode;
+    footer?: ReactNode;
+};
+/**
+ * The menu below `lg`: a modal `dialog` on the top layer, full height at
+ * the inline start, named by the navigation's label. Dialog's close-request
+ * mechanics make Escape, a backdrop press and a platform close request one
+ * `onClose`, after which focus returns to the menu button. Its close button
+ * sits where the menu button was, so it is the first control. The content
+ * is drawn only while open, so the page holds one navigation at a time.
+ */
+export declare function AppShellDrawer({ closeLabel, footer, groups, header, navLabel, onChoose, onClose, onNavigate, open, }: AppShellDrawerProps): import("react").JSX.Element;

package/dist/components/app-shell/AppShellDrawer.js

@@ -0,0 +1,17 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Button } from '../Button.js';
+import { useDialogCloseRequests } from '../dialog-close-requests.js';
+import { AppShellNav } from './AppShellNav.js';
+/**
+ * The menu below `lg`: a modal `dialog` on the top layer, full height at
+ * the inline start, named by the navigation's label. Dialog's close-request
+ * mechanics make Escape, a backdrop press and a platform close request one
+ * `onClose`, after which focus returns to the menu button. Its close button
+ * sits where the menu button was, so it is the first control. The content
+ * is drawn only while open, so the page holds one navigation at a time.
+ */
+export function AppShellDrawer({ closeLabel, footer, groups, header, navLabel, onChoose, onClose, onNavigate, open, }) {
+    const { nodeRef, handlers } = useDialogCloseRequests({ open, onClose });
+    return (_jsx("dialog", { ref: nodeRef, "aria-label": navLabel, className: "sw-app-shell-drawer", ...handlers, children: open ? (_jsxs(_Fragment, { children: [_jsxs("div", { className: "sw-app-shell-drawer-top", children: [_jsxs(Button, { className: "sw-app-shell-close", onPress: onClose, size: "sm", variant: "ghost", children: [_jsx("span", { className: "sw-sr-only", children: closeLabel }), _jsx("span", { "aria-hidden": "true", className: "sw-dialog-close-glyph" })] }), header ? (_jsx("div", { className: "sw-app-shell-header", children: header })) : null] }), _jsx(AppShellNav, { groups: groups, navLabel: navLabel, onChoose: onChoose, onNavigate: onNavigate }), footer ? _jsx("div", { className: "sw-app-shell-footer", children: footer }) : null] })) : null }));
+}

package/dist/components/app-shell/AppShellLink.d.ts

@@ -0,0 +1,14 @@
+import { type MouseEvent } from 'react';
+import { type AppShellNavItem } from './types.js';
+export type AppShellLinkProps = {
+    item: AppShellNavItem;
+    onClick?: (event: MouseEvent<HTMLAnchorElement>) => void;
+    /**
+     * The sidebar's links sit in a Tooltip with their label, shown only while
+     * `tooltip` is true (the rail, where the label is hidden). Left out (the
+     * drawer) there is no Tooltip at all.
+     */
+    tooltip?: boolean;
+};
+/** One destination in its list item: the glyph, the label and the count. */
+export declare function AppShellLink({ item, onClick, tooltip }: AppShellLinkProps): import("react").JSX.Element;

package/dist/components/app-shell/AppShellLink.js

@@ -0,0 +1,27 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from '../../class-names.js';
+import { countToneClass } from '../../css/css-count-pill.js';
+import { tabStop } from '../../tab-stop.js';
+import { navItemAriaCurrent } from '../nav-items.js';
+import { Tooltip } from '../Tooltip.js';
+/*
+ * The destination's link. A Tooltip around it passes its references in;
+ * only `aria-labelledby` is kept. Its `aria-describedby` is left out on
+ * purpose: the tooltip's words are the label the link is already named by,
+ * so they would be read twice.
+ */
+function AppShellAnchor({ 'aria-labelledby': labelledBy, children, item, onClick, }) {
+    return (_jsx("a", { "aria-current": navItemAriaCurrent(item.current), "aria-labelledby": labelledBy, className: "sw-app-shell-link", href: item.href, onClick: onClick, tabIndex: tabStop, children: children }));
+}
+/** The count after the label, read in the link's name as SectionNav's is. */
+function AppShellCount({ count, countLabel, countTone = 'danger', }) {
+    if (!count)
+        return null;
+    return (_jsxs(_Fragment, { children: [countLabel ? (_jsx("span", { className: "sw-sr-only", children: ` ${countLabel}` })) : (' '), _jsx("span", { "aria-hidden": countLabel ? true : undefined, className: cx('sw-app-shell-count', countTone !== 'danger' &&
+                    countToneClass('sw-app-shell-count', countTone)), children: count })] }));
+}
+/** One destination in its list item: the glyph, the label and the count. */
+export function AppShellLink({ item, onClick, tooltip }) {
+    const content = (_jsxs(_Fragment, { children: [_jsx("span", { "aria-hidden": "true", className: "sw-app-shell-icon", children: item.icon }), _jsx("span", { className: "sw-app-shell-label", children: item.label }), _jsx(AppShellCount, { count: item.count, countLabel: item.countLabel, countTone: item.countTone })] }));
+    return (_jsx("li", { className: "sw-app-shell-item", children: tooltip === undefined ? (_jsx(AppShellAnchor, { item: item, onClick: onClick, children: content })) : (_jsx(Tooltip, { content: item.label, disabled: !tooltip, trigger: _jsx(AppShellAnchor, { item: item, onClick: onClick, children: content }) })) }));
+}

package/dist/components/app-shell/AppShellNav.d.ts

@@ -0,0 +1,15 @@
+import { type AppShellNavGroup, type AppShellNavItem } from './types.js';
+export type AppShellNavProps = {
+    navLabel: string;
+    groups: readonly AppShellNavGroup[];
+    onNavigate?: (item: AppShellNavItem) => void;
+    /** The drawer's: a plain press on a destination also closes it. */
+    onChoose?: () => void;
+    /** The sidebar's: whether the rail's tooltips show (see AppShellLink). */
+    tooltip?: boolean;
+};
+/**
+ * The shell's navigation landmark: each group a list named by its label,
+ * the same in the sidebar and the drawer.
+ */
+export declare function AppShellNav({ groups, navLabel, onChoose, onNavigate, tooltip, }: AppShellNavProps): import("react").JSX.Element;

package/dist/components/app-shell/AppShellNav.js

@@ -0,0 +1,29 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from 'react';
+import { plainPress } from '../link-press.js';
+import { AppShellLink } from './AppShellLink.js';
+/**
+ * The shell's navigation landmark: each group a list named by its label,
+ * the same in the sidebar and the drawer.
+ */
+export function AppShellNav({ groups, navLabel, onChoose, onNavigate, tooltip, }) {
+    const idPrefix = useId();
+    // Only a given onNavigate or onChoose attaches a handler.
+    function pressHandler(item) {
+        if (!onNavigate && !onChoose)
+            return undefined;
+        return (event) => {
+            if (!plainPress(event))
+                return;
+            if (onNavigate) {
+                event.preventDefault();
+                onNavigate(item);
+            }
+            onChoose?.();
+        };
+    }
+    return (_jsx("nav", { "aria-label": navLabel, className: "sw-app-shell-nav", children: groups.map((group, index) => {
+            const labelId = `${idPrefix}-group-${index}`;
+            return (_jsxs("div", { className: "sw-app-shell-group", children: [group.label ? (_jsx("p", { className: "sw-app-shell-group-label", id: labelId, children: group.label })) : null, _jsx("ul", { "aria-labelledby": group.label ? labelId : undefined, className: "sw-app-shell-list", children: group.items.map((item) => (_jsx(AppShellLink, { item: item, onClick: pressHandler(item), tooltip: tooltip }, item.id))) })] }, group.id));
+        }) }));
+}

package/dist/components/app-shell/AppShellSidebar.d.ts

@@ -0,0 +1,18 @@
+import { type ReactNode } from 'react';
+import { type AppShellNavGroup, type AppShellNavItem } from './types.js';
+export type AppShellSidebarProps = {
+    navLabel: string;
+    groups: readonly AppShellNavGroup[];
+    onNavigate?: (item: AppShellNavItem) => void;
+    header?: ReactNode;
+    footer?: ReactNode;
+    railHeader?: ReactNode;
+    railFooter?: ReactNode;
+    /** Whether the window is in the rail's range, where tooltips show. */
+    rail: boolean;
+};
+/**
+ * The pinned column from `lg` up: a rail to 75rem, the full sidebar from
+ * there. Hidden below `lg`, where the drawer holds the same parts.
+ */
+export declare function AppShellSidebar({ footer, groups, header, navLabel, onNavigate, rail, railFooter, railHeader, }: AppShellSidebarProps): import("react").JSX.Element;

package/dist/components/app-shell/AppShellSidebar.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { AppShellNav } from './AppShellNav.js';
+/*
+ * A slot drawn in the full sidebar (`sw-app-shell-slot`) or only in the
+ * rail (`sw-app-shell-rail-slot`); the generated media queries pick one.
+ */
+function Slot({ children, part, rail, }) {
+    if (!children)
+        return null;
+    return (_jsx("div", { className: `sw-app-shell-${part} ${rail ? 'sw-app-shell-rail-slot' : 'sw-app-shell-slot'}`, children: children }));
+}
+/**
+ * The pinned column from `lg` up: a rail to 75rem, the full sidebar from
+ * there. Hidden below `lg`, where the drawer holds the same parts.
+ */
+export function AppShellSidebar({ footer, groups, header, navLabel, onNavigate, rail, railFooter, railHeader, }) {
+    return (_jsxs("div", { className: "sw-app-shell-sidebar", children: [_jsx(Slot, { part: "header", rail: false, children: header }), _jsx(Slot, { part: "header", rail: true, children: railHeader }), _jsx(AppShellNav, { groups: groups, navLabel: navLabel, onNavigate: onNavigate, tooltip: rail }), _jsx(Slot, { part: "footer", rail: false, children: footer }), _jsx(Slot, { part: "footer", rail: true, children: railFooter })] }));
+}

package/dist/components/app-shell/types.d.ts

@@ -0,0 +1,87 @@
+import { type ReactNode } from 'react';
+import { type NavCountTone } from '../NavCount.js';
+import { type NavItemCurrent } from '../nav-items.js';
+export type AppShellNavItem = {
+    id: string;
+    label: string;
+    href: string;
+    /**
+     * The destination's glyph (a consumer Lucide icon or mark), hidden from
+     * assistive technology. Required: in the rail it is all the item shows.
+     */
+    icon: ReactNode;
+    /**
+     * How many things wait there, such as work to do: the shared count pill
+     * (danger) after the label, or on the glyph in the rail, read in the
+     * link's name. A whole number; 0 (or none) shows no pill.
+     */
+    count?: number;
+    /**
+     * What the count means, in the consumer's words ("3 to confirm"): read in
+     * the name in place of the bare number, the pill then hidden from
+     * assistive technology. Needs `count`.
+     */
+    countLabel?: string;
+    /**
+     * The pill's colour, as NavCount's `tone`: `danger` (the default) for
+     * work waiting, `warning` (amber) for work that needs the person but is
+     * not urgent, `accent` for news. Needs `count`; say what it is in a
+     * `countLabel`, never by its colour alone.
+     */
+    countTone?: NavCountTone;
+    /**
+     * `page` when the item is this page, `location` (or `true`) when the page
+     * is inside the item's area, such as a detail page under its list.
+     */
+    current?: NavItemCurrent;
+};
+export type AppShellNavGroup = {
+    id: string;
+    /**
+     * A small muted caption over the group's destinations that names their
+     * list. In the rail it is hidden (still naming the list) and the group
+     * starts under a hairline.
+     */
+    label?: string;
+    items: readonly AppShellNavItem[];
+};
+/** The shell's own words: the menu button's name and the drawer's close. */
+export type AppShellLabels = {
+    openMenu: string;
+    closeMenu: string;
+};
+export type AppShellProps = {
+    /** The navigation landmark's name, also the drawer's. */
+    navLabel: string;
+    groups: readonly AppShellNavGroup[];
+    /**
+     * Called for a plain press on a destination (the main button, no
+     * modifier key), after the browser's own navigation is prevented, so a
+     * client router moves instead. A press with a modifier key, or a middle
+     * press, keeps the browser's behaviour. Without it the links navigate.
+     */
+    onNavigate?: (item: AppShellNavItem) => void;
+    /**
+     * The sidebar's top, such as a workspace switcher; also the drawer's.
+     * While the drawer is open it is mounted twice (the sidebar's copy is
+     * hidden), so each copy keeps its own state: put no fixed DOM `id` in it
+     * (use `useId`), and keep state that must be shared in the consumer.
+     * The same holds for `footer`, `railHeader` and `railFooter`.
+     */
+    header?: ReactNode;
+    /** The sidebar's bottom, such as the account menu; also the drawer's (see `header`). */
+    footer?: ReactNode;
+    /** A compact `header` for the rail. Left out, the rail shows none. */
+    railHeader?: ReactNode;
+    /** A compact `footer` for the rail. Left out, the rail shows none. */
+    railFooter?: ReactNode;
+    /** The compact top bar's title, below `lg`. */
+    barTitle: ReactNode;
+    /** Controls at the top bar's end, below `lg`. */
+    barEnd?: ReactNode;
+    /** The consumer's glyph for the menu button (Scalewing has no icon catalog). */
+    menuIcon: ReactNode;
+    labels: AppShellLabels;
+    /** The page, rendered in `main`. */
+    children: ReactNode;
+};

package/dist/components/app-shell/types.js

@@ -0,0 +1 @@
+export {};

package/dist/components/app-shell/validate.d.ts

@@ -0,0 +1,6 @@
+import { type AppShellProps } from './types.js';
+/**
+ * Fails closed on the shell's words, its groups and their items (ids unique
+ * across every group, each with an icon, which is all the rail shows).
+ */
+export declare function assertAppShellProps({ groups, labels, navLabel, }: Pick<AppShellProps, 'groups' | 'labels' | 'navLabel'>): void;