hazo_dataviz 0.3.0

package/CHANGE_LOG.md

@@ -0,0 +1,54 @@
+# hazo_dataviz — Change Log
+
+## 0.3.0 — 2026-06-13 (unreleased)
+
+"Studio" visual restyle — a warm, editorial light theme applied to every shipped
+visualizer and to the test-app showroom.
+
+- **Shared chart theme** (`visualizers/chart_frame.tsx`): new `CHART_THEME` tokens
+  (warm ink/muted/hairline/surface), `axisProps` + `gridProps` (hairline horizontal
+  grid, no tick marks), `legendProps`, `CHART_MARGIN`, and a `makeTooltip(labelFmt,
+  valueFmt)` factory that renders a warm floating card with a colored swatch + tabular
+  value per series. SVG `font-family` is intentionally left unset so charts inherit the
+  host page font. `EmptyState` restyled with an icon + "No data to display".
+- **Palette**: `DEFAULT_PALETTE` replaced with the Studio ramp (coral, teal, marigold,
+  plum, ocean, olive, rose, amber-brown) — warm/cool alternation so adjacent series stay
+  distinguishable; coral + teal lead as the default complementary pair.
+- **Visualizers restyled** to consume the shared theme: `line` (2.5px monotone stroke,
+  hover active-dot, custom tooltip), `area` (per-series `<linearGradient>` fills),
+  `bar` (rounded `radius`, `maxBarSize`, category gap), `stacked_bar` (rounded top
+  segment), `single_stat` (uppercase label, coral accent bar, 52px tabular figure),
+  `table` (warm sticky header, hairline rows, right-aligned tabular measures).
+- **stacked_bar.accepts** relaxed: now scores `0.95` for any 2-dimension + ≥1-measure
+  query with ≥1 categorical dimension (either dim ordering), so the canonical
+  "measure by category over time" shape (temporal x, categorical series) is accepted.
+  Previously required `dimensions[0]` itself to be categorical. Jest + autotest aligned.
+- **Test-app "Studio" showroom**: `next/font` wiring (Bricolage Grotesque display +
+  Hanken Grotesk body), warm-canvas `globals.css` with CSS-var design tokens and a
+  layered radial-glow background, redesigned sidebar (gradient brand mark, active-state
+  highlight via `usePathname`), an editorial gallery (eyebrow + display headline,
+  per-chart icon cards with hover lift), and a real overview landing page.
+
+## 0.2.0 — 2026-06-13 (unreleased)
+
+Build 02: Bespoke chart components + recharts visualizers.
+
+- `LineChart` — bespoke single-series line chart (recharts) exported from `./client`; accepts `data: ChartDataSeries`, `dates: string[]`, `color`, optional `width`/`height`/`unit`/`showTooltip`/`className`; null values render as gaps (`connectNulls={false}`); responsive by default (130 px height), fixed-size when `width` is given; empty data renders a placeholder without throwing
+- `MultiLineChart` — bespoke multi-series line chart (recharts) exported from `./client`; accepts `series: MultiSeries[]` (each with `label`/`color`/`data`), `dates`; optional `width`/`height`/`showTooltip`/`showLegend`/`className`; same null-gap + responsive behaviour as `LineChart`; empty/all-null series render a placeholder without throwing
+- New types (`ChartDataPoint`, `ChartDataSeries`, `MultiSeries`) added to `src/types/index.ts` and exported from `./client`
+- `charts_smoke.test.tsx` added (describe.skip — same recharts dual-React ESM limitation as render_smoke.test.tsx; real coverage via test-app)
+
+## 0.1.0 — 2026-06-13 (unreleased)
+
+Build 01: Scaffold + Headless Data Foundation.
+
+- Package scaffold: ESM, `moduleResolution: node16`, jest (ESM), test-app (Next 16 stub)
+- `DatasetDescriptor` + `Query` Zod schemas with `parseDescriptor` / `parseQuery`; coded `HAZO_DATAVIZ_INVALID_*` errors via `hazo_core.fromZodValidation`
+- `derivePickerOptions(descriptor)` — pure function returning all valid measures/dims/aggs
+- `createInMemoryRunner(descriptor, rows)` — full filter→time-bucket→group→aggregate→sort→limit pipeline; SQL null semantics; ISO-8601 week bucketing; `last` agg
+- `formatValue` / `formatPercent` / `formatCompact` — delegate currency/number/date to `hazo_core`; `en-US` locale pinned for SSR safety
+- `useDataQuery(descriptor, query, runner)` — React hook; loading→success/error; cancel-on-unmount
+- `./testing` export — `prices`, `sector_breakdown`, `sparse`, `badDescriptorInput` fixtures + `createInMemoryRunner` re-export
+- 70 Jest tests, all green; `audit:structure` + `audit:versions` pass
+
+**Deferred to next session:** server-SQL runner (blocked: `hazo_connect` has no GROUP BY/aggregate support — candidate FR); Explorer UI / recharts; saved views / DDL.

package/README.md

@@ -0,0 +1,115 @@
+# hazo_dataviz
+
+Headless data-visualization primitives for hazo apps. A descriptor-driven data layer (schema, in-memory runner, React hook, formatters) plus a set of built-in recharts visualizers that auto-select the right chart for a given query shape — all styled with a warm, self-contained **"Studio"** theme out of the box.
+
+## Status
+
+**v0.3.0** — in development (not yet published to npm). Data layer + built-in visualizers + auto-selection complete. The server-SQL runner is deferred (blocked on `hazo_connect` GROUP BY support — see FR-003).
+
+## Install
+
+```bash
+npm install hazo_dataviz hazo_core
+```
+
+Peer deps: `hazo_core` (required); `hazo_connect` / `hazo_ui` / `hazo_api` (optional). The visualizers depend on `recharts` and `react` (recharts is a direct dep; react is a peer).
+
+## Quick start — data layer
+
+```ts
+import {
+  parseDescriptor,
+  createInMemoryRunner,
+  useDataQuery,
+} from 'hazo_dataviz';
+
+const descriptor = parseDescriptor({
+  name: 'sales',
+  version: '1',
+  grain: ['date', 'region'],
+  fields: {
+    date:    { role: 'dimension', type: 'time', timeGrains: ['month', 'year'] },
+    region:  { role: 'dimension', type: 'category' },
+    revenue: { role: 'measure', agg: 'sum', format: { kind: 'currency', ccy: 'USD' } },
+  },
+});
+
+const rows = [/* your data */];
+const runner = createInMemoryRunner(descriptor, rows);
+
+// In a React component:
+const { result, status, error } = useDataQuery(descriptor, {
+  measures: [{ field: 'revenue' }],
+  dimensions: ['date'],
+  timeGrain: 'month',
+}, runner);
+```
+
+## Quick start — auto-selected visualizer
+
+`<VisualizerView>` scores every built-in visualizer against the descriptor + query
+and renders the best fit (argmax). It is client-only — import from `hazo_dataviz/visualizers`.
+
+```tsx
+'use client';
+import { VisualizerView } from 'hazo_dataviz/visualizers';
+
+// `result` comes from a runner (e.g. createInMemoryRunner above)
+<VisualizerView descriptor={descriptor} query={query} result={result} opts={{ height: 300 }} />;
+```
+
+Need manual control instead of auto-selection?
+
+```tsx
+import { builtinVisualizers, selectVisualizer, deriveEncoding } from 'hazo_dataviz/visualizers';
+
+const { visualizer } = selectVisualizer(descriptor, query, result);
+const encoding = deriveEncoding(query, result);
+const el = visualizer.render(result, encoding, { height: 300, colors: ['#f5563d', '#14a098'] });
+```
+
+### Built-in visualizers & how they score
+
+`accepts(descriptor, query) → number` (0 = can't render, higher = better fit). The winner is the highest score:
+
+| id | When it fits | Score |
+|---|---|---|
+| `single_stat` | 0 dimensions + exactly 1 measure | 0.9 |
+| `line` | ≥1 temporal dimension + ≥1 measure | 0.9 |
+| `bar` | exactly 1 categorical dimension + ≥1 measure | 0.9 |
+| `stacked_bar` | 2 dimensions + ≥1 measure + ≥1 categorical dim | 0.95 (categorical x) / 0.6 (temporal x) |
+| `area` | ≥1 temporal dimension + ≥1 measure | 0.5 (never beats `line`) |
+| `table` | anything | 0.1 (universal fallback) |
+
+`stacked_bar` is graduated so a multi-series time series (temporal x) still defaults to `line` while a category-by-category split (categorical x) picks the stacked bar.
+
+### Styling (the "Studio" theme)
+
+Charts ship pre-styled — warm hairline grid, custom tooltip, rounded bars, gradient
+area fills, tabular figures — with no Tailwind or external CSS required (everything is
+inline SVG/JS so it renders correctly in any consumer). The series palette and theme
+tokens live in `visualizers/palette.ts` and `visualizers/chart_frame.tsx`; override
+colors per-render via `opts.colors`. SVG `font-family` is intentionally left unset so
+charts inherit your app's font.
+
+## Bespoke chart primitives
+
+For hand-built charts (not query-driven), `hazo_dataviz/client` exports lightweight
+recharts wrappers: `LineChart` (single series) and `MultiLineChart` (multi series),
+both with null-gap handling and responsive sizing.
+
+## Exports
+
+| Entry point | Exports |
+|---|---|
+| `hazo_dataviz` (server) / `hazo_dataviz/client` | `parseDescriptor`, `parseQuery`, `derivePickerOptions`, `createInMemoryRunner`, `useDataQuery`, `formatValue` / `formatPercent` / `formatCompact`, `LineChart`, `MultiLineChart`, `CONTRACT_VERSION`, + types |
+| `hazo_dataviz/visualizers` | `VisualizerView`, `builtinVisualizers`, `selectVisualizer`, `deriveEncoding`, `classifyShape`, + `Visualizer` / `VisualizerOpts` / `QueryShape` types |
+| `hazo_dataviz/testing` | Fixtures (`prices`, `sector_breakdown`, `sparse`) + `createInMemoryRunner` re-export |
+| `hazo_dataviz/api` | HTTP route handler factories (`hazo_api`-based) |
+
+`hazo_dataviz/visualizers` and `hazo_dataviz/client` are client-only (`'use client'`); the
+root `hazo_dataviz` import is server-safe and re-exports the client-safe data layer.
+
+## License
+
+MIT

package/SETUP_CHECKLIST.md

@@ -0,0 +1,54 @@
+# hazo_dataviz — Setup Checklist
+
+Follow these steps when adding hazo_dataviz to a consuming application.
+
+## 1. Install
+
+```bash
+npm install hazo_dataviz hazo_core recharts
+```
+
+- `hazo_core` is a required peer dependency.
+- `recharts` is required by the built-in visualizers and `./client` chart primitives.
+- `react` / `react-dom` are peer deps (^18 or ^19).
+- `hazo_connect` / `hazo_ui` / `hazo_api` are optional peers — only needed if you use
+  the (future) server-SQL runner or the `./api` route handlers.
+
+## 2. Configure
+
+Nothing to configure. hazo_dataviz is headless and stateless — there are **no env vars,
+no config files, and no database tables**. The in-memory runner operates on rows you
+pass in; the visualizers are pure given a `Result` + `Encoding`.
+
+## 3. Wire it up
+
+1. Build a `DatasetDescriptor` with `parseDescriptor()` (throws a coded `HazoError` on
+   invalid shape).
+2. Create a runner with `createInMemoryRunner(descriptor, rows)` and query it (or use the
+   `useDataQuery` React hook).
+3. Render results with `<VisualizerView descriptor query result />` (auto-selects the
+   chart) from `hazo_dataviz/visualizers`.
+
+> **Client boundary:** import visualizers from `hazo_dataviz/visualizers` (or chart
+> primitives from `hazo_dataviz/client`) inside a `'use client'` component. The root
+> `hazo_dataviz` import is server-safe and exposes only the client-safe data layer.
+
+## 4. Verify
+
+A quick smoke test using the bundled fixtures (no app data required):
+
+```tsx
+'use client';
+import { VisualizerView } from 'hazo_dataviz/visualizers';
+import { pricesDescriptor, pricesRows, createInMemoryRunner } from 'hazo_dataviz/testing';
+
+const runner = createInMemoryRunner(pricesDescriptor, pricesRows);
+const query = { measures: [{ field: 'close' }], dimensions: ['date', 'symbol'] };
+const result = await runner(query);
+
+// Renders a multi-series line chart (the auto-selected fit for a temporal query):
+<VisualizerView descriptor={pricesDescriptor} query={query} result={result} opts={{ height: 300 }} />;
+```
+
+If the chart renders with a warm hairline grid and a coral/teal series palette, the
+package is wired correctly.

package/dist/api/index.d.ts

@@ -0,0 +1,4 @@
+export declare function createExampleHandler(options: {
+    getHazoConnect: () => Promise<unknown> | unknown;
+}): () => Promise<Response>;
+//# sourceMappingURL=index.d.ts.map

package/dist/api/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAEA,wBAAgB,oBAAoB,CAAC,OAAO,EAAE;IAAE,cAAc,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAA;CAAE,2BAQjG"}

package/dist/api/index.js

@@ -0,0 +1,11 @@
+// hazo_dataviz/src/api/index.ts — HTTP route handler factories.
+// Inject hazo_connect; never import it at module top-level.
+export function createExampleHandler(options) {
+    // const adapter = await options.getHazoConnect();
+    void options;
+    return async function handler() {
+        return new Response(JSON.stringify({ ok: true }), {
+            headers: { 'content-type': 'application/json' },
+        });
+    };
+}

package/dist/charts/line_chart.d.ts

@@ -0,0 +1,14 @@
+import * as React from 'react';
+import type { ChartDataSeries } from '../types/index.js';
+export interface LineChartProps {
+    data: ChartDataSeries;
+    dates: string[];
+    color: string;
+    width?: number;
+    height?: number;
+    unit?: string;
+    showTooltip?: boolean;
+    className?: string;
+}
+export declare function LineChart({ data, dates, color, width, height, unit, showTooltip, className, }: LineChartProps): React.ReactElement;
+//# sourceMappingURL=line_chart.d.ts.map

package/dist/charts/line_chart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"line_chart.d.ts","sourceRoot":"","sources":["../../src/charts/line_chart.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAU/B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,eAAe,CAAC;IACtB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,SAAS,CAAC,EACxB,IAAI,EACJ,KAAK,EACL,KAAK,EACL,KAAK,EACL,MAAM,EACN,IAAS,EACT,WAAkB,EAClB,SAAS,GACV,EAAE,cAAc,GAAG,KAAK,CAAC,YAAY,CA2DrC"}

package/dist/charts/line_chart.js

@@ -0,0 +1,26 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { LineChart as RechartsLineChart, Line, XAxis, YAxis, CartesianGrid, Tooltip, ResponsiveContainer, } from 'recharts';
+export function LineChart({ data, dates, color, width, height, unit = '', showTooltip = true, className, }) {
+    // Empty data guard — render a placeholder, never throw
+    if (!data || data.length === 0) {
+        return (_jsx("div", { className: className, style: {
+                display: 'flex',
+                alignItems: 'center',
+                justifyContent: 'center',
+                height: height ?? 130,
+                color: '#9ca3af',
+                fontSize: 14,
+            }, children: "No data" }));
+    }
+    const chartData = dates.map((d, i) => ({ x: d, value: data[i] ?? null }));
+    const chartHeight = height ?? 130;
+    const tooltipFormatter = unit
+        ? (v) => [`${v}${unit}`, '']
+        : undefined;
+    const inner = (_jsxs(RechartsLineChart, { data: chartData, width: width !== undefined ? width : undefined, height: width !== undefined ? chartHeight : undefined, children: [_jsx(CartesianGrid, { strokeDasharray: "3 3" }), _jsx(XAxis, { dataKey: "x" }), _jsx(YAxis, { tickFormatter: (v) => unit ? `${v}${unit}` : String(v) }), showTooltip && _jsx(Tooltip, { formatter: tooltipFormatter }), _jsx(Line, { type: "monotone", dataKey: "value", stroke: color, dot: false, connectNulls: false, isAnimationActive: false })] }));
+    if (width !== undefined) {
+        return (_jsx("div", { style: { width, height: chartHeight, overflow: 'hidden' }, className: className, children: inner }));
+    }
+    return (_jsx("div", { className: className, children: _jsx(ResponsiveContainer, { width: "100%", height: chartHeight, children: inner }) }));
+}

package/dist/charts/multi_line_chart.d.ts

@@ -0,0 +1,13 @@
+import * as React from 'react';
+import type { MultiSeries } from '../types/index.js';
+export interface MultiLineChartProps {
+    series: MultiSeries[];
+    dates: string[];
+    width?: number;
+    height?: number;
+    showTooltip?: boolean;
+    showLegend?: boolean;
+    className?: string;
+}
+export declare function MultiLineChart({ series, dates, width, height, showTooltip, showLegend, className, }: MultiLineChartProps): React.ReactElement;
+//# sourceMappingURL=multi_line_chart.d.ts.map

package/dist/charts/multi_line_chart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi_line_chart.d.ts","sourceRoot":"","sources":["../../src/charts/multi_line_chart.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAW/B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,cAAc,CAAC,EAC7B,MAAM,EACN,KAAK,EACL,KAAK,EACL,MAAM,EACN,WAAkB,EAClB,UAAiB,EACjB,SAAS,GACV,EAAE,mBAAmB,GAAG,KAAK,CAAC,YAAY,CAuE1C"}

package/dist/charts/multi_line_chart.js

@@ -0,0 +1,32 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { LineChart as RechartsLineChart, Line, XAxis, YAxis, CartesianGrid, Tooltip, Legend, ResponsiveContainer, } from 'recharts';
+export function MultiLineChart({ series, dates, width, height, showTooltip = true, showLegend = true, className, }) {
+    const chartHeight = height ?? 130;
+    // Empty series or all-empty guard — render a placeholder, never throw
+    const hasData = series.length > 0 &&
+        series.some((s) => s.data.some((v) => v !== null));
+    if (!hasData) {
+        return (_jsx("div", { className: className, style: {
+                display: 'flex',
+                alignItems: 'center',
+                justifyContent: 'center',
+                height: chartHeight,
+                color: '#9ca3af',
+                fontSize: 14,
+            }, children: "No data" }));
+    }
+    // Build wide rows: { x: date, [seriesLabel]: value | null, ... }
+    const chartData = dates.map((d, i) => {
+        const row = { x: d };
+        for (const s of series) {
+            row[s.label] = s.data[i] ?? null;
+        }
+        return row;
+    });
+    const inner = (_jsxs(RechartsLineChart, { data: chartData, width: width !== undefined ? width : undefined, height: width !== undefined ? chartHeight : undefined, children: [_jsx(CartesianGrid, { strokeDasharray: "3 3" }), _jsx(XAxis, { dataKey: "x" }), _jsx(YAxis, {}), showTooltip && _jsx(Tooltip, {}), showLegend && _jsx(Legend, {}), series.map((s) => (_jsx(Line, { type: "monotone", dataKey: s.label, stroke: s.color, dot: false, connectNulls: false, isAnimationActive: false }, s.label)))] }));
+    if (width !== undefined) {
+        return (_jsx("div", { style: { width, height: chartHeight, overflow: 'hidden' }, className: className, children: inner }));
+    }
+    return (_jsx("div", { className: className, children: _jsx(ResponsiveContainer, { width: "100%", height: chartHeight, children: inner }) }));
+}

package/dist/hooks/use_data_query.d.ts

@@ -0,0 +1,11 @@
+import type { DatasetDescriptor } from '../schema/descriptor.js';
+import type { Query } from '../schema/query.js';
+import type { Result, QueryRunner } from '../types/index.js';
+export type QueryStatus = 'idle' | 'loading' | 'success' | 'error';
+export interface UseDataQueryResult {
+    result: Result | undefined;
+    status: QueryStatus;
+    error: unknown;
+}
+export declare function useDataQuery(descriptor: DatasetDescriptor, query: Query, runner: QueryRunner): UseDataQueryResult;
+//# sourceMappingURL=use_data_query.d.ts.map

package/dist/hooks/use_data_query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use_data_query.d.ts","sourceRoot":"","sources":["../../src/hooks/use_data_query.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAE7D,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAEnE,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,MAAM,EAAE,WAAW,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,wBAAgB,YAAY,CAC1B,UAAU,EAAE,iBAAiB,EAC7B,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,WAAW,GAClB,kBAAkB,CAqCpB"}

package/dist/hooks/use_data_query.js

@@ -0,0 +1,35 @@
+import { useState, useEffect, useRef } from 'react';
+export function useDataQuery(descriptor, query, runner) {
+    const [result, setResult] = useState(undefined);
+    const [status, setStatus] = useState('idle');
+    const [error, setError] = useState(undefined);
+    // Use a ref to track abort between renders
+    const cancelledRef = useRef(false);
+    // Serialize query + descriptor for dependency comparison
+    const queryKey = JSON.stringify(query);
+    const descriptorKey = descriptor.name + '@' + descriptor.version;
+    useEffect(() => {
+        cancelledRef.current = false;
+        setStatus('loading');
+        setResult(undefined);
+        setError(undefined);
+        runner(query)
+            .then((res) => {
+            if (cancelledRef.current)
+                return;
+            setResult(res);
+            setStatus('success');
+        })
+            .catch((err) => {
+            if (cancelledRef.current)
+                return;
+            setError(err);
+            setStatus('error');
+        });
+        return () => {
+            cancelledRef.current = true;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [queryKey, descriptorKey, runner]);
+    return { result, status, error };
+}

package/dist/index.client.d.ts

@@ -0,0 +1,17 @@
+export { CONTRACT_VERSION } from './lib/contract-version.js';
+export { parseDescriptor } from './schema/descriptor.js';
+export { parseQuery } from './schema/query.js';
+export { derivePickerOptions } from './lib/picker.js';
+export { createInMemoryRunner } from './lib/runners/in_memory.js';
+export { formatValue, formatPercent, formatCompact } from './lib/format.js';
+export { useDataQuery } from './hooks/use_data_query.js';
+export type { DatasetDescriptor, Field, Agg, TimeGrain, Format, JoinSpec, } from './schema/descriptor.js';
+export type { Query, MeasureRef, Filter, FilterOp, Sort } from './schema/query.js';
+export type { Result, Column, Encoding, QueryRunner, PickerOptions } from './types/index.js';
+export type { QueryStatus, UseDataQueryResult } from './hooks/use_data_query.js';
+export { LineChart } from './charts/line_chart.js';
+export { MultiLineChart } from './charts/multi_line_chart.js';
+export type { LineChartProps } from './charts/line_chart.js';
+export type { MultiLineChartProps } from './charts/multi_line_chart.js';
+export type { ChartDataPoint, ChartDataSeries, MultiSeries } from './types/index.js';
+//# sourceMappingURL=index.client.d.ts.map

package/dist/index.client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.client.d.ts","sourceRoot":"","sources":["../src/index.client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,YAAY,EACV,iBAAiB,EACjB,KAAK,EACL,GAAG,EACH,SAAS,EACT,MAAM,EACN,QAAQ,GACT,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AACnF,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAC7F,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAGjF,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,YAAY,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,YAAY,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACxE,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/index.client.js

@@ -0,0 +1,11 @@
+// Client-safe entry — no Node.js builtins.
+export { CONTRACT_VERSION } from './lib/contract-version.js';
+export { parseDescriptor } from './schema/descriptor.js';
+export { parseQuery } from './schema/query.js';
+export { derivePickerOptions } from './lib/picker.js';
+export { createInMemoryRunner } from './lib/runners/in_memory.js';
+export { formatValue, formatPercent, formatCompact } from './lib/format.js';
+export { useDataQuery } from './hooks/use_data_query.js';
+// Bespoke chart components (recharts-based)
+export { LineChart } from './charts/line_chart.js';
+export { MultiLineChart } from './charts/multi_line_chart.js';

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './index.client.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+// Server entry — re-exports client surface and will add server-only exports later.
+export * from './index.client.js';

package/dist/lib/auto_encode.d.ts

@@ -0,0 +1,24 @@
+import type { DatasetDescriptor } from '../schema/descriptor.js';
+import type { Query } from '../schema/query.js';
+import type { Result, Encoding, Visualizer } from '../types/index.js';
+/**
+ * Derives an Encoding from a query and result.
+ * - x = query.dimensions[0] (or '' if none)
+ * - series = query.dimensions[1] if present
+ * - y = measure column keys from result.columns where role==='measure' (preserve order)
+ *
+ * When result is undefined, derive from query alone.
+ */
+export declare function deriveEncoding(query: Query, result?: Result): Encoding;
+export interface SelectVisualizerResult {
+    visualizer: Visualizer;
+    encoding: Encoding;
+    candidates: Visualizer[];
+}
+/**
+ * Score every builtin visualizer and return the best match with encoding.
+ * candidates = those with score > 0 sorted descending (stable; on tie keep builtins order).
+ * visualizer = top candidate (guaranteed non-empty because table always scores 0.1).
+ */
+export declare function selectVisualizer(descriptor: DatasetDescriptor, query: Query, result?: Result): SelectVisualizerResult;
+//# sourceMappingURL=auto_encode.d.ts.map

package/dist/lib/auto_encode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto_encode.d.ts","sourceRoot":"","sources":["../../src/lib/auto_encode.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAGtE;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAYtE;AAED,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,UAAU,CAAC;IACvB,QAAQ,EAAE,QAAQ,CAAC;IACnB,UAAU,EAAE,UAAU,EAAE,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,iBAAiB,EAC7B,KAAK,EAAE,KAAK,EACZ,MAAM,CAAC,EAAE,MAAM,GACd,sBAAsB,CAuBxB"}

package/dist/lib/auto_encode.js

@@ -0,0 +1,46 @@
+import { builtinVisualizers } from '../visualizers/builtins.js';
+/**
+ * Derives an Encoding from a query and result.
+ * - x = query.dimensions[0] (or '' if none)
+ * - series = query.dimensions[1] if present
+ * - y = measure column keys from result.columns where role==='measure' (preserve order)
+ *
+ * When result is undefined, derive from query alone.
+ */
+export function deriveEncoding(query, result) {
+    const x = query.dimensions[0] ?? '';
+    const series = query.dimensions.length >= 2 ? query.dimensions[1] : undefined;
+    let y;
+    if (result) {
+        y = result.columns.filter((c) => c.role === 'measure').map((c) => c.key);
+    }
+    else {
+        y = query.measures.map((m) => m.field);
+    }
+    return { x, series, y };
+}
+/**
+ * Score every builtin visualizer and return the best match with encoding.
+ * candidates = those with score > 0 sorted descending (stable; on tie keep builtins order).
+ * visualizer = top candidate (guaranteed non-empty because table always scores 0.1).
+ */
+export function selectVisualizer(descriptor, query, result) {
+    const scored = builtinVisualizers.map((v, idx) => ({
+        visualizer: v,
+        score: v.accepts(descriptor, query, result),
+        idx,
+    }));
+    // Keep only those with score > 0
+    const positive = scored.filter((s) => s.score > 0);
+    // Stable sort descending by score (preserve original order on tie)
+    positive.sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        return a.idx - b.idx;
+    });
+    // Table always scores 0.1 so candidates is never empty
+    const candidates = positive.map((s) => s.visualizer);
+    const visualizer = candidates[0];
+    const encoding = deriveEncoding(query, result);
+    return { visualizer, encoding, candidates };
+}

package/dist/lib/contract-version.d.ts

@@ -0,0 +1,2 @@
+export declare const CONTRACT_VERSION: "0.1";
+//# sourceMappingURL=contract-version.d.ts.map

package/dist/lib/contract-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-version.d.ts","sourceRoot":"","sources":["../../src/lib/contract-version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,gBAAgB,EAAG,KAAc,CAAC"}

package/dist/lib/contract-version.js

@@ -0,0 +1 @@
+export const CONTRACT_VERSION = '0.1';

package/dist/lib/format.d.ts

@@ -0,0 +1,5 @@
+import type { Format } from '../schema/descriptor.js';
+export declare function formatValue(value: unknown, format: Format): string;
+export declare function formatPercent(value: number, decimals?: number): string;
+export declare function formatCompact(value: number): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/lib/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/lib/format.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAItD,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAclE;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,CAMjE;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKnD"}

package/dist/lib/format.js

@@ -0,0 +1,31 @@
+import { formatCurrency, formatNumber, format_date } from 'hazo_core';
+const LOCALE = 'en-US';
+export function formatValue(value, format) {
+    if (value === null || value === undefined)
+        return '';
+    switch (format.kind) {
+        case 'currency':
+            return formatCurrency(Number(value), format.ccy);
+        case 'number':
+            return formatNumber(Number(value), format.decimals);
+        case 'percent':
+            return formatPercent(Number(value));
+        case 'compact':
+            return formatCompact(Number(value));
+        case 'date':
+            return format_date(String(value), format.dateFormat ?? 'dmy');
+    }
+}
+export function formatPercent(value, decimals = 2) {
+    return new Intl.NumberFormat(LOCALE, {
+        style: 'percent',
+        minimumFractionDigits: decimals,
+        maximumFractionDigits: decimals,
+    }).format(value / 100);
+}
+export function formatCompact(value) {
+    return new Intl.NumberFormat(LOCALE, {
+        notation: 'compact',
+        maximumFractionDigits: 1,
+    }).format(value);
+}

package/dist/lib/index.d.ts

@@ -0,0 +1,3 @@
+export { CONTRACT_VERSION } from './contract-version.js';
+export { derivePickerOptions } from './picker.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC"}

package/dist/lib/index.js

@@ -0,0 +1,2 @@
+export { CONTRACT_VERSION } from './contract-version.js';
+export { derivePickerOptions } from './picker.js';

package/dist/lib/picker.d.ts

@@ -0,0 +1,4 @@
+import type { DatasetDescriptor } from '../schema/descriptor.js';
+import type { PickerOptions } from '../types/index.js';
+export declare function derivePickerOptions(descriptor: DatasetDescriptor): PickerOptions;
+//# sourceMappingURL=picker.d.ts.map

package/dist/lib/picker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"picker.d.ts","sourceRoot":"","sources":["../../src/lib/picker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAO,MAAM,yBAAyB,CAAC;AACtE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAIvD,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,iBAAiB,GAAG,aAAa,CAmBhF"}

package/dist/lib/picker.js

@@ -0,0 +1,20 @@
+const ALL_AGGS = ['sum', 'avg', 'min', 'max', 'last', 'count'];
+export function derivePickerOptions(descriptor) {
+    const measures = [];
+    const dimensions = [];
+    const filterableFields = [];
+    for (const [field, def] of Object.entries(descriptor.fields)) {
+        filterableFields.push(field);
+        if (def.role === 'measure') {
+            measures.push({ field, aggs: ALL_AGGS });
+        }
+        else {
+            dimensions.push({
+                field,
+                type: def.type,
+                timeGrains: def.timeGrains,
+            });
+        }
+    }
+    return { measures, dimensions, filterableFields };
+}

package/dist/lib/runners/in_memory.d.ts

@@ -0,0 +1,4 @@
+import type { DatasetDescriptor } from '../../schema/descriptor.js';
+import type { QueryRunner } from '../../types/index.js';
+export declare function createInMemoryRunner(descriptor: DatasetDescriptor, rows: Record<string, unknown>[]): QueryRunner;
+//# sourceMappingURL=in_memory.d.ts.map

package/dist/lib/runners/in_memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"in_memory.d.ts","sourceRoot":"","sources":["../../../src/lib/runners/in_memory.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAkB,MAAM,4BAA4B,CAAC;AAEpF,OAAO,KAAK,EAAkB,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAmGxE,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,iBAAiB,EAC7B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAC9B,WAAW,CAkMb"}