@rasamjs/connectors 0.0.0-stage → 0.1.0

package/src/tool.ts

@@ -0,0 +1,344 @@
+import type { 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, 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'];
+
+/** Drag from a hinted anchor or free point. 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 targets = drawing.el.ownerDocument
+      .elementsFromPoint(event.clientX, event.clientY)
+      .map((element) => Registry.wrapper(element as SVGElement));
+    let target = targets.find(
+      (node): 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,
+    );
+    // 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 = sides.some((anchor) => {
+        const port = connectorPort({ target: previous, anchor }, 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 anchor of sides) {
+      const port = connectorPort({ target, anchor }, 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 = { target, anchor };
+      }
+    }
+    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 anchor of sides) {
+        const port = connectorPort({ target: this.hover.target, anchor }, { x: 0, y: 0 });
+        const point = port && this.surface.fromRoot(port.point);
+        if (point)
+          overlay.append(
+            svg(document, 'circle', {
+              cx: point.x,
+              cy: point.y,
+              r: 5,
+              fill: 'white',
+              stroke: '#2563eb',
+              'stroke-width': 1.5,
+              'pointer-events': 'none',
+              'data-connector-anchor': anchor,
+            }),
+          );
+      }
+    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,33 @@
+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;
+export type ConnectorEndpoint =
+  | { readonly target: ConnectorTarget; readonly anchor?: ConnectorAnchor }
+  | { 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;
+}