npm package: @liqueur/react
Description: Liquid UI - React component library for rendering LiquidView schemas with dashboard management
Author: Project Liquid Contributors
Latest version: 0.1.0

# @liqueur/react

React components for rendering Liquid Protocol schemas

## Overview

`@liqueur/react` provides React components that render UI from Liquid Protocol schemas. This enables dynamic, data-driven dashboards generated by AI or defined programmatically.

## Features

- **LiquidRenderer** - Main component for rendering schemas
- **Chart components** - Bar, line, pie, area charts (Recharts)
- **Table components** - Interactive tables (@tanstack/react-table)
- **Layout system** - Grid and Stack layouts
- **Loading states** - Built-in loading indicators
- **Type-safe** - Full TypeScript support

## Installation

```bash
npm install @liqueur/react @liqueur/protocol
```

### Peer Dependencies

```bash
npm install react react-dom
```

## Usage

### Basic Example

```tsx
import { LiquidRenderer } from '@liqueur/react';
import type { LiquidViewSchema } from '@liqueur/protocol';

const schema: LiquidViewSchema = {
  version: '1.0',
  layout: { type: 'grid', columns: 2 },
  components: [
    {
      type: 'chart',
      chart_type: 'bar',
      title: 'Monthly Sales',
      data_source: 'sales'
    },
    {
      type: 'table',
      columns: ['month', 'amount'],
      title: 'Sales Data',
      data_source: 'sales'
    }
  ],
  data_sources: {
    sales: { resource: 'sales' }
  }
};

const data = {
  sales: [
    { month: 'Jan', amount: 1000 },
    { month: 'Feb', amount: 1500 },
    { month: 'Mar', amount: 1200 }
  ]
};

function Dashboard() {
  return <LiquidRenderer schema={schema} data={data} />;
}
```

### With Loading State

```tsx
function Dashboard({ schema, data, loading }) {
  return (
    <LiquidRenderer
      schema={schema}
      data={data}
      loading={loading}
    />
  );
}
```

## Components

### LiquidRenderer

Main component for rendering complete schemas.

```tsx
<LiquidRenderer
  schema={schema}           // LiquidViewSchema
  data={data}               // Record<string, unknown[]>
  loading={false}           // boolean
  className="my-dashboard"  // string
/>
```

**Props:**
| Prop | Type | Description |
|------|------|-------------|
| `schema` | `LiquidViewSchema` | The schema to render |
| `data` | `Record<string, unknown[]>` | Data by data_source name |
| `loading` | `boolean` | Show loading indicators |
| `className` | `string` | CSS class name |

### ChartComponent

Renders charts (bar, line, pie, area).

```tsx
<ChartComponent
  chart_type="bar"
  title="Monthly Sales"
  data={salesData}
  xKey="month"
  yKeys={['amount']}
  height={300}
/>
```

**Props:**
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `chart_type` | `'bar' \| 'line' \| 'pie' \| 'area'` | - | Chart type |
| `title` | `string` | - | Chart title |
| `data` | `unknown[]` | - | Chart data |
| `xKey` | `string` | First key | X-axis field |
| `yKeys` | `string[]` | Numeric keys | Y-axis fields |
| `width` | `number \| string` | `'100%'` | Chart width |
| `height` | `number` | `300` | Chart height |
| `loading` | `boolean` | `false` | Loading state |

### TableComponent

Renders interactive data tables.

```tsx
<TableComponent
  columns={['name', 'amount', 'date']}
  title="Transactions"
  data={transactions}
/>
```

**Props:**
| Prop | Type | Description |
|------|------|-------------|
| `columns` | `string[]` | Column names to display |
| `title` | `string` | Table title |
| `data` | `unknown[]` | Table data |
| `loading` | `boolean` | Loading state |

## Layouts

### GridLayout

CSS Grid-based responsive layout.

```tsx
<GridLayout columns={2} gap={16}>
  <ChartComponent {...} />
  <TableComponent {...} />
</GridLayout>
```

### StackLayout

Vertical stacking layout.

```tsx
<StackLayout gap={16}>
  <ChartComponent {...} />
  <TableComponent {...} />
</StackLayout>
```

## Hooks

### useLiquidView

Fetches data for a Liquid schema.

```typescript
import { useLiquidView } from '@liqueur/react';

function Dashboard({ schema }) {
  const { data, loading, error } = useLiquidView({ schema });

  if (error) return <div>Error: {error.message}</div>;

  return <LiquidRenderer schema={schema} data={data} loading={loading} />;
}
```

### useDashboards

Fetches and manages dashboard list.

```typescript
const { dashboards, isLoading, error, refresh } = useDashboards({
  search: 'expenses',
  sort: 'created',
  order: 'desc',
});
```

### useDashboardMutations

CRUD operations for dashboards.

```typescript
const { createDashboard, updateDashboard, deleteDashboard } =
  useDashboardMutations();

await createDashboard({ title: 'New Dashboard', schema });
await updateDashboard('id', { title: 'Updated' });
await deleteDashboard('id');
```

### useFavorites

Manages favorite dashboards (localStorage).

```typescript
const { favorites, toggleFavorite, isFavorite } = useFavorites();

toggleFavorite('dashboard-id');
if (isFavorite('dashboard-id')) {
  // ...
}
```

## Dashboard Manager Components

Pre-built components for dashboard management UI:

```tsx
import {
  DashboardList,
  DashboardSearch,
  DashboardCard,
  useDashboards,
  useFavorites,
} from '@liqueur/react';

function DashboardManager() {
  const [search, setSearch] = useState('');
  const { dashboards, isLoading } = useDashboards({ search });
  const { toggleFavorite } = useFavorites();

  return (
    <>
      <DashboardSearch onSearch={setSearch} />
      <DashboardList
        dashboards={dashboards}
        isLoading={isLoading}
        onFavoriteToggle={toggleFavorite}
      />
    </>
  );
}
```

## Development

```bash
# Build
npm run build

# Test
npm test

# Test with coverage
npm run test:coverage

# Type check
npm run typecheck
```

## License

MIT