@fgv/ts-app-shell 5.1.0-1

package/lib/packlets/cascade/CascadeContainer.js

@@ -0,0 +1,119 @@
+"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.CascadeContainer = CascadeContainer;
+/**
+ * Column cascade container — horizontal scroll of detail columns.
+ * @packageDocumentation
+ */
+const react_1 = __importStar(require("react"));
+const responsive_1 = require("../responsive");
+const MobileCascadeStack_1 = require("./MobileCascadeStack");
+// ============================================================================
+// CascadeContainer Component
+// ============================================================================
+/**
+ * Horizontal scroll container for the column cascade.
+ *
+ * Renders a breadcrumb trail at the top and horizontally-scrollable
+ * detail columns below. Auto-scrolls to the rightmost column when
+ * a new column is pushed.
+ *
+ * @public
+ */
+function CascadeContainer(props) {
+    const { columns, onPopTo, minColumnWidth = '400px', onFocus, rootLabel = 'List' } = props;
+    const { layoutMode } = (0, responsive_1.useResponsive)();
+    const scrollRef = (0, react_1.useRef)(null);
+    const handleMouseDown = (0, react_1.useCallback)(() => {
+        onFocus === null || onFocus === void 0 ? void 0 : onFocus();
+    }, [onFocus]);
+    const handleKeyDown = (0, react_1.useCallback)((e) => {
+        if (e.key === 'Escape' || e.key === 'ArrowLeft') {
+            e.preventDefault();
+            e.stopPropagation();
+            if (columns.length > 1) {
+                onPopTo(columns.length - 1);
+            }
+            else {
+                onPopTo(0);
+            }
+        }
+    }, [columns.length, onPopTo]);
+    // Auto-scroll to rightmost column when columns change
+    (0, react_1.useEffect)(() => {
+        if (scrollRef.current) {
+            scrollRef.current.scrollTo({
+                left: scrollRef.current.scrollWidth,
+                behavior: 'smooth'
+            });
+        }
+    }, [columns.length]);
+    if (layoutMode === 'mobile') {
+        return react_1.default.createElement(MobileCascadeStack_1.MobileCascadeStack, Object.assign({}, props));
+    }
+    if (columns.length === 0) {
+        return null;
+    }
+    return (react_1.default.createElement("div", { className: "flex flex-col flex-1 overflow-hidden outline-none", tabIndex: -1, onKeyDown: handleKeyDown },
+        react_1.default.createElement("div", { className: "flex items-center gap-1 px-3 py-1.5 bg-surface-alt border-b border-border text-xs shrink-0 overflow-x-auto" },
+            react_1.default.createElement("button", { onClick: () => onPopTo(0), className: "text-brand-accent hover:text-brand-primary hover:underline shrink-0" }, rootLabel),
+            columns.map((col, idx) => (react_1.default.createElement(react_1.default.Fragment, { key: col.key },
+                react_1.default.createElement("span", { className: "text-muted shrink-0" }, "/"),
+                idx < columns.length - 1 ? (react_1.default.createElement("button", { onClick: () => onPopTo(idx + 1), className: "text-brand-accent hover:text-brand-primary hover:underline truncate max-w-[200px] shrink-0" }, col.label)) : (react_1.default.createElement("span", { className: "text-secondary font-medium truncate max-w-[200px] shrink-0" }, col.label)))))),
+        react_1.default.createElement("div", { ref: scrollRef, className: "flex flex-1 overflow-x-auto overflow-y-hidden", onMouseDown: handleMouseDown }, columns.map((col) => (react_1.default.createElement("div", { key: col.key, className: "flex flex-col shrink-0 border-r border-border overflow-y-auto", style: { minWidth: minColumnWidth, width: minColumnWidth } }, col.content))))));
+}
+//# sourceMappingURL=CascadeContainer.js.map

package/lib/packlets/cascade/ComparisonView.d.ts

@@ -0,0 +1,35 @@
+/**
+ * ComparisonView — side-by-side read-only comparison of 2–4 entities.
+ * @packageDocumentation
+ */
+import React from 'react';
+/**
+ * A single column in the comparison view.
+ * @public
+ */
+export interface IComparisonColumn {
+    /** Unique key for React reconciliation */
+    readonly key: string;
+    /** Column header label */
+    readonly label: string;
+    /** Column content (typically a detail component) */
+    readonly content: React.ReactNode;
+}
+/**
+ * Props for the ComparisonView component.
+ * @public
+ */
+export interface IComparisonViewProps {
+    /** Columns to compare (2–4) */
+    readonly columns: ReadonlyArray<IComparisonColumn>;
+}
+/**
+ * Side-by-side comparison view for entities.
+ *
+ * Renders 2–4 entity detail views in equal-width columns with
+ * synchronized scrolling (future) and column headers.
+ *
+ * @public
+ */
+export declare function ComparisonView(props: IComparisonViewProps): React.ReactElement;
+//# sourceMappingURL=ComparisonView.d.ts.map

package/lib/packlets/cascade/ComparisonView.js

@@ -0,0 +1,54 @@
+"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.ComparisonView = ComparisonView;
+/**
+ * ComparisonView — side-by-side read-only comparison of 2–4 entities.
+ * @packageDocumentation
+ */
+const react_1 = __importDefault(require("react"));
+// ============================================================================
+// ComparisonView Component
+// ============================================================================
+/**
+ * Side-by-side comparison view for entities.
+ *
+ * Renders 2–4 entity detail views in equal-width columns with
+ * synchronized scrolling (future) and column headers.
+ *
+ * @public
+ */
+function ComparisonView(props) {
+    const { columns } = props;
+    if (columns.length < 2) {
+        return (react_1.default.createElement("div", { className: "flex flex-1 items-center justify-center text-muted text-sm" }, "Select at least 2 items to compare."));
+    }
+    return (react_1.default.createElement("div", { className: "flex flex-1 overflow-hidden" }, columns.map((col) => (react_1.default.createElement("div", { key: col.key, className: "flex flex-col flex-1 min-w-0 border-r border-border last:border-r-0 overflow-hidden" },
+        react_1.default.createElement("div", { className: "px-3 py-1.5 bg-surface-alt border-b border-border shrink-0" },
+            react_1.default.createElement("span", { className: "text-xs font-medium text-secondary truncate block" }, col.label)),
+        react_1.default.createElement("div", { className: "flex-1 overflow-y-auto" }, col.content))))));
+}
+//# sourceMappingURL=ComparisonView.js.map

package/lib/packlets/cascade/EntityTabLayout.d.ts

@@ -0,0 +1,47 @@
+/**
+ * EntityTabLayout — shared layout for entity tab content with list + cascade + collapse-on-focus.
+ * @packageDocumentation
+ */
+import React from 'react';
+import { type ICascadeColumn } from './CascadeContainer';
+import { type IComparisonColumn } from './ComparisonView';
+/**
+ * Props for the EntityTabLayout component.
+ * @public
+ */
+export interface IEntityTabLayoutProps {
+    /** The entity list content (rendered in the collapsible left panel) */
+    readonly list: React.ReactNode;
+    /** Cascade columns to display (empty array = no cascade) */
+    readonly cascadeColumns: ReadonlyArray<ICascadeColumn>;
+    /** Callback to pop the cascade back to a specific depth (0 = clear all) */
+    readonly onPopTo: (depth: number) => void;
+    /** Whether the entity list is currently collapsed */
+    readonly listCollapsed: boolean;
+    /** Callback to collapse the entity list (fired when user clicks inside cascade) */
+    readonly onListCollapse: () => void;
+    /** Whether compare mode is active */
+    readonly compareMode?: boolean;
+    /** Columns for the comparison view (when compare mode is active with 2+ selections) */
+    readonly comparisonColumns?: ReadonlyArray<IComparisonColumn>;
+    /** Whether the comparison view is actively showing (user explicitly triggered) */
+    readonly showingComparison?: boolean;
+    /** Callback to exit the comparison view (back to selection list) */
+    readonly onExitComparison?: () => void;
+    /** Columns for variation comparison (when comparing variations of a single recipe) */
+    readonly variationCompareColumns?: ReadonlyArray<IComparisonColumn>;
+    /** Callback to exit variation comparison mode */
+    readonly onExitVariationCompare?: () => void;
+}
+/**
+ * Shared layout for entity tab content.
+ *
+ * Renders an entity list on the left and a cascade container on the right.
+ * The list stays expanded while browsing (selecting items in the list).
+ * It collapses when the user clicks inside the cascade detail pane,
+ * signaling they are focused on the detail rather than browsing.
+ *
+ * @public
+ */
+export declare function EntityTabLayout(props: IEntityTabLayoutProps): React.ReactElement;
+//# sourceMappingURL=EntityTabLayout.d.ts.map

package/lib/packlets/cascade/EntityTabLayout.js

@@ -0,0 +1,110 @@
+"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.EntityTabLayout = EntityTabLayout;
+/**
+ * EntityTabLayout — shared layout for entity tab content with list + cascade + collapse-on-focus.
+ * @packageDocumentation
+ */
+const react_1 = __importDefault(require("react"));
+const CascadeContainer_1 = require("./CascadeContainer");
+const responsive_1 = require("../responsive");
+const ComparisonView_1 = require("./ComparisonView");
+// ============================================================================
+// EntityTabLayout Component
+// ============================================================================
+/**
+ * Shared layout for entity tab content.
+ *
+ * Renders an entity list on the left and a cascade container on the right.
+ * The list stays expanded while browsing (selecting items in the list).
+ * It collapses when the user clicks inside the cascade detail pane,
+ * signaling they are focused on the detail rather than browsing.
+ *
+ * @public
+ */
+function EntityTabLayout(props) {
+    var _a;
+    const { list, cascadeColumns, onPopTo, listCollapsed, onListCollapse, compareMode, comparisonColumns } = props;
+    const variationCompareColumns = props.variationCompareColumns;
+    const onExitVariationCompare = props.onExitVariationCompare;
+    const showingComparison = (_a = props.showingComparison) !== null && _a !== void 0 ? _a : false;
+    const onExitComparison = props.onExitComparison;
+    const { layoutMode } = (0, responsive_1.useResponsive)();
+    const isVariationCompare = variationCompareColumns !== undefined && variationCompareColumns.length >= 2;
+    const showComparison = !isVariationCompare &&
+        showingComparison &&
+        comparisonColumns !== undefined &&
+        comparisonColumns.length >= 2;
+    const showCascade = !compareMode && !isVariationCompare && !showComparison && cascadeColumns.length > 0;
+    const hasCascadeOrCompare = cascadeColumns.length > 0 || showComparison;
+    // Variation compare banner — shared between mobile and desktop
+    const variationCompareBanner = isVariationCompare && onExitVariationCompare && (react_1.default.createElement("div", { className: "flex items-center gap-2 px-3 py-1.5 bg-status-warning-bg border-b border-status-warning-border shrink-0" },
+        react_1.default.createElement("span", { className: "text-xs text-status-warning-text" },
+            "Comparing ",
+            variationCompareColumns.length,
+            " variations"),
+        react_1.default.createElement("button", { onClick: onExitVariationCompare, className: "px-2 py-0.5 text-xs rounded border border-status-warning-border text-status-warning-text hover:bg-status-warning-surface transition-colors" }, "Exit")));
+    // Mobile: show one pane at a time — list or cascade/comparison full-screen
+    if (layoutMode === 'mobile') {
+        const hasCascadeContent = showCascade || showComparison || isVariationCompare;
+        return (react_1.default.createElement("div", { className: "flex flex-col flex-1 overflow-hidden" },
+            variationCompareBanner,
+            hasCascadeContent ? (react_1.default.createElement(react_1.default.Fragment, null,
+                showCascade && react_1.default.createElement(CascadeContainer_1.CascadeContainer, { columns: cascadeColumns, onPopTo: onPopTo }),
+                showComparison && (react_1.default.createElement("div", { className: "flex flex-col flex-1 overflow-hidden" },
+                    react_1.default.createElement("div", { className: "flex items-center gap-2 px-3 py-1.5 bg-status-info-bg border-b border-status-info-border shrink-0" },
+                        react_1.default.createElement("span", { className: "text-xs text-status-info-text" },
+                            "Comparing ",
+                            comparisonColumns.length,
+                            " items"),
+                        onExitComparison && (react_1.default.createElement("button", { onClick: onExitComparison, className: "px-2 py-0.5 text-xs rounded border border-status-info-border text-status-info-text hover:bg-status-info-surface transition-colors" }, "\u2190 Back to list"))),
+                    react_1.default.createElement(ComparisonView_1.ComparisonView, { columns: comparisonColumns }))),
+                isVariationCompare && react_1.default.createElement(ComparisonView_1.ComparisonView, { columns: variationCompareColumns }))) : (react_1.default.createElement("div", { className: "flex flex-col flex-1 overflow-hidden" }, list))));
+    }
+    // Desktop/compact: side-by-side list and cascade
+    return (react_1.default.createElement("div", { className: "flex flex-col flex-1 overflow-hidden" },
+        variationCompareBanner,
+        react_1.default.createElement("div", { className: "flex flex-1 overflow-hidden" },
+            react_1.default.createElement("div", { className: `flex flex-col overflow-hidden transition-all ${isVariationCompare || showComparison
+                    ? 'w-0 min-w-0'
+                    : listCollapsed
+                        ? 'w-0 min-w-0'
+                        : hasCascadeOrCompare
+                            ? 'w-1/4 max-w-xs shrink-0 border-r border-border'
+                            : 'w-full max-w-sm shrink-0 border-r border-border'}` }, list),
+            showCascade && (react_1.default.createElement(CascadeContainer_1.CascadeContainer, { columns: cascadeColumns, onPopTo: onPopTo, onFocus: onListCollapse })),
+            showComparison && (react_1.default.createElement("div", { className: "flex flex-col flex-1 overflow-hidden" },
+                react_1.default.createElement("div", { className: "flex items-center gap-2 px-3 py-1.5 bg-status-info-bg border-b border-status-info-border shrink-0" },
+                    react_1.default.createElement("span", { className: "text-xs text-status-info-text" },
+                        "Comparing ",
+                        comparisonColumns.length,
+                        " items"),
+                    onExitComparison && (react_1.default.createElement("button", { onClick: onExitComparison, className: "px-2 py-0.5 text-xs rounded border border-status-info-border text-status-info-text hover:bg-status-info-surface transition-colors" }, "\u2190 Back to list"))),
+                react_1.default.createElement(ComparisonView_1.ComparisonView, { columns: comparisonColumns }))),
+            isVariationCompare && react_1.default.createElement(ComparisonView_1.ComparisonView, { columns: variationCompareColumns }))));
+}
+//# sourceMappingURL=EntityTabLayout.js.map

package/lib/packlets/cascade/MobileCascadeStack.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Mobile view-stack cascade — one full-screen column at a time with back navigation.
+ * @packageDocumentation
+ */
+import React from 'react';
+import { type ICascadeContainerProps } from './CascadeContainer';
+/**
+ * Mobile replacement for {@link CascadeContainer}.
+ *
+ * Shows the rightmost (deepest) cascade column full-screen with a back button
+ * that pops one level at a time. At the first column, back returns to the list
+ * by calling `onPopTo(0)`.
+ *
+ * Accepts the same props as {@link CascadeContainer} so `CascadeContainer` can
+ * delegate to it transparently on mobile.
+ *
+ * @public
+ */
+export declare function MobileCascadeStack(props: ICascadeContainerProps): React.ReactElement | null;
+//# sourceMappingURL=MobileCascadeStack.d.ts.map

package/lib/packlets/cascade/MobileCascadeStack.js

@@ -0,0 +1,99 @@
+"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.MobileCascadeStack = MobileCascadeStack;
+/**
+ * Mobile view-stack cascade — one full-screen column at a time with back navigation.
+ * @packageDocumentation
+ */
+const react_1 = __importStar(require("react"));
+/**
+ * Mobile replacement for {@link CascadeContainer}.
+ *
+ * Shows the rightmost (deepest) cascade column full-screen with a back button
+ * that pops one level at a time. At the first column, back returns to the list
+ * by calling `onPopTo(0)`.
+ *
+ * Accepts the same props as {@link CascadeContainer} so `CascadeContainer` can
+ * delegate to it transparently on mobile.
+ *
+ * @public
+ */
+function MobileCascadeStack(props) {
+    const { columns, onPopTo, rootLabel = 'List' } = props;
+    const handleBack = (0, react_1.useCallback)(() => {
+        if (columns.length > 1) {
+            onPopTo(columns.length - 1);
+        }
+        else {
+            onPopTo(0);
+        }
+    }, [columns.length, onPopTo]);
+    if (columns.length === 0) {
+        return null;
+    }
+    const currentColumn = columns[columns.length - 1];
+    const backLabel = columns.length > 1 ? columns[columns.length - 2].label : rootLabel;
+    return (react_1.default.createElement("div", { className: "flex flex-col flex-1 overflow-hidden" },
+        react_1.default.createElement("div", { className: "flex items-center gap-2 px-3 py-2 bg-surface-alt border-b border-border shrink-0" },
+            react_1.default.createElement("button", { onClick: handleBack, className: "flex items-center gap-1 text-sm text-brand-accent hover:text-brand-primary", "aria-label": `Back to ${backLabel}` },
+                react_1.default.createElement("svg", { className: "w-4 h-4 shrink-0", fill: "none", viewBox: "0 0 24 24", strokeWidth: 2, stroke: "currentColor" },
+                    react_1.default.createElement("path", { strokeLinecap: "round", strokeLinejoin: "round", d: "M15.75 19.5L8.25 12l7.5-7.5" })),
+                backLabel),
+            columns.length > 1 && (react_1.default.createElement("span", { className: "ml-auto text-xs text-muted truncate" }, currentColumn.label))),
+        react_1.default.createElement("div", { className: "flex flex-col flex-1 overflow-y-auto" }, currentColumn.content)));
+}
+//# sourceMappingURL=MobileCascadeStack.js.map

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

@@ -0,0 +1,12 @@
+/**
+ * Cascade packlet - column cascade container, layout, and semantic operations.
+ * @packageDocumentation
+ */
+export { CascadeContainer, type ICascadeContainerProps, type ICascadeColumn } from './CascadeContainer';
+export { MobileCascadeStack } from './MobileCascadeStack';
+export { EntityTabLayout, type IEntityTabLayoutProps } from './EntityTabLayout';
+export { ComparisonView, type IComparisonViewProps, type IComparisonColumn } from './ComparisonView';
+export { type CascadeColumnMode, type CascadeEntryOrigin, type ICascadeEntryBase, CASCADE_NEW_ENTITY_ID } from './model';
+export { useSquashAt, useCascadeDrillDown } from './useCascadeTransitions';
+export { type ICascadeConflict, type ICascadeFind, type CascadeEntrySpec, type ICascadeOps, useCascadeOps } from './useCascadeOps';
+//# sourceMappingURL=index.d.ts.map

package/lib/packlets/cascade/index.js

@@ -0,0 +1,48 @@
+"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.useCascadeOps = exports.useCascadeDrillDown = exports.useSquashAt = exports.CASCADE_NEW_ENTITY_ID = exports.ComparisonView = exports.EntityTabLayout = exports.MobileCascadeStack = exports.CascadeContainer = void 0;
+/**
+ * Cascade packlet - column cascade container, layout, and semantic operations.
+ * @packageDocumentation
+ */
+// UI components
+var CascadeContainer_1 = require("./CascadeContainer");
+Object.defineProperty(exports, "CascadeContainer", { enumerable: true, get: function () { return CascadeContainer_1.CascadeContainer; } });
+var MobileCascadeStack_1 = require("./MobileCascadeStack");
+Object.defineProperty(exports, "MobileCascadeStack", { enumerable: true, get: function () { return MobileCascadeStack_1.MobileCascadeStack; } });
+var EntityTabLayout_1 = require("./EntityTabLayout");
+Object.defineProperty(exports, "EntityTabLayout", { enumerable: true, get: function () { return EntityTabLayout_1.EntityTabLayout; } });
+var ComparisonView_1 = require("./ComparisonView");
+Object.defineProperty(exports, "ComparisonView", { enumerable: true, get: function () { return ComparisonView_1.ComparisonView; } });
+// Cascade model types
+var model_1 = require("./model");
+Object.defineProperty(exports, "CASCADE_NEW_ENTITY_ID", { enumerable: true, get: function () { return model_1.CASCADE_NEW_ENTITY_ID; } });
+// Cascade transition hooks
+var useCascadeTransitions_1 = require("./useCascadeTransitions");
+Object.defineProperty(exports, "useSquashAt", { enumerable: true, get: function () { return useCascadeTransitions_1.useSquashAt; } });
+Object.defineProperty(exports, "useCascadeDrillDown", { enumerable: true, get: function () { return useCascadeTransitions_1.useCascadeDrillDown; } });
+// Semantic cascade operations
+var useCascadeOps_1 = require("./useCascadeOps");
+Object.defineProperty(exports, "useCascadeOps", { enumerable: true, get: function () { return useCascadeOps_1.useCascadeOps; } });
+//# sourceMappingURL=index.js.map

package/lib/packlets/cascade/model.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Base cascade model types for column cascade navigation.
+ *
+ * These types are domain-agnostic — they define the structure and semantics
+ * of cascade navigation without knowledge of specific entity types.
+ * Domain-specific applications extend {@link ICascadeEntryBase} with their
+ * own entity types and additional fields.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Mode for a cascade column (view-only, editing, or creating a new entity).
+ * @public
+ */
+export type CascadeColumnMode = 'view' | 'edit' | 'create' | 'preview';
+/**
+ * How a cascade entry was opened — determines save/cancel behavior.
+ *
+ * - `'primary'` — selected from the entity list. Save/cancel transitions to view mode in-place.
+ * - `'nested'` — reached via drill-down, typeahead-create, or sub-entity editing. Save/cancel pops (removes entry).
+ *
+ * Entries without an explicit origin are treated as `'primary'` for backwards compatibility.
+ * @public
+ */
+export type CascadeEntryOrigin = 'primary' | 'nested';
+/**
+ * Sentinel value used as entityId when creating a new entity.
+ * @public
+ */
+export declare const CASCADE_NEW_ENTITY_ID: '__new__';
+/**
+ * Base interface for a single entry in the column cascade stack.
+ *
+ * This interface contains only the fields needed by the generic cascade
+ * operations ({@link useCascadeOps}, {@link useSquashAt}, {@link useCascadeDrillDown}).
+ * Domain-specific applications should extend this interface with additional
+ * fields (e.g., target weights, source references, session context).
+ *
+ * @public
+ */
+export interface ICascadeEntryBase {
+    /** The type of entity displayed in this column (domain-specific string). */
+    readonly entityType: string;
+    /** The ID of the entity (qualified ID, e.g. 'collection.base-id'). */
+    readonly entityId: string;
+    /** Whether the column is in view, edit, create, or preview mode. */
+    readonly mode: CascadeColumnMode;
+    /** How this entry was opened. Determines save/cancel behavior. @see CascadeEntryOrigin */
+    readonly origin?: CascadeEntryOrigin;
+    /** Optional pre-resolved materialized entity. */
+    readonly entity?: unknown;
+    /** Whether this cascade entry has unsaved changes (set by the owning tab component). */
+    readonly hasChanges?: boolean;
+    /** Pre-fill name for entity creation (set when on-blur typeahead doesn't match). */
+    readonly prefillName?: string;
+}
+//# sourceMappingURL=model.d.ts.map

package/lib/packlets/cascade/model.js

@@ -0,0 +1,33 @@
+"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.CASCADE_NEW_ENTITY_ID = void 0;
+// ============================================================================
+// Cascade Entry Base
+// ============================================================================
+/**
+ * Sentinel value used as entityId when creating a new entity.
+ * @public
+ */
+exports.CASCADE_NEW_ENTITY_ID = '__new__';
+//# sourceMappingURL=model.js.map