bun add @duck_ui/embed @duckdb/duckdb-wasm

import { DuckUIProvider } from '@duck_ui/embed'

type DataInput =
  | Record<string, unknown>[]                              // Array of objects -> table
  | { url: string; format?: 'csv' | 'json' | 'parquet' }  // Remote file
  | { fetch: () => Promise<Record<string, unknown>[]> }    // Async callback
  | File                                                    // Browser File object

<DuckUIProvider
  data={{
    orders: [
      { id: 1, product: 'Widget', total: 99.50 },
      { id: 2, product: 'Gadget', total: 149.00 },
    ],
    sales: { url: '/data/sales.parquet', format: 'parquet' },
    users: { fetch: () => fetch('/api/users').then(r => r.json()) },
  }}
  theme={{ primaryColor: '#4f46e5' }}
  onReady={() => console.log('Ready')}
  onError={(err) => console.error(err)}
>
  {children}
</DuckUIProvider>

function useDuckUI(): { query: (sql: string) => Promise<QueryResult>; status: Status }

import { useDuckUI } from '@duck_ui/embed'

function MyComponent() {
  const { query, status } = useDuckUI()

  if (status !== 'ready') return <p>Loading...</p>

  const handleClick = async () => {
    const result = await query('SELECT count(*) as n FROM orders')
    console.log(result.rows) // [{ n: 42 }]
  }

  return <button onClick={handleClick}>Count orders</button>
}

function useTheme(): DuckTheme

import { useTheme } from '@duck_ui/embed'

const theme = useTheme()
// theme.primaryColor, theme.background, theme.palette, etc.

import { Chart } from '@duck_ui/embed'

<Chart
  sql="SELECT month, SUM(revenue) AS rev FROM sales GROUP BY 1 ORDER BY 1"
  type="bar"
  height={350}
  axes={{ y: { format: 'currency' } }}
/>

import { DataTable } from '@duck_ui/embed'

<DataTable sql="SELECT * FROM orders" pageSize={50} sortable />

import { KPICard } from '@duck_ui/embed'

<KPICard
  sql="SELECT SUM(total) AS value FROM orders"
  label="Total Revenue"
  format="currency"
  currency="USD"
  compareSql="SELECT SUM(total) AS value FROM orders WHERE year = 2024"
  compareLabel="vs 2024"
  sparklineSql="SELECT month, SUM(total) FROM orders GROUP BY 1 ORDER BY 1"
/>

import { ExportButton } from '@duck_ui/embed'

const { data } = useQuery('SELECT * FROM sales')
<ExportButton data={data} format="csv" fileName="sales-report" />

import { Dashboard } from '@duck_ui/embed'

<DuckUIProvider data={{ orders }}>
  <Dashboard columns={3} gap={16}>
    <Dashboard.Panel span={2}>
      <FilterBar auto="orders" />
    </Dashboard.Panel>
    <Dashboard.Panel>
      <KPICard sql="SELECT count(*) as value FROM orders" label="Orders" />
    </Dashboard.Panel>
    <Dashboard.Panel span={2}>
      <Chart sql="SELECT status, count(*) FROM orders GROUP BY 1" type="bar" />
    </Dashboard.Panel>
    <Dashboard.Panel>
      <Chart sql="SELECT date, sum(total) FROM orders GROUP BY 1" type="line" />
    </Dashboard.Panel>
    <Dashboard.Panel span={3}>
      <DataTable sql="SELECT * FROM orders" pageSize={20} sortable />
    </Dashboard.Panel>
  </Dashboard>
</DuckUIProvider>

import { FilterBar } from '@duck_ui/embed'

// Auto mode
<FilterBar auto="orders" />

// Manual mode
<FilterBar filters={[
  { column: 'status', type: 'select' },
  { column: 'total', type: 'range', min: 0, max: 1000 },
  { column: 'created_at', type: 'daterange' },
]} source="orders" />

interface FilterConfig {
  column: string
  type: 'select' | 'multiselect' | 'range' | 'daterange'
  label?: string
  min?: number        // For range
  max?: number        // For range
  step?: number       // For range
  options?: string[]  // For select (explicit options)
}

interface QueryResult {
  rows: Record<string, unknown>[]
  columns: ColumnInfo[]
  rowCount: number
  executionTime: number  // milliseconds
}

interface ColumnInfo {
  name: string
  type: string
  nullable: boolean
}

type FilterValue =
  | string
  | number
  | boolean
  | string[]
  | number[]
  | { min: number; max: number }
  | { start: string; end: string }
  | null

interface ChartTheme {
  background: string
  textColor: string
  gridColor: string
  axisColor: string
  palette: string[]
  fontFamily: string
  fontSize: number
}

interface DuckTheme extends ChartTheme {
  surfaceColor: string
  borderColor: string
  hoverColor: string
  primaryColor: string
  errorColor: string
  errorBgColor: string
  mutedTextColor: string
  stripeColor: string
  successColor: string
  successBgColor: string
  dangerColor: string
  dangerBgColor: string
}

interface AxisOptions {
  label?: string
  format?: 'number' | 'currency' | 'percent' | 'date' | ((value: number) => string)
}

import { lightTheme, darkTheme } from '@duck_ui/embed'