Check table

<cae-check-table> shows named values checked one by one: a row per name, with what it must be, what it is and the verdict. Register it with @contraagent/elements/check-table/define; the types, verdict and verdictStyles are in @contraagent/elements/check-table.

Reference: <cae-check-table>

docs/examples/check-table.ts

// A check table: hand-written fields of a settings file, each checked against
// what it must be. The host judges the values; the table shows the verdicts.
import '@contraagent/elements/check-table/define';
import type { CheckRow } from '@contraagent/elements/check-table';

const rows: CheckRow[] = [
  { name: 'name', expected: 'string', hasValue: true, value: 'release-build', verdict: 'pass', verdictLabel: 'passed' },
  { name: 'retries', expected: 'integer', hasValue: true, value: '3', verdict: 'fail', verdictLabel: 'wrong type', tip: 'Expected integer' },
  { name: 'targets', expected: 'list[str]', hasValue: true, value: ['linux', 'macos', 'windows', 'wasm'], verdict: 'pass', verdictLabel: 'passed' },
  { name: 'cache', expected: 'object', optional: true, hasValue: false, verdict: 'none', verdictLabel: 'absent (optional)' },
  { name: 'colour', expected: 'not in the schema', extra: true, hasValue: true, value: 'blue', verdict: 'warn', verdictLabel: 'extra field' },
];

export function mount(host: HTMLElement): void {
  const table = document.createElement('cae-check-table');
  table.rows = rows;
  table.strings = { name: 'Field', actual: 'In the file' };
  host.replaceChildren(table);
}

Rows

A row is a CheckRow. The host judges each value; the table shows the verdict: pass (✓ and its word), fail (✕ and its word, in the failed tone), warn (its word, in the attention tone) or none (its word, muted, or an empty cell without one). The marks are hidden from screen readers, which read the word.

src/checks/types.ts

export interface CheckRow {
  /** What is checked: a field's name. */
  name: string;
  /** What it must be: a type, in code; with `extra`, a phrase. */
  expected: string;
  /** It may be absent: "optional" follows `expected`. */
  optional?: boolean;
  /** Not one of the expected names: `expected` is a phrase, not code. */
  extra?: boolean;
  /** The value was found (`value`, possibly undefined or null); else "—". */
  hasValue: boolean;
  value?: unknown;
  verdict: Verdict;
  /** The verdict in words; '' with `none` for an empty cell. */
  verdictLabel: string;
  /** The verdict's tooltip. */
  tip?: string;
}

A value is shown in one line: a string quoted and cut, a list’s length and its first items, an object’s first keys. A row with extra names a value that is not expected: its expected is a phrase, not code. Without showValues, the table shows only the names and what each must be.

Verdicts elsewhere

verdict(v, label, tip) draws a verdict as the table does, for a host that shows one outside a table; add verdictStyles to the host’s styles.

Look

The table is as wide as its content, so each verdict sits next to the value it judges; a long value wraps. The parts are table, row and verdict. The words are strings (Strings): the headers, optional, and the summaries of a list (items) and an object.