sh3-core 0.1.0

package/dist/overlays/modal.d.ts

@@ -0,0 +1,9 @@
+import { type Component } from 'svelte';
+import type { ModalHandle, ModalOptions } from './types';
+export interface ModalManager {
+    open<P extends Record<string, unknown>>(Content: Component<P & {
+        close: () => void;
+    }>, props?: P, options?: ModalOptions): ModalHandle;
+    closeAll(): void;
+}
+export declare const modalManager: ModalManager;

package/dist/overlays/modal.js

@@ -0,0 +1,141 @@
+/*
+ * Modal manager — stackable, Escape-dismissed, focus-trapped dialogs.
+ *
+ * Public API:
+ *   modalManager.open(Content, props?) → ModalHandle
+ *   modalManager.closeAll()
+ *
+ * Semantics (from docs/design/layout.md):
+ *   - Modals stack. Opening a second modal pushes it on top of the first.
+ *   - Escape pops the topmost modal.
+ *   - Backdrop click does NOT dismiss. Content owns its own close UI.
+ *   - Each modal has its own focus trap (installed by ModalFrame).
+ *
+ * Implementation notes:
+ *   - Each open() creates a per-modal host <div> under the layer-4 root
+ *     and mounts a ModalFrame into it. The host isolates modals for clean
+ *     unmount/remove.
+ *   - A SINGLE shared backdrop element is inserted into the layer-4 root
+ *     on the first open and removed on the last close. It is repositioned
+ *     on every stack change to sit directly BENEATH the topmost modal host
+ *     (and above all other modal hosts), so stacked modals read as dimmed
+ *     and clearly non-interactive while the top modal renders clear. The
+ *     opacity is a single fixed value — depth-scaled opacity (an earlier
+ *     cut) is no longer meaningful because only the "layer beneath the
+ *     top" is ever being dimmed. Per-modal backdrops were the phase-5
+ *     first cut; they compounded (2 modals ≈ 0.75, 3 ≈ 0.88, …) and were
+ *     both unbounded and expensive.
+ *   - The manager owns a single document-level Escape listener, installed
+ *     lazily on first open and removed when the stack empties. This is
+ *     simpler than per-modal listeners and avoids "which listener wins"
+ *     ordering puzzles when modals stack.
+ *   - close() is idempotent: calling it after the modal has been removed
+ *     is a no-op, which makes it safe for content components to call from
+ *     both a close button and an "async action finished" callback.
+ */
+import { mount, unmount } from 'svelte';
+import ModalFrame from './ModalFrame.svelte';
+import { getLayerRoot } from './roots';
+const stack = [];
+let escapeInstalled = false;
+let backdrop = null;
+/** Single fixed backdrop opacity. The backdrop is repositioned beneath
+ *  the topmost modal on every stack change, so underlying modals appear
+ *  dimmed (visually communicating they're non-interactive) while the top
+ *  modal sits above the dim. Depth-scaled opacity is therefore obsolete:
+ *  only one "layer beneath the top" is ever being dimmed. */
+const BACKDROP_OPACITY = 0.5;
+function syncBackdrop() {
+    const root = getLayerRoot('modal');
+    if (stack.length === 0) {
+        if (backdrop) {
+            backdrop.remove();
+            backdrop = null;
+        }
+        return;
+    }
+    if (!backdrop) {
+        backdrop = document.createElement('div');
+        backdrop.className = 'sh3-modal-backdrop';
+        backdrop.style.position = 'absolute';
+        backdrop.style.inset = '0';
+        backdrop.style.pointerEvents = 'auto';
+        backdrop.style.transition = 'background-color 120ms ease';
+        backdrop.style.background = `rgba(0, 0, 0, ${BACKDROP_OPACITY})`;
+    }
+    // Place the backdrop directly before the topmost modal host so every
+    // modal beneath it is dimmed while the top modal renders clear above.
+    const topHost = stack[stack.length - 1].host;
+    root.insertBefore(backdrop, topHost);
+}
+function onDocumentKeydown(e) {
+    if (e.key !== 'Escape')
+        return;
+    if (stack.length === 0)
+        return;
+    e.stopPropagation();
+    e.preventDefault();
+    stack[stack.length - 1].handle.close();
+}
+function ensureEscapeListener() {
+    if (escapeInstalled)
+        return;
+    escapeInstalled = true;
+    document.addEventListener('keydown', onDocumentKeydown, true);
+}
+function removeEscapeListenerIfIdle() {
+    if (stack.length > 0)
+        return;
+    if (!escapeInstalled)
+        return;
+    escapeInstalled = false;
+    document.removeEventListener('keydown', onDocumentKeydown, true);
+}
+function removeEntry(entry) {
+    const idx = stack.indexOf(entry);
+    if (idx < 0)
+        return; // already closed — idempotent
+    stack.splice(idx, 1);
+    unmount(entry.frame);
+    entry.host.remove();
+    syncBackdrop();
+    removeEscapeListenerIfIdle();
+}
+function openModal(Content, props, options) {
+    const root = getLayerRoot('modal');
+    const host = document.createElement('div');
+    host.className = 'sh3-modal-host';
+    host.style.position = 'absolute';
+    host.style.inset = '0';
+    host.style.pointerEvents = 'auto';
+    root.appendChild(host);
+    const entry = {};
+    const handle = {
+        close: () => removeEntry(entry),
+    };
+    const frame = mount(ModalFrame, {
+        target: host,
+        props: {
+            Content: Content,
+            contentProps: (props !== null && props !== void 0 ? props : {}),
+            close: handle.close,
+            boxStyle: options === null || options === void 0 ? void 0 : options.boxStyle,
+        },
+    });
+    entry.host = host;
+    entry.frame = frame;
+    entry.handle = handle;
+    stack.push(entry);
+    syncBackdrop();
+    ensureEscapeListener();
+    return handle;
+}
+function closeAll() {
+    while (stack.length > 0) {
+        removeEntry(stack[stack.length - 1]);
+    }
+}
+export const modalManager = {
+    open: openModal,
+    closeAll,
+};

package/dist/overlays/popup.d.ts

@@ -0,0 +1,9 @@
+import { type Component } from 'svelte';
+import type { PopupHandle, PopupOptions } from './types';
+export interface PopupManager {
+    show<P extends Record<string, unknown>>(Content: Component<P & {
+        close: () => void;
+    }>, options: PopupOptions, props?: P): PopupHandle;
+    close(): void;
+}
+export declare const popupManager: PopupManager;

package/dist/overlays/popup.js

@@ -0,0 +1,108 @@
+/*
+ * Popup manager — anchored, non-stacking, outside-click-dismissable.
+ *
+ * Public API:
+ *   popupManager.show(Content, { anchor, placement? }, props?) → PopupHandle
+ *   popupManager.close()
+ *
+ * Semantics (from docs/design/layout.md):
+ *   - Popups do NOT stack. Opening a second popup dismisses the first.
+ *   - Clicking outside the popup dismisses it.
+ *   - Pressing Escape dismisses it.
+ *   - The caller provides an HTMLElement anchor; the popup positions
+ *     itself relative to the anchor's current viewport rect.
+ *
+ * Implementation notes:
+ *   - The manager keeps at most one active entry. show() closes any
+ *     prior entry before opening a new one — so callers can wire a
+ *     menu button to `shell.popup.show(...)` without worrying about
+ *     toggling themselves.
+ *   - Dismissal listeners (pointerdown for outside-click, keydown for
+ *     Escape) are installed when the popup opens and removed on close.
+ *     Outside-click detection uses the mounted frame element's DOM
+ *     containment check, so nested popups-inside-content still click-
+ *     through without closing (there are no nested popups in phase 5,
+ *     but the check is cheap and correct).
+ *   - close() is idempotent.
+ */
+import { mount, unmount } from 'svelte';
+import PopupFrame from './PopupFrame.svelte';
+import { getLayerRoot } from './roots';
+let current = null;
+function onDocumentPointerDown(e) {
+    if (!current)
+        return;
+    const target = e.target;
+    if (target && current.host.contains(target))
+        return;
+    current.handle.close();
+}
+function onDocumentKeydown(e) {
+    if (!current)
+        return;
+    if (e.key !== 'Escape')
+        return;
+    e.stopPropagation();
+    e.preventDefault();
+    current.handle.close();
+}
+function installDismissListeners() {
+    // `true` capture phase so we see the event before view-level handlers
+    // that might stopPropagation.
+    document.addEventListener('pointerdown', onDocumentPointerDown, true);
+    document.addEventListener('keydown', onDocumentKeydown, true);
+}
+function removeDismissListeners() {
+    document.removeEventListener('pointerdown', onDocumentPointerDown, true);
+    document.removeEventListener('keydown', onDocumentKeydown, true);
+}
+function removeEntry(entry) {
+    if (current !== entry)
+        return; // already closed / superseded
+    current = null;
+    removeDismissListeners();
+    unmount(entry.frame);
+    entry.host.remove();
+}
+function showPopup(Content, options, props) {
+    // Non-stacking: dismiss any existing popup first.
+    if (current)
+        removeEntry(current);
+    const root = getLayerRoot('popup');
+    const host = document.createElement('div');
+    host.className = 'sh3-popup-host';
+    host.style.position = 'absolute';
+    host.style.inset = '0';
+    host.style.pointerEvents = 'none'; // only the frame captures pointer events
+    root.appendChild(host);
+    const anchorRect = options.anchor.getBoundingClientRect();
+    const entry = {};
+    const handle = {
+        close: () => removeEntry(entry),
+    };
+    const frame = mount(PopupFrame, {
+        target: host,
+        props: {
+            Content: Content,
+            contentProps: (props !== null && props !== void 0 ? props : {}),
+            anchorRect,
+            close: handle.close,
+        },
+    });
+    entry.host = host;
+    entry.frame = frame;
+    entry.handle = handle;
+    current = entry;
+    // Defer listener install by a microtask so the same pointerdown that
+    // opened the popup (from a button click) doesn't instantly dismiss it.
+    queueMicrotask(installDismissListeners);
+    return handle;
+}
+function closeCurrent() {
+    if (current)
+        removeEntry(current);
+}
+export const popupManager = {
+    show: showPopup,
+    close: closeCurrent,
+};

package/dist/overlays/roots.d.ts

@@ -0,0 +1,4 @@
+import type { OverlayLayer } from './types';
+export declare function registerLayerRoot(layer: OverlayLayer, el: HTMLElement): void;
+export declare function unregisterLayerRoot(layer: OverlayLayer): void;
+export declare function getLayerRoot(layer: OverlayLayer): HTMLElement;

package/dist/overlays/roots.js

@@ -0,0 +1,31 @@
+/*
+ * Layer root registry.
+ *
+ * Shell.svelte owns the six overlay root <div>s (one per layer). Overlay
+ * managers — which are plain TypeScript modules, not Svelte components —
+ * need DOM references to those roots so they can append transient content
+ * (modals, popups, toasts) into the correct stacking context.
+ *
+ * Shell.svelte calls `registerLayerRoot(name, el)` on each root during its
+ * own mount effect. Managers call `getLayerRoot(name)` lazily the first
+ * time they need to open something, which is always *after* Shell has
+ * rendered because overlay triggers originate from views mounted into the
+ * layout tree. No race; no DOM queries.
+ *
+ * Unregister is exposed too so tests and hot-reload can reset the registry.
+ */
+const roots = {};
+export function registerLayerRoot(layer, el) {
+    roots[layer] = el;
+}
+export function unregisterLayerRoot(layer) {
+    delete roots[layer];
+}
+export function getLayerRoot(layer) {
+    const el = roots[layer];
+    if (!el) {
+        throw new Error(`Overlay layer "${layer}" root is not registered — ` +
+            `Shell.svelte must mount before opening overlays on this layer.`);
+    }
+    return el;
+}

package/dist/overlays/toast.d.ts

@@ -0,0 +1,6 @@
+import type { ToastHandle, ToastOptions } from './types';
+export interface ToastManager {
+    notify(message: string, options?: ToastOptions): ToastHandle;
+    clear(): void;
+}
+export declare const toastManager: ToastManager;

package/dist/overlays/toast.js

@@ -0,0 +1,93 @@
+/*
+ * Toast manager — auto-dismissing non-interactive notifications.
+ *
+ * Public API:
+ *   toastManager.notify(message, options?) → ToastHandle
+ *   toastManager.clear()
+ *
+ * Semantics (from docs/design/layout.md):
+ *   - Toasts queue and stack vertically at the bottom-right of the shell.
+ *   - Each toast auto-dismisses after `duration` ms (default 3000).
+ *     `duration: Infinity` pins the toast until the caller calls close().
+ *   - Clicking a toast dismisses it immediately.
+ *   - Level styling: info / warn / error / success.
+ *
+ * Implementation notes:
+ *   - A lazy layout container is appended to the layer-5 root on first
+ *     notify; it's a flex column anchored to the bottom-right with a
+ *     small gap between toasts.
+ *   - Each toast is a standalone mount — simpler than a single list
+ *     component tracking an array, and naturally handles independent
+ *     fade-in animations per item.
+ *   - The manager tracks entries for `clear()` and for idempotent close.
+ */
+import { mount, unmount } from 'svelte';
+import ToastItem from './ToastItem.svelte';
+import { getLayerRoot } from './roots';
+const entries = new Set();
+let container = null;
+function ensureContainer() {
+    if (container && container.isConnected)
+        return container;
+    const root = getLayerRoot('toast');
+    container = document.createElement('div');
+    container.className = 'sh3-toast-stack';
+    container.style.position = 'absolute';
+    container.style.right = '16px';
+    container.style.bottom = '16px';
+    container.style.display = 'flex';
+    container.style.flexDirection = 'column-reverse';
+    container.style.gap = '6px';
+    container.style.pointerEvents = 'none';
+    root.appendChild(container);
+    return container;
+}
+function removeEntry(entry) {
+    if (!entries.has(entry))
+        return;
+    entries.delete(entry);
+    if (entry.timer !== null) {
+        clearTimeout(entry.timer);
+        entry.timer = null;
+    }
+    unmount(entry.instance);
+    entry.host.remove();
+}
+function notify(message, options = {}) {
+    var _a, _b;
+    const level = (_a = options.level) !== null && _a !== void 0 ? _a : 'info';
+    const duration = (_b = options.duration) !== null && _b !== void 0 ? _b : 3000;
+    const parent = ensureContainer();
+    const host = document.createElement('div');
+    host.className = 'sh3-toast-host';
+    parent.appendChild(host);
+    const entry = {};
+    const handle = {
+        close: () => removeEntry(entry),
+    };
+    const instance = mount(ToastItem, {
+        target: host,
+        props: {
+            message,
+            level,
+            close: handle.close,
+        },
+    });
+    entry.host = host;
+    entry.instance = instance;
+    entry.handle = handle;
+    entry.timer =
+        Number.isFinite(duration) && duration > 0
+            ? setTimeout(() => removeEntry(entry), duration)
+            : null;
+    entries.add(entry);
+    return handle;
+}
+function clear() {
+    for (const entry of [...entries])
+        removeEntry(entry);
+}
+export const toastManager = {
+    notify,
+    clear,
+};

package/dist/overlays/types.d.ts

@@ -0,0 +1,31 @@
+export type OverlayLayer = 'floating' | 'drag-preview' | 'popup' | 'modal' | 'toast' | 'command';
+/** A handle returned by every overlay opener. Calling close() is idempotent. */
+export interface OverlayHandle {
+    close(): void;
+}
+export type ModalHandle = OverlayHandle;
+export type PopupHandle = OverlayHandle;
+export type ToastHandle = OverlayHandle;
+export type ToastLevel = 'info' | 'warn' | 'error' | 'success';
+/** Where a popup should sit relative to its anchor. Phase 5 ships bottom-start. */
+export type PopupPlacement = 'bottom-start';
+export interface PopupOptions {
+    anchor: HTMLElement;
+    placement?: PopupPlacement;
+}
+export interface ToastOptions {
+    level?: ToastLevel;
+    /** Auto-dismiss after this many ms. `Infinity` disables auto-dismiss. */
+    duration?: number;
+}
+export interface ModalOptions {
+    /**
+     * Inline style string applied to the modal's dialog box. Lets callers
+     * override the default centered-auto-sized layout for custom sizing
+     * and positioning. Setting `position: absolute; top: …; left: …`
+     * escapes the frame's grid centering and places the box at the given
+     * viewport-relative coordinates. Useful for test scaffolding and for
+     * views like non-centered palettes or inspectors.
+     */
+    boxStyle?: string;
+}

package/dist/overlays/types.js

@@ -0,0 +1,15 @@
+/*
+ * Overlay API types — shared between layer managers.
+ *
+ * The "layer" concept comes from docs/design/layout.md: overlays live
+ * above the docked layout in an explicit numbered stack (0 = docked,
+ * 1 = floating, 2 = drag preview, 3 = popup, 4 = modal, 5 = toast,
+ * 6 = command palette). Phase 5 wires up layers 3/4/5; the rest are
+ * stubbed as DOM roots in Shell.svelte but have no managers yet.
+ *
+ * No component in the codebase writes a z-index directly — the only
+ * z-index values live on the overlay root divs in Shell.svelte driven
+ * by the --shell-z-layer-N tokens. Overlay content is appended into the
+ * corresponding layer root and inherits its stacking context.
+ */
+export {};