@terpjs/react-core 0.13.1 → 0.14.0

package/src/tokens.guard.test.ts

@@ -84,21 +84,24 @@ const UNREAD_TOKENS: Record<string, string[]> = {
   "--shell-": [],
   "--color-sidebar-": [],
   // The whole semantic colour layer, which the comment above admitted was untracked and then
-  // left untracked. Seventeen of the forty-eight published `--color-` tokens have no `var()`
-  // reader anywhere in the sheet, and until now nothing said so — the exact `--color-fg-on-brand`
-  // shape that comment describes, seventeen times over.
+  // left untracked. Booked at seventeen of the forty-eight published `--color-` tokens with no
+  // `var()` reader anywhere in the sheet — the exact `--color-fg-on-brand` shape that comment
+  // describes, seventeen times over. Fifteen now: the flat-card change wired
+  // `--color-interactive-hover` (the table row's hover, which had been spelling that value as a
+  // ramp step) and `--color-interactive-selected` (the selected row and the selection band,
+  // which had no colour of their own at all).
   //
   // Booked as one family rather than four narrower ones on purpose. `--color-bg-`,
-  // `--color-border-`, `--color-interactive-` and `--color-chart-` are each read by NOTHING, and
-  // the assertion below requires a tracked family to publish more than it books — a deliberate
-  // "is the prefix right?" check that a wholly-unread family would trip. The broader prefix
-  // subsumes them and still catches the eighteenth. `--color-sidebar-` stays above because it
-  // makes a narrower claim worth keeping: that family is read in full.
+  // `--color-border-` and `--color-chart-` are each STILL read by nothing, and the assertion
+  // below requires a tracked family to publish more than it books — a deliberate "is the prefix
+  // right?" check that a wholly-unread family would trip. The broader prefix subsumes them and
+  // still catches the sixteenth. `--color-sidebar-` stays above because it makes a narrower
+  // claim worth keeping: that family is read in full.
   //
-  // None of these seventeen is a defect on its own. They are a published vocabulary that shipped
-  // ahead of its consumers — four surface tokens, three borders, three interactive states, a
+  // None of these fifteen is a defect on its own. They are a published vocabulary that shipped
+  // ahead of its consumers — four surface tokens, three borders, one interactive state, a
   // five-step chart ramp and two neutrals — and the point of booking them is that the list can
-  // only shrink from here, so wiring one is visible and adding an eighteenth has to argue.
+  // only shrink from here, so wiring one is visible and adding a sixteenth has to argue.
   "--color-": [
     "--color-bg-canvas",
     "--color-bg-inset",
@@ -113,8 +116,6 @@ const UNREAD_TOKENS: Record<string, string[]> = {
     "--color-chart-4",
     "--color-chart-5",
     "--color-interactive-active",
-    "--color-interactive-hover",
-    "--color-interactive-selected",
     "--color-neutral-500",
     "--color-neutral-800",
   ],
@@ -228,6 +229,45 @@ describe("design tokens", () => {
     }
   });
 
+  it("tightens the shell gutter for a phone rather than remapping it to itself", () => {
+    // --shell-gutter is published once and remapped once, on the shell root under
+    // data-variant="mobile". Existence is not the property worth holding: a remap that
+    // resolved back to the published value would leave every structural check green while
+    // the phone silently kept the desktop measure, and the whole reason the token exists is
+    // that the header, main, the footer and the page band all read it.
+    //
+    // Here rather than in styles.test.ts because the control is the PUBLISHED value, which
+    // means reading tokens.css — this file's subject, and this file runs in node where
+    // that read works.
+    const published = /--shell-gutter:\s*([^;]+);/.exec(tokensCss);
+    expect(published, "tokens.css must publish --shell-gutter").not.toBeNull();
+    const remap = /\[data-terp="appshell"\]\[data-variant="mobile"\] \{([^}]*)\}/.exec(sheet);
+    expect(remap, "the sheet must remap the gutter for a phone").not.toBeNull();
+    const remapped = /--shell-gutter:\s*([^;]+);/.exec(remap![1]!);
+    expect(remapped, "the remap must move --shell-gutter, not something else").not.toBeNull();
+    // It must stay on the spacing scale rather than becoming a literal, which is one way a
+    // shared measure rots.
+    expect(remapped![1]!.trim(), "the phone gutter must name a spacing token").toMatch(
+      /^var\(--space-\d+\)$/,
+    );
+    // RESOLVED, not spelled. Comparing the two strings was the first version of this and it
+    // could not fail the way that matters: `var(--space-4)` and `1rem` are different text and
+    // the same length, so publishing the gutter at the phone's own value passed while the
+    // remap became a no-op. Both sides resolve through tokens.css before they are compared.
+    const resolve = (value: string): string => {
+      const reference = /^var\((--[a-z0-9-]+)\)$/.exec(value.trim());
+      if (reference === null) return value.trim();
+      const declared = new RegExp(`${reference[1]!}:\\s*([^;]+);`).exec(tokensCss);
+      expect(declared, `${reference[1]!} must be declared in tokens.css`).not.toBeNull();
+      return declared![1]!.trim();
+    };
+    expect(
+      resolve(remapped![1]!),
+      "a remap that resolves to the published gutter is dead weight, and the phone silently "
+        + "keeps the desktop measure",
+    ).not.toBe(resolve(published![1]!));
+  });
+
   it("holds the bare type literals at their recorded count", () => {
     // The debt the type scale's arrival did not clear, as a ratchet. See BARE_TYPE_LITERALS:
     // most of these map onto no step in the published scale, so converting them changes

package/src/ui/Card.test.tsx

@@ -36,6 +36,44 @@ describe("Card", () => {
     expect(screen.getByRole("button", { name: "Nieuw" })).toBeInTheDocument();
   });
 
+  it("keeps the actions slot a sibling of the heading, description or not", () => {
+    // The DOM half of a defect whose visible half was CSS. `actions` is documented as a slot in
+    // the header ROW, and it stopped being one the moment `description` was set: the heading was
+    // sized from its content, a block holding a title and a sentence is as wide as the sentence,
+    // and flex breaks lines on that width before it shrinks anything — so the header wrapped and
+    // the control landed underneath. Measured 103px against 48px for the same component one prop
+    // apart.
+    //
+    // What the sheet's fix needs from the markup is exactly this shape: the description inside
+    // the heading (so :has() can find it and so the two lines stay one block) and the actions
+    // slot OUTSIDE it, as a sibling. Nesting the slot in the heading, or lifting the description
+    // out of it, would each render plausibly and defeat the rule silently — which is why this is
+    // asserted structurally rather than left to a screenshot.
+    for (const description of [undefined, "Wat dit blok beschrijft."]) {
+      cleanup();
+      render(
+        <Card
+          title="Projecten"
+          description={description}
+          actions={<button type="button">Nieuw</button>}
+        >
+          inhoud
+        </Card>,
+      );
+      const header = screen
+        .getByRole("heading", { level: 3, name: "Projecten" })
+        .closest('[data-terp="card-header"]') as HTMLElement;
+      const heading = header.querySelector('[data-terp="card-heading"]') as HTMLElement;
+      const actions = header.querySelector('[data-terp="card-actions"]') as HTMLElement;
+      expect(actions.parentElement, "the actions slot is the heading's sibling").toBe(header);
+      expect(heading.contains(actions)).toBe(false);
+      expect(
+        heading.querySelector('[data-terp="card-description"]') !== null,
+        "the description lives inside the heading, which is what the :has() rule reads",
+      ).toBe(description !== undefined);
+    }
+  });
+
   it("renders headerless with children only", () => {
     render(<Card>alleen inhoud</Card>);
     const card = screen.getByText("alleen inhoud").closest('[data-terp="card"]');
@@ -43,7 +81,7 @@ describe("Card", () => {
   });
   it("names the plain variant and leaves the boxed default unmarked", () => {
     // The chrome-less titled region. A variant rather than a `Section` component of its own,
-    // because a chrome-less region is this element with three declarations removed — a second
+    // because a chrome-less region is this element with two declarations removed — a second
     // component would have meant six more markers describing the same DOM, and a `Surface` is
     // a Card with no title, which this already is.
     const { rerender } = render(<Card variant="plain" title="Plain">body</Card>);

package/src/ui/Card.tsx

@@ -21,7 +21,7 @@ export interface CardProps
    * loses its full width.
    *
    * It is a variant rather than a `Section` component of its own, and that is a decision worth
-   * knowing. A chrome-less titled region is exactly this element with three declarations
+   * knowing. A chrome-less titled region is exactly this element with two declarations
    * removed: `Card` already renders a `<section>` with an `<h3>` and stacks its children on
    * the token scale. A second component would have meant six more markers describing the same
    * DOM, and a `Surface` — the third name the diagnosis suggested — is a `Card` with no title,
@@ -32,7 +32,18 @@ export interface CardProps
   title?: UiText;
   /** Optional muted one-liner under the title (what this block is about). */
   description?: UiText;
-  /** Optional right-hand slot in the header row (filters, a legend, an action). */
+  /**
+   * Optional right-hand slot in the header row (filters, a legend, an action).
+   *
+   * It stays on the title's line whether or not there is a {@link CardProps.description}, and
+   * that took a rule rather than coming for free: the header wraps, and a heading block sized
+   * from its content is as wide as its longest line — a description sentence — so flex broke
+   * the line before it shrank anything and the slot landed underneath. Measured at a 103px
+   * header against 48px for the same component with the description removed. The heading's
+   * flex base is 0 now, so both fit on one line by construction, and the header aligns to
+   * `start` once a description is present so the control sits beside the title rather than
+   * floating in the middle of the block.
+   */
   actions?: ReactNode;
   /** The rendered element — `"section"` by default (a titled block of a page). */
   as?: "section" | "article" | "div" | "aside";
@@ -42,10 +53,11 @@ export interface CardProps
 }
 
 /**
- * A token-styled surface that groups one block of a page — the sanctioned way to give
- * sections visual separation (border + background + padding) without module CSS, and
+ * A token-styled frame that groups one block of a page — the sanctioned way to give
+ * sections visual separation (a border, a radius and padding) without module CSS, and
  * allowed directly in `OverviewPage` / `DetailPage` body slots under the `standard`
- * layout contract. An optional header row carries a semantic `<h3>` title, a muted
+ * layout contract. It carries no fill: what shows through a card is the page's own
+ * canvas, so a card sits on a themed background instead of repainting it. An optional header row carries a semantic `<h3>` title, a muted
  * description and an `actions` slot; the body stacks its children on the token
  * spacing scale.
  */