f1ow 0.1.4 → 1.0.0

package/dist/lib/FlowCanvasProps.d.ts

@@ -1,6 +1,8 @@
 import { CanvasElement, ElementStyle, ToolType } from '../types';
 import { ContextMenuItem } from '../components/ContextMenu/ContextMenu';
 import { CollaborationConfig } from '../collaboration/types';
+import { CustomElementConfig } from '../utils/elementRegistry';
+import { RenderAnnotationFn } from '../components/Canvas/AnnotationsOverlay';
 export type { ContextMenuItem };
 /** Context passed to custom context menu renderers */
 export interface ContextMenuContext {
@@ -68,6 +70,42 @@ export interface FlowCanvasProps {
     readOnly?: boolean;
     /** Additional CSS class for the root container */
     className?: string;
+    /**
+     * Render custom annotations, badges, or status indicators on top of canvas elements.
+     *
+     * The callback receives an `AnnotationContext` with:
+     * - `element`      — the canvas element being annotated
+     * - `screenBounds` — pre-computed screen-space `{ x, y, width, height }`
+     * - `scale`        — current viewport zoom level
+     *
+     * Return a React node to render, or `null` to skip.
+     * The node is positioned inside a `div` that matches the element's
+     * screen bounding box. Use `position: absolute` to place content
+     * relative to the element (e.g. `top: -10, right: -10` for a badge).
+     *
+     * **Important:** The entire overlay is `pointerEvents: 'none'`.
+     * Add `pointerEvents: 'auto'` on interactive nodes (buttons, badges).
+     *
+     * @example
+     * ```tsx
+     * <FlowCanvas
+     *   renderAnnotation={({ element, scale }) => {
+     *     if (element.type !== 'rectangle') return null;
+     *     return (
+     *       <div style={{
+     *         position: 'absolute', top: -10, right: -10,
+     *         pointerEvents: 'auto',
+     *         // Scale-aware badge sizing:
+     *         transform: `scale(${1 / scale})`, transformOrigin: 'top right',
+     *       }}>
+     *         🔴
+     *       </div>
+     *     );
+     *   }}
+     * />
+     * ```
+     */
+    renderAnnotation?: RenderAnnotationFn;
     /**
      * Additional context menu items to append after the built-in items.
      * Can be static items or a function that receives selection context.
@@ -84,6 +122,27 @@ export interface FlowCanvasProps {
      * Pass a `CollaborationConfig` to connect, or `undefined`/`null` to disable.
      */
     collaboration?: CollaborationConfig | null;
+    /**
+     * Register custom element types for this canvas instance.
+     *
+     * Each config is passed to `elementRegistry.register()` once on mount.
+     * Custom types go through the same validation pipeline as built-in types;
+     * the optional `validate` callback handles type-specific field checks.
+     *
+     * @example
+     * ```tsx
+     * <FlowCanvas
+     *   customElementTypes={[{
+     *     type: 'sticky-note',
+     *     displayName: 'Sticky Note',
+     *     validate: (el) =>
+     *       typeof el.content === 'string' || 'content must be a string',
+     *     defaults: { content: '', color: '#ffeb3b' },
+     *   }]}
+     * />
+     * ```
+     */
+    customElementTypes?: CustomElementConfig[];
     /**
      * Configure Web Workers for background processing (elbow routing, SVG export).
      *

package/dist/lib/index.d.ts

@@ -1,6 +1,7 @@
 export { default as FlowCanvas } from './FlowCanvas';
 export type { FlowCanvasProps, FlowCanvasRef, FlowCanvasTheme, ContextMenuItem, ContextMenuContext, } from './FlowCanvasProps';
 export { DEFAULT_THEME } from './FlowCanvasProps';
+export type { AnnotationContext, AnnotationScreenBounds, RenderAnnotationFn, } from '../components/Canvas/AnnotationsOverlay';
 export type { CanvasElement, RectangleElement, EllipseElement, DiamondElement, LineElement, ArrowElement, FreeDrawElement, TextElement, ImageElement, BaseElement, ElementStyle, ElementType, ToolType, Point, ViewportState, ConnectionAnchor, BoundElement, Binding, SnapTarget, Arrowhead, LineType, TextAlign, VerticalAlign, ImageScaleMode, ImageCrop, ElementMeta, CanvasOperation, } from '../types';
 export { useCanvasStore } from '../store/useCanvasStore';
 export { DEFAULT_STYLE, STROKE_COLORS, FILL_COLORS, STROKE_WIDTHS, TOOLS, ARROWHEAD_TYPES, LINE_TYPES, ROUGHNESS_CONFIGS } from '../constants';
@@ -9,6 +10,9 @@ export { distance, normalizeRect, rotatePoint, isPointInRect, getDiamondPoints,
 export { exportToDataURL, downloadPNG, exportToJSON, downloadJSON, exportToSVG, downloadSVG } from '../utils/export';
 export { drawArrowhead, arrowheadSize, flatToPoints } from '../utils/arrowheads';
 export { computeCurveControlPoint, quadBezierAt, quadBezierTangent, curveArrowPrev, CURVE_RATIO } from '../utils/curve';
+export { LABEL_PADDING_H, LABEL_PADDING_V, LABEL_CORNER, LABEL_LINE_HEIGHT, LABEL_MIN_WIDTH, measureLabelText, computePillSize } from '../utils/labelMetrics';
+export { elementRegistry, registerCustomElement } from '../utils/elementRegistry';
+export type { CustomElementConfig, ValidationResult } from '../utils/elementRegistry';
 export { computeElbowPoints, computeElbowRoute, simplifyElbowPath, clearElbowRouteCache, directionFromFixedPoint, directionFromPoints, directionFromShapeToPoint, directionFromEdgePoint, getElbowPreferredDirection, } from '../utils/elbow';
 export type { Direction } from '../utils/elbow';
 export { getConnectionPoints, getEdgePoint, getEdgePointFromFixedPoint, computeFixedPoint, getAnchorPosition, findNearestSnapTarget, isConnectable, recomputeBoundPoints, findConnectorsForElement, addBoundElement, removeBoundElement, syncBoundElements, } from '../utils/connection';

package/dist/utils/camera.d.ts

@@ -1,7 +1,7 @@
 import { ViewportState, CanvasElement } from '../types';
 import { AABB } from './performance';
 /** Predefined zoom steps for smooth discrete zooming */
-export declare const ZOOM_STEPS: readonly [0.1, 0.25, 0.5, 0.75, 1, 1.5, 2, 3, 4, 5];
+export declare const ZOOM_STEPS: readonly [0.1, 0.25, 0.33, 0.5, 0.67, 0.75, 1, 1.25, 1.5, 1.75, 2, 2.5, 3, 4, 5];
 /** Default animation duration in ms */
 export declare const DEFAULT_ANIMATION_DURATION = 280;
 export interface ZoomAtPointOptions {

package/dist/utils/connection.d.ts

@@ -1,4 +1,4 @@
-import { CanvasElement, Point, ConnectionAnchor, Binding, SnapTarget, ArrowElement, LineElement, BoundElement } from '../types';
+import { CanvasElement, Point, ConnectionAnchor, Binding, SnapTarget, ArrowElement, LineElement, TextElement, BoundElement } 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 */
@@ -120,3 +120,28 @@ export declare function removeBoundElement(shape: CanvasElement, refId: string):
  * @param updateElement Callback to persist the shape update
  */
 export declare function syncBoundElements(connectorId: string, connectorType: 'arrow' | 'line', oldBinding: Binding | null, newBinding: Binding | null, elements: CanvasElement[], updateElement: (id: string, updates: Partial<CanvasElement>) => void): void;
+/**
+ * Compute the midpoint position for a text label on a connector (arrow/line).
+ * Uses the connector's current points and lineType (sharp/curved/elbow)
+ * to find the visual midpoint, then centers the label around it.
+ *
+ * @param connector - The connector element (ArrowElement | LineElement)
+ * @param textWidth  - Current label text width (px)
+ * @param textHeight - Current label text height (px)
+ * @returns `{ x, y }` in world coordinates for the text element.
+ */
+export declare function computeConnectorLabelPosition(connector: LineElement | ArrowElement, textWidth: number, textHeight: number): {
+    x: number;
+    y: number;
+};
+/**
+ * Sync bound text labels for a list of connector elements.
+ * Returns an array of text element updates to batch-apply.
+ *
+ * @param connectorIds - IDs of connectors whose labels need syncing
+ * @param elMap        - O(1) element lookup map
+ */
+export declare function syncConnectorLabels(connectorIds: Iterable<string>, elMap: Map<string, CanvasElement>): Array<{
+    id: string;
+    updates: Partial<TextElement>;
+}>;

package/dist/utils/dragSync.d.ts

@@ -0,0 +1,50 @@
+import { CanvasElement } from '../types';
+/** Shared padding between shape containers and their bound text. */
+export declare const BOUND_TEXT_PADDING = 4;
+/** Shape types that can contain bound text. */
+export declare const CONTAINER_TYPES: ReadonlySet<string>;
+/**
+ * Compute the stored position for bound text inside a shape container.
+ *
+ * @param container  The container shape (needs x, y, width, height)
+ * @param text       The text element (needs height, optionally verticalAlign)
+ * @returns          `{ x, y, width }` updates to apply on the text element
+ */
+export declare function computeBoundTextPosition(container: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, text: {
+    height: number;
+    verticalAlign?: string;
+}): {
+    x: number;
+    y: number;
+    width: number;
+};
+export interface DragSyncResult {
+    /** Batched updates to apply to the store in a single write. */
+    updates: Array<{
+        id: string;
+        updates: Partial<CanvasElement>;
+    }>;
+    /** IDs of connectors that were recomputed (for dedup / further processing). */
+    processedConnectorIds: Set<string>;
+}
+/**
+ * After one or more elements are moved / resized, recompute:
+ *
+ * 1. Connector bound-points for all attached connectors
+ * 2. Bound text positions for shape containers
+ * 3. Connector-label positions (depend on updated connector geometry)
+ *
+ * Returns all updates as a flat array — the caller is responsible for
+ * applying them to the store (single `batchUpdateElements` call).
+ *
+ * @param movedIds    IDs of elements that were moved / resized
+ * @param elements    Current **full** element list (post position-write)
+ * @param skipIds     Optional set of IDs to skip (e.g. group-internal
+ *                    elements that already moved together)
+ */
+export declare function syncAfterDrag(movedIds: Iterable<string>, elements: CanvasElement[], skipIds?: ReadonlySet<string>): DragSyncResult;

package/dist/utils/elementRegistry.d.ts

@@ -0,0 +1,146 @@
+/**
+ * ─── Element Registry ────────────────────────────────────────────────────────
+ *
+ * A plugin/extension point that lets consumers register custom element types
+ * alongside the 8 built-in types.  Every element passing through
+ * `addElement`, `updateElement`, or `setElements` is validated here first.
+ *
+ * Built-in types (rectangle | ellipse | diamond | line | arrow |
+ * freedraw | text | image) are pre-validated with field-level checks.
+ * Custom types only need to pass the common base checks; additional
+ * field validation is supplied via the `validate` callback.
+ *
+ * @example — register a custom type globally before rendering:
+ * ```ts
+ * import { registerCustomElement } from 'f1ow';
+ *
+ * registerCustomElement({
+ *   type: 'sticky-note',
+ *   displayName: 'Sticky Note',
+ *   validate: (el) => typeof el.content === 'string' || 'content must be a string',
+ *   defaults: { content: '', color: '#ffeb3b' },
+ * });
+ * ```
+ *
+ * @example — or pass directly to the component (registered on mount):
+ * ```tsx
+ * <FlowCanvas
+ *   customElementTypes={[{
+ *     type: 'sticky-note',
+ *     validate: (el) => typeof el.content === 'string' || 'content must be a string',
+ *   }]}
+ * />
+ * ```
+ */
+/** Result of a validation call. */
+export type ValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    error: string;
+};
+/**
+ * Configuration object for a custom element type.
+ *
+ * @template T - Shape of the custom element's extra fields.
+ */
+export interface CustomElementConfig<T extends Record<string, unknown> = Record<string, unknown>> {
+    /**
+     * Unique type identifier.
+     * Must not conflict with a built-in type unless `allowOverride` is `true`.
+     */
+    type: string;
+    /** Human-readable name used in error/warning messages. Defaults to `type`. */
+    displayName?: string;
+    /**
+     * Additional validator for type-specific fields.
+     * Called **after** base-field (id, x, y, width, height, rotation, style)
+     * validation passes.
+     *
+     * Return `true` if the element is valid, or a string describing the error.
+     */
+    validate?: (element: Record<string, unknown>) => true | string;
+    /**
+     * Default field values merged into the element object when it is added via
+     * `addElement`.  Fields already present on the element are NOT overwritten.
+     * Only applied to elements whose type matches this config.
+     */
+    defaults?: Partial<T>;
+    /**
+     * Allow replacing an existing registration (built-in or custom).
+     * Useful when a consumer wants to tighten / relax built-in validation.
+     * Default: `false`.
+     */
+    allowOverride?: boolean;
+}
+declare class ElementRegistryClass {
+    private customs;
+    /**
+     * Register a custom element type.
+     *
+     * @throws If the type already exists and `allowOverride` is not `true`.
+     */
+    register(config: CustomElementConfig): void;
+    /** Returns `true` if the type is known (built-in or custom). */
+    isRegistered(type: string): boolean;
+    /** Retrieve the custom config for a type (undefined for built-in types). */
+    getCustomConfig(type: string): CustomElementConfig | undefined;
+    /** All registered type names, built-in first then custom. */
+    getRegisteredTypes(): string[];
+    /**
+     * Validate a full element before it enters the canvas store.
+     *
+     * Checks:
+     * 1. Non-null object with required base fields (id, type, x, y, w, h, rotation, style)
+     * 2. `type` is a known/registered type
+     * 3. Type-specific field checks for all 8 built-in types
+     * 4. Custom `validate` callback (custom types only)
+     */
+    validateElement(element: unknown): ValidationResult;
+    /**
+     * Validate a partial update before it is applied to an existing element.
+     *
+     * Prevents overwriting immutable fields (`id` and `type`), and checks
+     * numeric fields for finiteness.
+     */
+    validateUpdate(updates: Record<string, unknown>): ValidationResult;
+    /**
+     * Merge custom `defaults` into the element.
+     * Existing fields on the element take priority — defaults only fill gaps.
+     * Only active when the element's type has a custom config with `defaults`.
+     */
+    applyDefaults<T extends {
+        type?: unknown;
+    }>(element: T): T;
+    private _validateStyle;
+    private _validateBuiltinFields;
+}
+/**
+ * The global element registry singleton.
+ *
+ * Pre-populated with field-level validators for all 8 built-in element types.
+ * Imported by the canvas store to gate every element mutation.
+ *
+ * Use `elementRegistry.register()` or the `registerCustomElement()` helper
+ * to add new element types before rendering `<FlowCanvas>`.
+ */
+export declare const elementRegistry: ElementRegistryClass;
+/**
+ * Shorthand to register a custom element type on the global registry.
+ *
+ * Equivalent to `elementRegistry.register(config)`.
+ *
+ * @example
+ * ```ts
+ * import { registerCustomElement } from 'f1ow';
+ *
+ * registerCustomElement({
+ *   type: 'sticky-note',
+ *   displayName: 'Sticky Note',
+ *   validate: (el) => typeof el.content === 'string' || 'content must be a string',
+ *   defaults: { content: '', color: '#ffeb3b' },
+ * });
+ * ```
+ */
+export declare function registerCustomElement(config: CustomElementConfig): void;
+export {};

package/dist/utils/labelMetrics.d.ts

@@ -0,0 +1,49 @@
+/**
+ * labelMetrics.ts
+ *
+ * Single source of truth for connector label sizing — shared by both
+ * the Konva display path (TextShape render) and the DOM textarea editor.
+ *
+ * By measuring text with the same Canvas 2D API that Konva uses internally,
+ * both modes produce identical dimensions → no visual "jump" between
+ * display and editing.
+ *
+ * @see docs/CONNECTOR_LABEL_DESIGN.md
+ */
+/** Horizontal padding inside the pill background (px, canvas-space) */
+export declare const LABEL_PADDING_H = 8;
+/** Vertical padding inside the pill background (px, canvas-space) */
+export declare const LABEL_PADDING_V = 4;
+/** Corner radius of the pill background (px, canvas-space) */
+export declare const LABEL_CORNER = 4;
+/** Line-height multiplier — must match Konva <Text lineHeight> */
+export declare const LABEL_LINE_HEIGHT = 1.18;
+/** Minimum text content width to avoid zero-width pill */
+export declare const LABEL_MIN_WIDTH = 10;
+/**
+ * Measure text width/height using Canvas 2D — the same engine Konva uses.
+ *
+ * This function is the **single measurement source** for connector labels.
+ * Both the Konva `<Text>` node and the DOM `<textarea>` editor derive
+ * their dimensions from these numbers.
+ *
+ * @param text       - The label string (single-line; newlines ignored)
+ * @param fontSize   - Font size in canvas-space pixels
+ * @param fontFamily - CSS font-family string
+ * @returns `{ width, height }` in canvas-space pixels (not screen pixels)
+ */
+export declare function measureLabelText(text: string, fontSize: number, fontFamily: string): {
+    width: number;
+    height: number;
+};
+/**
+ * Compute the full pill (background rect) dimensions for a connector label.
+ *
+ * @param textWidth  - Measured text content width (from `measureLabelText`)
+ * @param textHeight - Measured text content height (from `measureLabelText`)
+ * @returns `{ width, height }` of the pill in canvas-space pixels
+ */
+export declare function computePillSize(textWidth: number, textHeight: number): {
+    width: number;
+    height: number;
+};

package/package.json

@@ -1,99 +1,107 @@
-{
-  "name": "f1ow",
-  "version": "0.1.4",
-  "type": "module",
-  "description": "Interactive canvas drawing toolkit built on KonvaJS — drop-in React component for diagrams, sketches & whiteboards",
-  "author": "Nuumz <info@nuumz.com>",
-  "homepage": "https://github.com/nuumz/f1ow-canvas#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/nuumz/f1ow-canvas.git"
-  },
-  "bugs": {
-    "url": "https://github.com/nuumz/f1ow-canvas/issues"
-  },
-  "main": "./dist/f1ow.umd.cjs",
-  "module": "./dist/f1ow.js",
-  "types": "./dist/lib/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/lib/index.d.ts",
-      "import": "./dist/f1ow.js",
-      "require": "./dist/f1ow.umd.cjs"
-    }
-  },
-  "files": [
-    "dist",
-    "LICENSE",
-    "README.md"
-  ],
-  "sideEffects": false,
-  "peerDependencies": {
-    "react": ">=17.0.0",
-    "react-dom": ">=17.0.0",
-    "konva": ">=9.0.0",
-    "react-konva": ">=18.0.0",
-    "zustand": ">=5.0.0",
-    "yjs": ">=13.0.0",
-    "y-websocket": ">=2.0.0"
-  },
-  "peerDependenciesMeta": {
-    "konva": {
-      "optional": false
-    },
-    "react-konva": {
-      "optional": false
-    },
-    "zustand": {
-      "optional": false
-    },
-    "yjs": {
-      "optional": true
-    },
-    "y-websocket": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@types/node": "^25.2.1",
-    "@types/rbush": "^4.0.0",
-    "@types/react": "^18.3.18",
-    "@types/react-dom": "^18.3.5",
-    "@vitejs/plugin-react": "^4.3.4",
-    "konva": "^9.3.18",
-    "lucide-react": "^0.468.0",
-    "nanoid": "^5.0.9",
-    "rbush": "^4.0.1",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
-    "react-konva": "^18.2.10",
-    "typescript": "^5.7.3",
-    "vite": "^6.0.7",
-    "vite-plugin-dts": "^4.3.0",
-    "y-websocket": "^3.0.0",
-    "yjs": "^13.6.29",
-    "zustand": "^5.0.3"
-  },
-  "keywords": [
-    "canvas",
-    "drawing",
-    "konvajs",
-    "react",
-    "whiteboard",
-    "diagram",
-    "flowchart",
-    "react-component",
-    "konva",
-    "collaborative",
-    "vector",
-    "sketch"
-  ],
-  "license": "MIT",
-  "scripts": {
-    "dev": "vite",
-    "build": "vite build",
-    "build:lib": "vite build --mode lib",
-    "preview": "vite preview",
-    "typecheck": "tsc --noEmit"
-  }
-}
+{
+  "name": "f1ow",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Interactive canvas drawing toolkit built on KonvaJS — drop-in React component for diagrams, sketches & whiteboards",
+  "author": "Nuumz <info@nuumz.com>",
+  "homepage": "https://github.com/nuumz/f1ow-canvas#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nuumz/f1ow-canvas.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nuumz/f1ow-canvas/issues"
+  },
+  "main": "./dist/f1ow.umd.cjs",
+  "module": "./dist/f1ow.js",
+  "types": "./dist/lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/lib/index.d.ts",
+      "import": "./dist/f1ow.js",
+      "require": "./dist/f1ow.umd.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "build:lib": "vite build --mode lib",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run build:lib"
+  },
+  "peerDependencies": {
+    "react": ">=17.0.0",
+    "react-dom": ">=17.0.0",
+    "konva": ">=9.0.0",
+    "react-konva": ">=18.0.0",
+    "zustand": ">=5.0.0",
+    "yjs": ">=13.0.0",
+    "y-websocket": ">=2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "konva": {
+      "optional": false
+    },
+    "react-konva": {
+      "optional": false
+    },
+    "zustand": {
+      "optional": false
+    },
+    "yjs": {
+      "optional": true
+    },
+    "y-websocket": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.1",
+    "@types/rbush": "^4.0.0",
+    "@types/react": "^18.3.18",
+    "@types/react-dom": "^18.3.5",
+    "@vitejs/plugin-react": "^4.3.4",
+    "konva": "^9.3.18",
+    "lucide-react": "^0.468.0",
+    "nanoid": "^5.0.9",
+    "rbush": "^4.0.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-konva": "^18.2.10",
+    "typescript": "^5.7.3",
+    "vite": "^6.0.7",
+    "vite-plugin-dts": "^4.3.0",
+    "y-websocket": "^3.0.0",
+    "yjs": "^13.6.29",
+    "zustand": "^5.0.3"
+  },
+  "keywords": [
+    "canvas",
+    "drawing",
+    "konvajs",
+    "react",
+    "whiteboard",
+    "diagram",
+    "flowchart",
+    "react-component",
+    "konva",
+    "collaborative",
+    "vector",
+    "sketch"
+  ],
+  "license": "MIT",
+  "pnpm": {
+    "overrides": {
+      "minimatch@9": "9.0.7",
+      "minimatch@10": "10.2.1",
+      "ajv": "8.18.0"
+    }
+  }
+}