@rasamjs/tools 0.0.0-stage → 0.2.0

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/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>;