tsquare 0.13.2 → 0.14.0

package/dist/playground/viewer.d.ts

@@ -2,15 +2,35 @@
  * The zoomable board: zoom, pan, pinch, and zoom to a screen. Browser code,
  * published as `tsquare/viewer`: the playground page uses it, and so does the
  * VS Code extension's preview. Each brings its own markup and controls and
- * passes the elements in; the board comes from renderWireframeSvg + boardLayout.
+ * passes the elements in; the board comes from renderWireframeSvg + measureBoardLayout.
  *
  * The viewer sets the styles its math depends on (structuralStyles, and the
  * board image's size in show()), so the host only needs to size the stage and
  * optionally style the "panning", "animate" and "stale" classes it toggles on
  * the stage.
+ *
+ * Clicks and hovers on elements (0.14.0) need the board's measureElements
+ * entries, which the host makes where it renders and hands over with
+ * setElements: the viewer hit-tests them (hit.ts, nothing heavy) but never
+ * renders or measures.
  */
+import { type Measured, type MeasuredBox } from "../hit.js";
 import type { BoardItem } from "../render.js";
-export type { BoardItem };
+export type { BoardItem, Measured, MeasuredBox };
+export interface ViewerOptions {
+    /** A screen chip was clicked. */
+    onScreenZoom?: () => void;
+    /** The zoom level changed. */
+    onZoom?: (scale: number) => void;
+    /**
+     * A click on the board (a press that hardly moves; dragging pans): the element most likely meant
+     * and everything under the point, most likely first (elementsAt's order), from setElements'
+     * entries. Only once elements are set; `hit` is null outside every element.
+     */
+    onElementClick?: (hit: Measured | null, hits: Measured[], event: PointerEvent) => void;
+    /** The pointer is over a different element than before (null: over none), while no button is pressed. */
+    onElementHover?: (hit: Measured | null, hits: Measured[]) => void;
+}
 export interface ViewerElements {
     /**
      * The visible area; give it a size. It gets these classes, for optional styling:
@@ -40,8 +60,33 @@ export interface Viewer {
     zoomOut(): void;
     /** Stop: remove the viewer's listeners and release the board image. For hosts that remove the viewer (a React component unmounting). */
     destroy(): void;
+    /**
+     * The board's measureElements entries, for clicks, hovers and zoomTo; null (or none) turns
+     * element clicks off. Set them after each show() of a new board: they describe one board.
+     */
+    setElements(elements: Measured[] | null): void;
+    /**
+     * Outlines entries on the board, inside the zoomed canvas: a box per element, the line and label
+     * of a flow. Each kind replaces its own earlier ones ([] clears it); "selected" (the default) is
+     * solid, "hover" lighter. The color is the CSS variable --tsquare-highlight (default #3B99FB).
+     */
+    highlight(entries: Measured[], opts?: {
+        kind?: "selected" | "hover";
+    }): void;
+    /** Zooms to an entry's box (a flow: its line and label) or any box in board pixels, and stays on it as the stage resizes. */
+    zoomTo(target: Measured | MeasuredBox, opts?: {
+        animate?: boolean;
+    }): void;
+    /** A point on the page (a pointer event's clientX/clientY) in board pixels, where measureElements' boxes are. */
+    toBoard(clientX: number, clientY: number): {
+        x: number;
+        y: number;
+    };
+    /**
+     * An element over the board for the host's own marks (comment pins, a text field), positioned in
+     * board pixels: it pans and zooms with the board. It ignores the pointer; give children that
+     * should be clickable pointer-events: auto.
+     */
+    readonly layer: HTMLElement;
 }
-export declare function createViewer(el: ViewerElements, opts?: {
-    onScreenZoom?: () => void;
-    onZoom?: (scale: number) => void;
-}): Viewer;
+export declare function createViewer(el: ViewerElements, opts?: ViewerOptions): Viewer;

package/dist/playground/viewer.js

@@ -1,3 +1,44 @@
+// src/hit.ts
+var isFlow = (e) => e.type === "Flow";
+var OVERLAYS = /* @__PURE__ */ new Set(["Modal", "Drawer", "Toast"]);
+var CONTAINERS = /* @__PURE__ */ new Set(["Board", "Screen", "Stack", "Grid", "Card", "Accordion", "List", "Modal", "Drawer"]);
+var inside = (b, x, y) => !!b && b.width > 0 && b.height > 0 && x >= b.x && x <= b.x + b.width && y >= b.y && y <= b.y + b.height;
+var center = (b) => [b.x + b.width / 2, b.y + b.height / 2];
+function distanceToPath(path, x, y) {
+  let best = Infinity;
+  for (let i = 1; i < path.length; i++) {
+    const [ax, ay] = path[i - 1], [bx, by] = path[i];
+    const dx = bx - ax, dy = by - ay, len = dx * dx + dy * dy;
+    const t = len ? Math.max(0, Math.min(1, ((x - ax) * dx + (y - ay) * dy) / len)) : 0;
+    best = Math.min(best, Math.hypot(x - ax - t * dx, y - ay - t * dy));
+  }
+  return best;
+}
+var isContainer = (e) => CONTAINERS.has(e.type);
+function elementsAt(elements, x, y, opts = {}) {
+  const tolerance = opts.tolerance ?? 6;
+  const order = new Map(elements.map((e, i) => [e, i]));
+  const topFirst = (a, b) => order.get(b) - order.get(a);
+  const covered = /* @__PURE__ */ new Set();
+  const screens = elements.filter((e) => e.type === "Screen");
+  const screenAround = (b) => screens.find((s) => inside(s.box, ...center(b)));
+  for (const [i, m] of elements.entries()) {
+    if (isFlow(m) || !OVERLAYS.has(m.type)) continue;
+    const screen = screenAround(m.box);
+    if (!screen || !inside(m.box, x, y) && !(m.scrim && inside(screen.box, x, y))) continue;
+    for (const e of elements.slice(0, i)) if (!isFlow(e) && e.type !== "Screen" && e.type !== "Board" && screenAround(e.box) === screen) covered.add(e);
+  }
+  const owners = [], labels = [], leaves = [], lines = [], containers = [];
+  for (const e of elements) {
+    if (isFlow(e)) {
+      if (inside(e.labelBox, x, y)) labels.push(e);
+      else if (distanceToPath(e.path, x, y) <= tolerance) lines.push(e);
+    } else if (e.overlays?.some((o) => inside(o, x, y))) owners.push(e);
+    else if (!covered.has(e) && (inside(e.box, x, y) || inside(e.labelBox, x, y))) (isContainer(e) ? containers : leaves).push(e);
+  }
+  return [owners, labels, leaves, lines, containers].flatMap((g) => g.sort(topFirst));
+}
+
 // src/playground/viewer.ts
 function structuralStyles(stage, canvas) {
   if (getComputedStyle(stage).position === "static") stage.style.position = "relative";
@@ -16,6 +57,16 @@ function createViewer(el, opts = {}) {
   let scale = 1, x = 0, y = 0;
   let mode = "fit";
   const PAD = 16;
+  let elements = [];
+  const overlay = () => {
+    const d = document.createElement("div");
+    Object.assign(d.style, { position: "absolute", left: "0px", top: "0px", width: "0px", height: "0px", pointerEvents: "none" });
+    return d;
+  };
+  const marks = overlay(), layer = overlay();
+  marks.className = "tsquare-highlights";
+  layer.className = "tsquare-layer";
+  const highlights = { selected: [], hover: [] };
   const label = () => {
     if (el.zoomFit) el.zoomFit.textContent = `${Math.round(scale * 100)}%`;
     opts.onZoom?.(scale);
@@ -23,6 +74,7 @@ function createViewer(el, opts = {}) {
   const apply = (animate = false) => {
     stage.classList.toggle("animate", animate);
     canvas.style.transform = `translate(${x}px, ${y}px) scale(${scale})`;
+    canvas.style.setProperty("--tsquare-viewer-scale", String(scale));
     label();
   };
   const fitRect = (r, animate) => {
@@ -38,6 +90,7 @@ function createViewer(el, opts = {}) {
     if (!size.width) return;
     if (mode === "fit") fitRect({ x: 0, y: 0, ...size }, animate);
     else if (typeof mode === "number" && items[mode]) fitRect(items[mode], animate);
+    else if (typeof mode === "object") fitRect(mode, animate);
     else apply();
     markScreens();
   }
@@ -60,7 +113,7 @@ function createViewer(el, opts = {}) {
       img = document.createElement("img");
       img.alt = "Rendered wireframe";
       img.draggable = false;
-      canvas.replaceChildren(img);
+      canvas.replaceChildren(img, marks, layer);
       el.empty?.remove();
     }
     const old = img.src;
@@ -71,13 +124,14 @@ function createViewer(el, opts = {}) {
     img.width = width;
     img.height = height;
     Object.assign(img.style, { width: `${width}px`, height: `${height}px`, maxWidth: "none", maxHeight: "none" });
+    for (const o of [marks, layer]) Object.assign(o.style, { width: `${width}px`, height: `${height}px` });
     const screens = list.filter((i) => i.type === "Screen");
     if (screens.map((s) => s.name).join("\n") !== items.filter((i) => i.type === "Screen").map((s) => s.name).join("\n")) {
       if (typeof mode === "number") mode = "fit";
       buildScreenChips(screens);
     }
     items = screens;
-    if (resized && mode === "manual") mode = "fit";
+    if (resized && (mode === "manual" || typeof mode === "object")) mode = "fit";
     refresh();
   }
   function buildScreenChips(screens) {
@@ -98,8 +152,9 @@ function createViewer(el, opts = {}) {
       opts.onScreenZoom?.();
     }));
   }
+  const inLayer = (e) => e.target !== layer && layer.contains(e.target);
   stage.addEventListener("wheel", (e) => {
-    if (!size.width) return;
+    if (!size.width || inLayer(e)) return;
     e.preventDefault();
     const r = stage.getBoundingClientRect();
     if (e.ctrlKey || e.metaKey) zoomAt(Math.exp(-e.deltaY * 0.01), e.clientX - r.left, e.clientY - r.top);
@@ -117,15 +172,35 @@ function createViewer(el, opts = {}) {
     const [a, b] = [...pointers.values()];
     return { mid: { x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 }, dist: Math.hypot(a.x - b.x, a.y - b.y) };
   };
+  let press = null;
+  const hitsAt = (clientX, clientY) => {
+    const p = toBoard(clientX, clientY);
+    return elementsAt(elements, p.x, p.y, { tolerance: 8 / scale });
+  };
+  let hovered = null;
+  const hover = (hit, hits) => {
+    if (hit === hovered) return;
+    hovered = hit;
+    opts.onElementHover?.(hit, hits);
+  };
   stage.addEventListener("pointerdown", (e) => {
+    if (inLayer(e)) return;
     stage.setPointerCapture(e.pointerId);
+    press = pointers.size ? null : { id: e.pointerId, x: e.clientX, y: e.clientY, moved: false };
     pointers.set(e.pointerId, { x: e.clientX, y: e.clientY });
     stage.classList.add("panning");
     pinch = pointers.size === 2 ? twoFingers() : null;
   }, { signal });
   stage.addEventListener("pointermove", (e) => {
     const prev = pointers.get(e.pointerId);
-    if (!prev) return;
+    if (!prev) {
+      if (opts.onElementHover && elements.length && e.pointerType !== "touch") {
+        const hits = hitsAt(e.clientX, e.clientY);
+        hover(hits[0] ?? null, hits);
+      }
+      return;
+    }
+    if (press && (press.id !== e.pointerId || Math.hypot(e.clientX - press.x, e.clientY - press.y) > 4)) press.moved = true;
     pointers.set(e.pointerId, { x: e.clientX, y: e.clientY });
     if (pointers.size === 2 && pinch) {
       const now = twoFingers();
@@ -148,18 +223,80 @@ function createViewer(el, opts = {}) {
     }
   }, { signal });
   const release = (e) => {
+    if (e.type === "pointerup" && press && press.id === e.pointerId && !press.moved && pointers.size === 1 && opts.onElementClick && elements.length) {
+      const hits = hitsAt(e.clientX, e.clientY);
+      opts.onElementClick(hits[0] ?? null, hits, e);
+    }
+    if (press?.id === e.pointerId) press = null;
     pointers.delete(e.pointerId);
     pinch = pointers.size === 2 ? twoFingers() : null;
     if (!pointers.size) stage.classList.remove("panning");
   };
   stage.addEventListener("pointerup", release, { signal });
   stage.addEventListener("pointercancel", release, { signal });
-  stage.addEventListener("dblclick", fit, { signal });
+  stage.addEventListener("pointerleave", () => {
+    if (!pointers.size) hover(null, []);
+  }, { signal });
+  stage.addEventListener("dblclick", (e) => {
+    if (!inLayer(e)) fit();
+  }, { signal });
   const resize = new ResizeObserver(() => refresh());
   resize.observe(stage);
   el.zoomIn?.addEventListener("click", () => zoomAt(1.25), { signal });
   el.zoomOut?.addEventListener("click", () => zoomAt(0.8), { signal });
   el.zoomFit?.addEventListener("click", fit, { signal });
+  function toBoard(clientX, clientY) {
+    const r = stage.getBoundingClientRect();
+    return { x: (clientX - r.left - stage.clientLeft - x) / scale, y: (clientY - r.top - stage.clientTop - y) / scale };
+  }
+  function boxOf(e) {
+    if (!("type" in e)) return e;
+    if (!isFlow(e)) return e.box;
+    const xs = e.path.map((p) => p[0]), ys = e.path.map((p) => p[1]);
+    if (e.labelBox) xs.push(e.labelBox.x, e.labelBox.x + e.labelBox.width), ys.push(e.labelBox.y, e.labelBox.y + e.labelBox.height);
+    const [x0, y0] = [Math.min(...xs), Math.min(...ys)];
+    return { x: x0, y: y0, width: Math.max(...xs) - x0, height: Math.max(...ys) - y0 };
+  }
+  const SVG = "http://www.w3.org/2000/svg";
+  function mark(e, kind) {
+    const color = "var(--tsquare-highlight, #3B99FB)";
+    const width = "calc(2px / var(--tsquare-viewer-scale, 1))";
+    if (isFlow(e)) {
+      const svg = document.createElementNS(SVG, "svg");
+      svg.setAttribute("width", String(size.width));
+      svg.setAttribute("height", String(size.height));
+      Object.assign(svg.style, { position: "absolute", left: "0px", top: "0px", overflow: "visible" });
+      const line = document.createElementNS(SVG, "polyline");
+      line.setAttribute("points", e.path.map((p) => p.join(",")).join(" "));
+      line.setAttribute("fill", "none");
+      Object.assign(line.style, { stroke: color, strokeWidth: `calc(6px / var(--tsquare-viewer-scale, 1))`, strokeLinejoin: "round", strokeLinecap: "round", opacity: kind === "hover" ? "0.35" : "0.5" });
+      svg.append(line);
+      if (e.labelBox) {
+        const r = document.createElementNS(SVG, "rect");
+        for (const [k, v] of Object.entries({ x: e.labelBox.x, y: e.labelBox.y, width: e.labelBox.width, height: e.labelBox.height, rx: 12 })) r.setAttribute(k, String(v));
+        Object.assign(r.style, { fill: "none", stroke: color, strokeWidth: width, opacity: kind === "hover" ? "0.6" : "1" });
+        svg.append(r);
+      }
+      svg.setAttribute("class", `tsquare-highlight tsquare-highlight-${kind}`);
+      return svg;
+    }
+    const b = e.box;
+    const d = document.createElement("div");
+    d.className = `tsquare-highlight tsquare-highlight-${kind}`;
+    Object.assign(d.style, {
+      position: "absolute",
+      left: `${b.x}px`,
+      top: `${b.y}px`,
+      width: `${b.width}px`,
+      height: `${b.height}px`,
+      boxSizing: "border-box",
+      outline: `${width} ${kind === "hover" ? "dashed" : "solid"} ${color}`,
+      outlineOffset: "1px",
+      borderRadius: "3px",
+      background: kind === "selected" ? "color-mix(in srgb, var(--tsquare-highlight, #3B99FB) 8%, transparent)" : "transparent"
+    });
+    return d;
+  }
   return {
     show,
     refresh,
@@ -169,6 +306,24 @@ function createViewer(el, opts = {}) {
     fit,
     zoomIn: () => zoomAt(1.25),
     zoomOut: () => zoomAt(0.8),
+    setElements(list) {
+      elements = list ?? [];
+      if (hovered && !elements.includes(hovered)) hover(null, []);
+    },
+    highlight(entries, o = {}) {
+      const kind = o.kind ?? "selected";
+      for (const m of highlights[kind]) m.remove();
+      highlights[kind] = entries.filter((e) => isFlow(e) || e.box.width > 0 && e.box.height > 0).map((e) => mark(e, kind));
+      if (kind === "hover") marks.prepend(...highlights.hover);
+      else marks.append(...highlights.selected);
+    },
+    zoomTo(target, o = {}) {
+      const b = boxOf(target), m = 24;
+      mode = { x: b.x - m, y: b.y - m, width: b.width + 2 * m, height: b.height + 2 * m };
+      refresh(o.animate ?? true);
+    },
+    toBoard,
+    layer,
     destroy() {
       stop.abort();
       resize.disconnect();