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

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

@@ -0,0 +1,270 @@
+/**
+ * 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/angular/utils/switch-item/index.d.ts

@@ -0,0 +1,34 @@
+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/angular/utils/switch-item/slot-role-classification.d.ts

@@ -0,0 +1,31 @@
+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/angular/utils/switch-item/stories/switch-item.stories.d.ts

@@ -0,0 +1,17 @@
+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/angular/utils/switch-item/tests/slot-role-classification.test.d.ts

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,4 @@
+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/angular/utils/themes/orion.d.ts

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

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

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

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

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

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

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

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

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

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

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

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

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

package/angular/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/angular/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/angular/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/angular/utils/timezone/datetime-timezone.d.ts

@@ -0,0 +1,25 @@
+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/angular/utils/timezone/tests/datetime-timezone.test.d.ts

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

package/angular/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/angular/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/angular/utils/transformations/tests/convert-data-field-to-slot-content.test.d.ts

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

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

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

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

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

package/angular/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/components/ai-chat/ai-chat-request.d.ts

@@ -1,12 +1,20 @@
 import type { LuzmoChart } from '../../types';
-import type { AiPromptAgent, AiPromptCreateBody, AiPromptDeleteBody, AiPromptProperties, BuildAiPromptRequestContext } from './ai-prompt-types';
-export type { AiPromptAgent, AiPromptImageInput, AiPromptCreateBody, AiPromptDeleteBody, AiPromptInput, AiPromptItemTask, AiPromptProperties, AiPromptScreenMode, BuildAiPromptRequestContext, DashboardStatePayload, LuzmoDashboardGeneratedEventDetail, LuzmoPromptSubmittedEventDetail, LuzmoRestoreRequestedEventDetail } from './ai-prompt-types';
+import type { AiPromptAgent, AiPromptCreateBody, AiPromptDeleteBody, AiPromptProperties, AiPromptSavedAgentProperties, BuildAiPromptRequestContext } from './ai-prompt-types';
+export type { AiPromptAgent, AiPromptBuiltInAgentProperties, AiPromptImageInput, AiPromptCreateBody, AiPromptDeleteBody, AiPromptInput, AiPromptItemTask, AiPromptProperties, AiPromptPropertiesBase, AiPromptSavedAgentProperties, AiPromptScreenMode, BuildAiPromptRequestContext, DashboardStatePayload, LuzmoDashboardGeneratedEventDetail, LuzmoPromptSubmittedEventDetail, LuzmoRestoreRequestedEventDetail } from './ai-prompt-types';
 export { AI_PROMPT_ACCEPTED_IMAGE_MIME_TYPES, AI_PROMPT_MAX_ATTACHMENTS, assertValidAiPromptAttachmentFiles, assertValidAiPromptAttachmentUrls, isAiPromptAcceptedImageFile, isAiPromptAcceptedImageMimeType, isAiPromptAcceptedImageUrl } from '../../utils/ai-prompt';
 export declare function getAiPromptUrl(apiUrl: string, apiVersion: string): string;
 export declare function chartToItemAsset(chart: LuzmoChart): Record<string, unknown> | null;
 export declare function buildItemAiPromptProperties(ctx: BuildAiPromptRequestContext): AiPromptProperties;
 export declare function buildDashboardAiPromptProperties(ctx: BuildAiPromptRequestContext): AiPromptProperties;
 export declare function buildAnalystAiPromptProperties(ctx: BuildAiPromptRequestContext): AiPromptProperties;
+/**
+ * Properties for a saved Agent run. The agent id resolves datasets, capabilities and theme
+ * server-side, so `agent` and `task` are deliberately absent: sending either alongside
+ * `agent_id` is a 400. Chart and dashboard context still travel: a saved Agent runs as the
+ * universal agent, whose planner reads `item` and `dashboard` entries out of the current
+ * input, so dropping them would blind it to what the host is showing.
+ */
+export declare function buildSavedAgentAiPromptProperties(agentId: string, ctx: BuildAiPromptRequestContext): AiPromptSavedAgentProperties;
 export declare function buildAiPromptProperties(agent: AiPromptAgent, ctx: BuildAiPromptRequestContext): AiPromptProperties;
 export declare function buildAiPromptRequest(agent: AiPromptAgent, ctx: BuildAiPromptRequestContext): AiPromptCreateBody;
 export declare function buildAiPromptDeleteRequest(restoreToMessageId: string, authKey: string, authToken: string, apiVersion?: string, conversationId?: string | null): AiPromptDeleteBody;

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

@@ -161,11 +161,16 @@ export declare class LuzmoAiChat extends LuzmoElement {
     }) => Promise<string[]>;
     /**
      * Which aiprompt agent to use. Determines request payload and stream handling.
+     * With `agent-id` set it no longer shapes the request payload, only stream handling.
      * @default 'item'
      */
     agent: AiPromptAgent;
     /**
-     * Task for the item agent (`generate`, `suggest`, `describe`).
+     * Saved Agent id (UUID) to run the prompt as.
+     */
+    agentId?: string;
+    /**
+     * Task for the item agent (`generate`, `suggest`, `describe`). Ignored when `agent-id` is set.
      * @default 'generate'
      */
     task: AiPromptItemTask;

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

@@ -32,9 +32,8 @@ export interface AiPromptImageInput {
     url: string;
 }
 export type AiPromptInput = AiPromptTextInput | AiPromptDatasetInput | AiPromptItemInput | AiPromptDashboardInput | AiPromptImageInput;
-export interface AiPromptProperties {
-    agent: AiPromptAgent;
-    task: AiPromptItemTask | 'generate';
+/** Fields both aiprompt create shapes share, whichever agent selector is used. */
+export interface AiPromptPropertiesBase {
     conversation_id?: string;
     locale_id?: string;
     timezone_id?: string;
@@ -42,6 +41,22 @@ export interface AiPromptProperties {
     response_mode: 'mixed';
     input: AiPromptInput[];
 }
+/** Built-in agent request: `agent` (plus `task`) selects the server-side behaviour. */
+export interface AiPromptBuiltInAgentProperties extends AiPromptPropertiesBase {
+    agent: AiPromptAgent;
+    task: AiPromptItemTask | 'generate';
+    agent_id?: never;
+}
+/**
+ * Saved Agent request: the agent id resolves datasets, capabilities and theme server-side.
+ * `agent_id` combined with `agent`, `task` or `capabilities` is a 400 — it is strictly one or the other.
+ */
+export interface AiPromptSavedAgentProperties extends AiPromptPropertiesBase {
+    agent_id: string;
+    agent?: never;
+    task?: never;
+}
+export type AiPromptProperties = AiPromptBuiltInAgentProperties | AiPromptSavedAgentProperties;
 export interface AiPromptCreateBody {
     key: string;
     token: string;
@@ -66,6 +81,7 @@ export interface BuildAiPromptRequestContext {
     authKey: string;
     authToken: string;
     conversationId: string | null;
+    agentId?: string;
     apiVersion?: string;
     stream?: boolean;
     localeId?: string;