@luzmo/analytics-components-kit 1.0.1-alpha.13 → 1.0.1-alpha.130

package/LICENSE

@@ -1,6 +1,6 @@
 A kit of modern Luzmo Web Components for analytics in your web application.
 
-Copyright © 2024 Luzmo
+Copyright © 2026 Luzmo
 All rights reserved.
 Luzmo web components (“Luzmo Web Components”)
 must be used according to the Luzmo Terms of Service.

package/README.md

@@ -0,0 +1,586 @@
+# Luzmo Analytics Components Kit
+
+A collection of web components for building analytics interfaces with Luzmo. Built with [Lit](https://lit.dev/) and designed to work seamlessly with Luzmo's visualization platform.
+
+## Alpha
+
+> ⚠️ This package is in alpha state. Do not use in production. Expect breaking changes.
+
+## Dashboard Contents Compatibility
+
+> **Important**: This package is linked to `@luzmo/dashboard-contents-types@0.1.89`. Ensure you are using this version when working with `slotsContents`, `slotConfiguration`, `options`, and grid configurations.
+
+## Installation
+
+```bash
+npm install @luzmo/analytics-components-kit
+```
+
+## Table of contents
+
+- [Available Components](#available-components)
+  - [Panel Components (Recommended)](#panel-components-recommended)
+  - [Data Components (Individual)](#data-components-individual)
+  - [Filter Components](#filter-components)
+  - [Display Settings](#display-settings)
+  - [Layout Components](#layout-components)
+  - [Edit Components](#edit-components)
+- [Utilities](#utilities)
+- [Types](#types)
+- [Usage: Drag & Drop Data Flow](#usage-drag-drop-data-flow)
+  - [Concept](#concept)
+  - [Example Implementation](#example-implementation)
+    - [TypeScript](#typescript)
+    - [HTML](#html)
+  - [Key Points](#key-points)
+- [Item Definitions](#item-definitions)
+- [Theming](#theming)
+  - [Global Variables Reference](#global-variables-reference)
+    - [Animation](#animation)
+    - [Border Colors](#border-colors)
+    - [Border Radius](#border-radius)
+    - [Border Width](#border-width)
+    - [Background Colors](#background-colors)
+    - [Typography](#typography)
+    - [Font Colors](#font-colors)
+    - [Primary Color](#primary-color)
+    - [Secondary Color](#secondary-color)
+    - [Semantic Colors](#semantic-colors)
+    - [Selected State Colors](#selected-state-colors)
+    - [Spacing](#spacing)
+    - [Focus Indicator](#focus-indicator)
+    - [Component Heights](#component-heights)
+    - [Icon Sizes](#icon-sizes)
+  - [Overriding Variables](#overriding-variables)
+  - [Dark Theme](#dark-theme)
+  - [Component CSS Variable Overrides](#component-css-variable-overrides)
+- [Browser Support](#browser-support)
+- [License](#license)
+
+## Available Components
+
+### Panel Components (Recommended)
+
+| Component                   | Import                                                        | Description                                                         |
+| --------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------- |
+| Draggable Data Fields Panel | `@luzmo/analytics-components-kit/draggable-data-fields-panel` | Panel displaying draggable data fields from datasets                |
+| Item Data Drop Panel        | `@luzmo/analytics-components-kit/item-data-drop-panel`        | Drop panel for chart slot configuration                             |
+| Item Data Picker Panel      | `@luzmo/analytics-components-kit/item-data-picker-panel`      | Dropdown-based panel for chart slot configuration (mobile-friendly) |
+
+> **Note**: Use `Draggable Data Fields Panel` together with `Item Data Drop Panel` for a complete drag & drop experience. Use `Item Data Picker Panel` as a mobile-friendly alternative; swap between them with media queries.
+>
+> Prefer panel components over individual data components. Panels automatically handle slot constraints (e.g., "no multiple measures if legend is filled"). If using individual components directly, you must implement these constraints yourself.
+
+### Data Components (Individual)
+
+| Component            | Import                                                 | Description                                             |
+| -------------------- | ------------------------------------------------------ | ------------------------------------------------------- |
+| Draggable Data Field | `@luzmo/analytics-components-kit/draggable-data-field` | Draggable representation of a dataset column or formula |
+| Droppable Slot       | `@luzmo/analytics-components-kit/droppable-slot`       | Drop target for data items in chart configuration       |
+| Slot Contents Picker | `@luzmo/analytics-components-kit/slot-contents-picker` | Picker-based slot content selection                     |
+
+### Filter Components
+
+| Component    | Import                                         | Description                    |
+| ------------ | ---------------------------------------------- | ------------------------------ |
+| Filter Item  | `@luzmo/analytics-components-kit/filter-item`  | Filter configuration component |
+| Edit Filters | `@luzmo/analytics-components-kit/edit-filters` | Filter editing panel           |
+
+### Display Settings
+
+| Component        | Import                                             | Description             |
+| ---------------- | -------------------------------------------------- | ----------------------- |
+| Display Settings | `@luzmo/analytics-components-kit/display-settings` | Column display settings |
+
+### Layout Components
+
+| Component | Import                                 | Description                                |
+| --------- | -------------------------------------- | ------------------------------------------ |
+| Grid      | `@luzmo/analytics-components-kit/grid` | Responsive grid layout for dashboard items |
+
+### Edit Components
+
+| Component   | Import                                        | Description                         |
+| ----------- | --------------------------------------------- | ----------------------------------- |
+| Edit Item   | `@luzmo/analytics-components-kit/edit-item`   | Container for editing chart options |
+| Edit Option | `@luzmo/analytics-components-kit/edit-option` | Individual option editor            |
+
+## Utilities
+
+```typescript
+import { loadDraggableFieldsForDatasets, switchItem, transformFilters } from '@luzmo/analytics-components-kit/utils';
+import { itemTypes } from '@luzmo/analytics-components-kit/item-list';
+
+// Load datasets with draggable data fields (for manual rendering)
+const datasets = await loadDraggableFieldsForDatasets(['dataset-id-1'], {
+  dataBrokerConfig: {
+    apiUrl: 'https://api.luzmo.com',
+    authKey: 'your-auth-key',
+    authToken: 'your-auth-token'
+  }
+});
+
+// Switch chart type while preserving compatible slot data
+const newItem = switchItem({
+  oldItemType: 'bar-chart',
+  newItemType: 'line-chart',
+  slots: currentSlots,
+  options: currentOptions
+});
+
+// Transform filter groups for use with Luzmo charts
+const chartFilters = transformFilters(filterGroup);
+
+// Get list of available chart types (for building a chart picker)
+const chartOptions = itemTypes.map((item) => ({ label: item.label, value: item.type }));
+```
+
+## Types
+
+Import TypeScript types from the dedicated entrypoint:
+
+```typescript
+import type { DatasetDataField, SlotConfiguration, SlotContentsChangedEventDetail } from '@luzmo/analytics-components-kit/types';
+```
+
+Runtime values are exported from the main package (or via `@luzmo/analytics-components-kit/utils`):
+
+```typescript
+import { PeriodOverPeriodCondition } from '@luzmo/analytics-components-kit';
+```
+
+## Usage: Drag & Drop Data Flow
+
+This library provides a complete drag-and-drop system for building Luzmo chart configurations. The flow consists of loading dataset columns/formulas as draggable items and dropping them into chart slots.
+
+### Concept
+
+1. **Add panel components**: Use `<luzmo-draggable-data-fields-panel>` for data fields and `<luzmo-item-data-drop-panel>` for slots (or `<luzmo-item-data-picker-panel>` for mobile)
+2. **Configure panels**: Set `item-type` (e.g., 'bar-chart') and `datasetIds` - panels auto-load slot configurations and fetch data
+3. **Handle slot changes**: Listen to `luzmo-slots-contents-changed` event to capture the complete slots state
+4. **Use slot contents**: Pass `slotsContents` directly to Luzmo Flex SDK visualization components
+
+### Example Implementation (Panel Components)
+
+#### TypeScript
+
+```typescript
+import '@luzmo/analytics-components-kit/draggable-data-fields-panel';
+import '@luzmo/analytics-components-kit/item-data-drop-panel';
+import '@luzmo/analytics-components-kit/item-data-picker-panel';
+import { switchItem } from '@luzmo/analytics-components-kit/utils';
+
+const DATASET_ID = 'your-dataset-id';
+const API_CONFIG = {
+  apiUrl: 'https://api.luzmo.com',
+  authKey: 'your-auth-key',
+  authToken: 'your-auth-token'
+};
+
+// State
+let activeItem = {
+  type: 'bar-chart',
+  options: {},
+  slots: []
+};
+
+// Handle slot content changes (same handler for both panels)
+function handleSlotsChange(event: CustomEvent) {
+  activeItem.slots = event.detail.slotsContents;
+  // Update your Luzmo chart with the new slots
+}
+
+// Switch chart type while preserving compatible data
+function handleItemTypeChange(newType: string) {
+  const newItem = switchItem({
+    oldItemType: activeItem.type,
+    newItemType: newType,
+    slots: activeItem.slots,
+    options: activeItem.options
+  });
+  activeItem = { ...newItem };
+}
+```
+
+#### HTML
+
+```html
+<!-- Desktop: Drag & drop experience -->
+<div
+  class="drag-and-drop-panel"
+  style="display: flex; gap: 1rem;"
+>
+  <luzmo-draggable-data-fields-panel
+    .datasetIds="${[DATASET_ID]}"
+    .apiUrl="${API_CONFIG.apiUrl}"
+    .authKey="${API_CONFIG.authKey}"
+    .authToken="${API_CONFIG.authToken}"
+    draggable-data-field-variant="highlight"
+    language="en"
+    size="m"
+  >
+  </luzmo-draggable-data-fields-panel>
+
+  <luzmo-item-data-drop-panel
+    .itemType="${activeItem.type}"
+    .slotsContents="${activeItem.slots}"
+    .apiUrl="${API_CONFIG.apiUrl}"
+    .authKey="${API_CONFIG.authKey}"
+    .authToken="${API_CONFIG.authToken}"
+    grows
+    language="en"
+    size="m"
+    @luzmo-slots-contents-changed="${handleSlotsChange}"
+  >
+  </luzmo-item-data-drop-panel>
+</div>
+
+<!-- Mobile: Picker experience (toggle visibility with CSS/JS) -->
+<div class="picker-panel">
+  <luzmo-item-data-picker-panel
+    .itemType="${activeItem.type}"
+    .slotsContents="${activeItem.slots}"
+    .datasetIds="${[DATASET_ID]}"
+    .apiUrl="${API_CONFIG.apiUrl}"
+    .authKey="${API_CONFIG.authKey}"
+    .authToken="${API_CONFIG.authToken}"
+    grows
+    selects="multiple"
+    language="en"
+    size="m"
+    @luzmo-slots-contents-changed="${handleSlotsChange}"
+  >
+  </luzmo-item-data-picker-panel>
+</div>
+```
+
+### Key Points
+
+- **Panel components handle complexity**: Panels auto-load slot configurations based on `item-type` and handle slot constraints automatically
+- **Same event for both panels**: Both `item-data-drop-panel` and `item-data-picker-panel` emit `luzmo-slots-contents-changed` with `event.detail.slotsContents`
+- **Auto-fetch data**: Pass `datasetIds` to let panels fetch dataset columns/formulas automatically
+- **Responsive patterns**: Use CSS media queries to show drag & drop on desktop and picker on mobile
+- **Chart type switching**: Use `switchItem()` utility to change chart types while preserving compatible slot data
+- **Slot contents format**: The `slotsContents` array is in the format expected by Luzmo Flex SDK visualization components
+
+## Item Definitions
+
+Import chart-specific slot configurations:
+
+```typescript
+import barChartSlotsConfig from '@luzmo/analytics-components-kit/item-definitions/bar-chart/bar-chart-slots.config';
+import columnChartOptionsConfig from '@luzmo/analytics-components-kit/item-definitions/column-chart/column-chart-options.config';
+```
+
+Available chart types include: `area-chart`, `bar-chart`, `bubble-chart`, `bullet-chart`, `choropleth-map`, `circle-pack-chart`, `circular-gauge`, `column-chart`, `combination-chart`, `donut-chart`, `funnel-chart`, `heat-map`, `heat-table`, `line-chart`, `radar-chart`, `sankey-diagram`, `scatter-plot`, `speedometer-chart`, `sunburst-chart`, `treemap-chart`, `wordcloud-chart`, and more.
+
+## Theming
+
+Components are themed via global CSS custom properties (`--luzmo-*`). Define them on `:root` / `html` or scope them to a container.
+
+### Global Variables Reference
+
+All components inherit global CSS variables defined on `html` / `:root`. Overriding these variables updates the styling across all components.
+
+#### Animation
+
+| Variable                     | Default | Description                            |
+| ---------------------------- | ------- | -------------------------------------- |
+| `--luzmo-animation-duration` | `0.15s` | Duration of transitions and animations |
+
+#### Border Colors
+
+| Variable                          | Default               | Description                              |
+| --------------------------------- | --------------------- | ---------------------------------------- |
+| `--luzmo-border-color`            | `rgba(0, 0, 0, 0.1)`  | Default border color (semi-transparent)  |
+| `--luzmo-border-color-hover`      | `rgba(0, 0, 0, 0.15)` | Border color on hover                    |
+| `--luzmo-border-color-down`       | `rgba(0, 0, 0, 0.3)`  | Border color when pressed                |
+| `--luzmo-border-color-focus`      | `rgba(0, 0, 0, 0.15)` | Border color when focused                |
+| `--luzmo-border-color-rgb`        | `0, 0, 0`             | RGB values for border color calculations |
+| `--luzmo-border-color-full`       | `rgb(180, 180, 180)`  | Full opacity border color                |
+| `--luzmo-border-color-full-hover` | `rgb(140, 140, 140)`  | Full opacity border on hover             |
+| `--luzmo-border-color-full-down`  | `rgb(110, 110, 110)`  | Full opacity border when pressed         |
+| `--luzmo-border-color-full-focus` | `rgb(140, 140, 140)`  | Full opacity border when focused         |
+| `--luzmo-border-color-disabled`   | `#dddddd`             | Border color for disabled state          |
+
+#### Border Radius
+
+| Variable                     | Default  | Description                |
+| ---------------------------- | -------- | -------------------------- |
+| `--luzmo-border-radius`      | `6px`    | Default border radius      |
+| `--luzmo-border-radius-s`    | `4px`    | Small border radius        |
+| `--luzmo-border-radius-l`    | `8px`    | Large border radius        |
+| `--luzmo-border-radius-xl`   | `12px`   | Extra large border radius  |
+| `--luzmo-border-radius-full` | `999rem` | Fully rounded (pill shape) |
+
+#### Border Width
+
+| Variable               | Default | Description          |
+| ---------------------- | ------- | -------------------- |
+| `--luzmo-border-width` | `1px`   | Default border width |
+
+#### Background Colors
+
+| Variable                                      | Default              | Description                            |
+| --------------------------------------------- | -------------------- | -------------------------------------- |
+| `--luzmo-background-color`                    | `#ffffff`            | Default background color               |
+| `--luzmo-background-color-rgb`                | `255, 255, 255`      | RGB values for background calculations |
+| `--luzmo-background-color-disabled`           | `#eeeeee`            | Background for disabled state          |
+| `--luzmo-background-color-hover`              | `#f0f0fc`            | Background on hover                    |
+| `--luzmo-background-color-down`               | `#f1f1ff`            | Background when pressed                |
+| `--luzmo-background-color-focus`              | `#f0f0fc`            | Background when focused                |
+| `--luzmo-background-color-highlight`          | `rgb(240, 240, 240)` | Highlighted background                 |
+| `--luzmo-background-color-highlight-disabled` | `rgb(245, 245, 245)` | Disabled highlighted background        |
+| `--luzmo-background-color-highlight-hover`    | `rgb(225, 225, 225)` | Highlighted background on hover        |
+| `--luzmo-background-color-highlight-down`     | `rgb(215, 215, 215)` | Highlighted background when pressed    |
+| `--luzmo-background-color-highlight-focus`    | `rgb(225, 225, 225)` | Highlighted background when focused    |
+| `--luzmo-background-color-alt-1`              | `rgb(250, 250, 250)` | Alternate background 1                 |
+| `--luzmo-background-color-alt-2`              | `rgb(239, 239, 239)` | Alternate background 2                 |
+
+#### Typography
+
+| Variable                       | Default            | Description                 |
+| ------------------------------ | ------------------ | --------------------------- |
+| `--luzmo-font-family`          | System fonts stack | Font family for all text    |
+| `--luzmo-font-size-xs`         | `10px`             | Extra small font size       |
+| `--luzmo-font-size-s`          | `12px`             | Small font size             |
+| `--luzmo-font-size-m`          | `14px`             | Medium font size            |
+| `--luzmo-font-size`            | `14px`             | Default font size           |
+| `--luzmo-font-size-l`          | `16px`             | Large font size             |
+| `--luzmo-font-size-xl`         | `18px`             | Extra large font size       |
+| `--luzmo-font-size-xxl`        | `20px`             | Extra extra large font size |
+| `--luzmo-font-style`           | `normal`           | Default font style          |
+| `--luzmo-line-height`          | `normal`           | Default line height         |
+| `--luzmo-font-weight`          | `400`              | Regular font weight         |
+| `--luzmo-font-weight-semibold` | `500`              | Semi-bold font weight       |
+| `--luzmo-font-weight-bold`     | `600`              | Bold font weight            |
+
+#### Font Colors
+
+| Variable                          | Default   | Description              |
+| --------------------------------- | --------- | ------------------------ |
+| `--luzmo-font-color`              | `#333`    | Default text color       |
+| `--luzmo-font-color-hard`         | `#000`    | High contrast text color |
+| `--luzmo-font-color-disabled`     | `#aaaaaa` | Disabled text color      |
+| `--luzmo-font-color-extra-dimmed` | `#888`    | Very subtle text color   |
+| `--luzmo-font-color-hover`        | `#333`    | Text color on hover      |
+| `--luzmo-font-color-down`         | `#111`    | Text color when pressed  |
+| `--luzmo-font-color-focus`        | `#333`    | Text color when focused  |
+
+#### Primary Color
+
+| Variable                        | Default       | Description                      |
+| ------------------------------- | ------------- | -------------------------------- |
+| `--luzmo-primary`               | `#4434ff`     | Primary brand color              |
+| `--luzmo-primary-hover`         | `#4234e4`     | Primary color on hover           |
+| `--luzmo-primary-down`          | `#392cc7`     | Primary color when pressed       |
+| `--luzmo-primary-focus`         | `#4234e4`     | Primary color when focused       |
+| `--luzmo-primary-inverse-color` | `#ffffff`     | Text color on primary background |
+| `--luzmo-primary-rgb`           | `68, 52, 255` | RGB values for primary color     |
+
+#### Secondary Color
+
+| Variable                          | Default                  | Description                        |
+| --------------------------------- | ------------------------ | ---------------------------------- |
+| `--luzmo-secondary`               | `#ff00ff`                | Secondary brand color              |
+| `--luzmo-secondary-hover`         | `#e309e3`                | Secondary color on hover           |
+| `--luzmo-secondary-down`          | `#c711c7`                | Secondary color when pressed       |
+| `--luzmo-secondary-focus`         | `#e309e3`                | Secondary color when focused       |
+| `--luzmo-secondary-inverse-color` | `#ffffff`                | Text color on secondary background |
+| `--luzmo-secondary-rgb`           | `255, 0, 255`            | RGB values for secondary color     |
+| `--luzmo-secondary-outline`       | `rgba(255, 0, 255, 0.2)` | Secondary outline color            |
+
+#### Semantic Colors
+
+| Variable                        | Default             | Description                      |
+| ------------------------------- | ------------------- | -------------------------------- |
+| `--luzmo-negative-color`        | `#ca221c`           | Error/danger color               |
+| `--luzmo-negative-color-hover`  | `#b3241f`           | Negative color on hover          |
+| `--luzmo-negative-color-down`   | `#9f231f`           | Negative color when pressed      |
+| `--luzmo-negative-color-focus`  | `#b3241f`           | Negative color when focused      |
+| `--luzmo-negative-color-rgb`    | `202, 34, 28`       | RGB values for negative color    |
+| `--luzmo-positive-color`        | `rgb(20, 150, 101)` | Success color                    |
+| `--luzmo-positive-color-hover`  | `rgb(17, 128, 86)`  | Positive color on hover          |
+| `--luzmo-positive-color-down`   | `rgb(16, 105, 71)`  | Positive color when pressed      |
+| `--luzmo-positive-color-focus`  | `rgb(17, 128, 86)`  | Positive color when focused      |
+| `--luzmo-positive-color-rgb`    | `20, 150, 101`      | RGB values for positive color    |
+| `--luzmo-color-informative`     | `#1a77e9`           | Informational color              |
+| `--luzmo-color-informative-rgb` | `26, 119, 233`      | RGB values for informative color |
+| `--luzmo-color-disabled`        | `#aaaaaa`           | Disabled state color             |
+
+#### Selected State Colors
+
+| Variable                            | Default              | Description                  |
+| ----------------------------------- | -------------------- | ---------------------------- |
+| `--luzmo-selected-color`            | `rgb(110, 110, 110)` | Selected item color          |
+| `--luzmo-selected-color-hover`      | `rgb(70, 70, 70)`    | Selected color on hover      |
+| `--luzmo-selected-color-down`       | `rgb(40, 40, 40)`    | Selected color when pressed  |
+| `--luzmo-selected-color-focus`      | `rgb(70, 70, 70)`    | Selected color when focused  |
+| `--luzmo-selected-color-hard`       | `#1e1e1e`            | High contrast selected color |
+| `--luzmo-selected-color-hard-hover` | `rgb(0, 0, 0)`       | Hard selected on hover       |
+| `--luzmo-selected-color-hard-down`  | `rgb(0, 0, 0)`       | Hard selected when pressed   |
+| `--luzmo-selected-color-hard-focus` | `rgb(0, 0, 0)`       | Hard selected when focused   |
+
+#### Spacing
+
+| Variable            | Default | Description           |
+| ------------------- | ------- | --------------------- |
+| `--luzmo-spacing-1` | `2px`   | Smallest spacing unit |
+| `--luzmo-spacing-2` | `4px`   | Extra small spacing   |
+| `--luzmo-spacing-3` | `8px`   | Small spacing         |
+| `--luzmo-spacing-4` | `12px`  | Medium spacing        |
+| `--luzmo-spacing-5` | `16px`  | Large spacing         |
+
+#### Focus Indicator
+
+| Variable                  | Default                | Description                             |
+| ------------------------- | ---------------------- | --------------------------------------- |
+| `--luzmo-indicator-gap`   | `2px`                  | Gap between element and focus indicator |
+| `--luzmo-indicator-width` | `1px`                  | Focus indicator width                   |
+| `--luzmo-indicator-color` | `var(--luzmo-primary)` | Focus indicator color                   |
+
+#### Component Heights
+
+| Variable                       | Default | Description                        |
+| ------------------------------ | ------- | ---------------------------------- |
+| `--luzmo-component-height-xxs` | `20px`  | Extra extra small component height |
+| `--luzmo-component-height-xs`  | `24px`  | Extra small component height       |
+| `--luzmo-component-height-s`   | `28px`  | Small component height             |
+| `--luzmo-component-height`     | `32px`  | Default component height           |
+| `--luzmo-component-height-l`   | `40px`  | Large component height             |
+| `--luzmo-component-height-xl`  | `48px`  | Extra large component height       |
+| `--luzmo-component-height-xxl` | `64px`  | Extra extra large component height |
+
+#### Icon Sizes
+
+| Variable                | Default | Description            |
+| ----------------------- | ------- | ---------------------- |
+| `--luzmo-icon-size-xxs` | `12px`  | Extra extra small icon |
+| `--luzmo-icon-size-xs`  | `14px`  | Extra small icon       |
+| `--luzmo-icon-size-s`   | `16px`  | Small icon             |
+| `--luzmo-icon-size-m`   | `18px`  | Medium icon            |
+| `--luzmo-icon-size-l`   | `20px`  | Large icon             |
+| `--luzmo-icon-size-xl`  | `22px`  | Extra large icon       |
+| `--luzmo-icon-size-xxl` | `32px`  | Extra extra large icon |
+
+### Overriding Variables
+
+```css
+:root {
+  --luzmo-primary: #4434ff;
+  --luzmo-background-color: #ffffff;
+  --luzmo-font-color: #333;
+}
+
+/* Scope overrides to a specific container */
+.my-chart-editor {
+  --luzmo-primary: #7b90ff;
+  --luzmo-background-color: #262626;
+  --luzmo-font-color: #ced4da;
+}
+```
+
+### Dark Theme
+
+Apply the pre-defined dark theme by adding the `dark-theme` class to a container or `html`:
+
+```html
+<html class="dark-theme">
+  <!-- All components inherit dark theme -->
+</html>
+```
+
+```css
+.dark-theme {
+  /* Primary color (lighter for dark backgrounds) */
+  --luzmo-primary: #7b90ff;
+  --luzmo-primary-hover: #5e71d0;
+  --luzmo-primary-down: #6c80e4;
+  --luzmo-primary-focus: rgb(94, 113, 208);
+  --luzmo-primary-inverse-color: #ffffff;
+  --luzmo-primary-rgb: 94, 113, 208;
+
+  /* Secondary color */
+  --luzmo-secondary: #ebff00;
+  --luzmo-secondary-hover: #c8db00;
+  --luzmo-secondary-down: #b1c008;
+  --luzmo-secondary-focus: rgb(200, 219, 0);
+  --luzmo-secondary-inverse-color: #333;
+
+  /* Background colors */
+  --luzmo-background-color: #262626;
+  --luzmo-background-color-hover: #414040;
+  --luzmo-background-color-down: #585353;
+  --luzmo-background-color-focus: #414040;
+  --luzmo-background-color-highlight: rgb(72, 72, 72);
+  --luzmo-background-color-highlight-hover: rgb(90, 90, 90);
+  --luzmo-background-color-highlight-down: rgb(100, 100, 100);
+  --luzmo-background-color-alt-1: rgb(45, 45, 50);
+  --luzmo-background-color-rgb: 0, 0, 0;
+
+  /* Font colors */
+  --luzmo-font-color: #ced4da;
+  --luzmo-font-color-hover: #e0e4e8;
+  --luzmo-font-color-down: #efefef;
+  --luzmo-font-color-focus: #f8f9fa;
+  --luzmo-font-color-hard: #f8f9fa;
+  --luzmo-font-color-extra-dimmed: #72787f;
+
+  /* Border colors (white-based for dark backgrounds) */
+  --luzmo-border-color-rgb: 255, 255, 255;
+  --luzmo-border-color: rgba(255, 255, 255, 0.2);
+  --luzmo-border-color-hover: rgba(255, 255, 255, 0.3);
+  --luzmo-border-color-down: rgba(255, 255, 255, 0.35);
+  --luzmo-border-color-focus: rgba(255, 255, 255, 0.3);
+  --luzmo-border-color-full: #4c4c57;
+  --luzmo-border-color-full-hover: rgb(101, 101, 112);
+  --luzmo-border-color-full-down: rgb(130, 130, 138);
+
+  /* Selected state colors */
+  --luzmo-selected-color: #afafaf;
+  --luzmo-selected-color-hover: #dfdfdf;
+  --luzmo-selected-color-down: #efefef;
+  --luzmo-selected-color-focus: #dfdfdf;
+  --luzmo-selected-color-hard: #e9e9e9;
+
+  /* Disabled state */
+  --luzmo-color-disabled: #75797b;
+  --luzmo-border-color-disabled: #333;
+}
+```
+
+### Component CSS Variable Overrides
+
+Each component exposes its own CSS variables for fine-grained customization. To discover available variables:
+
+1. Inspect the component in your browser's DevTools
+2. Check the computed styles for CSS variables used by the component
+
+> **Important**: Only override variables prefixed with `--luzmo-`. Other variables are internal and cannot be reliably overridden.
+
+```css
+/* Override droppable-slot styling */
+luzmo-droppable-slot {
+  --luzmo-droppable-slot-height: 3rem;
+  --luzmo-droppable-slot-border-radius: 8px;
+  --luzmo-droppable-slot-background: var(--luzmo-background-color-alt-1);
+}
+
+/* Scope overrides to a specific container */
+.my-chart-editor luzmo-droppable-slot {
+  --luzmo-droppable-slot-height: 2.5rem;
+}
+```
+
+## Browser Support
+
+- Last 2 versions of Chrome
+- Last 2 versions of Firefox
+- Last 2 versions of Safari
+- Last 2 versions of Edge
+
+## License
+
+Copyright © 2026 Luzmo. All rights reserved.
+
+This package must be used according to the [Luzmo Terms of Service](https://www.luzmo.com/information-pages/terms-of-use). This license allows users with a current active Luzmo account to use this package.

package/angular/README.md

@@ -0,0 +1,67 @@
+# Luzmo Analytics Components - Angular wrappers
+
+> **Framework size: <2 kB per component (tree-shakeable)**
+
+This sub-package is generated automatically. Each wrapper is a thin
+layer produced by the internal `createComponent` helper which preserves the exact typing
+information of the underlying web component.
+
+## Installation
+
+```bash
+pnpm add @luzmo/analytics-components-kit @luzmo/analytics-components-kit-angular
+```
+
+## Usage (Angular 17+ standalone)
+
+```ts
+import { bootstrapApplication } from '@angular/platform-browser';
+import { AiInteractionTextareaComponent } from '@luzmo/analytics-components-kit-angular';
+
+bootstrapApplication(AiInteractionTextareaComponent);
+```
+
+## Available components
+- `AiInteractionTextareaComponent` → <luzmo-ai-interaction-textarea>
+- `DatasetIconComponent` → <luzmo-dataset-icon>
+- `DatasetSelectorListComponent` → <luzmo-dataset-selector-list>
+- `DatasetSelectorRowComponent` → <luzmo-dataset-selector-row>
+- `DisplaySettingsComponent` → <luzmo-display-settings>
+- `DisplaySettingsBinningComponent` → <luzmo-display-settings-binning>
+- `DisplaySettingsDatetimeComponent` → <luzmo-display-settings-datetime>
+- `DisplaySettingsGrandTotalsComponent` → <luzmo-display-settings-grand-totals>
+- `DisplaySettingsNumericComponent` → <luzmo-display-settings-numeric>
+- `DisplaySettingsPeriodOverPeriodComponent` → <luzmo-display-settings-period-over-period>
+- `DraggableDataFieldsPanelComponent` → <luzmo-draggable-data-fields-panel>
+- `DroppableSlotComponent` → <luzmo-droppable-slot>
+- `EditFiltersComponent` → <luzmo-edit-filters>
+- `EditItemComponent` → <luzmo-edit-item>
+- `EditOptionComponent` → <luzmo-edit-option>
+- `EditOptionActionButtonGroupComponent` → <luzmo-edit-option-action-button-group>
+- `EditOptionColorPalettePickerComponent` → <luzmo-edit-option-color-palette-picker>
+- `EditOptionColorPickerComponent` → <luzmo-edit-option-color-picker>
+- `EditOptionColorRangeComponent` → <luzmo-edit-option-color-range>
+- `EditOptionMultiLanguageFieldComponent` → <luzmo-edit-option-multi-language-field>
+- `EditOptionNumberFieldComponent` → <luzmo-edit-option-number-field>
+- `EditOptionPickerComponent` → <luzmo-edit-option-picker>
+- `EditOptionPositionPickerComponent` → <luzmo-edit-option-position-picker>
+- `EditOptionPositionsNumberFieldComponent` → <luzmo-edit-option-positions-number-field>
+- `EditOptionRadioButtonGroupComponent` → <luzmo-edit-option-radio-button-group>
+- `EditOptionSliderComponent` → <luzmo-edit-option-slider>
+- `EditOptionSwitchComponent` → <luzmo-edit-option-switch>
+- `EditOptionTextFieldComponent` → <luzmo-edit-option-text-field>
+- `FilterExpressionPickerComponent` → <luzmo-filter-expression-picker>
+- `FilterItemComponent` → <luzmo-filter-item>
+- `FilterParameterPickerComponent` → <luzmo-filter-parameter-picker>
+- `FilterValuePickerComponent` → <luzmo-filter-value-picker>
+- `FilterValuePickerDatetimeComponent` → <luzmo-filter-value-picker-datetime>
+- `FilterValuePickerHierarchyComponent` → <luzmo-filter-value-picker-hierarchy>
+- `FilterValuePickerNumericComponent` → <luzmo-filter-value-picker-numeric>
+- `GridComponent` → <luzmo-grid>
+- `GridItemActionsMenuComponent` → <luzmo-grid-item-actions-menu>
+- `ItemDataDropPanelComponent` → <luzmo-item-data-drop-panel>
+- `ItemDataPickerPanelComponent` → <luzmo-item-data-picker-panel>
+- `SlotContentsPickerComponent` → <luzmo-slot-contents-picker>
+- `SlotMenuComponent` → <luzmo-slot-menu>
+- `SlotMenuListComponent` → <luzmo-slot-menu-list>
+- `VizItemMenuComponent` → <luzmo-viz-item-menu>