@scalewing/react 1.46.0 → 1.48.0

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

@@ -0,0 +1,70 @@
+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 menu button's count: a whole number from 0, a
+ * nonempty label and a known tone, each of the last two with a count.
+ */
+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);
+    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/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 {};

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

@@ -0,0 +1,111 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Fragment, useId, useLayoutEffect, useRef, } from 'react';
+import { Button } from '../Button.js';
+import { contextSwitcherTriggerWidthVariable } from '../../css/css-context-switcher.js';
+import { useAnchoredPopover } from '../use-anchored-popover.js';
+import { SwitcherOption } from './SwitcherOption.js';
+import { useSwitcherList } from './use-switcher-list.js';
+/**
+ * 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 function SwitcherPopup({ actions, align, currentId, filter, groups, label, onAction, onChoose, onClose, triggerPressed, triggerRef, }) {
+    const popupRef = useRef(null);
+    const focusRef = useRef(null);
+    const listId = useId();
+    const list = useSwitcherList({
+        currentId,
+        filtering: filter !== undefined,
+        groups,
+        listId,
+        onChoose,
+    });
+    useAnchoredPopover(popupRef, triggerRef, triggerRef, () => onClose(false), {
+        align,
+        flipInline: true,
+    });
+    // At least as wide as the trigger (the stylesheet keeps its own least
+    // width and the viewport cap), followed while the trigger resizes.
+    useLayoutEffect(() => {
+        const popup = popupRef.current;
+        const trigger = triggerRef.current;
+        if (!popup || !trigger)
+            return;
+        const fit = () => popup.style.setProperty(contextSwitcherTriggerWidthVariable, `${trigger.offsetWidth}px`);
+        fit();
+        if (typeof ResizeObserver === 'undefined')
+            return;
+        const observer = new ResizeObserver(fit);
+        observer.observe(trigger);
+        return () => observer.disconnect();
+    }, [triggerRef]);
+    // The last place the pointer moved to: a list scrolled under a still
+    // pointer can report a move with no movement, which must not take the
+    // active row from the keys.
+    const pointerAt = useRef(null);
+    function pointerMoved(event) {
+        const last = pointerAt.current;
+        pointerAt.current = { x: event.clientX, y: event.clientY };
+        return !last || last.x !== event.clientX || last.y !== event.clientY;
+    }
+    // A press anywhere but the field or a command keeps focus where it is
+    // (the field or the listbox), so the keys keep working after a press on
+    // a caption, the padding or a row.
+    function keepFocus(event) {
+        const target = event.target;
+        if (target instanceof Element && target.closest('input, button'))
+            return;
+        event.preventDefault();
+    }
+    useLayoutEffect(() => {
+        focusRef.current?.focus({ preventScroll: true });
+    }, []);
+    const activeDomId = list.active?.domId;
+    useLayoutEffect(() => {
+        if (activeDomId)
+            document
+                .getElementById(activeDomId)
+                ?.scrollIntoView?.({ block: 'nearest' });
+    }, [activeDomId]);
+    function onKeyDown(event) {
+        if (event.key === 'Escape') {
+            // Stops a dialog round the trigger (a drawer) from closing too.
+            event.preventDefault();
+            event.stopPropagation();
+            onClose(true);
+            return;
+        }
+        if (event.target !== focusRef.current)
+            return;
+        if (list.onListKey(event))
+            event.preventDefault();
+    }
+    function onBlur(event) {
+        const next = event.relatedTarget;
+        if (!(next instanceof Node) || popupRef.current?.contains(next))
+            return;
+        // Shift+Tab back to the trigger closes it too; a press on the trigger
+        // leaves that to the trigger's own toggle.
+        if (triggerRef.current?.contains(next) && triggerPressed())
+            return;
+        onClose(false);
+    }
+    const empty = list.entries.length === 0;
+    const activeDescendant = list.active?.domId;
+    return (_jsxs("div", { "aria-label": label, className: "sw-context-switcher-popup", onBlur: onBlur, onKeyDown: onKeyDown, onMouseDown: keepFocus, ref: popupRef, role: "dialog", children: [filter ? (_jsx("input", { "aria-activedescendant": activeDescendant, "aria-autocomplete": "list", "aria-controls": listId, "aria-expanded": "true", "aria-label": filter.label, autoComplete: "off", className: "sw-context-switcher-filter", onChange: (event) => list.changeQuery(event.target.value), placeholder: filter.placeholder, ref: focusRef, role: "combobox", spellCheck: false, type: "text", value: list.query })) : null, _jsx("div", { "aria-activedescendant": filter ? undefined : activeDescendant, "aria-label": label, className: "sw-context-switcher-list", hidden: empty, id: listId, ref: filter ? undefined : focusRef, role: "listbox", tabIndex: filter ? undefined : 0, children: list.sections.map(({ entries, group }, index) => {
+                    const rows = entries.map((entry) => (_jsx(SwitcherOption, { active: entry === list.active, current: entry.option.id === currentId, entry: entry, onActivate: (event) => {
+                            if (pointerMoved(event))
+                                list.setActiveId(entry.option.id);
+                        }, onChoose: () => onChoose(entry) }, entry.option.id)));
+                    if (!group.label)
+                        return _jsx(Fragment, { children: rows }, group.id);
+                    const headingId = `${listId}-group-${index}`;
+                    return (_jsxs("div", { "aria-labelledby": headingId, role: "group", children: [_jsx("div", { className: "sw-context-switcher-heading", id: headingId, role: "presentation", children: group.label }), rows] }, group.id));
+                }) }), filter ? (_jsxs(_Fragment, { children: [empty ? (_jsx("p", { "aria-hidden": "true", className: "sw-context-switcher-empty", children: filter.emptyText })) : null, _jsx("div", { className: "sw-sr-only", role: "status", children: empty ? filter.emptyText : '' })] })) : null, actions.length > 0 ? (_jsx("div", { className: "sw-context-switcher-footer", children: actions.map((action) => (_jsxs(Button, { onPress: () => onAction(action), size: "sm", variant: "ghost", children: [action.icon ? (_jsx("span", { "aria-hidden": "true", className: "sw-context-switcher-action-icon", children: action.icon })) : null, action.label] }, action.id))) })) : null] }));
+}

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

@@ -0,0 +1,33 @@
+import { type ContextSwitcherGroup, type ContextSwitcherOption } from './types.js';
+/** An option in list order, with the stable DOM id its row keeps while filtered. */
+export type SwitcherEntry = {
+    option: ContextSwitcherOption;
+    groupId: string;
+    /** The row's id under the listbox, from its place in the full list. */
+    domId: string;
+};
+/** A group with the entries left after filtering (none are dropped here). */
+export type SwitcherSection = {
+    group: ContextSwitcherGroup;
+    entries: SwitcherEntry[];
+};
+/** Words folded for matching: no case and no accents ("Árbol" → "arbol"). */
+export declare function foldWords(words: string): string;
+/** Every option's entry, in order, each with a DOM id under `listId`. */
+export declare function switcherSections(listId: string, groups: readonly ContextSwitcherGroup[]): SwitcherSection[];
+/**
+ * The sections whose options match `query` in their label or detail
+ * (folded, anywhere in the words); a blank query keeps them all, and a
+ * section left with no entries is dropped.
+ */
+export declare function filterSections(sections: readonly SwitcherSection[], query: string): SwitcherSection[];
+/** The entries of the sections in list order: what the arrow keys move over. */
+export declare function flatEntries(sections: readonly SwitcherSection[]): SwitcherEntry[];
+/** How many options the groups hold together. */
+export declare function optionCount(groups: readonly ContextSwitcherGroup[]): number;
+/**
+ * The entry typeahead lands on: the first whose label starts with `typed`
+ * (folded), searching after `from` and wrapping. Repeating one letter
+ * ("b", "bb") steps through the labels starting with it. -1 when none.
+ */
+export declare function typeaheadIndex(entries: readonly SwitcherEntry[], typed: string, from: number): number;

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

@@ -0,0 +1,60 @@
+/** Words folded for matching: no case and no accents ("Árbol" → "arbol"). */
+export function foldWords(words) {
+    return words.normalize('NFD').replace(/\p{M}/gu, '').toLocaleLowerCase();
+}
+/** Every option's entry, in order, each with a DOM id under `listId`. */
+export function switcherSections(listId, groups) {
+    let place = 0;
+    return groups.map((group) => ({
+        group,
+        entries: group.options.map((option) => ({
+            option,
+            groupId: group.id,
+            domId: `${listId}-option-${place++}`,
+        })),
+    }));
+}
+/**
+ * The sections whose options match `query` in their label or detail
+ * (folded, anywhere in the words); a blank query keeps them all, and a
+ * section left with no entries is dropped.
+ */
+export function filterSections(sections, query) {
+    const needle = foldWords(query.trim());
+    if (!needle)
+        return [...sections];
+    return sections
+        .map((section) => ({
+        group: section.group,
+        entries: section.entries.filter(({ option }) => foldWords(`${option.label} ${option.detail ?? ''}`).includes(needle)),
+    }))
+        .filter((section) => section.entries.length > 0);
+}
+/** The entries of the sections in list order: what the arrow keys move over. */
+export function flatEntries(sections) {
+    return sections.flatMap((section) => section.entries);
+}
+/** How many options the groups hold together. */
+export function optionCount(groups) {
+    return groups.reduce((total, group) => total + group.options.length, 0);
+}
+/**
+ * The entry typeahead lands on: the first whose label starts with `typed`
+ * (folded), searching after `from` and wrapping. Repeating one letter
+ * ("b", "bb") steps through the labels starting with it. -1 when none.
+ */
+export function typeaheadIndex(entries, typed, from) {
+    const folded = foldWords(typed);
+    if (!folded || entries.length === 0)
+        return -1;
+    const repeated = [...folded].every((letter) => letter === folded[0]);
+    const prefix = repeated ? folded[0] : folded;
+    // A fresh word may stay on the current entry; a repeated letter moves on.
+    const start = repeated ? from + 1 : Math.max(from, 0);
+    for (let step = 0; step < entries.length; step += 1) {
+        const index = (start + step) % entries.length;
+        if (foldWords(entries[index].option.label).startsWith(prefix))
+            return index;
+    }
+    return -1;
+}