@fabio.caffarello/react-design-system 1.7.0 → 1.9.0

package/dist/ui/extensions/flow/hooks/useFlowStyles.d.ts

@@ -0,0 +1,33 @@
+/**
+ * useFlowStyles Hook
+ *
+ * Hook for accessing and managing Flow CSS variables and theming.
+ */
+import type { FlowThemeVariables, ThemeMode } from '../styles/flow-theme';
+/**
+ * Flow Styles Hook Return
+ */
+export interface UseFlowStylesReturn {
+    theme: ThemeMode;
+    setTheme: (theme: ThemeMode) => void;
+    variables: FlowThemeVariables;
+    getVariable: (key: keyof FlowThemeVariables) => string;
+    setVariable: (key: keyof FlowThemeVariables, value: string) => void;
+    setVariables: (variables: Partial<FlowThemeVariables>) => void;
+    getCSSVariable: (cssVarName: string) => string;
+    setCSSVariable: (cssVarName: string, value: string) => void;
+    applyTheme: (theme: ThemeMode, overrides?: Partial<FlowThemeVariables>) => void;
+    resetTheme: () => void;
+    getNodeColor: () => string;
+    getNodeBackgroundColor: () => string;
+    getEdgeStroke: () => string;
+    getHandleBackgroundColor: () => string;
+}
+/**
+ * Hook for accessing and managing Flow styles
+ */
+export declare function useFlowStyles(): UseFlowStylesReturn;
+/**
+ * Optional hook for accessing Flow styles (returns null if provider not available)
+ */
+export declare function useFlowStylesOptional(): UseFlowStylesReturn | null;

package/dist/ui/extensions/flow/hooks/useFlowUtils.d.ts

@@ -0,0 +1,47 @@
+/**
+ * useFlowUtils Hook
+ *
+ * Hook for Flow utility functions (geometry, helpers, etc.).
+ */
+import type { Node, Edge, XYPosition, Position, InternalNode } from '@xyflow/react';
+/**
+ * Flow Utils Hook Return
+ */
+export interface UseFlowUtilsReturn {
+    getEdgeParams: (source: InternalNode, target: InternalNode) => {
+        sx: number;
+        sy: number;
+        tx: number;
+        ty: number;
+        sourcePos: Position;
+        targetPos: Position;
+    };
+    screenToFlowPosition: (screenPosition: XYPosition) => XYPosition;
+    flowToScreenPosition: (flowPosition: XYPosition) => XYPosition;
+    getNodeById: (nodeId: string) => Node | undefined;
+    getNodesByType: (type: string) => Node[];
+    getConnectedNodes: (nodeId: string) => Node[];
+    getEdgeById: (edgeId: string) => Edge | undefined;
+    getEdgesByType: (type: string) => Edge[];
+    getEdgesForNode: (nodeId: string) => Edge[];
+    fitView: (options?: {
+        padding?: number;
+        duration?: number;
+    }) => void;
+    zoomTo: (zoomLevel: number) => void;
+    panTo: (position: XYPosition) => void;
+    getViewport: () => {
+        x: number;
+        y: number;
+        zoom: number;
+    };
+    setViewport: (viewport: {
+        x: number;
+        y: number;
+        zoom: number;
+    }) => void;
+}
+/**
+ * Hook for Flow utility functions
+ */
+export declare function useFlowUtils(): UseFlowUtilsReturn;

package/dist/ui/extensions/flow/hooks/useFlowValidation.d.ts

@@ -0,0 +1,19 @@
+/**
+ * useFlowValidation Hook
+ *
+ * Hook for validating flow using validation rules.
+ */
+import type { ValidationResult } from '../organisms/FlowTypes';
+/**
+ * Hook for flow validation
+ *
+ * Validates the flow using rules from context.
+ */
+export declare function useFlowValidation(): {
+    validate: () => ValidationResult[];
+    errors: ValidationResult[];
+    warnings: ValidationResult[];
+    isValid: boolean;
+    hasErrors: boolean;
+    hasWarnings: boolean;
+};

package/dist/ui/extensions/flow/hooks/useFlowViewport.d.ts

@@ -0,0 +1,64 @@
+/**
+ * useFlowViewport Hook
+ *
+ * Hook for viewport management (zoom, pan, fit view).
+ */
+import type { XYPosition, FitViewOptions } from '@xyflow/react';
+/**
+ * Flow Viewport Hook Return
+ */
+export interface UseFlowViewportReturn {
+    viewport: {
+        x: number;
+        y: number;
+        zoom: number;
+    };
+    isInitialized: boolean;
+    zoomIn: (options?: {
+        duration?: number;
+    }) => void;
+    zoomOut: (options?: {
+        duration?: number;
+    }) => void;
+    zoomTo: (zoomLevel: number, options?: {
+        duration?: number;
+    }) => void;
+    getZoom: () => number;
+    setZoom: (zoom: number) => void;
+    panTo: (position: XYPosition, options?: {
+        duration?: number;
+    }) => void;
+    panBy: (delta: XYPosition, options?: {
+        duration?: number;
+    }) => void;
+    getCenter: () => XYPosition;
+    setCenter: (x: number, y: number, options?: {
+        duration?: number;
+    }) => void;
+    fitView: (options?: FitViewOptions) => void;
+    fitBounds: (bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }, options?: FitViewOptions) => void;
+    getViewport: () => {
+        x: number;
+        y: number;
+        zoom: number;
+    };
+    setViewport: (viewport: {
+        x: number;
+        y: number;
+        zoom: number;
+    }, options?: {
+        duration?: number;
+    }) => void;
+    resetViewport: () => void;
+    screenToFlowPosition: (screenPosition: XYPosition) => XYPosition;
+    flowToScreenPosition: (flowPosition: XYPosition) => XYPosition;
+}
+/**
+ * Hook for viewport management
+ */
+export declare function useFlowViewport(): UseFlowViewportReturn;

package/dist/ui/extensions/flow/hooks/useFlowVirtualization.d.ts

@@ -0,0 +1,17 @@
+/**
+ * useFlowVirtualization Hook
+ *
+ * Hook for viewport-based rendering in very large flows (>1000 nodes).
+ */
+import type { Node, Edge } from '@xyflow/react';
+/**
+ * Hook for flow virtualization
+ *
+ * Filters nodes and edges to only those visible in the viewport.
+ * Useful for flows with >1000 nodes.
+ */
+export declare function useFlowVirtualization(nodes: Node[], edges: Edge[], enabled?: boolean, padding?: number): {
+    visibleNodes: Node[];
+    visibleEdges: Edge[];
+    isVirtualized: boolean;
+};

package/dist/ui/extensions/flow/hooks/useKeyboardShortcuts.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Keyboard Shortcuts Hook
+ *
+ * Hook for managing keyboard shortcuts in the playground
+ */
+export interface KeyboardShortcut {
+    key: string;
+    ctrl?: boolean;
+    shift?: boolean;
+    alt?: boolean;
+    meta?: boolean;
+    action: () => void;
+    description?: string;
+}
+export interface UseKeyboardShortcutsOptions {
+    enabled?: boolean;
+    shortcuts: KeyboardShortcut[];
+}
+/**
+ * Hook for managing keyboard shortcuts
+ */
+export declare function useKeyboardShortcuts({ enabled, shortcuts }: UseKeyboardShortcutsOptions): void;
+/**
+ * Common keyboard shortcuts for playground
+ */
+export declare const PLAYGROUND_SHORTCUTS: {
+    readonly UNDO: {
+        readonly key: "z";
+        readonly ctrl: true;
+        readonly description: "Undo";
+    };
+    readonly REDO: {
+        readonly key: "y";
+        readonly ctrl: true;
+        readonly description: "Redo";
+    };
+    readonly REDO_ALT: {
+        readonly key: "z";
+        readonly ctrl: true;
+        readonly shift: true;
+        readonly description: "Redo (alternative)";
+    };
+    readonly DELETE: {
+        readonly key: "Delete";
+        readonly description: "Delete selected";
+    };
+    readonly DELETE_ALT: {
+        readonly key: "Backspace";
+        readonly description: "Delete selected (alternative)";
+    };
+    readonly SELECT_ALL: {
+        readonly key: "a";
+        readonly ctrl: true;
+        readonly description: "Select all";
+    };
+    readonly COPY: {
+        readonly key: "c";
+        readonly ctrl: true;
+        readonly description: "Copy";
+    };
+    readonly PASTE: {
+        readonly key: "v";
+        readonly ctrl: true;
+        readonly description: "Paste";
+    };
+    readonly CUT: {
+        readonly key: "x";
+        readonly ctrl: true;
+        readonly description: "Cut";
+    };
+    readonly SEARCH: {
+        readonly key: "f";
+        readonly ctrl: true;
+        readonly description: "Search";
+    };
+    readonly FIT_VIEW: {
+        readonly key: "f";
+        readonly description: "Fit view";
+    };
+    readonly ZOOM_IN: {
+        readonly key: "+";
+        readonly ctrl: true;
+        readonly description: "Zoom in";
+    };
+    readonly ZOOM_OUT: {
+        readonly key: "-";
+        readonly ctrl: true;
+        readonly description: "Zoom out";
+    };
+    readonly ZOOM_RESET: {
+        readonly key: "0";
+        readonly ctrl: true;
+        readonly description: "Reset zoom";
+    };
+    readonly TAB_1: {
+        readonly key: "1";
+        readonly alt: true;
+        readonly description: "Switch to Nodes & Edges tab";
+    };
+    readonly TAB_2: {
+        readonly key: "2";
+        readonly alt: true;
+        readonly description: "Switch to Canvas tab";
+    };
+    readonly TAB_3: {
+        readonly key: "3";
+        readonly alt: true;
+        readonly description: "Switch to Background tab";
+    };
+    readonly TAB_4: {
+        readonly key: "4";
+        readonly alt: true;
+        readonly description: "Switch to Layout tab";
+    };
+    readonly TAB_5: {
+        readonly key: "5";
+        readonly alt: true;
+        readonly description: "Switch to Validation tab";
+    };
+    readonly TAB_6: {
+        readonly key: "6";
+        readonly alt: true;
+        readonly description: "Switch to Code tab";
+    };
+    readonly TAB_7: {
+        readonly key: "7";
+        readonly alt: true;
+        readonly description: "Switch to Settings tab";
+    };
+};

package/dist/ui/extensions/flow/hooks/useNodeSelection.d.ts

@@ -0,0 +1,18 @@
+/**
+ * useNodeSelection Hook
+ *
+ * Hook for managing node selection using React Flow's useOnSelectionChange.
+ */
+import type { Node, Edge } from '@xyflow/react';
+/**
+ * Hook for node selection
+ *
+ * Tracks selected nodes and edges using React Flow's native hook.
+ */
+export declare function useNodeSelection(): {
+    selectedNodes: Node[];
+    selectedEdges: Edge[];
+    hasSelection: boolean;
+    selectedNodeIds: string[];
+    selectedEdgeIds: string[];
+};

package/dist/ui/extensions/flow/hooks/usePlaygroundHistory.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Playground History Hook
+ *
+ * Hook for managing undo/redo history in the playground
+ */
+import type { Node, Edge } from '@xyflow/react';
+import type { FlowNodeData, FlowEdgeData } from '../organisms/FlowTypes';
+export interface HistoryState {
+    nodes: Node<FlowNodeData>[];
+    edges: Edge<FlowEdgeData>[];
+    timestamp: number;
+}
+export interface UsePlaygroundHistoryReturn {
+    canUndo: boolean;
+    canRedo: boolean;
+    undo: () => HistoryState | null;
+    redo: () => HistoryState | null;
+    pushState: (nodes: Node<FlowNodeData>[], edges: Edge<FlowEdgeData>[]) => void;
+    clearHistory: () => void;
+}
+/**
+ * Hook for managing playground history
+ */
+export declare function usePlaygroundHistory(): UsePlaygroundHistoryReturn;

package/dist/ui/extensions/flow/hooks/usePlaygroundKeyboardNavigation.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Playground Keyboard Navigation Hook
+ *
+ * Enhanced keyboard navigation for the playground with focus management.
+ */
+export interface PlaygroundKeyboardNavigationOptions {
+    enabled?: boolean;
+    onNodeDelete?: (nodeId: string) => void;
+    onEdgeDelete?: (edgeId: string) => void;
+    onNodeSelect?: (nodeId: string) => void;
+    onEdgeSelect?: (edgeId: string) => void;
+}
+/**
+ * Hook for enhanced keyboard navigation in playground
+ */
+export declare function usePlaygroundKeyboardNavigation({ enabled, onNodeDelete, onEdgeDelete, onNodeSelect, onEdgeSelect, }?: PlaygroundKeyboardNavigationOptions): {
+    canvasRef: import("react").RefObject<HTMLDivElement | null>;
+};

package/dist/ui/extensions/flow/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Flow Extension
+ *
+ * Complete flow diagram system built on top of React Flow (@xyflow/react)
+ * with design system integration.
+ */
+export { FlowHandle, type FlowHandleProps } from './atoms/FlowHandle';
+export { FlowNodeWrapper, type FlowNodeWrapperProps } from './atoms/FlowNodeWrapper';
+export { CardNode, type CardNodeProps, type CardNodeData } from './molecules/CardNode';
+export { CustomNode, type CustomNodeProps, type CustomNodeData } from './molecules/CustomNode';
+export { CustomEdge, type CustomEdgeProps, type CustomEdgeData } from './molecules/CustomEdge';
+export { FlowNodeToolbar, type FlowNodeToolbarProps } from './molecules/FlowNodeToolbar';
+export { FlowNodeContent, type FlowNodeContentProps } from './molecules/FlowNodeContent';
+export { InputNode } from './molecules/InputNode';
+export { OutputNode } from './molecules/OutputNode';
+export { SelectorNode } from './molecules/SelectorNode';
+export { ResizableNode } from './molecules/ResizableNode';
+export { FloatingEdge } from './molecules/FloatingEdge';
+export { FloatingConnectionLine } from './molecules/FloatingConnectionLine';
+export { ColorSelectorNode, type ColorSelectorNodeProps, type ColorSelectorNodeData } from './molecules/ColorSelectorNode';
+export { TextNode, type TextNodeProps, type TextNodeData } from './molecules/TextNode';
+export { NoteNode, type NoteNodeProps, type NoteNodeData } from './molecules/NoteNode';
+export { FlowCanvas, FlowCanvasRoot } from './organisms/FlowCanvas';
+export type { FlowCanvasRootProps } from './organisms/FlowCanvas';
+export { FlowProvider, type FlowProviderProps } from './organisms/FlowProvider';
+export { FlowNodeResizer, type FlowNodeResizerProps } from './organisms/FlowNodeResizer';
+export { FlowDragHandle, type FlowDragHandleProps } from './organisms/FlowDragHandle';
+export { FlowEdgeToolbar, type FlowEdgeToolbarProps } from './organisms/FlowEdgeToolbar';
+export { FlowControls, type FlowControlsProps } from './organisms/FlowControls';
+export { FlowMinimap, type FlowMinimapProps } from './organisms/FlowMinimap';
+export { FlowBackground, type FlowBackgroundProps } from './organisms/FlowBackground';
+export { FlowPanel, type FlowPanelProps } from './organisms/FlowPanel';
+export { FlowContext, useFlowContext, useFlowContextOptional } from './organisms/FlowContext';
+export type * from './organisms/FlowTypes';
+export * from './hooks';
+export * from './providers';
+export * from './context';
+export * from './factories';
+export * from './registries';
+export * from './strategies';
+export * from './styles';
+export { NodeTypeRegistry } from './utils/nodeTypes';
+export { EdgeTypeRegistry } from './utils/edgeTypes';
+export { NodeFactory } from './utils/nodeFactory';
+export { EdgeFactory } from './utils/edgeFactory';
+export { FlowValidator } from './utils/validation';
+export { LayoutEngine, layoutEngine, DagreLayoutStrategy, ELKLayoutStrategy, ForceDirectedLayoutStrategy } from './utils/layoutEngine';
+export * from './utils/cssUtils';
+export * from './utils/geometryUtils';
+export * from './utils/performanceUtils';

package/dist/ui/extensions/flow/molecules/CardNode.d.ts

@@ -0,0 +1,40 @@
+/**
+ * CardNode Component
+ *
+ * Basic node component using Card from design system.
+ * Hybrid structure: Card for content + FlowNodeWrapper for handles.
+ * Follows Atomic Design principles as a Molecule component.
+ */
+import React from 'react';
+import { Position, type NodeProps } from '@xyflow/react';
+import type { FlowNodeData } from '../organisms/FlowTypes';
+export interface CardNodeData extends FlowNodeData {
+    /**
+     * Custom source handles configuration
+     */
+    sourceHandles?: Array<{
+        id?: string;
+        position: Position;
+        variant?: FlowNodeData['variant'];
+    }>;
+    /**
+     * Custom target handles configuration
+     */
+    targetHandles?: Array<{
+        id?: string;
+        position: Position;
+        variant?: FlowNodeData['variant'];
+    }>;
+    /**
+     * Whether to show default handles if custom handles are not provided
+     */
+    showDefaultHandles?: boolean;
+}
+export type CardNodeProps = NodeProps<CardNodeData>;
+/**
+ * CardNode Component
+ *
+ * Uses Card from design system for the node content,
+ * wrapped by FlowNodeWrapper for handles and theming.
+ */
+export declare const CardNode: React.MemoExoticComponent<({ data, selected, }: CardNodeProps) => import("react/jsx-runtime").JSX.Element>;

package/dist/ui/extensions/flow/molecules/ColorSelectorNode.d.ts

@@ -0,0 +1,32 @@
+import React, { ChangeEvent } from 'react';
+import { type NodeProps } from '@xyflow/react';
+import type { FlowNodeData } from '../organisms/FlowTypes';
+/**
+ * ColorSelectorNode Component
+ *
+ * Node with integrated color picker, based on the React Flow example.
+ * Allows users to select colors and update node/background colors dynamically.
+ *
+ * @example
+ * ```tsx
+ * <ColorSelectorNode
+ *   data={{
+ *     label: 'Color Picker',
+ *     color: '#1A192B',
+ *     onChange: (color) => console.log(color)
+ *   }}
+ * />
+ * ```
+ */
+export interface ColorSelectorNodeData extends FlowNodeData {
+    /**
+     * Current color value
+     */
+    color?: string;
+    /**
+     * Callback when color changes
+     */
+    onChange?: (event: ChangeEvent<HTMLInputElement>) => void;
+}
+export type ColorSelectorNodeProps = NodeProps<ColorSelectorNodeData>;
+export declare const ColorSelectorNode: React.MemoExoticComponent<({ data, selected, isConnectable, }: ColorSelectorNodeProps) => import("react/jsx-runtime").JSX.Element>;

package/dist/ui/extensions/flow/molecules/CustomEdge.d.ts

@@ -0,0 +1,100 @@
+import React from 'react';
+import { MarkerType } from '@xyflow/react';
+import type { EdgeProps } from '@xyflow/react';
+import type { FlowEdgeData } from '../organisms/FlowTypes';
+/**
+ * CustomEdge Component
+ *
+ * Enhanced custom edge component with support for multiple edge types,
+ * custom markers, advanced labels with styling, JSX/ReactNode labels,
+ * and edge toolbar integration.
+ * Uses React.memo for performance optimization.
+ *
+ * @example
+ * ```tsx
+ * <CustomEdge
+ *   data={{
+ *     edgeType: 'simplebezier',
+ *     label: 'Custom Label',
+ *     markerEnd: { type: MarkerType.ArrowClosed },
+ *     animated: true
+ *   }}
+ * />
+ * ```
+ */
+export interface CustomEdgeData extends FlowEdgeData {
+    /**
+     * Edge type: 'default' | 'bezier' | 'simplebezier' | 'smoothstep' | 'step' | 'straight'
+     */
+    edgeType?: 'default' | 'bezier' | 'simplebezier' | 'smoothstep' | 'step' | 'straight';
+    /**
+     * Label can be string or ReactNode
+     */
+    label?: string | React.ReactNode;
+    /**
+     * Label styling
+     */
+    labelStyle?: React.CSSProperties;
+    /**
+     * Label background style
+     */
+    labelBgStyle?: React.CSSProperties;
+    /**
+     * Label background padding [horizontal, vertical]
+     */
+    labelBgPadding?: [number, number];
+    /**
+     * Label background border radius
+     */
+    labelBgBorderRadius?: number;
+    /**
+     * Show label background
+     */
+    labelShowBg?: boolean;
+    /**
+     * Custom marker configuration for start
+     */
+    customMarkerStart?: {
+        type: MarkerType;
+        color?: string;
+        width?: number;
+        height?: number;
+        strokeWidth?: number;
+        orient?: 'auto' | 'auto-start-reverse';
+        markerUnits?: 'userSpaceOnUse' | 'strokeWidth';
+    };
+    /**
+     * Custom marker configuration for end
+     */
+    customMarkerEnd?: {
+        type: MarkerType;
+        color?: string;
+        width?: number;
+        height?: number;
+        strokeWidth?: number;
+        orient?: 'auto' | 'auto-start-reverse';
+        markerUnits?: 'userSpaceOnUse' | 'strokeWidth';
+    };
+    /**
+     * Edge toolbar configuration
+     */
+    toolbarConfig?: {
+        visible?: boolean;
+        actions?: Array<{
+            label: string;
+            icon?: React.ReactNode;
+            onClick: () => void;
+            variant?: 'primary' | 'regular' | 'secondary' | 'error' | 'outline' | 'ghost';
+        }>;
+    };
+    /**
+     * Path length for animated edges (used with stroke-dasharray)
+     */
+    pathLength?: number;
+    /**
+     * Custom CSS class name for the edge
+     */
+    customClassName?: string;
+}
+export type CustomEdgeProps = EdgeProps<CustomEdgeData>;
+export declare const CustomEdge: React.MemoExoticComponent<({ id, sourceX, sourceY, targetX, targetY, sourcePosition, targetPosition, data, selected, style, markerEnd: defaultMarkerEnd, markerStart: defaultMarkerStart, ...props }: CustomEdgeProps) => import("react/jsx-runtime").JSX.Element>;