@luzmo/analytics-components-kit 1.0.9-beta.1 → 1.0.9-beta.10

package/LICENSE

@@ -1,18 +1,18 @@
-A kit of modern Luzmo Web Components for analytics in your web application.
-
-Copyright © 2026 Luzmo
-All rights reserved.
-Luzmo web components (“Luzmo Web Components”)
-must be used according to the Luzmo Terms of Service.
-This license allows users with a current active Luzmo account
-to use the Luzmo Web Components. This license terminates
-automatically if a user no longer has an active Luzmo account.
-Please view the Luzmo Terms of Service at: https://www.luzmo.com/information-pages/terms-of-use.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+A kit of modern Luzmo Web Components for analytics in your web application.
+
+Copyright © 2026 Luzmo
+All rights reserved.
+Luzmo web components (“Luzmo Web Components”)
+must be used according to the Luzmo Terms of Service.
+This license allows users with a current active Luzmo account
+to use the Luzmo Web Components. This license terminates
+automatically if a user no longer has an active Luzmo account.
+Please view the Luzmo Terms of Service at: https://www.luzmo.com/information-pages/terms-of-use.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -15,7 +15,7 @@ ACK produces and edits chart configuration (type, slots, options, filters). It d
 ## Installation
 
 ```bash
-npm install @luzmo/analytics-components-kit lit@^3.3.2 @luzmo/lucero@^2.2.1 @luzmo/icons@^1.0.1-alpha.46
+npm install @luzmo/analytics-components-kit lit@^3.3.2 @luzmo/lucero@^2.4.2 @luzmo/icons@^1.0.1-alpha.47
 ```
 
 ACK uses Lucero 2 for its design-system primitives. Package managers that do not install peer dependencies automatically must install the compatible peer versions explicitly.
@@ -267,6 +267,8 @@ grid.addEventListener('luzmo-item-grid-layout-changed', (e) => {
 
 Key events: `luzmo-item-grid-ready`, `luzmo-item-grid-layout-changed`, `luzmo-item-grid-item-action` (cancelable), and `luzmo-item-grid-item-states-changed`. Imperative helpers (`addGridItem`, `removeGridItem`, `cloneGridItem`, `updateGridItem*`) return the updated `GridItemData[]`.
 
+The `grid` object on `luzmo-item-grid-ready` (and the `grid` property) is a GridStack 14 instance. Use `mode()` and `getMode()` (`'top'`, `'float'`, `'list'`, or `'compact'`). `float()` and `getFloat()` are not available.
+
 See the [Item Grid reference](https://developer.luzmo.com/guide/ack--components--chart-rendering--luzmo-item-grid) for controlled vs uncontrolled details, all properties, events, methods, and examples.
 
 ## Utilities

package/angular/README.md

@@ -0,0 +1,40 @@
+# Luzmo Analytics Components Kit - Angular Wrappers
+
+> Standalone Angular wrapper components for the Luzmo Analytics Components Kit web components
+
+This package provides Angular wrappers for the Luzmo Analytics Components Kit web components.
+
+## Installation
+
+```bash
+npm install @luzmo/ngx-analytics-components-kit @luzmo/analytics-components-kit @angular/core @angular/forms
+```
+
+## Requirements
+
+- Angular `>= 17.3` (the wrappers use the functional `output()` API).
+- The peer package `@luzmo/analytics-components-kit` provides the underlying
+  custom-element classes that the wrappers register at import time.
+
+## Usage
+
+```ts
+import { Component } from '@angular/core';
+import { LuzmoDataField } from '@luzmo/ngx-analytics-components-kit';
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  imports: [LuzmoDataField],
+  template: `<luzmo-data-field></luzmo-data-field>`
+})
+export class AppComponent {}
+```
+
+The wrapper class name mirrors the host element (`LuzmoDataField`); the
+underlying `HTMLElement` subclass type is re-exported as
+`LuzmoDataFieldElement` for `@ViewChild` / `ElementRef<T>` use cases.
+
+## Notes
+
+- This package depends on `@luzmo/analytics-components-kit` for the underlying custom elements.

package/angular/components/add-to-dashboard.ts

@@ -0,0 +1,130 @@
+import { booleanAttribute, ChangeDetectionStrategy, Component, DestroyRef, ElementRef, inject, Input, OnChanges, output, Renderer2, SimpleChanges } from '@angular/core';
+import '@luzmo/analytics-components-kit/add-to-dashboard';
+import type { LuzmoAddToDashboard as LuzmoAddToDashboardHostElement, AddToDashboardChartAddFailedEventDetail, AddToDashboardChartAddedEventDetail } from '@luzmo/analytics-components-kit/add-to-dashboard';
+export type { AddToDashboardChartAddFailedEventDetail, AddToDashboardChartAddedEventDetail, AddToDashboardSettings, BuiltInDashboardActionsConfig, DashboardActionCallOptions, DashboardActions, DashboardListPage, DashboardListRequest, DashboardOption, FlexChartConfig } from '@luzmo/analytics-components-kit/add-to-dashboard';
+import type { Placement } from '@luzmo/lucero';
+
+@Component({
+  selector: 'luzmo-add-to-dashboard',
+  exportAs: 'luzmoAddToDashboard',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  template: '<ng-content />'
+})
+/**
+ * Angular wrapper component for <luzmo-add-to-dashboard>
+ */
+export class LuzmoAddToDashboard implements OnChanges {
+  private readonly elementRef = inject<ElementRef<LuzmoAddToDashboardHostElement>>(ElementRef);
+  private readonly renderer = inject<Renderer2>(Renderer2);
+  private readonly destroyRef = inject<DestroyRef>(DestroyRef);
+  private readonly host = this.elementRef.nativeElement;
+  private readonly listenerCleanup: Array<() => void> = [];
+
+  /** The underlying custom element instance. Use to call imperative methods. */
+  get nativeElement(): LuzmoAddToDashboardHostElement {
+    return this.host;
+  }
+
+  /** The language for UI labels. Supported values: 'en', 'nl', 'fr', 'de', 'es' */
+  @Input({ alias: 'language' })
+  language?: string;
+
+  /** Auth key for the built-in adapter. */
+  @Input({ alias: 'authKey' })
+  authKey?: string;
+
+  /** Auth token for the built-in adapter. */
+  @Input({ alias: 'authToken' })
+  authToken?: string;
+
+  /** API URL for the built-in adapter. */
+  @Input({ alias: 'apiUrl' })
+  apiUrl?: string;
+
+  /** Placement of the picker relative to the button. */
+  @Input({ alias: 'placement' })
+  placement?: Placement;
+
+  /** When present, the button is disabled. */
+  @Input({ alias: 'disabled', transform: booleanAttribute })
+  disabled?: boolean;
+
+  /** The size of the element */
+  @Input({ alias: 'size' })
+  size?: 's' | 'm' | 'l' | 'xl';
+
+  /** Fired after the chart was saved to a dashboard, a new dashboard or a variant. */
+  readonly luzmoChartAdded = output<CustomEvent<AddToDashboardChartAddedEventDetail>>({ alias: 'luzmoChartAdded' });
+
+  /** Fired when saving the chart failed. */
+  readonly luzmoChartAddFailed = output<CustomEvent<AddToDashboardChartAddFailedEventDetail>>({ alias: 'luzmoChartAddFailed' });
+
+  constructor() {
+    this.bindEvents();
+    this.destroyRef.onDestroy(() => {
+      for (const cleanup of this.listenerCleanup) {
+        cleanup();
+      }
+    });
+  }
+
+  ngOnChanges(changes: SimpleChanges): void {
+    for (const key of Object.keys(changes)) {
+      switch (key) {
+        case 'language':
+          this.setHostProperty('language', changes['language'].currentValue);
+          break;
+        case 'authKey':
+          this.setHostProperty('authKey', changes['authKey'].currentValue);
+          break;
+        case 'authToken':
+          this.setHostProperty('authToken', changes['authToken'].currentValue);
+          break;
+        case 'apiUrl':
+          this.setHostProperty('apiUrl', changes['apiUrl'].currentValue);
+          break;
+        case 'placement':
+          this.setHostProperty('placement', changes['placement'].currentValue);
+          break;
+        case 'disabled':
+          this.setHostProperty('disabled', changes['disabled'].currentValue);
+          break;
+        case 'size':
+          this.setHostProperty('size', changes['size'].currentValue);
+          break;
+        default:
+          break;
+      }
+    }
+  }
+
+  /**
+   * Forward a wrapper @Input to the underlying host element via Renderer2 so
+   * the wrapper stays compatible with non-DOM Angular platforms (SSR, tests).
+   * Unlike a "skip undefined" guard, this lets consumers reset values back to
+   * undefined / null by clearing their bindings.
+   */
+  private setHostProperty(key: string, value: unknown): void {
+    this.renderer.setProperty(this.host, key, value);
+  }
+
+  private bindEvents(): void {
+    this.listenerCleanup.push(
+      this.renderer.listen(this.host, 'luzmo-chart-added', (event: Event) => {
+        const typed = event as CustomEvent<AddToDashboardChartAddedEventDetail>;
+        this.luzmoChartAdded.emit(typed);
+      })
+    );
+
+    this.listenerCleanup.push(
+      this.renderer.listen(this.host, 'luzmo-chart-add-failed', (event: Event) => {
+        const typed = event as CustomEvent<AddToDashboardChartAddFailedEventDetail>;
+        this.luzmoChartAddFailed.emit(typed);
+      })
+    );
+  }
+}
+
+/** The underlying custom element type for LuzmoAddToDashboard */
+export type LuzmoAddToDashboardElement = LuzmoAddToDashboardHostElement;

package/angular/components/ai-chat-empty-state.ts

@@ -0,0 +1,105 @@
+import { booleanAttribute, ChangeDetectionStrategy, Component, DestroyRef, ElementRef, inject, Input, OnChanges, output, Renderer2, SimpleChanges } from '@angular/core';
+import '@luzmo/analytics-components-kit/ai-chat';
+import type { LuzmoAiChatEmptyState as LuzmoAiChatEmptyStateHostElement, AiChatEmptyStateSuggestion, AiChatEmptyStateSuggestionSelectedDetail } from '@luzmo/analytics-components-kit/ai-chat';
+export type { AgentStreamDefinition, AiChatAgentConfig, AiChatCompleteEvent, AiChatConversationIdChangedEventDetail, AiChatDatasetsChangedEventDetail, AiChatEmptyStateSuggestion, AiChatEmptyStateSuggestionSelectedDetail, AiChatMessageSentEventDetail, AiChatRecognizedStepType, AiChatSessionBuildContext, AiChatSessionCallbacks, AiChatSessionConfig, AiChatSessionControllerOptions, AiChatSessionRestoreParams, AiChatSessionRestoreResult, AiChatSessionSeed, AiChatSessionState, AiChatSessionSubmitParams, AiChatStepBase, AiChatStepEvent, AiDictationCreateBody, AiDictationProperties, AiPromptCreateBody, AiPromptDeleteBody, AssistantMessageAction, AssistantMessageActionConfirmVariant, AssistantMessageActionEventDetail, BuildAiDictationRequestOptions, ChatMessageElicitation, LuzmoPromptSubmittedEventDetail, LuzmoRestoreRequestedEventDetail, ProgressTreeNode, PromptBoxAttachment, PromptBoxFileIcons, RecognizedStepEvent, StreamAiDictationOptions, StreamHandlerCallbacks, StreamHandlerContext, StreamHandlerState, StreamingRequestOptions, StreamingResponse, UnknownStepEvent, UploadAiPromptImagesOptions } from '@luzmo/analytics-components-kit/ai-chat';
+
+@Component({
+  selector: 'luzmo-ai-chat-empty-state',
+  exportAs: 'luzmoAiChatEmptyState',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  template: '<ng-content />'
+})
+/**
+ * Angular wrapper component for <luzmo-ai-chat-empty-state>
+ */
+export class LuzmoAiChatEmptyState implements OnChanges {
+  private readonly elementRef = inject<ElementRef<LuzmoAiChatEmptyStateHostElement>>(ElementRef);
+  private readonly renderer = inject<Renderer2>(Renderer2);
+  private readonly destroyRef = inject<DestroyRef>(DestroyRef);
+  private readonly host = this.elementRef.nativeElement;
+  private readonly listenerCleanup: Array<() => void> = [];
+
+  /** The underlying custom element instance. Use to call imperative methods. */
+  get nativeElement(): LuzmoAiChatEmptyStateHostElement {
+    return this.host;
+  }
+
+  /** Heading shown above the suggestions. */
+  @Input({ alias: 'title' })
+  title?: string;
+
+  /** Supporting text shown above suggestion chips when `suggestions` is non-empty. */
+  @Input({ alias: 'subtitle' })
+  subtitle?: string;
+
+  /** Suggestion chips rendered with https://lucero.luzmo.com/ | Lucero `luzmo-action-button` (`variant="accent"`). */
+  @Input({ alias: 'suggestions' })
+  suggestions?: AiChatEmptyStateSuggestion[];
+
+  /** When true, suggestion chips cannot be activated. */
+  @Input({ alias: 'disabled', transform: booleanAttribute })
+  disabled?: boolean;
+
+  /** Size of the title, subtitle and suggestion chips: `s`, `m` (default), `l` or `xl` */
+  @Input({ alias: 'size' })
+  size?: unknown;
+
+  /** Fired when the user selects a suggestion chip */
+  readonly luzmoSuggestionSelected = output<CustomEvent<AiChatEmptyStateSuggestionSelectedDetail>>({ alias: 'luzmoSuggestionSelected' });
+
+  constructor() {
+    this.bindEvents();
+    this.destroyRef.onDestroy(() => {
+      for (const cleanup of this.listenerCleanup) {
+        cleanup();
+      }
+    });
+  }
+
+  ngOnChanges(changes: SimpleChanges): void {
+    for (const key of Object.keys(changes)) {
+      switch (key) {
+        case 'title':
+          this.setHostProperty('title', changes['title'].currentValue);
+          break;
+        case 'subtitle':
+          this.setHostProperty('subtitle', changes['subtitle'].currentValue);
+          break;
+        case 'suggestions':
+          this.setHostProperty('suggestions', changes['suggestions'].currentValue);
+          break;
+        case 'disabled':
+          this.setHostProperty('disabled', changes['disabled'].currentValue);
+          break;
+        case 'size':
+          this.setHostProperty('size', changes['size'].currentValue);
+          break;
+        default:
+          break;
+      }
+    }
+  }
+
+  /**
+   * Forward a wrapper @Input to the underlying host element via Renderer2 so
+   * the wrapper stays compatible with non-DOM Angular platforms (SSR, tests).
+   * Unlike a "skip undefined" guard, this lets consumers reset values back to
+   * undefined / null by clearing their bindings.
+   */
+  private setHostProperty(key: string, value: unknown): void {
+    this.renderer.setProperty(this.host, key, value);
+  }
+
+  private bindEvents(): void {
+    this.listenerCleanup.push(
+      this.renderer.listen(this.host, 'luzmo-suggestion-selected', (event: Event) => {
+        const typed = event as CustomEvent<AiChatEmptyStateSuggestionSelectedDetail>;
+        this.luzmoSuggestionSelected.emit(typed);
+      })
+    );
+  }
+}
+
+/** The underlying custom element type for LuzmoAiChatEmptyState */
+export type LuzmoAiChatEmptyStateElement = LuzmoAiChatEmptyStateHostElement;