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

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 {};

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,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/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/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 '@utils/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[];

package/utils/formula/config/expression-helpers.d.ts

@@ -0,0 +1,42 @@
+import { type FormulaAggregationFunction, type FormulaAggregationFunctionData, type FormulaAggregationWidgetData } from '../../../types/formula.types';
+/**
+ * Generates a unique id, preferring the native crypto API when available.
+ */
+export declare function generateId(): string;
+/**
+ * Returns the placeholder token for a new empty argument.
+ */
+export declare function getEmptyArgumentDropExpression(): string;
+/**
+ * Returns the placeholder token for an aggregation widget.
+ */
+export declare function getAggregationWidgetExpression(aggregationWidgetId: string): string;
+/**
+ * Renders the persisted aggregation widget state back into a formula expression.
+ */
+export declare function getAggregationFunctionExpression(aggregationWidgetData: FormulaAggregationWidgetData | undefined, aggregationFunctionsDataMap: Record<FormulaAggregationFunction, FormulaAggregationFunctionData>): string;
+/**
+ * Replaces the content of every string literal with spaces, keeping the quote
+ * characters and the overall length (and thus every index) intact. Run a syntax
+ * scan (e.g. an aggregation-function regex) against the masked string so matches
+ * inside literals - like `'SUM(x)'` - are ignored, then slice the original.
+ */
+export declare function maskStringLiterals(expression: string): string;
+/**
+ * Finds the index of the closing parenthesis that matches the (implicit) open
+ * parenthesis preceding `startIndex`. Returns -1 when no match is found.
+ */
+export declare function getClosingParenthesisIndex(expression: string, startIndex?: number): number;
+/**
+ * Parses the include / exclude column lists out of a `GROUPINEX(...)` tail
+ * expression of the form `[<included>], [<excluded>]`.
+ */
+export declare function getIncludeExcludeColumnsFromExpression(expression: string): {
+    includedColumns: string[];
+    excludedColumns: string[];
+};
+/**
+ * Returns the color palette used to color-code datasets when more than one
+ * dataset is present.
+ */
+export declare function getColorPalette(theme?: 'dark' | 'light'): string[];

package/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/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/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/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/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/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/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/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/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/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/utils/formula/store/tests/formula-editor-store.test.d.ts

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

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

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

package/components/ai-chat/ai-chat-streaming.d.ts

@@ -1,14 +0,0 @@
-import type { ProgressTreeNode } from '@luzmo/lucero/progress-steps';
-export declare function createInitialProgress(): ProgressTreeNode;
-export declare function hasProgressChunk(value: Record<string, unknown>): boolean;
-export interface StreamingRequestOptions {
-    url: string;
-    body: Record<string, unknown>;
-    signal?: AbortSignal;
-}
-export interface StreamingResponse {
-    body: ReadableStream<Uint8Array>;
-    conversationId: string | null;
-}
-export declare function fetchStreamingResponse(options: StreamingRequestOptions): Promise<StreamingResponse>;
-export declare function readNdjsonStream(body: ReadableStream<Uint8Array>, onChunk: (chunk: Record<string, unknown>) => void): Promise<void>;