sh3-core 0.1.0

package/dist/layout/drag.svelte.js

@@ -0,0 +1,191 @@
+/*
+ * Tab drag engine — state machine + global listeners + commit.
+ *
+ * Lifecycle:
+ *   1. TabbedPanel fires `beginTabDrag(slotId, entry, pointerEvent)`
+ *      from pointerdown on a tab. The engine records the starting
+ *      pointer position and the source slotId but does NOT enter the
+ *      "dragging" phase yet.
+ *   2. A global pointermove listener watches for movement exceeding
+ *      DRAG_THRESHOLD_PX. Clicks that never cross the threshold are
+ *      not drags — they fall through to the tab's own click handler.
+ *   3. On threshold cross, the engine transitions to `dragging` and
+ *      starts tracking the pointer; the status (visible ghost, drop
+ *      indicators) is driven by the reactive state.
+ *   4. pointerup commits a drop target (if one is currently hovered)
+ *      and tears down. No commit if the user released over nothing.
+ *
+ * State shape:
+ *   The engine exposes a single `dragState` $state object. Components
+ *   subscribe by reading its fields in a $derived or $effect. The
+ *   fields:
+ *     - phase: 'idle' | 'pending' | 'dragging'
+ *     - source: { slotId, entry } | null
+ *     - pointer: { x, y } current viewport coords while dragging
+ *     - target: DropTarget | null — where the commit would land now
+ *
+ * Drop targets:
+ *   Two kinds:
+ *     { kind: 'strip', tabsNode, insertIndex } — between tabs in a strip
+ *     { kind: 'split', path, side } — quadrant split of a node at path
+ *   The owning components compute these from their bounding rects and
+ *   call `setDropTarget` / `clearDropTarget` when the pointer enters /
+ *   leaves. Multiple overlapping targets: the one most recently set
+ *   wins (innermost component takes priority because it fires last).
+ *
+ * Commit:
+ *   `commit()` is called on pointerup. It looks at dragState.target
+ *   and runs the appropriate ops mutation against the shared root.
+ *   The root is handed to the engine on init (via `initDragEngine`)
+ *   because the engine is a module-level singleton and the root comes
+ *   from the composition layer.
+ */
+import { cleanupTree, insertTabIntoTabs, removeTabBySlotId, splitNodeAtPath, } from './ops';
+import { layoutStore } from './store.svelte';
+export const dragState = $state({
+    phase: 'idle',
+    source: null,
+    pointerX: 0,
+    pointerY: 0,
+    target: null,
+});
+/**
+ * True for exactly one macrotask after a drag ends, so the synthetic
+ * `click` the browser fires on the original tab (right after
+ * pointerup) can be ignored. Consumers check `suppressNextClick()` at
+ * the top of their click handler. Without this, the stale click would
+ * call the tab's `select(i)` on an index that no longer maps to the
+ * same tab after the layout mutation.
+ */
+let clickSuppressedUntil = 0;
+export function suppressNextClick() {
+    return performance.now() < clickSuppressedUntil;
+}
+const DRAG_THRESHOLD_PX = 4;
+let pendingStartX = 0;
+let pendingStartY = 0;
+/**
+ * Begin a potential tab drag. Call from pointerdown on a tab element.
+ * This does not yet enter the dragging phase — movement past the
+ * threshold is required.
+ */
+export function beginTabDrag(slotId, entry, event, tabElement) {
+    if (dragState.phase !== 'idle')
+        return;
+    const rect = tabElement.getBoundingClientRect();
+    dragState.phase = 'pending';
+    dragState.source = {
+        slotId,
+        entry,
+        startRect: rect,
+        offsetX: event.clientX - rect.left,
+        offsetY: event.clientY - rect.top,
+    };
+    dragState.pointerX = event.clientX;
+    dragState.pointerY = event.clientY;
+    dragState.target = null;
+    pendingStartX = event.clientX;
+    pendingStartY = event.clientY;
+    installGlobalListeners();
+}
+function installGlobalListeners() {
+    window.addEventListener('pointermove', onPointerMove, true);
+    window.addEventListener('pointerup', onPointerUp, true);
+    window.addEventListener('pointercancel', onPointerCancel, true);
+    // Lock selection / text caret during drag. Restored in teardown.
+    document.body.style.userSelect = 'none';
+    // Signal to non-drag-aware components that a drag is in progress,
+    // so they can suppress misleading hover states via CSS.
+    document.body.dataset.dragging = '';
+}
+function removeGlobalListeners() {
+    window.removeEventListener('pointermove', onPointerMove, true);
+    window.removeEventListener('pointerup', onPointerUp, true);
+    window.removeEventListener('pointercancel', onPointerCancel, true);
+    document.body.style.userSelect = '';
+    delete document.body.dataset.dragging;
+}
+function onPointerMove(e) {
+    dragState.pointerX = e.clientX;
+    dragState.pointerY = e.clientY;
+    if (dragState.phase === 'pending') {
+        const dx = e.clientX - pendingStartX;
+        const dy = e.clientY - pendingStartY;
+        if (dx * dx + dy * dy >= DRAG_THRESHOLD_PX * DRAG_THRESHOLD_PX) {
+            dragState.phase = 'dragging';
+        }
+    }
+}
+function onPointerUp(_e) {
+    const wasDragging = dragState.phase === 'dragging';
+    if (wasDragging) {
+        commit();
+        // Swallow the synthetic click that fires on the source tab
+        // immediately after pointerup. A few ms is plenty — the click
+        // is dispatched synchronously or on the next microtask.
+        clickSuppressedUntil = performance.now() + 50;
+    }
+    teardown();
+}
+function onPointerCancel(_e) {
+    teardown();
+}
+function commit() {
+    const { source, target } = dragState;
+    if (!source || !target)
+        return;
+    const root = layoutStore.root;
+    // Pulling the tab out of its source group. Must happen before the
+    // insertion so the source and destination can be the same group
+    // (reorder within a strip).
+    const removed = removeTabBySlotId(root, source.slotId);
+    if (!removed)
+        return;
+    if (target.kind === 'strip') {
+        // If the strip target is the same group we just removed from and
+        // the removal shifted subsequent indices, fix insertIndex: the
+        // engine recorded insertIndex in the pre-removal coordinate space
+        // (because the drop indicator is computed live from the DOM). If
+        // the source index is before the insertion index, subtract one.
+        // We can detect this by walking the tree to see if this tabs node
+        // is the one we mutated, but the simpler signal is: the engine
+        // sees the tab was removed from target.tabsNode iff tabsNode no
+        // longer contains the source slotId AND its length decreased. We
+        // know it decreased if the tab was in it; the ops.findTabBySlotId
+        // returned the group. Rather than re-searching, trust the caller
+        // of setDropTarget to normalize: the strip hit-test converts a
+        // same-strip hit into an index that is already in post-removal
+        // coordinates. See TabStrip.svelte.
+        insertTabIntoTabs(target.tabsNode, removed, target.insertIndex);
+    }
+    else {
+        splitNodeAtPath(root, target.path, removed, target.side);
+    }
+    cleanupTree(root);
+}
+function teardown() {
+    dragState.phase = 'idle';
+    dragState.source = null;
+    dragState.target = null;
+    removeGlobalListeners();
+}
+/**
+ * Called by drop zone components when the pointer is over them. The
+ * last call wins, so innermost / most-specific zones should call this
+ * on pointermove over their geometry. `clearDropTarget` is called when
+ * the pointer leaves.
+ */
+export function setDropTarget(target) {
+    if (dragState.phase !== 'dragging')
+        return;
+    dragState.target = target;
+}
+export function clearDropTarget(match) {
+    if (dragState.phase !== 'dragging')
+        return;
+    if (!dragState.target)
+        return;
+    if (match && !match(dragState.target))
+        return;
+    dragState.target = null;
+}

package/dist/layout/inspection.d.ts

@@ -0,0 +1,52 @@
+import type { LayoutNode, TabEntry } from './types';
+/**
+ * Read-only snapshot of the currently-rendered layout tree. The return
+ * value is the live object — callers MUST NOT mutate it directly;
+ * mutations go through `spliceIntoActiveLayout`. Returning the live
+ * object (not a deep clone) means reactive consumers can re-read on
+ * updates without manual subscription wiring.
+ */
+export declare function inspectActiveLayout(): {
+    root: LayoutNode;
+    source: 'home' | 'app';
+};
+/**
+ * Add a new tab at the end of the first tabs group found in the
+ * currently-rendered layout. If no tabs group exists (e.g. the active
+ * root is the single-slot home layout), throws. Phase 8 scope — richer
+ * variants arrive later.
+ */
+export declare function spliceIntoActiveLayout(entry: TabEntry): void;
+/**
+ * Activate the tab whose slot matches `slotId` in the currently-rendered
+ * layout. Returns `true` if a matching tab was found and activated.
+ */
+export declare function focusTab(slotId: string): boolean;
+/**
+ * Activate the first tab whose `viewId` matches in the currently-rendered
+ * layout. Returns `true` if a matching tab was found and activated.
+ */
+export declare function focusView(viewId: string): boolean;
+/**
+ * Collapse a child of a split node at the given path. Returns true if
+ * the split was found and the child was collapsed.
+ */
+export declare function collapseChild(splitPath: number[], childIndex: number): boolean;
+/**
+ * Expand a previously collapsed child of a split node. Returns true if
+ * the split was found and the child was expanded.
+ */
+export declare function expandChild(splitPath: number[], childIndex: number): boolean;
+/**
+ * Request to close a tab by its slot ID. Respects the view's closable
+ * policy:
+ *   - Non-closable (closable undefined/false): returns false immediately.
+ *   - Pure (closable true): removes the tab, returns true.
+ *   - Guarded (closable { canClose }): awaits canClose(); removes if
+ *     resolved true, returns false if resolved false.
+ *
+ * This is the single entry point for closing tabs — the tab strip's X
+ * button and programmatic callers both use it. The layout engine remains
+ * the sole authority on tree mutations.
+ */
+export declare function closeTab(slotId: string): Promise<boolean>;

package/dist/layout/inspection.js

@@ -0,0 +1,157 @@
+/*
+ * Layout inspection / mutation — public API for advanced shards.
+ *
+ * These helpers are how shards like `diagnostic` inject themselves into
+ * the currently-rendered layout. The mutation primitives delegate to
+ * ops.ts for the actual tree work; inspection reads through the layout
+ * manager so diagnostic content stays live as the user rearranges things.
+ *
+ * Scope note: `spliceIntoActiveLayout` targets the CURRENTLY-RENDERED
+ * root only. Mutating a held-but-not-active app tree (e.g. while the
+ * user is on home) is not supported in phase 8. If an advanced shard
+ * wants to reach the held tree, it has to do so while the app is
+ * rendered.
+ */
+import { activeLayout, getActiveRoot } from './store.svelte';
+import { nodeAtPath, findTabBySlotId, removeTabBySlotId, cleanupTree } from './ops';
+import { getSlotHandle } from './slotHostPool.svelte';
+/**
+ * Read-only snapshot of the currently-rendered layout tree. The return
+ * value is the live object — callers MUST NOT mutate it directly;
+ * mutations go through `spliceIntoActiveLayout`. Returning the live
+ * object (not a deep clone) means reactive consumers can re-read on
+ * updates without manual subscription wiring.
+ */
+export function inspectActiveLayout() {
+    return { root: activeLayout(), source: getActiveRoot() };
+}
+/**
+ * Add a new tab at the end of the first tabs group found in the
+ * currently-rendered layout. If no tabs group exists (e.g. the active
+ * root is the single-slot home layout), throws. Phase 8 scope — richer
+ * variants arrive later.
+ */
+export function spliceIntoActiveLayout(entry) {
+    const root = activeLayout();
+    const target = findFirstTabsNode(root);
+    if (!target) {
+        throw new Error('spliceIntoActiveLayout: no tabs group found in the active layout; ' +
+            'phase 8 only supports splicing into an existing tab group.');
+    }
+    target.tabs.push(entry);
+    target.activeTab = target.tabs.length - 1;
+}
+/**
+ * Activate the tab whose slot matches `slotId` in the currently-rendered
+ * layout. Returns `true` if a matching tab was found and activated.
+ */
+export function focusTab(slotId) {
+    const root = activeLayout();
+    return focusTabWhere(root, (entry) => entry.slotId === slotId);
+}
+/**
+ * Activate the first tab whose `viewId` matches in the currently-rendered
+ * layout. Returns `true` if a matching tab was found and activated.
+ */
+export function focusView(viewId) {
+    const root = activeLayout();
+    return focusTabWhere(root, (entry) => entry.viewId === viewId);
+}
+/** Walk the tree looking for a tab entry that satisfies `pred`, activate it. */
+function focusTabWhere(node, pred) {
+    if (node.type === 'tabs') {
+        const idx = node.tabs.findIndex(pred);
+        if (idx >= 0) {
+            node.activeTab = idx;
+            return true;
+        }
+        return false;
+    }
+    if (node.type === 'split') {
+        for (const child of node.children) {
+            if (focusTabWhere(child, pred))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Collapse a child of a split node at the given path. Returns true if
+ * the split was found and the child was collapsed.
+ */
+export function collapseChild(splitPath, childIndex) {
+    return setCollapsed(splitPath, childIndex, true);
+}
+/**
+ * Expand a previously collapsed child of a split node. Returns true if
+ * the split was found and the child was expanded.
+ */
+export function expandChild(splitPath, childIndex) {
+    return setCollapsed(splitPath, childIndex, false);
+}
+function setCollapsed(splitPath, childIndex, value) {
+    const root = activeLayout();
+    const node = nodeAtPath(root, splitPath);
+    if (!node || node.type !== 'split')
+        return false;
+    const split = node;
+    if (childIndex < 0 || childIndex >= split.children.length)
+        return false;
+    if (!split.collapsed)
+        split.collapsed = split.children.map(() => false);
+    split.collapsed[childIndex] = value;
+    return true;
+}
+/**
+ * Request to close a tab by its slot ID. Respects the view's closable
+ * policy:
+ *   - Non-closable (closable undefined/false): returns false immediately.
+ *   - Pure (closable true): removes the tab, returns true.
+ *   - Guarded (closable { canClose }): awaits canClose(); removes if
+ *     resolved true, returns false if resolved false.
+ *
+ * This is the single entry point for closing tabs — the tab strip's X
+ * button and programmatic callers both use it. The layout engine remains
+ * the sole authority on tree mutations.
+ */
+export async function closeTab(slotId) {
+    const root = activeLayout();
+    const located = findTabBySlotId(root, slotId);
+    if (!located)
+        return false;
+    const handle = getSlotHandle(slotId);
+    const closable = handle === null || handle === void 0 ? void 0 : handle.closable;
+    // Non-closable: no action.
+    if (!closable)
+        return false;
+    // Guarded: ask the shard.
+    if (typeof closable === 'object') {
+        const allowed = await closable.canClose();
+        if (!allowed)
+            return false;
+        // Re-verify the tab still exists after the async gap — another close
+        // request or a layout mutation may have removed it while we awaited.
+        if (!findTabBySlotId(root, slotId))
+            return false;
+    }
+    // Remove the tab from the tree. This causes Svelte to tear down the
+    // SlotContainer, which calls releaseSlotHost() — the pool's deferred
+    // destroy microtask then fires handle.unmount(). We do NOT call
+    // releaseSlotHost here; the existing component lifecycle handles it.
+    removeTabBySlotId(root, slotId);
+    // Cleanup: prune empty (non-persistent) tab groups, collapse single-child splits.
+    cleanupTree(root);
+    return true;
+}
+function findFirstTabsNode(node) {
+    if (node.type === 'tabs')
+        return node;
+    if (node.type === 'split') {
+        for (const c of node.children) {
+            const hit = findFirstTabsNode(c);
+            if (hit)
+                return hit;
+        }
+    }
+    return null;
+}

package/dist/layout/ops.d.ts

@@ -0,0 +1,78 @@
+import type { LayoutNode, SplitNode, TabsNode, SlotNode, TabEntry } from './types';
+/** A path down the tree: the list of child indices walked from the root. */
+export type LayoutPath = number[];
+/** A located tab: where it lives and which entry index inside its group. */
+export interface LocatedTab {
+    tabsNode: TabsNode;
+    tabsPath: LayoutPath;
+    tabIndex: number;
+    entry: TabEntry;
+}
+/**
+ * Find a tab by its slotId anywhere in the tree. Returns null if no
+ * tab carries that slotId. Used by the drag engine to look up the
+ * source tab before any mutation.
+ */
+export declare function findTabBySlotId(root: LayoutNode, slotId: string): LocatedTab | null;
+/** Find a standalone slot leaf by its slotId (only leaves, not tab entries). */
+export declare function findSlotBySlotId(root: LayoutNode, slotId: string): {
+    node: SlotNode;
+    parent: SplitNode | null;
+    index: number;
+} | null;
+/**
+ * Remove a tab from its current location, returning the removed entry
+ * (or null if not found). The tabs group it was in may become empty
+ * and is cleaned up by `cleanupTree` after the caller has finished its
+ * reinsertion. The two-phase shape (mutate → cleanup) means the caller
+ * can remove a tab and re-insert it into the SAME tabs group without
+ * the group being collapsed mid-move.
+ */
+export declare function removeTabBySlotId(root: LayoutNode, slotId: string): TabEntry | null;
+/**
+ * Insert a tab entry into an existing tabs group at a specific index.
+ * Clamps the index into range. The inserted tab becomes active — the
+ * user's drag landed there, so they want to see it.
+ */
+export declare function insertTabIntoTabs(tabsNode: TabsNode, entry: TabEntry, index: number): void;
+/** Which side of a split the dropped tab should land on. */
+export type SplitSide = 'left' | 'right' | 'top' | 'bottom';
+/**
+ * Split a slot-leaf (or tabs-leaf) into a new SplitNode, placing a
+ * single-tab group containing `entry` on the requested side and the
+ * existing node on the other side. The existing node is preserved
+ * as-is (it keeps its slotId, viewId, etc. — critical for re-parenting
+ * of the untouched side).
+ *
+ * Sides map to split direction:
+ *   left/right → horizontal split, new tab goes left or right
+ *   top/bottom → vertical split,   new tab goes top or bottom
+ *
+ * The target is identified by a LayoutPath from the root, because
+ * splitting requires rewriting the parent's child array and we need
+ * the parent reference. If the target IS the root, the root itself is
+ * replaced — callers that pass the root by reference need the wrapper
+ * form, so this function returns the new subtree and the caller
+ * reassigns parent.children[i] = returned value (or reassigns root).
+ */
+export declare function makeSplitWithNewTab(existing: LayoutNode, entry: TabEntry, side: SplitSide): SplitNode;
+/**
+ * Apply a slot-split as a tree mutation: find the target node at the
+ * given path and replace it with a new split. Handles the root case
+ * (path = []) by mutating the root's fields in place. The root object
+ * identity is preserved so Svelte's $state proxy keeps its reactivity.
+ */
+export declare function splitNodeAtPath(root: LayoutNode, path: LayoutPath, entry: TabEntry, side: SplitSide): void;
+/** Walk a LayoutPath and return the node at its tip, or null. */
+export declare function nodeAtPath(root: LayoutNode, path: LayoutPath): LayoutNode | null;
+/**
+ * Post-mutation cleanup pass. Removes empty tabs groups from their
+ * parents and collapses single-child splits. Runs until the tree
+ * stabilizes (a collapse can reveal another single-child split one
+ * level up).
+ *
+ * Called once at the end of every drag commit. Called separately from
+ * the mutation primitives so callers can do "remove then insert into
+ * the same group" without the group being collapsed between calls.
+ */
+export declare function cleanupTree(root: LayoutNode): void;