@charcuterie/ui 3.31.0 → 3.33.0

package/src/VirtualizedGrid/VirtualizedGrid.test.tsx

@@ -1,5 +1,5 @@
 import { composeStories } from "@storybook/react"
-import { expect, waitFor } from "storybook/test"
+import { expect, userEvent, waitFor } from "storybook/test"
 import { test } from "vitest"
 
 import { mountStory } from "../mountStory.testHelpers.ts"
@@ -31,10 +31,17 @@ import * as stories from "./VirtualizedGrid.stories.tsx"
  *    and "list, 40 items" on a list of 2,000.
  *  - **An empty list reserves no space.** The state a filter lands
  *    on.
+ *  - **A hidden panel measures nothing, and revealing it does not
+ *    scroll.** The regression that took Docket's Triage tab bar off
+ *    the top of the screen.
  */
 
-const { AllStates, Default, InShellScrollRegion } =
-  composeStories(stories)
+const {
+  AllStates,
+  Default,
+  InHiddenTabPanel,
+  InShellScrollRegion,
+} = composeStories(stories)
 
 const getLists = (canvasElement: HTMLElement) => [
   ...canvasElement.querySelectorAll<HTMLElement>("ul"),
@@ -205,6 +212,118 @@ test("a grid inside Shell follows Main's one scroll region", async () => {
   ).toBe("0px")
 })
 
+test("a grid inside a hidden panel mounts nothing and reveals without scrolling", async () => {
+  const { canvasElement } = await mountStory(
+    InHiddenTabPanel,
+  )
+
+  const main =
+    canvasElement.querySelector<HTMLElement>("main")
+
+  if (!main) {
+    throw new Error("The tab story has no Main element.")
+  }
+
+  await waitFor(async () => {
+    await expect(
+      getRowIndexes(canvasElement).length,
+    ).toBeGreaterThan(0)
+  })
+
+  const hiddenPanel = canvasElement.querySelector(
+    '[role="tabpanel"][hidden]',
+  )
+
+  if (!hiddenPanel) {
+    throw new Error("Both tab panels are showing.")
+  }
+
+  /*
+   * The direct observable, and the one the fix is: `display: none`
+   * gives an element no box, so nothing inside it can be measured.
+   * A grid that mounted its rows anyway would record a 0px-wide
+   * container and 0px-tall rows as facts.
+   */
+  /*
+   * THE ASSERTION THAT DISCRIMINATES, and it is the cause rather
+   * than the symptom on purpose.
+   *
+   * `display: none` gives an element no box, so nothing inside it
+   * can be measured. A grid that mounted its rows anyway records a
+   * 0px-wide container and 0px-tall rows as facts, and the
+   * virtualizer then reads the correction as a resize and
+   * compensates the scroll position for it.
+   *
+   * Whether that compensation actually lands is a RACE — between
+   * the `ResizeObserver` delivering the real row heights and the
+   * layout effect correcting `scrollMargin`. In Docket it landed
+   * and moved `Main` by 266px, 190px and 1,190px on three
+   * different switches; in this story it does not land at all. So
+   * the symptom is not what is asserted here. This is: with
+   * nothing mounted, the race has no entrants.
+   */
+  await expect(
+    hiddenPanel.querySelectorAll("ul").length,
+  ).toBe(0)
+
+  const tabs = [
+    ...canvasElement.querySelectorAll<HTMLElement>(
+      '[role="tab"]',
+    ),
+  ]
+
+  const nextTab = tabs.find(
+    (tab) => tab.getAttribute("aria-selected") === "false",
+  )
+
+  if (!nextTab) {
+    throw new Error("No unselected tab to switch to.")
+  }
+
+  await expect(main.scrollTop).toBe(0)
+
+  await userEvent.click(nextTab)
+
+  /**
+   * The list inside the panel that is SHOWING. Scoping matters:
+   * without the gate the hidden panel still holds a `<ul>`, and a
+   * query that took the first one in the canvas would watch the
+   * panel that was just put away and settle before the revealed
+   * one had measured anything.
+   */
+  const getShownList = () => {
+    const shown = canvasElement.querySelector(
+      '[role="tabpanel"]:not([hidden])',
+    )
+
+    const list = shown?.querySelector<HTMLElement>("ul")
+
+    if (!list) {
+      throw new Error("The shown panel has no grid.")
+    }
+
+    return list
+  }
+
+  // Wait for the revealed grid to have MEASURED, not merely to
+  // have mounted — the adjustment, when it happens, happens on the
+  // virtualizer's resize path.
+  await waitFor(async () => {
+    await expect(
+      Number(
+        getShownList().style.paddingBlockEnd.replace(
+          "px",
+          "",
+        ),
+      ),
+    ).toBeGreaterThan(0)
+  })
+
+  // The symptom, kept as a guard rather than as the proof. It is
+  // free, and it is the sentence a reader of this file wants.
+  await expect(main.scrollTop).toBe(0)
+})
+
 test("a screen reader is told the real length", async () => {
   const { canvasElement } = await mountStory(Default)
 

package/src/VirtualizedGrid/VirtualizedGrid.tsx

@@ -157,6 +157,41 @@ export type VirtualizedGridProps<Item> = {
  * answer: the browser's `Ctrl+F` only searches what is mounted, and
  * so does "select all". A page that needs either owes its users a
  * search field of its own.
+ *
+ * ### Nothing is mounted until there is a box to measure
+ *
+ * `display: none` gives an element no boxes at all, so every
+ * measurement taken through one reads zero — and zero is the
+ * absence of a measurement, not a measurement of nothing. A grid
+ * inside a `hidden` tab panel, a collapsed disclosure or a closed
+ * `<details>` therefore measures a 0px container (one column) and
+ * 0px-tall rows, and the virtualizer stores those as facts.
+ *
+ * Revealing the panel corrects all of them at once, and the
+ * virtualizer reads a correction as a **resize**. That is the one
+ * event it is entitled to move the scroll position for: an item
+ * above the viewport that grows must be compensated for, or the
+ * page slides under the reader. So it compensates — for a growth
+ * that never happened — and scrolls the shared scroll owner down
+ * by roughly the distance from the top of the region to the top of
+ * the grid.
+ *
+ * Whether the compensation lands is a race between the
+ * `ResizeObserver` delivering the real row heights and the layout
+ * effect correcting `scrollMargin`, so the symptom is intermittent
+ * and its size varies. Docket's Triage bar is where it was found:
+ * one switch moved `Main` 266px, another 190px, another 1,190px,
+ * and the tab bar went off the top of the screen. The cause is not
+ * the tab bar, and fixing it there would have left every other
+ * host of a hidden grid broken.
+ *
+ * `isLaidOut` is the gate. While the container has no box the
+ * windowed grid is not mounted, so there is nothing to measure
+ * wrongly and no virtualizer to mislead; it mounts when the box
+ * arrives and measures once, correctly. The cost is that a
+ * revealed grid re-measures from its estimate instead of resuming
+ * a cache — the same thing a routed tab does, and the reason a
+ * routed tab never had this bug.
  */
 export const VirtualizedGrid = <Item,>({
   blockSizeResolver,
@@ -227,7 +262,8 @@ export const VirtualizedGrid = <Item,>({
       )}
       ref={layout.containerRef}
     >
-      {scrollOwner?.kind === "element" ? (
+      {!layout.isLaidOut ? null : scrollOwner?.kind ===
+        "element" ? (
         <ElementGrid
           {...gridProps}
           scrollOwner={scrollOwner}

package/src/index.ts

@@ -37,6 +37,11 @@ export type {
   AccordionProps,
 } from "./Accordion/Accordion.tsx"
 export { Accordion } from "./Accordion/Accordion.tsx"
+export type {
+  ActionTileItem,
+  ActionTilesProps,
+} from "./ActionTiles/ActionTiles.tsx"
+export { ActionTiles } from "./ActionTiles/ActionTiles.tsx"
 export type { AdaptiveGridProps } from "./AdaptiveGrid/AdaptiveGrid.tsx"
 export { AdaptiveGrid } from "./AdaptiveGrid/AdaptiveGrid.tsx"
 export type { ColumnChoice } from "./AdaptiveGrid/chooseColumns.ts"

package/src/sourceRules.test.ts

@@ -537,7 +537,15 @@ test("the barrel is the only place components are re-exported", async () => {
   // active-path rule an app's tests want to assert directly, and
   // `useNavLayout.ts`, because the app has to read the width rule to
   // know which corner to render into.
-  expect(componentNames.length).toBe(61)
+  //
+  // `ActionTiles` is +1 -> 62. It is `RadioGroup itemShape="tile"`
+  // with the radio taken away: the box is shared through
+  // `tileStyles.ts`, and nothing else is. The 2026-08-25 record that
+  // made the choice tile a `RadioGroup` shape named this case under
+  // what it deliberately does not cover — a tile that navigates is
+  // not a radio, and giving one `aria-checked` would be worse than
+  // the paint it replaced.
+  expect(componentNames.length).toBe(62)
 
   for (const name of componentNames) {
     expect(barrel).toContain(`export { ${name} }`)

package/src/tileStyles.ts

@@ -0,0 +1,118 @@
+/**
+ * The tile shape, shared by the two components that draw it.
+ *
+ * A tile is a bordered card carrying a name and a line of help, laid
+ * out in a grid that gains columns with its CONTAINER. `RadioGroup`
+ * draws one per option when `itemShape="tile"`; `ActionTiles` draws
+ * one per action. The two must be the **same box** — a page that puts
+ * "which activity" beside "what would you like to do" would otherwise
+ * show two cards with different padding, different corners and
+ * different gaps, which is the drift this file exists to make
+ * impossible.
+ *
+ * Same argument as `CONTROL_BASE_CLASS`, which `Button` and
+ * `ButtonLink` share for the same reason: "identical" spelled as two
+ * copies of one string is a promise that survives exactly one edit.
+ *
+ * These were `RadioGroup`'s private constants until `ActionTiles`
+ * shipped. Nothing about their values changed on the way out.
+ */
+
+import type { ControlSize } from "@charcuterie/tokens"
+
+/**
+ * A tile is a card, so its padding is a card's rather than a
+ * control's — enough that the border reads as a box around content
+ * and not as an outline on a line of text.
+ *
+ * This is also the whole reason `ActionTiles` exists rather than a
+ * `Button` with a `className`: a `Button` is sized by
+ * `h-(--control-height-md)` and carries **no block padding at all**,
+ * so an app that reaches for `height: auto` to let one wrap gets a
+ * two-line card with `padding: 0` down its block axis and no error
+ * anywhere. QueuePilot's queue-type chooser shipped exactly that.
+ */
+export const TILE_PADDING_CLASS: Record<
+  ControlSize,
+  string
+> = {
+  sm: "px-3 py-2.5",
+  md: "px-3.5 py-3",
+  lg: "px-4 py-3.5",
+}
+
+/**
+ * The box, and only the box. Every state layered over it is a
+ * **border and a surface**, never colour alone — the same reason
+ * `Stepper` refuses to say "done" with a hue.
+ */
+export const TILE_BOX_CLASS =
+  "rounded-lg border border-border-subtle bg-surface-raised"
+
+export const TILE_TEXT_SIZE_CLASS: Record<
+  ControlSize,
+  string
+> = {
+  sm: "text-sm",
+  md: "text-md",
+  lg: "text-lg",
+}
+
+/**
+ * One step down from the tile's own text, and never below `xs`: a
+ * hint that keeps shrinking with the density axis is the 11px
+ * caption the 2026-08-10 ramp rebuild exists to have removed.
+ */
+export const TILE_HINT_TEXT_CLASS: Record<
+  ControlSize,
+  string
+> = {
+  sm: "text-xs",
+  md: "text-xs",
+  lg: "text-sm",
+}
+
+/**
+ * Wider than a list's row gaps: rows are separated by their leading,
+ * and tiles by nothing but the gap, so the same 6px that reads as a
+ * list reads as a seam between two cards.
+ */
+export const TILE_GAP_CLASS: Record<ControlSize, string> = {
+  sm: "gap-1.5",
+  md: "gap-2",
+  lg: "gap-3",
+}
+
+/**
+ * `auto-fill`, and deliberately not `auto-fit`.
+ *
+ * `auto-fit` collapses the empty tracks and lets the ones that
+ * remain 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%)` is what stops the floor overflowing a container
+ * narrower than one tile, which is the Narrow View and is otherwise
+ * a horizontal scrollbar on a phone.
+ *
+ * The floor arrives as a custom property rather than an interpolated
+ * class because Tailwind scans source *text* for complete class
+ * strings: `` `grid-cols-[…${n}px…]` `` generates nothing, paints
+ * nothing and reports nothing. One written-out literal reading
+ * `var(--charcuterie-tile-min-inline-size)` covers every width an
+ * app can ask for — the same reason `Card`'s accent edge goes
+ * through one property.
+ *
+ * This is **not** `useAdaptiveColumns`, and the difference is the
+ * question being asked. That hook buys a column with height, for an
+ * unbounded gallery that will scroll; a tile set is a bounded group
+ * inside a form section or a first step, where the only question is
+ * how many fit across the box it was given.
+ */
+export const TILE_COLUMNS_CLASS =
+  "grid-cols-[repeat(auto-fill,minmax(min(var(--charcuterie-tile-min-inline-size),100%),1fr))]"
+
+/** The property `TILE_COLUMNS_CLASS` reads its floor from. */
+export const TILE_MIN_INLINE_SIZE_PROPERTY =
+  "--charcuterie-tile-min-inline-size"