@rasamjs/tools 0.0.0-stage → 0.2.0

package/src/editor/path-editor.ts

@@ -0,0 +1,224 @@
+import { Path, PathArray, PointArray } from '@rasamjs/core';
+import type { Point, Polygon, Polyline, Svg, PathCommand } from '@rasamjs/core';
+import { beginChangeGroup } from '@rasamjs/core/changes';
+import type { SnapSession } from '../snapping/types.js';
+import { assertPoint } from '../snapping/options.js';
+import type { PointSnapper } from './draw-tool.js';
+import { Surface, svg } from './surface.js';
+import { PointerDrag } from './pointer.js';
+
+export type EditablePath = Path | Polyline | Polygon;
+export interface PathHandle {
+  readonly point: Point;
+  readonly command: number;
+  readonly coordinate: number;
+  readonly control: boolean;
+}
+export interface PathEditorOptions {
+  readonly snapper: PointSnapper;
+  readonly stroke?: string;
+}
+export class PathEditor {
+  private readonly surface: Surface;
+  private node: EditablePath | null = null;
+  private observe: MutationObserver | null = null;
+  private stopNode: (() => void) | null = null;
+  private active: {
+    handle: PathHandle;
+    before: PathCommand[] | Point[];
+    serialized: string;
+    session: SnapSession | null;
+    group: ReturnType<typeof beginChangeGroup>;
+  } | null = null;
+  constructor(
+    private readonly drawing: Svg,
+    private readonly options: PathEditorOptions,
+  ) {
+    if (!options?.snapper || typeof options.snapper.begin !== 'function')
+      throw new TypeError('Path editing needs a point snapper');
+    if (
+      options.stroke !== undefined &&
+      (typeof options.stroke !== 'string' || !options.stroke.trim())
+    )
+      throw new TypeError('Path stroke must be nonempty');
+    this.options = { ...options };
+    this.surface = new Surface(drawing, 'rasam-path-editor', () => this.render());
+    this.surface.element.style.zIndex = '20';
+    new PointerDrag(this.surface, {
+      start: (event) => {
+        const handle = (event.target as Element).closest('[data-path-handle]');
+        if (!handle) return false;
+        this.begin(Number(handle.getAttribute('data-path-handle')));
+        return true;
+      },
+      move: (event) =>
+        this.move({ x: event.clientX, y: event.clientY }, event.ctrlKey || event.metaKey),
+      end: (cancelled, event) => {
+        if (event && !cancelled)
+          this.move({ x: event.clientX, y: event.clientY }, event.ctrlKey || event.metaKey);
+        this.end(cancelled);
+      },
+    });
+    this.surface.cleanup(() => {
+      this.end(true);
+      this.observe?.disconnect();
+      this.stopNode?.();
+    });
+  }
+  attach(node: EditablePath | null): this {
+    if (node && this.surface.isDestroyed) throw new Error('Path editor is destroyed');
+    this.end(true);
+    this.observe?.disconnect();
+    this.stopNode?.();
+    this.stopNode = null;
+    if (
+      node &&
+      (node.isDestroyed ||
+        node.context !== this.drawing.context ||
+        !this.drawing.el.contains(node.el) ||
+        !['path', 'polyline', 'polygon'].includes(node.el.localName))
+    )
+      throw new TypeError('Expected a live path in this drawing');
+    this.node = node;
+    if (node) {
+      this.observe = new this.surface.view.MutationObserver(this.surface.schedule);
+      this.observe.observe(this.drawing.el, {
+        attributes: true,
+        childList: true,
+        subtree: true,
+      });
+      this.stopNode = node.onDispose(() => this.attach(null));
+    }
+    return this.update();
+  }
+  get handles(): readonly PathHandle[] {
+    if (!this.node || this.node.isDestroyed) return [];
+    if (!(this.node instanceof Path))
+      return this.node
+        .array()
+        .toArray()
+        .map((point, command) => ({ point, command, coordinate: 0, control: false }));
+    return this.node
+      .array()
+      .toArray()
+      .flatMap((command, index) => {
+        const offsets =
+          command[0] === 'Z'
+            ? []
+            : command[0] === 'A'
+              ? [6]
+              : command[0] === 'C'
+                ? [1, 3, 5]
+                : command[0] === 'Q'
+                  ? [1, 3]
+                  : [1];
+        return offsets.map((coordinate) => ({
+          command: index,
+          coordinate,
+          point: { x: command[coordinate] as number, y: command[coordinate + 1] as number },
+          control:
+            coordinate !==
+            (command[0] === 'C' ? 5 : command[0] === 'Q' ? 3 : command[0] === 'A' ? 6 : 1),
+        }));
+      });
+  }
+  begin(index: number): void {
+    if (this.surface.isDestroyed) throw new Error('Path editor is destroyed');
+    this.end(true);
+    const node = this.node,
+      handle = this.handles[index];
+    if (!node || !handle) throw new RangeError('Unknown path handle');
+    const client = node.toClient(handle.point);
+    if (!client) throw new Error('Path mapping is unavailable');
+    const session = this.options.snapper.begin({ kind: 'point', client, nodes: [node] });
+    this.active = {
+      handle,
+      before: node.array().toArray(),
+      serialized: node instanceof Path ? String(node.d) : String(node.attr('points')),
+      session,
+      group: beginChangeGroup(node, { source: 'path-editor' }),
+    };
+  }
+  move(client: Point, ignore = false): void {
+    assertPoint(client);
+    const active = this.active,
+      node = this.node;
+    if (!active || !node) return;
+    try {
+      const point = node.fromClient(active.session?.snap(client, { ignore }) ?? client);
+      if (!point) return;
+      active.group.run(() => {
+        if (node instanceof Path) {
+          const commands = (active.before as PathCommand[]).map((command) => [...command]);
+          commands[active.handle.command][active.handle.coordinate] = point.x;
+          commands[active.handle.command][active.handle.coordinate + 1] = point.y;
+          node.plot(new PathArray(commands as unknown as PathCommand[]));
+        } else {
+          const points = (active.before as Point[]).map((point) => ({ ...point }));
+          points[active.handle.command] = point;
+          node.plot(new PointArray(points));
+        }
+      });
+      this.update();
+    } catch (error) {
+      this.end(true);
+      throw error;
+    }
+  }
+  end(cancelled = false): void {
+    const active = this.active;
+    this.active = null;
+    if (!active) return;
+    try {
+      const node = this.node;
+      if (cancelled && node && !node.isDestroyed)
+        active.group.run(() => {
+          if (node instanceof Path) node.attr('d', active.serialized);
+          else node.attr('points', active.serialized);
+        });
+    } finally {
+      try {
+        active.group.end(cancelled);
+      } finally {
+        active.session?.end();
+      }
+    }
+    this.update();
+  }
+  update(): this {
+    this.surface.update();
+    return this;
+  }
+  get isDestroyed(): boolean {
+    return this.surface.isDestroyed;
+  }
+  destroy(): void {
+    this.surface.destroy();
+  }
+  private render(): void {
+    const node = this.node,
+      document = this.drawing.el.ownerDocument;
+    this.surface.element.replaceChildren(
+      ...this.handles.flatMap((handle, index) => {
+        const client = node?.toClient(handle.point),
+          point = client && this.surface.fromClient(client);
+        if (!point) return [];
+        const circle = svg(document, 'circle', {
+          cx: point.x,
+          cy: point.y,
+          r: handle.control ? 4 : 5,
+          fill: handle.control ? '#fff' : '#3f82df',
+          stroke: this.options.stroke ?? '#215eb3',
+          'vector-effect': 'non-scaling-stroke',
+          'data-path-handle': index,
+          tabindex: 0,
+          role: 'button',
+          'aria-label': `${handle.control ? 'Control' : 'Anchor'} point ${index + 1}`,
+        });
+        circle.style.pointerEvents = 'all';
+        circle.style.cursor = 'move';
+        return [circle];
+      }),
+    );
+  }
+}

package/src/editor/pointer.ts

@@ -0,0 +1,85 @@
+import type { Surface } from './surface.js';
+
+interface Callbacks {
+  start(event: PointerEvent): boolean;
+  move(event: PointerEvent): void;
+  end(cancelled: boolean, event?: PointerEvent): void;
+}
+/** Capture and cancellation are shared by drawing, path handles and ruler drags. */
+export class PointerDrag {
+  private pointer: number | null = null;
+  constructor(
+    private readonly surface: Surface,
+    private readonly callbacks: Callbacks,
+  ) {
+    surface.element.style.touchAction = 'none';
+    surface.listen(surface.element, 'pointerdown', this.down as EventListener);
+    surface.listen(surface.view, 'pointermove', this.move as EventListener);
+    surface.listen(surface.view, 'pointerup', this.up as EventListener);
+    surface.listen(surface.view, 'pointercancel', this.lost as EventListener);
+    surface.listen(surface.element, 'lostpointercapture', this.lost as EventListener);
+    surface.listen(surface.view, 'blur', () => this.cancel());
+    surface.listen(
+      surface.view,
+      'keydown',
+      ((event: KeyboardEvent) => {
+        if (this.pointer !== null && event.key === 'Escape') {
+          event.preventDefault();
+          event.stopPropagation();
+          this.cancel();
+        }
+      }) as EventListener,
+      true,
+    );
+    surface.cleanup(() => this.cancel());
+  }
+  private readonly down = (event: PointerEvent): void => {
+    if (event.defaultPrevented || this.pointer !== null || event.button !== 0 || !event.isPrimary)
+      return;
+    try {
+      if (!this.callbacks.start(event)) return;
+      this.pointer = event.pointerId;
+      this.surface.element.setPointerCapture(event.pointerId);
+      event.preventDefault();
+      event.stopPropagation();
+    } catch (error) {
+      try {
+        if (this.pointer === null) this.callbacks.end(true);
+        else this.cancel();
+      } catch (cleanup) {
+        throw new AggregateError([error, cleanup], 'Pointer acquisition and recovery failed');
+      }
+      throw error;
+    }
+  };
+  private readonly move = (event: PointerEvent): void => {
+    if (event.pointerId !== this.pointer) return;
+    try {
+      this.callbacks.move(event);
+    } catch (error) {
+      this.cancel();
+      throw error;
+    }
+  };
+  private readonly up = (event: PointerEvent): void => {
+    if (event.pointerId !== this.pointer) return;
+    this.finish(false, event);
+  };
+  private readonly lost = (event: PointerEvent): void => {
+    if (event.pointerId === this.pointer) this.cancel();
+  };
+  cancel(): void {
+    this.finish(true);
+  }
+  private finish(cancelled: boolean, event?: PointerEvent): void {
+    const pointer = this.pointer;
+    if (pointer === null) return;
+    this.pointer = null;
+    try {
+      this.callbacks.end(cancelled, event);
+    } finally {
+      if (this.surface.element.hasPointerCapture?.(pointer))
+        this.surface.element.releasePointerCapture(pointer);
+    }
+  }
+}

package/src/editor/surface.ts

@@ -0,0 +1,141 @@
+import { Matrix } from '@rasamjs/core';
+import type { Point, Svg } from '@rasamjs/core';
+import { Guards } from '@rasamjs/core/advanced';
+
+export function svg<Tag extends keyof SVGElementTagNameMap>(
+  document: Document,
+  tag: Tag,
+  attributes: Record<string, string | number> = {},
+): SVGElementTagNameMap[Tag] {
+  const element = document.createElementNS('http://www.w3.org/2000/svg', tag);
+  for (const [key, value] of Object.entries(attributes)) element.setAttribute(key, String(value));
+  return element;
+}
+
+/** Owns an editor-only SVG and every observer/listener registered by its tool. */
+export class Surface {
+  readonly element: SVGSVGElement;
+  readonly view: Window & typeof globalThis;
+  private readonly cleanups: (() => void)[] = [];
+  private pending: number | null = null;
+  private disposed = false;
+  constructor(
+    readonly drawing: Svg,
+    name: string,
+    private readonly render: () => void,
+  ) {
+    if (
+      !Guards.isTransformable(drawing) ||
+      drawing.isDestroyed ||
+      drawing.el.localName !== 'svg' ||
+      !drawing.el.isConnected ||
+      !drawing.el.ownerDocument.defaultView
+    )
+      throw new TypeError('Editor overlay needs a live mounted drawing');
+    this.view = drawing.el.ownerDocument.defaultView;
+    this.element = svg(drawing.el.ownerDocument, 'svg', {
+      class: name,
+      width: '100%',
+      height: '100%',
+      'aria-label': name.replaceAll('-', ' '),
+    });
+    Object.assign(this.element.style, {
+      position: 'absolute',
+      inset: '0',
+      overflow: 'visible',
+      pointerEvents: 'none',
+    });
+    let outer = drawing.el;
+    while (outer.ownerSVGElement) outer = outer.ownerSVGElement;
+    const host = outer.parentElement!;
+    host.append(this.element);
+    const observer = new this.view.MutationObserver(this.schedule);
+    for (
+      let ancestor: Element | null = drawing.el;
+      ancestor && ancestor !== host;
+      ancestor = ancestor.parentElement
+    )
+      observer.observe(ancestor, { attributes: true });
+    this.cleanup(() => observer.disconnect());
+    const resize = new this.view.ResizeObserver(this.schedule);
+    resize.observe(host);
+    this.cleanup(() => resize.disconnect());
+    this.listen(this.view, 'resize', this.schedule);
+    this.listen(this.view, 'scroll', this.schedule, true);
+    this.cleanup(drawing.onDispose(() => this.destroy()));
+    this.schedule();
+  }
+  cleanup(callback: () => void): void {
+    this.cleanups.push(callback);
+  }
+  get isDestroyed(): boolean {
+    return this.disposed;
+  }
+  listen(target: EventTarget, type: string, listener: EventListener, capture = false): void {
+    target.addEventListener(type, listener, capture);
+    this.cleanup(() => target.removeEventListener(type, listener, capture));
+  }
+  readonly schedule = (): void => {
+    if (!this.disposed && this.pending === null)
+      this.pending = this.view.requestAnimationFrame(() => {
+        this.pending = null;
+        this.update();
+      });
+  };
+  update(): this {
+    if (this.pending !== null) this.view.cancelAnimationFrame(this.pending);
+    this.pending = null;
+    if (!this.disposed) this.render();
+    return this;
+  }
+  screenMatrix(): Matrix | null {
+    const m = this.element.getScreenCTM?.();
+    return m ? new Matrix(m.a, m.b, m.c, m.d, m.e, m.f) : null;
+  }
+  fromClient(point: Point): Point | null {
+    return this.screenMatrix()?.inverse()?.apply(point) ?? null;
+  }
+  fromRoot(point: Point): Point | null {
+    const client = this.drawing.toClient(point);
+    return client && this.fromClient(client);
+  }
+  extent(): Point {
+    const rect = this.element.getBoundingClientRect();
+    return {
+      x: this.element.clientWidth || rect.width,
+      y: this.element.clientHeight || rect.height,
+    };
+  }
+  rootBounds(): { left: number; top: number; right: number; bottom: number } | null {
+    const matrix = this.screenMatrix(),
+      size = this.extent();
+    if (!matrix || !size.x || !size.y) return null;
+    const points = [
+      { x: 0, y: 0 },
+      { x: size.x, y: 0 },
+      { x: size.x, y: size.y },
+      { x: 0, y: size.y },
+    ].map((p) => this.drawing.fromClient(matrix.apply(p)));
+    if (points.some((p) => !p)) return null;
+    return {
+      left: Math.min(...points.map((p) => p!.x)),
+      right: Math.max(...points.map((p) => p!.x)),
+      top: Math.min(...points.map((p) => p!.y)),
+      bottom: Math.max(...points.map((p) => p!.y)),
+    };
+  }
+  destroy(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    if (this.pending !== null) this.view.cancelAnimationFrame(this.pending);
+    const failures: unknown[] = [];
+    for (const callback of this.cleanups.reverse())
+      try {
+        callback();
+      } catch (e) {
+        failures.push(e);
+      }
+    this.element.remove();
+    if (failures.length) throw new AggregateError(failures, 'Editor overlay cleanup failed');
+  }
+}

package/src/grid.ts

@@ -0,0 +1,99 @@
+import type { Point, Svg } from '@rasamjs/core';
+import { assertPoint } from './snapping/options.js';
+import { Surface, svg } from './editor/surface.js';
+
+export interface GridOptions {
+  readonly size: number;
+  readonly origin?: Point;
+  readonly stroke?: string;
+}
+/** A camera-aware grid outside the exported SVG, with bounded rendering at extreme zoom. */
+export class GridOverlay {
+  private readonly surface: Surface;
+  private readonly path: SVGPathElement;
+  private readonly origin: Point;
+  private enabledState = true;
+  constructor(
+    private readonly drawing: Svg,
+    private readonly options: GridOptions,
+  ) {
+    if (!Number.isFinite(options?.size) || options.size <= 0)
+      throw new RangeError('Grid size must be positive and finite');
+    this.options = { ...options };
+    this.origin = { ...(options.origin ?? { x: 0, y: 0 }) };
+    assertPoint(this.origin, 'Grid origin');
+    if (
+      options.stroke !== undefined &&
+      (typeof options.stroke !== 'string' || !options.stroke.trim())
+    )
+      throw new TypeError('Grid stroke must be nonempty');
+    this.surface = new Surface(drawing, 'rasam-grid', () => this.render());
+    this.surface.element.style.zIndex = '-1';
+    this.surface.element.setAttribute('aria-hidden', 'true');
+    this.path = svg(drawing.el.ownerDocument, 'path', {
+      fill: 'none',
+      stroke: options.stroke ?? '#d9dee8',
+      'stroke-width': 1,
+      'vector-effect': 'non-scaling-stroke',
+    });
+    this.surface.element.append(this.path);
+    this.update();
+  }
+  get enabled(): boolean {
+    return this.enabledState;
+  }
+  get isDestroyed(): boolean {
+    return this.surface.isDestroyed;
+  }
+  set enabled(value: boolean) {
+    if (typeof value !== 'boolean') throw new TypeError('enabled must be boolean');
+    this.enabledState = value;
+    this.update();
+  }
+  update(): this {
+    this.surface.update();
+    return this;
+  }
+  destroy(): void {
+    this.surface.destroy();
+  }
+  private render(): void {
+    this.surface.element.style.display = this.enabledState ? '' : 'none';
+    const bounds = this.surface.rootBounds();
+    if (!this.enabledState || !bounds) {
+      this.path.setAttribute('d', '');
+      return;
+    }
+    const a = this.drawing.toClient({ x: 0, y: 0 }),
+      b = this.drawing.toClient({ x: this.options.size, y: 0 });
+    const c = this.drawing.toClient({ x: 0, y: this.options.size });
+    if (!a || !b || !c) return;
+    let step = this.options.size;
+    const pixels = Math.min(Math.hypot(b.x - a.x, b.y - a.y), Math.hypot(c.x - a.x, c.y - a.y));
+    if (pixels <= 0) return;
+    while (
+      (step / this.options.size) * pixels < 8 ||
+      (bounds.right - bounds.left + bounds.bottom - bounds.top) / step > 512
+    )
+      step *= 2;
+    const segments: string[] = [];
+    const line = (a: Point, b: Point) => {
+      const from = this.surface.fromRoot(a),
+        to = this.surface.fromRoot(b);
+      if (from && to) segments.push(`M${from.x},${from.y}L${to.x},${to.y}`);
+    };
+    for (
+      let x = this.origin.x + Math.ceil((bounds.left - this.origin.x) / step) * step;
+      x <= bounds.right;
+      x += step
+    )
+      line({ x, y: bounds.top }, { x, y: bounds.bottom });
+    for (
+      let y = this.origin.y + Math.ceil((bounds.top - this.origin.y) / step) * step;
+      y <= bounds.bottom;
+      y += step
+    )
+      line({ x: bounds.left, y }, { x: bounds.right, y });
+    this.path.setAttribute('d', segments.join(''));
+  }
+}