@rasamjs/connectors 0.0.0-stage → 0.1.0

package/src/connectors.ts

@@ -0,0 +1,248 @@
+import { Path } from '@rasamjs/core';
+import type { Svg, AnyNode } from '@rasamjs/core';
+import { Guards } from '@rasamjs/core/advanced';
+import { beginChangeGroup, deriveChanges } from '@rasamjs/core/changes';
+import { isConnector, readConnector, writeConnector } from './metadata.js';
+import {
+  connectorPort,
+  endpointCenter,
+  pathData,
+  routeConnector,
+  validateAnchor,
+  validatePoint,
+} from './routing.js';
+import type { ConnectorEndpoint, ConnectorOptions, ConnectorState } from './types.js';
+
+const owners = new WeakMap<Svg, Connectors>();
+const drawableTags = new Set([
+  'rect',
+  'circle',
+  'ellipse',
+  'line',
+  'polyline',
+  'polygon',
+  'path',
+  'text',
+  'image',
+  'foreignObject',
+  'use',
+  'g',
+  'svg',
+]);
+export class Connectors {
+  private disposed = false;
+  private readonly cleanups: (() => void)[] = [];
+  private readonly disposals = new Set<() => void>();
+  constructor(readonly drawing: Svg) {
+    if (
+      !Guards.isTransformable(drawing) ||
+      drawing.isDestroyed ||
+      drawing !== drawing.context.root ||
+      drawing.el.localName !== 'svg'
+    )
+      throw new TypeError('Connectors needs a live SVG drawing root');
+    if (owners.has(drawing)) throw new Error('Connectors is already attached to this drawing');
+    // Validate saved attachments without changing stored routing during attachment or replay.
+    this.nodes.forEach(readConnector);
+    owners.set(drawing, this);
+    this.cleanups.push(
+      deriveChanges(drawing, (event) => {
+        if (event.source === 'viewport') return;
+        for (const path of this.nodes) {
+          const state = readConnector(path);
+          if (event.nodes.some((changed) => changed === path || this.affects(changed, state)))
+            this.route(state);
+        }
+      }),
+      drawing.onDispose(() => this.destroy()),
+    );
+  }
+  get isDestroyed(): boolean {
+    return this.disposed;
+  }
+  onDispose(listener: () => void): () => void {
+    this.assertLive();
+    if (typeof listener !== 'function') throw new TypeError('Disposal listener must be a function');
+    this.disposals.add(listener);
+    return () => {
+      this.disposals.delete(listener);
+    };
+  }
+  get nodes(): readonly Path[] {
+    this.assertLive();
+    return Object.freeze(this.drawing.descendants().filter(isConnector));
+  }
+  read(path: Path): ConnectorState {
+    this.assertPath(path);
+    return readConnector(path);
+  }
+  create(options: ConnectorOptions): Path {
+    this.assertLive();
+    this.validate(options);
+    return this.edit('Create connector', () => {
+      const path = this.drawing.path({
+        d: '',
+        fill: 'none',
+        stroke: options.stroke ?? '#334155',
+        'stroke-width': options.strokeWidth ?? 2,
+      });
+      writeConnector(path, {
+        start: options.start,
+        end: options.end,
+        routing: options.routing ?? 'straight',
+      });
+      if ((options.arrows ?? 'end') !== 'none') {
+        const marker = this.drawing.createMarker({
+          viewBox: '0 0 10 10',
+          markerWidth: 6,
+          markerHeight: 6,
+          refX: 9,
+          refY: 5,
+          orient: 'auto-start-reverse',
+        });
+        marker.path({ d: 'M0 0 L10 5 L0 10 Z', fill: 'context-stroke', stroke: 'none' });
+        path.marker('end', marker);
+        if (options.arrows === 'both') path.marker('start', marker);
+      }
+      if (!this.route(readConnector(path)))
+        throw new Error('Connector needs available bounds and invertible transforms');
+      return path;
+    });
+  }
+  update(path: Path, patch: Partial<Pick<ConnectorOptions, 'start' | 'end' | 'routing'>>): void {
+    this.assertPath(path);
+    const state = { ...readConnector(path), ...patch };
+    this.validate(state);
+    this.edit('Edit connector', () => {
+      writeConnector(path, state);
+      if (!this.route(state))
+        throw new Error('Connector needs available bounds and invertible transforms');
+    });
+  }
+  remove(path: Path): void {
+    this.assertPath(path);
+    this.edit('Delete connector', () => path.remove());
+  }
+  destroy(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    owners.delete(this.drawing);
+    const failures: unknown[] = [];
+    for (const stop of [...this.cleanups.splice(0).reverse(), ...this.disposals]) {
+      try {
+        stop();
+      } catch (error) {
+        failures.push(error);
+      }
+    }
+    this.disposals.clear();
+    if (failures.length) throw new AggregateError(failures, 'Connector cleanup failed');
+  }
+  private assertLive(): void {
+    if (this.disposed) throw new Error('Connectors is destroyed');
+  }
+  private assertPath(path: Path): void {
+    this.assertLive();
+    if (
+      !isConnector(path) ||
+      path.isDestroyed ||
+      path.context !== this.drawing.context ||
+      !this.drawing.descendants().includes(path)
+    )
+      throw new TypeError('Expected a connector in this drawing');
+  }
+  private validate(options: ConnectorOptions): void {
+    if (!options || typeof options !== 'object')
+      throw new TypeError('Connector options must be an object');
+    for (const endpoint of [options.start, options.end]) this.validateEndpoint(endpoint);
+    if (options.routing !== undefined && !['straight', 'elbow'].includes(options.routing))
+      throw new TypeError('Unknown connector routing');
+    if (options.arrows !== undefined && !['none', 'end', 'both'].includes(options.arrows))
+      throw new TypeError('Unknown connector arrows');
+    if (
+      options.stroke !== undefined &&
+      (typeof options.stroke !== 'string' || !options.stroke.trim())
+    )
+      throw new TypeError('Connector stroke must be nonempty');
+    if (
+      options.strokeWidth !== undefined &&
+      (!Number.isFinite(options.strokeWidth) || options.strokeWidth < 0)
+    )
+      throw new TypeError('Connector stroke width must be nonnegative');
+  }
+  private validateEndpoint(endpoint: ConnectorEndpoint): void {
+    if (!endpoint || typeof endpoint !== 'object' || 'target' in endpoint === 'point' in endpoint)
+      throw new TypeError('Endpoint needs either a target or a point');
+    if ('point' in endpoint) {
+      validatePoint(endpoint.point);
+      return;
+    }
+    const target = endpoint.target;
+    if (
+      !Guards.isTransformable(target) ||
+      target.isDestroyed ||
+      target === this.drawing ||
+      target.context !== this.drawing.context ||
+      !this.drawing.descendants().includes(target) ||
+      target.descendants().some(isConnector)
+    )
+      throw new TypeError(
+        'Endpoint target must be a drawable shape without connectors in this drawing',
+      );
+    for (let node: AnyNode | null = target; node && node !== this.drawing; node = node.parent)
+      if (!drawableTags.has(node.el.localName))
+        throw new TypeError('Connector targets cannot be inside definitions');
+    validateAnchor(endpoint.anchor ?? 'auto');
+  }
+  private affects(changed: AnyNode, { path, start, end }: ConnectorState): boolean {
+    // Parents can move, resize, reparent or change a group's local bounds through a descendant.
+    return [
+      path,
+      ...[start, end].flatMap((endpoint) => ('target' in endpoint ? [endpoint.target] : [])),
+    ].some(
+      (node) =>
+        node === changed ||
+        node.descendants().includes(changed) ||
+        changed.descendants().includes(node),
+    );
+  }
+  private route(state: ConnectorState): boolean {
+    const { path, start, end } = state;
+    for (const endpoint of [start, end])
+      if ('target' in endpoint) {
+        if (endpoint.target.isDestroyed || !this.drawing.descendants().includes(endpoint.target))
+          return false;
+        if (endpoint.target.descendants().includes(path))
+          throw new TypeError('A connector cannot be inside its endpoint target');
+      }
+    const a = endpointCenter(start),
+      b = endpointCenter(end);
+    const from = a && b ? connectorPort(start, b) : null;
+    const to = a && b ? connectorPort(end, a) : null;
+    const inverse = path.worldMatrix().inverse();
+    if (!from || !to || !inverse) return false;
+    const d = pathData(
+      routeConnector({ start: from, end: to, routing: state.routing }).map((point) =>
+        inverse.apply(point),
+      ),
+    );
+    if (path.getAttributeValue('d') !== d) path.attrs({ d });
+    return true;
+  }
+  private edit<Result>(label: string, run: () => Result): Result {
+    const group = beginChangeGroup(this.drawing, { source: 'connectors', label });
+    let result: Result;
+    try {
+      result = group.run(run);
+    } catch (error) {
+      try {
+        group.cancel();
+      } catch (cleanup) {
+        throw new AggregateError([error, cleanup], 'Connector edit and rollback failed');
+      }
+      throw error;
+    }
+    group.end();
+    return result;
+  }
+}

package/src/editor.ts

@@ -0,0 +1,82 @@
+import type { AnyNode, Svg } from '@rasamjs/core';
+import { Connectors } from './connectors.js';
+import { ConnectorTool } from './tool.js';
+
+export interface ConnectorScope {
+  readonly drawing: Svg;
+  readonly editor: {
+    readonly paint: { readonly stroke: string; readonly strokeWidth: number };
+    readonly selection: { canSelect(node: AnyNode): boolean };
+    readonly layers: { isSelectable(node: AnyNode): boolean };
+    fail(action: string, error: unknown): void;
+  };
+  use<Value extends { destroy(): void }>(value: Value): Value;
+  registerTool(definition: {
+    id: string;
+    label: string;
+    key: string;
+    hint: string;
+    commandId: string;
+    activate(scope: ConnectorScope): { destroy(): void; key?(event: KeyboardEvent): boolean };
+  }): () => void;
+  cleanup(callback: () => void): void;
+  on(type: 'camera' | 'paint', callback: () => void): void;
+  gesture(): () => void;
+  created(node: AnyNode): void;
+  exit(): void;
+}
+export function connectorEditing() {
+  return {
+    id: 'connectors',
+    create(scope: ConnectorScope) {
+      const service = scope.use(new Connectors(scope.drawing));
+      for (const routing of ['straight', 'elbow'] as const)
+        scope.registerTool({
+          id: `connector-${routing}`,
+          commandId: `connector-${routing}`,
+          label: routing === 'straight' ? 'Connector' : 'Elbow connector',
+          key: routing === 'straight' ? 'C' : 'Shift+C',
+          hint: 'Drag between shapes to connect; hover to choose an anchor; Escape cancels.',
+          activate(current) {
+            const editor = current.editor;
+            let release = () => {},
+              dragging = false;
+            current.cleanup(() => release());
+            const tool = current.use(
+              new ConnectorTool(service, {
+                routing,
+                ...editor.paint,
+                selectable: (node) =>
+                  editor.selection.canSelect(node) && editor.layers.isSelectable(node),
+                onGesture(active) {
+                  dragging = active;
+                  release();
+                  release = active ? current.gesture() : () => {};
+                },
+                onCreate: (path) => current.created(path),
+                onError: (error) => {
+                  editor.fail('Draw connector', error);
+                  current.exit();
+                },
+                onExit: () => current.exit(),
+              }),
+            );
+            current.on('camera', () => tool.update());
+            current.on('paint', () => {
+              tool.paint = editor.paint;
+            });
+            tool.enabled = true;
+            return {
+              destroy() {},
+              key(event: KeyboardEvent) {
+                if (event.type !== 'keydown' || event.key !== 'Escape' || !dragging) return false;
+                tool.cancel();
+                return true;
+              },
+            };
+          },
+        });
+      return service;
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export { Connectors } from './connectors.js';
+export { isConnector } from './metadata.js';
+export { connectorPort, routeConnector } from './routing.js';
+export type {
+  ConnectorTarget,
+  ConnectorAnchor,
+  ConnectorSide,
+  ConnectorEndpoint,
+  ConnectorRouting,
+  ConnectorOptions,
+  ConnectorState,
+  ConnectorPort,
+  ConnectorRoute,
+} from './types.js';

package/src/metadata.ts

@@ -0,0 +1,63 @@
+import { Path } from '@rasamjs/core';
+import type { AnyNode } from '@rasamjs/core';
+import { data } from '@rasamjs/core/data';
+import type {
+  ConnectorAnchor,
+  ConnectorEndpoint,
+  ConnectorRouting,
+  ConnectorState,
+} from './types.js';
+import { validateAnchor, validatePoint } from './routing.js';
+export const endpointAttribute = (end: 'start' | 'end') => `data-rasam-connector-${end}`;
+const metadataKey = 'rasam-connector';
+interface SavedEndpoint {
+  anchor?: ConnectorAnchor;
+  point?: import('@rasamjs/core').Point;
+}
+interface SavedConnector {
+  version: 1;
+  routing: ConnectorRouting;
+  start: SavedEndpoint;
+  end: SavedEndpoint;
+}
+export function isConnector(node: AnyNode): node is Path {
+  return node instanceof Path && node.getAttributeValue('data-rasam-connector') !== undefined;
+}
+export function readConnector(path: Path): ConnectorState {
+  const saved = data(path, metadataKey) as SavedConnector;
+  if (!saved || saved.version !== 1 || !['straight', 'elbow'].includes(saved.routing))
+    throw new TypeError('Invalid connector metadata');
+  const endpoint = (end: 'start' | 'end'): ConnectorEndpoint => {
+    const value = saved[end];
+    if (!value || typeof value !== 'object')
+      throw new TypeError('Invalid connector endpoint metadata');
+    if (value.point) {
+      validatePoint(value.point);
+      return { point: { ...value.point } };
+    }
+    const target = path.references.get(endpointAttribute(end));
+    if (!target || !('toRoot' in target))
+      throw new TypeError('Connector endpoint has no bound target');
+    validateAnchor(value.anchor ?? 'auto');
+    return {
+      target: target as import('./types.js').ConnectorTarget,
+      anchor: typeof value.anchor === 'object' ? { ...value.anchor } : (value.anchor ?? 'auto'),
+    };
+  };
+  return { path, start: endpoint('start'), end: endpoint('end'), routing: saved.routing };
+}
+export function writeConnector(path: Path, state: Omit<ConnectorState, 'path'>): void {
+  const save = (end: 'start' | 'end'): SavedEndpoint => {
+    const endpoint = state[end];
+    path.reference(endpointAttribute(end), 'target' in endpoint ? endpoint.target : null, 'href');
+    return 'point' in endpoint
+      ? { point: { ...endpoint.point } }
+      : { anchor: endpoint.anchor ?? 'auto' };
+  };
+  data(path, metadataKey, {
+    version: 1,
+    routing: state.routing,
+    start: save('start'),
+    end: save('end'),
+  } satisfies SavedConnector);
+}

package/src/routing.ts

@@ -0,0 +1,127 @@
+import type { Point } from '@rasamjs/core';
+import type {
+  ConnectorAnchor,
+  ConnectorEndpoint,
+  ConnectorPort,
+  ConnectorRoute,
+  ConnectorSide,
+} from './types.js';
+
+export function validatePoint(point: Point, normalized = false): void {
+  if (
+    !point ||
+    !Number.isFinite(point.x) ||
+    !Number.isFinite(point.y) ||
+    (normalized && (point.x < 0 || point.x > 1 || point.y < 0 || point.y > 1))
+  )
+    throw new TypeError(
+      normalized ? 'Anchor point must lie between 0 and 1' : 'Connector point must be finite',
+    );
+}
+export function validateAnchor(anchor: ConnectorAnchor): void {
+  if (typeof anchor === 'string') {
+    if (!['auto', 'top', 'right', 'bottom', 'left'].includes(anchor))
+      throw new TypeError('Unknown connector anchor');
+  } else validatePoint(anchor, true);
+}
+export function endpointCenter(endpoint: ConnectorEndpoint): Point | null {
+  if ('point' in endpoint) return endpoint.point;
+  const bounds = endpoint.target.bounds();
+  if (!('box' in bounds)) return null;
+  const { x, y, width, height } = bounds.box;
+  return endpoint.target.toRoot({ x: x + width / 2, y: y + height / 2 });
+}
+/** Resolve on the local box, then map into drawing units, retaining rotated anchors. */
+export function connectorPort(endpoint: ConnectorEndpoint, toward: Point): ConnectorPort | null {
+  if ('point' in endpoint) return { point: endpoint.point, direction: { x: 0, y: 0 } };
+  const { target, anchor = 'auto' } = endpoint;
+  const bounds = target.bounds();
+  if (!('box' in bounds)) return null;
+  const { x, y, width, height } = bounds.box;
+  const center = { x: x + width / 2, y: y + height / 2 };
+  let side: ConnectorSide = 'right';
+  let point: Point;
+  if (typeof anchor === 'object') point = { x: x + anchor.x * width, y: y + anchor.y * height };
+  else if (anchor !== 'auto') {
+    side = anchor;
+    point = {
+      x: side === 'left' ? x : side === 'right' ? x + width : center.x,
+      y: side === 'top' ? y : side === 'bottom' ? y + height : center.y,
+    };
+  } else {
+    const local = target.fromRoot(toward);
+    if (!local) return null;
+    const dx = local.x - center.x,
+      dy = local.y - center.y;
+    const ratio = Math.max(
+      width ? Math.abs(dx) / (width / 2) : Infinity,
+      height ? Math.abs(dy) / (height / 2) : Infinity,
+    );
+    point =
+      ratio > 0 && Number.isFinite(ratio)
+        ? { x: center.x + dx / ratio, y: center.y + dy / ratio }
+        : { x: x + width, y: center.y };
+    side =
+      Math.abs(point.x - center.x) / (width || 1) >= Math.abs(point.y - center.y) / (height || 1)
+        ? dx < 0
+          ? 'left'
+          : 'right'
+        : dy < 0
+          ? 'top'
+          : 'bottom';
+  }
+  const root = target.toRoot(point);
+  const localDirection =
+    typeof anchor === 'object'
+      ? { x: point.x - center.x, y: point.y - center.y }
+      : {
+          x: side === 'left' ? -1 : side === 'right' ? 1 : 0,
+          y: side === 'top' ? -1 : side === 'bottom' ? 1 : 0,
+        };
+  const offset = target.toRoot({ x: point.x + localDirection.x, y: point.y + localDirection.y });
+  const dx = offset.x - root.x,
+    dy = offset.y - root.y;
+  return {
+    point: root,
+    direction:
+      Math.abs(dx) >= Math.abs(dy) ? { x: Math.sign(dx), y: 0 } : { x: 0, y: Math.sign(dy) },
+  };
+}
+/** Manhattan routing with short outward leads. It does not avoid other shapes. */
+export function routeConnector({ start, end, routing }: ConnectorRoute): readonly Point[] {
+  if (routing === 'straight') return [start.point, end.point];
+  if (routing !== 'elbow') throw new TypeError('Unknown connector routing');
+  const lead = (port: ConnectorPort) => ({
+    x: port.point.x + port.direction.x * 16,
+    y: port.point.y + port.direction.y * 16,
+  });
+  const a = lead(start),
+    b = lead(end);
+  const horizontal =
+    start.direction.x !== 0 || (!start.direction.y && Math.abs(b.x - a.x) >= Math.abs(b.y - a.y));
+  const endHorizontal = end.direction.x !== 0 || (!end.direction.y && horizontal);
+  const bends =
+    horizontal !== endHorizontal
+      ? [horizontal ? { x: b.x, y: a.y } : { x: a.x, y: b.y }]
+      : horizontal
+        ? [
+            { x: (a.x + b.x) / 2, y: a.y },
+            { x: (a.x + b.x) / 2, y: b.y },
+          ]
+        : [
+            { x: a.x, y: (a.y + b.y) / 2 },
+            { x: b.x, y: (a.y + b.y) / 2 },
+          ];
+  return [start.point, a, ...bends, b, end.point].filter(
+    (point, index, points) =>
+      index === 0 || point.x !== points[index - 1].x || point.y !== points[index - 1].y,
+  );
+}
+export function pathData(points: readonly Point[]): string {
+  return points
+    .map(
+      (point, index) =>
+        `${index ? 'L' : 'M'}${Number(point.x.toFixed(6))} ${Number(point.y.toFixed(6))}`,
+    )
+    .join(' ');
+}

package/src/tool-surface.ts

@@ -0,0 +1,96 @@
+import { Matrix } from '@rasamjs/core';
+import type { Point, Svg } from '@rasamjs/core';
+const namespace = 'http://www.w3.org/2000/svg';
+export function svg<Tag extends keyof SVGElementTagNameMap>(
+  document: Document,
+  tag: Tag,
+  attributes: Record<string, string | number> = {},
+): SVGElementTagNameMap[Tag] {
+  const element = document.createElementNS(namespace, tag);
+  for (const [name, value] of Object.entries(attributes)) element.setAttribute(name, String(value));
+  return element;
+}
+/** Connector UI lives outside the managed SVG; none of it can enter export/history. */
+export class ToolSurface {
+  readonly element: SVGSVGElement;
+  readonly view: Window & typeof globalThis;
+  private readonly cleanups: (() => void)[] = [];
+  private pending: number | null = null;
+  private disposed = false;
+  constructor(
+    readonly drawing: Svg,
+    private readonly render: () => void,
+  ) {
+    if (drawing.isDestroyed || !drawing.el.isConnected || !drawing.el.parentElement)
+      throw new TypeError('Connector tool needs a mounted drawing');
+    this.view = drawing.el.ownerDocument.defaultView!;
+    this.element = svg(drawing.el.ownerDocument, 'svg', {
+      class: 'rasam-connector-tool',
+      width: '100%',
+      height: '100%',
+      'aria-label': 'Connector tool',
+    });
+    Object.assign(this.element.style, {
+      position: 'absolute',
+      inset: '0',
+      overflow: 'visible',
+      pointerEvents: 'none',
+      touchAction: 'none',
+      zIndex: '25',
+    });
+    drawing.el.parentElement.append(this.element);
+    this.listen(this.view, 'resize', this.schedule);
+    this.listen(this.view, 'scroll', this.schedule, true);
+    const mutation = new this.view.MutationObserver(this.schedule);
+    mutation.observe(drawing.el, { attributes: true });
+    const resize = new this.view.ResizeObserver(this.schedule);
+    resize.observe(drawing.el);
+    this.cleanup(() => {
+      mutation.disconnect();
+      resize.disconnect();
+    });
+    this.cleanup(drawing.onDispose(() => this.destroy()));
+  }
+  get isDestroyed(): boolean {
+    return this.disposed;
+  }
+  cleanup(stop: () => void): void {
+    this.cleanups.push(stop);
+  }
+  listen(target: EventTarget, type: string, listener: EventListener, capture = false): void {
+    target.addEventListener(type, listener, capture);
+    this.cleanup(() => target.removeEventListener(type, listener, capture));
+  }
+  fromRoot(point: Point): Point | null {
+    const client = this.drawing.toClient(point),
+      m = this.element.getScreenCTM?.();
+    return client && m
+      ? (new Matrix(m.a, m.b, m.c, m.d, m.e, m.f).inverse()?.apply(client) ?? null)
+      : null;
+  }
+  readonly schedule = (): void => {
+    if (!this.disposed && this.pending === null)
+      this.pending = this.view.requestAnimationFrame(() => {
+        this.pending = null;
+        this.render();
+      });
+  };
+  update(): void {
+    if (!this.disposed) this.render();
+  }
+  destroy(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    if (this.pending !== null) this.view.cancelAnimationFrame(this.pending);
+    const failures: unknown[] = [];
+    for (const stop of this.cleanups.splice(0).reverse()) {
+      try {
+        stop();
+      } catch (error) {
+        failures.push(error);
+      }
+    }
+    this.element.remove();
+    if (failures.length) throw new AggregateError(failures, 'Connector tool cleanup failed');
+  }
+}