@peter.prib/renderengine 0.0.0-stage → 0.2.0

package/src/workspace/workArea.js

@@ -0,0 +1,413 @@
+/**
+ * WorkArea — the IDE-style editor area: several views open at once, in tab
+ * groups that can sit side by side.
+ *
+ * The whole point is the separation the plain `tabs`/`split` layout does not
+ * make on its own: a view being OPEN (it has a tab) is not the same as it being
+ * VISIBLE (its tab is selected in a group that is on screen). A shell that
+ * rebuilds a fixed layout per view can only ever show one; a work area lets you
+ * put the data model next to the notebook that queries it.
+ *
+ * Structure lives in `workAreaModel.js` as pure functions over plain JSON, and
+ * this class is the thin rendering shell over them:
+ *
+ *   model (JSON)  --createLayout-->  live layout tree  --serialize-->  model
+ *
+ * The live tree is authoritative for the things the user adjusts directly —
+ * splitter positions, which tab is selected — so every structural change starts
+ * by reading them back out of it (`_syncFromTree`). Rebuilding the subtree
+ * afterwards is cheap and non-destructive: `PartNode.dispose()` only detaches a
+ * part and `Part.mount()` re-parents it, so a part keeps its DOM, its state and
+ * its bus subscriptions across the rebuild.
+ *
+ * Selecting a tab does NOT rebuild, though — the pane elements are what scroll,
+ * and replacing them would throw away scroll position on every tab click.
+ */
+import { createLayout } from './layout/index.js';
+import { el } from './dom.js';
+import {
+    emptyWorkArea, listGroups, listOpenParts, findPart,
+    openPart, closePart, focusPart,
+} from './workAreaModel.js';
+
+export class WorkArea {
+    /**
+     * @param {object}   [options]
+     * @param {object}   [options.area]           serialized area to restore
+     * @param {string}   [options.activeGroupId]  group new views open into
+     * @param {Function} [options.onChange]       ({ area, activeGroupId, reason }) — persist here
+     * @param {*}        [options.placeholder]    el() spec shown when nothing is open
+     * @param {Element}  [options.actionsHost]    filled with the focused view's `actions`
+     * @param {Element}  [options.outlineHost]    filled with the focused view's outline part
+     * @param {Function} [options.outlineFor]     (partId) => outline partId | null
+     * @param {*}        [options.outlinePlaceholder] el() spec when a view has no outline
+     * @param {Function} [options.beforeClose]    (partId) => false to keep a tab its close button was
+     *                                            pressed on (unsaved work, say); the handler may close it later
+     */
+    constructor({
+        area, activeGroupId, onChange, placeholder,
+        actionsHost, outlineHost, outlineFor, outlinePlaceholder, beforeClose,
+    } = {}) {
+        this.area = area ?? emptyWorkArea();
+        this.activeGroupId = activeGroupId ?? listGroups(this.area)[0]?.id ?? null;
+        this.onChange = onChange ?? null;
+        this.beforeClose = beforeClose ?? null;
+        this.placeholder = placeholder ?? { cls: 'ws-workarea-empty', text: 'Nothing open' };
+        this.host = null;
+        this.ctx = null;
+        this._tree = null;
+        this._outerCtx = null;
+
+        // Frame slots. Both are filled from whichever view has FOCUS, which is
+        // the whole reason they live here: the work area is the only thing that
+        // knows what that is.
+        this.actionsHost = actionsHost ?? null;
+        this.outlineHost = outlineHost ?? null;
+        this.outlineFor = outlineFor ?? null;
+        this.outlinePlaceholder = outlinePlaceholder ?? null;
+        this._outlinePart = null;
+        this._slotPartId = null;
+    }
+
+    /* ── Queries ────────────────────────────────────────────────────────── */
+
+    /** Every open part id, in group order. */
+    openParts() { return listOpenParts(this.area); }
+
+    isOpen(partId) { return !!findPart(this.area, partId); }
+
+    /** The part id selected in each group — i.e. what is actually on screen. */
+    visibleParts() {
+        return listGroups(this.area)
+            .map(g => g.children?.[g.active ?? 0]?.partId)
+            .filter(Boolean);
+    }
+
+    /**
+     * The view with focus: the selected tab of the active group. This is what a
+     * shell keys its chrome off — window title, breadcrumb, which toolbar
+     * belongs to what — and it is not the same as "the last thing opened",
+     * because clicking into another group changes it.
+     */
+    activePart() {
+        const groups = listGroups(this.area);
+        const group = groups.find(g => g.id === this.activeGroupId) ?? groups[0];
+        return group?.children?.[group.active ?? 0]?.partId ?? null;
+    }
+
+    groupCount() { return listGroups(this.area).length; }
+
+    /** `{ area, activeGroupId }` — hand straight to a store, pass back to the ctor. */
+    serialize() {
+        this._syncFromTree();
+        return { area: this.area, activeGroupId: this.activeGroupId };
+    }
+
+    /* ── Rendering ──────────────────────────────────────────────────────── */
+
+    render(host, ctx = {}) {
+        this.host = host;
+        this._outerCtx = ctx;
+        this.ctx = {
+            ...ctx,
+            // Closing and group focus are decisions about the AREA, not about
+            // one tab strip, so they are intercepted here rather than left to
+            // TabsNode's own handling.
+            onTabClose: ({ partId }) => { if (partId && this.beforeClose?.(partId) !== false) this.close(partId); },
+            onGroupFocus: (id) => this._setActiveGroup(id),
+            onLayoutChange: () => this._changed('layout'),
+        };
+        this._build();
+        // Both slots explicitly: nothing has focus yet as far as they are
+        // concerned, so a restored area would otherwise come back with an empty
+        // action bar and an empty rail.
+        this._syncSlots({ actions: true, outline: true });
+        return this;
+    }
+
+    _build() {
+        if (!this.host) return;
+        this._tree?.dispose();
+        this._tree = null;
+        this.host.textContent = '';
+
+        if (!listOpenParts(this.area).length) {
+            if (this.placeholder) this.host.appendChild(el(this.placeholder));
+            return;
+        }
+
+        this._tree = createLayout(this.area);
+        this._tree.render(this.host, this.ctx);
+        this._tree.activate();
+        this._markActiveGroup();
+    }
+
+    /* ── Frame slots ────────────────────────────────────────────────────── */
+
+    /**
+     * Point the action bar and outline rail at whatever now has focus.
+     *
+     * A slot is re-read when focus MOVED, or when the caller asks for that slot
+     * specifically. The two are asked for separately because their costs
+     * differ: re-reading actions is a handful of buttons, whereas re-showing an
+     * outline re-parents an element, which resets its scroll position — so a
+     * `refreshActions()` must not quietly scroll a long tree back to the top.
+     */
+    _syncSlots({ actions = false, outline = false } = {}) {
+        const partId = this.activePart();
+        const moved = partId !== this._slotPartId;
+        if (!moved && !actions && !outline) return;
+        this._slotPartId = partId;
+        if (moved || actions) this._renderActions(partId);
+        if (moved || outline) this._showOutline(partId);
+    }
+
+    _renderActions(partId) {
+        if (!this.actionsHost) return;
+        this.actionsHost.textContent = '';
+        const actions = partId ? (this.ctx?.registry?.get(partId)?.actions ?? []) : [];
+        this.actionsHost.classList.toggle('ws-actionbar-empty', !actions.length);
+        for (const action of actions) {
+            if (!action) continue;
+            // An already-built element is passed straight through. This is the
+            // AdapterPart bargain again: a panel that already has a working
+            // toolbar — with selects, labels and its own rebuild logic — joins
+            // the frame's action bar by handing it over, not by being rewritten
+            // into a button array that could not express it anyway.
+            if (typeof action.nodeType === 'number' || typeof action.appendChild === 'function') {
+                this.actionsHost.appendChild(action);
+                continue;
+            }
+            if (action.separator) { this.actionsHost.appendChild(el({ cls: 'ws-action-sep' })); continue; }
+            this.actionsHost.appendChild(el({
+                tag: 'button',
+                cls: ['ws-action', action.cls],
+                text: action.label ?? '',
+                attrs: {
+                    type: 'button',
+                    title: action.title ?? action.label ?? null,
+                    disabled: action.disabled || null,
+                },
+                on: { click: (e) => action.onClick?.(e, this) },
+            }));
+        }
+    }
+
+    /**
+     * Show the focused view's outline.
+     *
+     * An outline is an ordinary Part, resolved through the registry — not a new
+     * kind of thing. That is what gets it pooling, mount-once-then-re-parent and
+     * lifecycle for free: a tree keeps its expanded nodes and scroll position
+     * while you work in another view and come back.
+     */
+    _showOutline(partId) {
+        if (!this.outlineHost) return;
+        const outlineId = partId && this.outlineFor ? this.outlineFor(partId) : null;
+        const next = outlineId ? this.ctx?.registry?.get(outlineId) : null;
+
+        // Detached by name rather than by clearing the host: the outgoing
+        // outline is a pooled part, and `detach()` is the call that says so.
+        this._outlinePart?.detach();
+        this._outlinePart = null;
+        this._placeholderEl?.remove();
+        this._placeholderEl = null;
+        this.outlineHost.classList.toggle('ws-outline-empty', !next);
+
+        if (!next) {
+            if (this.outlinePlaceholder) {
+                this._placeholderEl = this.outlineHost.appendChild(el(this.outlinePlaceholder));
+            }
+            return;
+        }
+        try {
+            next.mount(this.outlineHost, this.ctx);
+            this._outlinePart = next;
+        } catch (err) {
+            console.error(`WorkArea: outline part "${outlineId}" failed to mount`, err);
+            this.outlineHost.classList.add('ws-outline-empty');
+        }
+    }
+
+    /** Re-read the focused view's actions — call when a panel's state changes. */
+    refreshActions() {
+        this._syncSlots({ actions: true });
+        return this;
+    }
+
+    /**
+     * Re-read both slots. For the case a lazily-mounted view creates the very
+     * things the slots are meant to show *after* it took focus — the action bar
+     * and outline were resolved against a panel that did not exist yet.
+     */
+    refreshSlots() {
+        this._syncSlots({ actions: true, outline: true });
+        return this;
+    }
+
+    /** The outline part currently on show, if any. */
+    get outlinePart() { return this._outlinePart; }
+
+    /**
+     * Read the live tree back into the model. Splitter drags and tab selections
+     * only ever happened to the DOM nodes; skipping this would silently undo
+     * them the next time anything opens or closes.
+     */
+    _syncFromTree() {
+        if (this._tree) this.area = this._tree.serialize();
+        return this.area;
+    }
+
+    /** Show every tab's label as its part's title is now (a file name that changed, say). */
+    refreshLabels() {
+        const walk = (node) => {
+            if (node?.constructor?.type === 'tabs') node.refreshLabels?.();
+            for (const child of node?.children ?? []) walk(child);
+        };
+        if (this._tree) walk(this._tree);
+        return this;
+    }
+
+    /** Live TabsNode for a group id, or null when nothing is rendered. */
+    _liveGroup(groupId) {
+        const walk = (node) => {
+            if (node?.id === groupId && node.constructor?.type === 'tabs') return node;
+            for (const child of node?.children ?? []) {
+                const hit = walk(child);
+                if (hit) return hit;
+            }
+            return null;
+        };
+        return this._tree ? walk(this._tree) : null;
+    }
+
+    /**
+     * Tint the active group's tab strip, but only once there is more than one
+     * group — with a single group "where the next view opens" is not a question
+     * anyone is asking, and the accent would just be noise.
+     */
+    _markActiveGroup() {
+        const many = this.groupCount() > 1;
+        for (const group of listGroups(this.area)) {
+            const live = this._liveGroup(group.id);
+            live?.el?.classList.toggle('ws-group-active', many && group.id === this.activeGroupId);
+        }
+    }
+
+    _setActiveGroup(id) {
+        if (!id || id === this.activeGroupId) return;
+        this.activeGroupId = id;
+        this._markActiveGroup();
+        this._changed('focus-group');
+    }
+
+    _changed(reason) {
+        this._syncFromTree();
+        // Before onChange, so a consumer reacting to the change (updating its
+        // own chrome, persisting) sees a frame that already agrees with focus.
+        this._syncSlots();
+        this.onChange?.({ area: this.area, activeGroupId: this.activeGroupId, reason });
+        this._outerCtx?.onLayoutChange?.();
+    }
+
+    /* ── Commands ───────────────────────────────────────────────────────── */
+
+    /**
+     * Open a view.
+     *
+     * `where`: `'tab'` (default) adds it to the active group; `'right'`,
+     * `'left'`, `'below'` or `'above'` opens a new group beside it — which is
+     * what actually gets two views on screen together.
+     *
+     * Already open anywhere -> focused, not duplicated: a part instance owns one
+     * DOM element, so a second tab for it would necessarily be empty.
+     */
+    open(partId, { where = 'tab' } = {}) {
+        if (!partId) return this;
+        if (this.isOpen(partId)) return this.focus(partId);
+        this._syncFromTree();
+        const next = openPart(this.area, partId, { where, activeGroupId: this.activeGroupId });
+        this.area = next.area;
+        this.activeGroupId = next.activeGroupId;
+        this._build();
+        this._changed('open');
+        return this;
+    }
+
+    /** Open beside the active group — the "split editor" gesture. */
+    openToSide(partId, side = 'right') { return this.open(partId, { where: side }); }
+
+    /**
+     * Select an already-open view. Deliberately does not rebuild: it drives the
+     * live TabsNode, so pane scroll positions and the DOM survive a tab click.
+     */
+    focus(partId) {
+        const found = findPart(this._syncFromTree(), partId);
+        if (!found) return this;
+        const live = this._liveGroup(found.group.id);
+        if (live) {
+            live.select(found.index, true);
+            this.activeGroupId = found.group.id;
+            this._markActiveGroup();
+            this._changed('focus');
+            return this;
+        }
+        const next = focusPart(this.area, partId, { activeGroupId: this.activeGroupId });
+        this.area = next.area;
+        this.activeGroupId = next.activeGroupId;
+        this._build();
+        this._changed('focus');
+        return this;
+    }
+
+    /**
+     * Close a view. Its group disappears when it held the last tab, and a split
+     * left with one child collapses into it — so closing back down to one view
+     * leaves a plain tab strip rather than a split with an empty half.
+     */
+    close(partId) {
+        this._syncFromTree();
+        const next = closePart(this.area, partId, { activeGroupId: this.activeGroupId });
+        if (!next.closed) return this;
+        this.area = next.area;
+        this.activeGroupId = next.activeGroupId;
+        this._build();
+        this._changed('close');
+        return this;
+    }
+
+    /** Close everything, leaving one empty group. */
+    closeAll() {
+        for (const partId of this.openParts()) this.close(partId);
+        return this;
+    }
+
+    /**
+     * Replace the whole area — restoring a saved one, or switching perspective.
+     * Parts the new area does not reference are left in the registry pool, so
+     * switching back finds them as they were.
+     */
+    setArea(area, activeGroupId) {
+        this.area = area ?? emptyWorkArea();
+        this.activeGroupId = activeGroupId ?? listGroups(this.area)[0]?.id ?? null;
+        this._build();
+        this._changed('set-area');
+        return this;
+    }
+
+    dispose() {
+        this._tree?.dispose();
+        this._tree = null;
+        // Detached, not disposed — the outline is a pooled part like any other,
+        // and destroying it here would take it out of the registry for good.
+        this._outlinePart?.detach();
+        this._outlinePart = null;
+        this._placeholderEl = null;
+        this._slotPartId = null;
+        if (this.host) this.host.textContent = '';
+        if (this.actionsHost) this.actionsHost.textContent = '';
+        if (this.outlineHost) this.outlineHost.textContent = '';
+        this.host = null;
+        this.ctx = null;
+    }
+}

package/src/workspace/workAreaModel.js

@@ -0,0 +1,197 @@
+/**
+ * workAreaModel — the pure half of an IDE-style work area.
+ *
+ * A work area is a layout subtree made only of TABS GROUPS, optionally
+ * arranged by SPLITS: one or more tab strips, each holding several open parts,
+ * side by side or stacked. That is the difference between "one view at a time"
+ * and an IDE: a part being OPEN (a tab exists) is separate from it being
+ * VISIBLE (its tab is selected, in a group that is on screen), and two parts in
+ * different groups are visible at once.
+ *
+ * Everything here is a pure function over plain JSON — the same descriptors
+ * `createLayout()` consumes — so the interesting behaviour (where a new tab
+ * lands, what collapses when the last tab in a group closes) is testable
+ * without a DOM. `WorkArea` (workArea.js) is the thin rendering shell on top.
+ *
+ *   group := { type:'tabs', id, active, closable, children:[{type:'part', partId}] }
+ *   area  := group | { type:'split', dir:'row'|'col', sizes, children:[area, …] }
+ *
+ * Only `tabs` nodes carry an `id`, because a group is the only thing anything
+ * needs to address: "open this beside the active group", "this group is now
+ * active". Splits are structure, and they come and go as groups are added and
+ * removed.
+ */
+
+const SIDES = { right: 'row', left: 'row', below: 'col', above: 'col' };
+
+const clone = (x) => (typeof structuredClone === 'function' ? structuredClone(x) : JSON.parse(JSON.stringify(x)));
+
+const isGroup = (n) => n?.type === 'tabs';
+const isSplit = (n) => n?.type === 'split';
+
+/** A work area with one empty group — what an area collapses to when the last tab closes. */
+export function emptyWorkArea(groupId = 'g1') {
+    return { type: 'tabs', id: groupId, active: 0, closable: true, children: [] };
+}
+
+/** Every tabs group in the area, in left-to-right/top-to-bottom order. */
+export function listGroups(area) {
+    if (!area) return [];
+    if (isGroup(area)) return [area];
+    return (area.children ?? []).flatMap(listGroups);
+}
+
+/** Every open part id, in group order. */
+export function listOpenParts(area) {
+    return listGroups(area).flatMap(g => (g.children ?? []).map(c => c.partId));
+}
+
+/** `{ group, index }` for whichever group holds `partId`, or null. */
+export function findPart(area, partId) {
+    for (const group of listGroups(area)) {
+        const index = (group.children ?? []).findIndex(c => c.partId === partId);
+        if (index >= 0) return { group, index };
+    }
+    return null;
+}
+
+/** The group `groupId` names, else the first group, else null. */
+export function resolveGroup(area, groupId) {
+    const groups = listGroups(area);
+    return groups.find(g => g.id === groupId) ?? groups[0] ?? null;
+}
+
+/** An id no existing group is using — `g1`, `g2`, … */
+function nextGroupId(area) {
+    const taken = new Set(listGroups(area).map(g => g.id));
+    for (let i = 1; ; i++) {
+        const id = `g${i}`;
+        if (!taken.has(id)) return id;
+    }
+}
+
+/**
+ * Open `partId`.
+ *
+ * Already open anywhere -> focus it instead of opening a second copy: a part
+ * instance owns one DOM element (see Part), so the same part cannot be in two
+ * panes at once, and silently cloning the tab would leave one of them empty.
+ *
+ * `where`:
+ *   'tab'                       — another tab in the active group (default)
+ *   'right'|'left'|'below'|'above' — a NEW group beside the active one, which
+ *                                 is what actually puts two parts on screen
+ *                                 together
+ *
+ * Returns `{ area, activeGroupId, opened }` — `opened` false when it was
+ * already open, so a caller can tell a fresh open from a focus.
+ */
+export function openPart(area, partId, { where = 'tab', activeGroupId } = {}) {
+    const existing = findPart(area, partId);
+    if (existing) return focusPart(area, partId, { activeGroupId });
+
+    const next = clone(area ?? emptyWorkArea());
+    const target = resolveGroup(next, activeGroupId) ?? resolveGroup(next);
+    const partNode = { type: 'part', partId };
+
+    if (where === 'tab' || !SIDES[where]) {
+        target.children = [...(target.children ?? []), partNode];
+        target.active = target.children.length - 1;
+        return { area: next, activeGroupId: target.id, opened: true };
+    }
+
+    const dir = SIDES[where];
+    const before = where === 'left' || where === 'above';
+    const group = { type: 'tabs', id: nextGroupId(next), active: 0, closable: true, children: [partNode] };
+    const placed = _placeBeside(next, target, group, dir, before);
+    return { area: placed, activeGroupId: group.id, opened: true };
+}
+
+/**
+ * Put `group` next to `target`. When target's own parent split already runs in
+ * the same direction the group joins it as a sibling rather than nesting a
+ * second split inside it — otherwise opening three views to the right builds a
+ * right-leaning tower of two-child splits, which serializes badly and resizes
+ * worse (each splitter would only move two of the panes).
+ */
+function _placeBeside(area, target, group, dir, before) {
+    const walk = (node, parentDir) => {
+        if (node === target) {
+            // No parent split in this direction — wrap the target in a new one.
+            if (parentDir !== dir) {
+                return { type: 'split', dir, sizes: [null, null], children: before ? [group, node] : [node, group] };
+            }
+            return node; // handled by the parent split below
+        }
+        if (!isSplit(node)) return node;
+
+        const children = node.children ?? [];
+        const at = children.indexOf(target);
+        if (at >= 0 && node.dir === dir) {
+            const insertAt = before ? at : at + 1;
+            const nextChildren = [...children];
+            nextChildren.splice(insertAt, 0, group);
+            const sizes = (node.sizes ?? []).slice();
+            while (sizes.length < children.length) sizes.push(null);
+            sizes.splice(insertAt, 0, null);
+            return { ...node, children: nextChildren, sizes };
+        }
+        return { ...node, children: children.map(c => walk(c, node.dir)) };
+    };
+    return walk(area, null);
+}
+
+/**
+ * Close `partId`. An emptied group is removed, and a split left holding a
+ * single child collapses into that child — so closing back down to one view
+ * leaves a plain tab strip, not a split with an empty half. The area never
+ * disappears entirely: closing the last tab anywhere leaves one empty group.
+ */
+export function closePart(area, partId, { activeGroupId } = {}) {
+    const found = findPart(area, partId);
+    if (!found) return { area, activeGroupId, closed: false };
+    const closedGroupId = found.group.id;
+
+    const prune = (node) => {
+        if (isGroup(node)) {
+            const children = (node.children ?? []).filter(c => c.partId !== partId);
+            if (!children.length) return null;
+            const removedAt = (node.children ?? []).findIndex(c => c.partId === partId);
+            let active = node.active ?? 0;
+            // Keep the neighbour selected rather than jumping to tab 0 — closing
+            // the active tab should land on what was next to it.
+            if (removedAt >= 0 && removedAt < active) active -= 1;
+            return { ...node, children, active: Math.max(0, Math.min(active, children.length - 1)) };
+        }
+        if (!isSplit(node)) return node;
+        const sizes = (node.sizes ?? []).slice();
+        const kept = [];
+        const keptSizes = [];
+        (node.children ?? []).forEach((child, i) => {
+            const pruned = prune(child);
+            if (pruned) { kept.push(pruned); keptSizes.push(sizes[i] ?? null); }
+        });
+        if (!kept.length) return null;
+        if (kept.length === 1) return kept[0]; // collapse the split away
+        return { ...node, children: kept, sizes: keptSizes };
+    };
+
+    const pruned = prune(clone(area));
+    const next = pruned ?? emptyWorkArea(closedGroupId);
+    const stillThere = listGroups(next).some(g => g.id === activeGroupId);
+    return {
+        area: next,
+        activeGroupId: stillThere ? activeGroupId : (listGroups(next)[0]?.id ?? null),
+        closed: true,
+    };
+}
+
+/** Select `partId`'s tab and make its group active. No-op if it isn't open. */
+export function focusPart(area, partId, { activeGroupId } = {}) {
+    const found = findPart(area, partId);
+    if (!found) return { area, activeGroupId, opened: false };
+    const next = clone(area);
+    const group = listGroups(next).find(g => g.id === found.group.id);
+    group.active = (group.children ?? []).findIndex(c => c.partId === partId);
+    return { area: next, activeGroupId: group.id, opened: false };
+}

package/src/workspace.js

@@ -0,0 +1,16 @@
+/**
+ * Compatibility shim.
+ *
+ * This path used to hold a standalone prototype shell: a fixed five-region
+ * slot layout (navigation/context/workspace/details/tabs) with an EventBus,
+ * a hard-coded perspective state machine, and a plugin manager whose plugins
+ * never actually contributed any UI. It could not express either target
+ * consumer — sqlengine workbench's sidebar+main+tool-panels, or its 12-column
+ * dashboard grid — so it was replaced by the part/layout/context model in
+ * `src/workspace/`. See WORKSPACE_ARCHITECTURE.md.
+ *
+ * Kept as a re-export so `import '.../src/workspace.js'` still registers the
+ * `<ws-workspace>` element. Both files defining the same tag would otherwise
+ * collide, with whichever imported first silently winning.
+ */
+export * from './workspace/index.js';