@rasamjs/connectors 0.1.0 → 0.3.0

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 {
@@ -22,6 +27,11 @@ export interface ConnectorState {
   readonly end: ConnectorEndpoint;
   readonly routing: ConnectorRouting;
 }
+/** Return at least two finite points in drawing units, or null to retain stored geometry. */
+export type ConnectorRouter = (state: ConnectorState) => readonly Point[] | null;
+export interface ConnectorsOptions {
+  readonly route?: ConnectorRouter;
+}
 export interface ConnectorPort {
   readonly point: Point;
   readonly direction: Point;