@zestl/zvolv-widgets 0.0.1 → 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`.
 
 ---

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