@zestl/zvolv-widgets 0.0.2 → 0.0.3

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 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

@@ -545,6 +545,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 +711,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 +733,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.
 
 ---
 

package/SKILL.md

@@ -191,9 +191,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 +204,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)`.