@rasamjs/tools 0.1.0 → 0.2.0

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

package/src/rulers.ts

@@ -0,0 +1,245 @@
+import type { Point, Svg } from '@rasamjs/core';
+import type { RulerGuide } from './advanced/types.js';
+import { Surface, svg } from './editor/surface.js';
+import { PointerDrag } from './editor/pointer.js';
+
+export interface RulerOptions {
+  readonly stroke?: string;
+  readonly onChange?: (guides: readonly NamedGuide[]) => void;
+}
+export interface NamedGuide extends RulerGuide {
+  readonly id: number;
+}
+export class RulerGuides {
+  private readonly surface: Surface;
+  private readonly values = new Map<number, NamedGuide>();
+  private next = 1;
+  private drag: { id: number; before: number | null } | null = null;
+  constructor(
+    private readonly drawing: Svg,
+    private readonly options: RulerOptions = {},
+  ) {
+    if (
+      options.stroke !== undefined &&
+      (typeof options.stroke !== 'string' || !options.stroke.trim())
+    )
+      throw new TypeError('Guide stroke must be nonempty');
+    if (options.onChange !== undefined && typeof options.onChange !== 'function')
+      throw new TypeError('onChange must be a function');
+    this.options = { ...options };
+    this.surface = new Surface(drawing, 'rasam-rulers', () => this.render());
+    this.surface.element.style.zIndex = '30';
+    new PointerDrag(this.surface, {
+      start: (event) => {
+        const target = event.target as Element;
+        const existing = target.closest('[data-guide-id]');
+        const ruler = target.closest('[data-ruler-axis]');
+        if (!existing && !ruler) return false;
+        const point = this.drawing.fromClient({ x: event.clientX, y: event.clientY });
+        if (!point) return false;
+        if (existing) {
+          const id = Number(existing.getAttribute('data-guide-id'));
+          this.drag = { id, before: this.values.get(id)!.position };
+        } else {
+          const axis = ruler!.getAttribute('data-ruler-axis') as 'x' | 'y';
+          this.drag = { id: this.add(axis, point[axis]), before: null };
+        }
+        return true;
+      },
+      move: (event) => {
+        const point = this.drawing.fromClient({ x: event.clientX, y: event.clientY });
+        if (this.drag && point) {
+          const guide = this.values.get(this.drag.id)!;
+          this.move(guide.id, point[guide.axis]);
+        }
+      },
+      end: (cancelled, event) => {
+        const drag = this.drag;
+        this.drag = null;
+        if (!drag) return;
+        if (this.surface.isDestroyed) return;
+        if (cancelled) {
+          if (drag.before === null) this.remove(drag.id);
+          else this.move(drag.id, drag.before);
+        } else if (event) {
+          const point = this.surface.fromClient({ x: event.clientX, y: event.clientY }),
+            size = this.surface.extent();
+          if (!point || point.x < 20 || point.y < 20 || point.x > size.x || point.y > size.y)
+            this.remove(drag.id);
+        }
+      },
+    });
+    this.surface.listen(this.surface.element, 'dblclick', ((event: MouseEvent) => {
+      const guide = (event.target as Element).closest('[data-guide-id]');
+      if (guide) {
+        event.preventDefault();
+        this.remove(Number(guide.getAttribute('data-guide-id')));
+      }
+    }) as EventListener);
+    this.surface.listen(this.surface.element, 'keydown', ((event: KeyboardEvent) => {
+      const target = event.target as Element,
+        handle = target.closest('[data-guide-id]');
+      if (handle) {
+        const id = Number(handle.getAttribute('data-guide-id')),
+          guide = this.values.get(id)!;
+        const direction =
+          guide.axis === 'x'
+            ? ({ ArrowLeft: -1, ArrowRight: 1 } as Record<string, number>)
+            : ({ ArrowUp: -1, ArrowDown: 1 } as Record<string, number>);
+        if (direction[event.key]) {
+          event.preventDefault();
+          event.stopPropagation();
+          this.move(id, guide.position + direction[event.key] * (event.shiftKey ? 10 : 1));
+        } else if (event.key === 'Delete' || event.key === 'Backspace') {
+          event.preventDefault();
+          event.stopPropagation();
+          this.remove(id);
+        }
+      } else if (event.key === 'Enter' || event.key === ' ') {
+        const ruler = target.closest('[data-ruler-axis]'),
+          bounds = this.surface.rootBounds();
+        if (!ruler || !bounds) return;
+        event.preventDefault();
+        event.stopPropagation();
+        const axis = ruler.getAttribute('data-ruler-axis') as 'x' | 'y';
+        const id = this.add(
+          axis,
+          axis === 'x' ? (bounds.left + bounds.right) / 2 : (bounds.top + bounds.bottom) / 2,
+        );
+        this.surface.element.querySelector<SVGElement>(`[data-guide-id="${id}"]`)?.focus();
+      }
+    }) as EventListener);
+    this.surface.cleanup(() => {
+      this.drag = null;
+      this.values.clear();
+    });
+    this.update();
+  }
+  get guides(): readonly NamedGuide[] {
+    return Object.freeze([...this.values.values()].map((g) => Object.freeze({ ...g })));
+  }
+  get isDestroyed(): boolean {
+    return this.surface.isDestroyed;
+  }
+  add(axis: 'x' | 'y', position: number): number {
+    this.assertLive();
+    if (!['x', 'y'].includes(axis) || !Number.isFinite(position))
+      throw new TypeError('Guide needs an axis and finite position');
+    const id = this.next++;
+    this.values.set(id, { id, axis, position });
+    this.changed();
+    return id;
+  }
+  move(id: number, position: number): void {
+    this.assertLive();
+    const guide = this.values.get(id);
+    if (!guide) throw new RangeError('Unknown guide');
+    if (!Number.isFinite(position)) throw new TypeError('Guide position must be finite');
+    this.values.set(id, { ...guide, position });
+    this.changed();
+  }
+  remove(id: number): boolean {
+    this.assertLive();
+    const removed = this.values.delete(id);
+    if (removed) this.changed();
+    return removed;
+  }
+  clear(): void {
+    this.assertLive();
+    this.values.clear();
+    this.changed();
+  }
+  update(): this {
+    this.surface.update();
+    return this;
+  }
+  destroy(): void {
+    this.surface.destroy();
+    this.values.clear();
+  }
+  private changed(): void {
+    this.update();
+    this.options.onChange?.(this.guides);
+  }
+  private assertLive(): void {
+    if (this.isDestroyed) throw new Error('Ruler guides are destroyed');
+  }
+  private render(): void {
+    const document = this.drawing.el.ownerDocument,
+      size = this.surface.extent(),
+      bounds = this.surface.rootBounds();
+    const focus = document.activeElement;
+    const activeId =
+      focus && this.surface.element.contains(focus) ? focus.getAttribute('data-guide-id') : null;
+    const parts: SVGElement[] = [];
+    for (const axis of ['x', 'y'] as const) {
+      const rect = svg(document, 'rect', {
+        x: 0,
+        y: 0,
+        width: axis === 'x' ? 20 : size.x,
+        height: axis === 'x' ? size.y : 20,
+        fill: '#edf0f5',
+        stroke: '#bbc3cf',
+        'data-ruler-axis': axis,
+        tabindex: 0,
+        role: 'button',
+        'aria-label': `Drag ${axis === 'x' ? 'vertical' : 'horizontal'} guide`,
+      });
+      rect.style.pointerEvents = 'all';
+      parts.push(rect);
+    }
+    if (bounds) {
+      for (const guide of this.values.values()) {
+        const a = this.surface.fromRoot(
+          guide.axis === 'x'
+            ? { x: guide.position, y: bounds.top }
+            : { x: bounds.left, y: guide.position },
+        );
+        const b = this.surface.fromRoot(
+          guide.axis === 'x'
+            ? { x: guide.position, y: bounds.bottom }
+            : { x: bounds.right, y: guide.position },
+        );
+        if (!a || !b) continue;
+        const line = svg(document, 'line', {
+          x1: a.x,
+          y1: a.y,
+          x2: b.x,
+          y2: b.y,
+          stroke: this.options.stroke ?? '#d23cdd',
+          'stroke-width': 1,
+          'vector-effect': 'non-scaling-stroke',
+          'data-guide-id': guide.id,
+          tabindex: 0,
+          role: 'button',
+          'aria-label': `${guide.axis} guide at ${guide.position}`,
+        });
+        line.style.pointerEvents = 'stroke';
+        line.style.cursor = guide.axis === 'x' ? 'ew-resize' : 'ns-resize';
+        parts.push(line);
+      }
+      for (const axis of ['x', 'y'] as const) {
+        const low = axis === 'x' ? bounds.left : bounds.top,
+          high = axis === 'x' ? bounds.right : bounds.bottom;
+        const step = Math.pow(10, Math.ceil(Math.log10(Math.max(1, (high - low) / 10))));
+        for (let value = Math.ceil(low / step) * step; value <= high; value += step) {
+          const p = this.surface.fromRoot(
+            axis === 'x' ? { x: value, y: bounds.top } : { x: bounds.left, y: value },
+          );
+          if (!p) continue;
+          const text = svg(document, 'text', {
+            x: axis === 'x' ? p.x + 2 : 2,
+            y: axis === 'x' ? 12 : p.y + 12,
+            'font-size': 10,
+            fill: '#536174',
+          });
+          text.textContent = String(value);
+          parts.push(text);
+        }
+      }
+    }
+    this.surface.element.replaceChildren(...parts);
+    if (activeId)
+      this.surface.element.querySelector<SVGElement>(`[data-guide-id="${activeId}"]`)?.focus();
+  }
+}

package/src/snapping/advanced.ts

@@ -0,0 +1,8 @@
+export { AdvancedSnapper } from '../advanced/snapper.js';
+export type {
+  AdvancedSnapperOptions,
+  AdvancedSnapRequest,
+  RulerGuide,
+  RotationSnapRequest,
+  RotationSnapSession,
+} from '../advanced/types.js';

package/src/snapping/targets.ts

@@ -43,11 +43,11 @@ function visible(node: AnyNode): boolean {
   return true;
 }
 
-export function measureTargets(
+export function targetNodes(
   drawing: Svg,
   nodes: readonly AnyNode[],
   options: ResolvedOptions,
-): Box[] {
+): AnyNode[] {
   const candidates = options.targets
     ? options.targets(nodes)
     : nodes.length
@@ -70,7 +70,16 @@ export function measureTargets(
   const ordered = [...eligible].sort((a, b) =>
     a === b ? 0 : a.el.compareDocumentPosition(b.el) & 4 ? -1 : 1,
   );
+  return ordered;
+}
+
+export function measureTargets(
+  drawing: Svg,
+  nodes: readonly AnyNode[],
+  options: ResolvedOptions,
+): Box[] {
   const boxes: Box[] = [];
+  const ordered = targetNodes(drawing, nodes, options);
   for (const node of ordered) {
     const bounds = boundsIn(node, drawing);
     if ('box' in bounds) boxes.push(bounds.box);