basalt-ui 1.30.2 → 1.32.0

package/src/content/code-block.tsx

@@ -13,7 +13,8 @@
  * <CodeBlock language="bash" code="bun add basalt-ui" showCopy />
  */
 import type { CSSProperties } from 'react'
-import { useEffect, useState } from 'react'
+import { useEffect, useRef, useState } from 'react'
+import { useIsomorphicLayoutEffect } from '../common/isomorphic-layout-effect'
 import classes from './code-block.module.css'
 import { CopyAction } from './copy-action'
 import { highlightCode } from './highlighter'
@@ -39,6 +40,10 @@ export function CodeBlock({
   // Intentionally NOT reset on every code/language change — keeping the last-good html while a
   // re-highlight is in flight avoids a flash back to plain mono on every keystroke of streamed code.
   const [html, setHtml] = useState<string | null>(null)
+  const bodyRef = useRef<HTMLElement | null>(null)
+  const setBodyRef = (node: HTMLElement | null): void => {
+    bodyRef.current = node
+  }
 
   useEffect(() => {
     if (language === undefined) return
@@ -52,6 +57,36 @@ export function CodeBlock({
     }
   }, [code, language])
 
+  // Trailing-edge overflow fade (docs/MATURATION-LEDGER.md): visible only while `.body` is
+  // actually wider than its box AND not yet scrolled to the end — never a permanent decoration on a
+  // block that already fits, never a fade implying more content once the reader reaches it. LTR
+  // only (no `dir` handling exists anywhere else in this file); a future RTL pass would fade the
+  // LEADING edge instead. `[data-code-overflow]` (not React state driving the mask itself) is the
+  // toggle the CSS module reads, so the fade never re-renders the block — only this one attribute.
+  const [showOverflowFade, setShowOverflowFade] = useState(false)
+
+  // Layout effect, not a plain effect: measuring after paint would let a code block that's
+  // already too wide on mount flash one frame with no fade before this fires. Isomorphic so an SSR
+  // render never trips React's "useLayoutEffect does nothing on the server" warning.
+  useIsomorphicLayoutEffect(() => {
+    const body = bodyRef.current
+    if (!body) return
+
+    const update = (): void => {
+      const atEnd = body.scrollLeft + body.clientWidth >= body.scrollWidth - 1
+      setShowOverflowFade(body.scrollWidth > body.clientWidth && !atEnd)
+    }
+    update()
+
+    body.addEventListener('scroll', update, { passive: true })
+    const observer = new ResizeObserver(update)
+    observer.observe(body)
+    return () => {
+      body.removeEventListener('scroll', update)
+      observer.disconnect()
+    }
+  }, [html, code])
+
   const containerClass = [classes.container, className].filter(Boolean).join(' ')
 
   return (
@@ -66,9 +101,18 @@ export function CodeBlock({
         </div>
       )}
       {html !== null ? (
-        <div className={classes.body} dangerouslySetInnerHTML={{ __html: html }} />
+        <div
+          ref={setBodyRef}
+          className={classes.body}
+          {...(showOverflowFade && { 'data-code-overflow': true })}
+          dangerouslySetInnerHTML={{ __html: html }}
+        />
       ) : (
-        <pre className={classes.body}>
+        <pre
+          ref={setBodyRef}
+          className={classes.body}
+          {...(showOverflowFade && { 'data-code-overflow': true })}
+        >
           <code>{code}</code>
         </pre>
       )}

package/src/content/prose.module.css

@@ -149,17 +149,22 @@
   display: inline-flex;
   vertical-align: middle;
   margin-left: var(--vx-space-prose-heading-anchor-gap);
-  opacity: 0;
   transition: opacity 120ms ease;
 }
 
-.root h1:hover .headingAnchor,
-.root h2:hover .headingAnchor,
-.root h3:hover .headingAnchor,
-.root h4:hover .headingAnchor,
-.root h5:hover .headingAnchor,
-.root h6:hover .headingAnchor,
-.headingAnchor:focus-within {
+/* Hidden-until-hover only where hover exists (pointer tier, docs/DESIGN-CORE.md § Layout,
+   elevation, shapes); touch shows it. Focus always reveals (the rule below outranks the hidden one). */
+@media (hover: hover) and (pointer: fine) {
+  .root :is(h1, h2, h3, h4, h5, h6) .headingAnchor {
+    opacity: 0;
+  }
+
+  .root :is(h1, h2, h3, h4, h5, h6):hover .headingAnchor {
+    opacity: 1;
+  }
+}
+
+.root :is(h1, h2, h3, h4, h5, h6) .headingAnchor:focus-within {
   opacity: 1;
 }
 

package/src/controls/actions.module.css

@@ -24,7 +24,7 @@
   padding: 0 var(--vx-space-row-inset-x);
 }
 
-@media (max-width: 47.99375em) {
+@media (pointer: coarse) {
   .menuItem,
   .customRow {
     min-height: var(--vx-space-sheet-row-height);
@@ -60,3 +60,16 @@
 
   color: var(--vx-faint);
 }
+
+/*
+ * The `Box` wrapping a joined `ControlGroup` run (`BAR_KEY_ATTR`, one level up from the group
+ * itself) so `useMeasuredFold` can measure the whole run as a single box. Without `flex: none` this
+ * wrapper is an ORDINARY flex item of the desktop row (`flex: 0 1 auto`, Mantine `Box`'s default) —
+ * exactly the shrink target the row's own fold arithmetic squeezes first, so its `offsetWidth` read
+ * back a compressed width instead of the run's real max-content width. `ControlGroup` itself
+ * already carries this on its own root (`.group`, `controls.module.css`) — this wrapper needs the
+ * same property one box further out.
+ */
+.joinBox {
+  flex: none;
+}

package/src/controls/actions.module.css.d.ts

@@ -9,5 +9,6 @@ declare const classes: {
   readonly customSlot: string
   readonly kebabIcon: string
   readonly chevronIcon: string
+  readonly joinBox: string
 }
 export default classes

package/src/controls/actions.tsx

@@ -12,11 +12,12 @@
  * rendered, once each, and Mantine's `visibleFrom`/`hiddenFrom` decides which one paints. No JS
  * media query, so there is no first-paint flash and no hook that re-renders on resize.
  */
-import { ActionIcon, Button, Group, Menu } from '@mantine/core'
-import type { MantineBreakpoint } from '@mantine/core'
-import { createContext, isValidElement, useContext, useEffect } from 'react'
-import type { ReactNode } from 'react'
+import { ActionIcon, Box, Button, Group, Menu } from '@mantine/core'
+import { createContext, isValidElement, useContext, useEffect, useRef, useState } from 'react'
+import type { ReactNode, RefObject } from 'react'
 import type { BasaltProps } from '../common/props'
+import { useMeasuredWidths } from '../common/use-measured-widths'
+import { useIsomorphicLayoutEffect } from '../common/isomorphic-layout-effect'
 import type { NavAnchor } from '../shell/nav-types'
 import type { AnyNavLink } from '../router-tanstack/nav'
 import { IconSlot } from '../theme/icon-slot'
@@ -98,9 +99,6 @@ export type GlobalAction = {
   mobile?: 'bar' | 'more' | 'hidden'
 }
 
-/** Secondaries rendered inline on desktop; the rest fold into `More` (`docs/CONTROLS-SPEC.md` §2.1). */
-export const DESKTOP_SECONDARY_MAX = 3
-
 /** `GlobalAction`s without an explicit `mobile` that still land on the mobile bar. */
 export const MOBILE_GLOBAL_BAR_MAX = 2
 
@@ -189,17 +187,12 @@ const MOBILE_PRIMARY_PADDING_X = 10
 const BAR_GAP = 6
 
 /**
- * A declared WIDTH TIER for one rendered form of an action — Mantine's own `visibleFrom`/`hiddenFrom`
- * style props, forwarded verbatim, which is the same CSS-only mechanism this file's `sm` swap uses
- * (see the module header). Never a JS media query: no first-paint flash, no resize re-render.
- *
- * It exists because `sm` is not the only width at which this row runs out of room — see
- * {@link BarEntry}'s `md` label fold for the arithmetic.
+ * The DOM contract between `PageBar` row 1 and {@link useMeasuredFold} — module-internal, not part
+ * of any barrel. `PAGE_BAR_END_ATTR` marks the elastic row the fold measures; `BAR_KEY_ATTR` tags
+ * each rendered action with its `key` so a measured box maps back to its action.
  */
-type TierVisibility = {
-  visibleFrom?: MantineBreakpoint
-  hiddenFrom?: MantineBreakpoint
-}
+export const PAGE_BAR_END_ATTR = 'data-basalt-page-bar-end'
+export const BAR_KEY_ATTR = 'data-bar-key'
 
 /**
  * One action as a button. No `size` prop anywhere: the enclosing `CtlSlot` (mounted by the home,
@@ -209,19 +202,16 @@ function BarButton({
   action,
   variant,
   px,
-  tier,
 }: {
   action: BarActionItem
   variant: 'filled' | 'default'
   /** Overrides the tier's horizontal inset — only the compact mobile primary passes it. */
   px?: number
-  /** The declared width tier this form paints at — see {@link TierVisibility}. */
-  tier?: TierVisibility
 }): ReactNode {
   const shared = {
     variant,
     ...(px !== undefined && { px }),
-    ...tier,
+    [BAR_KEY_ATTR]: action.key,
     disabled: action.disabled === true,
     loading: action.loading === true,
     // EVERY icon in this file goes through `IconSlot` — the box is the framework's, never the
@@ -252,17 +242,14 @@ function BarButton({
 function BarIconButton({
   action,
   variant,
-  tier,
 }: {
   action: BarActionItem
   /** `default` is the bordered desktop form — a joined `ControlGroup` member (see {@link BarEntry}). */
   variant: 'filled' | 'subtle' | 'default'
-  /** The declared width tier this form paints at — see {@link TierVisibility}. */
-  tier?: TierVisibility
 }): ReactNode {
   const shared = {
     variant,
-    ...tier,
+    [BAR_KEY_ATTR]: action.key,
     'aria-label': action.label,
     disabled: action.disabled === true,
     loading: action.loading === true,
@@ -470,16 +457,16 @@ type BarActionRowProps = ActionGroupProps & {
  * label, so a labelled joined set is unaffected; the rule reads what the caller actually supplied
  * rather than adding a prop to ask.
  */
-function joinRuns(
-  actions: readonly BarAction[],
+function joinRuns<T extends BarAction>(
+  actions: readonly T[],
   opts: { viewport: 'desktop' | 'mobile'; excludeKey?: string | undefined },
-): BarAction[][] {
-  const joinable = (action: BarAction): boolean =>
+): T[][] {
+  const joinable = (action: T): boolean =>
     action.kind === undefined &&
     action.key !== opts.excludeKey &&
     (action.group === true || (opts.viewport === 'mobile' && action.icon !== undefined))
 
-  const runs: BarAction[][] = []
+  const runs: T[][] = []
   for (const action of actions) {
     const tail = runs.at(-1)
     if (joinable(action) && tail !== undefined && tail.every(joinable)) tail.push(action)
@@ -488,6 +475,166 @@ function joinRuns(
   return runs
 }
 
+type FoldStep = 'icon' | 'overflow'
+
+/** The `More` trigger's estimated width — reserved only once something has folded (cf. `FOLD_PILL_WIDTH`). */
+const MORE_WIDTH = 80
+
+/**
+ * The measured fold as a pure decision. `room` is the row's available width, `fixed` everything in it
+ * that never folds (primary, sync, joined runs, custom nodes), each foldable `item` its labelled and
+ * icon-only width (`icon` absent when it ships no icon). Folds from the LAST item back: first to
+ * icon-only where an icon exists, then into `More`. Items that stay whole are absent from the result.
+ */
+export function planBarFold(input: {
+  room: number
+  fixed: number
+  gap: number
+  hasMenus: boolean
+  items: readonly { key: string; full: number; icon: number | undefined }[]
+}): Record<string, FoldStep> {
+  const { room, fixed, gap, hasMenus, items } = input
+  const steps: (FoldStep | undefined)[] = items.map(() => undefined)
+  const used = (): number =>
+    items.reduce(
+      (sum, item, i) => {
+        const step = steps[i]
+        if (step === 'overflow') return sum
+        return sum + gap + (step === 'icon' ? (item.icon ?? item.full) : item.full)
+      },
+      fixed + (hasMenus || steps.includes('overflow') ? MORE_WIDTH + gap : 0),
+    )
+
+  for (let i = items.length - 1; i >= 0 && used() > room; i -= 1) {
+    if (items[i]!.icon !== undefined) steps[i] = 'icon'
+  }
+  for (let i = items.length - 1; i >= 0 && used() > room; i -= 1) steps[i] = 'overflow'
+  return Object.fromEntries(items.flatMap((item, i) => (steps[i] ? [[item.key, steps[i]]] : [])))
+}
+
+/** The row's flex items, looking through `display: contents` wrappers (`CtlSlot`). */
+function flowItems(el: Element): Element[] {
+  return Array.from(el.children).flatMap((child) =>
+    getComputedStyle(child).display === 'contents' ? flowItems(child) : [child],
+  )
+}
+
+/**
+ * The desktop row's fold state — shared by `PageBar` row 1 (`host: 'page'`, whose ANCESTOR carries
+ * `PAGE_BAR_END_ATTR`, published by `PageBar` itself) and every other home's `ActionGroup` /
+ * `BarActionSlot` (`host: 'slot'`, which has no wider elastic row to measure against and so tags
+ * its OWN `Group` with the same attribute — `Element.closest` matches the element itself first,
+ * so one `resolveRoot` covers both). Measures the row and re-plans on every resize and once web
+ * fonts settle; a zero reading (hidden below `sm`, not yet laid out) is not overflow, so the row
+ * then stays whole. A changed action set or label drops every remembered width and re-measures
+ * from the whole row, because a folded run cannot report the width its new label would take.
+ *
+ * `runs` is `joinRuns`'s own output, not the flat action list: a `group: true` run (rendered as one
+ * `ControlGroup`) is measured and folded AS A UNIT, keyed by its first member — a run of length > 1
+ * has no `icon` step of its own (its members already render icon-only per {@link BarEntry}), so it
+ * can only stay whole or fold straight into `More`.
+ */
+function useMeasuredFold(input: {
+  host: 'page' | 'slot'
+  runs: readonly (BarActionItem | BarActionCustom)[][]
+  hasMenus: boolean
+}): { folds: Record<string, FoldStep>; groupRef: RefObject<HTMLDivElement | null> } {
+  const { host, runs, hasMenus } = input
+  const groupRef = useRef<HTMLDivElement>(null)
+  const [folds, setFolds] = useState<Record<string, FoldStep>>({})
+  const [epoch, setEpoch] = useState(0)
+  const foldsRef = useRef(folds)
+  const runsRef = useRef(runs)
+  // Menus are filtered out before `runs` is built, so `hasMenus` — which reserves `MORE_WIDTH` in
+  // `planBarFold` — rides the signature: a menu appearing or leaving is a re-measure trigger, not
+  // an invisible one. A run's signature is its representative key plus every member's label — its
+  // members never fold individually, so only the whole run's label set can move its measured width.
+  const signature = `${hasMenus ? 'menus' : 'nomenus'}|${runs
+    .map(
+      (run) => `${run[0]!.key}:${run.map((a) => (a.kind === undefined ? a.label : '')).join(',')}`,
+    )
+    .join('|')}`
+  const measuredSignature = useRef(signature)
+
+  // Declared before the measuring hook so it runs first on every commit.
+  useIsomorphicLayoutEffect(() => {
+    foldsRef.current = folds
+    runsRef.current = runs
+  })
+
+  const measured = useMeasuredWidths({
+    resolveRoot: () => groupRef.current?.closest(`[${PAGE_BAR_END_ATTR}]`) ?? null,
+    signature,
+    nonce: epoch,
+    onMeasure: (row, boxes) => {
+      if (measuredSignature.current !== signature) {
+        measuredSignature.current = signature
+        if (Object.keys(foldsRef.current).length > 0) {
+          // Render the row whole, then measure it: `epoch` re-runs this hook after that commit.
+          foldsRef.current = {}
+          setFolds({})
+          setEpoch((n) => n + 1)
+          return
+        }
+      }
+      const group = groupRef.current
+      if (group === null) return
+      const currentRuns = runsRef.current
+      // A `kind: 'custom'` entry is never a fold candidate (basalt does not draw it, so it has no
+      // form to fold into) — it is always a length-1 run, since `joinRuns` never joins one.
+      const foldable = new Set(
+        currentRuns.filter((run) => run[0]!.kind === undefined).map((run) => run[0]!.key),
+      )
+      const elements = Array.from(group.children).filter(
+        (el): el is HTMLElement =>
+          el instanceof HTMLElement && foldable.has(el.getAttribute(BAR_KEY_ATTR) ?? ''),
+      )
+      for (const el of elements) {
+        const key = el.getAttribute(BAR_KEY_ATTR)!
+        if (foldsRef.current[key] === undefined && el.offsetWidth > 0) {
+          boxes.current.set(key, { width: el.offsetWidth, height: el.offsetHeight })
+        }
+      }
+      const items = currentRuns.flatMap((run) => {
+        const rep = run[0]!
+        if (rep.kind !== undefined) return []
+        const seen = boxes.current.get(rep.key)
+        if (seen === undefined) return []
+        const icon = run.length === 1 && rep.icon !== undefined ? seen.height : undefined
+        return [{ key: rep.key, full: seen.width, icon }]
+      })
+      const rects = flowItems(row)
+        .map((el) => el.getBoundingClientRect())
+        .filter((r) => r.width > 0)
+      if (row.clientWidth <= 0 || rects.length === 0 || items.length === 0) return
+
+      const used = Math.max(...rects.map((r) => r.right)) - Math.min(...rects.map((r) => r.left))
+      const rendered = elements.reduce((sum, el) => sum + el.offsetWidth + BAR_GAP, 0)
+      const moreNow = hasMenus || Object.values(foldsRef.current).includes('overflow')
+      const fixed = used - rendered - (moreNow ? MORE_WIDTH + BAR_GAP : 0)
+      const next = planBarFold({ room: row.clientWidth, fixed, gap: BAR_GAP, hasMenus, items })
+      const prev = foldsRef.current
+      const same =
+        Object.keys(next).length === Object.keys(prev).length &&
+        Object.entries(next).every(([key, step]) => prev[key] === step)
+      if (!same) setFolds(next)
+    },
+  })
+
+  // The first measure can precede the web font, whose swap-in changes every label's width.
+  useIsomorphicLayoutEffect(() => {
+    let disposed = false
+    void document.fonts?.ready
+      ?.then(() => (disposed ? undefined : measured.remeasure()))
+      .catch(() => {})
+    return () => {
+      disposed = true
+    }
+  }, [host, signature])
+
+  return { folds, groupRef }
+}
+
 export function BarActionRow({
   primary,
   secondary,
@@ -505,8 +652,13 @@ export function BarActionRow({
 
   const flat = list.filter((a): a is BarActionItem | BarActionCustom => a.kind !== 'menu')
   const menus = list.filter((a): a is BarActionMenu => a.kind === 'menu')
-  const inline = flat.slice(0, DESKTOP_SECONDARY_MAX)
-  const desktopOverflow = [...flat.slice(DESKTOP_SECONDARY_MAX), ...menus]
+  const allRuns = joinRuns(flat, { viewport: 'desktop' })
+  const { folds, groupRef } = useMeasuredFold({ host, runs: allRuns, hasMenus: menus.length > 0 })
+  const runs = allRuns.filter((run) => folds[run[0]!.key] !== 'overflow')
+  const desktopOverflow = [
+    ...allRuns.flatMap((run) => (folds[run[0]!.key] === 'overflow' ? run : [])),
+    ...menus,
+  ]
 
   const wantsMobile = viewport === 'both'
   const mobileList = [...list, ...mobileOnly]
@@ -551,7 +703,7 @@ export function BarActionRow({
   const hasMobile = mobileBar.length > 0 || claimsKebab
   if (!hasDesktop && !hasMobile && syncNode === undefined) return null
 
-  const desktopLead = inline.length > 0 || desktopOverflow.length > 0 || syncNode === undefined
+  const desktopLead = flat.length > 0 || menus.length > 0 || syncNode === undefined
 
   // The caller's `className`/`style` land on the ONE desktop group and the ONE mobile group. A
   // `syncNode` splits the desktop row in two, and with nothing to lead with (no inline actions, no
@@ -566,16 +718,41 @@ export function BarActionRow({
   return (
     <>
       {hasDesktop && desktopLead && (
-        <Group gap={BAR_GAP} wrap="nowrap" visibleFrom="sm" {...rootProps}>
-          {joinRuns(inline, { viewport: 'desktop' }).map((run) =>
+        <Group
+          ref={groupRef}
+          gap={BAR_GAP}
+          wrap="nowrap"
+          visibleFrom="sm"
+          // A `slot` host has no wider elastic row to measure against (`PageBar` row 1 is the only
+          // one an ancestor tags) — it measures its OWN row instead, and `Element.closest` matches
+          // an element against itself before it walks up, so `useMeasuredFold`'s `resolveRoot` needs
+          // no branch for it.
+          {...(host === 'slot' && { [PAGE_BAR_END_ATTR]: '' })}
+          {...rootProps}
+        >
+          {runs.map((run) =>
             run.length === 1 ? (
-              <BarEntry key={run[0]!.key} action={run[0]!} emphasis="secondary" />
+              <BarEntry
+                key={run[0]!.key}
+                action={run[0]!}
+                emphasis="secondary"
+                iconOnly={folds[run[0]!.key] === 'icon'}
+              />
             ) : (
-              <ControlGroup key={`join-${run[0]!.key}`}>
-                {run.map((action) => (
-                  <BarEntry key={action.key} action={action} emphasis="secondary" iconOnly />
-                ))}
-              </ControlGroup>
+              // Tagged so the joined set is measured and folded AS ONE BOX — its members are
+              // grandchildren of this `Group`, invisible to the direct-children scan
+              // `useMeasuredFold` runs, so the run needs its own `BAR_KEY_ATTR` one level up.
+              <Box
+                key={`join-${run[0]!.key}`}
+                className={classes.joinBox}
+                {...{ [BAR_KEY_ATTR]: run[0]!.key }}
+              >
+                <ControlGroup>
+                  {run.map((action) => (
+                    <BarEntry key={action.key} action={action} emphasis="secondary" iconOnly />
+                  ))}
+                </ControlGroup>
+              </Box>
             ),
           )}
           <OverflowMenu actions={desktopOverflow} />
@@ -621,8 +798,8 @@ export function BarActionRow({
 /**
  * A home's `actions` slot, projected for both viewports.
  *
- * Desktop: `primary` as a `filled` button · up to `DESKTOP_SECONDARY_MAX` secondaries as `default`
- * buttons · everything past that, plus every `kind: 'menu'`, in one `More` menu.
+ * Desktop: `primary` as a `filled` button · secondaries as `default` buttons, folded by the row's
+ * measured width (icon-only, then into `More`) · every `kind: 'menu'` in that same `More` menu.
  * Mobile: `primary` as an icon button when it ships an icon and a compact labelled button when it
  * does not · one kebab holding every `mobile: 'more'` action · `mobile: 'hidden'` drops the action
  * entirely.
@@ -676,8 +853,8 @@ export function isBarActionList(actions: SlotActions): actions is BarAction[] {
 
 /**
  * Renders a {@link SlotActions} slot: the typed form goes through the SAME projection `PageBar` and
- * `ActionGroup` use — inline up to {@link DESKTOP_SECONDARY_MAX}, the rest folded into `More`, and a
- * mobile kebab below `sm` — and the node form is returned untouched.
+ * `ActionGroup` use — inline, `kind: 'menu'` folded into `More`, and a mobile kebab below `sm` — and
+ * the node form is returned untouched.
  *
  * Every entry lands in `secondary`: a `BarAction[]` carries no primary marker, and law C6's "exactly
  * one primary" is the page bar's rule, enforced by `ActionGroupProps.primary` being singular. A home
@@ -710,7 +887,7 @@ function BarEntry({
 }: {
   action: BarAction
   emphasis: 'primary' | 'secondary' | 'mobile-primary' | 'mobile-secondary'
-  /** Set by a JOINED run — see {@link joinRuns}. The label survives as the accessible name. */
+  /** Set by a JOINED run (see {@link joinRuns}) or a measured fold. The label survives as the accessible name. */
   iconOnly?: boolean
 }): ReactNode {
   if (action.kind === 'custom') return <span className={classes.customSlot}>{action.node}</span>
@@ -720,35 +897,6 @@ function BarEntry({
   if (iconOnly === true && action.icon !== undefined) {
     return <BarIconButton action={action} variant="default" />
   }
-  // THE `md` LABEL FOLD — the second declared tier, and the only fold this row had between `sm`
-  // (48em, where the whole mobile swap happens) and the width at which a desktop header is
-  // genuinely wide. Above `sm` the only fold was `DESKTOP_SECONDARY_MAX`, which is a COUNT and
-  // never a width: three labelled secondaries are three labelled secondaries at 768px and at
-  // 2560px.
-  //
-  // The arithmetic, on /dashboard at exactly 768px — the width where the navbar appears and takes
-  // 256px: 512px of header left, against ~554px of row 1 + ~102px of globals + ~48px of gaps ≈
-  // 704px. ~192px over, and nothing above `sm` folded — the breadcrumb absorbed it by shrinking to
-  // zero (`shell/app-header.module.css`'s `.lead`, now floored at 96px, which this tier pays for).
-  // Dropping up to `DESKTOP_SECONDARY_MAX` labelled secondaries to their 30px icon form returns
-  // roughly 180-240px on that row: a labelled `ctl` button is its icon slot + label + insets
-  // (~90-110px depending on the word), an icon-only one is the tier's 30px square.
-  //
-  // The PRIMARY keeps its label at every width — it is the one action a reader must be able to
-  // name without hovering (law C6: exactly one per home), so `emphasis === 'primary'` never enters
-  // this branch. An icon-LESS secondary keeps its label too: there is nothing to fall back to, the
-  // same reason `MobileBarEntry` renders a compact labelled button below `sm`.
-  //
-  // Both forms are rendered and CSS picks one, the mechanism the `sm` swap already uses — that is
-  // law C9 being HONOURED, not breached: the swap belongs to the control, and this is the control.
-  if (emphasis === 'secondary' && action.icon !== undefined) {
-    return (
-      <>
-        <BarIconButton action={action} variant="default" tier={{ hiddenFrom: 'md' }} />
-        <BarButton action={action} variant="default" tier={{ visibleFrom: 'md' }} />
-      </>
-    )
-  }
   return <BarButton action={action} variant={emphasis === 'primary' ? 'filled' : 'default'} />
 }
 

package/src/controls/controls.module.css

@@ -4,7 +4,7 @@
  * Two form factors per control, ONE mount each, switched by CSS only (C9): the `pill` surface
  * (bordered 30px chip + popover) and the `sheet` surface (`PanelRow` label-above-control rows
  * inside the mobile `Filters (n)` Drawer — the same rows the aside's `panel` surface renders;
- * `panel-row.module.css` owns their geometry). `48em` / `47.99375em` are the `sm` breakpoint in the
+ * `panel-row.module.css` owns their geometry). `52.5em` / `52.49375em` are the `sm` size-class boundary in the
  * exact literal form every other basalt CSS module uses — a media query cannot resolve a custom
  * property, so the breakpoint cannot be a token (see `content/prose.module.css`'s note).
  */
@@ -49,8 +49,13 @@
   flex-shrink: 0;
 }
 
+/* theme-allow-file raw-media-query — the ControlRow's own C9 swap (pills inline, the rest in a
+   sheet) keys on the SIZE CLASS by design: the sheet is compact-class chrome, the same axis the
+   shell's bottom bar reads. Every width query here is `SIZE_CLASSES.medium`, pinned by
+   `breakpoint-literals.test.ts`. */
+
 /* Below `sm` only the first `inline` slots are pills; the rest live in the sheet. */
-@media (max-width: 47.99375em) {
+@media (max-width: 52.49375em) {
   .pillSlot:not([data-inline]) {
     display: none;
   }
@@ -60,7 +65,7 @@
  * Folding is a DESKTOP concern only — scoped to `min-width` so a width measured on a wide viewport
  * can never hide a slot the mobile `inline` budget is supposed to keep.
  */
-@media (min-width: 48em) {
+@media (min-width: 52.5em) {
   .pillSlot[data-folded] {
     display: none;
   }
@@ -71,7 +76,7 @@
   display: none;
 }
 
-@media (min-width: 48em) {
+@media (min-width: 52.5em) {
   .foldPill[data-shown] {
     display: inline-flex;
   }
@@ -81,7 +86,7 @@
   display: none;
 }
 
-@media (max-width: 47.99375em) {
+@media (max-width: 52.49375em) {
   .sheetPill {
     display: inline-flex;
   }
@@ -101,10 +106,11 @@
  * outline the row reads as loose text. Declared here rather than by relaxing the resolver, which
  * would put a hairline back on every default button in the app.
  *
- * The ≥36px touch target below `sm` (C15) is drawn as a `::before` overlay so the visible box stays
- * 30px.
+ * The touch target (C15) is the shared `[data-basalt-hit]` overlay (`styles.css`), capped at the
+ * chip-row gap so neighbouring pills never overlap; the visible box stays 30px.
  */
 .pill {
+  --vx-hit-gap: var(--vx-space-control-gap);
   position: relative;
   max-width: 15rem;
   border-color: color-mix(in srgb, var(--vx-ink) 12%, transparent);
@@ -157,30 +163,6 @@
   color: var(--vx-ink);
 }
 
-@media (max-width: 47.99375em) {
-  /* Mantine's Button root clips to its box; the overlay must escape it to be hit-testable. Loading
-   * buttons keep the clip their overlay depends on (same pairing as page-bar.module.css). */
-  .pill:not([data-loading]) {
-    overflow: visible;
-  }
-
-  .pill::before {
-    content: '';
-    position: absolute;
-    /* Both operands scale with `--mantine-scale` (same reconstruction the theme uses for every
-     * other ctl-tier box, `theme/index.ts`'s `ctlSizeVars`) so the overlay stays centred on — and
-     * sized off — the ACTUAL scaled pill box, not its unscaled rem value. */
-    inset-block: calc(
-      (
-          calc(var(--vx-space-control-height-ctl, 1.875rem) * var(--mantine-scale, 1)) -
-            calc(var(--vx-space-touch-control-height, 2.25rem) * var(--mantine-scale, 1))
-        ) /
-        2
-    );
-    inset-inline: 0;
-  }
-}
-
 /* Label at the tier's own step and weight (`docs/CONTROLS-SPEC.md` §3) — Mantine's Button label
  * inherits the root's `--button-fz` but carries the body weight, which reads light against the
  * bordered box. */