@scalewing/react 1.47.0 → 1.48.0

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

package/dist/components/context-switcher/use-switcher-list.js

@@ -0,0 +1,93 @@
+'use client';
+import { useMemo, useRef, useState } from 'react';
+import { filterSections, flatEntries, switcherSections, typeaheadIndex, } from './options.js';
+/* How long typed letters build one typeahead word. */
+const typeaheadPause = 500;
+/** A key that types a letter, not a shortcut or a control key. */
+function isPrintable(event) {
+    return (event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey);
+}
+/**
+ * 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 function useSwitcherList({ currentId, filtering, groups, listId, onChoose, }) {
+    const [query, setQuery] = useState('');
+    const [activeId, setActiveId] = useState(currentId);
+    const typed = useRef({ words: '', at: 0 });
+    const all = useMemo(() => switcherSections(listId, groups), [listId, groups]);
+    const sections = useMemo(() => filterSections(all, query), [all, query]);
+    const entries = useMemo(() => flatEntries(sections), [sections]);
+    const activeIndex = Math.max(entries.findIndex((entry) => entry.option.id === activeId), entries.length > 0 ? 0 : -1);
+    const active = entries[activeIndex];
+    function changeQuery(next) {
+        setQuery(next);
+        setActiveId(flatEntries(filterSections(all, next))[0]?.option.id);
+    }
+    function moveTo(index) {
+        const entry = entries[Math.min(Math.max(index, 0), entries.length - 1)];
+        if (entry)
+            setActiveId(entry.option.id);
+    }
+    function typeahead(letter) {
+        const now = Date.now();
+        const words = now - typed.current.at > typeaheadPause
+            ? letter
+            : typed.current.words + letter;
+        typed.current = { words, at: now };
+        const index = typeaheadIndex(entries, words, activeIndex);
+        if (index >= 0)
+            moveTo(index);
+    }
+    /** Handles a key in the listbox or the filter field; true when it was used. */
+    function onListKey(event) {
+        // Keys that build a word in an input method are the method's.
+        if (event.nativeEvent.isComposing || event.keyCode === 229)
+            return false;
+        const typing = Date.now() - typed.current.at <= typeaheadPause;
+        switch (event.key) {
+            case 'ArrowDown':
+                moveTo(activeIndex + 1);
+                return true;
+            case 'ArrowUp':
+                moveTo(activeIndex - 1);
+                return true;
+            case 'Enter':
+                if (active)
+                    onChoose(active);
+                return true;
+            case 'Home':
+            case 'End':
+                if (filtering)
+                    return false;
+                moveTo(event.key === 'Home' ? 0 : entries.length - 1);
+                return true;
+            case ' ':
+                if (filtering)
+                    return false;
+                if (typing)
+                    typeahead(' ');
+                else if (active)
+                    onChoose(active);
+                return true;
+            default:
+                if (filtering || !isPrintable(event))
+                    return false;
+                typeahead(event.key);
+                return true;
+        }
+    }
+    return {
+        active,
+        changeQuery,
+        entries,
+        onListKey,
+        query,
+        sections,
+        setActiveId,
+    };
+}

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

@@ -0,0 +1,8 @@
+import { type ContextSwitcherProps } from './types.js';
+/**
+ * Fails closed on a switcher it cannot draw or name: blank words, empty or
+ * duplicate groups, options (ids unique across groups) or actions, a bad
+ * count, badge or tone, a `currentId` that names no option, a trigger that
+ * draws nothing, or an unknown appearance, width or alignment.
+ */
+export declare function assertContextSwitcher({ actions, align, currentId, filter, groups, label, trigger, triggerAppearance, width, }: ContextSwitcherProps): void;

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

@@ -0,0 +1,94 @@
+import { contextSwitcherTriggerAppearances, contextSwitcherWidths, } from '../../css/css-context-switcher-trigger.js';
+import { badgeTones } from '../../css/css-data.js';
+import { isOneOf } from '../../is-one-of.js';
+import { navCountTones } from '../NavCount.js';
+import { hasSlot } from '../slot.js';
+const name = 'ContextSwitcher';
+/** The trigger edges the popup can line up with. */
+const inlineAligns = ['start', 'end'];
+function isBlank(words) {
+    return typeof words !== 'string' || !words.trim();
+}
+function isWholeFromZero(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 0;
+}
+function hasDuplicates(ids) {
+    return new Set(ids).size !== ids.length;
+}
+function assertGroups(groups) {
+    if (groups.length === 0)
+        throw new RangeError(`${name} needs at least one group`);
+    if (groups.some((group) => isBlank(group.id)))
+        throw new RangeError(`${name} groups need nonempty ids`);
+    if (hasDuplicates(groups.map((group) => group.id)))
+        throw new RangeError(`${name} groups need unique ids`);
+    if (groups.some((group) => group.label !== undefined && isBlank(group.label)))
+        throw new RangeError(`${name} group labels are nonempty when given`);
+    if (groups.some((group) => group.options.length === 0))
+        throw new RangeError(`${name} groups need at least one option`);
+}
+function assertOption(option) {
+    if (isBlank(option.id) || isBlank(option.label))
+        throw new RangeError(`${name} options need nonempty ids and labels`);
+    if (option.detail !== undefined && isBlank(option.detail))
+        throw new RangeError(`${name} option details are nonempty when given`);
+    if (option.badge !== undefined &&
+        (isBlank(option.badge.label) || !isOneOf(badgeTones, option.badge.tone)))
+        throw new RangeError(`${name} option badges need a label and one of ${badgeTones.join(', ')}`);
+    if (option.count !== undefined && !isWholeFromZero(option.count))
+        throw new RangeError(`${name} option counts are whole numbers from 0`);
+    if (option.countLabel !== undefined &&
+        (isBlank(option.countLabel) || option.count === undefined))
+        throw new RangeError(`${name} option countLabel is nonempty and comes with a count`);
+    if (option.countTone !== undefined &&
+        (!isOneOf(navCountTones, option.countTone) || option.count === undefined))
+        throw new RangeError(`${name} option countTone is one of ${navCountTones.join(', ')} and comes with a count`);
+}
+function assertFilter(filter) {
+    if (filter === undefined)
+        return;
+    if (isBlank(filter.label) || isBlank(filter.emptyText))
+        throw new RangeError(`${name} filter needs a label and an emptyText`);
+    if (filter.placeholder !== undefined && isBlank(filter.placeholder))
+        throw new RangeError(`${name} filter placeholder is nonempty when given`);
+    if (filter.minOptions !== undefined && !isWholeFromZero(filter.minOptions))
+        throw new RangeError(`${name} filter minOptions is a whole number from 0`);
+}
+function assertActions(actions) {
+    if (actions === undefined)
+        return;
+    if (actions.some((action) => isBlank(action.id) || isBlank(action.label)))
+        throw new RangeError(`${name} actions need nonempty ids and labels`);
+    if (hasDuplicates(actions.map((action) => action.id)))
+        throw new RangeError(`${name} actions need unique ids`);
+}
+/**
+ * Fails closed on a switcher it cannot draw or name: blank words, empty or
+ * duplicate groups, options (ids unique across groups) or actions, a bad
+ * count, badge or tone, a `currentId` that names no option, a trigger that
+ * draws nothing, or an unknown appearance, width or alignment.
+ */
+export function assertContextSwitcher({ actions, align, currentId, filter, groups, label, trigger, triggerAppearance, width, }) {
+    if (isBlank(label))
+        throw new RangeError(`${name} label must be nonempty`);
+    if (!hasSlot(trigger) ||
+        (typeof trigger === 'string' && trigger.trim() === ''))
+        throw new RangeError(`${name} needs a trigger to draw`);
+    if (triggerAppearance !== undefined &&
+        !isOneOf(contextSwitcherTriggerAppearances, triggerAppearance))
+        throw new RangeError(`${name} triggerAppearance must be one of ${contextSwitcherTriggerAppearances.join(', ')}`);
+    if (width !== undefined && !isOneOf(contextSwitcherWidths, width))
+        throw new RangeError(`${name} width must be one of ${contextSwitcherWidths.join(', ')}`);
+    if (align !== undefined && !isOneOf(inlineAligns, align))
+        throw new RangeError(`${name} align must be one of ${inlineAligns.join(', ')}`);
+    assertGroups(groups);
+    const options = groups.flatMap((group) => group.options);
+    options.forEach(assertOption);
+    if (hasDuplicates(options.map((option) => option.id)))
+        throw new RangeError(`${name} options need unique ids`);
+    if (currentId !== undefined &&
+        !options.some((option) => option.id === currentId))
+        throw new RangeError(`${name} currentId must name one of its options`);
+    assertFilter(filter);
+    assertActions(actions);
+}

package/dist/components/fixture/fixture-list-context.d.ts

@@ -0,0 +1,4 @@
+/** Set by FixtureGroup around its list, so a FixtureRow knows it is in one. */
+export declare const FixtureListContext: import("react").Context<boolean>;
+/** Fails closed on a FixtureRow outside a FixtureGroup (its `li` needs the list). */
+export declare function useFixtureList(): void;

package/dist/components/fixture/fixture-list-context.js

@@ -0,0 +1,9 @@
+'use client';
+import { createContext, useContext } from 'react';
+/** Set by FixtureGroup around its list, so a FixtureRow knows it is in one. */
+export const FixtureListContext = createContext(false);
+/** Fails closed on a FixtureRow outside a FixtureGroup (its `li` needs the list). */
+export function useFixtureList() {
+    if (!useContext(FixtureListContext))
+        throw new RangeError('A FixtureRow lives in a FixtureGroup');
+}

package/dist/components/fixture/types.d.ts

@@ -0,0 +1,50 @@
+import { type MouseEvent, type ReactNode } from 'react';
+import { type VisibilityBreakpoint } from '../../css/breakpoints.js';
+import { type BadgeTone } from '../../css/css-data.js';
+import { type FixtureCenterKind } from '../../css/css-fixture.js';
+/** One side of a fixture: its name and an optional decorative mark (a crest). */
+export type FixtureSide = {
+    name: string;
+    /** A mark beside the name, on the centre's side; hidden from assistive technology. */
+    mark?: ReactNode;
+};
+/** A status after the row's details, such as "Final" or "To confirm". */
+export type FixtureStatus = {
+    label: string;
+    tone: BadgeTone;
+};
+export type FixtureRowProps = {
+    home: FixtureSide;
+    away: FixtureSide;
+    /** What sits between the sides: a kickoff time ("8:00") or a score ("2–1"). */
+    center: string;
+    /**
+     * `time` (default) draws the centre as a small grey chip; `score` as
+     * bold figures. Both are tabular, so the rows' centres line up.
+     */
+    centerKind?: FixtureCenterKind;
+    /** Details at the row's end, such as the field; under the sides below `md`. */
+    meta?: ReactNode;
+    /** Hides `meta` below this breakpoint (`md` or `lg`), such as a field a phone leaves out. */
+    metaHideBelow?: VisibilityBreakpoint;
+    status?: FixtureStatus;
+    /** Makes the whole row a link to this address. */
+    href?: string;
+    /**
+     * Makes the whole row a button; with `href`, a plain press on the link
+     * (main button, no modifier) is handed here for a client router.
+     */
+    onPress?: (event: MouseEvent<HTMLElement>) => void;
+    /**
+     * The row's name when it is a link or a button, in the consumer's words
+     * ("Heron Marsh with Otter Pool, 8:00"); without it the
+     * name is what the row shows, in order.
+     */
+    'aria-label'?: string;
+};
+export type FixtureGroupProps = {
+    /** The run's caption, such as a date and a venue; it names the list. */
+    title: string;
+    /** The run's FixtureRows. */
+    children: ReactNode;
+};

package/dist/components/fixture/types.js

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

package/dist/components/fixture/validate.d.ts

@@ -0,0 +1,8 @@
+import { type FixtureRowProps } from './types.js';
+/**
+ * Fails closed on a row it cannot name or draw: a side without a name, a
+ * blank centre, an unknown centre kind or breakpoint, a status with blank
+ * words or an unknown tone, a blank address or `aria-label`, or an
+ * `aria-label` on a row that is neither a link nor a button.
+ */
+export declare function assertFixtureRow({ away, center, centerKind, home, href, metaHideBelow, onPress, status, 'aria-label': ariaLabel, }: FixtureRowProps): void;

package/dist/components/fixture/validate.js

@@ -0,0 +1,36 @@
+import { visibilityBreakpoints } from '../../css/breakpoints.js';
+import { badgeTones } from '../../css/css-data.js';
+import { fixtureCenterKinds } from '../../css/css-fixture.js';
+import { isOneOf } from '../../is-one-of.js';
+function isBlank(words) {
+    return typeof words !== 'string' || !words.trim();
+}
+/**
+ * Fails closed on a row it cannot name or draw: a side without a name, a
+ * blank centre, an unknown centre kind or breakpoint, a status with blank
+ * words or an unknown tone, a blank address or `aria-label`, or an
+ * `aria-label` on a row that is neither a link nor a button.
+ */
+export function assertFixtureRow({ away, center, centerKind, home, href, metaHideBelow, onPress, status, 'aria-label': ariaLabel, }) {
+    const name = 'FixtureRow';
+    if (isBlank(home?.name) || isBlank(away?.name))
+        throw new RangeError(`${name} home and away need nonempty names`);
+    if (isBlank(center))
+        throw new RangeError(`${name} center must be nonempty`);
+    if (centerKind !== undefined && !isOneOf(fixtureCenterKinds, centerKind))
+        throw new RangeError(`${name} centerKind must be one of ${fixtureCenterKinds.join(', ')}`);
+    if (metaHideBelow !== undefined &&
+        !isOneOf(visibilityBreakpoints, metaHideBelow))
+        throw new RangeError(`${name} metaHideBelow must be one of ${visibilityBreakpoints.join(', ')}`);
+    if (status !== undefined &&
+        (isBlank(status.label) || !isOneOf(badgeTones, status.tone)))
+        throw new RangeError(`${name} status needs a label and one of ${badgeTones.join(', ')}`);
+    if (href !== undefined && isBlank(href))
+        throw new RangeError(`${name} href must be nonempty when given`);
+    if (ariaLabel !== undefined) {
+        if (isBlank(ariaLabel))
+            throw new RangeError(`${name} aria-label must be nonempty when given`);
+        if (href === undefined && onPress === undefined)
+            throw new RangeError(`${name} aria-label names a link or a button: give it href or onPress`);
+    }
+}