@elevasis/ui 1.0.0

package/dist/graph/index.d.ts

@@ -0,0 +1,429 @@
+export { default as graphStyles } from './Graph.module.css';
+import { Node, Edge, NodeMouseHandler, EdgeProps, Position } from '@xyflow/react';
+import * as react from 'react';
+import { MouseEvent, CSSProperties, ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Graph Component Constants
+ *
+ * Shared constants for graph layout, dimensions, and behavior
+ */
+declare const GRAPH_CONSTANTS: {
+    readonly NODE_WIDTH: 220;
+    readonly NODE_HEIGHT: 140;
+    readonly HANDLE_SIZE: 12;
+    readonly MIN_ZOOM: 0.2;
+    readonly MAX_ZOOM: 1.5;
+    readonly RANK_SEP: 140;
+    readonly NODE_SEP: 60;
+};
+
+/**
+ * Resource Type Metadata
+ *
+ * Centralized metadata for ResourceDefinition types including icon names and colors.
+ * Icon names reference @tabler/icons-react - UI layer maps these to actual components.
+ */
+
+/**
+ * Node color types for graph visualization
+ * Used by both @repo/core (metadata) and @repo/ui (components)
+ */
+type NodeColorType = 'violet' | 'blue' | 'orange' | 'teal' | 'gray' | 'yellow';
+
+/**
+ * Graph Component Types
+ *
+ * Shared type definitions for graph components
+ */
+
+type GlowIntensity = 'none' | 'subtle' | 'medium' | 'intense';
+interface GraphThemeColors {
+    primary: string;
+    agent: string;
+    workflow: string;
+    trigger: string;
+    integration: string;
+    approval: string;
+    primaryGlow: string;
+    agentGlow: string;
+    workflowGlow: string;
+    triggerGlow: string;
+    integrationGlow: string;
+    approvalGlow: string;
+    edgeTriggers: string;
+    edgeUses: string;
+    edgeApproval: string;
+    edgeTriggersGlow: string;
+    edgeUsesGlow: string;
+    edgeApprovalGlow: string;
+}
+
+/**
+ * useGraphTheme - Hook for theme-aware graph colors
+ *
+ * Returns color values that adapt to light/dark mode for graph elements.
+ * Self-contained: derives colors from hardcoded domain palette using color-mix().
+ */
+
+declare function useGraphTheme(): GraphThemeColors;
+
+/**
+ * useConnectionHighlight - Hook to track and highlight connected nodes/edges
+ *
+ * When a node is hovered, highlights all directly connected nodes and edges
+ * while dimming unconnected elements for better visual clarity.
+ */
+
+interface UseConnectionHighlightReturn {
+    hoveredNodeId: string | null;
+    highlightedNodeIds: Set<string>;
+    highlightedEdgeIds: Set<string>;
+    onNodeMouseEnter: (nodeId: string) => void;
+    onNodeMouseLeave: () => void;
+    getNodeClassName: (nodeId: string) => string;
+    getEdgeClassName: (edgeId: string) => string;
+}
+/**
+ * Hook to manage connection highlighting state
+ */
+declare function useConnectionHighlight(nodes: Node[], edges: Edge[]): UseConnectionHighlightReturn;
+
+/**
+ * useGraphHighlighting - Higher-level hook for connection highlighting
+ *
+ * Wraps useConnectionHighlight and automatically applies CSS classes to nodes/edges
+ * based on hover state. Eliminates boilerplate code in graph components.
+ *
+ * @example
+ * ```tsx
+ * const { nodes, edges, handleNodeMouseEnter, handleNodeMouseLeave } =
+ *   useGraphHighlighting(layoutNodes, layoutEdges)
+ *
+ * <ReactFlow
+ *   nodes={nodes}
+ *   edges={edges}
+ *   onNodeMouseEnter={handleNodeMouseEnter}
+ *   onNodeMouseLeave={handleNodeMouseLeave}
+ * />
+ * ```
+ */
+
+interface GraphHighlightingResult {
+    nodes: Node[];
+    edges: Edge[];
+    handleNodeMouseEnter: NodeMouseHandler;
+    handleNodeMouseLeave: NodeMouseHandler;
+}
+/**
+ * Apply connection highlighting to nodes and edges
+ *
+ * @param layoutNodes - Nodes from layout algorithm (without highlight classes)
+ * @param layoutEdges - Edges from layout algorithm (without highlight classes)
+ * @returns Nodes/edges with highlight classes and mouse handlers
+ */
+declare function useGraphHighlighting(layoutNodes: Node[], layoutEdges: Edge[]): GraphHighlightingResult;
+
+/**
+ * useDirectedChainHighlighting - Directed chain highlighting for ReactFlow graphs
+ *
+ * When a node is hovered, highlights all predecessors (upstream) and successors
+ * (downstream) following edge direction, while dimming unrelated nodes.
+ *
+ * Pre-computes directed reachability for O(1) lookup on hover.
+ *
+ * @example
+ * ```tsx
+ * const { nodes, edges, handleNodeMouseEnter, handleNodeMouseLeave } =
+ *   useDirectedChainHighlighting(layoutNodes, layoutEdges)
+ *
+ * <ReactFlow
+ *   nodes={nodes}
+ *   edges={edges}
+ *   onNodeMouseEnter={handleNodeMouseEnter}
+ *   onNodeMouseLeave={handleNodeMouseLeave}
+ * />
+ * ```
+ */
+
+interface DirectedChainHighlightingOptions {
+    /** Optional selected node ID - its chain will always be highlighted */
+    selectedNodeId?: string | null;
+}
+interface DirectedChainHighlightingResult<N extends Node, E extends Edge> {
+    nodes: N[];
+    edges: E[];
+    hoveredNodeId: string | null;
+    handleNodeMouseEnter: NodeMouseHandler;
+    handleNodeMouseLeave: NodeMouseHandler;
+}
+/**
+ * Apply directed chain highlighting to graph nodes and edges
+ *
+ * @param layoutNodes - Nodes from layout algorithm
+ * @param layoutEdges - Edges from layout algorithm
+ * @param options - Optional configuration (selectedNodeId for persistent chain highlight)
+ * @returns Nodes/edges with highlight classes and mouse handlers
+ */
+declare function useDirectedChainHighlighting<N extends Node, E extends Edge>(layoutNodes: N[], layoutEdges: E[], options?: DirectedChainHighlightingOptions): DirectedChainHighlightingResult<N, E>;
+
+/**
+ * Generic hook for handling node selection in ReactFlow graphs
+ * Supports both string-based and number-based node IDs
+ */
+declare function useNodeSelection<T extends string | number>(selectedId: T | null, onSelect: (id: T | null) => void): {
+    handleNodeClick: (event: MouseEvent, node: Node) => void;
+    handlePaneClick: () => void;
+    handleContainerClick: (event: MouseEvent) => void;
+};
+
+/**
+ * Hook to trigger fit view when data or nodes change
+ *
+ * @param data - Data that triggers fit view when changed (e.g., timelineData, iterationData)
+ * @param nodes - ReactFlow nodes array
+ * @returns fitViewTrigger - Increment value to pass to GraphFitViewHandler
+ */
+declare function useFitViewTrigger(data: unknown, nodes: Node[]): number;
+
+interface GraphContainerProps {
+    children: React.ReactNode;
+    height?: number | string;
+}
+/**
+ * Returns the animated grid background styles for the current theme.
+ * Uses color-mix() with --color-primary so the grid adapts to any preset.
+ *
+ * @param isDark - Whether dark mode is active
+ * @returns CSSProperties object with background styles
+ */
+declare function getGraphBackgroundStyles(isDark: boolean): CSSProperties;
+/**
+ * Hook that returns the animated grid background styles for the current theme
+ *
+ * @returns CSSProperties object with background styles
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const backgroundStyles = useGraphBackgroundStyles()
+ *
+ *   return (
+ *     <div style={{ ...myStyles, ...backgroundStyles }}>
+ *       Content
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+declare function useGraphBackgroundStyles(): CSSProperties;
+declare function GraphContainer({ children, height }: GraphContainerProps): react_jsx_runtime.JSX.Element;
+/**
+ * GraphBackground - Empty background component (no dots)
+ *
+ * Usage: Place inside <ReactFlow> component
+ */
+declare function GraphBackground(): null;
+
+/**
+ * GraphLegend - Legend panel for graph visualization
+ *
+ * Provides:
+ * - Theme-aware styling using CSS variables
+ * - Colored legend dots (for nodes) or lines (for edges)
+ * - Flexible positioning
+ */
+interface LegendItem {
+    color: string;
+    label: string;
+    /** Use 'line' for edge legends, 'dot' (default) for node legends */
+    type?: 'dot' | 'line';
+}
+interface GraphLegendProps {
+    title?: string;
+    items: LegendItem[];
+    position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+}
+/**
+ * GraphLegend - Main legend component
+ *
+ * Renders a glassmorphism panel with colored legend items.
+ * Can be positioned in any corner of the graph.
+ */
+declare function GraphLegend({ title, items, position }: GraphLegendProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * GraphFitViewButton - Custom fit view button for ReactFlow graphs
+ *
+ * Supports two variants:
+ * - 'reactflow': Native ReactFlow button style
+ * - 'mantine': Mantine ActionIcon with theme support
+ */
+type FitViewButtonVariant = 'reactflow' | 'mantine';
+interface GraphFitViewButtonProps {
+    padding?: number;
+    variant?: FitViewButtonVariant;
+    duration?: number;
+}
+/**
+ * GraphFitViewButton - Custom fit view button for ReactFlow visualizers
+ *
+ * Usage:
+ * ```tsx
+ * <ReactFlow>
+ *   <GraphFitViewButton padding={0.15} variant="mantine" duration={300} />
+ * </ReactFlow>
+ * ```
+ */
+declare function GraphFitViewButton({ padding, variant, duration }: GraphFitViewButtonProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * GraphFitViewHandler - Programmatic fit view trigger component
+ *
+ * Used to trigger fitView after animations complete (e.g., Mantine Collapse).
+ * Must be placed inside ReactFlow component.
+ *
+ * @example
+ * ```tsx
+ * const [fitViewTrigger, setFitViewTrigger] = useState(0)
+ *
+ * // When collapse expands, trigger fit view
+ * const handleExpand = () => {
+ *   setExpanded(true)
+ *   setFitViewTrigger(prev => prev + 1)
+ * }
+ *
+ * <ReactFlow>
+ *   <GraphFitViewHandler trigger={fitViewTrigger} />
+ * </ReactFlow>
+ * ```
+ */
+interface GraphFitViewHandlerProps {
+    /**
+     * Trigger value - increment to trigger fitView
+     * Must be > 0 to trigger
+     */
+    trigger?: number;
+    /**
+     * Padding around nodes when fitting view
+     * @default 0.15
+     */
+    padding?: number;
+    /**
+     * Animation duration in milliseconds
+     * @default 300
+     */
+    duration?: number;
+    /**
+     * Delay before triggering fitView (to wait for animations)
+     * @default 250
+     */
+    delay?: number;
+}
+/**
+ * Invisible component that triggers fitView when trigger value changes
+ *
+ * @param trigger - Increment this value to trigger fitView
+ * @param padding - Padding around nodes (default: 0.15)
+ * @param duration - Animation duration in ms (default: 300)
+ * @param delay - Delay before triggering in ms (default: 250)
+ */
+declare function GraphFitViewHandler({ trigger, padding, duration, delay }: GraphFitViewHandlerProps): null;
+
+interface BaseNodeProps {
+    children: ReactNode;
+    color: NodeColorType;
+    selected?: boolean;
+    highlighted?: boolean;
+    width?: number;
+    className?: string;
+    /** Handle layout direction: 'horizontal' (left/right) or 'vertical' (top/bottom) */
+    handleDirection?: 'horizontal' | 'vertical';
+    /** Whether to render the source (outgoing) handle. Default: true */
+    showSourceHandle?: boolean;
+    /** Whether to render the target (incoming) handle. Default: true */
+    showTargetHandle?: boolean;
+}
+declare const BaseNode: react.NamedExoticComponent<BaseNodeProps>;
+
+interface BaseEdgeProps {
+    id: string;
+    sourceX: number;
+    sourceY: number;
+    targetX: number;
+    targetY: number;
+    sourcePosition: EdgeProps['sourcePosition'];
+    targetPosition: EdgeProps['targetPosition'];
+    color: string;
+    glowColor: string;
+    label?: string;
+    animated?: boolean;
+    selected?: boolean;
+    dimmed?: boolean;
+    edgeIndex?: number;
+    totalEdges?: number;
+}
+declare const BaseEdge: react.NamedExoticComponent<BaseEdgeProps>;
+
+interface GlowingHandleProps {
+    type: 'source' | 'target';
+    position: Position;
+    color: NodeColorType;
+    id?: string;
+}
+declare function GlowingHandle({ type, position, color: _color, id }: GlowingHandleProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * calculateGraphHeight - Dynamic height calculation for graph containers
+ *
+ * Calculates container height based on item count with min/max bounds.
+ * Useful for graphs that grow with content (workflow steps, knowledge nodes, etc.)
+ *
+ * @example
+ * ```tsx
+ * const containerHeight = calculateGraphHeight({
+ *   itemCount: workflow.steps.length,
+ *   minHeight: 300,
+ *   maxHeight: 500,
+ *   heightPerItem: 80
+ * })
+ *
+ * <div style={{ height: containerHeight }}>
+ *   <ReactFlow ... />
+ * </div>
+ * ```
+ */
+interface GraphHeightOptions {
+    /**
+     * Number of items to calculate height for
+     */
+    itemCount: number;
+    /**
+     * Minimum container height in pixels
+     * @default 300
+     */
+    minHeight?: number;
+    /**
+     * Maximum container height in pixels
+     * @default 500
+     */
+    maxHeight?: number;
+    /**
+     * Additional height per item in pixels
+     * @default 80
+     */
+    heightPerItem?: number;
+}
+/**
+ * Calculate dynamic container height based on item count
+ *
+ * Formula: min(minHeight + (itemCount * heightPerItem), maxHeight)
+ *
+ * @param options - Configuration for height calculation
+ * @returns Container height in pixels
+ */
+declare function calculateGraphHeight({ itemCount, minHeight, maxHeight, heightPerItem }: GraphHeightOptions): number;
+
+export { BaseEdge, BaseNode, GRAPH_CONSTANTS, GlowingHandle, GraphBackground, GraphContainer, GraphFitViewButton, GraphFitViewHandler, GraphLegend, calculateGraphHeight, getGraphBackgroundStyles, useConnectionHighlight, useDirectedChainHighlighting, useFitViewTrigger, useGraphBackgroundStyles, useGraphHighlighting, useGraphTheme, useNodeSelection };
+export type { DirectedChainHighlightingOptions, DirectedChainHighlightingResult, FitViewButtonVariant, GlowIntensity, GraphFitViewHandlerProps, GraphHeightOptions, GraphHighlightingResult, GraphThemeColors, NodeColorType };

package/dist/graph/index.js

@@ -0,0 +1 @@
+export { BaseEdge, BaseNode, GRAPH_CONSTANTS, GlowingHandle, GraphBackground, GraphContainer, GraphFitViewButton, GraphFitViewHandler, GraphLegend, calculateGraphHeight, getGraphBackgroundStyles, Graph_default as graphStyles, useConnectionHighlight, useDirectedChainHighlighting, useFitViewTrigger, useGraphBackgroundStyles, useGraphHighlighting, useGraphTheme, useNodeSelection } from '../chunk-HUWJXLLF.js';