@geenius/ai-workflow 0.1.0 → 0.4.0

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

@@ -0,0 +1,466 @@
+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, 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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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 };