@heyramzi/ui 1.54.2 → 2.0.0

package/src/canvas/editor/text-field-context.ts

@@ -0,0 +1,41 @@
+// The text field a host hands the pen. A plain textarea keeps the canvas MIT-clean; a host that
+// formats text provides a component, set once with the page skin.
+
+import { getContext, setContext, type Component } from "svelte";
+
+/** What the pen asks of a text field. A host component takes these and may take more. */
+export type TextFieldProps = {
+  value: string;
+  placeholder?: string;
+  ariaLabel?: string;
+  class?: string;
+  style?: string;
+  /** `live` is true while typing, so a run of keystrokes folds into one undo step. */
+  onCommit: (next: string, live: boolean) => void;
+  /** A click on the text opens it. A pen text that opens on double-click turns this off. */
+  clickToEdit?: boolean;
+  /** The field closed: focus left it or Escape. */
+  onExit?: () => void;
+  /** Shown, never opened: a locked card. */
+  readonly?: boolean;
+};
+
+/** What the pen calls on a field it holds a reference to. */
+export type TextFieldHandle = {
+  edit: (point?: { x: number; y: number }) => void | Promise<void>;
+};
+
+export type TextFieldComponent = Component<TextFieldProps, TextFieldHandle>;
+
+/** For a host that mounts a pen node with `mount(..., { context })`, as a test does. */
+export const TEXT_FIELD_KEY = Symbol("canvas-text-field");
+
+/** Call during component init. */
+export function setTextField(component: TextFieldComponent): void {
+  setContext(TEXT_FIELD_KEY, component);
+}
+
+/** The host's field, or null: the pen then draws its own textarea. */
+export function useTextField(): TextFieldComponent | null {
+  return getContext<TextFieldComponent | undefined>(TEXT_FIELD_KEY) ?? null;
+}

package/src/canvas/editor/z-order.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from "vite-plus/test";
+import type { Node } from "@xyflow/svelte";
+import { reorderStack, topLayer } from "./z-order.js";
+
+function card(id: string, extra: Partial<Node> = {}): Node {
+  return { id, type: "note", position: { x: 0, y: 0 }, data: {}, ...extra };
+}
+
+/** Ids bottom to top, as the canvas paints them. */
+function stack(nodes: Node[], parentId?: string): string[] {
+  return nodes
+    .map((node, index) => ({ node, index }))
+    .filter(({ node }) => (node.parentId ?? "") === (parentId ?? ""))
+    .sort((a, b) => (a.node.zIndex ?? 0) - (b.node.zIndex ?? 0) || a.index - b.index)
+    .map(({ node }) => node.id);
+}
+
+describe("reorderStack", () => {
+  const board = [card("a"), card("b"), card("c"), card("d")];
+
+  it("brings one card to the front and sends one to the back", () => {
+    expect(stack(reorderStack(board, new Set(["a"]), "front") ?? board)).toEqual([
+      "b",
+      "c",
+      "d",
+      "a",
+    ]);
+    expect(stack(reorderStack(board, new Set(["d"]), "back") ?? board)).toEqual([
+      "d",
+      "a",
+      "b",
+      "c",
+    ]);
+  });
+
+  it("moves one step and keeps picked cards in their order", () => {
+    const up = reorderStack(board, new Set(["a", "c"]), "forward") ?? board;
+    expect(stack(up)).toEqual(["b", "a", "d", "c"]);
+    const down = reorderStack(board, new Set(["b", "d"]), "backward") ?? board;
+    expect(stack(down)).toEqual(["b", "a", "d", "c"]);
+  });
+
+  it("returns null when nothing would change", () => {
+    expect(reorderStack(board, new Set(["d"]), "front")).toBeNull();
+    expect(reorderStack(board, new Set(["a"]), "back")).toBeNull();
+    expect(reorderStack(board, new Set(["d"]), "forward")).toBeNull();
+  });
+
+  it("writes only the layers that changed", () => {
+    const next = reorderStack(board, new Set(["a"]), "front") ?? board;
+    expect(next.find((n) => n.id === "b")?.zIndex).toBeUndefined();
+    expect(next.find((n) => n.id === "a")?.zIndex).toBe(3);
+  });
+
+  it("stacks children inside their own group and leaves ink out", () => {
+    const nodes = [
+      card("g", { type: "wrapper" }),
+      card("x", { parentId: "g" }),
+      card("y", { parentId: "g" }),
+      card("ink", { type: "stroke" }),
+    ];
+    const next = reorderStack(nodes, new Set(["x"]), "front") ?? nodes;
+    expect(stack(next, "g")).toEqual(["y", "x"]);
+    expect(next.find((n) => n.id === "g")?.zIndex).toBeUndefined();
+    expect(reorderStack(nodes, new Set(["ink"]), "front")).toBeNull();
+  });
+});
+
+describe("topLayer", () => {
+  it("is undefined until a card has been raised, then one above the top", () => {
+    expect(topLayer([card("a"), card("b")])).toBeUndefined();
+    expect(topLayer([card("a", { zIndex: 4 }), card("b")])).toBe(5);
+    expect(topLayer([card("g"), card("x", { parentId: "g", zIndex: 9 })])).toBeUndefined();
+  });
+});

package/src/canvas/editor/z-order.ts

@@ -0,0 +1,87 @@
+// Stacking order for cards: pure functions over nodes. A card's place is its `zIndex` (missing
+// is 0), and array order breaks a tie, as xyflow paints equal layers.
+
+import type { Node } from "@xyflow/svelte";
+
+export type StackMove = "forward" | "backward" | "front" | "back";
+
+/** Ink is an annotation layer pinned above every card by pen.css, so it has no place in a stack. */
+export const INK_TYPES: ReadonlySet<string> = new Set(["stroke", "text", "shape"]);
+
+type Slot = { node: Node; index: number };
+
+function layerOf(node: Node): number {
+  return typeof node.zIndex === "number" ? node.zIndex : 0;
+}
+
+/** Cards stack among their siblings: a child never leaves its group's own stack. */
+function stacks(nodes: readonly Node[]): Map<string, Slot[]> {
+  const byParent = new Map<string, Slot[]>();
+  nodes.forEach((node, index) => {
+    if (INK_TYPES.has(node.type ?? "")) return;
+    const key = node.parentId ?? "";
+    const stack = byParent.get(key) ?? [];
+    stack.push({ node, index });
+    byParent.set(key, stack);
+  });
+  for (const stack of byParent.values()) {
+    stack.sort((a, b) => layerOf(a.node) - layerOf(b.node) || a.index - b.index);
+  }
+  return byParent;
+}
+
+/** One stack after a move, bottom first. Selected cards keep their order among themselves. */
+function moved(stack: Slot[], picked: ReadonlySet<string>, move: StackMove): Slot[] {
+  const isPicked = (slot: Slot) => picked.has(slot.node.id);
+  if (move === "front") return [...stack.filter((s) => !isPicked(s)), ...stack.filter(isPicked)];
+  if (move === "back") return [...stack.filter(isPicked), ...stack.filter((s) => !isPicked(s))];
+  const next = [...stack];
+  // One step: each picked card trades places with the unpicked card beside it.
+  if (move === "forward") {
+    for (let i = next.length - 2; i >= 0; i--) {
+      if (isPicked(next[i]) && !isPicked(next[i + 1]))
+        [next[i], next[i + 1]] = [next[i + 1], next[i]];
+    }
+  } else {
+    for (let i = 1; i < next.length; i++) {
+      if (isPicked(next[i]) && !isPicked(next[i - 1]))
+        [next[i], next[i - 1]] = [next[i - 1], next[i]];
+    }
+  }
+  return next;
+}
+
+/**
+ * The board after a stacking move, or null when nothing changes. Only a stack holding a
+ * picked card is touched, and only cards whose layer changed are rewritten.
+ */
+export function reorderStack(
+  nodes: readonly Node[],
+  picked: ReadonlySet<string>,
+  move: StackMove,
+): Node[] | null {
+  const layers = new Map<string, number>();
+  for (const stack of stacks(nodes).values()) {
+    if (!stack.some((slot) => picked.has(slot.node.id))) continue;
+    const next = moved(stack, picked, move);
+    if (next.every((slot, i) => slot === stack[i])) continue;
+    next.forEach((slot, rank) => {
+      if (layerOf(slot.node) !== rank) layers.set(slot.node.id, rank);
+    });
+  }
+  if (layers.size === 0) return null;
+  return nodes.map((node) => {
+    const layer = layers.get(node.id);
+    return layer === undefined ? node : { ...node, zIndex: layer };
+  });
+}
+
+/** The layer a new card needs to land on top of its siblings, or undefined while no card has been raised. */
+export function topLayer(nodes: readonly Node[], parentId?: string): number | undefined {
+  let top = 0;
+  for (const node of nodes) {
+    if (INK_TYPES.has(node.type ?? "") || (node.parentId ?? "") !== (parentId ?? "")) continue;
+    top = Math.max(top, layerOf(node));
+  }
+  return top > 0 ? top + 1 : undefined;
+}

package/src/canvas/headless/alignment.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vite-plus/test";
+import { alignNodesHorizontally, alignNodesVertically } from "./alignment.js";
+import { makeNode } from "../test-utils.js";
+
+describe("alignNodesHorizontally", () => {
+  it("sets all nodes to the topmost Y", () => {
+    const nodes = [
+      makeNode({ id: "a", position: { x: 0, y: 100 } }),
+      makeNode({ id: "b", position: { x: 50, y: 50 } }),
+      makeNode({ id: "c", position: { x: 100, y: 200 } }),
+    ];
+    alignNodesHorizontally(nodes);
+    expect(nodes.map((n) => n.position.y)).toEqual([50, 50, 50]);
+  });
+
+  it("preserves X positions", () => {
+    const nodes = [
+      makeNode({ id: "a", position: { x: 10, y: 100 } }),
+      makeNode({ id: "b", position: { x: 200, y: 50 } }),
+    ];
+    alignNodesHorizontally(nodes);
+    expect(nodes[0].position.x).toBe(10);
+    expect(nodes[1].position.x).toBe(200);
+  });
+
+  it("does nothing for fewer than 2 nodes", () => {
+    const single = [makeNode({ id: "a", position: { x: 5, y: 99 } })];
+    alignNodesHorizontally(single);
+    expect(single[0].position.y).toBe(99);
+  });
+});
+
+describe("alignNodesVertically", () => {
+  it("sets all nodes to the leftmost X", () => {
+    const nodes = [
+      makeNode({ id: "a", position: { x: 100, y: 0 } }),
+      makeNode({ id: "b", position: { x: 50, y: 50 } }),
+      makeNode({ id: "c", position: { x: 200, y: 100 } }),
+    ];
+    alignNodesVertically(nodes);
+    expect(nodes.map((n) => n.position.x)).toEqual([50, 50, 50]);
+  });
+
+  it("preserves Y positions", () => {
+    const nodes = [
+      makeNode({ id: "a", position: { x: 100, y: 10 } }),
+      makeNode({ id: "b", position: { x: 50, y: 200 } }),
+    ];
+    alignNodesVertically(nodes);
+    expect(nodes[0].position.y).toBe(10);
+    expect(nodes[1].position.y).toBe(200);
+  });
+
+  it("does nothing for fewer than 2 nodes", () => {
+    const single = [makeNode({ id: "a", position: { x: 99, y: 5 } })];
+    alignNodesVertically(single);
+    expect(single[0].position.x).toBe(99);
+  });
+});

package/src/canvas/headless/alignment.ts

@@ -0,0 +1,23 @@
+import type { CanvasNode } from "../types.js";
+
+/**
+ * Align nodes horizontally (same row): set all to the topmost Y.
+ */
+export function alignNodesHorizontally(nodes: CanvasNode[]): void {
+  if (nodes.length < 2) return;
+  const targetY = Math.min(...nodes.map((n) => n.position.y));
+  for (const node of nodes) {
+    node.position = { ...node.position, y: targetY };
+  }
+}
+
+/**
+ * Align nodes vertically (same column): set all to the leftmost X.
+ */
+export function alignNodesVertically(nodes: CanvasNode[]): void {
+  if (nodes.length < 2) return;
+  const targetX = Math.min(...nodes.map((n) => n.position.x));
+  for (const node of nodes) {
+    node.position = { ...node.position, x: targetX };
+  }
+}