Breakdown
Display host-prepared group metrics and contributing records; group selection is a host request.
Use the web element directly without the semantic runtime.
Use this component directly or compose it in application code.
The standard recipe resolver does not select this component automatically.
Import and live example#
Two authorized team groups with exact record counts and selectable group rows.
Interactive preview requires JavaScript.
View the complete example source
import {registerAeliqoElements} from "@varendo/web";
import {
AeliqoBreakdownElement,
AeliqoComparisonElement,
AeliqoExplorerElement,
AeliqoFormFlowElement,
AeliqoInvestigationElement,
AeliqoQualityPanelElement,
AeliqoRecordEditorElement,
AeliqoSearchResultsElement,
} from "@varendo/web/compound";
import {AeliqoDateRangeElement, AeliqoTextFieldElement} from "@varendo/web/inputs";
import type {ResultRef, Scalar} from "@varendo/core";
import type {VisualizationBindingContext, VisualizationSpec} from "@varendo/core/visualization";
import type {AeliqoDataColumn, AeliqoDataScope, AeliqoFieldOption} from "@varendo/web/data";
import type {VisualizationDataset} from "@varendo/web/visualization";
const catalogRef: ResultRef = {
id: "aeliqo-catalog-example",
revision: "1",
outputId: "people",
queryDigest: "catalog-query",
scopeDigest: "catalog-scope",
};
const catalogRows: readonly Readonly<Record<string, Scalar>>[] = [
{id: "ada", name: "Ada Lovelace", team: "Research", date: "2026-09-08", amount: 120},
{id: "lin", name: "Lin Chen", team: "Product", date: "2026-09-09", amount: 96},
{id: "grace", name: "Grace Hopper", team: "Research", date: "2026-09-10", amount: 144},
];
const catalogColumns: readonly AeliqoDataColumn[] = [
{key: "id", label: "ID", type: "text", sortable: true},
{key: "name", label: "Name", type: "text", sortable: true},
{key: "team", label: "Team", type: "text"},
{key: "date", label: "Date", type: "date", sortable: true},
{key: "amount", label: "Amount", type: "integer", align: "end"},
];
const catalogFields: readonly AeliqoFieldOption[] = [
{id: "name", label: "Name", type: "text"},
{id: "team", label: "Team", type: "text"},
{id: "amount", label: "Amount", type: "integer"},
];
const catalogScope: AeliqoDataScope = {loaded: catalogRows.length, filteredTotal: catalogRows.length, populationDigest: catalogRef.scopeDigest, kind: "filtered", label: "Authorized people"};
const catalogVisualizationContext: VisualizationBindingContext = {results: []};
const catalogVisualizationDataset: VisualizationDataset = {result: catalogRef, rows: catalogRows};
const catalogVisualizationSpecs: Readonly<Record<"trend", VisualizationSpec>> = {trend: {version: "1", view: "trend", plot: {version: "1", root: {kind: "unit", mark: "line", result: catalogRef, missing: "gap", encoding: {x: {field: "date", scale: "temporal"}, y: {field: "amount", scale: "linear"}}}}}};
registerAeliqoElements();
const host = document.querySelector<HTMLElement>("#aeliqo-example") ?? (() => {
const created = document.createElement("div");
created.id = "aeliqo-example";
(document.body ?? document.documentElement).append(created);
return created;
})();
function createCatalogRoot(container: HTMLElement): HTMLElement {
const root = document.createElement("div");
root.dataset.catalogSourceRoot = "true";
root.style.display = "grid";
root.style.gap = "12px";
container.append(root);
return root;
}
function createCatalogElement<T extends HTMLElement>(tagName: string, container: HTMLElement): T {
const element = document.createElement(tagName) as T;
element.setAttribute("data-aeliqo-theme", "light");
container.append(element);
return element;
}
function appendSlottedText(root: HTMLElement, slot: string, textContent: string): void {
const content = document.createElement("span");
content.slot = slot;
content.textContent = textContent;
root.append(content);
}
const root = createCatalogRoot(host);
(((root) => {
const element = createCatalogElement<AeliqoBreakdownElement>("aeliqo-breakdown", root);
element.groups = [{
key: "research",
label: "Research",
value: 264,
unit: "records",
recordCount: 2
}, {
key: "product",
label: "Product",
value: 96,
unit: "records",
recordCount: 1
}];
element.rows = catalogRows;
element.columns = catalogColumns;
element.identity = ["id"];
element.entity = "person";
element.result = catalogRef;
element.scope = catalogScope;
}))(root);
Purpose#
Breakdown shows host-computed groups with values, record counts, and contributing rows. Use it when a total must stay traceable to the records behind it.
When to use it#
- The host has grouped metrics ready; each group needs a label, value, and count.
- Selecting a group should send its key to the host, not expand scope itself.
- Groups need their contributing records shown alongside the totals.
- Empty, partial, or stale groups need an honest displayed state.
When to use a different component#
- Use Comparison for a fixed set of chosen entities.
- Use Metric for one headline value without contributing records.
- Use Table when raw rows matter more than grouped totals.
Properties and defaults#
Group keys and values are supplied by the host; group selection does not expand result scope.
| Property | Use and ownership | Declared type | Initial value |
|---|---|---|---|
groups | Supplies the bounded grouped values and stable group identities used by the breakdown. | readonly AeliqoBreakdownGroup[] | [] |
rows | Supplies the bounded records to render. The component never fetches or widens this set. | readonly AeliqoDataRecord[] | [] |
columns | Defines ordered visible fields, labels, formatting, alignment, and supported column interactions. | readonly AeliqoDataColumn[] | [] |
identity | Lists stable identity fields used for selection, detail targeting, and state transfer. | readonly string[] | [] |
entity | Names the catalog entity whose records and identities are displayed. | string | 'record' |
groupLabel | Provides the visible text for the group control or section. | string | 'Group' |
metricLabel | Provides the visible text for the metric control or section. | string | 'Metric' |
result | Supplies the Result reference that binds displayed data to its query and scope evidence. | ResultRef | undefined | undefined |
scope | Supplies the visible authorization and population scope associated with the displayed value or rows. | AeliqoDataScope | undefined | undefined |
status | Supplies the explicit ready, loading, empty, partial, stale, or error state. | AeliqoCompoundStatus | 'ready' |
message | Provides the user-facing status, error, or recovery message. | string | '' |
title | Provides the visible title for the current data or compound surface. | string | 'Breakdown' |
selectedGroup | Controls the currently selected breakdown group by stable group identity. | string | '' |
Events#
| Event | Payload | Emitted | Application responsibility |
|---|---|---|---|
aeliqo-breakdown-group | The selected stable group key. | After the user selects a breakdown row. | Validate the group against the current result and update the controlled selection. |
Events cross the component boundary as user proposals. Validate their detail and current authority before applying a business effect.
Listen for aeliqo-breakdown-group
const element = document.querySelector('aeliqo-breakdown');<p>element?.addEventListener('aeliqo-breakdown-group', (event) => {
const proposal = (event as CustomEvent<unknown>).detail;
// Validate the proposal, update host state, then assign controlled properties.
applyProposal(proposal);
});States and failure handling#
Relevant states:
- ready
- empty
- partial
- loading
- stale
- error
Expected result: The breakdown preserves group identity and emits a host request when a group is selected.
Keyboard, focus, and accessibility#
Keyboard behavior:
- Tab
- Arrow keys
- Enter or Space
Exposed semantics:
- aria-label
- role
- section
Responsive behavior#
Keep each group label beside its value and record count. Let groups wrap as the host column narrows.
Style hooks#
- Shadow parts:
detail,header,hint,root,scope,status,table - Varendo design tokens referenced: none referenced directly by this class lineage.
Performance limits#
- The source-defined `MAX_BREAKDOWN_GROUPS` limit is 100.
Related components#
Generated TypeScript declaration#
View generated declaration
export declare class AeliqoBreakdownElement extends AeliqoCompoundElement {
static readonly properties: {
groups: {
attribute: boolean;
};
rows: {
attribute: boolean;
};
columns: {
attribute: boolean;
};
identity: {
attribute: boolean;
};
entity: {
type: StringConstructor;
};
groupLabel: {
attribute: string;
type: StringConstructor;
};
metricLabel: {
attribute: string;
type: StringConstructor;
};
result: {
attribute: boolean;
};
scope: {
attribute: boolean;
};
status: {
type: StringConstructor;
};
message: {
type: StringConstructor;
};
title: {
type: StringConstructor;
};
selectedGroup: {
attribute: string;
type: StringConstructor;
};
};
static readonly styles: import("lit").CSSResult[];
groups: readonly AeliqoBreakdownGroup[];
rows: readonly AeliqoDataRecord[];
columns: readonly AeliqoDataColumn[];
identity: readonly string[];
entity: string;
groupLabel: string;
metricLabel: string;
result: ResultRef | undefined;
scope: AeliqoDataScope | undefined;
status: AeliqoCompoundStatus;
message: string;
title: string;
selectedGroup: string;
protected render(): import("lit").TemplateResult<1>;
private readonly forwardGroupSelection;
}Version#
This page documents the Varendo 0.6 component contract.
