Stat tiles

<cae-stat-tiles> shows figures as a grid of tiles: each a label, a value and lines of facts under it, and a link. Register it with @contraagent/elements/tiles/define, which also registers the <cae-count> a tile’s number counts up in; the types are in @contraagent/elements/tiles.

Reference: <cae-stat-tiles>

docs/examples/tiles.ts

// Stat tiles: hand-written figures, one with a tone and a link. The host holds
// the figures and answers `cae-action`.
import '@contraagent/elements/tiles/define';
import type { StatTile } from '@contraagent/elements/tiles';

const tiles: StatTile[] = [
  { id: 'jobs', label: 'Jobs', value: 24, sub: [[{ text: '22 passed' }, { text: '2 failed', tone: 'failed' }]] },
  {
    id: 'failed',
    label: 'Failed jobs',
    value: 2,
    tone: 'failed',
    sub: [['Unit tests', 'Lint']],
    action: { id: 'list', label: 'Failed jobs in the log' },
  },
  { id: 'time', label: 'Build time', value: '14m 05s', sub: [['Longest: Unit tests']], tip: 'Sum over all jobs' },
  { id: 'queued', label: 'Queued', value: 0, sub: [['No jobs waiting']] },
];

export function mount(host: HTMLElement): void {
  const grid = document.createElement('cae-stat-tiles');
  grid.columns = 4;
  grid.tiles = tiles;
  const shown = document.createElement('p');
  grid.addEventListener('cae-action', (e) => (shown.textContent = `Action: ${e.detail.action} of ${e.detail.id}`));
  host.replaceChildren(grid, shown);
}

Tiles

A tile is a StatTile. Its value is a number or a text: a number counts up to a new value, and the tile bumps when it changes (unless bump is off or the reader asks for reduced motion). Each line under the value is a row of facts (factLine, Primitives); a fact with a tone is in its status colour, and an empty line keeps its place.

src/tiles/types.ts

/** A figure as a tile: its name, its value and the lines under it. */
export interface StatTile {
  /** Unique among the tiles: `data-id` on the tile, and the `id` of `cae-action`. */
  id: string;
  label: string;
  /** A number counts up to a new value, and the tile bumps when it changes; a text is shown as it is. */
  value: number | string;
  /** The status the figure is in: its value, the mark before its label and an edge take the tone. None (or `neutral`) for a plain figure. */
  tone?: Tone;
  /** The tile's tooltip. */
  tip?: string;
  /** The lines under the value, each a row of facts (`factLine`); an empty line keeps its place. */
  sub?: readonly (readonly (string | Fact)[])[];
  /** A link under the lines: a click sends `cae-action` with the tile's id and this id. */
  action?: { id: string; label: string };
}

A tile is neutral by default. A tile with a tone takes it on its value, on the mark before its label (✓ done, ✕ failed, ◌ attention) and on a thin edge, and has data-tone. Give a tone only to a figure that is a status, such as a count of failures above 0; a total or a measure stays neutral.

Events

A tile’s link sends cae-action with the tile’s id and the action’s id; the host decides what it opens.

Look

columns sets the tiles per row in a wide element (5); a narrower one has 4 below 1100px of its width, 2 below 660px and 1 below 240px. --cae-stat-tiles-gap sets the space between the tiles. The parts are tiles, tile (with data-id and data-tone), label, value, sub and action.