@contraagent/elements 0.0.0-stage → 0.1.0

package/docs/theming.md

@@ -0,0 +1,147 @@
+# Theming
+
+Each element keeps its styles in its own shadow root, so your page's CSS cannot
+break it and its CSS cannot leak into your page. What reaches it are the
+`--ca-*` custom properties:
+
+1. **A built-in theme**, picked by `data-ca-theme="<name>"` on any ancestor
+   (or on the element), sets every colour property on that element. The
+   elements inside it read them, and so does your page's own CSS.
+2. **A `--ca-*` property of your own** wins over the theme when it is set on
+   the element that carries `data-ca-theme` or on an element inside it. A theme
+   of your own is a set of them.
+
+With neither, an element shows contraagent Dark.
+
+![The CI pipeline's page in the contraagent Dark theme](images/theming-dark.webp)
+
+## The built-in themes
+
+| `data-ca-theme` | Name | Source |
+|---|---|---|
+| `contraagent-dark` | contraagent Dark (the default) | this package |
+| `contraagent-light` | contraagent Light | this package: the hues of contraagent Dark, set for a light page |
+| `github-dark` | GitHub Dark | [GitHub Primer primitives](https://github.com/primer/primitives), dark (MIT, GitHub Inc.) |
+| `github-light` | GitHub Light | Primer primitives, light (MIT, GitHub Inc.) |
+| `one-dark` | One Dark | [Atom One Dark](https://github.com/atom/atom/tree/master/packages/one-dark-syntax) (MIT, GitHub Inc.) |
+| `nord` | Nord | [Nord](https://www.nordtheme.com) (MIT, Arctic Ice Studio and Sven Greb) |
+| `high-contrast` | High contrast | Primer primitives, dark high contrast (MIT, GitHub Inc.) |
+
+An editor theme takes its surfaces, borders and text from the editor's own
+colours, its accent from the palette's accent, the statuses from its red,
+yellow, green and cyan, and the code colours from its syntax colours. Where a
+palette colour reads under 4.5:1 on the theme's surfaces and tints, its lightness
+is raised (or lowered, on a light theme) as little as needed and its hue kept;
+`src/themes/data.ts` lists every value. High contrast keeps text at 7:1 or
+more on every surface, has stronger borders and a wider focus ring, and its
+status colours stay apart under protanopia, deuteranopia and tritanopia.
+
+## Choosing a theme
+
+Set `data-ca-theme` on any ancestor. The rules that apply it are a stylesheet
+that a document (or a shadow root) adopts once: add it to the page's document,
+and to a shadow root of your own that holds the elements and sets
+`data-ca-theme` inside it. No import adopts it; `<ca-monitor>` of
+`@contraagent/ui` adopts it for its document when it connects.
+
+```ts
+import { adoptThemes } from '@contraagent/elements/themes';
+
+adoptThemes(document);
+adoptThemes(myShadowRoot);
+```
+
+The themes are also plain data: `THEMES`, `resolveTheme` and `themeRules` in
+`@contraagent/elements/themes`. `themeRules` writes the rules for a selector of
+your own, and `themeBootScript` is a script for a page's `<head>` that sets the
+reader's theme before the first paint, as the monitor's page does.
+`preferredTheme` and `rememberTheme` keep the reader's choice in this browser;
+`system` follows the system's colour scheme (contraagent Dark or contraagent
+Light).
+
+## Use the theme in your own page
+
+The theme's properties have the same names in your page as in the elements, so
+your page and the elements show one theme. Here `<html data-ca-theme="nord">`
+picks it, and the page's CSS reads it:
+
+::code{file="examples/page.css"}
+
+A theme sets each property that has a value per theme: the colours,
+`--ca-tint`, `--ca-focus-width` and `--ca-color-scheme`. Its selector has no specificity,
+so any rule of your page that sets a `--ca-*` property wins over it:
+
+::code{file="../src/themes/data.ts" from="/** A theme's selector on a page" to="/**"}
+
+The tints (`--ca-accent-bg`, `--ca-status-*-bg`, `--ca-agent-bg`), the type
+scale and the corners have one default for every theme; that default exists only
+inside the elements, unless your page sets the property.
+
+## What a colour means
+
+A colour means one thing, on every screen and in every theme:
+
+- **Neutral by default.** Text, totals, cost, tokens, time and every count that
+  is not a count of a problem are in the text colours. A number is emphasised by
+  its size and weight, not by a colour of its own.
+- **A status colour marks a status, and only where it applies.** A count of a
+  problem (failed attempts, tasks not started) takes its status colour above 0;
+  at 0 it is neutral, with its words ("All attempts done"). A total is never
+  coloured by its worst part.
+- **A status also has a shape and a word**, so it reads without colour: ✓ done,
+  ✕ failed, ◌ not started, a round mark for done and a square one for failed.
+- **One rule set draws every status.** An element that shows a status carries
+  `data-tone`, its tone (`failed`, `attention`, `done`, `running`, `muted`; none
+  for `neutral`), which picks its `--ca-status-*` colour and tint, and
+  `data-mark` for its mark. The primitives set both
+  ([Primitives](primitives.md)).
+- **One accent** for links and the selected tab or item; the focus ring has
+  its own colour and width.
+- **Identity colours are small cues** (an agent task's icon and edge, the token
+  bars, the timeline's bars): none of them is a status hue.
+
+| Properties | Meaning |
+|---|---|
+| `--ca-backdrop`, `--ca-bg`, `--ca-card`, `--ca-panel`, `--ca-panel2`, `--ca-raise`, `--ca-well`, `--ca-track`, `--ca-line`, `--ca-line2`, `--ca-shadow` | the page, surfaces, borders and shadows |
+| `--ca-text`, `--ca-text-secondary`, `--ca-text-muted` | text, from the main text to labels and units |
+| `--ca-accent`, `--ca-accent-bg` | what can be clicked or is selected |
+| `--ca-focus`, `--ca-focus-width` | the focus ring |
+| `--ca-selection` | selected text |
+| `--ca-status-failed` | failed: a task, an attempt, a check |
+| `--ca-status-attention` | not failed, needs a look: not started, a usage limit near |
+| `--ca-status-done` | done or passed: in marks and small chips only |
+| `--ca-status-running` | running, live |
+| `--ca-status-muted` | skipped, waiting, not run |
+| `--ca-status-*-bg`, `--ca-tint` | the tint behind a status pill or chip: by default the status colour at `--ca-tint` |
+| `--ca-agent`, `--ca-agent-bg` | identity: an agent task |
+| `--ca-meter` | a bar that measures, not judges: time, usage, progress |
+| `--ca-tok-input`, `--ca-tok-cache-read`, `--ca-tok-cache-write`, `--ca-tok-output` | the kinds of tokens in a bar |
+| `--ca-series-1` to `--ca-series-6` | the series of a chart, in a fixed order; never a status, and each series also named in words |
+| `--ca-code-*` | syntax colours in code, prompts and JSON |
+| `--ca-color-scheme` | `light` or `dark`: native controls and scrollbars |
+| `--ca-sans`, `--ca-mono` | the fonts |
+| `--ca-font-size-xs` to `--ca-font-size-2xl` | the type scale |
+| `--ca-radius-sm`, `--ca-radius-md`, `--ca-radius-lg`, `--ca-radius-pill` | the corners |
+
+Every property, its meaning and its value in each built-in theme are in the
+site's theme reference, generated from `src/themes/tokens-list.ts` (`TOKENS`),
+`src/themes/token-meanings.ts` (`TOKEN_MEANINGS`)
+and `src/themes/data.ts` (`THEMES`).
+
+## Type and corners
+
+The type and radius scale is the same in every theme: no theme sets it, and
+each step has a default. A `--ca-*` property on an ancestor changes a step for
+every element under it.
+
+::code{file="../src/themes/tokens-list.ts" from="{ name: 'font-size-xs'" to="];"}
+
+## A theme of your own
+
+Set the `--ca-*` properties on an element, here with a class: on the element
+that carries `data-ca-theme`, or on one inside it (on `<body>` under
+`<html data-ca-theme>`). Build it
+the way the built-in themes are built: each text colour keeps a contrast of at
+least 4.5:1 (WCAG AA) on every surface and on every status tint.
+
+::code{file="examples/theme.css"}

package/docs/tiles.md

@@ -0,0 +1,40 @@
+# 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`.
+
+![Four stat tiles: jobs, failed jobs with a link, build time, and queued](images/tiles.webp)
+
+<!-- not on the site -->
+Live on this topic's page of the documentation site (`pnpm run docs` in `web/`).
+
+::code{file="examples/tiles.ts"}
+
+## 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](primitives.md)); a fact with a tone is in its status
+colour, and an empty line keeps its place.
+
+::code{file="../src/tiles/types.ts" from="/** A figure as a tile"}
+
+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`.

package/docs/transcript.md

@@ -0,0 +1,73 @@
+# Transcript
+
+`<cae-transcript>` shows a conversation with an agent: chat bubbles for the
+prompts, the answers and the model's reasoning, lines of the agent's own log,
+and a card per tool call that opens on its command and output. A web search
+lists the pages it returned as links; a page read shows its URL. Register it
+with `@contraagent/elements/transcript/define`; the types are in
+`@contraagent/elements/transcript`.
+
+![A transcript of two sessions: an API request sent again, a web search with 2 results, a log line, and the assistant's answer](images/transcript.webp)
+
+<!-- not on the site -->
+Live on this topic's page of the documentation site (`pnpm run docs` in `web/`).
+
+::code{file="examples/transcript.ts"}
+
+## Sections and items
+
+The conversation comes in sections, one per session with the agent. Above two
+sections, a picker shows one at a time; each section names itself (`title`),
+can add short facts after its name (a model) and a mark of how it ended
+(`verdict`: ✓ with the tone `done`, ✕ otherwise). A section's head shows its
+`tags` (who ran it) and its `details`: folded texts, code (a command line) or
+prose (a prompt). A `footer` after the items says how the section ended, with
+a list (errors) or a note.
+
+::code{file="../src/transcript/types.ts" from="export interface TranscriptSection {" to="/** Where the reader was in a transcript. */"}
+
+An item is a prompt, a message or reasoning (markdown), an event (a glyph, a
+title and a detail), a notice, or a tool card:
+
+::code{file="../src/transcript/types.ts" from="/** One tool call:" to="/** A labelled value in a section's head (who ran it). */"}
+
+## Following and reading
+
+`shown` picks a section (0-based); null follows the latest. While the reader
+is at the bottom, new content scrolls into view. Once they scroll up, it stays
+where they are, and a button counts what arrived below: `count` is how much
+the transcript holds (by default its sections and items), so a host that
+counts events sets it. A section that starts while the reader is scrolled up
+in the latest one keeps the one they read on screen. `live` shows the agent
+working, and a tool call with no result as running; without it, such a call
+was interrupted.
+
+A host that loads a transcript in pages sets `loading` until the first page
+has arrived, and `earlier` to the number of lines before it that are not
+loaded: a button then asks for them with `cae-load-earlier`, and the next
+`sections` it gets is the content from further back, which keeps the reader's
+place. For another transcript, give it a new element.
+
+`memory` keeps what the reader opened and where they were: `isOpen` and
+`setOpen` for the tool cards, `scroll` and `setScroll` for the position, which
+is restored once the content has arrived. Without it, both last as long as the
+element. `reveal(id)` opens a tool card and scrolls it into view once its
+section is shown; it returns that section's index for the host to show.
+
+## Events
+
+- `cae-section-change` with `{index}`: the reader picked a section (null: the
+  latest). The host sets `shown`.
+- `cae-section-shown` with `{index}`: the section on screen changed (-1: none),
+  also when a new section keeps the one being read.
+- `cae-load-earlier`: the reader asked for the content before `earlier`.
+
+## Look and words
+
+Markdown is turned into HTML by `markdown` (`md` of
+`@contraagent/elements/markdown` escapes the text); without it, answers and
+reasoning show as plain text. `renderDetail` draws an open prose detail. The
+parts are `picker`, `section`, `tag`, `bubble`, `notice`, `tool`, `tool-body`
+and `verdict`; `tagChips` and `tagStyles` draw tags elsewhere in the same
+look. The words are `strings` ([Strings](strings.md)): the picker's name and
+tooltip, the bubbles' heads, the tool cards' statuses, the counts.

package/docs/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  // The examples are documentation: they compile against the package as it is.
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "paths": {
+      "@contraagent/elements": ["../src/index.ts"],
+      "@contraagent/elements/segmented/define": ["../src/define/segmented.ts"],
+      "@contraagent/elements/data-table": ["../src/table/index.ts"],
+      "@contraagent/elements/data-table/define": ["../src/define/data-table.ts"],
+      "@contraagent/elements/tiles": ["../src/tiles/index.ts"],
+      "@contraagent/elements/tiles/define": ["../src/define/tiles.ts"],
+      "@contraagent/elements/lanes": ["../src/lanes/index.ts"],
+      "@contraagent/elements/lanes/define": ["../src/define/lanes.ts"],
+      "@contraagent/elements/check-table": ["../src/checks/index.ts"],
+      "@contraagent/elements/check-table/define": ["../src/define/check-table.ts"]
+    }
+  },
+  "include": ["examples/**/*.ts"]
+}

package/package.json

@@ -1,6 +1,163 @@
 {
   "name": "@contraagent/elements",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Generic web components (Lit) and their parts: design tokens, themes, status pills, legends, a segmented control, a data table, a layered graph, a mark matrix, stat tiles, time lanes, charts (columns, lines, a heatmap, horizontal bars), a check table, a transcript, a JSON tree, markdown and counters. No contraagent data, no localization library",
+  "license": "MIT",
+  "keywords": [
+    "web-components",
+    "lit",
+    "custom-elements",
+    "charts",
+    "data-table",
+    "design-tokens"
+  ],
+  "homepage": "https://t-tani.github.io/contraagent/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/t-tani/contraagent.git",
+    "directory": "web/packages/elements"
+  },
+  "bugs": {
+    "url": "https://github.com/t-tani/contraagent/issues"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./primitives": {
+      "types": "./dist/primitives/index.d.ts",
+      "default": "./dist/primitives/index.js"
+    },
+    "./styles": {
+      "types": "./dist/styles/index.d.ts",
+      "default": "./dist/styles/index.js"
+    },
+    "./themes": {
+      "types": "./dist/themes/index.d.ts",
+      "default": "./dist/themes/index.js"
+    },
+    "./json-tree": {
+      "types": "./dist/json/index.d.ts",
+      "default": "./dist/json/index.js"
+    },
+    "./markdown": {
+      "types": "./dist/markdown/index.d.ts",
+      "default": "./dist/markdown/index.js"
+    },
+    "./count": {
+      "types": "./dist/count/index.d.ts",
+      "default": "./dist/count/index.js"
+    },
+    "./data-table": {
+      "types": "./dist/table/index.d.ts",
+      "default": "./dist/table/index.js"
+    },
+    "./graph": {
+      "types": "./dist/graph/index.d.ts",
+      "default": "./dist/graph/index.js"
+    },
+    "./matrix": {
+      "types": "./dist/matrix/index.d.ts",
+      "default": "./dist/matrix/index.js"
+    },
+    "./tiles": {
+      "types": "./dist/tiles/index.d.ts",
+      "default": "./dist/tiles/index.js"
+    },
+    "./lanes": {
+      "types": "./dist/lanes/index.d.ts",
+      "default": "./dist/lanes/index.js"
+    },
+    "./charts": {
+      "types": "./dist/charts/index.d.ts",
+      "default": "./dist/charts/index.js"
+    },
+    "./check-table": {
+      "types": "./dist/checks/index.d.ts",
+      "default": "./dist/checks/index.js"
+    },
+    "./transcript": {
+      "types": "./dist/transcript/index.d.ts",
+      "default": "./dist/transcript/index.js"
+    },
+    "./define": {
+      "types": "./dist/define/all.d.ts",
+      "default": "./dist/define/all.js"
+    },
+    "./json-tree/define": {
+      "types": "./dist/define/json-tree.d.ts",
+      "default": "./dist/define/json-tree.js"
+    },
+    "./markdown/define": {
+      "types": "./dist/define/markdown.d.ts",
+      "default": "./dist/define/markdown.js"
+    },
+    "./count/define": {
+      "types": "./dist/define/count.d.ts",
+      "default": "./dist/define/count.js"
+    },
+    "./segmented/define": {
+      "types": "./dist/define/segmented.d.ts",
+      "default": "./dist/define/segmented.js"
+    },
+    "./data-table/define": {
+      "types": "./dist/define/data-table.d.ts",
+      "default": "./dist/define/data-table.js"
+    },
+    "./graph/define": {
+      "types": "./dist/define/graph.d.ts",
+      "default": "./dist/define/graph.js"
+    },
+    "./matrix/define": {
+      "types": "./dist/define/matrix.d.ts",
+      "default": "./dist/define/matrix.js"
+    },
+    "./tiles/define": {
+      "types": "./dist/define/tiles.d.ts",
+      "default": "./dist/define/tiles.js"
+    },
+    "./lanes/define": {
+      "types": "./dist/define/lanes.d.ts",
+      "default": "./dist/define/lanes.js"
+    },
+    "./charts/define": {
+      "types": "./dist/define/charts.d.ts",
+      "default": "./dist/define/charts.js"
+    },
+    "./check-table/define": {
+      "types": "./dist/define/check-table.d.ts",
+      "default": "./dist/define/check-table.js"
+    },
+    "./transcript/define": {
+      "types": "./dist/define/transcript.d.ts",
+      "default": "./dist/define/transcript.js"
+    },
+    "./custom-elements.json": "./custom-elements.json"
+  },
+  "customElements": "custom-elements.json",
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/__snapshots__",
+    "docs",
+    "!docs/images",
+    "custom-elements.json"
+  ],
+  "sideEffects": [
+    "./dist/define/*.js"
+  ],
+  "peerDependencies": {
+    "lit": "^3.3.3"
+  },
+  "devDependencies": {
+    "@custom-elements-manifest/analyzer": "^0.11.0",
+    "lit": "^3.3.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && cem analyze --litelement --globs 'src/*/{segmented,data-table,layered-graph,mark-matrix,stat-tiles,lanes,column-chart,line-chart,heatmap,bar-chart,check-table,transcript,json-tree,cae-markdown,count,elapsed}.ts'",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p docs"
+  }
+}

package/src/charts/bar-chart.ts

@@ -0,0 +1,74 @@
+import { css, html, nothing, type TemplateResult } from 'lit';
+import { property } from 'lit/decorators.js';
+import { toneAttr } from '../core/tone.js';
+import type { LegendItem } from '../primitives/legend.js';
+import { ChartElement } from './base.js';
+import type { ChartBar } from './types.js';
+
+/**
+ * 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.
+ *
+ * @tagname cae-bar-chart
+ * @csspart plot - the bars
+ * @csspart table - the table of its values
+ * @csspart switch - the button between the two
+ * @csspart empty - what it shows with no values
+ */
+export class CaeBarChart extends ChartElement {
+  static override styles = [
+    ...ChartElement.styles,
+    css`
+      .bars { display: grid; grid-template-columns: minmax(80px, max-content) minmax(0, 1fr) max-content; gap: 6px 12px; align-items: center;
+        font-size: var(--font-size-sm); }
+      .bars .r { display: contents; }
+      .bars .l { color: var(--text-2); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; max-width: 34ch; }
+      .bars .track { display: block; height: 12px; }
+      .bars .bar { display: block; height: 100%; min-width: 2px; border-radius: 1px 4px 4px 1px; background: var(--series-1); }
+      .bars .bar[data-tone] { background: var(--tone); }
+      .bars .v { color: var(--text-2); font-variant-numeric: tabular-nums; text-align: right; }
+    `,
+  ];
+
+  @property({ attribute: false }) bars: readonly ChartBar[] = [];
+
+  protected hasValues(): boolean {
+    return this.bars.length > 0;
+  }
+
+  protected legendItems(): LegendItem[] {
+    return [];
+  }
+
+  protected itemCount(): number {
+    return 0;
+  }
+
+  protected plot(): TemplateResult {
+    const top = Math.max(0, ...this.bars.map((b) => b.value));
+    return html`<div class="bars" role="list" aria-label=${this.label || nothing}>
+      ${this.bars.map(
+        (b) => html`<div class="r" role="listitem" aria-label="${b.label} | ${this.format(b.value)}">
+          <span class="l" aria-hidden="true" title=${b.label}>${b.label}</span>
+          <span class="track" aria-hidden="true"><span class="bar" data-tone=${toneAttr(b.tone)}
+            style="width: ${top > 0 ? (100 * Math.max(0, b.value)) / top : 0}%"></span></span>
+          <span class="v" aria-hidden="true">${this.format(b.value)}</span></div>`,
+      )}
+    </div>`;
+  }
+
+  protected table(): TemplateResult {
+    return html`<table aria-label=${this.label || nothing}>
+      <tbody>${this.bars.map((b) => html`<tr><th scope="row">${b.label}</th><td>${this.format(b.value)}</td></tr>`)}</tbody>
+    </table>`;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'cae-bar-chart': CaeBarChart;
+  }
+}