@luzmo/analytics-components-kit 1.0.3-beta.9 → 1.0.3

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/slot.types.d.ts

@@ -13,3 +13,13 @@ export interface SlotConstraintTriggeredEventDetail {
     proposedSlotsContents: VizItemSlot[];
     constraints: SlotConstraint[];
 }
+export interface SlotsContentsChangedEventDetail {
+    slotsContents: VizItemSlot[];
+    linkedDatasetsIds?: string[];
+}
+export interface DatasetConstraintTriggeredEventDetail {
+    previousDatasetId: string | undefined;
+    newDatasetId: string;
+    currentSlotsContents: VizItemSlot[];
+    wouldClearSlots: boolean;
+}

package/types.d.ts

@@ -7,20 +7,16 @@
  */
 export type { Column, ColumnSubtype, ColumnType, GenericSlotContent, GridConfig, ItemFilterGroup, OptionConfig, OptionsConfig, OptionTranslation, Slot, SlotConfig, SlotName, SlotPosition, SlotPositioningConfig, ThemeConfig, TranslationOverrides, TranslationsFile, VizItemSlot, VizItemType } from '@luzmo/dashboard-contents-types';
 export type { ElementSize, Placement } from '@luzmo/lucero';
-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';
+export type * from './components/item-option/types';
 export type * from './components/data-field/types';
 export type * from './components/data-field-panel/types';
 export type * from './components/item-slot-drop/types';
 export type * from './components/filters/types';
 export type * from './components/item-grid/types';
-export type * from './components/slot-menu/types';
-export type * from './components/viz-item-menu/types';
 export type * from './utils/data-broker';
 export type * from './utils/time/period-over-period-condition.const';
 export type * from './utils/transformations/convert-datasets-to-data-fields';

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/drag/pragmatic-element-adapter.d.ts

@@ -0,0 +1,2 @@
+import * as elementAdapter from '@atlaskit/pragmatic-drag-and-drop/element/adapter';
+export declare const draggable: typeof elementAdapter.draggable, dropTargetForElements: (args: import("@atlaskit/pragmatic-drag-and-drop/dist/types/internal-types").DropTargetArgs<import("@atlaskit/pragmatic-drag-and-drop/dist/types/internal-types").ElementDragType>) => import("@atlaskit/pragmatic-drag-and-drop/dist/types/internal-types").CleanupFn, monitorForElements: (args: import("@atlaskit/pragmatic-drag-and-drop/dist/types/internal-types").MonitorArgs<import("@atlaskit/pragmatic-drag-and-drop/dist/types/internal-types").ElementDragType>) => import("@atlaskit/pragmatic-drag-and-drop/dist/types/internal-types").CleanupFn;

package/utils/drag/tests/pragmatic-element-adapter.first-import.test.d.ts

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

package/utils/drag/tests/pragmatic-element-adapter.test.d.ts

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

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

@@ -0,0 +1,117 @@
+import { type PropertyValues, type TemplateResult } from 'lit';
+import { LuzmoElement } from '../../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 {};

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

@@ -0,0 +1,62 @@
+import type { Completion } from '@codemirror/autocomplete';
+import '@luzmo/lucero/progress-circle';
+import { type PropertyValues, type TemplateResult } from 'lit';
+import { FormulaEditorStore } from '../store/formula-editor-store';
+import { LuzmoFormulaBase } from './formula-base';
+/**
+ * Shared base for the editable formula surfaces (`luzmo-formula-field` and
+ * `luzmo-formula-editor`). Extends `LuzmoFormulaBase` with the input-specific
+ * surface: the editable-input sizing/placeholder/readonly properties and the
+ * rendering + change handling of the (lazily-loaded) CodeMirror input.
+ *
+ * The read-only display (`luzmo-formula`) extends `LuzmoFormulaBase` directly,
+ * so it never exposes these editing-only properties.
+ *
+ * Not a registered element - abstract base only.
+ */
+export declare abstract class LuzmoFormulaInputBase extends LuzmoFormulaBase<FormulaEditorStore> {
+    /** Autocompletion options offered while typing in the (lazily-loaded) CodeMirror input. */
+    protected _autoCompletionList: Completion[];
+    constructor();
+    /** The editable surfaces use the full (CodeMirror-backed) editor store. */
+    protected _createStore(): FormulaEditorStore;
+    /** Renders the field display-only (no editing). */
+    readonly: boolean;
+    /** Placeholder text shown in the editable input when the expression is empty. */
+    placeholder: string;
+    /** Number of text lines the input is sized to start with. Defaults to 3. */
+    rows: number;
+    /** Maximum number of text lines before a scrollbar appears (only when `grows`). */
+    maxRows?: number;
+    /** Whether the input grows in height with its content (up to `maxRows` if set). */
+    grows: boolean;
+    protected willUpdate(changedProperties: PropertyValues): void;
+    /** Rebuilds the CodeMirror autocompletion list from the current datasets. */
+    protected _rebuildAutoCompletion(): void;
+    /**
+     * Syncs the external expression into the store, then pushes the resolved root
+     * content into the (root) CodeMirror editor - either the live view or, before
+     * it exists, the input element.
+     */
+    protected _applyExternalExpression(): void;
+    protected _handleInputContentChanged(event: CustomEvent<{
+        content: string;
+    }>): void;
+    /**
+     * Renders the (lazily-loaded) CodeMirror input. While the module loads, a
+     * same-sized placeholder with a centered spinner is shown instead of `nothing`,
+     * so the input reserves its space and the surrounding layout doesn't shift in.
+     */
+    protected _renderFormulaCodeMirror(options?: {
+        part?: string;
+        hasError?: boolean;
+    }): TemplateResult;
+    /**
+     * A placeholder matching the CodeMirror input's box (border, radius and
+     * `rows`-based height) shown while the editor module loads, so swapping in the
+     * real input causes no content shift. The bottom radius follows
+     * `--luzmo-formula-field-bottom-radius`, which the editor squares off so the
+     * placeholder lines up with the lists below exactly like the loaded input.
+     */
+    private _renderInputLoadingPlaceholder;
+}

package/utils/formula/codemirror/actions.d.ts

@@ -0,0 +1,47 @@
+import type { EditorView } from '@codemirror/view';
+/**
+ * Replaces the entire document content. Used to set the initial / external expression.
+ *
+ * The cursor is kept at its current offset (clamped to the new length) instead of
+ * being remapped through the full-document replacement, which would otherwise
+ * collapse it to the document start. This matters when the host re-applies the
+ * `expression` while the user is editing: their caret must stay where it was so a
+ * subsequent insertion still lands at that spot rather than at the start / end.
+ */
+export declare function setEditorContent(view: EditorView, content: string): void;
+/**
+ * Inserts content at the current selection (replacing any selected text), and
+ * places the cursor right after the inserted content.
+ *
+ * The selection is read *before* focusing: refocusing a blurred editor (e.g. after
+ * double-clicking a column / function in one of the side lists, which moves focus
+ * out of the editor) can let the browser move the caret to the end of the content,
+ * so we pin the insertion to the range the user's cursor was actually at.
+ */
+export declare function insertAtSelection(view: EditorView, content: string): void;
+/**
+ * Replaces a range of the document (defaults to the whole document) with new content.
+ */
+export declare function replaceContent(view: EditorView, data: {
+    positionInDocument?: {
+        from: number;
+        to: number;
+    };
+    withContent: string;
+}): void;
+/**
+ * Moves the cursor to the document position nearest to the given screen coordinates.
+ */
+export declare function setCursorAtCoordinates(view: EditorView, coordinates: {
+    x: number;
+    y: number;
+}): void;
+/**
+ * Moves the cursor to the given document position.
+ */
+export declare function setCursorAtPosition(view: EditorView, position: number): void;
+/**
+ * Replaces an empty argument token (`##EMPTYARG-<emptyArgumentId>##`) with the
+ * provided content and places the cursor right after the inserted content.
+ */
+export declare function updateEmptyArgument(view: EditorView, withContent: string, emptyArgumentId: string): void;

package/utils/formula/codemirror/drop-cursor.d.ts

@@ -0,0 +1,15 @@
+import { type Extension } from '@codemirror/state';
+import { EditorView } from '@codemirror/view';
+/**
+ * Editor extension that renders a drop caret at the position set via
+ * {@link showDropCursorAt}. Use instead of CodeMirror's `dropCursor()` when the
+ * drag is handled by pragmatic drag-and-drop rather than native drag events.
+ */
+export declare function formulaDropCursor(): Extension;
+/** Shows the drop caret at the document position nearest the given coordinates. */
+export declare function showDropCursorAt(view: EditorView, coordinates: {
+    x: number;
+    y: number;
+}): void;
+/** Hides the drop caret if it is currently shown. */
+export declare function clearDropCursor(view: EditorView): void;

package/utils/formula/codemirror/icon-element.d.ts

@@ -0,0 +1,7 @@
+import type { IconDefinition } from '@luzmo/icons';
+/**
+ * Builds an inline `<svg>` element (filled with `currentColor`) from a Luzmo icon
+ * definition, for use in plain-DOM contexts such as CodeMirror autocompletion
+ * options and info tooltips (which cannot render Lit templates).
+ */
+export declare function createIconSvg(definition: IconDefinition): SVGElement;

package/utils/formula/codemirror/parser.d.ts

@@ -0,0 +1,16 @@
+import type { Range } from '@codemirror/state';
+import { Decoration } from '@codemirror/view';
+import type { FormulaEditorStore } from '../store/formula-editor-store';
+import type { FormulaEditorDataset } from '../../../types/formula.types';
+export interface ParseOptions {
+    store: FormulaEditorStore;
+    datasets: FormulaEditorDataset[];
+    contentLanguage: string;
+    parentAggregationWidgetId: string | null;
+    multiStageAggregation: boolean;
+}
+/**
+ * Scans the document and builds the set of replace-decorations for every
+ * column reference, empty argument and aggregation widget placeholder it finds.
+ */
+export declare function buildDecorations(doc: string, options: ParseOptions): Range<Decoration>[];

package/utils/formula/codemirror/tests/actions.test.d.ts

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

package/utils/formula/codemirror/theme.d.ts

@@ -0,0 +1,20 @@
+interface StyleSpec {
+    [property: string]: string | number | StyleSpec;
+}
+type ThemeSpec = Record<string, StyleSpec>;
+export declare const baseFormulaEditorTheme: ThemeSpec;
+/**
+ * Styling for the autocompletion dropdown and its info (hint) panel. Applied via
+ * `EditorView.theme` (which outranks the library's base theme) so sizing, spacing
+ * and font-size follow the editor size and colors come from the global tokens.
+ */
+export declare const formulaEditorAutocompleteTheme: ThemeSpec;
+export declare function createFormulaEditorDynamicTheme(options: {
+    rows?: number;
+    maxRows?: number;
+    grows?: boolean;
+    editorHeight?: string;
+    hasError?: boolean;
+    singleLine?: boolean;
+}): ThemeSpec;
+export {};

package/utils/formula/codemirror/widget.d.ts

@@ -0,0 +1,18 @@
+import { WidgetType } from '@codemirror/view';
+import type { FormulaEditorStore } from '../store/formula-editor-store';
+import type { FormulaEditorWidgetConfig } from '../../../types/formula.types';
+/**
+ * A CodeMirror widget that renders a formula editor pill in place of its
+ * placeholder text: an inline column pill (built directly as DOM, mirroring
+ * `luzmo-formula`'s display markup) or one of the pill custom elements
+ * (`luzmo-formula-empty-argument-pill` / `luzmo-formula-aggregation`).
+ */
+export declare class FormulaPillWidget extends WidgetType {
+    private readonly config;
+    private readonly store;
+    private _element?;
+    constructor(config: FormulaEditorWidgetConfig, store: FormulaEditorStore);
+    toDOM(): HTMLElement;
+    eq(other: FormulaPillWidget): boolean;
+    ignoreEvent(): boolean;
+}

package/utils/formula/config/aggregations.d.ts

@@ -0,0 +1,9 @@
+import type { FormulaAggregationFunction, FormulaAggregationFunctionData } from '../../../types/formula.types';
+/**
+ * The aggregation functions shown in the aggregations list, in display order.
+ */
+export declare const formulaAggregationFunctions: FormulaAggregationFunction[];
+/**
+ * Returns the localized metadata for every aggregation function.
+ */
+export declare function getFormulaAggregationFunctionsDataMap(): Record<FormulaAggregationFunction, FormulaAggregationFunctionData>;

package/utils/formula/config/build-datasets.d.ts

@@ -0,0 +1,10 @@
+import type { DatasetWithDataFields } from '../../transformations/convert-datasets-to-data-fields';
+import type { DatasetDataFields } from '../../../components/data-field-panel/types';
+import type { FormulaEditorDataset } from '../../../types/formula.types';
+/**
+ * Normalizes datasets provided directly (`DatasetDataFields`) or fetched from the
+ * Luzmo API (`DatasetWithDataFields`) into the {@link FormulaEditorDataset} shape
+ * consumed by the formula input and store. When more than one dataset is present,
+ * each gets an accent color from the shared palette.
+ */
+export declare function buildFormulaEditorDatasets(input: (DatasetDataFields | DatasetWithDataFields)[]): FormulaEditorDataset[];