@rasamjs/connectors 0.1.0 → 0.2.0

package/src/connectors.ts

@@ -2,16 +2,29 @@ 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 {
+  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,
+} from './types.js';
 
 const owners = new WeakMap<Svg, Connectors>();
 const drawableTags = new Set([
@@ -48,10 +61,12 @@ export class Connectors {
     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 +91,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);
@@ -147,7 +181,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 +217,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,27 +226,69 @@ 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 a = endpointCenter(start),

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 } 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: { 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)
+      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/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 {

package/src/tool.ts

@@ -1,9 +1,9 @@
-import type { Path, Point } from '@rasamjs/core';
+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, routeConnector } from './routing.js';
+import { connectorPort, endpointCenter, pathData, portsOf, routeConnector } from './routing.js';
 import { ToolSurface, svg } from './tool-surface.js';
 import type {
   ConnectorEndpoint,
@@ -32,8 +32,22 @@ interface Hover {
   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 or free point. The document is written only on release. */
+/**
+ * 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;
@@ -197,18 +211,23 @@ export class ConnectorTool {
     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,
-    );
+    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 (
@@ -218,8 +237,8 @@ export class ConnectorTool {
       drawing.el.contains(previous.el) &&
       this.options.selectable?.(previous) !== false
     ) {
-      const nearHint = sides.some((anchor) => {
-        const port = connectorPort({ target: previous, anchor }, point);
+      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;
       });
@@ -229,14 +248,14 @@ export class ConnectorTool {
     if (!target) return { point };
     let endpoint: ConnectorEndpoint = { target, anchor: 'auto' };
     let nearest = 12;
-    for (const anchor of sides) {
-      const port = connectorPort({ target, anchor }, point);
+    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 = { target, anchor };
+        endpoint = hint;
       }
     }
     this.hover = { target, endpoint };
@@ -299,20 +318,24 @@ export class ConnectorTool {
     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 });
+      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: 'white',
+              fill: active ? '#2563eb' : 'white',
               stroke: '#2563eb',
               'stroke-width': 1.5,
               'pointer-events': 'none',
-              'data-connector-anchor': anchor,
+              ...('port' in hint
+                ? { 'data-connector-port': hint.port }
+                : { 'data-connector-anchor': (hint as { anchor: ConnectorSide }).anchor }),
+              ...(active ? { 'data-connector-active': '' } : {}),
             }),
           );
       }

package/src/types.ts

@@ -4,8 +4,13 @@ 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 {