@fgv/ts-app-shell 5.1.0-1

package/lib/packlets/sidebar/SidebarLayout.js

@@ -0,0 +1,98 @@
+"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.SidebarLayout = SidebarLayout;
+const react_1 = __importStar(require("react"));
+const responsive_1 = require("../responsive");
+/**
+ * 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
+ */
+function SidebarLayout(props) {
+    const { sidebar, children, sidebarWidth = '280px', isSidebarOpen = false, onSidebarClose } = props;
+    const { layoutMode } = (0, responsive_1.useResponsive)();
+    const isDrawer = layoutMode !== 'full';
+    // Close drawer on Escape key
+    (0, react_1.useEffect)(() => {
+        if (!isDrawer || !isSidebarOpen) {
+            return;
+        }
+        const handleKeyDown = (e) => {
+            if (e.key === 'Escape') {
+                onSidebarClose === null || onSidebarClose === void 0 ? void 0 : onSidebarClose();
+            }
+        };
+        document.addEventListener('keydown', handleKeyDown);
+        return () => document.removeEventListener('keydown', handleKeyDown);
+    }, [isDrawer, isSidebarOpen, onSidebarClose]);
+    // Full mode: static sidebar
+    if (!isDrawer) {
+        return (react_1.default.createElement("div", { className: "flex flex-1 overflow-hidden" },
+            react_1.default.createElement("aside", { className: "flex flex-col border-r border-border bg-surface overflow-y-auto shrink-0", style: { width: sidebarWidth } }, sidebar),
+            react_1.default.createElement("div", { className: "flex flex-col flex-1 overflow-hidden" }, children)));
+    }
+    // Compact/mobile: drawer overlay
+    return (react_1.default.createElement("div", { className: "flex flex-col flex-1 overflow-hidden relative" },
+        react_1.default.createElement("div", { className: "flex flex-col flex-1 overflow-hidden" }, children),
+        isSidebarOpen && (react_1.default.createElement("div", { className: "fixed inset-0 bg-backdrop z-40 transition-opacity", onClick: onSidebarClose, "aria-hidden": "true" })),
+        react_1.default.createElement("aside", { className: `fixed inset-y-0 left-0 z-50 flex flex-col bg-surface border-r border-border overflow-y-auto shadow-lg transition-transform duration-200 ease-in-out ${isSidebarOpen ? 'translate-x-0' : '-translate-x-full'}`, style: { width: sidebarWidth } }, sidebar)));
+}
+//# sourceMappingURL=SidebarLayout.js.map

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

@@ -0,0 +1,12 @@
+/**
+ * Sidebar packlet - layout, search, filter rows, and entity list.
+ * @packageDocumentation
+ */
+export { SidebarLayout, type ISidebarLayoutProps } from './SidebarLayout';
+export { SearchBar, type ISearchBarProps } from './SearchBar';
+export { FilterRow, type IFilterRowProps, type IFilterOption } from './FilterRow';
+export { FilterBar, type IFilterBarProps } from './FilterBar';
+export { EntityList, type IEntityListProps, type IEntityDescriptor, type IEntityStatus, type IEmptyStateConfig, type IEmptyStateAction } from './EntityList';
+export { GroupedEntityList, type IGroupedEntityListProps, type IEntityGroupDescriptor } from './GroupedEntityList';
+export { CollectionSection, type ICollectionSectionProps, type ICollectionRowItem } from './CollectionSection';
+//# sourceMappingURL=index.d.ts.map

package/lib/packlets/sidebar/index.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Sidebar packlet - layout, search, filter rows, and entity list.
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CollectionSection = exports.GroupedEntityList = exports.EntityList = exports.FilterBar = exports.FilterRow = exports.SearchBar = exports.SidebarLayout = void 0;
+var SidebarLayout_1 = require("./SidebarLayout");
+Object.defineProperty(exports, "SidebarLayout", { enumerable: true, get: function () { return SidebarLayout_1.SidebarLayout; } });
+var SearchBar_1 = require("./SearchBar");
+Object.defineProperty(exports, "SearchBar", { enumerable: true, get: function () { return SearchBar_1.SearchBar; } });
+var FilterRow_1 = require("./FilterRow");
+Object.defineProperty(exports, "FilterRow", { enumerable: true, get: function () { return FilterRow_1.FilterRow; } });
+var FilterBar_1 = require("./FilterBar");
+Object.defineProperty(exports, "FilterBar", { enumerable: true, get: function () { return FilterBar_1.FilterBar; } });
+var EntityList_1 = require("./EntityList");
+Object.defineProperty(exports, "EntityList", { enumerable: true, get: function () { return EntityList_1.EntityList; } });
+var GroupedEntityList_1 = require("./GroupedEntityList");
+Object.defineProperty(exports, "GroupedEntityList", { enumerable: true, get: function () { return GroupedEntityList_1.GroupedEntityList; } });
+var CollectionSection_1 = require("./CollectionSection");
+Object.defineProperty(exports, "CollectionSection", { enumerable: true, get: function () { return CollectionSection_1.CollectionSection; } });
+//# sourceMappingURL=index.js.map

package/lib/packlets/theme/ThemeProvider.d.ts

@@ -0,0 +1,68 @@
+import React from 'react';
+/**
+ * A theme identifier string. Built-in values are 'light', 'dark', and 'system'.
+ * Custom themes use arbitrary strings that map to CSS classes (e.g., 'ocean' maps to '.theme-ocean').
+ * @public
+ */
+export type ThemeId = string;
+/**
+ * Describes an available theme for display in selectors.
+ * @public
+ */
+export interface IThemeOption {
+    /** Theme identifier used in settings and CSS class mapping */
+    readonly id: ThemeId;
+    /** Human-readable label for display */
+    readonly label: string;
+}
+/**
+ * Value exposed by ThemeContext.
+ * @public
+ */
+export interface IThemeContext {
+    /** The currently active theme ID */
+    readonly theme: ThemeId;
+    /** Whether the resolved (effective) appearance is dark */
+    readonly isDark: boolean;
+    /** Set the active theme */
+    readonly setTheme: (theme: ThemeId) => void;
+    /** All available theme options */
+    readonly availableThemes: ReadonlyArray<IThemeOption>;
+}
+/**
+ * Props for {@link ThemeProvider}.
+ * @public
+ */
+export interface IThemeProviderProps {
+    /** Initial theme ID (typically from persisted settings). Defaults to 'light'. */
+    readonly initialTheme?: ThemeId;
+    /** Additional custom themes beyond the built-in light/dark/system. */
+    readonly customThemes?: ReadonlyArray<IThemeOption>;
+    /** Called when the user changes the theme. Use this to persist the choice. */
+    readonly onThemeChange?: (theme: ThemeId) => void;
+    /** Children */
+    readonly children: React.ReactNode;
+}
+/**
+ * Provides theme context to the application and manages the CSS class on `<html>`.
+ *
+ * Wrap your app (or a subtree) with this provider. Components use {@link useTheme}
+ * to read or change the active theme.
+ *
+ * @example
+ * ```tsx
+ * <ThemeProvider initialTheme={settings.appearance?.theme} onThemeChange={saveTheme}>
+ *   <App />
+ * </ThemeProvider>
+ * ```
+ * @public
+ */
+export declare function ThemeProvider({ initialTheme, customThemes, onThemeChange, children }: IThemeProviderProps): React.JSX.Element;
+/**
+ * Access the current theme and theme-switching controls.
+ *
+ * Must be called within a {@link ThemeProvider}.
+ * @public
+ */
+export declare function useTheme(): IThemeContext;
+//# sourceMappingURL=ThemeProvider.d.ts.map

package/lib/packlets/theme/ThemeProvider.js

@@ -0,0 +1,178 @@
+"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.ThemeProvider = ThemeProvider;
+exports.useTheme = useTheme;
+const react_1 = __importStar(require("react"));
+/**
+ * Default built-in themes.
+ */
+const BUILT_IN_THEMES = [
+    { id: 'light', label: 'Light' },
+    { id: 'dark', label: 'Dark' },
+    { id: 'system', label: 'System' }
+];
+const ThemeContext = (0, react_1.createContext)(undefined);
+/**
+ * Maps a theme ID to the CSS class applied to the document element.
+ * - 'light': no class (uses :root defaults)
+ * - 'dark': 'dark' class
+ * - 'system': 'system-theme' class (uses prefers-color-scheme media query)
+ * - custom: 'theme-\{id\}' class
+ */
+function themeIdToCssClass(id) {
+    switch (id) {
+        case 'light':
+            return undefined;
+        case 'dark':
+            return 'dark';
+        case 'system':
+            return 'system-theme';
+        default:
+            return `theme-${id}`;
+    }
+}
+/**
+ * Determines whether the effective appearance is dark.
+ */
+function resolveIsDark(themeId) {
+    if (themeId === 'dark') {
+        return true;
+    }
+    if (themeId === 'system' && typeof window !== 'undefined') {
+        return window.matchMedia('(prefers-color-scheme: dark)').matches;
+    }
+    return false;
+}
+/**
+ * All CSS classes that ThemeProvider may apply.
+ * Used to cleanly remove the previous theme before applying a new one.
+ */
+const MANAGED_CLASSES = ['dark', 'system-theme'];
+/**
+ * Provides theme context to the application and manages the CSS class on `<html>`.
+ *
+ * Wrap your app (or a subtree) with this provider. Components use {@link useTheme}
+ * to read or change the active theme.
+ *
+ * @example
+ * ```tsx
+ * <ThemeProvider initialTheme={settings.appearance?.theme} onThemeChange={saveTheme}>
+ *   <App />
+ * </ThemeProvider>
+ * ```
+ * @public
+ */
+function ThemeProvider({ initialTheme = 'light', customThemes, onThemeChange, children }) {
+    const [theme, setThemeState] = (0, react_1.useState)(initialTheme);
+    const [isDark, setIsDark] = (0, react_1.useState)(() => resolveIsDark(initialTheme));
+    const availableThemes = (0, react_1.useMemo)(() => {
+        if (!customThemes || customThemes.length === 0) {
+            return BUILT_IN_THEMES;
+        }
+        return [...BUILT_IN_THEMES, ...customThemes];
+    }, [customThemes]);
+    const setTheme = (0, react_1.useCallback)((newTheme) => {
+        setThemeState(newTheme);
+        onThemeChange === null || onThemeChange === void 0 ? void 0 : onThemeChange(newTheme);
+    }, [onThemeChange]);
+    // Apply CSS class to document element when theme changes
+    (0, react_1.useEffect)(() => {
+        const root = document.documentElement;
+        // Remove all managed theme classes
+        for (const cls of MANAGED_CLASSES) {
+            root.classList.remove(cls);
+        }
+        // Also remove any custom theme classes
+        for (const cls of Array.from(root.classList)) {
+            if (cls.startsWith('theme-')) {
+                root.classList.remove(cls);
+            }
+        }
+        // Apply new theme class
+        const cssClass = themeIdToCssClass(theme);
+        if (cssClass) {
+            root.classList.add(cssClass);
+        }
+        setIsDark(resolveIsDark(theme));
+    }, [theme]);
+    // Listen for OS preference changes when using 'system' theme
+    (0, react_1.useEffect)(() => {
+        if (theme !== 'system') {
+            return;
+        }
+        const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
+        const handler = (e) => {
+            setIsDark(e.matches);
+        };
+        mediaQuery.addEventListener('change', handler);
+        return () => mediaQuery.removeEventListener('change', handler);
+    }, [theme]);
+    const value = (0, react_1.useMemo)(() => ({ theme, isDark, setTheme, availableThemes }), [theme, isDark, setTheme, availableThemes]);
+    return react_1.default.createElement(ThemeContext.Provider, { value: value }, children);
+}
+/**
+ * Access the current theme and theme-switching controls.
+ *
+ * Must be called within a {@link ThemeProvider}.
+ * @public
+ */
+function useTheme() {
+    const context = (0, react_1.useContext)(ThemeContext);
+    if (!context) {
+        throw new Error('useTheme must be used within a ThemeProvider');
+    }
+    return context;
+}
+//# sourceMappingURL=ThemeProvider.js.map

package/lib/packlets/theme/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Theme provider and hook for runtime theme switching.
+ * @packageDocumentation
+ */
+export { ThemeProvider, useTheme, type ThemeId, type IThemeOption, type IThemeContext, type IThemeProviderProps } from './ThemeProvider';
+//# sourceMappingURL=index.d.ts.map

package/lib/packlets/theme/index.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * Theme provider and hook for runtime theme switching.
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useTheme = exports.ThemeProvider = void 0;
+var ThemeProvider_1 = require("./ThemeProvider");
+Object.defineProperty(exports, "ThemeProvider", { enumerable: true, get: function () { return ThemeProvider_1.ThemeProvider; } });
+Object.defineProperty(exports, "useTheme", { enumerable: true, get: function () { return ThemeProvider_1.useTheme; } });
+//# sourceMappingURL=index.js.map

package/lib/packlets/top-bar/ModeSelector.d.ts

@@ -0,0 +1,38 @@
+import React from 'react';
+/**
+ * Configuration for a single mode in the mode selector.
+ * @public
+ */
+export interface IModeConfig<TMode extends string> {
+    /** Mode identifier */
+    readonly id: TMode;
+    /** Display label */
+    readonly label: string;
+}
+/**
+ * Props for the ModeSelector component.
+ * @public
+ */
+export interface IModeSelectorProps<TMode extends string> {
+    /** Available modes */
+    readonly modes: ReadonlyArray<IModeConfig<TMode>>;
+    /** Currently active mode */
+    readonly activeMode: TMode;
+    /** Callback when a mode is selected */
+    readonly onModeChange: (mode: TMode) => void;
+    /** Optional right-side content (e.g., settings gear icon) */
+    readonly rightContent?: React.ReactNode;
+    /** Application title */
+    readonly title: string;
+    /** Optional callback to toggle sidebar drawer (shows hamburger icon when provided). */
+    readonly onMenuToggle?: () => void;
+}
+/**
+ * Top-level mode selector bar.
+ * Renders the application title, mode toggle buttons, and optional right-side content.
+ * When {@link IModeSelectorProps.onMenuToggle | onMenuToggle} is provided, a hamburger
+ * menu button is shown at the left edge (for compact/mobile layouts).
+ * @public
+ */
+export declare function ModeSelector<TMode extends string>(props: IModeSelectorProps<TMode>): React.ReactElement;
+//# sourceMappingURL=ModeSelector.d.ts.map

package/lib/packlets/top-bar/ModeSelector.js

@@ -0,0 +1,52 @@
+"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.ModeSelector = ModeSelector;
+const react_1 = __importDefault(require("react"));
+const responsive_1 = require("../responsive");
+/**
+ * Top-level mode selector bar.
+ * Renders the application title, mode toggle buttons, and optional right-side content.
+ * When {@link IModeSelectorProps.onMenuToggle | onMenuToggle} is provided, a hamburger
+ * menu button is shown at the left edge (for compact/mobile layouts).
+ * @public
+ */
+function ModeSelector(props) {
+    const { modes, activeMode, onModeChange, rightContent, title, onMenuToggle } = props;
+    const { layoutMode } = (0, responsive_1.useResponsive)();
+    const isMobile = layoutMode === 'mobile';
+    return (react_1.default.createElement("div", { className: "flex items-center justify-between px-4 py-2 bg-brand-primary text-white" },
+        react_1.default.createElement("div", { className: `flex items-center ${isMobile ? 'gap-2' : 'gap-6'}` },
+            onMenuToggle && (react_1.default.createElement("button", { onClick: onMenuToggle, className: "p-1.5 -ml-1.5 rounded-md text-white/70 hover:text-white hover:bg-white/10 transition-colors", "aria-label": "Open menu" },
+                react_1.default.createElement("svg", { className: "w-5 h-5", fill: "none", viewBox: "0 0 24 24", strokeWidth: 1.5, stroke: "currentColor" },
+                    react_1.default.createElement("path", { strokeLinecap: "round", strokeLinejoin: "round", d: "M3.75 6.75h16.5M3.75 12h16.5m-16.5 5.25h16.5" })))),
+            !isMobile && react_1.default.createElement("h1", { className: "text-lg font-semibold whitespace-nowrap" }, title),
+            react_1.default.createElement("div", { className: "flex gap-1" }, modes.map((mode) => (react_1.default.createElement("button", { key: mode.id, onClick: () => onModeChange(mode.id), className: `rounded-md font-medium transition-colors ${isMobile ? 'px-2 py-1 text-xs' : 'px-4 py-1.5 text-sm'} ${activeMode === mode.id
+                    ? 'bg-white/20 text-white'
+                    : 'text-white/70 hover:text-white hover:bg-white/10'}`, "aria-current": activeMode === mode.id ? 'true' : undefined }, mode.label))))),
+        rightContent && react_1.default.createElement("div", { className: "flex items-center gap-2" }, rightContent)));
+}
+//# sourceMappingURL=ModeSelector.js.map

package/lib/packlets/top-bar/TabBar.d.ts

@@ -0,0 +1,31 @@
+import React from 'react';
+/**
+ * Configuration for a single tab.
+ * @public
+ */
+export interface ITabConfig<TTab extends string> {
+    /** Tab identifier */
+    readonly id: TTab;
+    /** Display label */
+    readonly label: string;
+}
+/**
+ * Props for the TabBar component.
+ * @public
+ */
+export interface ITabBarProps<TTab extends string> {
+    /** Available tabs */
+    readonly tabs: ReadonlyArray<ITabConfig<TTab>>;
+    /** Currently active tab */
+    readonly activeTab: TTab;
+    /** Callback when a tab is selected */
+    readonly onTabChange: (tab: TTab) => void;
+    /** Optional content pinned to the far right of the tab bar */
+    readonly rightContent?: React.ReactNode;
+}
+/**
+ * Second-level tab bar for switching views within a mode.
+ * @public
+ */
+export declare function TabBar<TTab extends string>(props: ITabBarProps<TTab>): React.ReactElement;
+//# sourceMappingURL=TabBar.d.ts.map

package/lib/packlets/top-bar/TabBar.js

@@ -0,0 +1,43 @@
+"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.TabBar = TabBar;
+const react_1 = __importDefault(require("react"));
+/**
+ * Second-level tab bar for switching views within a mode.
+ * @public
+ */
+function TabBar(props) {
+    const { tabs, activeTab, onTabChange, rightContent } = props;
+    return (react_1.default.createElement("div", { className: "flex items-center gap-1 px-4 py-1 bg-brand-secondary text-white border-t border-white/10 overflow-x-auto" },
+        tabs.map((tab) => (react_1.default.createElement("button", { key: tab.id, onClick: () => onTabChange(tab.id), className: `px-3 py-1.5 rounded-md text-sm font-medium transition-colors shrink-0 ${activeTab === tab.id
+                ? 'bg-white/20 text-white'
+                : 'text-white/60 hover:text-white hover:bg-white/10'}`, "aria-current": activeTab === tab.id ? 'page' : undefined }, tab.label))),
+        rightContent !== undefined && (react_1.default.createElement(react_1.default.Fragment, null,
+            react_1.default.createElement("div", { className: "flex-1" }),
+            rightContent))));
+}
+//# sourceMappingURL=TabBar.js.map

package/lib/packlets/top-bar/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Top bar components: mode selector and tab bar.
+ * @packageDocumentation
+ */
+export { ModeSelector, type IModeConfig, type IModeSelectorProps } from './ModeSelector';
+export { TabBar, type ITabConfig, type ITabBarProps } from './TabBar';
+//# sourceMappingURL=index.d.ts.map

package/lib/packlets/top-bar/index.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * Top bar components: mode selector and tab bar.
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TabBar = exports.ModeSelector = void 0;
+var ModeSelector_1 = require("./ModeSelector");
+Object.defineProperty(exports, "ModeSelector", { enumerable: true, get: function () { return ModeSelector_1.ModeSelector; } });
+var TabBar_1 = require("./TabBar");
+Object.defineProperty(exports, "TabBar", { enumerable: true, get: function () { return TabBar_1.TabBar; } });
+//# sourceMappingURL=index.js.map

package/lib/packlets/url-sync/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * URL sync packlet - bidirectional URL hash synchronization for mode/tab navigation.
+ * @packageDocumentation
+ */
+export { type IUrlSyncConfig, type IUrlSyncCallbacks, type IUrlSyncState, type IParsedHash, encodeUrlHash, parseUrlHash, useUrlSync } from './useUrlSync';
+//# sourceMappingURL=index.d.ts.map

package/lib/packlets/url-sync/index.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * URL sync packlet - bidirectional URL hash synchronization for mode/tab navigation.
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useUrlSync = exports.parseUrlHash = exports.encodeUrlHash = void 0;
+var useUrlSync_1 = require("./useUrlSync");
+Object.defineProperty(exports, "encodeUrlHash", { enumerable: true, get: function () { return useUrlSync_1.encodeUrlHash; } });
+Object.defineProperty(exports, "parseUrlHash", { enumerable: true, get: function () { return useUrlSync_1.parseUrlHash; } });
+Object.defineProperty(exports, "useUrlSync", { enumerable: true, get: function () { return useUrlSync_1.useUrlSync; } });
+//# sourceMappingURL=index.js.map