@charcuterie/ui 0.1.0

package/dist/testing/expectAgentDrivable.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 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;
+};
+/**
+ * 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 declare const expectAgentDrivable: (canvas: AgentQueries, target: AgentTarget) => HTMLElement;
+/**
+ * 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 declare const expectHiddenFromAgents: (element: Element) => void;
+//# sourceMappingURL=expectAgentDrivable.d.ts.map

package/dist/testing/expectAgentDrivable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expectAgentDrivable.d.ts","sourceRoot":"","sources":["../../src/testing/expectAgentDrivable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,cAAc,EAAE,CACd,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,KACjC,WAAW,EAAE,CAAA;CACnB,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IACtB,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AA6FD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAC9B,QAAQ,YAAY,EACpB,QAAQ,WAAW,KAClB,WAkHF,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,GACjC,SAAS,OAAO,KACf,IAMF,CAAA"}

package/dist/testing/expectAgentDrivable.js

@@ -0,0 +1,163 @@
+/**
+ * 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.
+ */
+const describeTarget = ({ name, role }) => 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) => {
+    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) => {
+    let current = 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, target) => {
+    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.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) => {
+    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.');
+    }
+};
+//# sourceMappingURL=expectAgentDrivable.js.map

package/dist/testing/expectAgentDrivable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expectAgentDrivable.js","sourceRoot":"","sources":["../../src/testing/expectAgentDrivable.ts"],"names":[],"mappings":"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"}

package/dist/testing/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@charcuterie/ui/testing` — the drivability gates, shipped so
+ * consumers can hold their own components to them.
+ *
+ * A separate entry point rather than part of the barrel: nothing
+ * here belongs in an app's production bundle, and a deep import is
+ * what keeps it out without a build-time trick.
+ */
+export type { AgentQueries, AgentTarget, } from "./expectAgentDrivable.ts";
+export { expectAgentDrivable, expectHiddenFromAgents, } from "./expectAgentDrivable.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,YAAY,EACV,YAAY,EACZ,WAAW,GACZ,MAAM,0BAA0B,CAAA;AACjC,OAAO,EACL,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,0BAA0B,CAAA"}

package/dist/testing/index.js

@@ -0,0 +1,10 @@
+/**
+ * `@charcuterie/ui/testing` — the drivability gates, shipped so
+ * consumers can hold their own components to them.
+ *
+ * A separate entry point rather than part of the barrel: nothing
+ * here belongs in an app's production bundle, and a deep import is
+ * what keeps it out without a build-time trick.
+ */
+export { expectAgentDrivable, expectHiddenFromAgents, } from "./expectAgentDrivable.js";
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,EACL,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,0BAA0B,CAAA"}

package/dist/toClassName.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Filter-and-join. Deliberately not `clsx`.
+ *
+ * Every call site in this package passes a flat list of strings and
+ * conditionals, which is four lines of work — and a published
+ * component library's dependency list is a thing consumers inherit,
+ * so it earns its entries. `clsx` also accepts objects and nested
+ * arrays, both of which make a className harder for the Tailwind
+ * scanner and for `tailwindCandidates.test.ts` to read statically.
+ */
+export declare const toClassName: (...parts: (false | string | null | undefined)[]) => string;
+//# sourceMappingURL=toClassName.d.ts.map

package/dist/toClassName.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toClassName.d.ts","sourceRoot":"","sources":["../src/toClassName.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,GACtB,GAAG,OAAO,CAAC,KAAK,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,WACb,CAAA"}

package/dist/toClassName.js

@@ -0,0 +1,12 @@
+/**
+ * Filter-and-join. Deliberately not `clsx`.
+ *
+ * Every call site in this package passes a flat list of strings and
+ * conditionals, which is four lines of work — and a published
+ * component library's dependency list is a thing consumers inherit,
+ * so it earns its entries. `clsx` also accepts objects and nested
+ * arrays, both of which make a className harder for the Tailwind
+ * scanner and for `tailwindCandidates.test.ts` to read statically.
+ */
+export const toClassName = (...parts) => parts.filter(Boolean).join(" ");
+//# sourceMappingURL=toClassName.js.map

package/dist/toClassName.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toClassName.js","sourceRoot":"","sources":["../src/toClassName.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CACzB,GAAG,KAA4C,EAC/C,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA"}

package/dist/tokens.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `@charcuterie/ui/tokens` — the tokens, under the name a React
+ * consumer already has installed.
+ *
+ * The build-graph split between `tokens` and `ui` exists for two
+ * consumers that cannot take a React tree: `castkit/packages/views`
+ * renders through Satori and needs resolved literals, and
+ * `slatecast` has 60 KB gz to spend. Neither should have to install
+ * `@charcuterie/ui` to read a colour.
+ *
+ * That is a build-graph split, **not an API split** — so a React app
+ * importing `@charcuterie/ui` gets the tokens from the same package
+ * name and never has to know the boundary exists.
+ */
+export * from "@charcuterie/tokens";
+//# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,cAAc,qBAAqB,CAAA"}

package/dist/tokens.js

@@ -0,0 +1,16 @@
+/**
+ * `@charcuterie/ui/tokens` — the tokens, under the name a React
+ * consumer already has installed.
+ *
+ * The build-graph split between `tokens` and `ui` exists for two
+ * consumers that cannot take a React tree: `castkit/packages/views`
+ * renders through Satori and needs resolved literals, and
+ * `slatecast` has 60 KB gz to spend. Neither should have to install
+ * `@charcuterie/ui` to read a colour.
+ *
+ * That is a build-graph split, **not an API split** — so a React app
+ * importing `@charcuterie/ui` gets the tokens from the same package
+ * name and never has to know the boundary exists.
+ */
+export * from "@charcuterie/tokens";
+//# sourceMappingURL=tokens.js.map

package/dist/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,cAAc,qBAAqB,CAAA"}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@charcuterie/ui",
+  "version": "0.1.0",
+  "description": "The Charcuterie components. Tokens for look, @charcuterie/logic for state, ARIA that agents can actually drive.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./styles.css": "./dist/styles.css",
+    "./testing": {
+      "source": "./src/testing/index.ts",
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    },
+    "./tokens": {
+      "source": "./src/tokens.ts",
+      "types": "./dist/tokens.d.ts",
+      "default": "./dist/tokens.js"
+    },
+    "./src/*": "./src/*"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node scripts/copyStyles.ts",
+    "prepack": "yarn build",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@charcuterie/logic": "0.1.0",
+    "@charcuterie/tokens": "0.1.0",
+    "@floating-ui/react": "^0.27.20"
+  },
+  "peerDependencies": {
+    "react": ">=19",
+    "react-dom": ">=19"
+  },
+  "devDependencies": {
+    "@storybook/react": "^10.3.6",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "storybook": "^10.3.6",
+    "tailwindcss": "^4.3.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Sawtaytoes/charcuterie.git",
+    "directory": "packages/ui"
+  }
+}

package/src/Alert/Alert.mdx

@@ -0,0 +1,70 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as AlertStories from "./Alert.stories";
+
+<Meta of={AlertStories} />
+
+# Alert
+
+**The component M5 found, rather than one the plan predicted.** rip-deck spells this shape
+four times — `TowerAlerts`, `UsbAlertBanner`, `LoadedDiscsBanner`, `VerdictBadge` — and two
+of those carry a byte-identical `TONE_CLASS` map of hardcoded hexes with no light mode.
+mux-magic spells the same idea a third way in `statusClassMap`.
+
+<Canvas of={AlertStories.Default} />
+
+## Props
+
+<Controls />
+
+<Canvas of={AlertStories.AllVariants} />
+
+## It is a block by default, and a landmark only when named
+
+`label` decides, and the evidence divides cleanly.
+
+The **banners** are one alert at the top of a page and want to be addressable —
+`getByRole("region", { name: "USB connection alert" })`. They pass a `label`.
+
+The **verdict** renders inside every bay card, and one of its two forms is the single
+sentence *"Part of the tower-wide problem above."* Nine landmarks sharing one name is axe's
+`landmark-unique`, so it passes none.
+
+A component that always took the landmark would fail its own a11y gate on a nine-bay tower.
+One that never took it leaves three `<section aria-label>` wrappers hand-rolled in the
+consumer — which is what rip-deck has today.
+
+<Canvas of={AlertStories.AllStates} />
+
+## The heading is not a heading element
+
+An alert's headline is a **sentence** — "Bay 7 is reading with errors; clean the disc and
+try again" — not a node in the document outline. Nine bays' worth of those as `<h3>`s
+builds a table of contents out of nine complaints, which is worse for a screen reader than
+no outline entry at all.
+
+`Card` and `EmptyState` take a real `headingLevel` precisely because their headings *are*
+short outline nodes. This one is styled text, and `label` is how it becomes findable.
+
+## It does not announce, and that is a component boundary
+
+No `role="alert"`, no `aria-live`. Two reasons, and the second is the load-bearing one:
+
+1. A live region takes **no accessible name from its content**
+   ([decision](../../../docs/decisions/2026-07-29-status-regions-carry-an-aria-label.md)),
+   so an announcing variant needs a name that duplicates the sentence it is announcing.
+2. `role="alert"` on a `<section>` **overrides the landmark**. It cannot be both a thing
+   you can scope queries to and a thing that interrupts you.
+
+A thing that interrupts you is a `Toast` (M6). This is a thing that is *on the page*.
+
+<Canvas of={AlertStories.Responsive} />
+
+## The evidence is a list
+
+`details` renders a `<ul>`, so a screen reader announces "list, 3 items" instead of running
+three measurements together into one sentence. The key is `${index}-${line}` rather than
+the line itself, because **evidence repeats**: two drives both reporting "3 read errors" is
+the normal case on a tower, not an edge one.
+
+<Canvas of={AlertStories.Interactive} />