src/primitives/companion.ts

Functions

Imports

It imports src/render/figure.ts. Imported by src/index.ts, src/primitives/heat-strip.ts, src/primitives/progress-ring.ts, src/primitives/sparkline.ts, src/primitives/timeline.ts, src/primitives/uptime-strip.ts.

Source

1import { type DataTable, dataTableBlock } from "../render/figure.js";
2
3/** Options for the companion functions (`sparklineTable` and the rest). */
4export interface PrimitiveTableOptions {
5  /**
6   * How `markup` shows the table: in a closed disclosure (default), or only to assistive
7   * technology. As on a figure.
8   */
9  readonly dataTable?: "details" | "visually-hidden";
10}
11
12/**
13 * What a primitive's companion function returns: its numbers as a table and as a sentence, both
14 * computed from the same values as the drawing, so neither can disagree with it.
15 */
16export interface PrimitiveTable {
17  /** A sentence stating the values, for a caption, a page's text or an AI agent. */
18  readonly summary: string;
19  /** The values as rows and columns; the first column holds row headers. */
20  readonly table: DataTable;
21  /** The table as markup, in a disclosure or visually hidden, ready to put beside the primitive. */
22  readonly markup: string;
23}
24
25/** Assembles a companion result from its parts. */
26export function primitiveTable(
27  summary: string,
28  table: DataTable,
29  caption: string,
30  options: PrimitiveTableOptions | undefined,
31): PrimitiveTable {
32  return {
33    summary,
34    table,
35    markup: dataTableBlock(table, `Data for: ${caption}`, options?.dataTable),
36  };
37}