@heyramzi/ui 1.54.1 → 2.0.0

package/src/canvas/pen/pen-session.ts

@@ -0,0 +1,177 @@
+// One pen gesture, pointer down to up, in flow coordinates. It talks to the
+// editor through a host, so the overlay stays thin.
+
+import { strokesAlong, type ErasableNode } from "./eraser.js";
+import { buildStrokeNode, type Box, type Pt } from "./geometry.js";
+import { addPenNode, removePenNode, type PenOp } from "./ops.js";
+import { buildShapeNode, buildTextNode, dragBox } from "./shapes.js";
+import { strokePath } from "./stroke-path.js";
+import {
+  PEN_DEFAULTS,
+  type PenColor,
+  type PenTool,
+  type ShapeKind,
+  type StrokePoint,
+} from "./types.js";
+
+export interface PenSettings {
+  tool: PenTool;
+  color: PenColor;
+  /** Brush width in flow units. Falls back to the tool's default. */
+  size?: number;
+  zoom: number;
+}
+
+export interface PenHost {
+  getNodes: () => readonly ErasableNode[];
+  /** Apply ops to the board. Called inside an open gesture. */
+  commit: (ops: PenOp[]) => void;
+  /** Open an undo transaction and hand back its commit. */
+  startGesture: () => () => void;
+  /** A text node was dropped. The editor opens it for typing. */
+  onTextPlaced?: (nodeId: string) => void;
+  onPreview?: (preview: PenPreview | null) => void;
+}
+
+/** What the overlay draws while the pointer is down, in flow coordinates. */
+export type PenPreview =
+  | { kind: "stroke"; d: string; color: PenColor; tool: "pen" | "highlighter" }
+  | { kind: "shape"; shape: ShapeKind; box: Box; color: PenColor }
+  | { kind: "eraser"; at: Pt; radius: number };
+
+const ERASER_RADIUS = 10;
+/** Samples closer than this, in screen pixels, add nothing to a stroke. */
+const MIN_SAMPLE = 1;
+
+function isShapeTool(tool: PenTool): tool is ShapeKind {
+  return tool === "rectangle" || tool === "ellipse" || tool === "diamond";
+}
+
+export function createPenSession(host: PenHost, getSettings: () => PenSettings) {
+  let endGesture: (() => void) | null = null;
+  let start: Pt | null = null;
+  let last: Pt | null = null;
+  let samples: StrokePoint[] = [];
+  const erased = new Set<string>();
+
+  function settingsNow() {
+    const settings = getSettings();
+    const fallback =
+      settings.tool === "highlighter" ? PEN_DEFAULTS.highlighter.size : PEN_DEFAULTS.pen.size;
+    return { ...settings, size: settings.size ?? fallback };
+  }
+
+  function reset() {
+    endGesture = null;
+    start = null;
+    last = null;
+    samples = [];
+    erased.clear();
+    host.onPreview?.(null);
+  }
+
+  function erase(from: Pt, to: Pt, radius: number) {
+    const remaining = host.getNodes().filter((node) => !erased.has(node.id));
+    const ids = strokesAlong(remaining, from, to, radius);
+    if (ids.length === 0) return;
+    for (const id of ids) erased.add(id);
+    host.commit(ids.map(removePenNode));
+  }
+
+  function placeText(at: Pt, color: PenColor) {
+    const op = addPenNode(buildTextNode(at, { color }));
+    host.commit([op]);
+    if (op.kind === "addNode" && op.node.id) host.onTextPlaced?.(op.node.id);
+  }
+
+  function sampleOf(at: Pt, pressure?: number): StrokePoint {
+    return pressure === undefined ? [at.x, at.y] : [at.x, at.y, pressure];
+  }
+
+  function previewStroke(pointerDown: boolean) {
+    const { tool, color, size } = settingsNow();
+    if (tool !== "pen" && tool !== "highlighter") return;
+    const hasPressure = samples.some((point) => point[2] !== undefined);
+    const d = strokePath(samples, { size, tool, simulatePressure: !hasPressure }, !pointerDown);
+    host.onPreview?.({ kind: "stroke", d, color, tool });
+  }
+
+  return {
+    /** True while a gesture is open, so the overlay knows to keep capturing. */
+    get active() {
+      return start !== null;
+    },
+
+    down(at: Pt, pressure?: number) {
+      if (start) return;
+      const { tool, color, zoom } = settingsNow();
+
+      if (tool === "text") {
+        placeText(at, color);
+        return;
+      }
+
+      endGesture = host.startGesture();
+      start = at;
+      last = at;
+      if (tool === "eraser") {
+        const radius = ERASER_RADIUS / zoom;
+        host.onPreview?.({ kind: "eraser", at, radius });
+        erase(at, at, radius);
+        return;
+      }
+      if (tool === "pen" || tool === "highlighter") {
+        samples = [sampleOf(at, pressure)];
+        previewStroke(true);
+      }
+    },
+
+    move(at: Pt, pressure?: number) {
+      if (!start || !last) return;
+      const { tool, color, zoom } = settingsNow();
+      if (tool === "eraser") {
+        const radius = ERASER_RADIUS / zoom;
+        host.onPreview?.({ kind: "eraser", at, radius });
+        erase(last, at, radius);
+        last = at;
+        return;
+      }
+      if (isShapeTool(tool)) {
+        host.onPreview?.({ kind: "shape", shape: tool, box: dragBox(start, at), color });
+        last = at;
+        return;
+      }
+      if (Math.hypot(at.x - last.x, at.y - last.y) * zoom < MIN_SAMPLE) return;
+      samples.push(sampleOf(at, pressure));
+      last = at;
+      previewStroke(true);
+    },
+
+    /** Pointer up. Writes the node, then closes the gesture so it's one undo step. */
+    up(at: Pt, options: { square?: boolean } = {}) {
+      if (!start || !endGesture) return;
+      const { tool, color, size, zoom } = settingsNow();
+      const close = endGesture;
+      try {
+        if (tool === "pen" || tool === "highlighter") {
+          const node = buildStrokeNode(samples, { color, size, tool, zoom });
+          if (node) host.commit([addPenNode(node)]);
+        } else if (isShapeTool(tool)) {
+          const box = dragBox(start, at, options.square);
+          host.commit([addPenNode(buildShapeNode(tool, box, { color }))]);
+        }
+      } finally {
+        close();
+        reset();
+      }
+    },
+
+    /** Escape or a lost pointer. Whatever the eraser already removed stays removed. */
+    cancel() {
+      if (!endGesture) return;
+      const close = endGesture;
+      close();
+      reset();
+    },
+  };
+}

package/src/canvas/pen/pen.css

@@ -0,0 +1,149 @@
+/* Pen colour tokens, light by default and lifted on a dark canvas. Values mirror colors.ts. */
+.svelte-flow,
+.pen-overlay {
+  --pen-ink: #1e1e1e;
+  --pen-red: #e03131;
+  --pen-blue: #1971c2;
+  --pen-green: #2f9e44;
+  --pen-amber: #e8a33d;
+  --pen-violet: #6741d9;
+  --pen-indigo: #414fd2;
+  --pen-terra: #f0503d;
+}
+
+.dark .svelte-flow,
+.svelte-flow.dark,
+.dark .pen-overlay {
+  --pen-ink: #e9ecef;
+  --pen-red: #ff8787;
+  --pen-blue: #74c0fc;
+  --pen-green: #69db7c;
+  --pen-amber: #ffd43b;
+  --pen-violet: #b197fc;
+  --pen-indigo: #8b96ff;
+  --pen-terra: #ff8a78;
+}
+
+/* Ink is an annotation layer, above every card, selected or framed, and in the order it was drawn.
+   The three classes beat a dragging card's own z-index. */
+.svelte-flow .svelte-flow__node.svelte-flow__node-stroke,
+.svelte-flow .svelte-flow__node.svelte-flow__node-text,
+.svelte-flow .svelte-flow__node.svelte-flow__node-shape {
+  z-index: 2000 !important;
+}
+
+/* The node box of a stroke is its bounding rectangle, so only the ink catches the pointer. */
+.svelte-flow__node-stroke {
+  pointer-events: none !important;
+}
+
+/* A text takes arrows on its top and bottom, dots that show on hover like a card's. */
+.svelte-flow__handle.pen-handle {
+  width: 8px;
+  height: 8px;
+  border: 2px solid var(--color-background, #fff);
+  border-radius: 9999px;
+  background: var(--color-muted-foreground, #868e96);
+  opacity: 0;
+  transition: opacity 120ms ease-out;
+}
+
+@media (hover: hover) and (pointer: fine) {
+  .svelte-flow__node-text:hover .pen-handle {
+    opacity: 1;
+  }
+}
+
+.diagram-connecting .pen-handle {
+  opacity: 1;
+}
+
+/* A shape is an outline, so a click inside an empty one reaches the cards beneath it. */
+.svelte-flow__node-shape {
+  pointer-events: none !important;
+}
+
+.svelte-flow__node-shape .svelte-flow__resize-control {
+  pointer-events: auto;
+}
+
+/* Selected ink thickens its own line; no ring or box. `--sw` is the line's own width,
+   and a host may set `--select-stroke`. */
+.svelte-flow__node.selected .pen-line {
+  stroke-width: calc(var(--sw) * var(--select-stroke, 1.7));
+}
+
+/* The resizer's lines are hit areas, not a drawn box; its handles stay small. */
+.svelte-flow__node-shape .svelte-flow__resize-control.line {
+  border-color: transparent;
+}
+
+.svelte-flow__node-shape .svelte-flow__resize-control.handle {
+  width: 8px;
+  height: 8px;
+  border: 1.5px solid var(--pen-blue);
+  border-radius: 9999px;
+  background: var(--color-background, #fff);
+}
+
+/* The words of a pen text and a shape label, plain textarea or the host's formatted field. */
+.pen-field {
+  display: block;
+  margin: 0;
+  padding: 2px 4px;
+  border: 0;
+  border-radius: 4px;
+  outline: none;
+  background: transparent;
+  font: inherit;
+  font-weight: 500;
+  line-height: 1.4;
+  min-width: 2ch;
+}
+
+textarea.pen-field {
+  field-sizing: content;
+  resize: none;
+}
+
+/* A drawn page writes in the hand; the host may name the face, else Excalifont. */
+.pen-field.hand {
+  font-family: var(--pen-hand-font, "Excalifont", "Segoe Print", "Bradley Hand", cursive);
+  font-weight: 400;
+}
+
+.pen-field.is-text {
+  max-width: 480px;
+}
+
+.pen-field.is-text.column {
+  width: 100%;
+  max-width: none;
+  box-sizing: border-box;
+}
+
+/* Selected, the glyphs themselves get heavier in their own ink; a box round
+   free text reads as a second shape. */
+.pen-field.is-text.selected {
+  -webkit-text-stroke: 0.045em currentColor;
+}
+
+.pen-field.is-label {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  max-width: 80%;
+  text-align: center;
+  pointer-events: auto;
+}
+
+/* The host's field is as wide as its words, like the textarea it stands in for. */
+.pen-field.is-rich {
+  min-height: 1.4em;
+}
+
+.pen-field.is-rich.is-label,
+.pen-field.is-rich.is-text:not(.column) {
+  width: max-content;
+}

package/src/canvas/pen/plugin.ts

@@ -0,0 +1,139 @@
+// The pen's node kinds and ops, with no DOM, so the CLI can add strokes.
+// ui.ts adds the renderers.
+
+import { z } from "zod";
+import { CanvasOpError } from "../ops/ops.js";
+import { definePlugin, type OpState } from "../plugin.js";
+import { buildStrokeNode } from "./geometry.js";
+import { buildShapeNode, buildTextNode } from "./shapes.js";
+import {
+  PEN_COLORS,
+  SHAPE_KINDS,
+  SHAPE_NODE,
+  STROKE_NODE,
+  TEXT_NODE,
+  type PenNodeInput,
+} from "./types.js";
+
+// =========================
+// SCHEMAS
+// =========================
+
+const colorSchema = z.enum(PEN_COLORS);
+const pointSchema = z.object({ x: z.number(), y: z.number() });
+
+/** A board holds a few thousand strokes at most, and one stroke past this is a scribble pasted from a file. */
+const MAX_POINTS = 5000;
+
+const addStrokeOp = z.object({
+  kind: z.literal("addStroke"),
+  id: z.string().min(1).optional(),
+  /** Flow coordinates, x then y then an optional 0 to 1 pressure. Simplified on the way in. */
+  points: z
+    .array(z.tuple([z.number(), z.number()]).rest(z.number()))
+    .min(1)
+    .max(MAX_POINTS),
+  color: colorSchema.optional(),
+  size: z.number().positive().optional(),
+  tool: z.enum(["pen", "highlighter"]).optional(),
+});
+
+const addTextOp = z.object({
+  kind: z.literal("addText"),
+  id: z.string().min(1).optional(),
+  at: pointSchema,
+  text: z.string(),
+  color: colorSchema.optional(),
+  fontSize: z.number().positive().optional(),
+});
+
+const addShapeOp = z.object({
+  kind: z.literal("addShape"),
+  id: z.string().min(1).optional(),
+  shape: z.enum(SHAPE_KINDS),
+  box: z.object({
+    x: z.number(),
+    y: z.number(),
+    width: z.number().nonnegative(),
+    height: z.number().nonnegative(),
+  }),
+  color: colorSchema.optional(),
+  filled: z.boolean().optional(),
+  label: z.string().optional(),
+});
+
+type AddStroke = z.infer<typeof addStrokeOp>;
+type AddText = z.infer<typeof addTextOp>;
+type AddShape = z.infer<typeof addShapeOp>;
+
+// =========================
+// HANDLERS
+// =========================
+
+function appendNode(
+  state: OpState,
+  node: PenNodeInput<Record<string, unknown>>,
+  opIndex: number,
+): void {
+  const id = node.id ?? crypto.randomUUID();
+  if (state.nodes.some((existing) => existing.id === id)) {
+    throw new CanvasOpError(`Node id already exists: ${id}`, opIndex);
+  }
+  state.nodes = [...state.nodes, { ...node, id }];
+}
+
+function applyAddStroke(state: OpState, op: AddStroke, opIndex: number): void {
+  const node = buildStrokeNode(op.points, {
+    id: op.id,
+    color: op.color,
+    size: op.size,
+    tool: op.tool,
+  });
+  if (!node) throw new CanvasOpError("addStroke needs at least one point", opIndex);
+  appendNode(state, node, opIndex);
+}
+
+function applyAddText(state: OpState, op: AddText, opIndex: number): void {
+  appendNode(
+    state,
+    buildTextNode(op.at, { id: op.id, text: op.text, color: op.color, fontSize: op.fontSize }),
+    opIndex,
+  );
+}
+
+function applyAddShape(state: OpState, op: AddShape, opIndex: number): void {
+  appendNode(
+    state,
+    buildShapeNode(op.shape, op.box, {
+      id: op.id,
+      color: op.color,
+      filled: op.filled,
+      label: op.label,
+    }),
+    opIndex,
+  );
+}
+
+// =========================
+// PLUGIN
+// =========================
+
+/** No `palette` on any kind: the tool bar's pen tools create these, not the card palette. */
+export const penPlugin = definePlugin({
+  id: "pen",
+  nodes: [
+    { type: STROKE_NODE, label: "Stroke" },
+    {
+      type: TEXT_NODE,
+      label: "Text",
+      sizing: "content-sized",
+      size: { width: 120 },
+    },
+    { type: SHAPE_NODE, label: "Shape", size: { width: 160, height: 100 } },
+  ],
+  ops: [
+    { kind: "addStroke", schema: addStrokeOp, apply: applyAddStroke },
+    { kind: "addText", schema: addTextOp, apply: applyAddText },
+    { kind: "addShape", schema: addShapeOp, apply: applyAddShape },
+  ],
+});

package/src/canvas/pen/shapes.ts

@@ -0,0 +1,104 @@
+// Shape and text nodes from a drag or a click. Pure, so the CLI can reuse it.
+
+import type { Box, Pt } from "./geometry.js";
+import type { PenColor, PenNodeInput, ShapeData, ShapeKind, TextData } from "./types.js";
+import { PEN_DEFAULTS, SHAPE_NODE, TEXT_NODE } from "./types.js";
+
+/** A shape smaller than this on both sides was a click, so it gets the default size. */
+const MIN_DRAG = 6;
+const DEFAULT_SHAPE = { width: 160, height: 100 } as const;
+
+/** The box a drag from `from` to `to` covers. Shift keeps it square. */
+export function dragBox(from: Pt, to: Pt, square = false): Box {
+  let dx = to.x - from.x;
+  let dy = to.y - from.y;
+  if (square) {
+    const side = Math.max(Math.abs(dx), Math.abs(dy));
+    dx = Math.sign(dx || 1) * side;
+    dy = Math.sign(dy || 1) * side;
+  }
+  return {
+    x: Math.min(from.x, from.x + dx),
+    y: Math.min(from.y, from.y + dy),
+    width: Math.abs(dx),
+    height: Math.abs(dy),
+  };
+}
+
+export interface BuildShapeOptions {
+  color?: PenColor;
+  filled?: boolean;
+  label?: string;
+  id?: string;
+}
+
+export function buildShapeNode(
+  shape: ShapeKind,
+  box: Box,
+  options: BuildShapeOptions = {},
+): PenNodeInput<ShapeData> {
+  const click = box.width < MIN_DRAG && box.height < MIN_DRAG;
+  const width = Math.round(click ? DEFAULT_SHAPE.width : Math.max(box.width, MIN_DRAG));
+  const height = Math.round(click ? DEFAULT_SHAPE.height : Math.max(box.height, MIN_DRAG));
+  // A click centres the default shape on the cursor.
+  const x = click ? box.x - width / 2 : box.x;
+  const y = click ? box.y - height / 2 : box.y;
+  return {
+    id: options.id,
+    type: SHAPE_NODE,
+    position: { x: Math.round(x), y: Math.round(y) },
+    data: {
+      shape,
+      color: options.color ?? PEN_DEFAULTS.color,
+      strokeWidth: PEN_DEFAULTS.strokeWidth,
+      filled: options.filled ?? false,
+      label: options.label ?? "",
+    },
+    width,
+    height,
+  };
+}
+
+export function buildTextNode(
+  at: Pt,
+  options: { text?: string; color?: PenColor; fontSize?: number; id?: string } = {},
+): PenNodeInput<TextData> {
+  return {
+    id: options.id,
+    type: TEXT_NODE,
+    position: { x: Math.round(at.x), y: Math.round(at.y) },
+    data: {
+      text: options.text ?? "",
+      color: options.color ?? PEN_DEFAULTS.color,
+      fontSize: options.fontSize ?? PEN_DEFAULTS.fontSize,
+    },
+    // Text sizes itself to the words once it renders, so this is only the empty box.
+    width: 120,
+    height: Math.round((options.fontSize ?? PEN_DEFAULTS.fontSize) * 1.4),
+  };
+}
+
+/** The outline of a shape inside a width by height box, as an SVG path. */
+export function shapeOutline(
+  shape: ShapeKind,
+  width: number,
+  height: number,
+  inset: number,
+): string {
+  const left = inset;
+  const top = inset;
+  const right = Math.max(width - inset, left);
+  const bottom = Math.max(height - inset, top);
+  if (shape === "diamond") {
+    const midX = (left + right) / 2;
+    const midY = (top + bottom) / 2;
+    return `M${midX},${top} L${right},${midY} L${midX},${bottom} L${left},${midY} Z`;
+  }
+  if (shape === "ellipse") {
+    const rx = (right - left) / 2;
+    const ry = (bottom - top) / 2;
+    const cy = (top + bottom) / 2;
+    return `M${left},${cy} a${rx},${ry} 0 1,0 ${rx * 2},0 a${rx},${ry} 0 1,0 ${-rx * 2},0 Z`;
+  }
+  return `M${left},${top} H${right} V${bottom} H${left} Z`;
+}

package/src/canvas/pen/stroke-path.ts

@@ -0,0 +1,54 @@
+// A stroke's points become one SVG path through perfect-freehand. The editor,
+// the headless export and the tests all call this, so they draw the same shape.
+
+import { getStroke } from "perfect-freehand";
+import type { StrokeData, StrokePoint } from "./types.js";
+
+function average(a: number, b: number): number {
+  return (a + b) / 2;
+}
+
+/** Quadratic smoothing through the outline's midpoints, the way perfect-freehand's README does it. */
+export function outlineToPath(outline: ReadonlyArray<readonly number[]>): string {
+  if (outline.length < 4) return "";
+  const first = outline[0];
+  const second = outline[1];
+  const third = outline[2];
+  let path =
+    `M${first[0].toFixed(2)},${first[1].toFixed(2)} ` +
+    `Q${second[0].toFixed(2)},${second[1].toFixed(2)} ` +
+    `${average(second[0], third[0]).toFixed(2)},${average(second[1], third[1]).toFixed(2)} T`;
+  for (let i = 2; i < outline.length - 1; i++) {
+    const a = outline[i];
+    const b = outline[i + 1];
+    path += `${average(a[0], b[0]).toFixed(2)},${average(a[1], b[1]).toFixed(2)} `;
+  }
+  return `${path}Z`;
+}
+
+type StrokeShape = Pick<StrokeData, "size" | "tool" | "simulatePressure">;
+
+/** `last` is false while the pen is still down, so the live tip isn't tapered to a point. */
+export function strokePath(
+  points: readonly StrokePoint[],
+  shape: StrokeShape,
+  last = true,
+): string {
+  if (points.length === 0) return "";
+  const highlighter = shape.tool === "highlighter";
+  const outline = getStroke(
+    points.map((point) =>
+      point[2] === undefined ? [point[0], point[1]] : [point[0], point[1], point[2]],
+    ),
+    {
+      size: shape.size,
+      // Flat ink for the highlighter: no pressure taper, a straight sweep.
+      thinning: highlighter ? 0 : 0.55,
+      smoothing: 0.6,
+      streamline: highlighter ? 0.7 : 0.5,
+      simulatePressure: shape.simulatePressure && !highlighter,
+      last,
+    },
+  );
+  return outlineToPath(outline);
+}