@charcuterie/ui 2.15.1 → 2.17.0

package/src/MediaTile/MediaTile.tsx

@@ -27,11 +27,27 @@ export type MediaTileProps = Omit<
   /** Shown in place of the image when it fails. */
   fallback?: ReactNode
   href?: string
+  /**
+   * Makes the tile a button. Hover, focus-visible and
+   * `cursor-pointer` come with it — wrapping `MediaTile` in a
+   * bare `<button>` is how a poster ends up with a text cursor
+   * and no hover at all. `href` wins if both are set.
+   */
+  isDisabled?: boolean
+  onClick?: ComponentPropsWithRef<"button">["onClick"]
   src?: string
   subtitle?: ReactNode
   title: string
 }
 
+/**
+ * Shared by the link and the button. A wrapped `<button
+ * className="block">` does not get these, which is why a
+ * Collection thumbnail looked inert under the pointer.
+ */
+const INTERACTIVE_CLASS =
+  "group flex cursor-pointer 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"
+
 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.
@@ -72,6 +88,8 @@ export const MediaTile = ({
   className,
   fallback,
   href,
+  isDisabled = false,
+  onClick,
   src,
   subtitle,
   title,
@@ -144,7 +162,7 @@ export const MediaTile = ({
           ) : null}
 
           <img
-            alt={href ? "" : alt}
+            alt={href || onClick ? "" : alt}
             className={toClassName(
               "size-full object-cover transition-opacity duration-(--duration-normal) ease-standard",
               status === "loaded"
@@ -177,19 +195,27 @@ export const MediaTile = ({
     </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}
+  const caption =
+    title === "" ? null : (
+      <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>
-      ) : null}
-    </figcaption>
-  )
+
+        {subtitle ? (
+          <span className="truncate text-content-muted text-xs">
+            {subtitle}
+          </span>
+        ) : null}
+      </figcaption>
+    )
+
+  // An empty `title` is how a tile sits next to a name the
+  // parent already printed. The control still needs a name, so
+  // the alt is the fallback — wrapping it in a nameless
+  // `<button>` was how Collection's cover thumbnail became
+  // unfindable as well as un-hoverable.
+  const accessibleName = title === "" ? alt : title
 
   return (
     <figure
@@ -207,14 +233,29 @@ export const MediaTile = ({
         // 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"
+          aria-label={accessibleName}
+          className={INTERACTIVE_CLASS}
           href={href}
         >
           {media}
 
           {caption}
         </a>
+      ) : onClick ? (
+        <button
+          aria-label={accessibleName}
+          className={toClassName(
+            INTERACTIVE_CLASS,
+            "w-full border-0 bg-transparent p-0 text-start disabled:cursor-not-allowed disabled:opacity-50 disabled:hover:opacity-50",
+          )}
+          disabled={isDisabled}
+          onClick={onClick}
+          type="button"
+        >
+          {media}
+
+          {caption}
+        </button>
       ) : (
         <>
           {media}

package/src/Overlay/useAnchoredOverlay.ts

@@ -225,7 +225,39 @@ export const useAnchoredOverlay = ({
   // input field and must be named.
   const generatedTriggerId = useUniqueId()
 
+  /**
+   * The trigger's OWN id wins over both.
+   *
+   * This hook used to mint an id and clone it over whatever the
+   * trigger already had, on the reasoning that the panel needs a
+   * stable target for `aria-labelledby`. It does — but any id serves
+   * that purpose, including the caller's, and overwriting had a
+   * consequence nobody traced: `Field` clones a `controlId` onto its
+   * child and renders `<label htmlFor={controlId}>`, so for every
+   * `Picker`/`Listbox`/`Combobox`/`Menu` inside a `Field` the label
+   * pointed at an element that did not exist. Measured in a real
+   * browser: zero nodes carried the id the `<label>` named.
+   *
+   * That is the exact defect `Field`'s docstring calls "precisely the
+   * defect this component was built to make impossible" — arriving by
+   * a different route, and silent, because a dangling `htmlFor`
+   * throws nothing and shows nothing.
+   *
+   * Preferring the child's id fixes the label without weakening the
+   * panel: `aria-labelledby` now points at the caller's id instead of
+   * a generated one, which is the same element either way.
+   *
+   * Two rediscoveries of the overwrite are already in the fleet —
+   * queuepilot and mux-magic both moved their e2e handles to
+   * `data-testid` because `id` "did not survive". `data-testid` is
+   * still the more robust handle, but `id` is no longer a trap.
+   */
+  const triggerOwnId = (
+    trigger?.props as { id?: string } | undefined
+  )?.id
+
   const triggerId =
+    triggerOwnId ??
     (referenceProps.id as string | undefined) ??
     generatedTriggerId
 

package/src/Picker/Picker.mdx

@@ -46,6 +46,37 @@ text of the whole node.
 
 <Canvas of={PickerStories.AllStates} />
 
+## The trigger is flush — the parent owns the gap
+
+`Picker` is a `Button`. It has **no outer margin**. Next to a text
+label it sits hard against the last word, which is how queuepilot's
+"Chapters queued per turn" landed flush on the `[2 Default]` trigger,
+and why that same app already had a one-off `#setmodal .fieldselect {
+margin-left: 10px }` for the *other* inline pickers.
+
+Do not put the gutter on `Picker`. A control that ships its own
+margin is a control that fights `Field` (`flex flex-col gap-1.5`) and
+every toolbar row. The parent that decided to sit text next to a
+trigger also owns the space:
+
+```tsx
+{/* stacked — this is Field's job */}
+<Field label="Chapters queued per turn" description="…">
+  <Picker label="Chapters queued per turn" … />
+</Field>
+
+{/* inline — the row owns the gap */}
+<span className="inline-flex items-center gap-2.5">
+  Chapters queued per turn
+  <Picker label="Chapters queued per turn" … />
+</span>
+```
+
+The same rule is `Button`, `Select`, and a `Listbox` trigger. They are
+all flush; they are all the same trap.
+
+<Canvas of={PickerStories.NextToText} />
+
 ## `id` does not survive; `data-testid` does
 
 `useAnchoredOverlay` overwrites the trigger's `id` with a generated one so the portalled

package/src/Picker/Picker.stories.tsx

@@ -12,6 +12,7 @@ import {
   StoryRow,
   StorySection,
 } from "../board.storyHelpers.tsx"
+import { Field } from "../Field/Field.tsx"
 import type { PickerOption } from "./Picker.tsx"
 import { Picker } from "./Picker.tsx"
 
@@ -182,3 +183,76 @@ export const Interactive: Story = {
     />
   ),
 }
+
+const COUNTS: PickerOption[] = [
+  { label: "1", value: "1" },
+  {
+    label: (
+      <span className="flex items-center gap-2">
+        <span>2</span>
+        <Badge intent="neutral" size="sm">
+          Default
+        </Badge>
+      </span>
+    ),
+    textValue: "2 Default",
+    value: "2",
+  },
+  { label: "Custom…", value: "custom" },
+]
+
+/**
+ * The trigger has no outer margin. Sitting it next to a label without
+ * a parent gap is the flush-against-the-word bug; `Field` or an
+ * `inline-flex gap-*` row is the parent owning the gutter.
+ */
+export const NextToText: Story = {
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <StorySection title="Flush — the parent gave it no gap">
+        <StoryRow>
+          <span>
+            Chapters queued per turn{" "}
+            <Picker
+              label="Flush count"
+              onChange={() => undefined}
+              options={COUNTS}
+              size="sm"
+              value="2"
+            />
+          </span>
+        </StoryRow>
+      </StorySection>
+      <StorySection title="Inline — the row owns the gap">
+        <StoryRow>
+          <span className="inline-flex items-center gap-2.5">
+            Chapters queued per turn
+            <Picker
+              label="Inline count"
+              onChange={() => undefined}
+              options={COUNTS}
+              size="sm"
+              value="2"
+            />
+          </span>
+        </StoryRow>
+      </StorySection>
+      <StorySection title="Stacked — Field owns the gap">
+        <StoryRow>
+          <Field
+            description="How long this entry’s turn is when the queue reaches it."
+            label="Chapters queued per turn"
+          >
+            <Picker
+              label="Stacked count"
+              onChange={() => undefined}
+              options={COUNTS}
+              size="sm"
+              value="2"
+            />
+          </Field>
+        </StoryRow>
+      </StorySection>
+    </div>
+  ),
+}

package/src/Picker/Picker.test.tsx

@@ -7,7 +7,7 @@ import { mountStory } from "../mountStory.testHelpers.ts"
 import { expectAgentDrivable } from "../testing/index.ts"
 import * as stories from "./Picker.stories.tsx"
 
-const { AllStates, Default, Interactive } =
+const { AllStates, Default, Interactive, NextToText } =
   composeStories(stories)
 
 test("the trigger's accessible name carries the current value", async () => {
@@ -83,6 +83,18 @@ test("a disabled picker does not open", async () => {
   )
 })
 
+test("an inline picker next to a label is still named and has no axe issues", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(NextToText)
+
+  expectAgentDrivable(canvas, {
+    name: "Inline count: 2 Default",
+    role: "button",
+  })
+
+  await expectNoAxeViolations(canvasElement)
+})
+
 test("a rich option label keeps a plain-string trigger via textValue", async () => {
   const { canvas, canvasElement } =
     await mountStory(AllStates)

package/src/Picker/Picker.tsx

@@ -108,14 +108,20 @@ export type PickerProps = Omit<
  *
  * Query it as `getByRole("button", { name: /^Language: / })`.
  *
- * ### `id` does not survive; `data-testid` does
+ * ### `id` survives — it did not always
  *
- * `useAnchoredOverlay` overwrites the trigger's `id` with a generated
- * one, so the portalled listbox can point `aria-labelledby` across at
- * it. An `id` passed here is therefore silently replaced — queuepilot
- * found this the hard way and switched its e2e handles to
- * `data-testid`, which nothing injects. Everything else on the button
- * (`data-*`, `onClick`, `form`, …) passes straight through.
+ * `useAnchoredOverlay` used to overwrite the trigger's `id` with a
+ * generated one so the portalled listbox could point `aria-labelledby`
+ * across at it. That silently broke `Field`, which renders
+ * `<label htmlFor>` against an id it clones onto its child: the label
+ * pointed at nothing for every overlay control in a `Field`. The hook
+ * now prefers the trigger's own id and mints one only when absent, so
+ * both the label and the panel name the same element.
+ *
+ * `data-testid` remains the sturdier e2e handle — queuepilot and
+ * mux-magic both moved to it while `id` was still being replaced — but
+ * `id` is no longer a trap. Everything else on the button (`data-*`,
+ * `onClick`, `form`, …) passes straight through.
  */
 export const Picker = ({
   appearance = "outline",

package/src/sourceRules.test.ts

@@ -499,6 +499,16 @@ const ENTRY_POINT_RUNTIMES: Record<
       // tree-shakeable, ~4 KB gz.
       "@tanstack/react-virtual",
       "react",
+      // `toClassName`'s conflict resolution — the third runtime
+      // dependency this package has ever taken. MIT, German origin
+      // (Dany Castillo), ~7 KB gz, no transitive deps.
+      //
+      // It earns the entry: without it `className` is not an escape
+      // hatch. A caller's `hidden` and the base `inline-flex` are
+      // display utilities at equal specificity, so the winner came
+      // from stylesheet source order and the caller could not win —
+      // silently, which is how it shipped broken in three repos.
+      "tailwind-merge",
     ],
     // The router seam's one shipped adapter, and the reason it is a
     // subpath rather than part of the barrel: `react-router` appears

package/src/toClassName.test.ts

@@ -0,0 +1,229 @@
+import { readdirSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+import { describe, expect, test } from "vitest"
+
+import {
+  type BadgeSize,
+  getControlClassName,
+} from "./controlStyles.ts"
+import { INTENT_APPEARANCE_CLASS } from "./intentStyles.ts"
+import { toClassName } from "./toClassName.ts"
+
+describe("a caller's class beats the base class", () => {
+  // The bug this file exists for. `CONTROL_BASE_CLASS` opens with
+  // `inline-flex`; both it and `hidden` are display utilities at equal
+  // specificity, so before the merge the winner was decided by
+  // stylesheet source order and the caller could not win.
+  test("display: `hidden` removes `inline-flex`", () => {
+    expect(
+      toClassName("inline-flex items-center", "hidden"),
+    ).toBe("items-center hidden")
+  })
+
+  test("the responsive form that shipped broken still works", () => {
+    // mail-sifter's header, verbatim: hide below `lg`, show above.
+    // The unprefixed `hidden` must beat the base `inline-flex` while
+    // the `lg:` variant is left alone — they are different breakpoints
+    // and must not cancel each other.
+    const result = toClassName(
+      "inline-flex cursor-pointer items-center",
+      "hidden lg:inline-flex",
+    )
+
+    expect(result).toContain("hidden")
+    expect(result).toContain("lg:inline-flex")
+    expect(result.split(" ")).not.toContain("inline-flex")
+  })
+
+  test.each([
+    ["rounded-md", "rounded-full"],
+    ["border-border-default", "border-transparent"],
+    ["bg-surface-base", "bg-surface-raised"],
+    ["whitespace-nowrap", "whitespace-normal"],
+    ["font-medium", "font-bold"],
+    ["h-(--control-height-md)", "h-(--control-height-lg)"],
+    ["px-(--control-padding-inline-md)", "px-0"],
+    ["text-sm", "text-lg"],
+    // Ours, not Tailwind's — registered explicitly in the merge
+    // config, and it would silently fail to merge without that.
+    ["ease-standard", "ease-linear"],
+  ])("%s is overridden by %s", (base, override) => {
+    expect(toClassName(base, override)).toBe(override)
+  })
+})
+
+describe("it does not over-merge", () => {
+  // The dangerous direction, and the reason this was measured rather
+  // than assumed: `text-md` is OUR font-size (theme.css bridges
+  // `--text-*` onto `--font-size-*`), and `text-content-primary` is a
+  // colour. A merge that classified both as `text-*` would silently
+  // drop the colour from every control in the package.
+  test("a custom font size does not eat a custom text colour", () => {
+    const result = toClassName(
+      "text-md",
+      "text-content-primary",
+    )
+
+    expect(result).toContain("text-md")
+    expect(result).toContain("text-content-primary")
+  })
+
+  test("a custom easing does not eat a duration", () => {
+    const result = toClassName(
+      "ease-standard duration-(--duration-fast)",
+    )
+
+    expect(result).toContain("ease-standard")
+    expect(result).toContain("duration-(--duration-fast)")
+  })
+
+  test("falsy parts are still dropped", () => {
+    expect(
+      toClassName(
+        "a-class",
+        false,
+        null,
+        undefined,
+        "b-class",
+      ),
+    ).toBe("a-class b-class")
+  })
+})
+
+/**
+ * Adopting a merge could in principle drop one of the package's OWN
+ * classes — a conflict we shipped on purpose, or one it misreads.
+ * These two tests are the evidence that it does not, and they are the
+ * reason the change is safe to make globally rather than only where a
+ * consumer `className` is folded in.
+ *
+ * They also fail loudly if a future class introduces a real internal
+ * conflict, which is worth knowing about on its own.
+ */
+describe("merging is a no-op on what this package emits", () => {
+  const walk = (dir: string): string[] =>
+    readdirSync(dir, { withFileTypes: true }).flatMap(
+      (entry) => {
+        const path = join(dir, entry.name)
+
+        if (entry.isDirectory()) {
+          return entry.name === "node_modules"
+            ? []
+            : walk(path)
+        }
+
+        return /\.tsx?$/.test(path) &&
+          !/\.test\./.test(path)
+          ? [path]
+          : []
+      },
+    )
+
+  const looksLikeClassList = (value: string) =>
+    value.includes(" ") &&
+    value
+      .split(" ")
+      .every((token) =>
+        /^[a-z0-9:[\]()\-_/.&>*+#!,%'"$@=~^|?]+$/i.test(
+          token,
+        ),
+      ) &&
+    /(flex|grid|text-|bg-|border|rounded|p[xytblr]?-|m[xytblr]?-|h-|w-|size-|gap-|items-|justify-|absolute|relative|hidden|block|inline|font-|shadow|outline|transition|duration|ease-|select-|cursor-|overflow|z-|opacity|ring|space-|min-|max-|whitespace|truncate|leading|tracking)/.test(
+      value,
+    )
+
+  test("every class-string literal in src survives untouched", () => {
+    const damaged: {
+      after: string
+      before: string
+      file: string
+    }[] = []
+
+    let checked = 0
+
+    for (const file of walk(
+      join(import.meta.dirname ?? "src"),
+    )) {
+      const source = readFileSync(file, "utf8")
+
+      for (const match of source.matchAll(
+        /"([a-z0-9][^"\n]*?)"/g,
+      )) {
+        const value = match[1]
+
+        if (!looksLikeClassList(value)) {
+          continue
+        }
+
+        checked++
+
+        const merged = toClassName(value)
+
+        if (merged !== value) {
+          damaged.push({
+            after: merged,
+            before: value,
+            file,
+          })
+        }
+      }
+    }
+
+    // A guard on the guard: if the heuristic stops matching, this
+    // test would pass by checking nothing.
+    expect(checked).toBeGreaterThan(300)
+    expect(damaged).toEqual([])
+  })
+
+  test("every composed control class string survives untouched", () => {
+    const intents = Object.keys(
+      INTENT_APPEARANCE_CLASS,
+    ) as (keyof typeof INTENT_APPEARANCE_CLASS)[]
+
+    const appearances = Object.keys(
+      INTENT_APPEARANCE_CLASS[intents[0]],
+    ) as (keyof (typeof INTENT_APPEARANCE_CLASS)[(typeof intents)[0]])[]
+
+    const damaged: string[] = []
+
+    let composed = 0
+
+    for (const intent of intents) {
+      for (const appearance of appearances) {
+        for (const size of [
+          "sm",
+          "md",
+          "lg",
+        ] as BadgeSize[] & string[]) {
+          for (const sizing of [
+            "control",
+            "icon",
+          ] as const) {
+            for (const isFullWidth of [false, true]) {
+              const value = getControlClassName({
+                appearance,
+                className: undefined,
+                disabledClass: "disabled:opacity-50",
+                intent,
+                isFullWidth,
+                size,
+                sizing,
+              })
+
+              composed++
+
+              // `getControlClassName` already routes through
+              // `toClassName`, so re-merging must be idempotent.
+              if (toClassName(value) !== value) {
+                damaged.push(value)
+              }
+            }
+          }
+        }
+      }
+    }
+
+    expect(composed).toBeGreaterThan(200)
+    expect(damaged).toEqual([])
+  })
+})

package/src/toClassName.ts

@@ -1,13 +1,74 @@
+import { extendTailwindMerge } from "tailwind-merge"
+
 /**
- * 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.
+ * `ease-standard` is ours, from the motion tokens — Tailwind ships
+ * `ease-linear`/`ease-in`/`ease-out`/`ease-in-out` and knows nothing
+ * about it. Without this it lands in no class group, so a caller
+ * passing `ease-linear` would get BOTH and the winner would be decided
+ * by stylesheet source order — exactly the bug this file now exists to
+ * prevent, one utility further along.
+ *
+ * Nothing else needs registering. Verified empirically rather than
+ * assumed: `toClassName.test.ts` asserts the merge is a no-op across
+ * every class string in this package and every string
+ * `getControlClassName` composes.
+ */
+const mergeClassNames = extendTailwindMerge({
+  extend: {
+    classGroups: { ease: [{ ease: ["standard"] }] },
+  },
+})
+
+/**
+ * Join a class list, and let a later class beat an earlier one that
+ * targets the same CSS property.
+ *
+ * ### Why this is not a plain join any more
+ *
+ * It was, and that was a bug. `getControlClassName` assembles
+ * `toClassName(CONTROL_BASE_CLASS, …, className)`, and
+ * `CONTROL_BASE_CLASS` opens with `inline-flex`. A caller writing
+ *
+ * ```tsx
+ * <Button className="hidden lg:inline-flex" />
+ * ```
+ *
+ * emitted `class="inline-flex … hidden lg:inline-flex"`. Both are
+ * display utilities at equal specificity, so the winner is decided by
+ * **source order in the generated stylesheet**, not by order in the
+ * class attribute — and the caller has no way to win. `className` is a
+ * documented escape hatch, and it did not work for the most common
+ * thing an escape hatch is used for.
+ *
+ * It failed *silently and invisibly*. mail-sifter's header used exactly
+ * that class to hide a duplicate button below `lg`; it never hid, and
+ * nobody noticed for weeks because at 390px the header happened to fit
+ * anyway. It only surfaced when an unrelated type-ramp change pushed the
+ * width to 427px and scrolled the page sideways. Two more repos hit the
+ * same shape independently.
+ *
+ * ### Why `tailwind-merge` and not `clsx`
+ *
+ * The old docblock argued against taking a dependency, on the grounds
+ * that a published component library's dependency list is inherited by
+ * consumers and that `clsx`'s object and nested-array forms make a
+ * className harder for the Tailwind scanner and for
+ * `tailwindCandidates.test.ts` to read statically.
+ *
+ * The first half still stands and this entry earns its place; the
+ * second half does not transfer. `tailwind-merge` does not change the
+ * *input* shape at all — this still takes a flat list of strings and
+ * conditionals, and every call site is still statically scannable. It
+ * changes only which of two conflicting classes survives.
+ *
+ * ### It is a no-op on everything this package emits
+ *
+ * Merging could in principle drop one of our own classes. It does not:
+ * the test file checks all 358 class-string literals in `src` and all
+ * 288 strings `getControlClassName` composes, and the merge changes
+ * none of them. So this only ever acts on a genuine caller conflict —
+ * which is the entire point.
  */
 export const toClassName = (
   ...parts: (false | string | null | undefined)[]
-) => parts.filter(Boolean).join(" ")
+) => mergeClassNames(parts.filter(Boolean).join(" "))