npm package: @flowtile/react
Description: React components for FlowTile ticket workflow system
Author: FlowTile Contributors
Latest version: 0.1.0

# @flowtile/react

React components and hooks for FlowTile ticket workflow system.

## Installation

```bash
npm install @flowtile/react @flowtile/core react react-dom
```

## Quick Start

```tsx
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: 'john@example.com' }}
    >
      <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.

```tsx
<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.

```tsx
const { engine, user, workflow, theme } = useFlowTile();
```

### useTickets()

Get all tickets with real-time updates.

```tsx
const { tickets, loading, error, refresh } = useTickets();
```

### useTicket(ticketId)

Get a single ticket with real-time updates.

```tsx
const { ticket, loading, error, refresh } = useTicket(ticketId);
```

### useTicketActions()

Get functions to perform ticket actions.

```tsx
const {
  createTicket,
  updateTicket,
  deleteTicket,
  advanceStage,
  sendBack,
  addEntry,
  createBundle,
  toggleBundlePin,
  createWorkOrder,
} = useTicketActions();
```

**Examples:**

```tsx
// 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

```tsx
const user = useFlowTileUser();
const workflow = useFlowTileWorkflow();
const theme = useFlowTileTheme();
const label = useFlowTileLabel('submit', 'Submit');
```

## Theme Customization

```tsx
<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:

```tsx
<FlowTileProvider
  engine={engine}
  labels={{
    'ticket.create': 'Create New Ticket',
    'ticket.advance': 'Move Forward',
    'ticket.sendback': 'Send Back',
    'note.add': 'Add Note',
  }}
>
  {/* ... */}
</FlowTileProvider>
```

```tsx
function MyComponent() {
  const createLabel = useFlowTileLabel('ticket.create', 'Create Ticket');
  return <button>{createLabel}</button>;
}
```

## TypeScript

Full TypeScript support with generics for custom stage keys:

```tsx
type MyStages = 'draft' | 'review' | 'approved';

const { tickets } = useTickets<MyStages>();
// tickets are typed as Ticket<MyStages>[]
```

## License

MIT