@misoto22/design 0.6.1 → 0.8.0

package/dist/diagrams/DiagramCanvas/DiagramCanvas.js

@@ -0,0 +1,229 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import {
+  useCallback,
+  useEffect,
+  useId,
+  useImperativeHandle,
+  useRef,
+  useState
+} from "react";
+import { cn } from "../../lib/cn.js";
+const MIN_SCALE = 0.35;
+const MAX_SCALE = 4;
+const STEP = 1.25;
+function DiagramCanvas({
+  children,
+  className,
+  height = "24rem",
+  onViewChange,
+  controls = true,
+  label = "Diagram canvas",
+  ref
+}) {
+  const uid = useId().replace(/:/g, "");
+  const frame = useRef(null);
+  const [view, setView] = useState({ scale: 1, x: 0, y: 0 });
+  const drag = useRef(null);
+  const measure = useCallback(() => {
+    const box = frame.current?.getBoundingClientRect();
+    return box && box.width > 0 ? { width: box.width, height: box.height } : void 0;
+  }, []);
+  const apply = useCallback(
+    (next) => {
+      const measured = { ...next, frame: measure() };
+      setView(measured);
+      onViewChange?.(measured);
+    },
+    [measure, onViewChange]
+  );
+  const zoomAbout = useCallback(
+    (factor, originX, originY) => {
+      const box = frame.current?.getBoundingClientRect();
+      const cx = originX ?? (box ? box.width / 2 : 0);
+      const cy = originY ?? (box ? box.height / 2 : 0);
+      setView((current) => {
+        const scale = Math.min(MAX_SCALE, Math.max(MIN_SCALE, current.scale * factor));
+        const ratio = scale / current.scale;
+        const next = {
+          scale,
+          x: cx - (cx - current.x) * ratio,
+          y: cy - (cy - current.y) * ratio,
+          frame: measure()
+        };
+        onViewChange?.(next);
+        return next;
+      });
+    },
+    [measure, onViewChange]
+  );
+  useImperativeHandle(
+    ref,
+    () => ({
+      zoomIn: () => zoomAbout(STEP),
+      zoomOut: () => zoomAbout(1 / STEP),
+      reset: () => apply({ scale: 1, x: 0, y: 0 }),
+      centerOn: (x, y) => {
+        const box = frame.current?.getBoundingClientRect();
+        if (!box) return;
+        setView((current) => {
+          const next = {
+            ...current,
+            x: box.width / 2 - x * current.scale,
+            y: box.height / 2 - y * current.scale,
+            frame: measure()
+          };
+          onViewChange?.(next);
+          return next;
+        });
+      },
+      view
+    }),
+    [apply, measure, onViewChange, view, zoomAbout]
+  );
+  useEffect(() => {
+    const node = frame.current;
+    if (!node) return;
+    const onWheel = (event) => {
+      if (!event.ctrlKey && !event.metaKey) return;
+      event.preventDefault();
+      const box = node.getBoundingClientRect();
+      zoomAbout(
+        event.deltaY < 0 ? STEP : 1 / STEP,
+        event.clientX - box.left,
+        event.clientY - box.top
+      );
+    };
+    node.addEventListener("wheel", onWheel, { passive: false });
+    return () => node.removeEventListener("wheel", onWheel);
+  }, [zoomAbout]);
+  const onPointerDown = (event) => {
+    if (event.button !== 0) return;
+    drag.current = { pointer: event.pointerId, x: event.clientX - view.x, y: event.clientY - view.y };
+    event.currentTarget.setPointerCapture(event.pointerId);
+  };
+  const onPointerMove = (event) => {
+    const state = drag.current;
+    if (!state || state.pointer !== event.pointerId) return;
+    apply({ ...view, x: event.clientX - state.x, y: event.clientY - state.y });
+  };
+  const endDrag = (event) => {
+    if (drag.current?.pointer !== event.pointerId) return;
+    drag.current = null;
+    if (event.currentTarget.hasPointerCapture(event.pointerId)) {
+      event.currentTarget.releasePointerCapture(event.pointerId);
+    }
+  };
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: cn(
+        "relative overflow-hidden rounded-(--radius-lg) border border-(--rule) bg-(--diagram-surface)",
+        className
+      ),
+      style: { height },
+      children: [
+        /* @__PURE__ */ jsx(
+          "div",
+          {
+            ref: frame,
+            role: "group",
+            "aria-label": label,
+            "aria-describedby": `${uid}-hint`,
+            tabIndex: 0,
+            className: "size-full cursor-grab touch-none select-none outline-none focus-visible:ring-2 focus-visible:ring-(--ring) focus-visible:ring-inset active:cursor-grabbing",
+            onPointerDown,
+            onPointerMove,
+            onPointerUp: endDrag,
+            onPointerCancel: endDrag,
+            onKeyDown: (event) => {
+              const nudge = event.shiftKey ? 80 : 24;
+              switch (event.key) {
+                case "+":
+                case "=":
+                  event.preventDefault();
+                  zoomAbout(STEP);
+                  break;
+                case "-":
+                  event.preventDefault();
+                  zoomAbout(1 / STEP);
+                  break;
+                case "0":
+                  event.preventDefault();
+                  apply({ scale: 1, x: 0, y: 0 });
+                  break;
+                case "ArrowLeft":
+                  event.preventDefault();
+                  apply({ ...view, x: view.x + nudge });
+                  break;
+                case "ArrowRight":
+                  event.preventDefault();
+                  apply({ ...view, x: view.x - nudge });
+                  break;
+                case "ArrowUp":
+                  event.preventDefault();
+                  apply({ ...view, y: view.y + nudge });
+                  break;
+                case "ArrowDown":
+                  event.preventDefault();
+                  apply({ ...view, y: view.y - nudge });
+                  break;
+                default:
+                  break;
+              }
+            },
+            children: /* @__PURE__ */ jsx(
+              "div",
+              {
+                className: "origin-top-left will-change-transform",
+                style: { transform: `translate(${view.x}px, ${view.y}px) scale(${view.scale})` },
+                "data-diagram-stage": "",
+                children
+              }
+            )
+          }
+        ),
+        /* @__PURE__ */ jsx("p", { id: `${uid}-hint`, className: "sr-only", children: "Drag to pan. Plus and minus zoom, zero resets, the arrow keys pan." }),
+        controls && /* @__PURE__ */ jsxs("div", { className: "absolute bottom-3 end-3 flex items-center gap-px rounded-(--radius) border border-(--rule-2) bg-(--panel-bg) p-0.5", children: [
+          /* @__PURE__ */ jsx(CanvasButton, { label: "Zoom out", onClick: () => zoomAbout(1 / STEP), children: /* @__PURE__ */ jsx("span", { "aria-hidden": true, children: "\u2212" }) }),
+          /* @__PURE__ */ jsxs(
+            "button",
+            {
+              type: "button",
+              onClick: () => apply({ scale: 1, x: 0, y: 0 }),
+              "aria-label": "Reset the view",
+              className: "min-w-12 rounded-(--radius-xs) px-1.5 py-1 mono-meta text-(--ink-2) transition-colors duration-(--duration-fast) hover:bg-(--stone) hover:text-(--ink) focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-(--ring)",
+              children: [
+                Math.round(view.scale * 100),
+                "%"
+              ]
+            }
+          ),
+          /* @__PURE__ */ jsx(CanvasButton, { label: "Zoom in", onClick: () => zoomAbout(STEP), children: /* @__PURE__ */ jsx("span", { "aria-hidden": true, children: "+" }) })
+        ] })
+      ]
+    }
+  );
+}
+function CanvasButton({
+  label,
+  onClick,
+  children
+}) {
+  return /* @__PURE__ */ jsx(
+    "button",
+    {
+      type: "button",
+      onClick,
+      "aria-label": label,
+      className: "flex size-7 items-center justify-center rounded-(--radius-xs) font-mono text-[13px] leading-none text-(--ink-2) transition-colors duration-(--duration-fast) hover:bg-(--stone) hover:text-(--ink) focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-(--ring)",
+      children
+    }
+  );
+}
+var DiagramCanvas_default = DiagramCanvas;
+export {
+  DiagramCanvas,
+  DiagramCanvas_default as default
+};
+//# sourceMappingURL=DiagramCanvas.js.map

package/dist/diagrams/DiagramCanvas/DiagramCanvas.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/diagrams/DiagramCanvas/DiagramCanvas.tsx"],"sourcesContent":["'use client'\n\nimport {\n  useCallback,\n  useEffect,\n  useId,\n  useImperativeHandle,\n  useRef,\n  useState,\n  type PointerEvent as ReactPointerEvent,\n  type ReactNode,\n  type Ref,\n} from 'react'\nimport { cn } from '../../lib/cn'\n\nconst MIN_SCALE = 0.35\nconst MAX_SCALE = 4\nconst STEP = 1.25\n\nexport interface CanvasView {\n  scale: number\n  x: number\n  y: number\n  /**\n   * How big the frame was, in CSS pixels, when this view was reported.\n   *\n   * Carried on the view because everything that consumes a view needs it and\n   * nothing outside this component can measure it: a `DiagramMinimap`'s\n   * viewport rectangle is the frame's size over the zoom, and a caller who had\n   * to hand-declare that number was hand-declaring the one number that makes\n   * the map lie. Absent until the frame has been measured — the first render\n   * has no box yet — which is exactly when a map should draw nothing.\n   */\n  frame?: { width: number; height: number }\n}\n\n/** What a caller can do to the canvas from outside it. */\nexport interface DiagramCanvasHandle {\n  zoomIn: () => void\n  zoomOut: () => void\n  reset: () => void\n  /** Pans so a point in CONTENT coordinates sits in the middle of the frame. */\n  centerOn: (x: number, y: number) => void\n  view: CanvasView\n}\n\nexport interface DiagramCanvasProps {\n  children: ReactNode\n  className?: string\n  /** How tall the frame is. Anything CSS accepts. */\n  height?: string\n  /** Told about every view change, for a minimap or a percentage readout. */\n  onViewChange?: (view: CanvasView) => void\n  /** Hides the built-in zoom controls, for a caller supplying its own. */\n  controls?: boolean\n  /** Names the region for assistive tech. */\n  label?: string\n  ref?: Ref<DiagramCanvasHandle>\n}\n\n/**\n * A frame that a picture larger than it can be moved around inside.\n *\n * Pan with a drag, zoom with the controls or with ⌘/Ctrl and the wheel, and\n * reset with a key. That is the whole of it — this is deliberately a VIEWPORT\n * and not a diagram editor: nothing here knows what a node is, so it works for\n * any oversized figure, an SVG, an image, a table that will not fold.\n *\n * Three decisions here are not obvious.\n *\n * **A plain wheel scrolls the page, not the diagram.** A canvas that swallows\n * the wheel is a scroll trap: a reader flicking down an article hits the figure\n * and the page stops moving for no reason they can see. Zooming needs the\n * modifier — which is also the platform gesture for zoom everywhere else, and\n * is what a trackpad pinch already sends.\n *\n * **The transform is on a wrapper, not on the content.** The child keeps its\n * own coordinate space, so a figure inside can still be measured, exported and\n * read by anything that walks it. Scaling the child directly would make every\n * `getBoundingClientRect` inside it a lie.\n *\n * **Keyboard first, and the frame is a real tab stop.** `+` / `-` / `0` and the\n * arrow keys move the view; the frame takes focus so they can be pressed at\n * all. A canvas that only answers a drag is a canvas half the readers cannot\n * operate.\n *\n * @example\n * <DiagramCanvas height=\"26rem\" label=\"Request path\">\n *   <ArchitectureFigure spec={spec} heading={false} legend=\"hidden\" cards={false} />\n * </DiagramCanvas>\n */\nexport function DiagramCanvas({\n  children,\n  className,\n  height = '24rem',\n  onViewChange,\n  controls = true,\n  label = 'Diagram canvas',\n  ref,\n}: DiagramCanvasProps) {\n  const uid = useId().replace(/:/g, '')\n  const frame = useRef<HTMLDivElement>(null)\n  const [view, setView] = useState<CanvasView>({ scale: 1, x: 0, y: 0 })\n  const drag = useRef<{ pointer: number; x: number; y: number } | null>(null)\n\n  /** The frame's own size, or nothing when it has not been laid out yet. */\n  const measure = useCallback(() => {\n    const box = frame.current?.getBoundingClientRect()\n    return box && box.width > 0 ? { width: box.width, height: box.height } : undefined\n  }, [])\n\n  const apply = useCallback(\n    (next: CanvasView) => {\n      const measured = { ...next, frame: measure() }\n      setView(measured)\n      onViewChange?.(measured)\n    },\n    [measure, onViewChange],\n  )\n\n  /**\n   * Zooms about a fixed point in FRAME coordinates.\n   *\n   * The arithmetic is what makes the pointer stay on the thing it is over:\n   * the content point under the cursor must land back under the cursor, so the\n   * offset moves by the difference the scale change opened up. Without it, a\n   * zoom drifts toward the origin and a reader chases the node they were\n   * looking at.\n   */\n  const zoomAbout = useCallback(\n    (factor: number, originX?: number, originY?: number) => {\n      const box = frame.current?.getBoundingClientRect()\n      const cx = originX ?? (box ? box.width / 2 : 0)\n      const cy = originY ?? (box ? box.height / 2 : 0)\n\n      setView((current) => {\n        const scale = Math.min(MAX_SCALE, Math.max(MIN_SCALE, current.scale * factor))\n        const ratio = scale / current.scale\n        const next = {\n          scale,\n          x: cx - (cx - current.x) * ratio,\n          y: cy - (cy - current.y) * ratio,\n          frame: measure(),\n        }\n        onViewChange?.(next)\n        return next\n      })\n    },\n    [measure, onViewChange],\n  )\n\n  useImperativeHandle(\n    ref,\n    () => ({\n      zoomIn: () => zoomAbout(STEP),\n      zoomOut: () => zoomAbout(1 / STEP),\n      reset: () => apply({ scale: 1, x: 0, y: 0 }),\n      centerOn: (x: number, y: number) => {\n        const box = frame.current?.getBoundingClientRect()\n        if (!box) return\n        setView((current) => {\n          const next = {\n            ...current,\n            x: box.width / 2 - x * current.scale,\n            y: box.height / 2 - y * current.scale,\n            frame: measure(),\n          }\n          onViewChange?.(next)\n          return next\n        })\n      },\n      view,\n    }),\n    [apply, measure, onViewChange, view, zoomAbout],\n  )\n\n  // Registered imperatively because React marks `wheel` passive, and a passive\n  // listener cannot call preventDefault — so the modifier-wheel zoom would also\n  // scroll the page underneath it.\n  useEffect(() => {\n    const node = frame.current\n    if (!node) return\n\n    const onWheel = (event: WheelEvent) => {\n      if (!event.ctrlKey && !event.metaKey) return\n      event.preventDefault()\n      const box = node.getBoundingClientRect()\n      zoomAbout(\n        event.deltaY < 0 ? STEP : 1 / STEP,\n        event.clientX - box.left,\n        event.clientY - box.top,\n      )\n    }\n\n    node.addEventListener('wheel', onWheel, { passive: false })\n    return () => node.removeEventListener('wheel', onWheel)\n  }, [zoomAbout])\n\n  const onPointerDown = (event: ReactPointerEvent<HTMLDivElement>) => {\n    if (event.button !== 0) return\n    drag.current = { pointer: event.pointerId, x: event.clientX - view.x, y: event.clientY - view.y }\n    event.currentTarget.setPointerCapture(event.pointerId)\n  }\n\n  const onPointerMove = (event: ReactPointerEvent<HTMLDivElement>) => {\n    const state = drag.current\n    if (!state || state.pointer !== event.pointerId) return\n    apply({ ...view, x: event.clientX - state.x, y: event.clientY - state.y })\n  }\n\n  const endDrag = (event: ReactPointerEvent<HTMLDivElement>) => {\n    if (drag.current?.pointer !== event.pointerId) return\n    drag.current = null\n    if (event.currentTarget.hasPointerCapture(event.pointerId)) {\n      event.currentTarget.releasePointerCapture(event.pointerId)\n    }\n  }\n\n  return (\n    <div\n      className={cn(\n        'relative overflow-hidden rounded-(--radius-lg) border border-(--rule) bg-(--diagram-surface)',\n        className,\n      )}\n      style={{ height }}\n    >\n      <div\n        ref={frame}\n        role=\"group\"\n        aria-label={label}\n        aria-describedby={`${uid}-hint`}\n        tabIndex={0}\n        className=\"size-full cursor-grab touch-none select-none outline-none focus-visible:ring-2 focus-visible:ring-(--ring) focus-visible:ring-inset active:cursor-grabbing\"\n        onPointerDown={onPointerDown}\n        onPointerMove={onPointerMove}\n        onPointerUp={endDrag}\n        onPointerCancel={endDrag}\n        onKeyDown={(event) => {\n          const nudge = event.shiftKey ? 80 : 24\n          switch (event.key) {\n            case '+':\n            case '=':\n              event.preventDefault()\n              zoomAbout(STEP)\n              break\n            case '-':\n              event.preventDefault()\n              zoomAbout(1 / STEP)\n              break\n            case '0':\n              event.preventDefault()\n              apply({ scale: 1, x: 0, y: 0 })\n              break\n            case 'ArrowLeft':\n              event.preventDefault()\n              apply({ ...view, x: view.x + nudge })\n              break\n            case 'ArrowRight':\n              event.preventDefault()\n              apply({ ...view, x: view.x - nudge })\n              break\n            case 'ArrowUp':\n              event.preventDefault()\n              apply({ ...view, y: view.y + nudge })\n              break\n            case 'ArrowDown':\n              event.preventDefault()\n              apply({ ...view, y: view.y - nudge })\n              break\n            default:\n              break\n          }\n        }}\n      >\n        <div\n          className=\"origin-top-left will-change-transform\"\n          style={{ transform: `translate(${view.x}px, ${view.y}px) scale(${view.scale})` }}\n          data-diagram-stage=\"\"\n        >\n          {children}\n        </div>\n      </div>\n\n      <p id={`${uid}-hint`} className=\"sr-only\">\n        Drag to pan. Plus and minus zoom, zero resets, the arrow keys pan.\n      </p>\n\n      {controls && (\n        <div className=\"absolute bottom-3 end-3 flex items-center gap-px rounded-(--radius) border border-(--rule-2) bg-(--panel-bg) p-0.5\">\n          <CanvasButton label=\"Zoom out\" onClick={() => zoomAbout(1 / STEP)}>\n            <span aria-hidden>−</span>\n          </CanvasButton>\n          <button\n            type=\"button\"\n            onClick={() => apply({ scale: 1, x: 0, y: 0 })}\n            aria-label=\"Reset the view\"\n            className=\"min-w-12 rounded-(--radius-xs) px-1.5 py-1 mono-meta text-(--ink-2) transition-colors duration-(--duration-fast) hover:bg-(--stone) hover:text-(--ink) focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-(--ring)\"\n          >\n            {Math.round(view.scale * 100)}%\n          </button>\n          <CanvasButton label=\"Zoom in\" onClick={() => zoomAbout(STEP)}>\n            <span aria-hidden>+</span>\n          </CanvasButton>\n        </div>\n      )}\n    </div>\n  )\n}\n\nfunction CanvasButton({\n  label,\n  onClick,\n  children,\n}: {\n  label: string\n  onClick: () => void\n  children: ReactNode\n}) {\n  return (\n    <button\n      type=\"button\"\n      onClick={onClick}\n      aria-label={label}\n      className=\"flex size-7 items-center justify-center rounded-(--radius-xs) font-mono text-[13px] leading-none text-(--ink-2) transition-colors duration-(--duration-fast) hover:bg-(--stone) hover:text-(--ink) focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-(--ring)\"\n    >\n      {children}\n    </button>\n  )\n}\n\nexport default DiagramCanvas\n"],"mappings":"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","names":[]}

package/dist/diagrams/DiagramExportMenu/DiagramExportMenu.d.ts

@@ -0,0 +1,106 @@
+import * as react from 'react';
+import { RefObject, ReactNode } from 'react';
+
+/** The files a figure can be taken away as. */
+type ExportFormat = 'png' | 'jpeg' | 'webp' | 'svg' | 'share-card';
+/** What came of an export, for a page that wants to say so. */
+interface ExportResult {
+    format: ExportFormat;
+    /**
+     * Whether the pipeline named by `source` finished without throwing.
+     *
+     * Read it with `source`, because the two sources can promise different
+     * amounts. `built-in` means a file was handed to the browser. `caller` means
+     * an `onExport` handler resolved — and a handler that did nothing resolves
+     * exactly like one that wrote a file, which is a thing this component cannot
+     * see and therefore does not claim.
+     */
+    ok: boolean;
+    error?: Error;
+    /** Which pipeline ran: this component's, or the caller's `onExport`. */
+    source: 'built-in' | 'caller';
+}
+interface DiagramExportMenuProps {
+    /**
+     * The `<svg>` to export, or an element containing exactly one.
+     *
+     * A ref rather than a selector, because a page can hold several figures and a
+     * selector would export whichever the document happened to reach first.
+     */
+    targetRef: RefObject<HTMLElement | SVGSVGElement | null>;
+    /** Names the file, and is printed on the share card. */
+    title: string;
+    /** Replaces the trigger. */
+    trigger?: ReactNode;
+    className?: string;
+    /**
+     * Runs instead of the built-in export — for a caller with its own pipeline.
+     *
+     * Taking it turns everything below into a no-op, INCLUDING the part that
+     * knows whether a file was produced: a result from this path reports
+     * `source: 'caller'` and an `ok` that means only "your handler resolved".
+     */
+    onExport?: (format: ExportFormat) => void | Promise<void>;
+    /** Told what happened, so a page can raise a toast. */
+    onResult?: (result: ExportResult) => void;
+    /**
+     * Painted behind the artwork. Defaults to the surface the reader is looking
+     * at; `null` exports on a transparent ground.
+     *
+     * JPEG has no alpha channel, so it is flattened onto the reader's own paper
+     * whatever this says — a transparent JPEG is a black one.
+     */
+    background?: string | null;
+}
+/**
+ * Taking the figure off the page: five files, one menu.
+ *
+ * WHY THE MENU DOES THE WORK rather than handing back a format: every one of
+ * these exports is the same six steps — find the `<svg>`, walk it with
+ * `getComputedStyle` to bake the custom properties into real colours,
+ * serialise, rasterise, name the file, hand it to the browser — and only the
+ * last two differ between them. A menu that emitted `'png'` and left the caller
+ * to do the rest would be a menu that every consumer reimplements, badly, and
+ * the interesting half (a serialised SVG resolves `var(--ink)` to nothing and
+ * comes out invisible) is exactly the half a caller would not know to write.
+ *
+ * `onExport` is still there for a page with its own pipeline — a server-side
+ * renderer, a different frame size — and taking it turns everything below into
+ * a no-op, which is why a result from that path says `source: 'caller'`: this
+ * component cannot see whether the handler produced a file, so it does not
+ * report that it did.
+ *
+ * What each format actually is, stated rather than implied.
+ *
+ * **SVG** is the artwork with resolved colours. It is editable and it is the
+ * only lossless one, but it carries no web fonts: a machine without the family
+ * renders it in a fallback, so type metrics will differ.
+ *
+ * **The ground** is the reader's own surface unless `background` says
+ * otherwise. `background={null}` exports on transparency — for a figure being
+ * dropped onto a coloured page — except in JPEG, which has no alpha and is
+ * flattened onto paper whatever is asked for.
+ *
+ * **PNG, JPEG and WebP** are the browser's own rasteriser re-drawing that SVG
+ * at 2×. Not a screenshot — antialiasing and any effect a page stylesheet
+ * applied from OUTSIDE the `<svg>` are not in it. **JPEG has no alpha**, so it
+ * is flattened onto the resolved paper colour rather than onto black, which is
+ * what a transparent PNG becomes when a format with no transparency is asked
+ * to hold it.
+ *
+ * **The share card** is a 1200 × 630 frame with the title on it and the whole
+ * diagram letterboxed inside — never cropped. A card that cropped to fill the
+ * frame would be a picture of a different diagram.
+ */
+declare function DiagramExportMenu({ targetRef, title, trigger, className, onExport, onResult, background, }: DiagramExportMenuProps): react.JSX.Element;
+/**
+ * One figure, one format, one file.
+ *
+ * Exported so a page can wire a keyboard shortcut or its own button to exactly
+ * what the menu does, without reimplementing the six steps.
+ */
+declare function exportFigure(target: HTMLElement | SVGSVGElement | null, title: string, format: ExportFormat, options?: {
+    background?: string | null;
+}): Promise<void>;
+
+export { DiagramExportMenu, type DiagramExportMenuProps, type ExportFormat, type ExportResult, DiagramExportMenu as default, exportFigure };

package/dist/diagrams/DiagramExportMenu/DiagramExportMenu.js

@@ -0,0 +1,123 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import { cn } from "../../lib/cn.js";
+import {
+  downloadBlob,
+  exportFilename,
+  rasterize,
+  readToken,
+  serializeSvg
+} from "../../lib/svg-export.js";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger
+} from "../../components/DropdownMenu/DropdownMenu.js";
+import { Button } from "../../components/Button/Button.js";
+const SHARE_CARD = { width: 1200, height: 630 };
+const ITEMS = [
+  { group: "Image", format: "png", title: "PNG", hint: "Lossless, 2\xD7 for retina" },
+  { group: "Image", format: "jpeg", title: "JPEG", hint: "Compact, flattened onto paper" },
+  { group: "Image", format: "webp", title: "WebP", hint: "Smaller, modern browsers" },
+  { group: "Vector", format: "svg", title: "SVG", hint: "Editable, colours resolved" },
+  { group: "Share", format: "share-card", title: "Share card", hint: "1200 \xD7 630 PNG" }
+];
+function DiagramExportMenu({
+  targetRef,
+  title,
+  trigger,
+  className,
+  onExport,
+  onResult,
+  background
+}) {
+  const [busy, setBusy] = useState(null);
+  async function run(format) {
+    const source = onExport ? "caller" : "built-in";
+    setBusy(format);
+    try {
+      if (onExport) {
+        await onExport(format);
+      } else {
+        await exportFigure(targetRef.current, title, format, { background });
+      }
+      onResult?.({ format, ok: true, source });
+    } catch (cause) {
+      onResult?.({ format, ok: false, error: cause, source });
+    } finally {
+      setBusy(null);
+    }
+  }
+  const groups = [...new Set(ITEMS.map((item) => item.group))];
+  return /* @__PURE__ */ jsxs(DropdownMenu, { children: [
+    /* @__PURE__ */ jsx(DropdownMenuTrigger, { asChild: true, children: trigger ?? /* @__PURE__ */ jsx(Button, { size: "sm", variant: "secondary", className, children: "Export" }) }),
+    /* @__PURE__ */ jsx(DropdownMenuContent, { align: "end", className: "w-64", children: groups.map((group, index) => /* @__PURE__ */ jsxs("div", { children: [
+      index > 0 && /* @__PURE__ */ jsx(DropdownMenuSeparator, {}),
+      /* @__PURE__ */ jsx(DropdownMenuLabel, { children: group }),
+      ITEMS.filter((item) => item.group === group).map((item) => /* @__PURE__ */ jsxs(
+        DropdownMenuItem,
+        {
+          disabled: busy !== null,
+          onSelect: () => void run(item.format),
+          className: cn("flex-col items-start gap-0.5"),
+          children: [
+            /* @__PURE__ */ jsxs("span", { className: "text-[13px] leading-tight text-(--ink)", children: [
+              item.title,
+              busy === item.format && " \u2026"
+            ] }),
+            /* @__PURE__ */ jsx("span", { className: "mono-meta text-(--ink-3-aa)", children: item.hint })
+          ]
+        },
+        item.format
+      ))
+    ] }, group)) })
+  ] });
+}
+async function exportFigure(target, title, format, options = {}) {
+  const svg = findArtwork(target);
+  if (!svg) throw new Error("exportFigure: found no <svg> to export inside the given element");
+  const paper = readToken(svg, "--diagram-surface", "#ffffff");
+  const ink = readToken(svg, "--ink", "#101010");
+  const font = getComputedStyle(svg).fontFamily || "sans-serif";
+  const plate = options.background === null ? void 0 : options.background ?? paper;
+  if (format === "share-card") {
+    const markup2 = serializeSvg(svg, {
+      padding: 56,
+      background: plate,
+      title,
+      titleColor: ink,
+      titleFont: font,
+      frame: SHARE_CARD
+    });
+    const blob2 = await rasterize(markup2, "png", { scale: 1 });
+    downloadBlob(blob2, exportFilename(title, "png", "share-card"));
+    return;
+  }
+  const markup = serializeSvg(svg, { padding: 20, background: plate });
+  if (format === "svg") {
+    downloadBlob(new Blob([markup], { type: "image/svg+xml;charset=utf-8" }), exportFilename(title, "svg"));
+    return;
+  }
+  const blob = await rasterize(markup, format, {
+    scale: 2,
+    // JPEG has no alpha channel, so an unflattened export lands on black.
+    background: format === "jpeg" ? paper : void 0
+  });
+  downloadBlob(blob, exportFilename(title, format));
+}
+function findArtwork(element) {
+  if (!element) return null;
+  if (element.tagName.toLowerCase() === "svg") return element;
+  return element.querySelector("svg[data-diagram-artwork]") ?? element.querySelector("svg");
+}
+var DiagramExportMenu_default = DiagramExportMenu;
+export {
+  DiagramExportMenu,
+  DiagramExportMenu_default as default,
+  exportFigure
+};
+//# sourceMappingURL=DiagramExportMenu.js.map

package/dist/diagrams/DiagramExportMenu/DiagramExportMenu.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/diagrams/DiagramExportMenu/DiagramExportMenu.tsx"],"sourcesContent":["'use client'\n\nimport { useState, type ReactNode, type RefObject } from 'react'\nimport { cn } from '../../lib/cn'\nimport {\n  downloadBlob,\n  exportFilename,\n  rasterize,\n  readToken,\n  serializeSvg,\n} from '../../lib/svg-export'\nimport {\n  DropdownMenu,\n  DropdownMenuContent,\n  DropdownMenuItem,\n  DropdownMenuLabel,\n  DropdownMenuSeparator,\n  DropdownMenuTrigger,\n} from '../../components/DropdownMenu/DropdownMenu'\nimport { Button } from '../../components/Button/Button'\n\n/** The files a figure can be taken away as. */\nexport type ExportFormat = 'png' | 'jpeg' | 'webp' | 'svg' | 'share-card'\n\n/** What came of an export, for a page that wants to say so. */\nexport interface ExportResult {\n  format: ExportFormat\n  /**\n   * Whether the pipeline named by `source` finished without throwing.\n   *\n   * Read it with `source`, because the two sources can promise different\n   * amounts. `built-in` means a file was handed to the browser. `caller` means\n   * an `onExport` handler resolved — and a handler that did nothing resolves\n   * exactly like one that wrote a file, which is a thing this component cannot\n   * see and therefore does not claim.\n   */\n  ok: boolean\n  error?: Error\n  /** Which pipeline ran: this component's, or the caller's `onExport`. */\n  source: 'built-in' | 'caller'\n}\n\n/** A share card is a fixed frame, because the surfaces that consume one are. */\nconst SHARE_CARD = { width: 1200, height: 630 } as const\n\nconst ITEMS: { format: ExportFormat; title: string; hint: string; group: string }[] = [\n  { group: 'Image', format: 'png', title: 'PNG', hint: 'Lossless, 2× for retina' },\n  { group: 'Image', format: 'jpeg', title: 'JPEG', hint: 'Compact, flattened onto paper' },\n  { group: 'Image', format: 'webp', title: 'WebP', hint: 'Smaller, modern browsers' },\n  { group: 'Vector', format: 'svg', title: 'SVG', hint: 'Editable, colours resolved' },\n  { group: 'Share', format: 'share-card', title: 'Share card', hint: '1200 × 630 PNG' },\n]\n\nexport interface DiagramExportMenuProps {\n  /**\n   * The `<svg>` to export, or an element containing exactly one.\n   *\n   * A ref rather than a selector, because a page can hold several figures and a\n   * selector would export whichever the document happened to reach first.\n   */\n  targetRef: RefObject<HTMLElement | SVGSVGElement | null>\n  /** Names the file, and is printed on the share card. */\n  title: string\n  /** Replaces the trigger. */\n  trigger?: ReactNode\n  className?: string\n  /**\n   * Runs instead of the built-in export — for a caller with its own pipeline.\n   *\n   * Taking it turns everything below into a no-op, INCLUDING the part that\n   * knows whether a file was produced: a result from this path reports\n   * `source: 'caller'` and an `ok` that means only \"your handler resolved\".\n   */\n  onExport?: (format: ExportFormat) => void | Promise<void>\n  /** Told what happened, so a page can raise a toast. */\n  onResult?: (result: ExportResult) => void\n  /**\n   * Painted behind the artwork. Defaults to the surface the reader is looking\n   * at; `null` exports on a transparent ground.\n   *\n   * JPEG has no alpha channel, so it is flattened onto the reader's own paper\n   * whatever this says — a transparent JPEG is a black one.\n   */\n  background?: string | null\n}\n\n/**\n * Taking the figure off the page: five files, one menu.\n *\n * WHY THE MENU DOES THE WORK rather than handing back a format: every one of\n * these exports is the same six steps — find the `<svg>`, walk it with\n * `getComputedStyle` to bake the custom properties into real colours,\n * serialise, rasterise, name the file, hand it to the browser — and only the\n * last two differ between them. A menu that emitted `'png'` and left the caller\n * to do the rest would be a menu that every consumer reimplements, badly, and\n * the interesting half (a serialised SVG resolves `var(--ink)` to nothing and\n * comes out invisible) is exactly the half a caller would not know to write.\n *\n * `onExport` is still there for a page with its own pipeline — a server-side\n * renderer, a different frame size — and taking it turns everything below into\n * a no-op, which is why a result from that path says `source: 'caller'`: this\n * component cannot see whether the handler produced a file, so it does not\n * report that it did.\n *\n * What each format actually is, stated rather than implied.\n *\n * **SVG** is the artwork with resolved colours. It is editable and it is the\n * only lossless one, but it carries no web fonts: a machine without the family\n * renders it in a fallback, so type metrics will differ.\n *\n * **The ground** is the reader's own surface unless `background` says\n * otherwise. `background={null}` exports on transparency — for a figure being\n * dropped onto a coloured page — except in JPEG, which has no alpha and is\n * flattened onto paper whatever is asked for.\n *\n * **PNG, JPEG and WebP** are the browser's own rasteriser re-drawing that SVG\n * at 2×. Not a screenshot — antialiasing and any effect a page stylesheet\n * applied from OUTSIDE the `<svg>` are not in it. **JPEG has no alpha**, so it\n * is flattened onto the resolved paper colour rather than onto black, which is\n * what a transparent PNG becomes when a format with no transparency is asked\n * to hold it.\n *\n * **The share card** is a 1200 × 630 frame with the title on it and the whole\n * diagram letterboxed inside — never cropped. A card that cropped to fill the\n * frame would be a picture of a different diagram.\n */\nexport function DiagramExportMenu({\n  targetRef,\n  title,\n  trigger,\n  className,\n  onExport,\n  onResult,\n  background,\n}: DiagramExportMenuProps) {\n  const [busy, setBusy] = useState<ExportFormat | null>(null)\n\n  async function run(format: ExportFormat) {\n    const source = onExport ? 'caller' : 'built-in'\n    setBusy(format)\n    try {\n      if (onExport) {\n        await onExport(format)\n      } else {\n        await exportFigure(targetRef.current, title, format, { background })\n      }\n      // `ok` says the pipeline finished, and `source` says whose. Reporting a\n      // bare success for a handler that may have done nothing was this menu\n      // claiming to know something only the caller can.\n      onResult?.({ format, ok: true, source })\n    } catch (cause) {\n      // Never swallowed: a download is something the reader just asked for, and\n      // a click that quietly does nothing is indistinguishable from a broken\n      // button. The caller gets the error to put in front of them.\n      onResult?.({ format, ok: false, error: cause as Error, source })\n    } finally {\n      setBusy(null)\n    }\n  }\n\n  const groups = [...new Set(ITEMS.map((item) => item.group))]\n\n  return (\n    <DropdownMenu>\n      <DropdownMenuTrigger asChild>\n        {trigger ?? (\n          <Button size=\"sm\" variant=\"secondary\" className={className}>\n            Export\n          </Button>\n        )}\n      </DropdownMenuTrigger>\n      <DropdownMenuContent align=\"end\" className=\"w-64\">\n        {groups.map((group, index) => (\n          <div key={group}>\n            {index > 0 && <DropdownMenuSeparator />}\n            <DropdownMenuLabel>{group}</DropdownMenuLabel>\n            {/* Menu ROWS, not buttons that happen to sit inside a menu. Radix\n                gives an item roving focus, typeahead and close-on-pick; a\n                plain <button> inside a role=\"menu\" gets none of the three and\n                leaves the menu open over the file it just wrote. */}\n            {ITEMS.filter((item) => item.group === group).map((item) => (\n              <DropdownMenuItem\n                key={item.format}\n                disabled={busy !== null}\n                onSelect={() => void run(item.format)}\n                className={cn('flex-col items-start gap-0.5')}\n              >\n                <span className=\"text-[13px] leading-tight text-(--ink)\">\n                  {item.title}\n                  {busy === item.format && ' …'}\n                </span>\n                <span className=\"mono-meta text-(--ink-3-aa)\">{item.hint}</span>\n              </DropdownMenuItem>\n            ))}\n          </div>\n        ))}\n      </DropdownMenuContent>\n    </DropdownMenu>\n  )\n}\n\n/**\n * One figure, one format, one file.\n *\n * Exported so a page can wire a keyboard shortcut or its own button to exactly\n * what the menu does, without reimplementing the six steps.\n */\nexport async function exportFigure(\n  target: HTMLElement | SVGSVGElement | null,\n  title: string,\n  format: ExportFormat,\n  options: { background?: string | null } = {},\n): Promise<void> {\n  const svg = findArtwork(target)\n  if (!svg) throw new Error('exportFigure: found no <svg> to export inside the given element')\n\n  // Read against the LIVE element, so the file comes out in whichever theme the\n  // reader is looking at rather than in whichever one the code assumed.\n  const paper = readToken(svg, '--diagram-surface', '#ffffff')\n  const ink = readToken(svg, '--ink', '#101010')\n  const font = getComputedStyle(svg).fontFamily || 'sans-serif'\n\n  // `null` is a request, not a missing value: a figure dropped onto a coloured\n  // page wants the page's own ground behind it, and a plate painted in every\n  // format meant no export could ever give it one.\n  const plate = options.background === null ? undefined : (options.background ?? paper)\n\n  if (format === 'share-card') {\n    const markup = serializeSvg(svg, {\n      padding: 56,\n      background: plate,\n      title,\n      titleColor: ink,\n      titleFont: font,\n      frame: SHARE_CARD,\n    })\n    const blob = await rasterize(markup, 'png', { scale: 1 })\n    downloadBlob(blob, exportFilename(title, 'png', 'share-card'))\n    return\n  }\n\n  const markup = serializeSvg(svg, { padding: 20, background: plate })\n\n  if (format === 'svg') {\n    downloadBlob(new Blob([markup], { type: 'image/svg+xml;charset=utf-8' }), exportFilename(title, 'svg'))\n    return\n  }\n\n  const blob = await rasterize(markup, format, {\n    scale: 2,\n    // JPEG has no alpha channel, so an unflattened export lands on black.\n    background: format === 'jpeg' ? paper : undefined,\n  })\n  downloadBlob(blob, exportFilename(title, format))\n}\n\n/**\n * The figure's own `<svg>`, not the first one in the subtree.\n *\n * The distinction is load-bearing: a toolbar sits inside the same wrapper and\n * every icon in it is an `<svg>`. Looking for the artwork marker first is what\n * stops an export of a diagram from being a picture of a chevron.\n */\nfunction findArtwork(element: HTMLElement | SVGSVGElement | null): SVGSVGElement | null {\n  if (!element) return null\n  if (element.tagName.toLowerCase() === 'svg') return element as SVGSVGElement\n  return (\n    element.querySelector<SVGSVGElement>('svg[data-diagram-artwork]') ??\n    element.querySelector<SVGSVGElement>('svg')\n  )\n}\n\nexport default DiagramExportMenu\n"],"mappings":"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","names":["markup","blob"]}

package/dist/diagrams/DiagramInspector/DiagramInspector.d.ts

@@ -0,0 +1,70 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+/** One fact about the selected thing: a short label and its value. */
+interface InspectorFact {
+    label: string;
+    value: ReactNode;
+    /** Sets the value in mono — an id, a path, a version, a port. */
+    mono?: boolean;
+}
+/** A relationship the selected thing takes part in. */
+interface InspectorLink {
+    id?: string;
+    /** Which way it runs, relative to the selected node. */
+    direction: 'in' | 'out';
+    label: string;
+    /** What sits at the other end. */
+    peer: string;
+    onSelect?: () => void;
+}
+interface DiagramInspectorProps {
+    /** The kicker over the title — what KIND of thing this panel is showing. */
+    eyebrow?: string;
+    title: string;
+    description?: ReactNode;
+    facts?: InspectorFact[];
+    links?: InspectorLink[];
+    /** Buttons under the facts — copy a link, open the source. */
+    actions?: ReactNode;
+    onClose?: () => void;
+    className?: string;
+    /** Renders as a floating panel over the surface rather than in the flow. */
+    floating?: boolean;
+}
+/**
+ * What the reader just picked, written out.
+ *
+ * A diagram can hold about eight words per node before it stops being a diagram
+ * and starts being a document with lines drawn on it. Everything past those
+ * eight — the port, the owning team, the file it was read out of, the six
+ * relationships it takes part in — belongs beside the picture rather than
+ * inside it, and this is that place.
+ *
+ * NOT A DIALOG, and that is deliberate. An inspector is a REGION that changes
+ * with the selection, not a modal. Giving it `role="dialog"` would trap focus
+ * and demand dismissal for something the reader never opened — they clicked a
+ * node, and the panel followed. So it is a labelled region with
+ * `aria-live="polite"`, which is what makes a screen reader announce the new
+ * selection without stealing the cursor from whatever the reader was doing.
+ *
+ * The relationships are real buttons when they carry `onSelect`, which is how
+ * the diagram becomes navigable from the keyboard: a reader can walk the graph
+ * peer by peer without ever touching the picture.
+ *
+ * @example
+ * <DiagramInspector
+ *   eyebrow="Service"
+ *   title="API Server"
+ *   description="FastAPI, behind the load balancer."
+ *   facts={[
+ *     { label: 'Port', value: '8000', mono: true },
+ *     { label: 'Id', value: 'api', mono: true },
+ *   ]}
+ *   links={[{ direction: 'out', label: 'SQL', peer: 'PostgreSQL' }]}
+ *   onClose={() => setSelected(null)}
+ * />
+ */
+declare function DiagramInspector({ eyebrow, title, description, facts, links, actions, onClose, className, floating, }: DiagramInspectorProps): react.JSX.Element;
+
+export { DiagramInspector, type DiagramInspectorProps, type InspectorFact, type InspectorLink, DiagramInspector as default };