@luzmo/analytics-components-kit 1.0.2 → 1.0.3-beta.10

package/react/esm/types.d.ts

@@ -7,8 +7,21 @@
  */
 export type { Column, ColumnSubtype, ColumnType, GenericSlotContent, GridConfig, ItemFilterGroup, OptionConfig, OptionsConfig, OptionTranslation, Slot, SlotConfig, SlotName, SlotPosition, SlotPositioningConfig, ThemeConfig, TranslationOverrides, TranslationsFile, VizItemSlot, VizItemType } from '@luzmo/dashboard-contents-types';
 export type { ElementSize, Placement } from '@luzmo/lucero';
+export type * from './types/ai-chat.types';
+export type * from './types/data-field-events.types';
+export type * from './types/dataset-data-field.types';
+export type * from './types/dataset.types';
+export type * from './types/formula.types';
+export type * from './types/slot.types';
+export type * from './components/dataset-icon/types';
+export type * from './components/display-settings/types';
 export type * from './components/data-field/types';
 export type * from './components/data-field-panel/types';
 export type * from './components/item-slot-drop/types';
 export type * from './components/filters/types';
 export type * from './components/item-grid/types';
+export type * from './components/slot-menu/types';
+export type * from './components/viz-item-menu/types';
+export type * from './utils/data-broker';
+export type * from './utils/time/period-over-period-condition.const';
+export type * from './utils/transformations/convert-datasets-to-data-fields';

package/react/index.ts

@@ -1,9 +1,32 @@
 // Auto-generated React wrappers for Luzmo Analytics Components Kit
 // Generated using @lit/react
 
+import { LuzmoAiChat } from './components/ai-chat.component';
+import { LuzmoAiInteractionTextarea } from './components/ai-interaction-textarea.component';
 import { LuzmoDataField } from './components/data-field.component';
+import { LuzmoDataFieldLevel } from './components/data-field-level.component';
 import { LuzmoDataFieldPanel } from './components/data-field-panel.component';
+import { LuzmoDataFieldsSelect } from './components/data-fields-select.component';
+import { LuzmoDatasetIcon } from './components/dataset-icon.component';
+import { LuzmoDatasetSelectorList } from './components/dataset-selector-list.component';
+import { LuzmoDatasetSelectorRow } from './components/dataset-selector-row.component';
+import { LuzmoDisplaySettings } from './components/display-settings.component';
+import { LuzmoDisplaySettingsBinning } from './components/display-settings-binning.component';
+import { LuzmoDisplaySettingsDatetime } from './components/display-settings-datetime.component';
+import { LuzmoDisplaySettingsGrandTotals } from './components/display-settings-grand-totals.component';
+import { LuzmoDisplaySettingsNumeric } from './components/display-settings-numeric.component';
+import { LuzmoDisplaySettingsPeriodOverPeriod } from './components/display-settings-period-over-period.component';
+import { LuzmoFilterExpressionPicker } from './components/filter-expression-picker.component';
+import { LuzmoFilterItem } from './components/filter-item.component';
+import { LuzmoFilterParameterPicker } from './components/filter-parameter-picker.component';
+import { LuzmoFilterValuePicker } from './components/filter-value-picker.component';
+import { LuzmoFilterValuePickerDatetime } from './components/filter-value-picker-datetime.component';
+import { LuzmoFilterValuePickerHierarchy } from './components/filter-value-picker-hierarchy.component';
+import { LuzmoFilterValuePickerNumeric } from './components/filter-value-picker-numeric.component';
 import { LuzmoFilters } from './components/filters.component';
+import { LuzmoFormula } from './components/formula.component';
+import { LuzmoFormulaEditor } from './components/formula-editor.component';
+import { LuzmoFormulaField } from './components/formula-field.component';
 import { LuzmoItemGrid } from './components/item-grid.component';
 import { LuzmoItemOption } from './components/item-option.component';
 import { LuzmoItemOptionActionButtonGroup } from './components/item-option-action-button-group.component';
@@ -24,10 +47,36 @@ import { LuzmoItemSlotDrop } from './components/item-slot-drop.component';
 import { LuzmoItemSlotDropPanel } from './components/item-slot-drop-panel.component';
 import { LuzmoItemSlotPicker } from './components/item-slot-picker.component';
 import { LuzmoItemSlotPickerPanel } from './components/item-slot-picker-panel.component';
+import { LuzmoSlotMenu } from './components/slot-menu.component';
+import { LuzmoSlotMenuList } from './components/slot-menu-list.component';
+import { LuzmoVizItemMenu } from './components/viz-item-menu.component';
 
+export { LuzmoAiChat, type LuzmoAiChatElement } from './components/ai-chat.component';
+export { LuzmoAiInteractionTextarea, type LuzmoAiInteractionTextareaElement } from './components/ai-interaction-textarea.component';
 export { LuzmoDataField, type LuzmoDataFieldElement } from './components/data-field.component';
+export { LuzmoDataFieldLevel, type LuzmoDataFieldLevelElement } from './components/data-field-level.component';
 export { LuzmoDataFieldPanel, type LuzmoDataFieldPanelElement } from './components/data-field-panel.component';
+export { LuzmoDataFieldsSelect, type LuzmoDataFieldsSelectElement } from './components/data-fields-select.component';
+export { LuzmoDatasetIcon, type LuzmoDatasetIconElement } from './components/dataset-icon.component';
+export { LuzmoDatasetSelectorList, type LuzmoDatasetSelectorListElement } from './components/dataset-selector-list.component';
+export { LuzmoDatasetSelectorRow, type LuzmoDatasetSelectorRowElement } from './components/dataset-selector-row.component';
+export { LuzmoDisplaySettings, type LuzmoDisplaySettingsElement } from './components/display-settings.component';
+export { LuzmoDisplaySettingsBinning, type LuzmoDisplaySettingsBinningElement } from './components/display-settings-binning.component';
+export { LuzmoDisplaySettingsDatetime, type LuzmoDisplaySettingsDatetimeElement } from './components/display-settings-datetime.component';
+export { LuzmoDisplaySettingsGrandTotals, type LuzmoDisplaySettingsGrandTotalsElement } from './components/display-settings-grand-totals.component';
+export { LuzmoDisplaySettingsNumeric, type LuzmoDisplaySettingsNumericElement } from './components/display-settings-numeric.component';
+export { LuzmoDisplaySettingsPeriodOverPeriod, type LuzmoDisplaySettingsPeriodOverPeriodElement } from './components/display-settings-period-over-period.component';
+export { LuzmoFilterExpressionPicker, type LuzmoFilterExpressionPickerElement } from './components/filter-expression-picker.component';
+export { LuzmoFilterItem, type LuzmoFilterItemElement } from './components/filter-item.component';
+export { LuzmoFilterParameterPicker, type LuzmoFilterParameterPickerElement } from './components/filter-parameter-picker.component';
+export { LuzmoFilterValuePicker, type LuzmoFilterValuePickerElement } from './components/filter-value-picker.component';
+export { LuzmoFilterValuePickerDatetime, type LuzmoFilterValuePickerDatetimeElement } from './components/filter-value-picker-datetime.component';
+export { LuzmoFilterValuePickerHierarchy, type LuzmoFilterValuePickerHierarchyElement } from './components/filter-value-picker-hierarchy.component';
+export { LuzmoFilterValuePickerNumeric, type LuzmoFilterValuePickerNumericElement } from './components/filter-value-picker-numeric.component';
 export { LuzmoFilters, type LuzmoFiltersElement } from './components/filters.component';
+export { LuzmoFormula, type LuzmoFormulaElement } from './components/formula.component';
+export { LuzmoFormulaEditor, type LuzmoFormulaEditorElement } from './components/formula-editor.component';
+export { LuzmoFormulaField, type LuzmoFormulaFieldElement } from './components/formula-field.component';
 export { LuzmoItemGrid, type LuzmoItemGridElement } from './components/item-grid.component';
 export { LuzmoItemOption, type LuzmoItemOptionElement } from './components/item-option.component';
 export { LuzmoItemOptionActionButtonGroup, type LuzmoItemOptionActionButtonGroupElement } from './components/item-option-action-button-group.component';
@@ -48,12 +97,38 @@ export { LuzmoItemSlotDrop, type LuzmoItemSlotDropElement } from './components/i
 export { LuzmoItemSlotDropPanel, type LuzmoItemSlotDropPanelElement } from './components/item-slot-drop-panel.component';
 export { LuzmoItemSlotPicker, type LuzmoItemSlotPickerElement } from './components/item-slot-picker.component';
 export { LuzmoItemSlotPickerPanel, type LuzmoItemSlotPickerPanelElement } from './components/item-slot-picker-panel.component';
+export { LuzmoSlotMenu, type LuzmoSlotMenuElement } from './components/slot-menu.component';
+export { LuzmoSlotMenuList, type LuzmoSlotMenuListElement } from './components/slot-menu-list.component';
+export { LuzmoVizItemMenu, type LuzmoVizItemMenuElement } from './components/viz-item-menu.component';
 
 // Array of all React component classes for easy imports
 export const LUZMO_REACT_COMPONENTS = [
+  LuzmoAiChat,
+  LuzmoAiInteractionTextarea,
   LuzmoDataField,
+  LuzmoDataFieldLevel,
   LuzmoDataFieldPanel,
+  LuzmoDataFieldsSelect,
+  LuzmoDatasetIcon,
+  LuzmoDatasetSelectorList,
+  LuzmoDatasetSelectorRow,
+  LuzmoDisplaySettings,
+  LuzmoDisplaySettingsBinning,
+  LuzmoDisplaySettingsDatetime,
+  LuzmoDisplaySettingsGrandTotals,
+  LuzmoDisplaySettingsNumeric,
+  LuzmoDisplaySettingsPeriodOverPeriod,
+  LuzmoFilterExpressionPicker,
+  LuzmoFilterItem,
+  LuzmoFilterParameterPicker,
+  LuzmoFilterValuePicker,
+  LuzmoFilterValuePickerDatetime,
+  LuzmoFilterValuePickerHierarchy,
+  LuzmoFilterValuePickerNumeric,
   LuzmoFilters,
+  LuzmoFormula,
+  LuzmoFormulaEditor,
+  LuzmoFormulaField,
   LuzmoItemGrid,
   LuzmoItemOption,
   LuzmoItemOptionActionButtonGroup,
@@ -73,14 +148,40 @@ export const LUZMO_REACT_COMPONENTS = [
   LuzmoItemSlotDrop,
   LuzmoItemSlotDropPanel,
   LuzmoItemSlotPicker,
-  LuzmoItemSlotPickerPanel
+  LuzmoItemSlotPickerPanel,
+  LuzmoSlotMenu,
+  LuzmoSlotMenuList,
+  LuzmoVizItemMenu
 ] as const;
 
 // List of all available React component names
 export const LUZMO_REACT_COMPONENT_NAMES = [
+  'LuzmoAiChat',
+  'LuzmoAiInteractionTextarea',
   'LuzmoDataField',
+  'LuzmoDataFieldLevel',
   'LuzmoDataFieldPanel',
+  'LuzmoDataFieldsSelect',
+  'LuzmoDatasetIcon',
+  'LuzmoDatasetSelectorList',
+  'LuzmoDatasetSelectorRow',
+  'LuzmoDisplaySettings',
+  'LuzmoDisplaySettingsBinning',
+  'LuzmoDisplaySettingsDatetime',
+  'LuzmoDisplaySettingsGrandTotals',
+  'LuzmoDisplaySettingsNumeric',
+  'LuzmoDisplaySettingsPeriodOverPeriod',
+  'LuzmoFilterExpressionPicker',
+  'LuzmoFilterItem',
+  'LuzmoFilterParameterPicker',
+  'LuzmoFilterValuePicker',
+  'LuzmoFilterValuePickerDatetime',
+  'LuzmoFilterValuePickerHierarchy',
+  'LuzmoFilterValuePickerNumeric',
   'LuzmoFilters',
+  'LuzmoFormula',
+  'LuzmoFormulaEditor',
+  'LuzmoFormulaField',
   'LuzmoItemGrid',
   'LuzmoItemOption',
   'LuzmoItemOptionActionButtonGroup',
@@ -100,7 +201,10 @@ export const LUZMO_REACT_COMPONENT_NAMES = [
   'LuzmoItemSlotDrop',
   'LuzmoItemSlotDropPanel',
   'LuzmoItemSlotPicker',
-  'LuzmoItemSlotPickerPanel'
+  'LuzmoItemSlotPickerPanel',
+  'LuzmoSlotMenu',
+  'LuzmoSlotMenuList',
+  'LuzmoVizItemMenu'
 ] as const;
 
 export type LuzmoReactComponentName = typeof LUZMO_REACT_COMPONENT_NAMES[number];

package/react/luzmo-stub.d.ts

@@ -3,9 +3,32 @@
 
 declare module '@luzmo/analytics-components-kit' {
   export const __placeholder: any;
+  export class LuzmoAiChat extends HTMLElement {}
+  export class LuzmoAiInteractionTextarea extends HTMLElement {}
   export class LuzmoDataField extends HTMLElement {}
+  export class LuzmoDataFieldLevel extends HTMLElement {}
   export class LuzmoDataFieldPanel extends HTMLElement {}
+  export class LuzmoDataFieldsSelect extends HTMLElement {}
+  export class LuzmoDatasetIcon extends HTMLElement {}
+  export class LuzmoDatasetSelectorList extends HTMLElement {}
+  export class LuzmoDatasetSelectorRow extends HTMLElement {}
+  export class LuzmoDisplaySettings extends HTMLElement {}
+  export class LuzmoDisplaySettingsBinning extends HTMLElement {}
+  export class LuzmoDisplaySettingsDatetime extends HTMLElement {}
+  export class LuzmoDisplaySettingsGrandTotals extends HTMLElement {}
+  export class LuzmoDisplaySettingsNumeric extends HTMLElement {}
+  export class LuzmoDisplaySettingsPeriodOverPeriod extends HTMLElement {}
+  export class LuzmoFilterExpressionPicker extends HTMLElement {}
+  export class LuzmoFilterItem extends HTMLElement {}
+  export class LuzmoFilterParameterPicker extends HTMLElement {}
+  export class LuzmoFilterValuePicker extends HTMLElement {}
+  export class LuzmoFilterValuePickerDatetime extends HTMLElement {}
+  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 {}
@@ -26,6 +49,20 @@ declare module '@luzmo/analytics-components-kit' {
   export class LuzmoItemSlotDropPanel extends HTMLElement {}
   export class LuzmoItemSlotPicker extends HTMLElement {}
   export class LuzmoItemSlotPickerPanel extends HTMLElement {}
+  export class LuzmoSlotMenu extends HTMLElement {}
+  export class LuzmoSlotMenuList extends HTMLElement {}
+  export class LuzmoVizItemMenu extends HTMLElement {}
+}
+
+declare module '@luzmo/analytics-components-kit/ai-chat' {
+  export class LuzmoAiChat extends HTMLElement {}
+  export type AiChatCompleteEvent = Record<string, unknown>;
+  export type AiChatStepEvent = Record<string, unknown>;
+}
+
+declare module '@luzmo/analytics-components-kit/ai-interaction-textarea' {
+  export class LuzmoAiInteractionTextarea extends HTMLElement {}
+
 }
 
 declare module '@luzmo/analytics-components-kit/data-field' {
@@ -33,16 +70,124 @@ declare module '@luzmo/analytics-components-kit/data-field' {
   export type DatasetDataField = Record<string, unknown>;
 }
 
+declare module '@luzmo/analytics-components-kit/data-field-level' {
+  export class LuzmoDataFieldLevel extends HTMLElement {}
+  export type DatasetDataField = Record<string, unknown>;
+}
+
 declare module '@luzmo/analytics-components-kit/data-field-panel' {
   export class LuzmoDataFieldPanel extends HTMLElement {}
 
 }
 
+declare module '@luzmo/analytics-components-kit/data-fields-select' {
+  export class LuzmoDataFieldsSelect extends HTMLElement {}
+
+}
+
+declare module '@luzmo/analytics-components-kit/dataset-icon' {
+  export class LuzmoDatasetIcon extends HTMLElement {}
+
+}
+
+declare module '@luzmo/analytics-components-kit/dataset-selector-list' {
+  export class LuzmoDatasetSelectorList extends HTMLElement {}
+
+}
+
+declare module '@luzmo/analytics-components-kit/dataset-selector-row' {
+  export class LuzmoDatasetSelectorRow extends HTMLElement {}
+
+}
+
+declare module '@luzmo/analytics-components-kit/display-settings' {
+  export class LuzmoDisplaySettings extends HTMLElement {}
+
+}
+
+declare module '@luzmo/analytics-components-kit/display-settings-binning' {
+  export class LuzmoDisplaySettingsBinning extends HTMLElement {}
+
+}
+
+declare module '@luzmo/analytics-components-kit/display-settings-datetime' {
+  export class LuzmoDisplaySettingsDatetime extends HTMLElement {}
+
+}
+
+declare module '@luzmo/analytics-components-kit/display-settings-grand-totals' {
+  export class LuzmoDisplaySettingsGrandTotals extends HTMLElement {}
+
+}
+
+declare module '@luzmo/analytics-components-kit/display-settings-numeric' {
+  export class LuzmoDisplaySettingsNumeric extends HTMLElement {}
+
+}
+
+declare module '@luzmo/analytics-components-kit/display-settings-period-over-period' {
+  export class LuzmoDisplaySettingsPeriodOverPeriod extends HTMLElement {}
+
+}
+
+declare module '@luzmo/analytics-components-kit/filter-expression-picker' {
+  export class LuzmoFilterExpressionPicker extends HTMLElement {}
+
+}
+
+declare module '@luzmo/analytics-components-kit/filter-item' {
+  export class LuzmoFilterItem extends HTMLElement {}
+
+}
+
+declare module '@luzmo/analytics-components-kit/filter-parameter-picker' {
+  export class LuzmoFilterParameterPicker extends HTMLElement {}
+
+}
+
+declare module '@luzmo/analytics-components-kit/filter-value-picker' {
+  export class LuzmoFilterValuePicker extends HTMLElement {}
+
+}
+
+declare module '@luzmo/analytics-components-kit/filter-value-picker-datetime' {
+  export class LuzmoFilterValuePickerDatetime extends HTMLElement {}
+
+}
+
+declare module '@luzmo/analytics-components-kit/filter-value-picker-hierarchy' {
+  export class LuzmoFilterValuePickerHierarchy extends HTMLElement {}
+
+}
+
+declare module '@luzmo/analytics-components-kit/filter-value-picker-numeric' {
+  export class LuzmoFilterValuePickerNumeric extends HTMLElement {}
+
+}
+
 declare module '@luzmo/analytics-components-kit/filters' {
   export class LuzmoFilters extends HTMLElement {}
 
 }
 
+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 {}
 
@@ -143,3 +288,18 @@ declare module '@luzmo/analytics-components-kit/item-slot-picker-panel' {
   export class LuzmoItemSlotPickerPanel extends HTMLElement {}
 
 }
+
+declare module '@luzmo/analytics-components-kit/slot-menu' {
+  export class LuzmoSlotMenu extends HTMLElement {}
+
+}
+
+declare module '@luzmo/analytics-components-kit/slot-menu-list' {
+  export class LuzmoSlotMenuList extends HTMLElement {}
+
+}
+
+declare module '@luzmo/analytics-components-kit/viz-item-menu' {
+  export class LuzmoVizItemMenu extends HTMLElement {}
+
+}

package/react/types.ts

@@ -30,12 +30,22 @@ export type {
 
 export type { ElementSize, Placement } from '@luzmo/lucero';
 
+export type * from './types/ai-chat.types';
+export type * from './types/data-field-events.types';
+export type * from './types/dataset-data-field.types';
+export type * from './types/dataset.types';
+export type * from './types/formula.types';
+export type * from './types/slot.types';
 
+export type * from './components/dataset-icon/types';
+export type * from './components/display-settings/types';
 export type * from './components/data-field/types';
 export type * from './components/data-field-panel/types';
 export type * from './components/item-slot-drop/types';
 export type * from './components/filters/types';
 export type * from './components/item-grid/types';
+export type * from './components/slot-menu/types';
+export type * from './components/viz-item-menu/types';
 
 export type * from './utils/data-broker';
 export type * from './utils/time/period-over-period-condition.const';

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/formatter/get-dataset-name.d.ts

@@ -0,0 +1,2 @@
+import type { Dataset } from '../../types/dataset.types';
+export declare function getDatasetName(dataset: Pick<Dataset, 'id' | 'name'>): string;

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