@scalewing/react 1.47.0 → 1.48.0

package/dist/components/Skeleton.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from 'react';
+import { cx } from '../class-names.js';
+import { skeletonLineRange, skeletonVariants, } from '../css/css-skeleton.js';
+import { isOneOf } from '../is-one-of.js';
+export { skeletonVariants };
+/** Fails closed on blank words, a count outside 1–6 or an unknown variant. */
+function assertSkeleton({ label, lines, variant }) {
+    if (typeof label !== 'string' || !label.trim())
+        throw new RangeError('Skeleton label must be nonempty');
+    if (!Number.isInteger(lines) ||
+        lines < skeletonLineRange.min ||
+        lines > skeletonLineRange.max)
+        throw new RangeError(`Skeleton lines must be a whole number from ${skeletonLineRange.min} to ${skeletonLineRange.max}: ${String(lines)}`);
+    if (!isOneOf(skeletonVariants, variant))
+        throw new RangeError(`Skeleton variant must be one of ${skeletonVariants.join(', ')}`);
+}
+/**
+ * Grey placeholder bars where content is loading, in place of a spinner:
+ * a polite status named by `label`, the bars decorative. They pulse
+ * gently, and stay still when reduced motion is asked for.
+ */
+export function Skeleton({ label, lines = 3, variant = 'lines', }) {
+    assertSkeleton({ label, lines, variant });
+    const labelId = useId();
+    // The bars and rows are divs and the words a span, so the generated
+    // :nth-of-type widths count bars only.
+    const places = Array.from({ length: lines }, (_, index) => index);
+    return (_jsxs("div", { "aria-labelledby": labelId, className: cx('sw-skeleton', `sw-skeleton-${variant}`), role: "status", children: [_jsx("span", { className: "sw-sr-only", id: labelId, children: label }), places.map((place) => variant === 'rows' ? (_jsxs("div", { "aria-hidden": "true", className: "sw-skeleton-row", children: [_jsx("div", { className: "sw-skeleton-mark" }), _jsx("div", { className: "sw-skeleton-bar" })] }, place)) : (_jsx("div", { "aria-hidden": "true", className: "sw-skeleton-bar" }, place)))] }));
+}

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

@@ -0,0 +1,23 @@
+import { type ReactNode, type Ref } from 'react';
+import { type AppShellProps } from './types.js';
+export type AppShellBarProps = Pick<AppShellProps, 'barEnd' | 'barTitle' | 'menuCount' | 'menuCountLabel' | 'menuCountTone'> & {
+    /** The bar itself, measured so a page bar can stick under it. */
+    barRef: Ref<HTMLElement>;
+    menuRef: Ref<HTMLButtonElement>;
+    menuIcon: ReactNode;
+    openMenuLabel: string;
+    menuOpen: boolean;
+    onOpenMenu: () => void;
+};
+/**
+ * The menu button's name: its label, then the count's words (or the bare
+ * number) after a comma while there is a count to read.
+ */
+export declare function menuButtonName(openMenu: string, menuCount: number | undefined, menuCountLabel: string | undefined): string;
+/**
+ * The compact top bar below `lg` (an AppHeader `bar`): the icon-only menu
+ * button, which may carry the shared count pill on its top end corner, the
+ * title and the end controls. The pill is hidden from assistive technology
+ * because the button's name already reads it.
+ */
+export declare function AppShellBar({ barEnd, barRef, barTitle, menuCount, menuCountLabel, menuCountTone, menuIcon, menuOpen, menuRef, onOpenMenu, openMenuLabel, }: AppShellBarProps): import("react").JSX.Element;

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

@@ -0,0 +1,25 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from '../../class-names.js';
+import { countToneClass } from '../../css/css-count-pill.js';
+import { AppHeader } from '../AppHeader.js';
+import { Button } from '../Button.js';
+/**
+ * The menu button's name: its label, then the count's words (or the bare
+ * number) after a comma while there is a count to read.
+ */
+export function menuButtonName(openMenu, menuCount, menuCountLabel) {
+    if (!menuCount)
+        return openMenu;
+    return `${openMenu}, ${menuCountLabel ?? String(menuCount)}`;
+}
+/**
+ * The compact top bar below `lg` (an AppHeader `bar`): the icon-only menu
+ * button, which may carry the shared count pill on its top end corner, the
+ * title and the end controls. The pill is hidden from assistive technology
+ * because the button's name already reads it.
+ */
+export function AppShellBar({ barEnd, barRef, barTitle, menuCount, menuCountLabel, menuCountTone = 'danger', menuIcon, menuOpen, menuRef, onOpenMenu, openMenuLabel, }) {
+    return (_jsxs(AppHeader, { ref: barRef, appearance: "bar", className: "sw-app-shell-bar", padding: 2, children: [_jsxs(Button, { ref: menuRef, "aria-expanded": menuOpen, "aria-haspopup": "dialog", "aria-label": menuButtonName(openMenuLabel, menuCount, menuCountLabel), className: "sw-app-shell-menu", onPress: onOpenMenu, size: "sm", variant: "ghost", children: [_jsx("span", { "aria-hidden": "true", className: "sw-app-shell-icon", children: menuIcon }), menuCount ? (_jsx("span", { "aria-hidden": "true", className: cx('sw-app-shell-count', menuCountTone !== 'danger' &&
+                            countToneClass('sw-app-shell-count', menuCountTone)), children: menuCount })) : null] }), _jsx("div", { className: "sw-app-shell-bar-title", children: barTitle }), barEnd ? _jsx("div", { className: "sw-app-shell-bar-end", children: barEnd }) : null] }));
+}

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

@@ -63,6 +63,9 @@ export type AppShellProps = {
     onNavigate?: (item: AppShellNavItem) => void;
     /**
      * The sidebar's top, such as a workspace switcher; also the drawer's.
+     * It may hold an interactive trigger (an `ActionMenu`, a `ContextSwitcher`):
+     * its popup opens on the top layer, so the sidebar and the drawer never
+     * clip it.
      * 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.
@@ -71,7 +74,11 @@ export type AppShellProps = {
     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. */
+    /**
+     * A compact `header` for the rail, such as a workspace switcher drawn as
+     * its glyph alone (an icon trigger named by its label). Left out, the
+     * rail shows none.
+     */
     railHeader?: ReactNode;
     /** A compact `footer` for the rail. Left out, the rail shows none. */
     railFooter?: ReactNode;
@@ -81,6 +88,34 @@ export type AppShellProps = {
     barEnd?: ReactNode;
     /** The consumer's glyph for the menu button (Scalewing has no icon catalog). */
     menuIcon: ReactNode;
+    /**
+     * How many things wait behind the menu, such as an inbox: the shared
+     * count pill on the menu button's top end corner, below `lg`, read in
+     * its name after `labels.openMenu` and a comma ("Open menu, 6"). A whole
+     * number; 0 (or none) shows no pill.
+     */
+    menuCount?: number;
+    /**
+     * What the menu's count means, in the consumer's words ("6 need you"):
+     * read in the name in place of the bare number ("Open menu, 6 need you").
+     * Needs `menuCount`.
+     */
+    menuCountLabel?: string;
+    /**
+     * The menu pill's colour, NavCount's tones: `danger` (the default),
+     * `warning` (amber) for work that needs the person but is not urgent,
+     * `accent` for news. Needs `menuCount`.
+     */
+    menuCountTone?: NavCountTone;
+    /**
+     * A band at the top of `main` on every layout, such as the page's
+     * context pickers and search: the solid surface with a hairline under it
+     * and the page's inline padding (space-4 below `lg`, space-6 from it),
+     * its children laid out in a wrapping row with space between them. It is
+     * sticky: under the compact top bar below `lg`, at the window's top
+     * from `lg` up. It scrolls with nothing else; keep it to one row.
+     */
+    pageBar?: ReactNode;
     labels: AppShellLabels;
     /** The page, rendered in `main`. */
     children: ReactNode;

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

@@ -1,6 +1,7 @@
 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).
+ * Fails closed on the shell's words, the menu's count, 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;
+export declare function assertAppShellProps({ groups, labels, menuCount, menuCountLabel, menuCountTone, navLabel, }: Pick<AppShellProps, 'groups' | 'labels' | 'menuCount' | 'menuCountLabel' | 'menuCountTone' | 'navLabel'>): void;

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

@@ -28,14 +28,32 @@ function assertGroups(groups) {
         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).
+ * Fails closed on the menu button's count: a whole number from 0, a
+ * nonempty label and a known tone, each of the last two with a count.
  */
-export function assertAppShellProps({ groups, labels, navLabel, }) {
+function assertMenuCount({ menuCount, menuCountLabel, menuCountTone, }) {
+    if (menuCount !== undefined &&
+        (!Number.isInteger(menuCount) || menuCount < 0))
+        throw new RangeError(`AppShell menuCount must be a whole number from 0: ${String(menuCount)}`);
+    if (menuCountLabel !== undefined && isBlank(menuCountLabel))
+        throw new RangeError('AppShell menuCountLabel must be nonempty');
+    if (menuCountTone !== undefined && !isOneOf(navCountTones, menuCountTone))
+        throw new RangeError(`AppShell menuCountTone must be one of ${navCountTones.join(', ')}`);
+    if (menuCount === undefined &&
+        (menuCountLabel !== undefined || menuCountTone !== undefined))
+        throw new RangeError('AppShell menuCountLabel and menuCountTone come with a menuCount');
+}
+/**
+ * Fails closed on the shell's words, the menu's count, 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, menuCount, menuCountLabel, menuCountTone, 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');
+    assertMenuCount({ menuCount, menuCountLabel, menuCountTone });
     assertGroups(groups);
     const items = groups.flatMap((group) => group.items);
     assertNavItems('AppShell', items);

package/dist/components/command-palette/PaletteList.d.ts

@@ -0,0 +1,20 @@
+import { type PointerEvent } from 'react';
+import { type CommandPaletteGroup, type CommandPaletteItem } from './types.js';
+type PaletteListProps = {
+    listId: string;
+    label: string;
+    groups: readonly CommandPaletteGroup[];
+    activeId: string | undefined;
+    /** The row's DOM id from the item's id. */
+    rowId: (item: CommandPaletteItem) => string;
+    onActivate: (item: CommandPaletteItem, event: PointerEvent) => void;
+    onChoose: (item: CommandPaletteItem) => void;
+};
+/**
+ * The always-open results: a listbox named by the palette's label, each
+ * group a `group` under its caption, each item its mark (hidden), label and
+ * detail, and the active row's Enter key hint (hidden: Enter is how a
+ * listbox row is chosen).
+ */
+export declare function PaletteList({ activeId, groups, label, listId, onActivate, onChoose, rowId, }: PaletteListProps): import("react").JSX.Element;
+export {};

package/dist/components/command-palette/PaletteList.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The always-open results: a listbox named by the palette's label, each
+ * group a `group` under its caption, each item its mark (hidden), label and
+ * detail, and the active row's Enter key hint (hidden: Enter is how a
+ * listbox row is chosen).
+ */
+export function PaletteList({ activeId, groups, label, listId, onActivate, onChoose, rowId, }) {
+    return (_jsx("div", { "aria-label": label, className: "sw-command-palette-list", hidden: !groups.some((group) => group.items.length > 0), id: listId, role: "listbox", children: groups.map((group, index) => {
+            if (group.items.length === 0)
+                return null;
+            const headingId = `${listId}-group-${index}`;
+            return (_jsxs("div", { "aria-labelledby": headingId, role: "group", children: [_jsx("div", { className: "sw-command-palette-heading", id: headingId, role: "presentation", children: group.label }), group.items.map((item) => {
+                        const active = item.id === activeId;
+                        return (_jsxs("div", { "aria-selected": active, className: "sw-command-palette-item", id: rowId(item), onClick: () => onChoose(item), onPointerMove: (event) => {
+                                if (!active)
+                                    onActivate(item, event);
+                            }, role: "option", children: [item.icon ? (_jsx("span", { "aria-hidden": "true", className: "sw-command-palette-icon", children: item.icon })) : null, _jsxs("span", { className: "sw-command-palette-words", children: [_jsx("span", { className: "sw-command-palette-label", children: item.label }), item.detail ? (_jsxs(_Fragment, { children: [' ', _jsx("span", { className: "sw-command-palette-detail", children: item.detail })] })) : null] }), active ? (_jsx("span", { "aria-hidden": "true", className: "sw-command-palette-key", children: "\u21B5" })) : null] }, item.id));
+                    })] }, group.id));
+        }) }));
+}

package/dist/components/command-palette/shortcut.d.ts

@@ -0,0 +1,19 @@
+import { type CommandPaletteShortcut } from './types.js';
+/** Whether the system's command key is ⌘ (Apple) rather than Ctrl. */
+export declare function usesCommandKey(platform: string): boolean;
+/** An element a person types into: a text field, a select or editable text. */
+export declare function isEditable(target: EventTarget | null): boolean;
+type ShortcutKey = Pick<KeyboardEvent, 'key' | 'code' | 'metaKey' | 'ctrlKey' | 'altKey' | 'shiftKey' | 'repeat' | 'isComposing'>;
+/**
+ * ⌘K on an Apple system or Ctrl+K elsewhere, with no other modifier: the K
+ * the layout types, or the key in K's place (`KeyK`) on a layout that types
+ * another letter there, such as Cyrillic or Greek.
+ */
+export declare function isModK(event: ShortcutKey, commandKey: boolean): boolean;
+/**
+ * Listens on the document for the palette's shortcut while `shortcut` is
+ * set: it calls `onToggle` (and stops the browser's own use of the keys)
+ * unless focus is in another text field than `ownField`.
+ */
+export declare function usePaletteShortcut(shortcut: CommandPaletteShortcut | null | undefined, ownField: () => HTMLElement | null, onToggle: () => void): void;
+export {};

package/dist/components/command-palette/shortcut.js

@@ -0,0 +1,75 @@
+'use client';
+import { useEffect, useRef } from 'react';
+/** Whether the system's command key is ⌘ (Apple) rather than Ctrl. */
+export function usesCommandKey(platform) {
+    return /mac|iphone|ipad|ipod/i.test(platform);
+}
+function systemPlatform() {
+    const nav = navigator;
+    return nav.userAgentData?.platform || nav.platform || nav.userAgent || '';
+}
+/** An element a person types into: a text field, a select or editable text. */
+export function isEditable(target) {
+    if (!(target instanceof HTMLElement))
+        return false;
+    if (target.isContentEditable)
+        return true;
+    if (target instanceof HTMLTextAreaElement ||
+        target instanceof HTMLSelectElement)
+        return true;
+    if (!(target instanceof HTMLInputElement))
+        return false;
+    return ![
+        'button',
+        'checkbox',
+        'radio',
+        'range',
+        'color',
+        'file',
+        'image',
+        'reset',
+        'submit',
+    ].includes(target.type);
+}
+/**
+ * ⌘K on an Apple system or Ctrl+K elsewhere, with no other modifier: the K
+ * the layout types, or the key in K's place (`KeyK`) on a layout that types
+ * another letter there, such as Cyrillic or Greek.
+ */
+export function isModK(event, commandKey) {
+    if (event.repeat || event.isComposing)
+        return false;
+    const isK = event.key.toLowerCase() === 'k' || event.code === 'KeyK';
+    if (!isK || event.altKey || event.shiftKey)
+        return false;
+    return commandKey
+        ? event.metaKey && !event.ctrlKey
+        : event.ctrlKey && !event.metaKey;
+}
+/**
+ * Listens on the document for the palette's shortcut while `shortcut` is
+ * set: it calls `onToggle` (and stops the browser's own use of the keys)
+ * unless focus is in another text field than `ownField`.
+ */
+export function usePaletteShortcut(shortcut, ownField, onToggle) {
+    const latest = useRef({ ownField, onToggle });
+    useEffect(() => {
+        latest.current = { ownField, onToggle };
+    });
+    useEffect(() => {
+        if (shortcut !== 'mod+k')
+            return;
+        const commandKey = usesCommandKey(systemPlatform());
+        function onKeyDown(event) {
+            if (event.defaultPrevented || !isModK(event, commandKey))
+                return;
+            const target = event.target;
+            if (isEditable(target) && target !== latest.current.ownField())
+                return;
+            event.preventDefault();
+            latest.current.onToggle();
+        }
+        document.addEventListener('keydown', onKeyDown);
+        return () => document.removeEventListener('keydown', onKeyDown);
+    }, [shortcut]);
+}

package/dist/components/command-palette/types.d.ts

@@ -0,0 +1,72 @@
+import { type ReactNode } from 'react';
+/** One result or command in the palette. */
+export type CommandPaletteItem = {
+    id: string;
+    label: string;
+    /** A muted line under the label, such as where a result lives. */
+    detail?: string;
+    /** A decorative mark before the label (a consumer glyph or crest). */
+    icon?: ReactNode;
+    /**
+     * Runs once the palette has closed after it was chosen (the consumer set
+     * `open` to false from `onOpenChange(false)`), so it can move focus to
+     * the page; without that, focus returns to where it was.
+     */
+    onSelect: () => void;
+};
+/** A run of items under a caption, such as "Teams" or "Actions". */
+export type CommandPaletteGroup = {
+    id: string;
+    label: string;
+    items: readonly CommandPaletteItem[];
+};
+/** The global shortcut that opens the palette: ⌘K on Apple systems, Ctrl+K elsewhere. */
+export declare const commandPaletteShortcuts: readonly ["mod+k"];
+export type CommandPaletteShortcut = (typeof commandPaletteShortcuts)[number];
+export type CommandPaletteProps = {
+    /** Whether the palette is shown. */
+    open: boolean;
+    /**
+     * Asked to open (the shortcut) or close (Escape, a press outside, the
+     * shortcut again, or a chosen item).
+     */
+    onOpenChange: (open: boolean) => void;
+    /** The palette's name and its field's, such as "Search". */
+    label: string;
+    placeholder?: string;
+    /** The field's words; the consumer filters `groups` from them. */
+    query: string;
+    onQueryChange: (query: string) => void;
+    /** The results in groups; a group with no items is not drawn. */
+    groups: readonly CommandPaletteGroup[];
+    /** Shown, and announced, when no group has an item (and not loading). */
+    emptyText: string;
+    /** The words announced for the number of items, such as `(n) => \`${n} results\``. */
+    countText?: (count: number) => string;
+    /** A muted line in the footer, such as how to use the keys. */
+    hint?: string;
+    /** While true, `loadingText` is shown and announced in place of the empty words. */
+    loading?: boolean;
+    loadingText?: string;
+    /**
+     * `'mod+k'` listens on the whole document for ⌘K (Apple) or Ctrl+K
+     * (elsewhere) to open the palette, or close it while open; it is left
+     * alone while focus is in another text field. `null` or nothing: no
+     * shortcut. Give it to one palette per page: two palettes listening for
+     * it would both open.
+     */
+    shortcut?: CommandPaletteShortcut | null;
+};
+export type CommandPaletteTriggerProps = {
+    /** The button's name, such as "Search". Start `placeholder` with its words. */
+    label: string;
+    /** The words drawn in the search-looking button, such as "Search teams and games". */
+    placeholder: string;
+    /** The key hint drawn at the end, such as "⌘K" or "Ctrl K"; hidden from assistive technology. */
+    shortcutLabel?: string;
+    /** The consumer's search glyph (Scalewing has no icon catalog). */
+    icon: ReactNode;
+    /** An icon-only button, the glyph alone, for a narrow bar. */
+    compact?: boolean;
+    onPress: () => void;
+};

package/dist/components/command-palette/types.js

@@ -0,0 +1,2 @@
+/** The global shortcut that opens the palette: ⌘K on Apple systems, Ctrl+K elsewhere. */
+export const commandPaletteShortcuts = ['mod+k'];

package/dist/components/command-palette/validate.d.ts

@@ -0,0 +1,10 @@
+import { type CommandPaletteProps, type CommandPaletteTriggerProps } from './types.js';
+/**
+ * Fails closed on a palette it cannot name or draw: blank words, a group
+ * without a caption, empty or duplicate group or item ids (items across
+ * groups), a blank item label or detail, loading without its words, or an
+ * unknown shortcut.
+ */
+export declare function assertCommandPalette({ emptyText, groups, hint, label, loading, loadingText, placeholder, shortcut, }: CommandPaletteProps): void;
+/** Fails closed on a trigger with blank words or a glyph that draws nothing. */
+export declare function assertCommandPaletteTrigger({ icon, label, placeholder, shortcutLabel, }: CommandPaletteTriggerProps): void;

package/dist/components/command-palette/validate.js

@@ -0,0 +1,50 @@
+import { isOneOf } from '../../is-one-of.js';
+import { hasSlot } from '../slot.js';
+import { commandPaletteShortcuts, } from './types.js';
+function isBlank(words) {
+    return typeof words !== 'string' || !words.trim();
+}
+function blankWhenGiven(words) {
+    return words !== undefined && isBlank(words);
+}
+function hasDuplicates(ids) {
+    return new Set(ids).size !== ids.length;
+}
+/**
+ * Fails closed on a palette it cannot name or draw: blank words, a group
+ * without a caption, empty or duplicate group or item ids (items across
+ * groups), a blank item label or detail, loading without its words, or an
+ * unknown shortcut.
+ */
+export function assertCommandPalette({ emptyText, groups, hint, label, loading, loadingText, placeholder, shortcut, }) {
+    const name = 'CommandPalette';
+    if (isBlank(label) || isBlank(emptyText))
+        throw new RangeError(`${name} label and emptyText must be nonempty`);
+    if (blankWhenGiven(placeholder) || blankWhenGiven(hint))
+        throw new RangeError(`${name} placeholder and hint are nonempty when given`);
+    if (blankWhenGiven(loadingText) || (loading && isBlank(loadingText)))
+        throw new RangeError(`${name} loading needs a nonempty loadingText`);
+    if (shortcut != null && !isOneOf(commandPaletteShortcuts, shortcut))
+        throw new RangeError(`${name} shortcut must be one of ${commandPaletteShortcuts.join(', ')} or null`);
+    if (groups.some((group) => isBlank(group.id) || isBlank(group.label)))
+        throw new RangeError(`${name} groups need nonempty ids and labels`);
+    if (hasDuplicates(groups.map((group) => group.id)))
+        throw new RangeError(`${name} groups need unique ids`);
+    const items = groups.flatMap((group) => group.items);
+    if (items.some((item) => isBlank(item.id) || isBlank(item.label)))
+        throw new RangeError(`${name} items need nonempty ids and labels`);
+    if (items.some((item) => blankWhenGiven(item.detail)))
+        throw new RangeError(`${name} item details are nonempty when given`);
+    if (hasDuplicates(items.map((item) => item.id)))
+        throw new RangeError(`${name} items need unique ids`);
+}
+/** Fails closed on a trigger with blank words or a glyph that draws nothing. */
+export function assertCommandPaletteTrigger({ icon, label, placeholder, shortcutLabel, }) {
+    const name = 'CommandPaletteTrigger';
+    if (isBlank(label) || isBlank(placeholder))
+        throw new RangeError(`${name} label and placeholder must be nonempty`);
+    if (blankWhenGiven(shortcutLabel))
+        throw new RangeError(`${name} shortcutLabel is nonempty when given`);
+    if (!hasSlot(icon) || (typeof icon === 'string' && !icon.trim()))
+        throw new RangeError(`${name} needs its search glyph`);
+}

package/dist/components/context-switcher/SwitcherOption.d.ts

@@ -0,0 +1,17 @@
+import { type PointerEvent } from 'react';
+import { type SwitcherEntry } from './options.js';
+type SwitcherOptionProps = {
+    entry: SwitcherEntry;
+    active: boolean;
+    current: boolean;
+    /** A pointer moved over the row; the popup decides whether it really moved. */
+    onActivate: (event: PointerEvent) => void;
+    onChoose: () => void;
+};
+/**
+ * One option: its mark (hidden), its label over its detail, its badge and
+ * count (both read in its name, a `countLabel` in place of the number) and
+ * the current one's check (hidden; `aria-selected` says it).
+ */
+export declare function SwitcherOption({ active, current, entry, onActivate, onChoose, }: SwitcherOptionProps): import("react").JSX.Element;
+export {};

package/dist/components/context-switcher/SwitcherOption.js

@@ -0,0 +1,20 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { cx } from '../../class-names.js';
+import { countToneClass } from '../../css/css-count-pill.js';
+import { Badge } from '../Badge.js';
+/**
+ * One option: its mark (hidden), its label over its detail, its badge and
+ * count (both read in its name, a `countLabel` in place of the number) and
+ * the current one's check (hidden; `aria-selected` says it).
+ */
+export function SwitcherOption({ active, current, entry, onActivate, onChoose, }) {
+    const { option } = entry;
+    const tone = option.countTone ?? 'danger';
+    return (_jsxs("div", { "aria-selected": current, className: "sw-context-switcher-option", "data-active": active ? 'true' : undefined, id: entry.domId, onClick: onChoose, 
+        // The pointer moves the active row, as the arrow keys do.
+        onPointerMove: (event) => {
+            if (!active)
+                onActivate(event);
+        }, role: "option", children: [option.icon ? (_jsx("span", { "aria-hidden": "true", className: "sw-context-switcher-icon", children: option.icon })) : null, _jsxs("span", { className: "sw-context-switcher-words", children: [_jsx("span", { className: "sw-context-switcher-label", children: option.label }), option.detail ? (_jsxs("span", { className: "sw-context-switcher-detail", children: [" ", option.detail] })) : null] }), option.badge ? (_jsx(Badge, { size: "sm", tone: option.badge.tone, children: option.badge.label })) : null, option.count ? (_jsxs(_Fragment, { children: [option.countLabel ? (_jsx("span", { className: "sw-sr-only", children: ` ${option.countLabel}` })) : null, _jsx("span", { "aria-hidden": option.countLabel ? true : undefined, className: cx('sw-context-switcher-count', tone !== 'danger' &&
+                            countToneClass('sw-context-switcher-count', tone)), children: option.count })] })) : null, current ? (_jsx("span", { "aria-hidden": "true", className: "sw-context-switcher-check" })) : null] }));
+}

package/dist/components/context-switcher/SwitcherPopup.d.ts

@@ -0,0 +1,31 @@
+import { type RefObject } from 'react';
+import { type InlineAlign } from '../../anchored-position.js';
+import { type SwitcherEntry } from './options.js';
+import { type ContextSwitcherAction, type ContextSwitcherFilter, type ContextSwitcherGroup } from './types.js';
+type SwitcherPopupProps = {
+    label: string;
+    groups: readonly ContextSwitcherGroup[];
+    currentId: string | undefined;
+    /** The filter, when it is shown (enough options). */
+    filter: ContextSwitcherFilter | undefined;
+    actions: readonly ContextSwitcherAction[];
+    align: InlineAlign;
+    triggerRef: RefObject<HTMLButtonElement | null>;
+    /** Whether a pointer is pressing the trigger (its click toggles the popup). */
+    triggerPressed: () => boolean;
+    /** Closes the popup; `refocus` hands focus back to the trigger. */
+    onClose: (refocus: boolean) => void;
+    onChoose: (entry: SwitcherEntry) => void;
+    onAction: (action: ContextSwitcherAction) => void;
+};
+/**
+ * The open popup: a non-modal `dialog` named by the switcher's label on the
+ * top layer beside the trigger. Focus moves into it, to the filter field
+ * (an ARIA combobox over the listbox) or else to the listbox itself; both
+ * point at the active row with `aria-activedescendant`. Escape closes it
+ * and returns focus to the trigger; a press outside or focus leaving it
+ * (Tab past its end, Shift+Tab back to the trigger) closes it where focus
+ * went.
+ */
+export declare function SwitcherPopup({ actions, align, currentId, filter, groups, label, onAction, onChoose, onClose, triggerPressed, triggerRef, }: SwitcherPopupProps): import("react").JSX.Element;
+export {};