basalt-ui 1.32.0 → 1.33.0

package/configs/oxlint-plugin.js

@@ -177,6 +177,7 @@ export const KNOWN_RULE_IDS = new Set([
   'in-body-page-title',
   'raw-selection-control',
   'raw-media-query',
+  'unknown-vx-token',
   // Retired guard kinds — no longer in GUARD_RULES, but a `theme-allow` naming one must still
   // parse as a real (dead) waiver rather than an unknown-id typo. See RETIRED_RULE_IDS above.
   ...RETIRED_RULE_IDS,
@@ -390,8 +391,12 @@ function hasFileDeclaration(context, ruleId) {
   )
 }
 
-/** Test/spec files — design guidance does not apply to a fixture. Mirrors `src/cli`'s own SKIP. */
-const TEST_FILE = /\.(?:test|spec)\.[cm]?[jt]sx?$|(?:^|[\\/])__tests__[\\/]/
+/**
+ * Test/spec files — design guidance does not apply to a fixture. Mirrors `src/cli`'s own SKIP, plus
+ * a `test/`/`tests/` directory (1.32.1): a test-setup polyfill (`tests/setup/dom.ts` stubbing
+ * `window.matchMedia`) is neither a `.test` file nor under `__tests__`, and needed a waiver.
+ */
+const TEST_FILE = /\.(?:test|spec)\.[cm]?[jt]sx?$|(?:^|[\\/])(?:__tests__|tests?)[\\/]/
 
 function isTestFile(context) {
   return TEST_FILE.test(getFilename(context))
@@ -2698,9 +2703,8 @@ const CONTROL_OUTSIDE_HOME_MESSAGE =
 
 /**
  * The cross-file half of C1, and the one rule here that is openly a HEURISTIC: "this control has
- * no home" is a claim about layout intent, which no AST can see. It ships `warn` for that reason
- * and stays warn until the playground and the five consumer repos run it with ≤3 waivers
- * (docs/CONTROLS-SPEC.md §9 wave 7).
+ * no home" is a claim about layout intent, which no AST can see. That is why it sat in grace from
+ * 1.26.0 to 1.33.0, promoting only once basalt's tree and nine consumers measured at zero.
  *
  * Four exemptions carry the false-positive load: an overlay/settings-row/form-row ancestor
  * ({@link CONTROL_HOST_TAGS}, `FormRow`/`FormGroup` included), an {@link isOverlayConventionFile}
@@ -2708,7 +2712,7 @@ const CONTROL_OUTSIDE_HOME_MESSAGE =
  * `@mantine/form` (a form is the third home and its inputs are not filters), and the owner
  * exemption — a file DEFINING a basalt control cannot be told to use one.
  */
-// Ships: warn (grace → 1.33.0)
+// Ships: error
 const controlOutsideHome = {
   meta: {
     type: 'suggestion',
@@ -3972,26 +3976,57 @@ function isResponsiveObjectValue(node, namedOnly = false) {
   return !namedOnly || names.some((name) => name !== 'base')
 }
 
+/** The `const` initializers {@link reachableObjects} can resolve an Identifier to. */
+const RESOLVABLE_INIT_TYPES = new Set([
+  'ObjectExpression',
+  'ConditionalExpression',
+  'LogicalExpression',
+  'Identifier',
+])
+
 /**
- * Does this prop value CONTAIN a responsive object — itself, nested one level down in a property
- * (`footer={{ height: { base: 60, sm: 0 } }}`, Mantine's own AppShell idiom), or behind a same-file
- * `const` binding at either place (`const h = { base: 60, sm: 0 }`, then `footer={{ height: h }}`)?
- * `consts` is the same-file name→object map, so an Identifier resolves identically wherever it
- * appears — the top-level attribute value and a nested property value alike. Matching only a nested
- * `ObjectExpression` left the Identifier-in-a-property shape trivially bypassable.
+ * Every object literal a value can evaluate to: an Identifier resolves through `consts` (the
+ * same-file name→init map) FIRST, then a conditional contributes both branches and a logical both
+ * sides — in any nesting, so `const span = wide ? { base: 12, md: 4 } : 12` then `span={span}` is
+ * the same shape as writing the conditional inline (rb's hero Grid was a false negative until
+ * 1.32.1). `seen` guards an Identifier cycle (`const a = b`, `const b = a`) and a shared object.
  */
-function containsResponsiveObjectValue(node, consts, namedOnly = false, seen = new Set()) {
-  const resolved =
-    node !== null && node !== undefined && node.type === 'Identifier' ? consts.get(node.name) : node
-  if (resolved === null || resolved === undefined || resolved.type !== 'ObjectExpression')
-    return false
-  if (seen.has(resolved)) return false
+function reachableObjects(node, consts, seen = new Set()) {
+  const resolved = node?.type === 'Identifier' ? consts.get(node.name) : node
+  if (resolved === null || resolved === undefined || seen.has(resolved)) return []
   seen.add(resolved)
-  if (isResponsiveObjectValue(resolved, namedOnly)) return true
-  return resolved.properties.some(
-    (prop) =>
-      prop.type === 'Property' &&
-      containsResponsiveObjectValue(prop.value, consts, namedOnly, seen),
+  switch (resolved.type) {
+    case 'ObjectExpression':
+      return [resolved]
+    case 'Identifier':
+      return reachableObjects(resolved, consts, seen)
+    case 'ConditionalExpression':
+      return [resolved.consequent, resolved.alternate].flatMap((branch) =>
+        reachableObjects(branch, consts, seen),
+      )
+    case 'LogicalExpression':
+      return [resolved.left, resolved.right].flatMap((side) => reachableObjects(side, consts, seen))
+    default:
+      return []
+  }
+}
+
+/**
+ * Does this prop value CONTAIN a responsive object — any object it can evaluate to
+ * ({@link reachableObjects}), or one nested one level down in a property of one
+ * (`footer={{ height: { base: 60, sm: 0 } }}`, Mantine's own AppShell idiom), the property value
+ * resolving the same way. Matching only a nested `ObjectExpression` left the Identifier-in-a-
+ * property shape trivially bypassable.
+ */
+function containsResponsiveObjectValue(node, consts, namedOnly = false, seen = new Set()) {
+  return reachableObjects(node, consts, seen).some(
+    (object) =>
+      isResponsiveObjectValue(object, namedOnly) ||
+      object.properties.some(
+        (prop) =>
+          prop.type === 'Property' &&
+          containsResponsiveObjectValue(prop.value, consts, namedOnly, seen),
+      ),
   )
 }
 
@@ -4031,8 +4066,9 @@ const CONTAINER_ROUTED_PROPS = {
  * `type` has to be the string literal `"container"`; a dynamic value is not a decision this rule
  * can read. `Grid.Col` takes its grid's mode by walking to the nearest enclosing `Grid` element.
  * `consts` is the rule's same-file name→object map, so `breakpoints={map}` resolves like any value.
+ * The one IMPORTED map trusted is basalt's own `CONTAINER_GRID_BREAKPOINTS` ({@link isShippedGridMap}).
  */
-function containerGridMode(opening, mantineImports, consts) {
+function containerGridMode(opening, mantineImports, consts, sourceCode) {
   let tag = resolveMantineTag(opening.name, mantineImports)
   let grid = opening
   if (tag === 'Grid.Col') {
@@ -4061,12 +4097,69 @@ function containerGridMode(opening, mantineImports, consts) {
   const breakpoints = attr('breakpoints')
   if (breakpoints === undefined) return 'fallback'
   let map = attrValue(breakpoints)
+  if (isShippedGridMap(sourceCode, map)) return 'container'
   if (map?.type === 'Identifier') map = consts.get(map.name)
   const nonEmpty =
     map?.type === 'ObjectExpression' && map.properties.some((prop) => prop.type === 'Property')
   return nonEmpty ? 'container' : 'fallback'
 }
 
+/**
+ * Whether `node` reads basalt's own `CONTAINER_GRID_BREAKPOINTS` — its value is known, so it is
+ * the one imported `breakpoints` map trusted. Resolved through the scope manager to the BINDING the
+ * identifier reads, never by local name: a parameter or inner `const` shadowing the import is not
+ * the import. The binding has to be an `ImportSpecifier` naming it from `basalt-ui/tokens` (any
+ * alias, not type-only), a `.CONTAINER_GRID_BREAKPOINTS` member of that module's namespace import,
+ * or a `const` whose initializer resolves the same way. Without a scope manager nothing is trusted
+ * — reported, the conservative answer.
+ */
+function isShippedGridMap(sourceCode, node, seen = new Set()) {
+  if (node?.type === 'MemberExpression') return isShippedGridMapMember(sourceCode, node)
+  if (node?.type !== 'Identifier' || seen.has(node)) return false
+  seen.add(node)
+  const def = soleDefinition(sourceCode, node)
+  if (def?.type === 'ImportBinding') {
+    const spec = def.node
+    const decl = def.parent
+    if (decl?.type !== 'ImportDeclaration' || decl.importKind === 'type') return false
+    if (decl.source?.value !== 'basalt-ui/tokens') return false
+    if (spec.type !== 'ImportSpecifier' || spec.importKind === 'type') return false
+    const imported = spec.imported
+    const importedName = imported.type === 'Identifier' ? imported.name : imported.value
+    return importedName === 'CONTAINER_GRID_BREAKPOINTS'
+  }
+  if (def?.type === 'Variable' && def.parent?.kind === 'const')
+    return isShippedGridMap(sourceCode, def.node.init, seen)
+  return false
+}
+
+/** `tokens.CONTAINER_GRID_BREAKPOINTS` (or `tokens['CONTAINER_GRID_BREAKPOINTS']`) on `import * as tokens from 'basalt-ui/tokens'`. */
+function isShippedGridMapMember(sourceCode, node) {
+  const property = node.property
+  const name = node.computed
+    ? isStringLiteral(property) && property.value
+    : property?.type === 'Identifier' && property.name
+  if (name !== 'CONTAINER_GRID_BREAKPOINTS' || node.object?.type !== 'Identifier') return false
+  const def = soleDefinition(sourceCode, node.object)
+  return (
+    def?.type === 'ImportBinding' &&
+    def.node.type === 'ImportNamespaceSpecifier' &&
+    def.parent?.importKind !== 'type' &&
+    def.parent?.source?.value === 'basalt-ui/tokens'
+  )
+}
+
+/** The one definition of the variable `identifier` reads, or `undefined` (unresolved, or more than one). */
+function soleDefinition(sourceCode, identifier) {
+  if (typeof sourceCode?.getScope !== 'function') return undefined
+  for (let scope = sourceCode.getScope(identifier); scope; scope = scope.upper) {
+    const variable = scope.set.get(identifier.name)
+    if (variable === undefined) continue
+    return variable.defs.length === 1 ? variable.defs[0] : undefined
+  }
+  return undefined
+}
+
 /**
  * The shell components that are `visibleFrom`/`hiddenFrom`'s legitimate home — the size-class
  * axis's one JSX escape hatch, alongside overlays. Matched by DECLARATION name, the same
@@ -4099,7 +4192,7 @@ const RAW_BREAKPOINT_EXEMPT_FILE = /(?:^|[\\/])(?:use-media-query\.ts|ChartToolt
 export const RAW_BREAKPOINT_RECIPE =
   'A page’s own layout keys on its container: <SimpleGrid type="container" cols={{ base: 1, ' +
   "'480px': 2, '800px': 3 }}> (px keys = CONTAINER_CLASSES, basalt-ui/tokens), or <Grid " +
-  'type="container" breakpoints={…}> mapping all five xs–xl onto those px widths, with Grid.Col ' +
+  'type="container" breakpoints={CONTAINER_GRID_BREAKPOINTS}> (basalt-ui/tokens), with Grid.Col ' +
   'span={{ base: 12, sm: 6 }} keyed through that map; a Flex direction swap becomes that SimpleGrid (equal ' +
   'columns), a wrapping Group, or a CSS-module @container basalt-grid rule. useSizeClass() is for ' +
   'shell chrome only. Recipes: basalt-ui MIGRATING.md § basalt/raw-breakpoint.'
@@ -4108,6 +4201,33 @@ const RAW_BREAKPOINT_RESPONSIVE_PROP_MESSAGE =
   'Responsive-object prop keyed on theme breakpoints — those are viewport widths. ' +
   `${RAW_BREAKPOINT_RECIPE} (basalt/raw-breakpoint)`
 
+/** rb r2 #5: a `(hover: none)` read was flagged with advice that only covered widths. */
+const RAW_BREAKPOINT_POINTER_HINT =
+  'A hover/pointer capability read belongs in CSS: @media (pointer: coarse) in a module (the ' +
+  'query --vx-hit keys on) — (hover: none) is not a sanctioned query.'
+
+const RAW_BREAKPOINT_BASE_ONLY_MESSAGE =
+  'Responsive-object prop with only a base key — there is no breakpoint in it at all, so drop the ' +
+  'object and write the value: cols={{ base: 3 }} → cols={3}. (basalt/raw-breakpoint)'
+
+/**
+ * Is every responsive object this value can evaluate to ({@link reachableObjects} — the same
+ * unwrap detection uses) one carrying ONLY `base`? That is no breakpoint decision, and the viewport
+ * recipe is the wrong advice for it — the fix is the bare value. Message-only: the shape still
+ * reports, as it always has.
+ */
+function isBaseOnlyResponsiveObject(node, consts) {
+  const responsive = reachableObjects(node, consts).filter((object) =>
+    isResponsiveObjectValue(object),
+  )
+  return (
+    responsive.length > 0 &&
+    responsive.every((object) =>
+      object.properties.every((prop) => propertyKeyName(prop) === 'base'),
+    )
+  )
+}
+
 const RAW_BREAKPOINT_CONTAINER_KEY_MESSAGE =
   'Theme breakpoint name under type="container" — Mantine does not resolve it there: ' +
   "SimpleGrid uses each key verbatim as a (min-width: …) length, so 'sm' is a dead query, " +
@@ -4121,11 +4241,12 @@ const RAW_BREAKPOINT_VISIBLE_HIDDEN_MESSAGE =
 const RAW_BREAKPOINT_HOOK_MESSAGE =
   "useMediaQuery/useMatches/useViewportSize — a raw viewport read outside the framework's " +
   'one seam. Shell chrome reads useSizeClass(); a page swapping its own layout (a table for a card ' +
-  `list, a column count) is a container decision. ${RAW_BREAKPOINT_RECIPE} (basalt/raw-breakpoint)`
+  `list, a column count) is a container decision. ${RAW_BREAKPOINT_POINTER_HINT} ` +
+  `${RAW_BREAKPOINT_RECIPE} (basalt/raw-breakpoint)`
 
 const RAW_BREAKPOINT_GLOBAL_MESSAGE =
   'window.matchMedia/window.innerWidth read directly — the viewport read useSizeClass() owns ' +
-  `for shell chrome. ${RAW_BREAKPOINT_RECIPE} (basalt/raw-breakpoint)`
+  `for shell chrome. ${RAW_BREAKPOINT_POINTER_HINT} ${RAW_BREAKPOINT_RECIPE} (basalt/raw-breakpoint)`
 
 /** The three viewport hooks the law names, whatever module they are imported from. */
 const RAW_BREAKPOINT_HOOK_NAMES = new Set(['useMediaQuery', 'useMatches', 'useViewportSize'])
@@ -4141,7 +4262,7 @@ const RAW_BREAKPOINT_HOOK_NAMES = new Set(['useMediaQuery', 'useMatches', 'useVi
  * declares a shell home (or a control's own C9 swap) is exempt for all four shapes uniformly — the
  * shell's own responsive chrome is the sanctioned use, whatever shape it takes.
  */
-// Ships: warn (grace → 1.33.0)
+// Ships: error
 const rawBreakpoint = {
   meta: {
     type: 'suggestion',
@@ -4168,12 +4289,14 @@ const rawBreakpoint = {
     let definesShellHome = false
     const visibleHiddenCandidates = []
     const responsiveObjectCandidates = []
-    // Same-file `const NAME = { base, sm }` bindings, resolved when a JSX attribute or a nested
-    // property passes the Identifier — no scope manager here, so this is a flat name→object map.
+    // Same-file `const NAME = { base, sm }` bindings (or a conditional/logical/alias init, see
+    // RESOLVABLE_INIT_TYPES), resolved when a JSX attribute or a nested property passes the
+    // Identifier — no scope manager here, so this is a flat name→init map.
     // A name declared more than once in the file is ambiguous (its two bindings cannot be told
     // apart), so it is dropped from the map entirely rather than guessed at last-wins.
     const responsiveObjectConsts = new Map()
     const seenDeclaratorNames = new Set()
+    const sourceCode = context.sourceCode ?? context.getSourceCode?.()
 
     const noteShellHomeOwner = (name) => {
       if (typeof name === 'string' && SHELL_HOME_NAMES.has(name)) definesShellHome = true
@@ -4217,7 +4340,7 @@ const rawBreakpoint = {
           return
         }
         seenDeclaratorNames.add(name)
-        if (node.init?.type === 'ObjectExpression') responsiveObjectConsts.set(name, node.init)
+        if (RESOLVABLE_INIT_TYPES.has(node.init?.type)) responsiveObjectConsts.set(name, node.init)
       },
       JSXAttribute(node) {
         const name = node.name?.name
@@ -4258,16 +4381,16 @@ const rawBreakpoint = {
             ? CONTAINER_ROUTED_PROPS[tag]
             : undefined
           const mode = routed?.has(node.name.name)
-            ? containerGridMode(owner, mantineImports, responsiveObjectConsts)
+            ? containerGridMode(owner, mantineImports, responsiveObjectConsts, sourceCode)
             : undefined
           if (mode === 'container') continue
           if (!containsResponsiveObjectValue(value, responsiveObjectConsts, mode !== undefined))
             continue
           if (hasThemeAllow(context, node, 'raw-breakpoint')) continue
-          const message =
-            mode === undefined
-              ? RAW_BREAKPOINT_RESPONSIVE_PROP_MESSAGE
-              : RAW_BREAKPOINT_CONTAINER_KEY_MESSAGE
+          let message = RAW_BREAKPOINT_RESPONSIVE_PROP_MESSAGE
+          if (mode !== undefined) message = RAW_BREAKPOINT_CONTAINER_KEY_MESSAGE
+          else if (isBaseOnlyResponsiveObject(value, responsiveObjectConsts))
+            message = RAW_BREAKPOINT_BASE_ONLY_MESSAGE
           context.report({ node, message })
         }
         for (const node of visibleHiddenCandidates) {
@@ -4309,59 +4432,7 @@ const rawBreakpoint = {
  *
  * @type {Record<string, GraceEntry>}
  */
-export const PLUGIN_RULE_GRACE = {
-  'control-outside-home': {
-    since: '1.26.0',
-    promote: '1.33.0',
-    why:
-      "Extended 1.32.0 -> 1.33.0 at the 1.32.0 release, the last extension: basalt's own tree is at 0 (consumer-loop r1 dogfood) and argo is at 2, but RE-MEASURED 2026-09-30 the fleet carries ~33 (image-gen 11, rb 7, image-share 6, weatherorb 5, email-gateway 4, argo 2). The 1.32.0 fleet upgrade clears them while they warn, together with raw-breakpoint, so 1.33.0 promotes all four ids against a measured-clean fleet. " +
-      'Extended 1.31.0 -> 1.32.0 at the 1.31.0 release: the basalt tree still carries incumbents (data-table, notifications center, theme-lab) and the argo sweep has not run. ' +
-      'the wave-6 control guards (docs/CONTROLS-SPEC.md §6). The one openly HEURISTIC rule of the ' +
-      'set — "this control has no home" is a claim about layout intent, so its false-positive load ' +
-      'is carried by four exemptions (overlay/settings-row ancestor, the overlay FILENAME ' +
-      'convention below, @mantine/form, owner definition) rather than by certainty. The other five ' +
-      'wave-6 rules promoted at 1.27.0; this one has not, across three re-datings. ' +
-      'RE-MEASURED 2026-09-09, every consumer freshly migrated to 1.29.2 and basalt built from ' +
-      'master: 29 incumbents across five repos — image-gen 10, rb 8, image-share 6, the playground ' +
-      '3, argo 2 — and zero in linewatch, meteo and obsidian. The 1.28.0 prediction held: ' +
-      "{@link isOverlayConventionFile} took argo's 9 cross-file overlay warns down to 2, which is " +
-      'the part of the remainder that was ever going to fall to an exemption. ' +
-      'Extended to 1.31.0, and the argument is NOT the count — it is that 1.30.0 is the first ' +
-      'release in which this rule names an answer the 29 can reach. Every home it listed was a ' +
-      'shell slot (PageBar / Section / WidgetHeader), so a consumer that mounts `BasaltProvider` ' +
-      'and no `BasaltShell` had no reachable home at all: image-gen is a Tauri window with a ' +
-      'hand-rolled header and carries 10 of the 29 by itself, and `bound-control-outside-home` ' +
-      'closed the `ViewTabs` escape it would otherwise have taken. 1.30.0 adds the missing ' +
-      'sentence to both messages ({@link SHELL_LESS_HOME_HINT} — a `PageBar` outside a shell ' +
-      'renders in flow, sticky, with its own title, which is what `src/shell/page-bar.tsx` ' +
-      'actually does). Promoting a rule to `error` in the same minor that first makes it ' +
-      'satisfiable hands a consumer zero minors to act on the answer, which is exactly the failure ' +
-      'the grace mechanism exists to prevent. 1.31.0 is when the 29 have been through the new home ' +
-      'and the remainder is measured against that number. A file outside the convention that is ' +
-      "still an overlay's own body declares it with " +
-      '`theme-allow-file control-outside-home — overlay`.',
-  },
-  'raw-breakpoint': {
-    since: '1.31.0',
-    promote: '1.33.0',
-    why:
-      'New in the wave-11 responsive/touch guards. Catches four independent shapes at once — a ' +
-      'responsive-object Mantine prop, visibleFrom/hiddenFrom outside the three shell homes, the ' +
-      'three raw viewport hooks, and window.matchMedia/innerWidth — none of which basalt policed ' +
-      'before this wave, so every consumer on an earlier minor has a green build with all four ' +
-      "shapes already in it. basalt-ui/content's own article-card.tsx (a `SimpleGrid cols={{ base: " +
-      "1, sm: 2, lg }}`) was one incumbent measured in basalt's own tree at ship time — a real " +
-      'number, not zero, so it shipped warn rather than error. ' +
-      'Extended 1.32.0 -> 1.33.0: 1.31.0 shipped the rule naming "a container query" but no ' +
-      'primitive, and MIGRATING never mentioned it (argo: 42 warns, no documented target). 1.32.0 ' +
-      'is the first minor with a reachable, documented answer (Mantine type="container" grids keyed ' +
-      'on CONTAINER_CLASSES, exempted here), and promoting in the minor that first makes a rule ' +
-      'satisfiable hands a consumer zero minors to act on it — the control-outside-home ' +
-      "extension's reasoning. 1.33.0 is when the incumbents are expected to have moved to a " +
-      'container grid or a theme-allow with a stated reason. Promotes together with its CSS twin, ' +
-      'the `raw-media-query` guard kind.',
-  },
-}
+export const PLUGIN_RULE_GRACE = {}
 
 /**
  * Plugin rules that stay `warn` in the shipped preset PERMANENTLY — outside the C16 version gate,