@terpjs/react-core 0.10.0 → 0.12.0

package/src/styles.test.ts

@@ -63,6 +63,38 @@ afterEach(() => {
 });
 
 describe("injectTerpStyles", () => {
+  it("adopts a constructable stylesheet when the document supports one", () => {
+    // jsdom exposes the CSSStyleSheet constructor but not document.adoptedStyleSheets,
+    // so the property is defined here to reach the branch a real browser takes. That
+    // branch is the whole point of the injector: an adopted sheet is not governed by
+    // CSP's style-src, so a generated app needs no 'unsafe-inline' — measured in
+    // Chromium, where a <style> element is reported as style-src-elem and dropped.
+    const sheets: CSSStyleSheet[] = [];
+    Object.defineProperty(document, "adoptedStyleSheets", {
+      configurable: true,
+      get: () => sheets,
+      set: (next: CSSStyleSheet[]) => {
+        sheets.length = 0;
+        sheets.push(...next);
+      },
+    });
+    try {
+      injectTerpStyles();
+      expect(sheets.length).toBe(1);
+      // No element: taking the adopted route must not also append a <style>, or the
+      // page would carry the rules twice and still need the CSP keyword.
+      expect(document.getElementById(TERP_STYLES_ID)).toBeNull();
+      expect(sheets[0]?.cssRules.length ?? 0).toBeGreaterThan(0);
+
+      // Idempotent by the sheet's own mark rather than by an element id.
+      injectTerpStyles();
+      injectTerpStyles();
+      expect(sheets.length).toBe(1);
+    } finally {
+      delete (document as unknown as { adoptedStyleSheets?: unknown }).adoptedStyleSheets;
+    }
+  });
+
   it("appends the stylesheet once and is idempotent on re-invocation", () => {
     injectTerpStyles();
     injectTerpStyles();
@@ -366,20 +398,30 @@ describe("cascade structure", () => {
     ).toContain("height: 100%");
   });
 
-  it("puts the DataView's surface on the full variant, not on the bare marker", () => {
+  it("puts the DataView's surface on the full variant's TABLE, not on the root or the marker", () => {
     // Both values of data-variant are stamped and only one has a rule, which is what keeps
     // the embedded variant a bare grid. The alternative — surface on the marker, un-declared
     // under [data-variant="embedded"] — needs background: transparent, border: 0 and
     // border-radius: 0, the un-declaring shape ADR 0094 exists to avoid.
     //
     // dataview-embedded is the negative evidence this rests on: deleting the full-variant
-    // rule must move five baselines and leave that one untouched.
+    // rule must move the full-variant baselines and leave that one untouched.
+    //
+    // The OWNER changed and the guarantee did not. The surface used to sit on the root, which
+    // made one card of the toolbar, the table and the pagination, divided by internal borders
+    // — and left the table's cells flush against the outer frame. It now sits on whatever
+    // occupies the table's slot, so the table is the object and the controls above and below
+    // it float on the page. Still keyed on the variant, for the reason above.
     const base = layerBody("terp.base");
     expect(declaresRuleFor(base, '[data-terp="dataview"]'), "the root needs a display").toBe(true);
     expect(
-      declaresRuleFor(base, '[data-terp="dataview"][data-variant="full"]'),
-      "the surface belongs to the full variant",
+      declaresRuleFor(base, '[data-terp="dataview"][data-variant="full"] > [data-terp="dataview-scroll"]'),
+      "the surface belongs to the full variant's table slot",
     ).toBe(true);
+    expect(
+      declaresRuleFor(base, '[data-terp="dataview"][data-variant="full"]'),
+      "the root must NOT carry a surface — that is the card this change removed",
+    ).toBe(false);
     expect(
       base,
       "un-declaring a surface under the embedded variant is the shape ADR 0094 avoids",
@@ -402,38 +444,30 @@ describe("cascade structure", () => {
     );
   });
 
-  it("keeps the toolbar band declaring its own surface, and no ink", () => {
-    // Three separate invariants about one element, and each has a way of going wrong that
-    // nothing else in the suite can see.
-    //
-    // The background. The inline style this replaced read `selectionMode ? neutral-50 :
-    // neutral-0` — an explicit value in BOTH branches, so the resting rule has to carry
-    // neutral-0 rather than leaving it to the host. Against every composed DataView specimen
-    // dropping it moves nothing, because the full variant's root and the workbench's specimen
-    // card are both neutral-0; it breaks the EMBEDDED variant in a real app, whose root
-    // declares nothing but a display, and the band would show the page canvas through it.
-    // `dataview-toolbar-bare` renders on a neutral-50 host so that mutation fails a baseline.
+  it("keeps the toolbar FLOATING — no surface, no divider, and still no ink", () => {
+    // This assertion reversed, and the reversal is the change: the band used to declare
+    // neutral-0 and two top radii because it was the top third of a card, and nothing else
+    // kept the selection colour inside the root's rounded frame. There is no card now. A
+    // background on a strip that sits on the page canvas paints a rectangle the design does
+    // not have, and a border under it draws a line across nothing.
     //
-    // The two top radii, which are load-bearing rather than decorative: the DataView root
-    // rounds its border with no overflow: hidden, so nothing else keeps the selection band's
-    // neutral-50 inside the rounded frame.
+    // The radii went with the card for the same reason: there is no rounded frame above the
+    // toolbar to stay inside. Selection mode keeps a fill — it marks a MODE and losing that
+    // makes selection invisible — but as a surface of its own, with its own padding and
+    // radius, asserted below.
     //
-    // And NO colour. Two of this element's direct children are arbitrary caller slots
-    // (`children` and `trailing`), so a muted ink here would inherit into app-authored filter
-    // controls — a silent restyle of app DOM, which is exactly what this migration exists to
-    // stop the framework doing.
+    // NO colour survives unchanged, and it is the invariant with the sharpest edge: two of
+    // this element's direct children are arbitrary caller slots (`children` and `trailing`),
+    // so a muted ink here would inherit into app-authored filter controls — a silent restyle
+    // of app DOM, which is what the styling migration exists to stop the framework doing.
     const base = layerBody("terp.base");
     const at = base.indexOf('[data-terp="dataview-toolbar"]');
     expect(at, "the toolbar band should have a base rule").toBeGreaterThan(-1);
     const block = base.slice(base.indexOf("{", at) + 1, base.indexOf("}", at));
-    expect(block, "the band must declare its own surface, not inherit the host's").toContain(
-      "background: var(--color-neutral-0)",
+    expect(block, "a floating strip paints no surface of its own").not.toContain("background:");
+    expect(block, "a divider under a floating strip is a line across nothing").not.toContain(
+      "border-block-end:",
     );
-    for (const radius of ["border-top-left-radius", "border-top-right-radius"]) {
-      expect(block, `${radius} keeps the selection band inside the root's rounded frame`).toContain(
-        `${radius}: var(--radius-lg)`,
-      );
-    }
     expect(
       /(^|;)\s*color:/.test(block),
       "a colour here inherits into the caller's filter slot and trailing slot",
@@ -449,11 +483,27 @@ describe("cascade structure", () => {
       layerBody("terp.state"),
       "selection mode is a resting surface, not an interaction state",
     ).not.toContain('[data-variant="selection"]');
-    // The bar reads the density token rather than a literal --space-3, which is what makes a
-    // compact view's band line up with its first cell. Zero-diff at comfortable, because
-    // comfortable --density-cell-pad-x IS --space-3 — so only dataview-compact can catch it.
-    expect(block, "the band's inline padding must follow density").toContain(
-      "padding: var(--space-2) var(--density-cell-pad-x)",
+    // The band used to read --density-cell-pad-x for its INLINE padding, so a compact view's
+    // band lined up with its first cell. That alignment target is gone with the card: the
+    // toolbar now aligns with the table's outer frame, whose position does not move with
+    // density, so inline padding here would push the controls off it. Block padding stays on
+    // the spacing scale — vertical rhythm was never the density question.
+    expect(block, "the band's block padding stays on the spacing scale").toContain(
+      "padding-block: var(--space-2)",
+    );
+    expect(
+      /padding-inline|padding:/.test(block),
+      "inline padding would push the controls off the table frame they now align to",
+    ).toBe(false);
+    // Selection mode is the exception and declares its own inline padding, because there it
+    // IS a surface and its fill needs to clear its text.
+    const selectionAt = base.indexOf('[data-terp="dataview-toolbar"][data-variant="selection"]');
+    const selectionBlock = base.slice(
+      base.indexOf("{", selectionAt) + 1,
+      base.indexOf("}", selectionAt),
+    );
+    expect(selectionBlock, "the selection surface reads density for its own inset").toContain(
+      "padding-inline: var(--density-cell-pad-x)",
     );
   });
 

package/src/styles.ts

@@ -1939,20 +1939,32 @@ textarea[data-terp="input"] {
 [data-terp="dataview"] {
   display: grid;
 }
-/* The full variant's surface. (0,2,0) against the bare marker's (0,1,0), so it wins
-   on specificity — no tie, no :not(), no source order. BOTH values of data-variant
-   are stamped and only this one has a rule, which is the theme-toggle idiom where
-   inline is stamped and takes the shared base while only stacked declares anything.
-   Rejected: putting the surface on the bare marker and un-declaring it under
-   [data-variant="embedded"], which needs background: transparent, border: 0 and
-   border-radius: 0 — the shape ADR 0094 exists to avoid. Also rejected: stamping
-   nothing for the default on the density precedent, which holds only because
-   comfortable IS the :root value and so has nothing to declare.
-   Byte-identical to [data-terp="card"]'s trio; written flat anyway, the Badge /
-   Alert / row-tone precedent. No overflow: hidden, and none should be added here —
-   the last row's border crossing the rounded bottom corners is pre-existing and
-   belongs to its own commit. */
-[data-terp="dataview"][data-variant="full"] {
+/* The full variant's surface belongs to the TABLE, not to the whole view.
+   It used to wrap everything: one card holding the toolbar, the table and the
+   pagination, divided internally by a border under the toolbar and over the
+   pagination. That reads as three bands of one object, and it costs twice — the
+   table's cells are then flush against the outer frame (nothing between the first
+   column's text and the card edge but cell padding), and the toolbar's controls sit
+   inside a surface they do not belong to.
+
+   So the surface moves down one level, onto whatever occupies the table's slot, and
+   the toolbar and the pagination float on the page background instead. The table
+   becomes the object; the controls above and below it become controls. That also
+   dissolves the flush-to-the-edge problem rather than padding around it: the table's
+   own frame is the edge now, and --density-cell-pad-x is already the inset from it.
+
+   The alternative considered was keeping the outer card and adding inline padding to
+   the table inside it. Rejected: it fixes the symptom by making the card thicker,
+   leaves the toolbar inside a surface, and leaves two nested frames whenever the view
+   is empty (the empty state's dashed frame inside the card's solid one).
+
+   Keyed on [data-variant="full"] rather than the bare marker for the reason the
+   previous rule gave and which still holds: [data-variant="embedded"] must declare
+   nothing, and un-declaring a surface with background: transparent / border: 0 is the
+   shape ADR 0094 exists to avoid. */
+[data-terp="dataview"][data-variant="full"] > [data-terp="dataview-scroll"],
+[data-terp="dataview"][data-variant="full"] > [data-terp="dataview-error"],
+[data-terp="dataview"][data-variant="full"] > [data-terp="dataview-skeleton"] {
   background: var(--color-neutral-0);
   border: 1px solid var(--color-neutral-200);
   border-radius: var(--radius-lg);
@@ -2031,22 +2043,38 @@ textarea[data-terp="input"] {
    No colour declaration here on purpose. Two of this element's direct children
    are arbitrary caller slots, and inheriting a muted ink onto app-authored filter
    controls would be a silent restyle of app DOM. */
+/* Floating: no background, no divider, and no inline padding. The divider was the
+   seam between two bands of one card and there is no card now — a border under a strip
+   that sits on the page background is a line drawn across nothing. Dropping the inline
+   padding aligns the controls with the table's OUTER edge (its frame) rather than with
+   its cell text, which is the alignment a floating control row wants: the eye follows
+   the frame, and a control indented to meet the first column's text reads as belonging
+   inside the table.
+
+   The background's previous justification is worth answering rather than deleting: it
+   was there for the EMBEDDED variant, whose root declares nothing but a display, so that
+   the band would not show the page canvas through it. That is now the intent in both
+   variants. A floating strip shows whatever is behind it — the page in the full variant,
+   the app's own card in the embedded one — and in neither case is a neutral-0 rectangle
+   under the controls something the design asks for. dataview-toolbar-bare still renders
+   on a neutral-50 host, so the difference is visible in a baseline either way. */
 [data-terp="dataview-toolbar"] {
   display: flex;
   align-items: center;
   gap: var(--space-2);
   flex-wrap: wrap;
-  padding: var(--space-2) var(--density-cell-pad-x);
-  border-block-end: 1px solid var(--color-neutral-200);
-  background: var(--color-neutral-0);
-  border-top-left-radius: var(--radius-lg);
-  border-top-right-radius: var(--radius-lg);
+  padding-block: var(--space-2);
   min-height: 3rem;
 }
 /* Selection mode. A resting surface rather than an interaction state, so
    terp.base — and (0,2,0) against the base's (0,1,0) means it wins on
    specificity alone, needing no :not() and no source-order dependency. */
 [data-terp="dataview-toolbar"][data-variant="selection"] {
+  /* Still a filled surface, because it marks a MODE and losing that would make
+     selection invisible — but now it is a surface of its own rather than a band of the
+     card, so it takes the padding and radius that make it read as one. */
+  padding-inline: var(--density-cell-pad-x);
+  border-radius: var(--radius-md);
   background: var(--color-neutral-50);
 }
 [data-terp="dataview-toolbar-count"] {
@@ -2263,6 +2291,17 @@ input[data-terp="input"][type="password"]::-ms-reveal {
    data-tone on an element no selector could reach, and the row-tones baseline
    would have lost its tints the moment the tone moved out of a style object.
    It is unconditional now, and clickability is an attribute of its own. */
+/* The last row draws no bottom border, which fixes two things the full variant's own
+   comment had already named and deferred. The container carries a 1px border and a
+   radius, so the last row's border sat a pixel inside it as a DOUBLE line, and with no
+   overflow: hidden it also ran straight across the rounded bottom corners. Dropping the
+   border is the fix rather than clipping the container: overflow: hidden here would trap
+   the horizontal scroll container and any overlay a cell renders, which is why that
+   comment refused it. tbody's last row, not the table's — a footer row would want its
+   own rule. */
+[data-terp="dataview-row"]:last-child > td {
+  border-bottom: none;
+}
 [data-terp="dataview-row"][data-clickable="true"] {
   cursor: pointer;
 }
@@ -2296,15 +2335,31 @@ input[data-terp="input"][type="password"]::-ms-reveal {
    sorted, so the unsorted glyph's dimming keys off its ABSENCE rather than off
    an attribute minted for it — this component owns aria-sort, unlike the
    breadcrumb's aria-current, which a router stamps on every ancestor link. */
+/* font: inherit is not enough, and the gap it leaves split the header row in two.
+   The font shorthand carries no text-transform and no letter-spacing, and the UA
+   stylesheet resets both on form controls — so in any table mixing sortable and
+   non-sortable columns the plain th rendered uppercase with 0.04em tracking while
+   the sortable one rendered sentence case with none, side by side in one row. Both
+   are named explicitly because inheritance is what the UA overrode.
+
+   The block padding mirrors the th's so the button fills the cell it sits in,
+   pulled back out by the negative margin. The control was a 17px-tall target inside
+   a 34px cell — half the cell unused, and the most-used control in a data app
+   clearing WCAG 2.5.8 only through the spacing exception. Filling the cell costs
+   nothing and changes no layout: the button's box grows into padding the th
+   already reserved. */
 [data-terp="dataview-column-sort"] {
   display: inline-flex;
   align-items: center;
   gap: var(--space-1);
   font: inherit;
+  text-transform: inherit;
+  letter-spacing: inherit;
   color: inherit;
   background: transparent;
   border: none;
-  padding: 0;
+  padding: var(--space-2) 0;
+  margin-block: calc(-1 * var(--space-2));
   cursor: pointer;
 }
 [data-terp="dataview-table"] > thead > tr > th:not([aria-sort]) > [data-terp="dataview-column-sort"] > svg {
@@ -2518,8 +2573,7 @@ th[data-terp="dataview-actions-cell"] > span {
   justify-content: space-between;
   gap: var(--space-3);
   flex-wrap: wrap;
-  padding: var(--space-2) var(--density-cell-pad-x);
-  border-block-start: 1px solid var(--color-neutral-200);
+  padding-block: var(--space-2);
   font-size: var(--font-size-sm);
   color: var(--color-fg-subtle);
 }
@@ -2707,6 +2761,24 @@ th[data-terp="dataview-actions-cell"] > span {
   border-radius: var(--radius-lg);
   background: var(--color-neutral-0);
 }
+/* Compact: a section's emptiness rather than the page's. Same frame and same words,
+   laid out as a row — the glyph beside the text instead of above it — so two of
+   these stacked read as two quiet sections rather than 480px of repeated poster. */
+[data-terp="empty-state"][data-size="compact"] {
+  grid-template-columns: auto 1fr;
+  justify-items: start;
+  align-items: center;
+  gap: var(--space-2) var(--space-3);
+  padding: var(--space-3) var(--space-4);
+  text-align: start;
+}
+[data-terp="empty-state"][data-size="compact"] > [data-terp="empty-state-title"] {
+  font-size: var(--font-size-sm);
+}
+[data-terp="empty-state"][data-size="compact"] > [data-terp="empty-state-description"],
+[data-terp="empty-state"][data-size="compact"] > :not([data-terp="empty-state-icon"]):not([data-terp="empty-state-title"]) {
+  grid-column: 2;
+}
 [data-terp="empty-state-icon"] {
   color: var(--color-neutral-400);
   display: inline-flex;
@@ -2822,6 +2894,71 @@ input[data-terp="input"][role="combobox"] {
   position: relative;
   display: grid;
 }
+/* Multiple: the tokens share the field's box with the input, wrapping onto as many rows
+   as the selection needs. A fixed-height field would either clip the third token or
+   reserve room for tokens nobody has chosen — and a set-valued field whose height never
+   changes is lying about how much is in it.
+
+   The input keeps a minimum inline size so a filter is still typeable when the tokens have
+   taken most of a row, and flex-basis 0 so it yields to them rather than pushing the last
+   token out of the box. */
+[data-terp="combobox-field"][data-multiple="true"] {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--space-1);
+  padding: var(--space-1);
+  border: 1px solid var(--color-neutral-300);
+  border-radius: var(--radius-md);
+  background: var(--color-neutral-0);
+}
+[data-terp="combobox-field"][data-multiple="true"] > [data-terp="input"] {
+  flex: 1 1 0;
+  min-inline-size: 6rem;
+  border: none;
+  background: transparent;
+  padding-inline: var(--space-1);
+}
+[data-terp="combobox-token"] {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-1);
+  padding-block: 0;
+  padding-inline: var(--space-2);
+  font-size: var(--font-size-sm);
+  color: var(--color-neutral-900);
+  background: var(--color-neutral-100);
+  border: 1px solid var(--color-neutral-200);
+  border-radius: var(--radius-sm);
+  /* Matches the control height a token sits beside, so a row of tokens and the input
+     share one baseline instead of the tokens riding high. */
+  min-block-size: calc(var(--density-control-min-height) - var(--space-2));
+}
+/* The remove control is a real button and a real tab stop, which is the accessible half of
+   the Backspace shortcut rather than a duplicate of it: the shortcut is discoverable only if
+   you already know it, and a token nobody can reach by keyboard cannot be removed by one. */
+[data-terp="combobox-token-remove"] {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-inline-size: var(--space-4);
+  min-block-size: var(--space-4);
+  padding: 0;
+  color: var(--color-neutral-600);
+  background: transparent;
+  border: none;
+  border-radius: var(--radius-sm);
+  cursor: pointer;
+  line-height: 1;
+}
+[data-terp="combobox-token-remove"]:hover:not(:disabled) {
+  color: var(--color-neutral-900);
+  background: var(--color-neutral-200);
+}
+[data-terp="combobox-token-remove"]:disabled {
+  cursor: not-allowed;
+  opacity: 0.5;
+}
 /* Addressed structurally rather than by a marker of its own: it is an
    iconbutton, and the only thing distinguishing it is where it sits. */
 [data-terp="combobox-field"] > [data-terp="iconbutton"] {
@@ -3006,7 +3143,7 @@ button[data-terp="input"][data-placeholder="true"] {
 }
 [data-terp="tooltip"] {
   position: absolute;
-  z-index: 1;
+  z-index: var(--z-index-tooltip);
   inset-block-end: calc(100% + var(--space-1));
   inset-inline-start: 0;
   max-inline-size: min(18rem, calc(100vw - 2 * var(--space-4)));
@@ -3393,10 +3530,21 @@ button[data-terp="input"][data-placeholder="true"] {
    viewport reads --z-index-toast. (This paragraph said "AppShell still writes
    50/40/30 ... and comes right with its own migration" for a release after that
    migration landed, which is the shape of stale comment worth naming: it read as
-   a known gap rather than as a finished one.) Tooltip's z-index:
-   1 above is deliberately NOT a token — the tooltip is absolutely positioned
-   inside its own anchor, so 1 is a local lift within a stacking context rather
-   than a place in the app-wide order. */
+   a known gap rather than as a finished one.) Tooltip's z-index WAS 1 on the
+   reasoning that the tooltip is absolutely positioned inside its own anchor, so 1
+   is a local lift within a stacking context rather than a place in the app-wide
+   order. That is sound about the anchor and wrong about the page:
+   [data-terp="tooltip-anchor"] is only position: relative, which does NOT create a
+   stacking context, so the 1 competed in the ROOT context — against a sticky header
+   at 30 and an open popover at 60 — and lost. Reported as a tooltip that renders
+   below content "sometimes, not always", which is exactly what a level that depends
+   on whatever ancestor happens to establish a context looks like. It reads
+   --z-index-tooltip (70) now, the level published for it.
+
+   Still true, and NOT fixed by this: an ancestor with overflow: hidden clips an
+   absolutely positioned tooltip whatever its level. The fix for that is the one
+   [data-terp="popover-panel"] already uses — position: fixed with measured
+   coordinates — and it is a change to the component rather than to this sheet. */
 [data-terp="popover-panel"] {
   position: fixed;
   z-index: var(--z-index-popover);
@@ -4080,13 +4228,50 @@ button[data-terp="input"][data-placeholder="true"] {
 }
 `;
 
+/**
+ * The property stamped on the constructed sheet so a second call recognises it.
+ *
+ * On the sheet object rather than on an element or a `data-` attribute: the sheet
+ * lives on the `document`, so the mark is document-scoped exactly like the old
+ * element-id check was, and it cannot collide with the `data-terp*` selectors
+ * this very stylesheet declares.
+ */
+const ADOPTED_MARKER = "__terpStylesId";
+
+/** A constructed sheet plus the mark identifying it as ours. */
+type MarkedSheet = CSSStyleSheet & { [ADOPTED_MARKER]?: string };
+
+/**
+ * `document.adoptedStyleSheets` is absent in jsdom, so the property is read
+ * through a type that admits that. Cast via `unknown` rather than intersected
+ * with `Document`, because the DOM lib declares the property as always present
+ * and an intersection would keep that stricter declaration.
+ */
+type AdoptableDocument = { adoptedStyleSheets?: MarkedSheet[] };
+
 /**
  * Inject the react-core interaction-state stylesheet once per document.
  *
- * SSR-safe: no-op when `document` is undefined. Idempotent: the sheet element
- * is keyed by {@link TERP_STYLES_ID}, so repeated calls (from any component's
- * module scope) attach the rules exactly once. Content is set via
- * `textContent` — never `innerHTML` — so no HTML-injection sink is touched.
+ * Prefers a **constructable stylesheet** (`new CSSStyleSheet()` +
+ * `document.adoptedStyleSheets`), because that is the only injection route a
+ * Content-Security-Policy does not have to widen for. A `<style>` element's
+ * rules are inline styles as far as CSP is concerned, so shipping them obliged
+ * every generated app to serve `style-src 'unsafe-inline'` — a keyword that,
+ * once present, also permits every *other* inline stylesheet on the page,
+ * including one an injection managed to introduce. Measured in Chromium: an
+ * adopted sheet applies cleanly under `style-src 'self'` while a `<style>`
+ * element is reported as a `style-src-elem` violation and its rules dropped.
+ *
+ * The `<style>` element remains the fallback, because a browser without
+ * constructable stylesheets would otherwise render the chrome unstyled. Under a
+ * strict policy those browsers get no styling either way, so the fallback only
+ * ever helps.
+ *
+ * SSR-safe: no-op when `document` is undefined. Idempotent by either route — the
+ * adopted sheet carries {@link ADOPTED_MARKER}, the element is keyed by
+ * {@link TERP_STYLES_ID} — so repeated calls from any component's module scope
+ * attach the rules exactly once. Neither route touches an HTML sink: the element
+ * path sets `textContent`, never `innerHTML`, and `replaceSync` parses CSS only.
  */
 export function injectTerpStyles(): void {
   if (typeof document === "undefined") {
@@ -4095,6 +4280,23 @@ export function injectTerpStyles(): void {
   if (document.getElementById(TERP_STYLES_ID) !== null) {
     return;
   }
+
+  const adopted = (document as unknown as AdoptableDocument).adoptedStyleSheets;
+  if (adopted !== undefined && typeof CSSStyleSheet === "function") {
+    if (adopted.some((sheet) => sheet[ADOPTED_MARKER] === TERP_STYLES_ID)) {
+      return;
+    }
+    try {
+      const sheet: MarkedSheet = new CSSStyleSheet();
+      sheet.replaceSync(TERP_STYLES_CSS);
+      sheet[ADOPTED_MARKER] = TERP_STYLES_ID;
+      (document as unknown as AdoptableDocument).adoptedStyleSheets = [...adopted, sheet];
+      return;
+    } catch {
+      // A browser that exposes the API but refuses this sheet still gets styling.
+    }
+  }
+
   const el = document.createElement("style");
   el.id = TERP_STYLES_ID;
   el.textContent = TERP_STYLES_CSS;

package/src/tokens.guard.test.ts

@@ -133,8 +133,13 @@ const UNREAD_TOKENS: Record<string, string[]> = {
  * prose scale.
  */
 const BARE_TYPE_LITERALS: Record<string, Record<string, number>> = {
-  "line-height": { "0": 2, "1": 4, "1.2": 4, "1.25": 7, "1.3": 2, "1.4": 3, "1.5": 4 },
-  "letter-spacing": { "0": 4, "0.04em": 1, "0.06em": 1 },
+  "line-height": { "0": 2, "1": 5, "1.2": 4, "1.25": 7, "1.3": 2, "1.4": 3, "1.5": 4 },
+  // `inherit` is recorded rather than tokenised, and it is the one value here that is not
+  // debt: the sort button in a table header must render the tracking its own `th` sets, and
+  // naming a token would pin it to whatever that header uses TODAY. The UA stylesheet resets
+  // letter-spacing on form controls, so inheritance has to be asked for explicitly — the
+  // header and its button were rendering two different treatments side by side until it was.
+  "letter-spacing": { "0": 4, "0.04em": 1, "0.06em": 1, inherit: 1 },
 };
 
 describe("design tokens", () => {
@@ -242,3 +247,45 @@ describe("design tokens", () => {
     }
   });
 });
+
+/**
+ * Bare `z-index` values the sheet is allowed to write, and why each one is not the app-wide
+ * order. This is a whitelist rather than a count, because unlike the type scale there is no
+ * migration debt here: a full `--z-index-*` family is published and read by seven rules, so
+ * any NEW bare value is a component opting out of the order rather than waiting for a pass.
+ *
+ * It exists because the absence of it cost a real defect. Tooltip wrote `z-index: 1` with a
+ * comment arguing it was "a local lift within a stacking context rather than a place in the
+ * app-wide order" — sound about its anchor and wrong about the page, since
+ * `[data-terp="tooltip-anchor"]` is only `position: relative` and so establishes no stacking
+ * context. The 1 competed in the root context against a sticky header at 30 and an open
+ * popover at 60, and lost: a tooltip that rendered below content "sometimes, not always".
+ * Nothing caught it, because a published scale with no guard against skipping it is a
+ * convention, not a contract.
+ */
+const LOCAL_STACKING_LIFTS: Record<string, string> = {
+  'dataview-column-resizer': "a lift inside the cell's own stacking context, above the cell's content and nothing else",
+};
+
+describe("stacking order", () => {
+  it("every z-index reads the published scale, or is a recorded local lift", () => {
+    const bare = [...sheet.matchAll(/([^{}]+)\{([^}]*)\}/g)].flatMap(([, selector, body]) => {
+      const match = /\bz-index:\s*([^;]+);/.exec(body ?? "");
+      if (match === null || match[1]!.includes("var(")) {
+        return [];
+      }
+      const marker = /data-terp="([^"]+)"/.exec(selector ?? "");
+      return [{ marker: marker?.[1] ?? (selector ?? "").trim(), value: match[1]!.trim() }];
+    });
+
+    const unrecorded = bare.filter(({ marker }) => !(marker in LOCAL_STACKING_LIFTS));
+    expect(
+      unrecorded,
+      "a bare z-index is a component opting out of the app-wide --z-index-* order. Read the " +
+        "token published for its level, or record it in LOCAL_STACKING_LIFTS with the reason " +
+        "its stacking context is genuinely local — and be sure it IS local: an anchor that is " +
+        "only position: relative establishes no stacking context, which is how the tooltip's " +
+        "own lift ended up competing with the page and losing.",
+    ).toEqual([]);
+  });
+});