@1agh/maude 1.4.5 → 1.5.0

package/apps/studio/annotations/types.ts

@@ -0,0 +1,77 @@
+/**
+ * @file       annotations/types.ts — the annotations-v2 element contract (DDR-242)
+ * @scope      apps/studio/annotations/types.ts
+ * @purpose    Type-only module: the element record, the per-type definition
+ *             interface every registry entry implements, and the geometry
+ *             context a definition computes against. React-free, DOM-free.
+ */
+
+import type { FieldSpecMap } from './fields.ts';
+
+/**
+ * A canonical element record. Always carries `id`, `type` and `index`; `parent`
+ * names a container (a section) and makes `x`/`y` (and pen points / free arrow
+ * points) RELATIVE to that container's origin. Every other key is type-specific
+ * and default-valued keys are omitted.
+ */
+export interface AnnotationElement {
+  id: string;
+  type: string;
+  parent?: string;
+  index: string;
+  [field: string]: unknown;
+}
+
+export interface Box {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/** Arrow end: bound to an element (auto-facing, or pinned to a magnet) or free. */
+export type ArrowEnd = { el: string; nx?: number; ny?: number } | { x: number; y: number };
+
+export interface ElementCaps {
+  /** Carries x/y/w/h (a card / shape / container). */
+  box: boolean;
+  rotatable: boolean;
+  resizable: boolean;
+  /** An arrow end can bind to it. */
+  bindable: boolean;
+  /** Other elements can have it as `parent` (sections). */
+  container: boolean;
+  /** Where its editable text lives: `text` field, `label` record, `label` string (section title), or none. */
+  textSlot: 'text' | 'label' | 'title' | null;
+  /** Resize keeps the aspect ratio (stickies are 1:1 at creation, not at resize). */
+  aspectLock?: boolean;
+}
+
+/**
+ * The world an element's geometry is computed in. Coordinates passed to and
+ * returned from an `ElementDef` are in the element's PARENT space; `resolve`
+ * gives another element's WORLD box + rotation (arrows need their hosts').
+ */
+export interface GeomCtx {
+  /** World-space origin of the element's parent (0,0 at top level). */
+  origin: { x: number; y: number };
+  /** World-space unrotated box + rotation of any element, or null when missing / box-less. */
+  resolve(id: string): { box: Box; rot: number; bindable: boolean } | null;
+}
+
+export interface ElementDef {
+  type: string;
+  /** Type-specific fields, in canonical key order. */
+  fields: FieldSpecMap;
+  caps: ElementCaps;
+  /** Unrotated bounds in PARENT space, or null when degenerate. */
+  bounds(el: AnnotationElement, ctx: GeomCtx): Box | null;
+  /** Hit-test a point given in PARENT space. */
+  hitTest(el: AnnotationElement, px: number, py: number, tol: number, ctx: GeomCtx): boolean;
+  /** Field patch moving the element by (dx, dy) in parent space. */
+  translate(el: AnnotationElement, dx: number, dy: number): Record<string, unknown>;
+  /** Field patch fitting the element to `box` (parent space, normalized). */
+  resize(el: AnnotationElement, box: Box, ctx: GeomCtx): Record<string, unknown>;
+  /** False when the element is too small / empty to keep (a mis-tap). */
+  meaningful(el: AnnotationElement): boolean;
+}

package/apps/studio/annotations/ui/board.ts

@@ -0,0 +1,126 @@
+/**
+ * @file       annotations/ui/board.ts — the canvas's element board (Task 26)
+ * @scope      apps/studio/annotations/ui/board.ts
+ * @purpose    DDR-242 AD8: the whiteboard UI works on v2 elements directly.
+ *             One store per canvas holds the board as last applied (the
+ *             server's state plus this tab's optimistic ops) and, during a
+ *             gesture, a PREVIEW overlay (the dragged / resized records) that
+ *             never reaches storage until the gesture commits as one op batch.
+ *
+ *             React-free; the layer reads it through `useSyncExternalStore`
+ *             (`version` changes on every change). `scene()` is the world-space
+ *             view (parents, world boxes, arrow endpoints), cached per version.
+ */
+
+import { type ApplyResult, applyOps, type Op } from '../ops.ts';
+import { Scene } from '../scene.ts';
+import type { AnnotationElement } from '../types.ts';
+
+export class BoardStore {
+  private base = new Map<string, AnnotationElement>();
+  private overlay: Map<string, AnnotationElement | null> | null = null;
+  private merged: Map<string, AnnotationElement> | null = null;
+  private sceneCache: { version: number; scene: Scene } | null = null;
+  private listeners = new Set<() => void>();
+  version = 0;
+
+  subscribe = (fn: () => void): (() => void) => {
+    this.listeners.add(fn);
+    return () => {
+      this.listeners.delete(fn);
+    };
+  };
+
+  getVersion = (): number => this.version;
+
+  private changed(): void {
+    this.version++;
+    this.merged = null;
+    for (const l of [...this.listeners]) l();
+  }
+
+  /** The board as the UI shows it: base plus any gesture preview. */
+  get elements(): ReadonlyMap<string, AnnotationElement> {
+    if (!this.overlay) return this.base;
+    if (!this.merged) {
+      const m = new Map(this.base);
+      for (const [id, el] of this.overlay) {
+        if (el) m.set(id, el);
+        else m.delete(id);
+      }
+      this.merged = m;
+    }
+    return this.merged;
+  }
+
+  /** The board without the preview — what the next commit diffs against. */
+  get committed(): ReadonlyMap<string, AnnotationElement> {
+    return this.base;
+  }
+
+  get(id: string): AnnotationElement | undefined {
+    return this.elements.get(id);
+  }
+
+  scene(): Scene {
+    if (this.sceneCache?.version !== this.version) {
+      this.sceneCache = { version: this.version, scene: new Scene(this.elements.values()) };
+    }
+    return this.sceneCache.scene;
+  }
+
+  /** Replace the board (load, a peer's change). Unchanged records keep their identity. */
+  setAll(elements: Iterable<AnnotationElement>): void {
+    const next = new Map<string, AnnotationElement>();
+    for (const el of elements) {
+      const prev = this.base.get(el.id);
+      next.set(el.id, prev && sameRecord(prev, el) ? prev : el);
+    }
+    if (next.size === this.base.size && [...next].every(([id, el]) => this.base.get(id) === el))
+      return;
+    this.base = next;
+    this.changed();
+  }
+
+  /** Apply an op batch locally (optimistic). Returns what applied and its inverse. */
+  apply(ops: readonly Op[]): ApplyResult {
+    const r = applyOps(this.base, ops);
+    if (r.touched.size) {
+      this.base = r.state;
+      this.changed();
+    }
+    return r;
+  }
+
+  /** Show `records` in place of their stored versions (null hides one) — a gesture in flight. */
+  preview(records: ReadonlyMap<string, AnnotationElement | null>): void {
+    this.overlay = new Map(records);
+    this.changed();
+  }
+
+  clearPreview(): void {
+    if (!this.overlay) return;
+    this.overlay = null;
+    this.changed();
+  }
+
+  get previewing(): boolean {
+    return this.overlay !== null;
+  }
+}
+
+function sameRecord(a: AnnotationElement, b: AnnotationElement): boolean {
+  if (a === b) return true;
+  const ka = Object.keys(a);
+  const kb = Object.keys(b);
+  if (ka.length !== kb.length) return false;
+  for (const k of ka) {
+    const x = a[k];
+    const y = b[k];
+    if (x === y) continue;
+    if (typeof x !== 'object' || typeof y !== 'object' || JSON.stringify(x) !== JSON.stringify(y)) {
+      return false;
+    }
+  }
+  return true;
+}

package/apps/studio/annotations/ui/containment.ts

@@ -0,0 +1,118 @@
+/**
+ * @file       annotations/ui/containment.ts — what an operation on a selection acts on
+ * @scope      apps/studio/annotations/ui/containment.ts
+ * @purpose    DDR-242 AD8 (Task 20). Containment is explicit — an element's
+ *             `parent` — so every operation on a section acts on its SUBTREE:
+ *             move, nudge, align, distribute, delete, copy, duplicate. One
+ *             expansion (groups, then section contents, to a fixpoint) instead
+ *             of each call site deciding for itself — the source of the
+ *             "section moved without its contents" bugs (characterization
+ *             test, known bugs).
+ *
+ *             Pure and React-free. It works on the element board (`parent`),
+ *             so a nested section's contents come along with it.
+ */
+
+import { Scene } from '../scene.ts';
+import type { AnnotationElement } from '../types.ts';
+
+export class Containment {
+  private readonly scene: Scene;
+  constructor(board: Iterable<AnnotationElement>) {
+    this.scene = new Scene(board);
+  }
+
+  /** Everything inside `id`, nested containers included (not `id` itself). */
+  contentsOf(id: string): string[] {
+    return this.scene.descendants(id).map((e) => e.id);
+  }
+
+  /** `ids` plus the full subtree of every container among them. */
+  withContents(ids: Iterable<string>): Set<string> {
+    const out = new Set<string>();
+    for (const id of ids) {
+      out.add(id);
+      for (const d of this.contentsOf(id)) out.add(d);
+    }
+    return out;
+  }
+
+  /** `ids` without those whose ancestor is also in `ids` (they ride along with it). */
+  roots(ids: Iterable<string>): string[] {
+    const set = new Set(ids);
+    return [...set].filter((id) => !this.scene.ancestors(id).some((a) => set.has(a)));
+  }
+
+  /** The container an element is drawn in, or null at top level. */
+  parentOf(id: string): string | null {
+    const el = this.scene.get(id);
+    return el ? this.scene.effectiveParent(el) : null;
+  }
+
+  /** Deepest container whose box holds the world point (the one a new section nests into). */
+  containerAt(wx: number, wy: number, exclude?: ReadonlySet<string>): string | null {
+    return this.scene.containerAt(wx, wy, exclude)?.id ?? null;
+  }
+}
+
+/**
+ * Selection → the ids an operation acts on: groups expanded, then every
+ * selected container's subtree, repeated until nothing new joins (a group
+ * member inside a section, a section inside a group).
+ */
+export function expandForOp(
+  ids: readonly string[],
+  expandGroups: (ids: readonly string[]) => readonly string[],
+  containment: Containment
+): string[] {
+  let cur = new Set(ids);
+  for (let i = 0; i < 8; i++) {
+    const next = containment.withContents(expandGroups([...cur]));
+    if (next.size === cur.size) return [...next];
+    cur = next;
+  }
+  return [...cur];
+}
+
+export interface MarqueeItem {
+  id: string;
+  box: { x: number; y: number; w: number; h: number };
+  container: boolean;
+}
+
+/**
+ * What a marquee selects. Elements are taken by TOUCH; a container only when
+ * the marquee ENCLOSES it — so a marquee drawn over a section's contents
+ * selects the contents, never the section around them (FigJam).
+ */
+export function marqueeHits(
+  items: readonly MarqueeItem[],
+  rect: { x1: number; y1: number; x2: number; y2: number }
+): string[] {
+  const xMin = Math.min(rect.x1, rect.x2);
+  const xMax = Math.max(rect.x1, rect.x2);
+  const yMin = Math.min(rect.y1, rect.y2);
+  const yMax = Math.max(rect.y1, rect.y2);
+  const hits: string[] = [];
+  for (const { id, box: b, container } of items) {
+    const hit = container
+      ? b.x >= xMin && b.x + b.w <= xMax && b.y >= yMin && b.y + b.h <= yMax
+      : b.x + b.w >= xMin && b.x <= xMax && b.y + b.h >= yMin && b.y <= yMax;
+    if (hit) hits.push(id);
+  }
+  return hits;
+}
+
+/**
+ * Where a new section goes in paint order: right ABOVE the section it is
+ * drawn inside (so it renders in front of it and adopts what sits on it), or
+ * at the very back at top level (a container under everything on it).
+ */
+export function insertSection<T extends { id: string }>(
+  list: readonly T[],
+  section: T,
+  outerId: string | null
+): T[] {
+  const at = outerId ? list.findIndex((x) => x.id === outerId) : -1;
+  return at >= 0 ? [...list.slice(0, at + 1), section, ...list.slice(at + 1)] : [section, ...list];
+}