@luzmo/analytics-components-kit 1.0.4 → 1.0.5-beta.1

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;