@fikar-ai/design-react 1.5.0

package/dist/nav-item.d.ts

@@ -0,0 +1,20 @@
+import type { ComponentPropsWithoutRef, ElementType, ReactNode } from 'react';
+interface NavItemOwnProps {
+    icon?: ReactNode;
+    label: ReactNode;
+    /** Small pill at the right of the item. Hidden in the rail. */
+    badge?: ReactNode;
+    active?: boolean;
+    /** `back` is the link that leads out of this surface to where the person came from. It renders quieter and sits apart from the items below it. */
+    variant?: 'default' | 'back';
+}
+export type NavItemProps<C extends ElementType = 'a'> = NavItemOwnProps & {
+    /** The element or router link to render. It must forward its ref and accept a string className. */
+    component?: C;
+} & Omit<ComponentPropsWithoutRef<C>, keyof NavItemOwnProps | 'component' | 'className' | 'children'>;
+/** Renders a group heading between nav items. Clipped in the rail, still read by screen readers. */
+export declare function NavHeading({ children }: {
+    children: ReactNode;
+}): JSX.Element;
+export declare function NavItem<C extends ElementType = 'a'>({ icon, label, badge, active, variant, component, onClick, ...rest }: NavItemProps<C>): JSX.Element;
+export {};

package/dist/nav-item.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useContext } from 'react';
+import * as Tooltip from '@radix-ui/react-tooltip';
+import { AppShellContext } from './context.js';
+let warnedNavLink = false;
+/** Renders a group heading between nav items. Clipped in the rail, still read by screen readers. */
+export function NavHeading({ children }) {
+    return _jsx("div", { className: "nav-heading", children: children });
+}
+export function NavItem({ icon, label, badge, active = false, variant = 'default', component, onClick, ...rest }) {
+    const shell = useContext(AppShellContext);
+    const Component = component ?? 'a';
+    // NavLink sets its own active class and aria-current from the route, which fights the
+    // `active` prop and doubles the class. The displayName is only present in development builds.
+    if (!warnedNavLink && Component.displayName === 'NavLink') {
+        warnedNavLink = true;
+        console.warn('NavItem: pass the router Link as `component` and compute `active` in the app, not NavLink.');
+    }
+    const handleClick = (event) => {
+        onClick?.(event);
+        // A tapped link should not leave the drawer covering the page it opened.
+        if (!event.defaultPrevented)
+            shell?.setDrawerOpen(false);
+    };
+    // Always a plain string. Radix's asChild joins className into a string, so a
+    // router NavLink that receives a function here loses every class (KAN-311).
+    const link = (_jsxs(Component, { ...rest, className: ['nav-item', active && 'active', variant === 'back' && 'nav-item-back'].filter(Boolean).join(' '), "aria-current": active ? 'page' : undefined, onClick: handleClick, children: [icon, _jsx("span", { className: "nav-label", children: label }), badge ? _jsx("span", { className: "nav-badge", children: badge }) : null] }));
+    if (!shell?.isRail)
+        return link;
+    return (_jsxs(Tooltip.Root, { children: [_jsx(Tooltip.Trigger, { asChild: true, children: link }), _jsx(Tooltip.Portal, { children: _jsx(Tooltip.Content, { side: "right", sideOffset: 8, className: "fk-tooltip", children: label }) })] }));
+}

package/dist/relative-time.d.ts

@@ -0,0 +1,12 @@
+export interface RelativeTimeProps {
+    /** The moment, as a Date or an ISO string. Anything that is not a date renders nothing. */
+    date: Date | string;
+    /** The current time, for tests. When it is given the text is fixed and never refreshes. */
+    now?: Date;
+}
+/**
+ * A moment as "4 h ago", with the exact time in the title for a hover. Renders the <time> of recipes/time.html: `datetime` is the machine value and the
+ * text and title are formatRelative and formatExact. It refreshes itself while mounted, every 30 seconds under an hour, every 5 minutes under a day, and
+ * not at all once the text is an exact time. The title is a plain attribute and not a tooltip, so it needs no provider and costs nothing in a long list.
+ */
+export declare function RelativeTime({ date, now }: RelativeTimeProps): JSX.Element | null;

package/dist/relative-time.js

@@ -0,0 +1,35 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { formatExact, formatRelative } from './format-time.js';
+const HALF_MINUTE = 30000;
+const FIVE_MINUTES = 300000;
+const HOUR = 3600000;
+const DAY = 24 * HOUR;
+/** How long until the text may have changed, or undefined when it is written exactly and only a much later render would change it. Under an hour the text changes each minute, and under a day each hour. */
+function refreshAfter(distanceMs) {
+    if (distanceMs < HOUR)
+        return HALF_MINUTE;
+    if (distanceMs < DAY)
+        return FIVE_MINUTES;
+    return undefined;
+}
+/**
+ * A moment as "4 h ago", with the exact time in the title for a hover. Renders the <time> of recipes/time.html: `datetime` is the machine value and the
+ * text and title are formatRelative and formatExact. It refreshes itself while mounted, every 30 seconds under an hour, every 5 minutes under a day, and
+ * not at all once the text is an exact time. The title is a plain attribute and not a tooltip, so it needs no provider and costs nothing in a long list.
+ */
+export function RelativeTime({ date, now }) {
+    const [ticks, setTicks] = useState(0);
+    const clock = now ?? new Date();
+    const time = new Date(date).getTime();
+    const delay = now || Number.isNaN(time) ? undefined : refreshAfter(Math.abs(clock.getTime() - time));
+    useEffect(() => {
+        if (delay === undefined)
+            return;
+        const timer = setTimeout(() => setTicks((n) => n + 1), delay);
+        return () => clearTimeout(timer);
+    }, [delay, ticks]);
+    if (Number.isNaN(time))
+        return null;
+    return (_jsx("time", { className: "fk-time", dateTime: new Date(time).toISOString(), title: formatExact(date, clock), children: formatRelative(date, clock) }));
+}

package/dist/search-box.d.ts

@@ -0,0 +1,31 @@
+import type { InputHTMLAttributes, ReactNode } from 'react';
+type OwnProps = 'className' | 'children' | 'type' | 'size' | 'value' | 'onChange' | 'placeholder' | 'role' | 'aria-label' | 'aria-expanded' | 'aria-controls' | 'aria-activedescendant' | 'aria-autocomplete';
+export interface SearchBoxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, OwnProps> {
+    value: string;
+    onChange: (value: string) => void;
+    /** Required: the CSS shows the shortcut hint or the clear button from whether the placeholder is showing. */
+    placeholder: string;
+    /** The box has no visible label, so it needs one. */
+    'aria-label': string;
+    /** `'bar'` fills the top bar's start slot, `'panel'` fills a sidebar or panel. Defaults to `'bar'`. */
+    size?: 'bar' | 'panel';
+    /** The text of the trailing hint, such as "/" or "⌘K". The page says what it registered with useShortcut or data-fk-search. Without it there is no hint. */
+    shortcutHint?: string;
+    /** Renders the clear button. Called when it is pressed, after which focus goes back to the input. Usually `() => setValue('')`. */
+    onClear?: () => void;
+    /** The id of the results listbox, which makes the input a combobox. Give it the `id` of the `SearchResults` under this box. */
+    listboxId?: string;
+    /** Whether the results are showing. Only read with `listboxId`. */
+    expanded?: boolean;
+    /** The id of the active result row, which is the row's own `id`. Only read with `listboxId`. */
+    activeId?: string;
+    /** Put `SearchResults` here, so it is positioned by the box. */
+    children?: ReactNode;
+}
+/**
+ * The search box: a leading icon, the input, a clear button and a trailing shortcut hint. Renders recipes/search.html. The ref is the input's, for useShortcut.
+ * It never renders data-fk-search, because the component owns the behaviour and shell.js would otherwise bind it too.
+ * The clear button is there only when `onClear` is given, and the hint only when `shortcutHint` is.
+ */
+export declare const SearchBox: import("react").ForwardRefExoticComponent<SearchBoxProps & import("react").RefAttributes<HTMLInputElement>>;
+export {};

package/dist/search-box.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useImperativeHandle, useRef } from 'react';
+/**
+ * The search box: a leading icon, the input, a clear button and a trailing shortcut hint. Renders recipes/search.html. The ref is the input's, for useShortcut.
+ * It never renders data-fk-search, because the component owns the behaviour and shell.js would otherwise bind it too.
+ * The clear button is there only when `onClear` is given, and the hint only when `shortcutHint` is.
+ */
+export const SearchBox = forwardRef(function SearchBox({ value, onChange, placeholder, size = 'bar', shortcutHint, onClear, listboxId, expanded = false, activeId, children, 'aria-label': ariaLabel, ...input }, ref) {
+    const inner = useRef(null);
+    useImperativeHandle(ref, () => inner.current);
+    return (_jsxs("div", { className: size === 'panel' ? 'search search-panel' : 'search search-bar', children: [_jsxs("svg", { className: "search-icon", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: [_jsx("circle", { cx: "11", cy: "11", r: "8" }), _jsx("path", { d: "m21 21-4.3-4.3" })] }), _jsx("input", { ...input, ref: inner, className: "inp", type: "search", autoComplete: "off", value: value, placeholder: placeholder, "aria-label": ariaLabel, onChange: (event) => onChange(event.target.value), ...(listboxId
+                    ? { role: 'combobox', 'aria-expanded': expanded, 'aria-controls': listboxId, 'aria-autocomplete': 'list', 'aria-activedescendant': activeId }
+                    : {}) }), onClear ? (_jsx("button", { className: "search-clear", type: "button", "aria-label": "Clear search", onClick: () => {
+                    onClear();
+                    inner.current?.focus();
+                }, children: _jsx("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: _jsx("path", { d: "M18 6 6 18M6 6l12 12" }) }) })) : null, shortcutHint ? _jsx("kbd", { className: "search-kbd", children: shortcutHint }) : null, children] }));
+});

package/dist/search-results.d.ts

@@ -0,0 +1,39 @@
+import type { RefObject } from 'react';
+import type { EntityType } from './entity-badge.js';
+export interface SearchResultItem {
+    /** Becomes the row's DOM id, so it is unique on the page and is what `activeId` and the input's aria-activedescendant name. */
+    id: string;
+    title: string;
+    /** Shows the entity badge. Without it the row has none. */
+    type?: EntityType;
+    /** Shown after the badge, such as how many mentions there are. */
+    count?: number;
+    /** One line under the title, cut with an ellipsis. */
+    description?: string;
+}
+export interface SearchResultsProps {
+    /** The listbox's id. Pass the same string as `listboxId` on the `SearchBox` above it. */
+    id: string;
+    items: readonly SearchResultItem[];
+    /** The `id` of the active row, or undefined for none. The app keeps it. */
+    activeId?: string;
+    onActiveChange: (id: string) => void;
+    /** Called with the row that was clicked, or the active row when Enter is pressed. */
+    onSelect: (item: SearchResultItem) => void;
+    /** Called on Escape. The app hides the list. Focus never left the input, so it stays there. */
+    onClose: () => void;
+    /** The `SearchBox` ref. The keys are heard on the input, because focus stays in it. */
+    inputRef: RefObject<HTMLInputElement>;
+    /** What the list says when `items` is empty. */
+    emptyText: string;
+    /** Names the listbox. Defaults to "Results". */
+    'aria-label'?: string;
+}
+/**
+ * The results listbox under a SearchBox. Renders the .search-results panel of recipes/search-results.html. It is shown while it is mounted,
+ * so the app mounts it while the list is open. Focus stays in the input, and the active row is marked with
+ * aria-selected, which the SearchBox's aria-activedescendant names. While it is mounted the input's ArrowDown and ArrowUp move the active row and wrap,
+ * Enter selects it and Escape asks the app to close the list. That is not the roving focus of the menus, which moves focus onto the rows.
+ * A press on a row keeps focus in the input, so the box does not lose focus before the click lands.
+ */
+export declare function SearchResults({ id, items, activeId, onActiveChange, onSelect, onClose, inputRef, emptyText, 'aria-label': label }: SearchResultsProps): JSX.Element;

package/dist/search-results.js

@@ -0,0 +1,46 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect } from 'react';
+import { EntityBadge } from './entity-badge.js';
+/**
+ * The results listbox under a SearchBox. Renders the .search-results panel of recipes/search-results.html. It is shown while it is mounted,
+ * so the app mounts it while the list is open. Focus stays in the input, and the active row is marked with
+ * aria-selected, which the SearchBox's aria-activedescendant names. While it is mounted the input's ArrowDown and ArrowUp move the active row and wrap,
+ * Enter selects it and Escape asks the app to close the list. That is not the roving focus of the menus, which moves focus onto the rows.
+ * A press on a row keeps focus in the input, so the box does not lose focus before the click lands.
+ */
+export function SearchResults({ id, items, activeId, onActiveChange, onSelect, onClose, inputRef, emptyText, 'aria-label': label = 'Results' }) {
+    useEffect(() => {
+        const input = inputRef.current;
+        if (!input)
+            return;
+        const onKeyDown = (event) => {
+            if (event.isComposing)
+                return;
+            if (event.key === 'Escape') {
+                onClose();
+                return;
+            }
+            const at = items.findIndex((item) => item.id === activeId);
+            if (event.key === 'Enter') {
+                const active = items[at];
+                if (!active)
+                    return;
+                event.preventDefault();
+                onSelect(active);
+                return;
+            }
+            const next = { ArrowDown: at + 1, ArrowUp: at < 0 ? items.length - 1 : at - 1 }[event.key];
+            if (next === undefined || items.length === 0)
+                return;
+            event.preventDefault();
+            onActiveChange(items[(next + items.length) % items.length].id);
+        };
+        input.addEventListener('keydown', onKeyDown);
+        return () => input.removeEventListener('keydown', onKeyDown);
+    }, [inputRef, items, activeId, onActiveChange, onSelect, onClose]);
+    useEffect(() => {
+        if (activeId)
+            document.getElementById(activeId)?.scrollIntoView?.({ block: 'nearest' });
+    }, [activeId]);
+    return (_jsx("div", { className: "launcher-panel search-results", id: id, role: "listbox", "aria-label": label, onMouseDown: (event) => event.preventDefault(), children: items.length === 0 ? (_jsx("div", { className: "search-empty", role: "option", "aria-disabled": "true", "aria-selected": "false", children: emptyText })) : (items.map((item) => (_jsxs("div", { className: "search-row", id: item.id, role: "option", "aria-selected": item.id === activeId, onClick: () => onSelect(item), children: [_jsx("span", { className: "search-row-title", children: item.title }), item.type ? _jsx(EntityBadge, { type: item.type }) : null, item.count === undefined ? null : _jsx("span", { className: "search-row-meta", children: item.count }), item.description ? _jsx("span", { className: "search-row-desc", children: item.description }) : null] }, item.id)))) }));
+}

package/dist/status-badge.d.ts

@@ -0,0 +1,9 @@
+import type { ReactNode } from 'react';
+export interface StatusBadgeProps {
+    /** Sets the colour of the dot: `success`, `warning`, `destructive` or `muted`. The word is what says the status, so it is never left out. */
+    status: 'success' | 'warning' | 'destructive' | 'muted';
+    /** The status in one plain word, such as "Ready" or "Failed". */
+    children: ReactNode;
+}
+/** A dot in the status colour and the word, from recipes/status-badge.html. Renders a span. */
+export declare function StatusBadge({ status, children }: StatusBadgeProps): JSX.Element;

package/dist/status-badge.js

@@ -0,0 +1,5 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/** A dot in the status colour and the word, from recipes/status-badge.html. Renders a span. */
+export function StatusBadge({ status, children }) {
+    return _jsx("span", { className: `badge b-${status}`, children: children });
+}

package/dist/storage.d.ts

@@ -0,0 +1,3 @@
+/** Returns null when nothing usable is stored or storage is unavailable. */
+export declare function readCollapsed(): boolean | null;
+export declare function writeCollapsed(collapsed: boolean): void;

package/dist/storage.js

@@ -0,0 +1,26 @@
+// Same key and values as the plain-HTML contract in @fikar-ai/design, so a
+// person's choice is read the same way by every surface on one origin.
+const KEY = 'fikar.shell.collapsed';
+/** Returns null when nothing usable is stored or storage is unavailable. */
+export function readCollapsed() {
+    try {
+        const value = window.localStorage.getItem(KEY);
+        if (value === '1')
+            return true;
+        if (value === '0')
+            return false;
+        return null;
+    }
+    catch {
+        // Blocked or full storage only means the choice is not remembered.
+        return null;
+    }
+}
+export function writeCollapsed(collapsed) {
+    try {
+        window.localStorage.setItem(KEY, collapsed ? '1' : '0');
+    }
+    catch {
+        // Same as reading: losing persistence must never break the shell.
+    }
+}

package/dist/theme-menu.d.ts

@@ -0,0 +1,14 @@
+export type ThemeChoice = 'light' | 'dark' | 'system';
+export interface ThemeMenuProps {
+    /** The theme the app has now. The menu keeps no state of its own, so the chosen row follows this. */
+    value: ThemeChoice;
+    /** Called with the row the person chose, unless it is the one already chosen. The app applies and saves the theme in its own way. */
+    onChange: (value: ThemeChoice) => void;
+}
+/**
+ * The theme button and its panel of Light, Dark and System, for the second slot of the shell cluster. Renders recipes/theme-menu.html.
+ * Both icons are always rendered and the CSS shows the sun or the moon from the theme on the root, so it needs no script and no theme prop.
+ * Opens on click and closes on Escape (focus returns to the button), on a press outside and on choosing a row, which also returns focus to the button.
+ * Arrow keys, Home and End move between rows.
+ */
+export declare function ThemeMenu({ value, onChange }: ThemeMenuProps): JSX.Element;

package/dist/theme-menu.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMenu } from './use-menu.js';
+const CHOICES = [
+    { value: 'light', label: 'Light' },
+    { value: 'dark', label: 'Dark' },
+    { value: 'system', label: 'System' },
+];
+/**
+ * The theme button and its panel of Light, Dark and System, for the second slot of the shell cluster. Renders recipes/theme-menu.html.
+ * Both icons are always rendered and the CSS shows the sun or the moon from the theme on the root, so it needs no script and no theme prop.
+ * Opens on click and closes on Escape (focus returns to the button), on a press outside and on choosing a row, which also returns focus to the button.
+ * Arrow keys, Home and End move between rows.
+ */
+export function ThemeMenu({ value, onChange }) {
+    const { open, toggle, root, trigger, rootClassName, moveFocus, closeOnFocusLeave, closeOnRow } = useMenu();
+    return (_jsxs("div", { ref: root, className: rootClassName, onKeyDown: moveFocus, onBlur: closeOnFocusLeave, children: [_jsxs("button", { ref: trigger, className: "launcher-btn theme-menu-btn", type: "button", "aria-haspopup": "menu", "aria-expanded": open, "aria-label": "Choose theme", onClick: toggle, children: [_jsxs("svg", { className: "theme-icon-sun", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: [_jsx("circle", { cx: "12", cy: "12", r: "4" }), _jsx("path", { d: "M12 2v2M12 20v2M4.93 4.93l1.41 1.41M17.66 17.66l1.41 1.41M2 12h2M20 12h2M6.34 17.66l-1.41 1.41M19.07 4.93l-1.41 1.41" })] }), _jsx("svg", { className: "theme-icon-moon", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: _jsx("path", { d: "M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z" }) })] }), _jsx("div", { className: "launcher-panel theme-menu-panel", role: "menu", "aria-label": "Theme", onClick: closeOnRow, children: CHOICES.map((choice) => {
+                    const chosen = choice.value === value;
+                    return (_jsx("button", { className: chosen ? 'launcher-item theme-menu-item current' : 'launcher-item theme-menu-item', type: "button", role: "menuitemradio", "aria-checked": chosen, "data-value": choice.value, onClick: () => {
+                            if (!chosen)
+                                onChange(choice.value);
+                        }, children: choice.label }, choice.value));
+                }) })] }));
+}

package/dist/use-menu.d.ts

@@ -0,0 +1,24 @@
+import type { FocusEvent, KeyboardEvent, MouseEvent, RefObject } from 'react';
+export interface MenuState {
+    open: boolean;
+    toggle: () => void;
+    root: RefObject<HTMLDivElement>;
+    trigger: RefObject<HTMLButtonElement>;
+    /** The class of the `.launcher` root, with `.open` while the panel shows. */
+    rootClassName: string;
+    /** For the root's onKeyDown: arrow keys, Home and End move focus between the rows. */
+    moveFocus: (event: KeyboardEvent<HTMLDivElement>) => void;
+    /** For the root's onBlur: focus moving to an element outside the menu closes it, so tabbing away or to another menu's trigger leaves one panel open. */
+    closeOnFocusLeave: (event: FocusEvent<HTMLDivElement>) => void;
+    /** For the panel's onClick: choosing a row closes the panel. */
+    closeOnRow: (event: MouseEvent<HTMLDivElement>) => void;
+}
+/**
+ * The open and close behaviour that the launcher, the theme menu and the user menu share, in the same terms as shell.js.
+ * A click on the trigger toggles it. Escape closes it and returns focus to the trigger, a press outside closes it, and a
+ * chosen row closes it. Focus moving to an element outside the menu closes it too, so tabbing to another menu's trigger and
+ * pressing Enter leaves one panel open, as a trigger click does in shell.js. A blur with no target (a click on the panel's
+ * padding, the window losing focus) does not close it. Another menu's press outside is what closes this one when that menu opens.
+ * The document listeners exist only while the panel is open. Not exported from the package.
+ */
+export declare function useMenu(): MenuState;

package/dist/use-menu.js

@@ -0,0 +1,71 @@
+import { useEffect, useRef, useState } from 'react';
+const ROWS = '[role="menuitem"], [role="menuitemradio"]';
+/**
+ * The open and close behaviour that the launcher, the theme menu and the user menu share, in the same terms as shell.js.
+ * A click on the trigger toggles it. Escape closes it and returns focus to the trigger, a press outside closes it, and a
+ * chosen row closes it. Focus moving to an element outside the menu closes it too, so tabbing to another menu's trigger and
+ * pressing Enter leaves one panel open, as a trigger click does in shell.js. A blur with no target (a click on the panel's
+ * padding, the window losing focus) does not close it. Another menu's press outside is what closes this one when that menu opens.
+ * The document listeners exist only while the panel is open. Not exported from the package.
+ */
+export function useMenu() {
+    const [open, setOpen] = useState(false);
+    const root = useRef(null);
+    const trigger = useRef(null);
+    useEffect(() => {
+        if (!open)
+            return;
+        const onPointerDown = (event) => {
+            if (!root.current?.contains(event.target))
+                setOpen(false);
+        };
+        const onKeyDown = (event) => {
+            if (event.key !== 'Escape')
+                return;
+            setOpen(false);
+            trigger.current?.focus();
+        };
+        document.addEventListener('pointerdown', onPointerDown);
+        document.addEventListener('keydown', onKeyDown);
+        return () => {
+            document.removeEventListener('pointerdown', onPointerDown);
+            document.removeEventListener('keydown', onKeyDown);
+        };
+    }, [open]);
+    const moveFocus = (event) => {
+        if (!open || !root.current)
+            return;
+        const rows = Array.from(root.current.querySelectorAll(ROWS));
+        const at = rows.indexOf(document.activeElement);
+        const next = { ArrowDown: at + 1, ArrowUp: at < 0 ? rows.length - 1 : at - 1, Home: 0, End: rows.length - 1 }[event.key];
+        if (next === undefined || rows.length === 0)
+            return;
+        event.preventDefault();
+        rows[(next + rows.length) % rows.length].focus();
+    };
+    const closeOnFocusLeave = (event) => {
+        const next = event.relatedTarget;
+        if (next && !event.currentTarget.contains(next))
+            setOpen(false);
+    };
+    // Focus stays with whatever the row does (a link navigates, a button acts). A radio row acts on the menu itself and is hidden once it
+    // closes, so focus goes back to the trigger.
+    const closeOnRow = (event) => {
+        const row = event.target.closest(ROWS);
+        if (!row)
+            return;
+        setOpen(false);
+        if (row.getAttribute('role') === 'menuitemradio')
+            trigger.current?.focus();
+    };
+    return {
+        open,
+        toggle: () => setOpen((wasOpen) => !wasOpen),
+        root,
+        trigger,
+        rootClassName: open ? 'launcher open' : 'launcher',
+        moveFocus,
+        closeOnFocusLeave,
+        closeOnRow,
+    };
+}

package/dist/use-shortcut.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Runs `handler` when one of the key combos is pressed, the same way shell.js binds / and Cmd-K for a plain page. Combos are "/" or "mod+k", and `keys` is one or a list.
+ * The hook calls preventDefault, so a "/" is not typed into the box the handler has just focused. A combo with no "mod" is ignored while
+ * the person is typing in an input, a textarea, a select or an editable element, and one with "mod" works from anywhere. A key already handled
+ * elsewhere and one pressed in the middle of an IME composition are ignored. The latest handler is always the one called.
+ */
+export declare function useShortcut(keys: string | readonly string[], handler: () => void): void;

package/dist/use-shortcut.js

@@ -0,0 +1,43 @@
+import { useEffect, useRef } from 'react';
+const TYPING = /^(INPUT|TEXTAREA|SELECT)$/;
+function isTyping(target) {
+    const node = target;
+    return !!node && (TYPING.test(node.tagName) || node.isContentEditable === true);
+}
+// A combo is a key, optionally after "mod+". "mod" is Cmd or Ctrl, as shell.js accepts both on every platform. Alt never matches.
+function parse(combo) {
+    const parts = combo.toLowerCase().split('+');
+    const key = parts.pop();
+    return { key, mod: parts.includes('mod') };
+}
+function matches({ key, mod }, event) {
+    return !event.altKey && mod === (event.metaKey || event.ctrlKey) && event.key.toLowerCase() === key;
+}
+/**
+ * Runs `handler` when one of the key combos is pressed, the same way shell.js binds / and Cmd-K for a plain page. Combos are "/" or "mod+k", and `keys` is one or a list.
+ * The hook calls preventDefault, so a "/" is not typed into the box the handler has just focused. A combo with no "mod" is ignored while
+ * the person is typing in an input, a textarea, a select or an editable element, and one with "mod" works from anywhere. A key already handled
+ * elsewhere and one pressed in the middle of an IME composition are ignored. The latest handler is always the one called.
+ */
+export function useShortcut(keys, handler) {
+    const latest = useRef(handler);
+    useEffect(() => {
+        latest.current = handler;
+    });
+    const spec = typeof keys === 'string' ? keys : keys.join(',');
+    useEffect(() => {
+        const combos = (typeof keys === 'string' ? [keys] : keys).map(parse);
+        const onKeyDown = (event) => {
+            if (event.defaultPrevented || event.isComposing)
+                return;
+            const combo = combos.find((one) => matches(one, event));
+            if (!combo || (!combo.mod && isTyping(event.target)))
+                return;
+            event.preventDefault();
+            latest.current();
+        };
+        document.addEventListener('keydown', onKeyDown);
+        return () => document.removeEventListener('keydown', onKeyDown);
+        // `spec` stands for `keys`: an inline array is a new object on every render, and its contents are what matter.
+    }, [spec]);
+}

package/dist/user-initials.d.ts

@@ -0,0 +1,8 @@
+/** The words of a name, split on any whitespace. Extra spaces and an empty or missing name give no words. */
+export declare function nameWords(name: string | null | undefined): string[];
+/**
+ * The initials every surface shows: the first letter of the first word of the name and of the last word, upper
+ * case. One word gives one letter. With no name it is the first letter of the email. Same rule as the
+ * `user_initials` Jinja macro.
+ */
+export declare function userInitials(name: string | null | undefined, email: string | null | undefined): string;

package/dist/user-initials.js

@@ -0,0 +1,18 @@
+/** The words of a name, split on any whitespace. Extra spaces and an empty or missing name give no words. */
+export function nameWords(name) {
+    return (name ?? '').split(/\s+/).filter(Boolean);
+}
+// Array.from walks code points, so a letter outside the basic plane is not cut in half.
+const firstLetter = (text) => Array.from(text)[0] ?? '';
+/**
+ * The initials every surface shows: the first letter of the first word of the name and of the last word, upper
+ * case. One word gives one letter. With no name it is the first letter of the email. Same rule as the
+ * `user_initials` Jinja macro.
+ */
+export function userInitials(name, email) {
+    const words = nameWords(name);
+    if (words.length === 0)
+        return firstLetter(email ?? '').toUpperCase();
+    const ends = words.length === 1 ? words : [words[0], words[words.length - 1]];
+    return ends.map(firstLetter).join('').toUpperCase();
+}

package/dist/user-menu.d.ts

@@ -0,0 +1,36 @@
+import type { ComponentPropsWithoutRef, ElementType, ReactNode } from 'react';
+/** The props of one link row, as NavItem takes them: `{ href }`, or `{ component: Link, to }`. The element or router link must forward its ref and accept a string className. Pass the router's `Link`, never `NavLink`. */
+export type UserMenuLinkProps<C extends ElementType = 'a'> = {
+    component?: C;
+} & Omit<ComponentPropsWithoutRef<C>, 'component' | 'className' | 'children'>;
+export type UserMenuItemProps<C extends ElementType = 'a'> = UserMenuLinkProps<C> & {
+    children: ReactNode;
+};
+/** One row of the user menu, for the app's own items. Renders a link, or the router link passed as `component`. */
+export declare function UserMenuItem<C extends ElementType = 'a'>({ component, children, ...rest }: UserMenuItemProps<C>): JSX.Element;
+/** Where Sign out goes: an address, or a handler for an app that clears local state first. Exactly one. */
+export type UserMenuSignOut = {
+    href: string;
+    onSelect?: never;
+} | {
+    onSelect: () => void;
+    href?: never;
+};
+export interface UserMenuProps<C extends ElementType = 'a'> {
+    email: string;
+    /** Full name. Without it the panel shows the email once and the initials come from the email. */
+    name?: string | null;
+    /** Picture. Without it, or when it fails to load, the avatar shows the initials on blue. */
+    avatarUrl?: string | null;
+    /** The Account settings row. Leave it out and the row is not rendered, for the page that would link to itself. */
+    accountSettings?: UserMenuLinkProps<C>;
+    signOut: UserMenuSignOut;
+    /** The app's own rows, as UserMenuItem elements. They render after Account settings and before Sign out. */
+    children?: ReactNode;
+}
+/**
+ * The avatar and account panel for the last slot of the shell cluster. Renders recipes/user-menu.html.
+ * Opens on click, and closes on Escape (focus returns to the avatar), on a press outside and on choosing a row.
+ * Arrow keys, Home and End move between rows. Because it closes on an outside press, opening another menu closes it.
+ */
+export declare function UserMenu<C extends ElementType = 'a'>({ email, name, avatarUrl, accountSettings, signOut, children }: UserMenuProps<C>): JSX.Element;

package/dist/user-menu.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Children, useState } from 'react';
+import { useMenu } from './use-menu.js';
+import { nameWords, userInitials } from './user-initials.js';
+/** One row of the user menu, for the app's own items. Renders a link, or the router link passed as `component`. */
+export function UserMenuItem({ component, children, ...rest }) {
+    const Component = component ?? 'a';
+    return (_jsx(Component, { ...rest, className: "launcher-item user-menu-item", role: "menuitem", children: children }));
+}
+/**
+ * The avatar and account panel for the last slot of the shell cluster. Renders recipes/user-menu.html.
+ * Opens on click, and closes on Escape (focus returns to the avatar), on a press outside and on choosing a row.
+ * Arrow keys, Home and End move between rows. Because it closes on an outside press, opening another menu closes it.
+ */
+export function UserMenu({ email, name, avatarUrl, accountSettings, signOut, children }) {
+    const { open, toggle, root, trigger, rootClassName, moveFocus, closeOnFocusLeave, closeOnRow } = useMenu();
+    // Keyed by address so a new avatarUrl gets a fresh try after an earlier one failed.
+    const [failedUrl, setFailedUrl] = useState(null);
+    const fullName = nameWords(name).join(' ');
+    const initials = userInitials(name, email);
+    const hasRowsBeforeSignOut = accountSettings !== undefined || Children.toArray(children).length > 0;
+    return (_jsxs("div", { ref: root, className: rootClassName, onKeyDown: moveFocus, onBlur: closeOnFocusLeave, children: [_jsx("button", { ref: trigger, className: "user-menu-btn", type: "button", "aria-haspopup": "menu", "aria-expanded": open, "aria-label": "Open account menu", "data-initials": initials, onClick: toggle, children: avatarUrl && failedUrl !== avatarUrl ? (_jsx("img", { className: "avatar", src: avatarUrl, alt: "", onError: () => setFailedUrl(avatarUrl) })) : (_jsx("span", { className: "avatar", "aria-hidden": "true", children: initials })) }), _jsxs("div", { className: "launcher-panel user-menu-panel", role: "menu", onClick: closeOnRow, children: [_jsxs("div", { className: "user-menu-id", children: [_jsx("span", { className: "user-menu-name", children: fullName || email }), fullName ? _jsx("span", { className: "user-menu-email", children: email }) : null] }), _jsx("div", { className: "user-menu-sep", role: "separator" }), accountSettings ? _jsx(UserMenuItem, { ...accountSettings, children: "Account settings" }) : null, children, hasRowsBeforeSignOut ? _jsx("div", { className: "user-menu-sep", role: "separator" }) : null, signOut.onSelect ? (_jsx("button", { className: "launcher-item user-menu-item", type: "button", role: "menuitem", onClick: signOut.onSelect, children: "Sign out" })) : (_jsx("a", { className: "launcher-item user-menu-item", role: "menuitem", href: signOut.href, children: "Sign out" }))] })] }));
+}