@fgv/ts-app-shell 5.1.0-1

package/lib/packlets/sidebar/FilterRow.d.ts

@@ -0,0 +1,42 @@
+import React from 'react';
+/**
+ * A single selectable filter option.
+ * Generic over the value type so apps can use string IDs, enums, etc.
+ * @public
+ */
+export interface IFilterOption<TValue> {
+    /** Unique value for this option */
+    readonly value: TValue;
+    /** Display label */
+    readonly label: string;
+    /** Optional count badge */
+    readonly count?: number;
+}
+/**
+ * Props for the FilterRow component.
+ * @public
+ */
+export interface IFilterRowProps<TValue> {
+    /** Filter label (e.g., 'Categories', 'Tags') */
+    readonly label: string;
+    /** Available options */
+    readonly options: ReadonlyArray<IFilterOption<TValue>>;
+    /** Currently selected values */
+    readonly selected: ReadonlyArray<TValue>;
+    /** Callback when selection changes */
+    readonly onSelectionChange: (selected: ReadonlyArray<TValue>) => void;
+    /** Whether multiple selections are allowed (default: true) */
+    readonly multiple?: boolean;
+    /** Custom equality check for values (default: ===) */
+    readonly isEqual?: (a: TValue, b: TValue) => boolean;
+}
+/**
+ * A compact filter row with a right-side flyout overlay for selecting filter values.
+ *
+ * Collapsed: shows the label, status summary text, and a `\u203A` chevron.
+ * Expanded: a flyout panel slides out to the right of the sidebar, overlaying the main pane.
+ *
+ * @public
+ */
+export declare function FilterRow<TValue>(props: IFilterRowProps<TValue>): React.ReactElement;
+//# sourceMappingURL=FilterRow.d.ts.map

package/lib/packlets/sidebar/FilterRow.js

@@ -0,0 +1,218 @@
+"use strict";
+/*
+ * 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.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FilterRow = FilterRow;
+const react_1 = __importStar(require("react"));
+const responsive_1 = require("../responsive");
+// ============================================================================
+// FilterRow Component
+// ============================================================================
+/** Minimum number of options before showing the search-within-filter input */
+const SEARCH_THRESHOLD = 8;
+/**
+ * A compact filter row with a right-side flyout overlay for selecting filter values.
+ *
+ * Collapsed: shows the label, status summary text, and a `\u203A` chevron.
+ * Expanded: a flyout panel slides out to the right of the sidebar, overlaying the main pane.
+ *
+ * @public
+ */
+function FilterRow(props) {
+    const { label, options, selected, onSelectionChange, multiple = true, isEqual = defaultIsEqual } = props;
+    const { layoutMode } = (0, responsive_1.useResponsive)();
+    const isMobile = layoutMode === 'mobile';
+    const [open, setOpen] = (0, react_1.useState)(false);
+    const [flyoutSearch, setFlyoutSearch] = (0, react_1.useState)('');
+    const rowRef = (0, react_1.useRef)(null);
+    const flyoutRef = (0, react_1.useRef)(null);
+    // Close flyout on outside click (check both row and flyout)
+    (0, react_1.useEffect)(() => {
+        if (!open) {
+            return undefined;
+        }
+        const handleClick = (e) => {
+            const target = e.target;
+            if (rowRef.current &&
+                !rowRef.current.contains(target) &&
+                flyoutRef.current &&
+                !flyoutRef.current.contains(target)) {
+                setOpen(false);
+                setFlyoutSearch('');
+            }
+        };
+        document.addEventListener('mousedown', handleClick);
+        return () => document.removeEventListener('mousedown', handleClick);
+    }, [open]);
+    // Close flyout on Escape
+    (0, react_1.useEffect)(() => {
+        if (!open) {
+            return undefined;
+        }
+        const handleKey = (e) => {
+            if (e.key === 'Escape') {
+                setOpen(false);
+                setFlyoutSearch('');
+            }
+        };
+        document.addEventListener('keydown', handleKey);
+        return () => document.removeEventListener('keydown', handleKey);
+    }, [open]);
+    const isSelected = (0, react_1.useCallback)((value) => selected.some((s) => isEqual(s, value)), [selected, isEqual]);
+    const toggleValue = (0, react_1.useCallback)((value) => {
+        if (multiple) {
+            if (isSelected(value)) {
+                onSelectionChange(selected.filter((s) => !isEqual(s, value)));
+            }
+            else {
+                onSelectionChange([...selected, value]);
+            }
+        }
+        else {
+            // Single-select: toggle off if already selected, otherwise select
+            if (isSelected(value)) {
+                onSelectionChange([]);
+            }
+            else {
+                onSelectionChange([value]);
+            }
+        }
+    }, [multiple, selected, onSelectionChange, isSelected, isEqual]);
+    const clearSelection = (0, react_1.useCallback)((e) => {
+        e.stopPropagation();
+        onSelectionChange([]);
+    }, [onSelectionChange]);
+    const activeCount = selected.length;
+    // Status summary text for the collapsed row
+    const statusText = (0, react_1.useMemo)(() => {
+        if (activeCount === 0) {
+            return 'All';
+        }
+        if (activeCount === 1) {
+            // Show the label of the single selected option
+            const sel = selected[0];
+            const match = options.find((o) => isEqual(o.value, sel));
+            return match ? match.label : '1 selected';
+        }
+        return `${activeCount} selected`;
+    }, [activeCount, selected, options, isEqual]);
+    // Filter options by flyout search
+    const filteredOptions = (0, react_1.useMemo)(() => {
+        const q = flyoutSearch.trim().toLowerCase();
+        if (q.length === 0) {
+            return options;
+        }
+        return options.filter((o) => o.label.toLowerCase().includes(q));
+    }, [options, flyoutSearch]);
+    // Compute flyout position: anchored to the right edge of the sidebar row, aligned vertically
+    const [flyoutStyle, setFlyoutStyle] = (0, react_1.useState)({});
+    (0, react_1.useEffect)(() => {
+        if (!open || !rowRef.current) {
+            return;
+        }
+        const rect = rowRef.current.getBoundingClientRect();
+        // Find the sidebar container (the <aside> ancestor)
+        let sidebar = rowRef.current;
+        while (sidebar && sidebar.tagName !== 'ASIDE') {
+            sidebar = sidebar.parentElement;
+        }
+        const rightEdge = sidebar ? sidebar.getBoundingClientRect().right : rect.right;
+        // Flyout appears at the right edge of the sidebar, vertically aligned with the row
+        const maxHeight = Math.min(400, window.innerHeight - rect.top - 8);
+        setFlyoutStyle({
+            position: 'fixed',
+            top: rect.top,
+            left: rightEdge,
+            width: 280,
+            maxHeight,
+            zIndex: 50
+        });
+    }, [open]);
+    const handleToggle = (0, react_1.useCallback)(() => {
+        setOpen((prev) => {
+            if (prev) {
+                setFlyoutSearch('');
+            }
+            return !prev;
+        });
+    }, []);
+    return (react_1.default.createElement("div", { ref: rowRef },
+        react_1.default.createElement("button", { onClick: handleToggle, className: `flex items-center justify-between w-full px-3 text-sm hover:bg-hover transition-colors ${isMobile ? 'py-3' : 'py-1.5'} ${activeCount > 0 ? 'text-brand-primary font-medium' : 'text-secondary'}` },
+            react_1.default.createElement("span", { className: "truncate" }, label),
+            react_1.default.createElement("span", { className: "flex items-center gap-1.5 shrink-0 ml-2" },
+                activeCount > 0 && (react_1.default.createElement("span", { onClick: clearSelection, className: "text-muted hover:text-secondary cursor-pointer text-xs", role: "button", "aria-label": `Clear ${label} filter` }, '\u00D7')),
+                react_1.default.createElement("span", { className: `text-xs ${activeCount > 0 ? 'text-brand-accent' : 'text-muted'}` }, statusText),
+                react_1.default.createElement("span", { className: "text-muted text-xs" }, '\u203A'))),
+        open && (react_1.default.createElement("div", { ref: flyoutRef, className: "bg-surface border border-border rounded-r-lg shadow-xl overflow-hidden flex flex-col", style: flyoutStyle },
+            react_1.default.createElement("div", { className: "flex items-center justify-between px-3 py-2 border-b border-border-subtle bg-surface-alt" },
+                react_1.default.createElement("span", { className: "text-xs font-medium text-secondary" }, label),
+                activeCount > 0 && (react_1.default.createElement("button", { onClick: () => onSelectionChange([]), className: "text-xs text-brand-accent hover:text-brand-primary" }, "Clear"))),
+            options.length >= SEARCH_THRESHOLD && (react_1.default.createElement("div", { className: "px-3 py-1.5 border-b border-border-subtle" },
+                react_1.default.createElement("input", { type: "text", value: flyoutSearch, onChange: (e) => setFlyoutSearch(e.target.value), placeholder: `Search ${label.toLowerCase()}...`, className: "w-full px-2 py-1 text-xs border border-border rounded bg-surface text-primary focus:outline-none focus:border-focus-ring", autoFocus: true }))),
+            react_1.default.createElement("div", { className: "flex-1 overflow-y-auto" }, filteredOptions.length === 0 ? (react_1.default.createElement("div", { className: "px-3 py-2 text-xs text-muted" }, options.length === 0 ? 'No options available' : 'No matches')) : (filteredOptions.map((option, idx) => {
+                const checked = isSelected(option.value);
+                return (react_1.default.createElement("button", { key: idx, onClick: () => toggleValue(option.value), className: `flex items-center gap-2 w-full px-3 text-sm text-left hover:bg-hover transition-colors ${isMobile ? 'py-2.5' : 'py-1.5'} ${checked ? 'text-brand-primary font-medium' : 'text-secondary'}` },
+                    react_1.default.createElement("span", { className: `inline-flex items-center justify-center w-4 h-4 border rounded ${multiple ? 'rounded' : 'rounded-full'} ${checked ? 'bg-brand-accent border-brand-accent text-white' : 'border-border'}` }, checked && react_1.default.createElement("span", { className: "text-[10px]" }, '\u2713')),
+                    react_1.default.createElement("span", { className: "flex-1 truncate" }, option.label),
+                    option.count !== undefined && react_1.default.createElement("span", { className: "text-xs text-muted" }, option.count)));
+            })))))));
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+function defaultIsEqual(a, b) {
+    return a === b;
+}
+//# sourceMappingURL=FilterRow.js.map

package/lib/packlets/sidebar/GroupedEntityList.d.ts

@@ -0,0 +1,59 @@
+import React from 'react';
+import type { IEntityDescriptor, IEmptyStateConfig } from './EntityList';
+/**
+ * Extends {@link IEntityDescriptor} with grouping support.
+ * @public
+ */
+export interface IEntityGroupDescriptor<TEntity, TId extends string = string> extends IEntityDescriptor<TEntity, TId> {
+    /** Extract a group key from an entity. Entities with the same key are grouped together. */
+    readonly getGroupKey: (entity: TEntity) => string;
+    /** Extract a display label for a group. Called on the first entity in each group. */
+    readonly getGroupLabel: (entity: TEntity) => string;
+    /** Optional sort comparator for group ordering. Receives group keys. */
+    readonly compareGroups?: (a: string, b: string) => number;
+}
+/**
+ * Props for the {@link GroupedEntityList} component.
+ * @public
+ */
+export interface IGroupedEntityListProps<TEntity, TId extends string = string> {
+    /** The entities to display (pre-sorted within groups by the caller). */
+    readonly entities: ReadonlyArray<TEntity>;
+    /** Descriptor for extracting display and grouping properties. */
+    readonly descriptor: IEntityGroupDescriptor<TEntity, TId>;
+    /** Currently selected entity ID (if any). */
+    readonly selectedId?: TId;
+    /** Callback when an entity is selected (browse — list stays open). */
+    readonly onSelect: (id: TId) => void;
+    /** Callback when the user drills into the selected entity (Enter/Arrow Right — collapses list). */
+    readonly onDrill?: () => void;
+    /** Whether compare mode is active. */
+    readonly compareMode?: boolean;
+    /** Entity IDs currently checked for comparison. */
+    readonly checkedIds?: ReadonlySet<string>;
+    /** Callback to toggle an entity ID in/out of compare selection. */
+    readonly onCheckedChange?: (id: TId) => void;
+    /** Empty state configuration. */
+    readonly emptyState?: IEmptyStateConfig;
+    /** Callback to toggle compare mode. */
+    readonly onToggleCompare?: () => void;
+    /** Number of items selected for comparison. */
+    readonly compareCount?: number;
+    /** Callback to start comparison view. */
+    readonly onStartComparison?: () => void;
+    /** Callback to delete an entity. */
+    readonly onDelete?: (id: TId) => void;
+    /** Predicate to control per-entity delete button visibility. */
+    readonly canDelete?: (id: TId) => boolean;
+}
+/**
+ * Entity list with sticky group headers.
+ *
+ * Groups entities by a key extracted via the descriptor, renders a sticky
+ * header per group, and delegates item rendering to the same visual pattern
+ * as {@link EntityList}.
+ *
+ * @public
+ */
+export declare function GroupedEntityList<TEntity, TId extends string = string>(props: IGroupedEntityListProps<TEntity, TId>): React.ReactElement;
+//# sourceMappingURL=GroupedEntityList.d.ts.map

package/lib/packlets/sidebar/GroupedEntityList.js

@@ -0,0 +1,219 @@
+"use strict";
+/*
+ * 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.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GroupedEntityList = GroupedEntityList;
+const react_1 = __importStar(require("react"));
+function GroupedEntityRowInner(props) {
+    var _a, _b;
+    const { entity, descriptor, selectedId, compareMode, checkedIds, onSelect, onDrill, onCheckedChange, onDelete, canDelete } = props;
+    const id = descriptor.getId(entity);
+    const label = descriptor.getLabel(entity);
+    const sublabel = (_a = descriptor.getSublabel) === null || _a === void 0 ? void 0 : _a.call(descriptor, entity);
+    const status = (_b = descriptor.getStatus) === null || _b === void 0 ? void 0 : _b.call(descriptor, entity);
+    const isSelected = id === selectedId;
+    const isChecked = compareMode === true && checkedIds !== undefined && checkedIds.has(id);
+    return (react_1.default.createElement("div", { className: `group flex items-center gap-2 w-full border-b border-border-subtle transition-colors ${isChecked
+            ? 'bg-selected border-l-2 border-l-selected-border'
+            : isSelected && !compareMode
+                ? 'bg-selected border-l-2 border-l-selected-border'
+                : 'hover:bg-hover border-l-2 border-l-transparent'}` },
+        react_1.default.createElement("button", { "data-entity-id": id, onClick: () => {
+                if (compareMode && onCheckedChange) {
+                    onCheckedChange(id);
+                }
+                else if (isSelected && onDrill) {
+                    onDrill();
+                }
+                else {
+                    onSelect(id);
+                }
+            }, className: "flex items-center gap-2 flex-1 min-w-0 px-3 py-2 text-left" },
+            compareMode && (react_1.default.createElement("span", { className: `flex items-center justify-center w-4 h-4 rounded border shrink-0 transition-colors ${isChecked ? 'bg-brand-accent border-brand-accent text-white' : 'border-border bg-surface'}` }, isChecked && (react_1.default.createElement("svg", { className: "w-3 h-3", fill: "none", viewBox: "0 0 24 24", stroke: "currentColor", strokeWidth: 3 },
+                react_1.default.createElement("path", { strokeLinecap: "round", strokeLinejoin: "round", d: "M5 13l4 4L19 7" }))))),
+            react_1.default.createElement("div", { className: "flex-1 min-w-0" },
+                react_1.default.createElement("div", { className: `text-sm truncate ${(isSelected && !compareMode) || isChecked ? 'font-medium text-brand-primary' : 'text-primary'}` }, label),
+                sublabel && react_1.default.createElement("div", { className: "text-xs text-muted truncate mt-0.5" }, sublabel)),
+            status && (react_1.default.createElement("span", { className: "flex items-center gap-1 shrink-0 mt-0.5" },
+                react_1.default.createElement("span", { className: `w-2 h-2 rounded-full ${status.colorClass}` }),
+                react_1.default.createElement("span", { className: "text-xs text-muted" }, status.label)))),
+        onDelete && !compareMode && (!canDelete || canDelete(id)) && (react_1.default.createElement("button", { onClick: (e) => {
+                e.stopPropagation();
+                onDelete(id);
+            }, className: "shrink-0 mr-1 w-6 h-6 flex items-center justify-center text-faint hover:text-status-error-icon opacity-0 group-hover:opacity-100 focus:opacity-100 transition-opacity rounded", title: `Delete ${label}`, "aria-label": `Delete ${label}` },
+            react_1.default.createElement("svg", { className: "w-3.5 h-3.5", fill: "none", viewBox: "0 0 24 24", stroke: "currentColor", strokeWidth: 2 },
+                react_1.default.createElement("path", { strokeLinecap: "round", strokeLinejoin: "round", d: "M19 7l-.867 12.142A2 2 0 0116.138 21H7.862a2 2 0 01-1.995-1.858L5 7m5 4v6m4-6v6m1-10V4a1 1 0 00-1-1h-4a1 1 0 00-1 1v3M4 7h16" }))))));
+}
+const GroupedEntityRow = react_1.default.memo(GroupedEntityRowInner);
+// ============================================================================
+// GroupedEntityList Component
+// ============================================================================
+/**
+ * Entity list with sticky group headers.
+ *
+ * Groups entities by a key extracted via the descriptor, renders a sticky
+ * header per group, and delegates item rendering to the same visual pattern
+ * as {@link EntityList}.
+ *
+ * @public
+ */
+function GroupedEntityList(props) {
+    const { entities, descriptor, selectedId, onSelect, onDrill, compareMode, checkedIds, onCheckedChange, emptyState, onDelete, canDelete } = props;
+    const listRef = (0, react_1.useRef)(null);
+    // Build groups and flat entity list for keyboard navigation
+    const { groups, flatEntities } = (0, react_1.useMemo)(() => {
+        const groupMap = new Map();
+        for (const entity of entities) {
+            const key = descriptor.getGroupKey(entity);
+            let group = groupMap.get(key);
+            if (!group) {
+                group = { label: descriptor.getGroupLabel(entity), items: [] };
+                groupMap.set(key, group);
+            }
+            group.items.push(entity);
+        }
+        const sortedKeys = Array.from(groupMap.keys());
+        if (descriptor.compareGroups) {
+            const cmp = descriptor.compareGroups;
+            sortedKeys.sort((a, b) => cmp(a, b));
+        }
+        const builtGroups = [];
+        const flat = [];
+        for (const key of sortedKeys) {
+            const group = groupMap.get(key);
+            builtGroups.push({ key, label: group.label, items: group.items });
+            flat.push(...group.items);
+        }
+        return { groups: builtGroups, flatEntities: flat };
+    }, [entities, descriptor]);
+    // Scroll selected item into view
+    (0, react_1.useEffect)(() => {
+        if (selectedId && listRef.current) {
+            const selectedButton = listRef.current.querySelector(`[data-entity-id="${selectedId}"]`);
+            if (selectedButton) {
+                selectedButton.scrollIntoView({ block: 'nearest' });
+            }
+        }
+    }, [selectedId]);
+    const selectedIndex = flatEntities.findIndex((e) => descriptor.getId(e) === selectedId);
+    const handleKeyDown = (0, react_1.useCallback)((e) => {
+        switch (e.key) {
+            case 'ArrowDown': {
+                e.preventDefault();
+                const nextIndex = selectedIndex < flatEntities.length - 1 ? selectedIndex + 1 : 0;
+                onSelect(descriptor.getId(flatEntities[nextIndex]));
+                break;
+            }
+            case 'ArrowUp': {
+                e.preventDefault();
+                const prevIndex = selectedIndex > 0 ? selectedIndex - 1 : flatEntities.length - 1;
+                onSelect(descriptor.getId(flatEntities[prevIndex]));
+                break;
+            }
+            case 'Enter':
+            case 'ArrowRight': {
+                if (selectedId !== undefined && onDrill) {
+                    e.preventDefault();
+                    onDrill();
+                }
+                break;
+            }
+            default:
+                break;
+        }
+    }, [flatEntities, descriptor, selectedId, selectedIndex, onSelect, onDrill]);
+    // Empty state
+    if (entities.length === 0 && emptyState) {
+        return (react_1.default.createElement("div", { className: "flex flex-col items-center justify-center flex-1 p-6 text-center" },
+            react_1.default.createElement("h3", { className: "text-sm font-medium text-secondary mb-1" }, emptyState.title),
+            react_1.default.createElement("p", { className: "text-xs text-muted mb-4" }, emptyState.description),
+            emptyState.action && (react_1.default.createElement("button", { onClick: emptyState.action.onClick, className: "px-3 py-1.5 text-xs font-medium text-white bg-brand-accent rounded-md hover:bg-brand-primary transition-colors" }, emptyState.action.label))));
+    }
+    return (react_1.default.createElement("div", { className: "flex flex-col flex-1 overflow-hidden", onKeyDown: handleKeyDown },
+        flatEntities.length > 0 && (react_1.default.createElement("div", { className: "flex items-center justify-between px-3 py-1.5 border-b border-border-subtle" },
+            react_1.default.createElement("span", { className: "text-xs text-muted" },
+                flatEntities.length,
+                " item",
+                flatEntities.length !== 1 ? 's' : '',
+                compareMode && props.compareCount !== undefined && props.compareCount > 0 && (react_1.default.createElement("span", { className: "ml-1.5 text-brand-accent" },
+                    "\u00B7 ",
+                    props.compareCount,
+                    " selected"))),
+            react_1.default.createElement("div", { className: "flex items-center gap-1" },
+                compareMode &&
+                    props.onStartComparison &&
+                    props.compareCount !== undefined &&
+                    props.compareCount >= 2 && (react_1.default.createElement("button", { onClick: (e) => {
+                        var _a;
+                        e.stopPropagation();
+                        (_a = props.onStartComparison) === null || _a === void 0 ? void 0 : _a.call(props);
+                    }, className: "px-2 py-0.5 text-[11px] rounded border transition-colors bg-brand-primary text-white border-brand-primary hover:bg-brand-primary/90" }, "Compare Now")),
+                props.onToggleCompare && (react_1.default.createElement("button", { onClick: (e) => {
+                        var _a;
+                        e.stopPropagation();
+                        (_a = props.onToggleCompare) === null || _a === void 0 ? void 0 : _a.call(props);
+                    }, className: `px-2 py-0.5 text-[11px] rounded border transition-colors ${compareMode
+                        ? 'bg-brand-accent text-white border-brand-accent'
+                        : 'bg-surface text-muted border-border hover:border-brand-accent hover:text-brand-accent'}` }, compareMode ? 'Cancel' : 'Compare'))))),
+        react_1.default.createElement("div", { ref: listRef, className: "flex-1 overflow-y-auto" }, groups.map((group) => (react_1.default.createElement("div", { key: group.key },
+            react_1.default.createElement("div", { className: "px-3 py-1.5 text-xs font-medium text-muted uppercase tracking-wider bg-surface-alt border-b border-border-subtle sticky top-0 z-10" },
+                group.label,
+                react_1.default.createElement("span", { className: "text-muted normal-case font-normal ml-1" },
+                    "(",
+                    group.items.length,
+                    ")")),
+            group.items.map((entity) => (react_1.default.createElement(GroupedEntityRow, { key: descriptor.getId(entity), entity: entity, descriptor: descriptor, selectedId: selectedId, compareMode: compareMode, checkedIds: checkedIds, onSelect: onSelect, onDrill: onDrill, onCheckedChange: onCheckedChange, onDelete: onDelete, canDelete: canDelete })))))))));
+}
+//# sourceMappingURL=GroupedEntityList.js.map

package/lib/packlets/sidebar/SearchBar.d.ts

@@ -0,0 +1,19 @@
+import React from 'react';
+/**
+ * Props for the SearchBar component.
+ * @public
+ */
+export interface ISearchBarProps {
+    /** Current search query */
+    readonly value: string;
+    /** Callback when the search query changes */
+    readonly onChange: (value: string) => void;
+    /** Placeholder text (default: 'Search...') */
+    readonly placeholder?: string;
+}
+/**
+ * Search input bar for the sidebar.
+ * @public
+ */
+export declare function SearchBar(props: ISearchBarProps): React.ReactElement;
+//# sourceMappingURL=SearchBar.d.ts.map

package/lib/packlets/sidebar/SearchBar.js

@@ -0,0 +1,40 @@
+"use strict";
+/*
+ * 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.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SearchBar = SearchBar;
+const react_1 = __importDefault(require("react"));
+/**
+ * Search input bar for the sidebar.
+ * @public
+ */
+function SearchBar(props) {
+    const { value, onChange, placeholder = 'Search...' } = props;
+    return (react_1.default.createElement("div", { className: "px-3 py-2" },
+        react_1.default.createElement("div", { className: "relative" },
+            react_1.default.createElement("input", { type: "text", value: value, onChange: (e) => onChange(e.target.value), placeholder: placeholder, className: "w-full pl-3 pr-8 py-1.5 text-sm border border-border rounded-md bg-surface text-primary focus:outline-none focus:ring-1 focus:ring-focus-ring focus:border-focus-ring" }),
+            value.length > 0 && (react_1.default.createElement("button", { onClick: () => onChange(''), className: "absolute right-2 top-1/2 -translate-y-1/2 text-muted hover:text-secondary text-xs", "aria-label": "Clear search" }, "\u00D7")))));
+}
+//# sourceMappingURL=SearchBar.js.map

package/lib/packlets/sidebar/SidebarLayout.d.ts

@@ -0,0 +1,28 @@
+import React from 'react';
+/**
+ * Props for the SidebarLayout component.
+ * @public
+ */
+export interface ISidebarLayoutProps {
+    /** Sidebar content (filter bar, collection section, etc.) */
+    readonly sidebar: React.ReactNode;
+    /** Main content area */
+    readonly children: React.ReactNode;
+    /** Sidebar width in CSS units (default: '280px') */
+    readonly sidebarWidth?: string;
+    /** Whether the sidebar drawer is open (compact/mobile only). */
+    readonly isSidebarOpen?: boolean;
+    /** Called when the drawer should close (backdrop click, etc.). */
+    readonly onSidebarClose?: () => void;
+}
+/**
+ * Layout component that renders a persistent left sidebar alongside a main content area.
+ *
+ * On `full` layout mode, the sidebar is a fixed-width panel.
+ * On `compact` and `mobile` layout modes, the sidebar becomes a slide-out drawer
+ * controlled by {@link ISidebarLayoutProps.isSidebarOpen | isSidebarOpen} and
+ * {@link ISidebarLayoutProps.onSidebarClose | onSidebarClose}.
+ * @public
+ */
+export declare function SidebarLayout(props: ISidebarLayoutProps): React.ReactElement;
+//# sourceMappingURL=SidebarLayout.d.ts.map