@openpresentation/opf-editor 0.26.10 → 0.28.0

package/dist/studio-kit/index.js

@@ -0,0 +1,12 @@
+// CE-18: the studio kit, the parts Layout Studio and the Studio share (STUDY.md 3.6, STUDIO-SPEC.md 17). It is internal for now: no package
+// subpath exports it until a second studio uses it (then `@openpresentation/opf-editor/studio-kit`). Nothing here knows a document format;
+// a studio supplies a document adapter (src/layout-adapter.js for Layout Studio).
+export { ICONS, KIT_PREFIX, createDom, isMac, isTypingTarget, nextId, openMenu, pct } from "./dom.js";
+export { createCommandRegistry, formatKey, isHandled, keyGuard, markHandled, matchKey, parseKey } from "./commands.js";
+export { clickTarget, createSelection } from "./selection.js";
+export { createGesture, createHistory } from "./gesture.js";
+export { ZOOM_STEPS, clampZoom, createViewport, scrollForZoom, stepZoom, toUnit } from "./viewport.js";
+export { boxesAt, createKeyedLayer, createOverlay, dividerKeyAction, inside, paintBadge, paintDivider, paintSelectable, ratioLabel, setBox } from "./overlay.js";
+export { createDragController, dragGhost, trackPointer } from "./drag.js";
+export { hitRow, rovingTabStop, rowDropMode, showTreeDrop, treeItem, treeKeyAction } from "./tree.js";
+export { createFields, createInspectorFrame } from "./inspector.js";

package/dist/studio-kit/inspector.d.ts

@@ -0,0 +1,22 @@
+/** CE-18 studio kit (internal): the inspector frame (sections chosen by the selection) and its field builders. */
+import type { KitDom } from "./dom.js";
+export interface KitInspectorSection<Ctx> { id: string; when?(ctx: Ctx): boolean; render(body: HTMLElement, ctx: Ctx): void }
+export interface KitInspectorFrame<Ctx> {
+  readonly editing: boolean;
+  sectionsFor(ctx: Ctx): KitInspectorSection<Ctx>[];
+  register(section: KitInspectorSection<Ctx>, options?: { before?: string }): () => void;
+  render(): void;
+  update(): void;
+  check(fn: () => void): void;
+  edit(callback: () => void): void;
+}
+export declare function createInspectorFrame<Ctx>(body: HTMLElement, options?: { sections?: KitInspectorSection<Ctx>[]; context?(): Ctx; before?(ctx: Ctx): void; after?(ctx: Ctx): void }): KitInspectorFrame<Ctx>;
+export interface KitFields<Path> {
+  field(label: string, control: HTMLElement, options?: { help?: string; path?: Path; field?: string; labelFor?: string; group?: boolean; target?: HTMLElement }): HTMLElement & { error: HTMLElement };
+  textInput(value: string | undefined, options?: { onInput?(value: string): void; name?: string; pattern?: string; placeholder?: string; multiline?: boolean }): HTMLInputElement | HTMLTextAreaElement;
+  select(entries: [string, string][], current: string, options: { onChange(value: string): void; name: string }): HTMLSelectElement;
+  segmented(entries: [string, string, string?][], current: string, options: { onPick(value: string): void; label: string; name: string }): HTMLElement;
+  actionButton(text: string, iconName: string | undefined, run: () => void, options?: { label?: string; disabled?: boolean; shortcut?: string }): HTMLButtonElement;
+  section(label?: string): HTMLElement;
+}
+export declare function createFields<Path>(dom: KitDom, frame: KitInspectorFrame<unknown>, options?: { idPrefix?: string; issues?(path: Path, field: string): { message: string }[]; readOnly?(): boolean }): KitFields<Path>;

package/dist/studio-kit/inspector.js

@@ -0,0 +1,119 @@
+// CE-18, the studio kit: the inspector frame. Sections are registered with `when(ctx)` and `render(body, ctx)`; every section whose `when`
+// holds for the current selection is drawn, in order. While the person types in a field of the panel, a change only refreshes the findings
+// under the fields (`update`), so the field keeps its focus and caret; any other change redraws the panel and puts focus back on the same
+// field. `createFields` builds the labeled fields, with core's findings shown under each. Plain DOM, styled by class prefix.
+import { nextId } from "./dom.js";
+
+/**
+ * The frame over `body`. Options: `sections` (`{ id, when(ctx), render(body, ctx) }`, in order), `context()` (the ctx of a redraw),
+ * `before(ctx)` and `after(ctx)` (around the sections: a title, findings that fit no field). Returns `{ render, update, edit, check, editing,
+ * sections }`: `edit(callback)` runs an edit from a typed field, `check(fn)` adds a findings check that `update` runs.
+ */
+export function createInspectorFrame(body, { sections = [], context = () => ({}), before, after } = {}) {
+  const list = [...sections];
+  let checks = [];
+  let editing = false;
+  const frame = {
+    get editing() { return editing; },
+    /** The sections drawn for `ctx`, in order. */
+    sectionsFor: (ctx) => list.filter((section) => section.when ? section.when(ctx) === true : true),
+    /** Add a section (before the one with id `before`, else at the end). Returns the function that removes it. */
+    register(section, { before: id } = {}) {
+      const at = id ? list.findIndex((entry) => entry.id === id) : -1;
+      if (at >= 0) list.splice(at, 0, section); else list.push(section);
+      return () => { const index = list.indexOf(section); if (index >= 0) list.splice(index, 1); };
+    },
+    render() {
+      const doc = body.ownerDocument;
+      const active = doc.activeElement;
+      const focusKey = body.contains(active) ? active.dataset?.field : undefined;
+      checks = [];
+      body.replaceChildren();
+      const ctx = context();
+      before?.(ctx);
+      for (const section of frame.sectionsFor(ctx)) section.render(body, ctx);
+      after?.(ctx);
+      frame.update();
+      if (focusKey) body.querySelector(`[data-field="${focusKey}"]`)?.focus({ preventScroll: true });
+    },
+    update() { for (const check of checks) check(); },
+    check(fn) { checks.push(fn); },
+    edit(callback) { editing = true; try { callback(); } finally { editing = false; } },
+  };
+  return frame;
+}
+
+/**
+ * Field builders bound to a frame. Options: `idPrefix` (field ids), `issues(path, field)` (the findings of one field, `{ message }`),
+ * `readOnly()`. Each builder returns an element; `field` wraps a control with its label, help and the live findings line.
+ */
+export function createFields(dom, frame, { idPrefix = nextId(`${dom.prefix}-fields`), issues = () => [], readOnly = () => false } = {}) {
+  const { el } = dom;
+  const p = dom.prefix;
+  /** A labeled field. `path`/`field` tie it to the findings: they show under the field and mark it invalid. */
+  function field(label, control, { help, path, field: key, labelFor, group, target } = {}) {
+    const wrap = el("div", `${p}-field`, { "data-field-name": key ?? "" });
+    const fieldId = `${idPrefix}-${nextId("f")}`;
+    const focusTarget = target ?? control;
+    if (group) {
+      const caption = el("span", `${p}-label-text`, { id: `${fieldId}-label`, text: label });
+      control.setAttribute("aria-labelledby", `${fieldId}-label`);
+      if (!control.getAttribute("role")) control.setAttribute("role", "group");
+      wrap.append(caption);
+    } else {
+      if (!labelFor && !control.id) control.id = fieldId;
+      wrap.append(el("label", `${p}-label-text`, { for: labelFor ?? control.id, text: label }));
+    }
+    wrap.append(control);
+    if (help) { const note = el("p", `${p}-help`, { id: `${fieldId}-help`, text: help }); wrap.append(note); if (!group) focusTarget.setAttribute("aria-describedby", note.id); }
+    const error = el("p", `${p}-field-error`, { id: `${fieldId}-error`, role: "status", "aria-live": "polite" });
+    error.hidden = true;
+    wrap.append(error);
+    if (path && key) {
+      frame.check(() => {
+        const found = issues(path, key);
+        error.hidden = !found.length;
+        error.replaceChildren();
+        if (found.length) error.append(dom.icon("CircleX", 14), el("span", "", { text: found.map((issue) => issue.message).join(" ") }));
+        wrap.dataset.invalid = String(Boolean(found.length));
+        if (!group) { if (found.length) { focusTarget.setAttribute("aria-invalid", "true"); focusTarget.setAttribute("aria-errormessage", error.id); } else { focusTarget.removeAttribute("aria-invalid"); focusTarget.removeAttribute("aria-errormessage"); } }
+      });
+    }
+    return Object.assign(wrap, { error });
+  }
+  /** A text field (or a textarea, `multiline`); `onInput(value)` runs as a typed edit. */
+  function textInput(value, { onInput, name, pattern, placeholder, multiline } = {}) {
+    const input = el(multiline ? "textarea" : "input", `${p}-input`, { type: multiline ? undefined : "text", "data-field": name, pattern, placeholder, spellcheck: "false", autocomplete: "off", rows: multiline ? 2 : undefined });
+    input.value = value ?? "";
+    input.addEventListener("input", () => frame.edit(() => onInput(input.value)));
+    return input;
+  }
+  /** A select of `[value, label]` entries. */
+  function select(entries, current, { onChange, name }) {
+    const input = el("select", `${p}-select`, { "data-field": name });
+    for (const [value, label] of entries) { const option = el("option", "", { value, text: label }); input.append(option); }
+    input.value = current;
+    input.addEventListener("change", () => onChange(input.value));
+    return input;
+  }
+  /** A segmented control of `[value, text, iconName]` entries (toggle buttons, one pressed). */
+  function segmented(entries, current, { onPick, label, name }) {
+    const wrap = el("div", `${p}-segmented`, { role: "group", "aria-label": label });
+    for (const [value, text, iconName] of entries) {
+      const button = dom.button(`${p}-segment`, { text, iconName, size: 14, pressed: value === current, attributes: { "data-field": `${name}-${value}`, "data-value": value } });
+      button.addEventListener("click", () => { if (value !== current) onPick(value); });
+      wrap.append(button);
+    }
+    return wrap;
+  }
+  /** An action button, disabled when `disabled` or read only. */
+  const actionButton = (text, iconName, run, { label, disabled, shortcut } = {}) => {
+    const button = dom.button(`${p}-action`, { text, iconName, size: 14, attributes: { "aria-label": label, "aria-keyshortcuts": shortcut } });
+    button.disabled = Boolean(disabled) || readOnly();
+    button.addEventListener("click", () => run());
+    return button;
+  };
+  /** A section of the panel, with an optional title. */
+  const section = (label) => { const node = el("div", `${p}-section`); if (label) node.append(el("h3", `${p}-section-title`, { text: label })); return node; };
+  return { field, textInput, select, segmented, actionButton, section };
+}

package/dist/studio-kit/overlay.d.ts

@@ -0,0 +1,29 @@
+/** CE-18 studio kit (internal): boxes, badges, dividers, the drop line, the ratio badge and the marker layer over a frame. */
+import type { KitDom } from "./dom.js";
+export interface KitBox { x: number; y: number; w: number; h: number }
+export declare function setBox(node: HTMLElement, box: KitBox, pad?: number): void;
+export declare function inside(box: KitBox, point: { x: number; y: number }, slack?: number): boolean;
+export declare function boxesAt<B extends KitBox & { depth: number }>(boxes: B[], point: { x: number; y: number }, options?: { slack?: number; skip?(box: B): boolean }): B[];
+export interface KitKeyedPass { ensure<E extends Element>(key: string, create: () => E): E; done(): void }
+export interface KitKeyedLayer { get(key: string): Element | undefined; entries(): IterableIterator<[string, Element]>; begin(): KitKeyedPass }
+export declare function createKeyedLayer(layer: HTMLElement): KitKeyedLayer;
+export declare function paintSelectable(node: HTMLElement, options: { box?: KitBox; selected: boolean; pressable?: boolean; label?: string; tabStop?: boolean }): void;
+export declare function paintBadge(dom: KitDom, node: HTMLElement, messages: string[]): HTMLElement | null;
+export declare function paintDivider(node: HTMLElement, options: { box?: KitBox; orientation: "vertical" | "horizontal"; draggable: boolean; tabbable?: boolean; label?: string; valueNow?: number; valueText?: string; title?: string }): void;
+export declare function dividerKeyAction(event: Pick<KeyboardEvent, "key" | "shiftKey" | "altKey" | "ctrlKey" | "metaKey">, orientation: "vertical" | "horizontal"): { type: "nudge"; step: -1 | 1; big: boolean } | { type: "equalize" } | null;
+export declare function ratioLabel(a: number, b: number): string;
+export interface KitOverlay {
+  guide: HTMLElement | null;
+  drop: HTMLElement;
+  ratio: HTMLElement;
+  markers: HTMLElement | null;
+  showGuide(box: KitBox, axis: "row" | "column"): void;
+  hideGuide(): void;
+  showDrop(line: KitBox, options: { orientation: "vertical" | "horizontal"; state?: "ok" | "same" | "refused"; reason?: string }): void;
+  hideDrop(): void;
+  showRatio(label: string, at: { x: number; y: number }): void;
+  hideRatio(): void;
+  hover(layer: HTMLElement, node: Element | null | undefined): void;
+  into(layer: HTMLElement, node: Element | null | undefined): void;
+}
+export declare function createOverlay(dom: KitDom, host: HTMLElement, options?: { guide?: string | false; markers?: boolean }): KitOverlay;

package/dist/studio-kit/overlay.js

@@ -0,0 +1,182 @@
+// CE-18, the studio kit: the overlay drawn over a studio's frame. Boxes are placed in unit coordinates (0 to 1 of the frame) and kept by key,
+// so a redraw moves the existing elements instead of rebuilding them. The overlay also has the hover outline, findings badges, the dividers
+// between tracks (role="separator", with their keyboard), the drop line and "into" highlight of a drag, the ratio badge of a resize, an
+// optional guide line, and an optional marker layer (for comment pins, proposal ghosts and peers later). It knows boxes, not documents.
+import { pct } from "./dom.js";
+
+/** Place an absolutely positioned element over `box` (`{ x, y, w, h }` in unit coordinates), grown by `pad` on every side. */
+export function setBox(node, box, pad = 0) {
+  node.style.left = pct(box.x - pad);
+  node.style.top = pct(box.y - pad);
+  node.style.width = pct(box.w + 2 * pad);
+  node.style.height = pct(box.h + 2 * pad);
+}
+
+/** Whether a unit point is inside `box`, with `slack` around it. */
+export const inside = (box, point, slack = 0) => point.x >= box.x - slack && point.x <= box.x + box.w + slack && point.y >= box.y - slack && point.y <= box.y + box.h + slack;
+
+/** The boxes under a unit point, from the outermost to the deepest (by `depth`), leaving out those `skip(box)` refuses. */
+export const boxesAt = (boxes, point, { slack = 0.0005, skip } = {}) => boxes.filter((box) => inside(box, point, slack) && !(skip && skip(box))).sort((a, b) => a.depth - b.depth);
+
+/**
+ * Keyed elements in `layer`. Each redraw is `const pass = keyed.begin()`, then `pass.ensure(key, create)` for every element in the order
+ * they should have (it creates the element the first time and returns the same one after), then `pass.done()`, which removes the elements
+ * not ensured in this pass and puts the rest in order, moving only those out of place (so focus and transitions survive).
+ */
+export function createKeyedLayer(layer) {
+  const keyed = new Map();
+  return {
+    get: (key) => keyed.get(key),
+    entries: () => keyed.entries(),
+    begin() {
+      const seen = new Set();
+      const order = [];
+      return {
+        ensure(key, create) {
+          let node = keyed.get(key);
+          if (!node) { node = create(); keyed.set(key, node); }
+          seen.add(key);
+          order.push(node);
+          return node;
+        },
+        done() {
+          for (const [key, node] of keyed) if (!seen.has(key)) { node.remove(); keyed.delete(key); }
+          let cursor = null;
+          for (const node of order) {
+            const expected = cursor ? cursor.nextSibling : layer.firstChild;
+            if (node.parentNode !== layer || expected !== node) layer.insertBefore(node, expected);
+            cursor = node;
+          }
+        },
+      };
+    },
+  };
+}
+
+/**
+ * Paint a selectable box: its place, `is-selected`, and what a screen reader hears. A `pressable` box is a toggle button (`aria-pressed`),
+ * a container is a `group`. `tabStop` makes it the one box in the tab order (a roving tab stop).
+ */
+export function paintSelectable(node, { box, selected, pressable = true, label, tabStop }) {
+  node.classList.toggle("is-selected", Boolean(selected));
+  node.setAttribute("role", pressable ? "button" : "group");
+  if (label !== undefined) node.setAttribute("aria-label", label);
+  if (pressable) node.setAttribute("aria-pressed", String(Boolean(selected))); else node.removeAttribute("aria-pressed");
+  node.tabIndex = tabStop ? 0 : -1;
+  if (box) setBox(node, box);
+}
+
+/** The findings badge of a box (the CircleX icon, with the messages as its title); removed when `messages` is empty. */
+export function paintBadge(dom, node, messages) {
+  const selector = `:scope > .${dom.prefix}-badge`;
+  let badge = node.querySelector(selector);
+  if (messages.length && !badge) { badge = dom.el("span", `${dom.prefix}-badge`, { "aria-hidden": "true" }); badge.append(dom.icon("CircleX", 14)); node.append(badge); }
+  if (badge) { if (messages.length) badge.title = messages.join("\n"); else badge.remove(); }
+  return badge?.isConnected ? badge : null;
+}
+
+const DIVIDER_ATTRIBUTES = ["aria-label", "aria-valuemin", "aria-valuemax", "aria-valuenow", "aria-valuetext", "title"];
+/**
+ * Paint a divider between two tracks (`role="separator"`). `orientation` is the line's ("vertical" between columns). A `draggable` divider
+ * is focusable when `tabbable`, with `aria-valuenow` (the first track's share in percent) and `aria-valuetext` ("2 : 1"); a fixed one is
+ * `aria-disabled`.
+ */
+export function paintDivider(node, { box, orientation, draggable, tabbable = true, label, valueNow, valueText, title }) {
+  node.dataset.orientation = orientation;
+  node.dataset.fixed = draggable ? "false" : "true";
+  if (box) setBox(node, box);
+  node.setAttribute("role", "separator");
+  node.setAttribute("aria-orientation", orientation);
+  if (draggable) {
+    node.tabIndex = tabbable ? 0 : -1;
+    node.setAttribute("aria-label", label ?? "Resize");
+    node.setAttribute("aria-valuemin", "0");
+    node.setAttribute("aria-valuemax", "100");
+    node.setAttribute("aria-valuenow", String(valueNow));
+    node.setAttribute("aria-valuetext", String(valueText));
+    node.removeAttribute("aria-disabled");
+    if (title) node.title = title; else node.removeAttribute("title");
+  } else {
+    node.removeAttribute("tabindex");
+    for (const name of DIVIDER_ATTRIBUTES) node.removeAttribute(name);
+    node.setAttribute("aria-disabled", "true");
+  }
+}
+
+/**
+ * What a key does on a focused divider whose line is `orientation`: the arrow keys across the line nudge it (`{ type: "nudge", step, big }`,
+ * Shift for a big step), Enter equalizes (`{ type: "equalize" }`), anything else (or a modifier) is null.
+ */
+export function dividerKeyAction(event, orientation) {
+  if (event.altKey || event.metaKey || event.ctrlKey) return null;
+  const keys = orientation === "vertical" ? ["ArrowLeft", "ArrowRight"] : ["ArrowUp", "ArrowDown"];
+  const step = event.key === keys[0] ? -1 : event.key === keys[1] ? 1 : 0;
+  if (step) return { type: "nudge", step, big: Boolean(event.shiftKey) };
+  if (event.key === "Enter") return { type: "equalize" };
+  return null;
+}
+
+/** The ratio of two track sizes as a label: "2 : 1". */
+export const ratioLabel = (a, b) => `${trim(a)} : ${trim(b)}`;
+const trim = (value) => String(Math.round(value * 1000) / 1000);
+
+/**
+ * The overlay's own elements inside `host`, in this order: the guide line (when `guide` names its class suffix, e.g. "cut"), the drop line,
+ * the ratio badge, and the marker layer (when `markers`). All start hidden and `aria-hidden`.
+ */
+export function createOverlay(dom, host, { guide = false, markers = false } = {}) {
+  const p = dom.prefix;
+  const hiddenEl = (name) => { const node = dom.el("div", `${p}-${name}`, { "aria-hidden": "true" }); node.hidden = true; return node; };
+  const guideEl = guide ? hiddenEl(guide) : null;
+  const drop = hiddenEl("drop");
+  const ratio = hiddenEl("ratio");
+  const markerEl = markers ? dom.el("div", `${p}-markers`, { "aria-hidden": "true" }) : null;
+  host.append(...[guideEl, drop, ratio, markerEl].filter(Boolean));
+
+  return {
+    guide: guideEl,
+    drop,
+    ratio,
+    markers: markerEl,
+    /** A guide line through the middle of `box`: across a row split it is vertical (axis "row"), else horizontal. */
+    showGuide(box, axis) {
+      if (!guideEl) return;
+      guideEl.hidden = false;
+      if (axis === "row") Object.assign(guideEl.style, { left: pct(box.x + box.w / 2), top: pct(box.y), width: "0", height: pct(box.h) });
+      else Object.assign(guideEl.style, { left: pct(box.x), top: pct(box.y + box.h / 2), width: pct(box.w), height: "0" });
+      guideEl.dataset.axis = axis;
+    },
+    hideGuide() { if (guideEl) guideEl.hidden = true; },
+    /**
+     * The drop line along `line` (`{ x, y, w, h }`): a vertical line at its left edge (between items of a row) or a horizontal one at its top.
+     * `state` is "ok", "same" (a drop that changes nothing) or "refused", with `reason` as its title.
+     */
+    showDrop(line, { orientation, state = "ok", reason = "" }) {
+      drop.hidden = false;
+      drop.dataset.orientation = orientation;
+      drop.dataset.state = state;
+      drop.title = reason;
+      if (orientation === "vertical") Object.assign(drop.style, { left: pct(line.x), top: pct(line.y), width: "0", height: pct(line.h) });
+      else Object.assign(drop.style, { left: pct(line.x), top: pct(line.y), width: pct(line.w), height: "0" });
+    },
+    hideDrop() { drop.hidden = true; },
+    /** The ratio badge, centered on a unit point. */
+    showRatio(label, at) {
+      ratio.hidden = false;
+      ratio.textContent = label;
+      ratio.style.left = pct(at.x);
+      ratio.style.top = pct(at.y);
+    },
+    hideRatio() { ratio.hidden = true; },
+    /** Mark the hovered element in `layer` (`data-hover`), clearing the others; null clears. */
+    hover(layer, node) {
+      for (const other of layer.querySelectorAll("[data-hover]")) other.removeAttribute("data-hover");
+      node?.setAttribute("data-hover", "true");
+    },
+    /** Mark the container a drop would go into (`data-into`), clearing the others; null clears. */
+    into(layer, node) {
+      for (const other of layer.querySelectorAll("[data-into]")) other.removeAttribute("data-into");
+      node?.setAttribute("data-into", "true");
+    },
+  };
+}

package/dist/studio-kit/selection.d.ts

@@ -0,0 +1,30 @@
+/** CE-18 studio kit (internal): the selection model (an ordered list of sibling keys; the last is the primary). */
+export interface KitSelectionAdapter<Key> {
+  equals?(a: Key, b: Key): boolean;
+  copy?(key: Key): Key;
+  exists(key: Key): boolean;
+  parent(key: Key): Key | null;
+  firstChild(key: Key): Key | null;
+  sibling(key: Key, delta: number): Key | null;
+  first(): Key | null;
+  siblings?(key: Key): Key[];
+}
+export interface KitSelection<Key> {
+  readonly items: Key[];
+  readonly primary: Key | null;
+  has(key: Key): boolean;
+  existing(keys: Key[]): Key[];
+  set(keys: Key[], options?: { source?: string }): boolean;
+  replace(keys: Key[]): void;
+  prune(): void;
+  snapshot(): Key[];
+  add(key: Key, options?: { source?: string }): boolean;
+  toggle(key: Key, options?: { source?: string }): boolean;
+  range(key: Key, options?: { source?: string }): boolean;
+  selectParent(options?: { source?: string }): boolean;
+  selectChild(options?: { source?: string }): boolean;
+  selectSibling(delta: number, options?: { source?: string }): boolean;
+  selectSiblings(options?: { source?: string }): boolean;
+}
+export declare function createSelection<Key>(adapter: KitSelectionAdapter<Key>, options?: { onChange?(event: { source?: string }): void }): KitSelection<Key>;
+export declare function clickTarget<Node, Key>(chain: Node[], primary: Key | null, options?: { shift?: boolean; equals?(a: Key, b: Key): boolean; keyOf?(node: Node): Key; isContainer?(node: Node): boolean }): Node | null;

package/dist/studio-kit/selection.js

@@ -0,0 +1,106 @@
+// CE-18, the studio kit: the selection model. An ordered list of node keys whose last entry is the primary; nothing selected means the
+// document itself (a layout, a deck). Multi-select holds siblings only: adding a node of another parent replaces the selection. The model
+// knows nothing about the document: a small adapter tells it whether a key exists and how keys relate. No DOM.
+
+/**
+ * Create a selection over `adapter`:
+ * - `equals(a, b)` (default `===`), `copy(key)` (default identity);
+ * - `exists(key)`: whether the key names a selectable node now;
+ * - `parent(key)`: the parent's key, or null for a top-level node;
+ * - `firstChild(key)`: the first child's key, or null when it has none or is not a container;
+ * - `sibling(key, delta)`: the key `delta` places away in the same parent, or null past either end;
+ * - `first()`: the key to select when nothing is and the person moves to a sibling, or null;
+ * - `siblings(key)` (optional): the keys of the parent's children in order, for `selectSiblings` and `range`.
+ * `onChange({ source })` runs after each change made by a select call (not after `replace` or `prune`).
+ */
+export function createSelection(adapter, { onChange } = {}) {
+  const equals = adapter.equals ?? ((a, b) => a === b);
+  const copy = adapter.copy ?? ((key) => key);
+  let items = [];
+  const has = (key) => items.some((entry) => equals(entry, key));
+  const existing = (keys) => (keys ?? []).filter((key) => adapter.exists(key));
+  const sameParent = (a, b) => { const pa = adapter.parent(a), pb = adapter.parent(b); return pa === null || pb === null ? pa === pb : equals(pa, pb); };
+
+  /** Select `keys` (those that exist, in order). Returns false when the selection is already exactly that. */
+  function set(keys, { source } = {}) {
+    const next = existing(keys).map(copy);
+    if (next.length === items.length && next.every((key, index) => equals(key, items[index]))) return false;
+    items = next;
+    onChange?.({ source });
+    return true;
+  }
+
+  return {
+    get items() { return items; },
+    get primary() { return items[items.length - 1] ?? null; },
+    has,
+    /** The keys of `keys` that exist now. */
+    existing,
+    set,
+    /** Replace the list as it is, without checks or a change event (history restore, a command's own result). */
+    replace(keys) { items = keys; },
+    /** Drop the keys that no longer exist, without a change event. */
+    prune() { items = existing(items); },
+    /** Copies of the keys, for a history snapshot. */
+    snapshot: () => items.map(copy),
+    /** Shift-click: add a sibling of the selection or remove a selected one; a node of another parent replaces the selection. */
+    add(key, options) {
+      if (!items.length || !existing([key]).length) return set([key], options);
+      if (!sameParent(items[0], key)) return set([key], options);
+      return set(has(key) ? items.filter((entry) => !equals(entry, key)) : [...items, key], options);
+    },
+    /** Cmd-click in a list: the same as `add`, by name. */
+    toggle(key, options) { return this.add(key, options); },
+    /** Shift-click in the layers: every sibling from the primary to `key`, in order (needs `adapter.siblings`). */
+    range(key, options) {
+      const anchor = items[items.length - 1];
+      if (!anchor || !adapter.siblings || !sameParent(anchor, key)) return set([key], options);
+      const list = adapter.siblings(key);
+      const from = list.findIndex((entry) => equals(entry, anchor)), to = list.findIndex((entry) => equals(entry, key));
+      if (from < 0 || to < 0) return set([key], options);
+      const span = from <= to ? list.slice(from, to + 1) : list.slice(to, from + 1).reverse();
+      return set(span, options);
+    },
+    /** Esc: the primary's parent, or nothing for a top-level node. */
+    selectParent(options) {
+      const key = items[items.length - 1];
+      if (key === undefined) return false;
+      const parent = adapter.parent(key);
+      return set(parent === null ? [] : [parent], options);
+    },
+    /** Enter: the primary's first child, when it is a container with children. */
+    selectChild(options) {
+      const key = items[items.length - 1];
+      if (key === undefined) return false;
+      const child = adapter.firstChild(key);
+      return child === null || child === undefined ? false : set([child], options);
+    },
+    /** Arrow keys: the primary's sibling `delta` away, or `first()` when nothing is selected. */
+    selectSibling(delta, options) {
+      const key = items[items.length - 1];
+      if (key === undefined) { const first = adapter.first(); return set(first === null || first === undefined ? [] : [first], options); }
+      const next = adapter.sibling(key, delta);
+      return next === null || next === undefined ? false : set([next], options);
+    },
+    /** Mod+A: every sibling of the primary (needs `adapter.siblings`). */
+    selectSiblings(options) {
+      const key = items[items.length - 1];
+      if (key === undefined || !adapter.siblings) return false;
+      return set(adapter.siblings(key), options);
+    },
+  };
+}
+
+/**
+ * What a click on a stack of nodes selects. `chain` is the nodes under the pointer from the outermost to the deepest. The deepest is the
+ * answer, except that when the primary is a container in the chain (and Shift is not held), the click goes one level into it.
+ */
+export function clickTarget(chain, primary, { shift = false, equals = (a, b) => a === b, keyOf = (node) => node.key, isContainer = () => false } = {}) {
+  if (!chain.length) return null;
+  const deepest = chain[chain.length - 1];
+  if (primary !== null && primary !== undefined && !shift) {
+    const at = chain.findIndex((node) => equals(keyOf(node), primary));
+    if (at >= 0 && isContainer(chain[at]) && at < chain.length - 1) return chain[at + 1];
+  }
+  return deepest;
+}

package/dist/studio-kit/tree.d.ts

@@ -0,0 +1,9 @@
+/** CE-18 studio kit (internal): the layers tree (WAI-ARIA tree pattern) and its drop places. */
+import type { KitDom } from "./dom.js";
+export declare function treeItem(dom: KitDom, options: { level: number; selected: boolean; expanded?: boolean; setsize?: number; posinset?: number; attributes?: Record<string, string | number>; className?: string }): HTMLLIElement;
+export declare function rovingTabStop(items: Iterable<HTMLElement>, stop: HTMLElement | null | undefined): void;
+export type KitTreeAction<Item> = { type: "focus"; target: Item | null } | { type: "expand" } | { type: "collapse" } | { type: "activate" } | { type: "menu" };
+export declare function treeKeyAction<Item>(event: Pick<KeyboardEvent, "key" | "shiftKey">, item: Item, items: Item[], state?: { expandable?: boolean; expanded?: boolean; collapsible?: boolean; parent?: Item | null; firstChild?: Item | null; menu?: boolean }): KitTreeAction<Item> | null;
+export declare function hitRow<R extends { row: Element }>(rows: R[], clientY: number): R | undefined;
+export declare function rowDropMode(fraction: number, options?: { root?: boolean; container?: boolean }): "into" | "before" | "after";
+export declare function showTreeDrop(mark: HTMLElement, scroller: HTMLElement, drop: { mode: "into" | "before" | "after"; state: "ok" | "same" | "refused"; reason?: string; box: DOMRect } | null | undefined): void;

package/dist/studio-kit/tree.js

@@ -0,0 +1,82 @@
+// CE-18, the studio kit: the layers tree (the WAI-ARIA tree pattern). `treeItem` makes a `role="treeitem"` with its level, place, selection
+// and expansion; `rovingTabStop` keeps one item in the tab order; `treeKeyAction` says what a key does on a focused item; `rowDropMode` and
+// `hitRow` find where a dragged row would land; `showTreeDrop` draws that place. The host builds the rows and owns the document.
+
+/**
+ * A tree item (`li`, `role="treeitem"`). `expanded` is true or false for an item with children and undefined for a leaf; `setsize` and
+ * `posinset` (1-based) are left out for the root. `attributes` are added as they are (`data-*`).
+ */
+export function treeItem(dom, { level, selected, expanded, setsize, posinset, attributes = {}, className = `${dom.prefix}-item` }) {
+  const li = dom.el("li", className, { role: "treeitem", "aria-level": level, ...attributes });
+  li.setAttribute("aria-selected", String(Boolean(selected)));
+  if (expanded !== undefined) li.setAttribute("aria-expanded", String(Boolean(expanded)));
+  if (setsize !== undefined) { li.setAttribute("aria-setsize", String(setsize)); li.setAttribute("aria-posinset", String(posinset)); }
+  return li;
+}
+
+/** Make `stop` the one item of `items` in the tab order. */
+export function rovingTabStop(items, stop) {
+  for (const item of items) item.tabIndex = item === stop ? 0 : -1;
+}
+
+/**
+ * What a key does on the focused tree item `item` (the tree pattern). `items` are the visible items in order. Returns null, or:
+ * - `{ type: "focus", target }` (ArrowDown, ArrowUp, Home, End; ArrowRight on an expanded item goes to `firstChild`, ArrowLeft on a child to
+ *   `parent`; `target` may be null when there is nowhere to go, and the key is still the tree's);
+ * - `{ type: "expand" }` (ArrowRight on a collapsed item) and `{ type: "collapse" }` (ArrowLeft on an expanded item that can collapse);
+ * - `{ type: "activate" }` (Enter or Space) and `{ type: "menu" }` (the ContextMenu key or Shift+F10, on an item that has one).
+ * `state` is `{ expandable, expanded, collapsible, parent, firstChild, menu }`.
+ */
+export function treeKeyAction(event, item, items, state = {}) {
+  const at = items.indexOf(item);
+  const focus = (target) => ({ type: "focus", target: target ?? null });
+  switch (event.key) {
+    case "ArrowDown": return focus(items[Math.min(items.length - 1, at + 1)]);
+    case "ArrowUp": return focus(items[Math.max(0, at - 1)]);
+    case "Home": return focus(items[0]);
+    case "End": return focus(items[items.length - 1]);
+    case "ArrowRight":
+      if (!state.expandable) return null;
+      return state.expanded ? focus(state.firstChild) : { type: "expand" };
+    case "ArrowLeft":
+      if (state.expanded && state.collapsible) return { type: "collapse" };
+      return state.parent ? focus(state.parent) : null;
+    case "Enter":
+    case " ":
+      return { type: "activate" };
+    default:
+      if ((event.key === "ContextMenu" || (event.key === "F10" && event.shiftKey)) && state.menu) return { type: "menu" };
+      return null;
+  }
+}
+
+/** The row of `rows` (`{ row, ... }`, `row` an element) that a client y is over, or undefined. */
+export const hitRow = (rows, clientY) => rows.find(({ row }) => { const box = row.getBoundingClientRect(); return clientY >= box.top && clientY <= box.bottom; });
+
+/**
+ * Where a drop at `fraction` of a row's height lands: "into" the row (always for the root, and in the middle 40% of a container), else
+ * "before" (the upper half) or "after".
+ */
+export function rowDropMode(fraction, { root = false, container = false } = {}) {
+  if (root) return "into";
+  if (container && fraction >= 0.3 && fraction <= 0.7) return "into";
+  return fraction < 0.5 ? "before" : "after";
+}
+
+/**
+ * Draw the drop place on `mark` (positioned in `scroller`): a line above or below the row's box, or the whole box for "into". `state` is
+ * "ok", "same" or "refused", with `reason` as its title. A null drop hides it.
+ */
+export function showTreeDrop(mark, scroller, drop) {
+  if (!drop) { mark.hidden = true; return; }
+  const parent = scroller.getBoundingClientRect();
+  mark.hidden = false;
+  mark.dataset.mode = drop.mode;
+  mark.dataset.state = drop.state;
+  mark.title = drop.reason ?? "";
+  const top = drop.mode === "after" ? drop.box.bottom : drop.box.top;
+  mark.style.top = `${top - parent.top + scroller.scrollTop}px`;
+  mark.style.left = `${drop.box.left - parent.left}px`;
+  mark.style.width = `${drop.box.width}px`;
+  mark.style.height = drop.mode === "into" ? `${drop.box.height}px` : "0px";
+}

package/dist/studio-kit/viewport.d.ts

@@ -0,0 +1,29 @@
+/** CE-18 studio kit (internal): zoom (steps, smooth, fit), pan (hand, Space, two fingers) and screen-to-unit mapping. */
+export declare const ZOOM_STEPS: readonly number[];
+export declare function clampZoom(value: number, steps?: readonly number[]): number;
+export declare function stepZoom(zoom: number, direction: number, steps?: readonly number[]): number;
+export declare function toUnit(point: { clientX: number; clientY: number }, rect: { left: number; top: number; width: number; height: number }): { x: number; y: number };
+export declare function scrollForZoom(scroll: { left: number; top: number }, anchor: { x: number; y: number }, from: number, to: number): { left: number; top: number };
+export interface KitViewportOptions {
+  root?: HTMLElement;
+  zoomVar?: string;
+  steps?: readonly number[];
+  zoom?: number;
+  panEnabled?(): boolean;
+  wheel?: "step" | "smooth" | false;
+  pinch?: boolean;
+  fitZoom?(mode: "slide" | "width"): number;
+  onZoom?(zoom: number): void;
+}
+export interface KitViewport {
+  readonly zoom: number;
+  readonly panMode: boolean;
+  readonly panning: boolean;
+  setZoom(zoom: number, options?: { anchor?: { clientX: number; clientY: number } }): number;
+  step(direction: number, options?: { anchor?: { clientX: number; clientY: number } }): number;
+  fit(mode?: "slide" | "width"): number;
+  holdSpace(on: boolean): void;
+  toUnit(event: { clientX: number; clientY: number }, element: Element): { x: number; y: number };
+  destroy(): void;
+}
+export declare function createViewport(viewport: HTMLElement, options?: KitViewportOptions): KitViewport;