@zestl/zvolv-widgets 0.0.0-stage → 0.0.0

package/README.md

@@ -1,3 +1,782 @@
-# Temporary Holding Version
+# @zestl/zvolv-widgets
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React widgets for Zvolv dashboards. **The library owns the data. You (or Claude) own the UI.**
+
+The library handles Elasticsearch query generation, pivot `postOperations`,
+summary/series alignment, filter merging, date math, user-id → name resolution,
+and **viewer interactions**: search, column filters, sort and widget-level
+filters. This logic is ported from ZAI-Dashboard's production widgets. Every
+visual decision can be overridden.
+
+| The library owns — never reimplement | You own — design freely |
+| --- | --- |
+| Query generation, Elasticsearch calls | Layout, spacing, composition |
+| Pivot `postOperations`, summary/series alignment | Colour, type, density (design tokens) |
+| Filter merging, date math, user-id → labels | Chart marks, every template |
+| **Applying** search / column filters / sort / widget filters | The **controls** for search / filters / sort (render slots) |
+| Loading / empty / unconfigured / error detection | Every pixel |
+
+48 widget type strings render (plus 4 non-rendering filter/automation types). A real-data runtime is built in.
+
+> **For LLM agents:** read [SKILL.md](./SKILL.md) before writing code. It is the
+> short, rule-first contract. This README is the full reference.
+
+---
+
+## Contents
+
+1. [Quick start](#1-quick-start)
+2. [Props every widget accepts](#2-props-every-widget-accepts)
+3. [Search, column filters, sort and widget filters](#3-search-column-filters-sort-and-widget-filters)
+4. [Data sources](#4-data-sources--where-the-data-comes-from)
+5. [Controlling the UI](#5-controlling-the-ui)
+6. [Widget catalogue](#6-widget-catalogue)
+7. [Headless hooks](#7-headless-hooks)
+8. [Runtime: mock and real data](#8-runtime-mock-and-real-data)
+9. [Install, link, test](#9-install-link-test)
+10. [Rules and known limitations](#10-rules-and-known-limitations)
+11. [Forms](#11-forms)
+
+---
+
+## 1. Quick start
+
+```tsx
+import {
+  ZvolvProvider, ZvolvThemeProvider, createMockRuntime,
+  DashboardTableWidget, BarChartWidget,
+  formSource, field, groupBy, aggregate, pivot,
+} from "@zestl/zvolv-widgets";
+
+const region  = field("Region",  "DROP_DOWN");
+const revenue = field("Revenue", "INPUT_CURRENCY");
+const owner   = field("Owner",   "INPUT_TEXT");
+
+// Raw rows → table
+const tableSource = formSource(1042, [region, revenue, owner]);
+
+// Grouped + aggregated → chart
+const chartSource = formSource(1042, [region, revenue], {
+  pivot: pivot({ rows: [groupBy(region)], summary: [aggregate(revenue, "sum")] }),
+});
+
+export function Dashboard() {
+  return (
+    <ZvolvProvider runtime={createMockRuntime()}>   {/* swap for the real runtime, §8 */}
+      <ZvolvThemeProvider tokens={{ colors: { primary: "#0f766e" } }}>
+        <div style={{ display: "grid", gridTemplateColumns: "1fr 1fr", gap: 16, height: 420 }}>
+          <DashboardTableWidget
+            dataSource={tableSource}
+            configurations={{ title: "Deals", showSearchbar: true, showColumnFilter: true }}
+          />
+          <BarChartWidget
+            dataSource={chartSource}
+            configurations={{
+              title: "Revenue by region",
+              series: [{ name: "Revenue", valueField: "Revenue", argumentField: "Region" }],
+            }}
+            showWidgetFilter
+          />
+        </div>
+      </ZvolvThemeProvider>
+    </ZvolvProvider>
+  );
+}
+```
+
+That table has a search box, per-column filters and click-to-sort headers. The
+chart has a "Filter" control. Each one re-queries or re-filters the data, and
+nothing else needs wiring.
+
+---
+
+## 2. Props every widget accepts
+
+Every data widget (charts, KPI, tables, collections, temporal, display) takes
+the same props. `TabWidget`, `FormWidget`, `FilterPanelWidget` and
+`ZaiChatWidget` hold no data of their own, so they do not take them.
+
+### Data props
+
+| Prop | Type | Notes |
+| --- | --- | --- |
+| `dataSource` | `DataSourceDefinition` | **What** is queried. Build with `formSource()` / `taskSource()`. Pass server-stored ones through untouched. |
+| `configurations` | object \| JSON string | **How** it looks and which fields it plots. Strings are parsed for you. |
+| `dashFilters` | object | Dashboard filter state (host `{ filter, filter_cond, cdate, search }`). |
+| `cdateFilters` | array | Dashboard date-filter definitions. |
+| `localFilters` | object | Raw host-format widget filter (`{ filter, filter_cond }` from ZFilters). Merged per form with `dashFilters`. Prefer `widgetFilters`. |
+| `automationRows` / `automationLoading` | `any[]` / `boolean` | Rows from an automation binding. No query is issued. |
+| `rowLimit` | number | Max rows fetched. Default 1000. |
+| `dateGap` | `{ unit, start?, end? }` | Fill empty periods on a time axis. |
+| `widgetId`, `workflowTypeId` | | Legacy (non form-framework) sources only. |
+
+### Chrome props
+
+`title`, `description`, `emptyMessage`, `unconfiguredMessage`, `className`,
+`style`, and `render` (see §5). The same chrome keys also work inside
+`configurations`: `title`, `description`, `hideHeader`, `customMessage`,
+`bgColor`, `template`, `style`.
+
+### Interaction props
+
+These are covered in §3.
+
+| Prop | Type | Applies to |
+| --- | --- | --- |
+| `search` / `defaultSearch` / `onSearchChange` | `string` | all data widgets |
+| `widgetFilters` / `defaultWidgetFilters` / `onWidgetFiltersChange` | `WidgetFilter[]` | all data widgets |
+| `columnFilters` / `defaultColumnFilters` / `onColumnFiltersChange` | `Record<string, any[]>` | tables |
+| `sort` / `defaultSort` / `onSortChange` | `{ key, direction: "asc" \| "desc" } \| null` | tables |
+| `onInteractionsChange` | `(state) => void` | all: fires with the full state after any change |
+| `showSearch` | boolean | all. Default `config.showSearchbar` |
+| `showWidgetFilter` | boolean | all. Default `config.showWidgetFilter` |
+| `showColumnFilter` | boolean | tables. Default `config.showColumnFilter` |
+| `enableSort` | boolean | tables. Default `true` |
+| `searchPlaceholder` | string | all |
+| `searchDebounceMs` | number | all. Default 400, applies to server-side search only |
+| `renderSearch`, `renderWidgetFilter`, `renderToolbar` | slot | all |
+| `renderColumnFilter`, `renderSortIndicator` | slot | tables |
+
+---
+
+## 3. Search, column filters, sort and widget filters
+
+There are four kinds of viewer control:
+
+| Control | What it does | Where it shows |
+| --- | --- | --- |
+| **Search** | Free text across all columns | Widget header |
+| **Widget filter** | Field + operator + value conditions (AND-ed) | Widget header |
+| **Column filter** | Tick values in one column | Table header cell |
+| **Sort** | One column, asc/desc | Table header cell |
+
+### 3.1 Turn them on
+
+You can enable each control from config, from props, or by passing a slot.
+Any one of these is enough:
+
+```tsx
+// from config (this is how dashboards store it)
+configurations={{ showSearchbar: true, showColumnFilter: true, showWidgetFilter: true }}
+
+// from props
+<DashboardTableWidget showSearch showColumnFilter showWidgetFilter ... />
+
+// by supplying a slot — passing renderSearch turns search on
+<DashboardTableWidget renderSearch={(a) => <MySearch {...a} />} ... />
+```
+
+Sort is on by default for tables. Turn it off with `enableSort={false}` or
+`config.enableSort: false`. Active widget filters always show as removable
+chips, unless you pass `showWidgetFilter={false}`.
+
+### 3.2 Where each control is applied
+
+The library decides this for you. You never write query code.
+
+| Data source | Search / column filter / sort | Widget filters |
+| --- | --- | --- |
+| Form or task source, **no** `pivot.rows` | **Server**: sent through `generateQuery`, so it covers the full dataset | **Server** |
+| Form or task source **with** `pivot.rows` (grouped) | **Local**: applied to the loaded buckets | **Server** (before aggregation) |
+| Legacy widget-id source | Local | Local |
+| `automationRows` | Local | Local |
+| `ChildTableWidget` | Local | Server |
+
+Server-side details (these match ZAI-Dashboard's `DashboardTable`):
+- Search becomes an `_ALL` clause, or a `MULTIPLE` clause when the text is a full date (`05/01/2026` → `2026-01-05`). It is debounced 400 ms.
+- Column filters become `IN` clauses, or `EMPTY` when only blanks are ticked. If the runtime provides `formatHeaderFilters`, it is used instead, which adds the user-name → id and workflow-title → id mapping.
+- Sort becomes `generateQuery`'s `dashboardSort`. If `configuration.columns` is missing (`generateQuery` needs it), the library builds it from `dataSource.fields`.
+- Widget filters become field clauses. `DATE_IS` tokens become `BETWEEN` date ranges, and numeric fields get numeric operands.
+
+`data.meta.tableMode` and `data.meta.filterMode` tell you which mode applies.
+Every slot also receives `mode`.
+
+### 3.3 Controlled vs uncontrolled
+
+**Uncontrolled.** The widget owns the state. Seed it with `default*`:
+
+```tsx
+<DashboardTableWidget
+  dataSource={ds} configurations={cfg}
+  defaultSort={{ key: "Revenue", direction: "desc" }}
+  defaultWidgetFilters={[{ field: "Status", operator: "IN", value: ["Open"] }]}
+/>
+```
+
+**Controlled.** You own the state (for example, sync it to the URL). Pass the
+value **and** its `on*Change`:
+
+```tsx
+const [search, setSearch] = useState("");
+const [sort, setSort] = useState<SortState | null>(null);
+const [columnFilters, setColumnFilters] = useState<ColumnFilters>({});
+const [widgetFilters, setWidgetFilters] = useState<WidgetFilter[]>([]);
+
+<DashboardTableWidget
+  dataSource={ds} configurations={cfg} showSearch showColumnFilter
+  search={search} onSearchChange={setSearch}
+  sort={sort} onSortChange={setSort}
+  columnFilters={columnFilters} onColumnFiltersChange={setColumnFilters}
+  widgetFilters={widgetFilters} onWidgetFiltersChange={setWidgetFilters}
+/>
+```
+
+A controlled value only changes when you update it. If you pass `search`
+without `onSearchChange`, the box cannot be edited.
+
+### 3.4 Value shapes
+
+```ts
+type SortState     = { key: string; direction: "asc" | "desc" };  // key = row field / column key
+type ColumnFilters = Record<string, any[]>;                         // column key → ticked values; "" = blanks
+interface WidgetFilter {
+  field: string;     // a `header` from dataSource.fields
+  operator: "IN" | "NOT_IN" | "EQUALS" | "CONTAINS" | "STARTS_WITH"
+          | "GREATER_THAN" | "LESS_THAN" | "BETWEEN" | "EMPTY" | "NOT_EMPTY" | "DATE_IS";
+  value?: any;       // IN/NOT_IN: list · BETWEEN: [from, to] · DATE_IS: token · EMPTY/NOT_EMPTY: none
+}
+// DATE_IS tokens: TODAY YESTERDAY LAST_SEVEN_DAYS LAST_THIRTY_DAYS THIS_WEEK THIS_MONTH THIS_YEAR
+```
+
+Some rules to follow:
+- `WidgetFilter.field` must be a field in `dataSource.fields`. Unknown fields are skipped with a console warning.
+- User fields (AUTO_COMPLETE, assignees) filter by **user id**, not name.
+- A column filter with both blanks and values can only OR them locally. Server-side, the blanks are dropped (with a warning).
+
+### 3.5 Supplying your own controls (slots)
+
+Each slot receives the current value and setters. It returns any React node.
+Whatever it sets is applied to the data automatically.
+
+```tsx
+<DashboardTableWidget
+  dataSource={ds} configurations={cfg}
+
+  renderSearch={({ value, setValue, placeholder, loading }) => (
+    <Input.Search value={value} onChange={(e) => setValue(e.target.value)}
+                  placeholder={placeholder} loading={loading} allowClear />
+  )}
+
+  renderWidgetFilter={({ filters, fields, addFilter, removeFilter, clear }) => (
+    <MyFilterBuilder
+      fields={fields}                 // [{ field, label, kind, operators[] }]
+      value={filters}
+      onAdd={addFilter} onRemove={removeFilter} onClear={clear}
+    />
+  )}
+
+  showColumnFilter
+  renderColumnFilter={({ column, options, selected, setSelected }) => (
+    <MultiSelectDropdown
+      title={column.header}
+      options={options}              // [{ value, label, count }]
+      value={selected}
+      onChange={setSelected}         // [] clears this column
+    />
+  )}
+
+  renderSortIndicator={({ direction, toggle }) => (
+    <SortIcon direction={direction} onClick={toggle} />   // toggle: none → asc → desc → none
+  )}
+
+  renderToolbar={({ search, widgetFilter, interactions }) => (
+    <Space>{widgetFilter}{search}
+      {interactions.active && <a onClick={interactions.clearAll}>Reset</a>}
+    </Space>
+  )}
+/>
+```
+
+| Slot | Receives |
+| --- | --- |
+| `renderSearch` | `{ value, setValue, clear, placeholder, mode, loading, tokens }` |
+| `renderWidgetFilter` | `{ filters, setFilters, addFilter, removeFilter, clear, fields, declared, mode, tokens }` |
+| `renderColumnFilter` | `{ column, selected, setSelected, clear, options, mode, tokens }` |
+| `renderSortIndicator` | `{ column, direction, toggle, setDirection, tokens }` |
+| `renderToolbar` | `{ search, widgetFilter, interactions, tokens }`. `search` and `widgetFilter` are the resolved nodes |
+
+`fields` comes from `dataSource.fields`. Each entry has `kind` (`text` /
+`number` / `date` / `boolean`) and the `operators` that suit that kind.
+`declared` is the host's `config.filters` list, when one exists.
+
+If you omit a slot, you get a small token-styled default: a search input, a
+filter builder with chips, a checkbox list for column values, and ▲▼ sort
+buttons.
+
+> **Return an element from a slot. Don't pass a component that uses hooks as the
+> slot itself.** Slots are called as plain functions, so
+> `renderColumnFilter={MyFilter}` runs `MyFilter`'s hooks inside the widget and
+> breaks when the column count changes. Write
+> `renderColumnFilter={(a) => <MyFilter {...a} />}` instead.
+
+### 3.6 A fully custom table
+
+A table `render` receives everything it needs to build its own header:
+
+```tsx
+<DashboardTableWidget
+  dataSource={ds} configurations={cfg}
+  render={({ rows, columns, renderCell, interactions, headerControls, getColumnOptions, enableSort }) => (
+    <MyGrid
+      rows={rows}                                       // already searched / filtered / sorted
+      columns={columns.map((c) => ({
+        ...c,
+        header: <>{c.header}{headerControls(c)}</>,     // slot or default sort + filter controls
+        sortOrder: interactions.sortDirectionFor(c.key),
+        onHeaderClick: enableSort ? () => interactions.toggleSort(c.key) : undefined,
+      }))}
+      cell={renderCell}
+    />
+  )}
+/>
+```
+
+`interactions` also exposes `setSearch`, `setColumnFilter(key, values)`, `setSort`,
+`setWidgetFilters`, `addWidgetFilter`, `removeWidgetFilter`, `clearAll` and `active`.
+
+---
+
+## 4. Data sources — where the data comes from
+
+`configurations` describes how a widget looks. `dataSource` describes what is
+queried. The query generator reads `dataSource`, so a widget with a perfect
+config and no data source shows "No data source configured".
+
+```tsx
+import { formSource, taskSource, field, taskField, groupBy, aggregate, derive, where, pivot } from "@zestl/zvolv-widgets";
+
+const region  = field("Region",  "DROP_DOWN");
+const revenue = field("Revenue", "INPUT_CURRENCY");
+const target  = field("Target",  "INPUT_CURRENCY");
+
+const dataSource = formSource(1042, [region, revenue, target], {
+  pivot: pivot({
+    rows:    [groupBy(region)],                               // GROUP BY Region
+    summary: [aggregate(revenue, "sum"), aggregate(target, "sum")],
+    postOperations: [derive("Gap", "SUB", ["Target", "Revenue"])],
+  }),
+});
+```
+
+### The name-matching rule (mismatches fail silently)
+
+| Config key | Must equal |
+| --- | --- |
+| `series[].argumentField` | `pivot.rows[].title` (defaults to the field's `header`) |
+| `series[].valueField` | `pivot.summary[].value` (defaults to the field's `header`), or a `derive()` title |
+| `WidgetFilter.field`, `SortState.key`, `ColumnFilters` keys | a `header` in `dataSource.fields` |
+
+```tsx
+series: [
+  { name: "Revenue", valueField: "Revenue", argumentField: "Region" },
+  { name: "Gap",     valueField: "Gap",     argumentField: "Region" },
+]
+```
+
+A mismatch produces an empty chart and **no error**. Reusing the same `field()`
+objects everywhere keeps the names in step.
+
+### Other data-source rules
+
+- **Declare every field** you group by, plot, filter, search or sort on in `fields`. An undeclared field silently returns nothing.
+- **`taskSource([...])` never takes a `formId`.** A task source with a `formId` queries submissions and returns the wrong rows. Use `taskField("Status")`, which camelCases the server name to `status`.
+- **Use the real element type** in `field(header, type)`. The ES data type is derived from it, and aggregations depend on it. `INPUT_NUMBER` / `INPUT_CURRENCY` / `INPUT_PERCENT` → FLOAT; `FORM_SEARCH` / `INPUT_TAG` → ARRAY; `CHECK_BOX` → BOOLEAN; everything else → STRING.
+- **Never invent a `formId` or field name.** Ask for them, or copy them from an existing widget's stored `DataSource`.
+
+### Baked-in (author) filters vs viewer filters
+
+```tsx
+// Always applied, part of the widget definition:
+field("Status", "DROP_DOWN", { filter: where("IN", "Open", "Pending") })
+field("Created", "INPUT_DATE", { filter: where("DATE_IS", "{@[TODAY]}") })
+
+// Chosen by the viewer at runtime (§3):
+defaultWidgetFilters={[{ field: "Status", operator: "IN", value: ["Open"] }]}
+```
+
+---
+
+## 5. Controlling the UI
+
+These are ordered from cheapest to most control.
+
+**1. Design tokens** restyle everything without touching components:
+
+```tsx
+<ZvolvThemeProvider tokens={{
+  colors: { primary: "#0f766e", charts: { palette: ["#0f766e", "#b45309", "#6d28d9"] } },
+  typography: { kpiValue: { fontSize: "34px", fontWeight: 700 } },
+  widget: { appearance: "flat", borderRadius: "18px", padding: "22px" },
+  surfaces: { table: { headerBg: "#f3f4f1", altRowBg: "#fafaf8" } },
+  overrides: { KPI_CARD: { appearance: "border" } },           // per widget type
+  widgetDefaults: { BAR_CHART: { template: "horizontal" } },   // layered UNDER each widget's config
+}}>
+```
+
+**2. The `render` prop** lets you own the visuals while keeping the data:
+
+```tsx
+<BarChartWidget dataSource={ds} configurations={cfg}
+  render={({ rows, xKey, series, colorFor, toLabel }) => (
+    <ResponsiveContainer>
+      <BarChart data={rows}>
+        <XAxis dataKey={xKey} tickFormatter={toLabel} />
+        {series.map((s, i) => <Bar key={s.valueField} dataKey={s.valueField} fill={colorFor(i, s)} />)}
+      </BarChart>
+    </ResponsiveContainer>
+  )}
+/>
+```
+
+Always use `xKey` and `series[].valueField` from the args. Never hard-code
+field names. Run category and user values through `toLabel`.
+
+**3. Template overrides** replace a template everywhere:
+
+```tsx
+<TemplateProvider templates={{ "KPI_CARD:standard": MyKpiCard, "BAR_CHART:*": MyBars }}>
+```
+
+KPI templates receive `{ vm, index }`. `vm` is fully resolved: `value`,
+`rawValue`, `prefix`, `suffix`, `delta`, `progress`, `status`, `series`.
+Never re-derive values from `vm.raw`.
+
+**4. Interaction slots** replace the search, filter and sort controls (§3.5).
+
+---
+
+## 6. Widget catalogue
+
+| Family | Components | Type strings | `render` receives |
+| --- | --- | --- | --- |
+| KPI | `KpiWidget` | `KPI` `KPI_CARD` `KPI_CARD_V2` | templates get `{ vm, index }` |
+| Charts | `BarChartWidget` `LineChartWidget` `AreaChartWidget` `PieChartWidget` `DoughnutChartWidget` `ScatterChartWidget` | `BAR(_CHART)` `LINE(_CHART)` `AREA_CHART` `PIE(_CHART)` `DOUGHNUT(_CHART)` `SCATTER_CHART` | `{ rows, xKey, series, colorFor, toLabel, template, config, tokens, meta }` |
+| Ranking | `RankingBarWidget` | `RANKING_BAR` | `{ rows: {rank,label,value,ratio,raw}[], max, … }` |
+| Gauge | `GaugeMeterWidget` | `GAUGE_METER` | `{ value, min, max, ratio, color, band, thresholds, rows }` |
+| Heat map | `HeatMapWidget` | `HEAT_MAP` | `{ cells: {zone,count,color,band}[], grid }` |
+| Tables (columns from `config.columns[]` as `{ label, dataPoint, type }`, the stored shape) | `DashboardTableWidget` `DatabaseTableWidget` `TaskTrackerTableWidget` `ChildTableWidget` `PivotGridWidget` | `TABLE` `DATABASE_TABLE` `TASK_TRACKER_TABLE` `CHILD_TABLE` `CHILD_DATABASE_TABLE` `PIVOTGRID` | `{ rows, columns, renderCell, toLabel, interactions, headerControls, getColumnOptions, enableSort, showColumnFilter, mode }` (+ `rowFields`, `columnFields`, `valueFields` for pivot) |
+| Collections | `CardListWidget` `ActivityFeedWidget` `EntityGalleryWidget` `GridCardWidget` `CarouselWidget` `BannerWidget` | `CARDLIST` `ACTIVITYFEED` `ENTITY_GALLERY` `GRID_CARD` `CAROUSEL` `BANNER` | `{ items: CollectionItem[], template, config, tokens, toLabel }` |
+| Temporal | `TimelineWidget` `GanttChartWidget` `CalendarWidget` `MeetingSchedulerWidget` | `TIMELINE` `GANTT(_CHART)` `CALENDAR` `MEETING_SCHEDULER` | `{ events: TemporalEvent[], range, lanes }` |
+| Stepper | `StepperWidget` | `STEPPER` | `{ steps: StepItem[], currentIndex }` |
+| Display | `HtmlWidget` `RawHtmlWidget` `IframeWidget` `GoogleMapWidget` `TreeWidget` `ActionCardWidget` | `HTML` `RAW_HTML` `STATICHTML` `IFRAME` `GOOGLE_MAP` `MAP_CHART` `TREE` `ACTION(_CARD)` | html `{ html, rows }` · map `{ markers, center, zoom }` · tree `{ nodes }` · action `{ actions }` |
+| Containers | `TabWidget` `FormWidget` `FilterPanelWidget` `ZaiChatWidget` | `TAB` `FORM` `FORM_WIDGET` `FILTER_PANEL` `ZAI_CHAT` | see types |
+
+Render any widget from its stored type string: `<ZvolvWidget type="BAR_CHART" {...props} />`.
+`DATE_FILTER`, `FILTER`, `FILTERS` and `DASHBOARD_AUTOMATION` render nothing by design.
+
+**`render` is required** for `FormWidget`, `ZaiChatWidget`, `GoogleMapWidget`
+and HTML markup in `HtmlWidget`. Form rendering, the chat transport, map SDKs
+and HTML sanitization stay in the host app. The package never calls
+`dangerouslySetInnerHTML`.
+
+**`FilterPanelWidget` vs widget filters.** `FilterPanelWidget` is a
+*dashboard-level* control. It is controlled (`value` / `onChange`) and issues no
+queries. Feed its values into other widgets' `dashFilters`. A widget filter
+(§3) narrows only its own widget.
+
+---
+
+## 7. Headless hooks
+
+Use these when a built-in widget is not enough and you want to own all of the
+rendering.
+
+```tsx
+import { useWidgetInteractions, useWidgetData } from "@zestl/zvolv-widgets";
+
+function MyTable({ dataSource, configurations }) {
+  const ix = useWidgetInteractions({ defaultSort: { key: "Revenue", direction: "desc" } });
+  const { rows, sourceRows, state, meta, refresh } = useWidgetData({
+    dataSource, configurations, widgetType: "TABLE",
+    search: ix.search, columnFilters: ix.columnFilters, sort: ix.sort, widgetFilters: ix.widgetFilters,
+  });
+  // rows: after interactions · sourceRows: as fetched (use for filter options)
+  // state: "loading" | "ready" | "empty" | "unconfigured" | "error"
+  // meta: { xKey, series, toLabel, tableMode, filterMode, filtered }
+}
+```
+
+`useInteractiveWidgetData(props, { table })` combines both hooks and adds the
+toolbar and slot resolution. Every built-in widget uses it. Other hooks:
+`useKpiContents`, `useCollectionItems`, `useTemporalEvents`, `useTableColumns`.
+
+Pure helpers, which also work outside React: `applyLocalSearch`,
+`applyLocalColumnFilters`, `applyLocalSort`, `applyLocalWidgetFilters`,
+`distinctColumnValues`, `buildWidgetFilterClauses`, `buildColumnFilterClauses`,
+`buildSearchClause`, `buildRemoteSort`, `resolveTableMode`, `resolveFilterMode`.
+
+---
+
+## 8. Runtime: mock and real data
+
+### Mock (no backend)
+
+```tsx
+<ZvolvProvider runtime={createMockRuntime({ delay: 400, rows: myRows, onQuery: console.log })}>
+```
+
+The mock applies the same filter clauses and sort that a real query would carry,
+so search, filters and sort visibly work in previews. It does **not** aggregate
+pivots: every widget receives the raw rows. The default rows (`SAMPLE_ROWS`)
+have `region`, `owner`, `revenue`, `target`, `orders`, `status`, `startDate`,
+`endDate`, `latitude`, `longitude` and `parentId`.
+
+### Real data — built in
+
+The query path (ZAI-Dashboard's `generateQuery`, filter formatters, logged-in-user
+resolution, field mappings, user-name lookup) ships inside the package, ported
+verbatim. Pass an initialised, logged-in SDK client:
+
+```tsx
+import { ZvolvClient } from "@zestl/zvolv-js-sdk";
+import { ZvolvProvider, createZvolvRuntime } from "@zestl/zvolv-widgets";
+
+const client = new ZvolvClient("app.zvolv.in", true);
+await client.workspace.init("your-domain");
+await client.auth.login(email, password);        // or client.auth.init() to restore a session
+
+const runtime = createZvolvRuntime({ client: () => client });   // a getter: swap clients freely
+<ZvolvProvider runtime={runtime}>…</ZvolvProvider>
+```
+
+Call `resetQueryUser()` after login or logout, so the cached user group is
+re-resolved. [`../zvolv-insights`](../zvolv-insights) is a complete app built
+this way: login → apps → dashboards on live data.
+
+Inside ZAI-Dashboard you can instead wire the host's own utilities into
+`<ZvolvProvider runtime={…}>` (see the runtime keys below).
+
+| Runtime key | Required | Used for |
+| --- | --- | --- |
+| `client` | yes | `workflow.elasticSearch`, `workflow.getDataSource` |
+| `generateQuery` | yes, for form/task sources | building the ES query |
+| `formatDashboardFilters` | recommended | `dashFilters` / `localFilters` → clauses |
+| `formatHeaderFilters` | optional | column filters with id mapping. A built-in fallback exists |
+| `prefetchQueryMappings`, `resolveQueryUser` | recommended | field mappings, logged-in-user filters |
+| `resolveUserLabels`, `getUserFieldKind` | optional | user id → name on axes and in search |
+
+`createZvolvRuntime` fills in all of them. Widget code is identical under the
+mock and the real runtime.
+
+### Rendering stored dashboards
+
+`workflow.getDashboard(dashId, zappId).elements[0].widgets` is a list of stored
+widgets. These helpers turn it into widgets, layout and filter state, using the
+same rules ZAI-Dashboard applies:
+
+| Helper | Does |
+| --- | --- |
+| `normalizeWidget(w)` | deep-parses `Configuration` / `DataSource` (double-encoded JSON), hoists legacy `isTask`/`formId` from `dataSource.query`. Returns `{ type, title, configurations, dataSource, … }` |
+| `gridWidgets(ws)` | drops FILTER / DATE_FILTER / automation types and widgets nested in a TAB |
+| `resolveDashboardLayout(ws)` | `{ id, x, y, w, h }` on the 60-column grid. Legacy 12-col layouts are scaled ×5, unset positions are packed, and the result is compacted vertically |
+| `gridHeight(h)`, `GRID` | pixel height of a tile (`h × 5 + (h − 1) × 16`) |
+| `dashboardFilterDefs(ws)` | the FILTER widget's declared fields, for a dashboard filter bar |
+| `buildDashFilters(values, range)` | the `dashFilters` object every widget takes (`{ filter, filter_cond, cdate }`) |
+| `dateRangeFor(token)`, `dashboardDefaultDateToken(ws)` | date presets, and the DATE_FILTER widget's default |
+| `cdateFiltersFor(w, ws)` | the per-widget `cdateFilters` (the fields a date range lands on) |
+| `buildDashboardTree(elements, isAdmin)` | `getDashboards()` → a sorted tree (`ChildReportIDs` nest), with hidden/mobile-only removed |
+
+```tsx
+const w = normalizeWidget(stored);
+<ZvolvWidget type={w.type} title={w.title} dataSource={w.dataSource} configurations={w.configurations}
+             dashFilters={buildDashFilters(values, range)} cdateFilters={cdateFiltersFor(stored, all)} />
+```
+
+---
+
+## 9. Install, link, test
+
+Install from npm, together with the peer dependencies:
+
+```bash
+npm install @zestl/zvolv-widgets @zestl/zvolv-js-sdk react react-dom
+```
+
+To work against an unpublished change, link the library locally:
+
+```bash
+cd /path/to/zvolv-widgets
+npm install
+npm run build
+npm link
+
+cd /path/to/your-dashboard-app
+npm link @zestl/zvolv-widgets
+```
+
+Your app must already have these peer dependencies: `react` ≥18, `react-dom` ≥18
+and `@zestl/zvolv-js-sdk`. After changing library source, run `npm run build`
+again. The link picks it up without a reinstall.
+
+### Scripts
+
+| Command | What it does |
+| --- | --- |
+| `npm run build` | ESM + CJS + types into `dist/` |
+| `npm run dev` | rebuild on change |
+| `npm run typecheck` | types only |
+| `npm test` | build, then `test/interactions.mjs`, `test/runtime.mjs` and `test/smoke.mjs` |
+| `npm run verify` | typecheck + tests + packaging checks (`test/verify.mjs`) |
+
+| Suite | Proves |
+| --- | --- |
+| `test/runtime.mjs` | The built-in real runtime against a fake SDK client: search, sort, widget, column and dashboard filters all appear in the generated ES query. Pivot aggregation queries. Stored-dashboard helpers (parsing, layout scaling and packing, tree, filters) |
+| `test/interactions.mjs` | Mode selection. Clause building for search, widget filters, column filters and sort. Local evaluators. Rendered end to end: typing, header-click sort, column-filter slots, the filter builder, controlled vs uncontrolled state, local vs remote, automation rows, dashboard + widget filter merging |
+| `test/smoke.mjs` | All 48 renderable type strings render without React errors, both plain and with search and widget filter on. `unconfigured` ≠ `empty` |
+| `test/verify.mjs` | Build artifacts, `SKILL.md` and `README.md` exist, and the built module loads |
+
+### Using with Claude
+
+`SKILL.md` (shipped in the package) is the short, rule-first contract for LLM
+agents. Point Claude at `node_modules/@zestl/zvolv-widgets/SKILL.md` before it
+writes widget code. Without it, Claude tends to write its own data fetching.
+
+---
+
+## 10. Rules and known limitations
+
+### Rules
+
+1. **Never write a raw API call, build an ES query, recompute a pivot, or filter/sort rows yourself.** Pass `search` / `columnFilters` / `sort` / `widgetFilters`, and the library applies them in the right place.
+2. **`empty` ≠ `unconfigured`.** `unconfigured` means no data source is wired (a build mistake). `empty` means it is wired correctly and returned zero rows. Never fall back to demo data for either.
+3. Pass stored `dataSource` / `configurations` through untouched.
+4. Widgets fill their container. Give them a sized parent.
+5. No colour, font or shadow literals in templates or slots. Read `tokens` (or `useTokens()`).
+6. A `ChildTableWidget` must be clamped to its parent's visible width.
+
+### Known limitations
+
+- **Live backend:** `zvolv-insights` reaches the live API through `createZvolvRuntime` (workspace init and login verified). Check real dashboards against ZAI-Dashboard before relying on the numbers.
+- **Tables fetch up to `rowLimit` rows (default 1000).** There is no server pagination yet. Server-side search, filters and sort run over the full dataset, but only the first `rowLimit` matches are shown.
+- **Column-filter options** come from the rows loaded so far. They accumulate across fetches, so options do not vanish once one is ticked. They are not a full distinct-values query.
+- **Widget filters are AND-ed.** For OR logic, pass a host ZFilters payload through `localFilters`.
+- **Calendar / MeetingScheduler are simplified.** There is no drag-to-resize, month-grid layout or virtual scrolling. For full parity, wrap FullCalendar in `render`.
+
+---
+
+## 11. Forms
+
+Every ZAI-Dashboard form element is available as a headless engine. The
+library owns the behaviour: loading the schema (v2 and legacy), values,
+show/hide/mandatory rules, formulas, validation, lookups, uploads, field
+automations, action buttons, child sheets and the exact submit wire format.
+Your app owns every pixel.
+
+### Rendering a form
+
+```tsx
+import { ZvolvForm, FormKitSlot } from "@zestl/zvolv-widgets";
+
+// 1. Once, near the root: how each field kind looks in your app.
+<FormKitSlot.Provider value={myKit}>…</FormKitSlot.Provider>
+
+// 2. Anywhere: a form by id. A FORM / FORM_WIDGET dashboard widget does this for you.
+<ZvolvForm formId="6ab5019b13f5e4aa859b1d28" onSubmitted={({ submissionId }) => …} />
+<ZvolvForm formId={id} mode="EDIT" submissionId={subId} />
+```
+
+With no kit, plain native controls render so a form still works.
+
+### The kit
+
+```ts
+interface FormKit {
+  field?:  (field: FormField, form: ZvolvFormApi) => ReactNode;   // one control per field
+  form?:   (form, { body, title, submitLabel }) => ReactNode;     // header / body / footer
+  status?: ({ status: "loading" | "error" | "submitted", form }) => ReactNode;
+  grid?:   (cells, fields) => ReactNode;                          // 24-column span layout
+}
+```
+
+Switch on `field.kind`. Each `FormField` carries `id, type, kind, label, placeholder, help,
+required, disabled, hidden, span (of 24), value, error, options, multiple, min, max, step,
+precision, prefix, suffix, accept, maxSizeKB, maxCount, childIds, pages, html, setValue, onBlur`.
+`required` / `disabled` / `hidden` already include the form's rules.
+
+| `kind` | Platform types | Behaviour hook |
+| --- | --- | --- |
+| `text` `textarea` `email` `phone` `url` `scan` | INPUT_SHORT_TEXT, EDIT_TEXT, INPUT_EMAIL, INPUT_PHONE, INPUT_URL, INPUT_SCAN | — |
+| `number` `currency` `percent` | INPUT_NUMBER, INPUT_CURRENCY, INPUT_PERCENT | — |
+| `select` `radio` | SPINNER, RADIO_GROUP | `useFieldOptions` |
+| `lookup` | FORM_SEARCH, INPUT_TAG, EXTERNAL_API, form-backed AUTO_COMPLETE | `useFieldOptions` (search, cascades, ExtraLabels autofill) |
+| `user` | AUTO_COMPLETE with jsonData (people / role search) | `useFieldOptions` |
+| `checkbox` | CHECK_BOX (`attributes.showAsSwitch`) | — |
+| `date` `time` `datetime` `daterange` | DATE_PICKER, TIME_PICKER, DATE_TIME_PICKER, INPUT_DATE_RANGE | — |
+| `rating` `slider` | RATING_BAR / INPUT_RATE, PROGRESS_BAR | — |
+| `file` | FILE_UPLOAD_V2, UPLOAD_FILE_IMAGE, MEDIA_UPLOAD | `useFileField` (validates, uploads, stores records) |
+| `signature` `richtext` `timer` `location` | SIGNATURE, RICH_TEXT_EDITOR, INPUT_TIMER, GPS | — |
+| `formula` `autonumber` `display` | INPUT_FORMULA, INPUT_AUTONUMBER / CREATED* / MODIFIED*, TEXT_VIEW / HTML_TEXT | computed by the engine |
+| `section` `container` `tabs` `steps` `matrix` `table` | GROUP_VIEW subtypes, STEPPER, TAB, MATRIX, TABLE_START | `form.childrenOf(field)` + `<FormFields>` |
+| `sheet` | INPUT_SHEET, NESTED_FORM, INPUT_CHILD_WIDGET | `useSheetField` (rows are posted before the parent) |
+| `action` | ACTION_BUTTON, TRIGGER_AUTOMATION, CASCADED_ACTIONS | `form.runAction(field)` |
+| `comments` `system` | COMMENTS, ON_BEHALF_OF, INPUT_IP, INPUT_DEVICE_INFO | system fields are filled automatically and never shown |
+
+**Dependent lookups.** A `FETCH_OPTIONS_FILTERS` rule sits on the lookup it filters, as in
+zvolv-web and ZAI-Dashboard: `{ type: "FETCH_OPTIONS_FILTERS", elementId: <source field>, masterField: <label on the
+lookup's source form> }`. `useFieldOptions` waits for the source (`waitingFor: "Select … first"`), filters by its
+value, clears the selection when the source changes, and auto-selects when exactly one row matches — so
+"pick a laptop → Asset ID and Model fill in" is two read-only lookups filtered on Serial Number. The older shape
+(rule on a non-lookup driver, `elementId` = the lookup) is still read. `cascade(source, target, masterField)` writes
+the platform shape.
+
+**Field parity with ZAI-Dashboard / zvolv-web.**
+
+- **Options load on focus.** Call `o.onFocus()` from your control's focus/open handler. Lookups and people search fetch nothing until then, as in zvolv-web (`nzFocus → onFocus`) and ZAI (`handleFocus`). Lookups re-fetch on later focuses (throttled to 2 s); people search re-fetches only when it has nothing loaded. Dependency-filtered lookups still load as soon as their source is set. Pass `useFieldOptions(form, field, { loadOn: "mount" })` for the old behaviour.
+- **Single vs multi** comes from `properties.maxResults` for FORM_SEARCH, INPUT_TAG and AUTO_COMPLETE (1 = single). `toggle` refuses picks past the limit; `o.maxCount` and `o.atLimit` tell the control.
+- **INPUT_TAG** can store a value that isn't in the list: `o.addFreeTag(text)` stores `{ view, select, extraLabels: [] }`.
+- **ExtraLabels auto-fill is off by default.** Neither platform copies a picked row's ExtraLabels into other fields; use a `FETCH_OPTIONS_FILTERS` dependent lookup. Opt in with `{ autofillExtraLabels: true }`.
+- **ON_BEHALF_OF** has kind `"onbehalf"`. It is shown read-only, stores the signed-in user's id (never a role id), shows `field.displayText` (the user's name), and isn't overwritten by automation `formData`.
+- **CHECK_BOX** with `attributes.showAsSwitch` gets `field.variant === "switch"`. `"1"` is read as true.
+- **DATE_PICKER** `dynamicDefault` supports `ADD` and `SUB`, any unit (`days`, `weeks`, `months`, `years`, `hours`), a bare number of days, and the `DynamicDefault` key. `field.dateFormat` is `properties.format` converted to dayjs tokens (default `DD/MM/YYYY`).
+- **RICH_TEXT_EDITOR**: markup with no text (`<p><br></p>`, `&nbsp;`) counts as empty and is sent as `null`. `field.maxLength` also reads `attributes.charactersCount`.
+- **FILE_UPLOAD_V2**: the count limit also reads `allowedFileMaxCount` and `properties.max` (1 for `ShowAsProfileImagePicker`). Blocked extensions (`.exe`, `.bat`, `.js`, … — `BLOCKED_FILE_EXTENSIONS`) are refused.
+- **INPUT_SHEET**: `useSheetField` returns `canAdd` / `canDelete` (from `allowedAddActions`, `allowedDeleteActions` or `allowedActions`), `maxRows` and `limitMessage`. Saved rows load without marking the form dirty. Row validation skips hidden, disabled and non-input columns and untouched saved rows.
+- **Action buttons** (`form.runAction`): `actionType` comes from `properties.actionType` or `subType`. `OPEN_URL` (default; falls back to `defaultValue`), `SUBMIT`, `TRIGGER_AUTOMATION` (also treats `code` 400/500 as an error), and `UPDATE` / `UPDATE_SUBMISSION` / `UPDATE_OPEN_NEW_FORM` / unknown types (set the button `true`, then save). `SAVE_SUBMISSION`, `CREATE_SUBMISSION`, `EDIT_SUBMISSION`, `OPEN_TASK`, `PRINT_PREVIEW`, `INVOKE_AGENT` and the like open other UI, so they go to your `onAction`; the library no longer submits the current form for `SAVE_SUBMISSION`.
+
+**Show / hide / mandatory rules (triage).** These match ZAI-Dashboard's `applyDependencies`:
+
+- Rules sit on the driving field. `properties.triage` replaces `dependencies` when present.
+- A rule with an array `value` needs the selected values to equal that set exactly. A lookup rule with one `value` needs exactly one selection.
+- When rules for the same target disagree, a matching rule beats a non-matching one. With no match, the field's own `hidden` / `required` / `disabled` applies. `*_WITHOUT_RESET` types act like the plain ones.
+- Hiding a field keeps its value, as in ZAI-Dashboard and zvolv-web. Hidden fields are skipped by validation.
+- `field.error` shows only after a submit (or `form.validate()`), and clears as soon as that field changes. A field that a rule newly makes mandatory does not turn red until the next submit.
+
+`form.runAction` handles OPEN_URL, SAVE_SUBMISSION and automation triggers (writing
+`formData` back into the form). Pass `onAction` to `<ZvolvForm>` for host actions such as
+"open another form".
+
+### Headless
+
+`useZvolvForm({ formId, mode, submissionId, defaultValues, hiddenFields, skipTypes, onSubmitted })`
+returns the same `ZvolvFormApi` without any markup. `setValue`, `validate(ids?)`, `submit()`,
+`reset()`, `applyValues(map)`, `dirty`, `submitting`, `submitError`, `status`.
+
+Pure helpers: `normaliseForm`, `serializeElementValue`, `buildSubmissionElements`,
+`buildTriggerBody`, `validateField`, `applyRules`, `evaluateFormula` (a parser; there is no `eval`).
+
+### Creating forms (for Claude and scripts)
+
+`el`, `when`, `cascade`, `defineForm` and `formWidget` build payloads for the MCP
+`create_form` / `create_widget` tools:
+
+```ts
+const sev = el.radio("Severity", ["Low", "High", "Critical"], { required: true });
+const cause = el.longText("Root Cause Analysis");
+when(sev, "High").show(cause).require(cause);
+when(sev, "Critical").show(cause).require(cause);
+const payload = defineForm({ title: "Incident Report", zappId: 11, zappName: "5S Audit", elements: [
+  el.lookup("Plant", { formId: PLANTS, field: "Plant", extra: ["Region"] }, { required: true }),
+  el.text("Region", { disabled: true, width: 25 }),   // autofilled from the lookup
+  sev, cause,
+  el.number("Quantity"), el.currency("Rate"),
+  el.formula("Order Value", "MUL(Quantity, Rate)"),
+]});
+const widget = formWidget({ formId: created.id, title: "Report an incident", layout: { x: 0, y: 91, w: 60, h: 56 } });
+```
+
+Platform rules these helpers follow:
+- `width` is a percentage (25, 50, 75 or 100). It goes at the element root and in `attributes.Width`.
+- Show/hide/mandatory rules sit on the driving field. Give the target `hidden: true` and add a SHOW rule for each value.
+- **Do not use `AVG`**: the platform lists it but does not implement it. Every write to the form then fails with a 502. Write the average out instead, e.g. `DIVI(ADD(A, ADD(B, C)), 3)`. `ADD`, `SUB`, `MUL`, `DIVI` and `IF` are verified working.
+- The `create_form` validator only accepts formulas with **bare, single-word labels**, e.g. `MUL(Quantity, Rate)`. It rejects `{Label}` and labels containing spaces, even though the KB documents `{Label}`. The engine evaluates both styles.
+- Row height is 21px. A tile of `h` rows is `h × 21 − 16` px tall, so size form tiles to their fields; forms scroll inside the tile with the footer pinned.