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

package/angular/utils/formula/tests/validate-expression.test.d.ts

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

package/angular/utils/get-css-variable.d.ts

@@ -0,0 +1 @@
+export declare const getCssVariableValue: (element: HTMLElement, variable: string) => string;

package/angular/utils/index.d.ts

@@ -0,0 +1,10 @@
+export { loadDataFieldsForDatasets } from './data/load-data-fields-for-datasets';
+export { decomposeNumericFormat } from './formatter/decompose-numeric-format';
+export { formatter } from './formatter/formatter';
+export { localize } from './formatter/localize';
+export { getLocale, setLocale, targetLocales } from './localize/set-locale';
+export { switchItem } from './switch-item';
+export * from './themes';
+export { convertDatasetsToDataFields } from './transformations/convert-datasets-to-data-fields';
+export { PeriodOverPeriodCondition } from './time/period-over-period-condition.const';
+export { DATE_LEVEL_AND_ABOVE, getValueForFormatter, transformDateToTimezone } from './timezone/datetime-timezone';

package/angular/utils/localize/set-locale.d.ts

@@ -0,0 +1,7 @@
+declare const getLocale: (() => string) & {
+    _LIT_LOCALIZE_GET_LOCALE_?: never;
+}, setLocale: ((newLocale: string) => Promise<void>) & {
+    _LIT_LOCALIZE_SET_LOCALE_?: never;
+};
+export { targetLocales } from './../../generated/locale-codes.js';
+export { getLocale, setLocale };

package/angular/utils/map-tile-providers/index.d.ts

@@ -0,0 +1,93 @@
+export declare const mapVectorTileProviders: {
+    'No Tiles': {
+        name: string;
+        id: string;
+        url: string;
+        attribution: string;
+        rasterName: string;
+    };
+    Basic: {
+        name: string;
+        id: string;
+        url: string;
+        attribution: string;
+        rasterName: string;
+    };
+    Bright: {
+        name: string;
+        id: string;
+        url: string;
+        attribution: string;
+        rasterName: string;
+    };
+    Dark: {
+        name: string;
+        id: string;
+        url: string;
+        attribution: string;
+        rasterName: string;
+    };
+    Fiord: {
+        name: string;
+        id: string;
+        url: string;
+        attribution: string;
+        rasterName: string;
+    };
+    Liberty: {
+        name: string;
+        id: string;
+        url: string;
+        attribution: string;
+        rasterName: string;
+    };
+    Pastel: {
+        name: string;
+        id: string;
+        url: string;
+        attribution: string;
+        rasterName: string;
+    };
+    Positron: {
+        name: string;
+        id: string;
+        url: string;
+        attribution: string;
+        rasterName: string;
+    };
+    Streets: {
+        name: string;
+        id: string;
+        url: string;
+        attribution: string;
+        rasterName: string;
+    };
+    Toner: {
+        name: string;
+        id: string;
+        url: string;
+        attribution: string;
+        rasterName: string;
+    };
+    Topographique: {
+        name: string;
+        id: string;
+        url: string;
+        attribution: string;
+        rasterName: string;
+    };
+    Voyager: {
+        name: string;
+        id: string;
+        url: string;
+        attribution: string;
+        rasterName: string;
+    };
+    '3D buildings': {
+        name: string;
+        id: string;
+        url: string;
+        attribution: string;
+        rasterName: string;
+    };
+};

package/angular/utils/set-nested-value.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Immutably set a value at a dot-delimited object path.
+ * Numeric path segments preserve or create arrays; missing, primitive, and null
+ * intermediate values are replaced with the container needed by the next segment.
+ */
+export declare const setNestedValue: (object: Record<string, unknown>, path: string, value: unknown) => Record<string, unknown>;

package/angular/utils/slot-content/ad-hoc-slot-content.d.ts

@@ -0,0 +1,7 @@
+import type { SlotConfig } from '@luzmo/dashboard-contents-types';
+import type { SlotContent } from '../../types/slot.types';
+export declare const isAdHocFormula: (content: SlotContent | undefined) => boolean;
+export declare const isAdHocExpression: (content: SlotContent | undefined) => boolean;
+export declare const getAdHocExpression: (content: SlotContent | undefined) => string | undefined;
+export declare const getSlotContentIdentityKey: (content: SlotContent | undefined) => string | undefined;
+export declare const shouldSurfaceAsFormula: (content: SlotContent | undefined, slotConfiguration: SlotConfig) => boolean;

package/angular/utils/slot-content/render-calculation-label.d.ts

@@ -0,0 +1,7 @@
+import { type TemplateResult } from 'lit';
+import type { SlotContent } from '../../types/slot.types';
+/**
+ * Renders the compact ad-hoc calculation label (icon + "Formula"/"Expression")
+ * shared by the slot picker, drop target and slot menu surfaces.
+ */
+export declare const renderAdHocCalculationLabel: (content: SlotContent | undefined) => TemplateResult;

package/angular/utils/slot-content/tests/ad-hoc-slot-content.test.d.ts

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

package/angular/utils/slot-state/slot-context.d.ts

@@ -0,0 +1,4 @@
+import type { SlotStore } from './slot-store';
+export declare const slotContext: {
+    __context__: SlotStore;
+};

package/angular/utils/slot-state/slot-store.d.ts

@@ -0,0 +1,43 @@
+import { SlotName, VizItemSlot, VizItemType } from '@luzmo/dashboard-contents-types';
+import type { SlotContent } from '../../types/slot.types';
+import { PeriodOverPeriodCondition } from '../time/period-over-period-condition.const';
+export declare class SlotStore {
+    /**
+     * Holds all contents for this item slot drop target.
+     */
+    readonly slotContents: import("signal-polyfill").Signal.State<SlotContent[]>;
+    readonly slotsContents: import("signal-polyfill").Signal.State<VizItemSlot[]>;
+    readonly periodOverPeriodUiType: import("signal-polyfill").Signal.State<PeriodOverPeriodCondition | null>;
+    readonly periodOverPeriodAllowsPeriodsWithoutDatetimeColumn: import("signal-polyfill").Signal.State<boolean>;
+    readonly periodOverPeriodHidesPastValue: import("signal-polyfill").Signal.State<boolean>;
+    readonly linkedDataset: import("signal-polyfill").Signal.State<{
+        name: any;
+        id: string;
+        columns: any[];
+    }[]>;
+    private readonly _popEnabledChartTypes;
+    private readonly _popPeriodsWithoutDatetimeColumnItemTypes;
+    private readonly _popWithoutPastValueItemTypes;
+    readonly activeSlotContents: import("signal-polyfill").Signal.Computed<SlotContent>;
+    /**
+     * Index of the content currently selected / active in a slot menu.
+     */
+    readonly activeIndex: import("signal-polyfill").Signal.State<number>;
+    private isArrayColumnType;
+    setPeriodOverPeriodCondition(itemType: VizItemType, currentSlotContents: SlotContent): void;
+    private getUiConditionToApply;
+    private oldConditionalLogic;
+    /**
+     * Detects if there's a datetime column on Category or X-axis slots
+     */
+    private hasDatetimeColumnOnCategoryOrXAxis;
+    /** Replace the full list (e.g. after dropping or re-ordering). */
+    setContents(contents: SlotContent[], slotName?: SlotName): void;
+    setFullContents(fullSlotsContents: VizItemSlot[]): void;
+    /** Change which item is considered active (e.g. user clicked in list). */
+    updateActive(index: number): void;
+    /** Update / overwrite a single content entry. */
+    updateContent(content: SlotContent, index?: number): void;
+    /** Remove one content entry by index. */
+    removeContent(index: number): void;
+}

package/angular/utils/slot-state/tests/slot-store.test.d.ts

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

package/angular/utils/store/base-store.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Base Store
+ *
+ * Abstract base class providing shared functionality for
+ * item and dashboard stores, including undo/redo, subscriptions, and sync helpers.
+ */
+import * as Y from 'yjs';
+import type { BaseStoreConfig, ChangeSubscriber, LocalUpdatesSubscriber, StateSubscriber, SubscribeOptions, Unsubscribe } from './types';
+/**
+ * Abstract base class for stores
+ *
+ * Provides shared functionality for undo/redo, subscriptions, and sync.
+ * Subclasses must implement state-specific initialization and accessors.
+ */
+export declare abstract class BaseStore<TState> {
+    /** Unique identifier for this store instance */
+    readonly id: string;
+    protected doc: Y.Doc;
+    protected undoManager: Y.UndoManager;
+    protected config: Required<Omit<BaseStoreConfig, 'peerId'>> & {
+        peerId?: bigint | `${number}`;
+    };
+    private stateSubscribers;
+    private changeSubscribers;
+    private localUpdatesSubscribers;
+    private isDestroyed;
+    /** Origin used for local changes (for undo tracking) */
+    protected static readonly LOCAL_ORIGIN = "local";
+    constructor(config?: BaseStoreConfig, storeId?: string);
+    /**
+     * Set up the undo manager with tracked types
+     * Called by subclasses after containers are initialized
+     */
+    protected setupUndoManager(trackedTypes: Array<Y.Map<unknown> | Y.Array<unknown> | Y.Text>): void;
+    /**
+     * Set up internal change subscription to relay to external subscribers
+     */
+    private setupChangeSubscription;
+    /**
+     * Notify all state subscribers with current state
+     */
+    protected notifyStateSubscribers(): void;
+    /**
+     * Initialize the document containers with initial state
+     */
+    protected abstract initializeContainers(initialState?: Partial<TState>): void;
+    /**
+     * Get the current state from containers
+     */
+    abstract getState(): TState;
+    /**
+     * Undo the last operation
+     * @returns true if undo was performed
+     */
+    undo(): boolean;
+    /**
+     * Redo the last undone operation
+     * @returns true if redo was performed
+     */
+    redo(): boolean;
+    /**
+     * Check if undo is available
+     */
+    canUndo(): boolean;
+    /**
+     * Check if redo is available
+     */
+    canRedo(): boolean;
+    /**
+     * Clear the undo/redo history
+     */
+    clearHistory(): void;
+    /**
+     * Subscribe to state changes
+     * @param callback Function called with new state on changes
+     * @param options Subscription options
+     * @returns Unsubscribe function
+     *
+     * @example
+     * ```typescript
+     * // Default: fires with current state (deferred to next microtask)
+     * store.subscribe((state) => updateUI(state));
+     *
+     * // Skip initial callback, only receive future changes
+     * store.subscribe(handleChanges, { fireImmediately: false });
+     * ```
+     */
+    subscribe(callback: StateSubscriber<TState>, options?: SubscribeOptions): Unsubscribe;
+    /**
+     * Subscribe to raw change events
+     * @param callback Function called with change event
+     * @returns Unsubscribe function
+     */
+    subscribeToChanges(callback: ChangeSubscriber): Unsubscribe;
+    /**
+     * Export updates since a given version
+     * @param since State vector (encoded as Uint8Array) to export from. If not provided, exports all updates.
+     * @returns Encoded updates as Uint8Array
+     */
+    exportUpdates(since?: Uint8Array): Uint8Array;
+    /**
+     * Import updates from another peer
+     * @param updates Encoded updates from exportUpdates
+     */
+    importUpdates(updates: Uint8Array): void;
+    /**
+     * Subscribe to local updates for broadcasting to other peers
+     * @param callback Function called with encoded updates
+     * @returns Unsubscribe function
+     */
+    subscribeLocalUpdates(callback: LocalUpdatesSubscriber): Unsubscribe;
+    /**
+     * Export the full document as a snapshot
+     * @returns Encoded snapshot as Uint8Array
+     */
+    exportSnapshot(): Uint8Array;
+    /**
+     * Import a snapshot, replacing current state
+     * @param snapshot Encoded snapshot from exportSnapshot
+     */
+    importSnapshot(snapshot: Uint8Array): void;
+    /**
+     * Get the current version vector (for sync)
+     */
+    getVersion(): Uint8Array;
+    /**
+     * Commit pending changes
+     * @param _message Optional commit message (not used in yjs, kept for API compatibility)
+     */
+    commit(_message?: string): void;
+    /**
+     * Reset the store with optional new initial state
+     * @param initialState New initial state (optional)
+     */
+    reset(initialState?: Partial<TState>): void;
+    /**
+     * Destroy the store and clean up resources
+     */
+    destroy(): void;
+    /**
+     * Get the underlying document (for advanced use cases)
+     * @internal
+     */
+    getDoc(): Y.Doc;
+    /**
+     * Get the peer ID of this store
+     */
+    getPeerId(): string;
+    /**
+     * Deep clone a value using structuredClone
+     */
+    protected clone<T>(value: T): T;
+    /**
+     * Execute a function within a transaction with local origin
+     * This ensures changes are tracked by the undo manager
+     */
+    protected transact<T>(fn: () => T): T;
+}

package/angular/utils/store/dashboard-store.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Dashboard Store
+ *
+ * State store for dashboard with multiple items (charts/visualizations).
+ * Supports undo/redo at the dashboard level (affecting all items),
+ * multiple screen modes (desktop, tablet, mobile), and real-time collaboration.
+ */
+import type { DashboardState, DashboardStore as IDashboardStore, DashboardStoreConfig } from './types';
+/**
+ * Create a new dashboard store
+ *
+ * @param initialState Initial dashboard state (optional)
+ * @param config Store configuration (optional)
+ * @param storeId Optional store ID (auto-generated UUID if not provided)
+ * @returns DashboardStore instance
+ *
+ * @example
+ * ```typescript
+ * const store = createDashboardStore({
+ *   version: '1.0.0',
+ *   views: [{
+ *     screenModus: 'desktop',
+ *     options: { theme: { id: 'default' } },
+ *     filters: [],
+ *     items: [{
+ *       id: 'item-1',
+ *       type: 'bar-chart',
+ *       position: { sizeX: 24, sizeY: 16, row: 0, col: 0 },
+ *       options: {},
+ *       slots: []
+ *     }]
+ *   }]
+ * });
+ *
+ * // Subscribe to changes
+ * store.subscribe((state) => {
+ *   console.log('Dashboard changed:', state);
+ * });
+ *
+ * // Batch multiple changes into single undo step
+ * store.batchUpdate(() => {
+ *   store.updateItemPosition('desktop', 'item-1', { row: 10 });
+ *   store.updateItemOptions('desktop', 'item-1', { title: 'New Title' });
+ * });
+ *
+ * store.undo(); // Undoes both changes
+ * ```
+ */
+export declare function createDashboardStore(initialState?: Partial<DashboardState>, config?: DashboardStoreConfig, storeId?: string): IDashboardStore;

package/angular/utils/store/index.d.ts

@@ -0,0 +1,135 @@
+/**
+ * State Store
+ *
+ * State management utilities for item and dashboard state
+ * with undo/redo support and real-time collaboration capabilities.
+ *
+ * @module store
+ *
+ * @example
+ * ```typescript
+ * // Standalone item with undo/redo
+ * import { createItemStore } from '@luzmo/analytics-components-kit/utils/store';
+ *
+ * const itemStore = createItemStore({
+ *   type: 'bar-chart',
+ *   slots: [{ name: 'measure', content: [...] }],
+ *   options: { display: { title: true } }
+ * });
+ *
+ * itemStore.subscribe((state) => {
+ *   // Update UI with new state
+ * });
+ *
+ * itemStore.updateOption('display.title', false);
+ * itemStore.undo(); // Restores title to true
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using the store registry
+ * import {
+ *   registerItemStore,
+ *   getStore
+ * } from '@luzmo/analytics-components-kit/utils/store';
+ *
+ * // Create and register stores
+ * const store = registerItemStore({ type: 'bar-chart' });
+ *
+ * // Use store ID in components
+ * element.storeId = store.id;
+ *
+ * // Retrieve store by ID anywhere in the app
+ * const sameStore = getStore(store.id);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Dashboard with real-time collaboration
+ * import { createDashboardStore } from '@luzmo/analytics-components-kit/utils/store';
+ *
+ * const dashboardStore = createDashboardStore(dashboardConfig);
+ *
+ * // Sync with other peers
+ * dashboardStore.subscribeLocalUpdates((updates) => {
+ *   websocket.send(updates);
+ * });
+ *
+ * websocket.onmessage = (msg) => {
+ *   dashboardStore.importUpdates(msg.data);
+ * };
+ * ```
+ */
+import type { ItemState, ItemStoreConfig, ItemStore, DashboardState, DashboardStoreConfig, DashboardStore } from './types';
+/**
+ * Promise that resolves immediately.
+ * Kept for API compatibility - yjs is pure JavaScript and doesn't require WASM initialization.
+ *
+ * @example
+ * ```typescript
+ * import { ready, createItemStore } from '@luzmo/analytics-components-kit/utils/store';
+ *
+ * await ready;
+ * const store = createItemStore({ type: 'bar-chart' });
+ * ```
+ */
+export declare const ready: Promise<void>;
+/**
+ * Execute a callback when the DOM is ready.
+ * Handles the ES module timing issue where DOMContentLoaded may have already fired.
+ *
+ * @param callback Function to execute when DOM is ready
+ *
+ * @example
+ * ```typescript
+ * import { onReady, createItemStore } from '@luzmo/analytics-components-kit/utils/store';
+ *
+ * onReady(() => {
+ *   const store = createItemStore({ type: 'bar-chart' });
+ *   initializeApp(store);
+ * });
+ * ```
+ */
+export declare function onReady(callback: () => void): void;
+export { createItemStore } from './item-store';
+export { createDashboardStore } from './dashboard-store';
+/**
+ * Create an item store.
+ * This async version is kept for API compatibility.
+ * Since yjs is pure JavaScript, no async initialization is needed.
+ *
+ * @param initialState Initial item state (optional)
+ * @param config Store configuration (optional)
+ * @param storeId Optional store ID (auto-generated UUID if not provided)
+ * @returns Promise resolving to ItemStore instance
+ *
+ * @example
+ * ```typescript
+ * const store = await createItemStoreAsync({
+ *   type: 'bar-chart',
+ *   options: { display: { title: true } }
+ * });
+ * ```
+ */
+export declare function createItemStoreAsync(initialState?: Partial<ItemState>, config?: ItemStoreConfig, storeId?: string): Promise<ItemStore>;
+/**
+ * Create a dashboard store.
+ * This async version is kept for API compatibility.
+ * Since yjs is pure JavaScript, no async initialization is needed.
+ *
+ * @param initialState Initial dashboard state (optional)
+ * @param config Store configuration (optional)
+ * @param storeId Optional store ID (auto-generated UUID if not provided)
+ * @returns Promise resolving to DashboardStore instance
+ *
+ * @example
+ * ```typescript
+ * const store = await createDashboardStoreAsync({
+ *   version: '1.0.0',
+ *   views: [{ screenModus: 'desktop', options: {}, filters: [], items: [] }]
+ * });
+ * ```
+ */
+export declare function createDashboardStoreAsync(initialState?: Partial<DashboardState>, config?: DashboardStoreConfig, storeId?: string): Promise<DashboardStore>;
+export { getStore, getItemStore, getDashboardStore, hasStore, getStoreIds, registerStore, registerItemStore, registerDashboardStore, removeStore, destroyStore, clearRegistry } from './store-registry';
+export type { BaseStoreConfig, DashboardStoreConfig, ItemStoreConfig, ItemState, Slot, SlotContent, DashboardItemState, DashboardParameter, DashboardState, FilterConfig, ItemPosition, ScreenMode, TimezoneConfig, ViewOptions, ViewState, BaseStore, DashboardStore, ItemStore, ChangeSubscriber, LocalUpdatesSubscriber, StateSubscriber, SubscribeOptions, Unsubscribe } from './types';

package/angular/utils/store/item-store.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Item Store
+ *
+ * State store for standalone item (chart/visualization) with undo/redo support
+ * and real-time collaboration capabilities.
+ */
+import type { ItemState, ItemStore as IItemStore, ItemStoreConfig } from './types';
+/**
+ * Create a new item store
+ *
+ * @param initialState Initial item state (optional)
+ * @param config Store configuration (optional)
+ * @param storeId Optional store ID (auto-generated UUID if not provided)
+ * @returns ItemStore instance
+ *
+ * @example
+ * ```typescript
+ * const store = createItemStore({
+ *   type: 'bar-chart',
+ *   slots: [{ name: 'measure', content: [...] }],
+ *   options: { display: { title: true } },
+ *   filters: []
+ * });
+ *
+ * store.subscribe((state) => {
+ *   console.log('State changed:', state);
+ * });
+ *
+ * store.updateOption('display.title', false);
+ * store.undo(); // Restores display.title to true
+ * ```
+ */
+export declare function createItemStore(initialState?: Partial<ItemState>, config?: ItemStoreConfig, storeId?: string): IItemStore;