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

package/react/luzmo-stub.d.ts

@@ -26,6 +26,9 @@ declare module '@luzmo/analytics-components-kit' {
   export class LuzmoFilterValuePickerHierarchy extends HTMLElement {}
   export class LuzmoFilterValuePickerNumeric extends HTMLElement {}
   export class LuzmoFilters extends HTMLElement {}
+  export class LuzmoFormula extends HTMLElement {}
+  export class LuzmoFormulaEditor extends HTMLElement {}
+  export class LuzmoFormulaField extends HTMLElement {}
   export class LuzmoItemGrid extends HTMLElement {}
   export class LuzmoItemOption extends HTMLElement {}
   export class LuzmoItemOptionActionButtonGroup extends HTMLElement {}
@@ -53,32 +56,40 @@ declare module '@luzmo/analytics-components-kit' {
 
 declare module '@luzmo/analytics-components-kit/ai-chat' {
   export class LuzmoAiChat extends HTMLElement {}
-
+  export type AiChatCompleteEvent = Record<string, unknown>;
+  export type AiChatConversationIdChangedEventDetail = Record<string, unknown>;
+  export type AiChatDatasetsChangedEventDetail = Record<string, unknown>;
+  export type AiChatMessageSentEventDetail = Record<string, unknown>;
+  export type AiChatStepEvent = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/ai-interaction-textarea' {
   export class LuzmoAiInteractionTextarea extends HTMLElement {}
-
+  export type PromptSubmittedEventDetail = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/data-field' {
   export class LuzmoDataField extends HTMLElement {}
-  export type DatasetDataField = Record<string, unknown>;
+  export type DataFieldDragStartedEventDetail = Record<string, unknown>;
+  export type DataFieldDroppedEventDetail = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/data-field-level' {
   export class LuzmoDataFieldLevel extends HTMLElement {}
-  export type DatasetDataField = Record<string, unknown>;
+  export type DataFieldDragStartedEventDetail = Record<string, unknown>;
+  export type DataFieldDroppedEventDetail = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/data-field-panel' {
   export class LuzmoDataFieldPanel extends HTMLElement {}
-
+  export type DataFieldDragStartedEventDetail = Record<string, unknown>;
+  export type DataFieldDroppedEventDetail = Record<string, unknown>;
+  export type DatasetChangedEventDetail = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/data-fields-select' {
   export class LuzmoDataFieldsSelect extends HTMLElement {}
-
+  export type DataFieldsSelectedEventDetail = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/dataset-icon' {
@@ -88,42 +99,44 @@ declare module '@luzmo/analytics-components-kit/dataset-icon' {
 
 declare module '@luzmo/analytics-components-kit/dataset-selector-list' {
   export class LuzmoDatasetSelectorList extends HTMLElement {}
-
+  export type Dataset = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/dataset-selector-row' {
   export class LuzmoDatasetSelectorRow extends HTMLElement {}
-
+  export type Dataset = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/display-settings' {
   export class LuzmoDisplaySettings extends HTMLElement {}
-
+  export type DisplaySettingsRemoveSlotContentEventDetail = Record<string, unknown>;
+  export type DisplaySettingsSlotContentChangedEventDetail = Record<string, unknown>;
+  export type InfoVisibilityChangedEventDetail = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/display-settings-binning' {
   export class LuzmoDisplaySettingsBinning extends HTMLElement {}
-
+  export type DisplaySettingsSlotContentChangedEventDetail = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/display-settings-datetime' {
   export class LuzmoDisplaySettingsDatetime extends HTMLElement {}
-
+  export type DisplaySettingsSlotContentChangedEventDetail = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/display-settings-grand-totals' {
   export class LuzmoDisplaySettingsGrandTotals extends HTMLElement {}
-
+  export type DisplaySettingsSlotContentChangedEventDetail = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/display-settings-numeric' {
   export class LuzmoDisplaySettingsNumeric extends HTMLElement {}
-
+  export type DisplaySettingsSlotContentChangedEventDetail = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/display-settings-period-over-period' {
   export class LuzmoDisplaySettingsPeriodOverPeriod extends HTMLElement {}
-
+  export type DisplaySettingsSlotContentChangedEventDetail = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/filter-expression-picker' {
@@ -163,121 +176,151 @@ declare module '@luzmo/analytics-components-kit/filter-value-picker-numeric' {
 
 declare module '@luzmo/analytics-components-kit/filters' {
   export class LuzmoFilters extends HTMLElement {}
+  export type FiltersChangedEventDetail = Record<string, unknown>;
+}
 
+declare module '@luzmo/analytics-components-kit/formula' {
+  export class LuzmoFormula extends HTMLElement {}
+  export type DatasetsErrorEventDetail = Record<string, unknown>;
+}
+
+declare module '@luzmo/analytics-components-kit/formula-editor' {
+  export class LuzmoFormulaEditor extends HTMLElement {}
+  export type DatasetsErrorEventDetail = Record<string, unknown>;
+  export type ExpressionChangedEventDetail = Record<string, unknown>;
+  export type ValidityChangedEventDetail = Record<string, unknown>;
+}
+
+declare module '@luzmo/analytics-components-kit/formula-field' {
+  export class LuzmoFormulaField extends HTMLElement {}
+  export type DatasetsErrorEventDetail = Record<string, unknown>;
+  export type ExpressionChangedEventDetail = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/item-grid' {
   export class LuzmoItemGrid extends HTMLElement {}
-
+  export type GridItemActionEventDetail = Record<string, unknown>;
+  export type GridItemStatesChangedEventDetail = Record<string, unknown>;
+  export type GridLifecycleEventDetail = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/item-option' {
   export class LuzmoItemOption extends HTMLElement {}
-
+  export type ItemOptionsChangedEventDetail = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/item-option-action-button-group' {
   export class LuzmoItemOptionActionButtonGroup extends HTMLElement {}
-
+  export type ItemOptionChangedEventDetail = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/item-option-color-palette-picker' {
   export class LuzmoItemOptionColorPalettePicker extends HTMLElement {}
-
+  export type ItemOptionChangedEventDetail = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/item-option-color-picker' {
   export class LuzmoItemOptionColorPicker extends HTMLElement {}
-
+  export type ItemOptionChangedEventDetail = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/item-option-color-range' {
   export class LuzmoItemOptionColorRange extends HTMLElement {}
-
+  export type ItemOptionChangedEventDetail = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/item-option-multi-language-field' {
   export class LuzmoItemOptionMultiLangField extends HTMLElement {}
-
+  export type ItemOptionChangedEventDetail = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/item-option-number-field' {
   export class LuzmoItemOptionNumberField extends HTMLElement {}
-
+  export type ItemOptionChangedEventDetail = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/item-option-panel' {
   export class LuzmoItemOptionPanel extends HTMLElement {}
-
+  export type ItemOptionsChangedEventDetail = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/item-option-picker' {
   export class LuzmoItemOptionPicker extends HTMLElement {}
-
+  export type ItemOptionChangedEventDetail = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/item-option-position-picker' {
   export class LuzmoItemOptionPositionPicker extends HTMLElement {}
-
+  export type ItemOptionChangedEventDetail = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/item-option-positions-number-field' {
   export class LuzmoItemOptionPositionsNumberField extends HTMLElement {}
-
+  export type ItemOptionChangedEventDetail = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/item-option-radio-button-group' {
   export class LuzmoItemOptionRadioButtonGroup extends HTMLElement {}
-
+  export type ItemOptionChangedEventDetail = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/item-option-slider' {
   export class LuzmoItemOptionSlider extends HTMLElement {}
-
+  export type ItemOptionChangedEventDetail = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/item-option-switch' {
   export class LuzmoItemOptionSwitch extends HTMLElement {}
-
+  export type ItemOptionChangedEventDetail = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/item-option-text-field' {
   export class LuzmoItemOptionTextField extends HTMLElement {}
-
+  export type ItemOptionChangedEventDetail = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/item-slot-drop' {
   export class LuzmoItemSlotDrop extends HTMLElement {}
   export type InfoVisibilityChangedEventDetail = Record<string, unknown>;
   export type SlotContentsChangedEventDetail = Record<string, unknown>;
+  export type SlotMenuActiveEventDetail = Record<string, unknown>;
+  export type SlotMenuHighlightEventDetail = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/item-slot-drop-panel' {
   export class LuzmoItemSlotDropPanel extends HTMLElement {}
-
+  export type SlotConstraintTriggeredEventDetail = Record<string, unknown>;
+  export type SlotsContentsChangedEventDetail = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/item-slot-picker' {
   export class LuzmoItemSlotPicker extends HTMLElement {}
-
+  export type SlotContentsChangedEventDetail = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/item-slot-picker-panel' {
   export class LuzmoItemSlotPickerPanel extends HTMLElement {}
-
+  export type DatasetChangedEventDetail = Record<string, unknown>;
+  export type DatasetConstraintTriggeredEventDetail = Record<string, unknown>;
+  export type SlotConstraintTriggeredEventDetail = Record<string, unknown>;
+  export type SlotsContentsChangedEventDetail = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/slot-menu' {
   export class LuzmoSlotMenu extends HTMLElement {}
-
+  export type InfoVisibilityChangedEventDetail = Record<string, unknown>;
+  export type SlotContentsChangedEventDetail = Record<string, unknown>;
+  export type SlotMenuActiveEventDetail = Record<string, unknown>;
+  export type SlotMenuHighlightEventDetail = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/slot-menu-list' {
   export class LuzmoSlotMenuList extends HTMLElement {}
-
+  export type SlotListChangedEventDetail = Record<string, unknown>;
 }
 
 declare module '@luzmo/analytics-components-kit/viz-item-menu' {
   export class LuzmoVizItemMenu extends HTMLElement {}
-
+  export type VizItemMenuButtonClickedEventDetail = Record<string, unknown>;
+  export type VizItemMenuSelectedChangedEventDetail = Record<string, unknown>;
 }

package/react/types.ts

@@ -34,10 +34,14 @@ 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/data-fields-select/types';
+export type * from './components/ai-interaction-textarea/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';

package/react/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/react/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 {};

package/react/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/react/utils/formula/codemirror/actions.d.ts

@@ -0,0 +1,35 @@
+import type { EditorView } from '@codemirror/view';
+/**
+ * Replaces the entire document content. Used to set the initial / external expression.
+ */
+export declare function setEditorContent(view: EditorView, content: string): void;
+/**
+ * Inserts content at the current selection (replacing any selected text), focusing first.
+ */
+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/react/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/react/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/react/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/react/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/react/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;
+}