basalt-ui 1.25.0 → 1.26.0

package/src/controls/filter-set.test.tsx

@@ -0,0 +1,472 @@
+/**
+ * `FilterSet`'s four owned behaviours (`docs/CONTROLS-SPEC.md` §2.1/§3), each asserted against real
+ * children bound to a real `createSearchStore`: the DERIVED active count, `Reset all` reaching every
+ * registered filter, the mobile `inline` budget, and the measured desktop fold.
+ *
+ * The fold is the one behaviour that needs the DOM stubbed rather than driven — happy-dom lays
+ * nothing out, so `offsetWidth`/`clientWidth` are 0 for every element and the no-op
+ * `ResizeObserver` from `tests/setup/dom.ts` never fires. Both are replaced here (restored in
+ * `afterEach`), which is what lets the fold arithmetic be tested at all instead of only in a
+ * browser.
+ */
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import type { ReactNode } from 'react'
+import { MantineProvider } from '@mantine/core'
+import { act, fireEvent, render, screen, waitFor } from '@testing-library/react'
+import {
+  Outlet,
+  RouterProvider,
+  createMemoryHistory,
+  createRootRoute,
+  createRoute,
+  createRouter,
+} from '@tanstack/react-router'
+import { field } from '../router-tanstack/field'
+import { createSearchStore } from '../router-tanstack/search-store'
+import { FilterSet } from './filter-set'
+import { SelectFilter } from './select-filter'
+import { ToggleFilter } from './toggle-filter'
+
+type Router = { state: { status: string; location: { search: unknown } } }
+
+const store = createSearchStore({
+  key: 'fs',
+  fields: {
+    currency: field.enum(['USD', 'EUR'], 'USD'),
+    region: field.enum(['all', 'eu', 'us'], 'all'),
+    tier: field.enum(['any', 'pro'], 'any'),
+    errorsOnly: field.boolean(false),
+  },
+})
+
+async function mountSet(entry: string, inline?: number): Promise<Router> {
+  const rootRoute = createRootRoute({ component: () => <Outlet /> })
+  const pageRoute = createRoute({
+    getParentRoute: () => rootRoute,
+    path: '/dashboard',
+    validateSearch: store.validateSearch,
+    component: () => (
+      <FilterSet {...(inline !== undefined && { inline })}>
+        <SelectFilter field={store.field.currency} label="Currency" />
+        <SelectFilter field={store.field.region} label="Region" />
+        <SelectFilter field={store.field.tier} label="Tier" />
+        <ToggleFilter field={store.field.errorsOnly} label="Errors only" />
+      </FilterSet>
+    ),
+  })
+  const router = createRouter({
+    routeTree: rootRoute.addChildren([pageRoute]),
+    history: createMemoryHistory({ initialEntries: [entry] }),
+  })
+
+  render(
+    <MantineProvider>
+      <RouterProvider router={router} />
+    </MantineProvider>,
+  )
+  await waitFor(() => {
+    expect(router.state.status).toBe('idle')
+  })
+  return router as unknown as Router
+}
+
+function slots(): HTMLElement[] {
+  return [...document.querySelectorAll<HTMLElement>('[data-filter-slot]')]
+}
+
+function row(): HTMLElement {
+  const node = document.querySelector<HTMLElement>('[data-filter-row]')
+  if (node === null) throw new Error('no filter row rendered')
+  return node
+}
+
+/** The stubbed layout: every element's width is whatever the test wrote to `data-test-width`. */
+function widthFromData(this: HTMLElement): number {
+  return Number(this.dataset['testWidth'] ?? '0')
+}
+
+beforeEach(() => {
+  localStorage.clear()
+})
+
+describe('the active count is derived from the children, never passed', () => {
+  test('no filter is off its default → the sheet pill states no count', async () => {
+    await mountSet('/dashboard')
+    expect(screen.getByRole('button', { name: 'Filters' })).toBeDefined()
+  })
+
+  test('two non-default fields on a deep link → Filters (2), with nothing told to FilterSet', async () => {
+    await mountSet('/dashboard?currency=EUR&errorsOnly=true')
+    await waitFor(() => {
+      expect(screen.getByRole('button', { name: 'Filters (2)' })).toBeDefined()
+    })
+  })
+})
+
+describe('Reset all reaches every registered filter, including the folded and the inline ones', () => {
+  test('one press writes every field back to its fallback', async () => {
+    const router = await mountSet('/dashboard?currency=EUR&region=eu&errorsOnly=true')
+    await waitFor(() => {
+      expect(screen.getByRole('button', { name: 'Filters (3)' })).toBeDefined()
+    })
+
+    await act(async () => {
+      fireEvent.click(screen.getByRole('button', { name: 'Filters (3)' }))
+    })
+    await act(async () => {
+      fireEvent.click(screen.getByRole('button', { name: 'Reset all', hidden: true }))
+    })
+
+    await waitFor(() => {
+      const search = router.state.location.search as Record<string, unknown>
+      expect(search['currency']).toBe('USD')
+      expect(search['region']).toBe('all')
+      expect(search['errorsOnly']).toBe(false)
+    })
+    expect(screen.getByRole('button', { name: 'Filters' })).toBeDefined()
+  })
+})
+
+describe('the mobile inline budget is per-slot data, not a second mount', () => {
+  test('inline defaults to 1 — the first slot only', async () => {
+    await mountSet('/dashboard')
+    expect(slots().map((slot) => slot.hasAttribute('data-inline'))).toEqual([
+      true,
+      false,
+      false,
+      false,
+    ])
+  })
+
+  test('inline={2} keeps the first two', async () => {
+    await mountSet('/dashboard', 2)
+    expect(slots().map((slot) => slot.hasAttribute('data-inline'))).toEqual([
+      true,
+      true,
+      false,
+      false,
+    ])
+  })
+
+  test('every child stays mounted regardless of the budget — the row is the whole census', async () => {
+    await mountSet('/dashboard')
+    expect(slots()).toHaveLength(4)
+  })
+})
+
+describe('the desktop fold is measured, and it never scrolls', () => {
+  const offsetWidth = Object.getOwnPropertyDescriptor(HTMLElement.prototype, 'offsetWidth')
+  const clientWidth = Object.getOwnPropertyDescriptor(HTMLElement.prototype, 'clientWidth')
+  let observers: (() => void)[] = []
+
+  function stubLayout(): void {
+    observers = []
+    Object.defineProperty(HTMLElement.prototype, 'offsetWidth', {
+      configurable: true,
+      get: widthFromData,
+    })
+    Object.defineProperty(HTMLElement.prototype, 'clientWidth', {
+      configurable: true,
+      get: widthFromData,
+    })
+    class ResizeObserverStub {
+      constructor(callback: () => void) {
+        observers.push(callback)
+      }
+      observe(): void {}
+      unobserve(): void {}
+      disconnect(): void {}
+    }
+    window.ResizeObserver = ResizeObserverStub as unknown as typeof ResizeObserver
+  }
+
+  afterEach(() => {
+    if (offsetWidth !== undefined) {
+      Object.defineProperty(HTMLElement.prototype, 'offsetWidth', offsetWidth)
+    }
+    if (clientWidth !== undefined) {
+      Object.defineProperty(HTMLElement.prototype, 'clientWidth', clientWidth)
+    }
+  })
+
+  async function resizeTo(available: number, perSlot: number): Promise<void> {
+    row().dataset['testWidth'] = String(available)
+    for (const slot of slots()) slot.dataset['testWidth'] = String(perSlot)
+    await act(async () => {
+      for (const notify of observers) notify()
+    })
+  }
+
+  test('four 100px pills in 250px: the tail folds into +3, and the row keeps one', async () => {
+    stubLayout()
+    await mountSet('/dashboard')
+    await resizeTo(250, 100)
+
+    expect(slots().map((slot) => slot.hasAttribute('data-folded'))).toEqual([
+      false,
+      true,
+      true,
+      true,
+    ])
+    const fold = screen.getByRole('button', { name: '3 more filters' })
+    expect(fold.hasAttribute('data-shown')).toBe(true)
+  })
+
+  test('slots of DIFFERENT widths fold at the right index, not at a uniform one', async () => {
+    // The uniform-100px case can be satisfied by arithmetic that ignores which slot is which. Here
+    // the widths are 40/40/300/40: the wide third pill is what pushes the row over, so the fold has
+    // to land at 2 rather than at some average-derived index.
+    stubLayout()
+    await mountSet('/dashboard')
+    row().dataset['testWidth'] = '250'
+    const widths = ['40', '40', '300', '40']
+    slots().forEach((slot, index) => {
+      slot.dataset['testWidth'] = widths[index] ?? '40'
+    })
+    await act(async () => {
+      for (const notify of observers) notify()
+    })
+
+    expect(slots().map((slot) => slot.hasAttribute('data-folded'))).toEqual([
+      false,
+      false,
+      true,
+      true,
+    ])
+    expect(screen.getByRole('button', { name: '2 more filters' }).hasAttribute('data-shown')).toBe(
+      true,
+    )
+  })
+
+  test('the same four pills in 900px: nothing folds and the +N pill stays unshown', async () => {
+    stubLayout()
+    await mountSet('/dashboard')
+    await resizeTo(900, 100)
+
+    expect(slots().some((slot) => slot.hasAttribute('data-folded'))).toBe(false)
+    expect(screen.getByRole('button', { name: '0 more filters' }).hasAttribute('data-shown')).toBe(
+      false,
+    )
+  })
+})
+
+describe('a folded filter is still operable from inside the +N dropdown', () => {
+  const offsetWidth = Object.getOwnPropertyDescriptor(HTMLElement.prototype, 'offsetWidth')
+  const clientWidth = Object.getOwnPropertyDescriptor(HTMLElement.prototype, 'clientWidth')
+
+  afterEach(() => {
+    if (offsetWidth !== undefined) {
+      Object.defineProperty(HTMLElement.prototype, 'offsetWidth', offsetWidth)
+    }
+    if (clientWidth !== undefined) {
+      Object.defineProperty(HTMLElement.prototype, 'clientWidth', clientWidth)
+    }
+  })
+
+  test('opening +N and changing a folded field writes the URL, and +N stays open', async () => {
+    // The regression this pins: rendering the fold body in PILL form gave each folded filter its own
+    // `withinPortal` Popover, whose mousedown is outside the +N dropdown's `composedPath()` — so +N
+    // closed, the pill unmounted, and the click never landed. The sheet form has no nested overlay.
+    let observers: (() => void)[] = []
+    Object.defineProperty(HTMLElement.prototype, 'offsetWidth', {
+      configurable: true,
+      get: widthFromData,
+    })
+    Object.defineProperty(HTMLElement.prototype, 'clientWidth', {
+      configurable: true,
+      get: widthFromData,
+    })
+    class ResizeObserverStub {
+      constructor(callback: () => void) {
+        observers.push(callback)
+      }
+      observe(): void {}
+      unobserve(): void {}
+      disconnect(): void {}
+    }
+    window.ResizeObserver = ResizeObserverStub as unknown as typeof ResizeObserver
+
+    const router = await mountSet('/dashboard')
+    row().dataset['testWidth'] = '250'
+    for (const slot of slots()) slot.dataset['testWidth'] = '100'
+    await act(async () => {
+      for (const notify of observers) notify()
+    })
+
+    await act(async () => {
+      fireEvent.click(screen.getByRole('button', { name: '3 more filters' }))
+    })
+
+    // The folded children render their sheet form — a named option list, no second pill. `group`,
+    // not `radiogroup`: the sheet form is a `<fieldset>` of native radios (`SheetOptionList`), which
+    // is the grouping role a fieldset carries. `Radio.Group` is the POPOVER form's shape.
+    const group = screen.getByRole('group', { name: 'Region', hidden: true })
+    expect(group).toBeDefined()
+
+    await act(async () => {
+      fireEvent.click(screen.getByRole('radio', { name: 'eu', hidden: true }))
+    })
+
+    await waitFor(() => {
+      expect((router.state.location.search as Record<string, unknown>)['region']).toBe('eu')
+    })
+    // Still open: the write did not tear its own container down.
+    expect(screen.getByRole('group', { name: 'Region', hidden: true })).toBeDefined()
+    observers = []
+  })
+})
+
+describe('the sheet names every control it holds', () => {
+  test('the option lists and the Switch row carry the filter name, not the pill text', async () => {
+    await mountSet('/dashboard?currency=EUR')
+    await act(async () => {
+      fireEvent.click(screen.getByRole('button', { name: 'Filters (1)' }))
+    })
+
+    // `Currency`, not `EUR` — the pill reads the VALUE once set, which names the selection rather
+    // than the filter. Each `<fieldset>` points at its own visible SheetField heading.
+    for (const name of ['Currency', 'Region', 'Tier']) {
+      expect(screen.getByRole('group', { name, hidden: true })).toBeDefined()
+    }
+    expect(screen.getByRole('switch', { name: 'Errors only', hidden: true })).toBeDefined()
+  })
+})
+
+/**
+ * The 44px touch target, asserted at the SOURCE. Neither half is checkable in the DOM here:
+ * happy-dom lays nothing out (so no bounding box), and a `.module.css` import resolves to `undefined`
+ * under `bun test` (so the emitted `class` attribute carries only Mantine's own names). What IS
+ * checkable is the pair that produces it — the CSS stretching the body and label to the row, and
+ * every row-rendering control actually passing those classes. A row whose height sits on a
+ * non-interactive wrapper is C15's number without C15's behaviour, which is the defect this pins.
+ */
+describe('sheet rows are tappable across their full height (C15)', () => {
+  const css = readFileSync(join(import.meta.dir, 'controls.module.css'), 'utf8')
+
+  function block(selector: string): string {
+    const start = css.indexOf(`${selector} {`)
+    expect(start).toBeGreaterThan(-1)
+    return css.slice(start, css.indexOf('}', start))
+  }
+
+  test('both row primitives pin the height to the sheet-row token, not a literal', () => {
+    expect(block('.sheetRow')).toContain('var(--vx-space-sheet-row-height')
+    expect(block('.sheetOption')).toContain('var(--vx-space-sheet-row-height')
+  })
+
+  test('the option row IS the hit target — the height sits on the label, never on a wrapper', () => {
+    // `.sheetOption` is the `<label>` (and, in a disclosure, the `<button>`) itself, so the 44px is
+    // on the interactive element by construction rather than by a classNames hand-off.
+    const rule = block('.sheetOption')
+    expect(rule).toContain('width: 100%')
+    expect(rule).toContain('cursor: pointer')
+  })
+
+  test('.sheetRowBody and .sheetRowLabel stretch the interactive element to that height', () => {
+    for (const selector of ['.sheetRowBody', '.sheetRowLabel']) {
+      const rule = block(selector)
+      expect(rule).toContain('flex: 1')
+      expect(rule).toContain('min-height: inherit')
+    }
+  })
+
+  test('every control that renders a sheet row goes through a 44px row primitive', () => {
+    // Two primitives, one law. `ToggleFilter` renders a Mantine `Switch` AS the row, so it needs
+    // `sheetRowClassNames` to stretch the control's own `<label>` across the 44px. The enum/multi/
+    // range filters render `SheetOptionList`, which owns the `<label>`-per-row box itself — the
+    // classNames escape exists for controls basalt does not draw the row for.
+    expect(readFileSync(join(import.meta.dir, 'toggle-filter.tsx'), 'utf8')).toContain(
+      'sheetRowClassNames',
+    )
+    for (const file of ['enum-filter.tsx', 'multi-select-filter.tsx', 'range-filter.tsx']) {
+      const source = readFileSync(join(import.meta.dir, file), 'utf8')
+      expect(source).toContain('SheetOptionList')
+    }
+  })
+
+  test('no control wraps its sheet row in a plain div — the height must sit on the label', () => {
+    // `SheetRow` puts `min-height` on a non-interactive wrapper, which is exactly the 20px-strip
+    // defect. It stays exported for a future non-interactive row; no filter may use it.
+    for (const file of ['enum-filter.tsx', 'multi-select-filter.tsx', 'toggle-filter.tsx']) {
+      const source = readFileSync(join(import.meta.dir, file), 'utf8')
+      expect(source).not.toContain('<SheetRow>')
+    }
+  })
+})
+
+describe('an empty home renders nothing (C14)', () => {
+  test('no children → no row, so no route pays for a reserved bar', async () => {
+    const rootRoute = createRootRoute({ component: () => <Outlet /> })
+    const pageRoute = createRoute({
+      getParentRoute: () => rootRoute,
+      path: '/dashboard',
+      component: (): ReactNode => <FilterSet>{null}</FilterSet>,
+    })
+    const router = createRouter({
+      routeTree: rootRoute.addChildren([pageRoute]),
+      history: createMemoryHistory({ initialEntries: ['/dashboard'] }),
+    })
+    render(
+      <MantineProvider>
+        <RouterProvider router={router} />
+      </MantineProvider>,
+    )
+    await waitFor(() => {
+      expect(router.state.status).toBe('idle')
+    })
+
+    expect(document.querySelector('[data-filter-row]')).toBeNull()
+  })
+})
+
+/**
+ * The `Filters (n)` pill is the mobile SHEET TRIGGER, and the sheet only ever holds what the
+ * `inline` budget folded away. With nothing folded it opens a drawer showing a copy of the pills
+ * already on screen — while costing the mobile row the width of a pill to say so.
+ */
+describe('the mobile sheet trigger appears only when a child is folded', () => {
+  async function mountOne(inline?: number): Promise<void> {
+    const rootRoute = createRootRoute({ component: () => <Outlet /> })
+    const pageRoute = createRoute({
+      getParentRoute: () => rootRoute,
+      path: '/dashboard',
+      validateSearch: store.validateSearch,
+      component: (): ReactNode => (
+        <FilterSet {...(inline !== undefined && { inline })}>
+          <SelectFilter field={store.field.currency} label="Currency" />
+        </FilterSet>
+      ),
+    })
+    const router = createRouter({
+      routeTree: rootRoute.addChildren([pageRoute]),
+      history: createMemoryHistory({ initialEntries: ['/dashboard'] }),
+    })
+    render(
+      <MantineProvider>
+        <RouterProvider router={router} />
+      </MantineProvider>,
+    )
+    await waitFor(() => {
+      expect(router.state.status).toBe('idle')
+    })
+  }
+
+  test('one child at the default budget → no Filters pill at all', async () => {
+    await mountOne()
+    expect(screen.queryByRole('button', { name: 'Filters' })).toBeNull()
+    // …and the filter itself is still there, inline.
+    expect(slots()).toHaveLength(1)
+  })
+
+  test('inline={0} folds that same child → the pill is back', async () => {
+    await mountOne(0)
+    expect(screen.getByRole('button', { name: 'Filters' })).toBeDefined()
+  })
+
+  test('four children at the default budget keep the pill', async () => {
+    await mountSet('/dashboard')
+    expect(screen.getByRole('button', { name: 'Filters' })).toBeDefined()
+  })
+})

package/src/controls/filter-set.tsx

@@ -0,0 +1,225 @@
+/**
+ * `FilterSet` — the filter home's container (`docs/CONTROLS-SPEC.md` §2.1 row 2, §3). It owns the
+ * three things a consumer used to hand-roll per page: the nowrap row, the overflow fold, and the
+ * mobile sheet.
+ *
+ * **Desktop.** One row, `wrap: nowrap`, and it NEVER scrolls (C7). When the measured pill widths
+ * exceed the container the tail folds into a `+N` menu pill — a `ResizeObserver` on the row plus
+ * per-slot `offsetWidth`, because the fold point depends on the labels actually painted (the same
+ * reasoning as the charts' `autoMargin`), not on a guessed pill width.
+ *
+ * **Mobile (`< sm`).** The first `inline` children stay pills; every child — inline ones included —
+ * also renders its full-width sheet form inside the `Filters (n)` Drawer — which exists only when
+ * the budget folded at least one child away (one filter at `inline: 1` gets no pill at all). `n` is
+ * DERIVED: each filter registers `{ isActive, reset }` with this component (`filter-context.tsx`),
+ * so `FilterSet` never needs to be told which fields its children hold, and `Reset all` reaches all
+ * of them.
+ *
+ * **Two mounts of the same children, one census.** The row keeps every child mounted on every
+ * viewport (hidden slots are `display: none`, never unmounted), so it is the single registration
+ * surface; the fold dropdown and the sheet mount a second copy under a `null` registry. That is why
+ * a folded filter still counts toward `n` and still answers `Reset all`.
+ *
+ * @example
+ * <PageBar
+ *   filters={
+ *     <FilterSet>
+ *       <RangeFilter field={analytics.field.range} customPicker={DateRangePicker} />
+ *       <CompareFilter field={analytics.field.compare} />
+ *       <SelectFilter field={analytics.field.currency} label="Currency" />
+ *     </FilterSet>
+ *   }
+ * />
+ */
+import { Children, isValidElement, useCallback, useEffect, useRef, useState } from 'react'
+import type { ReactNode, RefObject } from 'react'
+import classes from './controls.module.css'
+import { FilterSetScope, useFilterCensus } from './filter-context'
+import { FilterPill } from './filter-pill'
+import { FilterSheet } from './filter-sheet'
+import { FunnelGlyph } from './glyphs'
+
+/** Width reserved for the `+N` pill once folding is known to be necessary. */
+const FOLD_PILL_WIDTH = 52
+/** `--vx-space-control-gap`'s level-0 value — the fallback when the row has no computed style. */
+const FALLBACK_GAP = 6
+
+export type FilterSetProps = {
+  readonly children: ReactNode
+  /**
+   * How many children stay inline pills below `sm`. The rest are reachable only through the
+   * `Filters (n)` sheet — which always holds every child, inline ones included.
+   *
+   * @default 1
+   */
+  readonly inline?: number
+}
+
+export function FilterSet({ children, inline = 1 }: FilterSetProps): ReactNode {
+  const items = Children.toArray(children)
+  const { registry, activeCount, resetAll } = useFilterCensus()
+  const [sheetOpened, setSheetOpened] = useState(false)
+  const rowRef = useRef<HTMLDivElement | null>(null)
+  const fit = useOverflowFit(rowRef, items.length)
+
+  const openSheet = useCallback(() => {
+    setSheetOpened(true)
+  }, [])
+  const closeSheet = useCallback(() => {
+    setSheetOpened(false)
+  }, [])
+
+  // C14 — an empty home renders nothing, so no route pays for a reserved row.
+  if (items.length === 0) return null
+
+  const folded = items.slice(fit)
+  // Below `sm` the sheet is the ONLY way to reach a child past the `inline` budget — so with every
+  // child already inline (one filter at the default budget) it opens a drawer holding a copy of
+  // what is on screen, under a pill that costs the row its width for nothing. The trigger exists
+  // when something is actually folded away, and not before (law C14's reading of the mobile row).
+  const anyFoldedOnMobile = items.length > inline
+
+  return (
+    <>
+      <div className={classes.pillRow} ref={rowRef} data-filter-row>
+        <FilterSetScope surface="pill" registry={registry}>
+          {items.map((child, index) => (
+            // `Children.toArray` already stamped a stable `.0`/`.1`-style key on every child, so
+            // the slot wrapper reuses it rather than inventing an array-index key.
+            <div
+              key={slotKey(child, index)}
+              className={classes.pillSlot}
+              data-filter-slot
+              {...(index < inline && { 'data-inline': true })}
+              {...(index >= fit && { 'data-folded': true })}
+            >
+              {child}
+            </div>
+          ))}
+        </FilterSetScope>
+
+        <FilterPill
+          label={`+${folded.length}`}
+          ariaLabel={`${folded.length} more filters`}
+          className={classes.foldPill}
+          hideGlyph
+          shown={folded.length > 0}
+        >
+          <div className={classes.optionList}>
+            {/* SHEET form, not pill form. A folded pill would open a SECOND `withinPortal`
+                Popover, which is not a DOM descendant of this one — Mantine's click-outside check
+                walks `composedPath()` against the outer target/dropdown only, so the inner pill's
+                own mousedown reads as "outside", closes `+N`, unmounts the pill, and the click
+                never lands. The sheet form has no nested overlay at all, and it is the same form
+                the mobile `Filters (n)` Drawer already uses — one behaviour, not two. */}
+            <FilterSetScope surface="sheet" registry={null}>
+              {folded}
+            </FilterSetScope>
+          </div>
+        </FilterPill>
+
+        {anyFoldedOnMobile && (
+          <FilterPill
+            label={activeCount > 0 ? `Filters (${activeCount})` : 'Filters'}
+            active={activeCount > 0}
+            icon={<FunnelGlyph />}
+            className={classes.sheetPill}
+            hideGlyph
+            onClick={openSheet}
+          />
+        )}
+      </div>
+
+      {anyFoldedOnMobile && (
+        <FilterSheet opened={sheetOpened} onClose={closeSheet} onResetAll={resetAll}>
+          <FilterSetScope surface="sheet" registry={null}>
+            {items}
+          </FilterSetScope>
+        </FilterSheet>
+      )}
+    </>
+  )
+}
+
+/**
+ * How many of `count` slots fit the row at its current width. Measures the slots' own
+ * `offsetWidth` (remembering the last non-zero value per slot, since a folded or `inline`-budgeted
+ * slot measures 0) and re-runs on every `ResizeObserver` tick.
+ *
+ * The measurement is only honest because `.pillSlot` is `flex-shrink: 0` — see that rule's comment
+ * in `controls.module.css`. Every SLOT is observed alongside the row, not just the row: a label
+ * that grows (a preset becoming `Mar 1 – Mar 14`) changes no container width, so observing the row
+ * alone would miss exactly the case that pushes a fitting row over its budget.
+ */
+function useOverflowFit(rowRef: RefObject<HTMLDivElement | null>, count: number): number {
+  const [fit, setFit] = useState(count)
+  const widths = useRef<number[]>([])
+
+  useEffect(() => {
+    const row = rowRef.current
+    if (row === null) return
+    if (typeof ResizeObserver === 'undefined') {
+      setFit(count)
+      return
+    }
+
+    const measure = (): void => {
+      const slots = [...row.querySelectorAll<HTMLElement>('[data-filter-slot]')]
+      slots.forEach((slot, index) => {
+        const width = slot.offsetWidth
+        if (width > 0) widths.current[index] = width
+      })
+
+      const available = row.clientWidth
+      if (available <= 0) {
+        setFit(count)
+        return
+      }
+
+      const gap = readGap(row)
+      const bare = fitCount(widths.current, count, gap, available, 0)
+      // Reserve the `+N` pill only once folding is known to be needed — reserving it up front
+      // would fold a set that fits exactly.
+      setFit(
+        bare === count ? count : fitCount(widths.current, count, gap, available, FOLD_PILL_WIDTH),
+      )
+    }
+
+    measure()
+    const observer = new ResizeObserver(measure)
+    observer.observe(row)
+    for (const slot of row.querySelectorAll<HTMLElement>('[data-filter-slot]')) {
+      observer.observe(slot)
+    }
+    return () => {
+      observer.disconnect()
+    }
+  }, [rowRef, count])
+
+  return fit
+}
+
+function fitCount(
+  widths: readonly number[],
+  count: number,
+  gap: number,
+  available: number,
+  reserve: number,
+): number {
+  let used = reserve === 0 ? 0 : reserve + gap
+  for (let index = 0; index < count; index += 1) {
+    used += (index === 0 ? 0 : gap) + (widths[index] ?? 0)
+    if (used > available) return index
+  }
+  return count
+}
+
+function slotKey(child: ReactNode, index: number): string {
+  if (isValidElement(child) && child.key !== null) return child.key
+  return String(index)
+}
+
+function readGap(row: HTMLElement): number {
+  const parsed = Number.parseFloat(getComputedStyle(row).columnGap)
+  return Number.isFinite(parsed) ? parsed : FALLBACK_GAP
+}