@terpjs/react-core 0.13.1 → 0.15.0

package/src/styles.test.ts

@@ -347,7 +347,6 @@ describe("cascade structure", () => {
     for (const selector of [
       '[data-terp="appshell"][data-variant="mobile"] [data-terp="appshell-sidebar"]',
       '[data-terp="appshell-backdrop"]',
-      '[data-terp="appshell"][data-variant="mobile"] [data-terp="appshell-main"]',
     ]) {
       expect(
         declaresRuleFor(base, selector),
@@ -355,6 +354,163 @@ describe("cascade structure", () => {
           "pictures of it",
       ).toBe(true);
     }
+    // The gutter's phone value is ONE rule where the header and main used to carry a mobile
+    // override each, and it is asserted against the UNLAYERED prelude rather than terp.base
+    // because that is where it has to live: tokens.css declares --shell-gutter on :root and
+    // ships as an extracted <link> ahead of this sheet, so a layered copy would lose to it
+    // in a production build while winning in dev — the exposure the density remap beside it
+    // records. app-shell-mobile is still its only picture.
+    const prelude = css.slice(0, css.indexOf("@layer terp.reset {"));
+    expect(
+      declaresRuleFor(prelude, '[data-terp="appshell"][data-variant="mobile"]'),
+      "the phone gutter must be remapped in the unlayered prelude, or tokens.css outranks it",
+    ).toBe(true);
+    expect(
+      declaresRuleFor(layerBody("terp.base"), '[data-terp="appshell"][data-variant="mobile"]'),
+      "a layered copy of the remap loses to tokens.css in a production build",
+    ).toBe(false);
+    // That the remap actually TIGHTENS is asserted in tokens.guard.test.ts, not here: it
+    // compares the remapped value against the one tokens.css publishes, and this file runs
+    // in jsdom where import.meta.url is not a file URL. The guard file already reads the
+    // token sheet for exactly this kind of claim.
+    const remap = /\[data-terp="appshell"\]\[data-variant="mobile"\] \{([^}]*)\}/.exec(prelude);
+    expect(remap, "the phone remap should be one rule").not.toBeNull();
+    expect(
+      remap![1]!,
+      "the remap must move --shell-gutter, not something else",
+    ).toContain("--shell-gutter:");
+  });
+
+  it("keeps the content column's gutter one measure", () => {
+    // The bug this exists for: appshell-header carried padding-inline var(--space-4) while
+    // appshell-main and appshell-footer carried var(--space-6), so the breadcrumb trail —
+    // the first thing inside main on every routed view — sat 0.5rem right of the header's
+    // own toggle. Boxes stack in that column and the topmost content in each starts at its
+    // inline padding edge, so their gutters are ONE measure and any two disagreeing is the
+    // defect.
+    //
+    // No baseline caught it, and could not have: every app-shell specimen recorded the
+    // misalignment as its expected picture from the first run. A screenshot says "this is
+    // what it looks like", never "these two edges are meant to be the same edge".
+    //
+    // It is now a published token with one remap rather than a literal repeated per box,
+    // which stopped being a preference when the page band arrived: the band reads the same
+    // measure as a NEGATIVE margin to reach the column's edge, so a literal would have had
+    // to agree in sign across rules three hundred lines apart.
+    const base = layerBody("terp.base");
+    const bodyFor = (selector: string): string => {
+      for (const match of base.matchAll(/([^{}]+)\{([^{}]*)\}/g)) {
+        const selectors = match[1].split(",").map((part) => part.trim().replace(/\s+/g, " "));
+        if (selectors.includes(selector)) return match[2];
+      }
+      throw new Error(`the sheet declares no rule for exactly ${selector}`);
+    };
+    /**
+     * The inline padding a rule sets, from either the shorthand's second value or an
+     * explicit `padding-inline`. Both spellings are in play on purpose: the header and the
+     * footer set block and inline together, main sets one value for all four sides.
+     */
+    const gutterOf = (selector: string): string => {
+      const declarations = bodyFor(selector);
+      const inline = /padding-inline:\s*([^;]+);/.exec(declarations);
+      if (inline) return inline[1]!.trim();
+      const shorthand = /padding:\s*([^;]+);/.exec(declarations);
+      if (!shorthand) throw new Error(`${selector} declares no padding at all`);
+      const parts = shorthand[1]!.trim().split(/\s+(?![^(]*\))/);
+      // One value pads every side, two are block-then-inline. Nothing in this column writes
+      // the three- or four-value form, and a rule that started to would land here rather
+      // than being read wrong.
+      if (parts.length === 1) return parts[0]!;
+      if (parts.length === 2) return parts[1]!;
+      throw new Error(
+        `${selector} writes a ${parts.length}-value padding this reader cannot split`,
+      );
+    };
+
+    const column = [
+      '[data-terp="appshell-header"]',
+      '[data-terp="appshell-main"]',
+      '[data-terp="appshell-footer"]',
+    ].map((selector) => [selector, gutterOf(selector)] as const);
+    expect(
+      new Set(column.map(([, gutter]) => gutter)).size,
+      `the column's boxes must share one inline gutter, got ${column
+        .map(([selector, gutter]) => `${selector} = ${gutter}`)
+        .join(", ")}`,
+    ).toBe(1);
+    // And it is the published token, not a spacing step restated three times. A literal here
+    // is the exact state the defect was in, and a literal passes the check above.
+    expect(column[0]![1], "the gutter must read the shell's own token").toBe(
+      "var(--shell-gutter)",
+    );
+
+    // The band splits in two, and which half is gated on the shell is the whole point.
+    //
+    // CHROME is ungated: a bordered row at the app header's height is correct wherever Page
+    // renders, the workbench's specimen cards and these tests included. It used to sit in the
+    // shell-gated rule while the comment beside it claimed the opposite, so the three
+    // page-header specimens pictured a plain flex row that the prose called chrome.
+    const chrome = bodyFor(
+      '[data-terp="page"]:not([data-measure="narrow"]) > [data-terp="page-header"]',
+    );
+    // Same height as the app header, by reading the header's own token rather than restating
+    // 3rem — and border-box, or the two are a padding apart and the claim is off by 1rem.
+    expect(chrome, "the band takes the app header's height").toContain(
+      "min-height: var(--shell-header-height)",
+    );
+    expect(chrome, "without border-box the floor excludes the padding").toContain(
+      "box-sizing: border-box",
+    );
+    expect(chrome, "the band is what separates chrome from content").toContain(
+      "border-block-end: 1px solid var(--color-neutral-200)",
+    );
+    expect(
+      /padding-inline|padding:/.test(chrome),
+      "an inline pad with no bleed would inset the band from the body beneath it",
+    ).toBe(false);
+
+    // THE BLEED is gated, because the negative-margin idiom is only correct against a box
+    // that pads by exactly this token. ADR 0097 section 2 kept "it works with no shell above
+    // it at all" as a property of the mechanism, and this keying is what keeps it. The sign
+    // agreement is a fact about two declarations in ONE rule rather than between rules.
+    const bleed = bodyFor(
+      '[data-terp="appshell-main"] > [data-terp="page"]:not([data-measure="narrow"])'
+        + ' > [data-terp="page-header"]',
+    );
+    expect(bleed, "the band must bleed by negating the gutter it pads by").toContain(
+      "margin: calc(-1 * var(--shell-gutter)) calc(-1 * var(--shell-gutter)) 0",
+    );
+    expect(bleed, "the band must restore the gutter as its own padding").toContain(
+      "padding-inline: var(--shell-gutter)",
+    );
+    expect(
+      bleed.includes("margin") && !/margin:[^;]*calc\(-1/.test(bleed),
+      "a bleed whose margin is not negative escapes nothing",
+    ).toBe(false);
+  });
+
+  it("keeps a row's own colour out of the hover wash's reach", () => {
+    // A row's tone and its selection tint paint on the tr; the table's hover wash paints on
+    // the td, and a cell background paints ABOVE its row's. So an unguarded wash repaints a
+    // selected row over its tint and a danger row over its tone: the affordance overwrites
+    // the data. The selection half only became visible when --color-interactive-selected
+    // split away from --color-neutral-50 — while the two spelled one value the collision was
+    // pixel-identical — and the tone half was live before that. Neither is picturable: no
+    // specimen renders a hovered row, so this assertion is the only gate.
+    // terp.state, not terp.base: a hover is a state, and that is where the sheet keeps it.
+    const state = layerBody("terp.state");
+    const hover = /\[data-terp="dataview-table"\][^{]*:hover td \{/.exec(state);
+    expect(hover, "the table should declare a hover wash").not.toBeNull();
+    const selector = state.slice(
+      state.lastIndexOf("}", hover!.index) + 1,
+      hover!.index + hover![0].length,
+    );
+    for (const guard of ['[data-tone]', '[data-selected="true"]']) {
+      expect(
+        selector,
+        `the hover wash must exclude :not(${guard}), or it repaints what the row is telling you`,
+      ).toContain(`:not(${guard})`);
+    }
   });
 
   it("keeps the hub-card declarations the lanes cannot explain", () => {
@@ -654,6 +810,191 @@ describe("cascade structure", () => {
     }
   });
 
+  it("puts the DetailList gap rules after the layout rules they override", () => {
+    // The same tie as the responsive Stack rules above, on a different component.
+    // [data-terp="detail-list"][data-gap="3"] and [data-terp="detail-list"][data-layout="aligned"]
+    // both weigh (0,2,0), so nothing but source order decides which row-gap a list carrying both
+    // attributes renders. Backwards, the layout default wins and the prop silently does nothing
+    // — which reads as a broken prop rather than as a misplaced rule, and no baseline can say
+    // which of the two it is looking at.
+    const base = layerBody("terp.base");
+    const layoutAt = base.indexOf('[data-terp="detail-list"][data-layout="stacked"] {');
+    expect(layoutAt, "the layouts' default row gap should have a rule").toBeGreaterThan(-1);
+    for (const token of [0, 1, 2, 3, 4, 6, 8]) {
+      const at = base.indexOf(`[data-terp="detail-list"][data-gap="${token}"]`);
+      expect(at, `detail-list has no rule for gap ${token}`).toBeGreaterThan(-1);
+      expect(at, `gap ${token} must be declared after the layout default it overrides`).toBeGreaterThan(
+        layoutAt,
+      );
+    }
+  });
+
+  it("wins DetailList's wide rules on specificity, not on where they sit", () => {
+    // The mirror of the test above, and the opposite hazard. The sheet has exactly ONE
+    // wide-viewport block and DetailList's base rules are declared roughly a hundred lines
+    // BELOW it, so source order settles these the wrong way round and cannot be relied on.
+    // Specificity is what makes them apply, which is precisely how splitpage-panes already
+    // works from this same block — and it is invisible to a reader of either rule.
+    //
+    // Asserted as a property rather than as a list of pixel values: every selector in here
+    // carries the marker plus at least one attribute, so it out-weighs the (0,1,0) base rule
+    // it overrides. These selectors are attribute-only, so counting `[` counts specificity's
+    // b-component exactly.
+    const base = layerBody("terp.base");
+    const wideAt = base.indexOf("@media not all and (max-width: 768px)");
+    expect(wideAt, "the wide block should be in terp.base").toBeGreaterThan(-1);
+    let depth = 0;
+    let end = base.length;
+    for (let i = base.indexOf("{", wideAt); i < base.length; i += 1) {
+      if (base[i] === "{") depth += 1;
+      else if (base[i] === "}") {
+        depth -= 1;
+        if (depth === 0) {
+          end = i;
+          break;
+        }
+      }
+    }
+    const wide = base.slice(wideAt, end);
+    for (const selector of [
+      '[data-terp="detail-list"][data-columns="2"]',
+      '[data-terp="detail-list"][data-layout="aligned"]',
+      '[data-terp="detail-list"][data-layout="aligned"][data-columns="2"]',
+      '[data-terp="detail-list"][data-layout="aligned"] [data-terp="detail-list-row"]',
+    ]) {
+      expect(
+        declaresRuleFor(wide, selector),
+        `${selector} belongs inside the wide block — narrow is one column`,
+      ).toBe(true);
+      expect(
+        (selector.match(/\[/g) ?? []).length,
+        `${selector} must out-specify the base rule it overrides, which is declared later`,
+      ).toBeGreaterThan(1);
+    }
+    // And the base rules really are declared after it, or none of the above is load-bearing.
+    for (const selector of ['[data-terp="detail-list"] {', '[data-terp="detail-list-row"] {']) {
+      expect(base.indexOf(selector), `${selector} should exist`).toBeGreaterThan(-1);
+      expect(
+        base.indexOf(selector),
+        `${selector} is declared before the wide block, so order — not specificity — would settle it`,
+      ).toBeGreaterThan(wideAt);
+    }
+    // The one property the wide block must NOT declare: row-gap belongs to the gap prop, whose
+    // roll-call weighs the same (0,2,0) and is declared later on purpose. A row-gap in here
+    // would out-order it and the prop would stop working above the cutover only.
+    expect(wide, "row-gap in the wide block would silently disable the gap prop").not.toContain(
+      "row-gap",
+    );
+  });
+
+  it("mutes the DetailList label in both non-inline layouts, and in neither sentence", () => {
+    // The defect this closes was a divergence: `stacked` muted its term and `aligned` never
+    // got the rule, so an aligned label rendered at the VALUE's size, weight and ink — 16px,
+    // 500, near-black — and a card of five labelled values read as a wall of bold text with
+    // nothing saying which half of a pair to read first.
+    //
+    // `inline` is deliberately excluded, and that is the half worth pinning: there the term is
+    // part of a sentence (the colon comes from a ::after) and muting half a sentence is a
+    // different defect. So this asserts the selector list exactly, in both directions.
+    // Anchored on the RULES rather than on the section comment, because `css` above has its
+    // comments stripped — prose must not satisfy a structural assertion, so prose cannot
+    // delimit one either.
+    const base = layerBody("terp.base");
+    const muting = [...base.matchAll(/([^{}]+)\{([^{}]*)\}/g)]
+      .map((match) => ({
+        selectors: match[1].split(",").map((part) => part.trim().replace(/\s+/g, " ")),
+        body: match[2],
+      }))
+      .filter(
+        (rule) =>
+          rule.selectors.some((selector) => selector.includes('[data-terp="detail-list-term"]')) &&
+          rule.body.includes("--color-fg-muted"),
+      );
+    expect(muting, "one shared rule mutes the label, not one per layout").toHaveLength(1);
+    expect(muting[0]!.selectors).toEqual([
+      '[data-terp="detail-list"][data-layout="aligned"] [data-terp="detail-list-term"]',
+      '[data-terp="detail-list"][data-layout="stacked"] [data-terp="detail-list-term"]',
+    ]);
+    expect(muting[0]!.body).toContain("var(--font-size-xs)");
+    expect(muting[0]!.body).toContain("var(--font-weight-normal)");
+    // And the base term rule — the one the inline layout renders — carries no colour of its own.
+    const termAt = base.indexOf('[data-terp="detail-list-term"] {');
+    expect(termAt, "the base term rule should exist").toBeGreaterThan(-1);
+    expect(base.slice(termAt, base.indexOf("}", termAt))).not.toContain("color:");
+  });
+
+  it("keeps a Card's actions slot on the title's line, description or not", () => {
+    // The measured inconsistency: `actions` is documented as a header-row slot and delivered
+    // one only while `description` was unset. The heading declared min-width: 0 alone, so it
+    // computed flex: 0 1 auto and its hypothetical main size was the max-content width of a
+    // block holding a title AND a sentence — and flex breaks lines on hypothetical main sizes
+    // BEFORE it shrinks anything, so with the header's flex-wrap the heading took the line and
+    // the control wrapped underneath. 103px against 48px for the same component, one prop apart.
+    //
+    // A base size of 0 is what makes both fit by construction. min-width: 0 stays for the other
+    // half: a flex item's automatic minimum is its content's, so a long unbreakable title would
+    // otherwise refuse to shrink past it. Both are asserted, because dropping either brings a
+    // different half of the bug back.
+    const base = layerBody("terp.base");
+    const headingAt = base.indexOf('[data-terp="card-heading"] {');
+    expect(headingAt, "card-heading should have a base rule").toBeGreaterThan(-1);
+    const heading = base.slice(headingAt, base.indexOf("}", headingAt));
+    expect(heading, "a content-sized heading wraps the actions slot onto its own line").toContain(
+      "flex: 1 1 0",
+    );
+    expect(heading, "min-width: 0 is what lets an unbreakable title shrink").toContain(
+      "min-width: 0",
+    );
+    // The conditional half. `center` is right for a title alone — the slot is a control, so its
+    // box is taller than one line box — and wrong the moment a description makes the heading a
+    // block, where it floats the control in the middle instead of beside the title.
+    expect(
+      declaresRuleFor(base, '[data-terp="card-header"]:has([data-terp="card-description"])'),
+      "the header's alignment must depend on whether there is a description",
+    ).toBe(true);
+    const conditionalAt = base.indexOf(
+      '[data-terp="card-header"]:has([data-terp="card-description"])',
+    );
+    expect(base.slice(conditionalAt, base.indexOf("}", conditionalAt))).toContain(
+      "align-items: start",
+    );
+    // And the base rule still centres, or the title rides above the control in the common case.
+    const headerAt = base.indexOf('[data-terp="card-header"] {');
+    expect(base.slice(headerAt, base.indexOf("}", headerAt))).toContain("align-items: center");
+  });
+
+  it("gives the page title, a card title and body copy three different steps", () => {
+    // The scale was flat: the single h1 of a view rendered at lg (18px) against a card title at
+    // base (16px) against 16px prose — one step from the h1 to a section heading, and a section
+    // heading the same size as the text under it. --font-size-xl was published with exactly one
+    // reader, so the top of the scale existed and the page that most needs it was not using it.
+    //
+    // Pinned here rather than left to the baselines because a screenshot cannot say WHICH step a
+    // rendered size came from, and the point of the change is that these four are four steps of
+    // one published scale rather than four sizes that happen to differ.
+    const base = layerBody("terp.base");
+    for (const [selector, step] of [
+      // page-title left the TOP step when the header became a band, but it still has a step
+      // and this is it: sm, the trail's own size, because the title IS the trail's leaf and a
+      // 24px leaf on 14px ancestors reads as small-small-BIG rather than as one trail. Pinned
+      // rather than dropped — removing it from this loop, which is what the band change first
+      // did, left the one marker whose size the change was about free to drift.
+      ['[data-terp="page-title"]', "sm"],
+      // The top step keeps two readers, which is what stops the token going unread;
+      // tokens.guard.test.ts holds that end.
+      ['[data-terp="heading"][data-size="xl"]', "xl"],
+      ['[data-terp="card-title"]', "lg"],
+      ['[data-terp="card-description"]', "sm"],
+    ] as const) {
+      const at = base.indexOf(`${selector} {`);
+      expect(at, `${selector} should have a rule`).toBeGreaterThan(-1);
+      expect(
+        base.slice(at, base.indexOf("}", at)),
+        `${selector} should render the ${step} step of the published scale`,
+      ).toContain(`font-size: var(--font-size-${step})`);
+    }
+  });
+
   it("declares a wide-half gap rule for every step SpaceToken allows", () => {
     // The narrow half is covered by the roll-call below; this is its counterpart. A responsive
     // gap whose wide step has no rule silently renders the narrow gap at every width — which
@@ -852,7 +1193,12 @@ describe("cascade structure", () => {
     // silently fall back to the default gap rather than fail.
     const base = layerBody("terp.base");
     for (const token of [0, 1, 2, 3, 4, 6, 8]) {
-      for (const marker of ["stack", "card", "grid"]) {
+      // `detail-list` joined the three late, and its absence is why the value it now takes was
+      // unreachable: every other layout primitive published a gap on this scale, so a detail
+      // list wanting looser rows had nowhere to say so — and app modules may write neither
+      // `style` nor `className`. Its rules set `row-gap` rather than the shorthand, for the
+      // reason the sheet gives there: the column gap is the layout's, not the caller's.
+      for (const marker of ["stack", "card", "grid", "detail-list"]) {
         expect(
           declaresRuleFor(base, `[data-terp="${marker}"][data-gap="${token}"]`),
           `${marker} has no rule for gap ${token}`,
@@ -1288,8 +1634,9 @@ describe("cascade structure", () => {
       "appshell-footer",
       "page",
       "page-header",
-      "page-breadcrumbs",
       "page-heading",
+      "page-badges",
+      "page-description",
       "page-title",
       "resource-list",
       "resource-list-create",