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

package/components/item-grid/helpers/grid-item-management.d.ts

@@ -0,0 +1,30 @@
+import type { LuzmoEmbedVizItem } from '@luzmo/embed';
+import type { GridStackEngine } from 'gridstack';
+import type { AddGridItemInput, GridItemData } from '../types';
+export interface GridItemLookup {
+    item: GridItemData;
+    element: HTMLElement;
+    luzmoElement?: LuzmoEmbedVizItem;
+}
+interface SimulateItemPlacementArgs {
+    item: GridItemData;
+    engine: GridStackEngine;
+    existingItems: GridItemData[];
+    autoPosition: boolean;
+    excludeNodeId?: string;
+}
+export interface SimulateItemPlacementResult {
+    resolvedItem: GridItemData;
+    updatedItems: GridItemData[];
+}
+export declare const mapGridItems: (items: GridItemData[], gridElement: HTMLElement) => GridItemLookup[];
+export declare const simulateItemPlacement: ({ item, engine, existingItems, autoPosition, excludeNodeId }: SimulateItemPlacementArgs) => SimulateItemPlacementResult;
+interface SimulateItemMoveArgs {
+    itemId: string;
+    patch: Partial<NonNullable<GridItemData['position']>>;
+    engine: GridStackEngine;
+    existingItems: GridItemData[];
+}
+export declare const simulateItemMove: ({ itemId, patch, engine, existingItems }: SimulateItemMoveArgs) => GridItemData[];
+export declare const resolveNewGridItem: (newItem: AddGridItemInput) => GridItemData;
+export {};

package/components/item-grid/helpers/grid-item-popover.d.ts

@@ -0,0 +1,21 @@
+import type { Placement } from '@luzmo/lucero';
+import { type TemplateResult } from 'lit';
+import type { GridItemData } from '../types';
+import type { GridItemLookup } from './grid-item-management';
+interface CreateItemActionsMenuPopoverArgs {
+    element: HTMLElement;
+    activeActions?: string[];
+    getGridItemById: (id: string) => GridItemLookup | undefined;
+    placementItemActionsMenu: Placement;
+    renderOverlayContent: (item?: GridItemData, activeActions?: string[]) => TemplateResult;
+    removeItemActionsMenuPopover: (gridItem: HTMLElement) => void;
+    /**
+     * When false, skip `showPopover()` and use `position: fixed` + Floating UI so the menu does not
+     * enter the document popover top layer (avoids stacking above other `popover="manual"` UIs).
+     * @default true
+     */
+    itemActionsDocumentPopover?: boolean;
+}
+export declare const createItemActionsMenuPopover: ({ element, activeActions, getGridItemById, placementItemActionsMenu, renderOverlayContent, removeItemActionsMenuPopover, itemActionsDocumentPopover }: CreateItemActionsMenuPopoverArgs) => void;
+export declare const removeItemActionsMenuPopover: (gridItem: HTMLElement) => void;
+export {};

package/components/item-grid/helpers/grid-items.d.ts

@@ -0,0 +1,9 @@
+import type { GridStackWidget } from 'gridstack';
+import type { AddGridItemInput, GridItemData } from '../types';
+export declare const normalizeGridItems: (items: GridItemData[]) => void;
+export declare const ensureGridItemId: (item: GridItemData) => string;
+export declare const buildGridWidgetOptions: (item: GridItemData | undefined, id?: string) => GridStackWidget;
+export declare const createGridItemFromInput: (newItem: AddGridItemInput, id: string) => GridItemData;
+export declare const createOrphanGridItemElement: (itemId: string) => HTMLDivElement;
+export declare const readGridItemPosition: (gridItemElement: HTMLElement) => GridItemData["position"];
+export declare const findGridItemElementById: (elements: Iterable<HTMLElement>, id: string | undefined) => HTMLElement | undefined;

package/components/item-grid/helpers/grid-keyboard-updates.d.ts

@@ -0,0 +1,18 @@
+export type GridArrowKey = 'ArrowLeft' | 'ArrowRight' | 'ArrowUp' | 'ArrowDown';
+export interface GridKeyboardNode {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export type GridKeyboardUpdate = Partial<Pick<GridKeyboardNode, 'x' | 'y' | 'w' | 'h'>>;
+export interface GridKeyboardUpdateArgs {
+    key: GridArrowKey;
+    node: GridKeyboardNode;
+    maxColumns: number;
+    shiftKey: boolean;
+    ctrlKey: boolean;
+    metaKey: boolean;
+}
+export declare const isGridArrowKey: (key: string) => key is GridArrowKey;
+export declare const getGridKeyboardUpdate: ({ key, node, maxColumns, shiftKey, ctrlKey, metaKey }: GridKeyboardUpdateArgs) => GridKeyboardUpdate | undefined;

package/components/item-grid/helpers/grid-keydown-event.d.ts

@@ -0,0 +1,18 @@
+import type { GridStack } from 'gridstack';
+export interface HandleGridKeyDownArgs {
+    event: KeyboardEvent;
+    viewMode: boolean;
+    focusedItemElement?: HTMLElement;
+    activeItemElement?: HTMLElement;
+    gridElement: HTMLElement;
+    grid?: GridStack;
+    columns: number;
+    onDeleteRequest: (gridItemElement: HTMLElement) => void;
+    removeItemActionsMenuPopover: (gridItem: HTMLElement) => void;
+    createItemActionsMenuPopover: (element: HTMLElement, activeActions?: string[]) => void;
+}
+export interface HandleGridKeyDownResult {
+    focusedItemElement?: HTMLElement;
+    activeItemElement?: HTMLElement;
+}
+export declare const handleGridKeyDown: ({ event, viewMode, focusedItemElement, activeItemElement, gridElement, grid, columns, onDeleteRequest, removeItemActionsMenuPopover, createItemActionsMenuPopover }: HandleGridKeyDownArgs) => HandleGridKeyDownResult;

package/components/item-grid/helpers/grid-popover-cleanup.d.ts

@@ -0,0 +1,4 @@
+type CleanupCallback = () => void;
+export declare const setPopoverCleanup: (element: HTMLElement, cleanup: CleanupCallback) => void;
+export declare const clearPopoverCleanup: (element: HTMLElement) => void;
+export {};

package/components/item-grid/helpers/grid-rendering.d.ts

@@ -0,0 +1,69 @@
+import { ThemeConfig } from '@luzmo/dashboard-contents-types';
+import type { Placement } from '@luzmo/lucero';
+import { type TemplateResult } from 'lit';
+import { repeat } from 'lit/directives/repeat.js';
+import type { GridItemData, InputActionGroup } from '../types';
+interface RenderOverlayContentArgs {
+    item?: GridItemData;
+    activeActions?: string[];
+    defaultItemActionsMenu?: InputActionGroup[];
+    placementItemActionsMenu: Placement;
+    language: string;
+    handleAction: (event: CustomEvent) => void;
+    /**
+     * When false, the actions menu omits `popover` so it stays in normal stacking (e.g. alongside
+     * another document popover such as an embedded analyst pane that must paint above the grid).
+     * @default true
+     */
+    itemActionsDocumentPopover?: boolean;
+}
+interface RenderGridItemArgs {
+    item: GridItemData;
+    index: number;
+    initialized: boolean;
+    viewMode: boolean;
+    contentLanguage: string;
+    fullTheme?: ThemeConfig;
+    appServer?: string;
+    apiHost?: string;
+    authKey?: string;
+    authToken?: string;
+    handleMouseover: (event: Event) => void;
+    handleMouseout: (event: Event) => void;
+    handleFocus: (event: FocusEvent) => void;
+    handleBlur: (event: FocusEvent) => void;
+}
+interface RenderGridItemsArgs {
+    items: GridItemData[];
+    initialized: boolean;
+    viewMode: boolean;
+    contentLanguage: string;
+    fullTheme?: ThemeConfig;
+    appServer?: string;
+    apiHost?: string;
+    authKey?: string;
+    authToken?: string;
+    renderItem: (item: GridItemData, index: number) => TemplateResult;
+}
+interface RenderGridArgs {
+    items: GridItemData[];
+    initialized: boolean;
+    viewMode: boolean;
+    contentLanguage: string;
+    fullTheme?: ThemeConfig;
+    appServer?: string;
+    apiHost?: string;
+    authKey?: string;
+    authToken?: string;
+    columns: number;
+    ensureGridItemId: (item: GridItemData) => void;
+    handleMouseover: (event: Event) => void;
+    handleMouseout: (event: Event) => void;
+    handleFocus: (event: FocusEvent) => void;
+    handleBlur: (event: FocusEvent) => void;
+}
+export declare const renderOverlayContent: ({ item, activeActions, defaultItemActionsMenu, placementItemActionsMenu, language, handleAction, itemActionsDocumentPopover }: RenderOverlayContentArgs) => TemplateResult;
+export declare const renderGridItem: ({ item, index, initialized, viewMode, contentLanguage, fullTheme, appServer, apiHost, authKey, authToken, handleMouseover, handleMouseout, handleFocus, handleBlur }: RenderGridItemArgs) => TemplateResult;
+export declare const renderGridItems: ({ items, initialized, viewMode, contentLanguage, fullTheme, appServer, apiHost, authKey, authToken, renderItem }: RenderGridItemsArgs) => ReturnType<typeof repeat>;
+export declare const renderGrid: ({ items, initialized, viewMode, contentLanguage, fullTheme, appServer, apiHost, authKey, authToken, columns, ensureGridItemId, handleMouseover, handleMouseout, handleFocus, handleBlur }: RenderGridArgs) => TemplateResult;
+export {};

package/components/item-grid/helpers/grid-stack-lifecycle.d.ts

@@ -0,0 +1,26 @@
+import { ThemeConfig } from '@luzmo/dashboard-contents-types';
+import { GridStack, type GridStackNode } from 'gridstack';
+import type { GridItemData } from '../types';
+interface InitializeGridStackArgs {
+    gridElement: HTMLElement;
+    gridItemElements: NodeListOf<HTMLElement>;
+    items: GridItemData[];
+    columns: number;
+    rowHeight: number;
+    viewMode: boolean;
+    fullTheme?: ThemeConfig;
+    onCreateOrUpdateDimensionsHint: (element: HTMLElement, numberOfColumns: string, numberOfRows: string) => void;
+    onRemoveDimensionsHint: (element: HTMLElement) => void;
+    onChange: (changedItems: GridStackNode[]) => void;
+}
+interface CreateOrUpdateDimensionsHintArgs {
+    element: HTMLElement;
+    numberOfColumns: string;
+    numberOfRows: string;
+    offsetHint: number;
+}
+export declare const initializeGridStack: ({ gridElement, gridItemElements, items, columns, rowHeight, viewMode, fullTheme, onCreateOrUpdateDimensionsHint, onRemoveDimensionsHint, onChange }: InitializeGridStackArgs) => GridStack;
+export declare const buildUpdatedItemPositions: (items: GridItemData[], changedItems: GridStackNode[]) => GridItemData[];
+export declare const createOrUpdateDimensionsHint: ({ element, numberOfColumns, numberOfRows, offsetHint }: CreateOrUpdateDimensionsHintArgs) => void;
+export declare const removeDimensionsHint: (element: HTMLElement) => void;
+export {};

package/components/item-grid/helpers/grid-theme.d.ts

@@ -0,0 +1,16 @@
+import type { ThemeConfig } from '@luzmo/dashboard-contents-types';
+export interface GridThemeResolutionArgs {
+    theme?: ThemeConfig;
+    currentTheme?: ThemeConfig;
+}
+export declare const resolveGridTheme: ({ theme, currentTheme }: GridThemeResolutionArgs) => Promise<ThemeConfig | undefined>;
+export declare const getGridHalfMargins: (theme?: {
+    margins?: number[];
+}) => [number, number];
+export declare const getDimensionsHintOffset: (theme?: {
+    margins?: number[];
+}) => number;
+export declare const getGridBoxShadow: (theme?: ThemeConfig) => string;
+export declare const getGridCssVariables: (theme?: ThemeConfig) => ReadonlyMap<string, string | undefined>;
+export declare const isGridDarkBackground: (theme?: ThemeConfig) => boolean;
+export declare const applyThemeProperties: (style: CSSStyleDeclaration, fullTheme?: ThemeConfig) => void;

package/components/item-grid/helpers/grid-update-cycle.d.ts

@@ -0,0 +1,22 @@
+import type { GridStack } from 'gridstack';
+import type { GridItemData } from '../types';
+interface SyncGridItemsArgs {
+    initialized: boolean;
+    grid?: GridStack;
+    hasItemsChanged: boolean;
+    gridItemElements: NodeListOf<HTMLElement>;
+    items: GridItemData[];
+}
+interface ApplyViewModeChangeArgs {
+    initialized: boolean;
+    grid?: GridStack;
+    hasViewModeChanged: boolean;
+    viewMode: boolean;
+    previousViewMode: unknown;
+    activeItemElement?: HTMLElement;
+    gridElement: HTMLElement;
+    cleanupActiveItem: (item: HTMLElement) => void;
+}
+export declare const syncGridItems: ({ initialized, grid, hasItemsChanged, gridItemElements, items }: SyncGridItemsArgs) => void;
+export declare const applyViewModeChange: ({ initialized, grid, hasViewModeChanged, viewMode, previousViewMode, activeItemElement, gridElement, cleanupActiveItem }: ApplyViewModeChangeArgs) => HTMLElement | undefined;
+export {};

package/components/item-grid/index.d.ts

@@ -0,0 +1,12 @@
+import { LuzmoItemGrid } from './item-grid';
+import { LuzmoItemGridItemActionsMenu } from './item-grid-item-actions-menu';
+declare global {
+    interface HTMLElementTagNameMap {
+        'luzmo-item-grid': LuzmoItemGrid;
+        'luzmo-item-grid-item-actions-menu': LuzmoItemGridItemActionsMenu;
+    }
+}
+export { LuzmoItemGrid } from './item-grid';
+export { LuzmoItemGridItemActionsMenu } from './item-grid-item-actions-menu';
+export type { Action, ActionGroup, AddGridItemInput, ClonedItemPositioning, DefaultActionType, GridItemData, GridItemPatch, GridItemPosition, GridItemPositionPatch, GridItemRenderer, GridItemSizePatch, GridItemStatesChangedEventDetail, InputActionGroup, ItemStates } from './types';
+export type { GridItemActionEventDetail, GridLifecycleEventDetail } from './helpers/grid-events';

package/components/item-grid/item-grid-item-actions-menu.d.ts

@@ -0,0 +1,35 @@
+import { Placement } from '@luzmo/lucero';
+import '@luzmo/lucero/action-button';
+import '@luzmo/lucero/action-group';
+import '@luzmo/lucero/icon';
+import '@luzmo/lucero/tooltip';
+import { LuzmoElement } from '@luzmo/lucero/utils';
+import { CSSResultArray, TemplateResult } from 'lit';
+import type { ActionGroup } from './types';
+declare const LuzmoItemGridItemActionsMenu_base: (new (...args: any[]) => {
+    language: string;
+}) & typeof LuzmoElement;
+/**
+ * @customElement luzmo-item-grid-item-actions-menu
+ * @fires {CustomEvent} luzmo-item-grid-item-action - Fired when the user clicks an action in the menu; `detail` holds the action key, type, and active state.
+ */
+export declare class LuzmoItemGridItemActionsMenu extends LuzmoItemGridItemActionsMenu_base {
+    static get styles(): CSSResultArray;
+    /**
+     * The preferred placement of the menu
+     */
+    placement: Placement;
+    /**
+     * The Actions to display in the menu
+     */
+    actions: ActionGroup[];
+    private get isVertical();
+    private _dispatchAction;
+    private _handleActionClick;
+    clearActiveToggles(): void;
+    focus(): void;
+    private _generateActionButton;
+    private _generateActionGroup;
+    protected render(): TemplateResult;
+}
+export {};

package/components/item-grid/item-grid.d.ts

@@ -0,0 +1,251 @@
+import '@luzmo/embed';
+import type { ThemeConfig } from '@luzmo/dashboard-contents-types';
+import type { LuzmoEmbedVizItem } from '@luzmo/embed';
+import { Placement } from '@luzmo/lucero';
+import '@luzmo/lucero/action-button';
+import '@luzmo/lucero/action-group';
+import '@luzmo/lucero/icon';
+import { LuzmoElement } from '@luzmo/lucero/utils';
+import { GridStack } from 'gridstack';
+import { CSSResultArray, PropertyValues, TemplateResult } from 'lit';
+import { type GridItemLookup } from './helpers/grid-item-management';
+import './item-grid-item-actions-menu';
+import type { AddGridItemInput, ClonedItemPositioning, GridItemData, GridItemPatch, GridItemPositionPatch, GridItemRenderer, GridItemSizePatch, InputActionGroup, ItemStates } from './types';
+/**
+ * @customElement luzmo-item-grid
+ *
+ * A grid component that allows you to create a grid of items.
+ *
+ * @fires {CustomEvent<GridItemActionEventDetail>} luzmo-item-grid-item-action - Fired when an item action is performed
+ * @fires {CustomEvent<GridLifecycleEventDetail>} luzmo-item-grid-layout-changed - Fired when the grid layout is changed
+ * @fires {CustomEvent<GridLifecycleEventDetail>} luzmo-item-grid-ready - Fired when the grid is ready
+ * @fires {CustomEvent<GridItemStatesChangedEventDetail>} luzmo-item-grid-item-states-changed - Fired when item states change (controlled and uncontrolled mode)
+ */
+export declare class LuzmoItemGrid extends LuzmoElement {
+    static get styles(): CSSResultArray;
+    /**
+     * The URL of the app server
+     * @default https://app.luzmo.com
+     * @description The URL of the app server
+     */
+    appServer?: string;
+    /**
+     * The API Host of the databroker
+     * @default https://api.luzmo.com
+     * @description The host of the databroker API
+     */
+    apiHost?: string;
+    /**
+     * The auth key of the databroker
+     */
+    authKey?: string;
+    /**
+     * The auth token of the databroker
+     */
+    authToken?: string;
+    /**
+     * The cache time of the databroker
+     * @default 30000
+     * @description The time to cache the data in milliseconds
+     */
+    cacheTime?: number;
+    /**
+     * The language of the settings interface
+     */
+    language: string;
+    /**
+     * The language to use for locale-aware formatting and labels
+     */
+    contentLanguage: string;
+    /**
+     * The number of columns in the grid.
+     */
+    columns: number;
+    /**
+     * The height of each row in pixels in the grid.
+     */
+    rowHeight: number;
+    /**
+     * Whether the grid is in view mode. When true, dragging, resizing and action buttons are disabled.
+     * @default false
+     */
+    viewMode: boolean;
+    /**
+     * When true (default), the item actions menu uses the Document Popover API (`popover="manual"`),
+     * which paints in the top layer. Set to false when embedding the grid next to another UI that
+     * also uses a document popover (e.g. an analyst side pane) so the actions menu stays in normal
+     * stacking with `position: fixed` + Floating UI instead.
+     * @default true
+     */
+    itemActionsDocumentPopover: boolean;
+    /**
+     * The placement of the item actions menu.
+     * @default 'right-start'
+     */
+    placementItemActionsMenu: Placement;
+    /**
+     * The default item actions menu.
+     * @default [{ type: 'group', actions: ['edit-data', 'item-options', 'clone'] }, { type: 'group', actions: ['delete'] }]
+     */
+    defaultItemActionsMenu?: InputActionGroup[];
+    /**
+     * Where to position a cloned item in the grid.
+     * - `'below-item'` (default): places the clone directly below the original item, shifting other items down.
+     * - `'auto-position'`: lets the grid engine find the first available space (row-major scan, then compact upward).
+     * @default 'below-item'
+     */
+    clonedItemPositioning: ClonedItemPositioning;
+    /**
+     * Grid options configuration
+     */
+    theme?: ThemeConfig;
+    /**
+     * Items to add to the grid.
+     * The array is cloned on set so the component never mutates the caller's data.
+     */
+    set items(value: GridItemData[] | undefined);
+    get items(): GridItemData[];
+    private _items;
+    private _hasControlledItems;
+    /**
+     * Seed value for uncontrolled items mode. The component manages item changes internally from this starting point.
+     * Ignored when `items` is set.
+     */
+    set initialItems(value: GridItemData[] | undefined);
+    get initialItems(): GridItemData[] | undefined;
+    private _initialItems;
+    /**
+     * Custom renderers for different item types
+     */
+    renderers: Record<string, GridItemRenderer>;
+    /**
+     * Controlled item states. When set, the component becomes controlled:
+     * it only reflects what the parent provides and does not update internal state on user interaction.
+     */
+    set itemStates(value: ItemStates | undefined);
+    get itemStates(): ItemStates | undefined;
+    private _itemStates?;
+    /**
+     * Seed value for uncontrolled mode. The component manages state internally from this starting point.
+     * Ignored if `itemStates` is set.
+     *
+     * Only one item with one active action is supported. If multiple items or actions are provided,
+     * a warning is emitted and only the first item with its first action is applied.
+     * Use controlled mode (`itemStates`) for multiple simultaneous active items.
+     */
+    initialItemStates?: ItemStates;
+    private _initialized;
+    private _gridElement;
+    private _gridItemElements;
+    private _grid?;
+    defaultRenderer: GridItemRenderer;
+    private _activeItemElement?;
+    private _activeItemActionToggle?;
+    private _focusedItemElement?;
+    private _fullTheme?;
+    private _internalItemStates;
+    private _initialItemStatesApplied;
+    private _internalItems;
+    private _initialItemsApplied;
+    private _hasWarnedControlledAndInitialItems;
+    private _hasWarnedIgnoredInitialItems;
+    private _suppressItemStatesEvent;
+    private _suppressNextLayoutChangedEvent;
+    private _hasWarnedControlledAndInitialStates;
+    private _internalItemsVersion;
+    private get _isControlled();
+    private get _isItemsControlled();
+    private get _effectiveItems();
+    private get _effectiveItemStates();
+    private _validateItemsHaveIds;
+    private _loadTheme;
+    firstUpdated(): void;
+    disconnectedCallback(): void;
+    protected willUpdate(changedProperties: PropertyValues): void;
+    protected updated(changedProperties: PropertyValues): void;
+    private _setInternalItems;
+    private _handleMouseover;
+    private _handleMouseout;
+    private _handleKeyDown;
+    private _handleFocus;
+    private _handleBlur;
+    private _handleGridClick;
+    private _emitControlledClickAwayDeactivation;
+    private _cleanupActiveItem;
+    private _clearGridItemUiStateForDelete;
+    private _dispatchItemActionEvent;
+    private _sanitizeInitialItemStates;
+    private _diffItemStates;
+    private _computeNextItemStates;
+    private _filterItemStatesToExistingItems;
+    private _reconcileStaleItemStates;
+    private _simulateCloneLayout;
+    private _cleanup;
+    private _restoreItemsLayout;
+    private _initializeGrid;
+    private _applyItemStates;
+    private _createOrUpdateDimensionsHint;
+    private _removeDimensionsHint;
+    private _handleAction;
+    /**
+     * Get the GridStack instance
+     */
+    get grid(): GridStack | undefined;
+    get gridItems(): {
+        item: GridItemData;
+        element: HTMLElement;
+        luzmoElement?: LuzmoEmbedVizItem;
+    }[];
+    /**
+     * Register a custom renderer for a specific type
+     */
+    registerRenderer(type: string, renderer: GridItemRenderer): void;
+    private _renderOverlayContent;
+    private _createItemActionsMenuPopover;
+    private _removeItemActionsMenuPopover;
+    getGridItemById(id: string): GridItemLookup | undefined;
+    scrollToItem(id: string): void;
+    private _createMissingItemError;
+    private _requireGridItem;
+    private _resolvePositionFromEngine;
+    private _requireGridItemWithPosition;
+    private _assertAddItemHasId;
+    addGridItem(newItem: AddGridItemInput): GridItemData[];
+    private _enrichItemsWithEnginePositions;
+    private _updateGridItemPosition;
+    private _dispatchLayoutChangedEvent;
+    private _updateItemField;
+    removeGridItem(itemId: string): GridItemData[];
+    cloneGridItem(itemId: string): GridItemData[];
+    updateGridItemPosition(itemId: string, position: GridItemPositionPatch): GridItemData[];
+    updateGridItemSize(itemId: string, size: GridItemSizePatch): GridItemData[];
+    updateGridItemSlots(itemId: string, slots: NonNullable<GridItemData['slots']>): GridItemData[];
+    updateGridItemOptions(itemId: string, options: NonNullable<GridItemData['options']>): GridItemData[];
+    updateGridItemFilters(itemId: string, filters: NonNullable<GridItemData['filters']>): GridItemData[];
+    updateGridItemType(itemId: string, type: GridItemData['type']): GridItemData[];
+    updateGridItem(itemId: string, patch: GridItemPatch): GridItemData[];
+    /**
+     * Programmatically trigger a toggle action on a grid item.
+     * Toggles the state (active→inactive, inactive→active) unless `active` is explicitly set.
+     * Waits for any pending render to complete before checking for the element.
+     * @param itemId - The ID of the grid item
+     * @param action - The action name to trigger
+     * @param options - Optional configuration
+     * @param options.active - Force active state (true/false). If omitted, toggles the current state.
+     * @returns The new active state (true if activated, false if deactivated), or undefined if item not found
+     */
+    triggerItemAction(itemId: string, action: string, options?: {
+        active?: boolean;
+    }): Promise<boolean | undefined>;
+    activateItemAction(itemId: string, action: string, options?: {
+        active?: boolean;
+    }): Promise<boolean | undefined>;
+    private _triggerControlledItemAction;
+    /**
+     * Deactivate all active items and dispatch deactivation events.
+     * @returns The number of items that were deactivated
+     */
+    deactivateItems(): number;
+    private _renderGrid;
+    protected render(): TemplateResult;
+}

package/components/item-grid/types.d.ts

@@ -0,0 +1,57 @@
+import type { ItemFilterGroup, VizItemOptions, VizItemSlot, VizItemType } from '@luzmo/dashboard-contents-types';
+import type { IconDefinition } from '@luzmo/icons';
+import type { Placement } from '@luzmo/lucero';
+import type { TemplateResult } from 'lit';
+export type DefaultActionType = 'lock' | 'filters' | 'edit' | 'edit-data' | 'item-options' | 'delete' | 'clone';
+export interface Action {
+    icon?: IconDefinition;
+    label?: string;
+    action?: string | DefaultActionType;
+    type?: 'toggle' | 'button';
+    active?: boolean;
+    tooltip?: string;
+}
+export interface InputActionGroup {
+    type: 'group';
+    actions: (string | Action)[];
+}
+export interface ActionGroup {
+    type: 'group';
+    actions?: Action[];
+}
+export interface GridItemData {
+    id: string;
+    type: VizItemType;
+    placementActionsMenu?: Placement;
+    actionsMenu?: InputActionGroup[];
+    position?: {
+        sizeX: number;
+        sizeY: number;
+        row: number;
+        col: number;
+    };
+    options?: VizItemOptions;
+    slots?: VizItemSlot[];
+    filters?: ItemFilterGroup[];
+    contextId?: string;
+    canFilter?: string | string[];
+    renderer?: string;
+}
+export type ClonedItemPositioning = 'auto-position' | 'below-item';
+export type GridItemPosition = NonNullable<GridItemData['position']>;
+export type GridItemPositionPatch = Partial<Pick<GridItemPosition, 'col' | 'row'>>;
+export type GridItemSizePatch = Partial<Pick<GridItemPosition, 'sizeX' | 'sizeY'>>;
+export type GridItemPositionInput = Partial<GridItemPosition>;
+export type AddGridItemInput = Omit<GridItemData, 'position'> & {
+    position?: GridItemPositionInput;
+};
+export type GridItemPatch = Partial<Omit<GridItemData, 'id' | 'position'>> & {
+    position?: Partial<GridItemPosition>;
+};
+export type GridItemRenderer = (item: GridItemData, index: number) => TemplateResult;
+export type ItemStates = Record<string, string[]>;
+export interface GridItemStatesChangedEventDetail {
+    itemStates: ItemStates;
+    updatedItemStates: ItemStates;
+    changedItemStates: ItemStates;
+}

package/components/item-menu/item-list/item-list.d.ts

@@ -0,0 +1,37 @@
+export declare const itemGroups: {
+    key: string;
+    label: string;
+}[];
+export declare const itemTypes: {
+    type: string;
+    label: string;
+    receivesFiltersByDefault: boolean;
+    containsData: boolean;
+}[];
+export declare const itemList: ({
+    item: string;
+    type: string;
+    label: string;
+    group: string;
+    options?: undefined;
+} | {
+    item: string;
+    type: string;
+    label: string;
+    group: string;
+    options: {
+        layout: {
+            alignment: string;
+        };
+        mode?: undefined;
+    };
+} | {
+    item: string;
+    type: string;
+    label: string;
+    group: string;
+    options: {
+        mode: string;
+        layout?: undefined;
+    };
+})[];

package/components/item-option/helpers/control-markup.d.ts

@@ -0,0 +1,14 @@
+import { ElementSize } from '../../../utils/base';
+export interface ControlMarkupArgs {
+    controlType: string;
+    optionKey: string;
+    controlInfo: any;
+    options: any;
+    slots: any;
+    theme: any;
+    language: string;
+    translations: any;
+    size: ElementSize;
+    changeCallback: any;
+}
+export declare const controlMarkup: (args: ControlMarkupArgs) => import("lit-html").TemplateResult<1> | undefined;

package/components/item-option/helpers/control-templates/action-button-group-template.d.ts

@@ -0,0 +1,2 @@
+import { ControlMarkupArgs } from '../control-markup';
+export declare const actionButtonGroupMarkup: (args: ControlMarkupArgs) => import("lit-html").TemplateResult<1>;

package/components/item-option/helpers/control-templates/color-palette-picker-template.d.ts

@@ -0,0 +1,2 @@
+import { ControlMarkupArgs } from '../control-markup';
+export declare const colorPalettePickerMarkup: (args: ControlMarkupArgs) => import("lit-html").TemplateResult<1>;

package/components/item-option/helpers/control-templates/color-picker-template.d.ts

@@ -0,0 +1,2 @@
+import { ControlMarkupArgs } from '../control-markup';
+export declare const colorPickerMarkup: (args: ControlMarkupArgs) => import("lit-html").TemplateResult<1>;