@north-light/crouter 0.3.197 → 0.3.198

package/dist/pages/elements/table.js

@@ -15,51 +15,106 @@
  * 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.
+ *
+ * ## Styling
+ *
+ * Every styling value below is read through a `--crtr-table-*` component token, so a host
+ * restyles this element without touching crtr — custom properties inherit through the shadow
+ * boundary, which is the whole mechanism. The parts a person can name each own a scope:
+ * `container`, `caption`, `header`, `column-toggle`, `row`, `cell`, `selection` (the row
+ * control and the header's select-all, deliberately one thing), `comment-trigger`,
+ * `comment-editor`, `comment-input`, `comment-button` and its `comment-cancel` /
+ * `comment-save` paint, `notice`, `reason`, `empty`. Where a shared recipe draws the value the
+ * chain is `--crtr-table-<part>-<knob>` over the family's `--crtr-control-*` and then the kit
+ * default; every default stays inline at the rule that spends it, and no token is declared
+ * anywhere, which is what keeps the kit's own look when a host sets nothing.
+ *
+ * Layout and behaviour stay literal: `display`, positioning, the shrink-to-content column
+ * widths, text alignment, and the trigger's reveal-on-hover `opacity` are anatomy rather than
+ * paint, so they are not knobs.
  */
+import { controlStyle, focusRingStyle, writingBoxStyle } from '../controls.js';
 import { registerElement } from '../register.js';
 import { readSlotConfig, readSlotId } from '../slot-config.js';
-import { artifactData, respond, savedIds, savedResponse } from '../host.js';
-import { adoptComments, anchorLabel, findComment, setComment } from '../comments.js';
+import { respond, savedIds, savedResponse } from '../host.js';
+import { adoptComments, anchorLabel, canRecordComments, findComment, setComment } from '../comments.js';
+import { applyReadOnly, isReadOnly } from '../readonly.js';
+import { registerSlotResponse } from '../responses.js';
+/** The gap between a comment trigger and the editor that opens off it. */
+const EDITOR_GAP = 4;
+/**
+ * The motion the table's control-shaped things wear. A column toggle, a comment trigger and
+ * the editor's two buttons are all controls, so their timing chains through the family's
+ * `--crtr-control-transition` before reaching the kit default; a row is not a control, so its
+ * tint animation carries an element token alone.
+ */
+const TOGGLE_MOTION = 'var(--crtr-table-column-toggle-transition, var(--crtr-control-transition, 120ms ease))';
+const ROW_MOTION = 'var(--crtr-table-row-transition, 120ms ease)';
+const TRIGGER_MOTION = 'var(--crtr-table-comment-trigger-transition, var(--crtr-control-transition, 120ms ease))';
+const COMMENT_BUTTON_MOTION = 'var(--crtr-table-comment-button-transition, var(--crtr-control-transition, 120ms ease))';
 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"] {
+  /* The positioning context for the comment editor, and the ONLY one. The editor cannot live
+     inside the container: that box clips to its own rounded corners, so a popover anchored to
+     a row was cut off at the table's edge instead of floating over it. The frame has no paint
+     and no clipping, so the editor overlays whatever the table sits on. */
+  [part="frame"] {
     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);
+  }
+
+  /* Flat: the table sits in the flow of the page. A shadow in this bundle means floating —
+     the comment editor, and nothing else here. */
+  [part="container"] {
+    background: var(--crtr-table-container-fill, var(--crtr-color-background));
+    border: var(--crtr-table-container-border-width, 1px)
+      var(--crtr-table-container-border-style, solid)
+      var(--crtr-table-container-border-color, var(--crtr-color-border));
+    border-radius: var(--crtr-table-container-radius, var(--crtr-radius-medium));
     overflow: hidden;
   }
 
+  /* Inside the border, not outside it: the container is full-bleed, so an outset ring is
+     clipped at the edges of the frame the host gives the page and draws only three sides.
+     That is why this is NOT the shared control focus family — it is a focusable region rather
+     than a control, and it says so with its own inset outline. */
   [part="container"]:focus-visible {
-    outline: 2px solid var(--crtr-color-focus);
-    outline-offset: 2px;
+    outline: var(--crtr-table-container-focus-outline, 2px solid var(--crtr-color-focus));
+    outline-offset: var(--crtr-table-container-focus-outline-offset, -2px);
   }
 
+  /* Typography here is the element's host typography, not a second set of knobs: font stays
+     literal inherit so --crtr-table-font-family, --crtr-table-font-size and
+     --crtr-table-line-height reach the table, and the colour reads the host's own
+     --crtr-table-color, whose fallback is the colour this rule used to hard-code. */
   [part="table"] {
     width: 100%;
     border-collapse: collapse;
     font: inherit;
-    color: var(--crtr-color-text);
+    color: var(--crtr-table-color, var(--crtr-color-text));
   }
 
   [part="caption"] {
     caption-side: top;
-    padding: var(--crtr-space-3) var(--crtr-space-3) var(--crtr-space-2);
+    padding: var(--crtr-table-caption-padding, var(--crtr-space-3) var(--crtr-space-3) var(--crtr-space-2));
     text-align: left;
-    color: var(--crtr-color-text-muted);
+    color: var(--crtr-table-caption-text-color, var(--crtr-color-text-muted));
   }
 
   th {
-    padding: var(--crtr-space-2) var(--crtr-space-3);
+    padding: var(--crtr-table-header-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);
+    font-weight: var(--crtr-table-header-font-weight, 600);
+    color: var(--crtr-table-header-text-color, var(--crtr-color-text-muted));
+    /* A tinted header reads as the table's own chrome; the column-selected tint still wins,
+       on specificity (0-1-0 against this 0-0-1). */
+    background: var(--crtr-table-header-fill, var(--crtr-color-surface));
+    border-bottom: var(--crtr-table-header-border-width, 1px)
+      var(--crtr-table-header-border-style, solid)
+      var(--crtr-table-header-border-color, var(--crtr-color-border));
     white-space: nowrap;
   }
 
@@ -70,7 +125,7 @@ const STYLE = `
   [part="header-cell-inner"] {
     display: inline-flex;
     align-items: center;
-    gap: var(--crtr-space-1);
+    gap: var(--crtr-table-header-gap, var(--crtr-space-1));
   }
 
   th[data-align="right"] [part="header-cell-inner"] {
@@ -78,125 +133,170 @@ const STYLE = `
   }
 
   [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);
+    font: var(--crtr-table-column-toggle-font, inherit);
+    font-weight: var(--crtr-table-column-toggle-font-weight, 600);
+    color: var(--crtr-table-column-toggle-text-color, inherit);
+    background: var(--crtr-table-column-toggle-fill, transparent);
+    border: var(--crtr-table-column-toggle-border-width, 1px)
+      var(--crtr-table-column-toggle-border-style, solid)
+      var(--crtr-table-column-toggle-border-color, transparent);
+    border-radius: var(--crtr-table-column-toggle-radius, var(--crtr-radius-small));
+    padding: var(--crtr-table-column-toggle-padding, var(--crtr-space-1) var(--crtr-space-2));
+    /* The toggle is pulled back out of its own padding so the header label sits where an
+       unselectable one does; a host that repads the toggle repays this too. */
+    margin: var(--crtr-table-column-toggle-margin, calc(var(--crtr-space-1) * -1) calc(var(--crtr-space-2) * -1));
     cursor: pointer;
+    transition: color ${TOGGLE_MOTION}, background-color ${TOGGLE_MOTION}, border-color ${TOGGLE_MOTION};
   }
 
   [part="column-toggle"]:hover {
-    background: var(--crtr-color-surface-hover);
+    background: var(--crtr-table-column-toggle-hover-fill, 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);
+    color: var(--crtr-table-column-toggle-selected-text-color, var(--crtr-color-text));
+    background: var(--crtr-table-column-toggle-selected-fill,
+      color-mix(in srgb, var(--crtr-color-accent) 10%, transparent));
+    border-color: var(--crtr-table-column-toggle-selected-border-color,
+      color-mix(in srgb, var(--crtr-color-accent) 45%, 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="column-toggle"][aria-pressed="true"]:hover {
+    background: var(--crtr-table-column-toggle-selected-hover-fill,
+      color-mix(in srgb, var(--crtr-color-accent) 14%, transparent));
   }
 
+${focusRingStyle({ scope: 'table-column-toggle' }, '[part="column-toggle"]')}
+${focusRingStyle({ scope: 'table-comment-trigger' }, '[part="comment-trigger"]')}
+
   [part="row"] {
-    border-bottom: 1px solid color-mix(in srgb, var(--crtr-color-border) 60%, transparent);
+    border-bottom: var(--crtr-table-row-border-width, 1px)
+      var(--crtr-table-row-border-style, solid)
+      var(--crtr-table-row-border-color, color-mix(in srgb, var(--crtr-color-border) 60%, transparent));
+    transition: background-color ${ROW_MOTION};
   }
 
   [part="row"]:last-child {
-    border-bottom: none;
+    border-bottom: var(--crtr-table-row-last-border, none);
   }
 
   [part="row"]:hover,
   [part="row"][data-active="true"] {
-    background: var(--crtr-color-surface-hover);
+    background: var(--crtr-table-row-hover-fill, 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"][data-state="selected"] {
+    background: var(--crtr-table-row-selected-fill, color-mix(in srgb, var(--crtr-color-accent) 10%, transparent));
   }
 
+  [part="row"][data-state="selected"]:hover,
+  [part="row"][data-state="selected"][data-active="true"] {
+    background: var(--crtr-table-row-selected-hover-fill,
+      color-mix(in srgb, var(--crtr-color-accent) 14%, transparent));
+  }
+
+  /* Inset for the same reason the container's is: a row runs the full width of the table. */
   [part="row"]:focus-visible {
-    outline: 2px solid var(--crtr-color-focus);
-    outline-offset: -2px;
+    outline: var(--crtr-table-row-focus-outline, 2px solid var(--crtr-color-focus));
+    outline-offset: var(--crtr-table-row-focus-outline-offset, -2px);
   }
 
   td {
-    padding: var(--crtr-space-2) var(--crtr-space-3);
+    padding: var(--crtr-table-cell-padding, var(--crtr-space-2) var(--crtr-space-3));
     vertical-align: middle;
   }
 
   td[data-align="right"] {
     text-align: right;
-    font-variant-numeric: tabular-nums;
+    font-variant-numeric: var(--crtr-table-cell-numeric-font-variant, tabular-nums);
   }
 
   td[data-mono="true"] {
-    font-family: var(--crtr-font-mono);
-    font-size: 0.8125em;
+    font-family: var(--crtr-table-cell-mono-font-family, var(--crtr-font-mono));
+    font-size: var(--crtr-table-cell-mono-font-size, 0.8125em);
   }
 
   [data-column-selected="true"] {
-    background: color-mix(in srgb, var(--crtr-color-accent) 6%, transparent);
+    background: var(--crtr-table-column-selected-fill, color-mix(in srgb, var(--crtr-color-accent) 6%, transparent));
   }
 
   [part="select-cell"],
   [part="select-head"] {
     width: 1px;
-    padding-right: 0;
+    padding-right: var(--crtr-table-select-cell-padding-right, 0);
   }
 
   [part="comment-cell"],
   [part="comment-head"] {
     width: 1px;
     text-align: right;
-    padding-left: 0;
+    padding-left: var(--crtr-table-comment-cell-padding-left, 0);
   }
 
-  [part="row-control"],
-  [part="select-all"] {
-    accent-color: var(--crtr-color-accent);
-    margin: 0;
-    cursor: pointer;
+  /* One scope over both selectors: the header's select-all IS the row control, drawn once in
+     the head, and they are meant to be indistinguishable. */
+  ${controlStyle({ scope: 'table-selection' }, '[part="row-control"]', '[part="select-all"]')}
+
+  /* A page that can no longer take an answer keeps its selection legible and drops every
+     affordance that says it could still be changed. */
+  [part="column-toggle"]:disabled {
+    cursor: default;
+  }
+
+  [part="column-toggle"]:disabled:hover {
+    color: var(--crtr-table-column-toggle-disabled-text-color, var(--crtr-color-text-muted));
+    background: var(--crtr-table-column-toggle-disabled-fill, none);
   }
 
+  /* One size knob for a square button, and one for the glyph in it — width and height are one
+     visual decision each. The opacity is the reveal-on-hover mechanic, which is behaviour. */
   [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);
+    width: var(--crtr-table-comment-trigger-size, 1.5em);
+    height: var(--crtr-table-comment-trigger-size, 1.5em);
+    padding: var(--crtr-table-comment-trigger-padding, 0);
+    color: var(--crtr-table-comment-trigger-text-color, var(--crtr-color-text-muted));
+    background: var(--crtr-table-comment-trigger-fill, transparent);
+    border: var(--crtr-table-comment-trigger-border-width, 0)
+      var(--crtr-table-comment-trigger-border-style, none)
+      var(--crtr-table-comment-trigger-border-color, currentColor);
+    border-radius: var(--crtr-table-comment-trigger-radius, var(--crtr-radius-small));
     cursor: pointer;
     opacity: 0;
-    transition: opacity 120ms ease;
+    transition: opacity ${TRIGGER_MOTION}, color ${TRIGGER_MOTION}, background-color ${TRIGGER_MOTION};
   }
 
   [part="comment-trigger"] svg {
-    width: 0.875rem;
-    height: 0.875rem;
+    width: var(--crtr-table-comment-trigger-icon-size, 0.875em);
+    height: var(--crtr-table-comment-trigger-icon-size, 0.875em);
+  }
+
+  /* The path geometry stays the icon's anatomy; its paint is component styling. Attribute
+     selectors preserve the filled-comment state that syncState writes while allowing both
+     appearances to inherit document-root overrides through this shadow root. */
+  [part="comment-trigger"] path {
+    stroke: var(--crtr-table-comment-trigger-icon-stroke, currentColor);
+    stroke-width: var(--crtr-table-comment-trigger-icon-stroke-width, 1.25);
+    stroke-linejoin: var(--crtr-table-comment-trigger-icon-stroke-linejoin, round);
+  }
+
+  [part="comment-trigger"] path[fill="none"] {
+    fill: var(--crtr-table-comment-trigger-icon-fill, none);
+  }
+
+  [part="comment-trigger"] path[fill="currentColor"] {
+    fill: var(--crtr-table-comment-trigger-commented-icon-fill, currentColor);
   }
 
   [part="comment-trigger"][data-has-comment="true"] {
-    color: var(--crtr-color-accent);
+    color: var(--crtr-table-comment-trigger-commented-text-color, var(--crtr-color-accent));
     opacity: 1;
   }
 
   [part="comment-trigger"]:hover {
-    background: var(--crtr-color-surface-hover);
+    background: var(--crtr-table-comment-trigger-hover-fill, var(--crtr-color-surface-hover));
   }
 
   tr:hover [part="comment-trigger"],
@@ -207,108 +307,122 @@ const STYLE = `
     opacity: 1;
   }
 
+  /* A floating panel over the page, not a box in the table's layout: the background token
+     rather than the surface tint, so it reads as lifted off whatever it covers. */
   [part="comment-editor"] {
     position: absolute;
-    z-index: 2;
-    width: min(20rem, calc(100% - var(--crtr-space-4)));
+    z-index: 5;
+    box-sizing: border-box;
+    width: var(--crtr-table-comment-editor-width, min(20em, 100%));
     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);
+    gap: var(--crtr-table-comment-editor-gap, var(--crtr-space-2));
+    padding: var(--crtr-table-comment-editor-padding, var(--crtr-space-3));
+    background: var(--crtr-table-comment-editor-fill, var(--crtr-color-background));
+    border: var(--crtr-table-comment-editor-border-width, 1px)
+      var(--crtr-table-comment-editor-border-style, solid)
+      var(--crtr-table-comment-editor-border-color, var(--crtr-color-border));
+    border-radius: var(--crtr-table-comment-editor-radius, var(--crtr-radius-medium));
+    box-shadow: var(--crtr-table-comment-editor-shadow, var(--crtr-shadow));
   }
 
   [part="comment-editor"][hidden] {
     display: none;
   }
 
+  /* The editor's own prose, in the page's voice. It was set in caps mono, which shouted a
+     row id at someone who had just clicked that row. */
   [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);
+    margin: var(--crtr-table-comment-target-margin, 0);
+    font-size: var(--crtr-table-comment-target-font-size, 0.875em);
+    color: var(--crtr-table-comment-target-text-color, var(--crtr-color-text-muted));
   }
 
+${writingBoxStyle({ scope: 'table-comment-input' }, '[part="comment-input"]')}
   [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;
+    min-height: var(--crtr-table-comment-input-min-height, 4.5em);
     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);
+    gap: var(--crtr-table-comment-actions-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);
+    font-size: var(--crtr-table-comment-hint-font-size, 0.875em);
+    color: var(--crtr-table-comment-hint-text-color, var(--crtr-color-text-muted));
   }
 
+  /* The chrome both editor buttons share reads one scope — a person sees one pair of buttons —
+     and each button's own paint carries its own. */
   [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);
+    font: var(--crtr-table-comment-button-font, inherit);
+    font-size: var(--crtr-table-comment-button-font-size, 0.875em);
+    padding: var(--crtr-table-comment-button-padding, var(--crtr-space-1) var(--crtr-space-2));
+    border-radius: var(--crtr-table-comment-button-radius, var(--crtr-radius-small));
+    border: var(--crtr-table-comment-button-border-width, 1px)
+      var(--crtr-table-comment-button-border-style, solid)
+      var(--crtr-table-comment-button-border-color, var(--crtr-color-border));
     cursor: pointer;
+    transition: color ${COMMENT_BUTTON_MOTION}, background-color ${COMMENT_BUTTON_MOTION},
+      border-color ${COMMENT_BUTTON_MOTION};
   }
 
   [part="comment-cancel"] {
-    color: var(--crtr-color-text-muted);
-    background: transparent;
+    color: var(--crtr-table-comment-cancel-text-color, var(--crtr-color-text-muted));
+    background: var(--crtr-table-comment-cancel-fill, transparent);
+    border-color: var(--crtr-table-comment-cancel-border-color,
+      var(--crtr-table-comment-button-border-color, transparent));
+  }
+
+  [part="comment-cancel"]:hover {
+    color: var(--crtr-table-comment-cancel-hover-text-color, var(--crtr-color-text));
+    background: var(--crtr-table-comment-cancel-hover-fill, var(--crtr-color-surface-hover));
   }
 
   [part="comment-save"] {
-    color: var(--crtr-color-accent-contrast);
-    background: var(--crtr-color-accent);
-    border-color: var(--crtr-color-accent);
+    color: var(--crtr-table-comment-save-text-color, var(--crtr-color-accent-contrast));
+    background: var(--crtr-table-comment-save-fill, var(--crtr-color-accent));
+    border-color: var(--crtr-table-comment-save-border-color,
+      var(--crtr-table-comment-button-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;
+  /* Mixing toward the text colour darkens on a light token set and lightens on a dark one —
+     a brightness filter moves the wrong way on one of them. */
+  [part="comment-save"]:hover {
+    background: var(--crtr-table-comment-save-hover-fill,
+      color-mix(in srgb, var(--crtr-color-accent) 88%, var(--crtr-color-text)));
+    border-color: var(--crtr-table-comment-save-hover-border-color,
+      color-mix(in srgb, var(--crtr-color-accent) 88%, var(--crtr-color-text)));
   }
 
+${focusRingStyle({ scope: 'table-comment-cancel' }, '[part="comment-cancel"]')}
+${focusRingStyle({ scope: 'table-comment-save' }, '[part="comment-save"]')}
+
+  /* One scope over both: a loading line and an unavailable notice are the same box, saying
+     the table has nothing to show yet or ever. */
   [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);
+    padding: var(--crtr-table-notice-padding, var(--crtr-space-3));
+    color: var(--crtr-table-notice-text-color, var(--crtr-color-text-muted));
+    background: var(--crtr-table-notice-fill, var(--crtr-color-surface));
+    border: var(--crtr-table-notice-border-width, 1px)
+      var(--crtr-table-notice-border-style, solid)
+      var(--crtr-table-notice-border-color, var(--crtr-color-border));
+    border-radius: var(--crtr-table-notice-radius, var(--crtr-radius-medium));
   }
 
   [part="reason"] {
-    color: var(--crtr-color-text);
-    font-family: var(--crtr-font-mono);
+    color: var(--crtr-table-reason-text-color, var(--crtr-color-text));
+    font-family: var(--crtr-table-reason-font-family, var(--crtr-font-mono));
   }
 
   [part="empty"] {
-    padding: var(--crtr-space-3);
-    color: var(--crtr-color-text-muted);
+    padding: var(--crtr-table-empty-padding, var(--crtr-space-3));
+    color: var(--crtr-table-empty-text-color, var(--crtr-color-text-muted));
     text-align: center;
   }
 `;
@@ -321,34 +435,6 @@ function cellText(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');
@@ -369,6 +455,8 @@ function isTextEntry(target) {
     return target.closest('input[type="text"], textarea, [contenteditable="true"]') !== null;
 }
 class CrtrTableElement extends HTMLElement {
+    /** The host marks a resolved or canceled page `inert`; that is this element's read-only signal. */
+    static observedAttributes = ['inert'];
     #root;
     #slotId;
     #config;
@@ -379,8 +467,9 @@ class CrtrTableElement extends HTMLElement {
     #activeRowId = null;
     #editorAnchor = null;
     #editorTrigger;
-    #connected = false;
     #container;
+    /** The editor's positioning context — the unclipped wrapper around the container. */
+    #frame;
     #editor;
     #editorTarget;
     #editorInput;
@@ -394,7 +483,6 @@ class CrtrTableElement extends HTMLElement {
         this.#root = this.attachShadow({ mode: 'open' });
     }
     connectedCallback() {
-        this.#connected = true;
         const read = readSlotConfig(this);
         if (read.status !== 'ok') {
             this.#renderUnavailable(read.reason);
@@ -405,49 +493,43 @@ class CrtrTableElement extends HTMLElement {
             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;
+        // Only a selectable table bears a response — the host rejects a map naming a display-only
+        // slot — and the modes are known here before rendering.
+        if (this.#slotId !== undefined && (this.#rowSelect !== 'none' || this.#columnSelect !== 'none')) {
+            registerSlotResponse(this, this.#slotId, () => this.#response());
         }
-        if (!Array.isArray(config.rows)) {
-            this.#renderUnavailable('table config has neither rows nor source');
-            return;
-        }
-        this.#rows = config.rows;
+        this.#rows = config.rows ?? [];
         this.#hydrate();
         this.#renderTable();
     }
-    disconnectedCallback() {
-        this.#connected = false;
+    attributeChangedCallback() {
+        if (this.isConnected)
+            this.#syncReadOnly();
     }
-    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;
+    /**
+     * Repainted after every state sync, because a rebuild replaces the controls. Column
+     * toggles are buttons rather than inputs, so they are named here; the mutation paths
+     * refuse anyway, and this is what makes the refusal visible.
+     */
+    #syncReadOnly() {
+        const readOnly = isReadOnly(this);
+        applyReadOnly(this.#root, readOnly);
+        for (const parts of this.#columnParts.values()) {
+            if (parts.toggle !== undefined)
+                parts.toggle.disabled = readOnly;
         }
-        this.#rows = rows.rows;
-        this.#hydrate();
-        this.#renderTable();
+        // A page can go read-only while the composer is open — the host sets `inert` on a ticket
+        // that resolves under it. A box that can no longer save is closed rather than left there
+        // taking words nothing will keep.
+        if (readOnly && this.#editorAnchor !== null)
+            this.#closeEditor();
     }
     /**
      * Seed local state from the answer the host is already holding, so a reopened page shows
-     * the rows and columns that were picked. It runs once the rows are known — after a `source`
-     * load, not before — because a saved id is only honoured while it still names something on
+     * the rows and columns that were picked. It runs once rows are known because a saved id is
+     * only honoured while it still names something on
      * screen. The select modes are re-imposed for the same reason.
      */
     #hydrate() {
@@ -500,7 +582,7 @@ class CrtrTableElement extends HTMLElement {
     }
     #setRowSelected(rowId, selected) {
         const mode = this.#rowSelect;
-        if (mode === 'none')
+        if (mode === 'none' || isReadOnly(this))
             return;
         if (mode === 'single') {
             this.#selectedRowIds = selected ? [rowId] : [];
@@ -519,7 +601,7 @@ class CrtrTableElement extends HTMLElement {
     }
     #setColumnSelected(columnId, selected) {
         const mode = this.#columnSelect;
-        if (mode === 'none')
+        if (mode === 'none' || isReadOnly(this))
             return;
         if (mode === 'single') {
             this.#selectedColumnIds = selected ? [columnId] : [];
@@ -533,7 +615,7 @@ class CrtrTableElement extends HTMLElement {
         this.#setColumnSelected(columnId, !this.#selectedColumnIds.includes(columnId));
     }
     #setAllRows(selected) {
-        if (this.#rowSelect !== 'multi')
+        if (this.#rowSelect !== 'multi' || isReadOnly(this))
             return;
         this.#selectedRowIds = selected ? this.#rows.map((row) => row.id) : [];
         this.#commit();
@@ -544,6 +626,7 @@ class CrtrTableElement extends HTMLElement {
         this.#rowParts.clear();
         this.#columnParts.clear();
         this.#container = undefined;
+        this.#frame = undefined;
         this.#editor = undefined;
         this.#editorTrigger = undefined;
         this.#editorAnchor = null;
@@ -564,14 +647,6 @@ class CrtrTableElement extends HTMLElement {
         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)
@@ -590,10 +665,10 @@ class CrtrTableElement extends HTMLElement {
         this.#container = container;
         const table = document.createElement('table');
         table.part.add('table');
-        if (config.caption !== undefined && config.caption !== '') {
+        if (config.label !== undefined && config.label !== '') {
             const caption = document.createElement('caption');
             caption.part.add('caption');
-            caption.textContent = config.caption;
+            caption.textContent = config.label;
             table.append(caption);
         }
         table.append(this.#buildHead(config), this.#buildBody(config));
@@ -604,8 +679,13 @@ class CrtrTableElement extends HTMLElement {
             empty.textContent = 'No rows.';
             container.append(empty);
         }
-        container.append(this.#buildEditor());
-        this.#root.append(container);
+        const frame = document.createElement('div');
+        frame.part.add('frame');
+        frame.append(container);
+        if (this.#commentable)
+            frame.append(this.#buildEditor());
+        this.#frame = frame;
+        this.#root.append(frame);
         this.#syncState();
     }
     #buildHead(config) {
@@ -653,18 +733,25 @@ class CrtrTableElement extends HTMLElement {
                 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);
+            const comment = this.#commentable
+                ? this.#buildCommentTrigger({ kind: 'column', columnId: column.id }, `the ${column.label} column`)
+                : undefined;
+            if (comment !== undefined)
+                inner.append(comment);
             th.append(inner);
             tr.append(th);
-            this.#columnParts.set(column.id, { toggle, comment, cells: [], head: th });
+            this.#columnParts.set(column.id, { toggle, ...(comment === undefined ? {} : { comment }), cells: [], head: th });
+        }
+        // The trailing column exists to hold the whole-table trigger; without comments there is
+        // nothing to put in it, and an empty column would just be a stripe of dead width.
+        if (this.#commentable) {
+            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);
         }
-        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;
     }
@@ -705,16 +792,23 @@ class CrtrTableElement extends HTMLElement {
                 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);
+            let comment;
+            if (this.#commentable) {
+                const commentCell = document.createElement('td');
+                commentCell.part.add('comment-cell');
+                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 });
+            this.#rowParts.set(row.id, { tr, ...(control === undefined ? {} : { control }), ...(comment === undefined ? {} : { comment }) });
         }
         return body;
     }
+    /** Whether this table can keep a comment — see `canRecordComments`. */
+    get #commentable() {
+        return canRecordComments(this.#slotId);
+    }
     #buildCommentTrigger(anchor, target) {
         const button = document.createElement('button');
         button.type = 'button';
@@ -776,8 +870,10 @@ class CrtrTableElement extends HTMLElement {
     // ── comments ───────────────────────────────────────────────────────────────────────────
     #openEditor(anchor, trigger) {
         const editor = this.#editor;
-        const container = this.#container;
-        if (editor === undefined || container === undefined)
+        const frame = this.#frame;
+        // A composer opens only where its comment can land: never on a read-only page, whose
+        // textareas are already `readOnly`, so the box would take focus and refuse every keystroke.
+        if (editor === undefined || frame === undefined || !this.#commentable || isReadOnly(this))
             return;
         this.#editorAnchor = anchor;
         this.#editorTrigger = trigger;
@@ -791,11 +887,20 @@ class CrtrTableElement extends HTMLElement {
         }
         if (this.#editorHint !== undefined)
             this.#editorHint.textContent = existing === undefined ? '⌘↵ to save' : 'empty to delete';
-        const bounds = container.getBoundingClientRect();
+        const bounds = frame.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`;
+        // Below the trigger by default; above it when the viewport has no room below and does
+        // have room above. Measured after unhiding, because a hidden panel has no height.
+        editor.style.top = '0px';
+        const height = editor.getBoundingClientRect().height;
+        const below = rect.bottom + EDITOR_GAP + height <= window.innerHeight;
+        const above = rect.top - EDITOR_GAP - height >= 0;
+        editor.style.top =
+            !below && above
+                ? `${rect.top - EDITOR_GAP - height - bounds.top}px`
+                : `${rect.bottom + EDITOR_GAP - bounds.top}px`;
         this.#syncState();
         this.#editorInput?.focus();
     }
@@ -815,7 +920,7 @@ class CrtrTableElement extends HTMLElement {
     }
     #saveComment() {
         const anchor = this.#editorAnchor;
-        if (anchor === null)
+        if (anchor === null || isReadOnly(this))
             return;
         this.#comments = setComment(this.#comments, anchor, this.#editorInput?.value ?? '');
         this.#closeEditor();
@@ -854,9 +959,9 @@ class CrtrTableElement extends HTMLElement {
             if (key === 'x')
                 this.#toggleColumn(columnId);
             else {
-                const parts = this.#columnParts.get(columnId);
-                if (parts !== undefined)
-                    this.#openEditor({ kind: 'column', columnId }, parts.comment);
+                const comment = this.#columnParts.get(columnId)?.comment;
+                if (comment !== undefined)
+                    this.#openEditor({ kind: 'column', columnId }, comment);
             }
             return;
         }
@@ -877,9 +982,9 @@ class CrtrTableElement extends HTMLElement {
             this.#toggleRow(currentId);
             return;
         }
-        const parts = this.#rowParts.get(currentId);
-        if (parts !== undefined)
-            this.#openEditor({ kind: 'row', rowId: currentId }, parts.comment);
+        const comment = this.#rowParts.get(currentId)?.comment;
+        if (comment !== undefined)
+            this.#openEditor({ kind: 'row', rowId: currentId }, comment);
     }
     // ── state → DOM ────────────────────────────────────────────────────────────────────────
     #syncCommentTrigger(button, anchor) {
@@ -913,7 +1018,8 @@ class CrtrTableElement extends HTMLElement {
             parts.tr.setAttribute('aria-selected', selected ? 'true' : 'false');
             if (parts.control !== undefined)
                 parts.control.checked = selected;
-            this.#syncCommentTrigger(parts.comment, { kind: 'row', rowId });
+            if (parts.comment !== undefined)
+                this.#syncCommentTrigger(parts.comment, { kind: 'row', rowId });
         }
         for (const [columnId, parts] of this.#columnParts) {
             const selected = this.#selectedColumnIds.includes(columnId);
@@ -921,7 +1027,8 @@ class CrtrTableElement extends HTMLElement {
             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 (parts.comment !== undefined)
+                this.#syncCommentTrigger(parts.comment, { kind: 'column', columnId });
         }
         if (this.#wholeComment !== undefined)
             this.#syncCommentTrigger(this.#wholeComment, { kind: 'whole' });
@@ -930,6 +1037,7 @@ class CrtrTableElement extends HTMLElement {
             this.#selectAll.checked = all;
             this.#selectAll.indeterminate = this.#selectedRowIds.length > 0 && !all;
         }
+        this.#syncReadOnly();
     }
 }
 registerElement('crtr-table', CrtrTableElement);