phonux 0.1.0

package/windowOverlay.js

@@ -0,0 +1,137 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * WindowOverlay: how a view shows something over the WINDOW (a dialog, a full-screen viewer, a toast) with no
+ * host wiring and no Portal. It registers its children with a store, and the host's two OverlaySlots render
+ * them. Usage, why content is hoisted, and the numbered contract the content must keep (the layer adds no
+ * wrapper, so it cannot enforce it): DESIGN.md, "`WindowOverlay`: window-level content with no Portal".
+ * Not to be confused with Panel's `overlay` prop, which decorates ONE view and is clipped to it.
+ */
+import * as React from 'react';
+import { Fragment, createContext, useContext, useEffect, useId, useLayoutEffect, useState, useSyncExternalStore } from 'react';
+/**
+ * The z-index each slot's content applies to ITS OWN root. WindowOverlay adds no wrapper element,
+ * so it cannot set it for you. dialog 2000 clears the host's 1400 drag strip (the Closed Pages viewer);
+ * toast 1400 is MUI's snackbar band (the undo toast).
+ * @public
+ */
+export const OVERLAY_Z = { dialog: 2000, toast: 1400 };
+const EMPTY = Object.freeze([]);
+/** External store, NOT React state: a registration re-renders neither the host nor any view. @public */
+export class OverlayStore {
+    entries = new Map(); // Map keeps FIRST-insertion position across overwrites
+    listeners = new Set();
+    slots = new Map();
+    warned = new Set();
+    snap = { dialog: EMPTY, toast: EMPTY };
+    /** Count of listener notifications (test seam: pins the same-node short-circuit). */
+    notifications = 0;
+    set(id, entry) {
+        const prev = this.entries.get(id);
+        if (prev && prev.slot === entry.slot && prev.node === entry.node)
+            return;
+        this.entries.set(id, entry);
+        this.rebuild(entry.slot);
+        if (prev && prev.slot !== entry.slot)
+            this.rebuild(prev.slot);
+        this.emit();
+    }
+    remove(id) {
+        const prev = this.entries.get(id);
+        if (!prev)
+            return;
+        this.entries.delete(id);
+        this.rebuild(prev.slot);
+        this.emit();
+    }
+    mountSlot(name) {
+        this.slots.set(name, (this.slots.get(name) ?? 0) + 1);
+        return () => void this.slots.set(name, (this.slots.get(name) ?? 1) - 1);
+    }
+    hasSlot(name) {
+        return (this.slots.get(name) ?? 0) > 0;
+    }
+    /** True once per slot name per store: the caller logs the "no slot" error only the first time. */
+    firstWarning(name) {
+        if (this.warned.has(name))
+            return false;
+        this.warned.add(name);
+        return true;
+    }
+    subscribe = (l) => {
+        this.listeners.add(l);
+        return () => void this.listeners.delete(l);
+    };
+    read(slot) {
+        return this.snap[slot];
+    }
+    /** Ids in registration order across both slots (test seam). */
+    ids() {
+        return [...this.entries.keys()];
+    }
+    rebuild(slot) {
+        const items = [];
+        for (const [id, e] of this.entries)
+            if (e.slot === slot)
+                items.push({ id, node: e.node });
+        this.snap = { ...this.snap, [slot]: items.length ? items : EMPTY };
+    }
+    emit() {
+        this.notifications += 1;
+        for (const l of [...this.listeners])
+            l();
+    }
+}
+const StoreContext = createContext(null);
+const noopSubscribe = () => () => { };
+/**
+ * Rendered by HostProvider, so a host adds nothing. The store is never part of the app-supplied Host bag
+ * (nothing about an overlay is app-specific). `store` is a TEST SEAM: a test passes its own to read `notifications`/`ids()`.
+ * @public
+ */
+export function OverlayProvider({ children, store: injected }) {
+    const [store] = useState(() => injected ?? new OverlayStore()); // pure constructor: StrictMode's double init is harmless
+    return _jsx(StoreContext.Provider, { value: store, children: children }); // stable value: never re-renders consumers
+}
+/** Mounted by the HOST once per slot. Emits NO element: hoisted overlays become its parent's direct children. @public */
+export const OverlaySlot = React.memo(function OverlaySlot({ name }) {
+    const store = useContext(StoreContext);
+    useLayoutEffect(() => store?.mountSlot(name), [store, name]);
+    // A slot outside the provider sees an empty store forever: a host bug that would otherwise be silent.
+    useEffect(() => {
+        if (store === null)
+            console.error(`OverlaySlot name="${name}": rendered outside <OverlayProvider> (HostProvider renders it), so nothing hoisted will ever show here.`);
+    }, [store, name]);
+    const items = useSyncExternalStore(store ? store.subscribe : noopSubscribe, () => (store ? store.read(name) : EMPTY), () => EMPTY);
+    return _jsx(_Fragment, { children: items.map((i) => _jsx(Fragment, { children: i.node }, i.id)) });
+});
+/**
+ * Render this anywhere in a view, at any depth. Its children appear in the matching OverlaySlot.
+ * With no provider, or under renderToStaticMarkup (no effects), the children render IN PLACE instead.
+ * @public
+ */
+export function WindowOverlay({ slot = 'dialog', open = true, children }) {
+    const store = useContext(StoreContext);
+    // getServerSnapshot -> false (static markup); a client render with a provider -> true on the first pass.
+    const hoisting = useSyncExternalStore(noopSubscribe, () => store !== null, () => false);
+    const id = useId();
+    const active = hoisting && open && store !== null;
+    // Every commit: `children` is a fresh element each render. The store skips an identical node.
+    useLayoutEffect(() => {
+        if (active)
+            store.set(id, { slot, node: children });
+    });
+    // Unregister on unmount, close and slot change. Order against the set-effect above is not load-bearing:
+    // React runs every cleanup of a commit, StrictMode's simulated remount included, before any setup.
+    useLayoutEffect(() => () => {
+        store?.remove(id);
+    }, [store, id, active, slot]);
+    // Passive on purpose: by now every slot's layout effect has run, so "no slot" really means none.
+    useEffect(() => {
+        if (active && !store.hasSlot(slot) && store.firstWarning(slot)) {
+            console.error(`WindowOverlay: no <OverlaySlot name="${slot}"> is mounted, so this overlay will never be shown.`);
+        }
+    }, [active, store, slot]);
+    if (!open)
+        return null;
+    return active ? null : _jsx(_Fragment, { children: children });
+}

package/workspaceState.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Workspace state as a saved file: the JSON shape, its guard, and the pure pair that turns the panel list into
+ * that shape and back. DESIGN.md ("Workspace state persistence") holds the rules; this file holds no React and
+ * no host code.
+ */
+import type { FormFactor, JsonValue } from './hostApi.js';
+import { type PanelWindow } from './panelWindow.js';
+/**
+ * One saved panel. `id` only names this panel inside its own file, so an `anchor` can point at another entry;
+ * it is replaced on restore. Never saved: `hostData`, `size`, `locked`, `collapsible`, `anchoredEnter` and the
+ * host's root column.
+ * @public
+ */
+export type WorkspacePanelState = {
+    id: string;
+    view: string;
+    url: string;
+    title?: string;
+    params?: JsonValue;
+    listed?: boolean;
+    live: boolean;
+    anchor: {
+        panel: string;
+        position: 'left' | 'right';
+        priority: number;
+    };
+    formFactor?: FormFactor;
+    permanent?: boolean;
+    layer?: 'base' | 'raised';
+};
+/**
+ * The saved workspace: a version and one entry per saved panel, in row order. The host's root column is not in it.
+ * @public
+ */
+export type WorkspaceState = {
+    version: 1;
+    panels: WorkspacePanelState[];
+};
+/**
+ * What a host implements to keep the workspace between launches. `load` resolves the saved state, or `null` when
+ * there is none. `save` is fire-and-forget and must not throw.
+ * @public
+ */
+export type WorkspaceStorage = {
+    load(): Promise<WorkspaceState | null>;
+    save(state: WorkspaceState): void;
+};
+/**
+ * Whether `value` is a workspace file this version understands: version 1, a `panels` array of well-typed entries
+ * with unique ids. Unknown extra keys are accepted (a later optional field is additive); `params` is not deep-checked.
+ */
+export declare function isWorkspaceState(value: unknown): value is WorkspaceState;
+/**
+ * The saved form of `panels`: every entry but the root, with only the documented keys. `permanent` is derived
+ * (`!collapsible`) because PanelWindow has no such field, and an absent optional stays absent so no key holds
+ * `undefined`.
+ */
+export declare function projectWorkspaceState(panels: readonly PanelWindow[], rootId: string): WorkspaceState;
+/**
+ * The panels `state` describes, in row order and without the root, each under a fresh id from `freshId`. `hostData`
+ * is left for the caller: only the host knows what a new panel carries.
+ */
+export declare function hydrateWorkspaceState(state: WorkspaceState, freshId: () => string, rootId: string): PanelWindow[];

package/workspaceState.js

@@ -0,0 +1,95 @@
+import { computeRowOrder, deriveAnchorsFromOrder } from './panelRowOrder.js';
+import { appendPanel } from './panelWindow.js';
+const FORM_FACTORS = ['phone', 'tablet', 'desktop'];
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const isOptional = (value, type) => value === undefined || typeof value === type;
+function isSavedPanel(value) {
+    if (!isRecord(value))
+        return false;
+    const { anchor } = value;
+    return (typeof value.id === 'string' &&
+        typeof value.view === 'string' &&
+        typeof value.url === 'string' &&
+        typeof value.live === 'boolean' &&
+        isOptional(value.title, 'string') &&
+        isOptional(value.listed, 'boolean') &&
+        isOptional(value.permanent, 'boolean') &&
+        (value.formFactor === undefined || FORM_FACTORS.includes(value.formFactor)) &&
+        (value.layer === undefined || value.layer === 'base' || value.layer === 'raised') &&
+        isRecord(anchor) &&
+        typeof anchor.panel === 'string' &&
+        (anchor.position === 'left' || anchor.position === 'right') &&
+        typeof anchor.priority === 'number' &&
+        Number.isFinite(anchor.priority));
+}
+/**
+ * Whether `value` is a workspace file this version understands: version 1, a `panels` array of well-typed entries
+ * with unique ids. Unknown extra keys are accepted (a later optional field is additive); `params` is not deep-checked.
+ */
+export function isWorkspaceState(value) {
+    if (!isRecord(value) || value.version !== 1 || !Array.isArray(value.panels))
+        return false;
+    const panels = value.panels;
+    if (!panels.every(isSavedPanel))
+        return false;
+    return new Set(panels.map((p) => p.id)).size === panels.length;
+}
+/**
+ * The saved form of `panels`: every entry but the root, with only the documented keys. `permanent` is derived
+ * (`!collapsible`) because PanelWindow has no such field, and an absent optional stays absent so no key holds
+ * `undefined`.
+ */
+export function projectWorkspaceState(panels, rootId) {
+    const positional = new Map(deriveAnchorsFromOrder(panels, rootId).map((p) => [p.id, p.anchor]));
+    return {
+        version: 1,
+        panels: panels
+            .filter((p) => p.id !== rootId)
+            .map((p) => {
+            const anchor = p.anchor ?? positional.get(p.id);
+            return {
+                id: p.id,
+                view: p.view,
+                url: p.url,
+                ...(p.title !== undefined ? { title: p.title } : {}),
+                ...(p.params !== undefined ? { params: p.params } : {}),
+                ...(p.listed !== undefined ? { listed: p.listed } : {}),
+                live: p.live,
+                anchor: { panel: anchor.panel, position: anchor.position, priority: anchor.priority },
+                ...(p.formFactor !== undefined ? { formFactor: p.formFactor } : {}),
+                ...(!p.collapsible ? { permanent: true } : {}),
+                ...(p.layer !== undefined ? { layer: p.layer } : {}),
+            };
+        }),
+    };
+}
+/**
+ * The panels `state` describes, in row order and without the root, each under a fresh id from `freshId`. `hostData`
+ * is left for the caller: only the host knows what a new panel carries.
+ */
+export function hydrateWorkspaceState(state, freshId, rootId) {
+    // Every entry's id is drawn before anything else, so a saved id that happens to equal a fresh one is never reused.
+    const fresh = state.panels.map(() => freshId());
+    const freshOf = new Map(state.panels.map((s, i) => [s.id, fresh[i]]));
+    // One id nothing else holds stands in for every anchor target the file does not contain: a saved id kept as it
+    // is could equal a fresh one (both count up from 1 each launch) and attach the panel to a stranger.
+    let missing;
+    const targetOf = (saved) => {
+        if (saved === rootId)
+            return rootId;
+        const mapped = freshOf.get(saved);
+        if (mapped !== undefined)
+            return mapped;
+        missing ??= freshId();
+        return missing;
+    };
+    const built = state.panels.map((s, i) => {
+        // appendPanel owns the creation rules (permanent forces listed false and phone, size comes from the tier).
+        const entry = appendPanel([], { url: s.url, view: s.view, title: s.title, params: s.params, listed: s.listed, layer: s.layer, formFactor: s.formFactor, permanent: s.permanent }, fresh[i], rootId)[0];
+        // A permanent column is never parked, so one saved as parked would never render and never be revealed.
+        const live = s.permanent === true ? true : s.live;
+        return { ...entry, live, anchor: { panel: targetOf(s.anchor.panel), position: s.anchor.position, priority: s.anchor.priority } };
+    });
+    // One pass over the whole set: placing entries one at a time would rewrite an anchor that names a later entry.
+    return computeRowOrder(built, rootId);
+}