@fgv/ts-app-shell 5.1.0-1

package/dist/packlets/editing/MultiActionButton.js

@@ -0,0 +1,73 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+/**
+ * Multi-action button component with dropdown for alternative actions.
+ * @packageDocumentation
+ */
+import React, { useState, useRef, useEffect } from 'react';
+import { ChevronDownIcon } from '@heroicons/react/20/solid';
+// ============================================================================
+// Component
+// ============================================================================
+/**
+ * Multi-action button with dropdown for alternative actions.
+ * Similar to Git commit button with "Commit", "Commit & Push", etc.
+ *
+ * @public
+ */
+export function MultiActionButton(props) {
+    const { primaryAction, alternativeActions, variant = 'primary', disabled = false, dropdownDisabled, className = '' } = props;
+    const isDropdownDisabled = dropdownDisabled !== null && dropdownDisabled !== void 0 ? dropdownDisabled : disabled;
+    const [isOpen, setIsOpen] = useState(false);
+    const dropdownRef = useRef(null);
+    // Close dropdown when clicking outside
+    useEffect(() => {
+        const handleClickOutside = (event) => {
+            if (dropdownRef.current && !dropdownRef.current.contains(event.target)) {
+                setIsOpen(false);
+            }
+        };
+        if (isOpen) {
+            document.addEventListener('mousedown', handleClickOutside);
+            return () => document.removeEventListener('mousedown', handleClickOutside);
+        }
+    }, [isOpen]);
+    const variantClasses = {
+        primary: 'bg-brand-primary hover:bg-brand-primary/90 text-white',
+        default: 'bg-surface-raised hover:bg-surface-raised text-secondary',
+        danger: 'bg-status-error-btn hover:bg-status-error-btn-hover text-white'
+    };
+    const baseClasses = 'inline-flex items-center text-xs font-medium rounded transition-colors disabled:opacity-40 disabled:cursor-not-allowed';
+    return (React.createElement("div", { className: `relative inline-flex ${className}`, ref: dropdownRef },
+        React.createElement("button", { type: "button", onClick: primaryAction.onSelect, disabled: disabled, className: `${baseClasses} ${variantClasses[variant]} px-2.5 py-1 ${alternativeActions.length > 0 ? 'rounded-r-none' : 'rounded'}` },
+            primaryAction.icon,
+            React.createElement("span", null, primaryAction.label)),
+        alternativeActions.length > 0 && (React.createElement("button", { type: "button", onClick: () => setIsOpen(!isOpen), disabled: isDropdownDisabled, className: `${baseClasses} ${variantClasses[variant]} px-1 py-1 rounded-l-none border-l border-white/20` },
+            React.createElement(ChevronDownIcon, { className: "h-3.5 w-3.5" }))),
+        isOpen && alternativeActions.length > 0 && (React.createElement("div", { className: "absolute top-full right-0 mt-1 w-48 bg-surface rounded-md shadow-lg border border-border py-1 z-50" }, alternativeActions.map((action) => (React.createElement("button", { key: action.id, type: "button", onClick: () => {
+                action.onSelect();
+                setIsOpen(false);
+            }, className: "w-full text-left px-3 py-2 text-xs text-secondary hover:bg-surface-raised flex items-center gap-2" },
+            action.icon,
+            React.createElement("span", null, action.label))))))));
+}
+//# sourceMappingURL=MultiActionButton.js.map

package/dist/packlets/editing/NumericInput.js

@@ -0,0 +1,119 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+/**
+ * Numeric input with select-all-on-focus and empty-string support.
+ *
+ * Uses `type="text"` with `inputMode="decimal"` to avoid native number-input
+ * quirks (spinner buttons, empty-string rejection). Manages a string internally
+ * but exposes `number | undefined` to callers.
+ *
+ * @packageDocumentation
+ */
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+// ============================================================================
+// Constants
+// ============================================================================
+const NUMERIC_PATTERN = /^-?\d*\.?\d*$/;
+const DEFAULT_CLASS = 'text-sm border border-border rounded-md px-3 py-2 focus:outline-none focus:ring-2 focus:ring-focus-ring focus:border-focus-ring';
+// ============================================================================
+// Helpers
+// ============================================================================
+function formatValue(value) {
+    return value !== undefined ? String(value) : '';
+}
+function clamp(value, min, max) {
+    let result = value;
+    if (min !== undefined && result < min) {
+        result = min;
+    }
+    if (max !== undefined && result > max) {
+        result = max;
+    }
+    return result;
+}
+// ============================================================================
+// Component
+// ============================================================================
+/**
+ * Numeric input that selects all on focus and allows empty values.
+ *
+ * Internally manages a string so the user can freely type, backspace to empty,
+ * and replace the entire value. On blur, the string is parsed to a number
+ * (clamped to min/max) and reported to the parent via `onChange`.
+ *
+ * @public
+ */
+export function NumericInput(props) {
+    const { value, onChange, label, min, max, step, className, placeholder, autoFocus, disabled } = props;
+    const [displayValue, setDisplayValue] = useState(() => formatValue(value));
+    const focusedRef = useRef(false);
+    // Sync display when value prop changes externally (but not while focused)
+    useEffect(() => {
+        if (!focusedRef.current) {
+            setDisplayValue(formatValue(value));
+        }
+    }, [value]);
+    const handleFocus = useCallback((e) => {
+        focusedRef.current = true;
+        e.target.select();
+    }, []);
+    const handleChange = useCallback((e) => {
+        const raw = e.target.value;
+        if (raw === '' || NUMERIC_PATTERN.test(raw)) {
+            setDisplayValue(raw);
+        }
+    }, []);
+    const handleBlur = useCallback(() => {
+        focusedRef.current = false;
+        const trimmed = displayValue.trim();
+        if (trimmed === '' || trimmed === '-' || trimmed === '.') {
+            setDisplayValue('');
+            onChange(undefined);
+            return;
+        }
+        const parsed = parseFloat(trimmed);
+        if (isNaN(parsed)) {
+            setDisplayValue('');
+            onChange(undefined);
+            return;
+        }
+        const clamped = clamp(parsed, min, max);
+        setDisplayValue(String(clamped));
+        onChange(clamped);
+    }, [displayValue, onChange, min, max]);
+    const handleKeyDown = useCallback((e) => {
+        if (e.key !== 'ArrowUp' && e.key !== 'ArrowDown') {
+            return;
+        }
+        e.preventDefault();
+        const effectiveStep = step !== null && step !== void 0 ? step : 1;
+        const current = parseFloat(displayValue) || 0;
+        const next = e.key === 'ArrowUp' ? current + effectiveStep : current - effectiveStep;
+        const clamped = clamp(next, min, max);
+        // Round to avoid floating-point drift
+        const rounded = parseFloat(clamped.toFixed(10));
+        setDisplayValue(String(rounded));
+        onChange(rounded);
+    }, [displayValue, onChange, min, max, step]);
+    return (React.createElement("input", { type: "text", inputMode: "decimal", value: displayValue, onChange: handleChange, onFocus: handleFocus, onBlur: handleBlur, onKeyDown: handleKeyDown, className: className !== null && className !== void 0 ? className : DEFAULT_CLASS, "aria-label": label, placeholder: placeholder, autoFocus: autoFocus, disabled: disabled }));
+}
+//# sourceMappingURL=NumericInput.js.map

package/dist/packlets/editing/TypeaheadInput.js

@@ -0,0 +1,207 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+/**
+ * TypeaheadInput — text input with custom autocomplete dropdown supporting
+ * tiered suggestions and built-in blur resolution.
+ * @packageDocumentation
+ */
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useTypeaheadMatch } from './useTypeaheadMatch';
+// ============================================================================
+// Component
+// ============================================================================
+/**
+ * Text input with a custom autocomplete dropdown supporting tiered suggestions.
+ *
+ * Priority suggestions (e.g. recipe alternates) appear first, visually separated
+ * from the full catalog. On blur, applies resolution logic: exact match → auto-select,
+ * single partial match → auto-select, else fires `onUnresolved`.
+ *
+ * @public
+ */
+export function TypeaheadInput(props) {
+    const { value, onChange, suggestions, prioritySuggestions, onSelect, onUnresolved, placeholder, className, disabled, maxHeight = 240, autoFocus } = props;
+    const [isOpen, setIsOpen] = useState(false);
+    const [focusIndex, setFocusIndex] = useState(-1);
+    const inputRef = useRef(null);
+    const dropdownRef = useRef(null);
+    const itemRefs = useRef([]);
+    const mouseDownOnDropdownRef = useRef(false);
+    const matcher = useTypeaheadMatch(suggestions, prioritySuggestions);
+    // ---- Filtered suggestions ----
+    const filtered = useMemo(() => matcher.filterSuggestions(value), [matcher, value]);
+    const flatItems = useMemo(() => [...filtered.priority, ...filtered.catalog], [filtered.priority, filtered.catalog]);
+    const hasPriorityItems = filtered.priority.length > 0;
+    const hasCatalogItems = filtered.catalog.length > 0;
+    const hasItems = flatItems.length > 0;
+    // Reset focus index when suggestions change
+    useEffect(() => {
+        setFocusIndex(-1);
+    }, [value]);
+    // Scroll focused item into view
+    useEffect(() => {
+        var _a;
+        if (isOpen && focusIndex >= 0 && itemRefs.current[focusIndex]) {
+            (_a = itemRefs.current[focusIndex]) === null || _a === void 0 ? void 0 : _a.scrollIntoView({ block: 'nearest' });
+        }
+    }, [isOpen, focusIndex]);
+    // Close dropdown on outside click
+    useEffect(() => {
+        if (!isOpen)
+            return;
+        const handler = (e) => {
+            if (dropdownRef.current &&
+                !dropdownRef.current.contains(e.target) &&
+                inputRef.current &&
+                !inputRef.current.contains(e.target)) {
+                setIsOpen(false);
+            }
+        };
+        document.addEventListener('mousedown', handler);
+        return () => {
+            document.removeEventListener('mousedown', handler);
+        };
+    }, [isOpen]);
+    // ---- Selection ----
+    const handleSelect = useCallback((item) => {
+        onSelect(item);
+        setIsOpen(false);
+        setFocusIndex(-1);
+    }, [onSelect]);
+    const handleResolve = useCallback((text) => {
+        const trimmed = text.trim();
+        if (!trimmed) {
+            setIsOpen(false);
+            return;
+        }
+        const match = matcher.resolveOnBlur(trimmed);
+        if (match) {
+            handleSelect(match);
+        }
+        else if (onUnresolved) {
+            onUnresolved(trimmed);
+            setIsOpen(false);
+        }
+        else {
+            setIsOpen(false);
+        }
+    }, [matcher, handleSelect, onUnresolved]);
+    // ---- Input handlers ----
+    const handleChange = useCallback((e) => {
+        onChange(e.target.value);
+        if (!isOpen) {
+            setIsOpen(true);
+        }
+    }, [onChange, isOpen]);
+    const handleFocus = useCallback(() => {
+        var _a;
+        (_a = inputRef.current) === null || _a === void 0 ? void 0 : _a.select();
+        if (hasItems) {
+            setIsOpen(true);
+        }
+    }, [hasItems]);
+    const handleBlur = useCallback(() => {
+        // Guard: don't resolve if user is clicking an item in the dropdown
+        if (mouseDownOnDropdownRef.current) {
+            mouseDownOnDropdownRef.current = false;
+            return;
+        }
+        handleResolve(value);
+    }, [value, handleResolve]);
+    const handleKeyDown = useCallback((e) => {
+        if (!isOpen) {
+            if (e.key === 'ArrowDown' && hasItems) {
+                e.preventDefault();
+                setIsOpen(true);
+                setFocusIndex(0);
+            }
+            return;
+        }
+        switch (e.key) {
+            case 'Escape': {
+                e.preventDefault();
+                e.stopPropagation();
+                setIsOpen(false);
+                setFocusIndex(-1);
+                break;
+            }
+            case 'ArrowDown': {
+                e.preventDefault();
+                setFocusIndex((prev) => (prev < flatItems.length - 1 ? prev + 1 : 0));
+                break;
+            }
+            case 'ArrowUp': {
+                e.preventDefault();
+                setFocusIndex((prev) => (prev > 0 ? prev - 1 : flatItems.length - 1));
+                break;
+            }
+            case 'Enter': {
+                e.preventDefault();
+                if (focusIndex >= 0 && focusIndex < flatItems.length) {
+                    handleSelect(flatItems[focusIndex]);
+                }
+                else {
+                    handleResolve(value);
+                }
+                break;
+            }
+            case 'Tab': {
+                // Allow default tab behavior but resolve first
+                handleResolve(value);
+                break;
+            }
+            default:
+                break;
+        }
+    }, [isOpen, hasItems, flatItems, focusIndex, handleSelect, handleResolve, value]);
+    // ---- Dropdown mouse guard ----
+    const handleDropdownMouseDown = useCallback(() => {
+        mouseDownOnDropdownRef.current = true;
+    }, []);
+    // ---- Render ----
+    const priorityEndIndex = filtered.priority.length;
+    return (React.createElement("div", { className: "relative" },
+        React.createElement("input", { ref: inputRef, type: "text", value: value, onChange: handleChange, onFocus: handleFocus, onBlur: handleBlur, onKeyDown: handleKeyDown, placeholder: placeholder, disabled: disabled, autoFocus: autoFocus, className: className !== null && className !== void 0 ? className : 'w-full px-2 py-1 text-sm border border-border rounded focus:outline-none focus:ring-1 focus:ring-focus-ring focus:border-focus-ring', role: "combobox", "aria-expanded": isOpen, "aria-autocomplete": "list", autoComplete: "off" }),
+        isOpen && hasItems && (React.createElement("div", { ref: dropdownRef, className: "absolute z-50 mt-1 w-full bg-surface border border-border rounded-lg shadow-lg overflow-hidden", style: { maxHeight }, role: "listbox", onMouseDown: handleDropdownMouseDown },
+            React.createElement("div", { className: "overflow-y-auto", style: { maxHeight } },
+                hasPriorityItems &&
+                    filtered.priority.map((item, index) => {
+                        const isFocused = index === focusIndex;
+                        return (React.createElement("button", { key: item.id, ref: (el) => {
+                                itemRefs.current[index] = el;
+                            }, role: "option", "aria-selected": isFocused, onClick: () => handleSelect(item), className: `flex items-center w-full px-2.5 py-1.5 text-left text-sm transition-colors border-l-2 ${isFocused
+                                ? 'bg-surface-alt text-primary border-brand-primary/50'
+                                : 'text-secondary hover:bg-hover border-brand-primary/20'}` },
+                            React.createElement("span", { className: "flex-1 min-w-0 truncate" }, item.name)));
+                    }),
+                hasPriorityItems && hasCatalogItems && React.createElement("div", { className: "border-t border-border my-0.5" }),
+                hasCatalogItems &&
+                    filtered.catalog.map((item, catalogIndex) => {
+                        const flatIndex = priorityEndIndex + catalogIndex;
+                        const isFocused = flatIndex === focusIndex;
+                        return (React.createElement("button", { key: item.id, ref: (el) => {
+                                itemRefs.current[flatIndex] = el;
+                            }, role: "option", "aria-selected": isFocused, onClick: () => handleSelect(item), className: `flex items-center w-full px-2.5 py-1.5 text-left text-sm transition-colors ${isFocused ? 'bg-surface-alt text-primary' : 'text-secondary hover:bg-hover'}` },
+                            React.createElement("span", { className: "flex-1 min-w-0 truncate" }, item.name)));
+                    }))))));
+}
+//# sourceMappingURL=TypeaheadInput.js.map

package/dist/packlets/editing/index.js

@@ -0,0 +1,10 @@
+/**
+ * Editing packlet - generic form field primitives for entity editors.
+ * @packageDocumentation
+ */
+export { EditField, EditSection, TextInput, OptionalTextInput, TextAreaInput, NumberInput, SelectInput, TagsInput, CheckboxInput } from './EditFieldHelpers';
+export { MultiActionButton } from './MultiActionButton';
+export { NumericInput } from './NumericInput';
+export { TypeaheadInput } from './TypeaheadInput';
+export { useTypeaheadMatch } from './useTypeaheadMatch';
+//# sourceMappingURL=index.js.map

package/dist/packlets/editing/useTypeaheadMatch.js

@@ -0,0 +1,102 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+/**
+ * Reusable typeahead matching hook with tiered priority support.
+ * @packageDocumentation
+ */
+import { useCallback, useMemo } from 'react';
+// ============================================================================
+// Hook
+// ============================================================================
+/**
+ * Hook that provides typeahead matching and filtering with tiered priority support.
+ *
+ * `findExactMatch` matches by exact id or case-insensitive name (checks priority first).
+ * `resolveOnBlur` tries exact match, then single partial match (priority first).
+ * `filterSuggestions` returns suggestions split by tier, filtered by substring match.
+ *
+ * @param suggestions - The full catalog of suggestions
+ * @param prioritySuggestions - Optional priority suggestions shown first (e.g. recipe alternates)
+ * @returns Match and filter functions
+ * @public
+ */
+export function useTypeaheadMatch(suggestions, prioritySuggestions) {
+    // Pre-compute priority IDs for efficient catalog deduplication
+    const priorityIds = useMemo(() => { var _a; return new Set((_a = prioritySuggestions === null || prioritySuggestions === void 0 ? void 0 : prioritySuggestions.map((s) => s.id)) !== null && _a !== void 0 ? _a : []); }, [prioritySuggestions]);
+    const findExactMatch = useCallback((input) => {
+        const trimmed = input.trim();
+        if (!trimmed)
+            return undefined;
+        const lower = trimmed.toLowerCase();
+        if (prioritySuggestions) {
+            const match = prioritySuggestions.find((s) => s.id === trimmed || s.name.toLowerCase() === lower);
+            if (match)
+                return match;
+        }
+        return suggestions.find((s) => s.id === trimmed || s.name.toLowerCase() === lower);
+    }, [suggestions, prioritySuggestions]);
+    const resolveOnBlur = useCallback((input) => {
+        const trimmed = input.trim();
+        if (!trimmed)
+            return undefined;
+        const lower = trimmed.toLowerCase();
+        // Try exact match (priority first, then all)
+        if (prioritySuggestions) {
+            const priorityExact = prioritySuggestions.find((s) => s.id === trimmed || s.name.toLowerCase() === lower);
+            if (priorityExact)
+                return priorityExact;
+        }
+        const exact = suggestions.find((s) => s.id === trimmed || s.name.toLowerCase() === lower);
+        if (exact)
+            return exact;
+        // Try partial match in priority suggestions first
+        if (prioritySuggestions) {
+            const priorityPartials = prioritySuggestions.filter((s) => s.name.toLowerCase().includes(lower) || s.id.toLowerCase().includes(lower));
+            if (priorityPartials.length === 1)
+                return priorityPartials[0];
+        }
+        // Fall back to partial match in all suggestions
+        const partials = suggestions.filter((s) => s.name.toLowerCase().includes(lower) || s.id.toLowerCase().includes(lower));
+        if (partials.length === 1)
+            return partials[0];
+        return undefined;
+    }, [suggestions, prioritySuggestions]);
+    const filterSuggestions = useCallback((input) => {
+        var _a;
+        const trimmed = input.trim();
+        const lower = trimmed.toLowerCase();
+        // No input — return all suggestions split by tier
+        if (!trimmed) {
+            return {
+                priority: prioritySuggestions !== null && prioritySuggestions !== void 0 ? prioritySuggestions : [],
+                catalog: suggestions.filter((s) => !priorityIds.has(s.id))
+            };
+        }
+        // Filter by substring match
+        const matchesSuggestion = (s) => s.name.toLowerCase().includes(lower) || s.id.toLowerCase().includes(lower);
+        const priority = (_a = prioritySuggestions === null || prioritySuggestions === void 0 ? void 0 : prioritySuggestions.filter(matchesSuggestion)) !== null && _a !== void 0 ? _a : [];
+        const catalog = suggestions.filter((s) => !priorityIds.has(s.id) && matchesSuggestion(s));
+        return { priority, catalog };
+    }, [suggestions, prioritySuggestions, priorityIds]);
+    return { findExactMatch, resolveOnBlur, filterSuggestions };
+}
+//# sourceMappingURL=useTypeaheadMatch.js.map

package/dist/packlets/keyboard/index.js

@@ -0,0 +1,7 @@
+/**
+ * Keyboard shortcut packlet - registry, context, and hooks.
+ * @packageDocumentation
+ */
+export { KeyboardShortcutRegistry, matchesBinding } from './registry';
+export { KeyboardShortcutProvider, useKeyboardRegistry, useKeyboardShortcuts } from './useKeyboardShortcuts';
+//# sourceMappingURL=index.js.map

package/dist/packlets/keyboard/registry.js

@@ -0,0 +1,133 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+// ============================================================================
+// Key Matching
+// ============================================================================
+/**
+ * Tests whether a keyboard event matches a key binding.
+ * @param event - The keyboard event
+ * @param binding - The binding to match against
+ * @returns true if the event matches
+ * @public
+ */
+export function matchesBinding(event, binding) {
+    var _a, _b, _c;
+    const keyMatch = event.key.toLowerCase() === binding.key.toLowerCase();
+    const metaMatch = ((_a = binding.meta) !== null && _a !== void 0 ? _a : false) === (event.metaKey || event.ctrlKey);
+    const shiftMatch = ((_b = binding.shift) !== null && _b !== void 0 ? _b : false) === event.shiftKey;
+    const altMatch = ((_c = binding.alt) !== null && _c !== void 0 ? _c : false) === event.altKey;
+    return keyMatch && metaMatch && shiftMatch && altMatch;
+}
+// ============================================================================
+// Registry
+// ============================================================================
+/**
+ * Centralized keyboard shortcut registry.
+ *
+ * Components register shortcuts via `register()` and receive a handle
+ * to unregister when they unmount. The registry attaches a single global
+ * keydown listener that dispatches to the highest-priority matching handler.
+ *
+ * @public
+ */
+export class KeyboardShortcutRegistry {
+    constructor() {
+        this._shortcuts = new Map();
+        this._nextId = 0;
+    }
+    /**
+     * Registers a keyboard shortcut.
+     * @param shortcut - The shortcut to register
+     * @returns A registration handle with an `unregister()` method
+     */
+    register(shortcut) {
+        const id = `ks-${++this._nextId}`;
+        this._shortcuts.set(id, shortcut);
+        this._ensureListener();
+        return {
+            unregister: () => {
+                this._shortcuts.delete(id);
+                if (this._shortcuts.size === 0) {
+                    this._removeListener();
+                }
+            }
+        };
+    }
+    /**
+     * Returns all currently registered shortcuts (for command palette / help display).
+     */
+    getAll() {
+        return Array.from(this._shortcuts.values());
+    }
+    /**
+     * Dispatches a keyboard event to the highest-priority matching handler.
+     * @param event - The keyboard event
+     * @returns true if a handler consumed the event
+     */
+    dispatch(event) {
+        var _a;
+        // Skip if the event target is an input/textarea/contenteditable
+        const target = event.target;
+        if (target) {
+            const tagName = (_a = target.tagName) === null || _a === void 0 ? void 0 : _a.toLowerCase();
+            if (tagName === 'input' || tagName === 'textarea' || target.isContentEditable) {
+                return false;
+            }
+        }
+        // Find all matching shortcuts, sorted by priority (highest first)
+        const matches = Array.from(this._shortcuts.values())
+            .filter((s) => matchesBinding(event, s.binding))
+            .sort((a, b) => { var _a, _b; return ((_a = b.priority) !== null && _a !== void 0 ? _a : 0) - ((_b = a.priority) !== null && _b !== void 0 ? _b : 0); });
+        for (const shortcut of matches) {
+            const result = shortcut.handler();
+            if (result !== false) {
+                event.preventDefault();
+                event.stopPropagation();
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Removes all shortcuts and the global listener.
+     */
+    dispose() {
+        this._shortcuts.clear();
+        this._removeListener();
+    }
+    _ensureListener() {
+        if (this._listener) {
+            return;
+        }
+        this._listener = (e) => {
+            this.dispatch(e);
+        };
+        document.addEventListener('keydown', this._listener);
+    }
+    _removeListener() {
+        if (this._listener) {
+            document.removeEventListener('keydown', this._listener);
+            this._listener = undefined;
+        }
+    }
+}
+//# sourceMappingURL=registry.js.map