@charcuterie/ui 3.32.0 → 3.34.0

package/src/VirtualizedGrid/VirtualizedGrid.stories.tsx

@@ -10,6 +10,7 @@ import { Header } from "../Header/Header.tsx"
 import { Main } from "../Main/Main.tsx"
 import { SegmentedControl } from "../SegmentedControl/SegmentedControl.tsx"
 import { Shell } from "../Shell/Shell.tsx"
+import { Tabs } from "../Tabs/Tabs.tsx"
 import { VirtualizedGrid } from "./VirtualizedGrid.tsx"
 
 /**
@@ -130,6 +131,69 @@ export const InShellScrollRegion: Story = {
   ),
 }
 
+/**
+ * Two grids in a tab bar, one of them hidden — the shape that found
+ * the scroll bug.
+ *
+ * A `hidden` panel is `display: none`, so the grid inside it has no
+ * box: its container measures 0px wide (one column) and every
+ * mounted row measures 0px tall. Revealing the panel corrects all
+ * of that at once, and a virtualizer is entitled to read a
+ * correction as a resize and compensate the scroll position for it.
+ *
+ * Docket's Triage bar is where it showed: clicking a tab scrolled
+ * `Main` down 266px and put the tab bar off the top of the screen.
+ * So the claim this story exists to hold is one number — **switching
+ * tabs leaves `Main.scrollTop` where it was.**
+ *
+ * The chrome above the grid is not decoration either. The false
+ * adjustment is roughly the distance from the top of the scroll
+ * region to the top of the grid, so a story with the grid flush
+ * against the top of `Main` would have had nothing to measure and
+ * would have passed while the bug was still there.
+ */
+export const InHiddenTabPanel: Story = {
+  parameters: { layout: "fullscreen" },
+  render: (gridProps) => (
+    <Shell contentWidth="full">
+      <Header heading="Bays" />
+
+      <Main>
+        <p className="text-content-secondary text-sm">
+          Switching tabs must not move the page.
+        </p>
+
+        <Tabs
+          label="Bay views"
+          tabs={[
+            {
+              content: (
+                <VirtualizedGrid
+                  {...gridProps}
+                  label="Loaded bays"
+                />
+              ),
+              key: "loaded",
+              label: "Loaded",
+            },
+            {
+              content: (
+                <VirtualizedGrid
+                  {...gridProps}
+                  items={MANY_ITEMS.slice(0, 48)}
+                  label="Reserved bays"
+                />
+              ),
+              key: "reserved",
+              label: "Reserved",
+            },
+          ]}
+        />
+      </Main>
+    </Shell>
+  ),
+}
+
 /**
  * The same 2,000 items at three window heights.
  *

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

@@ -349,6 +349,12 @@ export type {
   RailSide,
 } from "./Rail/Rail.tsx"
 export { Rail } from "./Rail/Rail.tsx"
+export type {
+  RangeSliderProps,
+  RangeSliderTick,
+} from "./RangeSlider/RangeSlider.tsx"
+export { RangeSlider } from "./RangeSlider/RangeSlider.tsx"
+export type { RangeSliderValue } from "./RangeSlider/rangeSliderValue.ts"
 export type {
   ReorderListItem,
   ReorderListProps,
@@ -448,6 +454,18 @@ export type {
   TextLinkProps,
 } from "./TextLink/TextLink.tsx"
 export { TextLink } from "./TextLink/TextLink.tsx"
+export type { TimecodeInputProps } from "./TimecodeInput/TimecodeInput.tsx"
+export { TimecodeInput } from "./TimecodeInput/TimecodeInput.tsx"
+export type {
+  FormatTimecodeOptions,
+  TimecodeInputResult,
+  TimecodeRange,
+} from "./TimecodeInput/timecode.ts"
+export {
+  clampTimecode,
+  formatTimecode,
+  parseTimecodeInput,
+} from "./TimecodeInput/timecode.ts"
 export type { ToastProps } from "./Toast/Toast.tsx"
 export { Toast } from "./Toast/Toast.tsx"
 export type {

package/src/sliderStyles.ts

@@ -0,0 +1,69 @@
+/**
+ * The paint `Slider` and `RangeSlider` share.
+ *
+ * The two are separate components because their **focus models** are
+ * different — one `role="slider"` on the track against two of them in
+ * a `role="group"`, one tab stop against two
+ * ([decision](../../../docs/decisions/2026-09-01-a-two-thumb-range-is-its-own-component-and-shares-the-bar.md)).
+ * What is identical is the bar: a sunken rounded track, an intent
+ * fill inside it, and a round thumb pulled back by half its own
+ * width.
+ *
+ * Held here rather than copied for the reason `tileStyles.ts` exists:
+ * "the two look the same" spelled as two class strings is a promise
+ * that survives exactly one edit. `RangeSlider.test.tsx` compares the
+ * two thumbs as **computed** styles, so a class-name refactor cannot
+ * quietly break it either.
+ *
+ * No focus ring here. It is the one part of the bar the two do not
+ * share — `Slider` rings the track, because the track is the widget;
+ * `RangeSlider` rings each thumb, because each thumb is.
+ */
+
+export type SliderSize = "lg" | "md" | "sm"
+
+/** The bar itself. A `sm` bar is 2px; that is not a hit target. */
+export const SLIDER_TRACK_SIZE_CLASS: Record<
+  SliderSize,
+  string
+> = {
+  sm: "h-1",
+  md: "h-2",
+  lg: "h-3",
+}
+
+export const SLIDER_THUMB_SIZE_CLASS: Record<
+  SliderSize,
+  string
+> = {
+  sm: "size-3",
+  md: "size-4",
+  lg: "size-5",
+}
+
+/** Half of each `SLIDER_THUMB_SIZE_CLASS`, as the inline-start pull-back. */
+export const SLIDER_THUMB_OFFSET: Record<
+  SliderSize,
+  string
+> = {
+  sm: "-0.375rem",
+  md: "-0.5rem",
+  lg: "-0.625rem",
+}
+
+/**
+ * The row the bar sits in, which is taller than the bar: a 2px track
+ * is not a pointer target, and a finger is 44px. The height comes
+ * from the shared control-size system, so `[data-density]` decides
+ * it — never `MIN_TOUCH_TARGET_CLASS`, which would make this control
+ * taller than the ones beside it at desktop density
+ * ([decision](../../../docs/decisions/2026-08-05-controls-share-one-height-no-per-component-touch-floor.md)).
+ */
+export const SLIDER_ROW_CLASS =
+  "relative flex w-full touch-none cursor-pointer items-center rounded-full min-h-(--control-height-sm)"
+
+export const SLIDER_TRACK_CLASS =
+  "w-full overflow-hidden rounded-full bg-surface-sunken"
+
+export const SLIDER_THUMB_CLASS =
+  "absolute rounded-full border-2 border-surface-raised shadow-sm"

package/src/sourceRules.test.ts

@@ -545,7 +545,31 @@ test("the barrel is the only place components are re-exported", async () => {
   // 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)
+  //
+  // `TimecodeInput` — a typed media position, with an `isRange` mode
+  // for a section of a file — is +1 -> 63. `timecode.ts` is its
+  // member and stays out of this count by the `<Name>/<Name>.tsx`
+  // rule, while still being exported from the barrel: the fleet
+  // spells the *printing* half five times over (queuepilot twice,
+  // castkit, mux-magic twice) and a read-only surface needs the
+  // formatter without the field.
+  //
+  // `RangeSlider` is +1 -> 64. `Slider`'s own record said a two-thumb
+  // range is *"a different widget with its own focus model"*, and the
+  // focus model is exactly what makes it a component rather than an
+  // `isRange` mode: one `role="slider"` on the track becomes two of
+  // them on the thumbs inside a `role="group"`, and one tab stop
+  // becomes two. So this shares the ARITHMETIC (`sliderValue.ts`,
+  // called rather than copied) and the BAR (`sliderStyles.ts`, the
+  // same extraction `tileStyles.ts` is), and nothing else.
+  // `rangeSliderValue.ts` is its member and stays out of this count
+  // by the `<Name>/<Name>.tsx` rule. It lands beside `TimecodeInput`
+  // rather than instead of it: the two halves of QueuePilot's clip
+  // editor are a typed field and a dragged bar over one value, and
+  // `isRange` is right there and wrong here for a reason that is
+  // written down — a second text field is still a text field, while a
+  // second thumb cannot share one `aria-valuenow`.
+  expect(componentNames.length).toBe(64)
 
   for (const name of componentNames) {
     expect(barrel).toContain(`export { ${name} }`)