@fgv/ts-app-shell 5.1.0-1

package/lib/packlets/print/openPrintWindow.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Opens a popup window for print-optimized content rendering.
+ * @packageDocumentation
+ */
+import React from 'react';
+/**
+ * Options for {@link openPrintWindow}.
+ * @public
+ */
+export interface IPrintWindowOptions {
+    /** Title for the popup window. */
+    readonly title: string;
+    /** Width of the popup window in pixels (default 900). */
+    readonly width?: number;
+    /** Height of the popup window in pixels (default 700). */
+    readonly height?: number;
+    /** Extra toolbar controls to render in the print enclosure header. */
+    readonly toolbarExtras?: React.ReactNode;
+}
+/**
+ * Opens a popup window and renders the given React content inside a
+ * {@link PrintEnclosure} with Print and Close toolbar buttons.
+ *
+ * @remarks
+ * Must be called synchronously from a user click handler to avoid
+ * popup blockers. If the popup is blocked, returns `null`.
+ *
+ * Styles are cloned from the parent document so that Tailwind and other
+ * CSS frameworks work in the popup. An independent React root is created
+ * in the popup (not a portal) so the popup is fully self-contained.
+ *
+ * @public
+ */
+export declare function openPrintWindow(content: React.ReactElement, options: IPrintWindowOptions): Window | null;
+//# sourceMappingURL=openPrintWindow.d.ts.map

package/lib/packlets/print/openPrintWindow.js

@@ -0,0 +1,118 @@
+"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.openPrintWindow = openPrintWindow;
+/**
+ * Opens a popup window for print-optimized content rendering.
+ * @packageDocumentation
+ */
+const react_1 = __importDefault(require("react"));
+const client_1 = require("react-dom/client");
+const PrintEnclosure_1 = require("./PrintEnclosure");
+/**
+ * Clones all stylesheet-related elements from the source document head
+ * into the target document head so that styles are available in the popup.
+ */
+function cloneStyles(source, target) {
+    const styles = Array.from(source.querySelectorAll('style'));
+    for (const style of styles) {
+        target.head.appendChild(style.cloneNode(true));
+    }
+    const links = Array.from(source.querySelectorAll('link[rel="stylesheet"]'));
+    for (const link of links) {
+        target.head.appendChild(link.cloneNode(true));
+    }
+}
+/**
+ * Opens a popup window and renders the given React content inside a
+ * {@link PrintEnclosure} with Print and Close toolbar buttons.
+ *
+ * @remarks
+ * Must be called synchronously from a user click handler to avoid
+ * popup blockers. If the popup is blocked, returns `null`.
+ *
+ * Styles are cloned from the parent document so that Tailwind and other
+ * CSS frameworks work in the popup. An independent React root is created
+ * in the popup (not a portal) so the popup is fully self-contained.
+ *
+ * @public
+ */
+function openPrintWindow(content, options) {
+    const { title, width = 900, height = 700, toolbarExtras } = options;
+    const popup = window.open('', '', `width=${width},height=${height}`);
+    if (!popup) {
+        return null;
+    }
+    popup.document.write(`<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8" />
+  <title>${title.replace(/</g, '&lt;')}</title>
+  <style>
+    @media screen {
+      body {
+        background: #f9fafb;
+        padding: 2rem;
+        margin: 0;
+      }
+    }
+    @media print {
+      body {
+        margin: 0;
+        padding: 0;
+        background: white;
+      }
+      .print-toolbar {
+        display: none !important;
+      }
+      .break-before-page {
+        break-before: page;
+      }
+      .break-inside-avoid {
+        break-inside: avoid;
+      }
+    }
+  </style>
+</head>
+<body>
+  <div id="print-root"></div>
+</body>
+</html>`);
+    popup.document.close();
+    cloneStyles(document, popup.document);
+    const container = popup.document.getElementById('print-root');
+    if (!container) {
+        popup.close();
+        return null;
+    }
+    const root = (0, client_1.createRoot)(container);
+    root.render(react_1.default.createElement(PrintEnclosure_1.PrintEnclosure, { title: title, toolbarExtras: toolbarExtras, popupWindow: popup }, content));
+    popup.addEventListener('beforeunload', () => {
+        root.unmount();
+    });
+    return popup;
+}
+//# sourceMappingURL=openPrintWindow.js.map

package/lib/packlets/responsive/ResponsiveProvider.d.ts

@@ -0,0 +1,35 @@
+import React from 'react';
+import { type IResponsiveLayout, type LayoutMode } from './useResponsiveLayout';
+/**
+ * Props for {@link ResponsiveProvider}.
+ * @public
+ */
+export interface IResponsiveProviderProps {
+    /** Optional layout mode override (for testing or storybook). */
+    readonly forceLayoutMode?: LayoutMode;
+    /** Children */
+    readonly children: React.ReactNode;
+}
+/**
+ * Provides responsive layout information to the component tree via context.
+ *
+ * Wrap your app (or a subtree) with this provider. Descendants use
+ * {@link useResponsive} to read the current layout mode, device type, etc.
+ *
+ * @example
+ * ```tsx
+ * <ResponsiveProvider>
+ *   <App />
+ * </ResponsiveProvider>
+ * ```
+ * @public
+ */
+export declare function ResponsiveProvider({ forceLayoutMode, children }: IResponsiveProviderProps): React.JSX.Element;
+/**
+ * Access the current responsive layout information.
+ *
+ * Must be called within a {@link ResponsiveProvider}.
+ * @public
+ */
+export declare function useResponsive(): IResponsiveLayout;
+//# sourceMappingURL=ResponsiveProvider.d.ts.map

package/lib/packlets/responsive/ResponsiveProvider.js

@@ -0,0 +1,93 @@
+"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.ResponsiveProvider = ResponsiveProvider;
+exports.useResponsive = useResponsive;
+const react_1 = __importStar(require("react"));
+const useResponsiveLayout_1 = require("./useResponsiveLayout");
+const ResponsiveContext = (0, react_1.createContext)(undefined);
+/**
+ * Provides responsive layout information to the component tree via context.
+ *
+ * Wrap your app (or a subtree) with this provider. Descendants use
+ * {@link useResponsive} to read the current layout mode, device type, etc.
+ *
+ * @example
+ * ```tsx
+ * <ResponsiveProvider>
+ *   <App />
+ * </ResponsiveProvider>
+ * ```
+ * @public
+ */
+function ResponsiveProvider({ forceLayoutMode, children }) {
+    const layout = (0, useResponsiveLayout_1.useResponsiveLayout)(forceLayoutMode);
+    return react_1.default.createElement(ResponsiveContext.Provider, { value: layout }, children);
+}
+/**
+ * Access the current responsive layout information.
+ *
+ * Must be called within a {@link ResponsiveProvider}.
+ * @public
+ */
+function useResponsive() {
+    const context = (0, react_1.useContext)(ResponsiveContext);
+    if (!context) {
+        throw new Error('useResponsive must be used within a ResponsiveProvider');
+    }
+    return context;
+}
+//# sourceMappingURL=ResponsiveProvider.js.map

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

@@ -0,0 +1,7 @@
+/**
+ * Responsive layout detection and context provider.
+ * @packageDocumentation
+ */
+export { useResponsiveLayout, type DeviceType, type ScreenOrientation, type LayoutMode, type IResponsiveLayout } from './useResponsiveLayout';
+export { ResponsiveProvider, useResponsive, type IResponsiveProviderProps } from './ResponsiveProvider';
+//# sourceMappingURL=index.d.ts.map

package/lib/packlets/responsive/index.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * Responsive layout detection and context provider.
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useResponsive = exports.ResponsiveProvider = exports.useResponsiveLayout = void 0;
+var useResponsiveLayout_1 = require("./useResponsiveLayout");
+Object.defineProperty(exports, "useResponsiveLayout", { enumerable: true, get: function () { return useResponsiveLayout_1.useResponsiveLayout; } });
+var ResponsiveProvider_1 = require("./ResponsiveProvider");
+Object.defineProperty(exports, "ResponsiveProvider", { enumerable: true, get: function () { return ResponsiveProvider_1.ResponsiveProvider; } });
+Object.defineProperty(exports, "useResponsive", { enumerable: true, get: function () { return ResponsiveProvider_1.useResponsive; } });
+//# sourceMappingURL=index.js.map

package/lib/packlets/responsive/useResponsiveLayout.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Device type detection result.
+ * @public
+ */
+export type DeviceType = 'mobile' | 'tablet' | 'desktop';
+/**
+ * Screen orientation.
+ * @public
+ */
+export type ScreenOrientation = 'portrait' | 'landscape';
+/**
+ * Layout mode that drives structural rendering decisions.
+ * - `full`: Desktop — sidebar visible, cascade columns side-by-side.
+ * - `compact`: Tablet — sidebar as drawer, cascade still horizontal.
+ * - `mobile`: Phone — sidebar as drawer, cascade becomes a view stack.
+ * @public
+ */
+export type LayoutMode = 'full' | 'compact' | 'mobile';
+/**
+ * Responsive layout information exposed by the hook and context.
+ * @public
+ */
+export interface IResponsiveLayout {
+    /** Device type based on screen size and touch capability */
+    readonly deviceType: DeviceType;
+    /** Current screen orientation */
+    readonly orientation: ScreenOrientation;
+    /** Structural layout mode driving component tree decisions */
+    readonly layoutMode: LayoutMode;
+    /** Viewport width in pixels */
+    readonly screenWidth: number;
+    /** Viewport height in pixels */
+    readonly screenHeight: number;
+    /** Whether the device supports touch input */
+    readonly isTouchDevice: boolean;
+}
+/**
+ * Hook that tracks responsive layout information for the current viewport.
+ *
+ * Listens to `resize` and `orientationchange` events and recomputes layout
+ * on every change. Use the `layoutMode` field to drive structural rendering
+ * decisions (e.g., sidebar as drawer vs. fixed panel).
+ *
+ * @param forceLayoutMode - Optional override for testing or storybook use.
+ * @public
+ */
+export declare function useResponsiveLayout(forceLayoutMode?: LayoutMode): IResponsiveLayout;
+//# sourceMappingURL=useResponsiveLayout.d.ts.map

package/lib/packlets/responsive/useResponsiveLayout.js

@@ -0,0 +1,121 @@
+"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.useResponsiveLayout = useResponsiveLayout;
+const react_1 = require("react");
+/**
+ * Breakpoints for responsive design (in CSS pixels).
+ */
+const BREAKPOINTS = {
+    /** At or below this width, use mobile layout */
+    mobile: 640,
+    /** At or below this width, use compact layout */
+    compact: 1024
+};
+/**
+ * Detect if the device supports touch input.
+ */
+function detectTouchSupport() {
+    var _a;
+    return ('ontouchstart' in window ||
+        navigator.maxTouchPoints > 0 ||
+        ((_a = navigator.msMaxTouchPoints) !== null && _a !== void 0 ? _a : 0) > 0);
+}
+/**
+ * Determine device type from viewport dimensions and touch capability.
+ */
+function determineDeviceType(width, isTouch) {
+    if (width <= BREAKPOINTS.mobile) {
+        return 'mobile';
+    }
+    if (width <= BREAKPOINTS.compact && isTouch) {
+        return 'tablet';
+    }
+    return 'desktop';
+}
+/**
+ * Determine the structural layout mode from viewport width.
+ */
+function determineLayoutMode(width) {
+    if (width <= BREAKPOINTS.mobile) {
+        return 'mobile';
+    }
+    if (width <= BREAKPOINTS.compact) {
+        return 'compact';
+    }
+    return 'full';
+}
+/**
+ * Compute the full layout info from current viewport state.
+ */
+function computeLayout(forceLayoutMode) {
+    const width = window.innerWidth;
+    const height = window.innerHeight;
+    const isTouchDevice = detectTouchSupport();
+    const orientation = width > height ? 'landscape' : 'portrait';
+    const deviceType = determineDeviceType(width, isTouchDevice);
+    const layoutMode = forceLayoutMode !== null && forceLayoutMode !== void 0 ? forceLayoutMode : determineLayoutMode(width);
+    return {
+        deviceType,
+        orientation,
+        layoutMode,
+        screenWidth: width,
+        screenHeight: height,
+        isTouchDevice
+    };
+}
+/**
+ * Hook that tracks responsive layout information for the current viewport.
+ *
+ * Listens to `resize` and `orientationchange` events and recomputes layout
+ * on every change. Use the `layoutMode` field to drive structural rendering
+ * decisions (e.g., sidebar as drawer vs. fixed panel).
+ *
+ * @param forceLayoutMode - Optional override for testing or storybook use.
+ * @public
+ */
+function useResponsiveLayout(forceLayoutMode) {
+    const [layout, setLayout] = (0, react_1.useState)(() => computeLayout(forceLayoutMode));
+    (0, react_1.useEffect)(() => {
+        if (forceLayoutMode) {
+            return;
+        }
+        function updateLayout() {
+            setLayout(computeLayout());
+        }
+        window.addEventListener('resize', updateLayout);
+        const onOrientationChange = () => {
+            // Small delay to let the browser update viewport dimensions
+            setTimeout(updateLayout, 100);
+        };
+        window.addEventListener('orientationchange', onOrientationChange);
+        // Sync on mount in case viewport changed between SSR and hydration
+        updateLayout();
+        return () => {
+            window.removeEventListener('resize', updateLayout);
+            window.removeEventListener('orientationchange', onOrientationChange);
+        };
+    }, [forceLayoutMode]);
+    return layout;
+}
+//# sourceMappingURL=useResponsiveLayout.js.map

package/lib/packlets/selectors/EntityRow.d.ts

@@ -0,0 +1,45 @@
+/**
+ * EntityRow — clickable text row with optional discrete swap-icon for alternates.
+ *
+ * Renders a uniform row regardless of whether alternates exist:
+ * - Left slot: swap icon (when alternates exist) or empty spacer
+ * - Name text: clickable for drill-down
+ * - Optional right-side content (amount, sublabel, etc.)
+ * - Drill-down chevron ›
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+import type { ISelectableItem } from './PreferredSelector';
+/**
+ * Props for the EntityRow component.
+ * @public
+ */
+export interface IEntityRowProps<TId extends string = string> {
+    /** All options (preferred + alternates). If length === 1, no swap icon is shown. */
+    readonly items: ReadonlyArray<ISelectableItem<TId>>;
+    /** ID of the preferred/default item (shows ★ marker) */
+    readonly preferredId?: TId;
+    /** Controlled selected ID (overrides internal state). Use with onSelect. */
+    readonly selectedId?: TId;
+    /** Callback when the displayed item changes via the swap picker */
+    readonly onSelect?: (id: TId) => void;
+    /** Callback when the row is clicked (drill-down navigation) */
+    readonly onClick?: (id: TId) => void;
+    /** Callback to compare items. When provided, popover shows compare buttons. */
+    readonly onCompare?: (ids: ReadonlyArray<TId>) => void;
+    /** Optional right-side content rendered before the › chevron */
+    readonly rightContent?: React.ReactNode;
+    /** Optional section label displayed above the row */
+    readonly label?: string;
+}
+/**
+ * A clickable text row with an optional discrete swap-icon popover for
+ * switching between alternates. Clicking the row itself always triggers
+ * drill-down navigation. The swap icon opens a small picker to change
+ * which alternate is displayed.
+ *
+ * @public
+ */
+export declare function EntityRow<TId extends string = string>(props: IEntityRowProps<TId>): React.ReactElement;
+//# sourceMappingURL=EntityRow.d.ts.map