Investigation
Trend, baseline, event timeline and detail; associations never imply causes.
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#
A people investigation with baseline, trend evidence, and selected record detail.
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<AeliqoInvestigationElement>("aeliqo-investigation", root);
element.entity = "person";
element.result = catalogRef;
element.scope = catalogScope;
element.baseline = 100;
element.detailRecord = catalogRows[0];
element.detailFields = catalogColumns;
element.trend = catalogVisualizationSpecs.trend;
element.trendContext = catalogVisualizationContext;
element.trendDatasets = [catalogVisualizationDataset];
}))(root);
Purpose#
Investigation arranges a trend, baseline metric, event timeline, and record detail in one scope. Use it when evidence about an entity must be reviewed together without implying cause.
When to use it#
- An entity needs trend, baseline, and event evidence viewed in one place.
- The host supplies the visualization specs, datasets, and detail record.
- Missing trend or event data must surface an explicit message.
- Associations may be shown but never presented as causes.
When to use a different component#
- Use Explorer for routine browse, filter, and selection work.
- Use Trend or Timeline alone when one evidence view is enough.
- Use Detail when only the record fields matter, without evidence panels.
Properties and defaults#
Trend and event specs remain evidence in the selected scope; associations are not upgraded to causal claims.
| Property | Use and ownership | Declared type | Initial value |
|---|---|---|---|
trendContext | Supplies trend context to the component as application-owned input. | VisualizationBindingContext | { results: [] } |
trendDatasets | Supplies the bounded ordered trend datasets collection used by this component. | readonly VisualizationDataset[] | [] |
eventContext | Supplies event context to the component as application-owned input. | VisualizationBindingContext | { results: [] } |
eventDatasets | Supplies the bounded ordered event datasets collection used by this component. | readonly VisualizationDataset[] | [] |
trend | Supplies trend to the component as application-owned input. | VisualizationSpec | undefined | undefined |
baseline | Supplies the comparison baseline and its evidence. The component does not infer a baseline from visible rows. | Scalar | undefined | undefined |
events | Supplies events to the component as application-owned input. | VisualizationSpec | undefined | undefined |
detailRecord | Supplies detail record to the component as application-owned input. | AeliqoDataRecord | undefined | undefined |
detailFields | Supplies the bounded ordered detail fields collection used by this component. | readonly AeliqoDataColumn[] | [] |
result | Supplies the Result reference that binds displayed data to its query and scope evidence. | ResultRef | undefined | undefined |
eventResult | Supplies event result to the component as application-owned input. | ResultRef | undefined | undefined |
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' |
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 | 'Investigation' |
label | Provides the visible label and accessible name for the component. | string | 'Trend' |
Events#
| Event | Payload | Emitted | Application responsibility |
|---|---|---|---|
aeliqo-visualization-select | Selected mark identity plus Result lineage. | After a selectable mark is activated. | Validate lineage and update controlled visualization or linked-detail selection. |
Events cross the component boundary as user proposals. Validate their detail and current authority before applying a business effect.
Listen for aeliqo-visualization-select
const element = document.querySelector('aeliqo-investigation');<p>element?.addEventListener('aeliqo-visualization-select', (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
- loading
- empty
- partial
- stale
- error
Expected result: The investigation aligns baseline, evidence visualizations, and detail without changing their lineage.
Keyboard, focus, and accessibility#
Keyboard behavior:
- Tab
- Arrow keys in child visualizations
- Enter selects evidence
Exposed semantics:
- aria-label
- role
- section
Responsive behavior#
Stack baseline, evidence, and detail in reading order. Avoid separate horizontal panels that hide the shared scope.
Style hooks#
- Shadow parts:
baseline,caution,detail,events,grid,header,hint,root,scope,status,trend - Varendo design tokens referenced:
--aeliqo-color-warning,--aeliqo-space-12
Related components#
Generated TypeScript declaration#
View generated declaration
export declare class AeliqoInvestigationElement extends AeliqoCompoundElement {
static readonly properties: {
trendContext: {
attribute: boolean;
};
trendDatasets: {
attribute: boolean;
};
eventContext: {
attribute: boolean;
};
eventDatasets: {
attribute: boolean;
};
trend: {
attribute: boolean;
};
baseline: {
attribute: boolean;
};
events: {
attribute: boolean;
};
detailRecord: {
attribute: boolean;
};
detailFields: {
attribute: boolean;
};
result: {
attribute: boolean;
};
eventResult: {
attribute: boolean;
};
identity: {
attribute: boolean;
};
entity: {
type: StringConstructor;
};
scope: {
attribute: boolean;
};
status: {
type: StringConstructor;
};
message: {
type: StringConstructor;
};
title: {
type: StringConstructor;
};
label: {
type: StringConstructor;
};
};
static readonly styles: import("lit").CSSResult[];
trendContext: VisualizationBindingContext;
trendDatasets: readonly VisualizationDataset[];
eventContext: VisualizationBindingContext;
eventDatasets: readonly VisualizationDataset[];
trend: VisualizationSpec | undefined;
baseline: Scalar | undefined;
events: VisualizationSpec | undefined;
detailRecord: AeliqoDataRecord | undefined;
detailFields: readonly AeliqoDataColumn[];
result: ResultRef | undefined;
eventResult: ResultRef | undefined;
identity: readonly string[];
entity: string;
scope: AeliqoDataScope | undefined;
status: AeliqoCompoundStatus;
message: string;
title: string;
label: string;
protected render(): import("lit").TemplateResult<1>;
}Version#
This page documents the Varendo 0.6 component contract.
