@rasamjs/tools 0.0.0-stage → 0.1.0

package/src/snapping/snapper.ts

@@ -0,0 +1,147 @@
+import type { Box, Point, Svg } from '@rasamjs/core';
+import { Guards } from '@rasamjs/core/advanced';
+import { boxLines, targetLines } from './lines.js';
+import type { Features } from './lines.js';
+import { assertPoint, resolveOptions } from './options.js';
+import type { ResolvedOptions } from './options.js';
+import { createSession, resizeLines } from './session.js';
+import { measureTargets, movingBox, validateNodes } from './targets.js';
+import type { SnapperOptions, SnapRequest, SnapSession } from './types.js';
+import { guideReader } from './guides.js';
+import { GuideOverlay } from './overlay.js';
+import { createSpacing } from './spacing.js';
+
+/** Owns snapping state for one mounted drawing. */
+export class Snapper {
+  private enabledState = true;
+  private readonly overlay: GuideOverlay;
+  private readonly stopDisposal: () => void;
+  private readonly options: ResolvedOptions;
+  private active: SnapSession | null = null;
+  private sessionVersion = 0;
+  private disposed = false;
+
+  constructor(
+    private readonly drawing: Svg,
+    options: SnapperOptions = {},
+  ) {
+    if (
+      !Guards.isTransformable(drawing) ||
+      drawing.isDestroyed ||
+      drawing.el.localName !== 'svg' ||
+      !drawing.el.isConnected ||
+      !drawing.el.ownerDocument.defaultView
+    )
+      throw new TypeError('Snapper needs a live, mounted rasam SVG drawing');
+    this.options = resolveOptions(options);
+    this.overlay = new GuideOverlay(drawing, this.options.stroke, this.options.gapStroke);
+    this.stopDisposal = 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;
+  }
+
+  begin(request: SnapRequest): SnapSession | null {
+    const version = ++this.sessionVersion;
+    this.active?.end();
+    if (this.disposed || !this.enabled) return null;
+    if (!request || !['move', 'resize', 'point'].includes(request.kind))
+      throw new TypeError('Unknown snap request kind');
+    assertPoint(request.client, 'Start pointer');
+    if (request.kind !== 'point') validateNodes(request.nodes, this.drawing);
+    const start = this.drawing.fromClient(request.client);
+    if (!start) return null;
+    const geometry = this.geometry(request, start);
+    if (!geometry) return null;
+    const nodes = Object.freeze(request.kind === 'point' ? [] : [...new Set(request.nodes)]);
+    const targets = targetLines(
+      this.options.shapes || this.options.spacing
+        ? measureTargets(this.drawing, nodes, this.options)
+        : [],
+    );
+    if (version !== this.sessionVersion || this.disposed || !this.enabled) return null;
+    const spacing = this.options.spacing
+      ? createSpacing({
+          ...geometry,
+          targets: targets.boxes,
+          kind: request.kind,
+          centered: request.kind === 'resize' && request.centered,
+        })
+      : null;
+    if (
+      !this.options.grid &&
+      !(this.options.shapes && (targets.x.length || targets.y.length)) &&
+      !spacing
+    )
+      return null;
+    const read = guideReader(this.drawing, request, targets.boxes);
+    this.active = createSession({
+      start: { x: start.x, y: start.y },
+      features: geometry.features,
+      spacing,
+      targets,
+      mapping: this.drawing,
+      options: this.options,
+      isEnabled: () => this.enabled && !this.disposed,
+      onEnd: () => {
+        this.active = null;
+        this.overlay.clear();
+      },
+      onSnap: (matches, point) => {
+        if (version !== this.sessionVersion || this.disposed) return;
+        if (!point || !matches.some((match) => match)) this.overlay.clear();
+        else this.overlay.show(() => read(matches, point));
+      },
+    });
+    return this.active;
+  }
+
+  private geometry(request: SnapRequest, start: Point): { box: Box; features: Features } | null {
+    const box =
+      request.kind === 'point'
+        ? { ...start, width: 0, height: 0 }
+        : movingBox(request.nodes, this.drawing);
+    if (!box) return null;
+    if (request.kind !== 'resize') return { box, features: boxLines(box) };
+    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)
+    )
+      throw new TypeError('Resize snapping needs a unit-frame edge or corner anchor');
+    if (!Array.isArray(request.corners) || request.corners.length !== 4)
+      throw new TypeError('Resize snapping needs four frame corners');
+    const corners = request.corners.map((point) => {
+      assertPoint(point, 'Frame corner');
+      return this.drawing.fromClient(point);
+    });
+    const features = corners.every((point) => point !== null)
+      ? resizeLines(corners as Point[], request.anchor)
+      : null;
+    return features ? { box, features } : null;
+  }
+
+  destroy(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.active?.end();
+    this.overlay.destroy();
+    this.stopDisposal();
+  }
+}

package/src/snapping/spacing.ts

@@ -0,0 +1,157 @@
+import type { Box, Point } from '@rasamjs/core';
+import type { Features, Match } from './lines.js';
+import { lowerBound } from './lines.js';
+
+type Axis = 'x' | 'y';
+type Side = 'before' | 'after';
+const extent = { x: 'width', y: 'height' } as const;
+const end = (box: Box, axis: Axis) => box[axis] + box[extent[axis]];
+const across = (axis: Axis): Axis => (axis === 'x' ? 'y' : 'x');
+const overlaps = (a: Box, b: Box, axis: Axis) => a[axis] <= end(b, axis) && b[axis] <= end(a, axis);
+const middle = (a: Box, b: Box, axis: Axis) =>
+  (Math.max(a[axis], b[axis]) + Math.min(end(a, axis), end(b, axis))) / 2;
+
+export interface Gap {
+  readonly from: number;
+  readonly to: number;
+  readonly at: number;
+  readonly moving?: 'from' | 'to';
+  readonly neighbor?: number;
+}
+interface Setup {
+  readonly box: Box;
+  readonly targets: readonly Box[];
+  readonly features: Features;
+  readonly kind: 'move' | 'resize' | 'point';
+  readonly centered?: boolean;
+}
+export type Spacing = (request: {
+  readonly axis: Axis;
+  readonly offset: Point;
+  readonly tolerance: number;
+  readonly centered?: boolean;
+}) => Match | null;
+
+/**
+ * Only gaps after the furthest preceding overlapping box are unobstructed. Boxes that
+ * contain the next box on this axis are backgrounds, not obstructions.
+ */
+function referenceGaps(targets: readonly Box[], axis: Axis): Gap[] {
+  const gaps: Gap[] = [];
+  // Far edges ascending; equal edges scan the earliest document target first.
+  const ordered = targets
+    .map((box, order) => ({ box, order, value: end(box, axis) }))
+    .sort((a, b) => a.value - b.value || b.order - a.order);
+  for (const next of targets)
+    for (let index = lowerBound(ordered, end(next, axis)) - 1; index >= 0; index--) {
+      const previous = ordered[index];
+      if (previous.box[axis] >= next[axis] || !overlaps(previous.box, next, across(axis))) continue;
+      if (previous.value < next[axis])
+        gaps.push({
+          from: previous.value,
+          to: next[axis],
+          at: middle(previous.box, next, across(axis)),
+        });
+      break;
+    }
+  return gaps;
+}
+
+function projectedBox(setup: Setup, offset: Point, centered = setup.centered): Box {
+  const box = { ...setup.box };
+  for (const axis of ['x', 'y'] as const) {
+    if (setup.kind !== 'resize') {
+      box[axis] += offset[axis];
+      continue;
+    }
+    const feature = setup.features[axis][0];
+    if (!feature) continue;
+    const start = setup.box[axis],
+      finish = end(setup.box, axis);
+    const fixed =
+      Math.abs(feature.value - start) < Math.abs(feature.value - finish) ? finish : start;
+    const opposite = fixed - (centered ? offset[axis] : 0),
+      active = feature.value + offset[axis];
+    box[axis] = Math.min(active, opposite);
+    box[extent[axis]] = Math.abs(active - opposite);
+  }
+  return box;
+}
+
+/** Targets that contain the box on this axis (backgrounds, panels) are not neighbors. */
+function neighbors(box: Box, targets: readonly Box[], axis: Axis): [number, number] {
+  let left = -1,
+    right = -1;
+  targets.forEach((target, index) => {
+    if (!overlaps(box, target, across(axis))) return;
+    const before = target[axis] <= box[axis],
+      after = end(target, axis) >= end(box, axis);
+    if (before && after) return;
+    if (before && (left < 0 || end(target, axis) > end(targets[left], axis))) left = index;
+    if (after && (right < 0 || target[axis] < targets[right][axis])) right = index;
+  });
+  return [left, right];
+}
+
+/** Snapshot once; pointer queries scan cached boxes/gaps without any DOM reads. */
+export function createSpacing(input: Setup): Spacing | null {
+  const setup = {
+    ...input,
+    box: { ...input.box },
+    targets: input.targets.map((box) => ({ ...box })),
+  };
+  const references = { x: referenceGaps(setup.targets, 'x'), y: referenceGaps(setup.targets, 'y') };
+  if (!references.x.length && !references.y.length) return null;
+  return ({ axis, offset, tolerance, centered = setup.centered }) => {
+    const resizing = setup.kind === 'resize',
+      feature = setup.features[axis][0];
+    if (resizing && !feature) return null;
+    const box = projectedBox(setup, offset, centered),
+      [left, right] = neighbors(box, setup.targets, axis);
+    const active = feature && feature.value + offset[axis];
+    const dragged: Side = resizing && active! > box[axis] ? 'after' : 'before';
+    let best: Match | null = null;
+    const mark = (next: Box, side: Side): Gap => {
+      const index = side === 'before' ? left : right,
+        neighbor = setup.targets[index];
+      return {
+        from: side === 'before' ? end(neighbor, axis) : end(next, axis),
+        to: side === 'before' ? next[axis] : neighbor[axis],
+        at: middle(next, neighbor, across(axis)),
+        moving: side === 'before' ? 'to' : 'from',
+        neighbor: index,
+      };
+    };
+    const offer = (delta: number, side: Side, reference?: Gap) => {
+      if (Math.abs(delta) > tolerance || (best && Math.abs(delta) >= Math.abs(best.delta))) return;
+      const next = projectedBox(setup, { ...offset, [axis]: offset[axis] + delta }, centered);
+      const target = side === 'before' ? next[axis] : end(next, axis);
+      if (resizing && Math.abs(active! + delta - target) > 1e-7) return;
+      const gaps = reference
+        ? [reference, mark(next, side)]
+        : [mark(next, 'before'), mark(next, 'after')];
+      const length = gaps[0].to - gaps[0].from;
+      if (
+        length <= 0 ||
+        gaps.some((gap) => Math.abs(gap.to - gap.from - length) > 1e-7 * Math.max(1, length))
+      )
+        return;
+      best = { delta, target, order: side === 'before' ? left : right, grid: false, gaps };
+    };
+    if (left >= 0 && right >= 0 && left !== right) {
+      const before = box[axis] - end(setup.targets[left], axis),
+        after = setup.targets[right][axis] - end(box, axis);
+      let delta = (after - before) / 2;
+      if (resizing) delta = centered ? 0 : after - before;
+      offer(delta, dragged);
+    }
+    for (const reference of references[axis]) {
+      const length = reference.to - reference.from;
+      if (left >= 0 && (!resizing || dragged === 'before'))
+        offer(end(setup.targets[left], axis) + length - box[axis], 'before', reference);
+      if (right >= 0 && (!resizing || dragged === 'after'))
+        offer(setup.targets[right][axis] - length - end(box, axis), 'after', reference);
+    }
+    return best;
+  };
+}

package/src/snapping/targets.ts

@@ -0,0 +1,79 @@
+import type { AnyNode, Box, Svg } from '@rasamjs/core';
+import { Guards } from '@rasamjs/core/advanced';
+import { boundsIn } from '@rasamjs/core/viewport';
+import type { ResolvedOptions } from './options.js';
+
+export function validateNodes(nodes: readonly AnyNode[], drawing: Svg): void {
+  if (!Array.isArray(nodes)) throw new TypeError('Snap nodes must be an array');
+  for (const node of nodes)
+    if (
+      !Guards.isTransformable(node) ||
+      node.isDestroyed ||
+      node === drawing ||
+      node.context !== drawing.context ||
+      !drawing.el.contains(node.el)
+    )
+      throw new TypeError('Snap nodes must be live shapes inside this drawing');
+}
+
+export function movingBox(nodes: readonly AnyNode[], drawing: Svg): Box | null {
+  let left = Infinity,
+    top = Infinity,
+    right = -Infinity,
+    bottom = -Infinity;
+  for (const node of nodes) {
+    const bounds = boundsIn(node, drawing);
+    if (bounds.status === 'unavailable') return null;
+    if (!('box' in bounds)) continue;
+    const box = bounds.box;
+    left = Math.min(left, box.x);
+    top = Math.min(top, box.y);
+    right = Math.max(right, box.x + box.width);
+    bottom = Math.max(bottom, box.y + box.height);
+  }
+  return left === Infinity ? null : { x: left, y: top, width: right - left, height: bottom - top };
+}
+
+function visible(node: AnyNode): boolean {
+  const view = node.el.ownerDocument.defaultView!;
+  const visibility = view.getComputedStyle(node.el).visibility;
+  if (visibility === 'hidden' || visibility === 'collapse') return false;
+  for (let element: Element | null = node.el; element; element = element.parentElement)
+    if (view.getComputedStyle(element).display === 'none') return false;
+  return true;
+}
+
+export function measureTargets(
+  drawing: Svg,
+  nodes: readonly AnyNode[],
+  options: ResolvedOptions,
+): Box[] {
+  const candidates = options.targets
+    ? options.targets(nodes)
+    : nodes.length
+      ? nodes.flatMap((node) => node.parent?.children ?? [])
+      : drawing.children;
+  const eligible = new Set<AnyNode>();
+  for (const node of candidates) {
+    if (
+      !Guards.isTransformable(node) ||
+      node.isDestroyed ||
+      node.context !== drawing.context ||
+      !drawing.el.contains(node.el) ||
+      nodes.some((selected) => node.el.contains(selected.el) || selected.el.contains(node.el)) ||
+      !visible(node)
+    )
+      continue;
+    eligible.add(node);
+  }
+  // All eligible nodes are attached to the same document; bit 4 means FOLLOWING.
+  const ordered = [...eligible].sort((a, b) =>
+    a === b ? 0 : a.el.compareDocumentPosition(b.el) & 4 ? -1 : 1,
+  );
+  const boxes: Box[] = [];
+  for (const node of ordered) {
+    const bounds = boundsIn(node, drawing);
+    if ('box' in bounds) boxes.push(bounds.box);
+  }
+  return boxes;
+}

package/src/snapping/types.ts

@@ -0,0 +1,27 @@
+import type { AnyNode, Point } from '@rasamjs/core';
+
+export interface SnapperOptions {
+  readonly tolerance?: number;
+  readonly shapes?: boolean;
+  readonly spacing?: boolean;
+  readonly grid?: number | { readonly size: number; readonly origin?: Point } | null;
+  readonly targets?: (nodes: readonly AnyNode[]) => Iterable<AnyNode>;
+  readonly modifier?: 'ctrl' | 'none';
+  readonly style?: { readonly stroke?: string; readonly gapStroke?: string };
+}
+
+export type SnapRequest =
+  | { readonly kind: 'point'; readonly client: Point }
+  | {
+      readonly kind: 'move' | 'resize';
+      readonly nodes: readonly AnyNode[];
+      readonly client: Point;
+      readonly corners: readonly Point[];
+      readonly anchor?: Point;
+      readonly centered?: boolean;
+    };
+
+export interface SnapSession {
+  snap(client: Point, modifiers: { readonly ignore: boolean; readonly centered?: boolean }): Point;
+  end(): void;
+}

package/src/snapping.ts

@@ -0,0 +1,3 @@
+/** Opt-in snapping tools for rasam drawings. */
+export { Snapper } from './snapping/snapper.js';
+export type { SnapperOptions, SnapRequest, SnapSession } from './snapping/types.js';