@geenius/ai-workflow 0.1.0 → 0.5.0

package/packages/react/dist/index.d.ts

@@ -0,0 +1,514 @@
+import { WorkflowEngineOptions, WorkflowDefinition, WorkflowRun, WorkflowError, StepResult, WorkflowStepDef, StepConnection, RunStatus, StepStatus, WorkflowTemplate, StepType } from '@geenius/ai-workflow-shared';
+export { RunStatus, StepConfig, StepResult, StepStatus, StepType, WORKFLOW_TEMPLATES, WorkflowBuilderState, WorkflowDefinition, WorkflowEngine, WorkflowRun, WorkflowStatus, WorkflowStepDef, getTemplate, getTemplatesByCategory, validateRun, validateWorkflow } from '@geenius/ai-workflow-shared';
+import { ReactElement } from 'react';
+
+/**
+ * @module UseWorkflow
+ * @package @geenius/ai-workflow-react
+ * @description React hook for executing workflow definitions with the shared
+ * workflow engine. This file bridges engine lifecycle, run state, and typed
+ * error propagation into a stable React-friendly API.
+ */
+
+/**
+ * Runtime integrations accepted by the React workflow hook.
+ *
+ * @property callLLM Optional LLM execution callback inherited from `WorkflowEngineOptions`.
+ * @property callWebhook Optional webhook execution callback inherited from `WorkflowEngineOptions`.
+ * @property onApprovalRequired Optional approval callback inherited from `WorkflowEngineOptions`.
+ * @property onStepComplete Optional per-step completion callback inherited from `WorkflowEngineOptions`.
+ * @property customHandlers Optional custom step-handler registry inherited from `WorkflowEngineOptions`.
+ */
+interface UseWorkflowOptions extends WorkflowEngineOptions {
+}
+/**
+ * Result returned by `useWorkflow`.
+ *
+ * @property execute Execute a workflow definition against optional input data.
+ * @property cancel Cancel the current in-flight workflow run.
+ * @property run Latest workflow run snapshot.
+ * @property isRunning Whether a workflow run is currently in progress.
+ * @property error Latest typed workflow error.
+ * @property stepResults Step results emitted during the active run.
+ * @property reset Clear local run, error, and step-result state.
+ */
+interface UseWorkflowResult {
+    execute: (definition: WorkflowDefinition, input?: Record<string, unknown>) => Promise<WorkflowRun>;
+    cancel: () => void;
+    run: WorkflowRun | null;
+    isRunning: boolean;
+    error: WorkflowError | null;
+    stepResults: StepResult[];
+    reset: () => void;
+}
+/**
+ * Execute shared workflow definitions from React stateful components.
+ *
+ * @param options Runtime integrations and callbacks for the shared workflow engine.
+ * @returns Run state, execution methods, and cancellation controls.
+ */
+declare function useWorkflow(options: UseWorkflowOptions): UseWorkflowResult;
+
+/**
+ * @module UseWorkflowBuilder
+ * @package @geenius/ai-workflow-react
+ * @description React hook for building and editing workflow definitions in the
+ * Tailwind workflow surface, including selection and undo/redo history.
+ */
+
+/**
+ * Create workflow-builder state and mutations for the React builder UI.
+ *
+ * @param initial Optional partial workflow definition used to seed the builder.
+ * @returns Builder state, undo/redo status, and workflow mutation callbacks.
+ */
+declare function useWorkflowBuilder(initial?: Partial<WorkflowDefinition>): {
+    definition: WorkflowDefinition;
+    selectedStepId: string | null;
+    isDirty: boolean;
+    canUndo: boolean;
+    canRedo: boolean;
+    addStep: (step: WorkflowStepDef) => void;
+    removeStep: (stepId: string) => void;
+    updateStep: (stepId: string, updates: Partial<WorkflowStepDef>) => void;
+    addConnection: (conn: StepConnection) => void;
+    removeConnection: (fromStepId: string, toStepId: string) => void;
+    selectStep: (stepId: string | null) => void;
+    undo: () => void;
+    redo: () => void;
+    setDefinition: (def: WorkflowDefinition) => void;
+};
+
+/**
+ * @module UseWorkflowRun
+ * @package @geenius/ai-workflow-react
+ * @description React hook for tracking workflow execution progress, per-step
+ * results, and completion callbacks in the Tailwind workflow surface.
+ */
+
+/**
+ * Runtime options for workflow run tracking.
+ *
+ * @property pollIntervalMs Reserved polling interval for future remote sync.
+ * @property onStepComplete Optional callback fired whenever a step result changes.
+ * @property onRunComplete Optional callback fired when the run reaches a terminal state.
+ */
+interface UseWorkflowRunOptions {
+    /** Poll interval for checking run status (ms) */
+    pollIntervalMs?: number;
+    /** Callback when a step completes */
+    onStepComplete?: (result: StepResult) => void;
+    /** Callback when the run finishes */
+    onRunComplete?: (run: WorkflowRun) => void;
+}
+/**
+ * Track workflow execution state and emit lifecycle callbacks.
+ *
+ * @param options Optional polling and lifecycle callbacks for run updates.
+ * @returns Run state, derived flags, and update/reset helpers.
+ */
+declare function useWorkflowRun(options?: UseWorkflowRunOptions): {
+    run: WorkflowRun | null;
+    status: RunStatus;
+    currentStepIndex: number;
+    completedSteps: StepResult[];
+    progress: number;
+    error: string | null;
+    trackRun: (workflowRun: WorkflowRun) => void;
+    updateStep: (result: StepResult) => void;
+    reset: () => void;
+    isRunning: boolean;
+    isComplete: boolean;
+    isFailed: boolean;
+};
+
+/**
+ * @module UseWorkflowStep
+ * @package @geenius/ai-workflow-react
+ * @description React hook for tracking a single workflow step within the
+ * Tailwind workflow surface.
+ */
+
+interface UseWorkflowStepResult {
+    stepDef: WorkflowStepDef;
+    status: StepStatus;
+    output: unknown;
+    error: string | null;
+    durationMs: number;
+    icon: string;
+    statusColor: string;
+    updateFromResult: (result: StepResult) => void;
+    reset: () => void;
+    isComplete: boolean;
+    isRunning: boolean;
+    isFailed: boolean;
+    isWaiting: boolean;
+    config: WorkflowStepDef["config"];
+}
+/**
+ * Track the transient execution state for a single workflow step.
+ *
+ * @param stepDef Shared workflow step definition to project into UI state.
+ * @returns Step execution metadata, derived badges, and reset/update actions.
+ */
+declare function useWorkflowStep(stepDef: WorkflowStepDef): UseWorkflowStepResult;
+
+/**
+ * @module UseApprovalGate
+ * @package @geenius/ai-workflow-react
+ * @description React hook for managing human approval requests in the Tailwind
+ * workflow variant.
+ */
+/**
+ * Pending approval request exposed to the UI layer.
+ *
+ * @property id Stable approval-request identifier.
+ * @property stepId Workflow step awaiting the operator decision.
+ * @property message Approval prompt shown to the operator.
+ * @property requestedAt Unix timestamp for when the approval was created.
+ * @property approvers Optional list of users or roles allowed to approve.
+ */
+interface ApprovalRequest {
+    id: string;
+    stepId: string;
+    message: string;
+    requestedAt: number;
+    approvers?: string[];
+}
+/**
+ * Manage pending approval requests and completed approval history.
+ *
+ * @returns Approval state plus request, approve, reject, and reset helpers.
+ */
+declare function useApprovalGate(): {
+    pendingApprovals: ApprovalRequest[];
+    history: Array<ApprovalRequest & {
+        decision: 'approved' | 'rejected';
+        decidedAt: number;
+    }>;
+    hasPending: boolean;
+    requestApproval: (stepId: string, message: string, approvers?: string[]) => string;
+    approve: (approvalId: string) => void;
+    reject: (approvalId: string) => void;
+    clearHistory: () => void;
+};
+
+/**
+ * @module UseWorkflowTemplates
+ * @package @geenius/ai-workflow-react
+ * @description React hook for filtering and instantiating shared workflow
+ * templates in the Tailwind workflow surface.
+ */
+
+/**
+ * Manage template filtering, selection, and instantiation for the builder UI.
+ *
+ * @param userId User identifier injected into cloned workflow templates.
+ * @returns Template lists, selected state, and creation helpers.
+ */
+declare function useWorkflowTemplates(userId: string): {
+    templates: WorkflowTemplate[];
+    allTemplates: WorkflowTemplate[];
+    selectedTemplate: WorkflowTemplate | null;
+    selectedTemplateId: string | null;
+    categories: WorkflowTemplate['category'][];
+    filterCategory: WorkflowTemplate['category'] | 'all';
+    searchQuery: string;
+    setSelectedTemplateId: (value: string | null) => void;
+    setFilterCategory: (value: WorkflowTemplate['category'] | 'all') => void;
+    setSearchQuery: (value: string) => void;
+    createFromTemplate: (templateId: string) => WorkflowDefinition | null;
+};
+
+/**
+ * Props for the workflow builder canvas.
+ *
+ * @property definition Shared workflow definition to render.
+ * @property selectedStepId Currently selected step identifier.
+ * @property onSelectStep Callback used to change the selected step.
+ * @property onMoveStep Reserved callback for future drag interactions.
+ */
+interface WorkflowCanvasProps {
+    definition: WorkflowDefinition;
+    selectedStepId: string | null;
+    onSelectStep: (id: string | null) => void;
+    onMoveStep?: (stepId: string, pos: {
+        x: number;
+        y: number;
+    }) => void;
+}
+/**
+ * Render a workflow canvas with connectors, nodes, and an empty state.
+ *
+ * @param props Canvas state and interaction callbacks.
+ * @returns The workflow canvas for the current definition.
+ */
+declare function WorkflowCanvas({ definition, selectedStepId, onSelectStep, onMoveStep, }: WorkflowCanvasProps): ReactElement;
+
+/**
+ * Props for rendering one workflow step node.
+ *
+ * @property step Shared workflow step definition to render.
+ * @property isSelected Whether the step is currently selected in the builder.
+ * @property status Visual execution status displayed on the node.
+ * @property onClick Optional selection callback invoked from mouse or keyboard.
+ * @property className Optional class name override for outer layout composition.
+ */
+interface StepNodeProps {
+    step: WorkflowStepDef;
+    isSelected?: boolean;
+    status?: "pending" | "running" | "success" | "error" | "skipped" | "default";
+    onClick?: () => void;
+    className?: string;
+}
+/**
+ * Render one selectable workflow step node inside the builder canvas.
+ *
+ * @param props Step node rendering props.
+ * @returns A keyboard-accessible workflow step node.
+ */
+declare function StepNode({ step, isSelected, status, onClick, className, }: StepNodeProps): ReactElement;
+
+/**
+ * @module WorkflowStepConnector
+ * @package @geenius/ai-workflow-react
+ * @description SVG connector primitive for drawing directed edges between
+ * positioned workflow steps in the React builder canvas.
+ */
+
+/**
+ * Props for a workflow step connector path.
+ *
+ * @property from Starting node position for the connector.
+ * @property to Ending node position for the connector.
+ * @property label Optional inline label rendered above the curve.
+ * @property isActive Whether the connector should use the emphasized active style.
+ */
+interface StepConnectorProps {
+    from: {
+        x: number;
+        y: number;
+    };
+    to: {
+        x: number;
+        y: number;
+    };
+    label?: string;
+    isActive?: boolean;
+}
+/**
+ * Render a curved connector between two step positions.
+ *
+ * @param props Connector endpoints and optional label/state metadata.
+ * @returns The SVG group that draws the workflow edge.
+ */
+declare function StepConnector({ from, to, label, isActive }: StepConnectorProps): ReactElement;
+
+/**
+ * @module WorkflowStepConfigPanel
+ * @package @geenius/ai-workflow-react
+ * @description React side panel for inspecting and editing the currently
+ * selected workflow step. This component exposes step metadata, optional flags,
+ * and the raw configuration payload used by the builder surface.
+ */
+
+/**
+ * Props for the workflow step configuration panel.
+ *
+ * @property step Shared workflow step being edited in the panel.
+ * @property onUpdate Callback that persists partial step updates.
+ * @property onDelete Callback that removes the selected step.
+ * @property onClose Callback that closes the panel without mutating state.
+ */
+interface StepConfigPanelProps {
+    step: WorkflowStepDef;
+    onUpdate: (stepId: string, updates: Partial<WorkflowStepDef>) => void;
+    onDelete: (stepId: string) => void;
+    onClose: () => void;
+}
+/**
+ * Render the editable side panel for a selected workflow step.
+ *
+ * @param props Selected step data and mutation callbacks from the builder.
+ * @returns The workflow step configuration panel.
+ */
+declare function StepConfigPanel({ step, onUpdate, onDelete, onClose }: StepConfigPanelProps): ReactElement;
+
+/**
+ * Props for the workflow run panel.
+ *
+ * @property run Current workflow run snapshot or `null` when idle.
+ * @property isRunning Whether the run is still active.
+ * @property onCancel Optional callback that cancels the active run.
+ */
+interface WorkflowRunPanelProps {
+    run: WorkflowRun | null;
+    isRunning: boolean;
+    onCancel?: () => void;
+}
+/**
+ * Render execution progress and per-step status for a workflow run.
+ *
+ * @param props Run state and optional cancellation callback.
+ * @returns A run summary panel or idle placeholder.
+ */
+declare function WorkflowRunPanel({ run, isRunning, onCancel, }: WorkflowRunPanelProps): ReactElement;
+
+/**
+ * @module WorkflowApprovalModal
+ * @package @geenius/ai-workflow-react
+ * @description React approval dialog for human-gated workflow steps. This
+ * component traps keyboard focus, restores focus on close, and keeps the
+ * approval surface aligned with the CSS and SolidJS variants.
+ */
+
+/**
+ * Props for the workflow approval dialog.
+ *
+ * @property request Pending approval request to render, or `null` when idle.
+ * @property onApprove Callback that approves the active request by id.
+ * @property onReject Callback that rejects the active request by id.
+ * @property onDismiss Optional callback used for Escape-key and dismiss flows.
+ */
+interface ApprovalModalProps {
+    request: ApprovalRequest | null;
+    onApprove: (id: string) => void;
+    onReject: (id: string) => void;
+    onDismiss?: (id: string) => void;
+}
+/**
+ * Render the pending approval request as an accessible modal dialog.
+ *
+ * @param props Approval dialog callbacks and the current pending request.
+ * @returns The animated approval dialog, or `null` when no approval is pending.
+ */
+declare function ApprovalModal(props: ApprovalModalProps): ReactElement;
+
+/**
+ * @module WorkflowToolbar
+ * @package @geenius/ai-workflow-react
+ * @description React toolbar for workflow builder actions such as save, run,
+ * cancel, undo, redo, and export. This component owns the top-level command
+ * surface shared across the builder page.
+ */
+
+/**
+ * Props for the workflow toolbar action surface.
+ *
+ * @property workflowName Human-readable workflow name shown in the title slot.
+ * @property isDirty Whether unsaved edits are currently present.
+ * @property isRunning Whether a run is currently active.
+ * @property canUndo Whether the undo action should be enabled.
+ * @property canRedo Whether the redo action should be enabled.
+ * @property onSave Callback that persists the current workflow definition.
+ * @property onRun Callback that starts a workflow run.
+ * @property onCancel Optional callback that stops an in-flight run.
+ * @property onUndo Callback that restores the previous builder snapshot.
+ * @property onRedo Callback that reapplies the next builder snapshot.
+ * @property onExport Optional callback that exports the workflow definition.
+ * @property className Optional class-name override for the toolbar container.
+ */
+interface WorkflowToolbarProps {
+    workflowName: string;
+    isDirty: boolean;
+    isRunning: boolean;
+    canUndo: boolean;
+    canRedo: boolean;
+    onSave: () => void;
+    onRun: () => void;
+    onCancel?: () => void;
+    onUndo: () => void;
+    onRedo: () => void;
+    onExport?: () => void;
+    className?: string;
+}
+/**
+ * Render the builder command toolbar with run-state-aware actions.
+ *
+ * @param props Action callbacks and builder status flags for the toolbar.
+ * @returns The animated workflow toolbar.
+ */
+declare function WorkflowToolbar(props: WorkflowToolbarProps): ReactElement;
+
+/**
+ * Props for the workflow step palette component.
+ *
+ * @property onAddStep Callback invoked when a step type is selected.
+ */
+interface StepPaletteProps {
+    onAddStep: (type: StepType) => void;
+}
+/**
+ * Render the workflow step palette.
+ *
+ * @param props Palette interaction props.
+ * @returns A list of available workflow step types.
+ */
+declare function StepPalette({ onAddStep }: StepPaletteProps): ReactElement;
+
+/**
+ * @module WorkflowBuilderPage
+ * @package @geenius/ai-workflow-react
+ * @description React page for composing, editing, and running workflow
+ * definitions. This page coordinates the shared engine with the React builder
+ * hooks and component surface.
+ */
+
+/**
+ * Props for the React workflow builder page.
+ *
+ * @property engineOptions Shared workflow engine integrations used for execution.
+ * @property onSave Optional callback that persists the edited definition.
+ * @property className Optional class name override for outer layout composition.
+ * @property workflows Optional list of stored workflows shown in the summary strip.
+ * @property workflowRuns Optional list of stored workflow runs shown in the summary strip.
+ */
+interface WorkflowBuilderPageProps {
+    engineOptions: WorkflowEngineOptions;
+    onSave?: (definition: WorkflowDefinition) => void;
+    className?: string;
+    workflows?: Array<{
+        _id: string;
+        name: string;
+    }>;
+    workflowRuns?: Array<{
+        _id: string;
+        workflowId: string;
+    }>;
+}
+/**
+ * Render the full workflow builder page for React consumers.
+ *
+ * @param props Builder dependencies, persistence callbacks, and optional summaries.
+ * @returns The composed workflow builder page.
+ */
+declare function WorkflowBuilderPage({ engineOptions, onSave, className, workflows, workflowRuns, }: WorkflowBuilderPageProps): ReactElement;
+
+/**
+ * @module WorkflowRunsPage
+ * @package @geenius/ai-workflow-react
+ * @description React page component for browsing workflow execution history in
+ * the Tailwind workflow variant.
+ */
+
+/**
+ * Props for the workflow runs history page.
+ *
+ * @property runs Workflow run records rendered on the page.
+ * @property onSelectRun Optional callback fired when a run card is selected.
+ * @property className Optional class-name override for the page container.
+ */
+interface WorkflowRunsPageProps {
+    runs: WorkflowRun[];
+    onSelectRun?: (runId: string) => void;
+    className?: string;
+}
+/**
+ * Render the workflow run history page.
+ *
+ * @param props Workflow run records plus optional selection and layout hooks.
+ * @returns The workflow run history page.
+ */
+declare function WorkflowRunsPage({ runs, onSelectRun, className }: WorkflowRunsPageProps): ReactElement;
+
+export { ApprovalModal, type ApprovalModalProps, type ApprovalRequest, StepConfigPanel, type StepConfigPanelProps, StepConnector, type StepConnectorProps, StepNode, type StepNodeProps, StepPalette, type StepPaletteProps, type UseWorkflowOptions, type UseWorkflowRunOptions, WorkflowBuilderPage, type WorkflowBuilderPageProps, WorkflowCanvas, type WorkflowCanvasProps, WorkflowRunPanel, type WorkflowRunPanelProps, WorkflowRunsPage, type WorkflowRunsPageProps, WorkflowToolbar, type WorkflowToolbarProps, useApprovalGate, useWorkflow, useWorkflowBuilder, useWorkflowRun, useWorkflowStep, useWorkflowTemplates };