@rasamjs/tools 0.0.0-stage → 0.1.0

package/src/snapping/guides.ts

@@ -0,0 +1,132 @@
+import type { AnyNode, Box, Point, Svg } from '@rasamjs/core';
+import { Guards } from '@rasamjs/core/advanced';
+import { movingBox } from './targets.js';
+import type { Match } from './lines.js';
+import type { SnapRequest } from './types.js';
+
+export interface Guide {
+  readonly axis: 'x' | 'y';
+  readonly position: number;
+  readonly from: number;
+  readonly to: number;
+  readonly marks: readonly number[];
+  readonly gap?: boolean;
+}
+
+function rootMatrix(drawing: Svg, node: AnyNode) {
+  return Guards.isTransformable(node)
+    ? drawing.worldMatrix().inverse()?.multiply(node.worldMatrix())
+    : null;
+}
+
+/** Follow the dragged anchor, including group flips that exchange the outer edges. */
+function draggedAnchor(drawing: Svg, request: SnapRequest): () => Point | null {
+  if (request.kind !== 'resize') return () => null;
+  const nodes = [...new Set(request.nodes)];
+  const anchor = { ...request.anchor! };
+  if (nodes.length === 1)
+    return () => {
+      const matrix = rootMatrix(drawing, nodes[0]),
+        bounds = nodes[0].bounds();
+      return matrix && 'box' in bounds
+        ? matrix.apply({
+            x: bounds.box.x + bounds.box.width * anchor.x,
+            y: bounds.box.y + bounds.box.height * anchor.y,
+          })
+        : null;
+    };
+  const inverse = rootMatrix(drawing, nodes[0])?.inverse();
+  const corners = request.corners.map((point) => drawing.fromClient(point));
+  if (!inverse || corners.some((point) => !point)) return () => null;
+  const [a, b, , d] = corners as Point[];
+  const initial = {
+    x: a.x + (b.x - a.x) * anchor.x + (d.x - a.x) * anchor.y,
+    y: a.y + (b.y - a.y) * anchor.x + (d.y - a.y) * anchor.y,
+  };
+  return () => rootMatrix(drawing, nodes[0])?.multiply(inverse).apply(initial) ?? null;
+}
+
+/** Read accepted geometry after the transformer has applied its own constraints. */
+export function guideReader(drawing: Svg, request: SnapRequest, boxes: readonly Box[]) {
+  const pointOnly = request.kind === 'point',
+    resizing = request.kind === 'resize';
+  const nodes = pointOnly ? [] : [...new Set(request.nodes)];
+  const dragged = draggedAnchor(drawing, request);
+  return (matches: readonly (Match | null)[], point: Point | null): Guide[] => {
+    if (
+      !point ||
+      drawing.isDestroyed ||
+      nodes.some((node) => node.isDestroyed || !drawing.el.contains(node.el))
+    )
+      return [];
+    const box = pointOnly ? { ...point, width: 0, height: 0 } : movingBox(nodes, drawing);
+    if (!box) return [];
+    const active = dragged();
+    const guides: Guide[] = [];
+    for (const [index, axis] of (['x', 'y'] as const).entries()) {
+      const match = matches[index];
+      if (!match) continue;
+      const other = axis === 'x' ? 'y' : 'x',
+        size = axis === 'x' ? 'width' : 'height',
+        span = other === 'x' ? 'width' : 'height';
+      const values = resizing
+        ? active
+          ? [active[axis]]
+          : []
+        : [box[axis], box[axis] + box[size] / 2, box[axis] + box[size]];
+      const value = values.reduce(
+        (best, next) =>
+          Math.abs(next - match.target) < Math.abs(best - match.target) ? next : best,
+        Infinity,
+      );
+      if (!Number.isFinite(value)) continue;
+      const from = drawing.toClient({ ...point, [axis]: value }),
+        to = drawing.toClient({ ...point, [axis]: match.target });
+      if (!from || !to || Math.hypot(to.x - from.x, to.y - from.y) > 0.5) continue;
+      if (match.gaps) {
+        let valid = true;
+        const gaps = match.gaps.map<Guide>((gap) => {
+          const from = gap.moving === 'from' ? box[axis] + box[size] : gap.from;
+          const to = gap.moving === 'to' ? box[axis] : gap.to;
+          const expected = drawing.toClient({ ...point, [axis]: gap.to - gap.from });
+          const accepted = drawing.toClient({ ...point, [axis]: to - from });
+          const neighbor = gap.neighbor === undefined ? null : boxes[gap.neighbor];
+          const low = neighbor ? Math.max(box[other], neighbor[other]) : gap.at;
+          const high = neighbor
+            ? Math.min(box[other] + box[span], neighbor[other] + neighbor[span])
+            : gap.at;
+          if (
+            !expected ||
+            !accepted ||
+            to <= from ||
+            low > high ||
+            Math.hypot(accepted.x - expected.x, accepted.y - expected.y) > 0.5
+          )
+            valid = false;
+          return {
+            axis: other,
+            position: (low + high) / 2,
+            from,
+            to,
+            marks: [from, to],
+            gap: true,
+          };
+        });
+        if (valid) guides.push(...gaps);
+        continue;
+      }
+      const target = !match.grid && boxes[match.order];
+      guides.push({
+        axis,
+        position: match.target,
+        from: Math.min(box[other], target ? target[other] : box[other]),
+        to: Math.max(
+          box[other] + box[span],
+          target ? target[other] + target[span] : box[other] + box[span],
+        ),
+        marks: [box[other] + box[span] / 2, ...(target ? [target[other] + target[span] / 2] : [])],
+      });
+    }
+    return guides;
+  };
+}

package/src/snapping/lines.ts

@@ -0,0 +1,108 @@
+import type { Box } from '@rasamjs/core';
+import type { Gap } from './spacing.js';
+
+export interface MovingLine {
+  readonly value: number;
+  readonly edge: boolean;
+}
+export interface TargetLine {
+  readonly value: number;
+  readonly order: number;
+}
+export interface Features {
+  readonly x: readonly MovingLine[];
+  readonly y: readonly MovingLine[];
+}
+export interface Targets {
+  readonly x: readonly TargetLine[];
+  readonly y: readonly TargetLine[];
+  readonly boxes: readonly Box[];
+}
+export interface Match {
+  readonly delta: number;
+  readonly target: number;
+  readonly order: number;
+  readonly grid: boolean;
+  readonly gaps?: readonly Gap[];
+}
+interface AxisRequest {
+  readonly moving: readonly MovingLine[];
+  readonly targets: readonly TargetLine[];
+  readonly offset: number;
+  readonly tolerance: number;
+  readonly grid: { readonly size: number; readonly origin: number } | null;
+}
+
+function axisLines(value: number, size: number): MovingLine[] {
+  return [
+    { value, edge: true },
+    { value: value + size / 2, edge: false },
+    { value: value + size, edge: true },
+  ];
+}
+
+export function boxLines(box: Box): Features {
+  return { x: axisLines(box.x, box.width), y: axisLines(box.y, box.height) };
+}
+
+function sorted(lines: TargetLine[]): TargetLine[] {
+  return lines
+    .sort((a, b) => a.value - b.value || a.order - b.order)
+    .filter((line, index, all) => index === 0 || line.value !== all[index - 1].value);
+}
+
+export function targetLines(boxes: readonly Box[]): Targets {
+  const x: TargetLine[] = [],
+    y: TargetLine[] = [];
+  boxes.forEach((box, order) => {
+    const lines = boxLines(box);
+    for (const line of lines.x) x.push({ value: line.value, order });
+    for (const line of lines.y) y.push({ value: line.value, order });
+  });
+  return { x: sorted(x), y: sorted(y), boxes: boxes.map((box) => ({ ...box })) };
+}
+
+export function prefer(current: Match | null, candidate: Match): Match {
+  if (!current) return candidate;
+  const distance = Math.abs(candidate.delta) - Math.abs(current.delta);
+  if (distance !== 0) return distance < 0 ? candidate : current;
+  if (!!candidate.gaps !== !!current.gaps) return candidate.gaps ? current : candidate;
+  if (candidate.grid !== current.grid) return candidate.grid ? current : candidate;
+  return candidate.order < current.order ? candidate : current;
+}
+
+export function lowerBound(lines: readonly TargetLine[], value: number): number {
+  let low = 0,
+    high = lines.length;
+  while (low < high) {
+    const middle = Math.floor((low + high) / 2);
+    if (lines[middle].value < value) low = middle + 1;
+    else high = middle;
+  }
+  return low;
+}
+
+export function snapAxis(request: AxisRequest): Match | null {
+  let best: Match | null = null;
+  for (const line of request.moving) {
+    const value = line.value + request.offset;
+    const index = lowerBound(request.targets, value);
+    for (const neighbor of [index - 1, index]) {
+      const target = request.targets[neighbor];
+      if (target && Math.abs(target.value - value) <= request.tolerance)
+        best = prefer(best, {
+          delta: target.value - value,
+          target: target.value,
+          order: target.order,
+          grid: false,
+        });
+    }
+    if (request.grid && line.edge) {
+      const { size, origin } = request.grid;
+      const target = origin + Math.round((value - origin) / size) * size;
+      if (Math.abs(target - value) <= request.tolerance)
+        best = prefer(best, { delta: target - value, target, order: Infinity, grid: true });
+    }
+  }
+  return best;
+}

package/src/snapping/options.ts

@@ -0,0 +1,47 @@
+import type { Point } from '@rasamjs/core';
+import type { SnapperOptions } from './types.js';
+
+export function assertPoint(point: Point, name = 'Point'): void {
+  if (!point || !Number.isFinite(point.x) || !Number.isFinite(point.y))
+    throw new TypeError(`${name} must have finite x and y coordinates`);
+}
+
+export function resolveOptions(options: SnapperOptions = {}) {
+  const tolerance = options.tolerance ?? 6;
+  if (!Number.isFinite(tolerance) || tolerance < 0)
+    throw new RangeError('Snapping tolerance must be nonnegative and finite');
+  const shapes = options.shapes ?? true;
+  const spacing = options.spacing ?? true;
+  if (typeof spacing !== 'boolean') throw new TypeError('spacing must be a boolean');
+  if (typeof shapes !== 'boolean') throw new TypeError('shapes must be a boolean');
+  if (options.targets !== undefined && typeof options.targets !== 'function')
+    throw new TypeError('targets must be a function');
+  const modifier = options.modifier ?? 'ctrl';
+  if (modifier !== 'ctrl' && modifier !== 'none') throw new TypeError('Invalid snapping modifier');
+  const stroke = options.style?.stroke ?? '#f00';
+  const gapStroke = options.style?.gapStroke ?? stroke;
+  if ([stroke, gapStroke].some((value) => typeof value !== 'string' || !value.trim()))
+    throw new TypeError('Guide stroke must be a nonempty string');
+  let grid: { readonly size: number; readonly origin: Point } | null = null;
+  if (options.grid !== undefined && options.grid !== null) {
+    const size = typeof options.grid === 'number' ? options.grid : options.grid.size;
+    if (!Number.isFinite(size) || size <= 0)
+      throw new RangeError('Grid size must be positive and finite');
+    const origin =
+      typeof options.grid === 'number' ? { x: 0, y: 0 } : (options.grid.origin ?? { x: 0, y: 0 });
+    assertPoint(origin, 'Grid origin');
+    grid = { size, origin: { x: origin.x, y: origin.y } };
+  }
+  return {
+    tolerance,
+    shapes,
+    spacing,
+    grid,
+    targets: options.targets,
+    modifier,
+    stroke,
+    gapStroke,
+  };
+}
+
+export type ResolvedOptions = ReturnType<typeof resolveOptions>;

package/src/snapping/overlay.ts

@@ -0,0 +1,186 @@
+import { Matrix } from '@rasamjs/core';
+import type { Point, Svg } from '@rasamjs/core';
+import type { Guide } from './guides.js';
+
+const namespace = 'http://www.w3.org/2000/svg';
+const guidePoint = (guide: Guide, value: number): Point =>
+  guide.axis === 'x' ? { x: guide.position, y: value } : { x: value, y: guide.position };
+
+/** Native SVG outside the managed drawing; geometry is projected through client pixels. */
+export class GuideOverlay {
+  private readonly element: SVGSVGElement;
+  private readonly lines: SVGLineElement[];
+  private readonly marks: SVGPathElement;
+  private readonly gaps: SVGPathElement;
+  private readonly view: Window;
+  private pending: number | null = null;
+  private read: (() => readonly Guide[]) | null = null;
+
+  constructor(
+    private readonly drawing: Svg,
+    stroke: string,
+    gapStroke = stroke,
+  ) {
+    const document = drawing.el.ownerDocument;
+    this.view = document.defaultView!;
+    let outer = drawing.el;
+    while (outer.ownerSVGElement) outer = outer.ownerSVGElement;
+    if (!outer.parentElement) throw new TypeError('Guides need a mounted drawing container');
+    this.element = document.createElementNS(namespace, 'svg');
+    for (const [key, value] of Object.entries({
+      class: 'rasam-snapping',
+      width: '100%',
+      height: '100%',
+      'aria-hidden': 'true',
+      focusable: 'false',
+      fill: 'none',
+      stroke,
+    }))
+      this.element.setAttribute(key, value);
+    Object.assign(this.element.style, {
+      position: 'absolute',
+      inset: '0',
+      overflow: 'visible',
+      pointerEvents: 'none',
+      display: 'none',
+    });
+    this.lines = ['x', 'y'].map((axis) => {
+      const line = this.create('line');
+      line.setAttribute('data-axis', axis);
+      return line;
+    });
+    this.marks = this.create('path');
+    this.gaps = this.create('path');
+    this.gaps.setAttribute('data-gaps', '');
+    this.gaps.setAttribute('stroke', gapStroke);
+    outer.parentElement.append(this.element);
+    this.view.addEventListener('scroll', this.schedule, true);
+    this.view.addEventListener('resize', this.schedule);
+  }
+
+  private create<Tag extends 'line' | 'path'>(tag: Tag): SVGElementTagNameMap[Tag] {
+    const element = this.element.ownerDocument.createElementNS(namespace, tag);
+    element.setAttribute('stroke-width', '1');
+    element.setAttribute('vector-effect', 'non-scaling-stroke');
+    this.element.append(element);
+    return element;
+  }
+
+  show(read: () => readonly Guide[]): void {
+    this.read = read;
+    this.schedule();
+  }
+  private readonly schedule = (): void => {
+    if (this.read && this.pending === null)
+      this.pending = this.view.requestAnimationFrame(() => {
+        this.pending = null;
+        this.update();
+      });
+  };
+
+  update(): void {
+    if (this.pending !== null) this.view.cancelAnimationFrame(this.pending);
+    this.pending = null;
+    const guides = this.read?.() ?? [];
+    if (!guides.length || !this.element.isConnected) {
+      this.element.style.display = 'none';
+      return;
+    }
+    this.element.style.display = '';
+    const screen = this.element.getScreenCTM?.();
+    const inverse =
+      screen && new Matrix(screen.a, screen.b, screen.c, screen.d, screen.e, screen.f).inverse();
+    if (!inverse) {
+      this.element.style.display = 'none';
+      return;
+    }
+    const marks: string[] = [];
+    for (const [index, axis] of (['x', 'y'] as const).entries()) {
+      const line = this.lines[index],
+        guide = guides.find((guide) => !guide.gap && guide.axis === axis);
+      line.style.display = guide ? '' : 'none';
+      if (!guide) continue;
+      const point = (value: number) => guidePoint(guide, value);
+      const a = this.drawing.toClient(point(guide.from)),
+        b = this.drawing.toClient(point(guide.to)),
+        next = this.drawing.toClient(point(guide.from + 1));
+      if (!a || !b || !next) {
+        this.element.style.display = 'none';
+        return;
+      }
+      const length = Math.hypot(next.x - a.x, next.y - a.y);
+      if (!length) {
+        line.style.display = 'none';
+        continue;
+      }
+      const pad = { x: (8 * (next.x - a.x)) / length, y: (8 * (next.y - a.y)) / length };
+      const start = inverse.apply({ x: a.x - pad.x, y: a.y - pad.y }),
+        end = inverse.apply({ x: b.x + pad.x, y: b.y + pad.y });
+      for (const [name, value] of Object.entries({
+        x1: start.x,
+        y1: start.y,
+        x2: end.x,
+        y2: end.y,
+      }))
+        line.setAttribute(name, String(value));
+      for (const value of guide.marks) {
+        const client = this.drawing.toClient(point(value));
+        if (!client) continue;
+        for (const [a, b] of [
+          [-3, 3],
+          [3, -3],
+        ]) {
+          const start = inverse.apply({ x: client.x - 3, y: client.y + a }),
+            end = inverse.apply({ x: client.x + 3, y: client.y + b });
+          marks.push(`M${start.x},${start.y}L${end.x},${end.y}`);
+        }
+      }
+    }
+    this.marks.setAttribute('d', marks.join(''));
+    this.gaps.setAttribute(
+      'd',
+      guides
+        .filter((guide) => guide.gap)
+        .map((guide) => this.gapPath(guide, inverse))
+        .join(''),
+    );
+  }
+
+  private gapPath(guide: Guide, inverse: Matrix): string {
+    const a = this.drawing.toClient(guidePoint(guide, guide.from));
+    const b = this.drawing.toClient(guidePoint(guide, guide.to));
+    if (!a || !b) return '';
+    const length = Math.hypot(b.x - a.x, b.y - a.y);
+    if (!length) return '';
+    const cap = { x: (3 * (b.y - a.y)) / length, y: (3 * (b.x - a.x)) / length };
+    const segment = (from: Point, to: Point) => {
+      const start = inverse.apply(from),
+        end = inverse.apply(to);
+      return `M${start.x},${start.y}L${end.x},${end.y}`;
+    };
+    return (
+      segment(a, b) +
+      [a, b]
+        .map((point) =>
+          segment(
+            { x: point.x + cap.x, y: point.y - cap.y },
+            { x: point.x - cap.x, y: point.y + cap.y },
+          ),
+        )
+        .join('')
+    );
+  }
+
+  clear(): void {
+    if (this.pending !== null) this.view.cancelAnimationFrame(this.pending);
+    this.pending = null;
+    this.read = null;
+    this.element.style.display = 'none';
+  }
+  destroy(): void {
+    this.clear();
+    this.element.remove();
+    this.view.removeEventListener('scroll', this.schedule, true);
+    this.view.removeEventListener('resize', this.schedule);
+  }
+}

package/src/snapping/session.ts

@@ -0,0 +1,116 @@
+import type { Point } from '@rasamjs/core';
+import type { Features, Match, Targets } from './lines.js';
+import { prefer, snapAxis } from './lines.js';
+import type { Spacing } from './spacing.js';
+import type { ResolvedOptions } from './options.js';
+import { assertPoint } from './options.js';
+import type { SnapSession } from './types.js';
+
+interface Mapping {
+  fromClient(point: Point): Point | null;
+  toClient(point: Point): Point | null;
+}
+interface SessionConfig {
+  readonly start: Point;
+  readonly features: Features;
+  readonly targets: Targets;
+  readonly mapping: Mapping;
+  readonly options: ResolvedOptions;
+  readonly isEnabled: () => boolean;
+  readonly onEnd: () => void;
+  readonly onSnap?: (matches: readonly (Match | null)[], point: Point | null) => void;
+  readonly spacing?: Spacing | null;
+}
+
+/** Unit-frame anchors can map to either root axis after a quarter turn or reflection. */
+export function resizeLines(corners: readonly Point[], anchor: Point): Features | null {
+  if (corners.length !== 4) return null;
+  const [a, b, c, d] = corners;
+  const u = { x: b.x - a.x, y: b.y - a.y },
+    v = { x: d.x - a.x, y: d.y - a.y };
+  const epsilon = 1e-7 * Math.max(Math.abs(u.x), Math.abs(u.y), Math.abs(v.x), Math.abs(v.y));
+  const horizontal = (edge: Point) => Math.abs(edge.x) > 1e-7 * Math.hypot(edge.x, edge.y);
+  const vertical = (edge: Point) => Math.abs(edge.y) > 1e-7 * Math.hypot(edge.x, edge.y);
+  if (
+    [u, v].some((edge) => horizontal(edge) && vertical(edge)) ||
+    (horizontal(u) && horizontal(v)) ||
+    (vertical(u) && vertical(v)) ||
+    Math.abs(c.x - b.x - d.x + a.x) > epsilon ||
+    Math.abs(c.y - b.y - d.y + a.y) > epsilon
+  )
+    return null;
+  const point = {
+    x: a.x + u.x * anchor.x + v.x * anchor.y,
+    y: a.y + u.y * anchor.x + v.y * anchor.y,
+  };
+  const x = (anchor.x !== 0.5 && horizontal(u)) || (anchor.y !== 0.5 && horizontal(v));
+  const y = (anchor.x !== 0.5 && vertical(u)) || (anchor.y !== 0.5 && vertical(v));
+  return x || y
+    ? { x: x ? [{ value: point.x, edge: true }] : [], y: y ? [{ value: point.y, edge: true }] : [] }
+    : null;
+}
+
+function clientScale(mapping: Mapping): Point | null {
+  const origin = mapping.toClient({ x: 0, y: 0 }),
+    x = mapping.toClient({ x: 1, y: 0 }),
+    y = mapping.toClient({ x: 0, y: 1 });
+  if (!origin || !x || !y) return null;
+  const scale = {
+    x: Math.hypot(x.x - origin.x, x.y - origin.y),
+    y: Math.hypot(y.x - origin.x, y.y - origin.y),
+  };
+  return Number.isFinite(scale.x) && Number.isFinite(scale.y) && scale.x > 0 && scale.y > 0
+    ? scale
+    : null;
+}
+
+function correctedClient(client: Point, config: SessionConfig, centered?: boolean): Point {
+  assertPoint(client, 'Client pointer');
+  const point = config.mapping.fromClient(client),
+    scale = point && clientScale(config.mapping);
+  if (!point || !scale || !Number.isFinite(point.x) || !Number.isFinite(point.y)) {
+    config.onSnap?.([], null);
+    return client;
+  }
+  const offset = { x: point.x - config.start.x, y: point.y - config.start.y };
+  const correction = (axis: 'x' | 'y') => {
+    const tolerance = config.options.tolerance / scale[axis];
+    const alignment = snapAxis({
+      moving: config.features[axis],
+      targets: config.options.shapes ? config.targets[axis] : [],
+      offset: offset[axis],
+      tolerance,
+      grid: config.options.grid && {
+        size: config.options.grid.size,
+        origin: config.options.grid.origin[axis],
+      },
+    });
+    const spacing = config.spacing?.({ axis, offset, tolerance, centered });
+    return spacing ? prefer(alignment, spacing) : alignment;
+  };
+  const x = correction('x'),
+    y = correction('y');
+  const corrected = { x: point.x + (x?.delta ?? 0), y: point.y + (y?.delta ?? 0) };
+  const result = x?.delta || y?.delta ? config.mapping.toClient(corrected) : client;
+  config.onSnap?.(result ? [x, y] : [], result ? corrected : null);
+  return result ?? client;
+}
+
+export function createSession(config: SessionConfig): SnapSession {
+  let ended = false;
+  return {
+    snap(client, modifiers) {
+      if (ended) return client;
+      if (!config.isEnabled() || (modifiers.ignore && config.options.modifier !== 'none')) {
+        config.onSnap?.([], null);
+        return client;
+      }
+      return correctedClient(client, config, modifiers.centered);
+    },
+    end() {
+      if (ended) return;
+      ended = true;
+      config.onEnd();
+    },
+  };
+}