@rasamjs/tools 0.0.0-stage → 0.2.0

package/src/advanced/session.ts

@@ -0,0 +1,276 @@
+import type { AnyNode, Point } from '@rasamjs/core';
+import { Matrix } from '@rasamjs/core';
+import { boundsIn } from '@rasamjs/core/viewport';
+import { boxLines, snapAxis, targetLines } from '../snapping/lines.js';
+import type { Features, Match, Targets } from '../snapping/lines.js';
+import { assertPoint } from '../snapping/options.js';
+import { createSession, resizeLines } from '../snapping/session.js';
+import { movingBox, targetNodes, validateNodes } from '../snapping/targets.js';
+import { createSpacing } from '../snapping/spacing.js';
+import { guideReader } from '../snapping/guides.js';
+import type { SnapSession } from '../snapping/types.js';
+import type { AdvancedSnapRequest } from './types.js';
+import type { SessionContext } from './context.js';
+import {
+  add,
+  clientMatrix,
+  frameConstraint,
+  nearestOnSegments,
+  scale,
+  subtract,
+} from './geometry.js';
+import { curveSegments } from './curves.js';
+
+export function createAdvancedSession(
+  context: SessionContext<AdvancedSnapRequest>,
+): SnapSession | null {
+  const { request } = context;
+  if (!request || !['move', 'resize', 'point'].includes(request.kind))
+    throw new TypeError('Unknown snap request');
+  assertPoint(request.client, 'Start pointer');
+  const nodes =
+    request.kind === 'point' ? ('nodes' in request ? (request.nodes ?? []) : []) : request.nodes;
+  validateNodes(nodes, context.drawing);
+  const start = context.drawing.fromClient(request.client);
+  if (!start) return null;
+  const geometry = readGeometry(context, start, nodes);
+  if (!geometry) return null;
+  const { box, features, constraint, oblique, rotated } = geometry;
+  const { boxes, targets, curves, guides } = collectTargets(context, nodes);
+  const spacing =
+    !rotated && context.options.spacing
+      ? createSpacing({
+          box,
+          features,
+          targets: boxes,
+          kind: request.kind,
+          centered: request.kind === 'resize' && request.centered,
+        })
+      : null;
+  if (!context.isCurrent() || !context.isEnabled()) return null;
+  if (
+    !context.options.grid &&
+    !guides.length &&
+    !curves.length &&
+    !spacing &&
+    !(context.options.shapes && boxes.length)
+  )
+    return null;
+  const read = guideReader(context.drawing, request, boxes);
+  const publish = (matches: readonly (Match | null)[], point: Point | null): void => {
+    if (!context.isCurrent()) return;
+    if (point && matches.some(Boolean)) context.overlay.show(() => read(matches, point));
+    else context.overlay.clear();
+  };
+  let ended = false;
+  const axisSession = createSession({
+    start,
+    features,
+    targets,
+    mapping: context.drawing,
+    options: { ...context.options, shapes: context.options.shapes || !!guides.length },
+    spacing,
+    isEnabled: () => context.isEnabled(),
+    onEnd: () => context.onEnd(),
+    onSnap: publish,
+  });
+  const session: SnapSession = {
+    snap: (client, modifiers) => {
+      assertPoint(client);
+      if (
+        ended ||
+        !context.isEnabled() ||
+        (modifiers.ignore && context.options.modifier !== 'none')
+      ) {
+        context.overlay.clear();
+        return client;
+      }
+      const matrix = clientMatrix(context.drawing),
+        raw = context.drawing.fromClient(client);
+      if (!matrix || !raw) return client;
+      const projected = constraint?.project(subtract(raw, start));
+      let result: Point;
+      if (oblique && projected) {
+        const correction = obliqueCorrection(context, {
+          client,
+          raw,
+          point: projected,
+          direction: constraint!.direction,
+          targets,
+          matrix,
+        });
+        result = correction.client;
+        publish(correction.matches, context.drawing.fromClient(result));
+      } else result = axisSession.snap(client, modifiers);
+      const forward = (value: Point): Point => {
+        if (!request.keyboard) return value;
+        const movement = subtract(client, request.client),
+          accepted = subtract(value, request.client);
+        if (accepted.x * movement.x + accepted.y * movement.y <= 0) {
+          context.overlay.clear();
+          return client;
+        }
+        return value;
+      };
+      if (!curves.length) return forward(result);
+      const references = projected
+        ? [projected]
+        : request.kind === 'point'
+          ? [raw]
+          : features.x.flatMap((x) =>
+              features.y.map((y) => ({
+                x: x.value + raw.x - start.x,
+                y: y.value + raw.y - start.y,
+              })),
+            );
+      const segments = curves.map(([a, b]) => [matrix.apply(a), matrix.apply(b)] as const);
+      let distance =
+        result === client ? Infinity : Math.hypot(result.x - client.x, result.y - client.y);
+      for (const point of references) {
+        const screen = matrix.apply(point);
+        const direction =
+          constraint?.direction && subtract(matrix.apply(add(point, constraint.direction)), screen);
+        const closest = nearestOnSegments(screen, segments, direction);
+        if (!closest) continue;
+        const next = Math.hypot(closest.x - screen.x, closest.y - screen.y);
+        if (next <= context.options.tolerance && next < distance) {
+          distance = next;
+          result = add(client, subtract(closest, screen));
+          const root = context.drawing.fromClient(closest)!;
+          publish(
+            (['x', 'y'] as const).map((axis) => ({
+              target: root[axis],
+              delta: 0,
+              order: -1,
+              grid: false,
+            })),
+            context.drawing.fromClient(result),
+          );
+        }
+      }
+      return forward(result);
+    },
+    end: () => {
+      if (!ended) {
+        ended = true;
+        axisSession.end();
+      }
+    },
+  };
+  return session;
+}
+
+interface ObliqueSample {
+  readonly client: Point;
+  readonly raw: Point;
+  readonly point: Point;
+  readonly direction: Point | undefined;
+  readonly targets: Targets;
+  readonly matrix: Matrix;
+}
+function obliqueCorrection(
+  context: SessionContext<AdvancedSnapRequest>,
+  sample: ObliqueSample,
+): { client: Point; matches: (Match | null)[] } {
+  const { client, raw, point, direction, targets, matrix } = sample;
+  let result = client,
+    distance = Infinity;
+  const matches: (Match | null)[] = [null, null];
+  const origin = matrix.apply(point);
+  for (const [index, axis] of (['x', 'y'] as const).entries()) {
+    const unit = axis === 'x' ? { x: 1, y: 0 } : { x: 0, y: 1 };
+    const vector = subtract(matrix.apply(add(point, unit)), origin);
+    const pixels = Math.hypot(vector.x, vector.y);
+    const match = snapAxis({
+      moving: [{ value: point[axis], edge: true }],
+      targets: context.options.shapes || context.advanced.guides ? targets[axis] : [],
+      offset: 0,
+      tolerance: context.options.tolerance / pixels,
+      grid: context.options.grid && {
+        size: context.options.grid.size,
+        origin: context.options.grid.origin[axis],
+      },
+    });
+    if (!match || (direction && Math.abs(direction[axis]) < 1e-12)) continue;
+    const correction = direction
+      ? scale(direction, match.delta / direction[axis])
+      : scale(unit, match.delta);
+    const screen = matrix.apply(add(point, correction));
+    const next = Math.hypot(screen.x - origin.x, screen.y - origin.y);
+    if (next <= context.options.tolerance && next < distance) {
+      distance = next;
+      result = matrix.apply(add(raw, correction));
+      matches[0] = matches[1] = null;
+      matches[index] = match;
+    }
+  }
+  return { client: result, matches };
+}
+
+function readGeometry(
+  context: SessionContext<AdvancedSnapRequest>,
+  start: Point,
+  nodes: readonly AnyNode[],
+) {
+  const { request } = context;
+  const box =
+    request.kind === 'point'
+      ? { ...start, width: 0, height: 0 }
+      : movingBox(nodes, context.drawing);
+  if (!box) return null;
+  let features: Features = boxLines(box);
+  let constraint: ReturnType<typeof frameConstraint> = null;
+  let oblique = false;
+  let rotated = false;
+  if (request.kind === 'resize') {
+    if (
+      !request.anchor ||
+      ![0, 0.5, 1].includes(request.anchor.x) ||
+      ![0, 0.5, 1].includes(request.anchor.y) ||
+      (request.anchor.x === 0.5 && request.anchor.y === 0.5) ||
+      request.corners.length !== 4
+    )
+      throw new TypeError('Resize needs four corners and an edge/corner anchor');
+    const corners = request.corners.map((p) => {
+      assertPoint(p);
+      return context.drawing.fromClient(p);
+    });
+    if (corners.some((p) => !p)) return null;
+    constraint = frameConstraint(corners as Point[], request.anchor);
+    const aligned = resizeLines(corners as Point[], request.anchor);
+    if (!aligned && !constraint) return null;
+    rotated = !aligned;
+    oblique = rotated && !!constraint?.direction;
+    features = aligned ?? {
+      x: [{ value: constraint!.point.x, edge: true }],
+      y: [{ value: constraint!.point.y, edge: true }],
+    };
+  }
+  return { box, features, constraint, oblique, rotated };
+}
+
+function collectTargets(context: SessionContext<AdvancedSnapRequest>, nodes: readonly AnyNode[]) {
+  const candidates =
+    context.options.shapes || context.options.spacing || context.advanced.curves !== false
+      ? targetNodes(context.drawing, nodes, context.options)
+      : [];
+  const boxes = candidates.flatMap((node) => {
+    const b = boundsIn(node, context.drawing);
+    return 'box' in b ? [b.box] : [];
+  });
+  const initial = targetLines(context.options.shapes ? boxes : []);
+  const targets = { ...initial, x: [...initial.x], y: [...initial.y] };
+  const curves =
+    context.advanced.curves === false
+      ? []
+      : curveSegments(context.drawing, candidates, context.advanced.curveResolution ?? 0.25);
+  const guides = [...(context.advanced.guides?.() ?? [])].map((guide) => {
+    if (!guide || !['x', 'y'].includes(guide.axis) || !Number.isFinite(guide.position))
+      throw new TypeError('Ruler guides need a valid axis and finite position');
+    return { ...guide };
+  });
+  for (const guide of guides) targets[guide.axis].push({ value: guide.position, order: -1 });
+  for (const axis of ['x', 'y'] as const)
+    targets[axis].sort((a, b) => a.value - b.value || a.order - b.order);
+  return { boxes, targets, curves, guides };
+}

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