@rasamjs/tools 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rasamjs/tools",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "license": "MIT",
   "description": "Opt-in editing tools for rasam SVG drawings.",
@@ -23,6 +23,26 @@
       "rasam-source": "./src/snapping.ts",
       "types": "./dist/snapping.d.ts",
       "import": "./dist/snapping.js"
+    },
+    "./snapping/advanced": {
+      "rasam-source": "./src/snapping/advanced.ts",
+      "types": "./dist/snapping/advanced.d.ts",
+      "import": "./dist/snapping/advanced.js"
+    },
+    "./grid": {
+      "rasam-source": "./src/grid.ts",
+      "types": "./dist/grid.d.ts",
+      "import": "./dist/grid.js"
+    },
+    "./rulers": {
+      "rasam-source": "./src/rulers.ts",
+      "types": "./dist/rulers.d.ts",
+      "import": "./dist/rulers.js"
+    },
+    "./drawing": {
+      "rasam-source": "./src/drawing.ts",
+      "types": "./dist/drawing.d.ts",
+      "import": "./dist/drawing.js"
     }
   },
   "sideEffects": false,
@@ -30,10 +50,10 @@
     "@rasamjs/core": "^0.1.0"
   },
   "devDependencies": {
-    "@rasamjs/core": "0.1.1",
+    "@rasamjs/core": "0.1.2",
     "@rasamjs/history": "0.1.0",
-    "@rasamjs/selection": "0.2.0",
-    "@rasamjs/transformer": "0.3.0",
+    "@rasamjs/selection": "0.3.0",
+    "@rasamjs/transformer": "0.4.0",
     "@rasamjs/viewport": "0.1.0"
   },
   "scripts": {

package/src/advanced/context.ts

@@ -0,0 +1,15 @@
+import type { Svg } from '@rasamjs/core';
+import type { ResolvedOptions } from '../snapping/options.js';
+import type { GuideOverlay } from '../snapping/overlay.js';
+import type { AdvancedSnapperOptions } from './types.js';
+
+export interface SessionContext<Request> {
+  readonly drawing: Svg;
+  readonly options: ResolvedOptions;
+  readonly advanced: AdvancedSnapperOptions;
+  readonly overlay: GuideOverlay;
+  readonly request: Request;
+  readonly isEnabled: () => boolean;
+  readonly isCurrent: () => boolean;
+  readonly onEnd: () => void;
+}

package/src/advanced/curves.ts

@@ -0,0 +1,65 @@
+import { PathArray } from '@rasamjs/core';
+import type { AnyNode, Svg, PathCommand } from '@rasamjs/core';
+import { Guards } from '@rasamjs/core/advanced';
+import { clientMatrix } from './geometry.js';
+import type { Segment } from './geometry.js';
+
+function subpaths(geometry: SVGGeometryElement): SVGGeometryElement[] {
+  if (geometry.localName !== 'path') return [geometry];
+  const parts: PathCommand[][] = [];
+  for (const command of new PathArray(geometry.getAttribute('d') ?? '').toArray()) {
+    if (command[0] === 'M') parts.push([]);
+    parts.at(-1)!.push(command);
+  }
+  return parts.map((commands) => {
+    const path = geometry.cloneNode(false) as SVGGeometryElement;
+    path.setAttribute('d', new PathArray(commands).toString());
+    return path;
+  });
+}
+
+/** Detached geometry is sampled once: target edits never change an active session. */
+export function curveSegments(
+  drawing: Svg,
+  nodes: readonly AnyNode[],
+  resolution: number,
+): Segment[] {
+  const root = drawing.worldMatrix().inverse(),
+    screen = clientMatrix(drawing);
+  if (!root || !screen) return [];
+  const segments: Segment[] = [];
+  for (const node of nodes) {
+    if (!Guards.isTransformable(node)) continue;
+    if (!['path', 'line', 'polyline', 'polygon', 'circle', 'ellipse'].includes(node.el.localName))
+      continue;
+    node.flush();
+    const geometry = node.el.cloneNode(false) as SVGGeometryElement;
+    if (typeof geometry.getTotalLength !== 'function') continue;
+    const matrix = root.multiply(node.worldMatrix());
+    const pixels = screen.multiply(matrix);
+    const stretch = Math.hypot(pixels.a, pixels.b, pixels.c, pixels.d);
+    let parts: SVGGeometryElement[];
+    try {
+      parts = subpaths(geometry);
+    } catch {
+      continue;
+    }
+    for (const part of parts) {
+      let length: number;
+      try {
+        length = part.getTotalLength();
+      } catch {
+        continue;
+      }
+      if (!Number.isFinite(length) || length <= 0) continue;
+      const count = Math.max(1, Math.min(8192, Math.ceil((length * stretch) / resolution)));
+      let previous = matrix.apply(part.getPointAtLength(0));
+      for (let index = 1; index <= count; index++) {
+        const next = matrix.apply(part.getPointAtLength((length * index) / count));
+        segments.push([previous, next]);
+        previous = next;
+      }
+    }
+  }
+  return segments;
+}

package/src/advanced/geometry.ts

@@ -0,0 +1,74 @@
+import { Matrix } from '@rasamjs/core';
+import type { Point, Svg } from '@rasamjs/core';
+
+export type Segment = readonly [Point, Point];
+export const add = (a: Point, b: Point): Point => ({ x: a.x + b.x, y: a.y + b.y });
+export const subtract = (a: Point, b: Point): Point => ({ x: a.x - b.x, y: a.y - b.y });
+export const scale = (p: Point, value: number): Point => ({ x: p.x * value, y: p.y * value });
+const cross = (a: Point, b: Point) => a.x * b.y - a.y * b.x;
+
+/** The closest point on cached segments, optionally restricted to a resize line. */
+export function nearestOnSegments(
+  point: Point,
+  segments: readonly Segment[],
+  direction?: Point,
+): Point | null {
+  let best: Point | null = null,
+    distance = Infinity;
+  for (const [a, b] of segments) {
+    const edge = subtract(b, a),
+      relative = subtract(a, point);
+    let candidate: Point;
+    const determinant = direction && cross(direction, edge);
+    if (direction && Math.abs(determinant!) > 1e-12) {
+      const along = cross(relative, direction) / determinant!;
+      if (along < 0 || along > 1) continue;
+      candidate = add(point, scale(direction, cross(relative, edge) / determinant!));
+    } else {
+      if (direction && Math.abs(cross(relative, direction)) > 1e-9) continue;
+      const length = edge.x * edge.x + edge.y * edge.y;
+      const t = length
+        ? Math.max(0, Math.min(1, ((point.x - a.x) * edge.x + (point.y - a.y) * edge.y) / length))
+        : 0;
+      candidate = add(a, scale(edge, t));
+    }
+    const next = Math.hypot(candidate.x - point.x, candidate.y - point.y);
+    if (next < distance) {
+      best = candidate;
+      distance = next;
+    }
+  }
+  return best;
+}
+
+/** Root-to-client mapping is read once per sample, never once per target segment. */
+export function clientMatrix(drawing: Svg): Matrix | null {
+  const a = drawing.toClient({ x: 0, y: 0 });
+  const b = drawing.toClient({ x: 1, y: 0 });
+  const c = drawing.toClient({ x: 0, y: 1 });
+  return a && b && c ? new Matrix(b.x - a.x, b.y - a.y, c.x - a.x, c.y - a.y, a.x, a.y) : null;
+}
+
+export function frameConstraint(corners: readonly Point[], anchor: Point) {
+  const [a, b, , d] = corners;
+  const u = subtract(b, a),
+    v = subtract(d, a);
+  const inverse = new Matrix(u.x, u.y, v.x, v.y, 0, 0).inverse();
+  if (!inverse) return null;
+  const point = add(a, add(scale(u, anchor.x), scale(v, anchor.y)));
+  const direction = anchor.x === 0.5 ? v : anchor.y === 0.5 ? u : undefined;
+  return {
+    point,
+    direction,
+    project(delta: Point): Point {
+      const unit = inverse.apply(delta);
+      return add(
+        point,
+        add(scale(u, anchor.x === 0.5 ? 0 : unit.x), scale(v, anchor.y === 0.5 ? 0 : unit.y)),
+      );
+    },
+  };
+}
+
+export const angleDifference = (a: number, b: number, period = 360): number =>
+  ((((a - b + period * 1.5) % period) + period) % period) - period / 2;

package/src/advanced/rotation.ts

@@ -0,0 +1,93 @@
+import { Matrix } from '@rasamjs/core';
+import type { Point } from '@rasamjs/core';
+import { Guards } from '@rasamjs/core/advanced';
+import { assertPoint } from '../snapping/options.js';
+import { targetNodes, validateNodes } from '../snapping/targets.js';
+import { add, subtract, angleDifference } from './geometry.js';
+import type { SessionContext } from './context.js';
+import type { RotationSnapRequest, RotationSnapSession } from './types.js';
+
+export function createRotationSession(
+  context: SessionContext<RotationSnapRequest>,
+): RotationSnapSession | null {
+  const { request } = context;
+  validateNodes(request.nodes, context.drawing);
+  assertPoint(request.client);
+  assertPoint(request.pivot);
+  if (request.corners.length !== 4) throw new TypeError('Rotation needs four corners');
+  const root = context.drawing.worldMatrix().inverse();
+  const pivot = context.drawing.fromClient(request.pivot),
+    start = context.drawing.fromClient(request.client);
+  const corners = request.corners.map((p) => context.drawing.fromClient(p));
+  if (!root || !pivot || !start || corners.some((p) => !p)) return null;
+  const parent =
+    request.nodes.length === 1 && Guards.isTransformable(request.nodes[0].parent)
+      ? root.multiply(request.nodes[0].parent.worldMatrix())
+      : Matrix.identity();
+  const inverse = parent.inverse();
+  if (!inverse) return null;
+  const vector = (p: Point) => subtract(inverse.apply(add(p, pivot)), inverse.apply(pivot));
+  const first = vector(subtract(corners[1]!, corners[0]!));
+  const startAngle = Math.atan2(vector(subtract(start, pivot)).y, vector(subtract(start, pivot)).x);
+  const frameAngle = Math.atan2(first.y, first.x);
+  const angles = targetNodes(context.drawing, request.nodes, context.options).flatMap((node) => {
+    if (!Guards.isTransformable(node)) return [];
+    const matrix = root.multiply(node.worldMatrix());
+    return [Math.atan2(matrix.b, matrix.a)];
+  });
+  if (!angles.length || !context.isCurrent() || !context.isEnabled()) return null;
+  let ended = false,
+    snapped = false;
+  const session: RotationSnapSession = {
+    get angleSnapped() {
+      return snapped;
+    },
+    snap: (client, modifiers) => {
+      assertPoint(client);
+      snapped = false;
+      if (
+        ended ||
+        !context.isEnabled() ||
+        (modifiers.ignore && context.options.modifier !== 'none')
+      )
+        return client;
+      const current = context.drawing.fromClient(client);
+      if (!current) return client;
+      const local = vector(subtract(current, pivot));
+      const proposed = frameAngle + Math.atan2(local.y, local.x) - startAngle;
+      const mapped = subtract(
+        parent.apply({ x: Math.cos(proposed), y: Math.sin(proposed) }),
+        parent.apply({ x: 0, y: 0 }),
+      );
+      const visual = Math.atan2(mapped.y, mapped.x);
+      let best: number | null = null,
+        distance = ((context.advanced.angleTolerance ?? 5) * Math.PI) / 180;
+      for (const target of angles) {
+        const next = Math.abs(angleDifference(target, visual, Math.PI));
+        if (next <= distance) {
+          distance = next;
+          best = target;
+        }
+      }
+      if (best === null) return client;
+      const target = vector({ x: Math.cos(best), y: Math.sin(best) });
+      const correction = angleDifference(Math.atan2(target.y, target.x), proposed, Math.PI);
+      const rotated = {
+        x: local.x * Math.cos(correction) - local.y * Math.sin(correction),
+        y: local.x * Math.sin(correction) + local.y * Math.cos(correction),
+      };
+      const offset = subtract(parent.apply(rotated), parent.apply({ x: 0, y: 0 }));
+      const result = context.drawing.toClient(add(pivot, offset));
+      snapped = !!result;
+      return result ?? client;
+    },
+    end: () => {
+      if (!ended) {
+        ended = true;
+        snapped = false;
+        context.onEnd();
+      }
+    },
+  };
+  return session;
+}

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