@fgv/ts-app-shell 5.1.0-1

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

@@ -0,0 +1,111 @@
+import { type Result } from '@fgv/ts-utils';
+import type { CascadeColumnMode, ICascadeEntryBase } from './model';
+/**
+ * Describes a located entry in the cascade stack.
+ * @public
+ */
+export interface ICascadeFind<TEntry extends ICascadeEntryBase = ICascadeEntryBase> {
+    readonly depth: number;
+    readonly entry: TEntry;
+}
+/**
+ * Describes editors that would be affected by a cascade operation.
+ * Returned by {@link ICascadeOps.openEditor} when the operation is blocked.
+ * @public
+ */
+export interface ICascadeConflict<TEntry extends ICascadeEntryBase = ICascadeEntryBase> {
+    readonly conflictingEditors: ReadonlyArray<ICascadeFind<TEntry>>;
+}
+/**
+ * Partial cascade entry for operations that set mode and origin automatically.
+ * @public
+ */
+export type CascadeEntrySpec<TEntry extends ICascadeEntryBase = ICascadeEntryBase> = Omit<TEntry, 'mode' | 'origin'> & {
+    readonly mode?: CascadeColumnMode;
+};
+/**
+ * Semantic cascade operations.
+ *
+ * These operations encode the cascade navigation rules:
+ * 1. Views stack on views
+ * 2. Editor replaces its view and trims views above (but not below)
+ * 3. Editors never squash editors — blocked if editors exist above target
+ * 4. Editors can stack on editors (child above parent is fine)
+ * 5. Save/cancel on nested panels pops; on primary panels returns to view
+ * 6. Preview behaves like view for all stacking/trimming rules
+ * 7. Save/cancel blocked when child editors exist above
+ *
+ * @typeParam TEntry - The cascade entry type, defaults to {@link ICascadeEntryBase}.
+ * @public
+ */
+export interface ICascadeOps<TEntry extends ICascadeEntryBase = ICascadeEntryBase> {
+    /**
+     * Replace entire stack with a single view entry (from list selection).
+     * @returns The created entry at depth 0.
+     */
+    readonly select: (entry: CascadeEntrySpec<TEntry>) => Result<ICascadeFind<TEntry>>;
+    /**
+     * Push a view entry after `fromDepth`, trimming anything beyond.
+     * Toggle: if the same entity is already at `fromDepth + 1`, collapse instead.
+     * @returns The pushed entry, or the collapsed entry on toggle.
+     */
+    readonly drillDown: (fromDepth: number, entry: CascadeEntrySpec<TEntry>) => Result<ICascadeFind<TEntry>>;
+    /**
+     * Switch panel at `depth` to edit mode.
+     * Trims view/preview panels above `depth`. Blocked if editors/creates exist above.
+     * @returns The entry switched to edit mode, or failure if blocked by conflicting editors.
+     */
+    readonly openEditor: (depth: number) => Result<ICascadeFind<TEntry>>;
+    /**
+     * Push a nested panel (create or edit) on top of the current stack.
+     * Used for typeahead-on-blur creation and sub-entity editing.
+     * @returns The pushed nested entry.
+     */
+    readonly openNested: (fromDepth: number, entry: Omit<TEntry, 'origin'>) => Result<ICascadeFind<TEntry>>;
+    /**
+     * Pop the topmost entry (for nested save/cancel). Always safe.
+     * @returns The removed entry, or failure if the stack was empty.
+     */
+    readonly pop: () => Result<ICascadeFind<TEntry>>;
+    /**
+     * Transition entry at `depth` from edit/create to view mode.
+     * Used for primary entity save/cancel.
+     * @returns The entry transitioned to view mode.
+     */
+    readonly popToView: (depth: number, refreshedEntity?: unknown) => Result<ICascadeFind<TEntry>>;
+    /**
+     * Trim the stack to keep only entries below `depth` (exclusive).
+     * Removes the entry at `depth` and everything above it.
+     * @returns The last remaining entry after trimming, or failure if stack becomes empty.
+     */
+    readonly trimTo: (depth: number) => Result<ICascadeFind<TEntry>>;
+    /** Return editors/creates above a given depth. */
+    readonly editorsAbove: (depth: number) => ReadonlyArray<ICascadeFind<TEntry>>;
+    /** Whether any editors/creates exist anywhere in the stack. */
+    readonly hasUnsavedEditors: () => boolean;
+    /** Whether save/cancel is allowed at `depth` (false if child editors exist above). */
+    readonly canSaveOrCancel: (depth: number) => boolean;
+    /** Clear the entire cascade stack. */
+    readonly clear: () => void;
+    /** Clear the cascade if any entry has the given entity ID. */
+    readonly clearById: (entityId: string) => void;
+    /** Clear the cascade if any entry matches the predicate. */
+    readonly clearIf: (predicate: (entry: TEntry) => boolean) => void;
+    /** Find the first entry matching a predicate. */
+    readonly find: (predicate: (entry: TEntry) => boolean) => Result<ICascadeFind<TEntry>>;
+    /** The current cascade stack (for rendering). */
+    readonly stack: ReadonlyArray<TEntry>;
+}
+/**
+ * Hook providing semantic cascade operations.
+ *
+ * Takes the cascade stack and a squash function as parameters, making it
+ * independent of any specific state management solution. Domain-specific
+ * applications typically provide a convenience wrapper that reads these
+ * values from their own store.
+ *
+ * @typeParam TEntry - The cascade entry type. Inferred from `cascadeStack`.
+ * @public
+ */
+export declare function useCascadeOps<TEntry extends ICascadeEntryBase>(cascadeStack: ReadonlyArray<TEntry>, squashCascade: (entries: ReadonlyArray<TEntry>) => void): ICascadeOps<TEntry>;
+//# sourceMappingURL=useCascadeOps.d.ts.map

package/lib/packlets/cascade/useCascadeOps.js

@@ -0,0 +1,209 @@
+"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 = useCascadeOps;
+/**
+ * Semantic cascade operations hook.
+ *
+ * Encodes cascade navigation rules so tabs declare intent (select, drillDown,
+ * openEditor, pop) rather than manually computing cascade stacks.
+ *
+ * The hook is generic over the entry type `TEntry extends ICascadeEntryBase`.
+ * Domain-specific applications pass their extended entry type to preserve
+ * full type information through the cascade operations.
+ *
+ * @packageDocumentation
+ */
+const react_1 = require("react");
+const ts_utils_1 = require("@fgv/ts-utils");
+// ============================================================================
+// Helpers
+// ============================================================================
+function isEditOrCreate(mode) {
+    return mode === 'edit' || mode === 'create';
+}
+function findEditorsAbove(stack, depth) {
+    const result = [];
+    for (let i = depth + 1; i < stack.length; i++) {
+        if (isEditOrCreate(stack[i].mode)) {
+            result.push({ depth: i, entry: stack[i] });
+        }
+    }
+    return result;
+}
+// ============================================================================
+// Hook
+// ============================================================================
+/**
+ * Hook providing semantic cascade operations.
+ *
+ * Takes the cascade stack and a squash function as parameters, making it
+ * independent of any specific state management solution. Domain-specific
+ * applications typically provide a convenience wrapper that reads these
+ * values from their own store.
+ *
+ * @typeParam TEntry - The cascade entry type. Inferred from `cascadeStack`.
+ * @public
+ */
+function useCascadeOps(cascadeStack, squashCascade) {
+    const asTEntry = (entry) => entry;
+    const select = (0, react_1.useCallback)((entry) => {
+        var _a;
+        const created = asTEntry(Object.assign(Object.assign({}, entry), { mode: (_a = entry.mode) !== null && _a !== void 0 ? _a : 'view', origin: 'primary' }));
+        squashCascade([created]);
+        return (0, ts_utils_1.succeed)({ depth: 0, entry: created });
+    }, 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [squashCascade]);
+    const drillDown = (0, react_1.useCallback)((fromDepth, entry) => {
+        var _a;
+        const nextEntry = cascadeStack[fromDepth + 1];
+        if ((nextEntry === null || nextEntry === void 0 ? void 0 : nextEntry.entityType) === entry.entityType && nextEntry.entityId === entry.entityId) {
+            // Toggle: collapse if same entity is already at fromDepth + 1
+            squashCascade(cascadeStack.slice(0, fromDepth + 1));
+            return (0, ts_utils_1.succeed)({ depth: fromDepth + 1, entry: nextEntry });
+        }
+        const created = asTEntry(Object.assign(Object.assign({}, entry), { mode: (_a = entry.mode) !== null && _a !== void 0 ? _a : 'view', origin: 'nested' }));
+        squashCascade([...cascadeStack.slice(0, fromDepth + 1), created]);
+        return (0, ts_utils_1.succeed)({ depth: fromDepth + 1, entry: created });
+    }, 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [cascadeStack, squashCascade]);
+    const editorsAbove = (0, react_1.useCallback)((depth) => {
+        return findEditorsAbove(cascadeStack, depth);
+    }, [cascadeStack]);
+    const openEditor = (0, react_1.useCallback)((depth) => {
+        const entry = cascadeStack[depth];
+        if (!entry) {
+            return (0, ts_utils_1.fail)(`depth ${depth} out of bounds for cascade stack of length ${cascadeStack.length}`);
+        }
+        // Check for editors above the target depth
+        const conflicts = findEditorsAbove(cascadeStack, depth);
+        if (conflicts.length > 0) {
+            const names = conflicts.map((c) => `${c.entry.entityType}(${c.entry.mode}) at depth ${c.depth}`);
+            return (0, ts_utils_1.fail)(`blocked by editors above: ${names.join(', ')}`);
+        }
+        // Trim everything above depth (downstream views become incoherent),
+        // switch target to edit mode, preserving origin
+        const edited = asTEntry(Object.assign(Object.assign({}, entry), { mode: 'edit' }));
+        squashCascade([...cascadeStack.slice(0, depth), edited]);
+        return (0, ts_utils_1.succeed)({ depth, entry: edited });
+    }, 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [cascadeStack, squashCascade]);
+    const openNested = (0, react_1.useCallback)((fromDepth, entry) => {
+        const created = asTEntry(Object.assign(Object.assign({}, entry), { origin: 'nested' }));
+        const newDepth = fromDepth + 1;
+        squashCascade([...cascadeStack.slice(0, newDepth), created]);
+        return (0, ts_utils_1.succeed)({ depth: newDepth, entry: created });
+    }, 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [cascadeStack, squashCascade]);
+    const pop = (0, react_1.useCallback)(() => {
+        if (cascadeStack.length === 0) {
+            return (0, ts_utils_1.fail)('cannot pop from empty cascade stack');
+        }
+        const removed = cascadeStack[cascadeStack.length - 1];
+        squashCascade(cascadeStack.slice(0, -1));
+        return (0, ts_utils_1.succeed)({ depth: cascadeStack.length - 1, entry: removed });
+    }, [cascadeStack, squashCascade]);
+    const popToView = (0, react_1.useCallback)((depth, refreshedEntity) => {
+        const entry = cascadeStack[depth];
+        if (!entry) {
+            return (0, ts_utils_1.fail)(`depth ${depth} out of bounds for cascade stack of length ${cascadeStack.length}`);
+        }
+        const viewed = asTEntry(Object.assign(Object.assign(Object.assign({}, entry), { mode: 'view' }), (refreshedEntity !== undefined ? { entity: refreshedEntity } : {})));
+        squashCascade([...cascadeStack.slice(0, depth), viewed]);
+        return (0, ts_utils_1.succeed)({ depth, entry: viewed });
+    }, 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [cascadeStack, squashCascade]);
+    const trimTo = (0, react_1.useCallback)((depth) => {
+        const trimmed = Math.max(0, depth);
+        const newStack = cascadeStack.slice(0, trimmed);
+        squashCascade(newStack);
+        if (newStack.length === 0) {
+            return (0, ts_utils_1.fail)('cascade stack is empty after trim');
+        }
+        const lastIdx = newStack.length - 1;
+        return (0, ts_utils_1.succeed)({ depth: lastIdx, entry: newStack[lastIdx] });
+    }, [cascadeStack, squashCascade]);
+    const hasUnsavedEditors = (0, react_1.useCallback)(() => {
+        return cascadeStack.some((e) => isEditOrCreate(e.mode));
+    }, [cascadeStack]);
+    const canSaveOrCancel = (0, react_1.useCallback)((depth) => {
+        return findEditorsAbove(cascadeStack, depth).length === 0;
+    }, [cascadeStack]);
+    const clear = (0, react_1.useCallback)(() => {
+        squashCascade([]);
+    }, [squashCascade]);
+    const clearIf = (0, react_1.useCallback)((predicate) => {
+        if (cascadeStack.some(predicate)) {
+            squashCascade([]);
+        }
+    }, [cascadeStack, squashCascade]);
+    const clearById = (0, react_1.useCallback)((entityId) => {
+        clearIf((e) => e.entityId === entityId);
+    }, [clearIf]);
+    const find = (0, react_1.useCallback)((predicate) => {
+        const depth = cascadeStack.findIndex(predicate);
+        if (depth < 0) {
+            return (0, ts_utils_1.fail)('no matching entry in cascade stack');
+        }
+        return (0, ts_utils_1.succeed)({ depth, entry: cascadeStack[depth] });
+    }, [cascadeStack]);
+    return (0, react_1.useMemo)(() => ({
+        select,
+        drillDown,
+        openEditor,
+        openNested,
+        pop,
+        popToView,
+        trimTo,
+        editorsAbove,
+        hasUnsavedEditors,
+        canSaveOrCancel,
+        clear,
+        clearById,
+        clearIf,
+        find,
+        stack: cascadeStack
+    }), [
+        select,
+        drillDown,
+        openEditor,
+        openNested,
+        pop,
+        popToView,
+        trimTo,
+        editorsAbove,
+        hasUnsavedEditors,
+        canSaveOrCancel,
+        clear,
+        clearById,
+        clearIf,
+        find,
+        cascadeStack
+    ]);
+}
+//# sourceMappingURL=useCascadeOps.js.map

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

@@ -0,0 +1,19 @@
+import type { ICascadeEntryBase } from './model';
+/**
+ * Returns a depth-aware squash helper used by cascade views.
+ *
+ * Keeps stack entries up to and including `depth`, then appends `entry`.
+ *
+ * @public
+ */
+export declare function useSquashAt(cascadeStack: ReadonlyArray<ICascadeEntryBase>, squashCascade: (entries: ReadonlyArray<ICascadeEntryBase>) => void): (depth: number, entry: ICascadeEntryBase) => void;
+/**
+ * Returns a shared drill-down toggle helper for cascade columns.
+ *
+ * If the target entry is already immediately to the right of `depth`, it collapses
+ * back to `depth`. Otherwise, it appends a new view entry at `depth + 1`.
+ *
+ * @public
+ */
+export declare function useCascadeDrillDown(cascadeStack: ReadonlyArray<ICascadeEntryBase>, squashCascade: (entries: ReadonlyArray<ICascadeEntryBase>) => void, squashAt: (depth: number, entry: ICascadeEntryBase) => void): (depth: number, entityType: string, entityId: string, extra?: Partial<ICascadeEntryBase>) => void;
+//# sourceMappingURL=useCascadeTransitions.d.ts.map

package/lib/packlets/cascade/useCascadeTransitions.js

@@ -0,0 +1,62 @@
+"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.useSquashAt = useSquashAt;
+exports.useCascadeDrillDown = useCascadeDrillDown;
+/**
+ * Shared cascade transition hooks for entity tabs.
+ *
+ * @packageDocumentation
+ */
+const react_1 = require("react");
+/**
+ * Returns a depth-aware squash helper used by cascade views.
+ *
+ * Keeps stack entries up to and including `depth`, then appends `entry`.
+ *
+ * @public
+ */
+function useSquashAt(cascadeStack, squashCascade) {
+    return (0, react_1.useCallback)((depth, entry) => {
+        squashCascade([...cascadeStack.slice(0, depth + 1), entry]);
+    }, [cascadeStack, squashCascade]);
+}
+/**
+ * Returns a shared drill-down toggle helper for cascade columns.
+ *
+ * If the target entry is already immediately to the right of `depth`, it collapses
+ * back to `depth`. Otherwise, it appends a new view entry at `depth + 1`.
+ *
+ * @public
+ */
+function useCascadeDrillDown(cascadeStack, squashCascade, squashAt) {
+    return (0, react_1.useCallback)((depth, entityType, entityId, extra) => {
+        const nextEntry = cascadeStack[depth + 1];
+        if ((nextEntry === null || nextEntry === void 0 ? void 0 : nextEntry.entityType) === entityType && nextEntry.entityId === entityId) {
+            squashCascade(cascadeStack.slice(0, depth + 1));
+            return;
+        }
+        squashAt(depth, Object.assign({ entityType, entityId, mode: 'view' }, extra));
+    }, [cascadeStack, squashAt, squashCascade]);
+}
+//# sourceMappingURL=useCascadeTransitions.js.map

package/lib/packlets/detail/DetailHelpers.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Generic detail-view primitive components.
+ *
+ * Domain-agnostic building blocks for entity detail panels:
+ * - `DetailSection` — labeled section wrapper
+ * - `DetailRow` — key/value row with spread or inline layout
+ * - `TagList` — pill tag row
+ * - `StatusBadge` — colored pill badge (caller supplies color classes)
+ * - `DetailHeader` — two-line header with indicators and action slots
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+export interface IDetailSectionProps {
+    readonly title: string;
+    readonly children: React.ReactNode;
+}
+/**
+ * Labeled section wrapper with uppercase tracking header.
+ * @public
+ */
+export declare function DetailSection({ title, children }: IDetailSectionProps): React.ReactElement;
+export interface IDetailRowProps {
+    readonly label: string;
+    readonly value: React.ReactNode;
+    /**
+     * Layout variant:
+     * - `'spread'` (default) — label left, value right, justify-between
+     * - `'inline'` — label fixed-width, value follows immediately
+     */
+    readonly layout?: 'spread' | 'inline';
+}
+/**
+ * Key/value row for detail panels.
+ * Returns `null` if `value` is `null` or `undefined`.
+ * @public
+ */
+export declare function DetailRow({ label, value, layout }: IDetailRowProps): React.ReactElement | null;
+export interface ITagListProps {
+    readonly tags: ReadonlyArray<string>;
+}
+/**
+ * Horizontal pill row for string tags. Returns `null` if tags is empty.
+ * @public
+ */
+export declare function TagList({ tags }: ITagListProps): React.ReactElement | null;
+export interface IStatusBadgeProps {
+    readonly label: string;
+    /** Tailwind color classes, e.g. `'bg-amber-100 text-amber-800'` */
+    readonly colorClass: string;
+}
+/**
+ * Generic pill badge. Caller supplies the Tailwind color classes.
+ * @public
+ */
+export declare function StatusBadge({ label, colorClass }: IStatusBadgeProps): React.ReactElement;
+export interface IDetailHeaderProps {
+    /** Primary entity name — rendered full-width on its own line */
+    readonly title: string;
+    /** Optional de-emphasized subtitle (e.g. entity ID) rendered below the title */
+    readonly subtitle?: string;
+    /** Optional description rendered below the status bar */
+    readonly description?: string;
+    /** Left slot of the status bar — badges, icons, etc. */
+    readonly indicators?: React.ReactNode;
+    /** Right slot of the status bar — action buttons */
+    readonly actions?: React.ReactNode;
+    /** If provided, renders a close button in the upper-right corner, inline with the title */
+    readonly onClose?: () => void;
+}
+/**
+ * Three-line entity detail header.
+ *
+ * Line 1: full-width `title` (bold headline)
+ * Line 2: optional `subtitle` (de-emphasized, monospace — e.g. entity ID)
+ * Line 3: `indicators` left-justified, `actions` right-justified (status bar)
+ * Below: optional `description`
+ *
+ * Both `indicators` and `actions` are `React.ReactNode` — callers own the content.
+ * @public
+ */
+export declare function DetailHeader({ title, subtitle, description, indicators, actions, onClose }: IDetailHeaderProps): React.ReactElement;
+//# sourceMappingURL=DetailHelpers.d.ts.map

package/lib/packlets/detail/DetailHelpers.js

@@ -0,0 +1,113 @@
+"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.DetailSection = DetailSection;
+exports.DetailRow = DetailRow;
+exports.TagList = TagList;
+exports.StatusBadge = StatusBadge;
+exports.DetailHeader = DetailHeader;
+/**
+ * Generic detail-view primitive components.
+ *
+ * Domain-agnostic building blocks for entity detail panels:
+ * - `DetailSection` — labeled section wrapper
+ * - `DetailRow` — key/value row with spread or inline layout
+ * - `TagList` — pill tag row
+ * - `StatusBadge` — colored pill badge (caller supplies color classes)
+ * - `DetailHeader` — two-line header with indicators and action slots
+ *
+ * @packageDocumentation
+ */
+const react_1 = __importDefault(require("react"));
+const solid_1 = require("@heroicons/react/20/solid");
+/**
+ * Labeled section wrapper with uppercase tracking header.
+ * @public
+ */
+function DetailSection({ title, children }) {
+    return (react_1.default.createElement("div", { className: "mb-4" },
+        react_1.default.createElement("h3", { className: "text-xs font-semibold text-muted uppercase tracking-wider mb-1.5" }, title),
+        children));
+}
+/**
+ * Key/value row for detail panels.
+ * Returns `null` if `value` is `null` or `undefined`.
+ * @public
+ */
+function DetailRow({ label, value, layout = 'spread' }) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    if (layout === 'inline') {
+        return (react_1.default.createElement("div", { className: "flex items-baseline gap-2 py-0.5" },
+            react_1.default.createElement("span", { className: "text-xs text-muted w-32 shrink-0" }, label),
+            react_1.default.createElement("span", { className: "text-sm text-primary" }, value)));
+    }
+    return (react_1.default.createElement("div", { className: "flex items-baseline justify-between py-0.5 text-sm" },
+        react_1.default.createElement("span", { className: "text-muted shrink-0 mr-2" }, label),
+        react_1.default.createElement("span", { className: "text-primary text-right" }, value)));
+}
+/**
+ * Horizontal pill row for string tags. Returns `null` if tags is empty.
+ * @public
+ */
+function TagList({ tags }) {
+    if (tags.length === 0) {
+        return null;
+    }
+    return (react_1.default.createElement("div", { className: "flex flex-wrap gap-1" }, tags.map((tag) => (react_1.default.createElement("span", { key: tag, className: "px-2 py-0.5 text-xs rounded-full bg-surface-raised text-secondary" }, tag)))));
+}
+/**
+ * Generic pill badge. Caller supplies the Tailwind color classes.
+ * @public
+ */
+function StatusBadge({ label, colorClass }) {
+    return (react_1.default.createElement("span", { className: `inline-block px-2 py-0.5 text-[11px] font-medium rounded-full ${colorClass}` }, label));
+}
+/**
+ * Three-line entity detail header.
+ *
+ * Line 1: full-width `title` (bold headline)
+ * Line 2: optional `subtitle` (de-emphasized, monospace — e.g. entity ID)
+ * Line 3: `indicators` left-justified, `actions` right-justified (status bar)
+ * Below: optional `description`
+ *
+ * Both `indicators` and `actions` are `React.ReactNode` — callers own the content.
+ * @public
+ */
+function DetailHeader({ title, subtitle, description, indicators, actions, onClose }) {
+    return (react_1.default.createElement("div", { className: "mb-4 relative" },
+        react_1.default.createElement("div", { className: "flex items-start" },
+            react_1.default.createElement("h2", { className: "text-lg font-semibold text-primary flex-1 min-w-0" }, title),
+            onClose && (react_1.default.createElement("button", { type: "button", onClick: onClose, title: "Close", className: "shrink-0 ml-2 mt-0.5 p-0.5 text-muted hover:text-secondary hover:bg-surface-raised rounded transition-colors" },
+                react_1.default.createElement(solid_1.XMarkIcon, { className: "w-4 h-4" })))),
+        subtitle && react_1.default.createElement("p", { className: "text-xs text-muted font-mono mt-0.5 mb-1" }, subtitle),
+        (indicators !== undefined || actions !== undefined) && (react_1.default.createElement("div", { className: "flex items-center justify-between gap-2 mt-1" },
+            react_1.default.createElement("div", { className: "flex items-center gap-2" }, indicators),
+            actions !== undefined && react_1.default.createElement("div", { className: "flex items-center gap-1 shrink-0" }, actions))),
+        description && react_1.default.createElement("p", { className: "text-sm text-secondary mt-1" }, description)));
+}
+//# sourceMappingURL=DetailHelpers.js.map

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

@@ -0,0 +1,6 @@
+/**
+ * Detail packlet - generic detail-view primitive components.
+ * @packageDocumentation
+ */
+export { DetailSection, type IDetailSectionProps, DetailRow, type IDetailRowProps, TagList, type ITagListProps, StatusBadge, type IStatusBadgeProps, DetailHeader, type IDetailHeaderProps } from './DetailHelpers';
+//# sourceMappingURL=index.d.ts.map

package/lib/packlets/detail/index.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * Detail packlet - generic detail-view primitive components.
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DetailHeader = exports.StatusBadge = exports.TagList = exports.DetailRow = exports.DetailSection = void 0;
+var DetailHelpers_1 = require("./DetailHelpers");
+Object.defineProperty(exports, "DetailSection", { enumerable: true, get: function () { return DetailHelpers_1.DetailSection; } });
+Object.defineProperty(exports, "DetailRow", { enumerable: true, get: function () { return DetailHelpers_1.DetailRow; } });
+Object.defineProperty(exports, "TagList", { enumerable: true, get: function () { return DetailHelpers_1.TagList; } });
+Object.defineProperty(exports, "StatusBadge", { enumerable: true, get: function () { return DetailHelpers_1.StatusBadge; } });
+Object.defineProperty(exports, "DetailHeader", { enumerable: true, get: function () { return DetailHelpers_1.DetailHeader; } });
+//# sourceMappingURL=index.js.map

package/lib/packlets/drop-zone/JsonDropZone.d.ts

@@ -0,0 +1,40 @@
+import React from 'react';
+import { Converter } from '@fgv/ts-utils';
+/**
+ * Strips markdown code fences from text.
+ * AI agents often wrap JSON in code fences.
+ * @param text - Raw text that may contain code fences
+ * @returns Text with outer code fences removed
+ * @internal
+ */
+export declare function stripCodeFences(text: string): string;
+/**
+ * Props for the JsonDropZone component.
+ * @typeParam T - The expected validated type
+ * @public
+ */
+export interface IJsonDropZoneProps<T> {
+    /** Converter to validate parsed JSON against */
+    readonly converter: Converter<T>;
+    /** Called with the validated value on successful drop/paste */
+    readonly onValueReceived: (value: T) => void;
+    /** Called with an error message on parse/validation failure */
+    readonly onError?: (message: string) => void;
+    /** Externally-controlled error message to display */
+    readonly error?: string;
+    /** Placeholder hint text */
+    readonly hint?: string;
+    /** Additional CSS class names */
+    readonly className?: string;
+}
+/**
+ * Generic JSON drop/paste target with converter-based validation.
+ * Accepts text via drag-and-drop or paste, strips markdown code fences,
+ * parses as JSON, validates through the provided converter, and calls
+ * the appropriate callback.
+ *
+ * @typeParam T - The expected validated type
+ * @public
+ */
+export declare function JsonDropZone<T>(props: IJsonDropZoneProps<T>): React.ReactElement;
+//# sourceMappingURL=JsonDropZone.d.ts.map