@charcuterie/ui 0.1.0

package/src/statusIntent.test.ts

@@ -0,0 +1,136 @@
+/**
+ * The status → intent join, and the reachability of the machines it
+ * reads.
+ *
+ * The interesting assertions here are not "connected is green" —
+ * they are the two things that make a shared machine better than the
+ * `Record<string, string>` it replaces: **every** state has a colour
+ * and a wording, and every state is actually reachable.
+ */
+
+import type {
+  AsyncStatus,
+  ConnectionStatus,
+} from "@charcuterie/logic"
+import {
+  asyncTransitions,
+  connectionTransitions,
+  getUnreachableStates,
+} from "@charcuterie/logic"
+import { expect, test } from "vitest"
+
+import { mediaTransitions } from "./MediaTile/mediaStatus.ts"
+import {
+  getAsyncIntent,
+  getAsyncLabel,
+  getConnectionIntent,
+  getConnectionLabel,
+  getIsConnectionBusy,
+} from "./statusIntent.ts"
+
+const connectionStatuses = Object.keys(
+  connectionTransitions,
+) as ConnectionStatus[]
+
+const asyncStatuses = Object.keys(
+  asyncTransitions,
+) as AsyncStatus[]
+
+test("every connection state has an intent and a wording", () => {
+  // mux-magic's `statusClassMap` is keyed by `string`, so an
+  // unrecognised status renders with no colour at all. The
+  // exhaustive switch makes that a compile error; this makes it a
+  // test failure too, for the JS consumers who have no compiler.
+  for (const status of connectionStatuses) {
+    expect(getConnectionIntent(status)).toBeTruthy()
+
+    expect(getConnectionLabel(status)).toBeTruthy()
+  }
+
+  expect(connectionStatuses).toHaveLength(4)
+})
+
+test("reconnecting is not the same as connecting", () => {
+  // The distinction the whole shared machine exists for, and the one
+  // all four repos currently lose.
+  expect(getConnectionIntent("connecting")).toBe("info")
+
+  expect(getConnectionIntent("reconnecting")).toBe(
+    "warning",
+  )
+
+  expect(getConnectionLabel("connecting")).not.toBe(
+    getConnectionLabel("reconnecting"),
+  )
+})
+
+test("only the in-flight states animate", () => {
+  expect(getIsConnectionBusy("connecting")).toBe(true)
+
+  expect(getIsConnectionBusy("reconnecting")).toBe(true)
+
+  expect(getIsConnectionBusy("connected")).toBe(false)
+
+  expect(getIsConnectionBusy("disconnected")).toBe(false)
+})
+
+test("connection wordings are distinct", () => {
+  // Two states that read identically on a wall-mounted panel are two
+  // states the user cannot tell apart, which defeats the point.
+  const labels = connectionStatuses.map(getConnectionLabel)
+
+  expect(new Set(labels).size).toBe(labels.length)
+})
+
+test("every async state has an intent and a wording", () => {
+  for (const status of asyncStatuses) {
+    expect(getAsyncIntent(status)).toBeTruthy()
+
+    expect(getAsyncLabel(status)).toBeTruthy()
+  }
+
+  expect(
+    new Set(asyncStatuses.map(getAsyncLabel)).size,
+  ).toBe(asyncStatuses.length)
+})
+
+test("only failure is red", () => {
+  expect(getAsyncIntent("error")).toBe("danger")
+
+  expect(getAsyncIntent("idle")).toBe("neutral")
+
+  expect(getAsyncIntent("success")).toBe("success")
+})
+
+test("no state of any machine this package renders is unreachable", () => {
+  // A `failed` nobody can transition to is a badge variant that will
+  // never render — almost always a typo in a transition table. The
+  // check belongs to the *definition*, so each machine's consumer
+  // runs it.
+  expect(
+    getUnreachableStates(
+      connectionTransitions,
+      "connecting",
+    ),
+  ).toEqual([])
+
+  expect(
+    getUnreachableStates(asyncTransitions, "idle"),
+  ).toEqual([])
+
+  expect(
+    getUnreachableStates(mediaTransitions, "loading"),
+  ).toEqual([])
+})
+
+test("a loaded image cannot become an error", () => {
+  // MediaTile's one deliberate omission. A browser does not fire
+  // `error` on an image it has already decoded, so an app that
+  // thinks it saw that is misreading its own event wiring — and a
+  // fallback flickering over a good poster is worse than a throw.
+  expect(mediaTransitions.loaded).not.toContain("error")
+
+  expect(mediaTransitions.loaded).toContain("loading")
+
+  expect(mediaTransitions.error).toContain("loading")
+})

package/src/statusIntent.ts

@@ -0,0 +1,137 @@
+/**
+ * The two shared machines → an intent and a human label.
+ *
+ * This is the join M2 promised and the reason `Status` earned its
+ * place as a fifth state kind. `Badge` and `LiveStatusIndicator`
+ * consume `connectionTransitions` / `asyncTransitions` through
+ * these functions, so a connection state has **one** colour and
+ * **one** wording across the fleet — against four repos that each
+ * spell the same four states differently today, and one
+ * (`mux-magic`) whose `statusClassMap` is a
+ * `Record<string, string>` that silently renders an unknown status
+ * with no colour at all.
+ *
+ * Every switch here ends in `assertNeverStatus`, which is the whole
+ * point: add a state to `connectionTransitions` and this file stops
+ * compiling. A `Record<string, string>` would have shipped a blank
+ * badge instead.
+ */
+
+import type {
+  AsyncStatus,
+  ConnectionStatus,
+} from "@charcuterie/logic"
+import { assertNeverStatus } from "@charcuterie/logic"
+import type { IntentName } from "@charcuterie/tokens"
+
+export const getConnectionIntent = (
+  status: ConnectionStatus,
+): IntentName => {
+  switch (status) {
+    case "connected":
+      return "success"
+
+    case "connecting":
+      return "info"
+
+    // Warning rather than danger, and this is the distinction the
+    // shared machine exists for: a user who has seen data wants
+    // "lost it, getting it back", not the cold-start spinner they
+    // already sat through, and not the red of a dead link either.
+    case "reconnecting":
+      return "warning"
+
+    case "disconnected":
+      return "danger"
+
+    default:
+      return assertNeverStatus(status)
+  }
+}
+
+/**
+ * The ellipsis is a real `…`, not three dots, and the trailing one
+ * is load-bearing: it is what makes "Reconnecting…" read as
+ * in-progress to someone who glances at a wall-mounted panel from
+ * across the room.
+ */
+export const getConnectionLabel = (
+  status: ConnectionStatus,
+): string => {
+  switch (status) {
+    case "connected":
+      return "Connected"
+
+    case "connecting":
+      return "Connecting…"
+
+    case "reconnecting":
+      return "Reconnecting…"
+
+    case "disconnected":
+      return "Disconnected"
+
+    default:
+      return assertNeverStatus(status)
+  }
+}
+
+/** Whether the state is one a moving affordance should mark. */
+export const getIsConnectionBusy = (
+  status: ConnectionStatus,
+): boolean => {
+  switch (status) {
+    case "connecting":
+    case "reconnecting":
+      return true
+
+    case "connected":
+    case "disconnected":
+      return false
+
+    default:
+      return assertNeverStatus(status)
+  }
+}
+
+export const getAsyncIntent = (
+  status: AsyncStatus,
+): IntentName => {
+  switch (status) {
+    case "idle":
+      return "neutral"
+
+    case "loading":
+      return "info"
+
+    case "success":
+      return "success"
+
+    case "error":
+      return "danger"
+
+    default:
+      return assertNeverStatus(status)
+  }
+}
+
+export const getAsyncLabel = (
+  status: AsyncStatus,
+): string => {
+  switch (status) {
+    case "idle":
+      return "Idle"
+
+    case "loading":
+      return "Loading…"
+
+    case "success":
+      return "Done"
+
+    case "error":
+      return "Failed"
+
+    default:
+      return assertNeverStatus(status)
+  }
+}

package/src/storyControls.test.ts

@@ -0,0 +1,128 @@
+/**
+ * The rule that would have caught image 4 of the M4 review: a `size`
+ * prop rendering as a `{}` JSON textarea in the Controls panel,
+ * because Storybook could not see that `ControlSize` is three
+ * strings.
+ *
+ * `react-docgen` follows **relative** imports and stops at bare
+ * package specifiers. So a prop typed from `../intentStyles.ts`
+ * arrives as a resolved union and gets a radio for free, while the
+ * same prop typed from `@charcuterie/tokens` arrives as an opaque
+ * name — and Storybook's fallback for an unknown type is the object
+ * control. Nothing errors. The story renders. The control is just
+ * wrong, in a way only a human opening that panel will notice.
+ *
+ * So: a prop whose type comes from a bare specifier must have an
+ * explicit `argTypes` entry in its story.
+ */
+
+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 readComponent = async (name: string) => {
+  const [component, story] = await Promise.all([
+    readFile(
+      join(sourceDirectory, name, `${name}.tsx`),
+      "utf8",
+    ),
+    readFile(
+      join(sourceDirectory, name, `${name}.stories.tsx`),
+      "utf8",
+    ),
+  ])
+
+  return { component, name, story }
+}
+
+const componentNames = (
+  await readdir(sourceDirectory, { withFileTypes: true })
+)
+  .filter(
+    (entry) =>
+      entry.isDirectory() && /^[A-Z]/.test(entry.name),
+  )
+  .map((entry) => entry.name)
+  .sort()
+
+const components = await Promise.all(
+  componentNames.map(readComponent),
+)
+
+/**
+ * `import type { A, B } from "@scope/pkg"` — bare specifiers only.
+ * A relative one is exactly the case docgen *can* resolve.
+ */
+const getForeignTypeNames = (source: string) =>
+  new Set(
+    Array.from(
+      source.matchAll(
+        /import type \{([^}]+)\} from "([^".][^"]*)"/g,
+      ),
+    )
+      .filter(
+        ([, , specifier]) => !specifier?.startsWith("."),
+      )
+      .flatMap(([, names]) =>
+        (names ?? "")
+          .split(",")
+          .map((one) => one.trim())
+          .filter(Boolean),
+      ),
+  )
+
+const getPropsBlock = (source: string) =>
+  /export type \w+Props =[\s\S]*?\n\}/.exec(source)?.[0] ??
+  ""
+
+test("every component's props are declared where a story can find them", () => {
+  // A canary on the derivation: if the directory scan ever comes
+  // back empty this whole file passes forever.
+  expect(componentNames).toContain("Button")
+  expect(componentNames.length).toBeGreaterThanOrEqual(14)
+})
+
+test("a prop typed from another package has an explicit control", () => {
+  const offenders = components.flatMap(
+    ({ component, name, story }) => {
+      const foreignTypes = getForeignTypeNames(component)
+
+      if (foreignTypes.size === 0) {
+        return []
+      }
+
+      // `intent?: IntentName` / `size?: ControlSize`. React's own
+      // types are excluded: `ReactNode` and friends are not
+      // enumerable and are not meant to have a radio.
+      const declarations = Array.from(
+        getPropsBlock(component).matchAll(
+          /^\s{2}(\w+)\??:\s*([A-Za-z_]\w*)\s*$/gm,
+        ),
+      )
+
+      return declarations
+        .filter(
+          ([, , typeName]) =>
+            typeName &&
+            foreignTypes.has(typeName) &&
+            !typeName.startsWith("React"),
+        )
+        .filter(
+          ([, propName]) =>
+            // The story has to name the prop inside its `argTypes`.
+            !new RegExp(
+              `argTypes:[\\s\\S]*?\\b${propName}:`,
+            ).test(story),
+        )
+        .map(
+          ([, propName, typeName]) =>
+            `${name}.${propName} is \`${typeName}\`, imported from another package, with no argTypes entry`,
+        )
+    },
+  )
+
+  expect(offenders).toEqual([])
+})

package/src/styles.css

@@ -0,0 +1,130 @@
+/* `@charcuterie/ui/styles.css` — the four looping affordances, and
+ * nothing else.
+ *
+ * Every other visual in this package is a Tailwind utility reading
+ * a token, which is what makes a scheme/density/variant flip a
+ * repaint with no re-render. Animation is the one thing utilities
+ * cannot express against our tokens: Tailwind's own `animate-spin`
+ * and `animate-pulse` hardcode 1s and 2s, ignore
+ * `prefers-reduced-motion`, and are therefore beyond the theme's
+ * reach — which is exactly why `MotionTokens` carries a separate
+ * `loopFast`/`loopSlow` ramp.
+ *
+ * Consumers import this once, after `@charcuterie/tokens/theme.css`.
+ *
+ * The reduced-motion block is not a nicety. `variables.css` already
+ * collapses every duration to `0ms`, and for a *transition* that is
+ * the whole fix — but `animation: sweep 0ms infinite` still paints
+ * its first keyframe forever, and the first keyframe of a sweep is
+ * an off-screen bar. So each loop is switched off outright and owes
+ * a static fallback that still reads correctly, which is what the
+ * `@media` block below supplies. A spinner that stops spinning must
+ * still say "loading", and it does: the label is text in a
+ * `role="status"`, not the animation. */
+
+@keyframes charcuterie-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+@keyframes charcuterie-shimmer {
+  from {
+    background-position: 100% 0;
+  }
+
+  to {
+    background-position: -100% 0;
+  }
+}
+
+/* Logical, not `translateX`. A sweep is the one animation whose
+ * direction carries meaning — it reads as "moving forward" — so in
+ * RTL it has to move the other way, and `inset-inline-start` is
+ * what makes that free. */
+@keyframes charcuterie-sweep {
+  from {
+    inset-inline-start: -40%;
+  }
+
+  to {
+    inset-inline-start: 100%;
+  }
+}
+
+@keyframes charcuterie-pulse {
+  0% {
+    opacity: 1;
+    transform: scale(1);
+  }
+
+  50% {
+    opacity: 0.45;
+    transform: scale(0.82);
+  }
+
+  100% {
+    opacity: 1;
+    transform: scale(1);
+  }
+}
+
+.charcuterie-spin {
+  animation: charcuterie-spin var(--duration-loop-fast)
+    linear infinite;
+}
+
+.charcuterie-shimmer {
+  background-image: linear-gradient(
+    90deg,
+    var(--color-surface-sunken) 0%,
+    var(--color-surface-raised) 50%,
+    var(--color-surface-sunken) 100%
+  );
+  background-size: 200% 100%;
+  animation: charcuterie-shimmer var(--duration-loop-slow)
+    var(--easing-standard) infinite;
+}
+
+.charcuterie-sweep {
+  animation: charcuterie-sweep var(--duration-loop-slow)
+    var(--easing-standard) infinite;
+}
+
+.charcuterie-pulse {
+  animation: charcuterie-pulse var(--duration-loop-slow)
+    var(--easing-standard) infinite;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .charcuterie-spin,
+  .charcuterie-shimmer,
+  .charcuterie-sweep,
+  .charcuterie-pulse {
+    animation: none;
+  }
+
+  /* Flat, not mid-gradient: a stopped shimmer left holding its
+   * first keyframe is a lopsided highlight that reads as a
+   * rendering bug rather than as a placeholder. */
+  .charcuterie-shimmer {
+    background-image: none;
+    background-color: var(--color-surface-sunken);
+  }
+
+  /* The sweep's static fallback carries the whole meaning of the
+   * indeterminate state — "working, no measurable progress" — so it
+   * fills the track with hatching rather than parking a bar at one
+   * end, where it would read as either finished or stuck. */
+  .charcuterie-sweep {
+    inset-inline-start: 0;
+    inline-size: 100%;
+    background-image: repeating-linear-gradient(
+      135deg,
+      currentColor 0,
+      currentColor 2px,
+      transparent 2px,
+      transparent 6px
+    );
+  }
+}