@scalewing/react 1.45.0 → 1.47.0

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/Select.d.ts

@@ -1,6 +1,7 @@
 import { type SelectOption } from '../select-list.js';
 import { type FieldSize } from './Field.js';
 import { type RequiredMark } from './FieldLabelText.js';
+import { type SelectNaming } from './select/select-naming.js';
 export type { SelectOption };
 /**
  * `content` (the default) sizes the field to its longest option, as a native
@@ -12,10 +13,9 @@ export type SelectAction = {
     label: string;
     onPress: () => void;
 };
-export type SelectProps = {
+export type { SelectNaming };
+export type SelectProps = SelectNaming & {
     action?: SelectAction;
-    label: string;
-    labelVisuallyHidden?: boolean;
     onChange: (value: string) => void;
     options: readonly SelectOption[];
     size?: FieldSize;
@@ -25,7 +25,10 @@ export type SelectProps = {
      * (such as ''). It is not an option and never becomes the value.
      */
     placeholder?: string;
-    /** Marks the label as Field does and sets `aria-required`. */
+    /**
+     * Marks the label as Field does and sets `aria-required` (named by
+     * `aria-labelledby`, only `aria-required`: the page draws the words).
+     */
     required?: boolean;
     /**
      * `hidden` leaves out the label's " *" while the control stays required
@@ -43,4 +46,4 @@ export type SelectProps = {
      */
     width?: SelectWidth;
 };
-export declare function Select({ action, label, labelVisuallyHidden, onChange, options, size, value, placeholder, required, requiredMark, error, width, }: SelectProps): import("react").JSX.Element;
+export declare function Select({ action, label, labelVisuallyHidden, 'aria-labelledby': labelledBy, onChange, options, size, value, placeholder, required, requiredMark, error, width, }: SelectProps): import("react").JSX.Element;

package/dist/components/Select.js

@@ -5,16 +5,19 @@ import { cx } from '../class-names.js';
 import { selectedSelectIndex } from '../select-list.js';
 import { FieldErrorRegion } from './FieldErrorRegion.js';
 import { assertRequiredMark, FieldLabelText, } from './FieldLabelText.js';
+import { assertSelectNaming, } from './select/select-naming.js';
 import { SelectListbox } from './select/SelectListbox.js';
 import { SelectValue } from './select/SelectValue.js';
 import { useSelectList } from './select/use-select-list.js';
 import { Stack } from './Stack.js';
 import { tabStop } from '../tab-stop.js';
-export function Select({ action, label, labelVisuallyHidden = false, onChange, options, size = 'md', value, placeholder, required = false, requiredMark = 'visible', error, width = 'content', }) {
-    assertRequiredMark(requiredMark);
+export function Select({ action, label, labelVisuallyHidden, 'aria-labelledby': labelledBy, onChange, options, size = 'md', value, placeholder, required = false, requiredMark, error, width = 'content', }) {
+    assertSelectNaming({ label, labelVisuallyHidden, labelledBy, requiredMark });
+    assertRequiredMark(requiredMark ?? 'visible');
     if (placeholder !== undefined && !placeholder.trim())
         throw new RangeError('placeholder must not be empty');
-    const labelId = useId();
+    const ownLabelId = useId();
+    const labelId = labelledBy ?? ownLabelId;
     const triggerId = useId();
     const listId = useId();
     const optionIdPrefix = useId();
@@ -24,7 +27,7 @@ export function Select({ action, label, labelVisuallyHidden = false, onChange, o
     const showsPlaceholder = placeholder !== undefined &&
         !options.some((option) => option.value === value);
     const { commit, highlight, onTriggerKeyDown, open, openList, setHighlight, setOpen, } = useSelectList({ action, onChange, options, rootRef, value });
-    return (_jsx("div", { ref: rootRef, className: cx('sw-select', size === 'xs' && 'sw-select-xs', width === 'full' && 'sw-select-full', error && 'sw-select-invalid'), children: _jsxs(Stack, { gap: labelVisuallyHidden ? 0 : 1, children: [_jsx("label", { htmlFor: triggerId, id: labelId, children: _jsx(FieldLabelText, { label: label, required: required, requiredMark: requiredMark, size: size, visuallyHidden: labelVisuallyHidden }) }), _jsxs("div", { className: "sw-select-control", children: [_jsx("button", { "aria-activedescendant": open ? `${optionIdPrefix}-${highlight}` : undefined, "aria-controls": open ? listId : undefined, "aria-describedby": error ? errorId : undefined, "aria-expanded": open, "aria-haspopup": "listbox", "aria-invalid": error ? true : undefined, "aria-labelledby": labelId, "aria-required": required || undefined, className: "sw-select-trigger", id: triggerId, onBlur: (event) => {
+    return (_jsx("div", { ref: rootRef, className: cx('sw-select', size === 'xs' && 'sw-select-xs', width === 'full' && 'sw-select-full', error && 'sw-select-invalid'), children: _jsxs(Stack, { gap: label === undefined || labelVisuallyHidden ? 0 : 1, children: [label === undefined ? null : (_jsx("label", { htmlFor: triggerId, id: labelId, children: _jsx(FieldLabelText, { label: label, required: required, requiredMark: requiredMark ?? 'visible', size: size, visuallyHidden: labelVisuallyHidden ?? false }) })), _jsxs("div", { className: "sw-select-control", children: [_jsx("button", { "aria-activedescendant": open ? `${optionIdPrefix}-${highlight}` : undefined, "aria-controls": open ? listId : undefined, "aria-describedby": error ? errorId : undefined, "aria-expanded": open, "aria-haspopup": "listbox", "aria-invalid": error ? true : undefined, "aria-labelledby": labelId, "aria-required": required || undefined, className: "sw-select-trigger", id: triggerId, onBlur: (event) => {
                                 const next = event.relatedTarget;
                                 if (next instanceof Node && rootRef.current?.contains(next)) {
                                     return;

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;

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

@@ -0,0 +1,52 @@
+import { isOneOf } from '../../is-one-of.js';
+import { navCountTones } from '../NavCount.js';
+import { assertNavItems } from '../nav-items.js';
+/**
+ * An icon that is no glyph: nothing, a boolean or an empty string (which
+ * React draws as nothing), or 0 (which it draws as the text "0").
+ */
+function drawsNothing(node) {
+    return (node === undefined ||
+        node === null ||
+        typeof node === 'boolean' ||
+        node === '' ||
+        node === 0);
+}
+function isBlank(words) {
+    return typeof words !== 'string' || !words.trim();
+}
+function assertGroups(groups) {
+    if (groups.length === 0)
+        throw new RangeError('AppShell needs at least one group');
+    if (groups.some((group) => isBlank(group.id)))
+        throw new RangeError('AppShell groups need nonempty ids');
+    if (new Set(groups.map((group) => group.id)).size !== groups.length)
+        throw new RangeError('AppShell groups need unique ids');
+    if (groups.some((group) => group.label !== undefined && isBlank(group.label)))
+        throw new RangeError('AppShell group labels are nonempty when given');
+    if (groups.some((group) => group.items.length === 0))
+        throw new RangeError('AppShell groups need at least one item');
+}
+/**
+ * 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 function assertAppShellProps({ groups, labels, navLabel, }) {
+    if (isBlank(navLabel))
+        throw new RangeError('AppShell navLabel must be nonempty');
+    if (isBlank(labels?.openMenu) || isBlank(labels?.closeMenu))
+        throw new RangeError('AppShell labels openMenu and closeMenu are nonempty');
+    assertGroups(groups);
+    const items = groups.flatMap((group) => group.items);
+    assertNavItems('AppShell', items);
+    if (items.some((item) => drawsNothing(item.icon)))
+        throw new RangeError('AppShell items need an icon, all the rail shows');
+    for (const item of items) {
+        if (item.countTone === undefined)
+            continue;
+        if (!isOneOf(navCountTones, item.countTone))
+            throw new RangeError(`AppShell item countTone must be one of ${navCountTones.join(', ')}`);
+        if (item.count === undefined)
+            throw new RangeError('AppShell item countTone comes with a count');
+    }
+}

package/dist/components/file-field/ChosenFile.d.ts

@@ -0,0 +1,45 @@
+import { type ReactNode, type Ref } from 'react';
+import type { FileFieldValue } from '../FileField.js';
+/** The ids a chosen file's parts take, from the field's. */
+export type ChosenFileIds = {
+    label: string;
+    button: string;
+    name: string;
+    detail: string;
+    remove: string;
+};
+/** The change button's naming and description, as the field wires them. */
+export type ChosenFileNaming = {
+    'aria-labelledby': string;
+    'aria-describedby': string | undefined;
+    id: string;
+};
+/** Remove beside a chosen file: its words and what it does. */
+export type ChosenFileRemove = {
+    label: string;
+    onRemove: () => void;
+};
+type ChosenFileProps = {
+    value: FileFieldValue;
+    icon: ReactNode;
+    ids: ChosenFileIds;
+    naming: ChosenFileNaming;
+    changeLabel: string;
+    remove: ChosenFileRemove | null;
+    disabled: boolean;
+    onChange: () => void;
+    buttonRef: Ref<HTMLButtonElement>;
+};
+/**
+ * The chosen file in the full field: its mark, its name over its detail,
+ * then the change button (and Remove after it) at the row's end.
+ */
+export declare function ChosenFileRow({ value, icon, ids, naming, changeLabel, remove, disabled, onChange, buttonRef, }: ChosenFileProps): import("react").JSX.Element;
+/**
+ * The chosen file in a compact field: one row at a text field's height.
+ * The mark and the name (cut to one line) are the change button, named by
+ * the field's label and the change words, described by the name and the
+ * detail (which is not drawn); Remove, quiet, ends the row.
+ */
+export declare function ChosenFileCompact({ value, icon, ids, naming, changeLabel, remove, disabled, onChange, buttonRef, }: ChosenFileProps): import("react").JSX.Element;
+export {};

package/dist/components/file-field/ChosenFile.js

@@ -0,0 +1,48 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { tabStop } from '../../tab-stop.js';
+import { Button } from '../Button.js';
+/** Whether the consumer passed a mark to draw (not empty JSX). */
+function hasMark(icon) {
+    return (icon !== undefined &&
+        icon !== null &&
+        icon !== '' &&
+        typeof icon !== 'boolean');
+}
+/** Before a chosen file's name: its photo's thumbnail, else the consumer's mark. */
+function ChosenMark({ icon, preview }) {
+    if (preview !== undefined)
+        return _jsx("img", { alt: "", className: "sw-file-field-preview", src: preview });
+    if (!hasMark(icon))
+        return null;
+    return (_jsx("span", { "aria-hidden": "true", className: "sw-file-field-icon", children: icon }));
+}
+/**
+ * Remove: a quiet button named by its words and the field's label
+ * ("Remove Cover photo"), so two fields' Removes are told apart. Disabled,
+ * the neutral one greys as the change button does; the ghost one, which
+ * has no fill, fades as the compact row's pick button does.
+ */
+function RemoveButton({ ids, remove, disabled, variant, }) {
+    return (_jsx(Button
+    // Named by its own words, then the label: the self-reference is
+    // deliberate and needs the id below on the button itself.
+    , { "aria-labelledby": `${ids.remove} ${ids.label}`, className: "sw-file-field-remove", disabled: disabled, disabledAppearance: variant === 'neutral' ? 'neutral' : 'faded', id: ids.remove, onPress: remove.onRemove, size: variant === 'ghost' ? 'sm' : 'md', variant: variant, children: remove.label }));
+}
+/**
+ * The chosen file in the full field: its mark, its name over its detail,
+ * then the change button (and Remove after it) at the row's end.
+ */
+export function ChosenFileRow({ value, icon, ids, naming, changeLabel, remove, disabled, onChange, buttonRef, }) {
+    const change = (_jsx(Button, { ...naming, disabled: disabled, disabledAppearance: "neutral", onPress: onChange, ref: buttonRef, variant: "neutral", children: changeLabel }));
+    return (_jsxs(_Fragment, { children: [_jsx(ChosenMark, { icon: icon, preview: value.preview }), _jsxs("span", { className: "sw-file-field-file", children: [_jsx("span", { className: "sw-file-field-name", id: ids.name, children: value.name }), value.detail ? (_jsx("span", { className: "sw-file-field-detail", id: ids.detail, children: value.detail })) : null] }), remove === null ? (change) : (_jsxs("span", { className: "sw-file-field-actions", children: [change, _jsx(RemoveButton, { disabled: disabled, ids: ids, remove: remove, variant: "neutral" })] }))] }));
+}
+/**
+ * The chosen file in a compact field: one row at a text field's height.
+ * The mark and the name (cut to one line) are the change button, named by
+ * the field's label and the change words, described by the name and the
+ * detail (which is not drawn); Remove, quiet, ends the row.
+ */
+export function ChosenFileCompact({ value, icon, ids, naming, changeLabel, remove, disabled, onChange, buttonRef, }) {
+    return (_jsxs(_Fragment, { children: [_jsxs("button", { ...naming, className: "sw-file-field-pick", disabled: disabled, onClick: onChange, ref: buttonRef, tabIndex: tabStop, type: "button", children: [_jsx(ChosenMark, { icon: icon, preview: value.preview }), _jsx("span", { className: "sw-file-field-name", id: ids.name, children: value.name }), value.detail ? (_jsx("span", { className: "sw-sr-only", id: ids.detail, children: value.detail })) : null, _jsx("span", { className: "sw-sr-only", id: `${ids.button}-words`, children: changeLabel })] }), remove === null ? null : (_jsx(RemoveButton, { disabled: disabled, ids: ids, remove: remove, variant: "ghost" }))] }));
+}

package/dist/components/file-field/file-field-checks.d.ts

@@ -1,8 +1,9 @@
 import type { FileFieldValue } from '../FileField.js';
 /**
  * Fails closed on a FileField it cannot name or show: an empty label,
- * choose or change words, a blank drop hint, or a chosen file with no name,
- * a blank detail or a blank preview address.
+ * choose or change words, a blank drop hint, `onRemove` without its
+ * words (or words without it), blank Remove words, or a chosen file with
+ * no name, a blank detail or a blank preview address.
  */
 export declare function assertFileField(props: {
     label: string;
@@ -10,4 +11,6 @@ export declare function assertFileField(props: {
     changeLabel: string;
     dropLabel: string | undefined;
     value: FileFieldValue | null;
+    onRemove: (() => void) | undefined;
+    removeLabel: string | undefined;
 }): void;

package/dist/components/file-field/file-field-checks.js

@@ -3,8 +3,9 @@ function isBlank(text) {
 }
 /**
  * Fails closed on a FileField it cannot name or show: an empty label,
- * choose or change words, a blank drop hint, or a chosen file with no name,
- * a blank detail or a blank preview address.
+ * choose or change words, a blank drop hint, `onRemove` without its
+ * words (or words without it), blank Remove words, or a chosen file with
+ * no name, a blank detail or a blank preview address.
  */
 export function assertFileField(props) {
     for (const key of ['label', 'chooseLabel', 'changeLabel'])
@@ -12,6 +13,10 @@ export function assertFileField(props) {
             throw new RangeError(`FileField ${key} must be non-empty text`);
     if (props.dropLabel !== undefined && isBlank(props.dropLabel))
         throw new RangeError('FileField dropLabel must be non-empty text');
+    if ((props.onRemove === undefined) !== (props.removeLabel === undefined))
+        throw new RangeError('FileField onRemove and removeLabel go together');
+    if (props.removeLabel !== undefined && isBlank(props.removeLabel))
+        throw new RangeError('FileField removeLabel must be non-empty text');
     if (props.value === null)
         return;
     if (isBlank(props.value.name))