@rasamjs/connectors 0.0.0-stage → 0.2.0

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

package/src/tool.ts

@@ -0,0 +1,367 @@
+import type { AnyNode, Path, Point } from '@rasamjs/core';
+import { Guards, Registry } from '@rasamjs/core/advanced';
+import { observeChanges } from '@rasamjs/core/changes';
+import type { Connectors } from './connectors.js';
+import { isConnector } from './metadata.js';
+import { connectorPort, endpointCenter, pathData, portsOf, routeConnector } from './routing.js';
+import { ToolSurface, svg } from './tool-surface.js';
+import type {
+  ConnectorEndpoint,
+  ConnectorOptions,
+  ConnectorSide,
+  ConnectorTarget,
+} from './types.js';
+
+export interface ConnectorToolOptions extends Pick<
+  ConnectorOptions,
+  'routing' | 'arrows' | 'stroke' | 'strokeWidth'
+> {
+  readonly selectable?: (node: ConnectorTarget) => boolean;
+  readonly onCreate?: (path: Path) => void;
+  readonly onGesture?: (active: boolean) => void;
+  readonly onError?: (error: unknown) => void;
+  readonly onExit?: () => void;
+}
+interface Press {
+  id: number;
+  start: ConnectorEndpoint;
+  end: ConnectorEndpoint;
+}
+interface Hover {
+  target: ConnectorTarget;
+  endpoint: ConnectorEndpoint;
+}
+const sides: readonly ConnectorSide[] = ['top', 'right', 'bottom', 'left'];
+/** A target's ports replace its four side hints. */
+const hints = (target: ConnectorTarget): ConnectorEndpoint[] => {
+  const ports = portsOf(target);
+  return ports.length
+    ? ports.map((port) => ({ target, port: port.name }))
+    : sides.map((anchor) => ({ target, anchor }));
+};
+const same = (hint: ConnectorEndpoint, endpoint: ConnectorEndpoint): boolean =>
+  'port' in hint
+    ? 'port' in endpoint && endpoint.port === hint.port
+    : 'anchor' in hint && 'anchor' in endpoint && endpoint.anchor === hint.anchor;
+
+/**
+ * Drag from a hinted anchor, port or free point. Within twelve client pixels of a hint,
+ * the end snaps to it. The document is written only on release.
+ */
+export class ConnectorTool {
+  private readonly surface: ToolSurface;
+  private active = false;
+  private press: Press | null = null;
+  private hover: Hover | null = null;
+  private options: ConnectorToolOptions;
+  constructor(
+    readonly connectors: Connectors,
+    options: ConnectorToolOptions = {},
+  ) {
+    if (connectors.isDestroyed) throw new Error('Connectors is destroyed');
+    for (const name of ['selectable', 'onCreate', 'onGesture', 'onError', 'onExit'] as const)
+      if (options[name] !== undefined && typeof options[name] !== 'function')
+        throw new TypeError(`${name} must be a function`);
+    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');
+    this.options = { ...options };
+    this.surface = new ToolSurface(connectors.drawing, () => this.render());
+    this.surface.cleanup(connectors.onDispose(() => this.destroy()));
+    this.surface.cleanup(
+      observeChanges(connectors.drawing, () => {
+        const attached = (endpoint: ConnectorEndpoint) =>
+          'point' in endpoint ||
+          (!endpoint.target.isDestroyed && connectors.drawing.el.contains(endpoint.target.el));
+        if (this.press && (!attached(this.press.start) || !attached(this.press.end))) this.cancel();
+        if (this.hover && !attached(this.hover.endpoint)) this.hover = null;
+        this.surface.schedule();
+      }),
+    );
+    this.surface.listen(this.surface.element, 'pointerdown', this.down as EventListener);
+    this.surface.listen(this.surface.element, 'pointermove', this.over as EventListener);
+    this.surface.listen(this.surface.element, 'pointerleave', () => {
+      if (!this.press) {
+        this.hover = null;
+        this.update();
+      }
+    });
+    this.surface.listen(this.surface.view, 'pointermove', this.move as EventListener);
+    this.surface.listen(this.surface.view, 'pointerup', this.up as EventListener);
+    this.surface.listen(this.surface.view, 'pointercancel', this.lost as EventListener);
+    this.surface.listen(this.surface.element, 'lostpointercapture', this.lost as EventListener);
+    this.surface.listen(this.surface.view, 'blur', () => this.cancel());
+    this.surface.listen(
+      this.surface.view,
+      'keydown',
+      ((event: KeyboardEvent) => {
+        if (
+          !this.enabled ||
+          event.key !== 'Escape' ||
+          event.defaultPrevented ||
+          !this.acceptsKeyboard(event)
+        )
+          return;
+        event.preventDefault();
+        event.stopPropagation();
+        if (this.press) this.cancel();
+        else {
+          this.enabled = false;
+          this.options.onExit?.();
+        }
+      }) as EventListener,
+      true,
+    );
+    this.surface.cleanup(() => {
+      this.active = false;
+      this.cancel();
+    });
+  }
+  get isDestroyed(): boolean {
+    return this.surface.isDestroyed;
+  }
+  get enabled(): boolean {
+    return this.active;
+  }
+  get paint(): { readonly stroke: string; readonly strokeWidth: number } {
+    return Object.freeze({
+      stroke: this.options.stroke ?? '#334155',
+      strokeWidth: this.options.strokeWidth ?? 2,
+    });
+  }
+  set paint(paint: { readonly stroke: string; readonly strokeWidth: number }) {
+    if (this.isDestroyed) throw new Error('Connector tool is destroyed');
+    if (
+      !paint ||
+      typeof paint.stroke !== 'string' ||
+      !paint.stroke.trim() ||
+      !Number.isFinite(paint.strokeWidth) ||
+      paint.strokeWidth < 0
+    )
+      throw new TypeError('Invalid connector paint');
+    this.options = { ...this.options, stroke: paint.stroke, strokeWidth: paint.strokeWidth };
+    this.update();
+  }
+  set enabled(value: boolean) {
+    if (this.isDestroyed || this.connectors.isDestroyed)
+      throw new Error('Connector tool is destroyed');
+    if (typeof value !== 'boolean') throw new TypeError('Connector tool enabled must be boolean');
+    if (this.active === value) return;
+    this.cancel();
+    this.active = value;
+    this.hover = null;
+    this.surface.element.style.pointerEvents = value ? 'all' : 'none';
+    this.surface.element.style.cursor = value ? 'crosshair' : '';
+    this.update();
+  }
+  update(): this {
+    this.surface.update();
+    return this;
+  }
+  destroy(): void {
+    this.surface.destroy();
+  }
+  cancel(): void {
+    const press = this.press;
+    this.press = null;
+    if (press) {
+      if (this.surface.element.hasPointerCapture(press.id))
+        this.surface.element.releasePointerCapture(press.id);
+      this.options.onGesture?.(false);
+    }
+    this.update();
+  }
+  private acceptsKeyboard(event: KeyboardEvent): boolean {
+    const document = this.surface.element.ownerDocument,
+      active = document.activeElement;
+    return (
+      !document.querySelector('dialog[open],[role="dialog"][aria-modal="true"]') &&
+      !(event.target as Element)?.closest?.(
+        'input,textarea,select,[contenteditable]:not([contenteditable="false"])',
+      ) &&
+      (active === document.body ||
+        (!!active && this.surface.element.parentElement!.contains(active)))
+    );
+  }
+  private attempt(run: () => void): void {
+    try {
+      run();
+    } catch (error) {
+      try {
+        this.cancel();
+      } catch (cleanup) {
+        error = new AggregateError([error, cleanup], 'Connector tool and cleanup failed');
+      }
+      if (this.options.onError) this.options.onError(error);
+      else throw error;
+    }
+  }
+  private pick(event: PointerEvent): ConnectorEndpoint | null {
+    const drawing = this.connectors.drawing;
+    const point = drawing.fromClient({ x: event.clientX, y: event.clientY });
+    if (!point) return null;
+    const accepts = (node: unknown): node is ConnectorTarget =>
+      Guards.isTransformable(node) &&
+      node !== drawing &&
+      drawing.el.contains(node.el) &&
+      !isConnector(node) &&
+      !node.descendants().some(isConnector) &&
+      this.options.selectable?.(node as ConnectorTarget) !== false;
+    let target: ConnectorTarget | undefined;
+    // Hit testing never reports groups, so a rejected hit such as a component's rendered
+    // child resolves to its nearest accepted ancestor.
+    for (const element of drawing.el.ownerDocument.elementsFromPoint(event.clientX, event.clientY))
+      for (
+        let node: AnyNode | null | undefined = Registry.wrapper(element as SVGElement);
+        node && !target;
+        node = node.parent
+      )
+        if (accepts(node)) target = node;
+    // The outer half of an anchor hint can lie just outside its shape's hit area.
+    const previous = this.hover?.target;
+    if (
+      !target &&
+      previous &&
+      !previous.isDestroyed &&
+      drawing.el.contains(previous.el) &&
+      this.options.selectable?.(previous) !== false
+    ) {
+      const nearHint = hints(previous).some((hint) => {
+        const port = connectorPort(hint, point);
+        const client = port && drawing.toClient(port.point);
+        return client && Math.hypot(client.x - event.clientX, client.y - event.clientY) < 12;
+      });
+      if (nearHint) target = previous;
+    }
+    this.hover = null;
+    if (!target) return { point };
+    let endpoint: ConnectorEndpoint = { target, anchor: 'auto' };
+    let nearest = 12;
+    for (const hint of hints(target)) {
+      const port = connectorPort(hint, point);
+      const client = port && drawing.toClient(port.point);
+      if (!client) continue;
+      const distance = Math.hypot(client.x - event.clientX, client.y - event.clientY);
+      if (distance < nearest) {
+        nearest = distance;
+        endpoint = hint;
+      }
+    }
+    this.hover = { target, endpoint };
+    return endpoint;
+  }
+  private readonly over = (event: PointerEvent): void => {
+    if (!this.enabled || this.press || !event.isPrimary || event.buttons) return;
+    this.attempt(() => {
+      this.pick(event);
+      this.update();
+    });
+  };
+  private readonly down = (event: PointerEvent): void => {
+    if (
+      !this.enabled ||
+      this.press ||
+      !event.isPrimary ||
+      event.button !== 0 ||
+      event.defaultPrevented
+    )
+      return;
+    this.attempt(() => {
+      const endpoint = this.pick(event);
+      if (!endpoint) return;
+      this.surface.element.setPointerCapture(event.pointerId);
+      this.press = { id: event.pointerId, start: endpoint, end: endpoint };
+      event.preventDefault();
+      event.stopPropagation();
+      this.options.onGesture?.(true);
+      this.update();
+    });
+  };
+  private readonly move = (event: PointerEvent): void => {
+    if (event.pointerId !== this.press?.id) return;
+    this.attempt(() => {
+      const endpoint = this.pick(event);
+      if (endpoint && this.press) this.press.end = endpoint;
+      this.update();
+    });
+  };
+  private readonly up = (event: PointerEvent): void => {
+    if (event.pointerId !== this.press?.id) return;
+    this.attempt(() => {
+      const press = this.press!,
+        end = this.pick(event) ?? press.end;
+      this.cancel();
+      const a = endpointCenter(press.start),
+        b = endpointCenter(end);
+      if (!a || !b || Math.hypot(a.x - b.x, a.y - b.y) < 1e-6) return;
+      const path = this.connectors.create({ ...this.options, start: press.start, end });
+      this.options.onCreate?.(path);
+    });
+  };
+  private readonly lost = (event: PointerEvent): void => {
+    if (event.pointerId === this.press?.id) this.cancel();
+  };
+  private render(): void {
+    const overlay = this.surface.element;
+    overlay.replaceChildren();
+    if (!this.enabled) return;
+    const document = overlay.ownerDocument;
+    if (this.hover)
+      for (const hint of hints(this.hover.target)) {
+        const port = connectorPort(hint, { x: 0, y: 0 });
+        const point = port && this.surface.fromRoot(port.point);
+        const active = same(hint, this.hover.endpoint);
+        if (point)
+          overlay.append(
+            svg(document, 'circle', {
+              cx: point.x,
+              cy: point.y,
+              r: 5,
+              fill: active ? '#2563eb' : 'white',
+              stroke: '#2563eb',
+              'stroke-width': 1.5,
+              'pointer-events': 'none',
+              ...('port' in hint
+                ? { 'data-connector-port': hint.port }
+                : { 'data-connector-anchor': (hint as { anchor: ConnectorSide }).anchor }),
+              ...(active ? { 'data-connector-active': '' } : {}),
+            }),
+          );
+      }
+    if (!this.press) return;
+    const { start, end } = this.press;
+    const a = endpointCenter(start),
+      b = endpointCenter(end);
+    const from = a && b ? connectorPort(start, b) : null,
+      to = a && b ? connectorPort(end, a) : null;
+    if (!from || !to) return;
+    const points = routeConnector({
+      start: from,
+      end: to,
+      routing: this.options.routing ?? 'straight',
+    }).map((point) => this.surface.fromRoot(point));
+    if (points.some((point) => !point)) return;
+    overlay.append(
+      svg(document, 'path', {
+        d: pathData(points as Point[]),
+        fill: 'none',
+        stroke: this.options.stroke ?? '#334155',
+        'stroke-width': this.options.strokeWidth ?? 2,
+        'stroke-dasharray': '5 4',
+        'pointer-events': 'none',
+        'data-connector-preview': '',
+      }),
+    );
+  }
+}

package/src/types.ts

@@ -0,0 +1,38 @@
+import type { Point, Shape, Group, Svg, Path } from '@rasamjs/core';
+
+export type ConnectorTarget = Shape | Group | Svg;
+export type ConnectorSide = 'top' | 'right' | 'bottom' | 'left';
+/** A point is normalized within the target's local geometric bounds. */
+export type ConnectorAnchor = 'auto' | ConnectorSide | Point;
+/**
+ * A target with an anchor on its bounds, a target with a named port from its
+ * `portDefinitions` (for example a component's), or a loose point in drawing units.
+ */
+export type ConnectorEndpoint =
+  | { readonly target: ConnectorTarget; readonly anchor?: ConnectorAnchor }
+  | { readonly target: ConnectorTarget; readonly port: string }
+  | { readonly point: Point };
+export type ConnectorRouting = 'straight' | 'elbow';
+export interface ConnectorOptions {
+  readonly start: ConnectorEndpoint;
+  readonly end: ConnectorEndpoint;
+  readonly routing?: ConnectorRouting;
+  readonly arrows?: 'none' | 'end' | 'both';
+  readonly stroke?: string;
+  readonly strokeWidth?: number;
+}
+export interface ConnectorState {
+  readonly path: Path;
+  readonly start: ConnectorEndpoint;
+  readonly end: ConnectorEndpoint;
+  readonly routing: ConnectorRouting;
+}
+export interface ConnectorPort {
+  readonly point: Point;
+  readonly direction: Point;
+}
+export interface ConnectorRoute {
+  readonly start: ConnectorPort;
+  readonly end: ConnectorPort;
+  readonly routing: ConnectorRouting;
+}