@zestl/zvolv-widgets 0.0.2 → 0.0.4

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 0.0.4
+
+### Added
+- **`canViewDashboard(d, { isAdmin, groupId })`** — ZAI-Dashboard's dashboard view rule (admins all; `permissions` VIEW/EDIT_PERMISSION; `HideInMobileApp` needs EDIT_PERMISSION; `ViewPerm` fallback).
+- **`visibleDashboardTree(elements, viewer)`** — `canViewDashboard` + `buildDashboardTree`, for an app's sidebar.
+- README §12 and SKILL.md: apps on stored dashboards (pages, access, per-page loading, per-widget refresh) and writing records with `fetchSubmission` / `updateSubmission` / `createSubmission`.
+
+### Documented
+- A TABLE widget with `configuration.columns` returns only `id` + those columns (`_source`); store every field a host reads or writes back as a column.
+
+## 0.0.3
+
+These are all client-side enhancements that run after the query; none changes
+what is queried. Existing configs give byte-identical queries, rows and default
+markup, which `test/compat.mjs` checks against snapshots captured from 0.0.2.
+There is nothing for ZAI-Dashboard or the server to mirror.
+
+### Added
+- **KPI card layout.**
+  - `config.layout: "card"` (or `cardConfig.layout`) renders every item inside one card, through a `"KPI_CARD:card"` template override or the default `KpiCard`.
+  - `KpiWidget` takes `renderCard` (or `render`), which receives `{ vms, byKey, roles, state, tokens, config, onItemClick }`. Both are used only in card mode, so a generic `render` a host passes to every widget leaves KPIs unchanged.
+  - `KpiContentConfig.role` (`"main" | "sub" | "chip" | "series"`) places an item in the card; `resolveKpiRoles` does this sorting.
+  - `KpiSparkline` gains `width`, `height`, `area` and `scale: "minmax" | "zero"`.
+- **`unpivot`.** On `useWidgetData` and every data widget. It turns row 0's columns into one `{ label, value }` row per column, in the given order. A missing column gives 0. `extra` copies more columns onto the output rows. It runs after postOperations. With no declared series, x and y become `labelField` and `valueField`. Pure helper: `unpivotRows`.
+- **`ranking.order: "none"`.** `RankingBarWidget` keeps the incoming row order.
+- **`FunnelWidget` (type `FUNNEL`).** Each stage resolves to `{ label, value, ratioToFirst, stepPct, isFirst, index, raw }`, with `onItemClick(row)` for drill-down. `render` gets `{ rows, first, tokens, config, toLabel, onItemClick }`. Pure helper: `computeFunnelRows`.
+- **`categoryGap`.** On `useWidgetData` and every data widget. It gives one row per category in the given order, or in the form's dropdown order with `"fromForm"`. Missing buckets get 0 for every series valueField, and values that are not listed are kept at the end. It runs after postOperations and widget filters, and before local search, column filters and sort. Pure helpers: `fillCategoryGaps`, `elementOptionValues`.
+- **`FilterPanelWidget` options from a data source.**
+  - `filters[].optionsSource = { dataSource, labelField, valueField, sort?, allLabel? }` fetches the options in one request: a distinct-values aggregation over the whole index, with the source's filters applied server-side (`optionsDataSource`).
+  - Values restored from URL params match numeric options (`matchFilterOption`).
+  - `onFiltersChange(WidgetFilter[])` emits `{ field, operator: "IN", value: [v] }`, or nothing for "All".
+  - The `renderFilter` slot receives `{ control, options, value, setValue, loading, tokens }`.
+  - Pure helpers: `filterPanelToWidgetFilters`, `rowsToFilterOptions`.
+- **New tests:** `kpiCard`, `unpivot`, `funnel`, `categoryGap`, `filterOptions`. `compat` now also snapshots rows and default markup. A missing snapshot now fails the test instead of being regenerated.
+
 ## 0.0.2
 
 Every new feature is opt-in. Configs that existed before this release produce

package/MIRROR_NOTES.md

@@ -144,3 +144,13 @@ item below is what the client expects. Verify each one against a live index.
   - `dateDiff()`.
   - `aggregate(f, type, name, { percents, where })`.
   - `pivot()`, `formSource()` and `taskSource()` move `where` conditions into `pivot.filters` with `combine: "AND"`.
+
+---
+
+## 0.0.3: nothing to mirror
+
+`unpivot`, `categoryGap`, the KPI card layout, `FunnelWidget` and filter
+`optionsSource` all run in the browser after the query. They add no query
+shapes and need no server change. `categoryGap: "fromForm"` reads the form
+through the same `getSingleForm` call the widget's access check already makes.
+

package/README.md

@@ -36,6 +36,7 @@ visual decision can be overridden.
 9. [Install, link, test](#9-install-link-test)
 10. [Rules and known limitations](#10-rules-and-known-limitations)
 11. [Forms](#11-forms)
+12. [Apps on stored dashboards: pages, access, writes](#12-apps-on-stored-dashboards-pages-access-writes)
 
 ---
 
@@ -545,6 +546,117 @@ KPI card with 20 numbers on one form is one call. `pivot()`, `formSource()` and
 `combine: "AND"`. Stored `pivot.filters` entries without that marker keep the
 original rule: the last entry per metric wins.
 
+### Reshaping rows after the query (0.0.3)
+
+These run in the browser after the query returns. They never change what is
+queried.
+
+**One wide row → one row per category (`unpivot`).** A multi-number source
+returns one row such as `{ Longlist: 4, Contacted: 4, … }`. Turn it into one
+row per column, in your order:
+
+```tsx
+const STAGES = ["Longlist", "Contacted", "Interviewed", "Offered", "Placed"];
+
+<RankingBarWidget
+  dataSource={FUNNEL_ONE}
+  unpivot={{ columns: STAGES, extra: { "Contacted %": "step" } }}
+  configurations={{ ranking: { order: "none" } }}   // keep stage order; ratio = value / max
+/>
+```
+
+- Output rows are `{ label, value }`. Rename the keys with `labelField` / `valueField`.
+- A missing column gives 0.
+- `unpivot` runs after `postOperations`, so a `derive()` column can be a stage.
+- With no declared `series`, x and y become `labelField` and `valueField`.
+- `extra` copies a source column onto the stage row whose name it starts with. `"Contacted %"` lands on the "Contacted" row as `step`. A source column that matches no stage is copied onto every row.
+
+**All categories, in dropdown order (`categoryGap`).** ES returns a bucket only
+for values that have data. `categoryGap` adds a zero row for every missing
+category and orders the rows:
+
+```tsx
+<BarChartWidget
+  dataSource={MINI_FUNNEL}
+  categoryGap={{ field: "Pipeline Stage", values: "fromForm" }}   // or an explicit list
+  widgetFilters={[{ field: "Assignment", operator: "IN", value: [title] }]}
+  render={({ rows }) => <MiniBars rows={rows} />}
+/>
+```
+
+- `field` is the chart's argumentField.
+- `"fromForm"` reads that field's dropdown options from the form schema, once per form; it reuses the widget's form lookup.
+- Every series `valueField` is 0 in the added rows.
+- Values that are not in the list are kept, after the listed ones.
+- It runs after `postOperations` and widget filters, and before local search, column filters and sort.
+
+### Funnel
+
+```tsx
+<FunnelWidget
+  dataSource={FUNNEL_ONE}
+  unpivot={{ columns: STAGES }}
+  onItemClick={(row) => setStage(row.label)}
+/>
+```
+
+Each stage resolves to `{ label, value, ratioToFirst, stepPct, isFirst, index, raw }`:
+- `stepPct` is value ÷ previous stage × 100. It is `null` for the first stage, and after a stage of 0.
+- `ratioToFirst` is value ÷ first stage. It is 0 when the first stage is 0.
+
+Stages are never re-sorted. `render` gets `{ rows, first, tokens, config, toLabel, onItemClick }`.
+
+### One KPI card from several numbers
+
+```tsx
+<KpiWidget dataSource={cardSource} configurations={{ layout: "card", contents: [
+  { dataPoint: "value",  role: "main", title: "Open mandates", template: "chart", seriesPoints: P1toP12 },
+  { dataPoint: "total",  role: "sub",  title: "total" },
+  { dataPoint: "atRisk", role: "sub",  title: "at risk" },
+  { dataPoint: "P12",    role: "chip", template: "trend", deltaSource: "datapoint", deltaPoint: "P8",
+    deltaMode: "absolute", subtitle: "vs 4 wk" },
+]}} />
+```
+
+The default card puts the items in slots by `role`:
+- `main` is the big value. Without a `main` role, it is the first item with no role.
+- `sub` items are small inline values under it.
+- `chip` is the change badge (its `delta`).
+- `series` supplies the sparkline. Without it, the main item's series is used.
+
+Card mode turns on only with `layout: "card"`, set either at the config root
+or in `cardConfig`, where platform KPI payloads keep their items. To build the
+card yourself, pass `renderCard={({ vms, byKey, roles, state, tokens }) => …}`;
+`render` also works, but likewise only in card mode, so a `render` a host
+passes to every widget never changes a KPI. `byKey` maps each `dataPoint` to
+its resolved item; the first item wins when two share one. You can also
+register a `"KPI_CARD:card"` template. `KpiSparkline` accepts
+`width`, `height`, `area` (fill under the line) and `scale: "minmax" | "zero"`.
+
+### Filter options from another form
+
+```tsx
+<FilterPanelWidget
+  configurations={{ filters: [{
+    key: "scope", field: "Assignment", type: "select",
+    optionsSource: {
+      dataSource: OPEN_MANDATES,              // e.g. a formSource on Assignment with Status IN Open
+      labelField: "Assignment Title", valueField: "Assignment Title",
+      sort: "asc", allLabel: "Firm-wide",
+    },
+  }] }}
+  onFiltersChange={(filters) => setScopeFilters(filters)}   // → other widgets' widgetFilters
+  renderFilter={({ options, value, setValue, loading }) => <MySelect … />}
+/>
+```
+
+- **Fetch:** the options come from one request: a distinct-values (composite terms) aggregation over the **whole index**, with the source's own filters applied by Elasticsearch. It is not built from a page of rows. The cap is the composite size (50,000 distinct values, or `displayRowLimit`). Declare `labelField` and `valueField` in the source's `fields` so text fields aggregate on `.keyword`. A source that already has a `pivot` is used as is. The panel refetches only when `optionsSource.dataSource` changes.
+- **Where the filter runs:** the emitted filter is applied in the target widget's ES query, so over the whole index. Only automation-row and legacy widget-id sources, which have no query, filter their loaded rows.
+- **URL values:** values restored from URL params (strings) match numeric options, and the emitted filter carries the option's own typed value.
+- **Output:** choosing a value emits `[{ field, operator: "IN", value: [v] }]`; "All" emits `[]`.
+- **Lookup targets:** when `field` is a FORM_SEARCH lookup on the target form, the filter matches the lookup's `.view` value. So `valueField` must be the field named as the lookup's **ViewLabel**.
+- **Without a slot:** the panel renders a plain `<select>` for these controls.
+
 ---
 
 ## 5. Controlling the UI
@@ -600,9 +712,10 @@ Never re-derive values from `vm.raw`.
 
 | Family | Components | Type strings | `render` receives |
 | --- | --- | --- | --- |
-| KPI | `KpiWidget` | `KPI` `KPI_CARD` `KPI_CARD_V2` | templates get `{ vm, index }` |
+| KPI | `KpiWidget` | `KPI` `KPI_CARD` `KPI_CARD_V2` | templates get `{ vm, index }`; `render` / `"KPI_CARD:card"` get `{ vms, byKey, roles, state, tokens, config }` |
 | 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, … }` |
+| Ranking | `RankingBarWidget` | `RANKING_BAR` | `{ rows: {rank,label,value,ratio,raw}[], max, … }` (`ranking.order: "none"` keeps row order) |
+| Funnel | `FunnelWidget` | `FUNNEL` | `{ rows: {label,value,ratioToFirst,stepPct,isFirst,index,raw}[], first, tokens, config, toLabel, onItemClick }` |
 | 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) |
@@ -621,9 +734,10 @@ 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.
+*dashboard-level* control. It is controlled (`value` / `onChange`), and it
+issues no queries except one per `optionsSource`. Feed its values into other
+widgets' `dashFilters`, or pass `onFiltersChange` output to their
+`widgetFilters`. A widget filter (§3) narrows only its own widget.
 
 ---
 
@@ -726,6 +840,8 @@ same rules ZAI-Dashboard applies:
 | `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 |
+| `canViewDashboard(d, { isAdmin, groupId })` | ZAI-Dashboard's view rule: admins see all; otherwise `d.permissions` must hold `VIEW_PERMISSION` / `EDIT_PERMISSION` (`HideInMobileApp` needs `EDIT_PERMISSION`); without `permissions`, `ViewPerm` (group ids, `-1` = everyone) is checked |
+| `visibleDashboardTree(elements, viewer)` | `canViewDashboard` filter + `buildDashboardTree`: the sidebar of an app |
 
 ```tsx
 const w = normalizeWidget(stored);
@@ -800,6 +916,7 @@ writes widget code. Without it, Claude tends to write its own data fetching.
 - **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.
+- **A TABLE widget returns only its columns.** When `configuration.columns` is non-empty, the query asks Elasticsearch for `_source: ["id", ...columns.map(c => c.dataPoint)]` (`["uuid", …]` for tasks). A field that is not a column is not in the rows, even if it is in `dataSource.fields`. Store every field a host reads or writes back as a column (`hidden: true` hides it from the default table), or leave `columns` empty to get every field.
 - **Widget filters are AND-ed.** For OR logic, pass a host ZFilters payload through `localFilters`.
 - **0.0.2 query features need server and host support.** `interval` grouping, `dateDiff` metrics, percentiles and AND-ed per-metric filters produce ES shapes that the server's aggregation flattener and ZAI-Dashboard must also handle. See `MIRROR_NOTES.md`.
 - **Calendar / MeetingScheduler are simplified.** There is no drag-to-resize, month-grid layout or virtual scrolling. For full parity, wrap FullCalendar in `render`.
@@ -972,3 +1089,64 @@ Platform rules these helpers follow:
 - **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.
+
+---
+
+## 12. Apps on stored dashboards: pages, access, writes
+
+A custom app (e.g. a zapp app at `/v6/<app>/zapp/<id>`) can use the zapp's dashboards as its pages.
+The pattern below is what the `zvolv-zapp-app` skill's template does.
+
+### Pages = the dashboards the user may open
+
+```ts
+const res = await client.workflow.getDashboards(String(zappId));
+const elements = res?.data?.elements ?? res?.elements ?? [];
+const tree = visibleDashboardTree(elements, { isAdmin, groupId });   // sidebar, in SequenceID order, titles from Zvolv
+```
+
+- Tag each dashboard's Description (e.g. `app:screen:orders`) to pick the screen that draws it; draw an
+  untagged one generically with `normalizeWidget` + `resolveDashboardLayout` + `<ZvolvWidget>`.
+- Edit rights on the zapp: `client.workflow.checkPermissions(zappId, ["EDIT_WORKFLOW_TYPE"])` returns the
+  granted ops (ZAI-Dashboard's `hasDashboardEditAccess`).
+- `isAdmin`: the signed-in user's `profile.role_details.role === "admin"` (decrypt the session first:
+  `decryptAuthObject(client.auth.userInstance)`). `groupId`: `userGroupId` on the same object.
+
+### Load per page, refresh per widget
+
+On each visit to a page, call `getDashboard(dashId, zappId)` once and run only that page's widgets
+(`useWidgetData({ widgetId, widgetType, dataSource, configurations })` per widget, from
+`normalizeWidget`). Nothing is fetched for pages that are not open. A card's refresh button calls that
+widget's `refresh()`; nothing else refetches.
+
+### Writing records
+
+The submission engine `<ZvolvForm>` uses is exported for in-place edits (a status select, a drag to
+another stage, an owner pick):
+
+```ts
+import { fetchForm, fetchSubmission, updateSubmission, createSubmission, submissionIdOf } from "@zestl/zvolv-widgets";
+
+// update a few fields of one record, keeping every other stored value
+const { form, values } = await fetchSubmission(client, row.id);          // row.id = the submission id
+const def = form ?? (await fetchForm(client, formId));
+const byId = { ...values };
+for (const [label, v] of Object.entries(patch)) byId[def.elements.find((e) => e.label === label)!.elementId] = v;
+await updateSubmission(client, def, row.id, def.elements, byId);
+
+// create one
+const res = await createSubmission(client, def, def.elements, { [elementIdOf("Status")]: "Open" });
+const id = submissionIdOf(res);
+```
+
+| Field type | Value |
+| --- | --- |
+| text, number, date (`YYYY-MM-DD`), SPINNER | as is (the option text for SPINNER) |
+| CHECK_BOX | `true` / `false` |
+| AUTO_COMPLETE people picker | `[userId]` |
+| FORM_SEARCH / INPUT_TAG lookup | `{ view, select, extraLabels: [] }` |
+
+- A row's identity is `row.id` (the submission id). Autonumber fields come back only if they are columns
+  (see §10), so never key records on them.
+- After a write, refetch the widgets that read that form (`refresh()`), rather than patching rows locally.
+- The server re-evaluates formulas and enforces form permissions; show its error when a write is refused.

package/SKILL.md

@@ -18,6 +18,8 @@ design tokens, render props and control slots. You never write data logic.
 6. **No colour/font/shadow literals** in templates or slots. Use `tokens` / `useTokens()`.
 7. Pass stored `dataSource` / `configurations` through **untouched**. Give widgets a sized parent.
 8. Never call `getZvolvClient()` at module scope. The runtime's `client` is a getter.
+9. **A TABLE returns only its columns.** Non-empty `configuration.columns` limits the query to `["id", ...columns]`. Store every field you read or write back as a column (`hidden: true` to hide it), or leave `columns` empty.
+10. **Rows are keyed by `row.id`** (the submission id). Edits go through `fetchSubmission` + `updateSubmission` (or `<ZvolvForm mode="EDIT">`), creates through `createSubmission` / `<ZvolvForm>`. Never keep edited records only in app state.
 
 ## Setup
 
@@ -123,6 +125,7 @@ For `getDashboard(dashId, zappId).elements[0].widgets`, never parse or lay out b
 `dashboardFilterDefs(ws)` + `buildDashFilters(values, range)` → `dashFilters` ·
 `cdateFiltersFor(w, ws)` → `cdateFilters` · `dateRangeFor(token)` · `buildDashboardTree(getDashboards().elements, isAdmin)`.
 Stored table columns are `{ label, dataPoint, type }` and are read as-is.
+Sidebar of an app: `visibleDashboardTree(getDashboards().elements, { isAdmin, groupId })` — the access rule is `canViewDashboard` (admins all; else `permissions` has VIEW/EDIT_PERMISSION; else `ViewPerm` holds the group). Load a dashboard's widgets when its page opens, not before; a card refresh = that widget's `refresh()`. Zapp edit right: `workflow.checkPermissions(zappId, ["EDIT_WORKFLOW_TYPE"])`. Full pattern: README §12.
 
 ## Authoring a data source
 
@@ -191,9 +194,10 @@ KPI templates: `standard` `trend` `comparison` `progress` `financial` `status` `
 
 | Family | Components | `render` args |
 | --- | --- | --- |
-| KPI | `KpiWidget` | templates get `{ vm, index }`. `vm` is fully resolved; never read `vm.raw` |
+| KPI | `KpiWidget` | templates get `{ vm, index }`. `vm` is fully resolved; never read `vm.raw`. Card: `layout: "card"` (root or `cardConfig`) + `contents[].role` (`main`/`sub`/`chip`/`series`); custom card via `renderCard` (only in card mode) |
 | Charts | `BarChartWidget` `LineChartWidget` `AreaChartWidget` `PieChartWidget` `DoughnutChartWidget` `ScatterChartWidget` | `{ rows, xKey, series, colorFor, toLabel, template, config, tokens, meta }` |
-| Ranking | `RankingBarWidget` | `{ rows: {rank,label,value,ratio}[], max }` |
+| Ranking | `RankingBarWidget` | `{ rows: {rank,label,value,ratio}[], max }`; `ranking.order: "none"` keeps row order |
+| Funnel | `FunnelWidget` (`FUNNEL`) | `{ rows: {label,value,ratioToFirst,stepPct,isFirst}[], first, tokens }`; `onItemClick(row)` |
 | Gauge | `GaugeMeterWidget` | `{ value, min, max, ratio, color, band }` |
 | Heat map | `HeatMapWidget` | `{ cells: {zone,count,color,band}[], grid }` |
 | Tables | `DashboardTableWidget` `DatabaseTableWidget` `TaskTrackerTableWidget` `ChildTableWidget` `PivotGridWidget` | `{ rows, columns, renderCell, toLabel, interactions, headerControls(col), getColumnOptions(key), enableSort, showColumnFilter, mode }` |
@@ -203,6 +207,17 @@ KPI templates: `standard` `trend` `comparison` `progress` `financial` `status` `
 | Display | `HtmlWidget` `RawHtmlWidget` `IframeWidget` `GoogleMapWidget` `TreeWidget` `ActionCardWidget` | see types |
 | Containers | `TabWidget` `FormWidget` `FilterPanelWidget` `ZaiChatWidget` | see types |
 
+Reshaping after the query (0.0.3). Use these instead of re-shaping rows in React:
+
+```tsx
+unpivot={{ columns: STAGES, extra: { "Contacted %": "step" } }}   // one wide row → { label, value } per column, in order; missing → 0
+categoryGap={{ field: "Pipeline Stage", values: "fromForm" }}     // every category in dropdown order, 0 where no bucket
+<FunnelWidget dataSource={ONE_ROW} unpivot={{ columns: STAGES }} onItemClick={(r) => …} />
+<FilterPanelWidget configurations={{ filters: [{ key, field: "Assignment", type: "select",
+  optionsSource: { dataSource, labelField, valueField, allLabel: "Firm-wide" } }] }}
+  onFiltersChange={(f) => setWidgetFilters(f)} />   // valueField = the lookup's ViewLabel field for FORM_SEARCH targets
+```
+
 **`render` is REQUIRED** for `ZaiChatWidget`, `GoogleMapWidget` and `HtmlWidget` markup. `FormWidget` renders `<ZvolvForm>` by default (see Forms). The package never calls `dangerouslySetInnerHTML`.
 
 In chart `render`, always use `xKey` and `series[].valueField` from the args, pass axis and user values through `toLabel`, and colour with `colorFor(i, s)`.
@@ -257,6 +272,10 @@ When asked to build a dashboard that captures data:
 - `width` is a percentage, placed at the element root and in `attributes.Width`.
 - Rules go on the driving field; each target starts `hidden: true`.
 
+## Writing records
+
+`fetchSubmission(client, row.id)` → `updateSubmission(client, form, row.id, form.elements, valuesByElementId)` keeps every other stored value. `createSubmission(client, form, form.elements, values)` + `submissionIdOf(res)` for a create. Values: people `[userId]`, lookups `{ view, select, extraLabels: [] }`, checkbox `true/false`, dates `YYYY-MM-DD`. Refetch the widgets of that form after a write. See README §12.
+
 ## Checklist before you finish
 
 - [ ] Every plotted, grouped, filtered, searched or sorted name exists as a `dataSource.fields` header, and series names equal the pivot titles/values.
@@ -264,3 +283,4 @@ When asked to build a dashboard that captures data:
 - [ ] Controlled interaction props each have their `on*Change`.
 - [ ] No hard-coded colours. `render` is supplied for ZaiChat, GoogleMap and Html markup, and a FormKit is provided when forms are shown.
 - [ ] Each widget sits in a sized container, and `ChildTableWidget` is width-clamped.
+- [ ] Every change a user makes is written with `ZvolvForm` / `updateSubmission` / `createSubmission`; no records live only in app state or browser storage.