@flowtile/react

React components and hooks for FlowTile ticket workflow system.

Installation

npm install @flowtile/react @flowtile/core react react-dom

Quick Start

import { FlowTileProvider, useTickets, useTicketActions } from '@flowtile/react';
import { TicketEngine, MemoryAdapter, presets } from '@flowtile/core';
import '@flowtile/react/styles.css';

// Create engine
const engine = new TicketEngine({
  workflow: presets.kanban(),
  storage: new MemoryAdapter(),
});

// Wrap your app
function App() {
  return (
    <FlowTileProvider
      engine={engine}
      user={{ id: '1', name: 'John Doe', email: '[email protected]' }}
    >
      <TicketList />
    </FlowTileProvider>
  );
}

// Use hooks in components
function TicketList() {
  const { tickets, loading } = useTickets();
  const { createTicket, advanceStage } = useTicketActions();

  if (loading) return <div>Loading...</div>;

  return (
    <div>
      {tickets.map((ticket) => (
        <div key={ticket.id}>
          <h3>{ticket.title}</h3>
          <p>Stage: {ticket.currentStage}</p>
          <button onClick={() => advanceStage(ticket.id)}>
            Advance
          </button>
        </div>
      ))}
      <button
        onClick={() =>
          createTicket({
            title: 'New ticket',
            currentStage: 'todo',
          })
        }
      >
        Create Ticket
      </button>
    </div>
  );
}

Context & Provider

FlowTileProvider

Wraps your application to provide FlowTile context to all components.

<FlowTileProvider
  engine={engine}
  user={{ id: '1', name: 'John Doe' }}
  theme={{ borderRadius: 'lg' }}
  locale="en-US"
>
  <YourApp />
</FlowTileProvider>

Props:

• engine (required): TicketEngine instance from @flowtile/core
• user (optional): Current user information
• theme (optional): Theme customization
• locale (optional): Locale for date formatting (default: 'en-US')
• labels (optional): Custom labels/translations

Hooks

useFlowTile()

Access the FlowTile context.

const { engine, user, workflow, theme } = useFlowTile();

useTickets()

Get all tickets with real-time updates.

const { tickets, loading, error, refresh } = useTickets();

useTicket(ticketId)

Get a single ticket with real-time updates.

const { ticket, loading, error, refresh } = useTicket(ticketId);

useTicketActions()

Get functions to perform ticket actions.

const {
  createTicket,
  updateTicket,
  deleteTicket,
  advanceStage,
  sendBack,
  addEntry,
  createBundle,
  toggleBundlePin,
  createWorkOrder,
} = useTicketActions();

Examples:

// Create ticket
await createTicket({
  title: 'Fix login bug',
  currentStage: 'todo',
});

// Advance stage
await advanceStage(ticketId, {
  confidence: 'high',
  statement: 'Work completed',
});

// Send back
await sendBack(ticketId, 'Not ready yet', {
  targetStage: 'todo',
});

// Add note
await addEntry(ticketId, {
  stageKey: 'todo',
  kind: 'note',
  body: 'This is a note',
});

// Add photo
await addEntry(ticketId, {
  stageKey: 'verify',
  kind: 'photo',
  body: 'Completion photo',
  photoUrl: 'https://example.com/photo.jpg',
});

Helper Hooks

const user = useFlowTileUser();
const workflow = useFlowTileWorkflow();
const theme = useFlowTileTheme();
const label = useFlowTileLabel('submit', 'Submit');

Theme Customization

<FlowTileProvider
  engine={engine}
  theme={{
    stageColors: {
      todo: {
        main: '#6b7280',
        background: '#f3f4f6',
      },
      done: {
        main: '#10b981',
        background: '#d1fae5',
      },
    },
    borderRadius: 'lg',
    animationSpeed: 'fast',
  }}
>
  {/* ... */}
</FlowTileProvider>

Custom Labels

Provide custom labels for internationalization:

<FlowTileProvider
  engine={engine}
  labels={{
    'ticket.create': 'Create New Ticket',
    'ticket.advance': 'Move Forward',
    'ticket.sendback': 'Send Back',
    'note.add': 'Add Note',
  }}
>
  {/* ... */}
</FlowTileProvider>

function MyComponent() {
  const createLabel = useFlowTileLabel('ticket.create', 'Create Ticket');
  return <button>{createLabel}</button>;
}

TypeScript

Full TypeScript support with generics for custom stage keys:

type MyStages = 'draft' | 'review' | 'approved';

const { tickets } = useTickets<MyStages>();
// tickets are typed as Ticket<MyStages>[]

License

MIT