@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

npm install @liqueur/react @liqueur/protocol

Peer Dependencies

npm install react react-dom

Usage

Basic Example

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

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

Components

LiquidRenderer

Main component for rendering complete schemas.

<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).

<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.

<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.

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

StackLayout

Vertical stacking layout.

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

Hooks

useLiquidView

Fetches data for a Liquid schema.

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.

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

useDashboardMutations

CRUD operations for dashboards.

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

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

useFavorites

Manages favorite dashboards (localStorage).

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

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

Dashboard Manager Components

Pre-built components for dashboard management UI:

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

# Build
npm run build

# Test
npm test

# Test with coverage
npm run test:coverage

# Type check
npm run typecheck

License

MIT