@luzmo/analytics-components-kit 1.0.3-beta.1 → 1.0.3-beta.10

package/react/utils/formula/config/functions.d.ts

@@ -0,0 +1,3 @@
+import type { FormulaFunctionCategory, FormulaFunction, FormulaFunctionData } from '../../../types/formula.types';
+export declare function getFormulaFunctionCategories(): FormulaFunctionCategory[];
+export declare function getFormulaFunctionDataMap(): Record<FormulaFunction, FormulaFunctionData>;

package/react/utils/formula/config/groupings.d.ts

@@ -0,0 +1,9 @@
+import { FormulaAggregationGrouping, type FormulaAggregationGroupingData } from '../../../types/formula.types';
+/**
+ * The grouping scopes shown in the aggregation widget grouping selector, in display order.
+ */
+export declare const formulaAggregationGroupings: FormulaAggregationGrouping[];
+/**
+ * Returns the localized metadata for every aggregation grouping scope.
+ */
+export declare function getFormulaAggregationGroupingsDataMap(): Record<FormulaAggregationGrouping, FormulaAggregationGroupingData>;

package/react/utils/formula/config/regex.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Regular expressions used to tokenize and transform formula expressions.
+ *
+ * Tokens used internally by the editor:
+ * - `##EMPTYARG-<uuid>##`  -> an empty argument awaiting input
+ * - `{<datasetId>:<columnId>}` -> a column reference
+ * - `##AGGR-<uuid>##`  -> an aggregation widget placeholder
+ */
+/**
+ * Matches an empty argument, a column reference, or an aggregation widget placeholder.
+ * Capture groups: 1 = emptyArgumentId, 2 = `datasetId:columnId`, 3 = aggregationWidgetId.
+ */
+export declare const regexpToMatchEmptyArgumentOrColumnOrAggregationWidget: RegExp;
+/**
+ * Matches an empty argument or a column reference (no aggregation widgets).
+ * Capture groups: 1 = emptyArgumentId, 2 = `datasetId:columnId`.
+ */
+export declare const regexpToMatchEmptyArgumentOrColumn: RegExp;
+/**
+ * Matches the start of an aggregation function, optionally wrapped in a grouping function.
+ * Capture groups: 1 = grouping wrapper incl. `(`, 2 = grouping name, 3 = aggregation function.
+ */
+export declare const regexpToMatchAggregationFunctionStart: RegExp;
+/**
+ * Matches an aggregation function that has no arguments (an empty aggregation).
+ */
+export declare const regexpToMatchEmptyAggregationFunction: RegExp;
+/**
+ * Matches a single aggregation widget placeholder. Capture group 1 = aggregationWidgetId.
+ */
+export declare const regexpToMatchAggregationWidget: RegExp;
+/**
+ * Matches array content (used to parse the include / exclude column lists).
+ */
+export declare const regexpToMatchArrayContent: RegExp;
+/**
+ * Matches a column reference `{datasetId:columnId}`.
+ */
+export declare const regexpToMatchColumn: RegExp;

package/react/utils/formula/config/resolve-column-presentation.d.ts

@@ -0,0 +1,19 @@
+import type { IconDefinition } from '@luzmo/icons';
+import type { DatasetDataField } from '../../../types/dataset-data-field.types';
+/** The shared presentation (data-type icon + localized label) of a column reference. */
+export interface ColumnPresentation {
+    icon: IconDefinition;
+    label: string;
+}
+/**
+ * Resolves how a column reference is presented in the formula surfaces: its
+ * data-type icon and its localized label. Shared by the read-only display
+ * (`luzmo-formula`) and the CodeMirror column-pill widget so both render columns
+ * identically. Stays CodeMirror-free so the display path can use it too.
+ *
+ * @param column The resolved column (from the datasets), or `undefined` when it
+ *   could not be resolved yet (datasets still loading / unknown id).
+ * @param contentLanguage The locale used to pick the column name.
+ * @param fallbackLabel The label to show when the column is unresolved (the column id).
+ */
+export declare function resolveColumnPresentation(column: Pick<DatasetDataField, 'type' | 'subtype' | 'lowestLevel' | 'name'> | undefined, contentLanguage: string, fallbackLabel: string): ColumnPresentation;

package/react/utils/formula/config/validate-expression.d.ts

@@ -0,0 +1,19 @@
+import type { FormulaAggregationFunction, FormulaAggregationFunctionData, FormulaFunction, FormulaFunctionData } from '../../../types/formula.types';
+/**
+ * Builds the set of word identifiers (upper-cased) that may legitimately appear
+ * as bare text in a resolved formula expression: the function and aggregation
+ * names, the grouping wrappers, the `CAST` target types and the literal
+ * keywords. Columns are never bare (they are `{datasetId:columnId}` placeholders),
+ * so any other word is unresolved free text.
+ */
+export declare function getValidFormulaWordIdentifiers(functionDataMap: Record<FormulaFunction, FormulaFunctionData>, aggregationFunctionDataMap: Record<FormulaAggregationFunction, FormulaAggregationFunctionData>): Set<string>;
+/**
+ * Scans a resolved (function-syntax) expression for the first bare word that is
+ * not a known function, aggregation, grouping wrapper, cast type or literal -
+ * i.e. unresolved free text such as a half-typed column name. Returns that word,
+ * or `null` when every word resolves to a valid identifier.
+ *
+ * String literals and column placeholders are stripped first so their contents
+ * are never mistaken for unresolved identifiers.
+ */
+export declare function findUnresolvedToken(expression: string, validWordIdentifiers: Set<string>): string | null;

package/react/utils/formula/load-formula-codemirror.d.ts

@@ -0,0 +1,4 @@
+/** Loads (and registers) `luzmo-formula-codemirror` once, returning the same promise on repeat calls. */
+export declare function ensureFormulaCodeMirrorLoaded(): Promise<void>;
+/** Whether the formula CodeMirror module has finished loading. */
+export declare function isFormulaCodeMirrorLoaded(): boolean;

package/react/utils/formula/render-explanation-tooltip.d.ts

@@ -0,0 +1,7 @@
+import { nothing, type TemplateResult } from 'lit';
+/**
+ * Builds the rich tooltip body (description + optional formula example with
+ * inline column-type icons) slotted into a `luzmo-formula-draggable-field`'s `tooltip`
+ * slot. Returns `nothing` when there is no content to show.
+ */
+export declare function renderExplanationTooltip(description: string, example: string, exampleHasIcons: boolean): TemplateResult | typeof nothing;

package/react/utils/formula/store/formula-display-store.d.ts

@@ -0,0 +1,78 @@
+import type { ElementSize } from '@utils/base';
+import { type FormulaAggregationFunction, type FormulaAggregationFunctionData, type FormulaAggregationWidgetData, type FormulaEditorDataset, type FormulaFunction, type FormulaFunctionData } from '../../../types/formula.types';
+/**
+ * Display-safe core of the formula store, shared by the read-only `luzmo-formula`
+ * display and (through {@link FormulaEditorStore}) the editable surfaces.
+ *
+ * It owns everything a static rendering needs - the persisted aggregation-widget
+ * data, the operation data maps and the pure expression transforms - without any
+ * dependency on CodeMirror. The editable surfaces add the CodeMirror editor
+ * registry, expression insertion and autocompletion in the {@link FormulaEditorStore}
+ * subclass, which is the only part of the formula family that pulls CodeMirror in.
+ *
+ * It extends `EventTarget` so pill widgets and the container can subscribe to
+ * `widgets-changed` (aggregation widget state changed) updates.
+ */
+export declare class FormulaDisplayStore extends EventTarget {
+    readonly functionDataMap: Record<FormulaFunction, FormulaFunctionData>;
+    readonly aggregationFunctionDataMap: Record<FormulaAggregationFunction, FormulaAggregationFunctionData>;
+    /** When true, aggregations are rendered as nested aggregation widgets. */
+    multiStageAggregation: boolean;
+    /** When true, aggregations can be dropped inside another aggregation. */
+    nestedAggregation: boolean;
+    /** When true, the editor is read-only: inline pills cannot be edited or opened. */
+    readonly: boolean;
+    /** Language used to localize column names (for autocomplete and pills). */
+    contentLanguage: string;
+    /** Editor size, threaded into pills so their detail dropdowns (e.g. the include/exclude panel) scale with the editor. */
+    size: ElementSize;
+    /** Datasets available to the editor (used by transforms and autocomplete). */
+    datasets: FormulaEditorDataset[];
+    /** True while the editor is fetching datasets from `datasetIds`; column pills show a loading state. */
+    loading: boolean;
+    /** Id of the aggregation widget whose editor was focused last (null = root). */
+    lastFocusedAggregationWidgetId: string | null;
+    /**
+     * Id of an aggregation widget that was just created (via a list insert or
+     * autocomplete) and whose nested input should grab focus once rendered, so the
+     * user can keep typing into it. Only set for aggregations that accept content
+     * (arity > 0) and cleared by the pill after it focuses.
+     */
+    pendingFocusAggregationWidgetId: string | null;
+    private _aggregationWidgets;
+    get aggregationWidgets(): FormulaAggregationWidgetData[];
+    addWidgets(widgets: FormulaAggregationWidgetData[]): void;
+    removeWidgets(widgetIds: string[]): void;
+    updateWidget(widget: FormulaAggregationWidgetData): void;
+    getWidget(widgetId: string): FormulaAggregationWidgetData | undefined;
+    clearWidgets(): void;
+    protected _notifyWidgetsChanged(): void;
+    /**
+     * Toggles read-only and notifies mounted pills so their (already-rendered)
+     * controls re-render disabled / enabled. Setting the field directly (e.g. at
+     * construction) is fine; use this when toggling after pills exist.
+     */
+    setReadonly(value: boolean): void;
+    /**
+     * Toggles the dataset-loading flag and asks any listeners to rebuild their pill
+     * decorations, so column pills can reflect the loading state (a spinner while
+     * the column label is being resolved).
+     */
+    setLoading(value: boolean): void;
+    /**
+     * Flags a just-created aggregation widget so its nested input grabs focus once
+     * rendered, but only when the aggregation accepts content (arity > 0); e.g.
+     * COUNTR (arity 0) has no input to type into.
+     */
+    protected _markAggregationForFocus(widgets: FormulaAggregationWidgetData[]): void;
+    /**
+     * Replaces every aggregation function in the expression with an aggregation
+     * widget placeholder (`##AGGR-<id>##`), registering the parsed widget data.
+     */
+    transformToAggregationWidgetSyntax(expression: string): string;
+    /**
+     * Replaces every aggregation widget placeholder with the rendered aggregation
+     * function expression, recursively resolving nested widgets.
+     */
+    transformToAggregationFunctionSyntax(expression: string): string;
+}

package/react/utils/formula/store/formula-editor-context.d.ts

@@ -0,0 +1,8 @@
+import type { FormulaEditorStore } from './formula-editor-store';
+/**
+ * Context used to share a single {@link FormulaEditorStore} instance from the
+ * root `luzmo-formula-editor` down to nested inputs and pill widgets.
+ */
+export declare const formulaEditorContext: {
+    __context__: FormulaEditorStore;
+};

package/react/utils/formula/store/formula-editor-store.d.ts

@@ -0,0 +1,46 @@
+import type { Completion } from '@codemirror/autocomplete';
+import type { EditorView } from '@codemirror/view';
+import { FormulaDisplayStore } from './formula-display-store';
+import { type ExtendExpressionPayload, type ExtendExpressionType, type FormulaAggregationWidgetData, type FormulaEditorDataset } from '../../../types/formula.types';
+/** Key used to register the root (top-level) editor. */
+export declare const ROOT_EDITOR_ID = "__root__";
+/**
+ * The editable formula store: extends the display-safe {@link FormulaDisplayStore}
+ * with everything the CodeMirror-backed surfaces need - the registry of editor
+ * views (root + nested aggregation widgets), expression insertion and the
+ * autocompletion list.
+ *
+ * This is the only part of the formula family that depends on CodeMirror, so the
+ * read-only `luzmo-formula` display (which uses {@link FormulaDisplayStore}) never
+ * pulls it in.
+ */
+export declare class FormulaEditorStore extends FormulaDisplayStore {
+    private readonly _editors;
+    registerEditor(id: string | null, view: EditorView): void;
+    unregisterEditor(id: string | null): void;
+    getEditor(id?: string | null): EditorView | undefined;
+    /**
+     * Builds the expression fragment for a dropped / inserted item and any new
+     * aggregation widgets that need to be registered.
+     */
+    getDropExpression(type: ExtendExpressionType, id: string | null, datasetId?: string | null, textContent?: string): {
+        expression: string;
+        aggregationWidgets: FormulaAggregationWidgetData[];
+    };
+    /**
+     * Inserts the requested item into the targeted editor (root or aggregation
+     * widget), either at the cursor or by filling a specific empty argument.
+     */
+    onExtendExpression(payload: ExtendExpressionPayload): void;
+    /**
+     * Builds the CodeMirror autocompletion list from the functions, aggregations
+     * (when enabled) and the columns of the provided datasets.
+     */
+    getAutoCompletionList(datasets: FormulaEditorDataset[], showAggregations: boolean): Completion[];
+    /**
+     * Builds the autocompletion info (hint) tooltip for a function / aggregation:
+     * the example expression (with `⟨type⟩` markers rendered as column-type icons)
+     * followed by the description, mirroring the description region.
+     */
+    private _buildOperationInfo;
+}

package/react/utils/formula/store/tests/formula-editor-store.test.d.ts

@@ -0,0 +1 @@
+export {};

package/react/utils/formula/tests/validate-expression.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/ai-chat.types.d.ts

@@ -35,7 +35,7 @@ export interface LuzmoChart {
     update?: boolean;
     aichartId?: string;
 }
-export interface AISampleChart {
+export interface AiSampleChart {
     error?: string;
     generatedChart: Record<string, unknown> & {
         feedback: unknown;

package/types/formula.types.d.ts

@@ -0,0 +1,204 @@
+import type { Completion } from '@codemirror/autocomplete';
+import type { ColumnSubtype, ColumnType } from '@luzmo/dashboard-contents-types';
+import type { IconDefinition } from '@luzmo/icons';
+import type { DatasetDataField } from './dataset-data-field.types';
+/**
+ * All formula functions (operators and named functions) supported by the editor.
+ */
+export type FormulaFunction = '+' | '-' | '*' | '/' | '%' | '>' | '<' | '>=' | '<=' | '=' | '<>' | 'ABS' | 'CEIL' | 'E' | 'EXP' | 'FLOOR' | 'LN' | 'LOG' | 'PI' | 'POW' | 'RAND' | 'ROUND' | 'SQRT' | 'CAST' | 'IF' | 'COALESCE' | 'AND' | 'OR' | 'NOT' | 'SIN' | 'COS' | 'TAN' | 'ASIN' | 'ACOS' | 'ATAN' | 'SINH' | 'COSH' | 'TANH' | 'MEAN' | 'STDDEV' | '||' | 'LENGTH' | 'LOWER' | 'UPPER' | 'LTRIM' | 'RTRIM' | 'TRIM' | 'REPLACE' | 'STRPOS' | 'SPLIT_PART' | 'SUBSTR' | 'NOW' | 'YEAR' | 'YEAR_UTC' | 'QUARTER' | 'QUARTER_UTC' | 'MONTH' | 'MONTH_UTC' | 'WEEK' | 'WEEK_UTC' | 'DAY' | 'DAY_UTC' | 'DAY_OF_WEEK' | 'DAY_OF_WEEK_UTC' | 'DAY_OF_YEAR' | 'DAY_OF_YEAR_UTC' | 'YEAR_OF_WEEK' | 'YEAR_OF_WEEK_UTC' | 'HOUR' | 'HOUR_UTC' | 'MINUTE' | 'MINUTE_UTC' | 'SECOND' | 'SECOND_UTC' | 'DATE_ADD' | 'DATE_DIFF' | 'COORDS';
+/**
+ * Keys for the function categories shown in the functions list dropdown.
+ */
+export type FormulaFunctionCategoryKey = 'string' | 'dateTime' | 'mathematical' | 'conditional' | 'conversion' | 'comparison' | 'logical' | 'circular' | 'spatial';
+/**
+ * The shape of a function category (a localized title and the functions it contains).
+ */
+export interface FormulaFunctionCategory {
+    key: FormulaFunctionCategoryKey;
+    title: () => string;
+    functions: FormulaFunction[];
+}
+/**
+ * How a function is inserted into the expression. `infix` operators sit between
+ * two operands, `prefix` functions wrap their arguments in parentheses and
+ * `prefix_op` is a prefix keyword operator (e.g. `NOT`).
+ */
+export type FormulaFunctionType = 'infix' | 'prefix' | 'prefix_op';
+/**
+ * Metadata describing a single formula function. Labels, descriptions and
+ * examples are functions so they can be re-evaluated when the locale changes.
+ */
+export interface FormulaFunctionData {
+    type: FormulaFunctionType;
+    arity: number;
+    label: () => string;
+    description: () => string;
+    example: () => string;
+    /**
+     * Whether the example contains `⟨type⟩` markers that should be rendered as
+     * column-type icons in the description.
+     */
+    exampleHasIcons?: boolean;
+}
+/**
+ * The aggregation functions supported by the editor.
+ */
+export type FormulaAggregationFunction = 'AVG' | 'COUNT' | 'COUNTD' | 'COUNTR' | 'MAX' | 'MIN' | 'SUM';
+/**
+ * Metadata describing a single aggregation function.
+ */
+export interface FormulaAggregationFunctionData {
+    arity: 0 | 1;
+    label: () => string;
+    description: () => string;
+    example: () => string;
+    exampleHasIcons?: boolean;
+}
+/**
+ * The grouping scope applied to an aggregation widget.
+ */
+export declare enum FormulaAggregationGrouping {
+    GROUP = "",
+    GROUPFULL = "GROUPFULL",
+    GROUPINEX = "GROUPINEX"
+}
+/**
+ * Metadata describing an aggregation grouping scope (label, description, icon, accent color).
+ */
+export interface FormulaAggregationGroupingData {
+    label: () => string;
+    description: () => string;
+    icon: IconDefinition;
+    color: string;
+}
+/**
+ * A dataset as consumed by the formula editor. Columns are expressed as
+ * {@link DatasetDataField} so they can be reused as drag sources.
+ */
+export interface FormulaEditorDataset {
+    id: string;
+    name: Record<string, string>;
+    description?: Record<string, string>;
+    color?: string;
+    columns: DatasetDataField[];
+}
+/**
+ * A CodeMirror autocompletion option augmented with the Luzmo icon to render in
+ * front of it: the formula icon for functions / aggregations and the matching
+ * data-type icon for columns.
+ */
+export interface FormulaCompletion extends Completion {
+    iconDef?: IconDefinition;
+}
+/**
+ * Configuration for a column pill rendered inside the editor.
+ */
+export interface ColumnWidgetConfig {
+    widgetType: 'column';
+    data: {
+        columnId: string;
+        datasetId: string;
+        type: ColumnType;
+        subtype?: ColumnSubtype;
+        lowestLevel?: number;
+        text: string;
+        /** Resolved data-type icon (via `resolveColumnPresentation`) for the widget DOM builder to render. */
+        icon: IconDefinition;
+        /** True while datasets are still loading and this column's label is not yet resolved. */
+        pending: boolean;
+    };
+}
+/**
+ * Configuration for an empty argument pill rendered inside the editor.
+ */
+export interface EmptyArgumentWidgetConfig {
+    widgetType: 'emptyArgument';
+    data: {
+        emptyArgumentId: string;
+        /** Id of the aggregation widget containing this empty argument, or null for the root editor. */
+        parentAggregationWidgetId: string | null;
+    };
+}
+/**
+ * Configuration for a nested aggregation widget rendered inside the editor.
+ */
+export interface AggregationWidgetConfig {
+    widgetType: 'aggregation';
+    data: {
+        aggregationWidgetId: string;
+        linkedDatasets: FormulaEditorDataset[];
+        contentLanguage: string;
+        /** Id of the aggregation widget containing this widget, or null for the root editor. */
+        parentAggregationWidgetId: string | null;
+    };
+}
+export type FormulaEditorWidgetConfig = ColumnWidgetConfig | EmptyArgumentWidgetConfig | AggregationWidgetConfig;
+/**
+ * The persisted state of a single aggregation widget.
+ */
+export interface FormulaAggregationWidgetData {
+    widgetId: string;
+    aggregationFunction: FormulaAggregationFunction;
+    content: string;
+    grouping: FormulaAggregationGrouping;
+    /** Columns to always group by, as full `datasetId:columnId` references. */
+    includedColumns?: string[];
+    /** Columns to never group by, as full `datasetId:columnId` references. */
+    excludedColumns?: string[];
+}
+/**
+ * The kinds of content that can be inserted into the expression.
+ */
+export type ExtendExpressionType = 'column' | 'function' | 'aggregation' | 'text';
+/**
+ * Payload describing a request to extend / insert into the expression.
+ */
+export interface ExtendExpressionPayload {
+    type: ExtendExpressionType;
+    id: string | null;
+    aggregationWidgetId: string | null;
+    datasetId?: string | null;
+    isEmptyArgument?: boolean;
+    targetEmptyArgumentId?: string | null;
+    textContent?: string;
+}
+/**
+ * The kinds of item that can be described in the description.
+ */
+export type FormulaDescribeKind = 'function' | 'aggregation' | 'grouping';
+/**
+ * A formula-description target (the hovered / selected function, aggregation or grouping).
+ */
+export interface FormulaDescribeTarget {
+    kind: FormulaDescribeKind;
+    id: string;
+}
+/**
+ * Detail of the `luzmo-formula-insert` event fired by the lists when an item is
+ * clicked / double-clicked to be inserted into the focused editor.
+ */
+export interface FormulaInsertEventDetail {
+    kind: 'function' | 'aggregation' | 'column';
+    id: string;
+    datasetId?: string;
+}
+/**
+ * Detail of the `luzmo-expression-changed` event.
+ */
+export interface ExpressionChangedEventDetail {
+    expression: string;
+}
+/**
+ * Detail of the `luzmo-validity-changed` event.
+ */
+export interface ValidityChangedEventDetail {
+    valid: boolean;
+    error: string | null;
+    type?: ColumnType;
+}
+/**
+ * Detail of the `luzmo-datasets-error` event, fired when fetching datasets by id fails.
+ */
+export interface DatasetsErrorEventDetail {
+    error: unknown;
+}

package/types.d.ts

@@ -11,6 +11,7 @@ export type * from './types/ai-chat.types';
 export type * from './types/data-field-events.types';
 export type * from './types/dataset-data-field.types';
 export type * from './types/dataset.types';
+export type * from './types/formula.types';
 export type * from './types/slot.types';
 export type * from './components/dataset-icon/types';
 export type * from './components/display-settings/types';

package/utils/data-broker/index.d.ts

@@ -59,6 +59,33 @@ interface ApiRequestPayload {
     key?: string;
     token?: string;
 }
+/**
+ * The resource types whose expressions can be validated by the backend.
+ */
+export type ValidatableResource = 'column' | 'formula';
+/**
+ * The properties sent when validating an expression.
+ */
+export interface ExpressionValidationProperties {
+    expression: string;
+    explain_error?: boolean;
+}
+interface ValidateRequestPayload {
+    action: 'validate';
+    version: string;
+    properties: ExpressionValidationProperties;
+    key?: string;
+    token?: string;
+}
+/**
+ * The normalized result of an expression validation call.
+ */
+export interface ExpressionValidationResult {
+    valid: boolean;
+    reason?: string;
+    explanation?: string;
+    type?: Column['type'];
+}
 interface PaginatedApiResponse<T> {
     data: T[];
     pagination: PaginationResult;
@@ -133,7 +160,7 @@ export declare class DataBroker {
      * @returns API response
      * @throws {Error} If API request fails
      */
-    fetchApi<T>(endpoint: string, jsonBody?: ApiRequestPayload, options?: RequestInit): Promise<T>;
+    fetchApi<T>(endpoint: string, jsonBody?: ApiRequestPayload | ValidateRequestPayload, options?: RequestInit): Promise<T>;
     /**
      * Fetch all available datasets with pagination support
      * @param options - Pagination options
@@ -184,6 +211,18 @@ export declare class DataBroker {
         data: any[][];
         performance: PerformanceMetrics;
     }>;
+    /**
+     * Validates a column or formula expression against the Luzmo API.
+     *
+     * This is the REST equivalent of the legacy socket `validate` action: it POSTs
+     * to `/{version}/{resource}` with `{ action: 'validate', properties }`.
+     *
+     * @param resource - The resource whose expression is validated ('column' or 'formula').
+     * @param properties - The expression and options to validate.
+     * @returns A normalized validation result. When the backend cannot be reached,
+     *   the error is thrown so callers can fall back to local-only validation.
+     */
+    validate(resource: ValidatableResource, properties: ExpressionValidationProperties): Promise<ExpressionValidationResult>;
     /**
      * Fetch theme by ID with caching
      * @param themeId - Theme ID

package/utils/formula/base/formula-base.d.ts

@@ -0,0 +1,117 @@
+import { type PropertyValues, type TemplateResult } from 'lit';
+import { LuzmoElement } from '@utils/base';
+import type { DatasetDataFields } from '@components/data-field-panel/types';
+import { FormulaDisplayStore } from '../store/formula-display-store';
+import type { FormulaEditorDataset } from '../../../types/formula.types';
+/** A `luzmo-formula-codemirror` element with the imperative methods the host calls. */
+type FormulaCodeMirrorElement = HTMLElement & {
+    setContent: (value: string) => void;
+};
+declare const LuzmoFormulaBase_base: (new (...args: any[]) => {
+    language: string;
+}) & typeof LuzmoElement & {
+    new (...args: any[]): import("../../base/sized-mixin").SizedElementInterface;
+    prototype: import("../../base/sized-mixin").SizedElementInterface;
+};
+/**
+ * Shared base for `luzmo-formula` (display) and the editable surfaces. Owns the
+ * common, CodeMirror-free surface: a {@link FormulaDisplayStore} (created via the
+ * `_createStore` factory so the display uses the lightweight store and the
+ * editable surfaces a {@link FormulaEditorStore}), dataset loading (direct or by
+ * id), expression <-> store syncing and the debounced `luzmo-expression-changed`
+ * emit. Subclasses add their own rendering (and, for the editable surfaces,
+ * the CodeMirror input, autocompletion, validation + lists) and tune behaviour
+ * through the protected hooks.
+ *
+ * Not a registered element - abstract base only (mirrors `LuzmoItemOptionBase`).
+ */
+export declare abstract class LuzmoFormulaBase<TStore extends FormulaDisplayStore = FormulaDisplayStore> extends LuzmoFormulaBase_base {
+    /** The formula expression (function syntax), e.g. `SUM({datasetId:columnId})`. */
+    expression: string;
+    /** Datasets and their data fields, provided directly (takes preference over `datasetIds`). */
+    datasetsDataFields: DatasetDataFields[];
+    /** Dataset ids to fetch from the Luzmo API (auth attributes optional for public datasets). */
+    datasetIds: string[];
+    /** Base URL of the Luzmo API used to fetch datasets by id. */
+    apiUrl: string;
+    /** Luzmo API authorization key, used with `authToken` to fetch datasets by id. */
+    authKey?: string;
+    /** Luzmo API authorization token, used with `authKey` to fetch datasets by id. */
+    authToken?: string;
+    /**
+     * Whether aggregation functions are offered (in the autocompletion, and - for
+     * the editor - via the aggregations list and pills). Defaults to `true`.
+     *
+     * Note: as a boolean attribute defaulting to `true` it cannot be turned off via
+     * markup (an absent attribute keeps the default); set the `.showAggregations`
+     * property to `false` to disable.
+     */
+    showAggregations: boolean;
+    /** Language used for data labels (column / dataset names). */
+    contentLanguage: string;
+    /** When true, aggregations render as multi-stage nested widgets. */
+    multiStageAggregation: boolean;
+    /** When true, aggregations can be nested inside other aggregations. */
+    nestedAggregation: boolean;
+    protected _datasets: FormulaEditorDataset[];
+    /** Whether the CodeMirror-backed input module has finished loading. */
+    protected _codeMirrorLoaded: boolean;
+    protected readonly _store: TStore;
+    protected _rootContent: string;
+    protected _lastEmittedExpression: string | null;
+    protected _emitTimer?: ReturnType<typeof setTimeout>;
+    /**
+     * True while an external `expression` is being synced into the store. Store
+     * mutations during the sync (e.g. `clearWidgets()` emitting `widgets-changed`)
+     * must not recompute/emit: they run against stale `_rootContent` and would emit
+     * a bogus value back to the parent, overwriting the value it just set.
+     */
+    protected _applyingExternalExpression: boolean;
+    constructor();
+    /** Creates the store backing this surface; the display returns the lightweight (CodeMirror-free) store. */
+    protected abstract _createStore(): TStore;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private _handleWidgetsChanged;
+    protected firstUpdated(changedProperties: PropertyValues): void;
+    protected updated(changedProperties: PropertyValues): void;
+    /**
+     * Pushes the resolved root content into the (lazily-loaded) input.
+     *
+     * `_applyExternalExpression` runs in `willUpdate` (before the first render),
+     * when the input element does not exist yet, so its computed content is never
+     * pushed into the editor. The store widgets are already populated, so this
+     * renders the initial pills once the input is present.
+     */
+    protected _pushRootContent(): void;
+    /** The rendered input element, if present in the shadow root. */
+    protected get _codeMirrorElement(): FormulaCodeMirrorElement | null;
+    /** Lazily loads the CodeMirror-backed input so its dependency is split into an async chunk. */
+    protected _ensureCodeMirrorLoaded(): Promise<void>;
+    protected willUpdate(changedProperties: PropertyValues): void;
+    private _loadDatasets;
+    /** Rebuilds the (editor-only) autocompletion list. No-op here; the editable surfaces override it. */
+    protected _rebuildAutoCompletion(): void;
+    /**
+     * Clears the widgets and parses the external `expression` into the root
+     * content, returning the resolved content (or `null` when nothing changed so
+     * subclasses can skip pushing it into the input).
+     */
+    protected _syncExpressionToStore(): string | null;
+    protected _applyExternalExpression(): void;
+    protected _recomputeExpression(): void;
+    /** Dispatches the (debounced) `luzmo-expression-changed` event and tracks the last emitted value. */
+    protected _emitExpressionChanged(output: string): void;
+    /** Whether the CodeMirror input should be loaded for the current state (editor surfaces only). */
+    protected _shouldLoadInput(): boolean;
+    /** Whether expression changes should be recomputed/emitted in the current state. */
+    protected _canEmitExpression(): boolean;
+    /** Debounce (ms) before emitting `luzmo-expression-changed`. */
+    protected get _emitDebounceMs(): number;
+    /** Called (debounced) once the expression output is computed. */
+    protected _onExpressionComputed(output: string): void;
+    /** Tracks the dataset-loading state. No-op by default; the editor surfaces it on its lists. */
+    protected _setLoading(_value: boolean): void;
+    protected abstract render(): TemplateResult;
+}
+export {};