@fgv/ts-app-shell 5.1.0-1

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

@@ -0,0 +1,75 @@
+/**
+ * Configuration for the URL sync hook.
+ * Provides the validation tables and default values needed to
+ * parse and validate URL hash segments.
+ * @public
+ */
+export interface IUrlSyncConfig<TMode extends string, TTab extends string> {
+    /** All valid mode identifiers */
+    readonly validModes: ReadonlyArray<TMode>;
+    /** Valid tabs per mode */
+    readonly validTabs: Record<TMode, ReadonlyArray<TTab>>;
+    /** Default tab for each mode (used when hash has a valid mode but no valid tab) */
+    readonly defaultTabs: Record<TMode, TTab>;
+}
+/**
+ * Callbacks that connect the URL sync hook to the application's state management.
+ * @public
+ */
+export interface IUrlSyncCallbacks<TMode extends string, TTab extends string> {
+    /** Set the active mode */
+    readonly setMode: (mode: TMode) => void;
+    /** Set the active tab */
+    readonly setTab: (tab: TTab) => void;
+}
+/**
+ * Current navigation state to sync to the URL.
+ * @public
+ */
+export interface IUrlSyncState<TMode extends string, TTab extends string> {
+    /** Current mode */
+    readonly mode: TMode;
+    /** Current active tab */
+    readonly activeTab: TTab;
+}
+/**
+ * Result of parsing a URL hash.
+ * @public
+ */
+export interface IParsedHash<TMode extends string, TTab extends string> {
+    readonly mode: TMode;
+    readonly tab: TTab;
+}
+/**
+ * Encodes mode + tab into a URL hash string.
+ * @param mode - The current mode
+ * @param tab - The current tab
+ * @returns Hash string (e.g., '#/library/ingredients')
+ * @public
+ */
+export declare function encodeUrlHash<TMode extends string, TTab extends string>(mode: TMode, tab: TTab): string;
+/**
+ * Parses a URL hash string into mode + tab, validated against the config.
+ * Returns undefined if the hash is invalid or empty.
+ * @param hash - The hash string (with or without leading '#')
+ * @param config - Validation configuration
+ * @returns Parsed mode and tab, or undefined
+ * @public
+ */
+export declare function parseUrlHash<TMode extends string, TTab extends string>(hash: string, config: IUrlSyncConfig<TMode, TTab>): IParsedHash<TMode, TTab> | undefined;
+/**
+ * Hook that synchronizes two-tier mode/tab navigation state with the URL hash.
+ *
+ * - On mount: reads the URL hash and applies it to the store
+ * - On state change: updates the URL hash (pushes history entry)
+ * - On popstate (back/forward): reads the URL hash and applies it to the store
+ *
+ * Should be called once at the app root level.
+ *
+ * @param config - Validation configuration (modes, tabs, defaults)
+ * @param state - Current navigation state
+ * @param callbacks - State mutation callbacks
+ * @public
+ */
+export declare function useUrlSync<TMode extends string, TTab extends string>(config: IUrlSyncConfig<TMode, TTab>, state: IUrlSyncState<TMode, TTab>, callbacks: IUrlSyncCallbacks<TMode, TTab>): void;
+//# sourceMappingURL=useUrlSync.d.ts.map

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

@@ -0,0 +1,162 @@
+"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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeUrlHash = encodeUrlHash;
+exports.parseUrlHash = parseUrlHash;
+exports.useUrlSync = useUrlSync;
+/**
+ * Generic URL hash synchronization for two-tier mode/tab navigation.
+ *
+ * Encodes mode + tab in the URL hash: `#/{mode}/{tab}`
+ * Syncs bidirectionally between application state and the URL.
+ * Handles browser back/forward via popstate.
+ *
+ * @packageDocumentation
+ */
+const react_1 = require("react");
+/**
+ * Encodes mode + tab into a URL hash string.
+ * @param mode - The current mode
+ * @param tab - The current tab
+ * @returns Hash string (e.g., '#/library/ingredients')
+ * @public
+ */
+function encodeUrlHash(mode, tab) {
+    return `#/${mode}/${tab}`;
+}
+/**
+ * Parses a URL hash string into mode + tab, validated against the config.
+ * Returns undefined if the hash is invalid or empty.
+ * @param hash - The hash string (with or without leading '#')
+ * @param config - Validation configuration
+ * @returns Parsed mode and tab, or undefined
+ * @public
+ */
+function parseUrlHash(hash, config) {
+    const cleaned = hash.replace(/^#\/?/, '');
+    if (cleaned.length === 0) {
+        return undefined;
+    }
+    const parts = cleaned.split('/');
+    if (parts.length < 1) {
+        return undefined;
+    }
+    const mode = parts[0];
+    if (!config.validModes.includes(mode)) {
+        return undefined;
+    }
+    const validTabs = config.validTabs[mode];
+    if (parts.length >= 2) {
+        const tab = parts[1];
+        if (validTabs.includes(tab)) {
+            return { mode, tab };
+        }
+    }
+    // Valid mode but no valid tab — use default
+    return { mode, tab: config.defaultTabs[mode] };
+}
+// ============================================================================
+// URL Sync Hook
+// ============================================================================
+/**
+ * Hook that synchronizes two-tier mode/tab navigation state with the URL hash.
+ *
+ * - On mount: reads the URL hash and applies it to the store
+ * - On state change: updates the URL hash (pushes history entry)
+ * - On popstate (back/forward): reads the URL hash and applies it to the store
+ *
+ * Should be called once at the app root level.
+ *
+ * @param config - Validation configuration (modes, tabs, defaults)
+ * @param state - Current navigation state
+ * @param callbacks - State mutation callbacks
+ * @public
+ */
+function useUrlSync(config, state, callbacks) {
+    const { mode, activeTab } = state;
+    const { setMode, setTab } = callbacks;
+    // Track whether we're currently applying a URL change to avoid circular updates
+    const isApplyingUrl = (0, react_1.useRef)(false);
+    // Track whether we've done the initial load
+    const initialized = (0, react_1.useRef)(false);
+    // Keep refs to the latest values so the mount effect captures them without
+    // needing them in its dependency array (the effect must only run once).
+    const configRef = (0, react_1.useRef)(config);
+    configRef.current = config;
+    const modeRef = (0, react_1.useRef)(mode);
+    modeRef.current = mode;
+    const activeTabRef = (0, react_1.useRef)(activeTab);
+    activeTabRef.current = activeTab;
+    const setModeRef = (0, react_1.useRef)(setMode);
+    setModeRef.current = setMode;
+    const setTabRef = (0, react_1.useRef)(setTab);
+    setTabRef.current = setTab;
+    // ---- Initial load: URL → store ----
+    (0, react_1.useEffect)(() => {
+        if (initialized.current) {
+            return;
+        }
+        initialized.current = true;
+        const parsed = parseUrlHash(window.location.hash, configRef.current);
+        if (parsed) {
+            isApplyingUrl.current = true;
+            setModeRef.current(parsed.mode);
+            setTabRef.current(parsed.tab);
+            isApplyingUrl.current = false;
+        }
+        else {
+            // No valid hash — write current state to URL
+            const hash = encodeUrlHash(modeRef.current, activeTabRef.current);
+            window.history.replaceState(null, '', hash);
+        }
+        // Intentionally empty: this effect must run exactly once on mount.
+        // All values are accessed via refs to avoid stale closures.
+    }, []);
+    // ---- Store → URL: push history on navigation changes ----
+    (0, react_1.useEffect)(() => {
+        if (isApplyingUrl.current) {
+            return;
+        }
+        const hash = encodeUrlHash(mode, activeTab);
+        if (window.location.hash !== hash) {
+            window.history.pushState(null, '', hash);
+        }
+    }, [mode, activeTab]);
+    // ---- URL → store: handle popstate (back/forward) ----
+    (0, react_1.useEffect)(() => {
+        const handlePopState = () => {
+            const parsed = parseUrlHash(window.location.hash, config);
+            if (parsed) {
+                isApplyingUrl.current = true;
+                setMode(parsed.mode);
+                setTab(parsed.tab);
+                isApplyingUrl.current = false;
+            }
+        };
+        window.addEventListener('popstate', handlePopState);
+        return () => {
+            window.removeEventListener('popstate', handlePopState);
+        };
+    }, [config, setMode, setTab]);
+}
+//# sourceMappingURL=useUrlSync.js.map

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@fgv/ts-app-shell",
+  "version": "5.1.0-1",
+  "description": "Shared React UI primitives for application shells: column cascade, sidebar, toast/log messages, command palette, keybinding registry",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "scripts": {
+    "build": "heft build --clean",
+    "clean": "heft clean",
+    "test": "heft test --clean",
+    "lint": "eslint src --ext .ts,.tsx",
+    "fixlint": "eslint src --ext .ts,.tsx --fix",
+    "coverage": "jest --coverage"
+  },
+  "sideEffects": false,
+  "keywords": [
+    "typescript",
+    "react",
+    "components",
+    "app-shell",
+    "ui"
+  ],
+  "author": "Erik Fortune",
+  "license": "MIT",
+  "dependencies": {
+    "@fgv/ts-utils": "workspace:*",
+    "@heroicons/react": "~2.2.0",
+    "tslib": "^2.8.1",
+    "@fgv/ts-extras": "workspace:*"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@fgv/heft-dual-rig": "workspace:*",
+    "@fgv/ts-utils-jest": "workspace:*",
+    "@types/react": "~19.2.8",
+    "@types/react-dom": "~19.2.3",
+    "react": "~19.2.3",
+    "react-dom": "~19.2.3",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.14.9",
+    "@typescript-eslint/eslint-plugin": "^8.52.0",
+    "@typescript-eslint/parser": "^8.52.0",
+    "eslint": "^9.39.2",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-node": "^11.1.0",
+    "eslint-plugin-promise": "^7.2.1",
+    "eslint-plugin-react": "^7.34.0",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "jest": "^29.7.0",
+    "@testing-library/react": "^16",
+    "@testing-library/user-event": "^14.6.1",
+    "@testing-library/jest-dom": "^6.4.2",
+    "rimraf": "^6.1.2",
+    "ts-jest": "^29.4.6",
+    "typescript": "5.9.3",
+    "@rushstack/heft": "1.2.6",
+    "@rushstack/eslint-config": "4.6.4",
+    "@rushstack/heft-jest-plugin": "1.2.6",
+    "@testing-library/dom": "^10.4.0",
+    "@rushstack/heft-node-rig": "2.11.26"
+  },
+  "exports": {
+    ".": {
+      "node": {
+        "import": "./lib/index.js",
+        "require": "./lib/index.js"
+      },
+      "default": {
+        "import": "./lib/index.browser.js",
+        "require": "./lib/index.browser.js"
+      },
+      "types": "lib/index.d.ts"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ErikFortune/fgv.git"
+  }
+}