@charcuterie/ui 3.15.0 → 3.16.0

package/src/Combobox/Combobox.tsx

@@ -71,6 +71,13 @@ export type ComboboxProps = {
 
 const AUTO_VIRTUALIZE_THRESHOLD = 100
 
+/**
+ * How many frames the open seed will wait for the panel to be capped
+ * before it gives up on centring the chosen row. A few is all
+ * floating-ui's `size` middleware needs.
+ */
+const SEED_SCROLL_ATTEMPTS = 5
+
 const getOptionText = (item: ListboxItem) =>
   (
     item.textValue ??
@@ -288,6 +295,19 @@ export const Combobox = ({
   // short of it.
   const pendingSeedIndex = useRef<null | number>(null)
 
+  // Retrying the seed's centring scroll. `useAnchoredOverlay` caps the
+  // panel's height by writing `style.maxHeight` straight onto the
+  // floating element inside floating-ui's `size` middleware —
+  // deliberately outside the `floatingStyles` React manages, so a
+  // keystroke cannot wipe it. The cost lands here: it arrives a frame
+  // after the open seed, announces itself with no re-render, and until
+  // it does the list stands at its full content height with **nothing to
+  // scroll**. A seed scroll issued then is dropped without a trace,
+  // which is how the first build of this fix highlighted the chosen row
+  // and still left it off screen in a real app.
+  const [seedScrollAttempt, setSeedScrollAttempt] =
+    useState(0)
+
   useEffect(() => {
     if (!isVisible) {
       hasSeededOnOpen.current = false
@@ -319,6 +339,8 @@ export const Combobox = ({
 
     pendingSeedIndex.current = openSeedIndex
 
+    setSeedScrollAttempt(0)
+
     setActiveIndex(openSeedIndex)
   }, [
     isVisible,
@@ -536,6 +558,27 @@ export const Combobox = ({
       return
     }
 
+    const list = listElement.current
+
+    if (
+      isSeeding &&
+      seedScrollAttempt < SEED_SCROLL_ATTEMPTS &&
+      list !== null &&
+      list.scrollHeight <= list.clientHeight
+    ) {
+      // Nothing to scroll yet — the panel is still at its full height.
+      // Hold the seed and look again next frame rather than scroll a
+      // container that cannot move. Bounded, so a list that genuinely
+      // fits its panel stops instead of spinning.
+      const frame = requestAnimationFrame(() => {
+        setSeedScrollAttempt((attempt) => attempt + 1)
+      })
+
+      return () => {
+        cancelAnimationFrame(frame)
+      }
+    }
+
     pendingSeedIndex.current = null
 
     // The open seed centres its row; an arrow move only pulls the next
@@ -567,6 +610,7 @@ export const Combobox = ({
     isWindowed,
     listboxId,
     rowVirtualizer.scrollToIndex,
+    seedScrollAttempt,
   ])
 
   // ─── Attached mode: drive the consumer's input ──────────────────────

package/src/RadioGroup/RadioGroup.mdx

@@ -47,6 +47,68 @@ at.
 
 <Canvas of={RadioGroupStories.AllStates} />
 
+## `itemShape="tile"` — the choice tile
+
+A bordered card carrying a name, a line of help and a selected surface, laid out in a grid
+that gains columns with its **container**. It is a prop rather than a third component
+because **only the box changes**: the element, the `radio` role, the roving tab stop,
+selection-follows-focus and `isReadOnly` are the ones already tested on the row shape. A
+tile with its border taken away is a row.
+
+`SegmentedControl` earns its own file by being a different *control* — one connected strip,
+no radio affordance, options too short to carry a sentence. A tile is this control with a
+border, which is a different reason.
+
+<Canvas of={RadioGroupStories.Tiles} />
+
+Four apps in the fleet had each hand-painted this shape — ten instances between them — and
+**not one carried `aria-checked`**. Every one was a bare `<button>` or `<a>` whose selection
+was visible only as colour: correct to an eye, silent to a screen reader, and announced as
+neither pressed nor "3 of 6". That is what this prop is for, and it is why the semantics are
+not the part an app should be writing.
+
+Eight of the ten had a **second line** under the name, which is also why none of them
+reached for `RadioGroup`: a plain-text `label` could not express it. `hint` can, and it
+renders on a row as readily as on a tile.
+
+### The selected tile is an edge and a surface, never a fill
+
+The chosen tile takes the accent on its **border** and lifts to `surface-overlay`; the radio
+dot inside it is unchanged and is still the thing a screen reader reads. A state told in
+colour alone is the one state a monochrome ePaper build cannot show at all — the same reason
+`Stepper` refuses to say "done" with a hue.
+
+### A tile may lead with an icon
+
+`icon` is `tile` only — a row already leads with its radio, and a second mark either side of
+it has nowhere to sit — and it is `aria-hidden` by construction, because the name it sits
+above is inside the same button. The library still ships no icons; apps bring their own.
+
+<Canvas of={RadioGroupStories.TilesWithIcons} />
+
+## The grid takes its columns from the container
+
+`repeat(auto-fill, minmax(min(var(--charcuterie-tile-min-inline-size), 100%), 1fr))`, and
+each of those three parts is load-bearing:
+
+- **`auto-fill`, not `auto-fit`.** `auto-fit` collapses the empty tracks and lets the
+  survivors share the whole row, so six tiles in a 2560px container become six 420px slabs —
+  the full-width-row shape in a new costume. `auto-fill` keeps the empty tracks, so a tile
+  stays a tile and the grid simply has room to spare.
+- **`min(…, 100%)`.** Without it the 200px floor overflows a container narrower than one
+  tile, which is a horizontal scrollbar in the Narrow View.
+- **A custom property, not an interpolated class.** Tailwind scans source *text* for
+  complete class strings, so `` `grid-cols-[…${n}px…]` `` generates nothing, paints nothing
+  and reports nothing. `minTileInlineSize` lands in `--charcuterie-tile-min-inline-size`,
+  which one written-out literal reads.
+
+This is **not** `useAdaptiveColumns`, and the difference is which question is being asked.
+That hook buys a column with **height**, for an unbounded gallery that is going to scroll. A
+radio group is a bounded set of options inside a form section, where the only question is
+how many fit across the box it was handed.
+
+<Canvas of={RadioGroupStories.Responsive} />
+
 ## A read-only group shows the choice without moving it
 
 `isReadOnly` severs the one link that defines this component — selection follows focus — so

package/src/RadioGroup/RadioGroup.stories.tsx

@@ -2,10 +2,16 @@ import type { Meta, StoryObj } from "@storybook/react"
 
 import { controlSizeArgType } from "../argTypes.storyHelpers.ts"
 import {
+  ContainerBoard,
   StoryCell,
   StoryGrid,
   StorySection,
 } from "../board.storyHelpers.tsx"
+import {
+  InboxIcon,
+  PlayIcon,
+  SearchIcon,
+} from "../icons.storyHelpers.tsx"
 import type { RadioItem } from "./RadioGroup.tsx"
 import { RadioGroup } from "./RadioGroup.tsx"
 
@@ -23,6 +29,55 @@ const NAMING_ITEMS: RadioItem[] = [
   { label: "Use a custom pattern", value: "custom" },
 ]
 
+/**
+ * The same control with a name and a line of help per option — the
+ * shape four apps in the fleet had each hand-painted, and the reason
+ * none of them reached for this component.
+ */
+const IMPORT_ITEMS: RadioItem[] = [
+  {
+    hint: "Nothing is left behind at the source.",
+    label: "Move the files",
+    value: "move",
+  },
+  {
+    hint: "Twice the space, and the source is untouched.",
+    label: "Copy the files",
+    value: "copy",
+  },
+  {
+    hint: "One copy on disk, two names for it. Same volume only.",
+    label: "Hard link",
+    value: "link",
+  },
+  {
+    hint: "Catalogue them where they are.",
+    label: "Leave in place",
+    value: "leave",
+  },
+]
+
+const ICON_ITEMS: RadioItem[] = [
+  {
+    hint: "Everything that arrived since the last run.",
+    icon: <InboxIcon />,
+    label: "New arrivals",
+    value: "new",
+  },
+  {
+    hint: "Whatever the saved query matches today.",
+    icon: <SearchIcon />,
+    label: "Saved search",
+    value: "search",
+  },
+  {
+    hint: "Pick up where the last session stopped.",
+    icon: <PlayIcon />,
+    label: "Continue",
+    value: "continue",
+  },
+]
+
 const meta = {
   title: "Components/Controls/RadioGroup",
   component: RadioGroup,
@@ -31,7 +86,12 @@ const meta = {
   // The component's own defaults, restated — Storybook does not seed
   // `args` from docgen, so an unstated default shows in the props
   // table with nothing selected in its control.
-  args: { isReadOnly: false, size: "md" },
+  args: {
+    isReadOnly: false,
+    itemShape: "row",
+    minTileInlineSize: 200,
+    size: "md",
+  },
 } satisfies Meta<typeof RadioGroup>
 
 export default meta
@@ -61,6 +121,38 @@ export const AllVariants: Story = {
   ),
 }
 
+/**
+ * `itemShape="tile"` is the same `radiogroup` in a box: one choice
+ * out of several, exclusive, announced as "3 of 6", drawn as cards
+ * in a grid that gains columns with its **container**.
+ *
+ * The selected tile is an accent **edge** and a lifted surface, not
+ * a fill — the radio dot inside it is still the thing a screen
+ * reader reads, and a state told in colour alone is the one state a
+ * monochrome ePaper build cannot show.
+ */
+export const Tiles: Story = {
+  args: {
+    items: IMPORT_ITEMS,
+    itemShape: "tile",
+    label: "On import",
+  },
+}
+
+/**
+ * A tile may lead with an icon. The library ships none — these are
+ * story-only SVGs, exactly what an app passes — and the icon is
+ * `aria-hidden` by construction, because the name it sits above is
+ * in the same button.
+ */
+export const TilesWithIcons: Story = {
+  args: {
+    items: ICON_ITEMS,
+    itemShape: "tile",
+    label: "Where to start",
+  },
+}
+
 const STATE_ITEMS: RadioItem[] = [
   { label: "Match the Plex agent", value: "plex" },
   { label: "Match AniDB titles", value: "anidb" },
@@ -125,11 +217,82 @@ export const AllStates: Story = {
             selectedValue="anidb"
           />
         </StoryCell>
+
+        <StoryCell align="stretch" label="a hint on a row">
+          <RadioGroup
+            {...controlProps}
+            items={IMPORT_ITEMS}
+            label="On import, as rows"
+          />
+        </StoryCell>
+
+        <StoryCell
+          align="stretch"
+          label="tiles, third chosen"
+        >
+          <RadioGroup
+            {...controlProps}
+            items={IMPORT_ITEMS}
+            itemShape="tile"
+            label="On import, as tiles"
+            selectedValue="link"
+          />
+        </StoryCell>
+
+        <StoryCell
+          align="stretch"
+          label="tiles, read-only and disabled"
+        >
+          <RadioGroup
+            {...controlProps}
+            isReadOnly
+            items={[
+              ...IMPORT_ITEMS.slice(0, 2),
+              {
+                hint: "The source volume is read-only.",
+                isDisabled: true,
+                label: "Hard link",
+                value: "link",
+              },
+            ]}
+            itemShape="tile"
+            label="On import, read-only tiles"
+            selectedValue="copy"
+          />
+        </StoryCell>
       </StoryGrid>
     </StorySection>
   ),
 }
 
+/**
+ * Column count comes from the **container**, never the window — the
+ * standing rule for any list of cards, and the reason this board
+ * varies a wrapper's width rather than the viewport's.
+ *
+ * At the 200px default floor: one track at 15rem, one at 24rem, two
+ * at 34rem. `auto-fill` and deliberately not `auto-fit`, so the
+ * tiles keep their size in a container with room to spare instead of
+ * stretching to fill it.
+ */
+export const Responsive: Story = {
+  args: {
+    items: IMPORT_ITEMS,
+    itemShape: "tile",
+    label: "On import",
+  },
+  render: (controlProps) => (
+    <ContainerBoard>
+      {(width) => (
+        <RadioGroup
+          {...controlProps}
+          label={`On import at ${width}`}
+        />
+      )}
+    </ContainerBoard>
+  ),
+}
+
 /**
  * The complete keyboard path. Tab enters the group **once** — the
  * roving-tabindex rule — then the arrow keys move and check

package/src/RadioGroup/RadioGroup.test.tsx

@@ -7,8 +7,14 @@ import { mountStory } from "../mountStory.testHelpers.ts"
 import { expectAgentDrivable } from "../testing/index.ts"
 import * as stories from "./RadioGroup.stories.tsx"
 
-const { AllStates, Default, Interactive } =
-  composeStories(stories)
+const {
+  AllStates,
+  Default,
+  Interactive,
+  Responsive,
+  Tiles,
+  TilesWithIcons,
+} = composeStories(stories)
 
 /**
  * `querySelectorAll` rather than `getAllByRole("radio")`: a board
@@ -230,3 +236,174 @@ test("a read-only group is announced and its choice cannot move", async () => {
 
   await expectNoAxeViolations(canvasElement)
 })
+
+/**
+ * The tile shape is the same control in a box, so what these assert
+ * is that **nothing about the control changed** — role, exclusivity,
+ * the roving tab stop and selection-follows-focus are the ones
+ * already proven above, driven through the tile story.
+ */
+test("a tile group is still a radiogroup of radios", async () => {
+  const { canvas, canvasElement } = await mountStory(Tiles)
+
+  const group = expectAgentDrivable(canvas, {
+    name: "On import",
+    role: "radiogroup",
+  })
+
+  const options = getOptions(group)
+
+  await expect(options).toHaveLength(4)
+
+  await waitFor(() => {
+    expect(
+      options.filter(
+        (one) =>
+          one.getAttribute("aria-checked") === "true",
+      ),
+    ).toHaveLength(1)
+  })
+
+  // Exactly one tab stop — the roving rule survives the layout
+  // change, because the layout is all that changed.
+  await expect(
+    options.filter((one) => one.tabIndex === 0),
+  ).toHaveLength(1)
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("a tile's hint is part of the option's accessible name", async () => {
+  const { canvas } = await mountStory(Tiles)
+
+  // The reason the hint is rendered inside the button rather than
+  // beside it: a hint a screen reader never reads is a hint half the
+  // audience does not have. `getByRole` computes the name from
+  // contents, so this query only passes if it is in there.
+  expectAgentDrivable(canvas, {
+    name: "Hard link One copy on disk, two names for it. Same volume only.",
+    role: "radio",
+  })
+})
+
+test("a tile icon is decoration and stays out of the name", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(TilesWithIcons)
+
+  // Named by its words alone. An icon that joined the name would
+  // make this query fail, which is the whole reason it is
+  // `aria-hidden`.
+  expectAgentDrivable(canvas, {
+    name: "New arrivals Everything that arrived since the last run.",
+    role: "radio",
+  })
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("the arrow keys still move and check inside a tile grid", async () => {
+  const { canvas } = await mountStory(Tiles)
+
+  const options = getOptions(
+    expectAgentDrivable(canvas, {
+      name: "On import",
+      role: "radiogroup",
+    }),
+  )
+
+  options[0]?.focus()
+
+  // ArrowRight in a grid is `focus.next`, exactly as ArrowDown is in
+  // a stack. APG gives a radio group one traversal order, and a grid
+  // does not earn a second one.
+  await userEvent.keyboard("{ArrowRight}")
+
+  await waitFor(() => {
+    expect(options[1]).toHaveAttribute(
+      "aria-checked",
+      "true",
+    )
+  })
+})
+
+/**
+ * The three things about the box that fail *silently*, so all three
+ * are read off `getComputedStyle` in a real browser rather than off
+ * a class name. A class-name assertion would have passed while the
+ * grid was one column, because the class really was in the DOM.
+ */
+test("a tile carries a border, and the chosen one carries the accent", async () => {
+  const { canvas } = await mountStory(Tiles)
+
+  const options = getOptions(
+    expectAgentDrivable(canvas, {
+      name: "On import",
+      role: "radiogroup",
+    }),
+  )
+
+  const [first, second] = options as [
+    HTMLButtonElement,
+    HTMLButtonElement,
+  ]
+
+  await waitFor(() => {
+    expect(first).toHaveAttribute("aria-checked", "true")
+  })
+
+  const chosen = getComputedStyle(first)
+
+  const other = getComputedStyle(second)
+
+  await expect(
+    Number.parseFloat(chosen.borderTopWidth),
+  ).toBeGreaterThan(0)
+
+  // A border and a surface, never colour alone — but the two tiles
+  // must still differ, or "chosen" is told by the radio dot only.
+  await expect(chosen.borderTopColor).not.toBe(
+    other.borderTopColor,
+  )
+
+  await expect(chosen.backgroundColor).not.toBe(
+    other.backgroundColor,
+  )
+})
+
+test("the column count comes from the container, not the window", async () => {
+  const { canvas } = await mountStory(Responsive)
+
+  const getColumnCount = (name: string) =>
+    getComputedStyle(
+      expectAgentDrivable(canvas, {
+        name,
+        role: "radiogroup",
+      }),
+    ).gridTemplateColumns.split(" ").length
+
+  // One viewport, three container widths, and the answer changes
+  // with the container. Every panel is the same window.
+  await expect(getColumnCount("On import at 15rem")).toBe(1)
+
+  await expect(getColumnCount("On import at 34rem")).toBe(2)
+})
+
+test("a tile grid never overflows a container narrower than one tile", async () => {
+  const { canvas } = await mountStory(Responsive)
+
+  const group = expectAgentDrivable(canvas, {
+    name: "On import at 15rem",
+    role: "radiogroup",
+  })
+
+  // 15rem is 240px and the tile floor is 200px, so this passes
+  // either way — the case that matters is the `min(…, 100%)`, which
+  // is what stops a 200px floor from becoming a horizontal
+  // scrollbar in the Narrow View.
+  await expect(
+    group.getBoundingClientRect().width,
+  ).toBeLessThanOrEqual(
+    (group.parentElement?.getBoundingClientRect().width ??
+      0) + 1,
+  )
+})