@luzmo/analytics-components-kit 1.0.1-alpha.15 → 1.0.1-alpha.151

package/react/utils/themes/vivid.d.ts

@@ -0,0 +1,2 @@
+import { type ThemeConfig } from '@luzmo/dashboard-contents-types';
+export declare const vividTheme: ThemeConfig;

package/react/utils/time/formats.const.d.ts

@@ -0,0 +1,4 @@
+export type DateFormats = 'auto' | 'mmdd' | 'ddmm';
+export declare const DATE_FORMATS: Record<DateFormats, () => string>;
+export type DateSeparators = '~' | '.' | '-' | '/';
+export declare const DATE_SEPARATORS: Record<DateSeparators, () => string>;

package/react/utils/time/period-over-period-condition.const.d.ts

@@ -0,0 +1,8 @@
+export declare const PeriodOverPeriodCondition: {
+    readonly HasDatetimeColumnAndNoComparisonFilters: "hasDatetimeColumnAndNoComparisonFilters";
+    readonly NoDatetimeColumnAndNoComparisonFilters: "noDatetimeColumnAndNoComparisonFilters";
+    readonly NoDatetimeColumnButComparisonFilters: "noDatetimeColumnButComparisonFilters";
+    readonly HasDatetimeColumnAndComparisonFilters: "hasDatetimeColumnAndComparisonFilters";
+    readonly OldImplementation: "oldImplementation";
+};
+export type PeriodOverPeriodCondition = (typeof PeriodOverPeriodCondition)[keyof typeof PeriodOverPeriodCondition];

package/react/utils/time/periods.const.d.ts

@@ -0,0 +1,15 @@
+export declare const DATETIME_LEVELS: {
+    level: number;
+    key: string;
+    i18n: () => string;
+}[];
+export declare const DATETIME_AS_STRING_FORMATS_PER_LEVEL: Record<string, {
+    key: string;
+    label: string;
+    i18n: () => string;
+}[]>;
+export declare const DATETIME_WEEKDAY_AND_MONTH_STRING_FORMATS: Record<string, () => string>;
+export declare const WEEK_STARTS_ON: {
+    sunday: () => string;
+    monday: () => string;
+};

package/react/utils/transformations/convert-data-field-to-slot-content.d.ts

@@ -0,0 +1,9 @@
+import type { GenericSlotContent } from '@luzmo/dashboard-contents-types';
+import type { DatasetDataField } from '../../types/dataset-data-field.types';
+/**
+ * Converts data coming from a data field (representing a Dataset column or formula) to the expected format for Luzmo slot contents.
+ * @param data{DatasetDataField} - The DatasetDataField object to convert.
+ * @param isSublevelDrop{boolean} - Whether the drop is a sublevel drop.
+ * @returns - The GenericSlotContent object.
+ */
+export declare const convertDataFieldToSlotContent: (data: DatasetDataField, isSublevelDrop: boolean) => GenericSlotContent;

package/react/utils/transformations/convert-datasets-to-data-fields.d.ts

@@ -0,0 +1,30 @@
+import type { DatasetDataField } from '../../types/dataset-data-field.types';
+import type { DatasetColumnMetadata, DatasetFormulaMetadata, DatasetMetadata } from '../data-broker/index';
+export declare const mapDatasetColumnToDatasetDataField: (datasetId: string, column: DatasetColumnMetadata, options?: {
+    includeHidden?: boolean;
+}) => Extract<DatasetDataField, {
+    columnId: string;
+}> | null;
+export declare const mapDatasetFormulaToDatasetDataField: (datasetId: string, formula: DatasetFormulaMetadata, options?: {
+    includeHidden?: boolean;
+}) => Extract<DatasetDataField, {
+    formulaId: string;
+}> | null;
+export declare const mapDatasetToDataFields: (dataset: DatasetMetadata, options?: {
+    includeHidden?: boolean;
+}) => DatasetDataField[];
+export interface DatasetWithDataFields {
+    id: string;
+    name: Record<string, string>;
+    description?: Record<string, string>;
+    dataFields: DatasetDataField[];
+}
+/**
+ * Converts DataBroker dataset metadata to datasets with data fields.
+ * @param datasets Array of datasets to convert.
+ * @param options Mapping options to control visibility and field types.
+ * @returns Array of datasets, each containing its metadata and data fields.
+ */
+export declare const convertDatasetsToDataFields: (datasets: DatasetMetadata[], options?: {
+    includeHidden?: boolean;
+}) => DatasetWithDataFields[];

package/react/utils/transformations/tests/convert-data-field-to-slot-content.test.d.ts

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

package/react/utils/transformations/tests/convert-datasets-to-data-fields.test.d.ts

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

package/react/utils/types/tests/type-check.test.d.ts

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

package/react/utils/types/type-check.d.ts

@@ -0,0 +1,28 @@
+export declare function isEmpty(value: any): boolean;
+export declare function isString(value: any): value is string;
+export declare function isNumeric(value: any): value is number;
+export declare function isBoolean(value: any): value is boolean;
+export declare function isObject(value: any): boolean;
+export declare function isDate(value: any): value is Date;
+export declare function isEmptyObject(value: any): boolean;
+/**
+ * Validates if a string is a valid UUID v4 format
+ * @param value - The string to validate
+ * @returns true if the string is a valid UUID, false otherwise
+ */
+export declare function isValidUuid(value: unknown): boolean;
+/**
+ * Filters an array of strings to only include valid UUIDs
+ * @param ids - Array of strings to filter
+ * @returns Array containing only valid UUIDs
+ */
+export declare function filterValidUuids(ids: string[]): string[];
+/**
+ * Validates an array of IDs and returns info about invalid ones
+ * @param ids - Array of IDs to validate
+ * @returns Object with valid IDs array and invalid IDs array
+ */
+export declare function validateUuids(ids: string[]): {
+    valid: string[];
+    invalid: string[];
+};

package/storybook/register-components.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Storybook-only entry that registers all custom elements.
+ *
+ * AUTO-GENERATED by `scripts/generate-storybook-register-components.ts`.
+ * Source of truth: `src/index.ts` (only `./components/*` exports are used).
+ */
+import '../components/ai-chat';
+import '../components/ai-interaction-textarea';
+import '../components/data-fields-select';
+import '../components/dataset-icon';
+import '../components/dataset-selector-list';
+import '../components/dataset-selector-row';
+import '../components/display-settings';
+import '../components/display-settings-binning';
+import '../components/display-settings-datetime';
+import '../components/display-settings-grand-totals';
+import '../components/display-settings-numeric';
+import '../components/display-settings-period-over-period';
+import '../components/data-field';
+import '../components/data-field-level';
+import '../components/data-field-panel';
+import '../components/item-slot-drop';
+import '../components/filters';
+import '../components/item-option-panel';
+import '../components/item-option';
+import '../components/item-option-action-button-group';
+import '../components/item-option-color-palette-picker';
+import '../components/item-option-color-picker';
+import '../components/item-option-color-range';
+import '../components/item-option-multi-language-field';
+import '../components/item-option-number-field';
+import '../components/item-option-picker';
+import '../components/item-option-position-picker';
+import '../components/item-option-positions-number-field';
+import '../components/item-option-radio-button-group';
+import '../components/item-option-slider';
+import '../components/item-option-switch';
+import '../components/item-option-text-field';
+import '../components/filter-expression-picker';
+import '../components/filter-item';
+import '../components/filter-value-picker';
+import '../components/filter-value-picker-datetime';
+import '../components/filter-value-picker-hierarchy';
+import '../components/filter-value-picker-numeric';
+import '../components/item-grid';
+import '../components/item-slot-drop-panel';
+import '../components/item-slot-picker-panel';
+import '../components/item-slot-picker';
+import '../components/slot-menu';
+import '../components/slot-menu-list';
+import '../components/viz-item-menu';

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

@@ -0,0 +1,51 @@
+import type { ProgressTreeNode } from '@luzmo/lucero/progress-steps';
+export type { ProgressTreeNode };
+export interface ChatMessage {
+    id?: string;
+    apiMessageId?: string;
+    type: 'user' | 'ai';
+    message: string;
+    progress?: ProgressTreeNode;
+    isError?: boolean;
+    hasChart?: boolean;
+}
+export interface LuzmoChart {
+    version: string;
+    type: string;
+    position: {
+        sizeX: number;
+        sizeY: number;
+        row: number;
+        col: number;
+    };
+    title: Record<string, unknown>;
+    options: Record<string, unknown>;
+    content: Record<string, unknown>;
+    slots: Array<{
+        name: string;
+        content: unknown[];
+    }>;
+    filterGroups?: Array<{
+        condition: string;
+        filters: Array<{
+            expression: string;
+            parameters: unknown[];
+        }>;
+    }>;
+    update?: boolean;
+    aichartId?: string;
+}
+export interface AISampleChart {
+    error?: string;
+    generatedChart: Record<string, unknown> & {
+        feedback: unknown;
+    };
+    question: string;
+    functionCall: string;
+    functionResponse: any;
+    feedback: unknown;
+    conversationId?: string;
+    messageId?: string;
+    message?: string;
+    clarificationQuestion?: string;
+}

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

@@ -0,0 +1,7 @@
+import type { DatasetDataField } from './dataset-data-field.types';
+export interface DataFieldDroppedEventDetail {
+    data: DatasetDataField;
+}
+export interface DataFieldDragStartedEventDetail {
+    data: DatasetDataField;
+}

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

@@ -0,0 +1,53 @@
+import type { Column, Currency, Formula, HierarchyLevel } from '@luzmo/dashboard-contents-types';
+export type ColumnFieldData = {
+    type: Column['type'];
+    name: Column['name'];
+    datasetId: string;
+    formulaId?: never;
+    columnId: Column['id'];
+    formula?: never;
+    level?: number;
+    hierarchyLevels?: Pick<HierarchyLevel, 'id' | 'level' | 'name'>[];
+    currency?: Pick<Currency, 'id' | 'name' | 'symbol'>;
+} & Partial<Pick<Column, 'description' | 'subtype' | 'format' | 'lowestLevel' | 'highestLevel' | 'hierarchy_enabled' | 'duration_levels' | 'duration_format' | 'expression'>>;
+export type FormulaFieldData = {
+    type: Formula['type'];
+    name: Formula['name'];
+    datasetId: string;
+    formulaId: Formula['id'];
+    columnId?: never;
+    formula?: never;
+    level?: number;
+    currency?: Pick<Currency, 'id' | 'name' | 'symbol'>;
+} & Partial<Pick<Formula, 'description' | 'subtype' | 'format' | 'lowestLevel' | 'duration_levels' | 'duration_format' | 'expression'>>;
+/**
+ * An ad hoc formula defined inline (not saved on the dataset).
+ * The `formula` property holds the expression string, e.g. `AVG({datasetId:columnId})`.
+ */
+export type AdHocFormulaFieldData = {
+    type: Column['type'] | Formula['type'];
+    name: Record<string, string>;
+    datasetId: string;
+    formula: string;
+    formulaId?: never;
+    columnId?: never;
+    level?: number;
+    currency?: Pick<Currency, 'id' | 'name' | 'symbol'>;
+} & Partial<Pick<Column, 'description' | 'subtype' | 'format' | 'lowestLevel' | 'highestLevel' | 'duration_levels' | 'duration_format' | 'expression'>>;
+/**
+ * Input shape for ad hoc formulas passed alongside saved formulas in `datasetsDataFields[].formulas`.
+ * The `formula` expression string doubles as the unique identifier in the select value.
+ */
+export type AdHocFormulaInput = {
+    /** The ad hoc formula expression, e.g. `AVG({datasetId:columnId})`. Also used as the option value / identifier. */
+    formula: string;
+    /** Display label. Falls back to a localized "Ad-hoc formula" when not provided. */
+    label?: Record<string, string>;
+    /** The data type of the formula result. */
+    type: Column['type'] | Formula['type'];
+    /** Optional subtype (e.g. `currency`). */
+    subtype?: Column['subtype'] | null;
+    /** Optional format string. */
+    format?: string;
+};
+export type DatasetDataField = ColumnFieldData | FormulaFieldData | AdHocFormulaFieldData;

package/types/dataset.types.d.ts

@@ -0,0 +1,27 @@
+import type { DatasetFormulaMetadata, DatasetMetadata } from '../utils/data-broker';
+import type { AdHocFormulaInput } from './dataset-data-field.types';
+export interface Dataset {
+    id: string;
+    name: string | Record<string, string>;
+    subtype?: string;
+    updated_at?: string;
+    collections?: {
+        id: string;
+        favorite: boolean;
+    }[];
+    account?: {
+        id: string;
+        provider: string;
+        name: string;
+        plugin?: {
+            id: string;
+            thumbnails?: {
+                url: string;
+                size: string;
+            }[];
+        };
+    };
+}
+export type DatasetsDataFields = Pick<DatasetMetadata, 'id' | 'name' | 'columns'> & {
+    formulas: (DatasetFormulaMetadata | AdHocFormulaInput)[];
+};

package/types/slot.types.d.ts

@@ -0,0 +1,15 @@
+import type { GenericSlotContent, SlotName, VizItemSlot } from '@luzmo/dashboard-contents-types';
+export type SlotContent = GenericSlotContent;
+export type SlotConstraintType = 'keepOnlyFirstWhenOtherSlotFilled' | 'clearWhenOtherSlotHasMultipleItems' | 'clearSlotsWhenUnlinkedDataset';
+export interface SlotConstraint {
+    type: SlotConstraintType;
+    affectedSlotName: string;
+    triggeredBySlotName: string;
+}
+export interface SlotConstraintTriggeredEventDetail {
+    triggerSlotName: SlotName;
+    proposedTriggerContents: SlotContent[];
+    originalSlotsContents: VizItemSlot[];
+    proposedSlotsContents: VizItemSlot[];
+    constraints: SlotConstraint[];
+}

package/types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Public types entrypoint.
+ *
+ * This file must not declare types itself. It only re-exports types from the
+ * canonical owner modules (domain `src/types/*`, component `types.ts` files,
+ * and selected utils).
+ */
+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/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/utils/base/base.d.ts

@@ -0,0 +1,16 @@
+import { LitElement, ReactiveElement } from 'lit';
+type Constructor<T = Record<string, unknown>> = {
+    new (...args: any[]): T;
+    prototype: T;
+};
+export interface LuzmoInterface {
+    shadowRoot: ShadowRoot;
+    isLTR: boolean;
+    hasVisibleFocusInTree(): boolean;
+    dir: 'ltr' | 'rtl';
+}
+export declare function LuzmoMixin<T extends Constructor<ReactiveElement>>(constructor: T): T & Constructor<LuzmoInterface>;
+declare const LuzmoElement_base: typeof LitElement & Constructor<LuzmoInterface>;
+export declare class LuzmoElement extends LuzmoElement_base {
+}
+export {};

package/utils/base/focus-visible.d.ts

@@ -0,0 +1,29 @@
+declare global {
+    interface Window {
+        applyFocusVisiblePolyfill?: (scope: Document | ShadowRoot) => void;
+    }
+}
+type Constructor<T = Record<string, unknown>> = {
+    new (...args: any[]): T;
+    prototype: T;
+};
+interface OptionalLifecycleCallbacks {
+    connectedCallback?(): void;
+    disconnectedCallback?(): void;
+    manageAutoFocus?(): void;
+}
+type MixableBaseClass = HTMLElement & OptionalLifecycleCallbacks;
+/**
+ * This mixin function is designed to be applied to a class that inherits
+ * from HTMLElement. It makes it easy for a custom element to coordinate with
+ * the :focus-visible polyfill.
+ *
+ * NOTE(cdata): The code here was adapted from an example proposed with the
+ * introduction of ShadowDOM support in the :focus-visible polyfill.
+ *
+ * @see https://github.com/WICG/focus-visible/pull/196
+ * @param SuperClass The base class implementation to decorate with
+ * implementation that coordinates with the :focus-visible polyfill
+ */
+export declare const FocusVisiblePolyfillMixin: <T extends Constructor<MixableBaseClass>>(SuperClass: T) => T;
+export {};

package/utils/base/focusable.d.ts

@@ -0,0 +1,58 @@
+import { PropertyValues } from 'lit';
+import { LuzmoElement } from './base';
+type DisableableElement = HTMLElement & {
+    disabled?: boolean;
+};
+declare const Focusable_base: typeof LuzmoElement;
+/**
+ * Focusable base class handles tabindex setting into shadowed elements automatically.
+ *
+ * This implementation is based heavily on the aybolit delegate-focus-mixin at
+ * https://github.com/web-padawan/aybolit/blob/master/packages/core/src/mixins/delegate-focus-mixin.js
+ */
+export declare class Focusable extends Focusable_base {
+    /**
+     * Disable this control. It will not receive focus or events
+     */
+    disabled: boolean;
+    /**
+     * When this control is rendered, focus it automatically
+     *
+     * @private
+     */
+    autofocus: boolean;
+    /**
+     * The tab index to apply to this control. See general documentation about
+     * the tabindex HTML property
+     *
+     * @private
+     */
+    get tabIndex(): number;
+    set tabIndex(tabIndex: number);
+    private _tabIndex;
+    private onPointerdownManagementOfTabIndex;
+    private manageFocusElementTabindex;
+    private manipulatingTabindex;
+    /**
+     * @private
+     */
+    get focusElement(): DisableableElement;
+    /**
+     * @public
+     * @returns whether the component should manage its focusElement tab-index or not
+     * Needed for action-menu to be supported in action-group in an accessible way
+     */
+    get selfManageFocusElement(): boolean;
+    focus(options?: FocusOptions): void;
+    blur(): void;
+    click(): void;
+    protected manageAutoFocus(): void;
+    protected firstUpdated(changes: PropertyValues): void;
+    protected update(changedProperties: PropertyValues): void;
+    protected updated(changedProperties: PropertyValues): void;
+    private handleDisabledChanged;
+    protected getUpdateComplete(): Promise<boolean>;
+    private autofocusReady;
+    connectedCallback(): void;
+}
+export {};

package/utils/base/index.d.ts

@@ -0,0 +1,5 @@
+export { LuzmoElement, LuzmoMixin } from './base';
+export { Focusable } from './focusable';
+export { LocalizedMixin } from './localized-mixin';
+export { ElementSizes, SizedMixin } from './sized-mixin';
+export type { ElementSize } from './sized-mixin';

package/utils/base/localized-mixin.d.ts

@@ -0,0 +1,22 @@
+import { LitElement } from 'lit';
+type Constructor<T = {}> = new (...args: any[]) => T;
+/**
+ * A mixin that provides locale synchronization for components using lit-localize.
+ *
+ * This mixin:
+ * - Adds a `language` property (default: 'en')
+ * - Syncs the global locale on first mount (handles case where language equals class default)
+ * - Syncs the global locale when the language property changes
+ *
+ * Usage:
+ * ```ts
+ * @localized()
+ * export class MyComponent extends LocalizedMixin(LitElement) {
+ *   // language property and locale sync inherited
+ * }
+ * ```
+ */
+export declare const LocalizedMixin: <T extends Constructor<LitElement>>(Base: T) => Constructor<{
+    language: string;
+}> & T;
+export {};

package/utils/base/sized-mixin.d.ts

@@ -0,0 +1,17 @@
+import { ReactiveElement } from 'lit';
+type Constructor<T = Record<string, unknown>> = {
+    new (...args: any[]): T;
+    prototype: T;
+};
+export type ElementSize = 'xxs' | 'xs' | 's' | 'm' | 'l' | 'xl' | 'xxl';
+export declare const ElementSizes: Record<string, ElementSize>;
+export type DefaultElementSize = Exclude<ElementSize, 'xxs' | 'xs' | 'xxl'>;
+export interface SizedElementInterface {
+    size: ElementSize;
+}
+export declare function SizedMixin<T extends Constructor<ReactiveElement>>(constructor: T, { validSizes, noDefaultSize, defaultSize }?: {
+    validSizes?: ElementSize[];
+    noDefaultSize?: boolean;
+    defaultSize?: ElementSize;
+}): T & Constructor<SizedElementInterface>;
+export {};

package/utils/color/color-palettes.d.ts

@@ -0,0 +1,17 @@
+export type ColorValue = {
+    colors3?: string[];
+    colors4?: string[];
+    colors5?: string[];
+    colors6?: string[];
+    colors7?: string[];
+    colors8?: string[];
+    colors9?: string[];
+    colors10?: string[];
+    colors11?: string[];
+    colors12?: string[];
+    type: 'divergent' | 'qualitative' | 'sequential' | 'heat';
+};
+export type ColorMap = Record<ColorsClassKey, ColorValue>;
+export type ColorsClassKey = 'Spectral' | 'RdYlGn' | 'RdBu' | 'PiYG' | 'PRGn' | 'RdYlBu' | 'BrBG' | 'RdGy' | 'PuOr' | 'Paired' | 'Set1' | 'Set3' | 'OrRd' | 'PuBu' | 'BuPu' | 'Oranges' | 'BuGn' | 'GnBu' | 'YlOrBr' | 'YlGn' | 'Reds' | 'RdPu' | 'Greens' | 'YlGnBu' | 'Purples' | 'Greys' | 'YlOrRd' | 'PuRd' | 'Blues' | 'PuBuGn' | 'Spectrum' | 'BlueRed' | 'Plasma' | 'Viris' | 'Incan' | 'Fire' | 'Inferno' | 'Ocean' | 'Sunrise';
+export declare function getColorMaps(): ColorMap;
+export declare function getColorMapKeys(type?: 'divergent' | 'qualitative' | 'sequential' | 'heat'): string[];

package/utils/color/extrapolate-color.d.ts

@@ -0,0 +1 @@
+export declare const extrapolateNewColor: (colorStrings: string[], percent?: number) => string;

package/utils/data/load-data-fields-for-datasets.d.ts

@@ -0,0 +1,22 @@
+import { type DataBrokerConfig } from '../data-broker/index';
+import { DatasetWithDataFields } from '../transformations/convert-datasets-to-data-fields';
+export interface LoadDataFieldsOptions {
+    dataBrokerConfig: DataBrokerConfig;
+}
+/**
+ * Convenience helper that configures the shared DataBroker instance,
+ * loads the requested datasets with their metadata, and converts them into
+ * data fields the UI components understand.
+ *
+ * @param datasetIds - Array of dataset IDs to fetch and convert
+ * @param options.dataBrokerConfig - DataBroker configuration
+ * @param options.dataBrokerConfig.apiUrl - Optional Luzmo API endpoint URL (defaults to https://api.luzmo.com)
+ * @param options.dataBrokerConfig.authKey - Optional authentication key for Luzmo API access (required for private datasets)
+ * @param options.dataBrokerConfig.authToken - Optional authentication token for Luzmo API access (required for private datasets)
+ * @returns Promise that resolves to an array of datasets with their data fields
+ * @throws {Error} When datasetIds is empty or invalid
+ * @throws {Error} When dataBrokerConfig is missing
+ * @throws {Error} When API authentication fails (for private datasets)
+ * @throws {Error} When dataset fetching fails
+ */
+export declare const loadDataFieldsForDatasets: (datasetIds: string[], options: LoadDataFieldsOptions) => Promise<DatasetWithDataFields[]>;