@charcuterie/ui 0.1.0

package/src/tailwindCandidates.test.ts

@@ -0,0 +1,377 @@
+/**
+ * Every class name in this package, compiled through the real
+ * Tailwind, asserted to produce actual CSS.
+ *
+ * This is the test that makes the whole utility-class approach safe.
+ * Tailwind v4 scans source text for *complete* class strings, so a
+ * name it does not recognise — a typo, an interpolation, a utility
+ * that needed a `@theme` bridge nobody added — generates **nothing
+ * at all**. No error, no warning, no failing build: the element
+ * simply renders unstyled, which reads as "the token layer is
+ * broken" rather than as "the scanner never saw it". That is the
+ * single most expensive failure mode in a Tailwind component
+ * library, and it is entirely mechanical to catch.
+ *
+ * Two properties are asserted:
+ *
+ *  1. **No interpolated class names.** `` `bg-intent-${intent}-solid` ``
+ *     is rejected at the AST level, which is why `intentStyles.ts`
+ *     is 48 literals rather than a loop.
+ *  2. **Every literal resolves.** `candidatesToCss` returns `null`
+ *     for a candidate Tailwind cannot generate, and any `null` fails
+ *     here with the offending class and file.
+ *
+ * The design system is built in memory from
+ * `@charcuterie/tokens`' generator rather than from its `dist`, so
+ * this also fails the moment a token bridge is removed — `text-md`
+ * and `shadow-low` exist only because `theme.css` publishes
+ * `--text-*` and `--shadow-*`.
+ */
+
+import { readdir, readFile } from "node:fs/promises"
+import { createRequire } from "node:module"
+import { dirname, join, relative, resolve } from "node:path"
+
+import {
+  buildThemeCss,
+  buildVariablesCss,
+} from "@charcuterie/tokens/src/buildCss.ts"
+import { variants } from "@charcuterie/tokens/src/variants/index.ts"
+import { __unstable__loadDesignSystem } from "tailwindcss"
+import ts from "typescript"
+import { expect, test } from "vitest"
+
+const sourceDirectory = resolve(import.meta.dirname)
+
+const require_ = createRequire(import.meta.url)
+
+const getSourceFilePaths = async (
+  directory: string,
+): Promise<string[]> => {
+  const entries = await readdir(directory, {
+    withFileTypes: true,
+  })
+
+  const paths = await Promise.all(
+    entries.map(async (entry) => {
+      const path = join(directory, entry.name)
+
+      if (entry.isDirectory()) {
+        return getSourceFilePaths(path)
+      }
+
+      if (
+        /\.tsx?$/.test(entry.name) &&
+        !entry.name.endsWith(".test.ts")
+      ) {
+        return [path]
+      }
+
+      return []
+    }),
+  )
+
+  return paths.flat()
+}
+
+type Candidate = {
+  className: string
+  file: string
+}
+
+const collectFileCandidates = (
+  path: string,
+  contents: string,
+) => {
+  const sourceFile = ts.createSourceFile(
+    path,
+    contents,
+    ts.ScriptTarget.ESNext,
+    true,
+    path.endsWith(".tsx")
+      ? ts.ScriptKind.TSX
+      : ts.ScriptKind.TS,
+  )
+
+  const candidates: Candidate[] = []
+
+  const interpolations: string[] = []
+
+  const file = relative(sourceDirectory, path)
+
+  const COMPARISON_OPERATORS = new Set<ts.SyntaxKind>([
+    ts.SyntaxKind.EqualsEqualsEqualsToken,
+    ts.SyntaxKind.EqualsEqualsToken,
+    ts.SyntaxKind.ExclamationEqualsEqualsToken,
+    ts.SyntaxKind.ExclamationEqualsToken,
+  ])
+
+  const collectStrings = (node: ts.Node) => {
+    // `sizing === "icon" ? a : b` — the operand of a comparison is a
+    // prop value, not a class name. Descending into it is how
+    // `"icon"` ends up looking like a missing utility.
+    if (ts.isConditionalExpression(node)) {
+      collectStrings(node.whenTrue)
+
+      collectStrings(node.whenFalse)
+
+      return
+    }
+
+    if (ts.isBinaryExpression(node)) {
+      if (
+        COMPARISON_OPERATORS.has(node.operatorToken.kind)
+      ) {
+        return
+      }
+
+      if (
+        node.operatorToken.kind ===
+        ts.SyntaxKind.AmpersandAmpersandToken
+      ) {
+        collectStrings(node.right)
+
+        return
+      }
+    }
+
+    if (
+      ts.isStringLiteral(node) ||
+      ts.isNoSubstitutionTemplateLiteral(node)
+    ) {
+      for (const className of node.text.split(/\s+/)) {
+        if (className.length > 0) {
+          candidates.push({ className, file })
+        }
+      }
+
+      return
+    }
+
+    // The silent-failure case, refused outright: Tailwind cannot see
+    // a class name that only exists at runtime.
+    if (ts.isTemplateExpression(node)) {
+      interpolations.push(
+        `${file}: ${node.getText().split("\n")[0]}`,
+      )
+
+      return
+    }
+
+    ts.forEachChild(node, collectStrings)
+  }
+
+  const visit = (node: ts.Node) => {
+    if (
+      ts.isJsxAttribute(node) &&
+      node.name.getText() === "className" &&
+      node.initializer
+    ) {
+      collectStrings(node.initializer)
+    }
+
+    if (
+      ts.isCallExpression(node) &&
+      node.expression.getText() === "toClassName"
+    ) {
+      for (const argument of node.arguments) {
+        collectStrings(argument)
+      }
+    }
+
+    // The class maps — `INTENT_APPEARANCE_CLASS`,
+    // `CONTROL_SIZE_CLASS`, `FOCUS_RING_CLASS`, … — where every
+    // string literal is by definition a class list.
+    if (
+      ts.isVariableDeclaration(node) &&
+      /_CLASS$/.test(node.name.getText()) &&
+      node.initializer
+    ) {
+      collectStrings(node.initializer)
+    }
+
+    ts.forEachChild(node, visit)
+  }
+
+  visit(sourceFile)
+
+  return { candidates, interpolations }
+}
+
+const loadStylesheet = async (
+  id: string,
+  _base: string,
+) => {
+  if (id === "tailwindcss") {
+    const path = require_.resolve("tailwindcss/index.css")
+
+    return {
+      path,
+      base: dirname(path),
+      content: await readFile(path, "utf8"),
+    }
+  }
+
+  // Generated in memory, so this test fails on a *generator*
+  // regression rather than on a stale `dist`.
+  if (id === "./variables.css") {
+    return {
+      path: "/virtual/variables.css",
+      base: "/virtual",
+      content: buildVariablesCss(variants, "daylight"),
+    }
+  }
+
+  throw new Error(`Unexpected stylesheet import: ${id}`)
+}
+
+const collected = await Promise.all(
+  (await getSourceFilePaths(sourceDirectory)).map(
+    async (path) =>
+      collectFileCandidates(
+        path,
+        await readFile(path, "utf8"),
+      ),
+  ),
+)
+
+const candidates = collected.flatMap(
+  (result) => result.candidates,
+)
+
+const interpolations = collected.flatMap(
+  (result) => result.interpolations,
+)
+
+test("no class name is built by interpolation", () => {
+  // `` className={`bg-${intent}`} `` renders unstyled and passes
+  // every other test in the repo.
+  expect(interpolations).toEqual([])
+})
+
+test("this package has class names to check at all", () => {
+  // A regex refactor that quietly stops matching would otherwise
+  // turn the next test into a green no-op.
+  expect(candidates.length).toBeGreaterThan(200)
+})
+
+/**
+ * The two class names in this package that are deliberately not
+ * utilities.
+ *
+ * `group` is Tailwind's own marker — it generates no CSS by design,
+ * it is what `group-hover:` reads. The `charcuterie-*` four are the
+ * looping affordances, which cannot be utilities because Tailwind's
+ * own `animate-spin` hardcodes 1s past `prefers-reduced-motion`;
+ * they live in `styles.css` and are checked against it below.
+ */
+const TAILWIND_MARKER_CLASSES = ["group"]
+
+test("every `charcuterie-` class a component uses is defined in styles.css", async () => {
+  // The other half of the "no silently-unstyled component" gate. A
+  // component reaching for `.charcuterie-glow` fails here rather
+  // than rendering a static bar nobody notices.
+  const styles = await readFile(
+    join(sourceDirectory, "styles.css"),
+    "utf8",
+  )
+
+  const used = [
+    ...new Set(
+      candidates
+        .map((one) => one.className)
+        .filter((className) =>
+          className.startsWith("charcuterie-"),
+        ),
+    ),
+  ]
+
+  expect(used.length).toBeGreaterThan(0)
+
+  for (const className of used) {
+    expect(styles).toContain(`.${className}`)
+  }
+
+  // And every one of them is switched off under reduced motion —
+  // `variables.css` zeroing the duration is not enough, because a
+  // `0ms` looping animation still holds its first keyframe.
+  const reducedMotionBlock = styles.slice(
+    styles.indexOf(
+      "@media (prefers-reduced-motion: reduce)",
+    ),
+  )
+
+  for (const className of used) {
+    expect(reducedMotionBlock).toContain(`.${className}`)
+  }
+})
+
+test("every class name compiles to real CSS", async () => {
+  const design = await __unstable__loadDesignSystem(
+    `@import "tailwindcss";\n${buildThemeCss()}`,
+    {
+      base: sourceDirectory,
+      loadStylesheet,
+      loadModule: () => {
+        throw new Error(
+          "The token layer is plain CSS — no Tailwind plugin should be loaded.",
+        )
+      },
+    },
+  )
+
+  const unique = [
+    ...new Set(candidates.map((one) => one.className)),
+  ].filter(
+    (className) =>
+      !className.startsWith("charcuterie-") &&
+      !TAILWIND_MARKER_CLASSES.includes(className),
+  )
+
+  const generated = design.candidatesToCss(unique)
+
+  const unknown = unique
+    .filter((_, index) => generated[index] === null)
+    .map((className) => {
+      const source = candidates.find(
+        (one) => one.className === className,
+      )
+
+      return `${className} (${source?.file})`
+    })
+
+  expect(unknown).toEqual([])
+})
+
+test("the token bridges are load-bearing, not decorative", async () => {
+  // The mutation check for the test above: drop `theme.css` and the
+  // colour utilities, the type ramp, and the elevation scale all
+  // stop resolving. If this passes with Tailwind alone, the
+  // components are not actually reading our tokens.
+  const design = await __unstable__loadDesignSystem(
+    `@import "tailwindcss";\n`,
+    {
+      base: sourceDirectory,
+      loadStylesheet,
+      loadModule: () => {
+        throw new Error("no plugins")
+      },
+    },
+  )
+
+  const withoutTokens = design.candidatesToCss([
+    "bg-intent-accent-solid",
+    "text-content-primary",
+    "shadow-low",
+    "text-md",
+    "cq-sm:flex-row",
+  ])
+
+  expect(withoutTokens).toEqual([
+    null,
+    null,
+    null,
+    null,
+    null,
+  ])
+})

package/src/testing/expectAgentDrivable.test.tsx

@@ -0,0 +1,71 @@
+import { expect } from "storybook/test"
+import { afterEach, test } from "vitest"
+
+import { expectAgentDrivable } from "./expectAgentDrivable.ts"
+
+/**
+ * The mutation check on the roving-tabindex rule.
+ *
+ * M4 found this helper rejecting every roving-tabindex member
+ * outright and replaced the rejection with the rule itself — so the
+ * *failing* half has to be proved too, or "exactly one tab stop" is
+ * a sentence that never runs.
+ *
+ * It lived inside `Tabs`' `AllStates` play until the story/test
+ * split, where it was neither about `Tabs` nor about the board it
+ * was rendered beside. `AgentQueries` is structural on purpose,
+ * which is what lets a four-line stub stand in for a canvas here.
+ */
+let tablist: HTMLDivElement | undefined
+
+afterEach(() => {
+  tablist?.remove()
+
+  tablist = undefined
+})
+
+const mountTablist = (...tabIndexes: number[]) => {
+  tablist = document.createElement("div")
+
+  tablist.setAttribute("role", "tablist")
+
+  tablist.innerHTML = tabIndexes
+    .map(
+      (tabIndex, index) =>
+        `<button role="tab" tabindex="${tabIndex}">${index}</button>`,
+    )
+    .join("")
+
+  // Attached, because the helper walks up to find the group and a
+  // detached tree would be the stub cheating.
+  document.body.append(tablist)
+
+  const tabs = Array.from(
+    tablist.querySelectorAll("button"),
+  )
+
+  return () => {
+    expectAgentDrivable(
+      { queryAllByRole: () => [tabs[0] as HTMLElement] },
+      { role: "tab" },
+    )
+  }
+}
+
+test("two tab stops in one group is a failure", () => {
+  // Tab lands inside the group twice and the arrow keys are
+  // decoration.
+  expect(mountTablist(-1, 0, 0)).toThrow(/2 tab stops/)
+})
+
+test("exactly one tab stop passes", () => {
+  expect(mountTablist(-1, 0, -1)).not.toThrow()
+})
+
+test("no tab stop at all is also a failure", () => {
+  // The other half of "exactly one": a group nothing can Tab into
+  // is unreachable, and a rule that only catches the excess would
+  // call it fine. Matched on the count so it cannot pass by
+  // throwing for some unrelated reason.
+  expect(mountTablist(-1, -1, -1)).toThrow(/0 tab stops/)
+})

package/src/testing/expectAgentDrivable.ts

@@ -0,0 +1,273 @@
+/**
+ * Agent-drivability as a red/green property, not a hope.
+ *
+ * A stated goal of this library is that **Playwright MCP and AI
+ * agents can drive the fleet's apps**, and that reduces to one
+ * mechanical requirement: `getByRole(role, { name })` finds exactly
+ * one thing. The fleet fails it comprehensively today —
+ * plex-channels' icon buttons are bare glyphs (`↶`, `↷`, `▶`),
+ * mux-magic's status pills are `<div>`s with no role, xander has
+ * zero `aria-*` attributes — and every one of those failures is
+ * invisible in a browser and invisible to axe.
+ *
+ * So every component's story calls this, and the assertion is the
+ * same one Playwright will make.
+ *
+ * Deliberately dependency-free — no `expect`, no jest-dom, no
+ * testing-library import. This ships in `@charcuterie/ui/testing`
+ * for consumers to use on *their* components, and a published
+ * package should not drag a test framework into an app's dependency
+ * graph to do it. Plain `Error`s with actionable messages work in a
+ * story `play`, in Vitest, in Playwright, and in a scratch script.
+ */
+
+/**
+ * The subset of a testing-library query object this needs —
+ * structural, so Storybook's `canvas`, a `within(element)` result,
+ * and `screen` all satisfy it without an import.
+ */
+export type AgentQueries = {
+  queryAllByRole: (
+    role: string,
+    options?: { name?: RegExp | string },
+  ) => HTMLElement[]
+}
+
+export type AgentTarget = {
+  name?: RegExp | string
+  role: string
+}
+
+const describeTarget = ({ name, role }: AgentTarget) =>
+  name === undefined
+    ? `role "${role}"`
+    : `role "${role}" named ${
+        typeof name === "string"
+          ? `"${name}"`
+          : String(name)
+      }`
+
+/**
+ * The composite widgets whose members are *supposed* to carry
+ * `tabindex="-1"`.
+ *
+ * Found by M4. `Tabs` is the first component here to use the
+ * roving-tabindex pattern, and this helper rejected it outright:
+ * "has a negative tabindex, so it can be clicked but never reached
+ * with Tab". That rule is right for a standalone button and wrong
+ * for a tab — a roving group's whole design is that exactly one
+ * member is in the tab order and the arrow keys reach the rest, so
+ * a tab list where every tab had `tabindex="0"` would be the bug.
+ *
+ * So the check is not skipped for these; it is **replaced by the
+ * roving rule itself**, which is a stronger assertion than the one
+ * it stands in for.
+ */
+const COMPOSITE_ROLES = new Set([
+  "grid",
+  "listbox",
+  "menu",
+  "menubar",
+  "radiogroup",
+  "tablist",
+  "toolbar",
+  "tree",
+  "treegrid",
+])
+
+const COMPOSITE_MEMBER_ROLES = new Set([
+  "gridcell",
+  "menuitem",
+  "menuitemcheckbox",
+  "menuitemradio",
+  "option",
+  "radio",
+  "tab",
+  "treeitem",
+])
+
+const getCompositeGroup = (element: Element) => {
+  if (
+    !COMPOSITE_MEMBER_ROLES.has(
+      element.getAttribute("role") ?? "",
+    )
+  ) {
+    return null
+  }
+
+  let current = element.parentElement
+
+  while (current) {
+    if (
+      COMPOSITE_ROLES.has(
+        current.getAttribute("role") ?? "",
+      )
+    ) {
+      return current
+    }
+
+    current = current.parentElement
+  }
+
+  return null
+}
+
+const getIsHiddenFromAgents = (element: Element) => {
+  let current: Element | null = element
+
+  while (current) {
+    if (
+      current.getAttribute("aria-hidden") === "true" ||
+      current.hasAttribute("inert")
+    ) {
+      return true
+    }
+
+    current = current.parentElement
+  }
+
+  return false
+}
+
+/**
+ * Asserts the control an agent would reach for is reachable, unique,
+ * and keyboard-operable. Returns it, so a caller can go on to assert
+ * something specific about it.
+ */
+export const expectAgentDrivable = (
+  canvas: AgentQueries,
+  target: AgentTarget,
+): HTMLElement => {
+  const matches = canvas.queryAllByRole(
+    target.role,
+    target.name === undefined
+      ? undefined
+      : { name: target.name },
+  )
+
+  if (matches.length === 0) {
+    throw new Error(
+      `Not agent-drivable: nothing matches ${describeTarget(
+        target,
+      )}. An agent cannot click what it cannot name — give the control an accessible name (visible text, \`aria-label\`, or a \`VisuallyHidden\` label) rather than a \`data-testid\`.`,
+    )
+  }
+
+  // Ambiguity is a failure, not a warning. Two "Start" buttons on a
+  // page mean an agent picks one at random, which is worse than not
+  // finding either — and the fix is a `Card` heading turning each
+  // one into its own `region`.
+  if (matches.length > 1) {
+    throw new Error(
+      `Not agent-drivable: ${
+        matches.length
+      } elements match ${describeTarget(
+        target,
+      )}. Scope them — a labelled region per group — or make the names distinct.`,
+    )
+  }
+
+  const [element] = matches
+
+  if (!element) {
+    throw new Error(
+      `Not agent-drivable: ${describeTarget(
+        target,
+      )} matched an empty element.`,
+    )
+  }
+
+  if (getIsHiddenFromAgents(element)) {
+    throw new Error(
+      `Not agent-drivable: ${describeTarget(
+        target,
+      )} is inside an \`aria-hidden\` or \`inert\` subtree, so a real screen reader and a real agent both skip it.`,
+    )
+  }
+
+  if (element.querySelector("[data-testid]")) {
+    throw new Error(
+      `\`data-testid\` found inside ${describeTarget(
+        target,
+      )}. This library has none by rule: a testid is a name only the test suite can see, which is exactly the gap that leaves an app untestable by an agent.`,
+    )
+  }
+
+  const isNativelyInteractive = [
+    "a",
+    "button",
+    "input",
+    "select",
+    "textarea",
+  ].includes(element.tagName.toLowerCase())
+
+  const isDisabled =
+    element.hasAttribute("disabled") ||
+    element.getAttribute("aria-disabled") === "true"
+
+  if (
+    isNativelyInteractive &&
+    !isDisabled &&
+    element.tabIndex < 0
+  ) {
+    const group = getCompositeGroup(element)
+
+    if (!group) {
+      throw new Error(
+        `Not agent-drivable: ${describeTarget(
+          target,
+        )} has a negative tabindex, so it can be clicked but never reached with Tab.`,
+      )
+    }
+
+    // A roving group, so the question changes: not "is this
+    // element in the tab order" — it must not be — but "is the
+    // *group* reachable, exactly once". Zero tab stops strands the
+    // whole widget; several put every member back in the tab
+    // order, which is the pattern not being implemented at all.
+    const tabStops = Array.from(
+      group.querySelectorAll("[role]"),
+    ).filter(
+      (member) =>
+        COMPOSITE_MEMBER_ROLES.has(
+          member.getAttribute("role") ?? "",
+        ) &&
+        !member.hasAttribute("disabled") &&
+        member.getAttribute("aria-disabled") !== "true" &&
+        (member as HTMLElement).tabIndex >= 0,
+    )
+
+    if (tabStops.length !== 1) {
+      throw new Error(
+        `Not agent-drivable: ${describeTarget(
+          target,
+        )} is inside a \`${group.getAttribute(
+          "role",
+        )}\` with ${
+          tabStops.length
+        } tab stops. A roving-tabindex group needs exactly one — Tab enters and leaves it once, and the arrow keys move within it.`,
+      )
+    }
+  }
+
+  return element
+}
+
+/**
+ * The other half of the contract, for decoration.
+ *
+ * A `Skeleton` that assistive technology can see is a screen reader
+ * reading three empty bars, and an agent finding a "loading" element
+ * it cannot act on. Asserting the *absence* of a role is how that
+ * stays true — axe will not tell you, because there is nothing
+ * invalid about it.
+ */
+export const expectHiddenFromAgents = (
+  element: Element,
+): void => {
+  if (!getIsHiddenFromAgents(element)) {
+    throw new Error(
+      'Expected this element to be hidden from assistive technology (`aria-hidden="true"` or `inert`). Decoration that is announced is noise: the load has to be announced by the region that owns it, not by its placeholder.',
+    )
+  }
+}