basalt-ui 1.32.1 → 1.33.0

package/src/cli/index.ts

@@ -39,199 +39,8 @@ import { COMMAND_OPTIONS, USAGE, unknownFlag } from './help'
 import { init } from './init'
 import { sync } from './sync'
 import { fontsCss, normalizeColorFunctions, tokensCss } from './tokens-css'
-
-/** Shape of the optional `"basalt"` key in a consumer's package.json. */
-export type BasaltConfig = {
-  /** Source roots to scan. Default: `['src']`. Set explicitly for a monorepo layout. */
-  roots?: string[]
-  /** Files exempt from the scan (they ARE the palette source). Default: argo's exempt set. */
-  exempt?: string[]
-  /**
-   * Declares this package a tokens-only consumer: it uses the `--vx-*` layer and no Mantine. Turns
-   * off every guard kind whose remedy is a Mantine component, a Mantine prop or the React theme
-   * factory, leaving the color and typography kinds live. Default: `'mantine'`.
-   *
-   * Deliberately not inferred from a missing `@mantine/core`: silencing 17 rules (the live count is
-   * `TOKENS_ONLY_DISABLED_KINDS.size`, which the check-theme banner prints) is a decision, and
-   * a repo that keeps Mantine in a workspace package would otherwise switch off half its own guard
-   * without saying so. `basalt-ui doctor` detects the shape and tells you to set this.
-   */
-  profile?: 'mantine' | 'tokens-only'
-  /**
-   * Extra files to scan, named individually and relative to this package — for a design surface
-   * that lives outside every root and outside the `index.html` / `public/` conventions the walker
-   * already derives. Also the ONLY way a `.json` is ever scanned: the guard understands JSON as
-   * markup, but a consumer repo's JSON is overwhelmingly config, fixtures and lockfiles, so
-   * blanket-scanning it is a false-positive generator rather than a guard.
-   *
-   * @example
-   * { include: ['app/manifest.json', 'emails/template.html'] }
-   */
-  include?: string[]
-  /** Named spacing-scale steps (px) flagged when used as a raw spacing prop. Default: 10/12/16/20/32. */
-  spacingSteps?: number[]
-  /** Per-kind severity override — `'warn'` reports without failing, `'error'` fails the build.
-   *  See `GuardSeverity` in ../guard/types for the grace-minor doctrine behind it. */
-  severity?: Partial<Record<GuardKind, GuardSeverity>>
-  /** Off-identity Mantine accent families forbidden as chrome accents. Default: argo's set. */
-  forbiddenAccents?: string[]
-  /** Earned accent hue recorded in DESIGN.md `{{ACCENT_HUE}}`. Default: `blue`. */
-  accentHue?: string
-  /**
-   * Flag any numeric radius prop literal (radius={6}) — use the radius token scale instead.
-   * Default: `true` (ON). Set `false` to disable the `raw-radius` check (e.g. a repo that DEFINES
-   * the radius primitives).
-   */
-  rawRadius?: boolean
-  /**
-   * Flag ad-hoc inline surface styling (`border`/`borderRadius`/`boxShadow` literals in a `style={{}}`)
-   * that bypasses the radius-token + `VX.surface.*` + `VX.shadowCard` system. Default: `true` (ON).
-   * Set `false` to disable the `raw-surface` check.
-   */
-  rawSurface?: boolean
-  /**
-   * Flag `withBorder` on a `Card` / `Paper`. Card depth is `--vx-shadow-card` — a whisper shadow
-   * with the 1px ring baked into the SAME value — so `withBorder` draws a SECOND, real border over
-   * that ring and the card reads heavy/boxed (docs/DESIGN-SPEC.md doctrine inversion #1).
-   * `withBorder={false}` and `<Card.Section withBorder>` (a section divider) both pass.
-   * Default: `true` (ON). Set `false` to disable the `card-with-border` check.
-   */
-  cardWithBorder?: boolean
-  /**
-   * Flag references to a raw Mantine ramp step used for surface color
-   * (`var(--mantine-color-gray-N)` / `var(--mantine-color-dark-N)`) — these bypass the basalt
-   * surface tokens. Default: `true` (ON). Set `false` to disable the `off-system-surface-var` check.
-   */
-  offSystemSurfaceVar?: boolean
-  /**
-   * Flag a SHADE-PINNED Mantine color — `c="yellow.7"`, `bg="blue.4"`,
-   * `var(--mantine-color-red-6)`. A pinned step is one fixed swatch in BOTH color schemes, so it
-   * cannot stay legible in either; route a verdict color through `VX.status.*` / `--vx-status-*`,
-   * or drop the index (`c="red"`) and let the theme resolve the shade per scheme. `gray-*`/`dark-*`
-   * in `var()` form belong to `off-system-surface-var` instead. Default: `true` (ON). Set `false`
-   * to disable the `mantine-shade-index` check.
-   */
-  mantineShadeIndex?: boolean
-  /**
-   * Flag raw lowercase JSX layout/surface elements (`div`/`span`/`section`/…) carrying an inline
-   * `style={{}}` with a layout/surface property — steer to a Mantine layout primitive
-   * (`Box`/`Flex`/`Grid`/`Stack`/`Group`/`SimpleGrid`/`Paper`). Default: `true` (ON). Set `false`
-   * to disable the `raw-html-layout` check.
-   */
-  rawHtmlLayout?: boolean
-  /**
-   * Flag spacing/sizing literals inside an inline `style={{}}` (`padding`/`margin`/`gap`/…) — the
-   * `raw-spacing` check only catches the Mantine prop syntax. Default: `true` (ON). Set `false` to
-   * disable the `inline-spacing` check.
-   */
-  inlineSpacing?: boolean
-  /**
-   * Flag `display: 'flex' | 'grid' | 'inline-flex' | 'inline-grid'` in an inline `style={{}}` —
-   * steer to `<Flex>`/`<Grid>`/`<Group>`. Default: `true` (ON). Set `false` to disable the
-   * `inline-display` check.
-   */
-  inlineDisplay?: boolean
-  /**
-   * Flag raw `<AxisLeft>` / `<AxisBottom>` / `<AxisRight>` visx JSX inside chart files (a path
-   * containing `/charts/`) — these bypass the `AxisLeftNumeric` / `AxisBottomDate` /
-   * `AxisRightNumeric` primitives that carry the theme tokens + smart ticks. The legitimate wrapper
-   * (`Axes.tsx`, which IS the primitive) is exempt. Default: `true` (ON). Set `false` to disable the
-   * `raw-visx-axis` check.
-   */
-  rawVisxAxis?: boolean
-  /**
-   * Flag a hardcoded duration/spring/ease literal inline in a `transition={{...}}` prop — route it
-   * through `MOTION_DURATION` / `MOTION_SPRING` / `MOTION_EASE_STANDARD` instead. Default: `true`
-   * (ON). Set `false` to disable the `raw-motion-value` check.
-   */
-  rawMotionValue?: boolean
-  /**
-   * Flag a chart entry-point JSX tag (`MultiLine`/`Bars`/`Donut`/`DualPanel`/`Heatmap`/`ZonedLine`/
-   * `StackedArea`/`LineSparkline`/`BarSparkline`) missing an `ariaLabel` prop. Default: `true`
-   * (ON). Set `false` to disable the `chart-missing-aria-label` check.
-   */
-  chartMissingAriaLabel?: boolean
-  /**
-   * Flag a raw lowercase `<input>`/`<select>`/`<textarea>` JSX element — it bypasses the entire
-   * theme, not just the iOS font-size floor. Use the Mantine equivalents (`TextInput`,
-   * `NumberInput`, `Select`, `Textarea`, …) instead. Default: `true` (ON). Set `false` to disable
-   * the `raw-form-control` check.
-   */
-  rawFormControl?: boolean
-  /**
-   * Flag a `fontSize`/`font-size` literal below 16 inside a `style={{…}}` on a raw form control,
-   * or a Mantine `styles={{ input: {…} }}` per-part style — the `styles.css` iOS floor is
-   * `!important`, so the override is dead code. Default: `true` (ON). Set `false` to disable the
-   * `sub-16-input-font` check.
-   */
-  sub16InputFont?: boolean
-  /**
-   * Path of the consumer's guard-exempt series file, for DESIGN.md `{{SERIES_MODULE_PATH}}`.
-   * Default: `<first basalt.root>/lib/series.ts` — see `resolveSeriesModulePath`.
-   */
-  seriesModulePath?: string
-  /**
-   * Per-rule, per-path exemptions — complements whole-file `exempt` (which skips ALL rules for a
-   * file) and the hardcoded per-kind `appliesTo` scoping (e.g. `raw-visx-axis` → chart files
-   * only). Each value is a list of patterns matched against a finding's relative path. A pattern
-   * may be a whole path segment (`'agent'` matches `src/agent/x.tsx`, not `src/agenting.ts`), a
-   * relative path (`'public/site.webmanifest'`), a directory prefix, or a glob — `*` stops at `/`,
-   * `**` does not, and a slash-free glob also matches the basename, so `'*.module.css'` works.
-   * A trailing `/` is stripped. An entry that suppresses nothing is reported, and
-   * `check-theme --audit-allows` exits 1 on it. Default: `{}` (no exemptions).
-   *
-   * Two forms per kind. The bare array is paths only. The object form adds the REASON, which is
-   * the half a `theme-allow` carries and this key could not: JSON has no comments, so a
-   * `.webmanifest` / `.json` finding's only escape is this key, and it was un-reviewable by
-   * construction — the rationale ended up in a CLAUDE.md paragraph nobody reads next to the diff.
-   * `check-theme --audit-allows` prints the reason (or names its absence) beside what the entry
-   * still suppresses. The array form stays supported and unchanged; nothing here is required.
-   *
-   * @example
-   * { exemptRules: { 'inline-display': ['agent'] } } // inline-display never fires under src/agent/**
-   * @example
-   * { exemptRules: { 'raw-hex': { paths: ['site.webmanifest'],
-   *   reason: 'a PWA manifest theme_color MUST be a literal hex — JSON cannot reference a CSS var' } } }
-   */
-  exemptRules?: Partial<Record<GuardKind, ExemptRuleEntry>>
-  /**
-   * Declares an intentional `ai` package major-version skew across workspace packages, exempting
-   * `doctor`'s `ai-major-parity` hard check. The value IS the reason — a bare `true` is rejected,
-   * because the whole point of this key is that the pairing is written down, not just switched off.
-   * A written declaration is the pin `basalt/ai-sdk-major`'s own comment notes is otherwise missing.
-   *
-   * Semantics: absent (or present but not a non-empty string) → the skew still hard-fails exactly as
-   * without this key. A non-empty string with a skew present → `doctor` passes, echoing both the
-   * skew and this reason. A non-empty string with NO skew present → `doctor` warns that the
-   * exemption is stale and can be deleted (an exemption nobody re-checks is how a real, later skew
-   * slips through unnoticed).
-   *
-   * @example
-   * // apps/api streams on ai@5; apps/dashboard parses on ai@7; a producer-side TransformStream
-   * // neutralizes the one enum value that differs between the two majors.
-   * { aiMajorSkewReason: 'apps/api pinned to ai@5, apps/dashboard on ai@7 — the skew is neutralized '
-   *   + 'by a producer-side TransformStream in apps/api/src/stream-transform.ts' }
-   */
-  aiMajorSkewReason?: string
-}
-
-/**
- * One `basalt.exemptRules` value: the historical bare path list, or the same list with the reason
- * it exists. See `BasaltConfig.exemptRules`.
- */
-export type ExemptRuleEntry = string[] | { paths: string[]; reason: string }
-
-/** The paths half of an exemption entry, whichever form it was written in. */
-export function exemptRulePaths(entry: ExemptRuleEntry | undefined): string[] {
-  if (entry === undefined) return []
-  return Array.isArray(entry) ? entry : entry.paths
-}
-
-/** The recorded reason for an exemption entry, or null for the bare-array form. */
-export function exemptRuleReason(entry: ExemptRuleEntry | undefined): string | null {
-  if (entry === undefined || Array.isArray(entry)) return null
-  return entry.reason.trim().length > 0 ? entry.reason.trim() : null
-}
+import { DEFAULT_ROOT, exemptRulePaths, resolveRoots } from './config'
+import type { BasaltConfig } from './config'
 
 /**
  * The guard-shaped `exemptRules` — paths only. The reason the object form carries never reaches
@@ -247,19 +56,6 @@ export function resolveExemptRules(cfg: BasaltConfig): GuardConfig['exemptRules'
   return out
 }
 
-export const DEFAULT_ROOT = 'src'
-export const DEFAULT_ROOTS = [DEFAULT_ROOT]
-
-/**
- * The configured source roots, or the built-in default. The ONE resolution every roots-derived seed
- * reads — an empty `roots: []` falls back rather than resolving to nothing, because a bare `??`
- * would let `[]` through and render an empty oxfmt glob into the seeded CI, reproducing the exact
- * "matches zero files" break this derivation exists to prevent.
- */
-export function resolveRoots(cfg: BasaltConfig): string[] {
-  return cfg.roots?.length ? cfg.roots : DEFAULT_ROOTS
-}
-
 /**
  * The one consumer series path — the DESIGN.md template's `{{SERIES_MODULE_PATH}}`, the default
  * scan exemption, and the skills' prose all resolve through this single function.

package/src/commands/define-commands.ts

@@ -24,7 +24,6 @@
  */
 import type { ReactNode } from 'react'
 import type { Slot } from '../register'
-import { isDev } from '../common/is-dev'
 
 // ── Context ───────────────────────────────────────────────────────────────────
 
@@ -172,7 +171,8 @@ export function defineCommand(cmd: Command): Command {
 export function runCommand(id: CommandId, ctx?: CommandRunContext): void | Promise<void> {
   const cmd = activeCommands[id as string]
   if (cmd === undefined) {
-    if (isDev()) console.warn(`[basalt] runCommand: no command registered for "${id}"`)
+    if (process.env.NODE_ENV !== 'production')
+      console.warn(`[basalt] runCommand: no command registered for "${id}"`)
     return
   }
   return cmd.run(ctx)

package/src/commands/define-overlays.ts

@@ -29,7 +29,6 @@ import type { ReactNode } from 'react'
 import { useEffect } from 'react'
 import { missingLayer } from '../common/errors'
 import type { Slot } from '../register'
-import { isDev } from '../common/is-dev'
 
 // ── Lazy @mantine/modals resolution ───────────────────────────────────────────
 // @mantine/modals is an OPTIONAL peer — never imported at module evaluation time, so importing
@@ -372,7 +371,7 @@ export const overlays = {
   open<K extends OverlayKey>(key: K, props: OverlayProps<K>): void {
     const spec = activeOverlays[key as string]
     if (spec === undefined) {
-      if (isDev())
+      if (process.env.NODE_ENV !== 'production')
         console.warn(`[basalt] overlays.open: no overlay registered for "${String(key)}"`)
       return
     }

package/src/common/index.ts

@@ -19,5 +19,4 @@ export {
 } from './errors'
 export { useValidateProps, assertRequiredProps, resetValidatedProps } from './validate'
 export { scrollParentOf, SCROLLPORT_ATTRIBUTE } from './scroll-parent'
-export { isDev } from './is-dev'
 export { MOTION_DURATION, MOTION_EASE_STANDARD, MOTION_SPRING } from './motion'

package/src/common/validate.ts

@@ -7,7 +7,6 @@
  * mean warns once in dev and renders on (`useValidateProps`).
  */
 import { useEffect } from 'react'
-import { isDev } from './is-dev'
 import { requiredProp } from './errors'
 
 /** A check returns the message(s) it has, or nothing. `null`/`undefined` entries are ignored. */
@@ -23,8 +22,8 @@ const reported = new Set<string>()
 
 /**
  * Dev-only prop validation. `console.error`s each message ONCE per `(component, message)` pair, and
- * is a no-op in production: `isDev()` reads `process.env.NODE_ENV`, which every bundler
- * constant-folds, so the whole body disappears from a production build.
+ * is a no-op in production: the gate is a literal `process.env.NODE_ENV` read, which every bundler
+ * constant-folds, so the whole body disappears from a production build (see `dev-gate.test.ts`).
  *
  * **The dedup key is `${component} ${message}`, and nothing else** — not the instance, not the
  * props. Two instances of one component producing the SAME message say it once between them, which
@@ -46,7 +45,7 @@ export function useValidateProps(
   deps: unknown[],
 ): void {
   useEffect(() => {
-    if (!isDev()) return
+    if (process.env.NODE_ENV === 'production') return
     const result = check()
     const messages = Array.isArray(result) ? result : [result]
     for (const raw of messages) {
@@ -67,7 +66,7 @@ export function useValidateProps(
  * are about to win in the very next render.
  */
 export function reportOnce(component: string, message: string): void {
-  if (!isDev()) return
+  if (process.env.NODE_ENV === 'production') return
   const key = `${component} ${message}`
   if (reported.has(key)) return
   reported.add(key)

package/src/content/article-card.tsx

@@ -166,6 +166,7 @@ export type ArticleGridProps = {
 
 export function ArticleGrid({ children, cols = 3 }: ArticleGridProps) {
   return (
+    // theme-allow raw-breakpoint — `cols` is documented per viewport `lg`; container keys would re-flow every consumer's grid, so that move ships opt-in
     <SimpleGrid cols={{ base: 1, sm: 2, lg: cols }} spacing="sm">
       {children}
     </SimpleGrid>

package/src/controls/enum-filter.tsx

@@ -26,13 +26,13 @@
  * its doc). Both public wrappers still type `field` exactly, so a wrong field kind is still a type
  * error at the call site; the widening lives here, where nothing consumer-facing points at it.
  */
-import { Button, Radio, Stack } from '@mantine/core'
+import { Radio, Stack } from '@mantine/core'
 import type { ReactNode } from 'react'
 import type { BasaltProps } from '../common/props'
 import type { FieldOption } from '../state'
 import classes from './controls.module.css'
 import { POPOVER_ROW_HIT_GAP, useFilterRegistration, useFilterSurface } from './filter-context'
-import { FilterPill } from './filter-pill'
+import { FilterClearButton, FilterPill } from './filter-pill'
 import { useControlName } from './filter-sheet'
 import { PanelChoice, PanelRow } from './panel-row'
 import type { FilterOption } from './select-filter'
@@ -157,17 +157,7 @@ export function EnumFilter<T extends string>({
           />
         ))}
       </Stack>
-      {clearable === true && !isDefault && (
-        <Button
-          variant="subtle"
-          size="ctl"
-          onClick={() => {
-            field.clear()
-          }}
-        >
-          Clear
-        </Button>
-      )}
+      {clearable === true && !isDefault && <FilterClearButton onClear={() => field.clear()} />}
     </Radio.Group>
   )
 

package/src/controls/filter-pill.tsx

@@ -122,3 +122,23 @@ export function FilterPill({
     </Popover>
   )
 }
+
+/**
+ * The popover's `Clear` — one button for `EnumFilter`, `NumberFilter` and `MultiSelectFilter`. Its
+ * mousedown keeps focus where it is: a stepper commits its draft on blur, so a press that blurred
+ * first would land the typed value in the URL a tick before the clear replaced it.
+ */
+export function FilterClearButton({ onClear }: { readonly onClear: () => void }): ReactNode {
+  return (
+    <Button
+      variant="subtle"
+      size="ctl"
+      onMouseDown={(event) => {
+        event.preventDefault()
+      }}
+      onClick={onClear}
+    >
+      Clear
+    </Button>
+  )
+}

package/src/controls/multi-select-filter.tsx

@@ -22,7 +22,7 @@
  * // arrive as a map rather than baked into the labels the way the runtime catalogue does it.
  * <MultiSelectFilter field={shipments.field.origin} label="Origin" counts={countsByOrigin} />
  */
-import { Button, Checkbox, Stack } from '@mantine/core'
+import { Checkbox, Stack } from '@mantine/core'
 import { useState } from 'react'
 import type { CSSProperties, ReactNode } from 'react'
 import type { BasaltProps } from '../common/props'
@@ -31,7 +31,7 @@ import type { FieldHandle, MultiField } from '../state'
 import type { FilterOption } from './select-filter'
 import classes from './controls.module.css'
 import { POPOVER_ROW_HIT_GAP, useFilterRegistration, useFilterSurface } from './filter-context'
-import { FilterPill } from './filter-pill'
+import { FilterClearButton, FilterPill } from './filter-pill'
 import { CheckGlyph, useControlName } from './filter-sheet'
 import { PanelRow } from './panel-row'
 
@@ -153,17 +153,7 @@ export function MultiSelectFilter<T extends string>(props: MultiSelectFilterProp
           />
         ))}
       </Stack>
-      {!isDefault && (
-        <Button
-          variant="subtle"
-          size="ctl"
-          onClick={() => {
-            field.clear()
-          }}
-        >
-          Clear
-        </Button>
-      )}
+      {!isDefault && <FilterClearButton onClear={() => field.clear()} />}
     </Checkbox.Group>
   )
 

package/src/controls/number-filter.tsx

@@ -51,6 +51,12 @@
  * // An open threshold — a pill holding a stepper, applied on blur or Enter.
  * // minDuration: field.number({ fallback: 0, min: 0, max: 600 })
  * <NumberFilter field={lines.field.minDuration} label="Min duration" step={30} />
+ *
+ * @example
+ * // "No filter" is the fallback, not a row: `clearable` writes it back, and the pill reads the
+ * // filter's name while no preset is picked.
+ * // difficulty: field.number({ fallback: 0, min: 0, max: 5, int: true })
+ * <NumberFilter field={library.field.difficulty} label="Difficulty" options={LEVELS} clearable />
  */
 import { NumberInput } from '@mantine/core'
 import { useEffect, useRef, useState } from 'react'
@@ -62,7 +68,7 @@ import classes from './controls.module.css'
 import { EnumFilter } from './enum-filter'
 import type { ChoiceHandle } from './enum-filter'
 import { useFilterRegistration, useFilterSurface } from './filter-context'
-import { FilterPill } from './filter-pill'
+import { FilterClearButton, FilterPill } from './filter-pill'
 import { useControlName } from './filter-sheet'
 import { PanelRow } from './panel-row'
 
@@ -89,6 +95,9 @@ export type NumberFilterProps = BasaltProps & {
    * declared none. Absent on both, the input keeps Mantine's own default of 1.
    */
   readonly step?: number
+  /** Adds a `Clear` action that clears the field — the same `field.clear()` `Reset all` calls.
+   *  Parity with `SelectFilter`/`EnumFilter`, in both forms. */
+  readonly clearable?: boolean
 }
 
 export function NumberFilter(props: NumberFilterProps): ReactNode {
@@ -97,7 +106,7 @@ export function NumberFilter(props: NumberFilterProps): ReactNode {
   assertRequiredProps('NumberFilter', props, ['field'], {
     field: 'bind it to a store field (`store.field.<name>`), never a value/onChange pair.',
   })
-  const { field, label, icon, options, step, className, style } = props
+  const { field, label, icon, options, step, clearable, className, style } = props
   // Two BRANCHES, two components, and never a conditional hook: the radio form's state lives in
   // `EnumFilter` and the stepper's in `NumberStepper`, so which one mounts is decided once by a prop
   // that does not change across a mount's life.
@@ -107,6 +116,7 @@ export function NumberFilter(props: NumberFilterProps): ReactNode {
         field={field}
         label={label}
         options={options}
+        {...(clearable === true && { clearable: true })}
         {...(icon !== undefined && { icon })}
         {...(className !== undefined && { className })}
         {...(style !== undefined && { style })}
@@ -120,6 +130,7 @@ export function NumberFilter(props: NumberFilterProps): ReactNode {
     <NumberStepper
       field={field}
       label={label}
+      {...(clearable === true && { clearable: true })}
       {...(icon !== undefined && { icon })}
       {...(grain !== undefined && { step: grain })}
       {...(className !== undefined && { className })}
@@ -147,6 +158,7 @@ function NumberChoice({
   label,
   icon,
   options,
+  clearable,
   className,
   style,
 }: BasaltProps & {
@@ -154,6 +166,7 @@ function NumberChoice({
   readonly label: string
   readonly icon?: ReactNode
   readonly options: readonly NumberFilterOption[]
+  readonly clearable?: boolean
 }): ReactNode {
   const [value, setValue] = field.use()
   const rows = options.map((option) => ({ value: String(option.value), label: option.label }))
@@ -182,6 +195,7 @@ function NumberChoice({
       label={label}
       numeric
       options={rows}
+      {...(clearable === true && { clearable: true })}
       {...(icon !== undefined && { icon })}
       {...(className !== undefined && { className })}
       {...(style !== undefined && { style })}
@@ -195,6 +209,7 @@ function NumberStepper({
   label,
   icon,
   step,
+  clearable,
   className,
   style,
 }: BasaltProps & {
@@ -202,6 +217,7 @@ function NumberStepper({
   readonly label: string
   readonly icon?: ReactNode
   readonly step?: number
+  readonly clearable?: boolean
 }): ReactNode {
   const [value, setValue] = field.use()
   const surface = useFilterSurface()
@@ -265,7 +281,12 @@ function NumberStepper({
       {...(className !== undefined && { className })}
       {...(style !== undefined && { style })}
     >
-      <div className={classes.optionList}>{input}</div>
+      <div className={classes.optionList}>
+        {input}
+        {/* Same placement as `EnumFilter`'s: popover only — the sheet and panel rows reset through
+            the `FilterSet` registration above. The draft follows the clear via its effect. */}
+        {clearable === true && !isDefault && <FilterClearButton onClear={() => field.clear()} />}
+      </div>
     </FilterPill>
   )
 }

package/src/controls/range-filter.tsx

@@ -32,7 +32,6 @@ import { useEffect, useRef, useState } from 'react'
 import type { ComponentType, ReactNode } from 'react'
 import type { BasaltProps } from '../common/props'
 import { assertRequiredProps } from '../common/validate'
-import { isDev } from '../common/is-dev'
 import type { FieldHandle, RangeField, RangeValue } from '../state'
 import classes from './controls.module.css'
 import { useFilterRegistration, useFilterSurface } from './filter-context'
@@ -60,7 +59,7 @@ const noPickerWarned = new Set<string>()
  * the type cannot tell "deliberately preset-only" from "forgot the import".
  */
 function warnCustomWithoutPicker(label: string, unreachable: boolean): void {
-  if (!unreachable || !isDev() || noPickerWarned.has(label)) return
+  if (!unreachable || process.env.NODE_ENV === 'production' || noPickerWarned.has(label)) return
   noPickerWarned.add(label)
   // oxlint-disable-next-line no-console -- a dev-time wiring warning has no other channel
   console.warn(

package/src/data/data-table.tsx

@@ -98,7 +98,6 @@ import {
   useRowDisclosure,
 } from './data-table-state'
 import { dataQueryBranch } from './query-branch'
-import { isDev } from '../common/is-dev'
 import classes from './data-table.module.css'
 
 // ── Column alignment ──────────────────────────────────────────────────────────
@@ -303,7 +302,7 @@ function resolveFacetColumn<T>(
 ): Column<T, unknown> | undefined {
   const column = table.getColumn(facet.columnId)
   if (column) return column
-  if (isDev()) {
+  if (process.env.NODE_ENV !== 'production') {
     const knownIds = table
       .getAllColumns()
       .map((known) => known.id)
@@ -1231,7 +1230,7 @@ const reportedBreaches = new Set<string>()
 function enforceManualPaginationContract(breaches: ManualPaginationBreach[]): void {
   if (breaches.length === 0) return
   const message = manualPaginationMessage(breaches)
-  if (isDev()) throw new Error(message)
+  if (process.env.NODE_ENV !== 'production') throw new Error(message)
   if (reportedBreaches.has(message)) return
   reportedBreaches.add(message)
   console.error(message)