@contraagent/elements 0.1.0 → 0.3.0

package/src/markdown/highlight.ts

@@ -1,94 +1,2 @@
-// Syntax highlighting: a small tokenizer for what plugins and contracts contain
-// (Python, JSON), no library. Returns escaped HTML: every token is escaped
-// before it is wrapped, so no input can inject markup.
-import { esc } from '../core/format.js';
-
-const PY_KW = new Set(
-  'and as assert async await break class continue def del elif else except finally for from global if import in is lambda nonlocal not or pass raise return try while with yield'.split(
-    ' ',
-  ),
-);
-const PY_CONST = new Set(['None', 'True', 'False', 'self', 'cls']);
-const PY_BUILTIN = new Set(
-  'str int float bool list dict set tuple bytes object type len range print isinstance super Optional Literal Any Union Path'.split(' '),
-);
-const PY_TOKEN = new RegExp(
-  [
-    '(#[^\\n]*)', // 1 comment
-    '((?:[rRbBfFuU]{0,2})(?:"""[\\s\\S]*?"""|\'\'\'[\\s\\S]*?\'\'\'))', // 2 triple-quoted string (docstrings)
-    '((?:[rRbBfFuU]{0,2})(?:"(?:[^"\\\\\\n]|\\\\.)*"|\'(?:[^\'\\\\\\n]|\\\\.)*\'))', // 3 string
-    '(@[A-Za-z_][\\w.]*)', // 4 decorator
-    '(\\b\\d[\\d_]*(?:\\.\\d+)?(?:[eE][+-]?\\d+)?\\b)', // 5 number
-    '([A-Za-z_]\\w*)', // 6 name
-  ].join('|'),
-  'g',
-);
-
-export function hlPython(src: string): string {
-  let out = '';
-  let last = 0;
-  let prevWord = '';
-  PY_TOKEN.lastIndex = 0;
-  for (let m = PY_TOKEN.exec(src); m; m = PY_TOKEN.exec(src)) {
-    out += esc(src.slice(last, m.index));
-    last = PY_TOKEN.lastIndex;
-    const [tok, com, tri, str, dec, num, name] = m;
-    if (com) out += `<span class="hl-c">${esc(tok)}</span>`;
-    else if (tri) out += `<span class="hl-s hl-doc">${esc(tok)}</span>`;
-    else if (str) out += `<span class="hl-s">${esc(tok)}</span>`;
-    else if (dec) out += `<span class="hl-d">${esc(tok)}</span>`;
-    else if (num) out += `<span class="hl-n">${esc(tok)}</span>`;
-    else if (name) {
-      const cls = PY_KW.has(name)
-        ? 'hl-k'
-        : PY_CONST.has(name)
-          ? 'hl-k hl-const'
-          : prevWord === 'class'
-            ? 'hl-cls'
-            : prevWord === 'def'
-              ? 'hl-f'
-              : PY_BUILTIN.has(name)
-                ? 'hl-b'
-                : /^[A-Z]\w*$/.test(name) && name.length > 1 && /[a-z]/.test(name)
-                  ? 'hl-t'
-                  : '';
-      out += cls ? `<span class="${cls}">${esc(name)}</span>` : esc(name);
-      prevWord = name;
-      continue;
-    }
-    if (!/^\s*$/.test(tok)) prevWord = '';
-  }
-  return out + esc(src.slice(last));
-}
-
-export function hlJson(src: string): string {
-  const re = /("(?:[^"\\\n]|\\.)*")(\s*:)?|\b(true|false|null)\b|(-?\b\d+(?:\.\d+)?(?:[eE][+-]?\d+)?\b)/g;
-  let out = '';
-  let last = 0;
-  for (let m = re.exec(src); m; m = re.exec(src)) {
-    out += esc(src.slice(last, m.index));
-    last = re.lastIndex;
-    const [, str, colon, kw, num] = m;
-    out += str
-      ? colon
-        ? `<span class="hl-key">${esc(str)}</span>${esc(colon)}`
-        : `<span class="hl-s">${esc(str)}</span>`
-      : kw
-        ? `<span class="hl-k hl-const">${kw}</span>`
-        : `<span class="hl-n">${num ?? ''}</span>`;
-  }
-  return out + esc(src.slice(last));
-}
-
-const LANG_OF: Record<string, 'python' | 'json'> = { py: 'python', python: 'python', json: 'json', jsonc: 'json' };
-
-function langOf(hint: string | null | undefined): 'python' | 'json' | '' {
-  const h = String(hint || '').toLowerCase();
-  return LANG_OF[h.replace(/^.*\./, '')] || LANG_OF[h] || '';
-}
-
-/** Highlighted, escaped HTML. `hint` is a fence language ("python") or a file name ("schema.py"); anything unknown is plain. */
-export function highlight(code: string, hint?: string | null): string {
-  const lang = langOf(hint);
-  return lang === 'python' ? hlPython(code) : lang === 'json' ? hlJson(code) : esc(code);
-}
+// The highlighter of markdown's code blocks: `code/highlight.ts`, by the names of this entry.
+export { highlight, hlJson, hlPython } from '../code/highlight.js';

package/src/styles/prose.ts

@@ -56,4 +56,9 @@ export const prose = css`
   .hl-t { color: var(--code-type); }
   .hl-b { color: var(--code-name); }
   .hl-key { color: var(--code-name); }
+  .hl-tag { color: var(--code-keyword); }
+  .hl-attr { color: var(--code-name); }
+  .hl-meta { color: var(--code-comment); font-weight: 600; }
+  .hl-ins { color: var(--status-done); }
+  .hl-del { color: var(--status-failed); }
 `;

package/src/tree/index.ts

@@ -0,0 +1,3 @@
+// `@contraagent/elements/tree`: items in a tree, folded and opened by the reader;
+// `…/tree/define` registers the element.
+export * from './tree.js';

package/src/tree/tree.ts

@@ -0,0 +1,263 @@
+import { LitElement, css, html, nothing, svg, type PropertyValues, type TemplateResult } from 'lit';
+import { property, state } from 'lit/decorators.js';
+import { emit } from '../core/events.js';
+import { withDefaults } from '../core/strings.js';
+import type { Tone } from '../core/tone.js';
+import { statusChip } from '../primitives/pill.js';
+import { base } from '../styles/index.js';
+
+/** One item of a tree: its name, the items under it, and how it looks. */
+export interface TreeItem {
+  /** Its id, unique in the tree. */
+  id: string;
+  name: string;
+  /** Its icon: a directory for an item with children, a file for one without, unless given. */
+  icon?: 'file' | 'directory' | null;
+  /** A word beside the name, coloured by `tone` (with its mark: ✓ done, ✕ failed, ◌ attention). */
+  badge?: string | null;
+  tone?: Tone | null;
+  /** Its children are shown at first (default: true). */
+  open?: boolean | null;
+  children?: readonly TreeItem[] | null;
+  /** A click or Enter selects it (`cae-select`); default: an item with no children. An item with children that is not selectable opens and closes instead. */
+  selectable?: boolean | null;
+}
+
+export interface TreeStrings {
+  /** What a tree with no items shows. */
+  empty: string;
+}
+
+export const DEFAULT_TREE_STRINGS: Readonly<TreeStrings> = { empty: 'No items' };
+
+/** An item where the tree shows it: its depth (1 at the top), its parent, and its place among its siblings. */
+export interface TreeRow {
+  item: TreeItem;
+  level: number;
+  parent: string | null;
+  index: number;
+  siblings: number;
+}
+
+const hasChildren = (t: TreeItem): boolean => !!t.children?.length;
+const selectable = (t: TreeItem): boolean => t.selectable ?? !hasChildren(t);
+
+/** The items shown, top to bottom: every item whose ancestors are all open (`isOpen`). */
+export function visibleRows(items: readonly TreeItem[], isOpen: (t: TreeItem) => boolean): TreeRow[] {
+  const out: TreeRow[] = [];
+  const walk = (list: readonly TreeItem[], level: number, parent: string | null) =>
+    list.forEach((item, index) => {
+      out.push({ item, level, parent, index, siblings: list.length });
+      if (hasChildren(item) && isOpen(item)) walk(item.children!, level + 1, item.id);
+    });
+  walk(items, 1, null);
+  return out;
+}
+
+/** The ids of the ancestors of item `id`, outermost first; null when no item has that id. */
+export function ancestorsOf(items: readonly TreeItem[], id: string): string[] | null {
+  for (const t of items) {
+    if (t.id === id) return [];
+    const below = t.children ? ancestorsOf(t.children, id) : null;
+    if (below) return [t.id, ...below];
+  }
+  return null;
+}
+
+/** The first item, depth first, that `match` accepts. */
+export function findItem(items: readonly TreeItem[], match: (t: TreeItem) => boolean): TreeItem | null {
+  for (const t of items) {
+    if (match(t)) return t;
+    const below = t.children ? findItem(t.children, match) : null;
+    if (below) return below;
+  }
+  return null;
+}
+
+const FOLDER = svg`<path d="M1.5 3.5h4l1.5 1.5h7.5v8h-13z" fill="none" stroke="currentColor" stroke-width="1.2" stroke-linejoin="round"></path>`;
+const FILE = svg`<path d="M3.5 1.5h6l3 3v10h-9z M9.5 1.5v3h3" fill="none" stroke="currentColor" stroke-width="1.2" stroke-linejoin="round"></path>`;
+
+/**
+ * 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.
+ *
+ * @tagname cae-tree
+ * @fires cae-select - `{id}`: an item was chosen with a click, Enter or Space
+ * @fires cae-toggle - `{id, open}`: the reader opened or closed an item
+ * @csspart tree - the list of items
+ * @csspart item - an item's row
+ * @csspart empty - what it shows with no items
+ */
+export class CaeTree extends LitElement {
+  static override styles = [
+    base,
+    css`
+      :host { display: block; font-size: var(--font-size-md); }
+      .tree { margin: 0; padding: 2px 0; }
+      .row { display: flex; align-items: center; gap: 4px; min-height: 24px; padding: 0 8px 0 calc((var(--level) - 1) * 14px + 4px);
+        border-radius: var(--radius-sm); cursor: pointer; white-space: nowrap; color: var(--text-2); }
+      .row:hover { background: var(--raise); }
+      .row[aria-selected='true'] { background: color-mix(in srgb, var(--accent) 16%, transparent); color: var(--text); box-shadow: inset 2px 0 0 var(--accent); }
+      .row:focus-visible { outline-offset: -2px; }
+      .twist { flex: none; display: inline-grid; place-items: center; width: 16px; height: 16px; color: var(--text-muted); border-radius: var(--radius-sm); }
+      .twist svg { transition: transform 0.12s ease; }
+      [aria-expanded='true'] > .twist svg { transform: rotate(90deg); }
+      .twist:hover { color: var(--text); }
+      .icon { flex: none; width: 16px; height: 16px; color: var(--text-muted); }
+      .name { overflow: hidden; text-overflow: ellipsis; min-width: 0; }
+      .badge { flex: none; margin-left: 6px; font-size: 11px; padding: 0 6px; border-radius: var(--radius-pill); background: var(--raise); color: var(--text-2); }
+      .badge[data-tone] { background: var(--tone-bg); color: var(--tone); }
+      .badge[data-tone='done'] { background: none; color: var(--text-2); }
+      .empty { color: var(--text-muted); font-size: var(--font-size-sm); padding: 4px 8px; }
+      @media (prefers-reduced-motion: reduce) { .twist svg { transition: none; } }
+    `,
+  ];
+
+  @property({ attribute: false }) items: readonly TreeItem[] = [];
+  /** The selected item's id, or null. */
+  @property({ attribute: false }) selected: string | null = null;
+  /** What the tree is named to a screen reader. */
+  @property() label = '';
+  /** The visible words; English by default. */
+  @property({ attribute: false }) strings: Partial<TreeStrings> = {};
+
+  /** The reader's choice of open and closed items, by id, over each item's `open`. */
+  @state() private opened = new Map<string, boolean>();
+  /** The item that holds the tab stop. */
+  @state() private focusId: string | null = null;
+
+  private readonly isOpen = (t: TreeItem): boolean => this.opened.get(t.id) ?? t.open ?? true;
+
+  override willUpdate(changed: PropertyValues<this>): void {
+    if (changed.has('selected') && this.selected) {
+      const up = ancestorsOf(this.items, this.selected);
+      if (up?.some((id) => this.opened.get(id) !== true)) {
+        const next = new Map(this.opened);
+        for (const id of up) next.set(id, true);
+        this.opened = next;
+      }
+    }
+  }
+
+  override updated(changed: PropertyValues<this>): void {
+    if (changed.has('selected') && this.selected && !this.matches(':focus-within')) {
+      this.rowOf(this.selected)?.scrollIntoView?.({ block: 'nearest' });
+    }
+  }
+
+  private rowOf(id: string): HTMLElement | null {
+    return this.renderRoot.querySelector<HTMLElement>(`[data-id="${CSS.escape(id)}"]`);
+  }
+
+  private setOpen(t: TreeItem, open: boolean): void {
+    if (!hasChildren(t) || this.isOpen(t) === open) return;
+    this.opened = new Map(this.opened).set(t.id, open);
+    emit(this, 'cae-toggle', { id: t.id, open });
+  }
+
+  private choose(t: TreeItem): void {
+    this.focusId = t.id;
+    if (selectable(t)) emit(this, 'cae-select', { id: t.id });
+    else this.setOpen(t, !this.isOpen(t));
+  }
+
+  private async moveTo(id: string): Promise<void> {
+    this.focusId = id;
+    await this.updateComplete;
+    this.rowOf(id)?.focus();
+  }
+
+  private onKey(e: KeyboardEvent, rows: readonly TreeRow[], i: number): void {
+    const row = rows[i]!;
+    const t = row.item;
+    let to: TreeRow | undefined;
+    switch (e.key) {
+      case 'ArrowDown':
+        to = rows[i + 1];
+        break;
+      case 'ArrowUp':
+        to = rows[i - 1];
+        break;
+      case 'Home':
+        to = rows[0];
+        break;
+      case 'End':
+        to = rows[rows.length - 1];
+        break;
+      case 'ArrowRight':
+        if (hasChildren(t) && !this.isOpen(t)) this.setOpen(t, true);
+        else if (hasChildren(t)) to = rows[i + 1];
+        break;
+      case 'ArrowLeft':
+        if (hasChildren(t) && this.isOpen(t)) this.setOpen(t, false);
+        else if (row.parent) to = rows.find((r) => r.item.id === row.parent);
+        break;
+      case 'Enter':
+      case ' ':
+        this.choose(t);
+        break;
+      default: {
+        if (e.key.length !== 1 || e.ctrlKey || e.metaKey || e.altKey || !/\S/.test(e.key)) return;
+        const k = e.key.toLowerCase();
+        const order = [...rows.slice(i + 1), ...rows.slice(0, i)];
+        to = order.find((r) => r.item.name.toLowerCase().startsWith(k));
+        if (!to) return;
+      }
+    }
+    e.preventDefault();
+    if (to) void this.moveTo(to.item.id);
+  }
+
+  override render() {
+    if (!this.items.length) return html`<div class="empty" part="empty">${withDefaults(DEFAULT_TREE_STRINGS, this.strings).empty}</div>`;
+    const rows = visibleRows(this.items, this.isOpen);
+    const stop = rows.find((r) => r.item.id === this.focusId) ?? rows.find((r) => r.item.id === this.selected) ?? rows[0];
+    return html`<div class="tree" role="tree" part="tree" aria-label=${this.label || nothing}>
+      ${rows.map((r, i) => this.row(r, i, rows, r === stop))}
+    </div>`;
+  }
+
+  private row(r: TreeRow, i: number, rows: readonly TreeRow[], stop: boolean): TemplateResult {
+    const t = r.item;
+    const parent = hasChildren(t);
+    const open = parent && this.isOpen(t);
+    const directory = (t.icon ?? (parent ? 'directory' : 'file')) === 'directory';
+    return html`<div
+      class="row"
+      part="item"
+      role="treeitem"
+      data-id=${t.id}
+      tabindex=${stop ? 0 : -1}
+      style="--level: ${r.level}"
+      aria-level=${r.level}
+      aria-setsize=${r.siblings}
+      aria-posinset=${r.index + 1}
+      aria-expanded=${parent ? String(open) : nothing}
+      aria-selected=${selectable(t) ? String(t.id === this.selected) : nothing}
+      @click=${() => this.choose(t)}
+      @focus=${() => (this.focusId = t.id)}
+      @keydown=${(e: KeyboardEvent) => this.onKey(e, rows, i)}
+    >
+      <span class="twist" aria-hidden="true" @click=${(e: Event) => {
+        if (!parent) return;
+        e.stopPropagation();
+        this.focusId = t.id;
+        this.setOpen(t, !open);
+      }}>${parent ? html`<svg width="10" height="10" viewBox="0 0 10 10"><path d="M3 1.5 7 5 3 8.5" fill="none" stroke="currentColor" stroke-width="1.5"></path></svg>` : nothing}</span>
+      <svg class="icon" viewBox="0 0 16 16" aria-hidden="true">${directory ? FOLDER : FILE}</svg>
+      <span class="name">${t.name}</span>
+      ${t.badge ? statusChip('badge', { text: t.badge, tone: t.tone ?? 'neutral' }) : nothing}
+    </div>`;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'cae-tree': CaeTree;
+  }
+}