f1ow 0.1.4 → 0.1.5

package/dist/lib/FlowCanvasProps.d.ts

@@ -1,6 +1,7 @@
 import { CanvasElement, ElementStyle, ToolType } from '../types';
 import { ContextMenuItem } from '../components/ContextMenu/ContextMenu';
 import { CollaborationConfig } from '../collaboration/types';
+import { CustomElementConfig } from '../utils/elementRegistry';
 export type { ContextMenuItem };
 /** Context passed to custom context menu renderers */
 export interface ContextMenuContext {
@@ -84,6 +85,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

@@ -9,6 +9,8 @@ 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 { 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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "f1ow",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "type": "module",
   "description": "Interactive canvas drawing toolkit built on KonvaJS — drop-in React component for diagrams, sketches & whiteboards",
   "author": "Nuumz <info@nuumz.com>",