f1ow 1.0.0 → 1.1.0

package/dist/types/index.d.ts

@@ -2,6 +2,27 @@ export type ToolType = 'select' | 'hand' | 'rectangle' | 'ellipse' | 'diamond' |
 export type ElementType = 'rectangle' | 'ellipse' | 'diamond' | 'line' | 'arrow' | 'freedraw' | 'text' | 'image';
 export type Arrowhead = 'arrow' | 'triangle' | 'triangle_outline' | 'circle' | 'circle_outline' | 'diamond' | 'diamond_outline' | 'bar' | 'crowfoot_one' | 'crowfoot_many' | 'crowfoot_one_or_many';
 export type LineType = 'sharp' | 'curved' | 'elbow';
+/** Gradient definition for connector strokes */
+export interface LineGradient {
+    /** Color stops: [offset (0-1), cssColor] */
+    stops: [number, string][];
+    /** Gradient follows the path direction */
+    type: 'along-path';
+}
+/** Tapered stroke: width varies from start to end */
+export interface LineTaper {
+    startWidth: number;
+    endWidth: number;
+}
+/** Extended line style options for connectors */
+export interface LineStyleExtension {
+    /** Gradient stroke along the connector path */
+    gradient?: LineGradient;
+    /** Tapered stroke width */
+    taper?: LineTaper;
+    /** Animated flow direction indicator (dash animation) */
+    flowAnimation?: boolean;
+}
 export type FreehandStyle = 'standard' | 'pen' | 'brush' | 'pencil';
 export interface ElementStyle {
     strokeColor: string;
@@ -27,6 +48,17 @@ export interface BaseElement {
     isVisible: boolean;
     /** Bidirectional refs: arrows/text bound to this element */
     boundElements: BoundElement[] | null;
+    /**
+     * Custom ports defined on this element instance.
+     * Used for architecture diagrams where shapes have named I/O points.
+     */
+    ports?: Port[];
+    /**
+     * Monotonic version counter — bumped on every geometry/port mutation.
+     * Used by binding system to detect stale worker results and cache invalidation.
+     * Auto-managed by the store; consumers should not set this directly.
+     */
+    version: number;
     /** Group hierarchy: element belongs to these groups (innermost first, outermost last) */
     groupIds?: string[];
     /**
@@ -123,6 +155,8 @@ export interface LineElement extends BaseElement {
     curvature?: number;
     startBinding: Binding | null;
     endBinding: Binding | null;
+    /** Extended line style (gradient, taper, animation) */
+    lineStyle?: LineStyleExtension;
 }
 export interface ArrowElement extends BaseElement {
     type: 'arrow';
@@ -141,6 +175,8 @@ export interface ArrowElement extends BaseElement {
     curvature?: number;
     startBinding: Binding | null;
     endBinding: Binding | null;
+    /** Extended line style (gradient, taper, animation) */
+    lineStyle?: LineStyleExtension;
 }
 export interface FreeDrawElement extends BaseElement {
     type: 'freedraw';
@@ -208,8 +244,23 @@ export interface SelectionBox {
     width: number;
     height: number;
 }
+/** Named anchor positions on a shape's bounding box (compass notation) */
+export type AnchorId = 'n' | 's' | 'e' | 'w' | 'ne' | 'nw' | 'se' | 'sw' | 'center' | 'auto';
+/** Custom port on an element — user-defined attachment point */
+export interface Port {
+    /** Unique port identifier within the element */
+    id: string;
+    /** Normalized [0-1, 0-1] position on the element's bounding box */
+    ratio: [number, number];
+    /** Optional display label for the port */
+    label?: string;
+    /** Optional preferred edge (used for elbow routing direction) */
+    edge?: AnchorId;
+}
+/** How the binding target was determined */
+export type SnapMode = 'anchor' | 'port' | 'edge' | 'center';
 /**
- * @deprecated Use fixedPoint binding instead. Kept for backward-compat exports.
+ * @deprecated Use AnchorId instead. Kept for backward-compat exports.
  */
 export type ConnectionAnchor = 'top' | 'bottom' | 'left' | 'right' | 'center';
 /** Bidirectional reference stored on shapes to track bound connectors/text */
@@ -221,13 +272,30 @@ export type BoundElement = {
 export interface Binding {
     /** The element this end is connected to */
     elementId: string;
+    /**
+     * Named anchor position. When set, takes precedence over fixedPoint.
+     * Resolves to a fixedPoint at bind time, but re-resolves after resize
+     * to maintain semantic meaning (e.g. "always top-center").
+     * 'auto' = let the system choose the nearest anchor.
+     */
+    anchor?: AnchorId;
+    /** Custom port ID. When set, takes precedence over anchor and fixedPoint. */
+    portId?: string;
     /**
      * Continuous attachment ratio [0-1, 0-1] on target's bounding box.
      * e.g. [0.5, 0] = top center, [1, 0.5] = right center, [0.3, 0.7] = arbitrary.
+     * Always populated — serves as resolved cache when anchor/port is set.
      */
     fixedPoint: [number, number];
     /** Gap between the edge of the shape and the arrow tip (px) */
     gap: number;
+    /** How the binding target was determined */
+    snapMode: SnapMode;
+    /**
+     * Version of the target element at bind time.
+     * Used to detect stale bindings (e.g. worker results arriving after element changed).
+     */
+    elementVersion: number;
     /**
      * Whether to bind to the exact fixedPoint position, or to the shape center.
      * When false (default), the arrow connects from/to the shape's center,
@@ -250,6 +318,12 @@ export interface SnapTarget {
      * - `false`: cursor is in the center zone → attaches to center for auto-routing
      */
     isPrecise: boolean;
+    /** Named anchor if snapped to a cardinal position */
+    anchor?: AnchorId;
+    /** Custom port ID if snapped to a port */
+    portId?: string;
+    /** How the snap target was determined */
+    snapMode: SnapMode;
 }
 /** State for editing individual points of a line/arrow element */
 export interface LinearEditState {
@@ -266,3 +340,25 @@ export interface LinearEditState {
     /** Whether a point is currently being dragged */
     isDraggingPoint: boolean;
 }
+/**
+ * Consumer-facing configuration for the connection/binding system.
+ * Pass via `FlowCanvasProps.connectionConfig`.
+ */
+export interface ConnectionConfig {
+    /** Distance outside shape perimeter to activate edge snap (px). Default: 24 */
+    snapThreshold?: number;
+    /** Hysteresis margin to prevent edge/center mode flickering (px). Default: 6 */
+    hysteresisMargin?: number;
+    /** Clearance around shapes for elbow routing (px). Default: adaptive */
+    elbowMargin?: number;
+    /** Hit radius for port dots (px, before zoom compensation). Default: 8 */
+    portHitRadius?: number;
+    /** Minimum stub length for elbow route endpoints (px). Default: 36 */
+    stubLength?: number;
+    /** Whether to render custom ports on shapes. Default: true */
+    enablePorts?: boolean;
+    /** Default line style extension applied to new connectors */
+    defaultLineStyle?: LineStyleExtension;
+    /** Default line type for new arrows/lines. Default: 'sharp' */
+    defaultLineType?: LineType;
+}

package/dist/utils/connection.d.ts

@@ -1,4 +1,4 @@
-import { CanvasElement, Point, ConnectionAnchor, Binding, SnapTarget, ArrowElement, LineElement, TextElement, BoundElement } from '../types';
+import { CanvasElement, Point, ConnectionAnchor, Binding, SnapTarget, ArrowElement, LineElement, TextElement, BoundElement, AnchorId, SnapMode } from '../types';
 /** Whether an element can be a connection target */
 export declare function isConnectable(el: CanvasElement): boolean;
 /** Get the 5 named anchor positions for a bounding-box shape */
@@ -7,6 +7,29 @@ export declare function getConnectionPoints(el: CanvasElement): Record<Connectio
  * @deprecated Use fixedPoint-based getEdgePointFromFixedPoint() instead.
  */
 export declare function getAnchorPosition(el: CanvasElement, anchor: ConnectionAnchor): Point;
+/** Map a named AnchorId to its fixedPoint ratio on the bounding box */
+export declare function anchorToFixedPoint(anchor: AnchorId): [number, number];
+/** Find the nearest cardinal AnchorId for a given fixedPoint */
+export declare function fixedPointToAnchor(fp: [number, number]): AnchorId;
+/** Resolve a port's ratio to a fixedPoint on an element */
+export declare function resolvePort(el: CanvasElement, portId: string): [number, number] | null;
+/**
+ * Resolve the effective fixedPoint for a binding, respecting priority:
+ * portId > anchor > fixedPoint.
+ *
+ * Returns the resolved fixedPoint and the effective snapMode.
+ */
+export declare function resolveBindingPoint(binding: Binding, element: CanvasElement): {
+    fixedPoint: [number, number];
+    snapMode: SnapMode;
+};
+/**
+ * Create a Binding from a SnapTarget result.
+ * Convenience helper for LinearTool and LinearElementHandles.
+ */
+export declare function createBindingFromSnap(snap: SnapTarget, gap: number, elementVersion: number): Binding;
+/** Check whether a binding's elementVersion matches the current element */
+export declare function isBindingStale(binding: Binding, element: CanvasElement): boolean;
 /**
  * Compute the appropriate gap between a connector and a shape edge,
  * based on both the connector's stroke width and a base offset.
@@ -21,8 +44,13 @@ export declare function computeFixedPoint(el: CanvasElement, worldPt: Point): [n
 /**
  * Convert a fixedPoint ratio back to a world-space target point,
  * then compute the edge intersection from center to that target.
+ *
+ * @param toward  Optional direction hint for center fixedPoint [0.5, 0.5].
+ *                When the fixedPoint is exactly center, there's no meaningful
+ *                direction — `toward` provides the other endpoint so we can
+ *                compute a stable edge exit. Without it, returns the element center.
  */
-export declare function getEdgePointFromFixedPoint(el: CanvasElement, fixedPoint: [number, number], gap?: number): Point;
+export declare function getEdgePointFromFixedPoint(el: CanvasElement, fixedPoint: [number, number], gap?: number, toward?: Point): Point;
 /**
  * Given a shape and an external world-space point, compute the point on
  * the shape's perimeter closest to `toward`.

package/dist/utils/editable.d.ts

@@ -0,0 +1,2 @@
+export declare function isTextEditingTarget(target: EventTarget | null): boolean;
+export declare function blurTextEditingTarget(target: EventTarget | null): boolean;

package/dist/utils/elbow.d.ts

@@ -7,6 +7,7 @@ interface BBox {
     width: number;
     height: number;
 }
+type BoxLike = Pick<BBox, 'x' | 'y' | 'width' | 'height'>;
 /**
  * Determine the preferred exit direction for elbow routing from a
  * center (imprecise) binding.
@@ -21,8 +22,11 @@ interface BBox {
  * shapes at their vertical center — visually too close to objects and
  * often requiring more bends.
  *
- * Only uses horizontal exits when the target is strongly horizontally
- * aligned (>3× horizontal dominance after normalizing by shape size).
+ * When both endpoint shapes are known, prefer the axis with the smaller
+ * inter-shape gap (or the orthogonal axis with less overlap). This makes
+ * diagonal routes look more intentional than a pure center-to-center
+ * heuristic. If only a target point is known, fall back to the normalized
+ * center-delta heuristic with a slight vertical bias.
  *
  * This function should be used by BOTH:
  * - The binding system (connection.ts) to compute edge points for
@@ -31,12 +35,7 @@ interface BBox {
  *
  * For PRECISE bindings, always use directionFromFixedPoint instead.
  */
-export declare function getElbowPreferredDirection(shape: {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-}, targetPoint: Point): Direction;
+export declare function getElbowPreferredDirection(shape: BoxLike, targetPoint: Point, targetShape?: BoxLike | null, targetBinding?: Binding | null): Direction;
 /**
  * Determine the exit/entry direction from a binding's fixedPoint.
  * fixedPoint is [fx, fy] in [0-1, 0-1] on the target shape's bbox.
@@ -67,6 +66,34 @@ export declare function directionFromShapeToPoint(shape: BBox, targetPoint: Poin
  * computed edge point from the binding system.
  */
 export declare function directionFromEdgePoint(shape: BBox, edgePoint: Point): Direction;
+export declare function selectElbowDirectionPair(args: {
+    startWorld: Point;
+    endWorld: Point;
+    startBinding: Binding | null;
+    endBinding: Binding | null;
+    startShape?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+    endShape?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+    intermediateObstacles?: Array<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>;
+    minStubLength?: number;
+}): {
+    startDir: Direction;
+    endDir: Direction;
+};
 /**
  * Compute an orthogonal route between two points using a multi-candidate
  * grid-based shortest-path algorithm.
@@ -99,6 +126,12 @@ export declare function directionFromEdgePoint(shape: BBox, edgePoint: Point): D
 export declare function computeElbowRoute(start: Point, end: Point, startDir: Direction, endDir: Direction, startBBox?: BBox | null, endBBox?: BBox | null, minStubLength?: number, 
 /** Additional obstacles (intermediate shapes) to avoid — already as BBox */
 intermediateObstacles?: BBox[]): Point[];
+export declare function collectElbowIntermediateObstacles(startWorld: Point, endWorld: Point, allElements: CanvasElement[], excludeIds: Set<string>): Array<{
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}>;
 /** Clear the route cache (call when elements change structurally) */
 export declare function clearElbowRouteCache(): void;
 export declare function computeElbowPoints(startWorld: Point, endWorld: Point, startBinding: Binding | null, endBinding: Binding | null, allElements: CanvasElement[], minStubLength?: number): number[];

package/dist/utils/labelMetrics.d.ts

@@ -36,6 +36,27 @@ export declare function measureLabelText(text: string, fontSize: number, fontFam
     width: number;
     height: number;
 };
+/**
+ * Compute the CSS half-leading offset for a given font.
+ *
+ * Konva renders text with `textBaseline='top'` — the glyph top aligns
+ * with the node's y position (no leading above).
+ * CSS distributes leading equally above and below the content area
+ * within each line box.  The half-leading is the space ABOVE the glyphs
+ * that CSS adds but Konva does not.
+ *
+ * To align a DOM textarea's visible text with Konva's rendered text,
+ * shift the textarea UP by this amount (in canvas-space pixels).
+ *
+ * Uses `fontBoundingBoxAscent/Descent` for accurate per-font measurement
+ * with a safe fallback for older browsers.
+ *
+ * @param fontSize   - Font size in canvas-space pixels
+ * @param fontFamily - CSS font-family string
+ * @param lineHeight - Line-height multiplier (default: LABEL_LINE_HEIGHT)
+ * @returns Half-leading in canvas-space pixels (≥ 0)
+ */
+export declare function computeHalfLeading(fontSize: number, fontFamily: string, lineHeight?: number): number;
 /**
  * Compute the full pill (background rect) dimensions for a connector label.
  *

package/dist/utils/markdown.d.ts

@@ -0,0 +1,14 @@
+export declare function htmlToPlainText(html: string): string;
+/**
+ * Render markdown text to inline-styled HTML.
+ * Safe for use with `innerHTML` — raw HTML in the source is escaped.
+ */
+export declare function renderMarkdown(text: string): string;
+export declare function markdownToPlainText(text: string): string;
+/** CSS class name for the markdown overlay container */
+export declare const MD_CLASS = "fc-md";
+/**
+ * CSS rules for markdown-rendered content.
+ * Injected once via a <style> tag by the overlay component.
+ */
+export declare const MD_STYLES = "\n.fc-md { line-height: inherit; }\n.fc-md p { margin: 0; }\n.fc-md h1 { margin: 0; font-weight: bold; font-size: 1.5em; line-height: 1.3; }\n.fc-md h2 { margin: 0; font-weight: bold; font-size: 1.3em; line-height: 1.3; }\n.fc-md h3 { margin: 0; font-weight: bold; font-size: 1.15em; line-height: 1.3; }\n.fc-md h4, .fc-md h5, .fc-md h6 { margin: 0; font-weight: bold; font-size: 1em; }\n.fc-md strong { font-weight: bold; }\n.fc-md em { font-style: italic; }\n.fc-md del { text-decoration: line-through; }\n.fc-md code {\n    background: rgba(0,0,0,0.06);\n    padding: 0.1em 0.3em;\n    border-radius: 3px;\n    font-size: 0.9em;\n    font-family: 'SF Mono', Monaco, Menlo, Consolas, monospace;\n}\n.fc-md pre {\n    background: rgba(0,0,0,0.06);\n    padding: 0.4em 0.6em;\n    border-radius: 4px;\n    font-size: 0.85em;\n    overflow-x: auto;\n    margin: 0.2em 0;\n}\n.fc-md pre code { background: none; padding: 0; font-size: inherit; }\n.fc-md ul, .fc-md ol { padding-left: 1.5em; margin: 0.15em 0; }\n.fc-md li { margin: 0; }\n.fc-md blockquote {\n    border-left: 3px solid rgba(0,0,0,0.15);\n    padding-left: 0.8em;\n    margin: 0.2em 0;\n    color: rgba(0,0,0,0.55);\n}\n.fc-md a { color: #4f8df7; text-decoration: underline; }\n.fc-md hr { border: none; border-top: 1px solid rgba(0,0,0,0.12); margin: 0.3em 0; }\n.fc-md img { max-width: 100%; }\n";

package/dist/utils/markdownEditing.d.ts

@@ -0,0 +1 @@
+export declare function serializeEditableHtmlToMarkdown(html: string): string;

package/dist/utils/textBinding.d.ts

@@ -0,0 +1,18 @@
+import { CanvasElement, ElementStyle, Point, TextElement } from '../types';
+export type TextContainerElement = Extract<CanvasElement, {
+    type: 'rectangle' | 'ellipse' | 'diamond' | 'image';
+}>;
+export declare function isTextContainerElement(element: CanvasElement): element is TextContainerElement;
+export declare function isPointInsideTextContainer(element: TextContainerElement, point: Point): boolean;
+export declare function findTopmostTextContainerAtPoint(elements: CanvasElement[], point: Point): TextContainerElement | null;
+/**
+ * Reorder elements so every bound text element is placed immediately
+ * after its container. This keeps a shape and its label at the same
+ * logical z-index — shapes stacked above the container occlude the
+ * label, and the label never leaks above unrelated foreground elements.
+ *
+ * Pure function — returns the input reference unchanged when no
+ * reordering is required so downstream memoization stays stable.
+ */
+export declare function orderBoundTextWithContainers(elements: CanvasElement[]): CanvasElement[];
+export declare function createBoundTextElement(id: string, container: TextContainerElement, style: ElementStyle): TextElement;

package/dist/utils/textStyleTargets.d.ts

@@ -0,0 +1,6 @@
+import { CanvasElement } from '../types';
+/**
+ * Resolve text element ids that should receive font style updates.
+ * Includes directly selected text elements and bound text from selected containers.
+ */
+export declare function collectTextStyleTargetIds(selectedIds: string[], elements: CanvasElement[]): string[];

package/dist/yjsProvider-mWrSFiNG.js

@@ -0,0 +1,100 @@
+import * as Y from "yjs";
+import { WebsocketProvider } from "y-websocket";
+let _doc = null;
+let _provider = null;
+let _config = null;
+let _statusListeners = /* @__PURE__ */ new Set();
+function createCollaborationProvider(config) {
+  if (_provider) {
+    destroyCollaborationProvider();
+  }
+  _config = config;
+  _doc = new Y.Doc();
+  _provider = new WebsocketProvider(
+    config.serverUrl,
+    config.roomName,
+    _doc,
+    {
+      connect: true,
+      params: config.authToken ? { token: config.authToken } : void 0
+    }
+  );
+  _provider.awareness.setLocalState({
+    user: config.user,
+    cursor: null,
+    selectedIds: []
+  });
+  _provider.on("status", (event) => {
+    const status = event.status;
+    for (const listener of _statusListeners) {
+      listener(status);
+    }
+  });
+  return { doc: _doc, provider: _provider };
+}
+function destroyCollaborationProvider() {
+  if (_provider) {
+    _provider.awareness.setLocalState(null);
+    _provider.disconnect();
+    _provider.destroy();
+    _provider = null;
+  }
+  if (_doc) {
+    _doc.destroy();
+    _doc = null;
+  }
+  _config = null;
+}
+function getYDoc() {
+  return _doc;
+}
+function getYProvider() {
+  return _provider;
+}
+function getYElements() {
+  return _doc == null ? void 0 : _doc.getMap("elements");
+}
+function getCollaborationConfig() {
+  return _config;
+}
+function isCollaborationActive() {
+  return _provider !== null && _provider.wsconnected;
+}
+function onStatusChange(listener) {
+  _statusListeners.add(listener);
+  return () => {
+    _statusListeners.delete(listener);
+  };
+}
+function updateAwareness(update) {
+  if (!_provider) return;
+  const current = _provider.awareness.getLocalState();
+  _provider.awareness.setLocalState({
+    ...current,
+    ...update
+  });
+}
+function getRemoteAwareness() {
+  if (!_provider) return /* @__PURE__ */ new Map();
+  const all = _provider.awareness.getStates();
+  const localId = _provider.awareness.clientID;
+  const remote = /* @__PURE__ */ new Map();
+  for (const [clientId, state] of all) {
+    if (clientId !== localId && state && state.user) {
+      remote.set(clientId, state);
+    }
+  }
+  return remote;
+}
+export {
+  createCollaborationProvider,
+  destroyCollaborationProvider,
+  getCollaborationConfig,
+  getRemoteAwareness,
+  getYDoc,
+  getYElements,
+  getYProvider,
+  isCollaborationActive,
+  onStatusChange,
+  updateAwareness
+};