@rasamjs/tools 0.1.0 → 0.2.0

package/src/advanced/snapper.ts

@@ -0,0 +1,124 @@
+import type { Svg } from '@rasamjs/core';
+import { Guards } from '@rasamjs/core/advanced';
+import { resolveOptions } from '../snapping/options.js';
+import type { ResolvedOptions } from '../snapping/options.js';
+import { GuideOverlay } from '../snapping/overlay.js';
+import type { SnapSession } from '../snapping/types.js';
+import type {
+  AdvancedSnapperOptions,
+  AdvancedSnapRequest,
+  RotationSnapRequest,
+  RotationSnapSession,
+} from './types.js';
+import type { SessionContext } from './context.js';
+import { createAdvancedSession } from './session.js';
+import { createRotationSession } from './rotation.js';
+
+/** Owns enhanced sessions while sharing the original engine's geometry and guides. */
+export class AdvancedSnapper {
+  readonly rotatedResize = true;
+  readonly keyboard: boolean;
+  private readonly options: ResolvedOptions;
+  private readonly advanced: AdvancedSnapperOptions;
+  private readonly overlay: GuideOverlay;
+  private readonly dispose: () => void;
+  private active: SnapSession | null = null;
+  private version = 0;
+  private disposed = false;
+  private enabledState = true;
+  constructor(
+    private readonly drawing: Svg,
+    advanced: AdvancedSnapperOptions = {},
+  ) {
+    if (
+      !Guards.isTransformable(drawing) ||
+      drawing.isDestroyed ||
+      drawing.el.localName !== 'svg' ||
+      !drawing.el.isConnected ||
+      !drawing.el.ownerDocument.defaultView
+    )
+      throw new TypeError('AdvancedSnapper needs a live, mounted drawing');
+    this.advanced = { ...advanced };
+    this.options = resolveOptions(advanced);
+    this.keyboard = advanced.keyboard ?? true;
+    if (
+      typeof this.keyboard !== 'boolean' ||
+      (advanced.curves !== undefined && typeof advanced.curves !== 'boolean')
+    )
+      throw new TypeError('Keyboard and curve snapping options must be booleans');
+    if (advanced.guides !== undefined && typeof advanced.guides !== 'function')
+      throw new TypeError('guides must be a function');
+    for (const [name, value] of [
+      ['curveResolution', advanced.curveResolution ?? 0.25],
+      ['angleTolerance', advanced.angleTolerance ?? 5],
+    ] as const)
+      if (!Number.isFinite(value) || value <= 0)
+        throw new RangeError(`${name} must be positive and finite`);
+    this.overlay = new GuideOverlay(drawing, this.options.stroke, this.options.gapStroke);
+    this.dispose = drawing.onDispose(() => this.destroy());
+  }
+  get isDestroyed(): boolean {
+    return this.disposed;
+  }
+  get enabled(): boolean {
+    return this.enabledState;
+  }
+  set enabled(value: boolean) {
+    if (typeof value !== 'boolean') throw new TypeError('enabled must be a boolean');
+    this.enabledState = value;
+    if (!value) this.overlay.clear();
+  }
+  update(): this {
+    if (!this.disposed) this.overlay.update();
+    return this;
+  }
+  destroy(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    try {
+      this.active?.end();
+    } finally {
+      this.overlay.destroy();
+      this.dispose();
+    }
+  }
+  private reset(): number {
+    const version = ++this.version;
+    const previous = this.active;
+    this.active = null;
+    previous?.end();
+    return version;
+  }
+  private ended(version: number): void {
+    if (version !== this.version) return;
+    this.active = null;
+    this.overlay.clear();
+  }
+
+  begin(request: AdvancedSnapRequest): SnapSession | null {
+    const version = this.reset();
+    if (!this.enabled || this.disposed) return null;
+    const session = createAdvancedSession(this.context(request, version));
+    if (session) this.active = session;
+    return session;
+  }
+  rotate(request: RotationSnapRequest): RotationSnapSession | null {
+    const version = this.reset();
+    if (!this.enabled || this.disposed) return null;
+    const session = createRotationSession(this.context(request, version));
+    if (session) this.active = session;
+    return session;
+  }
+  private context<Request>(request: Request, version: number): SessionContext<Request> {
+    return {
+      drawing: this.drawing,
+      options: this.options,
+      advanced: this.advanced,
+      overlay: this.overlay,
+      request,
+      isEnabled: () => this.enabled && !this.disposed,
+      isCurrent: () => version === this.version && !this.disposed,
+      onEnd: () => this.ended(version),
+    };
+  }
+}

package/src/advanced/types.ts

@@ -0,0 +1,31 @@
+import type { AnyNode, Point } from '@rasamjs/core';
+import type { SnapperOptions, SnapRequest, SnapSession } from '../snapping/types.js';
+
+export interface RulerGuide {
+  readonly axis: 'x' | 'y';
+  readonly position: number;
+}
+export interface AdvancedSnapperOptions extends SnapperOptions {
+  readonly guides?: () => Iterable<RulerGuide>;
+  readonly curves?: boolean;
+  readonly curveResolution?: number;
+  readonly angleTolerance?: number;
+  readonly keyboard?: boolean;
+}
+export interface RotationSnapRequest {
+  readonly nodes: readonly AnyNode[];
+  readonly client: Point;
+  readonly pivot: Point;
+  readonly corners: readonly Point[];
+}
+export type AdvancedSnapRequest = (
+  | SnapRequest
+  | {
+      readonly kind: 'point';
+      readonly client: Point;
+      readonly nodes?: readonly AnyNode[];
+    }
+) & { readonly keyboard?: boolean };
+export interface RotationSnapSession extends SnapSession {
+  readonly angleSnapped: boolean;
+}

package/src/drawing.ts

@@ -0,0 +1,4 @@
+export { DrawTool } from './editor/draw-tool.js';
+export type { DrawToolOptions, DrawingKind, PointSnapper } from './editor/draw-tool.js';
+export { PathEditor } from './editor/path-editor.js';
+export type { PathEditorOptions, EditablePath, PathHandle } from './editor/path-editor.js';

package/src/editor/draw-tool.ts

@@ -0,0 +1,190 @@
+import type { AnyNode, Point, Svg } from '@rasamjs/core';
+import { beginChangeGroup } from '@rasamjs/core/changes';
+import type { SnapSession } from '../snapping/types.js';
+import { assertPoint } from '../snapping/options.js';
+import { Surface, svg } from './surface.js';
+import { PointerDrag } from './pointer.js';
+
+export interface PointSnapper {
+  begin(request: {
+    readonly kind: 'point';
+    readonly client: Point;
+    readonly nodes?: readonly AnyNode[];
+  }): SnapSession | null;
+}
+export type DrawingKind = 'rect' | 'ellipse' | 'line' | 'path';
+export interface DrawToolOptions {
+  readonly snapper: PointSnapper;
+  readonly kind?: DrawingKind;
+  readonly paint?: Readonly<Record<string, string | number>>;
+  readonly onCreate?: (node: AnyNode) => void;
+}
+export class DrawTool {
+  private readonly surface: Surface;
+  private readonly hit: SVGRectElement;
+  private enabledState = true;
+  private active: {
+    start: Point;
+    session: SnapSession | null;
+    attributes: Record<string, string | number>;
+    preview: SVGElement;
+  } | null = null;
+  constructor(
+    private readonly drawing: Svg,
+    private readonly options: DrawToolOptions,
+  ) {
+    if (!options?.snapper || typeof options.snapper.begin !== 'function')
+      throw new TypeError('Drawing needs a point snapper');
+    if (!['rect', 'ellipse', 'line', 'path'].includes(options.kind ?? 'rect'))
+      throw new TypeError('Unknown drawing tool');
+    if (options.onCreate !== undefined && typeof options.onCreate !== 'function')
+      throw new TypeError('onCreate must be a function');
+    this.options = { ...options, paint: { ...options.paint } };
+    this.surface = new Surface(drawing, 'rasam-draw-tool', () => this.render());
+    this.surface.element.style.zIndex = '10';
+    this.hit = svg(drawing.el.ownerDocument, 'rect', {
+      width: '100%',
+      height: '100%',
+      fill: 'transparent',
+    });
+    this.hit.style.pointerEvents = 'all';
+    this.hit.style.cursor = 'crosshair';
+    this.surface.element.append(this.hit);
+    new PointerDrag(this.surface, {
+      start: (event) => {
+        if (!this.enabled) return false;
+        this.begin({ x: event.clientX, y: event.clientY }, event.ctrlKey || event.metaKey);
+        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));
+  }
+  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;
+    if (!value) this.end(true);
+    this.render();
+  }
+  begin(client: Point, ignore = false): void {
+    if (this.isDestroyed) throw new Error('Drawing tool is destroyed');
+    this.end(true);
+    assertPoint(client);
+    const session = this.options.snapper.begin({ kind: 'point', client });
+    let start: Point | null;
+    try {
+      start = this.drawing.fromClient(session?.snap(client, { ignore }) ?? client);
+      if (!start) throw new Error('Drawing mapping is unavailable');
+    } catch (error) {
+      session?.end();
+      throw error;
+    }
+    const kind = this.options.kind ?? 'rect';
+    const preview = svg(this.drawing.el.ownerDocument, kind);
+    preview.style.pointerEvents = 'none';
+    this.surface.element.append(preview);
+    this.active = { start, session, preview, attributes: {} };
+    this.move(client, ignore);
+  }
+  move(client: Point, ignore = false): void {
+    assertPoint(client);
+    const active = this.active;
+    if (!active) return;
+    try {
+      const end = this.drawing.fromClient(active.session?.snap(client, { ignore }) ?? client);
+      if (!end) return;
+      const { start } = active,
+        x = Math.min(start.x, end.x),
+        y = Math.min(start.y, end.y);
+      const width = Math.abs(end.x - start.x),
+        height = Math.abs(end.y - start.y);
+      const paint = { fill: '#8bbbf4', stroke: '#2563a6', ...(this.options.paint ?? {}) };
+      const kind = this.options.kind ?? 'rect';
+      active.attributes =
+        kind === 'ellipse'
+          ? { ...paint, cx: x + width / 2, cy: y + height / 2, rx: width / 2, ry: height / 2 }
+          : kind === 'line'
+            ? { ...paint, x1: start.x, y1: start.y, x2: end.x, y2: end.y }
+            : kind === 'path'
+              ? { ...paint, d: `M${start.x} ${start.y} L${end.x} ${end.y}` }
+              : { ...paint, x, y, width, height };
+      for (const [key, value] of Object.entries(active.attributes))
+        active.preview.setAttribute(key, String(value));
+      this.update();
+    } catch (error) {
+      this.end(true);
+      throw error;
+    }
+  }
+  end(cancelled = false): AnyNode | null {
+    const active = this.active;
+    this.active = null;
+    if (!active) return null;
+    try {
+      active.preview.remove();
+      if (cancelled) return null;
+      const group = beginChangeGroup(this.drawing, { source: 'drawing-tool' });
+      let node: AnyNode;
+      try {
+        node = group.run(() => {
+          switch (this.options.kind ?? 'rect') {
+            case 'ellipse':
+              return this.drawing.ellipse({
+                ...active.attributes,
+                rx: Number(active.attributes.rx),
+                ry: Number(active.attributes.ry),
+              });
+            case 'line':
+              return this.drawing.line({
+                ...active.attributes,
+                x2: Number(active.attributes.x2),
+                y2: Number(active.attributes.y2),
+              });
+            case 'path':
+              return this.drawing.path({ ...active.attributes, d: String(active.attributes.d) });
+            default:
+              return this.drawing.rect(active.attributes);
+          }
+        });
+      } finally {
+        group.end();
+      }
+      this.options.onCreate?.(node);
+      return node;
+    } finally {
+      active.session?.end();
+    }
+  }
+
+  update(): this {
+    this.surface.update();
+    return this;
+  }
+  destroy(): void {
+    this.surface.destroy();
+  }
+  private render(): void {
+    this.surface.element.style.display = this.enabled ? '' : 'none';
+    if (!this.active) return;
+    const origin = this.surface.fromRoot({ x: 0, y: 0 }),
+      u = this.surface.fromRoot({ x: 1, y: 0 }),
+      v = this.surface.fromRoot({ x: 0, y: 1 });
+    if (origin && u && v)
+      this.active.preview.setAttribute(
+        'transform',
+        `matrix(${u.x - origin.x} ${u.y - origin.y} ${v.x - origin.x} ${v.y - origin.y} ${origin.x} ${origin.y})`,
+      );
+  }
+}

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);
+    }
+  }
+}