Utilities

The Analytics Components Kit exposes two standalone helper functions that you can use outside of any component. Import them from @luzmo/analytics-components-kit/utils .

• loadDataFieldsForDatasets -- fetches one or more datasets from the Luzmo API and converts their columns and saved formulas into the DatasetDataField shape that every ACK component expects.

• switchItem -- remaps slot contents from one chart type to another, preserving as much compatible data as possible.

loadDataFieldsForDatasets

Use loadDataFieldsForDatasets when you need component-ready data fields but are not using a component that fetches them automatically (such as luzmo-data-field-panel with dataset-ids ). It calls the Luzmo API for each dataset, retrieves columns and saved formulas, filters out hidden entries, and returns everything grouped by dataset. The result can be passed straight into datasetsDataFields on luzmo-data-field-panel , used to render individual luzmo-data-field elements, or consumed by any custom UI that needs the same field metadata ACK uses internally.

Signature

import { loadDataFieldsForDatasets } from '@luzmo/analytics-components-kit/utils';

const datasets = await loadDataFieldsForDatasets(
  datasetIds,  // string[] -- one or more dataset UUIDs
  {
    dataBrokerConfig: {
      apiUrl: string;    // Luzmo API base URL
      authKey: string;   // embed authorization key
      authToken: string; // embed authorization token
    };
  }
);

Return type

The function returns a Promise that resolves to an array of dataset objects, each containing its data fields:

Array<{
  id: string;
  name: Record<string, string>;          // e.g. { en: 'Sales' }
  description?: Record<string, string>;
  dataFields: DatasetDataField[];
}>

DatasetDataField is a discriminated union exported from @luzmo/analytics-components-kit/types . A field is either a column or a saved formula :

// Column variant
{
  datasetId: string;
  columnId: string;
  type: string;
  name: Record<string, string>;
  description?: Record<string, string>;
  subtype?: string;
  format?: string;
  lowestLevel?: number;
  highestLevel?: number;
  level?: number;
  hierarchyLevels?: Array<{ id: string; level: number; name: Record<string, string> }>;
}

// Saved-formula variant
{
  datasetId: string;
  formulaId: string;
  type: string;
  name: Record<string, string>;
  description?: Record<string, string>;
  subtype?: string;
  format?: string;
  lowestLevel?: number;
  level?: number;
}

Behavior notes

• datasetIds values are validated as UUIDs. Invalid entries trigger a warning and are skipped.

• Throws if datasetIds is empty or if no valid UUIDs remain after validation.

• Throws if dataBrokerConfig is missing.

• When authKey or authToken are omitted the function logs a warning; requests will only succeed for public datasets.

• Hidden columns and formulas are filtered out automatically.

• Authentication failures are re-thrown with a clearer error message.

Examples

Load fields for a single dataset:

import { loadDataFieldsForDatasets } from '@luzmo/analytics-components-kit/utils';

const datasets = await loadDataFieldsForDatasets(
  ['550e8400-e29b-41d4-a716-446655440000'],
  {
    dataBrokerConfig: {
      apiUrl: 'https://api.luzmo.com',
      authKey: '<your-auth-key>',
      authToken: '<your-auth-token>'
    }
  }
);

const fields = datasets[0]?.dataFields ?? [];

Feed the result into luzmo-data-field-panel :

const panel = document.querySelector('luzmo-data-field-panel');

const datasets = await loadDataFieldsForDatasets(datasetIds, {
  dataBrokerConfig: { apiUrl, authKey, authToken }
});

panel.datasetsDataFields = datasets;

Iterate fields to build a custom list (for example, showing only numeric fields):

const datasets = await loadDataFieldsForDatasets(datasetIds, {
  dataBrokerConfig: { apiUrl, authKey, authToken }
});

const numericFields = datasets.flatMap((ds) =>
  ds.dataFields.filter((f) => f.type === 'numeric')
);

switchItem

Use switchItem when a user changes the chart type in your editor and you need to carry their existing slot assignments over to the new type. The function loads the slot configurations for both chart types, then redistributes slot content so that numeric fields land in numeric slots and categorical fields land in categorical slots of the new chart. The result is a ready-to-use object you can write back into your editor state.

Signature

import { switchItem } from '@luzmo/analytics-components-kit/utils';

const result = await switchItem({
  oldItemType: string;   // current chart type, e.g. 'bar-chart'
  newItemType: string;   // target chart type, e.g. 'line-chart'
  slots: Array<{ name: string; content: unknown[] }>;
  options?: Record<string, unknown>;
});

Return type

{
  type: string;                                      // the resolved chart type
  slots: Array<{ name: string; content: unknown[] }>; // remapped slot contents
  options?: Record<string, unknown>;                  // shallow copy of the input options
}

How it maps content

• Loads the slot configuration for both the old and new chart types.

• Restores slot-type metadata on the old slots using the old chart type's config.

• Moves numeric content from old numeric slots (and numeric content found in mixed slots) into the new chart's numeric slots first, then into mixed slots.

• Moves non-numeric content from old categorical slots (and non-numeric content found in mixed slots) into the new chart's categorical slots first, then into mixed slots.

• Respects slot order and the canAcceptMultipleDataFields flag when distributing content.

• Returns the remapped slots as { name, content }[] .

Behavior notes

• options are shallow-copied into the result. Incompatible options for the new chart type are not removed automatically.

• If newItemType has no known slot configuration, the function falls back to { type: oldItemType || 'bar-chart', slots: originalSlots } .

Examples

Switch from a bar chart to a line chart:

import { switchItem } from '@luzmo/analytics-components-kit/utils';

const next = await switchItem({
  oldItemType: 'bar-chart',
  newItemType: 'line-chart',
  slots: [
    {
      name: 'measure',
      content: [{ type: 'numeric', column: 'revenue', set: 'dataset-id' }]
    },
    {
      name: 'y-axis',
      content: [{ type: 'hierarchy', column: 'month', set: 'dataset-id' }]
    }
  ],
  options: { mode: 'stacked' }
});

Apply the result to update your editor state and re-render the preview:

const next = await switchItem({
  oldItemType: currentType,
  newItemType: selectedType,
  slots: slotsContents,
  options: chartOptions
});

currentType = next.type;
slotsContents = next.slots;
chartOptions = next.options;

vizItem.type = currentType;
vizItem.slots = slotsContents;
vizItem.options = chartOptions;

Handle the fallback when the target type is unknown:

const next = await switchItem({
  oldItemType: 'bar-chart',
  newItemType: 'unknown-type',
  slots: currentSlots,
  options: currentOptions
});

// next.type will be 'bar-chart' (the old type) and
// next.slots will be the original slots, unchanged.