@north-light/crouter 0.3.192 → 0.3.193

package/dist/pages/elements/table.js

@@ -0,0 +1,906 @@
+/**
+ * `<crtr-table>` — a dataset the agent wants the user to pick from.
+ *
+ * Rows and columns are independently selectable, single or multi, because the two questions
+ * an agent asks of a table are "which of these records" and "which of these fields", and they
+ * are not the same question. Row selection wears a real checkbox or radio in a leading cell;
+ * column selection turns the header into a pressed toggle, since a column has no natural row
+ * to hang a checkbox on and the header IS the column.
+ *
+ * Anchored comments use the same one-per-anchor algebra as every other element: a row anchor
+ * in each row's trailing cell, a column anchor beside each header label, and a `whole` anchor
+ * in the trailing header cell for the table itself. Triggers stay invisible until the row is
+ * hovered or focused, or until a comment is actually there.
+ *
+ * Ported from the agent interaction kit's `agent-table.tsx` (northlight `3705fe9e2`), with the
+ * kit's `classic-list-keys` grammar — j/k move, x selects, c comments — reimplemented here
+ * over the shadow root.
+ */
+import { registerElement } from '../register.js';
+import { readSlotConfig, readSlotId } from '../slot-config.js';
+import { artifactData, respond } from '../host.js';
+import { anchorLabel, findComment, setComment } from '../comments.js';
+const COMMENT_BUBBLE = 'M3.25 3.5h9.5A1.75 1.75 0 0 1 14.5 5.25v5A1.75 1.75 0 0 1 12.75 12H7.4l-3.15 2.36A.5.5 0 0 1 3.5 14v-2H3.25A1.75 1.75 0 0 1 1.5 10.25v-5A1.75 1.75 0 0 1 3.25 3.5Z';
+const STYLE = `
+  :host {
+    display: block;
+  }
+
+  [part="container"] {
+    position: relative;
+    background: var(--crtr-color-background);
+    border: 1px solid var(--crtr-color-border);
+    border-radius: var(--crtr-radius-medium);
+    box-shadow: var(--crtr-shadow);
+    overflow: hidden;
+  }
+
+  [part="container"]:focus-visible {
+    outline: 2px solid var(--crtr-color-focus);
+    outline-offset: 2px;
+  }
+
+  [part="table"] {
+    width: 100%;
+    border-collapse: collapse;
+    font: inherit;
+    color: var(--crtr-color-text);
+  }
+
+  [part="caption"] {
+    caption-side: top;
+    padding: var(--crtr-space-3) var(--crtr-space-3) var(--crtr-space-2);
+    text-align: left;
+    color: var(--crtr-color-text-muted);
+  }
+
+  th {
+    padding: var(--crtr-space-2) var(--crtr-space-3);
+    text-align: left;
+    font-weight: 600;
+    color: var(--crtr-color-text-muted);
+    border-bottom: 1px solid var(--crtr-color-border);
+    white-space: nowrap;
+  }
+
+  th[data-align="right"] {
+    text-align: right;
+  }
+
+  [part="header-cell-inner"] {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--crtr-space-1);
+  }
+
+  th[data-align="right"] [part="header-cell-inner"] {
+    flex-direction: row-reverse;
+  }
+
+  [part="column-toggle"] {
+    font: inherit;
+    font-weight: 600;
+    color: inherit;
+    background: transparent;
+    border: 1px solid transparent;
+    border-radius: var(--crtr-radius-small);
+    padding: var(--crtr-space-1) var(--crtr-space-2);
+    margin: calc(var(--crtr-space-1) * -1) calc(var(--crtr-space-2) * -1);
+    cursor: pointer;
+  }
+
+  [part="column-toggle"]:hover {
+    background: var(--crtr-color-surface-hover);
+  }
+
+  [part="column-toggle"][aria-pressed="true"] {
+    color: var(--crtr-color-text);
+    background: color-mix(in srgb, var(--crtr-color-accent) 12%, transparent);
+    border-color: color-mix(in srgb, var(--crtr-color-accent) 40%, transparent);
+  }
+
+  [part="column-toggle"]:focus-visible,
+  [part="comment-trigger"]:focus-visible,
+  [part="row-control"]:focus-visible,
+  [part="select-all"]:focus-visible {
+    outline: 2px solid var(--crtr-color-focus);
+    outline-offset: 1px;
+  }
+
+  [part="row"] {
+    border-bottom: 1px solid color-mix(in srgb, var(--crtr-color-border) 60%, transparent);
+  }
+
+  [part="row"]:last-child {
+    border-bottom: none;
+  }
+
+  [part="row"]:hover,
+  [part="row"][data-active="true"] {
+    background: var(--crtr-color-surface-hover);
+  }
+
+  [part="row"][data-state="selected"],
+  [part="row"][data-state="selected"]:hover {
+    background: color-mix(in srgb, var(--crtr-color-accent) 8%, transparent);
+  }
+
+  [part="row"]:focus-visible {
+    outline: 2px solid var(--crtr-color-focus);
+    outline-offset: -2px;
+  }
+
+  td {
+    padding: var(--crtr-space-2) var(--crtr-space-3);
+    vertical-align: middle;
+  }
+
+  td[data-align="right"] {
+    text-align: right;
+    font-variant-numeric: tabular-nums;
+  }
+
+  td[data-mono="true"] {
+    font-family: var(--crtr-font-mono);
+    font-size: 0.8125em;
+  }
+
+  [data-column-selected="true"] {
+    background: color-mix(in srgb, var(--crtr-color-accent) 6%, transparent);
+  }
+
+  [part="select-cell"],
+  [part="select-head"] {
+    width: 1px;
+    padding-right: 0;
+  }
+
+  [part="comment-cell"],
+  [part="comment-head"] {
+    width: 1px;
+    text-align: right;
+    padding-left: 0;
+  }
+
+  [part="row-control"],
+  [part="select-all"] {
+    accent-color: var(--crtr-color-accent);
+    margin: 0;
+    cursor: pointer;
+  }
+
+  [part="comment-trigger"] {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 1.5rem;
+    height: 1.5rem;
+    padding: 0;
+    color: var(--crtr-color-text-muted);
+    background: transparent;
+    border: none;
+    border-radius: var(--crtr-radius-small);
+    cursor: pointer;
+    opacity: 0;
+    transition: opacity 120ms ease;
+  }
+
+  [part="comment-trigger"] svg {
+    width: 0.875rem;
+    height: 0.875rem;
+  }
+
+  [part="comment-trigger"][data-has-comment="true"] {
+    color: var(--crtr-color-accent);
+    opacity: 1;
+  }
+
+  [part="comment-trigger"]:hover {
+    background: var(--crtr-color-surface-hover);
+  }
+
+  tr:hover [part="comment-trigger"],
+  tr:focus-within [part="comment-trigger"],
+  tr[data-active="true"] [part="comment-trigger"],
+  [part="comment-trigger"]:focus-visible,
+  [part="comment-trigger"][data-open="true"] {
+    opacity: 1;
+  }
+
+  [part="comment-editor"] {
+    position: absolute;
+    z-index: 2;
+    width: min(20rem, calc(100% - var(--crtr-space-4)));
+    display: grid;
+    gap: var(--crtr-space-2);
+    padding: var(--crtr-space-3);
+    background: var(--crtr-color-surface);
+    border: 1px solid var(--crtr-color-border);
+    border-radius: var(--crtr-radius-medium);
+    box-shadow: var(--crtr-shadow);
+  }
+
+  [part="comment-editor"][hidden] {
+    display: none;
+  }
+
+  [part="comment-target"] {
+    margin: 0;
+    font-family: var(--crtr-font-mono);
+    font-size: 0.75em;
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+    color: var(--crtr-color-text-muted);
+  }
+
+  [part="comment-input"] {
+    font: inherit;
+    color: var(--crtr-color-text);
+    background: var(--crtr-color-background);
+    border: 1px solid var(--crtr-color-border);
+    border-radius: var(--crtr-radius-small);
+    padding: var(--crtr-space-2);
+    min-height: 4rem;
+    resize: vertical;
+  }
+
+  [part="comment-input"]:focus-visible {
+    outline: 2px solid var(--crtr-color-focus);
+    outline-offset: -1px;
+  }
+
+  [part="comment-actions"] {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--crtr-space-2);
+  }
+
+  [part="comment-hint"] {
+    font-family: var(--crtr-font-mono);
+    font-size: 0.75em;
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+    color: var(--crtr-color-text-muted);
+  }
+
+  [part="comment-cancel"],
+  [part="comment-save"] {
+    font: inherit;
+    font-size: 0.875em;
+    padding: var(--crtr-space-1) var(--crtr-space-2);
+    border-radius: var(--crtr-radius-small);
+    border: 1px solid var(--crtr-color-border);
+    cursor: pointer;
+  }
+
+  [part="comment-cancel"] {
+    color: var(--crtr-color-text-muted);
+    background: transparent;
+  }
+
+  [part="comment-save"] {
+    color: var(--crtr-color-accent-contrast);
+    background: var(--crtr-color-accent);
+    border-color: var(--crtr-color-accent);
+  }
+
+  [part="comment-cancel"]:focus-visible,
+  [part="comment-save"]:focus-visible {
+    outline: 2px solid var(--crtr-color-focus);
+    outline-offset: 1px;
+  }
+
+  [part="status"],
+  [part="unavailable"] {
+    padding: var(--crtr-space-3);
+    color: var(--crtr-color-text-muted);
+    background: var(--crtr-color-surface);
+    border: 1px solid var(--crtr-color-border);
+    border-radius: var(--crtr-radius-medium);
+    box-shadow: var(--crtr-shadow);
+  }
+
+  [part="reason"] {
+    color: var(--crtr-color-text);
+    font-family: var(--crtr-font-mono);
+  }
+
+  [part="empty"] {
+    padding: var(--crtr-space-3);
+    color: var(--crtr-color-text-muted);
+    text-align: center;
+  }
+`;
+/** A cell value the schema allows, as the string a table shows. */
+function cellText(value) {
+    if (value === undefined || value === null)
+        return '';
+    return typeof value === 'string' ? value : String(value);
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * The rows inside whatever the host handed back for a `source`. Accepted shapes are the same
+ * `{ id, cells }` rows an inline config carries, either as a bare array or under a `rows` key;
+ * anything else is a named unavailable state rather than a guess at the author's intent.
+ */
+function readSourceRows(data) {
+    const raw = Array.isArray(data) ? data : isPlainObject(data) && Array.isArray(data.rows) ? data.rows : undefined;
+    if (raw === undefined)
+        return { status: 'invalid', reason: 'source data is not a list of rows' };
+    const rows = [];
+    for (let index = 0; index < raw.length; index += 1) {
+        const row = raw[index];
+        if (!isPlainObject(row) || typeof row.id !== 'string' || row.id === '' || !isPlainObject(row.cells)) {
+            return { status: 'invalid', reason: `source row #${index} is not { id, cells }` };
+        }
+        const cells = {};
+        for (const [key, value] of Object.entries(row.cells)) {
+            if (value === undefined)
+                continue;
+            if (value !== null && typeof value !== 'string' && typeof value !== 'number' && typeof value !== 'boolean') {
+                return { status: 'invalid', reason: `source row "${row.id}" cell "${key}" is not a string, number, boolean or null` };
+            }
+            cells[key] = value;
+        }
+        rows.push({ id: row.id, cells });
+    }
+    return { status: 'ok', rows };
+}
+function commentIcon() {
+    const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+    svg.setAttribute('viewBox', '0 0 16 16');
+    svg.setAttribute('aria-hidden', 'true');
+    svg.setAttribute('focusable', 'false');
+    const path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+    path.setAttribute('d', COMMENT_BUBBLE);
+    path.setAttribute('fill', 'none');
+    path.setAttribute('stroke', 'currentColor');
+    path.setAttribute('stroke-width', '1.25');
+    path.setAttribute('stroke-linejoin', 'round');
+    svg.append(path);
+    return svg;
+}
+function isTextEntry(target) {
+    if (!(target instanceof HTMLElement))
+        return false;
+    return target.closest('input[type="text"], textarea, [contenteditable="true"]') !== null;
+}
+class CrtrTableElement extends HTMLElement {
+    #root;
+    #slotId;
+    #config;
+    #rows = [];
+    #selectedRowIds = [];
+    #selectedColumnIds = [];
+    #comments = [];
+    #activeRowId = null;
+    #editorAnchor = null;
+    #editorTrigger;
+    #connected = false;
+    #container;
+    #editor;
+    #editorTarget;
+    #editorInput;
+    #editorHint;
+    #selectAll;
+    #rowParts = new Map();
+    #columnParts = new Map();
+    #wholeComment;
+    constructor() {
+        super();
+        this.#root = this.attachShadow({ mode: 'open' });
+    }
+    connectedCallback() {
+        this.#connected = true;
+        const read = readSlotConfig(this);
+        if (read.status !== 'ok') {
+            this.#renderUnavailable(read.reason);
+            return;
+        }
+        const config = read.config;
+        if (!Array.isArray(config.columns) || config.columns.length === 0) {
+            this.#renderUnavailable('table config has no columns');
+            return;
+        }
+        if (config.rows !== undefined && config.source !== undefined) {
+            this.#renderUnavailable('table rows and source are mutually exclusive');
+            return;
+        }
+        this.#config = config;
+        this.#slotId = readSlotId(this);
+        if (config.source !== undefined) {
+            this.#renderStatus('Loading table data…');
+            void this.#loadSource(config.source);
+            return;
+        }
+        if (!Array.isArray(config.rows)) {
+            this.#renderUnavailable('table config has neither rows nor source');
+            return;
+        }
+        this.#rows = config.rows;
+        this.#renderTable();
+    }
+    disconnectedCallback() {
+        this.#connected = false;
+    }
+    async #loadSource(source) {
+        const result = await artifactData(source);
+        if (!this.#connected)
+            return;
+        if (result.status !== 'ok') {
+            this.#renderUnavailable(`table source "${source}" is ${result.status}: ${result.reason}`);
+            return;
+        }
+        const rows = readSourceRows(result.data);
+        if (rows.status !== 'ok') {
+            this.#renderUnavailable(`table source "${source}": ${rows.reason}`);
+            return;
+        }
+        this.#rows = rows.rows;
+        this.#renderTable();
+    }
+    // ── the response ───────────────────────────────────────────────────────────────────────
+    get #rowSelect() {
+        return this.#config?.rowSelect ?? 'none';
+    }
+    get #columnSelect() {
+        return this.#config?.columnSelect ?? 'none';
+    }
+    #response() {
+        return {
+            selectedRowIds: [...this.#selectedRowIds],
+            selectedColumnIds: [...this.#selectedColumnIds],
+            comments: [...this.#comments],
+        };
+    }
+    /** Every user change hands the host this slot's complete current response, never a delta. */
+    #commit() {
+        this.#syncState();
+        if (this.#slotId !== undefined)
+            respond(this.#slotId, this.#response());
+    }
+    /** Selection stays in the order the agent authored, not the order the user clicked. */
+    #orderRows(ids) {
+        return this.#rows.map((row) => row.id).filter((id) => ids.includes(id));
+    }
+    #orderColumns(ids) {
+        return (this.#config?.columns ?? []).map((column) => column.id).filter((id) => ids.includes(id));
+    }
+    #setRowSelected(rowId, selected) {
+        const mode = this.#rowSelect;
+        if (mode === 'none')
+            return;
+        if (mode === 'single') {
+            this.#selectedRowIds = selected ? [rowId] : [];
+        }
+        else {
+            this.#selectedRowIds = this.#orderRows(selected ? [...this.#selectedRowIds, rowId] : this.#selectedRowIds.filter((id) => id !== rowId));
+        }
+        this.#commit();
+    }
+    #toggleRow(rowId) {
+        if (this.#rowSelect === 'single') {
+            this.#setRowSelected(rowId, true);
+            return;
+        }
+        this.#setRowSelected(rowId, !this.#selectedRowIds.includes(rowId));
+    }
+    #setColumnSelected(columnId, selected) {
+        const mode = this.#columnSelect;
+        if (mode === 'none')
+            return;
+        if (mode === 'single') {
+            this.#selectedColumnIds = selected ? [columnId] : [];
+        }
+        else {
+            this.#selectedColumnIds = this.#orderColumns(selected ? [...this.#selectedColumnIds, columnId] : this.#selectedColumnIds.filter((id) => id !== columnId));
+        }
+        this.#commit();
+    }
+    #toggleColumn(columnId) {
+        this.#setColumnSelected(columnId, !this.#selectedColumnIds.includes(columnId));
+    }
+    #setAllRows(selected) {
+        if (this.#rowSelect !== 'multi')
+            return;
+        this.#selectedRowIds = selected ? this.#rows.map((row) => row.id) : [];
+        this.#commit();
+    }
+    // ── rendering ──────────────────────────────────────────────────────────────────────────
+    #reset() {
+        this.#root.replaceChildren();
+        this.#rowParts.clear();
+        this.#columnParts.clear();
+        this.#container = undefined;
+        this.#editor = undefined;
+        this.#editorTrigger = undefined;
+        this.#editorAnchor = null;
+        this.#selectAll = undefined;
+        this.#wholeComment = undefined;
+        const style = document.createElement('style');
+        style.textContent = STYLE;
+        this.#root.append(style);
+    }
+    #renderUnavailable(reason) {
+        this.#reset();
+        const box = document.createElement('div');
+        box.part.add('unavailable');
+        box.setAttribute('role', 'status');
+        const detail = document.createElement('span');
+        detail.part.add('reason');
+        detail.textContent = reason;
+        box.append('Table unavailable: ', detail);
+        this.#root.append(box);
+    }
+    #renderStatus(text) {
+        this.#reset();
+        const box = document.createElement('div');
+        box.part.add('status');
+        box.setAttribute('role', 'status');
+        box.textContent = text;
+        this.#root.append(box);
+    }
+    #renderTable() {
+        const config = this.#config;
+        if (config === undefined)
+            return;
+        this.#reset();
+        const container = document.createElement('div');
+        container.part.add('container');
+        container.tabIndex = 0;
+        container.addEventListener('keydown', (event) => this.#onKeyDown(event));
+        container.addEventListener('focus', () => {
+            if (this.#activeRowId === null && this.#rows.length > 0) {
+                this.#activeRowId = this.#rows[0].id;
+                this.#syncState();
+            }
+        });
+        this.#container = container;
+        const table = document.createElement('table');
+        table.part.add('table');
+        if (config.caption !== undefined && config.caption !== '') {
+            const caption = document.createElement('caption');
+            caption.part.add('caption');
+            caption.textContent = config.caption;
+            table.append(caption);
+        }
+        table.append(this.#buildHead(config), this.#buildBody(config));
+        container.append(table);
+        if (this.#rows.length === 0) {
+            const empty = document.createElement('div');
+            empty.part.add('empty');
+            empty.textContent = 'No rows.';
+            container.append(empty);
+        }
+        container.append(this.#buildEditor());
+        this.#root.append(container);
+        this.#syncState();
+    }
+    #buildHead(config) {
+        const head = document.createElement('thead');
+        const tr = document.createElement('tr');
+        tr.part.add('header-row');
+        if (this.#rowSelect !== 'none') {
+            const th = document.createElement('th');
+            th.part.add('select-head');
+            th.setAttribute('scope', 'col');
+            if (this.#rowSelect === 'multi') {
+                const all = document.createElement('input');
+                all.type = 'checkbox';
+                all.part.add('select-all');
+                all.setAttribute('aria-label', 'Select every row');
+                all.addEventListener('change', () => this.#setAllRows(all.checked));
+                this.#selectAll = all;
+                th.append(all);
+            }
+            tr.append(th);
+        }
+        for (const column of config.columns) {
+            const th = document.createElement('th');
+            th.part.add('column-header');
+            th.setAttribute('scope', 'col');
+            th.dataset.columnHeader = column.id;
+            if (column.align === 'right')
+                th.dataset.align = 'right';
+            const inner = document.createElement('span');
+            inner.part.add('header-cell-inner');
+            let toggle;
+            if (this.#columnSelect === 'none') {
+                const label = document.createElement('span');
+                label.textContent = column.label;
+                inner.append(label);
+            }
+            else {
+                toggle = document.createElement('button');
+                toggle.type = 'button';
+                toggle.part.add('column-toggle');
+                toggle.dataset.columnToggle = column.id;
+                toggle.setAttribute('aria-pressed', 'false');
+                toggle.setAttribute('aria-label', `Select the ${column.label} column`);
+                toggle.textContent = column.label;
+                toggle.addEventListener('click', () => this.#toggleColumn(column.id));
+                inner.append(toggle);
+            }
+            const comment = this.#buildCommentTrigger({ kind: 'column', columnId: column.id }, `the ${column.label} column`);
+            inner.append(comment);
+            th.append(inner);
+            tr.append(th);
+            this.#columnParts.set(column.id, { toggle, comment, cells: [], head: th });
+        }
+        const trailing = document.createElement('th');
+        trailing.part.add('comment-head');
+        trailing.setAttribute('scope', 'col');
+        this.#wholeComment = this.#buildCommentTrigger({ kind: 'whole' }, 'this table');
+        trailing.append(this.#wholeComment);
+        tr.append(trailing);
+        head.append(tr);
+        return head;
+    }
+    #buildBody(config) {
+        const body = document.createElement('tbody');
+        for (const row of this.#rows) {
+            const tr = document.createElement('tr');
+            tr.part.add('row');
+            tr.dataset.rowId = row.id;
+            tr.tabIndex = -1;
+            tr.addEventListener('mouseenter', () => this.#setActiveRow(row.id));
+            tr.addEventListener('focusin', () => this.#setActiveRow(row.id));
+            let control;
+            if (this.#rowSelect !== 'none') {
+                const td = document.createElement('td');
+                td.part.add('select-cell');
+                const input = document.createElement('input');
+                input.type = this.#rowSelect === 'single' ? 'radio' : 'checkbox';
+                input.part.add('row-control');
+                if (this.#rowSelect === 'single')
+                    input.name = `${this.#slotId ?? 'crtr-table'}-row`;
+                input.value = row.id;
+                input.setAttribute('aria-label', `Select row ${row.id}`);
+                input.addEventListener('change', () => this.#setRowSelected(row.id, input.checked));
+                control = input;
+                td.append(input);
+                tr.append(td);
+            }
+            for (const column of config.columns) {
+                const td = document.createElement('td');
+                td.part.add('cell');
+                td.dataset.columnId = column.id;
+                if (column.align === 'right')
+                    td.dataset.align = 'right';
+                if (column.mono === true)
+                    td.dataset.mono = 'true';
+                td.textContent = cellText(row.cells[column.id]);
+                tr.append(td);
+                this.#columnParts.get(column.id)?.cells.push(td);
+            }
+            const commentCell = document.createElement('td');
+            commentCell.part.add('comment-cell');
+            const comment = this.#buildCommentTrigger({ kind: 'row', rowId: row.id }, `row ${row.id}`);
+            commentCell.append(comment);
+            tr.append(commentCell);
+            body.append(tr);
+            this.#rowParts.set(row.id, { tr, ...(control === undefined ? {} : { control }), comment });
+        }
+        return body;
+    }
+    #buildCommentTrigger(anchor, target) {
+        const button = document.createElement('button');
+        button.type = 'button';
+        button.part.add('comment-trigger');
+        button.setAttribute('aria-label', `Comment on ${target}`);
+        button.dataset.commentTarget = target;
+        button.append(commentIcon());
+        button.addEventListener('click', () => this.#openEditor(anchor, button));
+        return button;
+    }
+    #buildEditor() {
+        const editor = document.createElement('div');
+        editor.part.add('comment-editor');
+        editor.hidden = true;
+        editor.setAttribute('role', 'dialog');
+        editor.setAttribute('aria-label', 'Comment');
+        const target = document.createElement('p');
+        target.part.add('comment-target');
+        editor.append(target);
+        const input = document.createElement('textarea');
+        input.part.add('comment-input');
+        input.placeholder = 'What should the agent know about this?';
+        input.addEventListener('keydown', (event) => {
+            if (event.key === 'Enter' && (event.metaKey || event.ctrlKey)) {
+                event.preventDefault();
+                this.#saveComment();
+            }
+            else if (event.key === 'Escape') {
+                event.preventDefault();
+                this.#closeEditor();
+            }
+        });
+        editor.append(input);
+        const actions = document.createElement('div');
+        actions.part.add('comment-actions');
+        const hint = document.createElement('span');
+        hint.part.add('comment-hint');
+        actions.append(hint);
+        const buttons = document.createElement('span');
+        const cancel = document.createElement('button');
+        cancel.type = 'button';
+        cancel.part.add('comment-cancel');
+        cancel.textContent = 'Cancel';
+        cancel.addEventListener('click', () => this.#closeEditor());
+        const save = document.createElement('button');
+        save.type = 'button';
+        save.part.add('comment-save');
+        save.textContent = 'Save';
+        save.addEventListener('click', () => this.#saveComment());
+        buttons.append(cancel, ' ', save);
+        actions.append(buttons);
+        editor.append(actions);
+        this.#editor = editor;
+        this.#editorTarget = target;
+        this.#editorInput = input;
+        this.#editorHint = hint;
+        return editor;
+    }
+    // ── comments ───────────────────────────────────────────────────────────────────────────
+    #openEditor(anchor, trigger) {
+        const editor = this.#editor;
+        const container = this.#container;
+        if (editor === undefined || container === undefined)
+            return;
+        this.#editorAnchor = anchor;
+        this.#editorTrigger = trigger;
+        const existing = findComment(this.#comments, anchor);
+        // The box is seeded from the saved comment every time it opens, so an abandoned edit
+        // never leaks into the next one.
+        if (this.#editorInput !== undefined)
+            this.#editorInput.value = existing?.text ?? '';
+        if (this.#editorTarget !== undefined) {
+            this.#editorTarget.textContent = `Comment on ${trigger.dataset.commentTarget ?? anchorLabel(anchor)}`;
+        }
+        if (this.#editorHint !== undefined)
+            this.#editorHint.textContent = existing === undefined ? '⌘↵ to save' : 'empty to delete';
+        const bounds = container.getBoundingClientRect();
+        const rect = trigger.getBoundingClientRect();
+        editor.hidden = false;
+        editor.style.top = `${Math.max(0, rect.bottom - bounds.top + 4)}px`;
+        editor.style.right = `${Math.max(0, bounds.right - rect.right)}px`;
+        this.#syncState();
+        this.#editorInput?.focus();
+    }
+    /**
+     * Closing hands focus back to the trigger that opened the editor. Without it the keyboard
+     * grammar dies on save: the focused Save button is inside the panel being hidden, so focus
+     * falls out of the element entirely and j/k/x/c stop arriving.
+     */
+    #closeEditor() {
+        const trigger = this.#editorTrigger;
+        this.#editorAnchor = null;
+        this.#editorTrigger = undefined;
+        if (this.#editor !== undefined)
+            this.#editor.hidden = true;
+        this.#syncState();
+        trigger?.focus();
+    }
+    #saveComment() {
+        const anchor = this.#editorAnchor;
+        if (anchor === null)
+            return;
+        this.#comments = setComment(this.#comments, anchor, this.#editorInput?.value ?? '');
+        this.#closeEditor();
+        this.#commit();
+    }
+    // ── interaction ────────────────────────────────────────────────────────────────────────
+    #setActiveRow(rowId) {
+        if (this.#activeRowId === rowId)
+            return;
+        this.#activeRowId = rowId;
+        this.#syncState();
+    }
+    #focusRow(rowId) {
+        const parts = this.#rowParts.get(rowId);
+        (parts?.control ?? parts?.tr)?.focus();
+    }
+    /**
+     * The kit's classic list grammar: j/k move (wrapping) and carry DOM focus with them, x
+     * selects, c comments. A key pressed on a column toggle acts on that column instead, since
+     * the header IS the column. Modified keys and anything typed in the comment box pass through.
+     */
+    #onKeyDown(event) {
+        if (event.metaKey || event.ctrlKey || event.altKey)
+            return;
+        const target = event.composedPath()[0] ?? event.target;
+        if (isTextEntry(target))
+            return;
+        const key = event.key.toLowerCase();
+        if (key !== 'j' && key !== 'k' && key !== 'x' && key !== 'c')
+            return;
+        // Anything focused inside a header cell — the toggle or that column's comment trigger —
+        // acts on the column, because the header IS the column.
+        const columnId = target instanceof HTMLElement ? target.closest('[data-column-header]')?.dataset.columnHeader : undefined;
+        if (columnId !== undefined && (key === 'x' || key === 'c')) {
+            event.preventDefault();
+            if (key === 'x')
+                this.#toggleColumn(columnId);
+            else {
+                const parts = this.#columnParts.get(columnId);
+                if (parts !== undefined)
+                    this.#openEditor({ kind: 'column', columnId }, parts.comment);
+            }
+            return;
+        }
+        const ids = this.#rows.map((row) => row.id);
+        if (ids.length === 0)
+            return;
+        const currentId = this.#activeRowId ?? this.#selectedRowIds[this.#selectedRowIds.length - 1] ?? ids[0];
+        if (key === 'j' || key === 'k') {
+            event.preventDefault();
+            const index = Math.max(0, ids.indexOf(currentId));
+            const nextId = ids[(index + (key === 'j' ? 1 : -1) + ids.length) % ids.length];
+            this.#setActiveRow(nextId);
+            this.#focusRow(nextId);
+            return;
+        }
+        event.preventDefault();
+        if (key === 'x') {
+            this.#toggleRow(currentId);
+            return;
+        }
+        const parts = this.#rowParts.get(currentId);
+        if (parts !== undefined)
+            this.#openEditor({ kind: 'row', rowId: currentId }, parts.comment);
+    }
+    // ── state → DOM ────────────────────────────────────────────────────────────────────────
+    #syncCommentTrigger(button, anchor) {
+        const comment = findComment(this.#comments, anchor);
+        const target = button.dataset.commentTarget ?? anchorLabel(anchor);
+        button.dataset.hasComment = comment === undefined ? 'false' : 'true';
+        button.setAttribute('aria-label', comment === undefined ? `Comment on ${target}` : `Edit comment on ${target}`);
+        button.title = comment?.text ?? '';
+        const path = button.querySelector('path');
+        path?.setAttribute('fill', comment === undefined ? 'none' : 'currentColor');
+        button.dataset.open = this.#isEditorAnchor(anchor) ? 'true' : 'false';
+    }
+    #isEditorAnchor(anchor) {
+        const current = this.#editorAnchor;
+        if (current === null || current.kind !== anchor.kind)
+            return false;
+        if (current.kind === 'row' && anchor.kind === 'row')
+            return current.rowId === anchor.rowId;
+        if (current.kind === 'column' && anchor.kind === 'column')
+            return current.columnId === anchor.columnId;
+        return current.kind === 'whole';
+    }
+    #syncState() {
+        for (const [rowId, parts] of this.#rowParts) {
+            const selected = this.#selectedRowIds.includes(rowId);
+            if (selected)
+                parts.tr.dataset.state = 'selected';
+            else
+                delete parts.tr.dataset.state;
+            parts.tr.dataset.active = this.#activeRowId === rowId ? 'true' : 'false';
+            parts.tr.setAttribute('aria-selected', selected ? 'true' : 'false');
+            if (parts.control !== undefined)
+                parts.control.checked = selected;
+            this.#syncCommentTrigger(parts.comment, { kind: 'row', rowId });
+        }
+        for (const [columnId, parts] of this.#columnParts) {
+            const selected = this.#selectedColumnIds.includes(columnId);
+            parts.toggle?.setAttribute('aria-pressed', selected ? 'true' : 'false');
+            parts.head.dataset.columnSelected = selected ? 'true' : 'false';
+            for (const cell of parts.cells)
+                cell.dataset.columnSelected = selected ? 'true' : 'false';
+            this.#syncCommentTrigger(parts.comment, { kind: 'column', columnId });
+        }
+        if (this.#wholeComment !== undefined)
+            this.#syncCommentTrigger(this.#wholeComment, { kind: 'whole' });
+        if (this.#selectAll !== undefined) {
+            const all = this.#rows.length > 0 && this.#selectedRowIds.length === this.#rows.length;
+            this.#selectAll.checked = all;
+            this.#selectAll.indeterminate = this.#selectedRowIds.length > 0 && !all;
+        }
+    }
+}
+registerElement('crtr-table', CrtrTableElement);