@luzmo/analytics-components-kit

v2.0.1

Published

5 days ago

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.

0High
0Medium
0Low

Luzmo design system components web components lucero analytics

Luzmo Analytics Components Kit

A collection of web components for building analytics interfaces with Luzmo. Built with Lit and designed to work seamlessly with Luzmo's visualization platform.

ACK produces and edits chart configuration (type, slots, options, filters). It does not render charts itself. You hand the configuration to Luzmo Embed (@luzmo/embed), which renders the visualization.

Full documentation: for detailed guides, component APIs, theming, and examples, see the Analytics Components Kit docs.

How it works

Configure: users interact with ACK components to pick data fields, assign them to chart slots, set options, and define filters. Each change fires an event your app captures.
Store: your app keeps the resulting slotsContents, options, and filters as its own state. ACK follows a one-way data flow: your app is the single source of truth.
Render: pass { type, slots, options, filters } into a Luzmo Embed component (luzmo-embed-viz-item for a single chart, or let luzmo-item-grid render a multi-chart layout).

Installation

npm install @luzmo/analytics-components-kit lit@^3.3.2 @luzmo/lucero@^2.7.1 @luzmo/icons@^1.0.1-alpha.49

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.

To render the configured charts, also install Luzmo Embed (optional):

npm install @luzmo/embed

@luzmo/embed works from 7.5.0 within 7.x and on any 8.x (peer range ^7.5.0 || ^8.0.0); 9 is not supported. A chart's inlineData (in luzmo-interactive-viz-item) needs 8.1.0 or a later 8.x and is a no-op on 7.x. The config panel loads its columns from the chart's datasets, so it hides itself for a chart with inlineData and no dataset columns. Embed applies no filters or ranking to inlineData, so a chart with it has no filters editor in the panel and no top-N ranking action. Saving a chart to a dashboard keeps inlineData, and the server rejects the save when the dashboard's inline data passes 2 MB in total. Embed treats inlineData as already-authorized output and does not apply viewer token filters to it, also after a dashboard save, so remove records the viewer must not see before you pass them.

Optional framework wrappers for embedding: @luzmo/react-embed, @luzmo/ngx-embed, @luzmo/vue-embed.

Important: This package is linked to @luzmo/[email protected]. Ensure you are using this version when working with slotsContents, slotConfiguration, options, and grid configurations.

Authentication

Every component that fetches data needs an embed authorization token. This is a short-lived, scoped token, not your org API credentials. It follows a two-tier model:

Server-side: your backend uses your org API key/token (environment variables, never shipped to the client) to call the Luzmo SDK and generate an embed authorization object.
Client-side: your frontend fetches that object from your backend and reads the authKey / authToken fields (or id / token if you return the raw Luzmo authorization object). These are passed to every component.

Set auth-key and auth-token consistently on every component that accesses data:

<luzmo-data-field-panel
  auth-key="your-auth-key"
  auth-token="your-auth-token"
></luzmo-data-field-panel>

<luzmo-item-slot-drop-panel
  auth-key="your-auth-key"
  auth-token="your-auth-token"
  item-type="bar-chart"
>
</luzmo-item-slot-drop-panel>

For the full walkthrough (generating embed tokens, token management, and multi-tenancy), see the authentication patterns guide.

Available Components

Import individual components so bundlers can tree-shake unused code. eg.

import '@luzmo/analytics-components-kit/data-field-panel';
import '@luzmo/analytics-components-kit/item-slot-drop-panel';
import '@luzmo/analytics-components-kit/item-option-panel';

Additional public components

All exposed components ship in the same package on latest, including AI chat and the composition primitives below. Import each using @luzmo/analytics-components-kit/<component>.

| Purpose | Component subpaths | | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | AI conversation and input | ai-chat, ai-interaction-textarea | | Interactive visualization and dashboard actions | interactive-viz-item, item-grid-item-actions-menu, add-to-dashboard | | Dataset selection | dataset-icon, dataset-selector-list, dataset-selector-row | | Display settings | display-settings, display-settings-binning, display-settings-datetime, display-settings-grand-totals, display-settings-numeric, display-settings-period-over-period | | Field selection and formula input | data-field-level, data-fields-select, formula-field | | Filter composition | filter-expression-picker, filter-item, filter-parameter-picker, filter-value-picker, filter-value-picker-datetime, filter-value-picker-hierarchy, filter-value-picker-numeric | | Slot menus | slot-menu, slot-menu-list |

See the ACK documentation for usage and API guidance. These exposed APIs follow semantic versioning. Internal helpers are not standalone public component subpaths.

luzmo-ai-chat can render a saved Agent's choice questions. It declares them to the aiprompt API only when you opt in with interactions: ['question'] in the AiChatSession config, because an API that predates client_capabilities rejects every request that carries it. Approval cards will follow in a later release.

Data Fields

Present the columns and formulas from a dataset so users can pick the data they want to visualize. Also includes components to display and edit Luzmo formula/column expressions (function syntax, e.g. SUM({datasetId:columnId})). Formula components accept datasets directly via datasetsDataFields or fetch them from the Luzmo API via dataset-ids (+ auth).

| Component | Import | Description | Reference | | ---------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- | | Data Field | @luzmo/analytics-components-kit/data-field | Single draggable representation of a dataset column or formula | Docs | | Data Field Panel | @luzmo/analytics-components-kit/data-field-panel | Panel listing all fields for one or more datasets, with search and dataset switching | Docs | | Formula | @luzmo/analytics-components-kit/formula | Read-only formula display: rich inline column/aggregation pills (display="rich") or plain text with inline type icons (display="text") | Docs | | Formula Editor | @luzmo/analytics-components-kit/formula-editor | Visual editor: CodeMirror input with inline column pills and nested aggregations, plus function/aggregation/dataset panels | Docs |

The editor emits debounced luzmo-expression-changed and, when auth-key/auth-token are set, DataBroker-backed luzmo-validity-changed (detail includes validating while the call is in flight). Event detail types (ExpressionChangedEventDetail, ValidityChangedEventDetail, DatasetsErrorEventDetail) and the related formula types are available from @luzmo/analytics-components-kit/types. Per-component developer-doc pages for Formula / Formula Editor are not published yet, so those rows link to the ACK overview until the docs go live.

Data Slots

Let users assign data fields to chart slots (e.g. x-axis, measure, legend). Drag-and-drop for desktop, dropdown pickers for compact/mobile layouts.

| Component | Import | Description | Reference | | ---------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | | Item Slot Drop | @luzmo/analytics-components-kit/item-slot-drop | Drop target for a single slot | Docs | | Item Slot Drop Panel | @luzmo/analytics-components-kit/item-slot-drop-panel | All slot drop targets for a chart type (drag & drop); auto constraints | Docs | | Item Slot Picker | @luzmo/analytics-components-kit/item-slot-picker | Dropdown picker for a single slot | Docs | | Item Slot Picker Panel | @luzmo/analytics-components-kit/item-slot-picker-panel | Dropdown pickers for all slots (no drag & drop); optional dataset picker | Docs |

Prefer the panel components (data-field-panel, item-slot-drop-panel, item-slot-picker-panel) over the individual primitives: panels auto-load slot configs and apply inter-slot constraints for you (e.g. "no multiple measures when the legend is filled"). Use the primitives only when you need custom layout/styling and can handle constraints yourself.

Slot panels also surface inline calculations supplied through slotsContents. An aggregating ad-hoc measure uses formula; a non-aggregating derived dimension uses expression. Slots show compact Formula or Expression labels with matching icons; the cog menu shows the full read-only calculation under the same heading, with vertical scrolling after four rows. Override its size-dependent maximum width with --luzmo-display-settings-calculation-max-width. Clear the picker with its X action, or clear a drop target with its trash action, to return to column selection.

Slot drops, pickers, and their panels accept hasConnectedComparisonFilter (default false) as runtime context. Update it when applicable comparison filters change, and supply full slotsContents plus itemType for comparison level limits. Emitted period comparisons, including event-only constraint proposals, contain only saved comparison settings and compact date-column references. Comparisons are supported for area, bar, combination, column and line charts, pivot tables and KPIs; chart categories using arrays, weekly levels or non-default datetime display modes are excluded.

Item Options

Let users adjust how a chart looks and behaves (colors, labels, chart mode, legend position, ...).

| Component | Import | Description | Reference | | ----------------- | --------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | Item Option | @luzmo/analytics-components-kit/item-option | Single option control (expose only what you need) | Docs | | Item Option Panel | @luzmo/analytics-components-kit/item-option-panel | Full grouped options editor for a chart type | Docs |

For an editor with undo, set live-interactions on luzmo-item-option, luzmo-item-option-panel, or luzmo-interactive-viz-item. You can also enable it directly on luzmo-item-option-slider, luzmo-item-option-color-picker, luzmo-item-option-color-range, and luzmo-item-option-guidelines (line colors). Drags and held keys then update live, without debounce. Gesture updates carry interaction: { id } on luzmo-option-changed for bare controls, luzmo-options-changed for item option/panel, and luzmo-chart-changed for interactive viz item.

All these entry points emit or forward luzmo-option-interaction-start (detail { id }) and -end / -cancel (detail { id, changed }) so you can record one history entry per gesture. A press that changes nothing emits no lifecycle events. Events through item option/panel include optionKey; bare controls omit it. Interactive viz item forwards the lifecycle with optionKey, plus the original chart and generation context. Call endInteraction() on the control or enclosing item option, panel, or interactive viz item before removing or rebinding it: it synchronously ends open gestures while keeping their current values. Live interactions are off by default; the default keeps the debounced behavior. The gesture boundaries come from Lucero; ACK requires @luzmo/lucero ^2.7.1 (at least 2.7.1 and below 3.0.0).

Individual option control editors are also exported for fully custom option UIs: item-option-action-button-group, item-option-color-palette-picker, item-option-color-picker, item-option-color-range, item-option-guidelines, item-option-multi-language-field, item-option-number-field, item-option-picker, item-option-position-picker, item-option-positions-number-field, item-option-radio-button-group, item-option-slider, item-option-switch, and item-option-text-field.

Filters

| Component | Import | Description | Reference | | --------- | ----------------------------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | Filters | @luzmo/analytics-components-kit/filters | Filter editor with nested AND/OR groups, plus read-only text and outline displays | Docs |

<luzmo-filters display="rich"> (the default) is the editor. display="text" renders the same tree as a read-only sentence: the outer group has no parentheses, and a nested AND/OR group that joins more than one filter is wrapped. display="outline" renders one wrapping filter per line inside bracket rails. In either read-only display, set column-display to outline, subtle, or fill to show column and formula references as Lucero badges one component size smaller (text is the default; xs at s, s at m, m at l, l at xl). Override their color with --luzmo-filters-column-badge-color and their label/icon color with --luzmo-filters-column-badge-font-color. Each outline row has a quiet delete button that emits luzmo-filters-changed; readonly hides those buttons. In the rich editor, quiet removes control chrome while the filters stay editable, and readonly keeps that appearance while blocking filter, group, and delete changes. display="text" does not emit that event. Hierarchy members stored as ids are resolved to localized names using content-language; a member object that already includes name is localized without a fetch. While names load, the value shows “1 item” or “N items” with an inline progress spinner. An id that is not returned stays visible, with a tooltip that some names could not be retrieved. Multiple values list the first few names, then a localized “and N more”; overflow uses a dotted underline and a Lucero tooltip.

<luzmo-filters> defaults to the standard Luzmo filter format (ItemFilterGroup[] from @luzmo/dashboard-contents-types). Narrow luzmo-filters-changed on event.detail.format before forwarding: canonical groups are compatible with luzmo-embed-viz-item's filters property and luzmo-item-grid items' filters; clean groups are for aligned hosts that accept ItemFilterOutput / DashboardFilterOutput. Group condition values are lowercase and / or. The published FilterGroup editor type uses the same casing, so typed consumers must migrate uppercase literals to and / or. At runtime uppercase AND / OR input is still accepted and normalized to lowercase on output.

filters accepts both halves of the public ItemFilterOutput / DashboardFilterOutput unions, so the result of an aligned getFilters() can be passed straight back in: canonical ItemFilterGroup[], or clean clause groups that own a top-level clause, nest inline, and flatten each leaf onto its reference (including dashboard retrieval envelopes). Output stays canonical unless you set format="clean", and event.detail.format names the half you received. A tree that cannot be represented cleanly — mixed where/having under or, a missing reference or value, an in / not in expression whose value is not an array, or a between expression whose range does not contain exactly two values — falls back to canonical output. A leaf that mixes encodings, or that matches neither a complete clean nor a complete canonical encoding, is rejected and the previous filters value is kept. Typed consumers of FiltersChangedEventDetail must narrow on format to keep filters as ItemFilterGroup[]. transformFilters, reverseTransformFilters, and detectFiltersFormat are exported from @luzmo/analytics-components-kit/filters for hosts that convert outside the editor. New groups and leaves receive a UUID (id on the group, properties.id on the leaf) that is kept on later edits. A newly chosen formula field defaults to properties.type: 'having'; an explicit where on a formula leaf is kept. A canonical leaf whose reference operands use the deprecated dataset_id, column_id or formula_id keys is read as datasetId, columnId or formulaId on every operand (both sides of a field-to-field comparison too), and an edit emits the camelCase keys.

Named parameter-backed values are opt-in with allow-parameters. Supply the initial definitions through the parameters property. A parameter created in the editor is appended to parameters and announced with luzmo-parameter-created, so handle that event to persist it; creating does not apply it to a filter, since the user attaches it by picking it from the list. Listen for luzmo-parameter-removed when a definition is detached from one filter. Detaching does not delete the definition. The exported FilterParameter, FilterParameterType, and FilterParameterEventDetail types describe this API.

Changing a hierarchy text operator such as contains to equals preserves the entered text and shows a pending value control while members load. The picker emits the member id: an exact id or localized label, otherwise the first matching member, otherwise the first loaded option. Opening a saved equals filter leaves that value unchanged. Loaded hierarchy members are reused across filter rows through the DataBroker cache, so another row for the same column opens without another /data request or pending state. Clearing the search or closing the picker restores that cached first page.

Set simple on <luzmo-filters> for an AND-only editor without the condition column or group actions. Existing OR conditions are preserved and cannot be edited in this mode; the component shows an explanation. Removing simple restores the full editor. Accepted replacements of filters cancel pending debounced changes; rejected values preserve pending edits. Changing only simple preserves pending AND edits. The read-only text display continues to show existing OR filters as a sentence. With default canonical output, removing the final filter preserves the empty root group and its id in both modes.

Filter rows are content-sized by default. Set the inherited filter-item width variables on luzmo-filters when the field, expression, and value controls should form aligned columns:

luzmo-filters {
  --luzmo-filter-item-field-width: 11rem;
  --luzmo-filter-item-expression-width: 7rem;
  --luzmo-filter-item-value-width: 0;
  --luzmo-filter-item-value-grow: 1;
}

Chart rendering

| Component | Import | Description | Reference | | --------- | ------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | | Item Grid | @luzmo/analytics-components-kit/item-grid | Interactive grid to arrange, resize, and manage multiple charts (renders internally) | Docs |

luzmo-interactive-viz-item (@luzmo/analytics-components-kit/interactive-viz-item) renders one chart with inline actions, a feedback bar and a config panel, for example as an AI chat answer. chartRenderOptions (property only) is merged into the embedded chart's options for display settings and is never emitted nor saved. In the config panel, hide-config-options hides the options tab, and slot-selects (multiple by default, or single) and slot-grows are passed to the slot picker panel as selects and grows. slotsConfiguration, customOptionsConfiguration and customTranslations (property only) pass the configs of a chart type ACK has no definition for, such as a custom chart, to the config panel. export(type) takes a VizItemExportType and forwards to the embedded chart's export, waiting for the embedded renderer when it has not loaded yet. It resolves without a value when there is no chart, when the embed fails, or when the chart is cleared or the element removed first. CSS parts: container, actions-bar, actions, chart-container, footer, config-panel.

To render a bare chart without these, use luzmo-embed-viz-item from @luzmo/embed (not part of this kit); see Rendering.

Usage: Drag & Drop Data Flow

Add <luzmo-data-field-panel> for data fields and <luzmo-item-slot-drop-panel> for slots (or <luzmo-item-slot-picker-panel> for mobile).
Feed the panel its data via dataset-ids (auto-fetch, with api-url + auth) or datasetsDataFields (your own data).
Set item-type (e.g. bar-chart) on the slot panel and listen to luzmo-slots-contents-changed to capture the slots state.
Treat slotsContents as your app state (re-apply it after each change for one-way data flow) and use { type, slots, options, filters } to render the configured chart.

import '@luzmo/analytics-components-kit/data-field-panel';
import '@luzmo/analytics-components-kit/item-slot-drop-panel';

const fieldsPanel = document.querySelector('luzmo-data-field-panel')!;
const dropPanel = document.querySelector('luzmo-item-slot-drop-panel')!;

for (const panel of [fieldsPanel, dropPanel]) {
  panel.apiUrl = 'https://api.luzmo.com'; // EU (default); US: https://api.us.luzmo.com; or your VPC host
  panel.authKey = 'your-auth-key';
  panel.authToken = 'your-auth-token';
}

fieldsPanel.datasetIds = ['your-dataset-id'];

// Tell the slot panel which chart type to build slots for (bar-chart, line-chart, ...)
dropPanel.itemType = 'bar-chart';

dropPanel.addEventListener('luzmo-slots-contents-changed', (event) => {
  const { slotsContents } = (event as CustomEvent<{ slotsContents: unknown[] }>).detail;
  dropPanel.slotsContents = slotsContents; // re-apply state (one-way data flow)

  // `slotsContents` is the `slots` half of the chart state; combine it with the
  // chart `type`, `options`, and `filters` you track to render (see Rendering).
});

item-slot-drop-panel and item-slot-picker-panel emit the same luzmo-slots-contents-changed event, so you can share one handler and swap them with CSS media queries for responsive layouts.

When item-slot-picker-panel (or item-slot-picker) itself sits in a popover or side panel, set slot-menu-mode="inline" together with selects="single": a data field's settings then expand below it instead of opening a second popover.

See the Data Field Panel reference for the full list of properties, events, and examples.

Rendering

ACK produces the configuration; luzmo-embed-viz-item (from @luzmo/embed) renders it. Store the state your ACK components emit and map it onto the viz item:

| Viz item input | Controlled by | ACK component(s) | | -------------- | ------------------- | -------------------------------------------------------------------------------------- | | type | which chart to draw | slot/option components via item-type | | slots | data the chart uses | item-slot-drop, item-slot-drop-panel, item-slot-picker, item-slot-picker-panel | | options | look and behavior | item-option, item-option-panel | | filters | rows included | filters |

import '@luzmo/embed';

const vizItem = document.querySelector('luzmo-embed-viz-item')!;
vizItem.appServer = 'https://app.luzmo.com'; // EU (default); US: https://app.us.luzmo.com; or your VPC host
vizItem.apiHost = 'https://api.luzmo.com'; // EU (default); US: https://api.us.luzmo.com; or your VPC host
vizItem.authKey = 'your-auth-key';
vizItem.authToken = 'your-auth-token';

// Map your ACK-produced state onto the viz item (your app is the single source of truth)
vizItem.type = itemType; // chart type
vizItem.slots = slotsContents; // from luzmo-slots-contents-changed
vizItem.options = options; // from luzmo-options-changed
vizItem.filters = filters; // canonical ItemFilterGroup[] from luzmo-filters-changed (narrow on detail.format if you set format="clean")

See the Flex reference and the "Using luzmo-embed-viz-item with the kit" guide in the ACK docs for every viz item property, event, and method.

Item Grid

Use <luzmo-item-grid> to render and edit a dashboard grid of charts (it embeds charts internally). Each item needs an id. Choose one of two modes:

Uncontrolled: seed the grid once with the initial-items attribute; the grid manages layout state internally.
Controlled: drive the grid with the items property and keep your app state in sync from the events.

const grid = document.querySelector('luzmo-item-grid')!;
grid.appServer = 'https://app.luzmo.com'; // EU (default); US: https://app.us.luzmo.com; or your VPC host
grid.apiHost = 'https://api.luzmo.com'; // EU (default); US: https://api.us.luzmo.com; or your VPC host
grid.authKey = 'your-auth-key';
grid.authToken = 'your-auth-token';

grid.items = [
  {
    id: 'chart-1',
    type: 'bar-chart',
    position: { col: 0, row: 0, sizeX: 24, sizeY: 20 },
    options: { mode: 'grouped' },
    slots: [
      // Each slot references a chart-type slot by `name` (bar-chart: y-axis, measure, legend).
      // Slot content describes the column/formula, not just its ids.
      {
        name: 'y-axis',
        content: [
          {
            datasetId: 'b35d4aaf-5f36-47a0-94e6-91a989d1635f',
            columnId: 'cb43b7f7-ede1-410f-88c1-5a93e1f9b92c',
            label: { en: 'Campaign' },
            type: 'hierarchy'
          }
        ]
      },
      {
        name: 'measure',
        content: [
          {
            datasetId: 'b35d4aaf-5f36-47a0-94e6-91a989d1635f',
            columnId: '8953c794-830c-46e5-bdb7-eee9b15dd8f5',
            label: { en: 'Opened emails' },
            type: 'hierarchy',
            aggregationFunc: 'count',
            format: ',.0f'
          }
        ]
      }
    ]
  }
];

// Controlled mode: re-apply the corrected items after each layout change
grid.addEventListener('luzmo-item-grid-layout-changed', (e) => {
  grid.items = (e as CustomEvent).detail.updatedItems;
});

Slot content is a full field descriptor (datasetId/columnId or formulaId, plus label, type, and modifiers like aggregationFunc, level, or format), not just an id pair. The easiest way to produce valid slot content is to let the drag & drop panels emit it; see Usage: Drag & Drop Data Flow.

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 for controlled vs uncontrolled details, all properties, events, methods, and examples.

Setting grid.items = undefined switches to uncontrolled mode and retains the last controlled items. Set grid.items = [] to clear the grid.

For a custom chart renderer, import ItemGridBase and the GridItemData type from @luzmo/analytics-components-kit/grid-core. Subclass the base and override renderItemContent(item, index) to supply the content. Item content is cached: also override getItemRenderDependencies() to return every reactive value used by your renderer beyond the item itself (for example, contentLanguage or credentials). Replace dependency object references when they change. The base handles layout and interactions without registering a grid element or importing @luzmo/embed. Existing /item-grid imports remain unchanged.

Utilities

Import helpers from @luzmo/analytics-components-kit/utils when you need ACK-compatible data or chart-state transformations without mounting a component.

import { loadDataFieldsForDatasets, switchItem, formatter, getValueForFormatter } from '@luzmo/analytics-components-kit/utils';
import { itemTypes } from '@luzmo/analytics-components-kit/item-list';

// Load datasets with their columns/formulas, converted to component-ready data fields
const datasets = await loadDataFieldsForDatasets(['dataset-id-1'], {
  // apiUrl: EU (default) https://api.luzmo.com; US: https://api.us.luzmo.com; or your VPC host
  dataBrokerConfig: { apiUrl: 'https://api.luzmo.com', authKey: 'your-auth-key', authToken: 'your-auth-token' }
});

// Switch chart type while preserving compatible slot data
const newItem = await switchItem({ oldItemType: 'bar-chart', newItemType: 'line-chart', slots, options });

// Build a chart picker from the available chart types
const chartOptions = itemTypes.map((item) => ({ label: item.label, value: item.type }));

See the Utilities reference for signatures, return types, behavior notes, and more examples.

Types

Import TypeScript types from the dedicated entrypoint:

import type {
  DatasetDataField,
  SlotContentsChangedEventDetail,
  SlotConstraintTriggeredEventDetail,
  ItemFilterGroup,
  FilterGroup,
  FiltersChangedEventDetail,
  FiltersInput,
  FiltersOutput,
  FiltersFormat,
  CleanFilterClauseGroup,
  ItemFilterOutput,
  DashboardFilterOutput,
  ItemOptionsChangedEventDetail,
  ItemOptionInteractionEventDetail,
  ChatMessage,
  ChatMessageQuestion,
  VizItemExportType
} from '@luzmo/analytics-components-kit/types';

Runtime values are exported from the main package (or @luzmo/analytics-components-kit/utils), e.g. import { PeriodOverPeriodCondition } from '@luzmo/analytics-components-kit';.

Language & Localization

Components render labels, placeholders, and data in the language you specify via two properties:

language: UI language (button labels, slot names, menu items). Supported: en, nl, fr, de, es.
content-language: locale-aware formatting and data labels (number formats, date patterns, column names). Defaults to language.

<luzmo-data-field-panel
  language="nl"
  content-language="nl"
></luzmo-data-field-panel>

See the patterns guide for multi-language data labels.

Item Definitions

Each chart type has a slots config, options config, and context config. Access them through dedicated subpaths (one named export per item type):

import { itemGroups, itemTypes, itemList } from '@luzmo/analytics-components-kit/item-list';
import { barChartSlotsConfig } from '@luzmo/analytics-components-kit/item-slots-configs';
import { barChartOptionsConfig } from '@luzmo/analytics-components-kit/item-options-configs';
import { barChartContextConfig } from '@luzmo/analytics-components-kit/item-context-configs';

Use itemTypes for the complete, authoritative list of chart types (bar-chart, line-chart, donut-chart, scatter-plot, heat-map, tables, numbers, and more). See the Item Definitions guide for details.

Theming

Components are themed via global CSS custom properties (--luzmo-*). Set them on :root / html for app-wide theming, or scope them to a container. eg.

:root {
  --luzmo-primary: #4434ff;
  --luzmo-background-color: #ffffff;
  --luzmo-font-color: #333;
}

Each component also exposes --luzmo-{component}-* variables for fine-grained overrides (only override variables prefixed with --luzmo-):

luzmo-item-slot-drop {
  --luzmo-item-slot-drop-height: 3rem;
  --luzmo-item-slot-drop-border-radius: 8px;
}

Browser Support

Last 2 versions of Chrome, Firefox, Safari, and Edge.

License

This package must be used according to the Luzmo Terms of Service. This license allows users with a current active Luzmo account to use this package.