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

package/react/utils/store/types.d.ts

@@ -1,270 +0,0 @@
-/**
- * State Store Types
- *
- * Type definitions for the item and dashboard state management system
- * with real-time collaboration and undo/redo support.
- */
-/**
- * Base configuration for all stores
- */
-export interface BaseStoreConfig {
-    /** Interval in ms within which undo steps are merged. Default: 300 */
-    mergeInterval?: number;
-    /** Maximum number of undo steps to retain. Default: 100 */
-    maxUndoSteps?: number;
-    /** Optional peer ID for collaboration (as bigint or numeric string). Auto-generated if not provided */
-    peerId?: bigint | `${number}`;
-}
-/**
- * Configuration for item store
- */
-export interface ItemStoreConfig extends BaseStoreConfig {
-}
-/**
- * Configuration for dashboard store
- */
-export interface DashboardStoreConfig extends BaseStoreConfig {
-}
-/**
- * Content within a slot
- */
-export interface SlotContent {
-    column?: string;
-    set?: string;
-    columnId?: string;
-    datasetId?: string;
-    label?: Record<string, string>;
-    type?: string;
-    subtype?: string | null;
-    color?: string;
-    format?: string;
-    lowestLevel?: number;
-    level?: number | null;
-    currency?: string | null;
-    id?: string;
-    [key: string]: unknown;
-}
-/**
- * A single slot configuration
- */
-export interface Slot {
-    name: string;
-    content: SlotContent[];
-}
-/**
- * State for a standalone item (chart/visualization)
- */
-export interface ItemState {
-    type: string;
-    options: Record<string, unknown>;
-    slots: Slot[];
-    filters: unknown[];
-}
-/**
- * Screen mode for responsive dashboard views
- */
-export type ScreenMode = 'desktop' | 'tablet' | 'mobile';
-/**
- * Position of an item within a dashboard grid
- */
-export interface ItemPosition {
-    sizeX: number;
-    sizeY: number;
-    row: number;
-    col: number;
-}
-/**
- * State of a single item (chart) within a dashboard view
- */
-export interface DashboardItemState {
-    id: string;
-    type: string;
-    position: ItemPosition;
-    title?: Record<string, string>;
-    options: Record<string, unknown>;
-    content?: Record<string, unknown>;
-    slots: Slot[];
-    sort?: unknown[];
-    /** Reference to an ItemStore ID (for hybrid store architecture) */
-    storeId?: string;
-}
-/**
- * Filter configuration
- */
-export interface FilterConfig {
-    expression?: string;
-    parameters?: unknown[];
-    properties?: {
-        type?: string;
-        id?: string;
-        origin?: string;
-    };
-}
-/**
- * Options for a dashboard view
- */
-export interface ViewOptions {
-    share?: {
-        poweredBy?: boolean;
-    };
-    theme?: {
-        id?: string;
-    };
-    showTitle?: boolean;
-    showSubtitle?: boolean;
-    alertingEnabled?: boolean;
-    columns?: number;
-    rowHeight?: number;
-    maxCols?: number;
-    minCols?: number;
-    [key: string]: unknown;
-}
-/**
- * State of a single view (screen mode) within a dashboard
- */
-export interface ViewState {
-    screenModus: ScreenMode;
-    options: ViewOptions;
-    filters: FilterConfig[];
-    items: DashboardItemState[];
-}
-/**
- * Parameter configuration for dashboard
- */
-export interface DashboardParameter {
-    parameter: string;
-    type: string;
-    value: unknown;
-}
-/**
- * Timezone configuration
- */
-export interface TimezoneConfig {
-    type: string;
-    id: string;
-}
-/**
- * Complete dashboard state
- */
-export interface DashboardState {
-    version?: string;
-    syncScreenModes?: boolean;
-    parameters?: DashboardParameter[];
-    timezone?: TimezoneConfig;
-    filters?: Record<string, unknown>;
-    views: ViewState[];
-    /** ID of the currently active/selected item for editing */
-    activeItemId?: string;
-    /** Map of item IDs to their ItemStore IDs (for hybrid store architecture) */
-    itemStoreIds?: Record<string, string>;
-}
-/**
- * Callback for state changes
- */
-export type StateSubscriber<T> = (state: T) => void;
-/**
- * Callback for change events
- */
-export type ChangeSubscriber = (event: unknown) => void;
-/**
- * Callback for local updates (for sync)
- */
-export type LocalUpdatesSubscriber = (updates: Uint8Array) => void;
-/**
- * Unsubscribe function returned by subscribe methods
- */
-export type Unsubscribe = () => void;
-/**
- * Options for state subscription
- */
-export interface SubscribeOptions {
-    /**
-     * Whether to immediately call the callback with current state.
-     * The callback is deferred to the next microtask to allow setup code to complete.
-     * Set to false to only receive future state changes.
-     * @default true
-     */
-    fireImmediately?: boolean;
-}
-/**
- * Base interface for all stores
- */
-export interface BaseStore<TState> {
-    /** Unique identifier for this store instance */
-    readonly id: string;
-    undo(): boolean;
-    redo(): boolean;
-    canUndo(): boolean;
-    canRedo(): boolean;
-    clearHistory(): void;
-    subscribe(callback: StateSubscriber<TState>, options?: SubscribeOptions): Unsubscribe;
-    subscribeToChanges(callback: ChangeSubscriber): Unsubscribe;
-    exportUpdates(since?: Uint8Array): Uint8Array;
-    importUpdates(updates: Uint8Array): void;
-    subscribeLocalUpdates(callback: LocalUpdatesSubscriber): Unsubscribe;
-    exportSnapshot(): Uint8Array;
-    importSnapshot(snapshot: Uint8Array): void;
-    reset(initialState?: Partial<TState>): void;
-    destroy(): void;
-    commit(message?: string): void;
-    getState(): TState;
-    getPeerId(): string;
-}
-/**
- * Item store interface
- */
-export interface ItemStore extends BaseStore<ItemState> {
-    /**
-     * Set multiple state properties atomically in a single transaction.
-     * This prevents intermediate states from being emitted to subscribers.
-     * Use this when updating type, slots, and options together (e.g., when switching item types).
-     */
-    setState(state: Partial<ItemState>): void;
-    setType(type: string): void;
-    setOptions(options: Record<string, unknown>): void;
-    updateOption(key: string, value: unknown): void;
-    setSlots(slots: Slot[]): void;
-    updateSlot(slotName: string, content: SlotContent[]): void;
-    setFilters(filters: unknown[]): void;
-    addFilter(filter: unknown): void;
-    removeFilter(index: number): void;
-    updateFilter(index: number, filter: unknown): void;
-    getType(): string;
-    getOptions(): Record<string, unknown>;
-    getSlots(): Slot[];
-    getFilters(): unknown[];
-    toJSON(): ItemState;
-    fromJSON(json: Partial<ItemState>): void;
-}
-/**
- * Dashboard store interface
- */
-export interface DashboardStore extends BaseStore<DashboardState> {
-    setVersion(version: string): void;
-    setSyncScreenModes(sync: boolean): void;
-    setParameters(params: DashboardParameter[]): void;
-    setTimezone(timezone: TimezoneConfig): void;
-    setDashboardFilters(filters: Record<string, unknown>): void;
-    setViewOptions(screenMode: ScreenMode, options: ViewOptions): void;
-    updateViewOption(screenMode: ScreenMode, key: string, value: unknown): void;
-    setViewFilters(screenMode: ScreenMode, filters: FilterConfig[]): void;
-    addItem(screenMode: ScreenMode, item: DashboardItemState): void;
-    removeItem(screenMode: ScreenMode, itemId: string): void;
-    updateItem(screenMode: ScreenMode, itemId: string, updates: Partial<DashboardItemState>): void;
-    updateItemPosition(screenMode: ScreenMode, itemId: string, position: Partial<ItemPosition>): void;
-    updateItemOptions(screenMode: ScreenMode, itemId: string, options: Record<string, unknown>): void;
-    updateItemSlots(screenMode: ScreenMode, itemId: string, slots: Slot[]): void;
-    updateItemFilters(screenMode: ScreenMode, itemId: string, filters: unknown[]): void;
-    batchUpdate(callback: () => void): void;
-    getView(screenMode: ScreenMode): ViewState | undefined;
-    getItem(screenMode: ScreenMode, itemId: string): DashboardItemState | undefined;
-    getItems(screenMode: ScreenMode): DashboardItemState[];
-    getActiveItemId(): string | undefined;
-    setActiveItemId(itemId: string | undefined): void;
-    getActiveItemStoreId(): string | undefined;
-    getItemStoreId(itemId: string): string | undefined;
-    setItemStoreId(itemId: string, storeId: string): void;
-    getItemStoreIds(): Map<string, string>;
-    toJSON(): DashboardState;
-    fromJSON(json: Partial<DashboardState>): void;
-}

package/react/utils/switch-item/index.d.ts

@@ -1,34 +0,0 @@
-import type { SlotConfig, VizItemSlot } from '@luzmo/dashboard-contents-types';
-/**
- * Converts a dashboard item's slot contents from one item type to another by re-mapping
- * each content entry into the target type's slot structure.
- *
- * Algorithm:
- * 1. Resolve slot configs for both the source and target item types.
- * 2. Short-circuit if this is an identity switch and all slot rules are already satisfied.
- * 3. Stage all source content entries, annotating each with its inferred role and content kind.
- * 4. Place staged entries into target slots in priority phases:
- *    - Main group-by entries onto main group-by slots.
- *    - Secondary group-by entries onto secondary (or fallback main) slots.
- *    - Overflow main group-by entries onto secondary slots (if available).
- *    - Measure entries onto measure slots, with deterministic multiplicity based on source shape:
- *      if source has both primary and secondary group-by content, only the first measure is retained.
- *    - Remaining entries onto any compatible slot.
- * 5. Enforce inter-slot dependency constraints after each phase and at the end.
- *
- * Staged entries that cannot be placed into any target slot are silently dropped.
- */
-export declare function switchItem(args: {
-    oldItemType: string;
-    newItemType: string;
-    slots?: VizItemSlot[];
-    options?: Record<string, unknown>;
-    customItemSlotsConfigs?: {
-        type: string;
-        slotsConfig: SlotConfig[];
-    }[];
-}): Promise<{
-    type: string;
-    slots: VizItemSlot[];
-    options?: Record<string, unknown>;
-}>;

package/react/utils/switch-item/slot-role-classification.d.ts

@@ -1,31 +0,0 @@
-import type { GenericSlotContent, Slot } from '@luzmo/dashboard-contents-types';
-/** Semantic role of a slot, used to match source content to compatible target slots. */
-export type SlotRole = 'mainGroupBy' | 'secondaryGroupBy' | 'measure' | 'other';
-/** Whether a slot content entry represents a numeric value or a categorical/temporal dimension. */
-export type SlotContentKind = 'numeric' | 'dimension';
-export declare function inferContentKind(content: GenericSlotContent): SlotContentKind;
-export declare function inferSlotRole(args: {
-    slotName: string;
-    slotType?: string;
-    contentKind: SlotContentKind;
-}): SlotRole;
-export declare function inferTargetSlotRoles(slot: Slot): Set<SlotRole>;
-export declare function hasTargetSecondaryGroupBySlot(slots: Slot[]): boolean;
-export declare function getAliasSlotNamesForRole(role: SlotRole, sourceSlotName: string): string[];
-/**
- * Returns target slots that are role-compatible with the source item, sorted by best fit.
- * Ranking criteria (highest to lowest priority):
- * 1. Role match order from `preferredRoles`.
- * 2. Source-name/alias match order.
- * 3. Slot config `order`.
- */
-export declare function rankCompatibleTargetSlots(args: {
-    targetSlots: Slot[];
-    sourceSlotName: string;
-    sourceRole: SlotRole;
-    preferredRoles: SlotRole[];
-    isAdditionalCompatible?: (slot: Slot) => boolean;
-}): Slot[];
-export declare function getPreferredRoles(item: {
-    sourceRole: SlotRole;
-}, hasTargetSecondaryGroupBy: boolean): SlotRole[];

package/react/utils/switch-item/stories/switch-item.stories.d.ts

@@ -1,17 +0,0 @@
-import '@luzmo/lucero/select';
-import type { StoryObj } from '@storybook/web-components-vite';
-import '../../../components/item-grid';
-import '../../../components/item-slot-picker-panel';
-declare const meta: {
-    title: string;
-    tags: string[];
-    render: () => HTMLElement;
-    parameters: {
-        controls: {
-            disable: boolean;
-        };
-    };
-};
-export default meta;
-type Story = StoryObj;
-export declare const Playground: Story;

package/react/utils/switch-item/tests/slot-role-classification.test.d.ts

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

package/react/utils/switch-item/tests/switch-item.test.d.ts

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

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

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

package/react/utils/themes/classic-dark.d.ts

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

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

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

package/react/utils/themes/default-dark.d.ts

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

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

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

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

@@ -1,4 +0,0 @@
-import { ThemeConfig } from '@luzmo/dashboard-contents-types';
-export declare const systemThemeIds: string[];
-export type SystemThemeId = 'default' | 'default_dark' | 'vivid' | 'seasonal' | 'orion' | 'royale' | 'urban' | 'pinky' | 'bliss' | 'radiant' | 'classic' | 'classic_dark';
-export declare const getTheme: (themeId: SystemThemeId | string) => Promise<ThemeConfig>;

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -1,4 +0,0 @@
-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

@@ -1,8 +0,0 @@
-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

@@ -1,15 +0,0 @@
-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/timezone/datetime-timezone.d.ts

@@ -1,25 +0,0 @@
-import type { GenericSlotContent } from '@luzmo/dashboard-contents-types';
-/**
- * Luzmo datetime levels 1–5 (year, quarter, month, week, day).
- * At these levels the API already returns values in the dashboard timezone.
- * Levels 6+ (hour, minute, second, millisecond) are returned as UTC and need a client-side shift.
- *
- * @see https://developer.luzmo.com/guide/guides--querying-data--options.md
- */
-export declare const DATE_LEVEL_AND_ABOVE = 5;
-/**
- * Shifts a datetime value for display based on the column's aggregation level.
- * Date-level values are parsed as-is; sub-day values are converted from UTC to the dashboard timezone.
- */
-export declare function transformDateToTimezone(value: unknown, level: number | undefined, timezoneId: string): Date | null | undefined;
-/**
- * Prepares a raw slot value for the Luzmo formatter, applying timezone conversion for
- * datetime columns in default display mode. Non-default display modes (e.g. month_number)
- * pass through unchanged as numeric values.
- *
- * When timezoneId is omitted (older Luzmo hosts), falls back to `new Date(value)` so the
- * browser's local timezone is used — matching pre-timezone custom chart behaviour.
- *
- * Call this before `formatter()`; do not change `formatter()` itself.
- */
-export declare function getValueForFormatter(rawValue: unknown, slotContent: GenericSlotContent | undefined, timezoneId?: string): string | number | Date | null | undefined;

package/react/utils/timezone/tests/datetime-timezone.test.d.ts

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

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

@@ -1,9 +0,0 @@
-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

@@ -1,30 +0,0 @@
-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

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

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

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

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

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

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

@@ -1,28 +0,0 @@
-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[];
-};