@zestl/zvolv-widgets 0.0.0 → 0.0.2

package/dist/index.d.cts

@@ -458,7 +458,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,14 +484,41 @@ 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 }: FillDateGapsArgs): any[];
+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 applyCumulative(rows: any[], xKey: string, fields: string[], baseline?: Record<string, number>): any[];
 declare function coerceSeriesNumbers(rows: any[], series: {
     valueField: string;
 }[]): any[];
@@ -528,14 +569,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 +606,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 +624,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 +672,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 +882,8 @@ 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;
     /** Rows supplied by an automation binding; when provided, no query is issued. */
     automationRows?: any[] | null;
     automationLoading?: boolean;
@@ -788,6 +898,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 +1151,11 @@ 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[]>;
 }
 declare const KpiWidget: React.FC<KpiWidgetProps>;
 
@@ -1652,7 +1800,7 @@ interface FieldOption {
  * The UI family a field belongs to. A host draws one control per kind; the
  * library owns everything behind it (value shape, validation, submit format).
  */
-type FieldKind = "text" | "textarea" | "email" | "phone" | "url" | "number" | "currency" | "percent" | "select" | "radio" | "checkbox" | "lookup" | "user" | "date" | "time" | "datetime" | "daterange" | "rating" | "slider" | "file" | "signature" | "richtext" | "scan" | "timer" | "location" | "formula" | "display" | "autonumber" | "section" | "container" | "tabs" | "steps" | "matrix" | "table" | "sheet" | "comments" | "action" | "onbehalf" | "system" | "unknown";
+type FieldKind = "text" | "textarea" | "email" | "phone" | "url" | "number" | "currency" | "percent" | "select" | "radio" | "checkbox" | "lookup" | "user" | "date" | "time" | "datetime" | "daterange" | "rating" | "slider" | "file" | "signature" | "richtext" | "scan" | "timer" | "location" | "formula" | "display" | "autonumber" | "section" | "container" | "tabs" | "steps" | "matrix" | "table" | "sheet" | "comments" | "action" | "onbehalf" | "trials" | "system" | "unknown";
 
 /** Types never sent in a submission body. */
 declare const SUBMISSION_SKIP_TYPES: Set<string>;
@@ -1709,6 +1857,22 @@ declare function submissionIdOf(res: any): string | null;
 declare function createSubmission(client: any, form: FormDefinition, elements: FormElement[], values: FormValues, opts?: SubmitOptions): Promise<any>;
 declare function updateSubmission(client: any, form: FormDefinition, submissionId: string, elements: FormElement[], values: FormValues, opts?: SubmitOptions): Promise<any>;
 declare function invokeTrigger(client: any, triggerId: string | number, body: Record<string, any>): Promise<any>;
+/** TRIGGER_AUTOMATION with properties.automationType "ZENO" (zvolv-web onTriggerZeno → invokeNuclioAutomation). */
+declare function invokeZeno(client: any, automationUuid: string, body: Record<string, any>): Promise<any>;
+/**
+ * INVOKE_AGENT.
+ * 1. With properties.flowId: POST /api/v1/zwall/agent/invoke/{flowId}/{agentId} — the
+ *    zvolv-web / ZAI-Dashboard call (legacy agent flows).
+ * 2. Without a flowId, or when that server has no such flow (it answers
+ *    `{ error: true, reply: "Error: '<flowId>'" }`): POST
+ *    /api/v1/zwall/v3/agent_manager/agent_flow/{agentId} — how the platform calls
+ *    current ZAI agents (zvolv-mcp zagent.call_agent).
+ * Called directly, not through the SDK's workflow.invokeAgent, whose handleRequest
+ * rejects any reply without `error: false` ("Error fetching data").
+ */
+declare function invokeAgent(client: any, body: any, flowId?: string, agentId?: string): Promise<any>;
+/** Field map from an agent reply: `{formData}` or wrapped in `response`, possibly JSON-encoded (ZAI extractAgentFormData). */
+declare function extractAgentFormData(reply: any): Record<string, any> | null;
 interface UploadedFile {
     media_name: string;
     media_type: string;
@@ -1799,7 +1963,7 @@ interface FormField {
      * Visual intent: action buttons (primary / outline); checkbox "switch" when
      * attributes.showAsSwitch is set (ZAI CheckboxField / zvolv-web nz-switch).
      */
-    variant?: "primary" | "outline" | "switch";
+    variant?: "primary" | "outline" | "switch" | "dropdown";
     /** Read-only text to show (ON_BEHALF_OF: the user's name rather than their id). */
     displayText?: string;
     /** DATE_PICKER display format from properties.format (dayjs tokens), default DD/MM/YYYY. */
@@ -1869,18 +2033,50 @@ interface ZvolvFormApi {
         response: any;
     } | null>;
     reset: () => void;
-    runAction: (field: FormField) => Promise<ActionOutcome>;
+    /**
+     * Run an action button. For ACTION_DROPDOWN pass the picked option's label
+     * (field.options) — only that action (or its cascade) runs, as in zvolv-web.
+     */
+    runAction: (field: FormField, choice?: string) => Promise<ActionOutcome>;
+    /** Re-fetch the form (and the saved submission). Used by properties.refreshForm. */
+    reload: () => void;
     /** Field ids with an action / automation in flight. */
     busy: Set<string>;
     client: any;
     /** Sheet child definitions register here so submit can post their rows. */
     registerSheet: (fieldId: string, def: FormDefinition) => void;
+    /** A registered sheet's child form (after useSheetField loaded it). */
+    sheetDefinition: (fieldId: string) => FormDefinition | undefined;
+    /** Bumps whenever a sheet definition registers — memo key for inspectors. */
+    sheetVersion: number;
 }
+/** Elements that go into the POST/PUT /api/v1/submissions body. */
+declare function submitElementsOf(elements: FormElement[]): FormElement[];
 declare const FormApiContext: React.Context<ZvolvFormApi | null>;
 /** The nearest form's api, for field components rendered inside <ZvolvForm>. */
 declare function useFormApi(): ZvolvFormApi;
 declare function useZvolvForm(args: UseZvolvFormArgs): ZvolvFormApi;
 
+/**
+ * What an "open another screen" action button wants, for the host's onAction —
+ * mirrors ZAI-Dashboard ActionButtonField:
+ *  CREATE_SUBMISSION → NEW on properties.formId
+ *  EDIT_SUBMISSION / OPEN_TASK → EDIT on the button's value (a submission / task id)
+ *  SAVE_SUBMISSION → properties.formId, EDIT when the button holds an id, else NEW,
+ *                    prefilled through properties.inputMap (source → destination elementId)
+ *  OPEN_PROJECT → the button's value is a project WID
+ * After the host saves, write the new id back with form.setValue(field.id, id).
+ */
+interface OpenFormRequest {
+    actionType: string;
+    formId?: string;
+    submissionId?: string;
+    projectId?: string;
+    mode: "NEW" | "EDIT";
+    defaultValues?: Record<string, any>;
+}
+declare function openFormRequest(field: FormField, form: Pick<ZvolvFormApi, "values">): OpenFormRequest | null;
+
 /**
  * <ZvolvForm> — renders a Zvolv form with whatever field kit the host
  * supplies. Behaviour comes from useZvolvForm; appearance comes from
@@ -2103,6 +2299,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 */
@@ -2134,6 +2343,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;
@@ -2160,7 +2384,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;
@@ -2193,7 +2417,12 @@ 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;
     };
@@ -2528,6 +2757,8 @@ interface FieldOptionsOptions {
     autofillExtraLabels?: boolean;
 }
 declare function useFieldOptions(form: ZvolvFormApi, field: FormField, opts?: FieldOptionsOptions): FieldOptionsState;
+/** Extensions the platform refuses (ZAI-Dashboard utils/constant BLOCKED_FILE_EXTENSIONS). */
+declare const BLOCKED_FILE_EXTENSIONS: Set<string>;
 interface FileItem {
     key: string;
     name: string;
@@ -2581,6 +2812,60 @@ interface SheetFieldState {
 }
 declare function useSheetField(form: ZvolvFormApi, field: FormField): SheetFieldState;
 
+interface TrialButton {
+    label: string;
+    icon?: string;
+    color?: string;
+    hideLabel?: boolean;
+    disabled?: boolean;
+    /** Second-level buttons shown after this response is pressed. */
+    prompts: {
+        label: string;
+        icon?: string;
+        color?: string;
+        hideLabel?: boolean;
+    }[];
+}
+interface TrialLogEntry {
+    label: string;
+    correct: boolean;
+    detail?: string;
+}
+interface TrialFieldState {
+    type: "percent" | "time" | "task";
+    /** Response buttons for the current trial (task analysis: for the current step). */
+    buttons: TrialButton[];
+    /** Set after a response with prompt buttons is pressed; pick one with prompt(). */
+    activeResponse?: string;
+    prompts: TrialButton["prompts"];
+    respond: (label: string) => void;
+    prompt: (label: string) => void;
+    cancelPrompt: () => void;
+    /** Percent correct / task analysis: undo the last trial. */
+    prev: () => void;
+    currentTrial: number;
+    maxTrials: number;
+    complete: boolean;
+    /** Share of responses labelled IND / NR / CHECK (ZAI's "correct" set), 0–100. */
+    percentCorrect: number;
+    log: TrialLogEntry[];
+    disabled: boolean;
+    timer: number;
+    formattedTimer: string;
+    running: boolean;
+    start: () => void;
+    pause: () => void;
+    reset: () => void;
+    interval: number;
+    intervalCount: number;
+    timeLimit: number;
+    steps: string[];
+    currentStep: number;
+    stepName: string;
+    chain: "forward" | "backward" | "whole";
+}
+declare function useTrialField(form: ZvolvFormApi, field: FormField): TrialFieldState;
+
 /**
  * Form definition + submission normalisation. Ported from ZAI-Dashboard
  * `formApi.ts` (normaliseForm / normaliseElement / flattenElements /
@@ -2627,6 +2912,7 @@ interface RuleOverride {
 }
 /** Does `dep` (declared on `src`) match the current values? */
 declare function ruleMatches(src: FormElement, dep: any, values: FormValues): boolean;
+declare function rulesOf(el: FormElement): any[];
 /**
  * Hidden / disabled / required overrides per target elementId. A matching rule
  * for a target wins over a non-matching one on the same aspect (Angular's
@@ -2651,6 +2937,8 @@ declare function optionFilterRules(elements: FormElement[], targetId: string): {
     masterField: string;
 }[];
 
+/** Legacy formulas reference bare labels — wrap them in {…}, longest first. */
+declare function toBraceFormula(formula: string, labels: string[]): string;
 /**
  * Evaluate `formula` with `valueOf(label)` resolving field references.
  * Returns null when the formula is invalid or the result is not finite.
@@ -2658,6 +2946,125 @@ declare function optionFilterRules(elements: FormElement[], targetId: string): {
 declare function evaluateFormula(formula: string, valueOf: (label: string) => any, labels?: string[]): any;
 /** Labels a formula depends on (for recompute triggers). */
 declare function formulaLabels(formula: string, labels?: string[]): string[];
+/**
+ * True when the platform can evaluate `formula` itself. The submission API
+ * re-evaluates INPUT_FORMULA fields and rejects a mismatch ("Evaluated value
+ * \"0\" and existing value \"8000\" … do not match"); it only resolves
+ * `{Label}` references — bare labels (`MUL(Qty, Price)`) evaluate to 0 there.
+ */
+declare function isServerSafeFormula(formula: string, labels?: string[]): boolean;
+/**
+ * Recompute every INPUT_FORMULA cell of one sheet row (references are the
+ * child form's labels). Returns a new row; other cells are untouched.
+ */
+declare function computeRowFormulas(elements: {
+    elementId: string;
+    label: string;
+    type: string;
+    attributes?: any;
+    properties?: any;
+}[], row: Record<string, any>): Record<string, any>;
+
+type RuleEffect = "show" | "hide" | "required" | "optional" | "editable" | "read-only";
+interface RuleInsight {
+    sourceId: string;
+    sourceLabel: string;
+    sourceValue: string;
+    action: string;
+    effect: RuleEffect;
+    targetId: string;
+    targetLabel: string;
+    /** What the rule waits for, in words. */
+    expected: string;
+    matched: boolean;
+    /** "triage" (properties.triage) or "dependencies". */
+    origin: "triage" | "dependencies";
+}
+interface FilterInsight {
+    targetId: string;
+    targetLabel: string;
+    sourceForm: string;
+    kind: "dependent" | "dynamic" | "static";
+    /** Label on the source form the filter is applied to. */
+    masterField: string;
+    /** The local field whose value feeds the filter (dependent / dynamic). */
+    sourceLabel?: string;
+    sourceValue?: string;
+    /** Static filters: the configured value. */
+    value?: string;
+    active: boolean;
+}
+interface ValidationInsight {
+    id: string;
+    label: string;
+    type: string;
+    /** e.g. Accessories · row 2 — for sheet cells. */
+    scope?: string;
+    required: boolean;
+    hidden: boolean;
+    checks: string[];
+    value: string;
+    /** What validateField says right now. */
+    error?: string;
+    /** What the user currently sees (set on submit, cleared on change). */
+    shownError?: string;
+}
+interface FormulaInsight {
+    fieldId: string;
+    label: string;
+    scope: "form" | "row";
+    sheetLabel?: string;
+    row?: number;
+    formula: string;
+    /** The same formula with {Label} references — what the platform understands. */
+    serverFormula: string;
+    serverSafe: boolean;
+    inputs: {
+        label: string;
+        value: any;
+    }[];
+    /** The library's result for the current inputs. */
+    expected: any;
+    /** The value that will be submitted. */
+    current: any;
+    inSync: boolean;
+}
+interface DefaultInsight {
+    id: string;
+    label: string;
+    source: string;
+    value: string;
+}
+interface PayloadInsight {
+    formId: string;
+    elements: any[];
+    sheets: {
+        fieldId: string;
+        label: string;
+        formId: string;
+        rows: any[][];
+    }[];
+}
+interface FormInspection {
+    rules: RuleInsight[];
+    filters: FilterInsight[];
+    validation: ValidationInsight[];
+    formulas: FormulaInsight[];
+    defaults: DefaultInsight[];
+    payload: PayloadInsight | null;
+    summary: {
+        rules: number;
+        matched: number;
+        filters: number;
+        activeFilters: number;
+        errors: number;
+        formulas: number;
+        formulaIssues: number;
+    };
+}
+declare function inspectForm(form: ZvolvFormApi): FormInspection;
+/** inspectForm, memoised on the form's values, definition and loaded sheets. */
+declare function useFormInspector(form: ZvolvFormApi): FormInspection;
 
 /**
  * Authoring helpers: build a platform `create_form` payload and the FORM
@@ -2841,4 +3248,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, 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, DoughnutChartWidget, EMPTY_INTERACTIONS, type ElementSpec, EntityGalleryWidget, type FieldFilter, type FieldKind, type FieldOption, type FieldOptionsState, type FileFieldState, type FileItem, type FilterControl, type FilterOperator, type FilterPanelConfig, type FilterPanelRenderArgs, FilterPanelWidget, type FilterPanelWidgetProps, type FilterableField, FormApiContext, type FormConfig, type FormDefinition, type FormElement, type FormErrors, type FormField, FormFields, type FormKit, FormKitSlot, type FormMode, type FormSpec, type FormStatus, type FormValues, FormWidget, type FormWidgetProps, 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, PREFIX_UNITS, 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 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 UploadedFile, type UseKpiContentsArgs, type UseWidgetDataArgs, type UseZvolvFormArgs, 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, createMockRuntime, createSubmission, createZvolvRuntime, dashboardDefaultDateToken, dashboardFilterDefs, dateRangeFor, defaultTokens, defineConfig, defineForm, derive, describeWidgetFilter, distinctColumnValues, eid, el, evaluateFormula, fetchForm, fetchLookupOptions, fetchSubmission, field, fieldKind, fieldKindOf, fillDateGaps, filterableFields, formSource, formWidget, formatAmountValue, formatCompact, formatFieldValue, formulaLabels, getDataType, getEmptyValue, getPostOpOperandSet, getPostOpResult, gridHeight, gridWidgets, groupBy, hasActiveInteractions, interpolate, invokeTrigger, isDataSourceConfigured, isLegacyId, isLikelyTimestamp, lookupConfigOf, mergeTokens, normaliseElement, normaliseForm, normalizeWidget, operatorsForKind, optionFilterRules, parseConfig, parseDeep, pivot, renderHtmlVariables, resetQueryUser, resolveChrome, resolveChromeConfig, resolveCollectionMapping, resolveDashboardLayout, resolveDateToken, resolveDrillDown, resolveFieldType, resolveFilterMode, resolveFormWidget, resolveSeries, resolveTableMode, resolveWidget, resolveWidgetDefaults, resolveXKey, rowSubmissionIds, ruleMatches, searchPeople, serializeElementValue, statusTone, submissionIdOf, submissionToValues, taskField, taskSource, toNum, toRelational, toneColor, toneSurface, updateSubmission, uploadFile, useCollectionItems, useFieldOptions, useFileField, useFormApi, useInteractiveWidgetData, useKpiContents, useSheetField, useTableColumns, useTemplateOverride, useTemporalEvents, useTokens, 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 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 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, 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 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, computeRowFormulas, createMockRuntime, createSubmission, createZvolvRuntime, dashboardDefaultDateToken, dashboardFilterDefs, dateDiff, dateRangeFor, defaultTokens, defineConfig, defineForm, derive, describeWidgetFilter, distinctColumnValues, eid, el, evaluateFormula, extractAgentFormData, fetchForm, fetchLookupOptions, fetchSubmission, field, fieldKind, fieldKindOf, fillDateGaps, 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, mergeTokens, normaliseElement, normaliseForm, normalizeWidget, openFormRequest, operatorsForKind, optionFilterRules, parseConfig, parseDateValue, parseDeep, percentileKey, pivot, renderHtmlVariables, resetQueryUser, resolveChrome, resolveChromeConfig, resolveCollectionMapping, resolveDashboardLayout, resolveDateToken, resolveDrillDown, resolveFieldType, resolveFilterMode, resolveFormWidget, resolveSeries, resolveTableMode, resolveWidget, resolveWidgetDefaults, resolveXKey, rowSubmissionIds, ruleMatches, rulesOf, searchPeople, serializeElementValue, startOfPeriod, 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 };