@liquidcars/atlas 0.1.48 → 0.1.49

package/src/diagram-view.js

@@ -0,0 +1,502 @@
+/** The document's 2D presentation. The SVG is also the source of SVG/PNG exports. */
+const escapeHtml = value => String(value ?? "").replace(/[&<>"']/g, char => ({
+  "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;"
+})[char]);
+
+const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+
+export const DIAGRAM_VIEW_CSS = `
+  .diagram-view{position:absolute;inset:0;overflow:auto;background-color:#f5f5f5;background-image:radial-gradient(circle,#b3b3b3 .8px,transparent 1px);background-size:16px 16px;color:#172c3a;cursor:grab;touch-action:none}
+  .diagram-view[hidden],:host(:not([data-view-mode="2d"])) .diagram-view{display:none!important}
+  :host([data-view-mode="2d"]) .viewport>canvas,:host([data-view-mode="2d"]) .atlas-jump{visibility:hidden;pointer-events:none}
+  :host([data-view-mode="2d"]) .toolbar-group[data-toolbar-group="camera"],
+  :host([data-view-mode="2d"]) .toolbar-group[data-toolbar-group="copy"]{display:none}
+  :host(:not([data-view-mode="2d"])) .toolbar-group[data-toolbar-group="diagram"]{display:none}
+  :host(:not([data-view-mode="2d"])) [data-action="diagram-relations-within"]{display:none!important}
+  :host([data-view-mode="2d"]) .toolbar{width:max-content;max-width:calc(100% - 16px);flex-wrap:wrap;justify-content:center}
+  :host([data-view-mode="2d"]) .toolbar-group[data-toolbar-group="diagram"]{flex-wrap:wrap;justify-content:center}
+  .diagram-content{position:relative;width:max-content;min-width:100%;min-height:100%;display:grid;place-items:center;padding:12px}
+  .diagram-content svg{display:block;max-width:none;overflow:visible}
+  .diagram-content [data-entity],.diagram-content [data-relation]{cursor:pointer}
+  .diagram-content [data-entity]:hover,.diagram-content [data-relation]:hover{filter:drop-shadow(0 0 5px #23a58f)}
+  .diagram-content [data-entity].selected,.diagram-content [data-relation].selected{filter:drop-shadow(0 0 7px #008fcb)}
+  .diagram-view.dragging{cursor:grabbing}
+  .diagram-toolbar select,.diagram-toolbar input{accent-color:#6ad7c0}
+  .diagram-toolbar .toolbar-popover{max-height:min(430px,65vh);overflow:auto}
+  .diagram-toolbar .toolbar-option.checkbox{display:flex;gap:8px;align-items:center}
+  .diagram-toolbar .toolbar-option.checkbox input{pointer-events:none}
+  .diagram-toolbar .diagram-spacing{padding:7px 9px;color:#dbe7ec;font-size:12px}
+  .diagram-toolbar .diagram-spacing input{width:100%;display:block;margin-top:6px}
+  .diagram-toolbar .diagram-items{max-height:220px;overflow:auto}
+  .diagram-orientation-cube{position:absolute;z-index:9;top:12px;left:12px;width:110px;height:110px;touch-action:none;cursor:grab}
+  .diagram-orientation-cube[hidden],:host(:not([data-view-mode="2d"])) .diagram-orientation-cube{display:none!important}
+  .diagram-orientation-cube svg{width:100%;height:100%}
+  .diagram-orientation-cube polygon{fill:#476782;stroke:#a8d0df;stroke-width:1.4}
+  .diagram-orientation-cube polygon:hover{fill:#4caeaa}
+  .diagram-orientation-cube text{fill:#fff;font:bold 10px system-ui;pointer-events:none}
+  .diagram-orientation-cube circle{fill:#132b3b;stroke:#50758b}
+  .diagram-toolbar .diagram-orbit,.diagram-toolbar .diagram-camera-zoom{display:block;padding:6px 9px;color:#dbe7ec;font-size:12px}
+  .diagram-toolbar .diagram-orbit select,.diagram-toolbar .diagram-camera-zoom input{display:block;width:100%;margin-top:4px}
+  :host([data-view-mode="2d"]) .hint{color:#527286}
+  @media print{:host([data-view-mode="2d"]) .diagram-view{display:block!important;overflow:hidden}.diagram-orientation-cube{display:none!important}}
+`;
+
+const menu = (name, label, content) => `<details class="toolbar-menu" data-toolbar-menu="diagram-${name}"><summary aria-label="${label}" title="${label}"><span class="toolbar-menu-status">${label}</span><svg class="toolbar-menu-chevron" viewBox="0 0 24 24" aria-hidden="true"><path d="m8 10 4 4 4-4"/></svg></summary><div class="toolbar-popover" role="menu"><div class="toolbar-popover-title">${label}</div>${content}</div></details>`;
+const option = (action, label) => `<button type="button" class="toolbar-option" data-action="${action}"><span>${label}</span></button>`;
+
+export const DIAGRAM_TOOLBAR = `<div class="toolbar-group diagram-toolbar" data-toolbar-group="diagram">
+  <button class="toolbar-icon" data-action="diagram-minus" aria-label="Zoom out" title="Zoom out">−</button>
+  <button class="toolbar-icon" data-action="diagram-plus" aria-label="Zoom in" title="Zoom in">＋</button>
+  <button class="toolbar-icon" data-action="diagram-fit" aria-label="Fit diagram" title="Fit diagram">⛶</button>
+  ${menu("orientation", "Orientation", '<div class="diagram-orientation-cube" data-diagram-cube tabindex="0" role="group" aria-label="Drag to orbit or click a face"></div><button type="button" class="toolbar-option checkbox" data-action="diagram-cube"><input type="checkbox" data-diagram-cube-visible><span>Show cube</span></button><label class="diagram-orbit">Orbit around<select data-diagram-orbit><option value="">Model center</option></select></label><label class="diagram-camera-zoom">Camera zoom<input type="range" min="50" max="500" step="10" data-diagram-camera-zoom></label>' + ["front", "back", "left", "right", "top", "bottom", "oblique"].map(value => option(`diagram-${value}`, value[0].toUpperCase() + value.slice(1))).join("") + option("diagram-turn-left", "Turn left 15°") + option("diagram-turn-right", "Turn right 15°"))}
+  ${menu("items", "Items", '<div class="diagram-items" data-diagram-items></div>')}
+  ${menu("options", "Options", '<label class="diagram-spacing">Spacing<input type="range" min="0" max="150" data-diagram-gap></label>')}
+</div>`;
+
+const DEFAULT_VIEW = Object.freeze({
+  cameraView: { position: [0, 0, 30], target: [0, 0, 0] },
+  cameraZoom: 1, gap: 20, labels: true, relations: "all", showOrientationCube: true,
+  focus: { mode: "all", effect: "dim", layout: "preserve", opacity: .2 }
+});
+
+export function normalizedDiagramView(value = {}) {
+  const view = value && typeof value === "object" ? value : {};
+  return {
+    ...DEFAULT_VIEW, ...view,
+    cameraView: view.cameraView?.position?.length === 3 && view.cameraView?.target?.length === 3
+      ? { position: [...view.cameraView.position], target: [...view.cameraView.target] }
+      : { position: [...DEFAULT_VIEW.cameraView.position], target: [...DEFAULT_VIEW.cameraView.target] },
+    cameraZoom: clamp(Number(view.cameraZoom) || 1, .5, 5),
+    gap: clamp(Number(view.gap ?? 20) || 0, 0, 150),
+    labels: view.labels !== false,
+    showOrientationCube: view.showOrientationCube !== false,
+    relations: ["all", "within", "selected", "callers", "called", "none"].includes(view.relations) ? view.relations : "all",
+    focus: {
+      mode: view.focus?.mode === "connected" ? "connected" : "all",
+      effect: view.focus?.effect === "hide" ? "hide" : "dim",
+      layout: view.focus?.layout === "reflow" ? "reflow" : "preserve",
+      opacity: clamp(Number(view.focus?.opacity ?? .2), 0, 1)
+    }
+  };
+}
+
+function diagramItemNode(atlas, node) {
+  return node.type !== "container" && node.type !== "shell" || (atlas.open && !atlas.open.has(node.id));
+}
+
+function diagramNodeVisible(atlas, node) {
+  return typeof atlas._isVisible === "function" ? atlas._isVisible(node) : node.group?.visible;
+}
+
+function modelCenter(atlas) {
+  const points = [...atlas.nodes.values()].filter(node => diagramNodeVisible(atlas, node) && diagramItemNode(atlas, node)).map(node => node.group.position);
+  if (!points.length) return [0, 0, 0];
+  return ["x", "y", "z"].map(axis => (Math.min(...points.map(point => point[axis])) + Math.max(...points.map(point => point[axis]))) / 2);
+}
+
+function cameraView(target, yaw, pitch) {
+  const distance = 30;
+  return { target: [...target], position: [target[0] + distance * Math.sin(yaw) * Math.cos(pitch), target[1] + distance * Math.sin(pitch), target[2] + distance * Math.cos(yaw) * Math.cos(pitch)] };
+}
+
+function cameraAngles(view) {
+  const [x, y, z] = view.position.map((value, index) => value - view.target[index]);
+  return { yaw: Math.atan2(x, z), pitch: Math.asin(clamp(y / (Math.hypot(x, y, z) || 1), -1, 1)) };
+}
+
+const CUBE_FACES = [
+  { id: "front", normal: [0, 0, 1], corners: [[-1,-1,1],[1,-1,1],[1,1,1],[-1,1,1]] },
+  { id: "back", normal: [0, 0, -1], corners: [[1,-1,-1],[-1,-1,-1],[-1,1,-1],[1,1,-1]] },
+  { id: "right", normal: [1, 0, 0], corners: [[1,-1,1],[1,-1,-1],[1,1,-1],[1,1,1]] },
+  { id: "left", normal: [-1, 0, 0], corners: [[-1,-1,-1],[-1,-1,1],[-1,1,1],[-1,1,-1]] },
+  { id: "top", normal: [0, 1, 0], corners: [[-1,1,1],[1,1,1],[1,1,-1],[-1,1,-1]] },
+  { id: "bottom", normal: [0, -1, 0], corners: [[-1,-1,-1],[1,-1,-1],[1,-1,1],[-1,-1,1]] }
+];
+
+function orientationCubeSvg({ yaw, pitch }) {
+  const dot = (a, b) => a.reduce((sum, value, index) => sum + value * b[index], 0);
+  const direction = [Math.sin(yaw) * Math.cos(pitch), Math.sin(pitch), Math.cos(yaw) * Math.cos(pitch)];
+  const right = [Math.cos(yaw), 0, -Math.sin(yaw)];
+  const up = [-Math.sin(yaw) * Math.sin(pitch), Math.cos(pitch), -Math.cos(yaw) * Math.sin(pitch)];
+  const project = point => [70 + 38 * dot(right, point), 70 - 38 * dot(up, point)];
+  const faces = CUBE_FACES.filter(face => dot(face.normal, direction) > .01)
+    .sort((a, b) => dot(a.normal, direction) - dot(b.normal, direction));
+  const shapes = faces.map(face => {
+    const points = face.corners.map(point => project(point).map(value => value.toFixed(1)).join(",")).join(" ");
+    const [x, y] = project(face.normal);
+    return '<g data-cube-face="' + face.id + '"><polygon points="' + points
+      + '"/><text x="' + x.toFixed(1) + '" y="' + (y + 3).toFixed(1)
+      + '" text-anchor="middle">' + face.id.toUpperCase() + "</text></g>";
+  }).join("");
+  return '<svg viewBox="0 0 140 140" role="img" aria-label="Model orientation"><circle cx="70" cy="70" r="62"/>' + shapes + "</svg>";
+}
+
+function panTarget(target, { yaw, pitch }, dx, dy, pixelScale) {
+  const right = [Math.cos(yaw), 0, -Math.sin(yaw)];
+  const up = [-Math.sin(yaw) * Math.sin(pitch), Math.cos(pitch), -Math.cos(yaw) * Math.sin(pitch)];
+  return target.map((value, index) => value - right[index] * dx / pixelScale + up[index] * dy / pixelScale);
+}
+
+export class DiagramView {
+  constructor(atlas) {
+    this.atlas = atlas;
+    this.root = atlas.shadowRoot.querySelector(".diagram-view");
+    this.content = this.root.querySelector(".diagram-content");
+    this.cube = atlas.toolbar.querySelector("[data-diagram-cube]");
+    atlas.shadowRoot.querySelector(".viewport").append(this.cube);
+    atlas.toolbar.querySelector('[data-toolbar-menu="relations"] .toolbar-popover')
+      ?.insertAdjacentHTML("beforeend", option("diagram-relations-within", "Same container"));
+    this.config = normalizedDiagramView();
+    this.zoom = "fit";
+    this.result = null;
+    this._bind();
+  }
+
+  get state() { return structuredClone(this.config); }
+
+  setState(value = {}) {
+    this.config = normalizedDiagramView(value?.cameraView ? value : {
+      ...value, cameraView: cameraView(modelCenter(this.atlas), 0, 0)
+    });
+    this.zoom = "fit";
+    this.refresh();
+  }
+
+  captureState() {
+    const state = this.state;
+    // Layout and framing are derived from the model and the current canvas.
+    // Older documents may have captured every computed position; omit those
+    // snapshots from new markup while continuing to read them on import.
+    delete state.placements;
+    delete state.frameAspect;
+    return state;
+  }
+
+  setConfig(patch, { layout = false, defer = false } = {}) {
+    this.config = normalizedDiagramView({ ...this.config, ...patch, ...(layout ? { placements: undefined, frameAspect: undefined } : {}) });
+    if (defer && globalThis.requestAnimationFrame) this.scheduleRefresh();
+    else this.refresh();
+    this.atlas.dispatchEvent(new CustomEvent("lc-diagram-change", { detail: { state: this.state }, bubbles: true, composed: true }));
+  }
+
+  scheduleRefresh() {
+    if (this._refreshQueued) return;
+    this._refreshQueued = true;
+    requestAnimationFrame(() => { if (this._refreshQueued) this.refresh(); });
+  }
+
+  renderOptions(extra = {}) {
+    const state = this.config;
+    const focused = this._focusedIds();
+    return {
+      cameraView: state.cameraView, cameraFrame: { zoom: state.cameraZoom, aspect: state.frameAspect || this.root.clientWidth / Math.max(1, this.root.clientHeight) },
+      includeIds: state.includeIds, relationGroups: state.relationGroups,
+      relations: state.relations, relationIndexes: this._relationIndexes(),
+      focus: focused ? { ids: [...focused], ...state.focus } : null,
+      gap: state.gap, labels: state.labels, placements: state.placements,
+      background: "#f5f5f5", ...extra
+    };
+  }
+
+  _relationIndexes() {
+    const mode = this.config.relations;
+    if (!["selected", "callers", "called"].includes(mode)) return null;
+    const atlas = this.atlas;
+    if (mode === "selected") {
+      if (atlas.selectedRelationIndex != null) return [atlas.selectedRelationIndex];
+      if (!atlas.selectedId) return [];
+      return atlas.relations.flatMap((relation, index) =>
+        relation.from === atlas.selectedId || relation.to === atlas.selectedId ? [index] : []);
+    }
+    const relation = atlas.selectedRelationIndex == null ? null : atlas.relations[atlas.selectedRelationIndex];
+    const seed = atlas.selectedId || (mode === "callers" ? relation?.to : relation?.from);
+    return seed ? atlas._recursiveRelationIndexes(seed, mode) : [];
+  }
+
+  _focusedIds() {
+    if (this.config.focus.mode !== "connected") return null;
+    const atlas = this.atlas;
+    const focused = new Set();
+    if (atlas.selectedId) focused.add(atlas.selectedId);
+    else if (atlas.selectedRelationIndex != null) {
+      const relation = atlas.relations[atlas.selectedRelationIndex];
+      if (relation) { focused.add(relation.from); focused.add(relation.to); }
+    }
+    if (!focused.size) return null;
+    const descendants = id => {
+      for (const node of atlas.nodes.values()) if (node.parent === id && !focused.has(node.id)) {
+        focused.add(node.id);
+        descendants(node.id);
+      }
+    };
+    for (const id of [...focused]) if (["container", "shell"].includes(atlas.nodes.get(id)?.type)) descendants(id);
+    const seeds = new Set(focused);
+    for (const relation of atlas.relations) if (seeds.has(relation.from) || seeds.has(relation.to)) {
+      focused.add(relation.from);
+      focused.add(relation.to);
+    }
+    for (const id of [...focused]) {
+      if (["container", "shell"].includes(atlas.nodes.get(id)?.type)) descendants(id);
+      let parent = atlas.nodes.get(id)?.parent, guard = 0;
+      while (parent && guard++ < atlas.nodes.size) {
+        focused.add(parent);
+        parent = atlas.nodes.get(parent)?.parent;
+      }
+    }
+    return focused;
+  }
+
+  refresh() {
+    this._refreshQueued = false;
+    if (this.atlas.viewMode !== "2d" || !this.atlas.ready || !this.root.clientWidth) return false;
+    this._syncControls();
+    const options = this.renderOptions({ faceCache: new Map(), background: null, maskGrid: true });
+    const viewport = { width: this.root.clientWidth, height: this.root.clientHeight };
+    const fit = result => Math.min(1, (viewport.width - 32) / result.width, (viewport.height - 32) / result.height);
+    const initial = this.atlas.exportDiagramSvg({ ...options, measureOnly: true });
+    let zoom = this.zoom === "fit" ? fit(initial) : this.zoom;
+    for (let i = 0; i < (this.zoom === "fit" ? 8 : 1); i += 1) {
+      zoom = Math.max(.08, zoom);
+      const result = this.atlas.exportDiagramSvg({ ...options, observerScale: zoom, measureOnly: true });
+      if (this.zoom !== "fit") break;
+      const next = fit(result);
+      if (Math.abs(next - zoom) < .002) break;
+      zoom = next;
+    }
+    const result = this.atlas.exportDiagramSvg({ ...options, observerScale: zoom });
+    this.result = result;
+    const previousX = this.root.scrollLeft, previousY = this.root.scrollTop;
+    this.content.innerHTML = result.svg;
+    const svg = this.content.querySelector("svg");
+    svg.style.width = `${Math.round(result.width * zoom)}px`;
+    svg.style.height = `${Math.round(result.height * zoom)}px`;
+    this.root.scrollLeft = this.zoom === "fit" ? 0 : previousX;
+    this.root.scrollTop = this.zoom === "fit" ? 0 : previousY;
+    this._syncSelection();
+    return true;
+  }
+
+  _syncSelection() {
+    this.content.querySelectorAll(".selected").forEach(element => element.classList.remove("selected"));
+    if (this.atlas.selectedId) for (const element of this.content.querySelectorAll("[data-entity]")) {
+      if (element.dataset.entity === this.atlas.selectedId) element.classList.add("selected");
+    }
+    if (this.atlas.selectedRelation?.id) for (const element of this.content.querySelectorAll("[data-relation]")) {
+      if (element.dataset.relation === this.atlas.selectedRelation.id) element.classList.add("selected");
+    }
+  }
+
+  _syncControls() {
+    const toolbar = this.atlas.toolbar;
+    this.cube.hidden = !this.config.showOrientationCube;
+    this.cube.innerHTML = orientationCubeSvg(cameraAngles(this.config.cameraView));
+    toolbar.querySelector("[data-diagram-cube-visible]").checked = this.config.showOrientationCube;
+    const orbit = toolbar.querySelector("[data-diagram-orbit]");
+    const orbitIds = [...this.atlas.nodes.values()].filter(node => diagramNodeVisible(this.atlas, node) && diagramItemNode(this.atlas, node));
+    orbit.innerHTML = '<option value="">Model center</option>' + orbitIds.map(node =>
+      '<option value="' + escapeHtml(node.id) + '">' + escapeHtml(node.name || node.id) + "</option>").join("");
+    orbit.value = this.config.orbitId || "";
+    toolbar.querySelector("[data-diagram-camera-zoom]").value = String(Math.round(this.config.cameraZoom * 100));
+    const items = toolbar.querySelector("[data-diagram-items]");
+    const visible = new Set(this.config.includeIds || [...this.atlas.nodes.keys()]);
+    const nodes = [...this.atlas.nodes.values()].filter(node => diagramNodeVisible(this.atlas, node) && diagramItemNode(this.atlas, node));
+    items.innerHTML = nodes.map(node => `<button type="button" class="toolbar-option checkbox" data-diagram-item="${escapeHtml(node.id)}"><input type="checkbox" ${visible.has(node.id) ? "checked" : ""}><span>${escapeHtml(node.name || node.id)}</span></button>`).join("");
+    const groupIds = [...new Set(this.atlas.relations.map(relation => relation.group || "default"))];
+    const selectedGroups = new Set(this.config.relationGroups || groupIds);
+    for (const button of toolbar.querySelectorAll('[data-action="relation-group-toggle"]')) {
+      const active = selectedGroups.has(button.dataset.relationGroup);
+      button.classList.toggle("active", active);
+      button.setAttribute("aria-pressed", String(active));
+    }
+    toolbar.querySelector("[data-diagram-gap]").value = String(this.config.gap);
+    const setActive = (action, active) => {
+      const button = toolbar.querySelector(`[data-action="${action}"]`);
+      if (!button) return;
+      button.classList.toggle("active", active);
+      button.setAttribute("aria-pressed", String(active));
+    };
+    setActive("labels", this.config.labels);
+    for (const mode of ["all", "selected", "callers", "called", "none"]) {
+      setActive(`relations-${mode}`, this.config.relations === mode);
+    }
+    setActive("diagram-relations-within", this.config.relations === "within");
+    const relationStatus = toolbar.querySelector('[data-toolbar-status="relations"]');
+    if (relationStatus) relationStatus.textContent = {
+      all: "All", selected: "Selection", callers: "Upstream", called: "Downstream",
+      within: "Same container", none: "Hide"
+    }[this.config.relations];
+    const focus = this.config.focus;
+    const focusMode = focus.mode === "all" ? "all" : focus.effect;
+    for (const mode of ["all", "dim", "hide"]) setActive(`focus-${mode}`, focusMode === mode);
+    setActive("focus-layout", focus.layout === "reflow");
+    const focusStatus = toolbar.querySelector('[data-toolbar-status="focus"]');
+    if (focusStatus) focusStatus.textContent = focusMode === "all" ? "All" : focusMode === "dim" ? "Connected" : "Isolate";
+    const layout = toolbar.querySelector('[data-action="focus-layout"]');
+    if (layout) layout.disabled = focus.mode === "all";
+    const selection = toolbar.querySelector('[data-action="focus-selection"]');
+    if (selection) selection.disabled = !this.atlas.selectedId && this.atlas.selectedRelationIndex == null;
+  }
+
+  focusSelection() {
+    if (this.zoom === "fit" && this.result) {
+      const fit = Math.min(1, (this.root.clientWidth - 32) / this.result.width,
+        (this.root.clientHeight - 32) / this.result.height);
+      this.zoom = clamp(Math.max(.75, fit * 1.8), .08, 4);
+      this.refresh();
+    }
+    const selected = [...this.content.querySelectorAll("[data-entity], [data-relation]")]
+      .find(element => element.dataset.entity === this.atlas.selectedId
+        || element.dataset.relation === this.atlas.selectedRelation?.id);
+    if (!selected) return;
+    const item = selected.getBoundingClientRect();
+    const frame = this.root.getBoundingClientRect();
+    this.root.scrollLeft += item.left + item.width / 2 - frame.left - frame.width / 2;
+    this.root.scrollTop += item.top + item.height / 2 - frame.top - frame.height / 2;
+  }
+
+  action(action, control) {
+    if (!action) return false;
+    if (action === "diagram-fit") { this.zoom = "fit"; this.refresh(); return true; }
+    if (action === "diagram-plus" || action === "diagram-minus") {
+      const current = this.zoom === "fit" ? Math.min(1, (this.root.clientWidth - 32) / (this.result?.width || 1), (this.root.clientHeight - 32) / (this.result?.height || 1)) : this.zoom;
+      this.zoom = clamp(current * (action === "diagram-plus" ? 1.4 : 1 / 1.4), .08, 4);
+      this.refresh(); return true;
+    }
+    if (action === "labels") { this.setConfig({ labels: !this.config.labels }, { layout: true }); return true; }
+    if (action === "diagram-cube") { this.setConfig({ showOrientationCube: !this.config.showOrientationCube }); return true; }
+    if (action?.startsWith("relations-")) { this.setConfig({ relations: action.slice(10) }); return true; }
+    if (action === "relation-group-toggle") {
+      const all = [...new Set(this.atlas.relations.map(relation => relation.group || "default"))];
+      const included = new Set(this.config.relationGroups || all);
+      const id = control?.dataset.relationGroup;
+      if (id && included.has(id)) included.delete(id); else if (id) included.add(id);
+      this.setConfig({ relationGroups: [...included] });
+      return true;
+    }
+    if (action === "focus-all") { this.setConfig({ focus: { ...this.config.focus, mode: "all" } }); return true; }
+    if (action === "focus-dim" || action === "focus-hide") {
+      this.setConfig({ focus: { ...this.config.focus, mode: "connected", effect: action.slice(6) } });
+      return true;
+    }
+    if (action === "focus-layout") {
+      this.setConfig({ focus: { ...this.config.focus, layout: this.config.focus.layout === "reflow" ? "preserve" : "reflow" } });
+      return true;
+    }
+    if (action === "focus-selection") { this.focusSelection(); return true; }
+    if (action.startsWith("diagram-relations-")) { this.setConfig({ relations: action.slice(18) }); return true; }
+    const angles = cameraAngles(this.config.cameraView);
+    const presets = { front: [0, 0], back: [Math.PI, 0], left: [-Math.PI / 2, 0], right: [Math.PI / 2, 0], top: [0, Math.PI / 2 - .015], bottom: [0, -.5 * Math.PI + .015], oblique: [.45, .31] };
+    const preset = action.slice(8);
+    if (presets[preset] || action === "diagram-turn-left" || action === "diagram-turn-right") {
+      const [yaw, pitch] = presets[preset] || [angles.yaw + (action === "diagram-turn-right" ? Math.PI / 12 : -Math.PI / 12), angles.pitch];
+      this.setConfig({ cameraView: cameraView(this.config.cameraView.target, yaw, pitch) }, { layout: true }); return true;
+    }
+    return false;
+  }
+
+  _bind() {
+    this.atlas.addEventListener("lc-select", () => {
+      if (this.atlas.viewMode !== "2d") return;
+      if (["selected", "callers", "called"].includes(this.config.relations) || this.config.focus.mode === "connected") this.refresh();
+      else this._syncSelection();
+    });
+    this.atlas.addEventListener("lc-model-change", () => this.refresh());
+    this.atlas.toolbar.addEventListener("input", event => {
+      if (event.target.matches("[data-diagram-gap]")) this.setConfig({ gap: Number(event.target.value) }, { layout: true, defer: true });
+      if (event.target.matches("[data-diagram-camera-zoom]")) this.setConfig({ cameraZoom: Number(event.target.value) / 100 }, { layout: true, defer: true });
+    });
+    this.atlas.toolbar.addEventListener("change", event => {
+      if (!event.target.matches("[data-diagram-orbit]")) return;
+      const orbitId = event.target.value;
+      const target = orbitId ? this.atlas.nodes.get(orbitId)?.group.position.toArray() : modelCenter(this.atlas);
+      const angles = cameraAngles(this.config.cameraView);
+      this.setConfig({ orbitId, cameraView: cameraView(target || modelCenter(this.atlas), angles.yaw, angles.pitch) }, { layout: true });
+    });
+    this.atlas.toolbar.addEventListener("click", event => {
+      const item = event.target.closest("[data-diagram-item]");
+      if (item) {
+        const all = [...this.atlas.nodes.keys()];
+        const included = new Set(this.config.includeIds || all);
+        if (included.has(item.dataset.diagramItem)) included.delete(item.dataset.diagramItem); else included.add(item.dataset.diagramItem);
+        this.setConfig({ includeIds: [...included] }, { layout: true });
+      }
+    });
+    const cube = this.cube;
+    cube.addEventListener("pointerdown", event => {
+      if (event.button !== 0) return;
+      this._cubeDrag = { id: event.pointerId, x: event.clientX, y: event.clientY,
+        face: event.target.closest?.("[data-cube-face]")?.dataset.cubeFace, moved: false };
+      cube.setPointerCapture(event.pointerId);
+    });
+    cube.addEventListener("pointermove", event => {
+      const drag = this._cubeDrag;
+      if (!drag || event.pointerId !== drag.id) return;
+      const dx = event.clientX - drag.x, dy = event.clientY - drag.y;
+      if (Math.hypot(dx, dy) < 2) return;
+      drag.moved = true; drag.x = event.clientX; drag.y = event.clientY;
+      const angles = cameraAngles(this.config.cameraView);
+      this.setConfig({ cameraView: cameraView(this.config.cameraView.target,
+        angles.yaw - dx * .007, clamp(angles.pitch + dy * .007, -Math.PI / 2 + .015, Math.PI / 2 - .015)) }, { layout: true, defer: true });
+    });
+    cube.addEventListener("pointerup", event => {
+      if (!this._cubeDrag || event.pointerId !== this._cubeDrag.id) return;
+      const { face, moved } = this._cubeDrag;
+      this._cubeDrag = null;
+      if (face && !moved) this.action("diagram-" + face);
+    });
+    cube.addEventListener("pointercancel", () => { this._cubeDrag = null; });
+    cube.addEventListener("keydown", event => {
+      const actions = { ArrowLeft: "diagram-turn-left", ArrowRight: "diagram-turn-right", Home: "diagram-front" };
+      if (!actions[event.key]) return;
+      event.preventDefault();
+      this.action(actions[event.key]);
+    });
+    this.root.addEventListener("click", event => {
+      if (this._dragged) { this._dragged = false; return; }
+      const entity = event.target.closest?.("[data-entity]");
+      const relation = event.target.closest?.("[data-relation]");
+      if (entity) this.atlas.select(entity.dataset.entity, { source: "diagram" });
+      else if (relation) this.atlas.selectRelation(relation.dataset.relation, { source: "diagram" });
+    });
+    this.root.addEventListener("pointerdown", event => {
+      if (event.button !== 0 && event.button !== 2) return;
+      this._dragged = false;
+      this._pointer = { id: event.pointerId, x: event.clientX, y: event.clientY };
+    });
+    this.root.addEventListener("pointermove", event => {
+      if (!this._pointer || this._pointer.id !== event.pointerId) return;
+      const dx = event.clientX - this._pointer.x, dy = event.clientY - this._pointer.y;
+      if (!this._dragged && Math.hypot(dx, dy) > 3) {
+        this._dragged = true;
+        this.root.setPointerCapture(event.pointerId);
+      }
+      if (this._dragged) {
+        this.root.classList.add("dragging");
+        const oldX = this.root.scrollLeft, oldY = this.root.scrollTop;
+        this.root.scrollLeft -= dx;
+        this.root.scrollTop -= dy;
+        const remainingX = dx + this.root.scrollLeft - oldX;
+        const remainingY = dy + this.root.scrollTop - oldY;
+        if ((remainingX || remainingY) && this.config.cameraZoom > 1) {
+          const angles = cameraAngles(this.config.cameraView);
+          const zoom = this.zoom === "fit" ? Math.min(1, this.root.clientWidth / (this.result?.width || 1),
+            this.root.clientHeight / (this.result?.height || 1)) : this.zoom;
+          const target = panTarget(this.config.cameraView.target, angles, remainingX, remainingY, 80 * Math.max(.08, zoom));
+          this.setConfig({ cameraView: cameraView(target, angles.yaw, angles.pitch) }, { layout: true, defer: true });
+        }
+      }
+      this._pointer.x = event.clientX; this._pointer.y = event.clientY;
+    });
+    const stop = () => { this._pointer = null; this.root.classList.remove("dragging"); };
+    this.root.addEventListener("pointerup", stop);
+    this.root.addEventListener("pointercancel", stop);
+    this.root.addEventListener("contextmenu", event => event.preventDefault());
+    this.root.addEventListener("wheel", event => {
+      if (!event.altKey && !event.ctrlKey) return;
+      event.preventDefault();
+      const zoom = this.zoom === "fit" ? Math.min(1, this.root.clientWidth / (this.result?.width || 1), this.root.clientHeight / (this.result?.height || 1)) : this.zoom;
+      this.zoom = clamp(zoom * (event.deltaY < 0 ? 1.15 : 1 / 1.15), .08, 4);
+      this.scheduleRefresh();
+    }, { passive: false });
+  }
+}

package/src/document-navigation.js

@@ -0,0 +1,27 @@
+/**
+ * Atlas paths are rooted in a document collection. atlas:/ starts at its root;
+ * atlas:foo resolves beside the current document. The fragment names an entity.
+ */
+export function resolveAtlasReference(reference, from = null) {
+  const raw = String(reference || "").trim();
+  if (!raw.startsWith("atlas:")) throw new TypeError("Expected an atlas: reference.");
+  const body = raw.slice(6);
+  if (body.startsWith("//")) throw new TypeError("Atlas authorities are not supported.");
+  const hash = body.indexOf("#");
+  const path = hash < 0 ? body : body.slice(0, hash);
+  const fragment = hash < 0 ? "" : decodeURIComponent(body.slice(hash + 1));
+  const base = from ? resolveAtlasReference(from).uri.slice(6) : "/";
+  if (!path && !from) throw new TypeError("An Atlas reference needs a document path.");
+  if (!path) return { uri: "atlas:" + base, fragment };
+  const segments = (path.startsWith("/") ? [] : base.split("/").slice(0, -1).filter(Boolean));
+  for (const part of path.split("/")) {
+    if (!part || part === ".") continue;
+    if (part === "..") {
+      if (!segments.length) throw new TypeError("Atlas reference escapes the collection root.");
+      segments.pop();
+    } else {
+      segments.push(decodeURIComponent(part));
+    }
+  }
+  return { uri: "atlas:/" + segments.map(encodeURIComponent).join("/"), fragment };
+}