@charcuterie/ui 0.1.0

package/src/LiveStatusIndicator/LiveStatusIndicator.tsx

@@ -0,0 +1,116 @@
+import type { ConnectionStatus } from "@charcuterie/logic"
+import type {
+  ComponentPropsWithRef,
+  ReactNode,
+} from "react"
+
+import { DOT_SIZE_CLASS } from "../controlStyles.ts"
+import {
+  INTENT_CONTENT_CLASS,
+  INTENT_SOLID_FILL_CLASS,
+} from "../intentStyles.ts"
+import {
+  getConnectionIntent,
+  getConnectionLabel,
+  getIsConnectionBusy,
+} from "../statusIntent.ts"
+import { toClassName } from "../toClassName.ts"
+import { VisuallyHidden } from "../VisuallyHidden/VisuallyHidden.tsx"
+
+export type LiveStatusIndicatorSize =
+  keyof typeof DOT_SIZE_CLASS
+
+export type LiveStatusIndicatorProps = Omit<
+  ComponentPropsWithRef<"span">,
+  "children"
+> & {
+  /** Extra context, announced after the label. "3 of 4 bays." */
+  detail?: string
+  isLabelVisible?: boolean
+  /** Overrides the machine's own wording. Rarely wanted. */
+  label?: string
+  size?: LiveStatusIndicatorSize
+  status: ConnectionStatus
+}
+
+/**
+ * Four repos, four different implementations, and **it is the thing
+ * users read most** — a wall-mounted panel showing stale data with a
+ * green dot is worse than one showing nothing.
+ *
+ * The second reason it is P0: all four collapse `connecting` and
+ * `reconnecting` into one state, which reads wrong on exactly the
+ * link that needs it. 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
+ * distinction is why `connectionTransitions` is one of the two
+ * machines `@charcuterie/logic` ships rather than something each app
+ * defines, and `getConnectionIntent` / `getConnectionLabel` are
+ * exhaustive switches over it — add a fifth state and this component
+ * stops compiling instead of rendering a grey dot.
+ *
+ * `role="status"` + `aria-live="polite"` on the wrapper, so a
+ * transition is announced without interrupting whatever the user is
+ * doing. `aria-live="assertive"` would be wrong here even for
+ * `disconnected`: it cuts off the sentence in progress, and the dot
+ * is not going anywhere.
+ */
+export const LiveStatusIndicator = ({
+  className,
+  detail,
+  isLabelVisible = true,
+  label,
+  size = "md",
+  status,
+  ...spanProps
+}: LiveStatusIndicatorProps): ReactNode => {
+  const intent = getConnectionIntent(status)
+
+  const statusLabel = label ?? getConnectionLabel(status)
+
+  return (
+    <span
+      {...spanProps}
+      // Named as well as live, for the same reason as `Spinner`: a
+      // `status` region gets no name from its content, so this is
+      // what makes `getByRole("status", { name: "Connected" })` — the
+      // query an agent will actually write — resolve.
+      aria-label={statusLabel}
+      aria-live="polite"
+      className={toClassName(
+        "inline-flex items-center gap-2 text-sm",
+        INTENT_CONTENT_CLASS[intent],
+        className,
+      )}
+      role="status"
+      // Not an ARIA attribute — a hook for a consumer's own CSS and
+      // for a Playwright assertion that wants the state rather than
+      // the wording, which survives translation.
+      data-status={status}
+    >
+      <span
+        aria-hidden="true"
+        className={toClassName(
+          "inline-block shrink-0 rounded-full",
+          DOT_SIZE_CLASS[size],
+          INTENT_SOLID_FILL_CLASS[intent],
+          // Only the two in-flight states move. A pulsing dot that
+          // never stops is the fleet's current "is it alive?"
+          // problem in a new costume.
+          getIsConnectionBusy(status) &&
+            "charcuterie-pulse",
+        )}
+      />
+
+      {isLabelVisible ? (
+        <span>{statusLabel}</span>
+      ) : (
+        <VisuallyHidden>{statusLabel}</VisuallyHidden>
+      )}
+
+      {detail ? (
+        <span className="text-content-muted">{detail}</span>
+      ) : null}
+    </span>
+  )
+}

package/src/MediaTile/MediaTile.mdx

@@ -0,0 +1,51 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as MediaTileStories from "./MediaTile.stories";
+
+<Meta of={MediaTileStories} />
+
+# MediaTile
+
+Three repos, and shipping one of these is what makes plex-channels, image-viewer, and
+gallery-downloader look like one family instead of three.
+
+<Canvas of={MediaTileStories.Grid} />
+
+## Props
+
+<Controls />
+
+## The three states no hand-rolled version models
+
+| State | What it does | Why |
+| --- | --- | --- |
+| loading | `Skeleton` at the tile's exact aspect ratio | A 200-poster grid that reflows on load loses the user's place |
+| error | Keeps the box, keeps the name (`role="img"` with the same `alt`) | A broken `<img>` collapses to a glyph and takes the row height with it |
+| cached | Checks `complete`/`naturalWidth` on mount and on every `src` change | A `complete` image never fires `load`, so an `onLoad`-only tile shimmers over a perfectly good poster forever |
+
+Those are a `useStatus` machine rather than a `useState<string>`, which is what makes
+`loaded → error` impossible instead of merely unlikely — see `mediaStatus.ts`. 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 the machine throws rather than flickering a fallback
+over a good poster.
+
+<Canvas of={MediaTileStories.AllStates} />
+
+## Sizing
+
+The tile is a container query (the caption's type steps up past `--cq-sm`), which means it
+may not be sized by its own contents: put it in a grid track or give it a definite inline
+size. In a shrink-to-fit parent it collapses to min-content — the same constraint `Card`
+carries, and for the same reason.
+
+## Names
+
+`alt` is required. When `href` is set, the link carries `aria-label={title}` and the image
+goes `alt=""` — an agent writing `getByRole("link", { name: "Blade Runner" })` should not
+have to know whether a subtitle happened to be rendered, and two names for one link is a
+screen reader reading it twice.
+
+The caption's type steps up past `--cq-sm`, so a tile in a dense 8-across grid and the same
+tile in a 3-across one are both legible.
+
+<Canvas of={MediaTileStories.Responsive} />

package/src/MediaTile/MediaTile.stories.tsx

@@ -0,0 +1,211 @@
+import type { Meta, StoryObj } from "@storybook/react"
+
+import { Badge } from "../Badge/Badge.tsx"
+import {
+  ContainerBoard,
+  StoryCell,
+  StoryGrid,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import { MediaTile } from "./MediaTile.tsx"
+
+/**
+ * An inline SVG rather than a fixture file or a placeholder service:
+ * it decodes synchronously, needs no network, and makes the
+ * `loaded` state deterministic in CI — which matters because the
+ * *cached* path is one of the three states this component exists to
+ * get right.
+ */
+const toPosterSrc = (label: string) =>
+  `data:image/svg+xml;utf8,${encodeURIComponent(
+    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 300"><rect width="200" height="300" fill="#3E38C4"/><text x="100" y="150" fill="#FFFFFF" font-family="sans-serif" font-size="18" text-anchor="middle">${label}</text></svg>`,
+  )}`
+
+/** 404s, which is what makes the error state real rather than mocked. */
+const MISSING_SRC = "/charcuterie-missing-poster.png"
+
+const meta = {
+  title: "Components/MediaTile",
+  component: MediaTile,
+  parameters: { layout: "padded" },
+  args: { aspectRatio: "poster" },
+} satisfies Meta<typeof MediaTile>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: {
+    alt: "Blade Runner (1982) poster",
+    src: toPosterSrc("Blade Runner"),
+    subtitle: "1982 · 4K remaster",
+    title: "Blade Runner",
+  },
+}
+
+export const AllVariants: Story = {
+  args: { alt: "Poster", title: "Blade Runner" },
+  render: () => (
+    <StorySection title="Three trims. 2:3 is the poster standard — Plex, Kavita, and every physical sleeve in the collection.">
+      <StoryGrid columns={3}>
+        <StoryCell align="stretch" label="poster (2:3)">
+          <MediaTile
+            alt="Blade Runner (1982) poster"
+            src={toPosterSrc("2:3")}
+            subtitle="1982"
+            title="Blade Runner"
+          />
+        </StoryCell>
+
+        <StoryCell align="stretch" label="square">
+          <MediaTile
+            alt="Kind of Blue album art"
+            aspectRatio="square"
+            src={toPosterSrc("1:1")}
+            subtitle="Miles Davis"
+            title="Kind of Blue"
+          />
+        </StoryCell>
+
+        <StoryCell align="stretch" label="video (16:9)">
+          <MediaTile
+            alt="Episode thumbnail"
+            aspectRatio="video"
+            src={toPosterSrc("16:9")}
+            subtitle="S01E04"
+            title="The Constant"
+          />
+        </StoryCell>
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+/**
+ * The three states are the component, and no hand-rolled version in
+ * the fleet models more than one of them.
+ */
+export const AllStates: Story = {
+  args: { alt: "Poster", title: "Blade Runner" },
+  render: () => (
+    <StoryGrid columns={4}>
+      <StoryCell align="stretch" label="loaded">
+        <MediaTile
+          alt="Blade Runner (1982) poster"
+          src={toPosterSrc("Blade Runner")}
+          subtitle="1982 · 4K remaster"
+          title="Blade Runner"
+        />
+      </StoryCell>
+
+      <StoryCell
+        align="stretch"
+        label="loading — skeleton holds the box"
+      >
+        <MediaTile
+          alt="Poster loading"
+          subtitle="waiting for the image"
+          title="Still loading"
+        />
+      </StoryCell>
+
+      <StoryCell
+        align="stretch"
+        label="error — box and name survive"
+      >
+        <MediaTile
+          alt="Dune (2021) poster"
+          src={MISSING_SRC}
+          subtitle="2021"
+          title="Dune"
+        />
+      </StoryCell>
+
+      <StoryCell align="stretch" label="link + badge">
+        <MediaTile
+          alt="Blade Runner (1982) poster"
+          badge={
+            <Badge intent="success" size="sm">
+              4K
+            </Badge>
+          }
+          href="#blade-runner"
+          src={toPosterSrc("Blade Runner")}
+          subtitle="1982 · 4K remaster"
+          title="Blade Runner"
+        />
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * The caption's type steps up past `--cq-sm`, so a tile in a dense
+ * 8-across grid and the same tile in a 3-across one are legible at
+ * both — the intermediate widths where the fleet's poster grids look
+ * wrong today.
+ */
+export const Responsive: Story = {
+  args: { alt: "Poster", title: "Blade Runner" },
+  render: () => (
+    <ContainerBoard>
+      <MediaTile
+        alt="Blade Runner (1982) poster"
+        src={toPosterSrc("Blade Runner")}
+        subtitle="1982 · 4K remaster"
+        title="Blade Runner"
+      />
+    </ContainerBoard>
+  ),
+}
+
+export const Grid: Story = {
+  args: { alt: "Poster", title: "Blade Runner" },
+  render: () => (
+    // Two elements, not one: the container and the grid that queries
+    // it **must** be different, because a container query matches
+    // descendants only. Collapsed into one `<div>` this compiles,
+    // generates real CSS, and silently stays two columns — which on a
+    // desktop is four 700px posters.
+    <div className="@container">
+      <div className="grid grid-cols-2 gap-4 cq-sm:grid-cols-3 cq-md:grid-cols-4 cq-lg:grid-cols-6">
+        {[
+          "Blade Runner",
+          "Dune",
+          "Arrival",
+          "Solaris",
+          "Stalker",
+          "Annihilation",
+        ].map((title, index) => (
+          <MediaTile
+            alt={`${title} poster`}
+            href={`#${title.toLowerCase().replace(" ", "-")}`}
+            key={title}
+            src={
+              index === 1 ? MISSING_SRC : toPosterSrc(title)
+            }
+            subtitle="Science fiction"
+            title={title}
+          />
+        ))}
+      </div>
+    </div>
+  ),
+}
+
+/**
+ * The linked tile's contract: the accessible name is exactly the
+ * title — not the title plus the subtitle plus the alt text — and
+ * Tab reaches it. `getByRole("link", { name: "Blade Runner" })` is
+ * what an agent will actually write.
+ */
+export const Interactive: Story = {
+  args: {
+    alt: "Blade Runner (1982) poster",
+    href: "#blade-runner",
+    src: toPosterSrc("Blade Runner"),
+    subtitle: "1982 · 4K remaster",
+    title: "Blade Runner",
+  },
+}

package/src/MediaTile/MediaTile.test.tsx

@@ -0,0 +1,41 @@
+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 "./MediaTile.stories.tsx"
+
+const { Default, Interactive } = composeStories(stories)
+
+test("an unlinked tile's poster carries the name", async () => {
+  const { canvas } = await mountStory(Default)
+
+  expectAgentDrivable(canvas, {
+    name: "Blade Runner (1982) poster",
+    role: "img",
+  })
+})
+
+/**
+ * The linked tile's contract: the accessible name is exactly the
+ * title — not the title plus the subtitle plus the alt text — and
+ * Tab reaches it. `getByRole("link", { name: "Blade Runner" })` is
+ * what an agent will actually write.
+ */
+test("a linked tile is one link named for its title", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  const link = expectAgentDrivable(canvas, {
+    name: "Blade Runner",
+    role: "link",
+  })
+
+  await userEvent.tab()
+
+  await expect(link).toHaveFocus()
+
+  // The image inside a linked tile is `alt=""` on purpose: two names
+  // for one link is a screen reader reading it twice.
+  await expect(canvas.queryAllByRole("img")).toHaveLength(0)
+})

package/src/MediaTile/MediaTile.tsx

@@ -0,0 +1,227 @@
+import { useStatus } from "@charcuterie/logic"
+import type {
+  ComponentPropsWithRef,
+  ReactNode,
+} from "react"
+import { useEffect, useRef } from "react"
+
+import { Skeleton } from "../Skeleton/Skeleton.tsx"
+import { toClassName } from "../toClassName.ts"
+import { mediaTransitions } from "./mediaStatus.ts"
+
+export type MediaTileRatio = "poster" | "square" | "video"
+
+export type MediaTileProps = Omit<
+  ComponentPropsWithRef<"figure">,
+  "children"
+> & {
+  /**
+   * Required. The one thing three hand-rolled poster grids all
+   * omit — and a 200-tile page of unnamed images is unnavigable
+   * rather than merely imperfect.
+   */
+  alt: string
+  aspectRatio?: MediaTileRatio
+  /** A `Badge`, usually. Pinned inside the media box. */
+  badge?: ReactNode
+  /** Shown in place of the image when it fails. */
+  fallback?: ReactNode
+  href?: string
+  src?: string
+  subtitle?: ReactNode
+  title: string
+}
+
+const RATIO_CLASS: Record<MediaTileRatio, string> = {
+  // 2:3 is the standard poster trim, which is what Plex, Kavita, and
+  // every physical sleeve in the collection actually are.
+  poster: "aspect-[2/3]",
+  square: "aspect-square",
+  video: "aspect-video",
+}
+
+/**
+ * Three repos, and shipping one of these is what makes
+ * plex-channels, image-viewer, and gallery-downloader look like one
+ * family instead of three.
+ *
+ * The interesting part is not the layout, it is the three states an
+ * image has and the fact that no hand-rolled version models them:
+ *
+ *  - **Loading** shows a `Skeleton` at the tile's exact aspect ratio,
+ *    so the grid does not reflow when 200 posters land. Layout shift
+ *    is the thing users notice in these apps today.
+ *  - **Error** keeps the tile's box and its name. An `<img>` with a
+ *    broken `src` collapses to a glyph and takes the row's height
+ *    with it; the fallback here is a `role="img"` carrying the same
+ *    `alt`, so the tile stays findable and the grid stays a grid.
+ *  - **Cached** is the case that bites: a `complete` image never
+ *    fires `load`, so a naive `onLoad`-only implementation leaves a
+ *    shimmering skeleton over a perfectly rendered poster forever.
+ *    The effect below checks `complete`/`naturalWidth` on mount and
+ *    on every `src` change.
+ *
+ * Those states are a `useStatus` machine rather than a
+ * `useState<string>`, which is what makes `loaded → error`
+ * impossible instead of merely unlikely — see `mediaStatus.ts`.
+ */
+export const MediaTile = ({
+  alt,
+  aspectRatio = "poster",
+  badge,
+  className,
+  fallback,
+  href,
+  src,
+  subtitle,
+  title,
+  ...figureProps
+}: MediaTileProps): ReactNode => {
+  const imageRef = useRef<HTMLImageElement>(null)
+
+  const { can, reset, status, transitionTo } = useStatus({
+    initialState: "loading",
+    transitions: mediaTransitions,
+  })
+
+  useEffect(() => {
+    // A new `src` is a new load, including after a failure.
+    reset()
+
+    const image = imageRef.current
+
+    if (!image?.complete) {
+      return
+    }
+
+    // `complete` with no intrinsic width is a *failed* cached
+    // load, not a successful one — the distinction browsers only
+    // expose this way.
+    if (image.naturalWidth > 0) {
+      if (can("loaded")) {
+        transitionTo("loaded")
+      }
+
+      return
+    }
+
+    if (can("error")) {
+      transitionTo("error")
+    }
+  }, [can, reset, transitionTo])
+
+  const media = (
+    <div
+      className={toClassName(
+        "relative overflow-hidden rounded-md bg-surface-sunken",
+        RATIO_CLASS[aspectRatio],
+      )}
+    >
+      {status === "error" ? (
+        <div
+          // Unconditionally an `img` carrying the same `alt`, even
+          // inside a link. The link's own `aria-label` is a name from
+          // the author and takes precedence, so this cannot
+          // double-name it — and a conditional role would leave the
+          // failure case nameless in exactly the arrangement (a
+          // poster grid of links) where it happens most.
+          aria-label={alt}
+          className="flex size-full flex-col items-center justify-center gap-1 p-2 text-center text-content-muted text-xs"
+          role="img"
+        >
+          {/* Words, not a glyph. The library ships zero SVGs by
+              rule, and a symbol character is not a safe substitute:
+              `▨` depends on the *system* having a font that covers
+              it, which the kiosk Pis and this repo's headless
+              Chromium do not — so the honest default is text, and an
+              app with an icon set passes `fallback`. */}
+          {fallback ?? <span>Image unavailable</span>}
+        </div>
+      ) : (
+        <>
+          {status === "loading" ? (
+            <Skeleton className="absolute inset-0 size-full" />
+          ) : null}
+
+          <img
+            alt={href ? "" : alt}
+            className={toClassName(
+              "size-full object-cover transition-opacity duration-(--duration-normal) ease-standard",
+              status === "loaded"
+                ? "opacity-100"
+                : "opacity-0",
+            )}
+            decoding="async"
+            loading="lazy"
+            onError={() => {
+              if (can("error")) {
+                transitionTo("error")
+              }
+            }}
+            onLoad={() => {
+              if (can("loaded")) {
+                transitionTo("loaded")
+              }
+            }}
+            ref={imageRef}
+            src={src}
+          />
+        </>
+      )}
+
+      {badge ? (
+        <div className="absolute top-2 start-2">
+          {badge}
+        </div>
+      ) : null}
+    </div>
+  )
+
+  const caption = (
+    <figcaption className="flex flex-col gap-0.5 pt-2">
+      <span className="truncate font-medium text-content-primary text-sm cq-sm:text-md">
+        {title}
+      </span>
+
+      {subtitle ? (
+        <span className="truncate text-content-muted text-xs">
+          {subtitle}
+        </span>
+      ) : null}
+    </figcaption>
+  )
+
+  return (
+    <figure
+      {...figureProps}
+      className={toClassName(
+        "@container flex flex-col",
+        className,
+      )}
+    >
+      {href ? (
+        // `aria-label` rather than the caption text, so the link's
+        // name is exactly the title — an agent matching
+        // `getByRole("link", { name: "Blade Runner" })` should not
+        // have to know whether a subtitle happened to be rendered.
+        // The `<img>` inside goes `alt=""` for the same reason: two
+        // names for one link is a screen reader reading it twice.
+        <a
+          aria-label={title}
+          className="group flex flex-col rounded-md outline-offset-2 hover:opacity-90 focus-visible:outline-solid focus-visible:outline-(length:--focus-ring-width) focus-visible:outline-focus-ring"
+          href={href}
+        >
+          {media}
+
+          {caption}
+        </a>
+      ) : (
+        <>
+          {media}
+
+          {caption}
+        </>
+      )}
+    </figure>
+  )
+}

package/src/MediaTile/mediaStatus.ts

@@ -0,0 +1,28 @@
+import type { StatusTransitions } from "@charcuterie/logic"
+
+export type MediaStatus = "error" | "loaded" | "loading"
+
+/**
+ * A component-owned machine, and the smallest honest example of what
+ * `createStatus` is for.
+ *
+ * `@charcuterie/logic` ships only the two machines that are
+ * genuinely fleet-wide — connection and async request — precisely so
+ * that a machine like this one lives next to the thing it describes.
+ * Three states, two of them terminal-ish, and the edges matter:
+ *
+ *  - `loaded → loading` and `error → loading` exist for a changed
+ *    `src`. Without them a poster grid that repaints with new URLs
+ *    keeps showing the old tile's error.
+ *  - `loaded → error` does **not** exist. A browser does not fire
+ *    `error` on an image it has already decoded, and an app that
+ *    thinks it saw that is misreading its own event wiring — so the
+ *    machine throws rather than flickering a fallback over a
+ *    perfectly good poster.
+ */
+export const mediaTransitions: StatusTransitions<MediaStatus> =
+  {
+    error: ["loading"],
+    loaded: ["loading"],
+    loading: ["error", "loaded"],
+  }