basalt-ui 1.26.0 → 1.27.0

package/src/dashboard/stat-card.module.css

@@ -42,6 +42,77 @@
   min-width: 0;
 }
 
+/*
+ * The `breakdown` rows — the two or three parts a hero number is made of, under it.
+ *
+ * NO hairline, anywhere in this block, and that is a law rather than a taste: `docs/CONTROLS-SPEC.md`
+ * §2.1 puts a horizontal rule between OPTION rows and nowhere else, and `theme/divider-law.test.ts`
+ * inventories every one basalt draws. Three rules inside a KPI card would read as a table wearing a
+ * card's clothes. The rows are separated by the stack rhythm and by weight — a muted label against
+ * an ink value — which is the same separation the sheet's own field groups use.
+ */
+.breakdown {
+  display: flex;
+  flex-direction: column;
+  margin: var(--vx-space-stack-sm) 0 0;
+  padding: 0;
+  min-width: 0;
+}
+
+/*
+ * One row, one line, at the TAG tier (`controlHeightTag`, 20px at level 0) — the smallest control
+ * step basalt declares, and a token rather than a literal so the rows track the density knob with
+ * everything else. `justify-content: space-between` is what makes the pair read as a row without a
+ * grid: the label leads, the value trails, and neither needs a column to align against because
+ * every row in one card is the same box.
+ */
+.breakdownRow {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--vx-space-control-gap);
+  min-height: var(--vx-space-control-height-tag);
+  min-width: 0;
+}
+
+.breakdownLabel {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: var(--vx-text-sm);
+  color: var(--vx-muted);
+}
+
+/* Mono and ink — a breakdown value is a number, and it is the half of the row worth reading. Never
+ * shrinks: the LABEL is the prose half and the one that may ellipsize. */
+.breakdownValue {
+  flex-shrink: 0;
+  margin: 0;
+  font-family: var(--basalt-font-mono);
+  font-size: var(--vx-text-sm);
+  font-weight: 500;
+  color: var(--vx-ink);
+}
+
+/*
+ * A row past a threshold. Same vocabulary and the same per-scheme solids as the card's own tone rail
+ * (`stat-card.tsx`'s `VX.status[tone]`), so a row saying `bad` and a rail saying `bad` are one claim
+ * at two scales. Colour is not the only carrier at the CARD level (the rail ships a
+ * `VisuallyHidden` verdict); at the ROW level the label is the carrier — a row reading
+ * `Paid · 1,204` states its own subject either way, and the tint only ranks it.
+ */
+.breakdownRow[data-tone='good'] .breakdownValue {
+  color: var(--vx-status-good);
+}
+
+.breakdownRow[data-tone='warn'] .breakdownValue {
+  color: var(--vx-status-warn);
+}
+
+.breakdownRow[data-tone='bad'] .breakdownValue {
+  color: var(--vx-status-bad);
+}
+
 .sparklineBleed {
   margin-top: auto;
   margin-inline: calc(-1 * var(--mantine-spacing-sm));

package/src/dashboard/stat-card.module.css.d.ts

@@ -5,6 +5,10 @@
 declare const classes: {
   readonly body: string
   readonly header: string
+  readonly breakdown: string
+  readonly breakdownRow: string
+  readonly breakdownLabel: string
+  readonly breakdownValue: string
   readonly sparklineBleed: string
   readonly sparklineRight: string
 }

package/src/dashboard/stat-card.test.tsx

@@ -21,6 +21,8 @@
  */
 import { MantineProvider } from '@mantine/core'
 import { describe, expect, test } from 'bun:test'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
 import { renderToStaticMarkup } from 'react-dom/server'
 import { StatCard } from './stat-card'
 import type { StatCardTone } from './stat-card'
@@ -152,3 +154,232 @@ describe('sparklinePlacement', () => {
     expect(markup).toContain('data-placement="right"')
   })
 })
+
+/**
+ * `unit` and `breakdown` — the two props that existed as hand-rolled cards in three consumers
+ * before they existed here. Both are asserted through the same static markup as the rail above; the
+ * CSS half (which cannot resolve under `bun test`, where a `.module.css` import is `undefined`) is
+ * pinned against the shipped stylesheet TEXT at the bottom of this file, the pattern
+ * `page-bar.test.tsx` uses.
+ */
+describe('unit — the hero value is a number and a unit, not one string', () => {
+  function renderUnit(props: { unit?: string; value?: string }) {
+    return renderToStaticMarkup(
+      <MantineProvider>
+        <StatCard title="Training load" value="412" {...props} />
+      </MantineProvider>,
+    )
+  }
+
+  test('renders after the value, and both are present', () => {
+    const markup = renderUnit({ unit: 'TSS' })
+    expect(markup).toContain('412')
+    expect(markup).toContain('TSS')
+    // Order matters — a unit BEFORE the numeral reads as a currency prefix, which it is not.
+    expect(markup.indexOf('412')).toBeLessThan(markup.indexOf('TSS'))
+  })
+
+  test('omitting it renders nothing extra', () => {
+    expect(renderUnit({})).not.toContain('TSS')
+  })
+
+  test('it is not the same channel as `subtitle` — a card may carry both', () => {
+    const markup = renderToStaticMarkup(
+      <MantineProvider>
+        <StatCard title="Training load" value="412" unit="TSS" subtitle="7-day rolling" />
+      </MantineProvider>,
+    )
+    expect(markup).toContain('TSS')
+    expect(markup).toContain('7-day rolling')
+  })
+})
+
+/**
+ * `deltaFormat` — because not every delta is a percentage, and the default said it was.
+ *
+ * A pace card's trend is `0:12 /km` and a speed card's is `0.3 km/h`; both rendered as `0.3%`, which
+ * is a wrong unit on a KPI — the failure worse than showing no chip at all, and the reason the
+ * consumer that needed one kept its card hand-rolled (the `HeroCard` fork `shadow-basalt-export`
+ * reports). The prop is a FUNCTION over the signed number, not a label string: `delta` still drives
+ * the tone and the glyph, so there is one place the sign is decided.
+ */
+describe('deltaFormat — a delta that is not a percentage', () => {
+  function renderDelta(props: {
+    delta?: number
+    deltaFormat?: (delta: number) => string
+    deltaGlyph?: boolean
+    deltaPeriod?: string
+  }) {
+    return renderToStaticMarkup(
+      <MantineProvider>
+        <StatCard title="Pace" value="5:31" unit="/km" {...props} />
+      </MantineProvider>,
+    )
+  }
+
+  test('the default is still a one-decimal percentage — no existing card moves', () => {
+    const markup = renderDelta({ delta: 0.3 })
+    expect(markup).toContain('0.3%')
+  })
+
+  test('a formatter replaces the label and the percent is gone', () => {
+    const markup = renderDelta({ delta: 0.3, deltaFormat: (v) => `${v.toFixed(1)} km/h` })
+    expect(markup).toContain('0.3 km/h')
+    expect(markup).not.toContain('0.3%')
+  })
+
+  test('the formatter receives the SIGNED value, so it can print an absolute delta itself', () => {
+    // argo's walking-pad pace card: the delta is seconds per km, faster is a negative number, and
+    // the sign belongs in the string. `deltaGlyph={false}` stops the ▼ saying it a second time.
+    const markup = renderDelta({
+      delta: -12,
+      deltaFormat: (s) => `${s < 0 ? '−' : '+'}0:${String(Math.abs(s)).padStart(2, '0')} /km`,
+      deltaGlyph: false,
+    })
+    // The chip's whole text, so nothing survives beside it — the glyph, or a stray `12.0%`.
+    expect(markup).toContain('>−0:12 /km</span>')
+    expect(markup).not.toContain('▼')
+  })
+
+  test('the glyph and the tone still come off the number, not the label', () => {
+    const markup = renderDelta({ delta: -12, deltaFormat: (s) => `${Math.abs(s)} s` })
+    // Negative reads as danger and keeps its ▼ — the formatter only owns the magnitude string.
+    expect(markup).toContain('▼')
+    expect(markup).toContain('var(--vx-status-bad)')
+  })
+
+  test('deltaPeriod still rides beside a formatted delta', () => {
+    const markup = renderDelta({
+      delta: 0.3,
+      deltaFormat: (v) => `${v.toFixed(1)} km/h`,
+      deltaPeriod: 'WoW',
+    })
+    expect(markup).toContain('0.3 km/h')
+    expect(markup).toContain('WoW')
+  })
+
+  test('a formatter with no delta renders no chip at all', () => {
+    expect(renderDelta({ deltaFormat: (v) => `${v} km/h` })).not.toContain('km/h')
+  })
+})
+
+describe('breakdown — the parts the hero number is made of', () => {
+  const ROWS = [
+    { label: 'Paid', value: '1,204' },
+    { label: 'Organic', value: '842' },
+    { label: 'Referral', value: '31', tone: 'bad' as const },
+  ]
+
+  function renderBreakdown(breakdown?: readonly { label: string; value: string }[]) {
+    return renderToStaticMarkup(
+      <MantineProvider>
+        <StatCard
+          title="Orders"
+          value="2,077"
+          {...(breakdown !== undefined ? { breakdown } : {})}
+        />
+      </MantineProvider>,
+    )
+  }
+
+  test('every row renders its label and its value', () => {
+    const markup = renderBreakdown(ROWS)
+    for (const row of ROWS) {
+      expect(markup).toContain(row.label)
+      expect(markup).toContain(row.value)
+    }
+  })
+
+  test('the rows are a description list — each row IS a term and its value', () => {
+    const markup = renderBreakdown(ROWS)
+    expect(markup).toContain('<dl')
+    expect((markup.match(/<dt/g) ?? []).length).toBe(3)
+    expect((markup.match(/<dd/g) ?? []).length).toBe(3)
+  })
+
+  test('a toned row carries data-tone; an untoned one carries nothing', () => {
+    const markup = renderBreakdown(ROWS)
+    expect(markup).toContain('data-tone="bad"')
+    // Omission is not `good`, exactly as it is not on the card itself.
+    expect(markup).not.toContain('data-tone="good"')
+  })
+
+  test('omitted, and an empty array, render no list at all', () => {
+    expect(renderBreakdown()).not.toContain('<dl')
+    expect(renderBreakdown([])).not.toContain('<dl')
+  })
+
+  // The reason the rows live INSIDE the header block rather than beside it: with
+  // `sparklinePlacement="right"` the card body is a flex ROW, so a third child there would sit next
+  // to the trend instead of under the number it splits.
+  test('the list sits inside the header block, before the sparkline slot', () => {
+    const markup = renderToStaticMarkup(
+      <MantineProvider>
+        <StatCard
+          title="Orders"
+          value="2,077"
+          breakdown={ROWS}
+          sparklinePlacement="right"
+          sparkline={<span>spark</span>}
+        />
+      </MantineProvider>,
+    )
+    expect(markup.indexOf('<dl')).toBeLessThan(markup.indexOf('spark'))
+  })
+})
+
+/**
+ * The CSS half, pinned against the shipped module text. A `.module.css` resolves to `undefined`
+ * under `bun test` (no bundler in the loop), so the class names never reach the markup and the only
+ * checkable thing is the stylesheet itself.
+ */
+describe('stat-card.module.css — the breakdown block', () => {
+  const css = readFileSync(resolve(import.meta.dirname, 'stat-card.module.css'), 'utf8')
+  /** Declarations only — the comments above them discuss hairlines and borders by name. */
+  const decls = css.replace(/\/\*[\s\S]*?\*\//g, '')
+
+  function rule(selector: string): string {
+    const start = decls.indexOf(`${selector} {`)
+    expect(start).toBeGreaterThan(-1)
+    return decls.slice(start, decls.indexOf('}', start))
+  }
+
+  test('a row is one line at the TAG tier, from the token and never a literal', () => {
+    expect(rule('.breakdownRow')).toContain('min-height: var(--vx-space-control-height-tag)')
+  })
+
+  // THE law this block had to not break: `theme/divider-law.test.ts` inventories every horizontal
+  // hairline basalt draws, and §2.1 puts one between OPTION rows and nowhere else. Three rules
+  // inside a KPI card would read as a table wearing a card's clothes — and would fail that test.
+  test('no row draws a hairline — not a border, not a rule, not a divider', () => {
+    expect(decls).not.toMatch(/\.breakdown[^{]*\{[^}]*border/)
+    expect(decls).not.toContain('--vx-surface-hairline')
+  })
+
+  test('the label is muted prose and the value is mono ink — the separation is weight, not a line', () => {
+    expect(rule('.breakdownLabel')).toContain('color: var(--vx-muted)')
+    expect(rule('.breakdownValue')).toContain('font-family: var(--basalt-font-mono)')
+    expect(rule('.breakdownValue')).toContain('color: var(--vx-ink)')
+  })
+
+  test('a toned row reads the per-scheme status solid, never a hex', () => {
+    for (const tone of ['good', 'warn', 'bad']) {
+      expect(rule(`.breakdownRow[data-tone='${tone}'] .breakdownValue`)).toContain(
+        `color: var(--vx-status-${tone})`,
+      )
+    }
+  })
+
+  test('the unit beside the hero value is mono, muted and small — in widget-header, its owner', () => {
+    const headerCss = readFileSync(
+      resolve(import.meta.dirname, '..', 'widget-header', 'widget-header.module.css'),
+      'utf8',
+    ).replace(/\/\*[\s\S]*?\*\//g, '')
+    const start = headerCss.indexOf('.unit {')
+    expect(start).toBeGreaterThan(-1)
+    const unit = headerCss.slice(start, headerCss.indexOf('}', start))
+    expect(unit).toContain('font-family: var(--basalt-font-mono)')
+    expect(unit).toContain('font-size: var(--vx-text-sm)')
+    expect(unit).toContain('color: var(--vx-muted)')
+  })
+})

package/src/dashboard/stat-card.tsx

@@ -100,6 +100,20 @@ import classes from './stat-card.module.css'
 /** A threshold verdict on the card's value. `undefined` is never tinted — see the module docblock. */
 export type StatCardTone = 'good' | 'warn' | 'bad'
 
+/**
+ * One row of a {@link StatCardProps.breakdown} — the two or three parts a hero number is made of.
+ *
+ * `value` is a pre-formatted `string` for the same reason the hero's is: the card cannot know the
+ * locale, the currency or the precision the number was measured at. `tone` marks ONE row as past a
+ * threshold and is the same vocabulary as the card's own `tone`, so a row saying `bad` and a rail
+ * saying `bad` are the same claim at two scales; omitting it is untinted, never `'good'`.
+ */
+export type StatCardBreakdownRow = {
+  readonly label: string
+  readonly value: string
+  readonly tone?: StatCardTone
+}
+
 /**
  * The `'right'` placement's slot width, in px — a flex BASIS, not a fixed size. 72 is the reference
  * KPI card's trend width and the slot asks for exactly that; when the hero row needs the space (a
@@ -187,10 +201,48 @@ export type StatCardProps = {
   info?: string
   /** Pre-formatted KPI value string (mono ~24px, weight 600, ink) — the hero-row value. */
   value: string
+  /** The value's unit, muted and mono at `--vx-text-sm`, immediately after it on the hero row —
+   * forwarded to `WidgetHeader`. `412` + `TSS`, not `"412 TSS"`: a unit painted at the hero's 24px
+   * reads as a second numeral. The BASIS (`7-day rolling`) is still `subtitle`; see
+   * `WidgetHeaderProps.unit`. */
+  unit?: string
+  /**
+   * The parts the hero number is made of — compact rows under it, one line each, no hairlines.
+   *
+   * It exists because three consumers wanted a KPI card that also SPLITS its number (revenue by
+   * channel, uptime by probe) and the only shapes basalt offered were a `subtitle` (one muted line,
+   * no second column) and a table. Both hand-rolled a card instead — which is the fork
+   * `shadow-basalt-export` reports as a `HeroCard`.
+   *
+   * Deliberately not a table and deliberately unruled: the divider law puts a hairline between
+   * OPTION rows and nowhere else (`docs/CONTROLS-SPEC.md` §2.1), and a KPI card that draws three
+   * of them stops reading as one card. Keep it to two or three rows — past that the card is a
+   * table, and a table is `BasaltDataTable` in a `Section`.
+   */
+  breakdown?: readonly StatCardBreakdownRow[]
   /** Signed delta rendered via `DeltaBadge`; omit to hide the trend chip entirely. */
   delta?: number
   /** Optional comparison timeframe shown after the delta (e.g. `MoM`) — forwarded to `DeltaBadge`. */
   deltaPeriod?: string
+  /**
+   * Formats `delta` into the chip's label — forwarded to `WidgetHeader` and on to `DeltaBadge`.
+   * Defaults to `${Math.abs(delta).toFixed(1)}%`.
+   *
+   * A delta is not always a percentage, and the default silently claimed it was: a pace card's trend
+   * (`0:12 /km`) and a speed card's (`0.3 km/h`) both rendered as `0.3%` — a wrong unit on a KPI is
+   * the one failure worse than no chip, and it is why the consumer that needed it kept the card
+   * hand-rolled instead (the `HeroCard` fork `shadow-basalt-export` reports).
+   *
+   * @example
+   * // An absolute delta that prints its own sign — no percent, no glyph saying it twice.
+   * <StatCard title="Pace" value="5:31" unit="/km" delta={-12}
+   *   deltaFormat={(s) => `${s < 0 ? '−' : '+'}0:${String(Math.abs(s)).padStart(2, '0')} /km`}
+   *   deltaGlyph={false} />
+   */
+  deltaFormat?: (delta: number) => string
+  /** Render the ▲/▼ glyph on the delta chip. Defaults to `true`; a zero delta never shows one. Pass
+   * `false` when `deltaFormat` prints the sign itself. */
+  deltaGlyph?: boolean
   /**
    * Optional trend visual. Either a node, or a RENDER PROP receiving the slot's measured box.
    *
@@ -223,8 +275,12 @@ export function StatCard({
   subtitle,
   info,
   value,
+  unit,
+  breakdown,
   delta,
   deltaPeriod,
+  deltaFormat,
+  deltaGlyph,
   sparkline,
   sparklinePlacement = 'bleed',
   actions,
@@ -291,8 +347,11 @@ export function StatCard({
             {...(subtitle !== undefined && { subtitle })}
             {...(info !== undefined && { info })}
             value={value}
+            {...(unit !== undefined && { unit })}
             {...(delta !== undefined && { delta })}
             {...(deltaPeriod !== undefined && { deltaPeriod })}
+            {...(deltaFormat !== undefined && { deltaFormat })}
+            {...(deltaGlyph !== undefined && { deltaGlyph })}
             // `tier="widget"`, not the default `ctl`: the header row this slot sits in is 28px
             // (`--vx-space-widget-header-height`) and a 30px `ctl` control grew it to 30, so a card
             // with a kebab sat 2px below a card without one in the same grid row. See
@@ -301,6 +360,28 @@ export function StatCard({
               actions: <CtlSlot tier="widget">{actions}</CtlSlot>,
             })}
           />
+
+          {breakdown !== undefined &&
+            breakdown.length > 0 && (
+              // A `<dl>`, not a table and not a stack of divs: each row IS a term and its value, which
+              // is the one semantic that survives a reader meeting the card out of context.
+              //
+              // INSIDE `.header`, not beside it: with `sparklinePlacement="right"` the body is a flex
+              // ROW, so a third child here would sit next to the trend rather than under the number
+              // it splits. The header block is the card's text column in both placements.
+              <dl className={classes.breakdown}>
+                {breakdown.map((row) => (
+                  <div
+                    key={row.label}
+                    className={classes.breakdownRow}
+                    {...(row.tone !== undefined && { 'data-tone': row.tone })}
+                  >
+                    <dt className={classes.breakdownLabel}>{row.label}</dt>
+                    <dd className={classes.breakdownValue}>{row.value}</dd>
+                  </div>
+                ))}
+              </dl>
+            )}
         </div>
 
         {sparkline !== undefined && (

package/src/data/data-table.tsx

@@ -189,6 +189,10 @@ function facetEnumHandle<T>(
         },
       ] as const
     },
+    // A facet column has no lane to unset: clearing the column filter IS its fallback state.
+    clear: () => {
+      column.setFilterValue(undefined)
+    },
     isDefault: (value) => value === FACET_ALL_VALUE,
   }
 }
@@ -215,6 +219,10 @@ function facetMultiHandle<T>(
         },
       ] as const
     },
+    // Same as the single-select facet: an empty column filter is this handle's fallback.
+    clear: () => {
+      column.setFilterValue(undefined)
+    },
     isDefault: (value) => value.length === 0,
   }
 }

package/src/guard/check-source.test.ts

@@ -2480,9 +2480,11 @@ describe('in-body-page-title', () => {
     expect(kinds(f)).not.toContain('in-body-page-title')
   })
 
-  it('lands warn while the grace entry stands (C16)', () => {
+  // Promoted at 1.27.0 — its GRACE_PERIOD_KINDS entry is gone, and so is the plugin rule of the
+  // same id from PLUGIN_RULE_GRACE. One law, two lanes, one promotion.
+  it('lands error now that the grace entry is gone (C16)', () => {
     const f = find(`<Title order={1}>Analytics</Title>`)
-    expect(f.find((x) => x.kind === 'in-body-page-title')?.severity).toBe('warn')
+    expect(f.find((x) => x.kind === 'in-body-page-title')?.severity).toBe('error')
   })
 })
 
@@ -2538,6 +2540,37 @@ describe('raw-selection-control', () => {
     expect(kinds(f)).not.toContain('raw-selection-control')
   })
 
+  // The CROSS-FILE exemption — the same basename convention the plugin's `control-outside-home`
+  // applies, so both lanes agree on the same file (one law, two lanes, one exemption). argo carried
+  // 9 of these: a control in a modal/form module whose `<Modal>` is rendered by the parent, which is
+  // outside the 12-line host window because the host tag is not in the file at all.
+  it.each([
+    'src/edit-session-modal.tsx',
+    'src/filters-drawer.tsx',
+    'src/column-popover.tsx',
+    'src/detail-panel.tsx',
+    'src/booking-form.tsx',
+  ])('does NOT flag %s — the overlay filename convention', (relPath) => {
+    expect(kinds(find(`<Select data={[]} />`, relPath))).not.toContain('raw-selection-control')
+  })
+
+  it('still flags a page module beside them', () => {
+    expect(kinds(find(`<Select data={[]} />`, 'src/bookings-page.tsx'))).toContain(
+      'raw-selection-control',
+    )
+  })
+
+  // Basename only, and it needs the leading subject: a `modal/` DIRECTORY holds the page pieces
+  // around the modals too, and a bare `modal.tsx` is a page module in every consumer that has one.
+  it.each(['src/modal/session.tsx', 'src/modal.tsx'])(
+    'is a subject-prefixed BASENAME convention, not %s',
+    (relPath) => {
+      expect(kinds(find(`<Select data={[]} />`, relPath))).toContain('raw-selection-control')
+    },
+  )
+
+  // Still warn at 1.27.0 — this kind and its AST twin `basalt/control-outside-home` are the C1 pair
+  // that moved to `promote: '1.28.0'` while the other wave-6 entries promoted.
   it('lands warn while the grace entry stands (C16)', () => {
     const f = find(`<Select data={[]} />`)
     expect(f.find((x) => x.kind === 'raw-selection-control')?.severity).toBe('warn')

package/src/guard/grace.test.ts

@@ -9,9 +9,10 @@
  * `assertGraceLedger` is tested directly against synthetic entries below rather than only through
  * the real ledger: every pre-existing entry promoted or moved to `PLUGIN_RULE_ADVISORY`'s guard-side
  * sibling, and an `it.each` over the empty ledger that left behind ran zero assertions, which proved
- * nothing about the gate actually firing. The ledger now carries the two wave-6 control kinds
- * (`in-body-page-title`, `raw-selection-control`, both `promote: '1.27.0'`), and the real-ledger
- * check below runs against them.
+ * nothing about the gate actually firing. The ledger carries ONE wave-6 control kind at 1.27.0 —
+ * `raw-selection-control`, re-dated to `promote: '1.28.0'` with its AST twin
+ * `basalt/control-outside-home` (`in-body-page-title` promoted on schedule and its entry is gone) —
+ * and the real-ledger check below runs against it.
  *
  * This gate measures the version already PUBLISHED, so it can only go red after the release that
  * shipped a due entry. `scripts/check-grace.ts` is the other end — `scripts/release.sh` runs it
@@ -138,8 +139,16 @@ describe('scripts/check-grace.ts', () => {
     expect(stderr).toContain('basalt/control-outside-home')
   })
 
-  it('refuses the version the wave-6 entries are due in (1.27.0)', () => {
-    expect(runCheckGrace('1.27.0').code).toBe(1)
+  // 1.27.0 promoted five of the six wave-6 plugin rules and one of the two guard kinds; what is
+  // LEFT is the C1 pair (`raw-selection-control` + `basalt/control-outside-home`), re-dated to
+  // 1.28.0 against a measurement rather than a hunch — see either entry's `why`. So the release
+  // this file used to refuse now passes, and the refusal moved with the pair.
+  it('passes 1.27.0 — the five entries due there promoted', () => {
+    expect(runCheckGrace('1.27.0').code).toBe(0)
+  })
+
+  it('refuses the version the remaining C1 pair is due in (1.28.0)', () => {
+    expect(runCheckGrace('1.28.0').code).toBe(1)
   })
 
   it('exits 2 on a missing or malformed version rather than passing vacuously', () => {

package/src/guard/index.ts

@@ -522,9 +522,25 @@ const CONTROL_HOST_TAG =
  */
 const CONTROL_HOST_WINDOW_LINES = 12
 
+/**
+ * A file whose BASENAME declares it is an overlay's or a form's own body — the cross-file half of
+ * {@link CONTROL_HOST_TAG}, and the same regex the plugin's `OVERLAY_CONVENTION_FILE` applies to
+ * `basalt/control-outside-home` (one law, two lanes, one exemption).
+ *
+ * Law C1's cross-file case is advisory by declaration (`docs/CONTROLS-SPEC.md` §6, "Honest
+ * coverage"), and this kind was paying for it: a `<Select>` inside `edit-session-modal.tsx` whose
+ * `<Modal>` is rendered by the parent route is outside BOTH the 12-line host window and any
+ * ancestry walk, because the host tag is not in the file at all. argo carried 9 of them.
+ *
+ * The trade is that a whole file goes unscanned on a naming convention — the same bargain
+ * {@link MANTINE_FORM_IMPORT} already buys, and a smaller one than promoting the kind with 9 known
+ * false positives. Basename only: a `modal/` DIRECTORY holds the page pieces around the modals too.
+ */
+const OVERLAY_CONVENTION_FILE = /(?:^|\/)[^/]*-(?:modal|drawer|popover|panel|form)\.[jt]sx$/
+
 /** A name whose DECLARATION means this file DEFINES a basalt control rather than consuming one. */
 const CONTROL_OWNER_DEF =
-  /\b(?:function|const|class)\s+(?:RangeFilter|CompareFilter|SelectFilter|MultiSelectFilter|SearchFilter|ToggleFilter|ViewTabs|FilterSet|FilterPill|SyncButton|ActionGroup|OverflowMenu|CtlSlot)(?![\w])/
+  /\b(?:function|const|class)\s+(?:RangeFilter|CompareFilter|SelectFilter|MultiSelectFilter|NumberFilter|SearchFilter|ToggleFilter|ViewTabs|FilterSet|FilterPill|SyncButton|ActionGroup|OverflowMenu|CtlSlot)(?![\w])/
 
 /** `@mantine/form` — a form is C1's third home, and its inputs are not filters. */
 const MANTINE_FORM_IMPORT = /from\s+['"]@mantine\/form['"]/
@@ -635,24 +651,19 @@ export type GraceEntry = { since: string; promote: string; why: string }
  * }
  */
 export const GRACE_PERIOD_KINDS: Partial<Record<GuardKind, GraceEntry>> = {
-  'in-body-page-title': {
-    since: '1.26.0',
-    promote: '1.27.0',
-    why:
-      'new in the wave-6 control guards (docs/CONTROLS-SPEC.md §6, law C8). Its AST twin is the ' +
-      'oxlint rule of the SAME id, whose PLUGIN_RULE_GRACE entry carries the same dates — one law, ' +
-      'two lanes, one promotion. Warn for a minor because the fix is a route/breadcrumb change ' +
-      '(the page is named by staticData.title), not a prop edit, so a consumer needs to schedule it.',
-  },
   'raw-selection-control': {
     since: '1.26.0',
-    promote: '1.27.0',
+    promote: '1.28.0',
     why:
       'new in the wave-6 control guards (docs/CONTROLS-SPEC.md §6, law C1). The text lane cannot ' +
       'see ancestry, so "no home" is approximated by a 12-line host-tag window — the loosest ' +
       'reading in the guard, and the reason this one lands warn rather than error even though its ' +
-      'law is settled. Promotion is gated with the plugin half on the wave-7 consumer run (≤3 ' +
-      'waivers), and `scripts/check-grace.ts` refuses the 1.27.0 release while the entry is still here.',
+      'law is settled. It moved from 1.27.0 to 1.28.0 with its AST twin, `basalt/control-outside-' +
+      'home`, whose PLUGIN_RULE_GRACE entry carries the measurement: the wave-7 run left 9 warns ' +
+      'in argo, all of them a control in a modal/form module whose `<Modal>` is rendered by the ' +
+      'PARENT — law C1 cross-file, which neither lane can see. `OVERLAY_CONVENTION_FILE` (this ' +
+      'file, and the same regex in the plugin) exempts that declared naming convention in both ' +
+      'lanes; 1.28.0 is when the remainder is re-measured. One law, two lanes, one promotion.',
   },
 }
 
@@ -1901,7 +1912,7 @@ export const GUARD_RULES = {
     enabled: (cfg: GuardConfig) => cfg.rawHtmlLayout,
     appliesTo: (relPath) => !isChartFile(relPath) && !relPath.endsWith('.css'),
     message:
-      'Raw HTML element with inline layout/surface styling that the line scan cannot see — the tag is formatted across lines, or the style object is hoisted to a const. Same violation as raw-html-layout: use a Mantine layout primitive (Box/Flex/Grid/Stack/Group). Promoted to error in the Unreleased minor (C16) with severity only — the kind stayed standalone rather than folding into raw-html-layout as originally planned; the merge is still open, tracked as a follow-up, not done here.',
+      'Raw HTML element with inline layout/surface styling that the line scan cannot see — the tag is formatted across lines, or the style object is hoisted to a const. Same violation as raw-html-layout: use a Mantine layout primitive (Box/Flex/Grid/Stack/Group). Promoted to error at 1.26.0 (C16) with severity only — the kind stayed standalone rather than folding into raw-html-layout as originally planned; the merge is still open, tracked as a follow-up, not done here.',
   },
   'in-body-page-title': {
     kind: 'in-body-page-title',
@@ -2369,11 +2380,13 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
   }
 
   // raw-selection-control — full-text tag scan plus the host WINDOW (see CONTROL_HOST_WINDOW_LINES).
-  // Two file-level exemptions mirror the plugin rule's, so the two lanes agree on the same file:
-  // a file that DEFINES a basalt control cannot be told to use one, and a file importing
-  // `@mantine/form` is a form — C1's third home, whose inputs are not filters.
+  // Three file-level exemptions mirror the plugin rule's, so the two lanes agree on the same file:
+  // a file that DEFINES a basalt control cannot be told to use one, a file importing
+  // `@mantine/form` is a form — C1's third home, whose inputs are not filters — and a file NAMED as
+  // an overlay body carries its `<Modal>` in the parent, where no scan of this file can reach it.
   if (
     ruleApplies('raw-selection-control', relPath) &&
+    !OVERLAY_CONVENTION_FILE.test(relPath) &&
     !CONTROL_OWNER_DEF.test(codeText) &&
     !MANTINE_FORM_IMPORT.test(codeText)
   ) {