@flowdrop/flowdrop 1.0.0

package/dist/registry/nodeComponentRegistry.js

@@ -0,0 +1,262 @@
+/**
+ * Node Component Registry
+ * Central registry for node component types that allows built-in and third-party
+ * components to be registered and resolved at runtime.
+ *
+ * This enables:
+ * - Custom node components to be registered by users
+ * - External libraries to contribute node types via plugins
+ * - Runtime switching between different node visualizations
+ */
+import { BaseRegistry } from './BaseRegistry.js';
+/**
+ * Central registry for node component types.
+ * Allows built-in and third-party components to be registered and resolved.
+ *
+ * Extends BaseRegistry for shared mechanics (subscribe, onClear, etc.).
+ *
+ * @example
+ * ```typescript
+ * // Register a custom node
+ * nodeComponentRegistry.register({
+ *     type: "myCustomNode",
+ *     displayName: "My Custom Node",
+ *     component: MyCustomNodeComponent,
+ *     icon: "mdi:star",
+ *     category: "custom"
+ * });
+ *
+ * // Get a component
+ * const component = nodeComponentRegistry.getComponent("myCustomNode");
+ * ```
+ */
+class NodeComponentRegistry extends BaseRegistry {
+    /** Default type to use when requested type is not found */
+    defaultType = 'workflowNode';
+    /** Initial default type, restored on clear() */
+    static INITIAL_DEFAULT_TYPE = 'workflowNode';
+    /**
+     * Register a node component type.
+     *
+     * @param registration - The component registration details
+     * @param overwrite - If true, allows overwriting existing registrations
+     * @throws Error if type already registered and overwrite is false
+     *
+     * @example
+     * ```typescript
+     * nodeComponentRegistry.register({
+     *     type: "fancy",
+     *     displayName: "Fancy Node",
+     *     component: FancyNode,
+     *     icon: "mdi:sparkles"
+     * });
+     * ```
+     */
+    /**
+     * Clear all registrations and reset default type.
+     */
+    clear() {
+        super.clear();
+        this.defaultType = NodeComponentRegistry.INITIAL_DEFAULT_TYPE;
+    }
+    register(registration, overwrite = false) {
+        if (this.items.has(registration.type) && !overwrite) {
+            throw new Error(`Node type "${registration.type}" is already registered. ` +
+                `Use overwrite: true to replace it, or use a namespaced type like "mylib:${registration.type}".`);
+        }
+        this.items.set(registration.type, registration);
+        this.notifyListeners();
+    }
+    /**
+     * Register multiple components at once.
+     * Useful for libraries registering multiple node types.
+     *
+     * @param registrations - Array of registrations to add
+     * @param overwrite - If true, allows overwriting existing registrations
+     */
+    registerAll(registrations, overwrite = false) {
+        for (const registration of registrations) {
+            this.register(registration, overwrite);
+        }
+    }
+    /**
+     * Get the component for a type, with fallback to default.
+     *
+     * @param type - The type identifier to look up
+     * @returns The component if found, or the default component
+     */
+    getComponent(type) {
+        const registration = this.items.get(type) ?? this.items.get(this.defaultType);
+        return registration?.component;
+    }
+    /**
+     * Get framework-agnostic metadata for a type, without the Svelte component.
+     *
+     * @param type - The type identifier to look up
+     * @returns The metadata if found, undefined otherwise
+     */
+    getMetadata(type) {
+        const reg = this.items.get(type);
+        if (!reg)
+            return undefined;
+        const { component: _, ...metadata } = reg;
+        return metadata;
+    }
+    /**
+     * Get all registered type identifiers.
+     *
+     * @returns Array of registered type strings
+     */
+    getTypes() {
+        return this.getKeys();
+    }
+    /**
+     * Get registrations filtered by criteria.
+     *
+     * @param filter - Filter options
+     * @returns Filtered array of registrations
+     *
+     * @example
+     * ```typescript
+     * // Get all visual nodes
+     * const visualNodes = nodeComponentRegistry.filter({ category: "visual" });
+     *
+     * // Get nodes from a specific library
+     * const libNodes = nodeComponentRegistry.filter({ source: "mylib" });
+     * ```
+     */
+    filter(filter) {
+        return this.getAll().filter((reg) => {
+            if (filter.category && reg.category !== filter.category) {
+                return false;
+            }
+            if (filter.source && reg.source !== filter.source) {
+                return false;
+            }
+            if (filter.predicate && !filter.predicate(reg)) {
+                return false;
+            }
+            return true;
+        });
+    }
+    /**
+     * Get registrations filtered by category.
+     *
+     * @param category - The category to filter by
+     * @returns Array of registrations in that category
+     */
+    getByCategory(category) {
+        return this.filter({ category });
+    }
+    /**
+     * Get registrations filtered by source.
+     *
+     * @param source - The source identifier to filter by (e.g., "flowdrop", "mylib")
+     * @returns Array of registrations from that source
+     */
+    getBySource(source) {
+        return this.filter({ source });
+    }
+    /**
+     * Set the default fallback type.
+     *
+     * @param type - The type to use as default when requested type is not found
+     * @throws Error if the type is not registered
+     */
+    setDefaultType(type) {
+        if (!this.items.has(type)) {
+            throw new Error(`Cannot set default to unregistered type: ${type}`);
+        }
+        this.defaultType = type;
+    }
+    /**
+     * Get the current default type.
+     *
+     * @returns The default type identifier
+     */
+    getDefaultType() {
+        return this.defaultType;
+    }
+    /**
+     * Get oneOf options for config forms.
+     * Returns array suitable for JSON Schema oneOf with const/title.
+     *
+     * @param filterFn - Optional filter function to limit which types are included
+     * @returns Array of oneOf items with const (type value) and title (display name)
+     *
+     * @example
+     * ```typescript
+     * const oneOf = nodeComponentRegistry.getOneOfOptions();
+     * // Use in configSchema: { type: "string", oneOf }
+     * ```
+     */
+    getOneOfOptions(filterFn) {
+        const registrations = filterFn ? this.getAll().filter(filterFn) : this.getAll();
+        return registrations.map((r) => ({
+            const: r.type,
+            title: r.displayName
+        }));
+    }
+    /**
+     * Get the status position for a node type.
+     *
+     * @param type - The node type
+     * @returns The status position, or default "top-right"
+     */
+    getStatusPosition(type) {
+        return this.items.get(type)?.statusPosition ?? 'top-right';
+    }
+    /**
+     * Get the status size for a node type.
+     *
+     * @param type - The node type
+     * @returns The status size, or default "md"
+     */
+    getStatusSize(type) {
+        return this.items.get(type)?.statusSize ?? 'md';
+    }
+}
+/** Singleton instance of the node component registry */
+export const nodeComponentRegistry = new NodeComponentRegistry();
+/**
+ * Helper function to create a namespaced type identifier.
+ * Use this to avoid conflicts when registering custom nodes.
+ *
+ * @param namespace - Your library/project namespace
+ * @param type - The node type name
+ * @returns Namespaced type string (e.g., "mylib:custom")
+ *
+ * @example
+ * ```typescript
+ * const type = createNamespacedType("mylib", "fancy");
+ * // Returns "mylib:fancy"
+ * ```
+ */
+export function createNamespacedType(namespace, type) {
+    return `${namespace}:${type}`;
+}
+/**
+ * Parse a namespaced type into its components.
+ *
+ * @param namespacedType - The full namespaced type (e.g., "mylib:custom")
+ * @returns Object with namespace and type, or null if not namespaced
+ *
+ * @example
+ * ```typescript
+ * parseNamespacedType("mylib:fancy");
+ * // Returns { namespace: "mylib", type: "fancy" }
+ *
+ * parseNamespacedType("simple");
+ * // Returns null (not namespaced)
+ * ```
+ */
+export function parseNamespacedType(namespacedType) {
+    const colonIndex = namespacedType.indexOf(':');
+    if (colonIndex === -1) {
+        return null;
+    }
+    return {
+        namespace: namespacedType.slice(0, colonIndex),
+        type: namespacedType.slice(colonIndex + 1)
+    };
+}

package/dist/registry/plugin.d.ts

@@ -0,0 +1,215 @@
+/**
+ * FlowDrop Plugin System
+ * Provides APIs for external libraries to register custom node components.
+ *
+ * This enables a plugin ecosystem where:
+ * - Third-party libraries can provide custom node types
+ * - Custom nodes are namespaced to avoid conflicts
+ * - Registration is simplified with a clean API
+ */
+import { type NodeComponentProps, type NodeComponentCategory, type StatusPosition, type StatusSize } from './nodeComponentRegistry.js';
+import type { Component } from 'svelte';
+/**
+ * Plugin configuration for external libraries.
+ * Use this to register multiple node types from a library.
+ */
+export interface FlowDropPluginConfig {
+    /**
+     * Unique namespace for this plugin.
+     * Used to prefix all node types (e.g., "mylib" -> "mylib:nodename").
+     * Should be lowercase, alphanumeric with optional hyphens.
+     */
+    namespace: string;
+    /** Display name for the plugin (for UI/debugging purposes) */
+    name: string;
+    /** Plugin version (optional, for debugging) */
+    version?: string;
+    /** Description of what this plugin provides */
+    description?: string;
+    /** Node components to register */
+    nodes: PluginNodeDefinition[];
+}
+/**
+ * Simplified node definition for plugins.
+ * Provides a cleaner API than full NodeComponentRegistration.
+ */
+export interface PluginNodeDefinition {
+    /**
+     * Type identifier for this node.
+     * Will be prefixed with the plugin namespace (e.g., "fancy" -> "mylib:fancy").
+     */
+    type: string;
+    /** Display name shown in UI */
+    displayName: string;
+    /** Description of what this node does */
+    description?: string;
+    /** The Svelte component to render */
+    component: Component<NodeComponentProps>;
+    /** Icon in iconify format (e.g., "mdi:star") */
+    icon?: string;
+    /** Category for organizing in UI */
+    category?: NodeComponentCategory;
+    /** Status overlay position */
+    statusPosition?: StatusPosition;
+    /** Status overlay size */
+    statusSize?: StatusSize;
+}
+/**
+ * Result of plugin registration.
+ * Contains information about what was registered and any errors.
+ */
+export interface PluginRegistrationResult {
+    /** Whether all nodes were registered successfully */
+    success: boolean;
+    /** The plugin namespace */
+    namespace: string;
+    /** Array of successfully registered type identifiers (namespaced) */
+    registeredTypes: string[];
+    /** Array of error messages for failed registrations */
+    errors: string[];
+}
+/**
+ * Register a FlowDrop plugin with custom node components.
+ * All node types are automatically namespaced with the plugin namespace.
+ *
+ * @param config - Plugin configuration with namespace and node definitions
+ * @returns Result object with registered types and any errors
+ *
+ * @example
+ * ```typescript
+ * import { registerFlowDropPlugin } from "@flowdrop/lib";
+ * import FancyNode from "./FancyNode.svelte";
+ * import GlowNode from "./GlowNode.svelte";
+ *
+ * const result = registerFlowDropPlugin({
+ *     namespace: "awesome",
+ *     name: "Awesome Nodes",
+ *     version: "1.0.0",
+ *     nodes: [
+ *         {
+ *             type: "fancy",
+ *             displayName: "Fancy Node",
+ *             component: FancyNode,
+ *             icon: "mdi:sparkles"
+ *         },
+ *         {
+ *             type: "glow",
+ *             displayName: "Glowing Node",
+ *             component: GlowNode,
+ *             icon: "mdi:lightbulb"
+ *         }
+ *     ]
+ * });
+ *
+ * // Result:
+ * // {
+ * //     success: true,
+ * //     namespace: "awesome",
+ * //     registeredTypes: ["awesome:fancy", "awesome:glow"],
+ * //     errors: []
+ * // }
+ * ```
+ */
+export declare function registerFlowDropPlugin(config: FlowDropPluginConfig): PluginRegistrationResult;
+/**
+ * Unregister all nodes from a plugin by namespace.
+ *
+ * @param namespace - The plugin namespace to unregister
+ * @returns Array of unregistered type identifiers
+ *
+ * @example
+ * ```typescript
+ * const removed = unregisterFlowDropPlugin("awesome");
+ * // Returns ["awesome:fancy", "awesome:glow"]
+ * ```
+ */
+export declare function unregisterFlowDropPlugin(namespace: string): string[];
+/**
+ * Check if a namespace is valid.
+ * Must be lowercase alphanumeric with optional hyphens.
+ *
+ * @param namespace - The namespace to validate
+ * @returns true if valid
+ */
+export declare function isValidNamespace(namespace: string): boolean;
+/**
+ * Get all registered plugins (unique namespaces).
+ *
+ * @returns Array of namespace strings
+ */
+export declare function getRegisteredPlugins(): string[];
+/**
+ * Get the count of nodes registered by a plugin.
+ *
+ * @param namespace - The plugin namespace
+ * @returns Number of nodes registered by this plugin
+ */
+export declare function getPluginNodeCount(namespace: string): number;
+/**
+ * Register a single custom node without a full plugin.
+ * Useful for project-specific custom nodes.
+ *
+ * @param type - Type identifier (can be namespaced or plain)
+ * @param displayName - Display name for UI
+ * @param component - Svelte component
+ * @param options - Additional options
+ *
+ * @example
+ * ```typescript
+ * import { registerCustomNode } from "@flowdrop/lib";
+ * import MyNode from "./MyNode.svelte";
+ *
+ * registerCustomNode("myproject:special", "Special Node", MyNode, {
+ *     icon: "mdi:star",
+ *     description: "A special node for my project"
+ * });
+ * ```
+ */
+export declare function registerCustomNode(type: string, displayName: string, component: Component<NodeComponentProps>, options?: {
+    description?: string;
+    icon?: string;
+    category?: NodeComponentCategory;
+    source?: string;
+    statusPosition?: StatusPosition;
+    statusSize?: StatusSize;
+}): void;
+/**
+ * Create a plugin builder for a fluent API experience.
+ *
+ * @param namespace - Plugin namespace
+ * @param name - Plugin name
+ * @returns Plugin builder with chainable methods
+ *
+ * @example
+ * ```typescript
+ * import { createPlugin } from "@flowdrop/lib";
+ *
+ * createPlugin("awesome", "Awesome Nodes")
+ *     .version("1.0.0")
+ *     .node("fancy", "Fancy Node", FancyNode)
+ *     .node("glow", "Glowing Node", GlowNode, { icon: "mdi:lightbulb" })
+ *     .register();
+ * ```
+ */
+export declare function createPlugin(namespace: string, name: string): {
+    /**
+     * Set plugin version
+     */
+    version(v: string): /*elided*/ any;
+    /**
+     * Set plugin description
+     */
+    description(desc: string): /*elided*/ any;
+    /**
+     * Add a node to the plugin
+     */
+    node(type: string, displayName: string, component: Component<NodeComponentProps>, options?: Partial<Omit<PluginNodeDefinition, "type" | "displayName" | "component">>): /*elided*/ any;
+    /**
+     * Register the plugin
+     */
+    register(): PluginRegistrationResult;
+    /**
+     * Get the config without registering (for testing/inspection)
+     */
+    getConfig(): FlowDropPluginConfig;
+};