@luzmo/analytics-components-kit 1.0.9-beta.7 → 1.0.9-beta.8

package/components/filters/transformations/clean-filters.d.ts

@@ -0,0 +1,37 @@
+import type { CleanFilter, CleanFilterClauseGroup, FilterClause, FilterCondition, FilterGroup as EditFilterGroup } from '../types';
+type UnknownRecord = Record<string, unknown>;
+/**
+ * A value that names a column rather than holding a literal. Mirrors the shared
+ * `isFilterColumnParam`: a named source stands on its own, while a bare
+ * `expression` needs a dataset to be a reference rather than a value. A reference
+ * missing its dataset still matches, so that clean emit rejects it instead of
+ * passing the raw canonical object through as a value.
+ */
+export declare function isFilterReference(value: unknown): value is UnknownRecord;
+/**
+ * Clean reference -> canonical `parameters[0]`. `columnId` wins over an ad-hoc
+ * expression, and `columnExpression` becomes the canonical reference `expression`.
+ */
+export declare function cleanReferenceToCanonical(reference: UnknownRecord, allowExpressionAlias?: boolean): UnknownRecord;
+/**
+ * Canonical `parameters[0]` -> clean inlined reference. Nested references inside
+ * `discretization.over` and `aggregation` are converted too, `lowestLevel` and
+ * null-valued optional members are dropped, and a reference that cannot be
+ * expressed publicly throws rather than leaking canonical keys into clean output.
+ */
+export declare function canonicalReferenceToClean(reference: UnknownRecord): UnknownRecord;
+/** Clean leaf -> editor condition, restoring the canonical `parameters` tuple. */
+export declare function cleanLeafToCondition(leaf: UnknownRecord, inheritedClause?: FilterClause): FilterCondition;
+/**
+ * Editor condition -> clean leaf. Returns `null` only for a leaf with no
+ * expression, matching the canonical exporter's drop rule. Anything else that
+ * cannot be expressed cleanly throws, the way the shared normalizer does:
+ * dropping a live predicate would silently widen the rows the host applies.
+ */
+export declare function conditionToCleanLeaf(condition: FilterCondition): CleanFilter | null;
+/**
+ * Editor group -> clean clause groups. A group holding both clauses becomes one
+ * `where` group and one `having` group; neither reuses the original group id.
+ */
+export declare function editGroupToCleanGroups(group: EditFilterGroup): CleanFilterClauseGroup[];
+export {};

package/components/filters/transformations/filter-format.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Runtime recognition of the two filter encodings ACK accepts.
+ *
+ * Groups look the same in both: a lowercase `and` / `or` condition plus a
+ * `filters` array. Only the leaves differ, so detection is per leaf rather than
+ * per array, and a payload that mixes the two converts leaf by leaf.
+ */
+/** Shared nesting limit, matching the platform-wide filter depth guard. */
+export declare const MAX_FILTER_NESTING_DEPTH = 20;
+/** Raised when a filter tree cannot be represented in the requested encoding. */
+export declare class FilterUnrepresentableError extends Error {
+    constructor(message: string);
+}
+/** Format label for a filter payload. Diagnostics only; conversion never depends on it. */
+export type DetectedFiltersFormat = 'empty' | 'canonical' | 'clean' | 'mixed' | 'unknown';
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * A group in either encoding, including a leftover uppercase condition. A group
+ * may omit `condition` entirely, which `toLogicalCondition` resolves to `and`;
+ * a condition that is present but not `and` / `or` is not a group.
+ */
+export declare function isFilterGroupLike(value: unknown): value is Record<string, unknown>;
+/** A leaf in either encoding. Groups are excluded by their `condition`. */
+export declare function isFilterLeafLike(value: unknown): value is Record<string, unknown>;
+export declare function hasCleanEncodingMarker(leaf: Record<string, unknown>): boolean;
+/**
+ * Clean references name exactly one source. `columnExpression` is an alias that
+ * loses to `columnId` rather than competing with it, so the two together are one
+ * source; `columnId` with `formulaId` is genuinely ambiguous and is rejected.
+ *
+ * `allowExpressionAlias` covers a standalone reference object, where a bare
+ * `expression` is the ad-hoc column. On a flattened leaf `expression` is the
+ * filter operator instead, so callers there must leave it off.
+ */
+export declare function hasExactlyOneReferenceSource(reference: Record<string, unknown>, allowExpressionAlias?: boolean): boolean;
+/** A flattened leaf: a dataset, exactly one reference source, and no `parameters`. */
+export declare function isCleanFilterLeaf(value: unknown): value is Record<string, unknown>;
+/** A canonical leaf: an ordered `parameters` tuple and no clean inline key. */
+export declare function isCanonicalFilterLeaf(value: unknown): value is Record<string, unknown>;
+/**
+ * A leaf carrying both encodings is ambiguous about which operand is the
+ * predicate, so it is rejected rather than guessed.
+ */
+export declare function assertLeafEncodingNotMixed(leaf: Record<string, unknown>): void;
+/**
+ * A leaf that is clean-encoded but not a valid clean leaf. Called only once
+ * `isCleanFilterLeaf` has rejected it, so that an incomplete reference is
+ * reported rather than silently reinterpreted as an empty canonical leaf.
+ */
+export declare function assertCleanLeafIsComplete(leaf: Record<string, unknown>): void;
+export declare function isFilterClause(value: unknown): value is 'where' | 'having';
+export declare function assertFilterNestingDepth(depth: number): void;
+/** Classifies a filter payload for diagnostics. Never throws. */
+export declare function detectFiltersFormat(input: unknown): DetectedFiltersFormat;

package/components/filters/transformations/transform-filters.d.ts

@@ -0,0 +1,52 @@
+import type { ItemFilterGroup } from '@luzmo/dashboard-contents-types';
+import type { CleanFilterClauseGroup, FilterGroup as EditFilterGroup, FiltersFormat, FiltersInput, FiltersOutput } from '../types';
+export { detectFiltersFormat, FilterUnrepresentableError, MAX_FILTER_NESTING_DEPTH } from './filter-format';
+export type { DetectedFiltersFormat } from './filter-format';
+export interface TransformFiltersOptions {
+    /** `canonical` (default) emits `ItemFilterGroup[]`; `clean` emits `CleanFilterClauseGroup[]`. */
+    format?: FiltersFormat;
+}
+/**
+ * Normalize a group condition to the lowercase `'and' | 'or'` contract.
+ * Accepts legacy uppercase `'AND' | 'OR'` values.
+ */
+export declare function toLogicalCondition(condition: string | undefined): ItemFilterGroup['condition'];
+/**
+ * Transform EditFilterGroup from filters component into the format
+ * expected by luzmo-embed-viz-item (ItemFilterGroup[]), or into the clean
+ * clause groups published as `ItemFilterOutput` / `DashboardFilterOutput`.
+ *
+ * @param filters - Filter group in the internal/legacy filters format
+ * @param options - `format: 'clean'` opts into clean clause-group output
+ * @returns Filter groups in the requested public format
+ *
+ * @example
+ * ```typescript
+ * const vizItemFilters = transformFilters(legacyFiltersGroup);
+ * vizItem.filters = vizItemFilters;
+ *
+ * const cleanFilters = transformFilters(legacyFiltersGroup, { format: 'clean' });
+ * ```
+ */
+export declare function transformFilters(filters: EditFilterGroup | null | undefined): ItemFilterGroup[];
+export declare function transformFilters(filters: EditFilterGroup | null | undefined, options: {
+    format: 'clean';
+}): CleanFilterClauseGroup[];
+export declare function transformFilters(filters: EditFilterGroup | null | undefined, options: {
+    format?: 'canonical';
+}): ItemFilterGroup[];
+export declare function transformFilters(filters: EditFilterGroup | null | undefined, options?: TransformFiltersOptions): FiltersOutput;
+/**
+ * Transform filter groups from luzmo-embed-viz-item format into the format
+ * used internally by luzmo-filters.
+ *
+ * Accepts both halves of the public `ItemFilterOutput` / `DashboardFilterOutput`
+ * unions: canonical `ItemFilterGroup[]` and clean clause groups with flattened
+ * leaves. Nested `and` / `or` groups are preserved, never flattened.
+ *
+ * @param filters - Filter groups from viz-item filters property or getFilters()
+ * @returns FilterGroup array in the internal filters format
+ * @throws FilterUnrepresentableError when a leaf mixes both encodings, matches
+ * neither a complete clean nor a complete canonical encoding, or nesting is too deep
+ */
+export declare function reverseTransformFilters(filters: FiltersInput | null | undefined): EditFilterGroup[];

package/components/filters/types.d.ts

@@ -0,0 +1,65 @@
+import type { ItemFilterGroup, ItemFilterParameterDefinition, ItemFilterProperties } from '@luzmo/dashboard-contents-types';
+import type { CleanFilter, CleanFilterClauseGroup, CleanFilterGroup, CleanRetrievedFilterGroup, DashboardFilterOutput, ItemFilterOutput } from '@luzmo/embed';
+export type FilterParameterType = 'numeric' | 'datetime' | 'hierarchy' | 'array[numeric]' | 'array[datetime]' | 'array[hierarchy]';
+export type FilterParameter = Omit<ItemFilterParameterDefinition, 'type'> & {
+    type: FilterParameterType;
+};
+export interface FilterParameterEventDetail {
+    parameter: FilterParameter;
+}
+export type { CleanFilter, CleanFilterClauseGroup, CleanFilterGroup, CleanRetrievedFilterGroup, DashboardFilterOutput, ItemFilterOutput };
+/** Clause owned by a top-level clean filter group. Nested groups inherit it. */
+export type FilterClause = 'where' | 'having';
+/** Output format for `luzmo-filters-changed` and `transformFilters`. */
+export type FiltersFormat = 'canonical' | 'clean';
+/** Presentation of `luzmo-filters`. `rich` is the editor; `text` and `outline` are read-only views. */
+export type FiltersDisplay = 'rich' | 'text' | 'outline';
+/**
+ * Every filter array `luzmo-filters` and `reverseTransformFilters` accept: both
+ * halves of the public `ItemFilterOutput` / `DashboardFilterOutput` unions.
+ */
+export type FiltersInput = ItemFilterOutput | DashboardFilterOutput;
+/** Every filter array `luzmo-filters` and `transformFilters` can produce. */
+export type FiltersOutput = ItemFilterGroup[] | CleanFilterClauseGroup[];
+/**
+ * Detail of `luzmo-filters-changed`, discriminated by `format` so a consumer
+ * that never opts into clean output keeps the narrow `ItemFilterGroup[]` type.
+ */
+export type FiltersChangedEventDetail = {
+    format: 'canonical';
+    filters: ItemFilterGroup[];
+} | {
+    format: 'clean';
+    filters: CleanFilterClauseGroup[];
+};
+export interface FilterCondition {
+    expression?: string;
+    parameters?: unknown[];
+    /**
+     * Canonical leaf metadata, preserved across ingest, edit, and export so that
+     * `properties.type` (clause), `properties.ignore` (`ignoredItemIds`), and
+     * `properties.id` survive a round trip. Never part of clean output.
+     */
+    properties?: ItemFilterProperties;
+}
+/**
+ * Nested filter group used by the `luzmo-filters` editor.
+ *
+ * `condition` uses the same lowercase `'and' | 'or'` values as `ItemFilterGroup`.
+ * Nested groups live in `filters`; the public `ItemFilterGroup` shape uses `subGroups`.
+ *
+ * Every member below `filters` is optional metadata carried through from the
+ * ingested group. Only `id` and `clause` reach clean output; the rest stay internal.
+ */
+export interface FilterGroup {
+    condition: ItemFilterGroup['condition'];
+    filters: (FilterCondition | FilterGroup)[];
+    id?: string;
+    clause?: FilterClause;
+    origin?: ItemFilterGroup['origin'];
+    datasetId?: string;
+    vizId?: string;
+    itemId?: string;
+    isDrilldown?: boolean;
+    type?: 'injected';
+}

package/components/formula/formula.d.ts

@@ -0,0 +1,66 @@
+import '@luzmo/lucero/icon';
+import '@luzmo/lucero/progress-circle';
+import { type PropertyValues, type TemplateResult } from 'lit';
+import { LuzmoFormulaBase } from '../../utils/formula/base/formula-base';
+import { FormulaDisplayStore } from '../../utils/formula/store/formula-display-store';
+/**
+ * @customElement luzmo-formula
+ * @description A read-only display of a formula. The default `display="rich"`
+ * renders the expression as inline column / aggregation pills (no CodeMirror);
+ * `display="text"` renders it as plain text with an inline column-type icon per
+ * column reference. Column references resolve to their names from the datasets
+ * provided via `datasetsDataFields` or fetched from the Luzmo API via
+ * `dataset-ids` (+ auth). To edit a formula use `luzmo-formula-field` (a single
+ * field) or `luzmo-formula-editor` (the full builder with lists).
+ *
+ * @fires {CustomEvent<ExpressionChangedEventDetail>} luzmo-expression-changed - Fired (debounced) when the formula expression changes; `detail.expression` holds the new expression.
+ * @fires {CustomEvent<DatasetsErrorEventDetail>} luzmo-datasets-error - Fired when fetching datasets by id fails.
+ */
+export declare class LuzmoFormula extends LuzmoFormulaBase {
+    static styles: import("lit").CSSResult;
+    /**
+     * Rendering mode. `rich` (default) renders read-only column / aggregation
+     * pills; `text` renders plain text with an inline type icon per column. Both
+     * are always read-only.
+     */
+    display: 'rich' | 'text';
+    private readonly _groupingDataMap;
+    /** A display uses the lightweight, CodeMirror-free store. */
+    protected _createStore(): FormulaDisplayStore;
+    /** A display never loads (or needs) the CodeMirror input. */
+    protected _shouldLoadInput(): boolean;
+    /** A display is read-only and never emits expression changes. */
+    protected _canEmitExpression(): boolean;
+    /**
+     * Parses the expression into aggregation widgets for the `rich` mode so the
+     * recursive renderer can resolve nested content. The `text` mode renders the
+     * raw expression directly, so it needs no store transform.
+     */
+    protected _applyExternalExpression(): void;
+    protected willUpdate(changedProperties: PropertyValues): void;
+    protected render(): TemplateResult;
+    private _renderPillFormula;
+    /**
+     * Recursively renders an aggregation-widget-syntax string: column references
+     * become column pills, aggregation placeholders become read-only aggregation
+     * pills (with their nested content rendered recursively) and everything else
+     * (operators, parentheses, literals) renders as plain text.
+     */
+    private _renderPillNodes;
+    private _renderOperatorText;
+    /**
+     * Renders a column reference as an inline column pill (data-type icon +
+     * localized label). The markup + styles are duplicated here and in the
+     * CodeMirror column-pill widget; only the icon/label resolution is shared (via
+     * `resolveColumnPresentation`). While datasets are still loading and the column
+     * is unresolved, a spinner is shown instead of the (raw column id) label.
+     */
+    private _renderColumnPill;
+    private _renderAggregationPill;
+    /**
+     * Renders the expression as plain text, replacing every `{datasetId:columnId}`
+     * reference with an inline type icon + column name.
+     */
+    private _renderTextFormula;
+    private _renderColumnReference;
+}

package/components/formula/index.d.ts

@@ -0,0 +1,7 @@
+import { LuzmoFormula } from './formula';
+declare global {
+    interface HTMLElementTagNameMap {
+        'luzmo-formula': LuzmoFormula;
+    }
+}
+export { LuzmoFormula } from './formula';

package/components/formula-codemirror/formula-codemirror.d.ts

@@ -0,0 +1,79 @@
+import { type Completion } from '@codemirror/autocomplete';
+import { type PropertyValues, type TemplateResult } from 'lit';
+import { LuzmoElement } from '../../utils/base';
+import type { FormulaEditorStore } from '../../utils/formula/store/formula-editor-store';
+import type { FormulaEditorDataset } from '../../types/formula.types';
+import '@luzmo/lucero/progress-circle';
+import './pills/formula-empty-argument-pill';
+import './pills/formula-aggregation';
+declare const LuzmoFormulaCodeMirror_base: (new (...args: any[]) => {
+    language: string;
+}) & typeof LuzmoElement;
+/**
+ * @customElement luzmo-formula-codemirror
+ * @description Internal CodeMirror-backed expression engine for the formula
+ * family. Renders columns, empty arguments and aggregation widgets as inline pills,
+ * supports drag-to-insert at the cursor and autocompletion. Used as the editing
+ * surface of `luzmo-formula-field` and `luzmo-formula-editor`, and inside nested
+ * aggregation widgets. Not part of the public API - prefer `luzmo-formula-field`
+ * / `luzmo-formula-editor`, which wire its store + autocompletion for you.
+ *
+ * @fires {CustomEvent<{ content: string }>} luzmo-input-content-changed - Fired when the editor content changes.
+ * @fires {CustomEvent<void>} luzmo-input-focused - Fired when the editor gains focus.
+ */
+export declare class LuzmoFormulaCodeMirror extends LuzmoFormulaCodeMirror_base {
+    static styles: import("lit").CSSResult;
+    /** The shared formula editor store. */
+    store?: FormulaEditorStore;
+    /** Id of the aggregation widget this input belongs to, or null for the root editor. */
+    aggregationWidgetId: string | null;
+    /** Datasets used to render column pills. */
+    datasets: FormulaEditorDataset[];
+    contentLanguage: string;
+    placeholder: string;
+    readonly: boolean;
+    singleLine: boolean;
+    hasError: boolean;
+    editorHeight?: 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;
+    /** The autocompletion options to offer. */
+    autoCompletionList: Completion[];
+    private _view?;
+    private _pendingContent;
+    private readonly _themeCompartment;
+    private readonly _readonlyCompartment;
+    get content(): string;
+    /** Replaces the whole editor content. */
+    setContent(content: string): void;
+    focusEditor(): void;
+    /** Forces the inline pill decorations to be recomputed. */
+    refresh(): void;
+    disconnectedCallback(): void;
+    /** Rebuilds pill decorations when the store signals a refresh (e.g. loading state changed). */
+    private _handleStoreRefresh;
+    protected firstUpdated(_changedProperties: PropertyValues): void;
+    protected updated(changedProperties: PropertyValues): void;
+    /**
+     * Read-only extensions, kept in a compartment so toggling `readonly` after the
+     * view is created can reconfigure them. `readOnly` blocks edits but the view
+     * stays focusable and keeps painting a blinking caret; `editable.of(false)`
+     * also drops the caret (and the contenteditable), which is what a read-only
+     * rendering should show.
+     */
+    private _readonlyExtensions;
+    private _buildDynamicTheme;
+    private _buildExtensions;
+    private _buildDecorations;
+    private _autoComplete;
+    private _cleanupDroppable;
+    private _attachDroppable;
+    private _canDrop;
+    private _handleDrop;
+    protected render(): TemplateResult;
+}
+export {};

package/components/formula-codemirror/index.d.ts

@@ -0,0 +1,7 @@
+import { LuzmoFormulaCodeMirror } from './formula-codemirror';
+declare global {
+    interface HTMLElementTagNameMap {
+        'luzmo-formula-codemirror': LuzmoFormulaCodeMirror;
+    }
+}
+export { LuzmoFormulaCodeMirror } from './formula-codemirror';

package/components/formula-codemirror/pills/formula-aggregation/formula-aggregation.d.ts

@@ -0,0 +1,125 @@
+import '@luzmo/lucero/icon';
+import '@luzmo/lucero/overlay';
+import '@luzmo/lucero/popover';
+import '@luzmo/lucero/select';
+import { type PropertyValues, type TemplateResult } from 'lit';
+import { LuzmoElement } from '../../../../utils/base';
+import type { FormulaEditorStore } from '../../../../utils/formula/store/formula-editor-store';
+import { type AggregationWidgetConfig } from '../../../../types/formula.types';
+declare const LuzmoFormulaAggregation_base: (new (...args: any[]) => {
+    language: string;
+}) & typeof LuzmoElement;
+/**
+ * @customElement luzmo-formula-aggregation
+ * @description A nested aggregation widget rendered inline inside the formula
+ * editor: an aggregation-function selector, a grouping-scope selector, a nested
+ * expression input and (for `GROUPINEX`) an include / exclude column panel.
+ */
+export declare class LuzmoFormulaAggregation extends LuzmoFormulaAggregation_base {
+    static styles: import("lit").CSSResult;
+    /** Configuration for this aggregation widget (set by the CodeMirror widget). */
+    config: AggregationWidgetConfig['data'];
+    /** The shared formula editor store (set by the CodeMirror widget). */
+    store?: FormulaEditorStore;
+    private _nestedCodeMirror?;
+    private _groupingOverlay?;
+    private _functionSelect?;
+    /** The element the focus/blur listeners are currently bound to, for clean teardown. */
+    private _functionFocusTarget?;
+    /**
+     * Explicit page override for the grouping popover. When `null` the page is
+     * derived from the current grouping (include/exclude scope -> the detail page,
+     * any other scope -> the scope chooser). Deriving the page - rather than
+     * resetting a stored page on open/close - keeps the (still hidden) popover on
+     * the correct page, so reopening a configured include/exclude pill no longer
+     * flashes the scope chooser for a frame.
+     */
+    private _groupingPageOverride;
+    /** Autocompletion options offered while typing inside this aggregation's nested input. */
+    private _autoCompletionList;
+    /** Whether the CodeMirror-backed nested input module has finished loading. */
+    private _codeMirrorLoaded;
+    /**
+     * Whether the aggregation-function select currently holds keyboard-driven focus.
+     * The select's focusable button lives in its shadow DOM, so a pure CSS
+     * `:focus-visible` can't reach it from here; instead we read the browser's own
+     * `:focus-visible` verdict off the focused element so the focus ring only shows
+     * for keyboard users (not after a mouse switch).
+     */
+    private _functionKeyboardFocus;
+    private readonly _groupingTriggerId;
+    private readonly _aggregationDataMap;
+    private readonly _groupingDataMap;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * Binds the keyboard-focus tracking to the `.function-select` element (not the
+     * host). The select swallows the bubbling focusin/focusout, so we use the
+     * capturing focus/blur events; and they must be bound to `.function-select`
+     * rather than the host so focus moving *within* the pill (e.g. Shift+Tab from
+     * the nested value input into the select) still crosses into the listener's
+     * subtree and is detected. Idempotent and safe to call before first render.
+     */
+    private _bindFunctionFocusListeners;
+    private _unbindFunctionFocusListeners;
+    private _handleFunctionFocus;
+    private _handleFunctionBlur;
+    private _handleWidgetsChanged;
+    /**
+     * Datasets reach the pill once (via `config.linkedDatasets`) when the widget
+     * is created. When the editor loads its datasets asynchronously the store is
+     * updated later, so this re-resolves the nested column labels and completions.
+     */
+    private _handleDatasetsRefresh;
+    /** The datasets to use for the nested input: the freshly loaded store ones take precedence. */
+    private get _linkedDatasets();
+    private _recomputeAutoCompletion;
+    private get _widget();
+    /** The grouping popover page: an explicit override (e.g. after pressing back), else derived from the grouping scope. */
+    private get _groupingPage();
+    protected willUpdate(changedProperties: PropertyValues): void;
+    /** Lazily loads the CodeMirror-backed input used for this aggregation's nested expression. */
+    private _ensureCodeMirrorLoaded;
+    protected firstUpdated(): void;
+    protected updated(_changedProperties: PropertyValues): void;
+    /**
+     * When this pill was just created via a list insert / autocomplete, move the
+     * cursor into its nested input so the user can immediately keep typing.
+     */
+    private _focusNestedIfPending;
+    private _updateWidget;
+    private _handleFunctionChange;
+    private _handleGroupingOptionClick;
+    private _handleGroupingBack;
+    private _handleGroupingMenuOpened;
+    private _handleGroupingMenuClosed;
+    /**
+     * Dismiss the grouping overlay on an outside pointerdown.
+     *
+     * The overlay is a `type="manual"` popover (see render) so the browser's native
+     * Popover-API light-dismiss never collapses it when a nested include / exclude
+     * select opens its own `auto` popover - the bug this works around. Manual
+     * overlays also opt out of the overlay stack's outside-pointer dismissal, so we
+     * reinstate it here. Clicks inside the popover - which include the DOM-nested
+     * include / exclude selects and their dropdowns - keep it open; a pointerdown on
+     * the trigger closes it (the click controller suppresses its own toggle while
+     * the overlay is already open). Escape still closes it through the stack's
+     * keydown handler, which does dismiss manual overlays.
+     */
+    private _handleDocumentPointerdown;
+    /**
+     * Whether a pointerdown landed inside the grouping popover content. The popover
+     * content is promoted to the top layer (native popover) but stays in the DOM
+     * tree, so we match the popover / panel by class along the composed path:
+     * after a nested select opens (and re-renders) an element reference can stop
+     * resolving, but the elements are still present in the click's composed path.
+     */
+    private _isPointerInsidePopover;
+    private _closeGroupingMenu;
+    private _handleNestedContentChanged;
+    private _handleIncludeExcludeChange;
+    private _renderGroupingTypesPage;
+    private _renderIncludeExcludePage;
+    protected render(): TemplateResult;
+}
+export {};

package/components/formula-codemirror/pills/formula-aggregation/index.d.ts

@@ -0,0 +1,7 @@
+import { LuzmoFormulaAggregation } from './formula-aggregation';
+declare global {
+    interface HTMLElementTagNameMap {
+        'luzmo-formula-aggregation': LuzmoFormulaAggregation;
+    }
+}
+export { LuzmoFormulaAggregation } from './formula-aggregation';

package/components/formula-codemirror/pills/formula-empty-argument-pill/formula-empty-argument-pill.d.ts

@@ -0,0 +1,28 @@
+import { type PropertyValues, type TemplateResult } from 'lit';
+import { LuzmoElement } from '../../../../utils/base';
+import type { FormulaEditorStore } from '../../../../utils/formula/store/formula-editor-store';
+declare const LuzmoFormulaEmptyArgumentPill_base: (new (...args: any[]) => {
+    language: string;
+}) & typeof LuzmoElement;
+/**
+ * @customElement luzmo-formula-empty-argument-pill
+ * @description An empty argument rendered inline inside the formula editor. Accepts
+ * dropped columns / functions / aggregations and lets the user type a literal value.
+ */
+export declare class LuzmoFormulaEmptyArgumentPill extends LuzmoFormulaEmptyArgumentPill_base {
+    static styles: import("lit").CSSResult;
+    emptyArgumentId: string;
+    parentAggregationWidgetId: string | null;
+    store?: FormulaEditorStore;
+    private _cleanupDroppable;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected firstUpdated(_changedProperties: PropertyValues): void;
+    private _attachDroppable;
+    private _canDrop;
+    private _handleDrop;
+    private _handleFocus;
+    private _handleInput;
+    protected render(): TemplateResult;
+}
+export {};

package/components/formula-codemirror/pills/formula-empty-argument-pill/index.d.ts

@@ -0,0 +1,7 @@
+import { LuzmoFormulaEmptyArgumentPill } from './formula-empty-argument-pill';
+declare global {
+    interface HTMLElementTagNameMap {
+        'luzmo-formula-empty-argument-pill': LuzmoFormulaEmptyArgumentPill;
+    }
+}
+export { LuzmoFormulaEmptyArgumentPill } from './formula-empty-argument-pill';

package/components/formula-codemirror/pills/formula-include-exclude-panel.d.ts

@@ -0,0 +1,38 @@
+import '@luzmo/lucero/action-button';
+import '@luzmo/lucero/field-label';
+import '@luzmo/lucero/icon';
+import '@luzmo/lucero/select';
+import '@luzmo/lucero/tooltip';
+import { type TemplateResult } from 'lit';
+import { type ElementSize } from '../../../utils/base';
+import type { FormulaEditorDataset } from '../../../types/formula.types';
+export interface IncludeExcludePanelParams {
+    /** The linked datasets whose columns can be included / excluded. */
+    datasets: FormulaEditorDataset[];
+    /** Columns to always group by, as full `datasetId:columnId` references. */
+    includedColumns: string[];
+    /** Columns to never group by, as full `datasetId:columnId` references. */
+    excludedColumns: string[];
+    /** Language used to localize column names. */
+    contentLanguage: string;
+    /** Size of the surrounding editor. */
+    size?: ElementSize;
+    /** Renders the picker read-only (no adding, removing or moving). */
+    readonly?: boolean;
+    /** Shows a back button in the header to return to the grouping scope chooser. */
+    showBack?: boolean;
+    /** Called with the next included / excluded selection whenever it changes. */
+    onChange: (includedColumns: string[], excludedColumns: string[]) => void;
+    /** Called when the back button is activated. */
+    onBack: () => void;
+}
+/**
+ * Renders the included / excluded column picker for a `GROUPINEX` aggregation
+ * grouping. Replaces the former `luzmo-formula-include-exclude-panel` element:
+ * stateless markup driven by the aggregation pill, which owns the widget update.
+ *
+ * The root carries the `include-exclude-panel` class so the aggregation pill can
+ * detect pointerdowns inside the (DOM-nested) panel and keep its grouping
+ * popover open.
+ */
+export declare function renderIncludeExcludePanel(params: IncludeExcludePanelParams): TemplateResult;

package/components/formula-draggable-field/formula-draggable-field.d.ts

@@ -0,0 +1,53 @@
+import type { Placement } from '@luzmo/lucero';
+import '@luzmo/lucero/icon';
+import '@luzmo/lucero/tooltip';
+import { type PropertyValues, type TemplateResult } from 'lit';
+import { LuzmoElement } from '../../utils/base';
+declare const LuzmoFormulaDraggableField_base: typeof LuzmoElement & {
+    new (...args: any[]): import("../../utils/base/sized-mixin").SizedElementInterface;
+    prototype: import("../../utils/base/sized-mixin").SizedElementInterface;
+};
+/**
+ * @customElement luzmo-formula-draggable-field
+ * @description A draggable field that can be dragged onto a drop target or
+ * activated (double-click / keyboard) to insert its value. An optional icon can
+ * be slotted (slot name `icon`) after the drag handle. A tooltip is shown on
+ * hover / focus when either the `description` property is set or rich content is
+ * provided via the `tooltip` slot (the slot takes precedence); its position is
+ * controlled by `tooltip-placement`. The `highlight` variant background can be
+ * themed via `--luzmo-formula-draggable-field-background`.
+ *
+ * Slots: `icon` (optional icon after the drag handle), `tooltip` (optional rich
+ * tooltip content shown on hover / focus).
+ *
+ * @fires {CustomEvent<FormulaDraggableFieldActivateEventDetail>} luzmo-formula-draggable-field-activate - Fired on double-click or keyboard activation.
+ * @fires {CustomEvent<FormulaDraggableFieldDescribeEventDetail>} luzmo-formula-draggable-field-describe - Fired on hover / focus.
+ */
+export declare class LuzmoFormulaDraggableField extends LuzmoFormulaDraggableField_base {
+    static styles: import("lit").CSSResult;
+    /** Free-form, consumer-defined category carried in the drag payload and events. */
+    kind: string;
+    /** Identifier carried in the drag payload and events. */
+    value: string;
+    label: string;
+    /** Optional explanation shown as a hover / focus tooltip on the field. */
+    description: string;
+    /** Placement of the hover / focus tooltip relative to the field. */
+    tooltipPlacement: Placement;
+    /** Visual variant: `default` (transparent) or `highlight` (filled background). */
+    variant: 'default' | 'highlight';
+    disabled: boolean;
+    private _hasIcon;
+    private _hasTooltipSlot;
+    private _cleanupDraggable;
+    private _handleIconSlotChange;
+    private _handleTooltipSlotChange;
+    disconnectedCallback(): void;
+    protected firstUpdated(_changedProperties: PropertyValues): void;
+    private _buildDragPreview;
+    private _handleClick;
+    private _activate;
+    private _describe;
+    protected render(): TemplateResult;
+}
+export {};

package/components/formula-draggable-field/index.d.ts

@@ -0,0 +1,8 @@
+import { LuzmoFormulaDraggableField } from './formula-draggable-field';
+declare global {
+    interface HTMLElementTagNameMap {
+        'luzmo-formula-draggable-field': LuzmoFormulaDraggableField;
+    }
+}
+export { LuzmoFormulaDraggableField } from './formula-draggable-field';
+export type { FormulaDraggableFieldPayload, FormulaDraggableFieldActivateEventDetail, FormulaDraggableFieldDescribeEventDetail } from './types';