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

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

@@ -0,0 +1,24 @@
+import type { LuzmoChart } from '../../types';
+import type { AiPromptCustomItemInput, AiPromptItemTask, AiPromptScreenMode, DashboardStatePayload } from './ai-prompt-types';
+/** Configuration for one built-in agent. Omitted context preserves the same agent's context; null clears it. */
+export type AiChatAgentConfig = {
+    type: 'item';
+    context?: {
+        chart?: LuzmoChart | null;
+        task?: AiPromptItemTask;
+    } | null;
+} | {
+    type: 'dashboard';
+    context?: {
+        dashboard?: DashboardStatePayload | null;
+        currentScreenMode?: AiPromptScreenMode;
+    } | null;
+} | {
+    type: 'custom-item';
+    context?: {
+        customItem?: AiPromptCustomItemInput['value'] | null;
+    } | null;
+} | {
+    type: 'analyst';
+    context?: null;
+};

package/components/ai-interaction-textarea/ai-interaction-textarea.d.ts

@@ -0,0 +1,239 @@
+import '@luzmo/lucero/action-button';
+import '@luzmo/lucero/icon';
+import '@luzmo/lucero/prompt-box';
+import { LitElement, PropertyValues, TemplateResult } from 'lit';
+import type { Agent } from '../../types/agent.types';
+import type { Dataset } from '../../types/dataset.types';
+import type { PromptBoxAttachment, PromptBoxFileIcons } from './types';
+import '../dataset-icon';
+import '../dataset-selector-row';
+declare const LuzmoAiInteractionTextarea_base: typeof LitElement & {
+    new (...args: any[]): import("../../utils/base/sized-mixin").SizedElementInterface;
+    prototype: import("../../utils/base/sized-mixin").SizedElementInterface;
+};
+/**
+ * @customElement luzmo-ai-interaction-textarea
+ * @summary A textarea for AI interaction with dataset selection. Uses Lucero `luzmo-prompt-box` for visuals; theme it with `--luzmo-prompt-box-*` on this host or an ancestor.
+ * @fires {CustomEvent<PromptSubmittedEventDetail>} prompt-submitted - Fired when a prompt is submitted with selected datasets
+ * @fires {CustomEvent<void>} prompt-stopped - Fired when a running prompt is stopped
+ *
+ * @property {boolean} disabled - When true, disables the entire component (opacity 60%, no interactions)
+ * @property {boolean} single-line - When true, starts in compact single-line mode and auto-expands as needed
+ * @property {boolean} hide-dataset-button - When true, hides the "+ Add dataset" button
+ * @property {boolean} hide-dataset-icons - When true, hides dataset-specific icons in selector tags and `@` mention dataset headers
+ * @property {number} max-visible-selected-datasets - Maximum number of selected dataset tags shown before the overflow control (default: 5)
+ * @property {boolean} disable-dataset-modification - When true, disables the "+ Add dataset" button and disables dataset pill removal
+ * @property {boolean} hide-selected-datasets - When true, hides the dataset row entirely
+ * @property {boolean} hide-agents - When true, hides the Agents section in the add dropdown and ignores `selectedAgent` for `require-dataset` and `prompt-submitted`
+ * @property {boolean} disable-column-mentions - When true, disables `@` trigger mentions completely
+ * @property {boolean} is-generating - When true, shows a spinning loader icon instead of the submit arrow
+ * @property {boolean} stoppable - When true, shows a stop control while `is-generating` is true
+ * @property {string} value - The current value of the textarea (can be controlled from parent to clear or set text)
+ * @property {boolean} retain-on-submit - When true, retains the input value after submission (default: false, clears on submit)
+ * @property {boolean} require-dataset - When true, a selected agent or at least one selected dataset is required before the prompt can be submitted
+ * @property {boolean} allow-images - When true, enables image attachments (paste or file picker); uploads eagerly on attach
+ * @property {boolean} allow-voice-input - When true, shows Lucero mic recording and streams transcript via `POST /aidictation`
+ * @property {string[]} accepted-file-types - Accepted MIME types or extensions for attachments (e.g. `image/png`, `.webp`)
+ * @property {string} api-version - API version for built-in `POST /upload` and `/aidictation` (default `0.1.0`)
+ * @property {Function} uploadAttachments - Optional override for eager image upload on attach; return one signed URL per file
+ *
+ * @attr size - Size of the prompt box, its dataset row and its attachment button: `s`, `m` (default), `l` or `xl`
+ *
+ * @property {string} --luzmo-ai-interaction-textarea-disabled-opacity - Opacity of the host when `disabled` (does not map to Lucero prompt-box tokens)
+ */
+export declare class LuzmoAiInteractionTextarea extends LuzmoAiInteractionTextarea_base {
+    static styles: import("lit").CSSResult;
+    static tagName: string;
+    /**
+     * Placeholder text for the textarea
+     */
+    placeholder: string;
+    /**
+     * Array of selected datasets
+     */
+    selectedDatasets: Dataset[];
+    /**
+     * Auth key for DataBroker authentication
+     */
+    authKey: string;
+    /**
+     * Auth token for DataBroker authentication
+     */
+    authToken: string;
+    /**
+     * API URL for DataBroker
+     * @default https://api.luzmo.com
+     */
+    apiUrl: string;
+    /**
+     * The URL of the app server for thumbnails and assets
+     * @default https://app.luzmo.com
+     */
+    appServer: string;
+    /** When true, shows public datasets alongside the user's other datasets. */
+    includePublicDatasets: boolean;
+    /**
+     * Alias for includePublicDatasets.
+     * @deprecated Use includePublicDatasets instead.
+     */
+    get flagOpendata(): boolean;
+    set flagOpendata(value: boolean);
+    /**
+     * When true, disables the entire component (sets opacity to 60% and prevents all interactions)
+     */
+    disabled: boolean;
+    /**
+     * When true, starts in compact single-line mode and auto-expands as needed
+     */
+    singleLine: boolean;
+    /**
+     * When true, hides the "+ Add dataset" button
+     */
+    hideDatasetButton: boolean;
+    /**
+     * When true, hides dataset-specific icons in selector tags and @ mention dataset headers
+     */
+    hideDatasetIcons: boolean;
+    /** Maximum number of selected dataset tags shown before the overflow control. */
+    maxVisibleSelectedDatasets: number;
+    /**
+     * The saved Agent the prompt is scoped to, or null
+     */
+    selectedAgent: Agent | null;
+    /**
+     * When true, hides the Agents section in the add dropdown and ignores `selectedAgent` for `require-dataset` and `prompt-submitted`
+     */
+    hideAgents: boolean;
+    /**
+     * When true, disables the "+ Add dataset" button and disables dataset pill removal
+     */
+    disableDatasetModification: boolean;
+    /**
+     * When true, hides the dataset row entirely
+     */
+    hideSelectedDatasets: boolean;
+    /**
+     * When true, disables @ trigger mentions completely
+     */
+    disableColumnMentions: boolean;
+    /**
+     * When true, shows a spinning loader icon instead of the submit arrow
+     */
+    isGenerating: boolean;
+    /**
+     * When true, shows a stop control on the prompt box while `isGenerating` is true
+     */
+    stoppable: boolean;
+    /**
+     * The current value of the textarea (controlled from parent)
+     */
+    value: string;
+    /**
+     * When true, retains the input value after submitting a prompt (default: false)
+     * When false (default), clears the textarea value after submission
+     */
+    retainOnSubmit: boolean;
+    /**
+     * When true, a selected agent or at least one selected dataset is required before the prompt can be submitted
+     */
+    requireDataset: boolean;
+    /** When true, enables image attachments via paste or the file picker. */
+    allowImages: boolean;
+    /** When true, shows Lucero's mic control; the `POST /aidictation` transcript is inserted, never auto-sent. */
+    allowVoiceInput: boolean;
+    /** Accepted attachment MIME types or extensions. */
+    acceptedFileTypes: string[];
+    /** API version for built-in `POST /upload` and `POST /aidictation` (default `0.1.0`). */
+    apiVersion: string;
+    /** Optional upload override; return one signed URL per file. */
+    uploadAttachments?: (files: File[], options?: {
+        signal?: AbortSignal;
+    }) => Promise<string[]>;
+    /** Custom icons for non-image attachment tiles, keyed by extension. */
+    fileIcons: PromptBoxFileIcons;
+    private _promptValue;
+    private _isPromptValid;
+    private _fieldTriggerOptions;
+    private _datasetsFieldConfig;
+    private _attachmentError;
+    /** True while Lucero is capturing microphone audio. */
+    private _isRecording;
+    /** True while `/aidictation` is in flight (awaiting / streaming transcript). */
+    private _isTranscribing;
+    private _activeFieldRequestId;
+    private readonly _attachmentUploads;
+    private _pendingAttachmentSync;
+    private _attachmentSyncScheduled;
+    private _attachmentErrorClearHandle;
+    private _submitInProgress;
+    /** True from the start of a voice session until it completes, fails, or is cancelled. */
+    private _voiceSessionActive;
+    /** Exact prompt contents from when the current voice session started. */
+    private _preRecordingValue;
+    /** Text before the insert point (cursor at recording start). */
+    private _voicePrefix;
+    /** Text after the insert point (cursor at recording start). */
+    private _voiceSuffix;
+    /** Accumulated transcript for the current dictation request. */
+    private _streamedTranscript;
+    private _transcriptionController;
+    private _promptBox?;
+    private get _voiceBusy();
+    private get _buttonDisabled();
+    private get _activeAgent();
+    private get _promptPending();
+    private get _promptReadonly();
+    private get _actionsDisabled();
+    private get _fieldTriggers();
+    private _renderFieldTriggerIcon;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private _configureBroker;
+    private _handlePromptInput;
+    openFilePicker(): void;
+    addFiles(files: File[]): string[];
+    removeAttachment(id: string): void;
+    setAttachmentLoading(id: string, loading: boolean): void;
+    clearAttachments(): void;
+    getAttachments(): PromptBoxAttachment[];
+    getAttachmentUrls(attachments?: PromptBoxAttachment[]): string[];
+    private _handleAttachClick;
+    private _showAttachmentError;
+    private _cleanupAttachmentUpload;
+    private _abortAllAttachmentUploads;
+    private _uploadSingleFile;
+    private _startAttachmentUpload;
+    private _handleAttachmentsChange;
+    private _syncAttachments;
+    private _waitForAttachmentUploads;
+    private _submitPrompt;
+    private _handleDatasetSelected;
+    private _handleDatasetRemoved;
+    private _handleAgentSelected;
+    private _handleAgentRemoved;
+    private _getLocalizedFieldLabel;
+    private _mapColumnToTriggerOption;
+    private _mapFormulaToTriggerOption;
+    private _updateFieldTriggerOptionsFromConfig;
+    private _refreshDatasetsFieldConfig;
+    private _handlePromptSubmit;
+    private _handlePromptStop;
+    private _handleVoiceKeydown;
+    private _getCaretTextOffset;
+    private _setPromptText;
+    private _captureVoiceInsertPoint;
+    private _applyStreamedTranscript;
+    private _resetVoiceSessionState;
+    private _abortTranscription;
+    private _cancelVoiceSession;
+    private _handleRecord;
+    private _handleRecordCancel;
+    private _handleRecordError;
+    private _handleRecordingComplete;
+    private _transcribeRecording;
+    private _syncControlledValueToPromptBox;
+    protected willUpdate(changedProperties: PropertyValues): void;
+    protected updated(changedProperties: PropertyValues): void;
+    protected render(): TemplateResult;
+}
+export {};

package/components/ai-interaction-textarea/index.d.ts

@@ -0,0 +1,10 @@
+import { LuzmoAiInteractionTextarea } from './ai-interaction-textarea';
+declare global {
+    interface HTMLElementTagNameMap {
+        'luzmo-ai-interaction-textarea': LuzmoAiInteractionTextarea;
+    }
+}
+export { LuzmoAiInteractionTextarea } from './ai-interaction-textarea';
+export type { PromptBoxAttachment, PromptBoxFileIcons, PromptSubmittedEventDetail } from './types';
+export type { Agent } from '../../types/agent.types';
+export type { Dataset } from '../../types/dataset.types';

package/components/ai-interaction-textarea/types.d.ts

@@ -0,0 +1,12 @@
+import type { PromptBoxAttachment, PromptBoxFileIcons } from '@luzmo/lucero';
+import type { Agent } from '../../types/agent.types';
+import type { Dataset } from '../../types/dataset.types';
+export type { PromptBoxAttachment, PromptBoxFileIcons };
+export interface PromptSubmittedEventDetail {
+    prompt: string;
+    selectedDatasets: Dataset[];
+    selectedAgent: Agent | null;
+    attachments: PromptBoxAttachment[];
+    /** Signed image URLs from eager upload on attach, ordered to match image attachments. */
+    attachmentUrls: string[];
+}

package/components/data-field/data-field.d.ts

@@ -0,0 +1,31 @@
+import { TemplateResult } from 'lit';
+import { LuzmoElement } from '../../utils/base';
+import './../data-field-level';
+import type { DatasetDataField } from '../../types/dataset-data-field.types';
+declare const LuzmoDataField_base: (new (...args: any[]) => {
+    language: string;
+}) & typeof LuzmoElement & {
+    new (...args: any[]): import("../../utils/base/sized-mixin").SizedElementInterface;
+    prototype: import("../../utils/base/sized-mixin").SizedElementInterface;
+};
+/**
+ * @customElement luzmo-data-field
+ * @fires {CustomEvent<DataFieldDroppedEventDetail>} luzmo-data-field-dropped - Announces that the data field has been dropped
+ * @fires {CustomEvent<DataFieldDragStartedEventDetail>} luzmo-data-field-drag-started - Announces that the drag is started on the data field
+ */
+export declare class LuzmoDataField extends LuzmoDataField_base {
+    static styles: import("lit").CSSResult;
+    /** Visual treatment of the field: `highlight` to emphasize it, or `normal` (default). */
+    variant: 'highlight' | 'normal';
+    /** Whether the data field is disabled (non-interactive and visually muted). */
+    disabled: boolean;
+    /** Hides the expandable sublevel rows (datetime levels and hierarchy levels). */
+    hideSublevels: boolean;
+    /** Hides the data type icon shown before the field label. */
+    hideTypeIcon: boolean;
+    /** The dataset data field descriptor to render (a column or formula field). */
+    data: DatasetDataField;
+    private renderSublevels;
+    protected render(): TemplateResult;
+}
+export {};

package/components/data-field/index.d.ts

@@ -0,0 +1,9 @@
+import { LuzmoDataField } from './data-field';
+declare global {
+    interface HTMLElementTagNameMap {
+        'luzmo-data-field': LuzmoDataField;
+    }
+}
+export { LuzmoDataField } from './data-field';
+export type { DatasetDataFieldWithSublevel } from './types';
+export type { DataFieldDragStartedEventDetail, DataFieldDroppedEventDetail } from '../../types/data-field-events.types';

package/components/data-field/types.d.ts

@@ -0,0 +1,4 @@
+import type { DatasetDataField } from '../../types/dataset-data-field.types';
+export type DatasetDataFieldWithSublevel = DatasetDataField & {
+    sublevelLabel?: string;
+};

package/components/data-field-level/data-field-level.d.ts

@@ -0,0 +1,40 @@
+import '@luzmo/lucero/icon';
+import '@luzmo/lucero/tooltip';
+import { PropertyValues, TemplateResult } from 'lit';
+import { LuzmoElement } from '../../utils/base';
+import type { DatasetDataField } from '../../types/dataset-data-field.types';
+declare const LuzmoDataFieldLevel_base: typeof LuzmoElement & {
+    new (...args: any[]): import("../../utils/base/sized-mixin").SizedElementInterface;
+    prototype: import("../../utils/base/sized-mixin").SizedElementInterface;
+};
+/**
+ * @customElement luzmo-data-field-level
+ * @fires {CustomEvent<DataFieldDroppedEventDetail>} luzmo-data-field-dropped - Announces that the data field has been dropped
+ * @fires {CustomEvent<DataFieldDragStartedEventDetail>} luzmo-data-field-drag-started - Announces that the drag is started on the data field
+ */
+export declare class LuzmoDataFieldLevel extends LuzmoDataFieldLevel_base {
+    static styles: import("lit").CSSResult;
+    /** Visual treatment of the level: `highlight` to emphasize it, or `normal`. */
+    variant?: 'highlight' | 'normal';
+    /** Hides the data type icon shown before the level label. */
+    hideTypeIcon?: boolean;
+    /** Whether this is rendered as a nested sublevel row (indented under a parent field). */
+    sublevel?: boolean;
+    /** The language in which to display the level labels. */
+    language: string;
+    /** Whether the level is disabled (non-interactive and visually muted). */
+    disabled: boolean;
+    /** The dataset data field descriptor (column or formula field) this level represents. */
+    data: DatasetDataField;
+    private _cleanupDraggable;
+    private _isCurrentlyHighlighted;
+    private _handleHighlight;
+    private _clearHighlight;
+    disconnectedCallback(): void;
+    connectedCallback(): void;
+    private dataFieldLevelDropped;
+    private dataFieldLevelDragStarted;
+    protected firstUpdated(_changedProperties: PropertyValues): void;
+    protected render(): TemplateResult;
+}
+export {};

package/components/data-field-level/helpers/generate-preview.d.ts

@@ -0,0 +1,9 @@
+interface GenerateDragPreviewArgs {
+    source: {
+        element: HTMLElement;
+        data: Record<string, unknown>;
+    };
+    nativeSetDragImage: ((image: Element, offsetX: number, offsetY: number) => void) | null;
+}
+export declare const generateDragPreview: (args: GenerateDragPreviewArgs) => HTMLDivElement;
+export {};

package/components/data-field-level/index.d.ts

@@ -0,0 +1,8 @@
+import { LuzmoDataFieldLevel } from './data-field-level';
+declare global {
+    interface HTMLElementTagNameMap {
+        'luzmo-data-field-level': LuzmoDataFieldLevel;
+    }
+}
+export { LuzmoDataFieldLevel } from './data-field-level';
+export type { DataFieldDragStartedEventDetail, DataFieldDroppedEventDetail } from '../../types/data-field-events.types';

package/components/data-field-panel/data-field-panel.d.ts

@@ -0,0 +1,231 @@
+import '@luzmo/lucero/progress-circle';
+import '@luzmo/lucero/search';
+import '@luzmo/lucero/select';
+import { PropertyValues, TemplateResult } from 'lit';
+import { LuzmoElement } from '../../utils/base';
+import '../data-field';
+import type { DatasetDataFields } from './types';
+declare const LuzmoDataFieldPanel_base: (new (...args: any[]) => {
+    language: string;
+}) & typeof LuzmoElement & {
+    new (...args: any[]): import("../../utils/base/sized-mixin").SizedElementInterface;
+    prototype: import("../../utils/base/sized-mixin").SizedElementInterface;
+};
+/**
+ * A panel component that displays a list of data fields from a dataset.
+ * Optionally includes a dataset picker dropdown to switch between datasets.
+ *
+ * Data can be provided in two ways:
+ * 1. `datasetsDataFields` - Direct data, takes preference when provided
+ * 2. `datasetIds` + auth props - Fetches data automatically using the Luzmo API
+ *
+ * @customElement luzmo-data-field-panel
+ *
+ * @fires {CustomEvent<DataFieldDroppedEventDetail>} luzmo-data-field-dropped - Announces that a data field has been dropped
+ * @fires {CustomEvent<DataFieldDragStartedEventDetail>} luzmo-data-field-drag-started - Announces that a drag has started on a data field
+ * @fires {CustomEvent<DatasetChangedEventDetail>} luzmo-dataset-changed - Announces that the selected dataset has changed
+ *
+ * @property {string} container - The main container element
+ * @property {string} dataset-picker - The dataset picker container
+ * @property {string} search - The search input container
+ * @property {string} data-fields-list - The scrollable list of data fields
+ * @property {string} pending-state - The pending state container with progress circle
+ * @property {string} empty-state - The empty state container when no data fields are available
+ */
+export declare class LuzmoDataFieldPanel extends LuzmoDataFieldPanel_base {
+    static styles: import("lit").CSSResult;
+    /**
+     * Event delegation: Listen on the panel to catch bubbling events from all child
+     * luzmo-data-field elements. More efficient than binding to each field,
+     * and no re-binding needed when fields are added/removed.
+     */
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private _handleDataFieldDropped;
+    private _handleDataFieldDragStarted;
+    /**
+     * Array of dataset IDs to fetch and display.
+     * Used as an alternative to datasetsDataFields - when provided (and datasetsDataFields is empty),
+     * the component will fetch the dataset metadata automatically.
+     * Requires apiUrl, authKey, and authToken to be set.
+     */
+    datasetIds: string[];
+    /**
+     * The datasets and their data fields (columns and formulas) to display.
+     * Takes preference over datasetIds when provided.
+     */
+    datasetsDataFields: DatasetDataFields[];
+    /**
+     * The currently selected dataset ID.
+     * If not provided, defaults to the first available dataset.
+     */
+    selectedDatasetId?: string;
+    /**
+     * Whether to show the dataset picker dropdown.
+     * @default false
+     */
+    datasetPicker: boolean;
+    /**
+     * Whether the panel is disabled.
+     */
+    disabled: boolean;
+    /**
+     * Whether the panel is in a pending/loading state.
+     * When true, shows a loading indicator instead of data fields.
+     */
+    pending: boolean;
+    /**
+     * Visual variant for the draggable items.
+     */
+    dataFieldVariant: 'highlight' | 'normal';
+    /**
+     * Whether the search input should use quiet styling.
+     */
+    searchQuiet: boolean;
+    /**
+     * Whether to hide the type icons on data fields.
+     */
+    hideTypeIcon: boolean;
+    /**
+     * Whether to hide the sublevels (datetime levels, hierarchy levels) on data fields.
+     */
+    hideSublevels: boolean;
+    /**
+     * Placeholder text for the dataset picker.
+     */
+    datasetPickerPlaceholder?: string;
+    /**
+     * The Luzmo API URL. Required when using datasetIds.
+     * @default 'https://api.luzmo.com'
+     */
+    apiUrl: string;
+    /**
+     * Authentication key for the Luzmo API. Required when using datasetIds.
+     */
+    authKey?: string;
+    /**
+     * Authentication token for the Luzmo API. Required when using datasetIds.
+     */
+    authToken?: string;
+    /**
+     * Whether to show the search input.
+     * - 'on': Always show search
+     * - 'off': Never show search
+     * - 'auto': Show search when there are more than 20 data fields
+     * @default 'auto'
+     */
+    search: 'on' | 'off' | 'auto';
+    /**
+     * Placeholder text for the search input.
+     */
+    searchPlaceholder?: string;
+    /**
+     * Threshold for auto-showing search (number of items).
+     * @default 20
+     */
+    searchThreshold: number;
+    private _currentDatasetId?;
+    private _searchQuery;
+    /**
+     * Set of dataset IDs that failed to fetch or don't exist.
+     * Used to prevent infinite retry loops for invalid datasets.
+     * TanStack Query handles API errors, but empty results (dataset not found) need tracking.
+     */
+    private _failedDatasetIds;
+    /**
+     * Task for loading data fields for the current dataset.
+     * Automatically re-runs when dependencies change.
+     * TanStack Query handles API-level caching.
+     */
+    private _loadDataFieldsTask;
+    /**
+     * Dataset list items for the picker (id, name, description only).
+     * Loaded separately from the full dataset data using virtual infinite scroll.
+     */
+    private _datasetListItems;
+    /**
+     * Whether the dataset list is being retrieved (for infinite scroll).
+     */
+    private _datasetListRetrieving;
+    /**
+     * Whether the dataset list is in initial pending state.
+     */
+    private _datasetListPending;
+    /**
+     * Whether the dataset names fetch has been attempted (regardless of success or failure).
+     * Used to prevent showing pending state forever after an error.
+     */
+    private _datasetNamesFetchAttempted;
+    /**
+     * Whether there are more datasets to load.
+     */
+    private _hasMoreDatasets;
+    /**
+     * Whether the component is in a pending state for data fields (either external or internal fetch)
+     */
+    private get _isDataFieldsPending();
+    /**
+     * Get the error message from the task if any
+     */
+    private get _error();
+    /**
+     * Get the available datasets for the picker (id, name, description only).
+     * Does NOT include data fields - use _dataFields for the current dataset's data fields.
+     * This getter is stable and doesn't depend on _currentDatasetId or task state,
+     * preventing unnecessary re-renders of the picker when dataset selection changes.
+     */
+    private get _availableDatasets();
+    /**
+     * Get the currently selected dataset
+     */
+    private get _selectedDataset();
+    /**
+     * Get all data fields (columns + formulas) from the selected dataset.
+     * Supports both formats:
+     * - dataFields property: Combined array (from loadDataFieldsForDatasets / DatasetWithDataFields)
+     * - columns/formulas: Separate arrays (from datasetsDataFields / DatasetDataFields)
+     */
+    private get _dataFields();
+    /**
+     * Check if the picker should use API fetching (datasetPicker enabled and no direct data)
+     */
+    private get _shouldFetchDatasetList();
+    /**
+     * Check if search should be shown
+     */
+    private get _showSearch();
+    /**
+     * Get filtered data fields based on search query
+     */
+    private get _filteredDataFields();
+    protected willUpdate(changedProperties: PropertyValues): void;
+    /**
+     * Fetch dataset names and descriptions for the picker.
+     * Uses lightweight API call - columns/formulas are lazy-loaded when a dataset is selected.
+     */
+    private _fetchDatasetNamesForPicker;
+    /**
+     * Load more datasets for the picker (virtual infinite scroll).
+     */
+    private _loadMoreDatasets;
+    /**
+     * Handle scroll event from the dataset picker for infinite scroll.
+     * Only applies when fetching all datasets (not when using datasetIds).
+     */
+    private _handlePickerScrolled;
+    /**
+     * Handle picker opened event - load initial data if needed.
+     */
+    private _handlePickerOpened;
+    private _updateCurrentDatasetId;
+    private _handleDatasetChange;
+    private _getDataFieldKey;
+    private _handleSearchInput;
+    private _renderDatasetPicker;
+    private _renderSearch;
+    private _renderPendingState;
+    private _renderErrorState;
+    private _renderDataFields;
+    protected render(): TemplateResult;
+}
+export {};

package/components/data-field-panel/index.d.ts

@@ -0,0 +1,9 @@
+import { LuzmoDataFieldPanel } from './data-field-panel';
+declare global {
+    interface HTMLElementTagNameMap {
+        'luzmo-data-field-panel': LuzmoDataFieldPanel;
+    }
+}
+export { LuzmoDataFieldPanel } from './data-field-panel';
+export type { DatasetChangedEventDetail, DatasetDataFields } from './types';
+export type { DataFieldDragStartedEventDetail, DataFieldDroppedEventDetail } from '../../types/data-field-events.types';

package/components/data-field-panel/types.d.ts

@@ -0,0 +1,27 @@
+import type { DatasetDataField } from '../../types/dataset-data-field.types';
+/**
+ * Dataset with data fields (columns and formulas) for the panel.
+ * Supports two formats:
+ * 1. Separate columns/formulas arrays (from datasetsDataFields)
+ * 2. Combined dataFields array (from loadDataFieldsForDatasets)
+ */
+export interface DatasetDataFields {
+    /** Unique dataset identifier */
+    id: string;
+    /** Localized dataset name */
+    name: {
+        [key: string]: string;
+    };
+    /** Column data fields (optional when using dataFields) */
+    columns?: DatasetDataField[];
+    /** Formula data fields (optional when using dataFields) */
+    formulas?: DatasetDataField[];
+    /** Combined data fields (from loadDataFieldsForDatasets) */
+    dataFields?: DatasetDataField[];
+}
+/**
+ * Event detail emitted when the selected dataset changes
+ */
+export interface DatasetChangedEventDetail {
+    datasetId: string;
+}