Charts and Widgets

Overview

The chart module and the three card modules cover dashboard surfaces: a chart of a series, a single figure with a delta, a ranked list, and the period selector the others read their date range from. Each one is a builder that produces a component description; each one either carries its data inline (staticDataset, staticItems, staticValue) or names a fetchUrl the frontend calls.

All of them are exported from the package root; the charts also have their own subpath.

import {
  ChartArea,
  ChartCard,
  KpiCard,
  PeriodSelector,
  TopListCard,
} from "@antelopejs/interface-dms/base";
// charts only
import { ChartLine, ChartType } from "@antelopejs/interface-dms/base/chart";

A Dashboard in One Page

The widgets compose through the layout builders from Layout and Containers. One PeriodSelector declares a scope id; every widget that names the same periodScope follows its range.

import {
  PageController,
  pagesCategory,
  RegisterPage,
} from "@antelopejs/interface-dms/page";
import {
  ChartArea,
  ChartCard,
  KpiCard,
  PeriodSelector,
  TopListCard,
} from "@antelopejs/interface-dms/base";
import { Grid, GridRow } from "@antelopejs/interface-dms/base/grid";
import { DefaultLayout } from "@antelopejs/interface-dms/base/layouts";

const SCOPE_ID = "ai-overview";

@RegisterPage()
export class OverviewPage extends PageController(
  "overview",
  { displayName: "Overview", icon: "i-ph-chart-line", category: pagesCategory },
  DefaultLayout({ fullWidth: true }),
) {
  static periodSelector = PeriodSelector({
    id: SCOPE_ID,
    align: "right",
    defaultPreset: "last-7-days",
    defaultComparison: "previous-period",
    presets: ["today", "last-7-days", "last-30-days"],
  });

  static kpis = Grid({ gap: "1rem" }).child(
    "kpiRow",
    GridRow().child(
      "actions",
      KpiCard({
        title: "Actions",
        icon: "i-ph-lightning",
        fetchUrl: "/ai/metrics/kpi/actions",
        periodScope: SCOPE_ID,
        valueFormat: "compact",
        compareLabel: "vs previous period",
      }),
    ),
  );

  static activityRow = Grid({ gap: "1rem" }).child(
    "row",
    GridRow()
      .child(
        "activityChart",
        ChartCard({
          title: "AI activity",
          description: "Actions over the selected period",
          icon: "i-ph-chart-line",
          fetchUrl: "/ai/metrics/series",
          periodScope: SCOPE_ID,
          valueFormat: "compact",
          chart: ChartArea({ xaxisType: "datetime" }),
        }),
        { colSpan: 2 },
      )
      .child(
        "topSkills",
        TopListCard({
          title: "Top skills",
          fetchUrl: "/ai/metrics/top-skills?limit=5",
          periodScope: SCOPE_ID,
        }),
      ),
  );
}

Chart Builders

There is one builder per chart type. Each takes its own props with the type discriminant optional — the builder fills it in — and returns a ComponentBuilder for that props type.

ChartType is the enum behind the discriminant: LINE, AREA, RANGE_AREA, BAR, COLUMN, SCATTER, DONUT, PIE, MIXED, RADAR, RADIAL_BAR, HEATMAP, CANDLESTICK. AnyChartProps is the union of all thirteen props interfaces.

Every builder gives the component a display name from title, falling back to the chart's own name ("Line Chart", "Donut Chart", …), and a matching icon.

Common Options

Every chart props interface extends BaseComponentProps and adds:

KeyValuePair is { key: string; value: string }.

When realtimeTopic is set, the builder registers each topic against the page it is declared on, using RegisterPageTopic from @antelopejs/interface-dms/realtime.

Cartesian Charts

LineChartProps, AreaChartProps, RangeAreaChartProps, BarChartProps, ColumnChartProps, ScatterChartProps, MixedChartProps, RadarChartProps and CandlestickChartProps share a second layer of options on top of the common ones:

ChartAutoYRange exposes padding?: number, defaulting to 0.08. The renderer extends native bounds to include finite annotation y and y2 coordinates, then subtracts abs(min) * padding from the lower bound and adds abs(max) * padding to the upper bound. At zero, the magnitude is 1 instead. Zero padding is valid; negative or nonfinite padding uses the default. Native series handling remains with the chart engine, including range and candle points and stacked series. This option does not add data to empty charts or enforce a zero baseline. The existing raw yaxis escape hatch remains the final override.

And each adds its own:

MixedChartSeriesDef declares how one series of a mixed chart is drawn: { name: string; type: ChartType.LINE | ChartType.AREA | ChartType.COLUMN | ChartType.RANGE_AREA; color?: ChartColorValue }.

ChartCurve is "smooth" | "straight" | "stepline". Prefer it to smooth, which only chooses between the first two.

ChartAnnotation draws a horizontal reference on the Y axis — a spend cap, a max bound, a volume capacity:

syncGroup is what turns a grid of separate metrics into one readable timeline: give every chart on the page the same group name and hovering one moves the crosshair on all of them.

Circular Charts

CircularChartProps extends the common options with staticDataset?: DonutRecord[] — a flat list of { label: string; value: number } rather than series.

Heatmap

HeatmapChartProps extends the common options directly — not the cartesian layer — with staticDataset?: ChartSeries[], shadeIntensity?: number and distributed?: boolean.

Series and Points

import type {
  ChartCandlePoint,
  ChartSeries,
  ChartSeriesPoint,
} from "@antelopejs/interface-dms/base/chart";

const series: ChartSeries[] = [
  {
    name: "Actions",
    data: [
      { x: "2026-07-01", y: 12 },
      { x: "2026-07-02", y: 18 },
      { x: "2026-07-03", y: null },
    ],
  },
];

A null y marks a gap. ChartSeries.type overrides the chart's own type for that series, which is what a mixed chart uses.

Set strokeWidth and strokeDashArray on each series, including comparison series, to keep stroke styling attached to the data when series are reordered, added or removed. Both values are non-negative pixel lengths: strokeWidth: 0 hides the stroke and strokeDashArray: 0 draws a solid line. A positive dash length draws repeating dashes; it is not a custom SVG dash pattern.

Each property falls back independently to the existing chart configuration when omitted. Series values override the chart-level strokeWidth and comparison defaults. Without series styles, line widths remain 3 pixels (1.5 for comparison series), and comparison dashes remain 4 pixels for comparisonStyle: "dashed". rawOptions still wins last: a stroke entry replaces the entire generated stroke section, without deep merging.

These properties also survive mixed-series definition projection. Set them on the data series, not on the positional seriesDefs. Rendering follows the chart type's stroke support; circular records do not expose series strokes. This API does not change fills, interpolation, markers, axes or legends.

Colours and Formats

ColorName is the chart palette and is distinct from the Color enum in Shared Types: it adds accent and it is a string union rather than an enum. ValueFormat is used by the three card components rather than by the charts themselves.

Chart Events

ChartCard

ChartCard wraps a chart in a card that owns the title, the fetch URL and the delta display, and holds the chart as a child under the id "chart".

import { ChartArea, ChartCard } from "@antelopejs/interface-dms/base";

const card = ChartCard({
  title: "Revenue",
  description: "Billed amount over the selected period",
  icon: "i-ph-currency-eur",
  fetchUrl: "/metrics/revenue",
  periodScope: "finance",
  valueFormat: "currency",
  currencyCode: "EUR",
  showDelta: true,
  chart: ChartArea({ xaxisType: "datetime" }),
});

ChartCardBuilderOptions is ChartCardProps plus one required field, chart: Component. The chart is taken out of the options and attached as the card's child, so the serialized card options are exactly ChartCardProps.

ChartCardProps extends BaseComponentProps:

KpiCard

KpiCard shows a single figure with an optional delta and sparkline.

import { KpiCard } from "@antelopejs/interface-dms/base";

const denied = KpiCard({
  title: "Denied",
  icon: "i-ph-prohibit",
  fetchUrl: "/ai/metrics/kpi/denied",
  valueFormat: "compact",
  invert: true,
  compareLabel: "vs previous period",
});

KpiCardProps extends BaseComponentProps:

TopListCard

TopListCard shows a ranked list of items, each with a value and optionally a delta, a sparkline and an avatar.

import { TopListCard } from "@antelopejs/interface-dms/base";

const topSkills = TopListCard({
  title: "Top skills",
  description: "Most-used tools over the selected period",
  fetchUrl: "/ai/metrics/top-skills?limit=5",
  periodScope: "ai-overview",
  showRank: true,
  highlightTopN: 3,
});

TopListCardProps extends BaseComponentProps:

TopListItem is the item shape, the element type of staticItems:

PeriodSelector

PeriodSelector owns a date range and a comparison mode, and publishes them under its id. Every widget carrying the same value in periodScope uses that range.

import { PeriodSelector } from "@antelopejs/interface-dms/base";

const selector = PeriodSelector({
  id: "finance",
  align: "right",
  defaultPreset: "this-month",
  defaultComparison: "previous-year",
  presets: ["this-month", "last-month", "ytd", "custom"],
  presetLabels: { ytd: "Year to date" },
  showRangeLabel: true,
});

PeriodSelectorProps extends BaseComponentProps:

PeriodPreset is "last-hour", "last-24h", "today", "yesterday", "last-7-days", "last-30-days", "last-90-days", "this-month", "last-month", "this-quarter", "last-quarter", "ytd", "last-year", "all" or "custom". "all" is every period: it has no bounds, so the bound widgets are sent no from / to. PeriodComparison is "none", "previous-period", "previous-year" or "custom". PeriodAlign is "left" | "center" | "right".

The selector keeps its period in the page URL, under keys prefixed with its id: ?<id>.period=<preset>&<id>.compare=<comparison> for a preset, ?<id>.from=<date>&<id>.to=<date> for a custom range (an ISO date, or an ISO date-time), plus <id>.compareFrom / <id>.compareTo for a custom comparison; ?<id>.period=all for every period. A URL naming from / to opens on that range even when "custom" is not offered, with no preset selected, and is not remembered. It starts from the URL, then from the user's last choice on that selector of that page (or on any selector sharing its rememberKey), then from defaultPreset / defaultComparison; the range and the comparison are read apart, and an unknown value, one the selector does not offer, or an invalid range falls back silently to the next source. A change replaces the history entry instead of adding one. There is no option to turn this off.

PeriodSelectorVariant is "default" | "segmented". segmented renders the presets as inline pills for one-click range switching; the custom range stays in its popover calendar either way.

Next Steps

• Layout and Containers - Grids, stacks, tabs, layouts and the custom-component escape hatch.