@charcuterie/ui 0.1.0

package/src/IconButton/IconButton.stories.tsx

@@ -0,0 +1,191 @@
+import type { Meta, StoryObj } from "@storybook/react"
+
+import { controlSizeArgType } from "../argTypes.storyHelpers.ts"
+
+import {
+  ContainerBoard,
+  StoryCell,
+  StoryGrid,
+  StoryRow,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import {
+  RedoIcon,
+  SettingsIcon,
+  UndoIcon,
+} from "../icons.storyHelpers.tsx"
+import { IconButton } from "./IconButton.tsx"
+
+/**
+ * The library ships **no icons** — lucide is the fleet recommendation
+ * and `children` is whatever the app already has, so these are
+ * story-only SVGs.
+ *
+ * `RawGlyph` below keeps plex-channels' actual `↶` for comparison:
+ * the glyph is unchanged, the *name* is what this component adds.
+ */
+const UNDO_ICON = <UndoIcon />
+
+const meta = {
+  title: "Components/IconButton",
+  component: IconButton,
+  parameters: { layout: "padded" },
+  argTypes: { size: controlSizeArgType },
+  args: {
+    appearance: "ghost",
+    isDisabled: false,
+    isLoading: false,
+    size: "md",
+  },
+} satisfies Meta<typeof IconButton>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+/**
+ * The name is the whole component. plex-channels renders `↶` into a
+ * bare `<button>` today, so a screen reader announces "↶" and
+ * `getByRole("button", { name: "Undo" })` finds nothing.
+ */
+export const Default: Story = {
+  args: { children: UNDO_ICON, label: "Undo" },
+}
+
+export const AllVariants: Story = {
+  args: { children: UNDO_ICON, label: "Undo" },
+  render: (iconButtonProps) => (
+    <StorySection title="Same four appearances as Button — ghost is the toolbar default, because a row of six solid squares is a wall.">
+      <StoryGrid columns={4}>
+        <StoryCell label="solid">
+          <IconButton
+            {...iconButtonProps}
+            appearance="solid"
+          />
+        </StoryCell>
+
+        <StoryCell label="soft">
+          <IconButton
+            {...iconButtonProps}
+            appearance="soft"
+          />
+        </StoryCell>
+
+        <StoryCell label="outline">
+          <IconButton
+            {...iconButtonProps}
+            appearance="outline"
+          />
+        </StoryCell>
+
+        <StoryCell label="ghost">
+          <IconButton
+            {...iconButtonProps}
+            appearance="ghost"
+          />
+        </StoryCell>
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+export const AllStates: Story = {
+  args: { children: UNDO_ICON, label: "Undo" },
+  parameters: {
+    pseudo: {
+      active: ["#active"],
+      focusVisible: ["#focus-target"],
+      hover: ["#hover"],
+    },
+  },
+  render: (iconButtonProps) => (
+    <StoryGrid columns={4}>
+      <StoryCell label="default">
+        <IconButton {...iconButtonProps} />
+      </StoryCell>
+
+      <StoryCell label="hover (forced)">
+        <IconButton {...iconButtonProps} id="hover" />
+      </StoryCell>
+
+      <StoryCell label="active (forced)">
+        <IconButton {...iconButtonProps} id="active" />
+      </StoryCell>
+
+      <StoryCell label="focus-visible (forced)">
+        <IconButton
+          {...iconButtonProps}
+          id="focus-target"
+        />
+      </StoryCell>
+
+      <StoryCell label="disabled">
+        <IconButton {...iconButtonProps} isDisabled />
+      </StoryCell>
+
+      <StoryCell label="loading">
+        <IconButton {...iconButtonProps} isLoading />
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+export const Sizes: Story = {
+  args: { children: UNDO_ICON, label: "Undo" },
+  render: (iconButtonProps) => (
+    <StorySection title="Square on the control height, so an icon button lines up with the text button beside it.">
+      <StoryRow>
+        <IconButton {...iconButtonProps} size="sm" />
+
+        <IconButton {...iconButtonProps} size="md" />
+
+        <IconButton {...iconButtonProps} size="lg" />
+      </StoryRow>
+    </StorySection>
+  ),
+}
+
+export const Responsive: Story = {
+  args: { children: UNDO_ICON, label: "Undo" },
+  render: (iconButtonProps) => (
+    <ContainerBoard>
+      <StoryRow>
+        <IconButton
+          {...iconButtonProps}
+          appearance="ghost"
+        />
+
+        <IconButton
+          {...iconButtonProps}
+          appearance="ghost"
+          label="Redo"
+        >
+          <RedoIcon />
+        </IconButton>
+
+        <IconButton
+          {...iconButtonProps}
+          appearance="ghost"
+          label="Settings"
+        >
+          <SettingsIcon />
+        </IconButton>
+      </StoryRow>
+    </ContainerBoard>
+  ),
+}
+
+/**
+ * plex-channels' `↶`, rendered exactly as it is today — and named,
+ * which it is not today. `getByRole("button", { name: "Undo" })`
+ * resolves here and finds nothing there.
+ *
+ * A glyph depends on a font having that code point: this repo's
+ * headless Chromium has none for `↶`, so in a CI screenshot the
+ * button is empty while the *name* is still correct. That is the
+ * argument for an SVG icon set, made by the story rather than in a
+ * comment.
+ */
+export const RawGlyph: Story = {
+  args: { children: "↶", label: "Undo" },
+}

package/src/IconButton/IconButton.test.tsx

@@ -0,0 +1,70 @@
+import {
+  composeStories,
+  composeStory,
+} from "@storybook/react"
+import { expect, fn, userEvent } from "storybook/test"
+import { test } from "vitest"
+
+import { UndoIcon } from "../icons.storyHelpers.tsx"
+import { mountStory } from "../mountStory.testHelpers.ts"
+import { expectAgentDrivable } from "../testing/index.ts"
+import meta, * as stories from "./IconButton.stories.tsx"
+
+const { Default, RawGlyph } = composeStories(stories)
+
+/**
+ * The assertion the fleet fails today: plex-channels renders `↶`
+ * into a bare `<button>`, so a screen reader announces "↶" and this
+ * query finds nothing.
+ */
+test("a glyph gets a name", async () => {
+  const { canvas } = await mountStory(Default)
+
+  expectAgentDrivable(canvas, {
+    name: "Undo",
+    role: "button",
+  })
+})
+
+test("the same is true of a raw text glyph", async () => {
+  const { canvas } = await mountStory(RawGlyph)
+
+  // The glyph is unchanged from what plex-channels ships; the *name*
+  // is what this component adds. A font without the code point
+  // renders nothing at all — as this repo's headless chromium does —
+  // and the name still resolves.
+  expectAgentDrivable(canvas, {
+    name: "Undo",
+    role: "button",
+  })
+})
+
+test("Tab reaches it and Enter activates", async () => {
+  const onClick = fn()
+
+  const { canvas } = await mountStory(
+    composeStory(
+      {
+        args: {
+          children: <UndoIcon />,
+          label: "Undo",
+          onClick,
+        },
+      },
+      meta,
+    ),
+  )
+
+  const button = expectAgentDrivable(canvas, {
+    name: "Undo",
+    role: "button",
+  })
+
+  await userEvent.tab()
+
+  await expect(button).toHaveFocus()
+
+  await userEvent.keyboard("{Enter}")
+
+  await expect(onClick).toHaveBeenCalledTimes(1)
+})

package/src/IconButton/IconButton.tsx

@@ -0,0 +1,54 @@
+import type { ReactNode } from "react"
+
+import type { ButtonProps } from "../Button/Button.tsx"
+import { Button } from "../Button/Button.tsx"
+
+export type IconButtonProps = Omit<
+  ButtonProps,
+  | "aria-label"
+  | "children"
+  | "iconEnd"
+  | "iconStart"
+  | "sizing"
+> & {
+  /**
+   * Required, and this single line is most of the component's
+   * reason to exist. `label` cannot be defaulted, cannot be
+   * omitted, and is not a `ReactNode` — it becomes `aria-label`,
+   * which is a string by specification.
+   */
+  label: string
+  /** The glyph. Anything — lucide, an inline SVG, a character. */
+  children: ReactNode
+}
+
+/**
+ * Three repos, three strategies, and **none of them names the
+ * button**: mux-magic hand-writes five SVG components, castkit
+ * keeps an `ICON_PATHS` map, and plex-channels renders raw glyphs
+ * (`↶`, `↷`, `▶`, `⚙`, `≡`) straight into a `<button>`. A screen
+ * reader reads the last of those as "↶", and
+ * `getByRole("button", { name: "Undo" })` finds nothing at all —
+ * which is the concrete reason the fleet is not agent-drivable
+ * today.
+ *
+ * So the type system asks for the name. There is no way to render
+ * this component without one, and `expectAgentDrivable` in the
+ * story proves the name is the one Playwright will match on.
+ *
+ * **No icons ship here.** The library does not own an icon set —
+ * lucide (ISC) is the fleet recommendation — so `children` is
+ * whatever the app already has, and the icon is `aria-hidden` by
+ * virtue of the `aria-label` overriding the subtree name.
+ */
+export const IconButton = ({
+  children,
+  label,
+  ...buttonProps
+}: IconButtonProps): ReactNode => (
+  <Button {...buttonProps} aria-label={label} sizing="icon">
+    <span aria-hidden="true" className="contents">
+      {children}
+    </span>
+  </Button>
+)

package/src/LiveStatusIndicator/LiveStatusIndicator.mdx

@@ -0,0 +1,43 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as LiveStatusIndicatorStories from "./LiveStatusIndicator.stories";
+
+<Meta of={LiveStatusIndicatorStories} />
+
+# LiveStatusIndicator
+
+Four repos, four implementations, and **it is the thing users read most** — a wall-mounted
+panel showing stale data under a green dot is worse than one showing nothing.
+
+<Canvas of={LiveStatusIndicatorStories.Default} />
+
+## Props
+
+<Controls />
+
+## The distinction all four repos lose
+
+`connecting` and `reconnecting` are different states and they are collapsed everywhere
+today. A user who has seen data wants "lost it, getting it back" (amber, moving), not the
+cold-start spinner they already sat through (blue), and not a dead link (red). That is why
+`connectionTransitions` is one of only two machines `@charcuterie/logic` ships rather than
+something each app defines.
+
+Wording and colour both come from exhaustive switches over that machine, so adding a fifth
+state stops this package compiling instead of rendering a grey dot.
+
+<Canvas of={LiveStatusIndicatorStories.AllVariants} />
+
+## Accessibility contract
+
+- `role="status"` + `aria-live="polite"`, so a transition is announced without interrupting
+  what the user is doing. `assertive` would cut off the sentence in progress, and the dot is
+  not going anywhere.
+- `aria-label` as well, because a `status` region takes no accessible name from its content
+  — that is what makes `getByRole("status", { name: "Connected" })` resolve.
+- Only `connecting` and `reconnecting` animate. A dot that pulses forever is the fleet's
+  current "is it alive?" problem in a new costume.
+- `data-status` is the stable handle for a Playwright assertion — it survives translation,
+  where the visible wording does not.
+
+<Canvas of={LiveStatusIndicatorStories.Interactive} />

package/src/LiveStatusIndicator/LiveStatusIndicator.stories.tsx

@@ -0,0 +1,199 @@
+import {
+  connectionTransitions,
+  useStatus,
+} from "@charcuterie/logic"
+import type { Meta, StoryObj } from "@storybook/react"
+
+import { connectionStatusArgType } from "../argTypes.storyHelpers.ts"
+import { Button } from "../Button/Button.tsx"
+import {
+  ContainerBoard,
+  StoryCell,
+  StoryGrid,
+  StoryRow,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import { Card } from "../Card/Card.tsx"
+import { LiveStatusIndicator } from "./LiveStatusIndicator.tsx"
+
+const CONNECTION_STATUSES = [
+  "connecting",
+  "connected",
+  "reconnecting",
+  "disconnected",
+] as const
+
+const meta = {
+  title: "Components/LiveStatusIndicator",
+  component: LiveStatusIndicator,
+  parameters: { layout: "padded" },
+  argTypes: { status: connectionStatusArgType },
+  args: { isLabelVisible: true, size: "md" },
+} satisfies Meta<typeof LiveStatusIndicator>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+/**
+ * A named live region, plus a `data-status` attribute — the stable
+ * handle for a Playwright assertion, because it survives translation
+ * where the visible wording does not.
+ */
+export const Default: Story = {
+  args: { status: "connected" },
+}
+
+/**
+ * The four states, and the distinction four repos currently lose:
+ * `connecting` is blue and cold-start, `reconnecting` is amber and
+ * means "you had data, I am getting it back". Collapsing them is why
+ * a flaky link reads wrong today.
+ */
+export const AllVariants: Story = {
+  args: { status: "connected" },
+  render: (indicatorProps) => (
+    <StorySection title="Wording and colour both come from the shared machine — add a fifth state to `connectionTransitions` and `statusIntent.ts` stops compiling.">
+      <StoryGrid columns={4}>
+        {CONNECTION_STATUSES.map((status) => (
+          <StoryCell key={status} label={status}>
+            <LiveStatusIndicator
+              {...indicatorProps}
+              status={status}
+            />
+          </StoryCell>
+        ))}
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+export const AllStates: Story = {
+  args: { status: "reconnecting" },
+  render: (indicatorProps) => (
+    <StoryGrid columns={2}>
+      <StoryCell label="label visible (default)">
+        <LiveStatusIndicator {...indicatorProps} />
+      </StoryCell>
+
+      <StoryCell label="dot only — label still announced">
+        <LiveStatusIndicator
+          {...indicatorProps}
+          isLabelVisible={false}
+        />
+      </StoryCell>
+
+      <StoryCell label="with detail">
+        <LiveStatusIndicator
+          {...indicatorProps}
+          detail="3 of 4 bays reporting"
+        />
+      </StoryCell>
+
+      <StoryCell label="sizes">
+        <StoryRow>
+          <LiveStatusIndicator
+            {...indicatorProps}
+            size="sm"
+          />
+
+          <LiveStatusIndicator
+            {...indicatorProps}
+            size="md"
+          />
+
+          <LiveStatusIndicator
+            {...indicatorProps}
+            size="lg"
+          />
+        </StoryRow>
+      </StoryCell>
+
+      {/*
+        `stretch`, because `Card` declares a container query. A
+        default `start` cell is shrink-to-fit, and
+        `container-type: inline-size` forbids the element from
+        being sized by its own contents — so the card collapses to
+        min-content and "16 bays · 4 ripping" wraps after every
+        word. `storyRules.test.ts` now fails on this.
+      */}
+      <StoryCell
+        align="stretch"
+        label="in a card header — the real placement"
+      >
+        <Card
+          actions={
+            <LiveStatusIndicator
+              status="connected"
+              size="sm"
+            />
+          }
+          heading="Tower"
+        >
+          <p className="text-content-secondary text-sm">
+            16 bays · 4 ripping
+          </p>
+        </Card>
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+export const Responsive: Story = {
+  args: {
+    detail: "3 of 4 bays reporting",
+    status: "reconnecting",
+  },
+  render: (indicatorProps) => (
+    <ContainerBoard>
+      <LiveStatusIndicator {...indicatorProps} />
+    </ContainerBoard>
+  ),
+}
+
+const ConnectionLifecycle = () => {
+  const { can, status, transitionTo } = useStatus({
+    initialState: "connecting",
+    transitions: connectionTransitions,
+  })
+
+  return (
+    <div className="flex flex-col gap-3">
+      <LiveStatusIndicator status={status} />
+
+      <StoryRow>
+        {CONNECTION_STATUSES.map((next) => (
+          <Button
+            appearance="soft"
+            isDisabled={!can(next) && status !== next}
+            key={next}
+            onClick={() => {
+              transitionTo(next)
+            }}
+            size="sm"
+          >
+            {next}
+          </Button>
+        ))}
+      </StoryRow>
+
+      <p className="text-content-muted text-xs">
+        Buttons disable themselves on illegal edges —
+        `connected → connecting` is not one, because a live
+        link that wants to reconnect goes through
+        `reconnecting`.
+      </p>
+    </div>
+  )
+}
+
+/**
+ * The live region, driven. Each click is a real transition through
+ * `connectionTransitions`, and the indicator's wording, colour, and
+ * whether the dot moves all follow from the state rather than from
+ * four independent booleans.
+ */
+export const Interactive: Story = {
+  args: { status: "connecting" },
+  render: () => <ConnectionLifecycle />,
+}

package/src/LiveStatusIndicator/LiveStatusIndicator.test.tsx

@@ -0,0 +1,63 @@
+import { composeStories } from "@storybook/react"
+import { expect, userEvent } from "storybook/test"
+import { test } from "vitest"
+
+import { mountStory } from "../mountStory.testHelpers.ts"
+import { expectAgentDrivable } from "../testing/index.ts"
+import * as stories from "./LiveStatusIndicator.stories.tsx"
+
+const { Default, Interactive } = composeStories(stories)
+
+test("it is a named live region with a stable status handle", async () => {
+  const { canvas } = await mountStory(Default)
+
+  const indicator = expectAgentDrivable(canvas, {
+    name: "Connected",
+    role: "status",
+  })
+
+  // `data-status` survives translation; the visible wording does
+  // not. A Playwright assertion in a consumer app wants the former.
+  await expect(indicator).toHaveAttribute(
+    "data-status",
+    "connected",
+  )
+})
+
+/**
+ * The live region, driven. Each click is a real transition through
+ * `connectionTransitions`, so the wording, the colour, and whether
+ * the dot moves all follow from one state rather than from four
+ * independent booleans.
+ */
+test("the indicator follows the connection machine", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  const indicator = canvas.getByRole("status")
+
+  await expect(indicator).toHaveAttribute(
+    "data-status",
+    "connecting",
+  )
+
+  await userEvent.click(
+    canvas.getByRole("button", { name: "connected" }),
+  )
+
+  await expect(canvas.getByText("Connected")).toBeVisible()
+
+  await userEvent.click(
+    canvas.getByRole("button", { name: "reconnecting" }),
+  )
+
+  await expect(
+    canvas.getByText("Reconnecting…"),
+  ).toBeVisible()
+
+  // The distinction four repos currently lose: `reconnecting` is
+  // warning — you had data and I am getting it back — not the
+  // `connecting` blue and not the `disconnected` red.
+  await expect(indicator).toHaveClass(
+    "text-intent-warning-content",
+  )
+})