@zestl/zvolv-widgets 0.0.0-stage → 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,3070 @@
+import React from 'react';
+import dayjs from 'dayjs';
+
+interface ZvolvRuntime {
+    client: any;
+    resolveQueryUser?: () => Promise<any>;
+    resolveUserLabels?: (ids: any[], kind: string) => Promise<Record<string, string>>;
+    prefetchQueryMappings?: (formId: any) => Promise<any>;
+    generateQuery?: (...args: any[]) => any;
+    formatDashboardFilters?: (cfg: any, dataSource: any, filters: any) => any;
+    getUserFieldKind?: (type: any) => string | null;
+    /**
+     * Optional. Host's column-filter formatter (user name → id, workflow title →
+     * id, durations). When absent, a built-in plain-value IN filter is used.
+     */
+    formatHeaderFilters?: (dataSource: any, columnFilters: Record<string, any[]>) => any[];
+}
+interface ZvolvProviderProps {
+    runtime: ZvolvRuntime;
+    children: React.ReactNode;
+}
+declare const ZvolvProvider: React.FC<ZvolvProviderProps>;
+declare function useZvolvRuntime(): ZvolvRuntime;
+declare function useZvolvClient(): any;
+
+/** Forget the cached user — call on login / logout. */
+declare const resetQueryUser: () => void;
+
+/**
+ * The real-data runtime, built in. Pass an initialised, logged-in
+ * @zestl/zvolv-js-sdk client and every widget queries live Zvolv data — no host
+ * utilities required. The query path is ported verbatim from ZAI-Dashboard.
+ */
+
+interface CreateZvolvRuntimeOptions {
+    /** A ZvolvClient after `workspace.init(domain)` and login. A getter works too. */
+    client: any | (() => any);
+    /** Returns the logged-in user (decrypted). Default: `client.auth.userInstance`. */
+    readUser?: () => any;
+}
+declare function createZvolvRuntime({ client, readUser }: CreateZvolvRuntimeOptions): ZvolvRuntime;
+
+/**
+ * A fake runtime for local development and design work.
+ *
+ * Use this to build and preview dashboards without a backend or login. Swap in
+ * the real adapter when you want live data — the widget code does not change.
+ *
+ * The mock honours the filter clauses and sort a real query would carry
+ * (dashboard filters, widget filters, column filters, search, sort), applied to
+ * its in-memory rows, so interactive controls visibly work in previews.
+ * It does NOT aggregate pivots: every widget receives the raw rows.
+ */
+
+interface MockRuntimeOptions {
+    /** Rows every widget receives. Default: a small generic sample. */
+    rows?: any[];
+    /** Artificial latency in ms, to exercise loading states. */
+    delay?: number;
+    /** Called with every generated mock query — handy for asserting what was sent. */
+    onQuery?: (query: MockQuery) => void;
+}
+/** What the mock's generateQuery produces and its elasticSearch consumes. */
+interface MockQuery {
+    filters: any[];
+    dashboardSort: Record<string, string> | null;
+    columns: any[];
+    limit: number | null;
+}
+declare const SAMPLE_ROWS: ({
+    id: number;
+    region: string;
+    owner: string;
+    revenue: number;
+    target: number;
+    orders: number;
+    status: string;
+    startDate: string;
+    endDate: string;
+    latitude: number;
+    longitude: number;
+    parentId: null;
+} | {
+    id: number;
+    region: string;
+    owner: string;
+    revenue: number;
+    target: number;
+    orders: number;
+    status: string;
+    startDate: string;
+    endDate: string;
+    latitude: number;
+    longitude: number;
+    parentId: number;
+})[];
+declare function createMockRuntime(options?: MockRuntimeOptions): ZvolvRuntime;
+
+/**
+ * Design tokens. This is the contract Claude's design pass writes to.
+ * Every visual decision a widget makes resolves through these values —
+ * no colour, font or spacing literal should appear in a template.
+ */
+interface WidgetChrome {
+    appearance: "shadow" | "border" | "flat";
+    padding: string;
+    borderRadius: string;
+    borderWidth: string;
+    borderColor: string;
+    backgroundColor: string;
+    shadow: string;
+    hoverLift: boolean;
+    gap: string;
+}
+interface ZvolvTokens {
+    fontFamily: string;
+    monoFontFamily: string;
+    colors: {
+        background: string;
+        surface: string;
+        cardBackground: string;
+        textPrimary: string;
+        textSecondary: string;
+        textTertiary: string;
+        primary: string;
+        primaryLight: string;
+        border: string;
+        success: string;
+        error: string;
+        warning: string;
+        info: string;
+        onAccent: string;
+        charts: {
+            palette: string[];
+            grid: string;
+            axis: string;
+            neutral: string;
+        };
+    };
+    typography: {
+        title: {
+            fontSize: string;
+            fontWeight: number;
+            letterSpacing: string;
+            color?: string;
+        };
+        description: {
+            fontSize: string;
+            color?: string;
+        };
+        kpiValue: {
+            fontSize: string;
+            fontWeight: number;
+            letterSpacing: string;
+        };
+        kpiLabel: {
+            fontSize: string;
+            fontWeight: number;
+            textTransform: string;
+            letterSpacing: string;
+        };
+        body: {
+            fontSize: string;
+            lineHeight: string;
+        };
+        caption: {
+            fontSize: string;
+        };
+    };
+    /** Shared visual language for data-dense widgets. */
+    surfaces: {
+        /** Zebra / header / hover bands for tables, pivots and grids. */
+        table: {
+            headerBg: string;
+            rowBg: string;
+            altRowBg: string;
+            hoverBg: string;
+            borderColor: string;
+        };
+        /** Pills, chips and status badges. */
+        badge: {
+            radius: string;
+            paddingX: string;
+            paddingY: string;
+            fontSize: string;
+            fontWeight: number;
+        };
+        /** Card-like children inside a widget (list items, gallery tiles, steps). */
+        tile: {
+            bg: string;
+            radius: string;
+            padding: string;
+            borderColor: string;
+            gap: string;
+        };
+        /** Calendar / scheduler / gantt canvases. */
+        canvas: {
+            bg: string;
+            gridLine: string;
+            todayBg: string;
+            nowLine: string;
+            eventRadius: string;
+        };
+    };
+    widget: WidgetChrome;
+    /** Per-widget-type chrome overrides, keyed by widget type (case-insensitive). */
+    overrides?: Record<string, Partial<WidgetChrome>>;
+    /**
+     * Theme-level default `template` and config per widget type. Layered UNDER a
+     * widget's own config, so existing dashboards are never overridden.
+     */
+    widgetDefaults?: Record<string, {
+        template?: string;
+        [k: string]: any;
+    }>;
+}
+declare const defaultTokens: ZvolvTokens;
+/** Deep-merges a partial design spec onto the defaults. Arrays replace wholesale. */
+declare function mergeTokens(base: ZvolvTokens, patch?: DeepPartial<ZvolvTokens>): ZvolvTokens;
+type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+/** Resolves final chrome for a widget: base ← type override ← per-widget config.style. */
+declare function resolveChrome(tokens: ZvolvTokens, widgetType?: string, perWidget?: Partial<WidgetChrome> | null): WidgetChrome;
+/** Theme-level default config for a widget type, layered UNDER the widget's own config. */
+declare function resolveWidgetDefaults(tokens: ZvolvTokens, widgetType: string | undefined, config: any): any;
+
+interface ZvolvThemeProviderProps {
+    /** A partial design spec — deep-merged onto the defaults. This is Claude's design output. */
+    tokens?: DeepPartial<ZvolvTokens>;
+    children: React.ReactNode;
+}
+declare const ZvolvThemeProvider: React.FC<ZvolvThemeProviderProps>;
+declare function useTokens(): ZvolvTokens;
+
+type KpiTemplateId = "standard" | "trend" | "comparison" | "progress" | "financial" | "status" | "chart" | "hero_chart" | "icon";
+type BadgeTone = "success" | "warning" | "error" | "info" | "neutral";
+/**
+ * View-model for a single resolved KPI item.
+ *
+ * Templates are PURELY PRESENTATIONAL and must never re-derive values from `raw`.
+ * Everything a template needs to render is already resolved here.
+ */
+interface KpiContentVM {
+    template: KpiTemplateId;
+    title: string;
+    subtitle: string;
+    value: string | number;
+    rawValue: number | null;
+    prefix: string;
+    suffix: string;
+    target: string | number;
+    rawTarget: number | null;
+    valueColor?: string;
+    icon: string | null;
+    iconColor: string;
+    iconSize: string;
+    textAlign: string;
+    iconAlign: string;
+    isLast: boolean;
+    delta?: {
+        value: number;
+        mode: "percent" | "absolute";
+        isPositive: boolean;
+    };
+    progress?: {
+        ratio: number;
+        max: number;
+    };
+    status?: {
+        label: string;
+        tone: BadgeTone;
+        description?: string;
+    };
+    series?: number[];
+    raw: any;
+    config: any;
+}
+/** Props every KPI template component receives. */
+interface KpiTemplateProps {
+    vm: KpiContentVM;
+    index: number;
+}
+
+/** Anything Claude can override, keyed by "WIDGET_TYPE:templateId". */
+type TemplateComponent = React.FC<any>;
+type TemplateMap = Record<string, TemplateComponent>;
+interface TemplateProviderProps {
+    /**
+     * Claude's UI layer. Keys are "WIDGET_TYPE:templateId", e.g.
+     *   { "KPI_CARD:standard": MyKpiCard, "BAR_CHART:standard": MyBars }
+     * Any key not supplied falls back to the package's built-in template.
+     */
+    templates?: TemplateMap;
+    children: React.ReactNode;
+}
+declare const TemplateProvider: React.FC<TemplateProviderProps>;
+declare function useTemplateOverride(widgetType: string, templateId: string): TemplateComponent | null;
+
+declare const Label: React.FC<{
+    children: React.ReactNode;
+}>;
+declare const Value: React.FC<{
+    vm: KpiTemplateProps["vm"];
+    mono?: boolean;
+}>;
+declare const Delta: React.FC<{
+    vm: KpiTemplateProps["vm"];
+}>;
+declare const Sparkline: React.FC<{
+    series: number[];
+    color: string;
+    height?: number;
+}>;
+declare const KPI_DEFAULT_TEMPLATES: {
+    standard: React.FC<KpiTemplateProps>;
+    trend: React.FC<KpiTemplateProps>;
+    comparison: React.FC<KpiTemplateProps>;
+    progress: React.FC<KpiTemplateProps>;
+    financial: React.FC<KpiTemplateProps>;
+    status: React.FC<KpiTemplateProps>;
+    chart: React.FC<KpiTemplateProps>;
+    hero_chart: React.FC<KpiTemplateProps>;
+    icon: React.FC<KpiTemplateProps>;
+};
+
+type WidgetTypeId = "KPI_CARD" | "BAR_CHART" | "LINE_CHART" | "PIE_CHART" | "TABLE";
+interface ZvolvDataSource {
+    formId?: string | number;
+    isTask?: boolean;
+    newFormFramework?: boolean;
+    fields?: any[];
+    pivot?: {
+        rows?: any[];
+        summary?: any[];
+        postOperations?: any[];
+        [k: string]: any;
+    };
+    automation?: {
+        automationId?: string | number;
+        enabled?: boolean;
+        [k: string]: any;
+    };
+    [k: string]: any;
+}
+interface SeriesConfig {
+    name?: string;
+    valueField: string;
+    argumentField: string;
+    color?: string;
+    formatting?: any[];
+    [k: string]: any;
+}
+interface WidgetConfigurations {
+    template?: string;
+    description?: string;
+    series?: SeriesConfig[];
+    legends?: {
+        showLabels?: boolean;
+        position?: string;
+        [k: string]: any;
+    };
+    axis?: {
+        argumentAxis?: any;
+        valueAxis?: any;
+        [k: string]: any;
+    };
+    sortOrder?: "none" | "asc" | "desc";
+    stackOrder?: "none" | "asc" | "desc";
+    contents?: any[];
+    style?: WidgetStyleOverrides | null;
+    [k: string]: any;
+}
+interface WidgetStyleOverrides {
+    appearance?: "shadow" | "border" | "flat";
+    padding?: string;
+    borderRadius?: string;
+    borderWidth?: string;
+    borderColor?: string;
+    borderTopWidth?: string;
+    borderTopColor?: string;
+    backgroundColor?: string;
+    hideScrollbar?: boolean;
+    hoverLift?: boolean;
+    titleFontSize?: string;
+    titleFontWeight?: number;
+    titleColor?: string;
+}
+type WidgetState = "loading" | "ready" | "empty" | "unconfigured" | "error";
+interface WidgetDataResult<TRow = any> {
+    /** Rows to render — after local search / column filters / sort / widget filters. */
+    rows: TRow[];
+    /** Rows as fetched, before local interactions. Use for column-filter options. */
+    sourceRows: TRow[];
+    state: WidgetState;
+    loading: boolean;
+    initialLoading: boolean;
+    error: Error | null;
+    refresh: () => void;
+    meta: {
+        xKey: string;
+        series: SeriesConfig[];
+        template: string;
+        userLabels: Record<string, string>;
+        toLabel: (value: any) => any;
+        /** Where search / column filters / sort run for this widget. */
+        tableMode: "remote" | "local";
+        /** Where widget-level filters run for this widget. */
+        filterMode: "remote" | "local";
+        /** True when any search / filter is applied (drives the "no matches" message). */
+        filtered: boolean;
+    };
+}
+
+interface WidgetShellProps {
+    widgetType?: string;
+    title?: string;
+    description?: string;
+    state: WidgetState;
+    error?: Error | null;
+    /** Message shown when the widget has no data source configured. */
+    unconfiguredMessage?: string;
+    /** Message shown when the widget IS wired but returned zero rows. */
+    emptyMessage?: string;
+    /** Header controls (search, filters, buttons), right-aligned next to the title. */
+    actions?: React.ReactNode;
+    /** A refetch is in flight while rows stay on screen; the body dims slightly. */
+    busy?: boolean;
+    /** A search / filter is applied — an empty result then reads "no matches". */
+    filtered?: boolean;
+    style?: React.CSSProperties;
+    className?: string;
+    children: React.ReactNode;
+}
+/** What a host needs to draw a non-ready widget state in its own style. */
+interface WidgetStateRenderArgs {
+    state: Exclude<WidgetState, "ready">;
+    widgetType?: string;
+    /** The message the library would show (defaults or the widget's overrides). */
+    message: string;
+    error?: Error | null;
+    filtered: boolean;
+}
+/**
+ * Supply one renderer for loading / unconfigured / empty / error across every
+ * widget: `<WidgetStateSlot.Provider value={(a) => <MyState {...a} />}>`.
+ * Return `undefined` to fall back to the built-in text.
+ */
+declare const WidgetStateSlot: React.Context<((args: WidgetStateRenderArgs) => React.ReactNode) | null>;
+/**
+ * Chrome + state handling shared by every widget: card frame, header, and the
+ * loading / unconfigured / empty / error states.
+ *
+ * `unconfigured` (no data source wired) and `empty` (wired, zero rows) are
+ * deliberately distinct — collapsing them hides real configuration mistakes.
+ */
+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";
+interface FillDateGapsArgs {
+    rows: any[];
+    xKey: string;
+    series: {
+        valueField: string;
+    }[];
+    unit: DateGapUnit;
+    range: {
+        start: dayjs.Dayjs;
+        end: dayjs.Dayjs;
+    } | null;
+}
+/**
+ * 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.
+ */
+declare function fillDateGaps({ rows, xKey, series, unit, range }: FillDateGapsArgs): any[];
+declare function coerceSeriesNumbers(rows: any[], series: {
+    valueField: string;
+}[]): any[];
+
+/**
+ * DataSource authoring — how a widget says WHERE its data comes from.
+ *
+ * `configurations` describes how a widget LOOKS and which fields it plots.
+ * `dataSource` describes WHAT is queried: the form, its fields, and any pivot
+ * (group-by + aggregate). The query generator reads `dataSource`, not `configurations`.
+ *
+ * Every builder here produces the exact object shape the server and the query
+ * generator expect. Prefer them over hand-writing the literals.
+ */
+/** Zvolv form element types, as `masterFieldType`. */
+type MasterFieldType = "INPUT_TEXT" | "INPUT_TEXTAREA" | "INPUT_NUMBER" | "INPUT_CURRENCY" | "INPUT_PERCENT" | "INPUT_FORMULA" | "INPUT_AUTONUMBER" | "INPUT_DATE" | "INPUT_DATE_RANGE" | "INPUT_TIME" | "INPUT_TIMER" | "CHECK_BOX" | "RADIO_BUTTON" | "DROP_DOWN" | "INPUT_TAG" | "FORM_SEARCH" | "INPUT_SEARCH" | "AUTO_COMPLETE" | "EXTERNAL_API" | "RATING_BAR" | "PROGRESS_BAR" | "UPLOAD_FILE_IMAGE" | "FILE_UPLOAD_V2" | "INPUT_SHEET";
+/** Elasticsearch-side data type, derived from the element type. */
+type MasterFieldDataType = "STRING" | "INT" | "FLOAT" | "BOOLEAN" | "ARRAY" | "OBJECT";
+/**
+ * Mirrors the app's getDataType(): maps a form element type to its ES data type.
+ * Wrong values here produce empty aggregations, so always derive rather than guess.
+ */
+declare function getDataType(elementType: string): MasterFieldDataType;
+type FilterOperator = "EQUALS" | "NOT_IN" | "IN" | "IN_UG" | "CONTAINS" | "STARTS_WITH" | "GREATER_THAN" | "LESS_THAN" | "BETWEEN" | "EMPTY" | "NOT_EMPTY" | "DATE_IS" | "MULTIPLE" | "_ALL";
+interface FieldFilter {
+    operator: FilterOperator;
+    /** Values. Date fields accept date-math tokens like `{@[TODAY]}`. */
+    operand: any[];
+}
+/**
+ * One queryable field. `header` is the name rows come back under — it is what a
+ * series' `valueField` / `argumentField` and a pivot's `title` must match.
+ */
+interface DataSourceField {
+    /** Output name in the returned rows. Series and pivots reference THIS. */
+    header: string;
+    /** Server-side field name. For task fields, the camelCase form. */
+    masterfield?: string;
+    masterFieldType?: MasterFieldType | string;
+    masterFieldDataType?: MasterFieldDataType;
+    /** Form element id, when known. */
+    id?: string | number;
+    formID?: string | number;
+    /** True for built-in task fields (status, priority, assignee…). */
+    isTaskField?: boolean;
+    taskfield?: string;
+    sortOrder?: "asc" | "desc";
+    filter?: FieldFilter;
+    formula?: any[];
+}
+interface PivotRow {
+    /** Output column name. Must match the series `argumentField`. */
+    title: string;
+    masterField: string;
+    masterFieldType?: string;
+    masterFieldDataType?: MasterFieldDataType;
+}
+type AggregationType = "sum" | "avg" | "min" | "max" | "count" | "value_count" | "cardinality";
+interface PivotSummary {
+    title: string;
+    masterField: string;
+    masterFieldType?: string;
+    masterFieldDataType?: MasterFieldDataType;
+    /** Output name of the aggregated value. Must match the series `valueField`. */
+    value: string;
+    type: AggregationType;
+}
+interface PivotFilter {
+    field: string;
+    operand: string;
+    masterField: string;
+    masterFieldType?: string;
+    masterFieldDataType?: MasterFieldDataType;
+    operator: FilterOperator;
+    value: any[];
+}
+type PostOperator = "ADD" | "SUB" | "MUL" | "DIV" | "PERCENT";
+interface PostOperation {
+    /** Output name of the derived value. A series may plot it. */
+    title: string;
+    operator: PostOperator;
+    /** Names of OTHER summary entries, by their `value`. Order matters for SUB/DIV. */
+    operands: string[];
+}
+interface PivotConfig {
+    rows?: PivotRow[];
+    columns?: PivotRow[];
+    summary?: PivotSummary[];
+    filters?: PivotFilter[];
+    postOperations?: PostOperation[];
+}
+interface DataSourceDefinition {
+    formId?: string | number;
+    /** Set for form-backed sources. Omit only for legacy widget-id sources. */
+    newFormFramework?: boolean;
+    /** True to query the tasks index instead of a form's submissions. */
+    isTask?: boolean;
+    fields?: DataSourceField[];
+    pivot?: PivotConfig;
+    /** Max rows for pivot aggregations. */
+    displayRowLimit?: number | string;
+    automation?: {
+        automationId: string | number;
+        enabled?: boolean;
+    };
+    [k: string]: any;
+}
+/**
+ * Declares a queryable field. `masterFieldDataType` is derived from the element
+ * type when not given, which is what aggregations and filters key off.
+ */
+declare function field(header: string, masterFieldType: MasterFieldType | string, options?: Partial<DataSourceField>): DataSourceField;
+/**
+ * A built-in task field. The server expects these camelCased, so `header`
+ * "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;
+/**
+ * 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;
+/**
+ * A value derived from other aggregates, computed after the query returns.
+ *
+ * Operands name OTHER summaries by their `value`. Operand order matters:
+ * SUB is left-to-right, and PERCENT is operands[0] / operands[1] * 100.
+ */
+declare function derive(title: string, operator: PostOperator, operands: string[]): PostOperation;
+/** A filter applied to a field at query time. */
+declare function where(operator: FilterOperator, ...operand: any[]): FieldFilter;
+/**
+ * Builds a form-backed data source.
+ *
+ * Every field a widget plots, groups by, or filters on must be listed in
+ * `fields` — the query generator builds its field map from this list, so an
+ * omitted field silently returns nothing.
+ */
+declare function formSource(formId: string | number, fields: DataSourceField[], options?: {
+    pivot?: PivotConfig;
+    displayRowLimit?: number;
+}): DataSourceDefinition;
+/**
+ * Builds a task-backed data source.
+ *
+ * Task sources query the tasks index and must NOT carry a formId — passing one
+ * makes the generator query submissions instead, returning the wrong rows.
+ */
+declare function taskSource(fields: DataSourceField[], options?: {
+    pivot?: PivotConfig;
+    displayRowLimit?: number;
+}): DataSourceDefinition;
+/** Builds a data source whose rows come from an automation rather than a query. */
+declare function automationSource(automationId: string | number, fields?: DataSourceField[]): DataSourceDefinition;
+/** Assembles a pivot. Omit `rows` for a single-number (summary-only) result. */
+declare function pivot(config: PivotConfig): PivotConfig;
+
+/**
+ * Viewer interactions — search, column filters, sort and widget-level filters.
+ *
+ * These are the runtime choices a person makes while LOOKING at a widget, as
+ * opposed to `dataSource` filters an author bakes in. The UI for each one is
+ * supplied by the caller (render slots); this module owns what an applied
+ * interaction MEANS for the data:
+ *
+ *   remote — translated into query clauses and sent through generateQuery, so
+ *            the server filters/sorts the full dataset (form-framework sources).
+ *   local  — applied to the rows already loaded (pivot tables, legacy widget-id
+ *            sources, automation rows), where the server cannot do it.
+ *
+ * Mirrors ZAI-Dashboard's DashboardTable (search `_ALL`, header filters,
+ * `dashboardSort`) and ZFilters (widget filters) so results match production.
+ */
+
+type SortDirection = "asc" | "desc";
+/** One active sort. `key` is the column key (the row field name). */
+interface SortState {
+    key: string;
+    direction: SortDirection;
+}
+/**
+ * Column (header) filters: column key → the values the viewer ticked.
+ * Include `COLUMN_FILTER_BLANK` ("") to match empty cells.
+ */
+type ColumnFilters = Record<string, any[]>;
+/** Value that selects empty cells in a column filter. */
+declare const COLUMN_FILTER_BLANK = "";
+/** Relative-date tokens accepted by the `DATE_IS` operator. */
+type DateToken = "TODAY" | "YESTERDAY" | "LAST_SEVEN_DAYS" | "LAST_THIRTY_DAYS" | "THIS_WEEK" | "THIS_MONTH" | "THIS_YEAR";
+/**
+ * One widget-level filter, as the viewer applies it from the widget header.
+ *
+ * `field` is the field's `header` in `dataSource.fields` (the name rows come
+ * back under). Several filters are combined with AND.
+ */
+interface WidgetFilter {
+    field: string;
+    operator: FilterOperator | "DATE_IS";
+    /**
+     * Scalar or array. `IN`/`NOT_IN` take a list, `BETWEEN` takes `[from, to]`,
+     * `DATE_IS` takes a DateToken, `EMPTY`/`NOT_EMPTY` take nothing.
+     * User fields (AUTO_COMPLETE, assignees) take user ids, not names.
+     */
+    value?: any;
+}
+/** Everything a viewer can apply to one widget. */
+interface WidgetInteractionState {
+    search: string;
+    columnFilters: ColumnFilters;
+    sort: SortState | null;
+    widgetFilters: WidgetFilter[];
+}
+declare const EMPTY_INTERACTIONS: WidgetInteractionState;
+type InteractionMode = "remote" | "local";
+/**
+ * Where search / column filters / sort run.
+ *
+ * Remote only for form-framework sources WITHOUT pivot rows: a pivot returns
+ * aggregated buckets, so searching or sorting the underlying documents would
+ * not change what is shown. Same rule as ZAI-Dashboard's `isRemoteSort`.
+ */
+declare function resolveTableMode(dataSource: any, widgetType?: string, hasAutomationRows?: boolean): InteractionMode;
+/**
+ * Where widget-level filters run. They are query filters, so any form-framework
+ * source (pivot or not) filters server-side; only automation rows and legacy
+ * widget-id sources fall back to filtering loaded rows.
+ */
+declare function resolveFilterMode(dataSource: any, hasAutomationRows?: boolean): InteractionMode;
+declare function hasActiveInteractions(s: Partial<WidgetInteractionState>): boolean;
+/** `[from, to]` (YYYY-MM-DD) for a relative-date token. Mirrors host getDateRange. */
+declare function resolveDateToken(token: string, now?: dayjs.Dayjs): [string, string] | null;
+/** Search → the `_ALL` (or `MULTIPLE` for a date) clause DashboardTable sends. */
+declare function buildSearchClause(search: string): any | null;
+/**
+ * Widget filters → generateQuery filter clauses.
+ * Unknown fields are skipped with a console warning rather than silently.
+ */
+declare function buildWidgetFilterClauses(dataSource: any, filters?: WidgetFilter[]): any[];
+/**
+ * Column filters → IN clauses (EMPTY when only blanks are ticked).
+ *
+ * The host's `formatHeaderFilters` also maps user names → ids, workflow titles →
+ * ids and humanized durations. Supply it as `runtime.formatHeaderFilters` for
+ * full parity; this built-in covers plain values.
+ */
+declare function buildColumnFilterClauses(dataSource: any, columnFilters?: ColumnFilters): any[];
+/**
+ * Sort → generateQuery's `dashboardSort` + the `configuration.columns` it needs.
+ *
+ * generateQuery matches `configuration.columns[].dataPoint` to a field's header
+ * and then reads `dashboardSort[column.label]`; with no `columns` it throws.
+ * So columns are synthesized from `dataSource.fields` when the config has none.
+ */
+declare function buildRemoteSort(config: any, dataSource: any, sort: SortState | null): {
+    dashboardSort: Record<string, "ASC" | "DESC"> | null;
+    config: any;
+};
+/** Case-insensitive substring search across every cell (and its label). */
+declare function applyLocalSearch(rows: any[], search: string, toLabel?: (v: any) => any): any[];
+/** Keeps rows whose cell matches any ticked value, per column (AND across columns). */
+declare function applyLocalColumnFilters(rows: any[], columnFilters?: ColumnFilters): any[];
+/** Applies widget filters to loaded rows (AND). */
+declare function applyLocalWidgetFilters(rows: any[], filters?: WidgetFilter[]): any[];
+/** Numeric-aware, blanks-last sort. Returns a new array. */
+declare function applyLocalSort(rows: any[], sort: SortState | null): any[];
+/** Distinct values of a column, with counts, for a column-filter dropdown. */
+declare function distinctColumnValues(rows: any[], key: string, toLabel?: (v: any) => any): {
+    value: any;
+    label: string;
+    count: number;
+}[];
+
+interface UseWidgetDataArgs {
+    widgetId?: string | number;
+    widgetType?: string;
+    workflowTypeId?: string | number;
+    title?: string;
+    dataSource?: ZvolvDataSource;
+    configurations?: any;
+    /** Dashboard-level filter state (URL params / ZFilters payload). */
+    dashFilters?: any;
+    /** Dashboard date filters (`cdate`). */
+    cdateFilters?: any[];
+    /**
+     * Raw host-format widget filter state (`{ filter, filter_cond }` from ZFilters).
+     * Prefer `widgetFilters`; this exists for migrated host code.
+     */
+    localFilters?: any;
+    rowLimit?: number;
+    dateGap?: {
+        unit: DateGapUnit;
+        start?: string;
+        end?: string;
+    } | null;
+    /** Rows supplied by an automation binding; when provided, no query is issued. */
+    automationRows?: any[] | null;
+    automationLoading?: boolean;
+    /** Free-text search across all columns. */
+    search?: string;
+    /** Column key → ticked values. */
+    columnFilters?: ColumnFilters;
+    /** Active sort, or null. */
+    sort?: SortState | null;
+    /** Widget-level filters, AND-ed. */
+    widgetFilters?: WidgetFilter[];
+    /** Debounce for remote search, ms. Default 400. */
+    searchDebounceMs?: number;
+}
+/**
+ * Fetches, normalizes and shapes a widget's rows.
+ *
+ * This owns the whole Zvolv data path — query generation, Elasticsearch, pivot
+ * postOperations, summary/series alignment, user-label resolution, date-gap
+ * filling, and viewer interactions (search / column filters / sort / widget
+ * filters, sent to the server or applied locally per `meta.tableMode` /
+ * `meta.filterMode`). It renders nothing: the caller owns the UI.
+ */
+declare function useWidgetData(args: UseWidgetDataArgs): WidgetDataResult;
+
+/**
+ * Value + change props for each viewer interaction.
+ *
+ * Every interaction works both ways:
+ * - uncontrolled — omit the value; pass `default*` to seed it. The widget owns it.
+ * - controlled   — pass the value AND its `on*Change`. You own it (URL, store…).
+ */
+interface InteractionStateProps {
+    search?: string;
+    defaultSearch?: string;
+    onSearchChange?: (search: string) => void;
+    columnFilters?: ColumnFilters;
+    defaultColumnFilters?: ColumnFilters;
+    onColumnFiltersChange?: (columnFilters: ColumnFilters) => void;
+    sort?: SortState | null;
+    defaultSort?: SortState | null;
+    onSortChange?: (sort: SortState | null) => void;
+    widgetFilters?: WidgetFilter[];
+    defaultWidgetFilters?: WidgetFilter[];
+    onWidgetFiltersChange?: (widgetFilters: WidgetFilter[]) => void;
+    /** Fires after any interaction changes, with the full next state. */
+    onInteractionsChange?: (state: WidgetInteractionState) => void;
+}
+/** The live interaction state plus every setter a UI slot needs. */
+interface WidgetInteractions extends WidgetInteractionState {
+    setSearch: (search: string) => void;
+    setColumnFilters: (columnFilters: ColumnFilters) => void;
+    /** Sets one column's ticked values; an empty array clears that column. */
+    setColumnFilter: (key: string, values: any[]) => void;
+    setSort: (sort: SortState | null) => void;
+    /** Cycles a column: none → asc → desc → none. */
+    toggleSort: (key: string) => void;
+    sortDirectionFor: (key: string) => SortDirection | null;
+    setWidgetFilters: (filters: WidgetFilter[]) => void;
+    addWidgetFilter: (filter: WidgetFilter) => void;
+    removeWidgetFilter: (index: number) => void;
+    /** Clears search, column filters, sort and widget filters. */
+    clearAll: () => void;
+    /** True when anything is applied. */
+    active: boolean;
+}
+/**
+ * Headless state for search, column filters, sort and widget filters.
+ *
+ * Feed the returned values to `useWidgetData` (they are the same prop names)
+ * and hand the setters to your own controls. Widgets call this internally;
+ * use it directly only when building a widget from `useWidgetData`.
+ */
+declare function useWidgetInteractions(props?: InteractionStateProps): WidgetInteractions;
+
+/**
+ * Interactive widget layer — wires viewer controls (search, widget filters,
+ * column filters, sort) to the data path, with the UI supplied by the caller.
+ *
+ * Each control has a render slot. Pass your own component and the widget hands
+ * it the current value and setters; applying a value re-queries (remote) or
+ * re-filters loaded rows (local) automatically. Omit a slot and a minimal,
+ * token-styled default is used when that control is enabled.
+ */
+
+/** A field the viewer may filter on, derived from `dataSource.fields`. */
+interface FilterableField {
+    /** Pass this as `WidgetFilter.field`. */
+    field: string;
+    label: string;
+    masterFieldType?: string;
+    kind: "text" | "number" | "date" | "boolean";
+    /** Operators that make sense for this field's type, most useful first. */
+    operators: string[];
+}
+interface SearchSlotArgs {
+    value: string;
+    setValue: (value: string) => void;
+    clear: () => void;
+    placeholder: string;
+    /** "remote" = server-side search (debounced); "local" = filters loaded rows. */
+    mode: "remote" | "local";
+    loading: boolean;
+    tokens: ZvolvTokens;
+}
+interface WidgetFilterSlotArgs {
+    filters: WidgetFilter[];
+    setFilters: (filters: WidgetFilter[]) => void;
+    addFilter: (filter: WidgetFilter) => void;
+    removeFilter: (index: number) => void;
+    clear: () => void;
+    /** Fields that can be filtered, with valid operators per field. */
+    fields: FilterableField[];
+    /** The host's declared filter list (`config.filters`), when present. */
+    declared: any[];
+    mode: "remote" | "local";
+    tokens: ZvolvTokens;
+}
+interface ColumnFilterSlotArgs {
+    column: {
+        key: string;
+        header: string;
+        kind?: string;
+    };
+    selected: any[];
+    setSelected: (values: any[]) => void;
+    clear: () => void;
+    /** Distinct values seen in this column. `value` is what goes in `selected`. */
+    options: {
+        value: any;
+        label: string;
+        count: number;
+    }[];
+    mode: "remote" | "local";
+    tokens: ZvolvTokens;
+}
+interface SortSlotArgs {
+    column: {
+        key: string;
+        header: string;
+        kind?: string;
+    };
+    direction: SortDirection | null;
+    /** none → asc → desc → none */
+    toggle: () => void;
+    setDirection: (direction: SortDirection | null) => void;
+    tokens: ZvolvTokens;
+}
+interface ToolbarSlotArgs {
+    /** The resolved search control (slot or default), or null when disabled. */
+    search: React.ReactNode;
+    /** The resolved widget-filter control (slot or default), or null when disabled. */
+    widgetFilter: React.ReactNode;
+    interactions: WidgetInteractions;
+    tokens: ZvolvTokens;
+}
+/** UI props shared by every data widget. */
+interface InteractionUiProps {
+    /** Show the search box. Default: `config.showSearchbar` / `config.styling.showSearchbar`. */
+    showSearch?: boolean;
+    /** Show the widget-level filter control. Default: `config.showWidgetFilter`, or on when a slot is passed. */
+    showWidgetFilter?: boolean;
+    /** Tables only. Show per-column filters. Default: `config.showColumnFilter` / `config.styling.showColumnFilter`. */
+    showColumnFilter?: boolean;
+    /** Tables only. Click a header to sort. Default: true (`config.enableSort === false` turns it off). */
+    enableSort?: boolean;
+    searchPlaceholder?: string;
+    renderSearch?: (args: SearchSlotArgs) => React.ReactNode;
+    renderWidgetFilter?: (args: WidgetFilterSlotArgs) => React.ReactNode;
+    /** Tables only. Rendered in each filterable header cell. */
+    renderColumnFilter?: (args: ColumnFilterSlotArgs) => React.ReactNode;
+    /** Tables only. Rendered in each sortable header cell. */
+    renderSortIndicator?: (args: SortSlotArgs) => React.ReactNode;
+    /** Replaces the whole header toolbar; receives the resolved controls to place. */
+    renderToolbar?: (args: ToolbarSlotArgs) => React.ReactNode;
+}
+type InteractionProps = InteractionStateProps & InteractionUiProps;
+/** Props every data widget accepts: data args + interaction state + UI slots. */
+type InteractiveWidgetProps = UseWidgetDataArgs & InteractionProps;
+declare function fieldKind(masterFieldType?: string, dataType?: string): FilterableField["kind"];
+declare function operatorsForKind(kind: FilterableField["kind"]): string[];
+/** Every field in `dataSource.fields` as a filterable field. */
+declare function filterableFields(dataSource: any): FilterableField[];
+declare function describeWidgetFilter(f: WidgetFilter): string;
+interface InteractiveWidgetData {
+    data: WidgetDataResult;
+    interactions: WidgetInteractions;
+    config: any;
+    tokens: ZvolvTokens;
+    /** Header toolbar node — pass to `<WidgetShell actions={toolbar}>`. */
+    toolbar: React.ReactNode;
+    /** Extra WidgetShell props (busy / filtered). Spread onto the shell. */
+    shell: {
+        busy: boolean;
+        filtered: boolean;
+    };
+    flags: {
+        showSearch: boolean;
+        showWidgetFilter: boolean;
+        showColumnFilter: boolean;
+        enableSort: boolean;
+    };
+    /** Column-filter options: values seen so far plus currently ticked ones. */
+    getColumnOptions: (key: string) => {
+        value: any;
+        label: string;
+        count: number;
+    }[];
+    /** Header controls (sort indicator + column filter) for one column. Tables use this. */
+    headerControls: (column: {
+        key: string;
+        header: string;
+        kind?: string;
+    }) => React.ReactNode;
+    ui: InteractionUiProps;
+}
+/**
+ * Resolves data + interactions + toolbar for one widget. Widgets call this in
+ * place of `useWidgetData`; custom widgets may too.
+ */
+declare function useInteractiveWidgetData(props: InteractiveWidgetProps & {
+    widgetType: string;
+}, options?: {
+    table?: boolean;
+}): InteractiveWidgetData;
+
+interface KpiWidgetProps extends Omit<InteractiveWidgetProps, "widgetType"> {
+    title?: string;
+    description?: string;
+    emptyMessage?: string;
+    unconfiguredMessage?: string;
+    className?: string;
+    style?: React.CSSProperties;
+    onItemClick?: (vm: any, index: number) => void;
+}
+declare const KpiWidget: React.FC<KpiWidgetProps>;
+
+interface ChartRenderArgs {
+    rows: any[];
+    xKey: string;
+    series: SeriesConfig[];
+    /** Palette colour for series index i, honouring an explicit series.color. */
+    colorFor: (index: number, series?: SeriesConfig) => string;
+    /** Maps an axis value through resolved user labels. */
+    toLabel: (value: any) => any;
+    template: string;
+    config: any;
+    tokens: ReturnType<typeof useTokens>;
+    meta: WidgetDataResult["meta"];
+}
+interface ChartWidgetProps extends Omit<InteractiveWidgetProps, "widgetType"> {
+    widgetType: string;
+    title?: string;
+    description?: string;
+    emptyMessage?: string;
+    unconfiguredMessage?: string;
+    className?: string;
+    style?: React.CSSProperties;
+    /**
+     * Claude's UI. Receives fully-resolved rows + axis keys + palette and returns
+     * the chart. When omitted, a registered template override is used; if there is
+     * none either, the widget renders a minimal built-in fallback.
+     */
+    render?: (args: ChartRenderArgs) => React.ReactNode;
+    children?: (args: ChartRenderArgs) => React.ReactNode;
+}
+/**
+ * Data-complete chart container. It resolves the Zvolv query, rows, series,
+ * axis key, palette and user labels, then hands them to a renderer. It draws
+ * no marks itself — the visual layer is entirely the caller's.
+ */
+declare const ChartWidget: React.FC<ChartWidgetProps>;
+
+type ChartProps = Omit<ChartWidgetProps, "widgetType">;
+/**
+ * Cartesian + categorical charts. Each is ChartWidget with its type bound, so a
+ * `render` prop or a registered template override supplies all the marks.
+ */
+declare const BarChartWidget: React.FC<ChartProps>;
+declare const LineChartWidget: React.FC<ChartProps>;
+declare const AreaChartWidget: React.FC<ChartProps>;
+declare const PieChartWidget: React.FC<ChartProps>;
+declare const DoughnutChartWidget: React.FC<ChartProps>;
+declare const ScatterChartWidget: React.FC<ChartProps>;
+interface RankingRow {
+    rank: number;
+    label: any;
+    value: number;
+    /** value / max, clamped 0..1 — for bar widths. */
+    ratio: number;
+    raw: any;
+}
+interface RankingRenderArgs extends Omit<ChartRenderArgs, "rows"> {
+    rows: RankingRow[];
+    max: number;
+}
+interface RankingBarWidgetProps extends Omit<InteractiveWidgetProps, "widgetType"> {
+    title?: string;
+    description?: string;
+    emptyMessage?: string;
+    unconfiguredMessage?: string;
+    className?: string;
+    style?: React.CSSProperties;
+    render?: (args: RankingRenderArgs) => React.ReactNode;
+}
+/**
+ * Ranked list of categories. Sorting, ranking and ratio math happen here; the
+ * caller renders. `config.ranking` supplies { limit, order, labelField, valueField }.
+ */
+declare const RankingBarWidget: React.FC<RankingBarWidgetProps>;
+interface GaugeRenderArgs {
+    value: number;
+    min: number;
+    max: number;
+    /** (value - min) / (max - min), clamped 0..1. */
+    ratio: number;
+    /** Themed colour for the band the value falls in. */
+    color: string;
+    band: "low" | "medium" | "high";
+    thresholds: {
+        low: number;
+        medium: number;
+        high: number;
+    };
+    config: any;
+    tokens: ReturnType<typeof useTokens>;
+    rows: any[];
+}
+interface GaugeMeterWidgetProps extends Omit<InteractiveWidgetProps, "widgetType"> {
+    title?: string;
+    description?: string;
+    emptyMessage?: string;
+    unconfiguredMessage?: string;
+    className?: string;
+    style?: React.CSSProperties;
+    render?: (args: GaugeRenderArgs) => React.ReactNode;
+}
+/** Single-value gauge. Band resolution is data logic; the dial is yours. */
+declare const GaugeMeterWidget: React.FC<GaugeMeterWidgetProps>;
+interface HeatCell {
+    zone: any;
+    count: number;
+    /** Themed colour for the cell's threshold band. */
+    color: string;
+    band: "low" | "medium" | "high";
+    breakdown: Record<string, any>;
+    raw: any;
+}
+interface HeatMapRenderArgs {
+    cells: HeatCell[];
+    grid: {
+        rows: number;
+        cols: number;
+    };
+    config: any;
+    tokens: ReturnType<typeof useTokens>;
+}
+interface HeatMapWidgetProps extends Omit<InteractiveWidgetProps, "widgetType"> {
+    title?: string;
+    description?: string;
+    emptyMessage?: string;
+    unconfiguredMessage?: string;
+    className?: string;
+    style?: React.CSSProperties;
+    render?: (args: HeatMapRenderArgs) => React.ReactNode;
+}
+/**
+ * Zone/count heat grid. Threshold banding is data logic; cell shape is yours.
+ * `config.heatMap` supplies { grid, thresholds, dataMapping }.
+ */
+declare const HeatMapWidget: React.FC<HeatMapWidgetProps>;
+
+type Tone = "success" | "warning" | "error" | "info" | "neutral" | "primary";
+/** Resolves a semantic tone to its themed colour. Never hardcode a status colour. */
+declare function toneColor(tokens: ZvolvTokens, tone?: Tone): string;
+/** A soft background derived from a tone, for pills and highlight bands. */
+declare function toneSurface(tokens: ZvolvTokens, tone?: Tone, pct?: number): string;
+/**
+ * Maps a free-text status string onto a tone. Zvolv status vocabularies vary by
+ * workspace, so unknown values fall back to neutral rather than guessing.
+ */
+declare function statusTone(status: any): Tone;
+
+/**
+ * One item in a collection widget, with the configured field mapping already
+ * applied. Renderers read these named slots instead of guessing field names.
+ */
+interface CollectionItem {
+    id: string | number;
+    title: any;
+    subtitle?: any;
+    description?: any;
+    value?: any;
+    image?: string;
+    status?: {
+        label: any;
+        tone: ReturnType<typeof statusTone>;
+    };
+    timestamp?: any;
+    /** Extra configured fields, in config order, for detail rows. */
+    fields: {
+        label: string;
+        value: any;
+    }[];
+    raw: any;
+}
+interface CollectionRenderArgs {
+    items: CollectionItem[];
+    template: string;
+    config: any;
+    tokens: ZvolvTokens;
+    toLabel: (v: any) => any;
+    onItemClick?: (item: CollectionItem, index: number) => void;
+}
+interface CollectionWidgetProps extends Omit<InteractiveWidgetProps, "widgetType"> {
+    widgetType: string;
+    title?: string;
+    description?: string;
+    emptyMessage?: string;
+    unconfiguredMessage?: string;
+    className?: string;
+    style?: React.CSSProperties;
+    onItemClick?: (item: CollectionItem, index: number) => void;
+    render?: (args: CollectionRenderArgs) => React.ReactNode;
+}
+/**
+ * The item mapping for a collection widget, from whichever block its platform
+ * config uses: CARDLIST `<template>Configuration`, `activityfeed`, `banner`,
+ * or a gallery/carousel bound through `series[0]` (image = valueField).
+ */
+declare function resolveCollectionMapping(config: any, series?: any[]): any;
+/**
+ * Maps rows to CollectionItems using a config block. Field mapping lives here so
+ * every collection widget resolves the same way and renderers stay presentational.
+ */
+declare function useCollectionItems(rows: any[], mapping: any): CollectionItem[];
+/**
+ * Shared container for every list/card/gallery widget. Resolves rows into named
+ * item slots; the visual arrangement is entirely the renderer's.
+ */
+declare const CollectionWidget: React.FC<CollectionWidgetProps>;
+type Bound = Omit<CollectionWidgetProps, "widgetType">;
+declare const CardListWidget: React.FC<Bound>;
+declare const ActivityFeedWidget: React.FC<Bound>;
+declare const EntityGalleryWidget: React.FC<Bound>;
+declare const GridCardWidget: React.FC<Bound>;
+declare const CarouselWidget: React.FC<Bound>;
+declare const BannerWidget: React.FC<Bound>;
+
+interface TableColumn {
+    key: string;
+    header: string;
+    align?: "left" | "right" | "center";
+    width?: number | string;
+    /** Hint for default cell treatment; a custom renderer may ignore it. */
+    kind?: "text" | "number" | "date" | "status" | "user" | "html";
+}
+interface CellArgs {
+    value: any;
+    row: any;
+    column: TableColumn;
+    rowIndex: number;
+    tokens: ZvolvTokens;
+    toLabel: (v: any) => any;
+}
+interface TableRenderArgs {
+    rows: any[];
+    columns: TableColumn[];
+    toLabel: (v: any) => any;
+    tokens: ZvolvTokens;
+    config: any;
+    /** Default cell content for a column, so a custom renderer can reuse it. */
+    renderCell: (args: CellArgs) => React.ReactNode;
+    onRowClick?: (row: any, index: number) => void;
+    /** Live search / column filter / sort / widget filter state and setters. */
+    interactions: WidgetInteractions;
+    /** Sort indicator + column filter for a header cell (slots or defaults). */
+    headerControls: (column: TableColumn) => React.ReactNode;
+    /** Distinct values for a column-filter dropdown. */
+    getColumnOptions: (key: string) => {
+        value: any;
+        label: string;
+        count: number;
+    }[];
+    /** Whether header sort / column filters are enabled for this table. */
+    enableSort: boolean;
+    showColumnFilter: boolean;
+    /** "remote" = server sorts/filters the full dataset; "local" = loaded rows only. */
+    mode: "remote" | "local";
+}
+interface TableWidgetProps extends Omit<InteractiveWidgetProps, "widgetType"> {
+    widgetType?: string;
+    title?: string;
+    description?: string;
+    columns?: TableColumn[];
+    emptyMessage?: string;
+    unconfiguredMessage?: string;
+    className?: string;
+    style?: React.CSSProperties;
+    onRowClick?: (row: any, index: number) => void;
+    /** Replace a single cell's content, keeping the default table chrome. */
+    cell?: (args: CellArgs) => React.ReactNode;
+    /** Replace the entire table body. */
+    render?: (args: TableRenderArgs) => React.ReactNode;
+}
+/** Derives columns from explicit props, then config, then the first row's shape. */
+declare function useTableColumns(explicit: TableColumn[] | undefined, config: any, rows: any[]): TableColumn[];
+/**
+ * Tabular widgets. Column resolution, field-type mapping and user-label lookup
+ * are data logic; the markup is fully replaceable via `cell` or `render`.
+ */
+declare const TableWidget: React.FC<TableWidgetProps>;
+type BoundTable = Omit<TableWidgetProps, "widgetType">;
+declare const DashboardTableWidget: React.FC<BoundTable>;
+declare const DatabaseTableWidget: React.FC<BoundTable>;
+declare const TaskTrackerTableWidget: React.FC<BoundTable>;
+/**
+ * Child table. The host is responsible for clamping this to the parent body's
+ * visible width — an unclamped child steals the parent's horizontal scroll.
+ */
+declare const ChildTableWidget: React.FC<BoundTable>;
+interface PivotRenderArgs extends TableRenderArgs {
+    rowFields: string[];
+    columnFields: string[];
+    valueFields: string[];
+}
+interface PivotGridWidgetProps extends Omit<BoundTable, "render"> {
+    render?: (args: PivotRenderArgs) => React.ReactNode;
+}
+/**
+ * Pivot grid. The server returns already-pivoted rows, so this resolves the
+ * row/column/value field names and renders them as a table.
+ */
+declare const PivotGridWidget: React.FC<PivotGridWidgetProps>;
+
+/** A scheduled item, normalized from whatever field names the config maps. */
+interface TemporalEvent {
+    id: string | number;
+    title: any;
+    group?: any;
+    start: Date | null;
+    end: Date | null;
+    allDay: boolean;
+    status?: {
+        label: any;
+        tone: Tone;
+    };
+    /** 0..1 progress, when the config maps a progress/percent field. */
+    progress?: number;
+    color?: string;
+    raw: any;
+}
+interface TemporalRenderArgs {
+    events: TemporalEvent[];
+    /** Overall [min, max] span of the events, for laying out a track. */
+    range: {
+        start: Date;
+        end: Date;
+    } | null;
+    /** Events grouped by their `group` value, preserving first-seen order. */
+    lanes: {
+        key: string;
+        label: any;
+        events: TemporalEvent[];
+    }[];
+    template: string;
+    config: any;
+    tokens: ZvolvTokens;
+    toLabel: (v: any) => any;
+    onEventClick?: (event: TemporalEvent, index: number) => void;
+}
+interface TemporalWidgetProps extends Omit<InteractiveWidgetProps, "widgetType"> {
+    widgetType: string;
+    title?: string;
+    description?: string;
+    emptyMessage?: string;
+    unconfiguredMessage?: string;
+    className?: string;
+    style?: React.CSSProperties;
+    onEventClick?: (event: TemporalEvent, index: number) => void;
+    render?: (args: TemporalRenderArgs) => React.ReactNode;
+}
+/**
+ * Normalizes rows into events. Field names come from the config and keep the
+ * zvolv-web spellings (projectTitle/taskTitle/taskStatus/startDate/endDate) so
+ * migrated dashboards map without edits.
+ */
+declare function useTemporalEvents(rows: any[], mapping: any): TemporalEvent[];
+/**
+ * Shared container for timeline / gantt / calendar / scheduler widgets. Event
+ * normalization, range and lane grouping are data logic; the canvas is yours.
+ */
+declare const TemporalWidget: React.FC<TemporalWidgetProps>;
+type BoundTemporal = Omit<TemporalWidgetProps, "widgetType">;
+declare const TimelineWidget: React.FC<BoundTemporal>;
+declare const GanttChartWidget: React.FC<BoundTemporal>;
+declare const CalendarWidget: React.FC<BoundTemporal>;
+declare const MeetingSchedulerWidget: React.FC<BoundTemporal>;
+interface StepItem {
+    index: number;
+    label: any;
+    description?: any;
+    state: "complete" | "current" | "upcoming";
+    status?: {
+        label: any;
+        tone: Tone;
+    };
+    raw: any;
+}
+interface StepperRenderArgs {
+    steps: StepItem[];
+    currentIndex: number;
+    template: string;
+    config: any;
+    tokens: ZvolvTokens;
+    onStepClick?: (step: StepItem) => void;
+}
+interface StepperWidgetProps extends Omit<InteractiveWidgetProps, "widgetType"> {
+    title?: string;
+    description?: string;
+    emptyMessage?: string;
+    unconfiguredMessage?: string;
+    className?: string;
+    style?: React.CSSProperties;
+    onStepClick?: (step: StepItem) => void;
+    render?: (args: StepperRenderArgs) => React.ReactNode;
+}
+/** Process stepper. Config lives under `config.stepper.*`. */
+declare const StepperWidget: React.FC<StepperWidgetProps>;
+
+/**
+ * The chrome envelope every Zvolv widget config carries, independent of type.
+ * Mirrors the keys the ZAI-Dashboard widgets read off `parsedConfig`.
+ */
+interface WidgetChromeConfig {
+    title?: string;
+    description?: string;
+    hideHeader?: boolean;
+    hideTitle?: boolean;
+    showTitle?: boolean;
+    headerIcon?: string;
+    bgColor?: string;
+    color?: string;
+    outlineColor?: string;
+    outlineWidth?: string;
+    showHighlight?: boolean;
+    /** Text shown when the widget is wired but returned no rows. */
+    customMessage?: string;
+    enableFullScreen?: boolean;
+    enableRefreshButtons?: boolean;
+    disableExport?: boolean;
+    style?: WidgetStyleOverrides | null;
+    template?: string;
+    drillDown?: any;
+    drilldown?: any;
+    /** Show the header search box. */
+    showSearchbar?: boolean;
+    /** Show the widget-level filter control. */
+    showWidgetFilter?: boolean;
+    searchPlaceholder?: string;
+    /** Older dashboards nest the toggles here; top-level keys win. */
+    styling?: {
+        showSearchbar?: boolean;
+        showWidgetFilter?: boolean;
+        showColumnFilter?: boolean;
+        [k: string]: any;
+    };
+}
+interface ResolvedChromeConfig {
+    title?: string;
+    description?: string;
+    showHeader: boolean;
+    headerIcon?: string;
+    emptyMessage?: string;
+    showFullScreen: boolean;
+    showRefresh: boolean;
+    showExport: boolean;
+    bgColor?: string;
+    accentColor?: string;
+    outlineColor?: string;
+    outlineWidth?: string;
+    showHighlight: boolean;
+}
+/**
+ * Normalizes the chrome envelope. `hideHeader`/`hideTitle`/`showTitle` are three
+ * spellings of the same idea across different widget generations — an explicit
+ * hide always wins, and `showTitle === false` also suppresses the header.
+ */
+declare function resolveChromeConfig(config?: WidgetChromeConfig): ResolvedChromeConfig;
+/** Drill-down target, however the config spells it. */
+declare function resolveDrillDown(config?: WidgetChromeConfig): any;
+
+interface HtmlRenderArgs {
+    /** Template with {{field}} placeholders already substituted from row 0. */
+    html: string;
+    rows: any[];
+    config: any;
+    tokens: ZvolvTokens;
+}
+interface HtmlWidgetProps extends Omit<InteractiveWidgetProps, "widgetType"> {
+    widgetType?: string;
+    title?: string;
+    description?: string;
+    emptyMessage?: string;
+    unconfiguredMessage?: string;
+    className?: string;
+    style?: React.CSSProperties;
+    /**
+     * REQUIRED to render markup. The package never calls dangerouslySetInnerHTML —
+     * the host owns sanitization (DOMPurify or equivalent). Without this, the raw
+     * template is shown as text.
+     */
+    render?: (args: HtmlRenderArgs) => React.ReactNode;
+}
+/** Substitutes {{field}} / {field} placeholders from a row. */
+declare function interpolate(template: string, row: any): string;
+/**
+ * `{{label}}` substitution driven by `config.variables` — ported from the host
+ * HTMLWidget.getViewText (Angular raw-html parity). A variable reads
+ * rows[0][dataPoint]; a falsy value (0, "", null) falls back to defaultValue.
+ */
+declare function renderHtmlVariables(template: string, rows: any[], variables: any[]): string;
+declare const HtmlWidget: React.FC<HtmlWidgetProps>;
+declare const RawHtmlWidget: React.FC<Omit<HtmlWidgetProps, "widgetType">>;
+interface IframeWidgetProps extends Omit<InteractiveWidgetProps, "widgetType"> {
+    title?: string;
+    description?: string;
+    emptyMessage?: string;
+    unconfiguredMessage?: string;
+    className?: string;
+    style?: React.CSSProperties;
+    render?: (args: {
+        url: string;
+        config: any;
+        tokens: ZvolvTokens;
+    }) => React.ReactNode;
+}
+declare const IframeWidget: React.FC<IframeWidgetProps>;
+interface MapMarker {
+    id: string | number;
+    lat: number;
+    lng: number;
+    label?: any;
+    raw: any;
+}
+interface MapRenderArgs {
+    markers: MapMarker[];
+    center: {
+        lat: number;
+        lng: number;
+    } | null;
+    zoom: number;
+    config: any;
+    tokens: ZvolvTokens;
+}
+interface MapWidgetProps extends Omit<InteractiveWidgetProps, "widgetType"> {
+    title?: string;
+    description?: string;
+    emptyMessage?: string;
+    unconfiguredMessage?: string;
+    className?: string;
+    style?: React.CSSProperties;
+    /** Required to draw a map — the package does not bundle a maps SDK. */
+    render?: (args: MapRenderArgs) => React.ReactNode;
+}
+/** Resolves lat/lng markers from rows. Rendering needs a maps SDK you supply. */
+declare const GoogleMapWidget: React.FC<MapWidgetProps>;
+interface ActionItem {
+    id: string | number;
+    label: any;
+    icon?: string;
+    actionType?: string;
+    disabled?: boolean;
+    raw: any;
+}
+interface ActionRenderArgs {
+    actions: ActionItem[];
+    config: any;
+    tokens: ZvolvTokens;
+    onAction?: (action: ActionItem) => void;
+}
+interface ActionCardWidgetProps extends Omit<InteractiveWidgetProps, "widgetType"> {
+    title?: string;
+    description?: string;
+    emptyMessage?: string;
+    unconfiguredMessage?: string;
+    className?: string;
+    style?: React.CSSProperties;
+    /** The host performs the action (new submission, popup, external link…). */
+    onAction?: (action: ActionItem) => void;
+    render?: (args: ActionRenderArgs) => React.ReactNode;
+}
+declare const ActionCardWidget: React.FC<ActionCardWidgetProps>;
+interface TreeNode {
+    key: string;
+    label: any;
+    children: TreeNode[];
+    depth: number;
+    raw: any;
+}
+interface TreeRenderArgs {
+    nodes: TreeNode[];
+    config: any;
+    tokens: ZvolvTokens;
+    onNodeClick?: (node: TreeNode) => void;
+}
+interface TreeWidgetProps extends Omit<InteractiveWidgetProps, "widgetType"> {
+    title?: string;
+    description?: string;
+    emptyMessage?: string;
+    unconfiguredMessage?: string;
+    className?: string;
+    style?: React.CSSProperties;
+    onNodeClick?: (node: TreeNode) => void;
+    render?: (args: TreeRenderArgs) => React.ReactNode;
+}
+/** Builds a tree from flat parent-keyed rows. Orphans are promoted to roots. */
+declare function buildTree(rows: any[], idField: string, parentField: string, labelField: string): TreeNode[];
+declare const TreeWidget: React.FC<TreeWidgetProps>;
+
+/**
+ * Form schema types — the platform's form definition after normalisation.
+ * Ported from ZAI-Dashboard `src/forms/types.ts` (itself a port of Angular
+ * z-form). Both the v2 camelCase schema and the legacy PascalCase schema
+ * normalise to this one shape.
+ */
+type FormMode = "NEW" | "EDIT" | "DISABLED" | "NEW_DO_NOT_SUBMIT";
+interface FormElement {
+    elementId: string;
+    /** Legacy numeric id (FormElementID) — the key legacy submissions use. */
+    id?: string;
+    label: string;
+    /** The stored type. Use `resolveFieldType` for routing (applies subType). */
+    type: string;
+    defaultValue?: any;
+    required: boolean;
+    disabled: boolean;
+    hidden: boolean;
+    unique?: boolean;
+    /** Grid span out of 24 (a stored Width of 50% → 12). */
+    width: number;
+    widthSpecified: boolean;
+    hideLabel: boolean;
+    dataType?: string;
+    properties: Record<string, any>;
+    attributes: Record<string, any>;
+    validations?: any[];
+    dependencies?: any;
+}
+interface FormDefinition {
+    /** The id submissions are posted against (24-hex v2 id, or legacy numeric id). */
+    uuid: string;
+    title: string;
+    description?: string;
+    type: string;
+    elements: FormElement[];
+    allowDraft: boolean;
+    configurations: Record<string, any>;
+    hideSubmit: boolean;
+    hideFormTitle: boolean;
+    successMsg: string | null;
+    warningMsg: string | null;
+}
+type FormValues = Record<string, any>;
+type FormErrors = Record<string, string | undefined>;
+interface FieldOption {
+    label: string;
+    value: any;
+    /** Extra columns pulled from a lookup row (ExtraLabels). */
+    extra?: string[];
+    color?: string;
+    /** The stored shape for relational fields: { view, select, extraLabels }. */
+    raw?: any;
+}
+/**
+ * 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" | "trials" | "system" | "unknown";
+
+/** Types never sent in a submission body. */
+declare const SUBMISSION_SKIP_TYPES: Set<string>;
+declare function getEmptyValue(type: string): any;
+/** `'a|||b'`, scalars and option objects → the {view, select, extraLabels} shape. */
+declare function toRelational(el: FormElement, raw: any): any;
+/**
+ * Initial values: explicit defaults win, then a loaded submission value, then
+ * the element's defaultValue / dynamicDefault, then the type's empty value.
+ */
+declare function buildInitialValues(elements: FormElement[], opts?: {
+    defaults?: FormValues;
+    submission?: FormValues;
+    user?: any;
+}): FormValues;
+/** One element's value in the POST/PUT /api/v1/submissions body. */
+declare function serializeElementValue(el: FormElement, value: any): any;
+/** Sheet rows → their child submission ids. */
+declare function rowSubmissionIds(raw: any): string[];
+/** `elements[]` for POST/PUT /api/v1/submissions. */
+declare function buildSubmissionElements(elements: FormElement[], values: FormValues): any[];
+/**
+ * Flat `{ formID, formSubmissionId, <elementId>: value }` body for automation
+ * triggers — intentionally looser than the submission format (Angular parity).
+ */
+declare function buildTriggerBody(elements: FormElement[], values: FormValues, opts?: {
+    formId?: string;
+    submissionId?: string | null;
+    byLabel?: boolean;
+}): Record<string, any>;
+/** Human-readable value, for read-only views and summaries. */
+declare function formatFieldValue(el: FormElement, value: any): string;
+
+/**
+ * Form transport — every network call the form engine makes, against the
+ * logged-in @zestl/zvolv-js-sdk client. Endpoints and bodies are ported from
+ * ZAI-Dashboard `formApi.ts` / `FormSearchField.tsx` / `FileUploadField.tsx`.
+ */
+
+declare const isLegacyId: (id: any) => boolean;
+declare function fetchForm(client: any, formId: string): Promise<FormDefinition>;
+/** EDIT / DISABLED: the submission carries its own element list plus values. */
+declare function fetchSubmission(client: any, submissionId: string): Promise<{
+    form: FormDefinition | null;
+    values: FormValues;
+}>;
+interface SubmitOptions {
+    skipAutomation?: boolean;
+    skipValidations?: boolean;
+    parentSubmissionId?: string;
+}
+/** Pulls the created submission id out of either API generation's response. */
+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;
+    media: string;
+    media_size: number;
+    mediaKey?: string;
+    [k: string]: any;
+}
+/** UPLOAD_FILE_IMAGE with a cardID → dbFileUpload; otherwise the SDK's mediaUpload. */
+declare function uploadFile(client: any, el: FormElement, file: File, zappId?: string): Promise<UploadedFile>;
+interface LookupConfig {
+    formId: string;
+    viewLabel?: string;
+    selectLabel?: string;
+    searchLabel?: string;
+    extraLabels: string[];
+    staticFilters: any[];
+    dynamicFilters: any[];
+    maxResults: number;
+    operator: "$and" | "$or";
+    loadOnDependency: boolean;
+    colorLabel?: string;
+}
+declare function lookupConfigOf(el: FormElement): LookupConfig | null;
+interface LookupFilter {
+    label: string;
+    value: any;
+    arr_value: any[];
+    operator: "eq" | "in" | "regex";
+    mode?: string;
+}
+/** Options from the source form (getSubmissionAll) — eq/in filters re-applied client-side. */
+declare function fetchLookupOptions(client: any, cfg: LookupConfig, dependency: LookupFilter[], search?: string, maxAgeMs?: number): Promise<FieldOption[]>;
+declare function clearLookupCache(): void;
+declare function searchPeople(client: any, el: FormElement, query: string): Promise<FieldOption[]>;
+
+/**
+ * useZvolvForm — the headless form engine. Zvolv owns loading, values,
+ * show/hide/mandatory rules, formulas, validation, field automations, action
+ * buttons, child sheets and the submit wire format; the host draws every
+ * control from the `FormField` descriptors it returns.
+ */
+
+interface FormField {
+    id: string;
+    /** Routing type (subType applied), e.g. "INPUT_CURRENCY". */
+    type: string;
+    kind: FieldKind;
+    label: string;
+    hideLabel: boolean;
+    placeholder?: string;
+    /** Help text under the field (attributes.helpMsg / infoMsg). */
+    help?: string;
+    required: boolean;
+    disabled: boolean;
+    hidden: boolean;
+    /** Grid span out of 24. */
+    span: number;
+    value: any;
+    /** Set from the last submit / validate(); cleared when this field's value changes. */
+    error?: string;
+    touched: boolean;
+    /** Static options (SPINNER / RADIO_GROUP / static AUTO_COMPLETE). Lookups use useFieldOptions. */
+    options: FieldOption[];
+    multiple: boolean;
+    allowAddOptions: boolean;
+    min?: number;
+    max?: number;
+    step?: number;
+    precision?: number;
+    prefix?: string;
+    suffix?: string;
+    /** For file fields: accept string, max size (KB) and max count. */
+    accept?: string;
+    maxSizeKB?: number;
+    maxCount?: number;
+    /** Ids of fields a container holds, in order. */
+    childIds: string[];
+    /** STEPPER / TAB pages. */
+    pages?: {
+        title: string;
+        description?: string;
+        fieldIds: string[];
+    }[];
+    /** TEXT_VIEW / HTML_TEXT content (HTML). */
+    html?: string;
+    /**
+     * Visual intent: action buttons (primary / outline); checkbox "switch" when
+     * attributes.showAsSwitch is set (ZAI CheckboxField / zvolv-web nz-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. */
+    dateFormat?: string;
+    /** Character limit (properties.maxLength / max, or attributes.charactersCount for rich text). */
+    maxLength?: number;
+    element: FormElement;
+    setValue: (value: any) => void;
+    onBlur: () => void;
+}
+type FormStatus = "loading" | "ready" | "error" | "submitted";
+interface ActionOutcome {
+    ok: boolean;
+    message?: string;
+}
+interface UseZvolvFormArgs {
+    formId?: string;
+    mode?: FormMode;
+    submissionId?: string | null;
+    /** Supply the schema yourself (raw platform JSON or a FormDefinition) to skip the fetch. */
+    definition?: any;
+    /** Initial values keyed by elementId or label. */
+    defaultValues?: FormValues;
+    /** Field ids (or labels) never shown. */
+    hiddenFields?: string[];
+    /** Element types never shown, e.g. ["COMMENTS"]. */
+    skipTypes?: string[];
+    skipAutomation?: boolean;
+    skipValidations?: boolean;
+    zappId?: string;
+    onSubmitted?: (result: {
+        submissionId: string | null;
+        response: any;
+        values: FormValues;
+    }) => void;
+    /**
+     * Action buttons whose effect belongs to the host (open another form, a task,
+     * a print preview …). Return an outcome, or undefined when not handled.
+     */
+    onAction?: (field: FormField, form: ZvolvFormApi) => Promise<ActionOutcome | void> | ActionOutcome | void;
+}
+interface ZvolvFormApi {
+    status: FormStatus;
+    error: Error | null;
+    definition: FormDefinition | null;
+    mode: FormMode;
+    readOnly: boolean;
+    values: FormValues;
+    errors: FormErrors;
+    /** Every field, resolved. */
+    fields: FormField[];
+    /** Visible top-level fields in order (containers hold the rest). */
+    rootFields: FormField[];
+    field: (id: string) => FormField | undefined;
+    childrenOf: (field: FormField | string, visibleOnly?: boolean) => FormField[];
+    setValue: (id: string, value: any) => void;
+    /** Writes a map keyed by elementId, label or legacy id (automation formData). */
+    applyValues: (data: Record<string, any>) => void;
+    dirty: boolean;
+    submitting: boolean;
+    submitAttempted: boolean;
+    submitError: string | null;
+    submittedId: string | null;
+    validate: (ids?: string[]) => boolean;
+    submit: () => Promise<{
+        submissionId: string | null;
+        response: any;
+    } | null>;
+    reset: () => void;
+    /**
+     * 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
+ * `FormKitSlot` (or the `kit` prop). The built-in kit is deliberately plain
+ * native HTML so a form still works when no kit is provided.
+ */
+
+interface FormKit {
+    /** Draw one field (any kind, containers included). Return undefined to use the built-in control. */
+    field?: (field: FormField, form: ZvolvFormApi) => React.ReactNode | undefined;
+    /** Draw the whole form: header, body and footer. Default: <FormFields> + submit bar. */
+    form?: (form: ZvolvFormApi, parts: {
+        body: React.ReactNode;
+        title?: string;
+        submitLabel: string;
+    }) => React.ReactNode;
+    /** Loading / error / submitted screens. Return undefined for the default. */
+    status?: (args: {
+        status: "loading" | "error" | "submitted";
+        form: ZvolvFormApi;
+    }) => React.ReactNode | undefined;
+    /** Grid wrapper for a list of fields (24-column spans). */
+    grid?: (children: React.ReactNode, fields: FormField[]) => React.ReactNode;
+}
+declare const FormKitSlot: React.Context<FormKit | null>;
+/** Renders fields in a 24-column grid with the active kit. Use it inside section / tab renderers. */
+declare const FormFields: React.FC<{
+    form: ZvolvFormApi;
+    fields: FormField[];
+    kit?: FormKit;
+}>;
+interface ZvolvFormProps extends UseZvolvFormArgs {
+    /** Heading above the form; defaults to the form's own title unless hidden in its config. */
+    title?: string | false;
+    submitLabel?: string;
+    kit?: FormKit;
+    className?: string;
+    style?: React.CSSProperties;
+    /** Receive the api (e.g. to put a submit button elsewhere). */
+    formRef?: React.MutableRefObject<ZvolvFormApi | null>;
+}
+declare const ZvolvForm: React.FC<ZvolvFormProps>;
+declare const DefaultField: React.FC<{
+    field: FormField;
+    form: ZvolvFormApi;
+}>;
+
+interface TabItem {
+    key: string;
+    label: any;
+    /** The child widget definition this tab hosts, rendered by the host app. */
+    widget: any;
+}
+interface TabRenderArgs {
+    tabs: TabItem[];
+    activeKey: string;
+    setActiveKey: (key: string) => void;
+    tokens: ZvolvTokens;
+    config: any;
+}
+interface TabWidgetProps {
+    title?: string;
+    description?: string;
+    configurations?: any;
+    className?: string;
+    style?: React.CSSProperties;
+    /** Renders one tab's child widget. The host owns widget dispatch. */
+    renderChild?: (widget: any, tab: TabItem) => React.ReactNode;
+    render?: (args: TabRenderArgs) => React.ReactNode;
+}
+/**
+ * Tab container. It holds no data of its own — it arranges child widget
+ * definitions, which the host renders via `renderChild`.
+ */
+declare const TabWidget: React.FC<TabWidgetProps>;
+interface FormWidgetProps {
+    title?: string;
+    description?: string;
+    configurations?: any;
+    dataSource?: any;
+    className?: string;
+    style?: React.CSSProperties;
+    /** Extra <ZvolvForm> props (kit, onSubmitted, onAction, defaultValues …). */
+    form?: Partial<ZvolvFormProps>;
+    onSubmitted?: ZvolvFormProps["onSubmitted"];
+    /**
+     * Replace the form body entirely. Without it the widget renders <ZvolvForm>,
+     * styled by the nearest FormKitSlot.
+     */
+    render?: (args: {
+        formId: any;
+        submissionId: any;
+        mode: "NEW" | "EDIT" | "DISABLED";
+        config: any;
+        tokens: ZvolvTokens;
+    }) => React.ReactNode;
+}
+/** Resolves the form a FORM / FORM_WIDGET config points at. */
+declare function resolveFormWidget(config: any, dataSource?: any): {
+    formId: string | null;
+    submissionId: any;
+    mode: "NEW" | "EDIT" | "DISABLED";
+};
+/** Form widget: the headless form engine inside widget chrome. */
+declare const FormWidget: React.FC<FormWidgetProps>;
+interface FilterControl {
+    key: string;
+    label: any;
+    type: "text" | "select" | "multiselect" | "date" | "daterange" | "number";
+    options?: {
+        label: any;
+        value: any;
+    }[];
+    value?: any;
+}
+interface FilterPanelRenderArgs {
+    controls: FilterControl[];
+    values: Record<string, any>;
+    setValue: (key: string, value: any) => void;
+    apply: () => void;
+    reset: () => void;
+    tokens: ZvolvTokens;
+    config: any;
+}
+interface FilterPanelWidgetProps {
+    title?: string;
+    configurations?: any;
+    className?: string;
+    style?: React.CSSProperties;
+    /** Current filter values, owned by the dashboard (URL params). */
+    value?: Record<string, any>;
+    onChange?: (values: Record<string, any>) => void;
+    render?: (args: FilterPanelRenderArgs) => React.ReactNode;
+}
+/**
+ * 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
+ * changes, and never issues queries itself.
+ */
+declare const FilterPanelWidget: React.FC<FilterPanelWidgetProps>;
+interface ZaiChatWidgetProps {
+    title?: string;
+    configurations?: any;
+    className?: string;
+    style?: React.CSSProperties;
+    /**
+     * REQUIRED. The chat transport must stay byte-compatible with the existing
+     * send body, so the host owns it; this only supplies chrome and tokens.
+     */
+    render?: (args: {
+        config: any;
+        tokens: ZvolvTokens;
+    }) => React.ReactNode;
+}
+declare const ZaiChatWidget: React.FC<ZaiChatWidgetProps>;
+
+/**
+ * Every Zvolv widget type string → component. Aliases (BAR/BAR_CHART,
+ * HTML/RAW_HTML/STATICHTML …) map to the same component, matching how the
+ * dashboard config stores them across generations.
+ */
+declare const WIDGET_REGISTRY: Record<string, React.FC<any>>;
+/** Types that never render as a grid widget (filters and data bindings). */
+declare const NON_RENDERING_TYPES: Set<string>;
+declare function resolveWidget(type?: string): React.FC<any> | null;
+interface ZvolvWidgetProps {
+    type: string;
+    [key: string]: any;
+}
+/** Renders any widget by its Zvolv type string. */
+declare const ZvolvWidget: React.FC<ZvolvWidgetProps>;
+
+interface UseKpiContentsArgs {
+    contents: any[];
+    rows: any[];
+    cardTemplate?: KpiTemplateId;
+    /** Externally-fetched series keyed by content index (e.g. a history-form time series). */
+    externalSeriesByIndex?: Record<number, number[]>;
+    /** Fallback icon colour when a content item does not set one. */
+    defaultIconColor?: string;
+    dateFormatter?: (value: string, format: string) => string | null;
+}
+/**
+ * Resolves raw KPI config + fetched rows into per-item view-models.
+ *
+ * The value/target/format resolution (the "00"→0 normalization, AMOUNT/DATE/precision
+ * branches, target truthy resolution, prefix/suffix maps) is ported verbatim from the
+ * ZAI-Dashboard KPI card so numbers match the Angular original exactly.
+ */
+declare function useKpiContents({ contents, rows, cardTemplate, externalSeriesByIndex, defaultIconColor, dateFormatter, }: UseKpiContentsArgs): KpiContentVM[];
+
+/**
+ * Mirrors Angular getResult() for postOperations.
+ * Ported verbatim from ZAI-Dashboard src/widgets/kpi/formatters.ts — do not
+ * re-derive; the operand semantics here match the server's aggregation output.
+ */
+declare function getPostOpResult(row: any, operator: string, operands: any[]): number;
+/**
+ * Applies pivot `postOperations` to each fetched row, writing the derived value
+ * onto `row[op.title]` so it's available for a series' valueField lookup.
+ */
+declare function applyPostOperations(rows: any[], postOperations?: any[]): any[];
+/**
+ * The set of every summary field referenced as a postOperation operand. Summary
+ * entries in this set are intermediate feeds (e.g. "Total Status Count" deriving
+ * "Incomplete = Total − Completed") and must keep their original agg output name —
+ * renaming them to a series valueField breaks the operand lookup in getPostOpResult.
+ */
+declare function getPostOpOperandSet(postOperations?: any[]): Set<string>;
+/**
+ * Aligns each summary agg's output name with its series valueField so the SDK maps
+ * the aggregated value onto the right key. Only `value` (the agg name) is touched —
+ * title/masterFieldDataType/masterFieldType/type describe WHICH field is aggregated
+ * and HOW, and must stay as the metric field (e.g. Population/FLOAT/sum). Overwriting
+ * them turned a sum(Population) into a value_count(State.keyword).
+ *
+ * Summary entries referenced as postOperations operands are intermediate values with
+ * no series of their own — renaming them positionally broke the operand lookup and
+ * silently zeroed out the subtraction, so those are left untouched.
+ */
+declare function alignSummaryToSeries(dataSource: any, series: any[]): any;
+
+declare const PREFIX_UNITS: Record<string, string>;
+declare const SUFFIX_UNITS: Record<string, string>;
+/** Mirrors Angular formatAmountValue() from dashboards.utils */
+declare function formatAmountValue(value: number, suffix?: string, precision?: number): string;
+declare function toNum(v: any): number | null;
+/** Compact axis/label formatting: 1.2K, 3.4M, 1.1B. */
+declare function formatCompact(value: any): string;
+
+/** Config may arrive as a JSON string from the server — parse defensively. */
+declare function parseConfig(configurations: any): WidgetConfigurations;
+/**
+ * The configured series. Stored widgets spell it `series` (React dashboards) or
+ * `serieses` (Angular-era dashboards) — both are read, `series` first.
+ */
+declare function resolveSeries(config: WidgetConfigurations): SeriesConfig[];
+declare function resolveXKey(series: SeriesConfig[]): string;
+/**
+ * A null/empty DataSource parses to {} — that is NOT "configured". Widgets must
+ * show the unconfigured empty state rather than falling back to demo data.
+ */
+declare function isDataSourceConfigured(dataSource: any): boolean;
+declare function usesFormFramework(dataSource: ZvolvDataSource): boolean;
+
+/**
+ * Typed config schemas — the authoring surface for writing widget configs in code.
+ *
+ * These describe the server's shape. Every field is optional because real configs
+ * are sparse, and unknown keys are preserved: widen, never narrow, a config you
+ * did not author.
+ */
+
+interface AxisConfig {
+    title?: string;
+    valueFormat?: string;
+    /** Rotate/hide long category labels. */
+    labelRotation?: number;
+    showLabels?: boolean;
+    min?: number;
+    max?: number;
+}
+interface LegendConfig {
+    show?: boolean;
+    position?: "top" | "bottom" | "left" | "right";
+    showLabels?: boolean;
+}
+interface ChartConfig extends WidgetChromeConfig {
+    template?: string;
+    series?: SeriesConfig[];
+    axis?: {
+        argumentAxis?: AxisConfig;
+        valueAxis?: AxisConfig;
+    };
+    legends?: LegendConfig;
+    sortOrder?: "none" | "asc" | "desc";
+    stackOrder?: "none" | "asc" | "desc";
+    /** Insert zero rows for empty periods so a time axis reads continuously. */
+    fillDateGaps?: boolean;
+    dateGapUnit?: "day" | "week" | "month";
+}
+interface KpiContentConfig {
+    title?: string;
+    subtitle?: string;
+    /** Field whose value this item displays. */
+    dataPoint?: string;
+    targetPoint?: string;
+    defaultVale?: any;
+    template?: KpiTemplateId;
+    dataFormat?: "AMOUNT" | "DATE" | "NUMBER";
+    amountSuffix?: "Rupees" | "Lakhs" | "Crores" | "Millions";
+    dateFormat?: string;
+    precision?: number;
+    unit?: string;
+    icon?: string;
+    iconColor?: string;
+    valueColor?: string;
+    deltaSource?: "target" | "datapoint";
+    deltaPoint?: string;
+    deltaMode?: "percent" | "absolute";
+    invertColors?: boolean;
+    maxSource?: "value" | "datapoint";
+    maxPoint?: string;
+    progressMax?: number;
+    statusMap?: Record<string, {
+        label?: string;
+        tone?: string;
+        description?: string;
+    }>;
+    statusFallbackTone?: string;
+    seriesPoints?: string[];
+    seriesPoint?: string;
+    seriesSource?: {
+        mode?: "timeseries" | "fields";
+        [k: string]: any;
+    };
+}
+interface KpiConfig extends WidgetChromeConfig {
+    template?: KpiTemplateId;
+    contents?: KpiContentConfig[];
+}
+interface TableColumnConfig {
+    key?: string;
+    masterfield?: string;
+    field?: string;
+    header?: string;
+    title?: string;
+    align?: "left" | "right" | "center";
+    width?: number | string;
+    hidden?: boolean;
+    masterFieldType?: string;
+    kind?: "text" | "number" | "date" | "status" | "user" | "html";
+}
+interface TableConfig extends WidgetChromeConfig {
+    columns?: TableColumnConfig[];
+    pageSize?: number;
+    /** Per-column value filters in the header. */
+    showColumnFilter?: boolean;
+    /** Click-to-sort headers. Default true. */
+    enableSort?: boolean;
+}
+interface CollectionMappingConfig {
+    titleField?: string;
+    subtitleField?: string;
+    descriptionField?: string;
+    valueField?: string;
+    imageField?: string;
+    statusField?: string;
+    dateField?: string;
+    fields?: {
+        field?: string;
+        label?: string;
+    }[];
+}
+interface CollectionConfig extends WidgetChromeConfig {
+    template?: string;
+    cardConfiguration?: CollectionMappingConfig;
+    mapping?: CollectionMappingConfig;
+}
+interface TemporalMappingConfig {
+    /** zvolv-web spellings are preserved so migrated dashboards map unchanged. */
+    taskTitle?: string;
+    projectTitle?: string;
+    taskStatus?: string;
+    startDate?: string;
+    endDate?: string;
+    titleField?: string;
+    groupField?: string;
+    statusField?: string;
+    progressField?: string;
+    colorField?: string;
+}
+interface TemporalConfig extends WidgetChromeConfig {
+    template?: string;
+    timeline?: TemporalMappingConfig;
+    gantt?: TemporalMappingConfig;
+    calendar?: TemporalMappingConfig;
+    scheduler?: TemporalMappingConfig;
+}
+interface StepperConfig extends WidgetChromeConfig {
+    template?: string;
+    stepper?: {
+        steps?: any[];
+        labelField?: string;
+        descriptionField?: string;
+        statusField?: string;
+        currentIndex?: number;
+    };
+}
+interface GaugeConfig extends WidgetChromeConfig {
+    gauge?: {
+        valueField?: string;
+        min?: number;
+        max?: number;
+        thresholds?: {
+            low?: number;
+            medium?: number;
+            high?: number;
+        };
+    };
+}
+interface HeatMapConfig extends WidgetChromeConfig {
+    heatMap?: {
+        grid?: {
+            rows?: number;
+            cols?: number;
+        };
+        thresholds?: {
+            low?: {
+                value?: number;
+                color?: string;
+            };
+            medium?: {
+                value?: number;
+                color?: string;
+            };
+            high?: {
+                value?: number;
+                color?: string;
+            };
+        };
+        dataMapping?: {
+            zoneField?: string;
+            countField?: string;
+            breakdownFields?: string[];
+        };
+    };
+}
+interface RankingConfig extends WidgetChromeConfig {
+    ranking?: {
+        labelField?: string;
+        valueField?: string;
+        order?: "asc" | "desc";
+        limit?: number;
+    };
+}
+interface TreeConfig extends WidgetChromeConfig {
+    tree?: {
+        idField?: string;
+        parentField?: string;
+        labelField?: string;
+    };
+}
+interface MapConfig extends WidgetChromeConfig {
+    map?: {
+        latField?: string;
+        lngField?: string;
+        labelField?: string;
+        centerLat?: number;
+        centerLng?: number;
+        zoom?: number;
+    };
+}
+interface HtmlConfig extends WidgetChromeConfig {
+    /** Supports {{field}} placeholders, substituted from the first row. */
+    html?: string;
+    content?: string;
+}
+interface IframeConfig extends WidgetChromeConfig {
+    url?: string;
+    sandbox?: string;
+}
+interface ActionConfig extends WidgetChromeConfig {
+    actions?: {
+        id?: string | number;
+        label?: string;
+        icon?: string;
+        actionType?: string;
+        disabled?: boolean;
+        [k: string]: any;
+    }[];
+}
+interface TabConfig extends WidgetChromeConfig {
+    tabs?: {
+        key?: string;
+        label?: string;
+        widget?: any;
+    }[];
+}
+interface FormConfig extends WidgetChromeConfig {
+    formId?: string | number;
+    submissionId?: string | number | null;
+    mode?: "NEW" | "EDIT" | "DISABLED";
+}
+interface FilterPanelConfig extends WidgetChromeConfig {
+    filters?: {
+        key?: string;
+        field?: string;
+        label?: string;
+        type?: "text" | "select" | "multiselect" | "date" | "daterange" | "number";
+        options?: {
+            label: any;
+            value: any;
+        }[];
+    }[];
+}
+/** A complete widget definition as a dashboard stores it. */
+interface WidgetDefinition<TConfig = any> {
+    WidgetID?: string | number;
+    Type: string;
+    Title?: string;
+    DataSource?: ZvolvDataSource | string | null;
+    Configurations?: TConfig | string | null;
+    WorkflowTypeID?: string | number;
+}
+/** Identity helper: gives a config literal its type without widening. */
+declare function defineConfig<T>(config: T): T;
+
+/** JSON-parses until the value is no longer a string (handles double encoding). */
+declare function parseDeep(raw: any): any;
+interface NormalizedWidget {
+    id: string;
+    type: string;
+    title?: string;
+    description?: string;
+    configurations: any;
+    dataSource: any;
+    workflowTypeId?: string | number;
+    raw: any;
+}
+/** A stored widget → the props every @zestl/zvolv-widgets component takes. */
+declare function normalizeWidget(widget: any): NormalizedWidget;
+/**
+ * Widgets that render as grid tiles: drops filter/automation types and
+ * widgets nested inside a TAB's `childWidget` (the tab renders those).
+ */
+declare function gridWidgets(widgets: any[]): any[];
+declare const GRID: {
+    readonly COLS: 60;
+    /** Row unit in px. A tile's height = h * ROW_HEIGHT + (h - 1) * GAP. */
+    readonly ROW_HEIGHT: 5;
+    readonly GAP: 16;
+    /** Layouts saved before grid v2 used 12 columns. */
+    readonly VERSION: 2;
+    readonly LEGACY_SCALE: 5;
+};
+interface GridItem {
+    id: string;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/**
+ * Grid positions from each widget's `Configuration.additionalProperties`, with
+ * legacy 12-col layouts scaled up and unset positions packed row by row, then
+ * compacted vertically like react-grid-layout (`compactType="vertical"`).
+ */
+declare function resolveDashboardLayout(widgets: any[]): GridItem[];
+/** Pixel height of a tile `h` rows tall. */
+declare function gridHeight(h: number): number;
+/** One control in the dashboard filter bar (from the FILTER widget's config). */
+interface DashboardFilterDef {
+    label: string;
+    formId?: any;
+    formTitle: string;
+    fieldLabel: string;
+    fieldType?: string;
+}
+/** The dashboard's FILTER widget's declared filters, if it has one. */
+declare function dashboardFilterDefs(widgets: any[]): DashboardFilterDef[];
+interface DashboardFilterValue {
+    formTitle: string;
+    fieldLabel: string;
+    operator: string;
+    values: any[];
+}
+interface DateRange {
+    start: string;
+    end: string;
+}
+/**
+ * Builds the `dashFilters` object every widget takes — the same shape the host
+ * derives from its `filters` / `operator` / `cdate` URL params.
+ */
+declare function buildDashFilters(values?: DashboardFilterValue[], dateRange?: DateRange | null, operator?: "AND" | "OR"): any;
+type DateRangeToken = "TODAY" | "LAST_7_DAYS" | "LAST_30_DAYS" | "THIS_MONTH" | "LAST_MONTH" | "THIS_YEAR";
+declare function dateRangeFor(token: DateRangeToken | string): DateRange;
+/** The DATE_FILTER widget's default range token, if the dashboard has one. */
+declare function dashboardDefaultDateToken(widgets: any[]): string | null;
+/**
+ * The per-widget `cdateFilters` — which of its fields a dashboard date range
+ * lands on. Explicit DATE_FILTER mappings win; otherwise the widget's own date
+ * field is picked (task sources by column name).
+ */
+declare function cdateFiltersFor(widget: any, allWidgets: any[]): any[];
+interface DashboardNode {
+    id: string;
+    title: string;
+    raw: any;
+    children: DashboardNode[];
+}
+/** Strips the `<i class="…"></i>` icon tag some dashboard titles carry. */
+declare function cleanTitle(title: any): string;
+/**
+ * `getDashboards()` elements → a sorted tree (ChildReportIDs nest), hiding
+ * MobileOnly / HideInMobileApp dashboards from non-admins.
+ */
+declare function buildDashboardTree(elements: any[], isAdmin?: boolean): DashboardNode[];
+
+interface FieldOptionsState {
+    options: FieldOption[];
+    loading: boolean;
+    error: string | null;
+    search: string;
+    setSearch: (q: string) => void;
+    /** Set when a dependency must be filled first, e.g. "Select Region first". */
+    waitingFor: string | null;
+    /** The field's current selection as options (resolves stored ids to labels). */
+    selected: FieldOption[];
+    /** Commit a pick: stores the right shape for the field type. */
+    select: (option: FieldOption | FieldOption[] | null) => void;
+    /** Toggle one option in a multi-select (refused once `maxCount` is reached). */
+    toggle: (option: FieldOption) => void;
+    isSelected: (option: FieldOption) => boolean;
+    /**
+     * Call when the control gets focus / opens. Remote options (lookups, people
+     * search) load on first focus, as in zvolv-web (nzFocus → onFocus) and
+     * ZAI-Dashboard (handleFocus). Lookups reload on later focuses (throttled
+     * 2 s); people search loads only when it has nothing yet.
+     */
+    onFocus: () => void;
+    /** Force a reload of remote options. */
+    refresh: () => void;
+    /** Most selections allowed (properties.maxResults). 1 = single select. */
+    maxCount: number;
+    /** A multi-select already holds `maxCount` items. */
+    atLimit: boolean;
+    /** INPUT_TAG: add a tag that isn't in the list (ZAI FormSearchField free-text tag). */
+    addFreeTag: (text: string) => void;
+}
+interface FieldOptionsOptions {
+    debounceMs?: number;
+    /**
+     * When remote options load. "focus" (default) = on first onFocus(), like
+     * zvolv-web and ZAI-Dashboard; "mount" = as soon as the control renders.
+     * Dependency-filtered lookups always load when their source changes.
+     */
+    loadOn?: "focus" | "mount";
+    /**
+     * Copy a picked row's ExtraLabels into same-labelled fields on this form.
+     * Off by default: neither zvolv-web nor ZAI-Dashboard does this — use a
+     * FETCH_OPTIONS_FILTERS dependent lookup instead.
+     */
+    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;
+    size: number;
+    type: string;
+    url?: string;
+    uploading: boolean;
+    error?: string;
+    record?: UploadedFile;
+}
+interface FileFieldState {
+    items: FileItem[];
+    uploading: boolean;
+    /** Validates size / count / type, then uploads immediately. */
+    add: (files: FileList | File[]) => void;
+    remove: (key: string) => void;
+    canAdd: boolean;
+    rejectReason: string | null;
+}
+declare function useFileField(form: ZvolvFormApi, field: FormField, opts?: {
+    zappId?: string;
+}): FileFieldState;
+interface SheetColumn {
+    id: string;
+    label: string;
+    type: string;
+    required: boolean;
+    options: FieldOption[];
+    element: any;
+}
+interface SheetFieldState {
+    loading: boolean;
+    error: string | null;
+    columns: SheetColumn[];
+    rows: Record<string, any>[];
+    addRow: (values?: Record<string, any>) => void;
+    updateRow: (index: number, columnId: string, value: any) => void;
+    removeRow: (index: number) => void;
+    /** Row-level validation errors, keyed `${index}:${columnId}`. */
+    rowErrors: Record<string, string>;
+    display: (column: SheetColumn, value: any) => string;
+    childForm: FormDefinition | null;
+    /** properties.allowedAddActions / allowedActions include "ADD" (or neither is set), and the row cap isn't reached. */
+    canAdd: boolean;
+    /** properties.allowedDeleteActions / allowedActions include "DELETE" (or neither is set). */
+    canDelete: boolean;
+    /** properties.maxRows, when set. */
+    maxRows?: number;
+    /** Set when addRow was refused (row cap). */
+    limitMessage: string | null;
+}
+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 /
+ * submissionToValues) so both schema generations land in one shape.
+ */
+
+declare function normaliseElement(el: any): FormElement;
+/** Accepts getSingleForm output, the legacy `{value:{<id>:{…}}}` envelope, or an array. */
+declare function normaliseForm(raw: any, formId?: string): FormDefinition;
+/** Values keyed by elementId from a getSingleSubmission response. */
+declare function submissionToValues(sub: any): FormValues;
+/** The effective type: attributes.subType overrides the stored type for routing. */
+declare function resolveFieldType(el: FormElement): string;
+declare function fieldKindOf(el: FormElement): FieldKind;
+/** Kinds that hold other fields (their children are not rendered at the root). */
+declare const CONTAINER_KINDS: Set<FieldKind>;
+/** Child element ids declared by a container, in order. */
+declare function childIdsOf(el: FormElement): string[];
+
+/**
+ * Field validation. Ported from ZAI-Dashboard `formUtils.ts` (validateField /
+ * validateForm / runCustomValidators); expression validators run through the
+ * formula parser instead of `new Function`.
+ */
+
+/** Types that are layout, display or actions — never validated. */
+declare const NON_INPUT_TYPES: Set<string>;
+declare function validateField(el: FormElement, value: any, required?: boolean): string | undefined;
+declare function validateForm(elements: FormElement[], values: FormValues, state?: (el: FormElement) => {
+    hidden: boolean;
+    required: boolean;
+}): FormErrors;
+
+/**
+ * Conditional logic: `dependencies[]` rules live on the DRIVING element and
+ * target another field or container. Ported from ZAI-Dashboard
+ * ZFormRenderer `applyDependencies` / `depMatches` / `evaluateCondition`.
+ */
+
+interface RuleOverride {
+    isHidden?: boolean;
+    isDisabled?: boolean;
+    isRequired?: boolean;
+}
+/** 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
+ * "perfect match" semantics).
+ */
+declare function applyRules(elements: FormElement[], values: FormValues): Map<string, RuleOverride>;
+/**
+ * FETCH_OPTIONS_FILTERS rules that narrow `targetId`'s lookup options:
+ * [{ elementId: <source field>, masterField: <label on the lookup's source form> }].
+ *
+ * Platform shape (zvolv-web ZFormService.listenDependencies, ZAI-Dashboard
+ * FormSearchField.buildDependencyFilters): the rule sits ON THE LOOKUP being
+ * filtered; `elementId` is the field whose value is the filter, `masterField`
+ * the label matched on the lookup's source form.
+ *
+ * Legacy shape (this library's earlier `cascade()`): the rule sits on a
+ * NON-lookup driver and `elementId` is the lookup to filter. The platform never
+ * reads FETCH_OPTIONS_FILTERS on a non-lookup, so the two cannot be confused.
+ */
+declare function optionFilterRules(elements: FormElement[], targetId: string): {
+    elementId: 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.
+ */
+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
+ * widget that renders it on a dashboard. Encodes the rules the platform
+ * validates silently (see the zvibe KB `form_payload_field_types.md`):
+ *   - `width` is a percentage (25/50/75/100) and must be at the element root
+ *     AND in attributes.Width;
+ *   - SPINNER / RADIO_GROUP options and FORM_SEARCH dataSource sit at the root;
+ *   - formulas use bare single-word labels with MUL / ADD / SUB / DIVI / IF —
+ *     AVG is listed by the KB but 502s every write on the live platform;
+ *   - show / hide / mandatory rules live on the DRIVING element.
+ */
+type Width = 25 | 50 | 75 | 100;
+interface ElementSpec {
+    label: string;
+    type: string;
+    width?: Width;
+    required?: boolean;
+    hidden?: boolean;
+    disabled?: boolean;
+    elementId?: string;
+    [k: string]: any;
+}
+/** A stable elementId from a label, e.g. "Quantity (MT)" → "EID_quantity_mt". */
+declare const eid: (label: string) => string;
+type Opt = Partial<ElementSpec>;
+declare const el: {
+    text: (label: string, o?: Opt) => ElementSpec;
+    longText: (label: string, o?: Opt) => ElementSpec;
+    richText: (label: string, o?: Opt) => ElementSpec;
+    email: (label: string, o?: Opt) => ElementSpec;
+    phone: (label: string, o?: Opt & {
+        countryCode?: string;
+    }) => ElementSpec;
+    url: (label: string, o?: Opt) => ElementSpec;
+    number: (label: string, o?: Opt & {
+        minVal?: number;
+        maxVal?: number;
+    }) => ElementSpec;
+    currency: (label: string, o?: Opt) => ElementSpec;
+    percent: (label: string, o?: Opt) => ElementSpec;
+    /** formula uses `{Label}` references: `MUL({Quantity}, {Rate})`. */
+    formula: (label: string, formula: string, o?: Opt) => ElementSpec;
+    date: (label: string, o?: Opt & {
+        today?: boolean;
+    }) => ElementSpec;
+    time: (label: string, o?: Opt) => ElementSpec;
+    dateTime: (label: string, o?: Opt) => ElementSpec;
+    dateRange: (label: string, o?: Opt) => ElementSpec;
+    dropdown: (label: string, options: string[], o?: Opt) => ElementSpec;
+    radio: (label: string, options: string[], o?: Opt) => ElementSpec;
+    checkbox: (label: string, o?: Opt) => ElementSpec;
+    /** Look up rows of another form; `extra` columns autofill same-labelled fields. */
+    lookup: (label: string, src: {
+        formId: string;
+        field: string;
+        extra?: string[];
+        multiple?: boolean;
+    }, o?: Opt) => ElementSpec;
+    rating: (label: string, o?: Opt & {
+        maxVal?: number;
+    }) => ElementSpec;
+    progress: (label: string, o?: Opt & {
+        minVal?: number;
+        maxVal?: number;
+        step?: number;
+        suffix?: string;
+    }) => ElementSpec;
+    file: (label: string, o?: Opt) => ElementSpec;
+    signature: (label: string, o?: Opt) => ElementSpec;
+    section: (label: string, childIds: string[], o?: Opt) => ElementSpec;
+    note: (label: string, html: string, o?: Opt) => ElementSpec;
+    createdAt: (label?: string) => {
+        label: string;
+        type: string;
+        width: Width;
+        attributes: {
+            Width: number;
+        };
+    };
+    createdBy: (label?: string) => {
+        label: string;
+        type: string;
+        width: Width;
+        attributes: {
+            Width: number;
+        };
+    };
+    autoNumber: (label: string) => {
+        label: string;
+        type: string;
+        width: Width;
+        attributes: {
+            Width: number;
+        };
+    };
+};
+/** Rules go on the driving element: `when(severity, "Critical").show(rootCause)`. */
+declare function when(driver: ElementSpec, value: any): {
+    show: (t: ElementSpec | string) => /*elided*/ any;
+    hide: (t: ElementSpec | string) => /*elided*/ any;
+    require: (t: ElementSpec | string) => /*elided*/ any;
+};
+/**
+ * Filter `target`'s lookup options by `driver`'s value, matched against
+ * `masterField` on the target's source form. Written in the platform shape —
+ * the rule sits on the target lookup (zvolv-web / ZAI-Dashboard). When the
+ * filter leaves exactly one row the target selects it automatically.
+ */
+declare function cascade(driver: ElementSpec, target: ElementSpec, masterField: string): void;
+interface FormSpec {
+    title: string;
+    zappId: string | number;
+    /** Zapp name, for the MASTER tag "<name> <id>". */
+    zappName: string;
+    type?: "MASTER" | "WORKFLOW" | "NESTED";
+    description?: string;
+    elements: ElementSpec[];
+    successMsg?: string;
+}
+/** The `payload` for the MCP `create_form` tool. */
+declare function defineForm(spec: FormSpec): {
+    elements: ElementSpec[];
+    configurations?: {
+        successMsg: string;
+    } | undefined;
+    title: string;
+    type: "MASTER" | "WORKFLOW" | "NESTED";
+    zappId: string[];
+    tags: string[];
+    description: string;
+};
+/**
+ * A FORM widget payload for `create_widget`. The host app renders it with
+ * <ZvolvForm>; `mode` NEW captures a submission, EDIT/DISABLED show one.
+ */
+declare function formWidget(o: {
+    formId: string;
+    title: string;
+    description?: string;
+    mode?: "NEW" | "EDIT" | "DISABLED";
+    submissionId?: string;
+    submitLabel?: string;
+    layout?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    workflowTypeId?: number;
+}): {
+    DataSource: {
+        version: string;
+        active: boolean;
+        formId: string;
+        fields: never[];
+    };
+    Configuration: {
+        additionalProperties: {
+            x: number;
+            y: number;
+            w: number;
+            h: number;
+            formId: string;
+        };
+        submitLabel?: string | undefined;
+        submissionId?: string | undefined;
+        version: string;
+        formId: string;
+        mode: "NEW" | "EDIT" | "DISABLED";
+    };
+    Layout: {
+        x: number;
+        y: number;
+        cols: number;
+        rows: number;
+    };
+    WorkflowTypeID?: number | undefined;
+    Title: string;
+    Type: string;
+    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 };