@rasamjs/connectors 0.1.0 → 0.3.0

package/package.json

@@ -1,63 +1,64 @@
-{
-  "name": "@rasamjs/connectors",
-  "version": "0.1.0",
-  "type": "module",
-  "license": "MIT",
-  "description": "Attached straight and elbow connectors for rasam SVG drawings.",
-  "files": [
-    "dist",
-    "src",
-    "README.md",
-    "API.md",
-    "CHANGELOG.md",
-    "RELEASING.md",
-    "LICENSE"
-  ],
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "rasam-source": "./src/index.ts",
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./tool": {
-      "rasam-source": "./src/tool.ts",
-      "types": "./dist/tool.d.ts",
-      "import": "./dist/tool.js"
-    },
-    "./editor": {
-      "rasam-source": "./src/editor.ts",
-      "types": "./dist/editor.d.ts",
-      "import": "./dist/editor.js"
-    }
-  },
-  "sideEffects": false,
-  "peerDependencies": {
-    "@rasamjs/core": "^0.2.0"
-  },
-  "devDependencies": {
-    "@rasamjs/core": "0.2.0",
-    "@rasamjs/history": "0.2.0",
-    "@rasamjs/transformer": "0.5.0"
-  },
-  "scripts": {
-    "build": "node scripts/build.mjs",
-    "typecheck": "tsc -p tsconfig.check.json",
-    "test": "vitest run",
-    "test:browser": "playwright test",
-    "dev": "vite --host 127.0.0.1",
-    "format": "prettier --write src tests scripts fixtures *.json *.ts *.md",
-    "format:check": "prettier --check src tests scripts fixtures *.json *.ts *.md",
-    "check:consumer": "node scripts/check-consumer.mjs",
-    "check:docs": "node scripts/check-docs.mjs",
-    "check:size": "node scripts/check-size.mjs",
-    "api:check": "node scripts/check-api.mjs",
-    "api:update": "node scripts/check-api.mjs --update",
-    "release:check": "node scripts/check-release.mjs"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/hdevlop/rasam.git",
-    "directory": "packages/connectors"
-  }
-}
+{
+  "name": "@rasamjs/connectors",
+  "version": "0.3.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "Attached straight and elbow connectors for rasam SVG drawings.",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "API.md",
+    "CHANGELOG.md",
+    "RELEASING.md",
+    "LICENSE"
+  ],
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "rasam-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./tool": {
+      "rasam-source": "./src/tool.ts",
+      "types": "./dist/tool.d.ts",
+      "import": "./dist/tool.js"
+    },
+    "./editor": {
+      "rasam-source": "./src/editor.ts",
+      "types": "./dist/editor.d.ts",
+      "import": "./dist/editor.js"
+    }
+  },
+  "sideEffects": false,
+  "peerDependencies": {
+    "@rasamjs/core": "^0.3.0"
+  },
+  "devDependencies": {
+    "@rasamjs/core": "0.3.0",
+    "@rasamjs/history": "0.2.0",
+    "@rasamjs/transformer": "0.5.0"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "tsc -p tsconfig.check.json",
+    "test": "vitest run",
+    "test:browser": "playwright test",
+    "dev": "vite --host 127.0.0.1",
+    "format": "prettier --write src tests scripts fixtures *.json *.ts *.md",
+    "format:check": "prettier --check src tests scripts fixtures *.json *.ts *.md",
+    "check:consumer": "node scripts/check-consumer.mjs",
+    "check:docs": "node scripts/check-docs.mjs",
+    "check:size": "node scripts/check-size.mjs",
+    "api:check": "node scripts/check-api.mjs",
+    "api:update": "node scripts/check-api.mjs --update",
+    "release:check": "node scripts/check-release.mjs",
+    "bench": "node scripts/benchmark.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hdevlop/rasam.git",
+    "directory": "packages/connectors"
+  }
+}

package/src/connectors.ts

@@ -1,17 +1,32 @@
 import { Path } from '@rasamjs/core';
-import type { Svg, AnyNode } from '@rasamjs/core';
+import type { Svg, AnyNode, Point } from '@rasamjs/core';
 import { Guards } from '@rasamjs/core/advanced';
 import { beginChangeGroup, deriveChanges } from '@rasamjs/core/changes';
-import { isConnector, readConnector, writeConnector } from './metadata.js';
+import {
+  endpointAttribute,
+  isConnector,
+  pathEnd,
+  readConnector,
+  unbound,
+  writeConnector,
+} from './metadata.js';
 import {
   connectorPort,
   endpointCenter,
+  findPort,
   pathData,
   routeConnector,
   validateAnchor,
   validatePoint,
 } from './routing.js';
-import type { ConnectorEndpoint, ConnectorOptions, ConnectorState } from './types.js';
+import type {
+  ConnectorEndpoint,
+  ConnectorOptions,
+  ConnectorState,
+  ConnectorTarget,
+  ConnectorRouter,
+  ConnectorsOptions,
+} from './types.js';
 
 const owners = new WeakMap<Svg, Connectors>();
 const drawableTags = new Set([
@@ -33,7 +48,11 @@ export class Connectors {
   private disposed = false;
   private readonly cleanups: (() => void)[] = [];
   private readonly disposals = new Set<() => void>();
-  constructor(readonly drawing: Svg) {
+  private router?: ConnectorRouter;
+  constructor(
+    readonly drawing: Svg,
+    options: ConnectorsOptions = {},
+  ) {
     if (
       !Guards.isTransformable(drawing) ||
       drawing.isDestroyed ||
@@ -42,16 +61,25 @@ export class Connectors {
     )
       throw new TypeError('Connectors needs a live SVG drawing root');
     if (owners.has(drawing)) throw new Error('Connectors is already attached to this drawing');
+    if (
+      !options ||
+      typeof options !== 'object' ||
+      (options.route !== undefined && typeof options.route !== 'function')
+    )
+      throw new TypeError('Connector route must be a function');
+    this.router = options.route;
     // 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);
+        for (const path of this.affected(event.nodes)) {
+          let state = readConnector(path);
+          const loose = this.loosen(state);
+          if (loose !== state || unbound.has(state.start) || unbound.has(state.end))
+            writeConnector(path, (state = loose));
+          this.route(state);
         }
       }),
       drawing.onDispose(() => this.destroy()),
@@ -76,6 +104,25 @@ export class Connectors {
     this.assertPath(path);
     return readConnector(path);
   }
+  /** Connectors with an end on `target`, or only on its port named `port`. */
+  links(target: ConnectorTarget, port?: string): readonly Path[] {
+    this.assertLive();
+    if (port !== undefined && (typeof port !== 'string' || !port))
+      throw new TypeError('Port names must be non-empty strings');
+    return Object.freeze(
+      this.attached(target)
+        .filter((path) => {
+          const { start, end } = readConnector(path);
+          return [start, end].some(
+            (endpoint) =>
+              'target' in endpoint &&
+              endpoint.target === target &&
+              (port === undefined || ('port' in endpoint && endpoint.port === port)),
+          );
+        })
+        .sort((a, b) => (a.el.compareDocumentPosition(b.el) & 4 ? -1 : 1)),
+    );
+  }
   create(options: ConnectorOptions): Path {
     this.assertLive();
     this.validate(options);
@@ -105,7 +152,7 @@ export class Connectors {
         if (options.arrows === 'both') path.marker('start', marker);
       }
       if (!this.route(readConnector(path)))
-        throw new Error('Connector needs available bounds and invertible transforms');
+        throw new Error('Connector route is unavailable or its transform is not invertible');
       return path;
     });
   }
@@ -116,7 +163,7 @@ export class Connectors {
     this.edit('Edit connector', () => {
       writeConnector(path, state);
       if (!this.route(state))
-        throw new Error('Connector needs available bounds and invertible transforms');
+        throw new Error('Connector route is unavailable or its transform is not invertible');
     });
   }
   remove(path: Path): void {
@@ -126,6 +173,7 @@ export class Connectors {
   destroy(): void {
     if (this.disposed) return;
     this.disposed = true;
+    this.router = undefined;
     owners.delete(this.drawing);
     const failures: unknown[] = [];
     for (const stop of [...this.cleanups.splice(0).reverse(), ...this.disposals]) {
@@ -147,7 +195,7 @@ export class Connectors {
       !isConnector(path) ||
       path.isDestroyed ||
       path.context !== this.drawing.context ||
-      !this.drawing.descendants().includes(path)
+      !this.drawing.el.contains(path.el)
     )
       throw new TypeError('Expected a connector in this drawing');
   }
@@ -183,7 +231,7 @@ export class Connectors {
       target.isDestroyed ||
       target === this.drawing ||
       target.context !== this.drawing.context ||
-      !this.drawing.descendants().includes(target) ||
+      !this.drawing.el.contains(target.el) ||
       target.descendants().some(isConnector)
     )
       throw new TypeError(
@@ -192,42 +240,90 @@ export class Connectors {
     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),
-    );
+    if (!('port' in endpoint)) return validateAnchor(endpoint.anchor ?? 'auto');
+    if ('anchor' in endpoint) throw new TypeError('Endpoint needs either a port or an anchor');
+    if (typeof endpoint.port !== 'string' || !findPort(target, endpoint.port))
+      throw new TypeError(`Unknown connector port: ${String(endpoint.port)}`);
+  }
+  /** An end whose target left the drawing, or whose port is gone, stays where it is. */
+  private loosen(state: ConnectorState): ConnectorState {
+    const loose = (end: 'start' | 'end'): ConnectorEndpoint => {
+      const endpoint = state[end];
+      if ('point' in endpoint) return endpoint;
+      const { target } = endpoint;
+      const gone =
+        target.isDestroyed ||
+        !this.drawing.el.contains(target.el) ||
+        ('port' in endpoint && !findPort(target, endpoint.port));
+      const point = gone && pathEnd(state.path, end);
+      return point ? { point } : endpoint;
+    };
+    const start = loose('start'),
+      end = loose('end');
+    return start === state.start && end === state.end ? state : { ...state, start, end };
+  }
+  /** Connectors in this drawing with an end on `target`, from core's reference index. */
+  private attached(target: AnyNode): Path[] {
+    return this.drawing.context.defs
+      .consumersOf(target)
+      .filter(
+        (node): node is Path =>
+          isConnector(node) &&
+          this.drawing.el.contains(node.el) &&
+          (['start', 'end'] as const).some(
+            (end) => node.references.get(endpointAttribute(end)) === target,
+          ),
+      );
+  }
+  /**
+   * Connectors to route after a change: those inside a changed subtree, and those attached
+   * to a changed node, its descendants or its ancestors, since parents move, resize or
+   * reparent targets and a descendant changes a group's bounds. The work follows the
+   * size of the change, not the number of connectors.
+   */
+  private affected(changed: readonly AnyNode[]): Set<Path> {
+    const paths = new Set<Path>(),
+      seen = new Set<AnyNode>();
+    const visit = (node: AnyNode) => {
+      if (node.isDestroyed || seen.has(node)) return;
+      seen.add(node);
+      if (isConnector(node) && this.drawing.el.contains(node.el)) paths.add(node);
+      for (const path of this.attached(node)) paths.add(path);
+    };
+    for (const node of changed) {
+      node.descendants().forEach(visit);
+      for (let parent = node.parent; parent; parent = parent.parent) visit(parent);
+    }
+    return paths;
   }
   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))
+        if (endpoint.target.isDestroyed || !this.drawing.el.contains(endpoint.target.el))
           return false;
-        if (endpoint.target.descendants().includes(path))
+        if (endpoint.target.el.contains(path.el))
           throw new TypeError('A connector cannot be inside its endpoint target');
       }
+    const inverse = path.worldMatrix().inverse();
+    if (!inverse) return false;
+    const points = this.router ? this.router(state) : this.defaultRoute(state);
+    if (points === null) return false;
+    if (!Array.isArray(points) || points.length < 2)
+      throw new TypeError('Connector route must return at least two finite points or null');
+    for (const point of points) validatePoint(point);
+    const local = points.map((point) => inverse.apply(point));
+    local.forEach((point) => validatePoint(point));
+    const d = pathData(local);
+    if (path.getAttributeValue('d') !== d) path.attrs({ d });
+    return true;
+  }
+  private defaultRoute({ start, end, routing }: ConnectorState): readonly Point[] | null {
     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;
+    return from && to ? routeConnector({ start: from, end: to, routing }) : null;
   }
   private edit<Result>(label: string, run: () => Result): Result {
     const group = beginChangeGroup(this.drawing, { source: 'connectors', label });

package/src/editor.ts

@@ -1,6 +1,19 @@
 import type { AnyNode, Svg } from '@rasamjs/core';
 import { Connectors } from './connectors.js';
 import { ConnectorTool } from './tool.js';
+import type { ConnectorOptions, ConnectorsOptions } from './types.js';
+
+/** One registered connector tool; its id is also its command id. */
+export interface ConnectorEditingTool extends Pick<ConnectorOptions, 'routing' | 'arrows'> {
+  readonly id: string;
+  readonly label: string;
+  readonly key: string;
+  readonly hint?: string;
+}
+const defaultTools: readonly ConnectorEditingTool[] = [
+  { id: 'connector-straight', label: 'Connector', key: 'C', routing: 'straight' },
+  { id: 'connector-elbow', label: 'Elbow connector', key: 'Shift+C', routing: 'elbow' },
+];
 
 export interface ConnectorScope {
   readonly drawing: Svg;
@@ -25,18 +38,27 @@ export interface ConnectorScope {
   created(node: AnyNode): void;
   exit(): void;
 }
-export function connectorEditing() {
+/**
+ * The connectors service and its tools. `tools` replaces the default Connector (`C`)
+ * and Elbow connector (`Shift+C`), for example with a Wire tool without arrows.
+ */
+export function connectorEditing(
+  options: ConnectorsOptions & { readonly tools?: readonly ConnectorEditingTool[] } = {},
+) {
+  const tools = options.tools ?? defaultTools;
+  if (!Array.isArray(tools)) throw new TypeError('Connector tools must be an array');
   return {
     id: 'connectors',
     create(scope: ConnectorScope) {
-      const service = scope.use(new Connectors(scope.drawing));
-      for (const routing of ['straight', 'elbow'] as const)
+      const service = scope.use(new Connectors(scope.drawing, options));
+      for (const { id, label, key, routing = 'straight', arrows, hint } of tools)
         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.',
+          id,
+          commandId: id,
+          label,
+          key,
+          hint:
+            hint ?? 'Drag between shapes to connect; hover to choose an anchor; Escape cancels.',
           activate(current) {
             const editor = current.editor;
             let release = () => {},
@@ -45,6 +67,7 @@ export function connectorEditing() {
             const tool = current.use(
               new ConnectorTool(service, {
                 routing,
+                arrows,
                 ...editor.paint,
                 selectable: (node) =>
                   editor.selection.canSelect(node) && editor.layers.isSelectable(node),

package/src/index.ts

@@ -9,6 +9,8 @@ export type {
   ConnectorRouting,
   ConnectorOptions,
   ConnectorState,
+  ConnectorRouter,
+  ConnectorsOptions,
   ConnectorPort,
   ConnectorRoute,
 } from './types.js';

package/src/metadata.ts

@@ -1,5 +1,5 @@
 import { Path } from '@rasamjs/core';
-import type { AnyNode } from '@rasamjs/core';
+import type { AnyNode, Point } from '@rasamjs/core';
 import { data } from '@rasamjs/core/data';
 import type {
   ConnectorAnchor,
@@ -12,7 +12,20 @@ export const endpointAttribute = (end: 'start' | 'end') => `data-rasam-connector
 const metadataKey = 'rasam-connector';
 interface SavedEndpoint {
   anchor?: ConnectorAnchor;
-  point?: import('@rasamjs/core').Point;
+  /** Readers without port support fall back to an automatic anchor on the target. */
+  port?: string;
+  point?: Point;
+}
+/** Loose ends read from a path whose saved target is missing, such as a pasted copy. */
+export const unbound = new WeakSet<ConnectorEndpoint>();
+/** Where the routed path ends now, in drawing units. */
+export function pathEnd(path: Path, end: 'start' | 'end'): Point | null {
+  const values = String(path.getAttributeValue('d') ?? '')
+    .match(/[-+]?(?:\d+\.?\d*|\.\d+)(?:e[-+]?\d+)?/gi)
+    ?.map(Number);
+  if (!values || values.length < 4) return null;
+  const index = end === 'start' ? 0 : values.length - 2;
+  return path.worldMatrix().apply({ x: values[index], y: values[index + 1] });
 }
 interface SavedConnector {
   version: 1;
@@ -36,8 +49,18 @@ export function readConnector(path: Path): ConnectorState {
       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');
+    if (!target || !('toRoot' in target)) {
+      const point = pathEnd(path, end);
+      if (!point) throw new TypeError('Connector endpoint has no bound target');
+      const loose = { point };
+      unbound.add(loose);
+      return loose;
+    }
+    if (value.port !== undefined) {
+      if (typeof value.port !== 'string' || !value.port)
+        throw new TypeError('Invalid connector port metadata');
+      return { target: target as import('./types.js').ConnectorTarget, port: value.port };
+    }
     validateAnchor(value.anchor ?? 'auto');
     return {
       target: target as import('./types.js').ConnectorTarget,
@@ -52,7 +75,9 @@ export function writeConnector(path: Path, state: Omit<ConnectorState, 'path'>):
     path.reference(endpointAttribute(end), 'target' in endpoint ? endpoint.target : null, 'href');
     return 'point' in endpoint
       ? { point: { ...endpoint.point } }
-      : { anchor: endpoint.anchor ?? 'auto' };
+      : 'port' in endpoint
+        ? { port: endpoint.port }
+        : { anchor: endpoint.anchor ?? 'auto' };
   };
   data(path, metadataKey, {
     version: 1,

package/src/routing.ts

@@ -1,12 +1,25 @@
-import type { Point } from '@rasamjs/core';
+import type { Point, PortDefinition } from '@rasamjs/core';
 import type {
   ConnectorAnchor,
   ConnectorEndpoint,
   ConnectorPort,
   ConnectorRoute,
   ConnectorSide,
+  ConnectorTarget,
 } from './types.js';
 
+/** Reads ports structurally from `portDefinitions`, the way tools read `editRules`. */
+export function portsOf(target: ConnectorTarget): readonly PortDefinition[] {
+  const ports = (target as { readonly portDefinitions?: unknown }).portDefinitions;
+  return Array.isArray(ports) ? ports : [];
+}
+export const findPort = (target: ConnectorTarget, name: string): PortDefinition | undefined =>
+  portsOf(target).find((port) => port?.name === name);
+const sideVector = (side?: ConnectorSide): Point => ({
+  x: side === 'left' ? -1 : side === 'right' ? 1 : 0,
+  y: side === 'top' ? -1 : side === 'bottom' ? 1 : 0,
+});
+
 export function validatePoint(point: Point, normalized = false): void {
   if (
     !point ||
@@ -26,6 +39,10 @@ export function validateAnchor(anchor: ConnectorAnchor): void {
 }
 export function endpointCenter(endpoint: ConnectorEndpoint): Point | null {
   if ('point' in endpoint) return endpoint.point;
+  if ('port' in endpoint) {
+    const port = findPort(endpoint.target, endpoint.port);
+    return port ? endpoint.target.toRoot(port) : null;
+  }
   const bounds = endpoint.target.bounds();
   if (!('box' in bounds)) return null;
   const { x, y, width, height } = bounds.box;
@@ -34,7 +51,13 @@ export function endpointCenter(endpoint: ConnectorEndpoint): Point | null {
 /** 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 { target } = endpoint;
+  if ('port' in endpoint) {
+    // A port end sits exactly on the port and leaves in the direction of its side.
+    const port = findPort(target, endpoint.port);
+    return port ? place(target, port, sideVector(port.side)) : null;
+  }
+  const { anchor = 'auto' } = endpoint;
   const bounds = target.bounds();
   if (!('box' in bounds)) return null;
   const { x, y, width, height } = bounds.box;
@@ -70,15 +93,18 @@ export function connectorPort(endpoint: ConnectorEndpoint, toward: Point): Conne
           ? 'top'
           : 'bottom';
   }
-  const root = target.toRoot(point);
-  const localDirection =
+  return place(
+    target,
+    point,
     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 });
+      : sideVector(side),
+  );
+}
+/** Maps a local point and outward direction into drawing units, snapped to an axis. */
+function place(target: ConnectorTarget, point: Point, local: Point): ConnectorPort {
+  const root = target.toRoot(point);
+  const offset = target.toRoot({ x: point.x + local.x, y: point.y + local.y });
   const dx = offset.x - root.x,
     dy = offset.y - root.y;
   return {