@zestl/zvolv-widgets 0.0.1 → 0.0.3

package/dist/index.d.ts

@@ -235,6 +235,8 @@ declare function useTokens(): ZvolvTokens;
 
 type KpiTemplateId = "standard" | "trend" | "comparison" | "progress" | "financial" | "status" | "chart" | "hero_chart" | "icon";
 type BadgeTone = "success" | "warning" | "error" | "info" | "neutral";
+/** Where a content item goes in a card-level KPI layout (`config.layout: "card"`). */
+type KpiRole = "main" | "sub" | "chip" | "series";
 /**
  * View-model for a single resolved KPI item.
  *
@@ -273,9 +275,34 @@ interface KpiContentVM {
         description?: string;
     };
     series?: number[];
+    /** From `KpiContentConfig.role`; set only when configured. */
+    role?: KpiRole;
     raw: any;
     config: any;
 }
+/** Content items sorted into card slots. */
+interface KpiCardRoles {
+    /** role "main", else the first item without a role, else the first item. */
+    main: KpiContentVM | null;
+    /** role "sub": small values under the main one. */
+    subs: KpiContentVM[];
+    /** role "chip": its `delta` is the change badge. */
+    chip: KpiContentVM | null;
+    /** Sparkline data: the role "series" item's series, else main's. */
+    series: number[] | undefined;
+}
+/** Args for `KpiWidget` `render` and the `"KPI_CARD:card"` template. */
+interface KpiCardRenderArgs {
+    /** Every resolved item, in config order. */
+    vms: KpiContentVM[];
+    /** Items by `dataPoint` (the first item wins when two share one). */
+    byKey: Record<string, KpiContentVM>;
+    roles: KpiCardRoles;
+    state: "loading" | "ready" | "empty" | "unconfigured" | "error";
+    tokens: any;
+    config: any;
+    onItemClick?: (vm: KpiContentVM, index: number) => void;
+}
 /** Props every KPI template component receives. */
 interface KpiTemplateProps {
     vm: KpiContentVM;
@@ -307,11 +334,23 @@ declare const Value: React.FC<{
 declare const Delta: React.FC<{
     vm: KpiTemplateProps["vm"];
 }>;
-declare const Sparkline: React.FC<{
+interface KpiSparklineProps {
     series: number[];
     color: string;
+    /** CSS width. Default "100%". */
+    width?: number | string;
+    /** Height in px. Default 40. */
     height?: number;
-}>;
+    /** Fill the area under the line. */
+    area?: boolean;
+    /** "minmax" (default) fits the data; "zero" keeps 0 on the axis. */
+    scale?: "minmax" | "zero";
+}
+declare const Sparkline: React.FC<KpiSparklineProps>;
+/** Sorts card items into slots by `role`. Pure. */
+declare function resolveKpiRoles(vms: KpiContentVM[]): KpiCardRoles;
+/** Default `"KPI_CARD:card"` template: one card, items placed by `role`. */
+declare const Card: React.FC<KpiCardRenderArgs>;
 declare const KPI_DEFAULT_TEMPLATES: {
     standard: React.FC<KpiTemplateProps>;
     trend: React.FC<KpiTemplateProps>;
@@ -458,7 +497,21 @@ declare const WidgetShell: React.FC<WidgetShellProps>;
 
 /** Heuristic: a plain number in the ~2000–2100 ms-epoch band is a timestamp, not a value. */
 declare function isLikelyTimestamp(v: any): boolean;
-type DateGapUnit = "day" | "week" | "month";
+type DateGapUnit = "day" | "week" | "month" | "quarter" | "year";
+/**
+ * Start of the period containing `d`. Weeks start on Monday (ISO), matching
+ * Elasticsearch's `1w` calendar_interval; quarters start Jan/Apr/Jul/Oct.
+ * Periods are in the browser's zone unless `timeZone` (IANA) is given.
+ */
+declare function startOfPeriod(d: dayjs.Dayjs, unit: DateGapUnit, timeZone?: string): dayjs.Dayjs;
+/** The period after `d` (which must already be a period start). */
+declare function addPeriod(d: dayjs.Dayjs, unit: DateGapUnit, timeZone?: string): dayjs.Dayjs;
+/**
+ * Parses an x-value. Epoch ms and strings with an explicit offset are instants;
+ * other strings ("2026-01-05", "2026-01-05 10:00") are wall time in `timeZone`
+ * when given, else in the browser's zone.
+ */
+declare function parseDateValue(v: any, timeZone?: string): dayjs.Dayjs;
 interface FillDateGapsArgs {
     rows: any[];
     xKey: string;
@@ -470,18 +523,92 @@ interface FillDateGapsArgs {
         start: dayjs.Dayjs;
         end: dayjs.Dayjs;
     } | null;
+    /**
+     * How rows falling in the same period combine. "sum" (default) adds each
+     * series valueField and keeps the first row's other fields (x included).
+     * "last" keeps only the last row per period — the pre-0.0.2 behaviour, which
+     * drops data when day-level rows are shown weekly or monthly.
+     */
+    merge?: "sum" | "last";
+    /**
+     * x-value format for inserted zero rows when it cannot be inferred from the
+     * data (e.g. empty input). Default: "date" ("YYYY-MM-DD"), or "timestamp"
+     * when the first row's x is epoch ms.
+     */
+    xFormat?: "timestamp" | "date";
+    /**
+     * IANA zone periods are computed in. Must match the ES `time_zone` the rows
+     * were bucketed in (`groupBy(..., { timeZone })`). Default: browser zone.
+     */
+    timeZone?: string;
 }
 /**
  * Inserts zero rows for periods with no data so a time axis reads continuously.
  *
- * Keying by each period's start date (rather than a week/month number) avoids
- * needing dayjs's weekOfYear plugin and stays unambiguous across year boundaries.
+ * Periods are keyed by their start instant, so keys stay unambiguous across
+ * year boundaries. A period's existing row keeps its own x-value and format
+ * (epoch ms stays epoch ms, strings stay strings); inserted zero rows use the
+ * period start in the same format.
+ */
+declare function fillDateGaps({ rows, xKey, series, unit, range, merge, xFormat, timeZone, }: FillDateGapsArgs): any[];
+/**
+ * Running totals ("level over time"): replaces each `fields` value with the sum
+ * of itself and every earlier row, starting from `baseline[field]` (the total
+ * before the first row). Rows are ordered by `xKey` date first; rows whose x is
+ * not a date keep their position at the end.
  */
-declare function fillDateGaps({ rows, xKey, series, unit, range }: FillDateGapsArgs): any[];
+declare function applyCumulative(rows: any[], xKey: string, fields: string[], baseline?: Record<string, number>): any[];
 declare function coerceSeriesNumbers(rows: any[], series: {
     valueField: string;
 }[]): any[];
 
+/**
+ * Row reshaping that runs client-side after the query: turning one wide row
+ * into one row per category (`unpivot`), and filling categories that returned
+ * no bucket (`categoryGap`). Neither changes what is queried.
+ */
+interface UnpivotOptions {
+    /** Columns of row 0 to turn into rows, in output order. */
+    columns: string[];
+    /** Output key for the column name. Default "label". */
+    labelField?: string;
+    /** Output key for the column value. Default "value". */
+    valueField?: string;
+    /**
+     * Extra columns to copy onto an output row: source column → output field.
+     * A source column belongs to the listed column its name starts with (the
+     * longest such match), so `{ "Contacted %": "step" }` sets `step` on the
+     * "Contacted" row. A source column matching no listed column is copied
+     * onto every output row.
+     */
+    extra?: Record<string, string>;
+}
+interface CategoryGapOptions {
+    /** Row key holding the category — normally the chart's argumentField. */
+    field: string;
+    /**
+     * Categories in display order, or "fromForm" to read the field's dropdown
+     * options from the form schema.
+     */
+    values: string[] | "fromForm";
+}
+/**
+ * Row 0's `columns` → one row per column, in the given order:
+ * `{ [labelField]: column, [valueField]: number }`. A missing column is 0.
+ * Other input rows are ignored (a multi-number source returns one row).
+ */
+declare function unpivotRows(rows: any[], options: UnpivotOptions): any[];
+/** The dropdown values of a form element, as stored (select value first). */
+declare function elementOptionValues(element: any): string[];
+/**
+ * One row per value of `field`, in `values` order. Categories with no row get
+ * `{ [field]: value }` plus 0 for every series valueField. Rows whose category
+ * is not listed are kept, in their original order, after the listed ones.
+ */
+declare function fillCategoryGaps(rows: any[], field: string, values: string[], series: {
+    valueField: string;
+}[]): any[];
+
 /**
  * DataSource authoring — how a widget says WHERE its data comes from.
  *
@@ -528,14 +655,35 @@ interface DataSourceField {
     filter?: FieldFilter;
     formula?: any[];
 }
+type DateInterval = "day" | "week" | "month" | "quarter" | "year";
 interface PivotRow {
     /** Output column name. Must match the series `argumentField`. */
     title: string;
+    /** The Elasticsearch field grouped on. */
     masterField: string;
     masterFieldType?: string;
     masterFieldDataType?: MasterFieldDataType;
+    /**
+     * Date fields only: bucket by calendar period (ES `date_histogram`) instead of
+     * by exact value. Weeks start on Monday (ISO). Row keys are epoch ms.
+     */
+    interval?: DateInterval;
+    /** IANA zone for `interval` bucket boundaries. Default: the browser's zone. */
+    timeZone?: string;
+}
+type AggregationType = "sum" | "avg" | "min" | "max" | "count" | "value_count" | "cardinality" | "percentiles";
+type DateDiffUnit = "days" | "hours" | "minutes";
+/** `end - start` between two date fields, as built by `dateDiff()`. */
+interface DateDiffSpec {
+    /** Start date masterfield. */
+    start: string;
+    /**
+     * End date masterfield; or a fixed end: a date token (`{@[TODAY]}`,
+     * `{@[7DAYSAGO]}`, …) or a literal date ("2026-03-31", ISO date-time).
+     */
+    end: string;
+    unit: DateDiffUnit;
 }
-type AggregationType = "sum" | "avg" | "min" | "max" | "count" | "value_count" | "cardinality";
 interface PivotSummary {
     title: string;
     masterField: string;
@@ -544,6 +692,15 @@ interface PivotSummary {
     /** Output name of the aggregated value. Must match the series `valueField`. */
     value: string;
     type: AggregationType;
+    /** Aggregate a date difference (script) instead of a stored field. */
+    dateDiff?: DateDiffSpec;
+    /** `percentiles` only: which percentiles. Rows get `<value>_p50`-style keys. */
+    percents?: number[];
+    /**
+     * Conditions from `aggregate(..., { where })`. `pivot()` / `formSource()` /
+     * `taskSource()` move them into `pivot.filters`; they are not read from here.
+     */
+    filters?: PivotFilter[];
 }
 interface PivotFilter {
     field: string;
@@ -553,6 +710,12 @@ interface PivotFilter {
     masterFieldDataType?: MasterFieldDataType;
     operator: FilterOperator;
     value: any[];
+    /**
+     * "AND": AND this condition with every other entry targeting the same
+     * `field` (summary). Without it, only the last entry per field applies —
+     * the original behaviour, kept for stored configs.
+     */
+    combine?: "AND";
 }
 type PostOperator = "ADD" | "SUB" | "MUL" | "DIV" | "PERCENT";
 interface PostOperation {
@@ -595,13 +758,49 @@ declare function field(header: string, masterFieldType: MasterFieldType | string
  * "Status" becomes masterfield "status" automatically.
  */
 declare function taskField(header: string, masterFieldType?: MasterFieldType | string, options?: Partial<DataSourceField>): DataSourceField;
-/** A group-by dimension. `title` is what a series' `argumentField` must match. */
-declare function groupBy(f: DataSourceField, title?: string): PivotRow;
+/**
+ * A group-by dimension. `title` is what a series' `argumentField` must match;
+ * the query groups on the field's masterfield.
+ *
+ * Pass `{ interval }` on a date field to bucket by calendar period:
+ * `groupBy(requestDate, "Month", { interval: "month" })`.
+ */
+declare function groupBy(f: DataSourceField, title?: string, options?: {
+    interval?: DateInterval;
+    timeZone?: string;
+}): PivotRow;
+/** A field-like spec for `aggregate()`: the time from `start` to `end`. */
+interface DateDiffField extends DataSourceField {
+    dateDiff: DateDiffSpec;
+}
+/**
+ * The time between two date fields, for `aggregate()` (avg / min / max / sum /
+ * percentiles). Documents missing either date are skipped.
+ *
+ * `end` is a date field, or a fixed end that only needs `start` to exist:
+ * `"TODAY"` / a date token like `{@[30DAYSAGO]}` (start of that day), or a
+ * literal date such as `"2026-03-31"` (local midnight) or an ISO date-time.
+ * Any other string is treated as a field name; an unknown `{@[…]}` token warns.
+ *
+ *   aggregate(dateDiff(requestDate, offerDate, "days"), "avg", "Avg Days to Offer")
+ */
+declare function dateDiff(start: DataSourceField, end: DataSourceField | "TODAY" | string, unit?: DateDiffUnit): DateDiffField;
+interface AggregateOptions {
+    /** `percentiles` only. Default (ES): 1, 5, 25, 50, 75, 95, 99. */
+    percents?: number[];
+    /**
+     * Conditions this metric alone is filtered by, AND-ed together. Several
+     * filtered metrics on one form still run as one request.
+     *
+     *   aggregate(amount, "sum", "Billed", { where: [[status, where("IN", "Invoiced", "Paid")]] })
+     */
+    where?: [DataSourceField, FieldFilter][];
+}
 /**
  * An aggregated metric. `outputName` is what a series' `valueField` must match,
  * and what a postOperation references as an operand.
  */
-declare function aggregate(f: DataSourceField, type?: AggregationType, outputName?: string): PivotSummary;
+declare function aggregate(f: DataSourceField, type?: AggregationType, outputName?: string, options?: AggregateOptions): PivotSummary;
 /**
  * A value derived from other aggregates, computed after the query returns.
  *
@@ -769,11 +968,19 @@ interface UseWidgetDataArgs {
      */
     localFilters?: any;
     rowLimit?: number;
-    dateGap?: {
-        unit: DateGapUnit;
-        start?: string;
-        end?: string;
-    } | null;
+    /** Fill empty periods (and optionally accumulate) on a date x-axis. See `DateGapOptions`. */
+    dateGap?: DateGapOptions | null;
+    /**
+     * Turn row 0's columns into one row per column, in order (after
+     * postOperations). With no declared series, x/y become `labelField`/`valueField`.
+     */
+    unpivot?: UnpivotOptions | null;
+    /**
+     * Ensure one row per category, in the given order, with 0 for every series
+     * valueField where no bucket came back. Applied after postOperations and
+     * widget filters, before local search / column filters / sort.
+     */
+    categoryGap?: CategoryGapOptions | null;
     /** Rows supplied by an automation binding; when provided, no query is issued. */
     automationRows?: any[] | null;
     automationLoading?: boolean;
@@ -788,6 +995,39 @@ interface UseWidgetDataArgs {
     /** Debounce for remote search, ms. Default 400. */
     searchDebounceMs?: number;
 }
+interface DateGapOptions {
+    unit: DateGapUnit;
+    /** Range to fill, inclusive. Both are needed to insert zero rows. */
+    start?: string;
+    end?: string;
+    /** How rows in the same period combine. Default "sum"; "last" is the pre-0.0.2 behaviour. */
+    merge?: "sum" | "last";
+    /**
+     * IANA zone for period boundaries. Default: the `timeZone` of the pivot row
+     * plotted on x (`groupBy(..., { interval, timeZone })`), else the browser's.
+     */
+    timeZone?: string;
+    /**
+     * Running totals after gap filling: `true` for every series valueField, or a
+     * list of fields. Each row then holds the level at the end of its period.
+     * Rows before `start` are dropped (they belong to the baseline), even when
+     * `end` is not given.
+     */
+    cumulative?: string[] | true;
+    /** Starting value per cumulative field: the total before `start`. */
+    baseline?: Record<string, number>;
+    /**
+     * Fetch `baseline` instead of passing it: a summary-only data source whose
+     * summary output names match the cumulative fields. The hook adds
+     * `dateField < start` and the widget's dashboard / widget filters (not the
+     * dashboard date range, which would exclude everything before `start`).
+     * One extra request. An explicit `baseline` value wins per field.
+     */
+    baselineSource?: {
+        dataSource: ZvolvDataSource;
+        dateField: string;
+    };
+}
 /**
  * Fetches, normalizes and shapes a widget's rows.
  *
@@ -1008,6 +1248,19 @@ interface KpiWidgetProps extends Omit<InteractiveWidgetProps, "widgetType"> {
     className?: string;
     style?: React.CSSProperties;
     onItemClick?: (vm: any, index: number) => void;
+    /**
+     * Sparkline series per content index, for `seriesSource.mode: "timeseries"`
+     * items you fetch yourself. Wins over a self-fetched `seriesSource.dataSource`.
+     */
+    externalSeriesByIndex?: Record<number, number[]>;
+    /**
+     * Render the whole card yourself. Used only with `layout: "card"` (so a
+     * generic `render` a host passes to every widget never changes a KPI).
+     * Wins over the `"KPI_CARD:card"` template.
+     */
+    renderCard?: (args: KpiCardRenderArgs) => React.ReactNode;
+    /** Same as `renderCard`, and likewise only with `layout: "card"`. */
+    render?: (args: KpiCardRenderArgs) => React.ReactNode;
 }
 declare const KpiWidget: React.FC<KpiWidgetProps>;
 
@@ -1081,9 +1334,49 @@ interface RankingBarWidgetProps extends Omit<InteractiveWidgetProps, "widgetType
 }
 /**
  * Ranked list of categories. Sorting, ranking and ratio math happen here; the
- * caller renders. `config.ranking` supplies { limit, order, labelField, valueField }.
+ * caller renders. `config.ranking` supplies { limit, order, labelField, valueField };
+ * `order: "none"` keeps the incoming row order.
  */
 declare const RankingBarWidget: React.FC<RankingBarWidgetProps>;
+interface FunnelRow {
+    label: any;
+    value: number;
+    /** value ÷ the first stage's value, 0..∞. 0 when the first stage is 0. */
+    ratioToFirst: number;
+    /** value ÷ the previous stage × 100. null for the first stage, or when the previous is 0. */
+    stepPct: number | null;
+    isFirst: boolean;
+    index: number;
+    raw: any;
+}
+interface FunnelRenderArgs {
+    rows: FunnelRow[];
+    /** The first stage, or null with no rows. */
+    first: FunnelRow | null;
+    tokens: ZvolvTokens;
+    config: any;
+    toLabel: (value: any) => any;
+    onItemClick?: (row: FunnelRow) => void;
+}
+interface FunnelWidgetProps extends Omit<InteractiveWidgetProps, "widgetType"> {
+    title?: string;
+    description?: string;
+    emptyMessage?: string;
+    unconfiguredMessage?: string;
+    className?: string;
+    style?: React.CSSProperties;
+    /** Called with the clicked stage — for drill-down. */
+    onItemClick?: (row: FunnelRow) => void;
+    render?: (args: FunnelRenderArgs) => React.ReactNode;
+}
+/** Rows (in stage order) → funnel stages. Pure; usable outside React. */
+declare function computeFunnelRows(rows: any[], labelField: string, valueField: string): FunnelRow[];
+/**
+ * Stage funnel (type FUNNEL). Rows arrive in stage order — usually from `unpivot` on a
+ * one-row, many-number source — and are never re-sorted. `config.funnel`
+ * may set { labelField, valueField }; defaults are the series x / y.
+ */
+declare const FunnelWidget: React.FC<FunnelWidgetProps>;
 interface GaugeRenderArgs {
     value: number;
     min: number;
@@ -2034,15 +2327,45 @@ declare function resolveFormWidget(config: any, dataSource?: any): {
 };
 /** Form widget: the headless form engine inside widget chrome. */
 declare const FormWidget: React.FC<FormWidgetProps>;
+/** Options for a filter control fetched from another data source. */
+interface FilterOptionsSource {
+    /** Usually a raw-rows formSource on another form, e.g. open mandates. */
+    dataSource: any;
+    /** Row key shown in the dropdown. */
+    labelField: string;
+    /**
+     * Row key used as the filter value. For a FORM_SEARCH lookup target this
+     * must be the lookup's ViewLabel field: the filter matches `<field>.view`.
+     */
+    valueField: string;
+    /** Sort options by label. Default: keep the source's row order. */
+    sort?: "asc" | "desc";
+    /** Label of the "no filter" option. Default "All". */
+    allLabel?: string;
+}
+interface FilterOption {
+    label: any;
+    value: any;
+}
 interface FilterControl {
     key: string;
     label: any;
     type: "text" | "select" | "multiselect" | "date" | "daterange" | "number";
-    options?: {
-        label: any;
-        value: any;
-    }[];
+    options?: FilterOption[];
     value?: any;
+    /** Field the produced WidgetFilter targets. */
+    field?: string;
+    optionsSource?: FilterOptionsSource;
+    /** True while `optionsSource` options load. */
+    loading?: boolean;
+}
+interface FilterSlotArgs {
+    control: FilterControl;
+    options: FilterOption[];
+    value: any;
+    setValue: (value: any) => void;
+    loading: boolean;
+    tokens: ZvolvTokens;
 }
 interface FilterPanelRenderArgs {
     controls: FilterControl[];
@@ -2050,6 +2373,8 @@ interface FilterPanelRenderArgs {
     setValue: (key: string, value: any) => void;
     apply: () => void;
     reset: () => void;
+    /** Current selections as widget filters (select / multiselect controls with a `field`). */
+    filters: WidgetFilter[];
     tokens: ZvolvTokens;
     config: any;
 }
@@ -2061,8 +2386,31 @@ interface FilterPanelWidgetProps {
     /** Current filter values, owned by the dashboard (URL params). */
     value?: Record<string, any>;
     onChange?: (values: Record<string, any>) => void;
+    /**
+     * Selections as `WidgetFilter[]` — pass straight to a widget's
+     * `widgetFilters`. A control on "All" (null / empty) contributes nothing.
+     */
+    onFiltersChange?: (filters: WidgetFilter[]) => void;
+    /** Replaces one control's UI; the panel still owns options and state. */
+    renderFilter?: (args: FilterSlotArgs) => React.ReactNode;
     render?: (args: FilterPanelRenderArgs) => React.ReactNode;
 }
+/**
+ * The option a stored value refers to. Values restored from URL params are
+ * strings, so "123" matches an option whose value is 123.
+ */
+declare function matchFilterOption(options: FilterOption[] | undefined, value: any): FilterOption | undefined;
+/** Panel values → widget filters: `{ field, operator: "IN", value: [...] }` per selected control. */
+declare function filterPanelToWidgetFilters(controls: FilterControl[], values: Record<string, any>): WidgetFilter[];
+/**
+ * The query behind a control's options: a distinct-values (composite terms)
+ * aggregation over the WHOLE index, with the source's own filters applied by
+ * Elasticsearch — never "the first N rows". A source that already declares a
+ * pivot is used as is.
+ */
+declare function optionsDataSource(source: FilterOptionsSource): any;
+/** Fetched rows → distinct, non-empty options. Pure. */
+declare function rowsToFilterOptions(rows: any[], source: FilterOptionsSource): FilterOption[];
 /**
  * In-grid filter panel. Dashboard filters are URL-param driven and owned by the
  * host, so this is a controlled component: it renders controls and reports
@@ -2151,6 +2499,19 @@ declare function getPostOpOperandSet(postOperations?: any[]): Set<string>;
  */
 declare function alignSummaryToSeries(dataSource: any, series: any[]): any;
 
+/**
+ * Percentiles summaries come back as an object of percent → value rather than
+ * a number. These helpers spread it into flat, chartable keys.
+ */
+/** Output key for one percentile: ("Days", 50) → "Days_p50", 99.9 → "Days_p99_9". */
+declare function percentileKey(name: string, percent: number | string): string;
+/**
+ * For each named percentiles summary, writes `<name>_p<percent>` keys and sets
+ * `<name>` itself to the median (p50) when it was requested. Rows whose value
+ * is already a number, or flat `<name>_p..` keys from the server, are left as is.
+ */
+declare function flattenPercentiles(rows: any[], names: string[]): any[];
+
 declare const PREFIX_UNITS: Record<string, string>;
 declare const SUFFIX_UNITS: Record<string, string>;
 /** Mirrors Angular formatAmountValue() from dashboards.utils */
@@ -2182,6 +2543,21 @@ declare function usesFormFramework(dataSource: ZvolvDataSource): boolean;
  * did not author.
  */
 
+/**
+ * A KPI sparkline that fetches its own series. The widget runs one query per
+ * content item through `useWidgetData`, applies `dateGap`, and plots
+ * `rows[].valueField` in x order.
+ */
+interface KpiTimeseriesSource {
+    mode: "timeseries";
+    /** Usually a pivot grouped by a date row with `interval`. */
+    dataSource: ZvolvDataSource;
+    /** Row key of the period — the groupBy title. */
+    xField: string;
+    /** Row key of the plotted value — the aggregate output name. */
+    valueField: string;
+    dateGap?: DateGapOptions;
+}
 interface AxisConfig {
     title?: string;
     valueFormat?: string;
@@ -2208,7 +2584,7 @@ interface ChartConfig extends WidgetChromeConfig {
     stackOrder?: "none" | "asc" | "desc";
     /** Insert zero rows for empty periods so a time axis reads continuously. */
     fillDateGaps?: boolean;
-    dateGapUnit?: "day" | "week" | "month";
+    dateGapUnit?: DateGapUnit;
 }
 interface KpiContentConfig {
     title?: string;
@@ -2241,13 +2617,25 @@ interface KpiContentConfig {
     statusFallbackTone?: string;
     seriesPoints?: string[];
     seriesPoint?: string;
-    seriesSource?: {
+    /**
+     * `{ mode: "timeseries", dataSource, xField, valueField, dateGap }` makes the
+     * widget fetch the sparkline itself. `{ mode: "timeseries" }` alone still
+     * reads the `externalSeriesByIndex` prop.
+     */
+    seriesSource?: KpiTimeseriesSource | {
         mode?: "timeseries" | "fields";
         [k: string]: any;
     };
+    /** Slot in `layout: "card"`: big value, small inline value, delta chip, or sparkline. */
+    role?: KpiRole;
 }
 interface KpiConfig extends WidgetChromeConfig {
     template?: KpiTemplateId;
+    /**
+     * "card" renders every item inside ONE card, placed by `role` (template key
+     * `"KPI_CARD:card"`). Default: each item as its own block.
+     */
+    layout?: "card" | "stack";
     contents?: KpiContentConfig[];
 }
 interface TableColumnConfig {
@@ -2361,10 +2749,19 @@ interface RankingConfig extends WidgetChromeConfig {
     ranking?: {
         labelField?: string;
         valueField?: string;
-        order?: "asc" | "desc";
+        /** "none" keeps the incoming row order. Default "desc". */
+        order?: "asc" | "desc" | "none";
         limit?: number;
     };
 }
+interface FunnelConfig extends WidgetChromeConfig {
+    template?: string;
+    /** Defaults: the series x / y (with `unpivot`, "label" / "value"). */
+    funnel?: {
+        labelField?: string;
+        valueField?: string;
+    };
+}
 interface TreeConfig extends WidgetChromeConfig {
     tree?: {
         idField?: string;
@@ -2423,6 +2820,19 @@ interface FilterPanelConfig extends WidgetChromeConfig {
             label: any;
             value: any;
         }[];
+        /**
+         * Fetch options from another data source (one request). Selecting one
+         * emits `{ field, operator: "IN", value: [v] }` via `onFiltersChange`;
+         * "All" emits nothing. For a FORM_SEARCH `field`, `valueField` must be
+         * the lookup's ViewLabel field (the filter matches `<field>.view`).
+         */
+        optionsSource?: {
+            dataSource: ZvolvDataSource;
+            labelField: string;
+            valueField: string;
+            sort?: "asc" | "desc";
+            allLabel?: string;
+        };
     }[];
 }
 /** A complete widget definition as a dashboard stores it. */
@@ -3067,4 +3477,4 @@ declare function formWidget(o: {
     Description: string;
 };
 
-export { ActionCardWidget, type ActionCardWidgetProps, type ActionConfig, type ActionItem, type ActionOutcome, type ActionRenderArgs, ActivityFeedWidget, type AggregationType, AreaChartWidget, type AxisConfig, BLOCKED_FILE_EXTENSIONS, type BadgeTone, BannerWidget, BarChartWidget, COLUMN_FILTER_BLANK, CONTAINER_KINDS, CalendarWidget, CardListWidget, CarouselWidget, type CellArgs, type ChartConfig, type ChartRenderArgs, ChartWidget, type ChartWidgetProps, ChildTableWidget, type CollectionConfig, type CollectionItem, type CollectionMappingConfig, type CollectionRenderArgs, CollectionWidget, type CollectionWidgetProps, type ColumnFilterSlotArgs, type ColumnFilters, type CreateZvolvRuntimeOptions, type DashboardFilterDef, type DashboardFilterValue, type DashboardNode, DashboardTableWidget, type DataSourceDefinition, type DataSourceField, DatabaseTableWidget, type DateGapUnit, type DateRange, type DateRangeToken, type DateToken, type DeepPartial, DefaultField, type DefaultInsight, DoughnutChartWidget, EMPTY_INTERACTIONS, type ElementSpec, EntityGalleryWidget, type FieldFilter, type FieldKind, type FieldOption, type FieldOptionsState, type FileFieldState, type FileItem, type FilterControl, type FilterInsight, type FilterOperator, type FilterPanelConfig, type FilterPanelRenderArgs, FilterPanelWidget, type FilterPanelWidgetProps, type FilterableField, FormApiContext, type FormConfig, type FormDefinition, type FormElement, type FormErrors, type FormField, FormFields, type FormInspection, type FormKit, FormKitSlot, type FormMode, type FormSpec, type FormStatus, type FormValues, FormWidget, type FormWidgetProps, type FormulaInsight, GRID, GanttChartWidget, type GaugeConfig, GaugeMeterWidget, type GaugeMeterWidgetProps, type GaugeRenderArgs, GoogleMapWidget, GridCardWidget, type GridItem, type HeatCell, type HeatMapConfig, type HeatMapRenderArgs, HeatMapWidget, type HeatMapWidgetProps, type HtmlConfig, type HtmlRenderArgs, HtmlWidget, type HtmlWidgetProps, type IframeConfig, IframeWidget, type IframeWidgetProps, type InteractionMode, type InteractionProps, type InteractionStateProps, type InteractionUiProps, type InteractiveWidgetData, type InteractiveWidgetProps, KPI_DEFAULT_TEMPLATES, type KpiConfig, type KpiContentConfig, type KpiContentVM, Delta as KpiDelta, Label as KpiLabel, Sparkline as KpiSparkline, type KpiTemplateId, type KpiTemplateProps, Value as KpiValue, KpiWidget, type KpiWidgetProps, type LegendConfig, LineChartWidget, type LookupConfig, type MapConfig, type MapMarker, type MapRenderArgs, type MapWidgetProps, type MasterFieldDataType, type MasterFieldType, MeetingSchedulerWidget, type MockQuery, type MockRuntimeOptions, NON_INPUT_TYPES, NON_RENDERING_TYPES, type NormalizedWidget, type OpenFormRequest, PREFIX_UNITS, type PayloadInsight, PieChartWidget, type PivotConfig, type PivotFilter, PivotGridWidget, type PivotGridWidgetProps, type PivotRenderArgs, type PivotRow, type PivotSummary, type PostOperation, type PostOperator, RankingBarWidget, type RankingBarWidgetProps, type RankingConfig, type RankingRenderArgs, type RankingRow, RawHtmlWidget, type ResolvedChromeConfig, type RuleEffect, type RuleInsight, type RuleOverride, SAMPLE_ROWS, SUBMISSION_SKIP_TYPES, SUFFIX_UNITS, ScatterChartWidget, type SearchSlotArgs, type SeriesConfig, type SheetColumn, type SheetFieldState, type SortDirection, type SortSlotArgs, type SortState, type StepItem, type StepperConfig, type StepperRenderArgs, StepperWidget, type StepperWidgetProps, type SubmitOptions, type TabConfig, type TabItem, type TabRenderArgs, TabWidget, type TabWidgetProps, type TableColumn, type TableColumnConfig, type TableConfig, type TableRenderArgs, TableWidget, type TableWidgetProps, TaskTrackerTableWidget, type TemplateComponent, type TemplateMap, TemplateProvider, type TemporalConfig, type TemporalEvent, type TemporalMappingConfig, type TemporalRenderArgs, TemporalWidget, type TemporalWidgetProps, TimelineWidget, type Tone, type ToolbarSlotArgs, type TreeConfig, type TreeNode, type TreeRenderArgs, TreeWidget, type TreeWidgetProps, type TrialButton, type TrialFieldState, type TrialLogEntry, type UploadedFile, type UseKpiContentsArgs, type UseWidgetDataArgs, type UseZvolvFormArgs, type ValidationInsight, WIDGET_REGISTRY, type WidgetChrome, type WidgetChromeConfig, type WidgetConfigurations, type WidgetDataResult, type WidgetDefinition, type WidgetFilter, type WidgetFilterSlotArgs, type WidgetInteractionState, type WidgetInteractions, WidgetShell, type WidgetShellProps, type WidgetState, type WidgetStateRenderArgs, WidgetStateSlot, type WidgetStyleOverrides, type WidgetTypeId, ZaiChatWidget, type ZaiChatWidgetProps, type ZvolvDataSource, ZvolvForm, type ZvolvFormApi, type ZvolvFormProps, ZvolvProvider, type ZvolvProviderProps, type ZvolvRuntime, ZvolvThemeProvider, type ZvolvTokens, ZvolvWidget, type ZvolvWidgetProps, aggregate, alignSummaryToSeries, applyLocalColumnFilters, applyLocalSearch, applyLocalSort, applyLocalWidgetFilters, applyPostOperations, applyRules, automationSource, buildColumnFilterClauses, buildDashFilters, buildDashboardTree, buildInitialValues, buildRemoteSort, buildSearchClause, buildSubmissionElements, buildTree, buildTriggerBody, buildWidgetFilterClauses, cascade, cdateFiltersFor, childIdsOf, cleanTitle, clearLookupCache, coerceSeriesNumbers, computeRowFormulas, createMockRuntime, createSubmission, createZvolvRuntime, dashboardDefaultDateToken, dashboardFilterDefs, dateRangeFor, defaultTokens, defineConfig, defineForm, derive, describeWidgetFilter, distinctColumnValues, eid, el, evaluateFormula, extractAgentFormData, fetchForm, fetchLookupOptions, fetchSubmission, field, fieldKind, fieldKindOf, fillDateGaps, filterableFields, formSource, formWidget, formatAmountValue, formatCompact, formatFieldValue, formulaLabels, getDataType, getEmptyValue, getPostOpOperandSet, getPostOpResult, gridHeight, gridWidgets, groupBy, hasActiveInteractions, inspectForm, interpolate, invokeAgent, invokeTrigger, invokeZeno, isDataSourceConfigured, isLegacyId, isLikelyTimestamp, isServerSafeFormula, lookupConfigOf, mergeTokens, normaliseElement, normaliseForm, normalizeWidget, openFormRequest, operatorsForKind, optionFilterRules, parseConfig, parseDeep, pivot, renderHtmlVariables, resetQueryUser, resolveChrome, resolveChromeConfig, resolveCollectionMapping, resolveDashboardLayout, resolveDateToken, resolveDrillDown, resolveFieldType, resolveFilterMode, resolveFormWidget, resolveSeries, resolveTableMode, resolveWidget, resolveWidgetDefaults, resolveXKey, rowSubmissionIds, ruleMatches, rulesOf, searchPeople, serializeElementValue, statusTone, submissionIdOf, submissionToValues, submitElementsOf, taskField, taskSource, toBraceFormula, toNum, toRelational, toneColor, toneSurface, updateSubmission, uploadFile, useCollectionItems, useFieldOptions, useFileField, useFormApi, useFormInspector, useInteractiveWidgetData, useKpiContents, useSheetField, useTableColumns, useTemplateOverride, useTemporalEvents, useTokens, useTrialField, useWidgetData, useWidgetInteractions, useZvolvClient, useZvolvForm, useZvolvRuntime, usesFormFramework, validateField, validateForm, when, where };
+export { ActionCardWidget, type ActionCardWidgetProps, type ActionConfig, type ActionItem, type ActionOutcome, type ActionRenderArgs, ActivityFeedWidget, type AggregateOptions, type AggregationType, AreaChartWidget, type AxisConfig, BLOCKED_FILE_EXTENSIONS, type BadgeTone, BannerWidget, BarChartWidget, COLUMN_FILTER_BLANK, CONTAINER_KINDS, CalendarWidget, CardListWidget, CarouselWidget, type CategoryGapOptions, type CellArgs, type ChartConfig, type ChartRenderArgs, ChartWidget, type ChartWidgetProps, ChildTableWidget, type CollectionConfig, type CollectionItem, type CollectionMappingConfig, type CollectionRenderArgs, CollectionWidget, type CollectionWidgetProps, type ColumnFilterSlotArgs, type ColumnFilters, type CreateZvolvRuntimeOptions, type DashboardFilterDef, type DashboardFilterValue, type DashboardNode, DashboardTableWidget, type DataSourceDefinition, type DataSourceField, DatabaseTableWidget, type DateDiffField, type DateDiffSpec, type DateDiffUnit, type DateGapOptions, type DateGapUnit, type DateInterval, type DateRange, type DateRangeToken, type DateToken, type DeepPartial, DefaultField, type DefaultInsight, DoughnutChartWidget, EMPTY_INTERACTIONS, type ElementSpec, EntityGalleryWidget, type FieldFilter, type FieldKind, type FieldOption, type FieldOptionsState, type FileFieldState, type FileItem, type FillDateGapsArgs, type FilterControl, type FilterInsight, type FilterOperator, type FilterOption, type FilterOptionsSource, type FilterPanelConfig, type FilterPanelRenderArgs, FilterPanelWidget, type FilterPanelWidgetProps, type FilterSlotArgs, type FilterableField, FormApiContext, type FormConfig, type FormDefinition, type FormElement, type FormErrors, type FormField, FormFields, type FormInspection, type FormKit, FormKitSlot, type FormMode, type FormSpec, type FormStatus, type FormValues, FormWidget, type FormWidgetProps, type FormulaInsight, type FunnelConfig, type FunnelRenderArgs, type FunnelRow, FunnelWidget, type FunnelWidgetProps, GRID, GanttChartWidget, type GaugeConfig, GaugeMeterWidget, type GaugeMeterWidgetProps, type GaugeRenderArgs, GoogleMapWidget, GridCardWidget, type GridItem, type HeatCell, type HeatMapConfig, type HeatMapRenderArgs, HeatMapWidget, type HeatMapWidgetProps, type HtmlConfig, type HtmlRenderArgs, HtmlWidget, type HtmlWidgetProps, type IframeConfig, IframeWidget, type IframeWidgetProps, type InteractionMode, type InteractionProps, type InteractionStateProps, type InteractionUiProps, type InteractiveWidgetData, type InteractiveWidgetProps, KPI_DEFAULT_TEMPLATES, Card as KpiCard, type KpiCardRenderArgs, type KpiCardRoles, type KpiConfig, type KpiContentConfig, type KpiContentVM, Delta as KpiDelta, Label as KpiLabel, type KpiRole, Sparkline as KpiSparkline, type KpiSparklineProps, type KpiTemplateId, type KpiTemplateProps, type KpiTimeseriesSource, Value as KpiValue, KpiWidget, type KpiWidgetProps, type LegendConfig, LineChartWidget, type LookupConfig, type MapConfig, type MapMarker, type MapRenderArgs, type MapWidgetProps, type MasterFieldDataType, type MasterFieldType, MeetingSchedulerWidget, type MockQuery, type MockRuntimeOptions, NON_INPUT_TYPES, NON_RENDERING_TYPES, type NormalizedWidget, type OpenFormRequest, PREFIX_UNITS, type PayloadInsight, PieChartWidget, type PivotConfig, type PivotFilter, PivotGridWidget, type PivotGridWidgetProps, type PivotRenderArgs, type PivotRow, type PivotSummary, type PostOperation, type PostOperator, RankingBarWidget, type RankingBarWidgetProps, type RankingConfig, type RankingRenderArgs, type RankingRow, RawHtmlWidget, type ResolvedChromeConfig, type RuleEffect, type RuleInsight, type RuleOverride, SAMPLE_ROWS, SUBMISSION_SKIP_TYPES, SUFFIX_UNITS, ScatterChartWidget, type SearchSlotArgs, type SeriesConfig, type SheetColumn, type SheetFieldState, type SortDirection, type SortSlotArgs, type SortState, type StepItem, type StepperConfig, type StepperRenderArgs, StepperWidget, type StepperWidgetProps, type SubmitOptions, type TabConfig, type TabItem, type TabRenderArgs, TabWidget, type TabWidgetProps, type TableColumn, type TableColumnConfig, type TableConfig, type TableRenderArgs, TableWidget, type TableWidgetProps, TaskTrackerTableWidget, type TemplateComponent, type TemplateMap, TemplateProvider, type TemporalConfig, type TemporalEvent, type TemporalMappingConfig, type TemporalRenderArgs, TemporalWidget, type TemporalWidgetProps, TimelineWidget, type Tone, type ToolbarSlotArgs, type TreeConfig, type TreeNode, type TreeRenderArgs, TreeWidget, type TreeWidgetProps, type TrialButton, type TrialFieldState, type TrialLogEntry, type UnpivotOptions, type UploadedFile, type UseKpiContentsArgs, type UseWidgetDataArgs, type UseZvolvFormArgs, type ValidationInsight, WIDGET_REGISTRY, type WidgetChrome, type WidgetChromeConfig, type WidgetConfigurations, type WidgetDataResult, type WidgetDefinition, type WidgetFilter, type WidgetFilterSlotArgs, type WidgetInteractionState, type WidgetInteractions, WidgetShell, type WidgetShellProps, type WidgetState, type WidgetStateRenderArgs, WidgetStateSlot, type WidgetStyleOverrides, type WidgetTypeId, ZaiChatWidget, type ZaiChatWidgetProps, type ZvolvDataSource, ZvolvForm, type ZvolvFormApi, type ZvolvFormProps, ZvolvProvider, type ZvolvProviderProps, type ZvolvRuntime, ZvolvThemeProvider, type ZvolvTokens, ZvolvWidget, type ZvolvWidgetProps, addPeriod, aggregate, alignSummaryToSeries, applyCumulative, applyLocalColumnFilters, applyLocalSearch, applyLocalSort, applyLocalWidgetFilters, applyPostOperations, applyRules, automationSource, buildColumnFilterClauses, buildDashFilters, buildDashboardTree, buildInitialValues, buildRemoteSort, buildSearchClause, buildSubmissionElements, buildTree, buildTriggerBody, buildWidgetFilterClauses, cascade, cdateFiltersFor, childIdsOf, cleanTitle, clearLookupCache, coerceSeriesNumbers, computeFunnelRows, computeRowFormulas, createMockRuntime, createSubmission, createZvolvRuntime, dashboardDefaultDateToken, dashboardFilterDefs, dateDiff, dateRangeFor, defaultTokens, defineConfig, defineForm, derive, describeWidgetFilter, distinctColumnValues, eid, el, elementOptionValues, evaluateFormula, extractAgentFormData, fetchForm, fetchLookupOptions, fetchSubmission, field, fieldKind, fieldKindOf, fillCategoryGaps, fillDateGaps, filterPanelToWidgetFilters, filterableFields, flattenPercentiles, formSource, formWidget, formatAmountValue, formatCompact, formatFieldValue, formulaLabels, getDataType, getEmptyValue, getPostOpOperandSet, getPostOpResult, gridHeight, gridWidgets, groupBy, hasActiveInteractions, inspectForm, interpolate, invokeAgent, invokeTrigger, invokeZeno, isDataSourceConfigured, isLegacyId, isLikelyTimestamp, isServerSafeFormula, lookupConfigOf, matchFilterOption, mergeTokens, normaliseElement, normaliseForm, normalizeWidget, openFormRequest, operatorsForKind, optionFilterRules, optionsDataSource, parseConfig, parseDateValue, parseDeep, percentileKey, pivot, renderHtmlVariables, resetQueryUser, resolveChrome, resolveChromeConfig, resolveCollectionMapping, resolveDashboardLayout, resolveDateToken, resolveDrillDown, resolveFieldType, resolveFilterMode, resolveFormWidget, resolveKpiRoles, resolveSeries, resolveTableMode, resolveWidget, resolveWidgetDefaults, resolveXKey, rowSubmissionIds, rowsToFilterOptions, ruleMatches, rulesOf, searchPeople, serializeElementValue, startOfPeriod, statusTone, submissionIdOf, submissionToValues, submitElementsOf, taskField, taskSource, toBraceFormula, toNum, toRelational, toneColor, toneSurface, unpivotRows, updateSubmission, uploadFile, useCollectionItems, useFieldOptions, useFileField, useFormApi, useFormInspector, useInteractiveWidgetData, useKpiContents, useSheetField, useTableColumns, useTemplateOverride, useTemporalEvents, useTokens, useTrialField, useWidgetData, useWidgetInteractions, useZvolvClient, useZvolvForm, useZvolvRuntime, usesFormFramework, validateField, validateForm, when, where };