Elements of @contraagent/elements

Generated from the custom-elements.json of @contraagent/elements: 18 elements.

• <cae-bar-chart>
• <cae-check-table>
• <cae-code>
• <cae-column-chart>
• <cae-count>
• <cae-data-table>
• <cae-elapsed>
• <cae-heatmap>
• <cae-json-tree>
• <cae-lanes>
• <cae-layered-graph>
• <cae-line-chart>
• <cae-mark-matrix>
• <cae-markdown>
• <cae-segmented>
• <cae-stat-tiles>
• <cae-transcript>
• <cae-tree>

<cae-bar-chart>

Horizontal bars, one per label, in the order given (a funnel's stages, a ranking): each its label, a bar as long as its value against the longest, and the value in words. A bar with a tone takes that status colour, the others one colour. Every value is written beside its bar, so no tooltip is needed; the switch shows them as a table.

CaeBarChart | src/charts/bar-chart.ts | Live: Charts

Property	Attribute	Type	Description
bars	none	readonly ChartBar[]

Part	Meaning
plot	the bars
table	the table of its values
switch	the button between the two
empty	what it shows with no values

<cae-check-table>

Named values checked one by one: a row per name, with what it must be, what it is and the verdict. Without showValues, only the names and what each must be (nothing to check them against).

CaeCheckTable | src/checks/check-table.ts | Live: Check table | Live: Element gallery

Property	Attribute	Type	Description
rows	none	readonly CheckRow[]
showValues	showValues	boolean	Show the values and the verdicts.
strings	none	Partial<CheckTableStrings>

Part	Meaning
table	the <table>
row	each row of a name
verdict	each verdict

<cae-code>

A text shown as code: highlighted by its language (LANGUAGES, another name of one or a file name; anything else is plain), each line numbered from start, the lines of highlight marked (a bar beside the number and a tint). Long lines scroll sideways, or wrap with wrap or the reader's switch. A text of more than maxLines lines or maxCharacters characters shows its first lines and says how many it has; the copy button copies the whole text. The line numbers are not part of a selection.

CaeCode | src/code/code.ts | Live: Code | Live: Tree | Live: Element gallery

Property	Attribute	Type	Description
code	code	string	The text.
language	language	string	Its language: a name of LANGUAGES, another name of one, or a file name; anything else is plain text.
start	start	number	The number of the first line.
highlight	none	readonly LineMark[]	The lines marked, in the numbers shown.
path	path	string	The file the text is, named over it.
label	label	string	What the lines are named to a screen reader (default: the path).
wrap	wrap	boolean	Long lines wrap at first; the reader's switch changes it.
maxLines	maxLines	number	The most lines shown.
maxCharacters	maxCharacters	number	The most characters shown, at the end of a line.
strings	none	Partial<CodeStrings>	The visible words; English by default.

Part	Meaning
header	the path, the language and the buttons
code	the lines, which scroll
cut	the note under a text cut short

<cae-column-chart>

Vertical bars, one group per label of x: a bar per series side by side, or with stacked, the series of a label on one bar. Six series take the series colours in their order; past six, the sixth and later are one bar part, "other". A legend names the series when there are two or more. Pointing at a label, or moving to it with the arrow keys, shows its values; the switch shows them all as a table.

CaeColumnChart | src/charts/column-chart.ts | Live: Charts

Property	Attribute	Type	Description
x	none	readonly string[]	A label per group of bars, in order.
series	none	readonly ChartSeries[]
stacked	stacked	boolean	The series of a label on one bar, instead of side by side.

Part	Meaning
plot	the chart
table	the table of its values
switch	the button between the two
empty	what it shows with no values
legend	the legend

<cae-count>

A number that counts up (or down) to its new value when it changes; at once for a reader who asks for reduced motion.

CaeCount | src/count/count.ts

Property	Attribute	Type	Description
value	value	number

<cae-data-table>

A table of rows, one per item, in a real <table>: a header cell per column (scope="col"), the first rowHeader column as the row's header. The rows are one tab stop: the arrow keys, Home and End move between them, and Enter or a click is the row's primary action (cae-activate), or chooses it as the selection when the table is not activatable (cae-select). A sortable header sends cae-sort; the host orders the rows (sortRows) and sets them. Above windowAt rows, only the rows on screen are drawn, and a spacer stands for the others: as high as those rows were when drawn, or, for a row not drawn yet, as the rows drawn are on average. Rows may differ in height. Its look: --cae-data-table-gap (between the columns), --cae-data-table-row-padding, the parts, and cellStyles (styles for what the cells draw, added to the table's own).

CaeDataTable | src/table/data-table.ts | Live: @contraagent/elements | Live: Data table | Live: Element gallery

Property	Attribute	Type	Description
columns	none	readonly DataColumn<R>[]
rows	none	readonly R[]
rowKey	none	(row: R) => string	A row's id: unique among the rows (data-key, the id of the events). By default its id.
rowTone	none	(row: R) => Tone | undefined | undefined	A row's tone (data-tone on the row).
rowAttrs	none	(row: R) => Readonly<Record<string, string>> | undefined	More attributes on a row (data-*), for the host's styles and tests.
activatable	activatable	boolean	A click or Enter on a row is its primary action (cae-activate); otherwise it selects the row (cae-select).
selected	selected	string | null	The id of the selected row.
sort	none	SortState | null	The column the rows are ordered by: shown in its header (aria-sort). The host orders the rows.
windowAt	windowAt	number	Above this many rows, only the rows on screen are drawn.
rowHeight	rowHeight	number	A row's height in px, until rows are measured.
caption	caption	string	The table's caption (its accessible name).
strings	none	Partial<DataTableStrings>
cellStyles	none	readonly CSSResult[]	Styles for what the cells draw, added after the table's own (the rows are tr, the cells th and td).

Event	Detail and meaning
cae-activate	{id}: a row's primary action (a click or Enter, when activatable)
cae-select	{id}: a row chosen as the selection (a click or Enter, when not activatable)
cae-sort	{id, direction}: a sortable header was clicked

Part	Meaning
table	the <table>
caption	the caption
head	the header row's group
header-cell	each header cell
row	each row
row-selected	the selected row
cell	each cell
empty	the cell that stands for no rows

<cae-elapsed>

Time since since (epoch ms), ticking every second: 42s, 3m 05s, 1h 02m.

CaeElapsed | src/count/elapsed.ts

Property	Attribute	Type	Description
since	since	number

<cae-heatmap>

A value per row (y) and column (x), each a cell coloured on one scale, light to dark (values[row][column]; a null cell is left empty, a 0 is the lightest step). The legend gives the scale's lowest and highest value. Pointing at a cell, or moving to it with the arrow keys (up and down by a row), shows its row, column and value; the switch shows them all as a table.

CaeHeatmap | src/charts/heatmap.ts | Live: Charts

Property	Attribute	Type	Description
x	none	readonly string[]
y	none	readonly string[]
values	none	readonly (readonly (number | null)[])[]

Part	Meaning
plot	the chart
table	the table of its values
switch	the button between the two
empty	what it shows with no values
legend	the legend

<cae-json-tree>

Any JSON value as a foldable tree: the first level open, deeper levels folded.

CaeJsonTree | src/json/json-tree.ts

Property	Attribute	Type	Description
value	none	unknown
open	open	number	Levels opened from the start.

Part	Meaning
tree	the tree

<cae-lanes>

Bars on a time axis, a lane per group: each bar as long as it took, the overlapping bars of a lane stacked, a running bar (end null) growing until now and a line at now. A bar's look is its style in barStyles, whose labels are the legend (a row per group). The bars grow in when they are first drawn. Its look: --cae-lanes-label-width (the lanes' labels; 112px, 78px on a narrow screen) and the parts.

CaeLanes | src/lanes/lanes.ts | Live: Lanes | Live: Element gallery

Property	Attribute	Type	Description
lanes	none	readonly Lane[]
barStyles	none	Readonly<Record<string, LaneStyle>>	A look per style key of the bars, in legend order.
range	none	TimeRange | null	The time the axis spans; null fits the bars (fitRange).
live	live	boolean	Draws again every second, so the running bars and the line at now move.
omitted	omitted	number	Bars the host left out, as a note after the legend.
locale	locale	string	The language of the axis' times; by default the page's (lang).
strings	none	Partial<LanesStrings>

Part	Meaning
axis	the times above the lanes
lane	each lane
lane-label	a lane's label
track	the area of a lane's bars
bar	each bar
now	the line at now, while a bar runs
legend	each row of the legend
empty	what the element shows with no bars

<cae-layered-graph>

A layered graph: each node in a layer by the longest path to it, edges bending only in the gaps between layers and never passing a node or a cluster's label; a cluster of nodes in a box (a cluster in a cluster: a box in a box), with, when it cycles, a dotted return from its last layer to its first; an edge from outside the graph from a named stub. Inside each node, one mark per series id, at the same place in every node, so a series can be followed across the graph; a mark is drawn in its state's look (states). Above barAt marks, a node shows a bar of its counts and lists its failed marks. The order depends on the structure only, and keeps a previous order: nodes that appear later are added at the end of their layer. A click selects a mark, a node or a cluster (cae-select); a card beside it (the host's content, in the inspector slot) moves with it as the graph pans and zooms, and hides while it is out of the frame; on a narrow screen it is a sheet under the frame. A double click or Enter is the item's action (cae-activate), or opens its inner view (cae-drill, for an item with drill). Hovering or focusing a mark highlights its series and what related names. The frame first shows the whole graph; Ctrl (or ⌘) and the wheel, or the buttons, zoom; dragging pans; "Show all" goes back. "Graph | Table" changes the view (cae-view-change): the table is a row per node, with its status and the nodes it is joined to. With matrix, the frame shows that <cae-mark-matrix> as the table instead. Size: the element is as wide as its container. Without a height set on it, the frame is as tall as the whole drawing at that width (never scaled up), up to 70% of the window's height or 360 px, whichever is more, and taller when the card needs it; top to bottom, as tall as the drawing. A height set on the element (or given it by a flex or grid container) is shared: the crumbs slot and the row under the frame keep theirs, and the frame takes the rest, the drawing fitted in it. Keyboard: Tab moves between nodes; the arrow keys, Home and End move between a node's marks, and a mark out of the frame is brought into it; Shift and an arrow key move along an edge to an earlier or a later node, on the same series; what has the focus is selected (Tab goes on to the card); Enter is the item's action; Escape clears the selection (and, with none, is left to the host).

CaeLayeredGraph | src/graph/layered-graph.ts | Live: @contraagent/elements | Live: Layered graph | Live: Element gallery

Event	Detail and meaning
cae-select	{id}: a mark, a node, a cluster or a table row was selected; {id: null}: the selection was cleared
cae-activate	{id}: an item's action (a double click or Enter)
cae-drill	{id}: an item's inner view (a double click or Enter on an item with drill, a cluster's chip in the table, a later part of a cluster's path)
cae-toggle	{id, open}: an item's open or close control (toggle) was used
cae-view-change	{view}: "Graph" or "Table" was chosen

Part	Meaning
frame	the frame every view is drawn in
stage	what pans and zooms
node	each node
node-header	a node's first line
node-name	a node's name
mark	each mark
cluster	each cluster
cluster-label	a cluster's header
edge	each edge
stub	each stub
legend	the legend
keys	the line of key hints under the legend
inspector	the selected item's card
table	the node table
row	each row of the node table

<cae-line-chart>

Lines over the labels of x, one per series (a value per label; null breaks the line). Six series take the series colours in their order; any past six are drawn in the colour of "other" and named in the legend and the tooltip. Pointing at a label, or moving to it with the arrow keys, marks it with a rule and shows every series' value there; the switch shows them all as a table.

CaeLineChart | src/charts/line-chart.ts | Live: Charts

Property	Attribute	Type	Description
x	none	readonly string[]
series	none	readonly ChartSeries[]

Part	Meaning
plot	the chart
table	the table of its values
switch	the button between the two
empty	what it shows with no values
legend	the legend

<cae-mark-matrix>

A table of marks: a row per series (its label, then a value), a column per item, the columns under nested groups (a border where a group starts). A mark is drawn in its state's look (states). A click selects a mark (cae-select); a double click or Enter is its action (cae-activate, or cae-drill for a mark with an inner view). The arrow keys, Home, End, Page Up and Page Down move between the marks (Ctrl with Home and End: the first and the last row). The hovered, focused or selected mark's row is highlighted, else highlight's. The host sorts the rows: the sort control sends cae-sort. Above windowAt rows, only the rows in view are drawn.

CaeMarkMatrix | src/matrix/mark-matrix.ts | Live: Mark matrix | Live: Element gallery

Event	Detail and meaning
cae-select	{id}: a mark was clicked or focused
cae-activate	{id}: a mark's action (a double click or Enter)
cae-drill	{id}: a mark's inner view (a double click or Enter on a mark with drill)
cae-sort	{id, direction: 'asc'}: an order was chosen

Part	Meaning
matrix	the <table>
head-cell	each header cell
row-header	each row's label
mark	each mark
sort	the sort control

<cae-markdown>

A markdown text with a rendered/source switch. split may take a leading line off the text, shown apart above the rendered body; the source is the text as it is.

CaeMarkdown | src/markdown/cae-markdown.ts

Property	Attribute	Type	Description
text	text	string
split	none	(text: string) => { head: string; body: string } | undefined	Takes a leading line off the text (head), shown apart above the rendered body.
transform	none	(html: string) => string | undefined	Marks up the rendered (escaped) HTML further, as mdFile's mark.
strings	none	Partial<MarkdownStrings>	The visible words; English by default.

Part	Meaning
toggle	the rendered/source button

<cae-segmented>

One choice among a few, as a row of buttons (a radio group): a click, or the arrow keys, Home and End, choose. The group is one tab stop. Its look: --cae-segmented-radius, --cae-segmented-height, --cae-segmented-padding, --cae-segmented-font-size, --cae-segmented-divider (the line between options) and --cae-segmented-hover (an option's text under the pointer), or the parts.

CaeSegmented | src/primitives/segmented.ts | Live: @contraagent/elements | Live: Primitives | Live: Element gallery

Property	Attribute	Type	Description
options	none	readonly SegmentedOption[]
value	value	string
label	label	string	The group's accessible name.

Event	Detail and meaning
cae-change	{value}: the option the reader chose

Part	Meaning
group	the row of options
option	each option
option-selected	the chosen option

<cae-stat-tiles>

Figures as a grid of tiles: each its label, its value (a number counts up in <cae-count>), the lines of facts under it and a link. A tile whose number changes bumps, unless bump is off or the reader asks for reduced motion. Its look: columns (fewer in a narrow element: 4 below 1100px of its width, 2 below 660px, 1 below 240px), --cae-stat-tiles-gap and the parts.

CaeStatTiles | src/tiles/stat-tiles.ts | Live: @contraagent/elements | Live: Theming | Live: Stat tiles | Live: Element gallery

Property	Attribute	Type	Description
tiles	none	readonly StatTile[]
columns	columns	number	Tiles per row on a wide screen.
bump	bump	boolean	A tile whose number changes bumps.

Event	Detail and meaning
cae-action	{id, action}: a tile's link, by the tile's id and the action's id

Part	Meaning
tiles	the grid
tile	each tile (data-id is its id, data-tone its tone)
label	a tile's label
value	a tile's value
sub	each line under the value
action	a tile's link

<cae-transcript>

A conversation with an agent, in sections (one session each): chat bubbles, reasoning, notices and collapsible tool cards (a web search lists the pages it returned as links). Above two sections, a picker shows one at a time; the latest is followed unless shown names another. While the reader is at the bottom, new content scrolls into view; once they scroll up, it stays, and a button counts what arrived below. A new section that starts while they read the latest one keeps the one they read on screen. Give it a new element (or set loading until the content arrives) for another transcript: what the reader opened and where they were belong to one transcript, kept in memory.

CaeTranscript | src/transcript/transcript.ts | Live: Transcript | Live: Element gallery

Property	Attribute	Type	Description
sections	none	readonly TranscriptSection[]
shown	none	number | null	The section to show, 0-based; null follows the latest.
live	live	boolean	The transcript is still being written: it shows the agent working; a tool call with no result is running, not interrupted.
earlier	earlier	number	Lines before the content that are not loaded: above 0, a button asks for them (cae-load-earlier).
loading	loading	boolean	The content has not arrived yet: the reader's position is restored once it has.
count	none	number | null	How much the transcript holds, for the count of what arrived below; by default its sections and items.
mode	mode	'full' | 'tabs' | 'none'	full; tabs: only the section picker; none: hidden.
memory	none	TranscriptMemory | null	Where the open tool cards and the scroll position are kept.
markdown	none	((text: string) => string) | null	Markdown to safe HTML (the text escaped), for answers and reasoning; without it they show as plain text.
renderDetail	none	((detail: TranscriptDetail) => unknown) | null	Draws an open prose detail (a prompt); by default as markdown.
strings	none	Partial<TranscriptStrings>
shownIndex	none	number	The section on screen, 0-based; -1 with none.

Event	Detail and meaning
cae-section-change	{index}: the reader picked a section (null: the latest)
cae-section-shown	{index}: the section on screen changed (-1: none)
cae-load-earlier	the reader asked for the content before earlier

Part	Meaning
picker	the section picker
section	the section shown
tag	a chip at the head of the section
bubble	a prompt, an answer, reasoning or an event
notice	a line of the agent's log
tool	a tool card
tool-body	an open tool card's body
verdict	the box after the items (footer)

<cae-tree>

Items in a tree, the children of each under it, folded and opened by the reader: files and directories, say. It is one tab stop: Up and Down move between the items shown, Right opens an item (then moves to its first child), Left closes it (or moves to its parent), Home and End go to the first and the last, a letter to the next item of that initial; Enter, Space or a click selects a selectable item (cae-select) and opens or closes any other. The toggle before an item with children opens and closes it (cae-toggle). The ancestors of selected are always open.

CaeTree | src/tree/tree.ts | Live: Tree | Live: Element gallery

Property	Attribute	Type	Description
items	none	readonly TreeItem[]
selected	none	string | null	The selected item's id, or null.
label	label	string	What the tree is named to a screen reader.
strings	none	Partial<TreeStrings>	The visible words; English by default.

Event	Detail and meaning
cae-select	{id}: an item was chosen with a click, Enter or Space
cae-toggle	{id, open}: the reader opened or closed an item

Part	Meaning
tree	the list of items
item	an item's row
empty	what it shows with no items