@flowdrop/flowdrop 1.0.0

package/dist/types/settings.js

@@ -0,0 +1,97 @@
+/**
+ * Settings Types for FlowDrop
+ *
+ * Provides comprehensive type definitions for all user-configurable settings.
+ * Supports theme, editor, UI, behavior, and API settings with hybrid persistence.
+ *
+ * @module types/settings
+ */
+/**
+ * All available settings categories
+ */
+export const SETTINGS_CATEGORIES = ['theme', 'editor', 'ui', 'behavior', 'api'];
+/**
+ * Human-readable labels for settings categories
+ */
+export const SETTINGS_CATEGORY_LABELS = {
+    theme: 'Theme',
+    editor: 'Editor',
+    ui: 'UI',
+    behavior: 'Behavior',
+    api: 'API'
+};
+/**
+ * Icons for settings categories (Iconify icon names)
+ */
+export const SETTINGS_CATEGORY_ICONS = {
+    theme: 'mdi:palette',
+    editor: 'mdi:grid',
+    ui: 'mdi:view-dashboard',
+    behavior: 'mdi:cog-play',
+    api: 'mdi:api'
+};
+// =========================================================================
+// Default Settings
+// =========================================================================
+/**
+ * Default theme settings
+ */
+export const DEFAULT_THEME_SETTINGS = {
+    preference: 'dark'
+};
+/**
+ * Default editor settings
+ */
+export const DEFAULT_EDITOR_SETTINGS = {
+    showGrid: true,
+    snapToGrid: true,
+    gridSize: 20,
+    showMinimap: true,
+    defaultZoom: 1,
+    fitViewOnLoad: true,
+    proximityConnect: false,
+    proximityConnectDistance: 150
+};
+/**
+ * Default UI settings
+ */
+export const DEFAULT_UI_SETTINGS = {
+    sidebarWidth: 280,
+    sidebarCollapsed: false,
+    compactMode: false
+};
+/**
+ * Default behavior settings
+ */
+export const DEFAULT_BEHAVIOR_SETTINGS = {
+    autoSave: false,
+    autoSaveInterval: 30000,
+    undoHistoryLimit: 50,
+    confirmDelete: false
+};
+/**
+ * Default API settings
+ */
+export const DEFAULT_API_SETTINGS = {
+    timeout: 30000,
+    retryEnabled: true,
+    retryAttempts: 3,
+    cacheEnabled: false
+};
+/**
+ * Complete default settings object
+ */
+export const DEFAULT_SETTINGS = {
+    theme: DEFAULT_THEME_SETTINGS,
+    editor: DEFAULT_EDITOR_SETTINGS,
+    ui: DEFAULT_UI_SETTINGS,
+    behavior: DEFAULT_BEHAVIOR_SETTINGS,
+    api: DEFAULT_API_SETTINGS
+};
+// =========================================================================
+// Settings Persistence Types
+// =========================================================================
+/**
+ * localStorage key for persisting settings
+ */
+export const SETTINGS_STORAGE_KEY = 'flowdrop-settings';

package/dist/types/uischema.d.ts

@@ -0,0 +1,144 @@
+/**
+ * UISchema Types for FlowDrop Form Layout
+ *
+ * Inspired by JSON Forms (EclipseSource) UISchema specification.
+ * Controls how form fields are arranged, grouped, and displayed
+ * without modifying the underlying data schema (ConfigSchema).
+ *
+ * The UISchema is a separate concern from the data schema:
+ * - ConfigSchema defines what data is valid (validation)
+ * - UISchema defines how the form is rendered (presentation)
+ *
+ * @see https://jsonforms.io/docs/uischema
+ *
+ * @example
+ * ```json
+ * {
+ *   "type": "VerticalLayout",
+ *   "elements": [
+ *     { "type": "Control", "scope": "#/properties/model" },
+ *     {
+ *       "type": "Group",
+ *       "label": "Advanced Settings",
+ *       "collapsible": true,
+ *       "defaultOpen": false,
+ *       "elements": [
+ *         { "type": "Control", "scope": "#/properties/temperature" },
+ *         { "type": "Control", "scope": "#/properties/maxTokens" }
+ *       ]
+ *     }
+ *   ]
+ * }
+ * ```
+ */
+/**
+ * Supported UISchema element types.
+ * Designed for future extension with HorizontalLayout, Categorization, etc.
+ */
+export type UISchemaElementType = 'VerticalLayout' | 'Group' | 'Control';
+/**
+ * Base interface for all UISchema elements.
+ */
+export interface UISchemaElementBase {
+    /** Discriminator for the element type */
+    type: UISchemaElementType;
+}
+/**
+ * Control element - references a single field in the data schema.
+ * Uses JSON Pointer syntax for the scope path.
+ *
+ * @example
+ * ```json
+ * { "type": "Control", "scope": "#/properties/temperature" }
+ * ```
+ */
+export interface UISchemaControl extends UISchemaElementBase {
+    type: 'Control';
+    /**
+     * JSON Pointer to the property in the data schema.
+     * Must follow the format: #/properties/<fieldName>
+     */
+    scope: string;
+    /**
+     * Optional label override. If not provided, the field's
+     * schema title or key is used.
+     */
+    label?: string;
+}
+/**
+ * Layout container that arranges its child elements vertically.
+ * Can be used as root element or nested inside groups.
+ *
+ * @example
+ * ```json
+ * {
+ *   "type": "VerticalLayout",
+ *   "elements": [
+ *     { "type": "Control", "scope": "#/properties/name" },
+ *     { "type": "Control", "scope": "#/properties/email" }
+ *   ]
+ * }
+ * ```
+ */
+export interface UISchemaVerticalLayout extends UISchemaElementBase {
+    type: 'VerticalLayout';
+    /** Child elements to render vertically */
+    elements: UISchemaElement[];
+}
+/**
+ * Group element - renders a fieldset with a label and optional collapsible behavior.
+ * Extends the JSON Forms Group with FlowDrop-specific collapse options.
+ *
+ * @example
+ * ```json
+ * {
+ *   "type": "Group",
+ *   "label": "Advanced Settings",
+ *   "description": "Fine-tuning parameters",
+ *   "collapsible": true,
+ *   "defaultOpen": false,
+ *   "elements": [
+ *     { "type": "Control", "scope": "#/properties/temperature" },
+ *     { "type": "Control", "scope": "#/properties/maxTokens" }
+ *   ]
+ * }
+ * ```
+ */
+export interface UISchemaGroup extends UISchemaElementBase {
+    type: 'Group';
+    /** Display label for the fieldset legend / summary */
+    label: string;
+    /** Child elements within the group */
+    elements: UISchemaElement[];
+    /** Optional description displayed below the label */
+    description?: string;
+    /**
+     * Whether the group can be collapsed.
+     * When true, renders as `<details>/<summary>`.
+     * @default true
+     */
+    collapsible?: boolean;
+    /**
+     * Whether the group is initially open (expanded).
+     * Only relevant when collapsible is true.
+     * @default true
+     */
+    defaultOpen?: boolean;
+}
+/**
+ * Union type of all supported UISchema elements.
+ * This is the recursive type used in elements arrays.
+ */
+export type UISchemaElement = UISchemaControl | UISchemaVerticalLayout | UISchemaGroup;
+/**
+ * Type guard: checks if element is a Control
+ */
+export declare function isUISchemaControl(element: UISchemaElement): element is UISchemaControl;
+/**
+ * Type guard: checks if element is a VerticalLayout
+ */
+export declare function isUISchemaVerticalLayout(element: UISchemaElement): element is UISchemaVerticalLayout;
+/**
+ * Type guard: checks if element is a Group
+ */
+export declare function isUISchemaGroup(element: UISchemaElement): element is UISchemaGroup;

package/dist/types/uischema.js

@@ -0,0 +1,51 @@
+/**
+ * UISchema Types for FlowDrop Form Layout
+ *
+ * Inspired by JSON Forms (EclipseSource) UISchema specification.
+ * Controls how form fields are arranged, grouped, and displayed
+ * without modifying the underlying data schema (ConfigSchema).
+ *
+ * The UISchema is a separate concern from the data schema:
+ * - ConfigSchema defines what data is valid (validation)
+ * - UISchema defines how the form is rendered (presentation)
+ *
+ * @see https://jsonforms.io/docs/uischema
+ *
+ * @example
+ * ```json
+ * {
+ *   "type": "VerticalLayout",
+ *   "elements": [
+ *     { "type": "Control", "scope": "#/properties/model" },
+ *     {
+ *       "type": "Group",
+ *       "label": "Advanced Settings",
+ *       "collapsible": true,
+ *       "defaultOpen": false,
+ *       "elements": [
+ *         { "type": "Control", "scope": "#/properties/temperature" },
+ *         { "type": "Control", "scope": "#/properties/maxTokens" }
+ *       ]
+ *     }
+ *   ]
+ * }
+ * ```
+ */
+/**
+ * Type guard: checks if element is a Control
+ */
+export function isUISchemaControl(element) {
+    return element.type === 'Control';
+}
+/**
+ * Type guard: checks if element is a VerticalLayout
+ */
+export function isUISchemaVerticalLayout(element) {
+    return element.type === 'VerticalLayout';
+}
+/**
+ * Type guard: checks if element is a Group
+ */
+export function isUISchemaGroup(element) {
+    return element.type === 'Group';
+}

package/dist/utils/colors.d.ts

@@ -0,0 +1,288 @@
+/**
+ * Centralized color management for FlowDrop
+ * Ensures consistent category colors across sidebar and canvas
+ * Uses BEM syntax for CSS classes
+ */
+import type { NodeCategory, PortDataTypeConfig } from '../types/index.js';
+/**
+ * Category color mapping to design tokens (CSS variables)
+ * Uses --fd-node-* tokens from tokens.css
+ * These serve as static defaults; the categories store provides dynamic overrides.
+ */
+export declare const CATEGORY_COLOR_TOKENS: Record<string, string>;
+/**
+ * Get the design token for a category color.
+ * Checks the categories store first (which includes API overrides),
+ * then falls back to the static CATEGORY_COLOR_TOKENS map, then to slate.
+ */
+export declare function getCategoryColorToken(category: NodeCategory): string;
+/**
+ * Get the reference color token for a data type (configurable version)
+ */
+export declare function getDataTypeColorToken(dataType: string): string;
+/**
+ * Get data type configuration from port config
+ */
+export declare function getDataTypeConfig(dataType: string): PortDataTypeConfig | undefined;
+/**
+ * Get all available data types from port configuration
+ */
+export declare function getAvailableDataTypes(): PortDataTypeConfig[];
+/**
+ * Default colors for fallback cases
+ */
+export declare const DEFAULT_COLORS: {
+    background: string;
+    accent: string;
+    text: string;
+    border: string;
+};
+/**
+ * Get category colors
+ * @param category - The node category
+ * @returns The color configuration for the category
+ */
+export declare function getCategoryColors(category: NodeCategory): string;
+/**
+ * Get category background color
+ * @param category - The node category
+ * @returns The background color class
+ */
+export declare function getCategoryBackground(category: NodeCategory): string;
+/**
+ * Get category accent color
+ * @param category - The node category
+ * @returns The accent color class
+ */
+export declare function getCategoryAccent(category: NodeCategory): string;
+/**
+ * Get category text color
+ * @param category - The node category
+ * @returns The text color class
+ */
+export declare function getCategoryText(category: NodeCategory): string;
+/**
+ * Get category border color
+ * @param category - The node category
+ * @returns The border color class
+ */
+export declare function getCategoryBorder(category: NodeCategory): string;
+/**
+ * Get node colors based on category and state
+ * @param category - The node category
+ * @param isError - Whether the node is in error state
+ * @param isProcessing - Whether the node is processing
+ * @param isSelected - Whether the node is selected
+ * @returns The color configuration object
+ */
+export declare function getNodeColors(category: NodeCategory, isError?: boolean, isProcessing?: boolean, isSelected?: boolean): {
+    background: string;
+    accent: string;
+    text: string;
+    border: string;
+};
+/**
+ * Get node background color
+ * @param category - The node category
+ * @param isError - Whether the node is in error state
+ * @param isProcessing - Whether the node is processing
+ * @param isSelected - Whether the node is selected
+ * @returns The background color
+ */
+export declare function getNodeBackground(category: NodeCategory, isError?: boolean, isProcessing?: boolean, isSelected?: boolean): string;
+/**
+ * Get node accent color
+ * @param category - The node category
+ * @param isError - Whether the node is in error state
+ * @param isProcessing - Whether the node is processing
+ * @param isSelected - Whether the node is selected
+ * @returns The accent color
+ */
+export declare function getNodeAccent(category: NodeCategory, isError?: boolean, isProcessing?: boolean, isSelected?: boolean): string;
+/**
+ * Get node text color
+ * @param category - The node category
+ * @param isError - Whether the node is in error state
+ * @param isProcessing - Whether the node is processing
+ * @param isSelected - Whether the node is selected
+ * @returns The text color
+ */
+export declare function getNodeText(category: NodeCategory, isError?: boolean, isProcessing?: boolean, isSelected?: boolean): string;
+/**
+ * Get node border color
+ * @param category - The node category
+ * @param isError - Whether the node is in error state
+ * @param isProcessing - Whether the node is processing
+ * @param isSelected - Whether the node is selected
+ * @returns The border color
+ */
+export declare function getNodeBorder(category: NodeCategory, isError?: boolean, isProcessing?: boolean, isSelected?: boolean): string;
+/**
+ * Get data type color
+ * @param dataType - The data type
+ * @returns The color for the data type
+ */
+export declare function getDataTypeColor(dataType: string): string;
+/**
+ * Parse typed array notation and get display information
+ * @param dataType - The data type (e.g., "string[]", "number", "object[]")
+ * @returns Object with display information
+ */
+export declare function parseDataTypeDisplay(dataType: string): {
+    baseType: string;
+    isArray: boolean;
+    displayName: string;
+    elementType?: string;
+};
+/**
+ * Get formatted display text for a data type
+ * @param dataType - The data type
+ * @returns Formatted display text
+ */
+export declare function getDataTypeDisplayText(dataType: string): string;
+/**
+ * Check if a data type represents an array
+ * @param dataType - The data type
+ * @returns True if it's an array type
+ */
+export declare function isArrayDataType(dataType: string): boolean;
+/**
+ * Get the element type from an array data type
+ * @param arrayDataType - The array data type (e.g., "string[]")
+ * @returns The element type (e.g., "string") or null if not an array
+ */
+export declare function getArrayElementType(arrayDataType: string): string | null;
+/**
+ * Parse a hex color string to RGB components
+ * @param hex - Hex color string (e.g., "#f59e0b" or "f59e0b")
+ * @returns Object with r, g, b values (0-255) or null if invalid
+ */
+export declare function hexToRgb(hex: string): {
+    r: number;
+    g: number;
+    b: number;
+} | null;
+/**
+ * Calculate the relative luminance of a color
+ * Based on WCAG 2.1 guidelines for contrast calculations
+ * @param r - Red component (0-255)
+ * @param g - Green component (0-255)
+ * @param b - Blue component (0-255)
+ * @returns Relative luminance value (0-1)
+ */
+export declare function getRelativeLuminance(r: number, g: number, b: number): number;
+/**
+ * Determine if a background color is considered "light" (needs dark text)
+ * @param hex - Hex color string
+ * @returns True if the color is light and needs dark text for contrast
+ */
+export declare function isLightColor(hex: string): boolean;
+/**
+ * Get the appropriate contrast text color (black or white) for a background
+ * @param backgroundColor - Hex color string of the background
+ * @returns CSS color value for text that provides good contrast
+ */
+export declare function getContrastTextColor(backgroundColor: string): string;
+/**
+ * Resolve a CSS variable token to its hex value
+ * @param token - CSS variable token (e.g., "var(--fd-node-amber)")
+ * @returns Hex color value or the original value if not a known token
+ */
+export declare function resolveColorToken(token: string): string;
+/**
+ * Get the appropriate contrast text color for a data type badge
+ * @param dataType - The data type (e.g., "array", "string", "number")
+ * @returns CSS color value for text that provides good contrast on the data type's background
+ */
+export declare function getContrastTextColorForDataType(dataType: string): string;
+/**
+ * Get the appropriate contrast text color for a category badge
+ * @param category - The node category
+ * @returns CSS color value for text that provides good contrast on the category's background
+ */
+export declare function getContrastTextColorForCategory(category: NodeCategory): string;
+/**
+ * Get a semi-transparent tinted background color for ports
+ * Creates a cohesive look with the icon wrapper styling
+ * @param dataType - The data type
+ * @param opacity - Opacity percentage (default 25%)
+ * @returns CSS color-mix expression for the tinted background
+ */
+export declare function getPortBackgroundColor(dataType: string, opacity?: number): string;
+/**
+ * Get the border color for ports (solid data type color)
+ * @param dataType - The data type
+ * @returns CSS color value for the port border
+ */
+export declare function getPortBorderColor(dataType: string): string;
+/**
+ * Convert RGB components to hex color string
+ * @param r - Red component (0-255)
+ * @param g - Green component (0-255)
+ * @param b - Blue component (0-255)
+ * @returns Hex color string with # prefix
+ */
+export declare function rgbToHex(r: number, g: number, b: number): string;
+/**
+ * Generate a light tint of a color (similar to Tailwind's -50 shade)
+ * Creates a very light background-friendly version of the color for light mode
+ * @param hex - Base hex color string
+ * @returns Light tint hex color string
+ */
+export declare function getLightTint(hex: string): string;
+/**
+ * Generate a dark tint of a color for dark mode backgrounds
+ * Creates a subtle, muted version of the color that works well on dark backgrounds
+ * @param hex - Base hex color string
+ * @param opacity - Optional opacity for the color overlay (default 0.15)
+ * @returns Dark tint hex color string
+ */
+export declare function getDarkTint(hex: string, opacity?: number): string;
+/**
+ * Generate a border tint of a color (similar to Tailwind's -300 shade)
+ * Creates a medium-light version suitable for borders in light mode
+ * @param hex - Base hex color string
+ * @returns Border tint hex color string
+ */
+export declare function getBorderTint(hex: string): string;
+/**
+ * Generate a dark border tint of a color for dark mode
+ * Creates a medium-dark version suitable for borders in dark mode
+ * @param hex - Base hex color string
+ * @returns Dark border tint hex color string
+ */
+export declare function getDarkBorderTint(hex: string): string;
+/**
+ * Color variants interface for theming components
+ */
+export interface ColorVariants {
+    /** Base color value */
+    base: string;
+    /** Light tint for light mode backgrounds */
+    light: string;
+    /** Border tint for light mode borders */
+    border: string;
+    /** Dark tint for dark mode backgrounds */
+    darkLight: string;
+    /** Dark border tint for dark mode borders */
+    darkBorder: string;
+}
+/**
+ * Generate color variants for theming a component
+ * Returns variants for both light and dark modes
+ * @param baseColor - Base hex color string
+ * @returns Object with base, light, border, darkLight, and darkBorder color variants
+ */
+export declare function getColorVariants(baseColor: string): ColorVariants;
+/**
+ * Get theme-aware color variants
+ * Returns the appropriate light or dark variants based on the theme
+ * @param baseColor - Base hex color string
+ * @param isDarkMode - Whether dark mode is active
+ * @returns Object with base, background, and border colors appropriate for the theme
+ */
+export declare function getThemeAwareColorVariants(baseColor: string, isDarkMode: boolean): {
+    base: string;
+    background: string;
+    border: string;
+};