@zestl/zvolv-widgets 0.0.0 → 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## 0.0.2
+
+Every new feature is opt-in. Configs that existed before this release produce
+byte-identical queries (`test/compat.mjs`). The query-generator changes that
+ZAI-Dashboard and the server must mirror are listed in `MIRROR_NOTES.md`.
+
+### Fixed
+- **A pivot output name is no longer used as the ES field name.** Pivot rows, columns and summaries now group and aggregate on `masterField`. `title` only names the output key. Before, `groupBy(f, "alias")` queried a field called `alias` and returned no buckets. Configs where `title === masterField` are unchanged.
+  - This also fixes the library's own `groupBy(taskField("Status"))`, which used to query `Status.keyword` instead of `status.keyword`.
+- **`fillDateGaps` no longer overwrites rows in the same period.** Day-level rows shown weekly or monthly are now summed per series `valueField`. The first row's other fields are kept. `merge: "last"` restores the old behaviour.
+- **Changing `dateGap` now refetches.** Before, `useWidgetData` kept rows normalised with the previous `dateGap`.
+
+### Added
+- **Calendar-period grouping.** `groupBy(f, title, { interval, timeZone })` groups by `"day" | "week" | "month" | "quarter" | "year"` using an ES composite `date_histogram` source. Keys are epoch ms at the start of each period.
+- **More `dateGap` units.** `DateGapUnit` adds `"quarter"` and `"year"`. Weeks now start on Monday (ISO), consistent with ES `1w`.
+- **Running totals.** `dateGap.cumulative` (`true` or a list of fields) with a `baseline` value, or with `baselineSource` to have the hook fetch the baseline in one extra request. New pure helper: `applyCumulative`.
+- **Time between two dates.** `dateDiff(start, end | "TODAY", unit)` for `aggregate(..., "avg" | "min" | "max" | "sum" | "percentiles")`. It uses a painless script metric, and documents missing either date are excluded.
+- **Percentiles.** `"percentiles"` is now an `AggregationType`, with `{ percents }`. Rows get `<name>_p50`-style keys (`flattenPercentiles`, `percentileKey`).
+- **Several conditions per metric.** `aggregate(f, type, name, { where: [[field, where(...)], ...] })` filters one metric by AND-ed conditions. All filtered metrics still run in one request. `PivotFilter.combine: "AND"` opts stored configs into AND-ing.
+- **Self-fetching KPI sparklines.** `KpiContentConfig.seriesSource = { mode: "timeseries", dataSource, xField, valueField, dateGap }` makes `KpiWidget` fetch the sparkline itself. A new `externalSeriesByIndex` prop is also accepted.
+- **New exports:**
+  - functions: `dateDiff`, `startOfPeriod`, `addPeriod`
+  - types: `DateGapOptions`, `DateInterval`, `DateDiffUnit`, `DateDiffSpec`, `DateDiffField`, `AggregateOptions`, `KpiTimeseriesSource`, `FillDateGapsArgs`
+- **New tests:** `test/compat.mjs`, `test/timeseries.mjs`, `test/datediff.mjs`, `test/summaryFilters.mjs`.
+
+### Fixed during review
+- **Time zones.** `dateGap` now computes periods in the `groupBy(..., { timeZone })` zone, or in `dateGap.timeZone`. Before, it used the browser's zone, so ES buckets landed in the wrong period whenever the two zones differed. `startOfPeriod` and `addPeriod` take an optional zone, and there is a new `parseDateValue` helper.
+- **Running totals without `end`.** `cumulative` now drops rows before `start` even when `end` is missing. Before, they were counted twice: once in the rows and once in the baseline.
+- **Sort order.** AND-filtered metrics keep the summary `bucket_sort`.
+- **KPI sparklines.** A self-fetched sparkline is cleared when its item loses `seriesSource.dataSource` or the items are reordered.
+- **`dateDiff` end values.** `end` now accepts any date token and literal dates (`"2026-03-31"`, ISO date-times). An unknown `{@[…]}` token logs a warning instead of silently being queried as a field.
+
+### Changed
+- **Week periods in `fillDateGaps` start on Monday** instead of following the dayjs locale, which defaulted to Sunday.
+- **Version bumped to 0.0.2.** `package.json` said `0.0.0`.

package/MIRROR_NOTES.md

@@ -0,0 +1,146 @@
+# Mirror notes: what ZAI-Dashboard and the server must copy
+
+`src/runtime/queryGenerator.ts` is a verbatim port of ZAI-Dashboard
+`src/utils/queryGenerator.ts`. Every change in this repo is in a block marked
+`// [zvolv-widgets extension]`. Search for that marker to find each one.
+
+**Compatibility guarantee.** For every config shape that existed before 0.0.2,
+the generated query is byte-identical. `test/compat.mjs` checks 12 such shapes
+against snapshots captured from the old code.
+
+**The one intended exception (item 1).** A pivot entry whose `title` differs
+from its `masterField` now queries `masterField`. Before, it queried a field
+named after the title, which normally does not exist. Saved ZAI-Dashboard
+configs observed so far have `title === masterField`. Before rolling out,
+check task widgets that might have stored `title: "Status"` with
+`masterField: "status"`.
+
+---
+
+## A. ZAI-Dashboard `queryGenerator.ts`: changes to copy
+
+### A1. ES field comes from `masterField`, not `title` (bug fix)
+
+In each function below, `title` stays the aggregation or source **name**, which
+is the output key. Only the **field** changes.
+
+| Function | Before | After |
+| --- | --- | --- |
+| `getCompositeAggregations` | `terms.field` built from `row.title` in all four branches: `resolveFormSearchViewField(row.title)`, `` `${row.title}.mediaKey.keyword` ``, `` `${row.title}.keyword` ``, `row.title` | the same, built from `esField = row.masterField \|\| row.title` |
+| `getCompositeAggregations` | `terms: scriptFields[row.title]` | unchanged (script fields are keyed by header) |
+| `getColumnAggregations` | `terms: { field: col.title }` | `terms: { field: col.masterField \|\| col.title }` |
+| `getSummaryAggregations` | `aggField = sumary.title` (and `.keyword`, `.mediaKey.keyword`, `resolveFormSearchViewField(...)` variants) | the same, built from `esField = sumary.masterField \|\| sumary.title` |
+| `getSummaryAggregations` | `usesRawField = aggField === sumary.title`, `addBucketSort(sumary.title)` | `usesRawField = aggField === esField`, `addBucketSort(esField)` |
+
+### A2. `date_histogram` grouping (`PivotRow.interval`)
+
+In `getCompositeAggregations`, before the existing `FORM_SEARCH` / `FILE_UPLOAD_V2` /
+`.keyword` / raw branches:
+
+```ts
+if (row.interval && (dateTypes.includes(mfType) || isTaskDateField)) {
+  sourceObj[row.title] = { date_histogram: {
+    field: esField,
+    calendar_interval: { day: '1d', week: '1w', month: '1M', quarter: '1q', year: '1y' }[row.interval],
+    time_zone: row.timeZone || timezone,          // module-level Intl zone
+    ...(sortOrder ? { order: sortOrder } : {}),
+  } };
+}
+```
+
+- A task date field is one in `taskDate`, where the row or its field metadata has `isTaskField` or `taskfield` set.
+- When `interval` is set on a non-date field, the generator calls `console.warn` and falls back to the existing branches.
+- Helpers: `getDateHistogramSource`, `HISTOGRAM_INTERVALS`.
+
+### A3. Per-summary extensions: `dateDiff`, `percentiles`, AND-ed filters
+
+**New module state.** `summaryFilterLists: Map<string, any[]>`, which is
+`pivot.filters` grouped by `field` with every entry kept. The original
+`filterMap` keeps only the last entry per field.
+- `generateQuery` resets it next to `currentMappings`.
+- `generateQuery` fills it with `groupPivotFilters(dataSource.pivot.filters)` right after building `filterMap2`.
+
+**Hook.** At the top of the `pivotBody.summary.forEach` loop in
+`getSummaryAggregations`, after `aggDataPoints.summary.push`, add:
+
+```ts
+if (buildExtendedSummary(sumary, summaryAggs, loggedInUser)) return;
+```
+
+`buildExtendedSummary` returns `false` and changes nothing unless one of these holds:
+
+1. **`sumary.dateDiff = { start, end, unit }` is set.** The metric becomes `{ [type]: { script } }`, where `script` is:
+   - with two date fields: `{ source: "if(doc['S'].size()==0 || doc['E'].size()==0) { return null; } return (doc['E'].value.millis - doc['S'].value.millis) / <div>;", lang: 'painless' }`
+   - with a fixed `end`: `{ source: "if(doc['S'].size()==0) { return null; } return (params.now - doc['S'].value.millis) / <div>;", lang: 'painless', params: { now } }`. `end` is fixed when it is either:
+     - a `dateFormulas` token: `now = dayjs(getDate(end)).valueOf()`
+     - a literal date matching `/^\d{4}-\d{2}-\d{2}([T ][\d:.]+(Z|±hh:mm)?)?$/`: `now = dayjs(end).valueOf()`, where a date-only value means local midnight
+   - Any other `end` is a field name. An unknown `{@[…]}` token logs a `console.warn`.
+   - `<div>` is `86400000.0` for days, `3600000.0` for hours, `60000.0` for minutes.
+   - It is always wrapped in a filter: `must` gets `{ exists: { field: S } }`, plus `{ exists: { field: E } }` unless `end` is fixed.
+2. **`sumary.type === 'percentiles'` and `sumary.percents` is set.** The metric gets `percents` (`{ percentiles: { field | script, percents } }`).
+3. **The summary has two or more `pivot.filters` entries, at least one with `combine: 'AND'`.** Every entry is AND-ed:
+   - Each entry is converted with the original `getFilters(fb, 'PIVOT')` call and the same `fb` shape as the original branch.
+   - Operators in `mustNotOp` go into `bool.must_not`; all others go into `bool.must`.
+   - `_ALL` and `MULTIPLE` are skipped, because they only make sense as global filters.
+
+The output nesting is the same as the original per-summary filter branch:
+
+```json
+"<name>": { "filter": { "bool": { "must": [...], "must_not": [...] } }, "aggs": { "<name>": { "<type>": { ... } } } }
+```
+
+or the bare `"<name>": { "<type>": { ... } }` when there are no conditions. A
+summary-only query with a filtered summary therefore still takes the existing
+`dummy_row` composite path. Field resolution for plain-field percentiles and
+AND-filtered metrics (`.keyword`, `FORM_SEARCH` `.view`, `FILE_UPLOAD_V2`
+`.mediaKey.keyword`, text → `value_count`) copies the original loop.
+
+**Sort.** AND-filtered single-value metrics on a raw field get the same
+`<name>_sort` `bucket_sort` as the original `addBucketSort`, so
+`buildExtendedSummary` receives `sortKeys`. Percentiles and `dateDiff` metrics
+get no sort, because they have no single-value field to sort on.
+
+Helpers: `buildExtendedSummary`, `finish`, `getDateDiffScript`, `getDateDiffFixedEnd`,
+`getSummaryFilterClause`, `groupPivotFilters`, `DATE_DIFF_DIVISOR`.
+
+### A4. Optional: `fillDateGaps`, if the host has its own copy
+
+If the host has its own `fillDateGaps`, mirror these changes from `src/transforms/dateGaps.ts`:
+- Rows in the same period are summed, not overwritten.
+- Weeks start on Monday (ISO), which matches ES `1w`.
+- `quarter` and `year` units are supported.
+- Periods are keyed by their start instant.
+- An optional `timeZone` computes periods on that zone's calendar. It must match the `date_histogram` `time_zone`; otherwise bucket keys land in the previous or next period.
+
+---
+
+## B. Server: aggregation response flattener
+
+This repo cannot see the flattener that turns ES `aggregations` into
+`elements` rows, driven by `aggsDataPoints.rows` / `cols` / `summary`. Each
+item below is what the client expects. Verify each one against a live index.
+
+| # | ES response shape | What the client expects in each row | Likely server change |
+| --- | --- | --- | --- |
+| B1 | `date_histogram` composite source: `bucket.key = { "Month": 1767205800000 }` (epoch ms, a number) | `row["Month"] = 1767205800000` | **Probably none.** Composite `terms` keys on date fields are already epoch-ms numbers. Confirm the flattener copies `bucket.key[row]` without assuming the source is `terms`. |
+| B2 | Filter-wrapped script metric: `bucket["Avg Days"] = { doc_count, "Avg Days": { value: 4.5 } }` | `row["Avg Days"] = 4.5` | **None** if filtered summaries already work: the nesting is identical. A bucket where no document has both dates returns `value: null`. Keep that as `null`; the client coerces it to 0 for charts. |
+| B3 | `percentiles`: `{ values: { "50.0": 3, "95.0": 9 } }`, either at the top level (summary only) or under the filter wrapper | Either `row["Days"] = { values: {...} }` or `{ "50.0": 3, ... }`, or flat `row["Days_p50"]` / `row["Days_p95"]` | **Likely needed.** If the flattener reads only `.value`, percentiles come back `undefined`. Pass the `values` object through, or emit `<name>_p<percent>` keys (`99.9` → `_p99_9`). The client accepts all three shapes. |
+| B4 | Summary-only `dateDiff` metric under `dummy_row` | `row["Avg Days to Offer"]` | None. Same path as existing filtered KPI summaries. |
+| B5 | Script metrics in general | n/a | `doc[...].value.millis` is the idiom `getFormula`'s DAYS_DIFF already uses, so it works on the current cluster. On ES 8+ it would need `.toInstant().toEpochMilli()`. |
+
+---
+
+## C. Not query-generator changes, for reference
+
+- **`useWidgetData`:**
+  - New `dateGap.merge`, `cumulative`, `baseline` and `baselineSource` options. `baselineSource` makes one extra request with `dateField < start` and no dashboard date range.
+  - Percentile-row flattening.
+  - `dateGap` content changes now trigger a refetch. Before, the effect ignored them and showed stale rows.
+- **`KpiWidget`:**
+  - Self-fetches `seriesSource: { mode: "timeseries", dataSource, ... }`, with one request per content item.
+  - New `externalSeriesByIndex` prop.
+- **`dataSource.ts`:**
+  - `groupBy(f, title, { interval, timeZone })`.
+  - `dateDiff()`.
+  - `aggregate(f, type, name, { percents, where })`.
+  - `pivot()`, `formSource()` and `taskSource()` move `where` conditions into `pivot.filters` with `combine: "AND"`.

package/README.md

@@ -343,7 +343,7 @@ 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";
+import { formSource, taskSource, field, taskField, groupBy, aggregate, dateDiff, derive, where, pivot } from "@zestl/zvolv-widgets";
 
 const region  = field("Region",  "DROP_DOWN");
 const revenue = field("Revenue", "INPUT_CURRENCY");
@@ -394,6 +394,157 @@ field("Created", "INPUT_DATE", { filter: where("DATE_IS", "{@[TODAY]}") })
 defaultWidgetFilters={[{ field: "Status", operator: "IN", value: ["Open"] }]}
 ```
 
+### Output names vs field names
+
+`groupBy(f, title)` and `aggregate(f, type, outputName)` take an output name,
+which is the key the rows come back under. The query always groups and
+aggregates on the field's `masterfield`. So `groupBy(requestDate, "day")`
+queries `Request Date` and returns rows keyed `day`. (Before 0.0.2, the title
+was used as the field name, so an alias returned no buckets.)
+
+### Grouping by calendar period
+
+Pass `interval` to group a date field by calendar period
+(`date_histogram` in Elasticsearch) instead of by exact value:
+
+```tsx
+const requestDate = field("Request Date", "DATE_PICKER");
+const requests    = field("Request ID", "INPUT_TEXT");
+
+const monthly = formSource(1042, [requestDate, requests], {
+  pivot: pivot({
+    rows:    [groupBy(requestDate, "Month", { interval: "month" })], // day | week | month | quarter | year
+    summary: [aggregate(requests, "value_count", "Requests")],
+  }),
+});
+
+<LineChartWidget
+  dataSource={monthly}
+  configurations={{ series: [{ argumentField: "Month", valueField: "Requests" }] }}
+  dateGap={{ unit: "month", start: "2026-01-01", end: "2026-12-31" }}
+/>
+```
+
+- Row keys are epoch ms at the start of each period.
+- Weeks start on Monday (ISO).
+- Period boundaries use the browser's time zone. Pass `{ interval, timeZone: "Asia/Kolkata" }` to fix one. `dateGap` then fills and merges periods in that same zone.
+- `interval` on a non-date field is ignored, with a console warning.
+
+`dateGap` fills empty periods with zero rows. Rows that fall in the same
+period are **summed** (`merge: "sum"`, the default), so day-level data shown
+weekly or monthly no longer loses rows. `merge: "last"` restores the old
+keep-the-last-row behaviour.
+
+### Running totals (level over time)
+
+```tsx
+<LineChartWidget
+  dataSource={monthly}
+  configurations={{ series: [{ argumentField: "Month", valueField: "Requests" }] }}
+  dateGap={{
+    unit: "month", start: "2026-01-01", end: "2026-12-31",
+    cumulative: true,                 // or ["Requests"]
+    baseline: { Requests: 1250 },     // the total before `start`
+  }}
+/>
+```
+
+`cumulative` runs after gap filling, so each point is the level at the end of
+its period. Rows before `start` are dropped even when there is no `end`,
+because the baseline already counts them. You can let the hook fetch the baseline instead. This costs one
+extra request:
+
+```tsx
+dateGap={{
+  unit: "month", start: "2026-01-01", end: "2026-12-31", cumulative: true,
+  baselineSource: {
+    dataSource: formSource(1042, [requestDate, requests], {
+      pivot: pivot({ summary: [aggregate(requests, "value_count", "Requests")] }), // same output name
+    }),
+    dateField: "Request Date",   // the hook adds Request Date < 2026-01-01
+  },
+}}
+```
+
+The baseline query applies the widget's dashboard and widget filters, but not
+the dashboard date range, because that range would exclude everything before
+`start`. An explicit `baseline` wins over the fetched value, field by field.
+
+### KPI sparklines without custom code
+
+A KPI item can fetch its own sparkline:
+
+```tsx
+<KpiWidget
+  dataSource={formSource(1042, [requests], { pivot: pivot({ summary: [aggregate(requests, "value_count", "Total")] }) })}
+  configurations={{ contents: [{
+    title: "Requests", dataPoint: "Total", template: "trend",
+    seriesSource: {
+      mode: "timeseries",
+      dataSource: monthly,            // grouped by a date row with `interval`
+      xField: "Month", valueField: "Requests",
+      dateGap: { unit: "month", start: "2026-01-01", end: "2026-06-30", cumulative: true },
+    },
+  }] }}
+/>
+```
+
+Each such item makes one request through `useWidgetData`, with the widget's
+dashboard filters applied. `externalSeriesByIndex={{ 0: [..] }}` still works
+and takes precedence.
+
+### Time between two dates (avg / min / max / sum / percentiles)
+
+```tsx
+const offerDate = field("Actual Offer Date", "DATE_PICKER");
+const partner   = field("Lead Partner", "DROP_DOWN");
+
+// Overall: one number
+formSource(1042, [requestDate, offerDate], { pivot: pivot({
+  summary: [aggregate(dateDiff(requestDate, offerDate, "days"), "avg", "Avg Days to Offer")],
+}) });
+
+// Per partner, or per month with groupBy(requestDate, "Month", { interval: "month" })
+formSource(1042, [requestDate, offerDate, partner], { pivot: pivot({
+  rows:    [groupBy(partner)],
+  summary: [
+    aggregate(dateDiff(requestDate, offerDate), "avg", "Avg Days to Offer"),
+    aggregate(dateDiff(requestDate, offerDate), "percentiles", "Days", { percents: [50, 90] }),
+    aggregate(dateDiff(requestDate, "TODAY"), "max", "Oldest Open (days)"),
+  ],
+}) });
+```
+
+- The value is `end − start`. The unit is `"days"`, `"hours"` or `"minutes"`, and the result is fractional.
+- Documents missing either date are skipped.
+- `end` can be a fixed end instead of a field: `"TODAY"`, a date token such as `{@[30DAYSAGO]}`, or a literal date (`"2026-03-31"` means local midnight; an ISO date-time is also accepted). Only the start date is then required. Any other string is treated as a field name, and an unknown `{@[…]}` token logs a warning.
+- Percentiles come back as `<name>_p50`, `<name>_p90` (`99.9` becomes `_p99_9`). `<name>` itself holds the median when 50 was requested.
+
+### Filtered metrics: many KPIs, one request
+
+```tsx
+const amount = field("Amount", "INPUT_CURRENCY");
+const status = field("Status", "DROP_DOWN");
+const invoiceDate = field("Invoice Date", "DATE_PICKER");
+
+formSource(1042, [amount, status, invoiceDate], { pivot: pivot({
+  summary: [
+    aggregate(amount, "sum", "Billed", { where: [
+      [status, where("IN", "Invoiced", "Paid")],
+      [invoiceDate, where("BETWEEN", "2026-04-01", "2026-06-30")],  // AND-ed
+    ] }),
+    aggregate(amount, "sum", "Pipeline", { where: [[status, where("IN", "Quoted")]] }),
+    aggregate(amount, "sum", "Total"),
+  ],
+}) });
+```
+
+Each metric is filtered on its own, and all of them run in **one** request. A
+KPI card with 20 numbers on one form is one call. `pivot()`, `formSource()` and
+`taskSource()` move the `where` conditions into `pivot.filters`, marked
+`combine: "AND"`. Stored `pivot.filters` entries without that marker keep the
+original rule: the last entry per metric wins.
+
 ---
 
 ## 5. Controlling the UI
@@ -650,6 +801,7 @@ writes widget code. Without it, Claude tends to write its own data fetching.
 - **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`.
+- **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`.
 
 ---
@@ -709,6 +861,8 @@ precision, prefix, suffix, accept, maxSizeKB, maxCount, childIds, pages, html, s
 | `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)` |
+| `trials` | INPUT_PERCENT_CORRECT, INPUT_TIME_SAMPLING, INPUT_TASK_ANALYSIS (ABA trial widgets) | `useTrialField` (response / prompt buttons, trials, timer, steps, % correct, log) |
+| `onbehalf` | ON_BEHALF_OF | read-only; `field.displayText` is the user's name |
 | `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
@@ -719,19 +873,39 @@ value, clears the selection when the source changes, and auto-selects when exact
 (rule on a non-lookup driver, `elementId` = the lookup) is still read. `cascade(source, target, masterField)` writes
 the platform shape.
 
+**Type coverage.** Every element type ZAI-Dashboard's FormFieldRouter and zvolv-web's z-form-widgets render has a kind. Aliases: `SCAN` → `INPUT_SCAN`, `HTML_TEXT` → `TEXT_VIEW`, `TRIGGER_AUTOMATION` → an action button, `ACTION_DROPDOWN` → an action with `field.variant === "dropdown"` whose `field.options` are its actions (`form.runAction(field, label)` runs only the picked one, as in zvolv-web). `INPUT_CARD_CONTAINER` is commented out in zvolv-web and is not supported. Like zvolv-web, any `attributes.subType` that is a known type replaces `type` — so an element saved as `INPUT_SHORT_TEXT` with subType `INPUT_PERCENT_CORRECT` (and `dataType: "OBJECT"`) is a trial widget. `DOWNLOAD_FILE` / `PRINT_PREVIEW` fall back to `properties.url` when the button has no value.
+
+**Trial widgets** (`useTrialField(form, field)`): the configuration comes from the stored value's `conf` (ZAI) over `element.properties` (zvolv-web): `ResponseButtons` (with `PromptButtons`), `maximumNumberOfTrials`, `minimumNumberOfTrials`, `LinkedTimerField`, `timeLimit` / `timeInterval`, `steps` and `type` (forward / backward / whole). Values match ZAI: `{ conf, buttonResp, lastStatus? , currentStatus? }`. `minimumNumberOfTrials` is checked on submit for percent correct and time sampling.
+
 **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 }`.
+- **Signed-in user is decrypted** like ZAI-Dashboard `getStoredUser()`: the host's `readUser`, else the SDK's `readUserFromStorage()`, else `client.auth.userInstance` through `decryptAuthObject`. Values still `enc::…` are dropped, and forms re-read the user on the SDK's `zvAuthCryptReady` event. Pass `createZvolvRuntime({ client, readUser: readUserFromStorage })` to be explicit.
 - **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`.
+- **Action buttons** (`form.runAction`) handle every actionType ZAI-Dashboard and zvolv-web do. `actionType` = `properties.actionType` ?? `attributes.subType` ?? `properties.subType` ?? `OPEN_URL`.
+
+  | actionType | What runs |
+  | --- | --- |
+  | `OPEN_URL` / `URL` | opens `properties.url`, the button's value, or `defaultValue` |
+  | `TRIGGER_AUTOMATION` | `invokeTriggers(triggerID)`; `automationType: "ZENO"` uses `invokeNuclioAutomation(automationUuid)`. `formData` is written back; `code` 400/500 or `error` is a failure; `refreshForm` / `refreshFormDelay` reloads a saved record |
+  | `INVOKE_AGENT` | `invokeAgent({ content: { query } }, flowId, agentId)` with a label-keyed body; the reply's `formData` is written back |
+  | `DOWNLOAD_FILE` | downloads the button's value (a URL), `properties.fileName` |
+  | `PRINT_PREVIEW` | loads the PDF at the button's value and opens the print dialog |
+  | `UPLOAD_FILE` | file picker → upload (card upload when `cardID` is set) → stores the file URL in the button |
+  | `UPDATE`, `UPDATE_SUBMISSION`, `UPDATE_OPEN_NEW_FORM`, `EDIT_OPEN_NEW_FORM`, unknown | sets the button `true`, then saves |
+  | `SUBMIT` | saves the form |
+  | `CREATE_SUBMISSION`, `EDIT_SUBMISSION`, `SAVE_SUBMISSION`, `OPEN_TASK`, `OPEN_PROJECT` | open other screens: handle in `onAction`; `openFormRequest(field, form)` gives `{ formId, submissionId, mode, defaultValues (inputMap) }` |
+  | `CASCADED_ACTIONS` | runs `actionEleIds` in order, stops at the first failure, then saves when `submit` is true |
+
+  `successMessage`, `errorMessage` and `hideSuccessMessage` shape the returned message; `form.reload()` re-fetches the record.
 
 **Show / hide / mandatory rules (triage).** These match ZAI-Dashboard's `applyDependencies`:
 
@@ -745,6 +919,24 @@ the platform shape.
 `formData` back into the form). Pass `onAction` to `<ZvolvForm>` for host actions such as
 "open another form".
 
+### Inspector (validation, rules, filters, formulas, payload)
+
+`useFormInspector(form)` (or the pure `inspectForm(form)`) explains what the engine is doing for the current values. Every verdict comes from the same functions the form uses, so a host can draw an inspector panel without re-implementing anything:
+
+| Key | What it holds |
+| --- | --- |
+| `rules` | each dependency / triage rule: source value, expected value, effect (show / hide / required / optional / editable / read-only), target, `matched` |
+| `filters` | each lookup filter (FETCH_OPTIONS_FILTERS, DynamicFilters, StaticFilters) with the feeding value and `active` |
+| `validation` | each input field and sheet cell: checks, current `error` from `validateField`, the error shown to the user |
+| `formulas` | each form and sheet-row formula: inputs, `expected`, `current`, `inSync`, `serverSafe`, `serverFormula` |
+| `defaults` | dynamic and fixed defaults and the value they produced |
+| `payload` | the exact submission body — sheet rows (posted first) and the parent |
+| `summary` | counts for tiles |
+
+**Formulas must use `{Label}` references.** The submission API re-evaluates every INPUT_FORMULA and rejects a mismatch (`Evaluated value "0" and existing value "8000" … do not match`). It resolves only `{Label}`; bare labels (`MUL(Qty, Price)`) evaluate to 0 on the server even though the library computes them. `isServerSafeFormula(formula, labels)` detects this and `toBraceFormula` gives the fix; the inspector flags it per formula.
+
+Sheet row formulas are recalculated by `useSheetField().updateRow` / `addRow` (`computeRowFormulas`), and again before rows are posted.
+
 ### Headless
 
 `useZvolvForm({ formId, mode, submissionId, defaultValues, hiddenFields, skipTypes, onSubmitted })`

package/SKILL.md

@@ -127,7 +127,7 @@ Stored table columns are `{ label, dataPoint, type }` and are read as-is.
 ## Authoring a data source
 
 ```tsx
-import { formSource, taskSource, field, taskField, groupBy, aggregate, derive, where, pivot } from "@zestl/zvolv-widgets";
+import { formSource, taskSource, field, taskField, groupBy, aggregate, dateDiff, derive, where, pivot } from "@zestl/zvolv-widgets";
 
 const region  = field("Region",  "DROP_DOWN");       // use the REAL element type
 const revenue = field("Revenue", "INPUT_CURRENCY");
@@ -147,6 +147,21 @@ field("Status", "DROP_DOWN", { filter: where("IN", "Open") });  // baked-in auth
 
 Element type → ES type: `INPUT_NUMBER`/`INPUT_CURRENCY`/`INPUT_PERCENT` → FLOAT · `FORM_SEARCH`/`INPUT_TAG` → ARRAY · `CHECK_BOX` → BOOLEAN · else STRING.
 
+Time series, date differences and filtered metrics (0.0.2). Never post-process rows for these:
+
+```tsx
+groupBy(requestDate, "Month", { interval: "month" })      // date_histogram; day|week(Mon)|month|quarter|year; keys = epoch ms
+aggregate(dateDiff(requestDate, offerDate, "days"), "avg", "Avg Days")   // end − start; docs missing a date skipped
+aggregate(dateDiff(requestDate, "TODAY"), "max", "Age")
+aggregate(dateDiff(a, b), "percentiles", "Days", { percents: [50, 90] }) // rows get Days_p50, Days_p90
+aggregate(amount, "sum", "Billed", { where: [[status, where("IN", "Paid")], [date, where("BETWEEN", from, to)]] }) // AND-ed; many metrics = 1 request
+```
+
+- `title` / `outputName` only name the output key. The query uses the field's `masterfield`.
+- `dateGap={{ unit, start, end }}` sums rows in the same period (`merge: "last"` gives the old behaviour).
+- Add `cumulative: true | [fields]` with `baseline: { field: n }`, or `baselineSource: { dataSource, dateField }`, for running totals.
+- KPI sparkline: `contents[i].seriesSource = { mode: "timeseries", dataSource, xField, valueField, dateGap }`. The widget fetches it.
+
 ## Writing configuration
 
 ```tsx
@@ -222,7 +237,10 @@ Forms work like widgets: Zvolv owns the behaviour and you own the look.
 
 - Render with `<ZvolvForm formId … />`, or let a `FORM` / `FORM_WIDGET` dashboard widget do it.
 - Style every field once with `<FormKitSlot.Provider value={{ field, form, status, grid }}>`. Switch on `field.kind`, and use `useFieldOptions`, `useFileField`, `useSheetField` and `form.runAction` for behaviour. Never re-implement rules, formulas, lookups or the submit body.
+- Sheet row formulas: call `useSheetField().updateRow` — it recalculates formula cells. For a debug/inspector panel use `useFormInspector(form)` (rules, filters, validation, formulas, defaults, payload).
+- Write formulas with `{Label}` references (`MUL({Qty}, {Price})`). The submission API re-evaluates formulas and reads bare labels as 0, so `MUL(Qty, Price)` is rejected with "Evaluated value \"0\" … do not match". Check with `isServerSafeFormula`.
 - Nested layout: for `section`, `tabs` and `steps` kinds, render `<FormFields form={form} fields={form.childrenOf(field)} />`.
+- Kind `"trials"` (ABA widgets) → draw with `useTrialField`; action `variant === "dropdown"` (ACTION_DROPDOWN) → a select of `field.options`, call `form.runAction(field, label)`.
 - Lookup / people controls must call `o.onFocus()` on focus — options load on focus (zvolv-web / ZAI parity). Single vs multi is `maxResults`; respect `o.atLimit`; INPUT_TAG free text via `o.addFreeTag`. ExtraLabels auto-fill is opt-in (`autofillExtraLabels`); prefer FETCH_OPTIONS_FILTERS. Draw kind `"onbehalf"` read-only with `field.displayText`; checkbox `variant === "switch"`; sheets honour `canAdd` / `canDelete` / `limitMessage`. SAVE_SUBMISSION and other open-UI actions need `onAction`.
 - Triage / show-hide-mandatory rules follow ZAI-Dashboard: `properties.triage` overrides `dependencies`; array values must match the selection exactly; a matching rule beats a non-matching one; hiding keeps the value; `field.error` appears only after submit and clears when the field changes. Don't add reset-on-hide or live "touched" errors in the app.
 - Dependent lookups (`FETCH_OPTIONS_FILTERS`) use the platform shape: the rule sits **on the dependent lookup** — `{ type: "FETCH_OPTIONS_FILTERS", elementId: <source field>, masterField: <label on its source form> }`. `useFieldOptions` filters by the source's value, reports `waitingFor` until it is set, clears the selection when it changes, and auto-selects when exactly one row matches. Build it with `cascade(source, target, masterField)`.