@scalewing/react 1.47.0 → 1.49.0

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;
+}

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

@@ -0,0 +1,96 @@
+import { type ReactNode } from 'react';
+import { type InlineAlign } from '../../anchored-position.js';
+import { type BadgeTone } from '../../css/css-data.js';
+import { type ContextSwitcherTriggerAppearance, type ContextSwitcherWidth } from '../../css/css-context-switcher-trigger.js';
+import { type NavCountTone } from '../NavCount.js';
+/** A short status after an option's words, such as a season's "Live". */
+export type ContextSwitcherBadge = {
+    label: string;
+    tone: BadgeTone;
+};
+/** One context the person can switch to, such as a workspace or a season. */
+export type ContextSwitcherOption = {
+    id: string;
+    label: string;
+    /** A muted line under the label, such as the person's role there. */
+    detail?: string;
+    /** A decorative mark before the label (a consumer glyph or crest). */
+    icon?: ReactNode;
+    /** A status Badge after the words, read in the option's name. */
+    badge?: ContextSwitcherBadge;
+    /**
+     * How many things wait there: the shared count pill at the row's end,
+     * read in the option's name. A whole number; 0 shows no pill.
+     */
+    count?: number;
+    /** What the count means ("7 need you"), read in place of the number. Needs `count`. */
+    countLabel?: string;
+    /** The pill's colour, NavCount's tones (`danger` by default). Needs `count`. */
+    countTone?: NavCountTone;
+};
+/** A run of options, under a caption when it has a `label`. */
+export type ContextSwitcherGroup = {
+    id: string;
+    label?: string;
+    options: readonly ContextSwitcherOption[];
+};
+/** A command in the popup's footer, such as "Create a workspace". */
+export type ContextSwitcherAction = {
+    id: string;
+    label: string;
+    /** A decorative glyph before the label. */
+    icon?: ReactNode;
+    onSelect: () => void;
+};
+/** The filter field over the options, for a long list. */
+export type ContextSwitcherFilter = {
+    /** The field's name, such as "Find a workspace". */
+    label: string;
+    placeholder?: string;
+    /** Shown, and announced, when nothing matches the typed words. */
+    emptyText: string;
+    /**
+     * The field shows only from this many options (all groups together);
+     * 0, the default, always shows it.
+     */
+    minOptions?: number;
+};
+export type ContextSwitcherProps = {
+    /**
+     * What is being switched, such as "Workspace": the start of the
+     * trigger's name (then what the trigger shows) and the popup's name.
+     */
+    label: string;
+    /**
+     * What the trigger shows, usually the current context (its words, or a
+     * mark and words). With `triggerAppearance="icon"` it is a glyph alone,
+     * and the name is `label` and the current option's label.
+     */
+    trigger: ReactNode;
+    /**
+     * `framed` (default) is the outlined control with a chevron; `text` is
+     * the words and a chevron with no fill until hovered or open; `pill` is
+     * a rounded outlined pill at label weight with a chevron; `icon` is the
+     * glyph alone in a round quiet button, no chevron (a compact rail).
+     */
+    triggerAppearance?: ContextSwitcherTriggerAppearance;
+    /**
+     * `full` makes the trigger fill its column, such as a sidebar's top,
+     * its content at the start and the chevron at the end; `content` (the
+     * default) sizes it to what it shows.
+     */
+    width?: ContextSwitcherWidth;
+    groups: readonly ContextSwitcherGroup[];
+    /** The option in use, marked with a check and `aria-selected`. */
+    currentId?: string;
+    /**
+     * Called with the chosen option after the popup closes and focus is back
+     * on the trigger. Choosing the current option only closes the popup.
+     */
+    onSelect: (option: ContextSwitcherOption) => void;
+    filter?: ContextSwitcherFilter;
+    /** Commands under the options, after a hairline. */
+    actions?: readonly ContextSwitcherAction[];
+    /** The trigger edge the popup lines up with (start by default). */
+    align?: InlineAlign;
+};

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

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

package/dist/components/context-switcher/use-switcher-list.d.ts

@@ -0,0 +1,29 @@
+import { type KeyboardEvent } from 'react';
+import { type SwitcherEntry } from './options.js';
+import { type ContextSwitcherGroup } from './types.js';
+type SwitcherListOptions = {
+    listId: string;
+    groups: readonly ContextSwitcherGroup[];
+    currentId: string | undefined;
+    /** Whether the filter field holds focus (it keeps Home, End and letters). */
+    filtering: boolean;
+    onChoose: (entry: SwitcherEntry) => void;
+};
+/**
+ * The open popup's list model: the filter's words, the sections left by
+ * them, the active row (by its option id, so it stays put while the list
+ * changes), and the keys. Arrows move the active row (stopping at the
+ * ends), Enter chooses it; in the listbox Home and End go to the ends,
+ * Space chooses and letters jump by typeahead; in the filter field those
+ * keys edit the words, which make the first match active.
+ */
+export declare function useSwitcherList({ currentId, filtering, groups, listId, onChoose, }: SwitcherListOptions): {
+    active: SwitcherEntry | undefined;
+    changeQuery: (next: string) => void;
+    entries: SwitcherEntry[];
+    onListKey: (event: KeyboardEvent) => boolean;
+    query: string;
+    sections: import("./options.js").SwitcherSection[];
+    setActiveId: import("react").Dispatch<import("react").SetStateAction<string | undefined>>;
+};
+export {};