@charcuterie/ui 0.1.0

package/src/intentStyles.ts

@@ -0,0 +1,207 @@
+/**
+ * One intent → class map, for the whole fleet.
+ *
+ * This file is what M5 deletes from rip-deck. `TONE_CLASS` is
+ * declared *identically* in `VerdictBadge.tsx` and
+ * `TowerAlerts.tsx` today — hardcoded hexes and `slate-400`s, no
+ * light mode, no relationship to mux-magic's `statusClassMap` which
+ * spells the same idea a fourth way. Six intents x four
+ * appearances, named once, is the generalisation.
+ *
+ * **Every class name is written out in full, and that is not
+ * negotiable.** Tailwind v4 scans source text for *complete* class
+ * strings, so `` `bg-intent-${intent}-solid` `` generates nothing
+ * at all — the element renders unstyled with no error, no warning,
+ * and no failing test unless something checks. Something does:
+ * `tailwindCandidates.test.ts` compiles every literal in this
+ * package through the real Tailwind and fails on any candidate
+ * Tailwind cannot generate. That test is the reason this file is
+ * allowed to be 24 lines of near-duplication instead of a loop.
+ */
+
+import type { IntentName } from "@charcuterie/tokens"
+
+/**
+ * Four treatments, and the split is semantic rather than cosmetic:
+ *
+ *  - `solid` — the saturated fill. One per view, usually; it is the
+ *    thing you are meant to press.
+ *  - `soft` — the tinted treatment the fleet already reaches for on
+ *    status pills (`bg-blue-950 text-blue-300` in mux-magic,
+ *    `bg-amber-950/40 text-amber-200` in rip-deck).
+ *  - `outline` — border and content only. Reads as secondary
+ *    without claiming a surface.
+ *  - `ghost` — nothing until hovered. Toolbars and icon rows.
+ */
+export type IntentAppearance =
+  | "ghost"
+  | "outline"
+  | "soft"
+  | "solid"
+
+export const INTENT_APPEARANCE_CLASS: Record<
+  IntentName,
+  Record<IntentAppearance, string>
+> = {
+  neutral: {
+    ghost:
+      "border-transparent bg-transparent text-content-primary",
+    outline:
+      "border-intent-neutral-border bg-transparent text-intent-neutral-content",
+    soft: "border-intent-neutral-border bg-intent-neutral-surface text-intent-neutral-content",
+    solid:
+      "border-transparent bg-intent-neutral-solid text-intent-neutral-on-solid",
+  },
+  accent: {
+    ghost:
+      "border-transparent bg-transparent text-intent-accent-content",
+    outline:
+      "border-intent-accent-border bg-transparent text-intent-accent-content",
+    soft: "border-intent-accent-border bg-intent-accent-surface text-intent-accent-content",
+    solid:
+      "border-transparent bg-intent-accent-solid text-intent-accent-on-solid",
+  },
+  success: {
+    ghost:
+      "border-transparent bg-transparent text-intent-success-content",
+    outline:
+      "border-intent-success-border bg-transparent text-intent-success-content",
+    soft: "border-intent-success-border bg-intent-success-surface text-intent-success-content",
+    solid:
+      "border-transparent bg-intent-success-solid text-intent-success-on-solid",
+  },
+  warning: {
+    ghost:
+      "border-transparent bg-transparent text-intent-warning-content",
+    outline:
+      "border-intent-warning-border bg-transparent text-intent-warning-content",
+    soft: "border-intent-warning-border bg-intent-warning-surface text-intent-warning-content",
+    solid:
+      "border-transparent bg-intent-warning-solid text-intent-warning-on-solid",
+  },
+  danger: {
+    ghost:
+      "border-transparent bg-transparent text-intent-danger-content",
+    outline:
+      "border-intent-danger-border bg-transparent text-intent-danger-content",
+    soft: "border-intent-danger-border bg-intent-danger-surface text-intent-danger-content",
+    solid:
+      "border-transparent bg-intent-danger-solid text-intent-danger-on-solid",
+  },
+  info: {
+    ghost:
+      "border-transparent bg-transparent text-intent-info-content",
+    outline:
+      "border-intent-info-border bg-transparent text-intent-info-content",
+    soft: "border-intent-info-border bg-intent-info-surface text-intent-info-content",
+    solid:
+      "border-transparent bg-intent-info-solid text-intent-info-on-solid",
+  },
+}
+
+/**
+ * Hover, split out rather than folded into the appearance above —
+ * because most things wearing an intent are **not** interactive.
+ *
+ * A `Badge` that lightens under the cursor is telling the user it
+ * can be clicked, and rip-deck's verdict pills (which cannot) would
+ * inherit exactly that if the two maps were one. So an interactive
+ * component opts in, and a static one cannot accidentally opt in.
+ *
+ * `solid` hovers toward `solidHover`; the other three land on the
+ * intent's tinted surface, which is what gives a ghost toolbar
+ * button something to become.
+ */
+export const INTENT_HOVER_CLASS: Record<
+  IntentName,
+  Record<IntentAppearance, string>
+> = {
+  neutral: {
+    ghost: "hover:bg-intent-neutral-surface",
+    outline: "hover:bg-intent-neutral-surface",
+    soft: "hover:bg-intent-neutral-surface-hover",
+    solid: "hover:bg-intent-neutral-solid-hover",
+  },
+  accent: {
+    ghost: "hover:bg-intent-accent-surface",
+    outline: "hover:bg-intent-accent-surface",
+    soft: "hover:bg-intent-accent-surface-hover",
+    solid: "hover:bg-intent-accent-solid-hover",
+  },
+  success: {
+    ghost: "hover:bg-intent-success-surface",
+    outline: "hover:bg-intent-success-surface",
+    soft: "hover:bg-intent-success-surface-hover",
+    solid: "hover:bg-intent-success-solid-hover",
+  },
+  warning: {
+    ghost: "hover:bg-intent-warning-surface",
+    outline: "hover:bg-intent-warning-surface",
+    soft: "hover:bg-intent-warning-surface-hover",
+    solid: "hover:bg-intent-warning-solid-hover",
+  },
+  danger: {
+    ghost: "hover:bg-intent-danger-surface",
+    outline: "hover:bg-intent-danger-surface",
+    soft: "hover:bg-intent-danger-surface-hover",
+    solid: "hover:bg-intent-danger-solid-hover",
+  },
+  info: {
+    ghost: "hover:bg-intent-info-surface",
+    outline: "hover:bg-intent-info-surface",
+    soft: "hover:bg-intent-info-surface-hover",
+    solid: "hover:bg-intent-info-solid-hover",
+  },
+}
+
+/**
+ * The fill colour on its own, for the parts of a component that are
+ * a bar or a dot rather than a box — a `ProgressBar`'s fill, a
+ * `LiveStatusIndicator`'s dot. Same values, no border and no hover,
+ * because neither of those is a surface anyone can point at.
+ */
+export const INTENT_SOLID_FILL_CLASS: Record<
+  IntentName,
+  string
+> = {
+  neutral: "bg-intent-neutral-solid",
+  accent: "bg-intent-accent-solid",
+  success: "bg-intent-success-solid",
+  warning: "bg-intent-warning-solid",
+  danger: "bg-intent-danger-solid",
+  info: "bg-intent-info-solid",
+}
+
+/** The same six as text, for a glyph or a dot's ring. */
+export const INTENT_CONTENT_CLASS: Record<
+  IntentName,
+  string
+> = {
+  neutral: "text-intent-neutral-content",
+  accent: "text-intent-accent-content",
+  success: "text-intent-success-content",
+  warning: "text-intent-warning-content",
+  danger: "text-intent-danger-content",
+  info: "text-intent-info-content",
+}
+
+/**
+ * The focus ring, in one place, reading the variant's own width and
+ * offset.
+ *
+ * `focus-visible` rather than `focus`: a mouse click on a button
+ * should not leave a ring behind, and every hand-rolled button in
+ * the inventory either rings on click or — more often — has
+ * `outline-none` with nothing put back.
+ */
+export const FOCUS_RING_CLASS =
+  "focus-visible:outline-solid focus-visible:outline-(length:--focus-ring-width) focus-visible:outline-offset-(--focus-ring-offset) focus-visible:outline-focus-ring"
+
+/**
+ * WCAG 1.4.3 exempts *inactive* controls from contrast, which is
+ * the only reason `content.disabled` is allowed to be this quiet —
+ * and the exemption is honest only on something actually disabled.
+ * Keeping it in one constant is what stops it drifting onto prose.
+ */
+export const DISABLED_CLASS =
+  "disabled:cursor-not-allowed disabled:border-border-subtle disabled:bg-surface-sunken disabled:text-content-disabled disabled:shadow-none"

package/src/mdxReferences.test.ts

@@ -0,0 +1,95 @@
+/**
+ * Every `<Canvas of={XStories.Y} />` in an `.mdx` names a story that
+ * still exists.
+ *
+ * A missing one does not fail the build, does not fail typecheck,
+ * and does not fail `vitest` — MDX resolves `of` at *runtime*, so a
+ * renamed story turns into `of={undefined}` and the docs page
+ * renders Storybook's "component failed to render" panel instead of
+ * the page. `yarn smoke:storybook` catches it, which is good, but
+ * only after a full Storybook build; this catches it in under a
+ * second, which is the difference between noticing during the edit
+ * and noticing in CI.
+ *
+ * Found the expensive way: the M4 story/test split renamed
+ * `Tabs.Interactive` to `Tabs.Manual` and deleted three
+ * assertion-only stories, and every gate stayed green while
+ * `Components/Tabs › Docs` was broken.
+ */
+
+import { readdir, readFile } from "node:fs/promises"
+import { join, resolve } from "node:path"
+
+import { expect, test } from "vitest"
+
+const sourceDirectory = resolve(import.meta.dirname)
+
+const componentNames = (
+  await readdir(sourceDirectory, { withFileTypes: true })
+)
+  .filter(
+    (entry) =>
+      entry.isDirectory() && /^[A-Z]/.test(entry.name),
+  )
+  .map((entry) => entry.name)
+  .sort()
+
+const readIfPresent = async (path: string) => {
+  try {
+    return await readFile(path, "utf8")
+  } catch {
+    return undefined
+  }
+}
+
+const documented = (
+  await Promise.all(
+    componentNames.map(async (name) => {
+      const [mdx, story] = await Promise.all([
+        readIfPresent(
+          join(sourceDirectory, name, `${name}.mdx`),
+        ),
+        readIfPresent(
+          join(
+            sourceDirectory,
+            name,
+            `${name}.stories.tsx`,
+          ),
+        ),
+      ])
+
+      return mdx && story ? [{ mdx, name, story }] : []
+    }),
+  )
+).flat()
+
+test("every component with stories has a docs page", () => {
+  // A canary on the derivation — an empty list would make the rule
+  // below pass forever.
+  expect(documented.length).toBeGreaterThanOrEqual(14)
+})
+
+test("no docs page references a story that no longer exists", () => {
+  const offenders = documented.flatMap(
+    ({ mdx, name, story }) => {
+      const exported = new Set(
+        Array.from(
+          story.matchAll(/^export const (\w+): Story/gm),
+          (match) => match[1],
+        ),
+      )
+
+      return Array.from(
+        mdx.matchAll(/of=\{\w+Stories\.(\w+)\}/g),
+        (match) => match[1],
+      )
+        .filter((reference) => !exported.has(reference))
+        .map(
+          (reference) =>
+            `${name}.mdx references ${name}Stories.${reference}, which is not exported`,
+        )
+    },
+  )
+
+  expect(offenders).toEqual([])
+})

package/src/mountStory.testHelpers.ts

@@ -0,0 +1,41 @@
+import { within } from "storybook/test"
+
+type Canvas = ReturnType<typeof within>
+
+/**
+ * Structural on purpose — the one thing this helper needs off a
+ * composed story. `ComposedStoryFn` is invariant in its `Args`, so
+ * naming it here would force every caller to restate the props of
+ * the component it is testing.
+ */
+type MountableStory = {
+  run: (context: {
+    canvasElement: HTMLElement
+  }) => Promise<void>
+}
+
+/**
+ * Mount a composed story into a fresh canvas and hand back the same
+ * two things a `play` function used to receive.
+ *
+ * `run()` — rather than rendering the component directly — is what
+ * keeps these tests honest after the story/test split: the subject
+ * is the story a reader sees, with its args, its decorators, and its
+ * loaders, not a second assembly of the same component that can
+ * drift from it. It is also what triggers the a11y addon's
+ * `afterEach`, so every mount here is an axe run.
+ */
+export const mountStory = async (
+  story: MountableStory,
+): Promise<{
+  canvas: Canvas
+  canvasElement: HTMLElement
+}> => {
+  const canvasElement = document.createElement("div")
+
+  document.body.append(canvasElement)
+
+  await story.run({ canvasElement })
+
+  return { canvas: within(canvasElement), canvasElement }
+}

package/src/sourceRules.test.ts

@@ -0,0 +1,303 @@
+/**
+ * The three rules about this package's source that no compiler and no
+ * axe run can see.
+ *
+ * All three come straight from the plan's verification list, and each
+ * one is a thing the fleet does today that the library exists to
+ * stop.
+ */
+
+import { readdir, readFile } from "node:fs/promises"
+import { join, relative, resolve } from "node:path"
+
+import { expect, test } from "vitest"
+
+const sourceDirectory = resolve(import.meta.dirname)
+
+const packageDirectory = resolve(sourceDirectory, "..")
+
+const getSourceFiles = async (
+  directory: string,
+): Promise<{ contents: string; file: string }[]> => {
+  const entries = await readdir(directory, {
+    withFileTypes: true,
+  })
+
+  const files = await Promise.all(
+    entries.map(async (entry) => {
+      const path = join(directory, entry.name)
+
+      if (entry.isDirectory()) {
+        return getSourceFiles(path)
+      }
+
+      if (!/\.(css|tsx?)$/.test(entry.name)) {
+        return []
+      }
+
+      return [
+        {
+          contents: await readFile(path, "utf8"),
+          file: relative(sourceDirectory, path),
+        },
+      ]
+    }),
+  )
+
+  return files.flat()
+}
+
+const sourceFiles = await getSourceFiles(sourceDirectory)
+
+const componentFiles = sourceFiles.filter(
+  (one) =>
+    !one.file.endsWith(".test.ts") &&
+    !one.file.endsWith(".test.tsx"),
+)
+
+/**
+ * Comments are prose about the fleet, not code. `intentStyles.ts`
+ * quotes mux-magic's `bg-blue-950 text-blue-300` as the evidence for
+ * the intent scale existing at all, and a rule that cannot tell a
+ * citation from a usage is a rule that gets switched off.
+ */
+const stripComments = (contents: string) =>
+  contents
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/^\s*\/\/.*$/gm, "")
+
+test("`data-testid` appears nowhere in @charcuterie/ui", () => {
+  // A rule, not a preference. A testid is a name only the test suite
+  // can see, so reaching for one is how a component ends up
+  // unnameable by a screen reader *and* undrivable by an agent — the
+  // exact gap that makes the fleet's current UIs unautomatable. If a
+  // control is hard to query, the fix is an accessible name.
+  // `data-testid=` — the attribute in *use*. `testing/` mentions the
+  // name in a selector and an error message, which is the opposite
+  // of the offence; and this file has to spell it to search for it,
+  // which is why the scan is over shipped source and stories rather
+  // than over the tests.
+  const offenders = componentFiles
+    .filter((one) => /data-testid=/.test(one.contents))
+    .map((one) => one.file)
+
+  expect(offenders).toEqual([])
+})
+
+test("no component reaches past tier 2 for a colour", () => {
+  // The M6 problem, prevented here rather than repeated: mux-magic
+  // has **993 hardcoded `*-slate-*` utilities across 134 files**, and
+  // every one of them is why that app cannot have a light mode. A
+  // component may name a semantic role — `bg-surface-raised`,
+  // `text-intent-danger-content` — and nothing else.
+  //
+  // Tier 1 ramps (`colour.slate.500`) exist so a *variant author*
+  // has something to build tier 2 out of. A component naming one
+  // pins itself to a palette.
+  const palettePattern =
+    /\b(?:bg|text|border|from|to|via|outline|ring|fill|stroke|shadow|decoration|accent|caret|divide)-(?:slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-\d{2,3}\b/
+
+  const hexPattern = /#[0-9a-fA-F]{3,8}\b/
+
+  const offenders = componentFiles
+    .filter(
+      (one) =>
+        // The story fixtures are allowed literal hexes: the SVG
+        // poster data-URI in `MediaTile.stories.tsx` is a stand-in
+        // for an app's own image, not component styling.
+        !one.file.endsWith(".stories.tsx"),
+    )
+    .filter((one) => {
+      const code = stripComments(one.contents)
+
+      return (
+        palettePattern.test(code) || hexPattern.test(code)
+      )
+    })
+    .map((one) => one.file)
+
+  expect(offenders).toEqual([])
+})
+
+test("nothing queries a container it declares itself", () => {
+  // A container query matches **descendants of the container**, never
+  // the container element. So `className="@container cq-md:px-8"`
+  // compiles, generates real CSS, passes `tailwindCandidates.test.ts`
+  // — and never fires. Nothing errors; the padding is simply always
+  // the small one, forever.
+  //
+  // Caught here because it is invisible everywhere else: axe does not
+  // care, the class exists, and a reviewer sees a plausible-looking
+  // className. It cost this milestone one round of screenshots.
+  const offenders = componentFiles
+    .filter((one) => /\.tsx$/.test(one.file))
+    .flatMap((one) => {
+      const classStrings =
+        stripComments(one.contents).match(/"[^"\n]*"/g) ??
+        []
+
+      return classStrings
+        .filter(
+          (candidate) =>
+            candidate.includes("@container") &&
+            /\bcq-(?:xs|sm|md|lg|xl):/.test(candidate),
+        )
+        .map((candidate) => `${one.file}: ${candidate}`)
+    })
+
+  expect(offenders).toEqual([])
+})
+
+test("a container-query component is never storied in a shrink-to-fit cell", () => {
+  // The twin of the rule above, and the one the M3 screenshots
+  // actually caught: the component is right, the *story* is wrong.
+  //
+  // `container-type: inline-size` implies `contain: inline-size`,
+  // which forbids the element from being sized by its own contents.
+  // In a default `StoryCell` — `items-start`, so shrink-to-fit — the
+  // card has no width to shrink *to*, collapses to min-content, and
+  // every line of text wraps after one word. Valid CSS, no error, no
+  // axe violation, and it only shows up if somebody looks at a
+  // screenshot. `align="stretch"` hands it a definite inline size
+  // from the grid track.
+  //
+  // The container list is derived rather than hardcoded, so the
+  // component M4 adds with an `@container` on it joins this rule the
+  // moment it lands.
+  const containerComponents = componentFiles
+    .flatMap((one) => {
+      const match = /^([A-Z]\w+)\/\1\.tsx$/.exec(one.file)
+
+      return match?.[1] &&
+        stripComments(one.contents).includes("@container")
+        ? [match[1]]
+        : []
+    })
+    .sort()
+
+  // A canary on the derivation itself: if this ever comes back
+  // empty the rule silently passes forever.
+  expect(containerComponents).toEqual([
+    "Alert",
+    "Card",
+    "EmptyState",
+    "MediaTile",
+  ])
+
+  // `StoryCell`s are never nested, so the lazy match really does
+  // pair each opening tag with its own closing one.
+  const cellPattern =
+    /<StoryCell\b([^>]*)>([\s\S]*?)<\/StoryCell>/g
+
+  const offenders = componentFiles
+    .filter((one) => one.file.endsWith(".stories.tsx"))
+    .flatMap((one) =>
+      Array.from(
+        stripComments(one.contents).matchAll(cellPattern),
+      )
+        .filter(
+          ([, attributes, body]) =>
+            !attributes.includes('align="stretch"') &&
+            containerComponents.some((name) =>
+              body.includes(`<${name}`),
+            ),
+        )
+        .map(
+          ([, attributes]) =>
+            `${one.file}: <StoryCell${attributes}>`,
+        ),
+    )
+
+  expect(offenders).toEqual([])
+})
+
+test("the barrel is the only place components are re-exported", async () => {
+  // One sanctioned barrel per package. A component importing a
+  // sibling *through* `index.ts` turns every component into a
+  // dependency of every other one, which is how a 3 KB `Spinner`
+  // starts pulling in `MediaTile`.
+  const offenders = componentFiles
+    .filter((one) => one.file !== "index.ts")
+    .filter(
+      (one) =>
+        /from "\.\.?\/index\.ts"/.test(one.contents) ||
+        /from "@charcuterie\/ui"/.test(one.contents),
+    )
+    .map((one) => one.file)
+
+  expect(offenders).toEqual([])
+
+  // And the barrel really does export every component, so a new one
+  // cannot land unexported — which would make it invisible to every
+  // consumer while all its own tests pass.
+  const barrel = await readFile(
+    join(sourceDirectory, "index.ts"),
+    "utf8",
+  )
+
+  // `Button/Button.tsx` — the component files, as distinct from
+  // their stories and helpers.
+  const componentNames = componentFiles
+    .map((one) => /^([A-Z]\w+)\/\1\.tsx$/.exec(one.file))
+    .flatMap((match) => (match?.[1] ? [match[1]] : []))
+
+  // M3's ten P0 components, plus `VisuallyHidden` — a Layer-0
+  // primitive `Spinner`, `ProgressBar`, and `LiveStatusIndicator` all
+  // need, so it shipped here rather than being stubbed three times.
+  // M4 adds the three overlays: `Modal`, `Popover`, `Tabs`.
+  //
+  // M5 adds the two the first consumer proved were shared rather
+  // than app-specific: `Alert` (rip-deck spells it four times, twice
+  // with a byte-identical `TONE_CLASS`) and `SegmentedControl`.
+  //
+  // `TabTrigger` and `SegmentedOption` are deliberately not in this
+  // count and not exported. Each is its own component's member —
+  // its own file only because both registrations are effects and an
+  // effect cannot run in a loop — and the `<Name>/<Name>.tsx`
+  // pattern this regex matches is what keeps them out.
+  expect(componentNames.length).toBe(16)
+
+  for (const name of componentNames) {
+    expect(barrel).toContain(`export { ${name} }`)
+  }
+})
+
+test("dependency direction is tokens ← logic ← ui", async () => {
+  // CI-enforced by the plan, and this is the enforcement. `ui` may
+  // depend on both; `logic` may depend on `tokens`; `tokens` depends
+  // on nothing, which is what lets `castkit/packages/views` read a
+  // colour without a React tree.
+  const readPackage = async (name: string) =>
+    JSON.parse(
+      await readFile(
+        join(packageDirectory, "..", name, "package.json"),
+        "utf8",
+      ),
+    ) as {
+      dependencies?: Record<string, string>
+      peerDependencies?: Record<string, string>
+    }
+
+  const getCharcuterieDependencies = (manifest: {
+    dependencies?: Record<string, string>
+    peerDependencies?: Record<string, string>
+  }) =>
+    Object.keys({
+      ...manifest.dependencies,
+      ...manifest.peerDependencies,
+    }).filter((name) => name.startsWith("@charcuterie/"))
+
+  expect(
+    getCharcuterieDependencies(await readPackage("tokens")),
+  ).toEqual([])
+
+  expect(
+    getCharcuterieDependencies(await readPackage("logic")),
+  ).toEqual([])
+
+  expect(
+    getCharcuterieDependencies(
+      await readPackage("ui"),
+    ).sort(),
+  ).toEqual(["@charcuterie/logic", "@charcuterie/tokens"])
+})