@brethex/flow

A comprehensive React component library for building workflow and approval-based user interfaces with TypeScript, Vite, and shadcn/ui.

Table of Contents

• Features
• Installation
• Quick Start
• Core Components
• API Client
• Hooks
• Usage Guide
• Development
• Contributing
• License

Features

• 🎯 Complete Workflow Management - Full-featured workflow component with draft editing, reviewer assignment, and approval workflows
• 🎨 Beautiful UI - Styled with Tailwind CSS and shadcn/ui for a modern, accessible interface
• 📱 Fully Responsive - Works seamlessly across desktop, tablet, and mobile devices
• 🔧 TypeScript First - Complete type safety with comprehensive TypeScript definitions
• ⚡ Performance Optimized - Built with Vite for lightning-fast development and production builds
• 🔄 Real-time Updates - Optimistic UI updates with proper error handling
• 🎪 Highly Customizable - Easy to extend with custom handlers, clients, and styling
• 🏗️ Modular Architecture - Well-structured hooks and components for maximum flexibility

Installation

Install the package using your preferred package manager:

# npm
npm install @brethex/flow

# pnpm
pnpm add @brethex/flow

# yarn
yarn add @brethex/flow

Quick Start

Basic Setup

Initialize the workflow client and use the main component:

import { WorkflowComponent, initWorkflowClient } from "@brethex/flow";
import "@brethex/flow/styles";

// Initialize once at app startup
initWorkflowClient({
  baseUrl: "https://your-api.com/api",
});

function App() {
  return (
    <div className="container mx-auto p-4">
      <WorkflowComponent workflowId="workflow-123" />
    </div>
  );
}

That's it! The WorkflowComponent handles everything automatically - data fetching, UI rendering, and all user interactions.

Creating Workflows

import {
  useWorkflowMutationsWithClient,
  getWorkflowClient,
} from "@brethex/flow";

function CreateWorkflowButton() {
  const { createWorkflow, isLoading } = useWorkflowMutationsWithClient(
    getWorkflowClient()
  );

  const handleCreate = async () => {
    try {
      const workflow = await createWorkflow(
        "New Project Approval",
        "Approval workflow for Q1 marketing campaign",
        "template-uuid-123"
      );
      console.log("Created workflow:", workflow.id);
    } catch (error) {
      console.error("Failed to create workflow:", error);
    }
  };

  return (
    <button onClick={handleCreate} disabled={isLoading}>
      {isLoading ? "Creating..." : "Create Workflow"}
    </button>
  );
}

Direct API Usage

For simple use cases, you can import and use createWorkflow directly without hooks:

import { createWorkflow } from "@brethex/flow";

async function createNewWorkflow() {
  try {
    const workflow = await createWorkflow(
      "New Project Approval",
      "Approval workflow for Q1 marketing campaign",
      "template-uuid-123"
    );
    console.log("Created workflow:", workflow.id);
  } catch (error) {
    console.error("Failed to create workflow:", error);
  }
}

Core Components

WorkflowComponent

The main component that provides a complete workflow management interface. It includes:

• Workflow Display - Shows workflow details, status, and current step
• Step Cards - Individual cards for each workflow step with reviewer management
• Draft Editing - Add/remove reviewers when workflow is in draft status
• Action Handling - Approve/reject actions with optional remarks
• Confirmation Dialogs - Prevents accidental operations
• Loading States - Proper loading indicators and error handling

Props

interface WorkflowComponentProps {
  workflowId: string; // Required: The workflow ID to load
  client?: WorkflowApiClient; // Optional: Custom API client
  onSaveDraft?: (reviewers: Record<number, string[]>) => Promise<void>;
  onSaveWorkflow?: (reviewers: Record<number, string[]>) => Promise<void>;
  onPerformAction?: (
    workflowId: string,
    actionId: string,
    action: WorkflowActionType,
    remarks?: string
  ) => Promise<void>;
  onDeleteReviewer?: (actionId: string) => Promise<void>;
}

Basic Usage

<WorkflowComponent workflowId="workflow-123" />

With Custom Handlers

<WorkflowComponent
  workflowId="workflow-123"
  onSaveDraft={async (reviewers) => {
    console.log("Saving draft with reviewers:", reviewers);
    // Custom logic here
  }}
  onPerformAction={async (workflowId, actionId, action, remarks) => {
    console.log(`Performing ${action} on action ${actionId}`);
    // Custom logic here
  }}
/>

API Client

WorkflowApiClient

A complete HTTP client for workflow operations:

import { WorkflowApiClient } from "@brethex/flow";

const client = new WorkflowApiClient({
  baseUrl: "https://api.example.com/api",
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

// Available methods
await client.getWorkflow(workflowId);
await client.getSteps(templateId);
await client.getWorkflowActions(workflowId);
await client.getPersonnelOptions();
await client.createWorkflow(title, description, templateId);
await client.saveDraft(workflowId, reviewers);
await client.saveWorkflow(workflowId, reviewers);
await client.performAction(workflowId, actionId, action, remarks);
await client.deleteReviewer(workflowId, actionId);

Global Client Setup

For apps that use a single API endpoint:

import { initWorkflowClient } from "@brethex/flow";

// Call once at app startup
initWorkflowClient({
  baseUrl: "https://api.example.com/api",
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

// Components will automatically use the global client
<WorkflowComponent workflowId="workflow-123" />;

Hooks

useWorkflowMutationsWithClient

Provides workflow mutation functions with loading states:

const {
  createWorkflow,
  saveDraft,
  saveWorkflow,
  performAction,
  deleteReviewer,
  isLoading,
  error,
} = useWorkflowMutationsWithClient(client);

useWorkflowDataWithClient

Fetches workflow data:

const { workflow, steps, actions, personnelOptions, isLoading, error } =
  useWorkflowDataWithClient(workflowId, client);

Usage Guide

For comprehensive documentation, see USAGE_GUIDE.md which includes:

• Complete API reference
• Component architecture deep dive
• Data flow explanations
• Custom handler patterns
• Error handling strategies
• Best practices

Type Definitions

The package exports comprehensive TypeScript types:

import type {
  Workflow,
  Step,
  WorkflowAction,
  PersonnelOption,
  ApiResponse,
  WorkflowApiClientConfig,
} from "@brethex/flow";

Styles

Import the default styles (includes Tailwind CSS utilities):

import "@brethex/flow/styles";

Development

Prerequisites

• Node.js 18+
• pnpm (recommended) or npm/yarn

Setup

# Install dependencies
pnpm install

# Start development server
pnpm dev

# Build library
pnpm build

# Run linter
pnpm lint

Project Structure

src/
├── api/           # API client and request handling
├── client/        # Global client initialization
├── components/    # React components
│   ├── ui/       # shadcn/ui components
│   └── workflow.tsx
├── context/       # React context providers
├── hooks/         # Custom React hooks
├── lib/           # Utility functions
├── types/         # TypeScript definitions
└── index.ts       # Main exports

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support, please open an issue on the GitHub repository.

Built with ❤️ using React, TypeScript, Vite, and shadcn/ui