@hoardodile/ui 0.0.0

package/dist/hooks/useMobileBackToClose.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/viewport.ts","../../src/hooks/use-mobile.ts","../../src/hooks/useMobileBackToClose.ts"],"names":[],"mappings":"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","file":"useMobileBackToClose.js","sourcesContent":["/**\n * Mobile viewport initial-scale factor used across the app shell and\n * plugin iframe previews. Kept in one place so it can be changed\n * without hunting through HTML templates and CSS rules.\n */\nexport const MOBILE_INITIAL_SCALE = 0.8\n\n/**\n * Width in pixels at which the app switches from below-md to md+ layouts.\n *\n * This value is intentionally aligned with Tailwind's `md` breakpoint\n * (768 px) so that JS detection and CSS responsive prefixes stay in sync.\n * Components that need to know whether they are in the \"below md\" viewport\n * should use {@link isBelowMd} or {@link useBelowMd} from @hoardodile/ui/hooks/use-mobile.\n */\nexport const MOBILE_BREAKPOINT_PX = 768\n\n/**\n * Same breakpoint expressed in rems, matching Tailwind's default theme\n * (`--breakpoint-md: 48rem`). Useful for CSS media queries and comments.\n */\nexport const MOBILE_BREAKPOINT_REM = MOBILE_BREAKPOINT_PX / 16\n\n/**\n * Media query string that matches viewports below the `md` breakpoint\n * (< 768 px). Shared between JS hooks and anywhere else that needs to detect\n * a below-md viewport.\n *\n * Keep this in sync with the CSS/Tailwind breakpoint so JS and CSS never\n * disagree about the viewport size.\n */\nexport const MOBILE_QUERY = `(max-width: ${MOBILE_BREAKPOINT_PX - 1}px)`\n\n/**\n * Width in pixels at which the app switches from a drawer to a fixed left\n * sidebar (the \"app shell\"). Raised above `md` so mid-size viewports keep\n * the whole width for their content column — below this the sidebar hides\n * behind the hamburger drawer.\n *\n * Use the CSS `sidebar:` / `max-sidebar:` variants (`--breakpoint-sidebar`)\n * at call sites — this value is the single source of truth for both.\n */\nexport const SIDEBAR_BREAKPOINT_PX = 1150\n\n/**\n * Media query string that matches viewports below the sidebar breakpoint\n * (`max-sidebar`), i.e. where the shell shows the drawer instead of the fixed\n * sidebar. Shared between JS hooks and anywhere else that needs the\n * below-sidebar viewport.\n */\nexport const SIDEBAR_QUERY = `(max-width: ${SIDEBAR_BREAKPOINT_PX - 1}px)`\n\n/**\n * Width in pixels at which the right filter rail switches from a fixed\n * column to a drawer (DESIGN.md — Layout: \"the panel becomes an\n * overlay below 1440px\"). Below this the sidebar + panel + content no\n * longer fit comfortably, so the rail hides behind a Filters button.\n *\n * Use the CSS `panel:` / `max-panel:` variants (`--breakpoint-panel`)\n * at call sites — this value is the single source of truth for both.\n */\nexport const PANEL_BREAKPOINT_PX = 1440\n\n/**\n * Media query string that matches viewports below the panel breakpoint\n * (< 1440 px), i.e. where the filter rail lives in a drawer. Shared\n * between JS hooks and anywhere else that needs the below-panel viewport.\n */\nexport const PANEL_QUERY = `(max-width: ${PANEL_BREAKPOINT_PX - 1}px)`\n","import {\n\tMOBILE_QUERY,\n\tPANEL_QUERY,\n\tSIDEBAR_QUERY,\n} from \"@hoardodile/ui/viewport\"\nimport { useMedia } from \"react-use\"\n\n/**\n * One-shot check for viewports below the `md` breakpoint (< 768 px).\n *\n * Prefer {@link useBelowMd} in React components so they re-render when the\n * viewport crosses the breakpoint. Use this helper only in event handlers,\n * utility functions, or effects where a reactive hook is not appropriate.\n */\nexport function isBelowMd(): boolean {\n\tif (typeof window === \"undefined\") return false\n\treturn window.matchMedia(MOBILE_QUERY).matches\n}\n\nexport function useBelowMd(): boolean {\n\treturn useMedia(MOBILE_QUERY, false)\n}\n\n/**\n * Reactive check for viewports below the app-shell sidebar breakpoint\n * (`max-sidebar`), where the fixed sidebar is replaced by the hamburger\n * drawer. Keep in sync with `SIDEBAR_BREAKPOINT_PX` and the\n * `sidebar:` / `max-sidebar:` CSS variants. The shell alone decides its own chrome;\n * compact-UI consumers keep using {@link useBelowMd}.\n */\nexport function useBelowSidebar(): boolean {\n\treturn useMedia(SIDEBAR_QUERY, false)\n}\n\n/**\n * Reactive check for viewports below the filter-rail breakpoint\n * (< 1440 px), where the rail becomes a drawer instead of a fixed right\n * column. Keep in sync with `PANEL_BREAKPOINT_PX` and the\n * `panel:` / `max-panel:` CSS variants.\n */\nexport function useBelowPanel(): boolean {\n\treturn useMedia(PANEL_QUERY, false)\n}\n\n/**\n * Compatibility alias for official shadcn-generated components (e.g.\n * `sidebar.tsx`), which import `useIsMobile` from this module. Mobile\n * detection rules are owned by THIS file for the whole repo (apps and\n * plugins alike) — never let the registry version of `use-mobile.ts`\n * replace it; restore after every `shadcn add`.\n */\nexport function useIsMobile(): boolean {\n\treturn useBelowMd()\n}\n","import { isBelowMd } from \"@hoardodile/ui/hooks/use-mobile\"\nimport { useEffect, useRef } from \"react\"\n\nconst HISTORY_KEY = \"__appMobileOverlay\"\n\n/**\n * LIFO stack of currently-open overlays registered via\n * {@link useMobileBackToClose}. Each entry knows how to close its own\n * overlay. The browser back gesture only closes the top entry, so\n * stacking dialogs/popovers/sheets unwind in reverse opening order\n * instead of all collapsing on the first back press.\n *\n * State is module-level so multiple component instances share a\n * single popstate listener and a single ordering source of truth.\n */\ntype OverlayEntry = {\n\treadonly id: number\n\t/** Original history state captured at push time for later restore. */\n\treadonly baseState: unknown\n\tclose: (() => void) | undefined\n}\n\nconst overlayStack: OverlayEntry[] = []\nlet popListenerInstalled = false\nlet historyPatched = false\nlet nextOverlayId = 0\n// Counts consecutive popstate events to suppress. When we call\n// `history.back()` N times (e.g. to unwind an active entry plus\n// parked entries), the next N popstate events must be swallowed so\n// they don't cascade-close deeper overlays.\nlet suppressPopCount = 0\n/**\n * Tracks every synthetic entry ID ever pushed. Used by the\n * capture-phase popstate listener to identify \"phantom\" entries —\n * synthetic history slots that remain in forward/back history after\n * the overlay was closed via route navigation. The listener auto-skips\n * these to prevent dead back-presses and router confusion.\n */\nconst seenSyntheticIds = new Set<number>()\n\n/**\n * Optional navigation-resolver registration injected by the host app.\n *\n * When set (via {@link setNavigationResolver}), `scheduleStateRestore`\n * uses it to receive a deterministic \"navigation complete\" signal from\n * the router instead of guessing timing via `requestAnimationFrame`.\n *\n * The registered function accepts a one-shot callback and returns an\n * unsubscribe function. The hook calls it, inspects `history.state`\n * inside the callback, then unsubscribes.\n */\ntype NavigationResolver = (onResolved: () => void) => () => void\nlet navigationResolver: NavigationResolver | undefined\n\n/**\n * Registers a navigation-resolver factory so that\n * {@link useMobileBackToClose} can wait for the router to finish\n * flushing its history mutations before inspecting `history.state`.\n *\n * Call this once at app startup, after the router is created:\n *\n * ```ts\n * import { setNavigationResolver } from \"@hoardodile/ui\"\n * import { router } from \"./router\"\n *\n * setNavigationResolver((fn) => router.subscribe(\"onResolved\", fn))\n * ```\n *\n * When no resolver is registered, the hook falls back to\n * `requestAnimationFrame` (correct for microtask-based routers but\n * less deterministic).\n */\nexport function setNavigationResolver(resolver: NavigationResolver): void {\n\tnavigationResolver = resolver\n}\n\n/**\n * Patches `history.pushState` once (idempotent) so that every call\n * from a router (or any other non-overlay code) is intercepted.\n *\n * When a pushState is detected that does NOT carry our\n * {@link HISTORY_KEY} marker, all open overlay entries are closed\n * and the stack is cleared. The synthetic entry's marker is\n * intentionally NOT stripped — the capture-phase popstate listener\n * uses it to identify and auto-skip the stranded entry when the\n * user later navigates past it.\n */\nfunction patchHistory(): void {\n\tif (historyPatched) return\n\tif (typeof window === \"undefined\") return\n\thistoryPatched = true\n\tconst origPush = window.history.pushState.bind(window.history)\n\twindow.history.pushState = (\n\t\tdata: unknown,\n\t\tunused: string,\n\t\turl?: string | URL | null,\n\t): void => {\n\t\tconst state = data as Record<string, unknown> | null\n\t\tif (state !== null && typeof state === \"object\" && HISTORY_KEY in state) {\n\t\t\t// Our own synthetic push — pass through.\n\t\t\torigPush(data, unused, url)\n\t\t\treturn\n\t\t}\n\t\t// Real navigation — close all overlays so the stack is\n\t\t// cleared synchronously (before React's async effects).\n\t\t// The synthetic entry remains in history with its marker\n\t\t// intact; the capture-phase popstate listener will\n\t\t// auto-skip it later.\n\t\tif (overlayStack.length > 0) {\n\t\t\tcloseAllOverlays()\n\t\t}\n\t\torigPush(data, unused, url)\n\t}\n}\n\n/**\n * Closes every active overlay in the stack (top-down) and clears\n * the stack. Called when a real navigation is detected so that\n * overlay state doesn't leak across route boundaries.\n */\nfunction closeAllOverlays(): void {\n\twhile (overlayStack.length > 0) {\n\t\tconst entry = overlayStack.pop()\n\t\tif (entry?.close !== undefined) {\n\t\t\tconst fn = entry.close\n\t\t\tentry.close = undefined\n\t\t\tfn()\n\t\t}\n\t}\n}\n\n/**\n * Installs popstate listeners and patches history.pushState.\n *\n * Two listeners are installed:\n *\n * 1. **Capture-phase** — runs BEFORE any bubbling-phase listeners\n *    (including TanStack Router's popstate handler). Inspects the\n *    state at the history pointer:\n *\n *    - **Active entry** (id found in overlayStack): the back\n *      gesture landed on a synthetic entry that belongs to an\n *      overlay still below the top of the stack. Pop and close the\n *      top overlay (the one the user is actually dismissing) and\n *      block the event from reaching the router via\n *      `stopImmediatePropagation()`.\n *\n *    - **Phantom entry** (id in `seenSyntheticIds` but NOT in\n *      overlayStack): a synthetic history slot that remains after\n *      the overlay was closed via route navigation. Blocks the\n *      event AND auto-skips by calling `history.back()` to advance\n *      the pointer past the phantom, so the router never sees its\n *      stale URL.\n *\n * 2. **Bubbling-phase** — closes the top overlay when the back\n *    gesture returns to the base route state (no synthetic marker),\n *    which happens for the last open overlay.\n */\nfunction ensurePopListener(): void {\n\tif (popListenerInstalled) return\n\tif (typeof window === \"undefined\") return\n\tpopListenerInstalled = true\n\n\t// Capture-phase gate: block synthetic popstate from reaching\n\t// the router (or any other bubbling-phase listener on window).\n\twindow.addEventListener(\n\t\t\"popstate\",\n\t\t(e: PopStateEvent) => {\n\t\t\tif (suppressPopCount > 0) return // let the counter handle it\n\t\t\tconst state = e.state as Record<string, unknown> | null\n\t\t\tif (state !== null && typeof state === \"object\" && HISTORY_KEY in state) {\n\t\t\t\tconst id = state[HISTORY_KEY]\n\t\t\t\t// Active entry still in the stack → the back gesture\n\t\t\t\t// landed on a synthetic entry of an overlay below the\n\t\t\t\t// top. Close the top overlay and hide the event from\n\t\t\t\t// the router.\n\t\t\t\tif (\n\t\t\t\t\ttypeof id === \"number\" &&\n\t\t\t\t\toverlayStack.some((entry) => entry.id === id)\n\t\t\t\t) {\n\t\t\t\t\tcloseTopOverlay()\n\t\t\t\t\te.stopImmediatePropagation()\n\t\t\t\t\treturn\n\t\t\t\t}\n\t\t\t\t// Phantom entry: a synthetic history slot that\n\t\t\t\t// remains after the overlay was closed via\n\t\t\t\t// route navigation. Block the event from the\n\t\t\t\t// router AND auto-skip by calling history.back()\n\t\t\t\t// to move the pointer past the phantom.\n\t\t\t\te.stopImmediatePropagation()\n\t\t\t\tif (typeof id === \"number\" && seenSyntheticIds.has(id)) {\n\t\t\t\t\twindow.history.back()\n\t\t\t\t}\n\t\t\t}\n\t\t},\n\t\ttrue, // capture phase\n\t)\n\n\twindow.addEventListener(\"popstate\", handlePop)\n\tpatchHistory()\n}\n\nfunction closeTopOverlay(): void {\n\tconst top = overlayStack.pop()\n\tif (top === undefined) return\n\t// `close` may be cleared if this entry was dismissed via UI from a\n\t// non-top position; the popstate then just unwinds a stale\n\t// synthetic history slot and there is nothing to close.\n\tif (top.close === undefined) return\n\t// Clear close before calling it so the resulting effect sees\n\t// idRef as undefined (back-gesture close) and skips the\n\t// back() + replaceState() UI-close path.\n\tconst closeFn = top.close\n\ttop.close = undefined\n\tcloseFn()\n}\n\nfunction handlePop(): void {\n\tif (suppressPopCount > 0) {\n\t\tsuppressPopCount--\n\t\treturn\n\t}\n\tcloseTopOverlay()\n}\n\n/**\n * Removes the entry with the given `id` from the overlay stack.\n *\n * When the entry is **not** the top of the stack, it is \"parked\"\n * (left in place with its close callback cleared) so the synthetic\n * history slot survives until swept.\n *\n * @returns An object describing what was removed:\n *   - `removed`: whether the entry was found.\n *   - `parkedBelow`: how many parked (close=undefined) entries were\n *     found below the removed entry. These must be unwound alongside\n *     the active entry to prevent dead back-presses.\n */\nfunction removeFromStack(id: number): {\n\treadonly removed: boolean\n\treadonly parkedBelow: number\n} {\n\tconst idx = overlayStack.findIndex((e) => e.id === id)\n\tif (idx === -1) return { removed: false, parkedBelow: 0 }\n\tconst wasTop = idx === overlayStack.length - 1\n\tif (!wasTop) {\n\t\t// Park: keep the history slot but neutralise the callback.\n\t\tconst entry = overlayStack[idx]\n\t\tif (entry !== undefined) entry.close = undefined\n\t\treturn { removed: true, parkedBelow: 0 }\n\t}\n\t// Top entry — remove it and count ALL parked entries below so\n\t// their orphaned synthetic history slots are unwound in the same\n\t// batch as the active entry's slot.\n\toverlayStack.pop()\n\tconst remaining = overlayStack.splice(0, overlayStack.length)\n\tconst active = remaining.filter((e) => e.close !== undefined)\n\tconst parkedBelow = remaining.length - active.length\n\toverlayStack.push(...active)\n\treturn { removed: true, parkedBelow }\n}\n\n/**\n * Cleans up the synthetic history entry after an overlay closes via\n * UI (not back gesture, not route navigation).\n *\n * `history.back()` is asynchronous — it queues a history traversal\n * task. The popstate event fires only after the traversal completes\n * (pointer has moved to the target entry). By replacing the state\n * inside the popstate handler, we ensure:\n *\n * 1. The pointer is at the base entry (not the synthetic one).\n * 2. `replaceState` truncates forward history, eliminating the\n *    phantom synthetic entry that `back()` alone would leave behind.\n *\n * **Route-change safety**: When a navigation-resolver is registered\n * (via {@link setNavigationResolver}), `scheduleStateRestore` uses\n * the router's deterministic \"navigation resolved\" signal to know\n * when `history.state` reflects the new route. When no resolver is\n * available (e.g. tests), it falls back to `requestAnimationFrame`,\n * which runs after the microtask queue where the router flushes its\n * pending `pushState` calls.\n *\n * - If `history.state` still carries our marker → normal UI close,\n *   proceed with the `back()` + `replaceState()` cleanup.\n * - If `history.state` no longer carries our marker → a route\n *   change has pushed a real entry on top. Skip the `back()` call\n *   to avoid racing with the router's push. The capture-phase\n *   popstate listener will auto-skip the stranded phantom entry.\n */\nfunction scheduleStateRestore(\n\tid: number,\n\tbaseState: unknown,\n\tparkedBelow: number,\n): void {\n\tfunction check(): void {\n\t\tconst currentState = window.history.state as Record<string, unknown> | null\n\n\t\t// The history pointer is no longer on this overlay's own\n\t\t// synthetic entry (route change, or another overlay has\n\t\t// already pushed/popped on top). Do NOT call history.back()\n\t\t// — it would race with the current top entry and navigate\n\t\t// to the wrong place. Just sweep parked entries from the\n\t\t// stack but do NOT prune `seenSyntheticIds`; any stranded\n\t\t// synthetic entries will be auto-skipped by the capture-phase\n\t\t// listener when the user navigates past them.\n\t\tif (\n\t\t\tcurrentState === null ||\n\t\t\ttypeof currentState !== \"object\" ||\n\t\t\t!(HISTORY_KEY in currentState) ||\n\t\t\tcurrentState[HISTORY_KEY] !== id\n\t\t) {\n\t\t\tsweepParkedEntries()\n\t\t\treturn\n\t\t}\n\n\t\tconst totalBacks = 1 + parkedBelow\n\t\tlet done = false\n\n\t\tfunction restore(): void {\n\t\t\tif (done) return\n\t\t\tdone = true\n\t\t\twindow.removeEventListener(\"popstate\", onPop)\n\t\t\twindow.history.replaceState(baseState, \"\")\n\t\t\t// replaceState truncates forward history, eliminating\n\t\t\t// phantom entries. Safe to prune their IDs from\n\t\t\t// `seenSyntheticIds` (excluding IDs still in the\n\t\t\t// active stack).\n\t\t\tconst sweptIds = sweepParkedEntries()\n\t\t\tcleanupSeenIds(sweptIds)\n\t\t}\n\n\t\tfunction onPop(): void {\n\t\t\tif (suppressPopCount > 0) {\n\t\t\t\tsuppressPopCount--\n\t\t\t\treturn\n\t\t\t}\n\t\t\trestore()\n\t\t}\n\n\t\twindow.addEventListener(\"popstate\", onPop)\n\n\t\tsuppressPopCount += totalBacks\n\t\tfor (let i = 0; i < totalBacks; i++) {\n\t\t\twindow.history.back()\n\t\t}\n\t}\n\n\t// Use both the router's deterministic \"navigation resolved\" signal\n\t// and a requestAnimationFrame fallback. In the common UI-close case\n\t// (e.g. clicking outside a dropdown) there is no route change, so\n\t// the resolver never fires. Without the fallback the synthetic\n\t// history entry would be left behind as a phantom.\n\tlet disposed = false\n\tlet rafId: number | undefined\n\tlet unsub: (() => void) | undefined\n\n\tfunction run(): void {\n\t\tif (disposed) return\n\t\tdisposed = true\n\t\tunsub?.()\n\t\tif (rafId !== undefined) {\n\t\t\tcancelAnimationFrame(rafId)\n\t\t}\n\t\tcheck()\n\t}\n\n\tif (navigationResolver !== undefined) {\n\t\tunsub = navigationResolver(run)\n\t}\n\n\trafId = requestAnimationFrame(run)\n}\n\n/**\n * Sweeps all parked entries (those with no close callback) from the\n * overlay stack. Called after `replaceState` truncates forward\n * history, since parked entries no longer have corresponding history\n * entries and would cause dead back-presses.\n *\n * @returns The IDs of entries that were removed, used by the caller\n *   to prune `seenSyntheticIds`.\n */\nfunction sweepParkedEntries(): readonly number[] {\n\tconst sweptIds: number[] = []\n\tfor (let i = overlayStack.length - 1; i >= 0; i--) {\n\t\tconst entry = overlayStack[i]\n\t\tif (entry !== undefined && entry.close === undefined) {\n\t\t\tsweptIds.push(entry.id)\n\t\t\toverlayStack.splice(i, 1)\n\t\t}\n\t}\n\treturn sweptIds\n}\n\n/**\n * Removes swept IDs from `seenSyntheticIds` to prevent unbounded\n * growth over the lifetime of the SPA session.\n *\n * After `replaceState` truncates forward history, phantom entries\n * for swept parked overlays are eliminated. Their IDs can safely\n * be removed from `seenSyntheticIds` — unless the same ID belongs\n * to an entry still active in the stack (which happens when a\n * lower-ID entry is parked but a higher-ID entry above it is still\n * open and not swept).\n */\nfunction cleanupSeenIds(sweptIds: readonly number[]): void {\n\tconst activeIds = new Set(overlayStack.map((e) => e.id))\n\tfor (const id of sweptIds) {\n\t\tif (!activeIds.has(id)) {\n\t\t\tseenSyntheticIds.delete(id)\n\t\t}\n\t}\n}\n\n/**\n * On mobile (< sm), when an overlay (dialog/sheet/popover) opens we push a\n * synthetic history entry so the device back gesture closes it instead of\n * navigating away from the page.\n *\n * **Closing via UI** calls `history.back()` to navigate past the\n * synthetic entry, then uses `replaceState` (inside the resulting\n * popstate handler) to restore the original history state.\n *\n * **Closing via back gesture** is handled by the popstate listener,\n * which pops the stack entry and calls the close callback.\n *\n * **Closing via route navigation**: the `pushState` interceptor\n * closes all overlays synchronously but does NOT strip the synthetic\n * marker. The React effect's `scheduleStateRestore` waits for the\n * router's navigation-resolved signal (or falls back to\n * `requestAnimationFrame`); by then the router's push has completed\n * and the marker is gone from `history.state`, so `back()` is\n * skipped. The stranded synthetic entry is later auto-skipped by the\n * capture-phase popstate listener when the user navigates past it.\n *\n * Multiple overlays open at once stack: pressing back closes the most\n * recently opened one first, matching the visual stacking order.\n *\n * No-op on non-mobile viewports and when no `onOpenChange` is provided\n * (uncontrolled overlays cannot be closed externally).\n */\nexport function useMobileBackToClose(\n\topen: boolean | undefined,\n\tonOpenChange: ((open: boolean) => void) | undefined,\n): void {\n\tconst idRef = useRef<number | undefined>(undefined)\n\tconst onChangeRef = useRef(onOpenChange)\n\tonChangeRef.current = onOpenChange\n\n\tuseEffect(() => {\n\t\tif (typeof window === \"undefined\") return\n\t\tif (onChangeRef.current === undefined) return\n\t\tif (!isBelowMd()) return\n\t\tensurePopListener()\n\n\t\tif (open === true && idRef.current === undefined) {\n\t\t\tconst id = ++nextOverlayId\n\t\t\tidRef.current = id\n\t\t\tseenSyntheticIds.add(id)\n\t\t\t// Capture the base state BEFORE pushing so we can restore\n\t\t\t// it on close (via replaceState) to eliminate phantoms.\n\t\t\tconst baseState = window.history.state ?? null\n\t\t\twindow.history.pushState(\n\t\t\t\t{\n\t\t\t\t\t...((baseState as Record<string, unknown>) ?? {}),\n\t\t\t\t\t[HISTORY_KEY]: id,\n\t\t\t\t},\n\t\t\t\t\"\",\n\t\t\t)\n\t\t\toverlayStack.push({\n\t\t\t\tid,\n\t\t\t\tbaseState,\n\t\t\t\tclose() {\n\t\t\t\t\tidRef.current = undefined\n\t\t\t\t\tonChangeRef.current?.(false)\n\t\t\t\t},\n\t\t\t})\n\t\t\treturn\n\t\t}\n\n\t\tif (open !== true && idRef.current !== undefined) {\n\t\t\tconst id = idRef.current\n\t\t\tidRef.current = undefined\n\t\t\tconst entryIdx = overlayStack.findIndex((e) => e.id === id)\n\t\t\tconst entry = entryIdx !== -1 ? overlayStack[entryIdx] : undefined\n\t\t\tconst { removed, parkedBelow } = removeFromStack(id)\n\t\t\tif (removed && entry !== undefined) {\n\t\t\t\tscheduleStateRestore(id, entry.baseState, parkedBelow)\n\t\t\t}\n\t\t}\n\t}, [open])\n\n\tuseEffect(() => {\n\t\treturn () => {\n\t\t\tif (idRef.current !== undefined) {\n\t\t\t\tconst id = idRef.current\n\t\t\t\tidRef.current = undefined\n\t\t\t\tconst entryIdx = overlayStack.findIndex((e) => e.id === id)\n\t\t\t\tconst entry = entryIdx !== -1 ? overlayStack[entryIdx] : undefined\n\t\t\t\tconst { removed, parkedBelow } = removeFromStack(id)\n\t\t\t\tif (removed && entry !== undefined) {\n\t\t\t\t\tscheduleStateRestore(id, entry.baseState, parkedBelow)\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}, [])\n}\n"]}

package/dist/icon-BOgL5bpL.d.ts

@@ -0,0 +1,85 @@
+import * as React from 'react';
+import { ComponentType } from 'react';
+
+/**
+ * Icon-mode-aware glyph wrapper (Settings → Icons in the host app).
+ *
+ * The active icon style lives as `data-icon-style` on `document.documentElement`
+ * — the host app writes it from its preference store, plugin iframes receive
+ * it through the `themeChanged` push — so this module needs no context or
+ * injected state: a single shared `MutationObserver` watches the attribute
+ * and every wrapped component re-renders through `useSyncExternalStore`
+ * when it flips.
+ *
+ * Only `linear` needs a component swap: the boldDuotone glyphs change to
+ * their thin-line linear counterparts. `grayscale` is pure CSS (theme.css
+ * recolors the `.hd-icon` hook), so the store only tracks the mode.
+ */
+type IconStyleValue = "duotone" | "grayscale" | "linear";
+/**
+ * The parallel Solar weights an icon registers — named after Solar's own
+ * weights (DESIGN.md — Iconography). Every icon carries all of them;
+ * adding a mode here forces every registry entry to fill it in.
+ */
+type IconMode = "bold" | "boldDuotone" | "linear";
+/** All three mode glyphs of one icon. Mandatory and complete by type. */
+type IconVariants = Record<IconMode, IconType>;
+/**
+ * Wraps a Solar glyph family so its render follows the host's icon style.
+ *
+ * `createIcon({ bold, boldDuotone, linear })` — the three parallel weights
+ * of one icon. Without a `mode` prop the wrapper renders the glyph for the
+ * active icon style; an explicit `mode` overrides it (selected states pass
+ * `"bold"` through `Icon`).
+ *
+ * Every wrapped render merges the `hd-icon` hook class, so the duotone /
+ * grayscale CSS in theme.css applies to direct renders too. Returns
+ * `undefined`-free components callable through the `Icon` wrapper or bare
+ * JSX alike.
+ */
+declare function createIcon(variants: IconVariants): ComponentType<Record<string, unknown>>;
+
+/** Anything renderable through `Icon`: a Solar icon (imported from the
+    central registry on the web side) or a local utility mark (marks.tsx) —
+    both take `className`; registry icons take `mode` (marks ignore it). */
+type IconType = ComponentType<{
+    className?: string;
+    mode?: IconMode;
+}>;
+/** The three sanctioned icon sizes: `sm` 12 inside pills and meta lines,
+    `md` 16 by default, `lg` 20 for primary toolbar actions. */
+type IconSize = "sm" | "md" | "lg";
+/**
+ * Solar icons with the design system's defaults baked in: callers pass
+ * the registry icon — by default it renders the boldDuotone weight,
+ * whose second tone takes the palette's `--icon-tone` hue (theme.css
+ * recolors the duotone accent via `--solar-secondary-color` under the
+ * `hd-icon` hook), so colored palettes feel alive while mono stays
+ * neutral.
+ *
+ * Mode is one channel: `mode` picks the weight directly; `selected` maps
+ * to `"bold"` (the filled, single-color weight — the only sanctioned use
+ * of Bold); otherwise the active icon style preference decides.
+ *
+ * Sizing is class-based, three tiers only — `sm`/`md`/`lg` map to
+ * `size-3/4/5` (12/16/20). Escape the tiers with
+ * `className="size-[18px]"` — twMerge lets the later class win.
+ *
+ * ✓/×/+ semantics never use Solar's Circle/Square composites — the
+ * container is full-bleed while the informative mark is barely a third
+ * of the box, so it goes muddy at small sizes. The plain marks (Check,
+ * Cross, Plus from marks.tsx) cover these at every size; `sm` otherwise
+ * belongs to simple single-stroke glyphs (arrows, dots, grips).
+ */
+declare function Icon({ icon: IconComponent, mode, size, selected, className, ...rest }: {
+    icon: IconType;
+    /** Explicit weight override; `selected` and the style preference lose
+        to it. */
+    mode?: IconMode;
+    size?: IconSize;
+    /** Selected state — renders the icon's `"bold"` weight. */
+    selected?: boolean;
+    className?: string;
+} & Record<string, unknown>): React.JSX.Element;
+
+export { type IconType as I, type IconSize as a, type IconMode as b, type IconStyleValue as c, type IconVariants as d, createIcon as e, Icon as f };

package/dist/icons/actions.d.ts

@@ -0,0 +1,4 @@
+export { Plus as Add, Check, Cross as Remove } from './marks.js';
+export { MenuDots as More } from './registry.js';
+import 'react';
+import '../icon-BOgL5bpL.js';