@luzmo/analytics-components-kit 1.0.6 → 1.0.8-beta.1

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,39 @@
+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 linkedDataset: import("signal-polyfill").Signal.State<{
+        name: any;
+        id: string;
+        columns: any[];
+    }[]>;
+    private readonly _popEnabledChartTypes;
+    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/store/base-store.d.ts

@@ -0,0 +1,162 @@
+/**
+ * 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;
+    /**
+     * Set a nested value in an object using dot notation path
+     */
+    protected setNestedValue(obj: Record<string, unknown>, path: string, value: unknown): Record<string, unknown>;
+    /**
+     * 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;

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

@@ -0,0 +1,170 @@
+/**
+ * Store Registry
+ *
+ * A global registry for stores that allows components to reference stores
+ * by ID.
+ *
+ * @module store-registry
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   registerItemStore,
+ *   getStore
+ * } from '@luzmo/analytics-components-kit/utils/store';
+ *
+ * // Create and register a store (auto-registers with its ID)
+ * const store = registerItemStore({ type: 'bar-chart' });
+ * const storeId = store.id; // Use this in component props
+ *
+ * // Later, retrieve the store by ID
+ * const sameStore = getStore(storeId);
+ * ```
+ */
+import type { BaseStore, DashboardState, DashboardStore, DashboardStoreConfig, ItemState, ItemStore, ItemStoreConfig } from './types';
+/**
+ * Get a store by its ID
+ *
+ * @param storeId The unique store identifier
+ * @returns The store instance, or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const store = getStore('my-store-id');
+ * if (store) {
+ *   const state = store.getState();
+ * }
+ * ```
+ */
+export declare function getStore<T = unknown>(storeId: string): BaseStore<T> | undefined;
+/**
+ * Get an item store by its ID
+ *
+ * @param storeId The unique store identifier
+ * @returns The item store instance, or undefined if not found
+ */
+export declare function getItemStore(storeId: string): ItemStore | undefined;
+/**
+ * Get a dashboard store by its ID
+ *
+ * @param storeId The unique store identifier
+ * @returns The dashboard store instance, or undefined if not found
+ */
+export declare function getDashboardStore(storeId: string): DashboardStore | undefined;
+/**
+ * Check if a store exists in the registry
+ *
+ * @param storeId The store ID to check
+ * @returns true if the store exists
+ */
+export declare function hasStore(storeId: string): boolean;
+/**
+ * Get all registered store IDs
+ *
+ * @returns Array of all registered store IDs
+ */
+export declare function getStoreIds(): string[];
+/**
+ * Register an existing store in the registry
+ *
+ * @param store The store instance to register
+ * @returns The store instance (for chaining)
+ * @throws Error if a store with the same ID already exists
+ *
+ * @example
+ * ```typescript
+ * const store = createItemStore({ type: 'bar-chart' });
+ * registerStore(store);
+ * // Now accessible via getStore(store.id)
+ * ```
+ */
+export declare function registerStore<T extends BaseStore<unknown>>(store: T): T;
+/**
+ * Create and register a new item store
+ *
+ * @param initialState Initial item state (optional)
+ * @param config Store configuration (optional)
+ * @param storeId Optional custom store ID (auto-generated if not provided)
+ * @returns The registered ItemStore instance
+ *
+ * @example
+ * ```typescript
+ * // Create stores
+ * const store1 = registerItemStore({ type: 'bar-chart' });
+ * const store2 = registerItemStore({ type: 'line-chart' });
+ *
+ * // Use store IDs in components
+ * element.storeId = store1.id;
+ * ```
+ */
+export declare function registerItemStore(initialState?: Partial<ItemState>, config?: ItemStoreConfig, storeId?: string): ItemStore;
+/**
+ * Create and register a new dashboard store
+ *
+ * @param initialState Initial dashboard state (optional)
+ * @param config Store configuration (optional)
+ * @param storeId Optional custom store ID (auto-generated if not provided)
+ * @returns The registered DashboardStore instance
+ *
+ * @example
+ * ```typescript
+ * // Create dashboard store
+ * const dashboardStore = registerDashboardStore({
+ *   views: [{ screenModus: 'desktop', options: {}, filters: [], items: [] }]
+ * });
+ *
+ * // Use in components
+ * dashboardElement.storeId = dashboardStore.id;
+ * ```
+ */
+export declare function registerDashboardStore(initialState?: Partial<DashboardState>, config?: DashboardStoreConfig, storeId?: string): DashboardStore;
+/**
+ * Remove a store from the registry
+ *
+ * Note: This does NOT destroy the store, only removes it from the registry.
+ * Call store.destroy() separately if you want to clean up the store.
+ *
+ * @param storeId The store ID to remove
+ * @returns true if the store was removed, false if it wasn't in the registry
+ *
+ * @example
+ * ```typescript
+ * const store = getStore(storeId);
+ * if (store) {
+ *   removeStore(storeId);
+ *   store.destroy(); // Clean up the store
+ * }
+ * ```
+ */
+export declare function removeStore(storeId: string): boolean;
+/**
+ * Remove and destroy a store
+ *
+ * Removes the store from the registry and calls destroy() on it.
+ *
+ * @param storeId The store ID to remove and destroy
+ * @returns true if the store was found and destroyed
+ *
+ * @example
+ * ```typescript
+ * destroyStore('my-store-id');
+ * ```
+ */
+export declare function destroyStore(storeId: string): boolean;
+/**
+ * Clear all stores from the registry
+ *
+ * Optionally destroys all stores before clearing.
+ *
+ * @param destroy If true, calls destroy() on each store before clearing
+ *
+ * @example
+ * ```typescript
+ * // Just clear the registry
+ * clearRegistry();
+ *
+ * // Clear and destroy all stores
+ * clearRegistry(true);
+ * ```
+ */
+export declare function clearRegistry(destroy?: boolean): void;

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

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

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

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

package/angular/utils/store/tests/store-registry.test.d.ts

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