@charcuterie/ui 0.1.0

package/src/board.storyHelpers.tsx

@@ -0,0 +1,150 @@
+import type { ReactNode } from "react"
+
+/**
+ * The furniture every story set uses: a labelled grid for
+ * `AllVariants`, a labelled row for `AllStates`, and the three
+ * container widths `Responsive` renders into.
+ *
+ * `.storyHelpers.tsx` rather than `.tsx` because `react/no-multi-comp`
+ * is switched off for that suffix — a file whose entire job is
+ * several small layout components is the case that rule exists to
+ * exempt, and it is excluded from the package build so none of this
+ * ships.
+ */
+
+export const StoryGrid = ({
+  children,
+  columns = 4,
+}: {
+  children: ReactNode
+  columns?: number
+}): ReactNode => (
+  <div
+    className="grid items-start gap-4"
+    style={{
+      gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))`,
+    }}
+  >
+    {children}
+  </div>
+)
+
+export const StoryCell = ({
+  align = "start",
+  children,
+  label,
+}: {
+  /**
+   * `stretch` for anything that establishes a **container query** —
+   * `Card`, `MediaTile`, `EmptyState`.
+   *
+   * Not a cosmetic choice. `container-type: inline-size` implies
+   * `contain: inline-size`, which means the element's inline size may
+   * not depend on its own contents — so in a shrink-to-fit context
+   * (`items-start`, an inline-flex parent) it collapses to
+   * min-content and every line of text wraps after one word. It
+   * needs a definite inline size from its parent, which a grid track
+   * gives it for free.
+   *
+   * The default stays `start`, because a `Button` in a stretched cell
+   * would silently become full-width and misrepresent itself.
+   */
+  align?: "start" | "stretch"
+  children: ReactNode
+  label: string
+}): ReactNode => (
+  <div
+    className={
+      align === "stretch"
+        ? "flex flex-col items-stretch gap-2"
+        : "flex flex-col items-start gap-2"
+    }
+  >
+    <span className="font-mono text-content-muted text-xs">
+      {label}
+    </span>
+
+    {children}
+  </div>
+)
+
+export const StoryRow = ({
+  children,
+}: {
+  children: ReactNode
+}): ReactNode => (
+  <div className="flex flex-wrap items-center gap-4">
+    {children}
+  </div>
+)
+
+export const StorySection = ({
+  children,
+  title,
+}: {
+  children: ReactNode
+  title: string
+}): ReactNode => (
+  <section className="flex flex-col gap-3">
+    <h3 className="font-semibold text-content-secondary text-sm">
+      {title}
+    </h3>
+
+    {children}
+  </section>
+)
+
+/**
+ * The three container widths, side by side.
+ *
+ * The **only honest way to story a container query**: resizing the
+ * viewport does not exercise one, because the component's container
+ * is what changed, not the window. Each panel is a fixed inline size
+ * matching a `--cq-*` step, so a `cq-sm:` utility flips between the
+ * first and second panel while the browser window never moves.
+ *
+ * The labels are the token names on purpose — a reviewer should be
+ * able to read "this is what the card does below `cq-sm`" straight
+ * off the board.
+ */
+export const ContainerBoard = ({
+  children,
+}: {
+  /**
+   * A function form as well as a node, because three copies of the
+   * same subtree can be an a11y violation rather than a convenience:
+   * two `<section>`s with the same accessible name is axe's
+   * `landmark-unique`, and a board comparing widths must not fail for
+   * a reason the component would never hit in an app. Callers whose
+   * component becomes a landmark pass a function and vary the name.
+   */
+  children: ReactNode | ((width: string) => ReactNode)
+}): ReactNode => (
+  <div className="flex flex-wrap items-start gap-6">
+    {[
+      {
+        inlineSize: "15rem",
+        label: "narrower than --cq-xs (15rem)",
+      },
+      { inlineSize: "24rem", label: "--cq-sm (24rem)" },
+      {
+        inlineSize: "34rem",
+        label: "wider than --cq-md (34rem)",
+      },
+    ].map((panel) => (
+      <div
+        className="flex flex-col gap-2"
+        key={panel.label}
+        style={{ inlineSize: panel.inlineSize }}
+      >
+        <span className="font-mono text-content-muted text-xs">
+          {panel.label}
+        </span>
+
+        {typeof children === "function"
+          ? children(panel.inlineSize)
+          : children}
+      </div>
+    ))}
+  </div>
+)

package/src/controlStyles.ts

@@ -0,0 +1,79 @@
+/**
+ * Control sizing, read from the density axis rather than chosen per
+ * component.
+ *
+ * The values are never in this file — `h-(--control-height-md)`
+ * points at a variable that `[data-density]` rewrites, so the same
+ * `<Button size="md">` is 2.25rem on a desktop, 1.875rem in a
+ * compact bay list, and 3.25rem on the kiosk with no prop change
+ * and no re-render. That is the entire argument for a density axis
+ * over a `size="kiosk"` prop, and it only works because nothing
+ * here hardcodes a length.
+ *
+ * `text-sm`/`text-md`/`text-lg` are ours too, not Tailwind's:
+ * `theme.css` bridges `--text-*` onto `--font-size-*`, which the
+ * density axis also scales. See
+ * `packages/tokens/src/tailwindCollisions.test.ts`.
+ */
+
+import type { ControlSize } from "@charcuterie/tokens"
+
+export const CONTROL_SIZE_CLASS: Record<
+  ControlSize,
+  string
+> = {
+  sm: "h-(--control-height-sm) gap-(--control-gap-sm) px-(--control-padding-inline-sm) text-sm",
+  md: "h-(--control-height-md) gap-(--control-gap-md) px-(--control-padding-inline-md) text-md",
+  lg: "h-(--control-height-lg) gap-(--control-gap-lg) px-(--control-padding-inline-lg) text-lg",
+}
+
+/**
+ * Square, and sized by the *height* token on both axes so an icon
+ * button lines up with the text button beside it in a toolbar. No
+ * inline padding at all — a glyph centres itself.
+ */
+export const ICON_CONTROL_SIZE_CLASS: Record<
+  ControlSize,
+  string
+> = {
+  sm: "size-(--control-height-sm) px-0 text-sm",
+  md: "size-(--control-height-md) px-0 text-md",
+  lg: "size-(--control-height-lg) px-0 text-lg",
+}
+
+/**
+ * The kiosk floor. `--control-min-touch-target` is 44px in every
+ * density — a finger does not get smaller because the list is
+ * dense — so this is opt-in per control rather than baked into the
+ * size classes, which would make `compact` a lie.
+ */
+export const MIN_TOUCH_TARGET_CLASS =
+  "min-h-(--control-min-touch-target) min-w-(--control-min-touch-target)"
+
+/**
+ * Non-control sizing: badges, indicator dots, spinners. These are
+ * type-relative on purpose — a badge beside `text-sm` prose that
+ * stays 20px tall while the kiosk scales the prose to 1.19x reads
+ * as a rendering bug.
+ */
+export const BADGE_SIZE_CLASS = {
+  sm: "gap-1 px-2 py-0.5 text-xs",
+  md: "gap-1.5 px-2.5 py-1 text-sm",
+} as const
+
+export type BadgeSize = keyof typeof BADGE_SIZE_CLASS
+
+export const DOT_SIZE_CLASS = {
+  sm: "size-1.5",
+  md: "size-2",
+  lg: "size-2.5",
+} as const
+
+export const SPINNER_SIZE_CLASS: Record<
+  ControlSize,
+  string
+> = {
+  sm: "size-3.5 border-2",
+  md: "size-4 border-2",
+  lg: "size-5 border-2",
+}

package/src/expectNoAxeViolations.testHelpers.ts

@@ -0,0 +1,41 @@
+import axe from "axe-core"
+
+/**
+ * Run axe against a subtree, now.
+ *
+ * The a11y addon audits a story **once**, in an `afterEach` that
+ * fires when `run()` resolves — i.e. immediately after the first
+ * paint. That was enough while the assertions lived in `play`,
+ * because the addon's hook ran after the play had finished driving.
+ * With the tests split out, `run()` returns before a test has
+ * clicked anything, so the states that most need auditing — an open
+ * dialog, a shown popover, a selected tab panel — would never be
+ * seen by axe at all.
+ *
+ * So a driven state audits itself explicitly. The rule set is left
+ * at axe's default, matching the addon, except that `region` is
+ * disabled for the same reason the addon disables it: a component
+ * mounted on its own is not a page and owes nobody a landmark.
+ */
+export const expectNoAxeViolations = async (
+  element: Element,
+): Promise<void> => {
+  const results = await axe.run(element, {
+    rules: { region: { enabled: false } },
+  })
+
+  if (results.violations.length === 0) {
+    return
+  }
+
+  throw new Error(
+    `Expected no accessibility violations, found ${results.violations.length}:\n\n${results.violations
+      .map(
+        (violation) =>
+          `  ${violation.id} (${violation.impact}) — ${violation.help}\n${violation.nodes
+            .map((node) => `    ${node.html}`)
+            .join("\n")}`,
+      )
+      .join("\n\n")}`,
+  )
+}

package/src/icons.storyHelpers.tsx

@@ -0,0 +1,116 @@
+import type { ReactNode } from "react"
+
+/**
+ * Story-only icons. **Nothing here ships.**
+ *
+ * The library deliberately owns no icon set — `IconButton`,
+ * `EmptyState`, `Badge`, and `MediaTile` all take a `ReactNode`, and
+ * lucide (ISC) is the fleet recommendation — but the boards still
+ * have to show *something*, and what they show should be what an app
+ * will actually pass: an inline SVG inheriting `currentColor`.
+ *
+ * They are hand-drawn rather than copied, and they exist for a second
+ * reason worth writing down: **this sandbox's headless Chromium has
+ * no font covering `⚙`, `↶`, `▨`, or `⚠`** — every one of those
+ * measures blank, so a glyph-only board screenshots as an empty box
+ * and a reviewer cannot tell a missing font from a broken component.
+ * `IconButton`'s `RawGlyph` story keeps one glyph on purpose, because
+ * a raw glyph is what plex-channels renders today and the point of
+ * that story is that it gets a *name* regardless.
+ */
+
+/**
+ * `aria-hidden` is repeated on every `<svg>` below rather than living
+ * here, because Biome's `noSvgWithoutTitle` cannot see through a
+ * spread — and a rule that fires on correct code gets switched off,
+ * which would then miss the icon that really is unlabelled. Every
+ * icon in this file is decoration beside a real name.
+ */
+const iconProps = {
+  className: "size-[1.15em] shrink-0",
+  fill: "none",
+  focusable: false,
+  stroke: "currentColor",
+  strokeLinecap: "round",
+  strokeLinejoin: "round",
+  strokeWidth: 1.75,
+  viewBox: "0 0 24 24",
+  xmlns: "http://www.w3.org/2000/svg",
+} as const
+
+export const SettingsIcon = (): ReactNode => (
+  <svg {...iconProps} aria-hidden="true">
+    <path d="M4 7h10M18 7h2M4 17h4M12 17h8" />
+
+    <circle cx="16" cy="7" r="2.2" />
+
+    <circle cx="10" cy="17" r="2.2" />
+  </svg>
+)
+
+export const UndoIcon = (): ReactNode => (
+  <svg {...iconProps} aria-hidden="true">
+    <path d="M9 14 4 9l5-5" />
+
+    <path d="M4 9h9a6 6 0 0 1 0 12h-3" />
+  </svg>
+)
+
+export const RedoIcon = (): ReactNode => (
+  <svg {...iconProps} aria-hidden="true">
+    <path d="m15 14 5-5-5-5" />
+
+    <path d="M20 9h-9a6 6 0 0 0 0 12h3" />
+  </svg>
+)
+
+export const PlayIcon = (): ReactNode => (
+  <svg {...iconProps} aria-hidden="true">
+    <path d="M8 5.5v13l11-6.5z" />
+  </svg>
+)
+
+export const InboxIcon = (): ReactNode => (
+  <svg {...iconProps} aria-hidden="true">
+    <path d="M3 13h4l2 3h6l2-3h4" />
+
+    <path d="M5 5h14l2 8v6H3v-6z" />
+  </svg>
+)
+
+export const SearchIcon = (): ReactNode => (
+  <svg {...iconProps} aria-hidden="true">
+    <circle cx="10.5" cy="10.5" r="6.5" />
+
+    <path d="m15.5 15.5 4.5 4.5" />
+  </svg>
+)
+
+export const AlertIcon = (): ReactNode => (
+  <svg {...iconProps} aria-hidden="true">
+    <path d="M12 4 2.5 20h19z" />
+
+    <path d="M12 10v4.5M12 17.5h.01" />
+  </svg>
+)
+
+export const ImageOffIcon = (): ReactNode => (
+  <svg {...iconProps} aria-hidden="true">
+    <path d="M4 4h16v16H4z" />
+
+    <path d="m4 20 6-7 4 4 3-3 3 3.5" />
+
+    <path d="m3 3 18 18" />
+  </svg>
+)
+
+export const DotIcon = (): ReactNode => (
+  <svg
+    {...iconProps}
+    aria-hidden="true"
+    fill="currentColor"
+    stroke="none"
+  >
+    <circle cx="12" cy="12" r="4" />
+  </svg>
+)

package/src/index.ts

@@ -0,0 +1,132 @@
+/**
+ * `@charcuterie/ui` — the one sanctioned barrel.
+ *
+ * Components never import each other through this file; they import
+ * the sibling module directly (`../Spinner/Spinner.tsx`). A barrel
+ * that a package's own internals go through turns every component
+ * into a dependency of every other one, which is how a 3 KB
+ * `Spinner` starts pulling in `MediaTile`.
+ *
+ * `"./src/*"` is also in `exports`, for the budget-sensitive
+ * consumers — `castkit/packages/slatecast` has 60 KB gz to spend and
+ * should be able to reach one component without the barrel. Same
+ * arrangement as `mux-magic/packages/tools`.
+ *
+ * The token **types and values** are re-exported at
+ * `@charcuterie/ui/tokens` rather than from here, so a React
+ * consumer's TypeScript never names a second package while Satori
+ * still gets `@charcuterie/tokens` with no React in sight.
+ *
+ * The token **stylesheet** is not, and M5 is why. There was a
+ * `"./tokens.css": "./node_modules/@charcuterie/tokens/dist/theme.css"`
+ * export here, and it resolved to nothing in the first real
+ * consumer: a hoisting linker puts `@charcuterie/tokens` at the
+ * *project* root, not inside this package, so that path exists only
+ * under a nesting one. A CSS `@import` fails silently in Tailwind —
+ * no error, no utilities, an unstyled app — which is exactly the
+ * class of failure `portal:` was chosen to catch
+ * ([decision](../../../docs/decisions/2026-07-29-consumers-link-tokens-by-portal-until-publish.md)).
+ * So a consumer installs both package names and imports
+ * `@charcuterie/tokens/theme.css` by its own name, which is what
+ * this package's README has always told it to do.
+ */
+
+export type {
+  AlertProps,
+  AlertSize,
+} from "./Alert/Alert.tsx"
+export { Alert } from "./Alert/Alert.tsx"
+export type { BadgeProps } from "./Badge/Badge.tsx"
+export { Badge } from "./Badge/Badge.tsx"
+export type { ButtonProps } from "./Button/Button.tsx"
+export { Button } from "./Button/Button.tsx"
+export type {
+  CardPadding,
+  CardProps,
+  CardSurface,
+} from "./Card/Card.tsx"
+export { Card } from "./Card/Card.tsx"
+export type { BadgeSize } from "./controlStyles.ts"
+export {
+  BADGE_SIZE_CLASS,
+  CONTROL_SIZE_CLASS,
+  DOT_SIZE_CLASS,
+  ICON_CONTROL_SIZE_CLASS,
+  MIN_TOUCH_TARGET_CLASS,
+  SPINNER_SIZE_CLASS,
+} from "./controlStyles.ts"
+export type {
+  EmptyStateProps,
+  EmptyStateSize,
+} from "./EmptyState/EmptyState.tsx"
+export { EmptyState } from "./EmptyState/EmptyState.tsx"
+export type { IconButtonProps } from "./IconButton/IconButton.tsx"
+export { IconButton } from "./IconButton/IconButton.tsx"
+export type { IntentAppearance } from "./intentStyles.ts"
+export {
+  DISABLED_CLASS,
+  FOCUS_RING_CLASS,
+  INTENT_APPEARANCE_CLASS,
+  INTENT_CONTENT_CLASS,
+  INTENT_HOVER_CLASS,
+  INTENT_SOLID_FILL_CLASS,
+} from "./intentStyles.ts"
+export type {
+  LiveStatusIndicatorProps,
+  LiveStatusIndicatorSize,
+} from "./LiveStatusIndicator/LiveStatusIndicator.tsx"
+export { LiveStatusIndicator } from "./LiveStatusIndicator/LiveStatusIndicator.tsx"
+export type {
+  MediaTileProps,
+  MediaTileRatio,
+} from "./MediaTile/MediaTile.tsx"
+export { MediaTile } from "./MediaTile/MediaTile.tsx"
+export type { MediaStatus } from "./MediaTile/mediaStatus.ts"
+export { mediaTransitions } from "./MediaTile/mediaStatus.ts"
+export type {
+  ModalProps,
+  ModalSize,
+} from "./Modal/Modal.tsx"
+export { Modal } from "./Modal/Modal.tsx"
+export type { PopoverProps } from "./Popover/Popover.tsx"
+export { Popover } from "./Popover/Popover.tsx"
+export type {
+  ProgressBarProps,
+  ProgressBarSize,
+} from "./ProgressBar/ProgressBar.tsx"
+export { ProgressBar } from "./ProgressBar/ProgressBar.tsx"
+export type { ProgressThreshold } from "./ProgressBar/progressValue.ts"
+export {
+  getProgressIntent,
+  toProgressPercent,
+  toProgressValue,
+} from "./ProgressBar/progressValue.ts"
+export type {
+  SegmentedControlProps,
+  SegmentedItem,
+} from "./SegmentedControl/SegmentedControl.tsx"
+export { SegmentedControl } from "./SegmentedControl/SegmentedControl.tsx"
+export type {
+  SkeletonProps,
+  SkeletonShape,
+} from "./Skeleton/Skeleton.tsx"
+export { Skeleton } from "./Skeleton/Skeleton.tsx"
+export type { SpinnerProps } from "./Spinner/Spinner.tsx"
+export { Spinner } from "./Spinner/Spinner.tsx"
+export {
+  getAsyncIntent,
+  getAsyncLabel,
+  getConnectionIntent,
+  getConnectionLabel,
+  getIsConnectionBusy,
+} from "./statusIntent.ts"
+export type {
+  TabItem,
+  TabsActivation,
+  TabsOrientation,
+  TabsProps,
+} from "./Tabs/Tabs.tsx"
+export { Tabs } from "./Tabs/Tabs.tsx"
+export { toClassName } from "./toClassName.ts"
+export type { VisuallyHiddenProps } from "./VisuallyHidden/VisuallyHidden.tsx"
+export { VisuallyHidden } from "./VisuallyHidden/VisuallyHidden.tsx"