@heyramzi/ui 1.54.1 → 2.0.0

package/src/canvas/pen/PenOverlay.svelte

@@ -0,0 +1,172 @@
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import "./pen.css";
+import PreviewSvg from "../components/shared/svg/PreviewSvg.svelte";
+import type { ErasableNode } from "./eraser.js";
+import type { PenOp } from "./ops.js";
+import { createPenSession, type PenPreview } from "./pen-session.js";
+import type { PenColor, PenTool } from "./types.js";
+
+// =========================
+// TYPES
+// =========================
+interface Props {
+	tool: PenTool;
+	color?: PenColor;
+	/** Brush width in flow units. Unset takes the tool's default. */
+	size?: number;
+	/** The xyflow viewport, so screen pixels map to flow units. */
+	viewport: { x: number; y: number; zoom: number };
+	nodes: readonly ErasableNode[];
+	commit: (ops: PenOp[]) => void;
+	startGesture: () => () => void;
+	onTextPlaced?: (nodeId: string) => void;
+}
+
+// =========================
+// PROPS
+// =========================
+let {
+	tool,
+	color = "ink",
+	size,
+	viewport,
+	nodes,
+	commit,
+	startGesture,
+	onTextPlaced,
+}: Props = $props();
+
+// =========================
+// STATE
+// =========================
+let layer = $state<HTMLDivElement | null>(null);
+let preview = $state<PenPreview | null>(null);
+const session = createPenSession(
+	{
+		getNodes: () => nodes,
+		commit: (ops) => commit(ops),
+		startGesture: () => startGesture(),
+		onTextPlaced: (id) => onTextPlaced?.(id),
+		onPreview: (next) => {
+			preview = next;
+		},
+	},
+	() => ({ tool, color, size, zoom: viewport.zoom }),
+);
+
+// =========================
+// EFFECTS
+// =========================
+// Switching tool mid-stroke unmounts the overlay, and an open gesture would block undo for good.
+$effect(() => () => session.cancel());
+
+// =========================
+// FUNCTIONS
+// =========================
+function toFlow(event: { clientX: number; clientY: number }) {
+	const rect = layer?.getBoundingClientRect();
+	const left = rect?.left ?? 0;
+	const top = rect?.top ?? 0;
+	return {
+		x: (event.clientX - left - viewport.x) / viewport.zoom,
+		y: (event.clientY - top - viewport.y) / viewport.zoom,
+	};
+}
+
+function pressureOf(event: PointerEvent): number | undefined {
+	return event.pointerType === "pen" ? event.pressure : undefined;
+}
+
+function onpointerdown(event: PointerEvent) {
+	// A second finger or a right click mustn't start a stroke.
+	if (event.button !== 0 || !event.isPrimary) return;
+	layer?.setPointerCapture(event.pointerId);
+	session.down(toFlow(event), pressureOf(event));
+}
+
+function onpointermove(event: PointerEvent) {
+	if (!session.active) return;
+	// Coalesced events keep a fast pen stroke smooth between animation frames.
+	const batch = event.getCoalescedEvents?.() ?? [];
+	for (const sample of batch.length > 0 ? batch : [event]) {
+		session.move(toFlow(sample), pressureOf(sample));
+	}
+}
+
+function onpointerup(event: PointerEvent) {
+	if (!session.active) return;
+	layer?.releasePointerCapture(event.pointerId);
+	session.up(toFlow(event), { square: event.shiftKey });
+}
+
+function onkeydown(event: KeyboardEvent) {
+	if (event.key === "Escape") session.cancel();
+}
+
+// The overlay sits above xyflow's zoom pane, so a wheel or a trackpad pinch would
+// never reach it. Hand those to the pane so you can zoom and pan mid-drawing.
+function forwardWheel(node: HTMLElement) {
+	const handler = (event: WheelEvent) => {
+		const zoomPane = node.closest(".svelte-flow")?.querySelector(".svelte-flow__zoom");
+		if (!zoomPane) return;
+		event.preventDefault();
+		zoomPane.dispatchEvent(
+			new WheelEvent("wheel", {
+				deltaX: event.deltaX,
+				deltaY: event.deltaY,
+				deltaZ: event.deltaZ,
+				deltaMode: event.deltaMode,
+				clientX: event.clientX,
+				clientY: event.clientY,
+				screenX: event.screenX,
+				screenY: event.screenY,
+				ctrlKey: event.ctrlKey,
+				shiftKey: event.shiftKey,
+				altKey: event.altKey,
+				metaKey: event.metaKey,
+				bubbles: true,
+				cancelable: true,
+			}),
+		);
+	};
+	node.addEventListener("wheel", handler, { passive: false });
+	return () => node.removeEventListener("wheel", handler);
+}
+
+function cursorFor(current: PenTool): string {
+	if (current === "text") return "text";
+	return "crosshair";
+}
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<svelte:window {onkeydown} />
+
+<div
+	bind:this={layer}
+	{@attach forwardWheel}
+	class="pen-overlay"
+	style:cursor={cursorFor(tool)}
+	role="presentation"
+	{onpointerdown}
+	{onpointermove}
+	{onpointerup}
+	onpointercancel={() => session.cancel()}
+>
+	<PreviewSvg {preview} {viewport} />
+</div>
+
+<style>
+	.pen-overlay {
+		position: absolute;
+		inset: 0;
+		z-index: 5;
+		touch-action: none;
+		user-select: none;
+	}
+</style>

package/src/canvas/pen/ShapeNode.svelte

@@ -0,0 +1,64 @@
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import { NodeResizer, type NodeProps } from "@xyflow/svelte";
+import ShapeOutline from "../components/shared/svg/ShapeOutline.svelte";
+import PenField from "./PenField.svelte";
+import { getDiagramEditorContext } from "../editor/editor-context.js";
+import { useHandDrawn } from "../editor/hand-context.js";
+import { isLocked } from "../editor/lock.js";
+import "./pen.css";
+import { penColorVar } from "./colors.js";
+import { shapeOutline } from "./shapes.js";
+import type { ShapeData } from "./types.js";
+
+// =========================
+// PROPS
+// =========================
+let { id, data, selected, width, height }: NodeProps = $props();
+
+// =========================
+// STATE
+// =========================
+const editor = getDiagramEditorContext();
+const handDrawn = useHandDrawn();
+let endResize: (() => void) | null = null;
+
+// =========================
+// DERIVED
+// =========================
+let shape = $derived(data as ShapeData);
+let outline = $derived(
+	shapeOutline(shape.shape, width ?? 0, height ?? 0, shape.strokeWidth / 2),
+);
+let ink = $derived(penColorVar(shape.color));
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<NodeResizer
+	isVisible={selected}
+	minWidth={24}
+	minHeight={24}
+	onResizeStart={() => {
+		endResize = editor?.startGesture() ?? null;
+	}}
+	onResizeEnd={() => {
+		endResize?.();
+		endResize = null;
+	}}
+/>
+<ShapeOutline {shape} {outline} {ink} {width} {height} hand={handDrawn()} seed={id} />
+{#if shape.label || selected}
+	<PenField
+		variant="label"
+		value={shape.label}
+		readonly={!editor || isLocked({ data })}
+		ariaLabel="Shape label"
+		color={ink}
+		onCommit={(next, live) => editor?.patchNodeData(id, { label: next }, live ? { coalesce: true } : undefined)}
+		onExit={() => editor?.endTextEdit()}
+	/>
+{/if}

package/src/canvas/pen/TextNode.svelte

@@ -0,0 +1,97 @@
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import { Handle, Position, type NodeProps } from "@xyflow/svelte";
+import { onMount } from "svelte";
+import TextRule from "../components/shared/svg/TextRule.svelte";
+import PenField from "./PenField.svelte";
+import { getDiagramEditorContext } from "../editor/editor-context.js";
+import { useHandDrawn } from "../editor/hand-context.js";
+import { isLocked } from "../editor/lock.js";
+import { roughUnderline, seedFrom, sketchColors } from "../headless/sketch.js";
+import "./pen.css";
+import { penColorVar } from "./colors.js";
+import type { TextData } from "./types.js";
+
+// =========================
+// PROPS
+// =========================
+let { id, data, selected }: NodeProps = $props();
+
+// =========================
+// STATE
+// =========================
+const editor = getDiagramEditorContext();
+const handDrawn = useHandDrawn();
+let field = $state<ReturnType<typeof PenField>>();
+let boxWidth = $state(0);
+
+// =========================
+// DERIVED
+// =========================
+let text = $derived(data as TextData);
+let ink = $derived(penColorVar(text.color));
+let rule = $derived(
+	text.underline && boxWidth > 2
+		? roughUnderline(
+				boxWidth,
+				{ seed: seedFrom(id) + 7, colors: { ...sketchColors("ink", false), stroke: ink } },
+				{ formal: !handDrawn() },
+			)
+		: [],
+);
+
+// =========================
+// EFFECTS
+// =========================
+// The editor asks a freshly dropped text to open, so the first thing typed lands in it.
+onMount(() => editor?.registerStartEdit(id, () => void field?.edit()));
+
+// =========================
+// FUNCTIONS
+// =========================
+function onExit() {
+	editor?.endTextEdit();
+	// A click that typed nothing leaves no empty node behind.
+	if (editor && text.text.trim() === "") editor.removeNode(id);
+}
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<Handle type="target" position={Position.Top} class="pen-handle" />
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<div
+	class="pen-text-box"
+	class:column={text.fixedWidth}
+	bind:clientWidth={boxWidth}
+	ondblclick={(event) => field?.edit({ x: event.clientX, y: event.clientY })}
+>
+	<PenField
+		bind:this={field}
+		variant="text"
+		value={text.text}
+		readonly={!editor || isLocked({ data })}
+		ariaLabel="Text"
+		{selected}
+		color={ink}
+		fontSize={text.fontSize}
+		fontWeight={text.fontWeight === "bold" ? 700 : undefined}
+		center={text.align === "center"}
+		column={text.fixedWidth}
+		onCommit={(next, live) => editor?.patchNodeData(id, { text: next }, live ? { coalesce: true } : undefined)}
+		{onExit}
+	/>
+	{#if rule.length > 0}
+		<TextRule {rule} {ink} width={boxWidth} />
+	{/if}
+</div>
+<Handle type="source" position={Position.Bottom} class="pen-handle" />
+
+<style>
+	.pen-text-box.column {
+		width: 100%;
+	}
+</style>

package/src/canvas/pen/colors.ts

@@ -0,0 +1,28 @@
+// Pen colours as CSS variables. pen.css gives each variable a light and a dark
+// value, and a hex fallback keeps the node readable when that file isn't loaded.
+
+import type { PenColor } from "./types.js";
+
+export const PEN_HEX: Record<PenColor, { light: string; dark: string }> = {
+  ink: { light: "#1e1e1e", dark: "#e9ecef" },
+  red: { light: "#e03131", dark: "#ff8787" },
+  blue: { light: "#1971c2", dark: "#74c0fc" },
+  green: { light: "#2f9e44", dark: "#69db7c" },
+  amber: { light: "#e8a33d", dark: "#ffd43b" },
+  violet: { light: "#6741d9", dark: "#b197fc" },
+  // The brand pair the email lesson figures are drawn in (headless/sketch.ts PALETTE).
+  indigo: { light: "#414fd2", dark: "#8b96ff" },
+  terra: { light: "#f0503d", dark: "#ff8a78" },
+};
+
+export function penColorVar(color: string): string {
+  const known = color in PEN_HEX ? (color as PenColor) : "ink";
+  return `var(--pen-${known}, ${PEN_HEX[known].light})`;
+}
+
+/** The `:root` block pen.css carries, built from the table so the two can't drift. */
+export function penCssTokens(mode: "light" | "dark"): string {
+  return (Object.keys(PEN_HEX) as PenColor[])
+    .map((name) => `--pen-${name}: ${PEN_HEX[name][mode]};`)
+    .join(" ");
+}

package/src/canvas/pen/eraser.ts

@@ -0,0 +1,46 @@
+// The eraser hits whole strokes only, so a swipe across a big shape never wipes it.
+
+import { distanceToStroke, type Pt } from "./geometry.js";
+import { STROKE_NODE, type StrokeData } from "./types.js";
+
+export interface ErasableNode {
+  id: string;
+  type?: string;
+  position: Pt;
+  data: Record<string, unknown>;
+}
+
+function isStrokeData(data: Record<string, unknown>): data is StrokeData {
+  return Array.isArray(data.points) && typeof data.size === "number";
+}
+
+/** Ids of the strokes whose line passes within `radius` of `at`, a flow-space point. */
+export function strokesUnder(nodes: readonly ErasableNode[], at: Pt, radius: number): string[] {
+  const hits: string[] = [];
+  for (const node of nodes) {
+    if (node.type !== STROKE_NODE || !isStrokeData(node.data)) continue;
+    const local = { x: at.x - node.position.x, y: at.y - node.position.y };
+    if (distanceToStroke(node.data.points, local) <= radius + node.data.size / 2) {
+      hits.push(node.id);
+    }
+  }
+  return hits;
+}
+
+/** The same test along a swipe, so a fast pointer can't skip over a thin line. */
+export function strokesAlong(
+  nodes: readonly ErasableNode[],
+  from: Pt,
+  to: Pt,
+  radius: number,
+): string[] {
+  const length = Math.hypot(to.x - from.x, to.y - from.y);
+  const steps = Math.max(1, Math.ceil(length / Math.max(radius / 2, 1)));
+  const hits = new Set<string>();
+  for (let i = 0; i <= steps; i++) {
+    const t = i / steps;
+    const at = { x: from.x + (to.x - from.x) * t, y: from.y + (to.y - from.y) * t };
+    for (const id of strokesUnder(nodes, at, radius)) hits.add(id);
+  }
+  return [...hits];
+}

package/src/canvas/pen/geometry.ts

@@ -0,0 +1,148 @@
+// Stroke geometry with no DOM and no xyflow, so it runs headless.
+
+import type {
+  PenColor,
+  PenNodeInput,
+  StrokeData,
+  StrokePoint,
+  StrokeSample,
+} from "./types.js";
+import { PEN_DEFAULTS, STROKE_NODE } from "./types.js";
+
+export interface Pt {
+  x: number;
+  y: number;
+}
+
+export interface Box {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** How far, in screen pixels, a saved stroke may stray from what was drawn. */
+const SIMPLIFY_TOLERANCE = 0.6;
+
+function round(value: number, places: number): number {
+  const factor = 10 ** places;
+  return Math.round(value * factor) / factor;
+}
+
+/** Distance from p to the segment a-b. */
+export function distanceToSegment(p: Pt, a: Pt, b: Pt): number {
+  const dx = b.x - a.x;
+  const dy = b.y - a.y;
+  const lengthSquared = dx * dx + dy * dy;
+  if (lengthSquared === 0) return Math.hypot(p.x - a.x, p.y - a.y);
+  const t = Math.max(0, Math.min(1, ((p.x - a.x) * dx + (p.y - a.y) * dy) / lengthSquared));
+  return Math.hypot(p.x - (a.x + t * dx), p.y - (a.y + t * dy));
+}
+
+/**
+ * Ramer-Douglas-Peucker over x and y, run on an index stack so a long scribble
+ * can't overflow the call stack. The first and last samples always stay.
+ */
+export function simplifyPoints<P extends StrokeSample>(
+  points: readonly P[],
+  tolerance: number,
+): P[] {
+  if (points.length <= 2) return [...points];
+  const keep = new Uint8Array(points.length);
+  keep[0] = 1;
+  keep[points.length - 1] = 1;
+  const stack: Array<[number, number]> = [[0, points.length - 1]];
+  while (stack.length > 0) {
+    const [start, end] = stack.pop() as [number, number];
+    const a = { x: points[start][0], y: points[start][1] };
+    const b = { x: points[end][0], y: points[end][1] };
+    let farthest = -1;
+    let farthestDistance = tolerance;
+    for (let i = start + 1; i < end; i++) {
+      const distance = distanceToSegment({ x: points[i][0], y: points[i][1] }, a, b);
+      if (distance > farthestDistance) {
+        farthest = i;
+        farthestDistance = distance;
+      }
+    }
+    if (farthest === -1) continue;
+    keep[farthest] = 1;
+    stack.push([start, farthest], [farthest, end]);
+  }
+  return points.filter((_, i) => keep[i] === 1);
+}
+
+export function pointsBounds(points: readonly StrokeSample[]): Box {
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  for (const [x, y] of points) {
+    minX = Math.min(minX, x);
+    minY = Math.min(minY, y);
+    maxX = Math.max(maxX, x);
+    maxY = Math.max(maxY, y);
+  }
+  return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
+}
+
+export interface BuildStrokeOptions {
+  color?: PenColor;
+  size?: number;
+  tool?: "pen" | "highlighter";
+  /** Flow units per screen pixel is 1 / zoom, so a zoomed-out stroke keeps its detail. */
+  zoom?: number;
+  id?: string;
+}
+
+/** Points are saved relative to the node, padded by the brush so the selection box holds the whole outline. */
+export function buildStrokeNode(
+  samples: readonly StrokeSample[],
+  options: BuildStrokeOptions = {},
+): PenNodeInput<StrokeData> | null {
+  if (samples.length === 0) return null;
+  const tool = options.tool ?? "pen";
+  const size = options.size ?? PEN_DEFAULTS[tool].size;
+  const tolerance = SIMPLIFY_TOLERANCE / Math.max(options.zoom ?? 1, 0.1);
+  // A tap is one sample. Doubling it gives the outline a segment, so it draws as a dot.
+  const source = samples.length === 1 ? [samples[0], samples[0]] : samples;
+  const simplified = simplifyPoints(source, tolerance);
+  const hasPressure = simplified.some((point) => point[2] !== undefined);
+
+  const pad = Math.ceil(size / 2) + 2;
+  const box = pointsBounds(simplified);
+  const origin = { x: box.x - pad, y: box.y - pad };
+  const points: StrokePoint[] = simplified.map(([x, y, pressure]) => {
+    const px = round(x - origin.x, 1);
+    const py = round(y - origin.y, 1);
+    return hasPressure ? [px, py, round(pressure ?? 0.5, 2)] : [px, py];
+  });
+
+  return {
+    id: options.id,
+    type: STROKE_NODE,
+    position: { x: round(origin.x, 1), y: round(origin.y, 1) },
+    data: {
+      points,
+      color: options.color ?? PEN_DEFAULTS.color,
+      size,
+      tool,
+      simulatePressure: !hasPressure,
+    },
+    width: Math.ceil(box.width + pad * 2),
+    height: Math.ceil(box.height + pad * 2),
+  };
+}
+
+/** Smallest distance from p to the stroke's centre line, in the stroke's own coordinates. */
+export function distanceToStroke(points: readonly StrokeSample[], p: Pt): number {
+  if (points.length === 0) return Infinity;
+  if (points.length === 1) return Math.hypot(p.x - points[0][0], p.y - points[0][1]);
+  let best = Infinity;
+  for (let i = 1; i < points.length; i++) {
+    const a = { x: points[i - 1][0], y: points[i - 1][1] };
+    const b = { x: points[i][0], y: points[i][1] };
+    best = Math.min(best, distanceToSegment(p, a, b));
+  }
+  return best;
+}

package/src/canvas/pen/host-field.test.svelte

@@ -0,0 +1,13 @@
+<script lang="ts">
+// A host's text field for the PenField test: shows its value, records that it was opened.
+import type { TextFieldProps } from "../editor/text-field-context.js";
+
+let { value, readonly = false, class: klass = "" }: TextFieldProps = $props();
+let opened = $state(0);
+
+export function edit() {
+	opened++;
+}
+</script>
+
+<div data-host-field class={klass} data-readonly={readonly} data-opened={opened}>{value}</div>

package/src/canvas/pen/index.ts

@@ -0,0 +1,40 @@
+// The pen layer, server-safe. Svelte parts are in ./ui.js.
+
+export { PEN_HEX, penColorVar } from "./colors.js";
+export { strokesAlong, strokesUnder, type ErasableNode } from "./eraser.js";
+export {
+  buildStrokeNode,
+  distanceToStroke,
+  pointsBounds,
+  simplifyPoints,
+  type Box,
+  type BuildStrokeOptions,
+  type Pt,
+} from "./geometry.js";
+export { addPenNode, removePenNode, type PenOp } from "./ops.js";
+export {
+  createPenSession,
+  type PenHost,
+  type PenPreview,
+  type PenSettings,
+} from "./pen-session.js";
+export { penPlugin } from "./plugin.js";
+export { buildShapeNode, buildTextNode, dragBox, shapeOutline } from "./shapes.js";
+export { outlineToPath, strokePath } from "./stroke-path.js";
+export {
+  HIGHLIGHTER_OPACITY,
+  PEN_COLORS,
+  PEN_DEFAULTS,
+  SHAPE_KINDS,
+  SHAPE_NODE,
+  STROKE_NODE,
+  TEXT_NODE,
+  type PenColor,
+  type PenNodeInput,
+  type PenTool,
+  type ShapeData,
+  type ShapeKind,
+  type StrokeData,
+  type StrokePoint,
+  type TextData,
+} from "./types.js";

package/src/canvas/pen/ops.ts

@@ -0,0 +1,16 @@
+// The two ops the pen layer emits. They match the editor's addNode and removeNode
+// ops, so a stroke goes through applyOps like any card and the history sees it.
+
+import type { PenNodeInput } from "./types.js";
+
+export type PenOp =
+  | { kind: "addNode"; node: PenNodeInput<Record<string, unknown>> }
+  | { kind: "removeNode"; nodeId: string };
+
+export function addPenNode(node: PenNodeInput<Record<string, unknown>>): PenOp {
+  return { kind: "addNode", node: { ...node, id: node.id ?? crypto.randomUUID() } };
+}
+
+export function removePenNode(nodeId: string): PenOp {
+  return { kind: "removeNode", nodeId };
+}