@slowclap/rezi-core 0.1.0-fork.1

package/dist/runtime/layers.js

@@ -0,0 +1,289 @@
+/**
+ * packages/core/src/runtime/layers.ts — Layer manager for modal/overlay system.
+ *
+ * Why: Manages z-ordered layers for modals, dropdowns, and tooltips. Handles
+ * layer registry, hit testing with z-order respect, and backdrop blocking for
+ * modal layers.
+ *
+ * Layer concepts:
+ *   - Z-order: Higher z-index renders on top and receives input first
+ *   - Tie-break: Equal z-index uses registration order (later registration on top)
+ *   - Backdrop: Optional overlay that can dim or block lower layers
+ *   - Modal: Blocks input to layers below
+ *   - Focus trapping: Modal layers trap focus within their bounds
+ *
+ * @see docs/guide/runtime-and-layout.md (GitHub issue #117)
+ */
+/** Counter for auto-generating z-indices. */
+let nextAutoZIndex = 1000;
+/**
+ * Create a new layer registry.
+ */
+export function createLayerRegistry() {
+    const layers = new Map();
+    let nextRegistrationOrder = 0;
+    let cacheDirty = true;
+    let sortedSnapshot = Object.freeze([]);
+    let topmostSnapshot;
+    let topmostModalSnapshot;
+    function markDirty() {
+        cacheDirty = true;
+    }
+    function refreshSnapshots() {
+        if (!cacheDirty)
+            return;
+        const sorted = Array.from(layers.values()).sort((a, b) => {
+            if (a.zIndex !== b.zIndex)
+                return a.zIndex - b.zIndex;
+            return a.registrationOrder - b.registrationOrder;
+        });
+        const nextSorted = [];
+        let nextTopmost;
+        let nextTopmostModal;
+        for (let i = 0; i < sorted.length; i++) {
+            const layer = sorted[i];
+            if (!layer)
+                continue;
+            const snapshot = Object.freeze({
+                id: layer.id,
+                zIndex: layer.zIndex,
+                rect: layer.rect,
+                backdrop: layer.backdrop,
+                modal: layer.modal,
+                closeOnEscape: layer.closeOnEscape,
+                onClose: layer.onClose,
+            });
+            nextSorted.push(snapshot);
+            nextTopmost = snapshot;
+            if (snapshot.modal)
+                nextTopmostModal = snapshot;
+        }
+        sortedSnapshot = Object.freeze(nextSorted);
+        topmostSnapshot = nextTopmost;
+        topmostModalSnapshot = nextTopmostModal;
+        cacheDirty = false;
+    }
+    return Object.freeze({
+        register(layerInput) {
+            const zIndex = layerInput.zIndex ?? nextAutoZIndex++;
+            const layer = {
+                id: layerInput.id,
+                zIndex,
+                registrationOrder: nextRegistrationOrder++,
+                rect: layerInput.rect,
+                backdrop: layerInput.backdrop,
+                modal: layerInput.modal,
+                closeOnEscape: layerInput.closeOnEscape,
+                onClose: layerInput.onClose,
+            };
+            layers.set(layer.id, layer);
+            markDirty();
+        },
+        unregister(id) {
+            if (layers.delete(id))
+                markDirty();
+        },
+        get(id) {
+            const layer = layers.get(id);
+            if (!layer)
+                return undefined;
+            return Object.freeze({
+                id: layer.id,
+                zIndex: layer.zIndex,
+                rect: layer.rect,
+                backdrop: layer.backdrop,
+                modal: layer.modal,
+                closeOnEscape: layer.closeOnEscape,
+                onClose: layer.onClose,
+            });
+        },
+        getAll() {
+            refreshSnapshots();
+            return sortedSnapshot;
+        },
+        getTopmost() {
+            refreshSnapshots();
+            return topmostSnapshot;
+        },
+        getTopmostModal() {
+            refreshSnapshots();
+            return topmostModalSnapshot;
+        },
+        updateRect(id, rect) {
+            const layer = layers.get(id);
+            if (layer) {
+                layer.rect = rect;
+                markDirty();
+            }
+        },
+        clear() {
+            if (layers.size > 0) {
+                layers.clear();
+                markDirty();
+            }
+        },
+    });
+}
+/* ========== Hit Testing ========== */
+/**
+ * Check if a point is inside a rect.
+ */
+function containsPoint(rect, x, y) {
+    return x >= rect.x && x < rect.x + rect.w && y >= rect.y && y < rect.y + rect.h;
+}
+/**
+ * Hit test layers to find which layer contains a point.
+ * Returns the topmost layer containing the point, respecting modal blocking.
+ * Order is deterministic: higher z-index first, then later registration for equal z-index.
+ *
+ * @param registry - Layer registry
+ * @param x - X coordinate to test
+ * @param y - Y coordinate to test
+ * @returns Hit test result
+ */
+export function hitTestLayers(registry, x, y) {
+    const layers = registry.getAll();
+    // Find topmost modal layer for blocking check.
+    let topmostModalIndex = -1;
+    for (let i = layers.length - 1; i >= 0; i--) {
+        const layer = layers[i];
+        if (layer?.modal) {
+            topmostModalIndex = i;
+            break;
+        }
+    }
+    const topmostModal = topmostModalIndex >= 0 ? (layers[topmostModalIndex] ?? null) : null;
+    let blockingLayer = null;
+    // Check from topmost to bottom
+    for (let i = layers.length - 1; i >= 0; i--) {
+        const layer = layers[i];
+        if (!layer)
+            continue;
+        if (containsPoint(layer.rect, x, y)) {
+            // Block if the topmost modal is above this layer in resolved stack order.
+            if (topmostModal && topmostModalIndex > i) {
+                blockingLayer = topmostModal;
+                return Object.freeze({
+                    layer: null,
+                    blocked: true,
+                    blockingLayer,
+                });
+            }
+            return Object.freeze({
+                layer,
+                blocked: false,
+                blockingLayer: null,
+            });
+        }
+    }
+    // Point not in any layer - modal layers block ALL input below, regardless of backdrop style
+    // The backdrop property controls visual dimming, not input blocking
+    if (topmostModal) {
+        return Object.freeze({
+            layer: null,
+            blocked: true,
+            blockingLayer: topmostModal,
+        });
+    }
+    return Object.freeze({
+        layer: null,
+        blocked: false,
+        blockingLayer: null,
+    });
+}
+/**
+ * Create initial layer stack state.
+ */
+export function createLayerStackState() {
+    return Object.freeze({
+        stack: Object.freeze([]),
+        closeCallbacks: new Map(),
+    });
+}
+/**
+ * Push a layer onto the stack.
+ */
+export function pushLayer(state, layerId, onClose) {
+    const stack = [...state.stack.filter((id) => id !== layerId), layerId];
+    const closeCallbacks = new Map(state.closeCallbacks);
+    if (onClose) {
+        closeCallbacks.set(layerId, onClose);
+    }
+    else {
+        closeCallbacks.delete(layerId);
+    }
+    return Object.freeze({
+        stack: Object.freeze(stack),
+        closeCallbacks,
+    });
+}
+/**
+ * Pop a layer from the stack.
+ * Returns the new state and the onClose callback if any.
+ */
+export function popLayer(state, layerId) {
+    const onClose = state.closeCallbacks.get(layerId);
+    const stack = state.stack.filter((id) => id !== layerId);
+    const closeCallbacks = new Map(state.closeCallbacks);
+    closeCallbacks.delete(layerId);
+    return {
+        state: Object.freeze({
+            stack: Object.freeze(stack),
+            closeCallbacks,
+        }),
+        onClose,
+    };
+}
+/**
+ * Get the topmost layer ID from the stack.
+ */
+export function getTopmostLayerId(state) {
+    const len = state.stack.length;
+    if (len === 0)
+        return null;
+    return state.stack[len - 1] ?? null;
+}
+/**
+ * Close the topmost layer.
+ * Returns the new state and whether a layer was closed.
+ */
+export function closeTopmostLayer(state) {
+    const topmostId = getTopmostLayerId(state);
+    if (!topmostId) {
+        return { state, closed: false, closedLayerId: null };
+    }
+    const { state: newState, onClose } = popLayer(state, topmostId);
+    // Call the onClose callback
+    if (onClose) {
+        try {
+            onClose();
+        }
+        catch {
+            // Swallow errors from close callbacks
+        }
+    }
+    return {
+        state: newState,
+        closed: true,
+        closedLayerId: topmostId,
+    };
+}
+/**
+ * Get backdrop configurations for all layers that need them.
+ * Returns in render order (lowest z-index first).
+ */
+export function getBackdrops(registry) {
+    const layers = registry.getAll();
+    const backdrops = [];
+    for (const layer of layers) {
+        if (layer.backdrop !== "none") {
+            backdrops.push(Object.freeze({
+                style: layer.backdrop,
+                rect: layer.rect,
+                zIndex: layer.zIndex,
+            }));
+        }
+    }
+    return Object.freeze(backdrops);
+}
+//# sourceMappingURL=layers.js.map

package/dist/runtime/layers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layers.js","sourceRoot":"","sources":["../../src/runtime/layers.ts"],"names":[],"mappings":"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"}

package/dist/runtime/localState.d.ts

@@ -0,0 +1,194 @@
+/**
+ * packages/core/src/runtime/localState.ts — Per-instance local state storage.
+ *
+ * Why: Provides a key-value store for runtime-local state associated with
+ * widget instances. State is keyed by instanceId and persists across renders
+ * for reused instances, but is cleaned up when instances are unmounted.
+ *
+ * Stored state:
+ *   - layout: computed rect from layout pass
+ *   - hover: mouse hover state
+ *   - pressed: mouse press state
+ *   - focusable: whether widget can receive focus
+ *   - tabIndex: position in focus traversal order
+ *
+ * @see docs/guide/runtime-and-layout.md
+ */
+import type { InstanceId } from "./instance.js";
+/** Rectangle in terminal cell coordinates. */
+export type Rect = Readonly<{
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}>;
+/** Local state stored per widget instance. */
+export type RuntimeLocalState = Readonly<{
+    layout: Rect | null;
+    hover: boolean;
+    pressed: boolean;
+    focusable: boolean;
+    tabIndex: number | null;
+}>;
+/** Local state for virtualList instances. */
+export type VirtualListLocalState = Readonly<{
+    scrollTop: number;
+    selectedIndex: number;
+    viewportHeight: number;
+    /** First visible item index (derived from scrollTop). */
+    startIndex: number;
+    /** One past last visible item index (derived from scrollTop + viewportHeight). */
+    endIndex: number;
+    /**
+     * Cached measured heights (index -> height) used by estimateItemHeight mode.
+     * Internal detail; consumers should treat this as read-only snapshot state.
+     */
+    measuredHeights?: ReadonlyMap<number, number>;
+    /** Width used when building `measuredHeights`. */
+    measuredWidth?: number;
+    /** Item count used when building `measuredHeights`. */
+    measuredItemCount?: number;
+}>;
+/** Partial update to local state (undefined fields are not changed). */
+export type RuntimeLocalStatePatch = Readonly<{
+    layout?: Rect | null;
+    hover?: boolean;
+    pressed?: boolean;
+    focusable?: boolean;
+    tabIndex?: number | null;
+}>;
+/** Store interface for per-instance local state. */
+export type RuntimeLocalStateStore = Readonly<{
+    get: (instanceId: InstanceId) => RuntimeLocalState | undefined;
+    set: (instanceId: InstanceId, patch: RuntimeLocalStatePatch) => RuntimeLocalState;
+    delete: (instanceId: InstanceId) => void;
+}>;
+/** Create a new local state store instance. */
+export declare function createRuntimeLocalStateStore(): RuntimeLocalStateStore;
+/** Partial update to virtual list state. */
+export type VirtualListLocalStatePatch = Readonly<{
+    scrollTop?: number;
+    selectedIndex?: number;
+    viewportHeight?: number;
+    startIndex?: number;
+    endIndex?: number;
+    measuredHeights?: ReadonlyMap<number, number>;
+    measuredWidth?: number;
+    measuredItemCount?: number;
+}>;
+/** Store interface for per-instance virtual list state. */
+export type VirtualListStateStore = Readonly<{
+    get: (id: string) => VirtualListLocalState;
+    set: (id: string, patch: VirtualListLocalStatePatch) => VirtualListLocalState;
+    delete: (id: string) => void;
+    keys: () => IterableIterator<string>;
+}>;
+/** Create a new virtual list state store instance. */
+export declare function createVirtualListStateStore(): VirtualListStateStore;
+/** Local state for table instances. */
+export type TableLocalState = Readonly<{
+    /** Current scroll position (row offset). */
+    scrollTop: number;
+    /** Index of the focused row (-1 if none). */
+    focusedRowIndex: number;
+    /** Index of the focused header column (when focusedRowIndex === -1). */
+    focusedColumnIndex: number;
+    /** Last clicked row key (for shift-select). */
+    lastClickedKey: string | null;
+    /** Viewport height in rows. */
+    viewportHeight: number;
+    /** First visible row index (derived). */
+    startIndex: number;
+    /** One past last visible row index (derived). */
+    endIndex: number;
+}>;
+/** Partial update to table state. */
+export type TableLocalStatePatch = Readonly<{
+    scrollTop?: number;
+    focusedRowIndex?: number;
+    focusedColumnIndex?: number;
+    lastClickedKey?: string | null;
+    viewportHeight?: number;
+    startIndex?: number;
+    endIndex?: number;
+}>;
+/** Store interface for per-instance table state. */
+export type TableStateStore = Readonly<{
+    get: (id: string) => TableLocalState;
+    set: (id: string, patch: TableLocalStatePatch) => TableLocalState;
+    delete: (id: string) => void;
+    keys: () => IterableIterator<string>;
+}>;
+/** Create a new table state store instance. */
+export declare function createTableStateStore(): TableStateStore;
+/** Local state for tree instances. */
+export type TreeLocalState = Readonly<{
+    /** Key of the focused node (null if none). */
+    focusedKey: string | null;
+    /** Set of node keys currently loading. */
+    loadingKeys: ReadonlySet<string>;
+    /** Scroll position for virtualized trees. */
+    scrollTop: number;
+    /** Viewport height for virtualization. */
+    viewportHeight: number;
+    /**
+     * Cached flattened nodes for tree-like widgets (tree/filePicker/fileTreeExplorer).
+     * Used to avoid per-frame allocations when inputs are referentially stable.
+     */
+    flatCache: TreeFlatCache | null;
+    /** Cached expanded set (for faster lookup). */
+    expandedSetRef: readonly string[] | undefined;
+    expandedSet: ReadonlySet<string> | undefined;
+    /** Cached tree line prefixes keyed to flatNodes/showLines/indentSize. */
+    prefixCache: TreePrefixCache | null;
+}>;
+export type TreePrefixCache = Readonly<{
+    flatNodesRef: readonly unknown[];
+    showLines: boolean;
+    indentSize: number;
+    prefixes: readonly string[];
+}>;
+export type TreeFlatCache = Readonly<{
+    kind: "fileNode" | "tree";
+    dataRef: unknown;
+    expandedRef: readonly string[];
+    /** Optional file-picker filter identity (used only for kind="fileNode"). */
+    filterRef?: string | undefined;
+    /** Optional hidden-file visibility flag (used only for kind="fileNode"). */
+    showHiddenRef?: boolean | undefined;
+    /** Loaded-children map identity (only used for kind="tree"). */
+    loadedRef?: unknown;
+    /** Key function identity (only used for kind="tree"). */
+    getKeyRef: unknown;
+    /** Children function identity (only used for kind="tree"). */
+    getChildrenRef: unknown;
+    /** hasChildren function identity (only used for kind="tree"). */
+    hasChildrenRef: unknown;
+    /** Flattened nodes (typed by kind at call sites). */
+    flatNodes: readonly unknown[];
+}>;
+/** Partial update to tree state. */
+export type TreeLocalStatePatch = Readonly<{
+    focusedKey?: string | null;
+    loadingKeys?: ReadonlySet<string>;
+    scrollTop?: number;
+    viewportHeight?: number;
+    flatCache?: TreeFlatCache | null;
+    expandedSetRef?: readonly string[];
+    expandedSet?: ReadonlySet<string>;
+    prefixCache?: TreePrefixCache | null;
+}>;
+/** Store interface for per-instance tree state. */
+export type TreeStateStore = Readonly<{
+    get: (id: string) => TreeLocalState;
+    set: (id: string, patch: TreeLocalStatePatch) => TreeLocalState;
+    delete: (id: string) => void;
+    keys: () => IterableIterator<string>;
+    /** Add a key to the loading set. */
+    startLoading: (id: string, nodeKey: string) => TreeLocalState;
+    /** Remove a key from the loading set. */
+    finishLoading: (id: string, nodeKey: string) => TreeLocalState;
+}>;
+/** Create a new tree state store instance. */
+export declare function createTreeStateStore(): TreeStateStore;
+//# sourceMappingURL=localState.d.ts.map

package/dist/runtime/localState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"localState.d.ts","sourceRoot":"","sources":["../../src/runtime/localState.ts"],"names":[],"mappings":"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"}