basalt-ui 1.19.1 → 1.20.0

package/src/guard/types.ts

@@ -1,12 +1,12 @@
 /**
  * Guard types — Mantine-free, dependency-free (zero imports beyond TS types).
  *
- * GuardKind is the closed set of 20 violation kinds the theme guard can emit.
+ * GuardKind is the closed set of 25 violation kinds the theme guard can emit.
  * Finding is the structured result per violation, replacing the old `Violation` shape.
  * GuardConfig is the per-run configuration that drives checkSource.
  */
 
-/** The 20 theme-guard violation kinds. */
+/** The 25 theme-guard violation kinds. */
 export type GuardKind =
   | 'raw-hex'
   | 'raw-color-fn'
@@ -28,6 +28,11 @@ export type GuardKind =
   | 'raw-form-control'
   | 'sub-16-input-font'
   | 'raw-font-family'
+  | 'theme-allow-unscoped'
+  | 'surface-shadow-override'
+  | 'css-raw-surface'
+  | 'inline-font-size'
+  | 'hidden-inline-style'
 
 /**
  * How hard a finding lands. `error` fails the build; `warn` reports and passes.
@@ -151,10 +156,30 @@ export type GuardConfig = {
    */
   readonly sub16InputFont: boolean
   /**
-   * Allow-comment policy: a line containing this substring is skipped entirely.
-   * Default 'theme-allow'. Pure-comment lines (// * /\*) are always skipped.
+   * Allow-comment policy. The token that opens an exception annotation inside a COMMENT, on the
+   * finding's own line or the line directly above it (matching the oxlint plugin's placement, and
+   * surviving an `oxfmt` reflow that moves the comment off the offending line). Default
+   * `'theme-allow'`.
+   *
+   * The accountable form is `theme-allow <rule-id>[, <rule-id>] — <reason>`: the rule ids scope the
+   * exception to those kinds only, and the reason says why. A `theme-allow` missing either half
+   * still suppresses (so an upgrade never breaks a build over it) but reports
+   * {@link GuardKind} `theme-allow-unscoped` on its own line.
    */
   readonly allowComment: string
+  /**
+   * Which kinds apply to this consumer. `'mantine'` (default) is the full framework guard.
+   *
+   * `'tokens-only'` is for a consumer that installs the TOKEN LAYER and nothing else — no
+   * `@mantine/core`, often no React (`basalt-ui tokens:css` + `basalt-ui/tokens`). Every kind whose
+   * remedy is a Mantine component or prop is disabled there, because "use `TextInput` from
+   * `@mantine/core`" is not advice, it is a dependency the consumer deliberately does not have.
+   * The color/typography kinds stay on — those are the tokens, which is the whole surface they DO
+   * consume. See `TOKENS_ONLY_DISABLED_KINDS` in `./index` for the exact set.
+   *
+   * Optional so a caller built before this field existed keeps compiling; absent means `'mantine'`.
+   */
+  readonly profile?: 'mantine' | 'tokens-only'
   /**
    * Per-rule, per-path exemptions — complements whole-file `exempt` (BasaltConfig, which skips
    * ALL rules for a file) and code-level `appliesTo` (hardcoded per-kind path scoping, e.g.

package/src/register.ts

@@ -156,3 +156,35 @@ export namespace StandardSchemaV1 {
     T['~standard']['types']
   >['output']
 }
+
+// ── Ambient app globals ───────────────────────────────────────────────────────────────────────────
+
+declare global {
+  /**
+   * The app's version string, injected as a build-time constant by basalt's own Vite preset —
+   * `basaltViteConfig` defines it from `BUILD_VERSION`, falling back to the app package.json
+   * `version` (see `../vite`, the `define` block).
+   *
+   * Declared HERE rather than beside the define because a consumer's `src/**` never loads
+   * `basalt-ui/vite`'s types (that subpath is imported from `vite.config.ts`, which most apps keep
+   * in a separate tsconfig project). This file is re-exported from the root barrel, so an app that
+   * imports from `'basalt-ui'` at all has it in scope with no `/// <reference>` and no
+   * `src/vite-env.d.ts` entry — which is the point: basalt shipped the define and no declaration,
+   * so every consumer hand-wrote this block, one of them needing an `oxlint-disable` in a file that
+   * existed only because basalt asked for it.
+   *
+   * A consumer importing ONLY a subpath (`basalt-ui/tokens`, `basalt-ui/charts`) does not load this
+   * file and does not get the global. That gap is the same set as the applicability gap: reaching
+   * for the root barrel is what `BasaltProvider` requires, and an app that never does is not on
+   * basalt's Vite preset either, so there is no `__APP_VERSION__` to declare.
+   *
+   * Precondition: only defined when your Vite config actually goes through `basaltViteConfig` (or
+   * you define it yourself). An app that hand-rolls its Vite config and reads this gets a
+   * ReferenceError at runtime — TypeScript is trusting the preset, not proving it.
+   */
+  // The dangle IS the API: this declares the build-time constant basalt's own Vite preset defines,
+  // so the name is not ours to change. The SHIPPED preset allows it (configs/oxlint.json); this
+  // repo's own root .oxlintrc.json does not, hence the local suppression.
+  // oxlint-disable-next-line no-underscore-dangle
+  const __APP_VERSION__: string
+}

package/src/shell/app-mobile-nav.module.css

@@ -46,9 +46,17 @@
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  /* Deliberately sub-scale: the active pill hugs a 24px glyph, so it is a shape inset rather than
-   * layout spacing — the xs..xl scale has no step this tight. */
-  padding: 2px 12px; /* theme-allow */
+  /* This span IS the active pill, so its box may not depend on what it contains: shipping no icon
+   * dependency is a supported configuration, and an empty span collapsed the pill to a 24x4px
+   * dash. The floor is the icon box PLUS its inset — everything is border-box under Mantine's
+   * reset — so the pill renders identically with and without a glyph, at every density. */
+  min-width: calc(
+    var(--vx-space-mobile-nav-icon-size) + 2 * var(--vx-space-mobile-nav-tab-inset-x)
+  );
+  min-height: calc(
+    var(--vx-space-mobile-nav-icon-size) + 2 * var(--vx-space-mobile-nav-tab-inset-y)
+  );
+  padding: var(--vx-space-mobile-nav-tab-inset-y) var(--vx-space-mobile-nav-tab-inset-x);
   border-radius: var(--vx-radius-ctrl);
   transition: transform 140ms cubic-bezier(0.32, 0.72, 0, 1);
 }

package/src/shell/app-mobile-nav.tsx

@@ -38,7 +38,7 @@ import classes from './app-mobile-nav.module.css'
  * bottom-anchored menu puts it UNDER the footer, off-screen — `menuMax` is what guarantees it fits
  * above the bar (§2.2). `shift.padding` is a viewport inset in px, not a layout spacing token.
  */
-const MENU_MIDDLEWARES = { flip: false, shift: { padding: 8 } } // theme-allow
+const MENU_MIDDLEWARES = { flip: false, shift: { padding: 8 } } // theme-allow inline-spacing — a floating-ui viewport inset, not layout spacing
 
 /** A slot that navigates on tap. */
 type LinkSlot = Extract<MobileNavSlot, { kind: 'link' }>

package/src/surfaces.ts

@@ -467,7 +467,7 @@ export const SURFACES = {
     kind: 'tooling',
     layer: 'non-js-asset',
     description:
-      'Prebuilt --vx-* token stylesheet — the default buildPaletteCss() output as a plain file, for a consumer with no bundler, no React and no Mantine; retune the selector or trim the spacing set with `basalt-ui tokens:css`',
+      'Prebuilt --vx-* token stylesheet — the default buildPaletteCss() output as a plain file, for a consumer that has a bundler to resolve the subpath but no React and no Mantine; with no bundler, emit a file you own via `basalt-ui tokens:css`',
     forbiddenImports: [],
   },
   './configs/*': {

package/src/theme/density-relations.test.ts

@@ -266,17 +266,20 @@ describe("Fix 7 — the knob's resolution is honest at every notch", () => {
     expect(minRatio).toBeLessThan(0.7)
   })
 
-  test('frozen-vs-baseline ceiling: fewer than 25 of the ~108 values equal their level-0 value at any non-zero level', () => {
-    // Measured under the 0.1/±3 law: worst case is 22 (at level ±1) — down from 43 under the old
-    // 0.06/±5 law. The ceiling of 25 leaves margin while still catching a future step reduction
-    // that reintroduces that dead zone.
+  test('frozen-vs-baseline ceiling: fewer than 27 of the ~129 values equal their level-0 value at any non-zero level', () => {
+    // Measured under the 0.1/±3 law: worst case is 25 (at level −1) — down from 43 under the old
+    // 0.06/±5 law. It is 25 rather than 24 because `mobileNavTabInsetY` (base 2) joined the set:
+    // a base that small rounds back to itself at ±1 and ±2 under any multiplier this law can
+    // produce, exactly as `mobileNavTabGap` (base 3) already did. That is the rounding law, not a
+    // resolution regression — the ceiling of 27 keeps the same margin over the measured worst case
+    // while still catching a future step reduction that reintroduces the real dead zone.
     const baseline = flattenSpacing(0)
     const keys = Object.keys(baseline)
     for (const level of ALL_LEVELS) {
       if (level === 0) continue
       const values = flattenSpacing(level)
       const frozen = keys.filter((k) => values[k] === baseline[k]).length
-      expect(frozen).toBeLessThan(25)
+      expect(frozen).toBeLessThan(27)
     }
   })
 

package/src/theme/spacing.test.ts

@@ -357,6 +357,8 @@ const SPACE_STEP_SWEEP: ReadonlyArray<
   // `app-mobile-nav.tsx` hands `mobileNavMenuWidth` to `<Menu width={…}>`.
   ['mobileNavBarHeight', 56, null],
   ['mobileNavIconSize', 24, 'space-mobile-nav-icon-size'],
+  ['mobileNavTabInsetY', 2, 'space-mobile-nav-tab-inset-y'],
+  ['mobileNavTabInsetX', 12, 'space-mobile-nav-tab-inset-x'],
   ['mobileNavRowHeight', 44, 'space-mobile-nav-row-height'],
   ['mobileNavMenuWidth', 232, null],
   ['agentRailInsetX', 10, 'space-agent-rail-inset-x'],

package/src/theme-toggle/index.tsx

@@ -84,7 +84,7 @@ function SchemeGlyph({ dark, reduceMotion }: { dark: boolean; reduceMotion: bool
       {dark ? (
         <motion.span
           key="moon"
-          style={{ display: 'inline-flex' }} // theme-allow: framer-motion element — inline-flex glyph wrapper, not a Mantine node
+          style={{ display: 'inline-flex' }} // theme-allow inline-display — a framer-motion glyph wrapper, not a Mantine layout node
           initial={{ opacity: 0, scale: 0.6, rotate: 30 }}
           animate={{ opacity: 1, scale: 1, rotate: 0 }}
           exit={{ opacity: 0, scale: 0.6, rotate: -30 }}
@@ -95,7 +95,7 @@ function SchemeGlyph({ dark, reduceMotion }: { dark: boolean; reduceMotion: bool
       ) : (
         <motion.span
           key="sun"
-          style={{ display: 'inline-flex' }} // theme-allow: framer-motion element — inline-flex glyph wrapper, not a Mantine node
+          style={{ display: 'inline-flex' }} // theme-allow inline-display — a framer-motion glyph wrapper, not a Mantine layout node
           initial={{ opacity: 0, scale: 0.6, rotate: -30 }}
           animate={{ opacity: 1, scale: 1, rotate: 0 }}
           exit={{ opacity: 0, scale: 0.6, rotate: 30 }}

package/src/tokens/index.ts

@@ -533,6 +533,8 @@ function spaceDecls(space: SpaceValues): string[] {
     decl('space-app-header-mobile-actions-height', `${space.step.appHeaderMobileActionsHeight}px`),
     decl('space-mobile-nav-tab-gap', `${space.step.mobileNavTabGap}px`),
     decl('space-mobile-nav-icon-size', `${space.step.mobileNavIconSize}px`),
+    decl('space-mobile-nav-tab-inset-y', `${space.step.mobileNavTabInsetY}px`),
+    decl('space-mobile-nav-tab-inset-x', `${space.step.mobileNavTabInsetX}px`),
     decl('space-mobile-nav-row-height', `${space.step.mobileNavRowHeight}px`),
     decl('space-agent-rail-inset-x', `${space.step.agentRailInsetX}px`),
     decl('space-agent-part-gap-top', `${space.step.agentPartGapTop}px`),
@@ -758,13 +760,13 @@ export type BuildPaletteOpts = {
    */
   mediaFallback?: boolean
   /**
-   * How much of the SPACING set to emit. Default: `'all'` (every one of the 104 `--vx-space-*`
+   * How much of the SPACING set to emit. Default: `'all'` (every one of the 108 `--vx-space-*`
    * declarations the framework's own components read).
    *
    * `'core'` keeps the 9 generic anchors — the stack rhythm, the two control heights, the row
-   * insets — and drops the 95 named for a specific basalt component
+   * insets — and drops the 99 named for a specific basalt component
    * (`--vx-space-agent-transcript-inset`, `--vx-space-toc-sub-indent`, …), taking the emitted set
-   * from 197 variables to 102. Nothing outside basalt's own React components reads those, so a
+   * from 202 variables to 103. Nothing outside basalt's own React components reads those, so a
    * framework-free consumer is carrying them for nothing.
    *
    * This is a SPACING filter only: color, radius, shadow, type and status variables are identical

package/src/tokens/palette.ts

@@ -97,12 +97,12 @@ export const p = (fam: readonly string[], light = 2, dark = 3): ColorPair => ({
  */
 export const SHADOW = {
   card: {
-    light: '0 1px 2px rgba(28,25,23,0.05), 0 0 0 1px var(--vx-surface-hairline)',
-    dark: '0 1px 3px rgba(0,0,0,0.4), inset 0 0 0 1px color-mix(in srgb, #ffffff 4%, transparent)',
+    light: '0 1px 2px rgba(28, 25, 23, 0.05), 0 0 0 1px var(--vx-surface-hairline)',
+    dark: '0 1px 3px rgba(0, 0, 0, 0.4), inset 0 0 0 1px color-mix(in srgb, #ffffff 4%, transparent)',
   },
   ctrl: {
-    light: '0 1px 2px rgba(28,25,23,0.12)',
-    dark: '0 1px 2px rgba(0,0,0,0.35)',
+    light: '0 1px 2px rgba(28, 25, 23, 0.12)',
+    dark: '0 1px 2px rgba(0, 0, 0, 0.35)',
   },
   /**
    * Interactive-control depth — the ONE value every raised Button/ActionIcon/Input variant shares
@@ -132,16 +132,16 @@ export const SHADOW = {
    * ever needs more, raise the DROP. Do not reintroduce an edge; both shapes have been tried.
    */
   raised: {
-    light: '0 1px 2px rgba(28,25,23,0.10)',
-    dark: '0 1px 2px rgba(0,0,0,0.35), inset 0 0 0 1px color-mix(in srgb, #ffffff 8%, transparent)',
+    light: '0 1px 2px rgba(28, 25, 23, 0.10)',
+    dark: '0 1px 2px rgba(0, 0, 0, 0.35), inset 0 0 0 1px color-mix(in srgb, #ffffff 8%, transparent)',
   },
   // Floating-layer elevation (menus, popovers, tooltips, modals, drawers) — a REAL drop shadow, a
   // step above `card`, so detached surfaces read as lifted off the page (`docs/DESIGN-SPEC.md` §5).
   // Unlike `card`, no embedded ring: floating surfaces carry a real 1px `--vx-surface-border` so
   // Mantine's rotated-square arrow inherits a proper edge.
   overlay: {
-    light: '0 8px 24px rgba(28,25,23,0.10)',
-    dark: '0 8px 24px rgba(0,0,0,0.5)',
+    light: '0 8px 24px rgba(28, 25, 23, 0.10)',
+    dark: '0 8px 24px rgba(0, 0, 0, 0.5)',
   },
 } as const
 
@@ -613,8 +613,14 @@ const SPACE_STEP_BASE = {
    *  `env(safe-area-inset-bottom)` to it. JS-consumed (AppShell `footer.height`), no `--vx-*` var,
    *  same shape as `appShellHeaderHeight`. Floored at 48px in `deriveSpacing`. */
   mobileNavBarHeight: 56,
-  /** Slot icon box. */
+  /** Slot icon box. Also the MIN box of the icon slot itself, so the active pill keeps its shape
+   *  when a destination ships no icon (an icon-less consumer is a supported configuration). */
   mobileNavIconSize: 24,
+  /** Active-pill inset around the slot icon, vertical. Sub-scale on its own, but it is one half of
+   *  a pair with `mobileNavTabInsetX` — a step keeps the pill's shape tracking density. */
+  mobileNavTabInsetY: 2,
+  /** Active-pill inset around the slot icon, horizontal. */
+  mobileNavTabInsetX: 12,
   /** Menu/sheet row height. Floored at 44px in `deriveSpacing` (Apple HIG 44pt / WCAG 2.5.5 AAA). */
   mobileNavRowHeight: 44,
   /** More/group `<Menu width={…}>`. JS-consumed, no var — same rationale as
@@ -1059,22 +1065,22 @@ function buildPaletteDataUncached(config: DeriveConfig) {
   const NEUTRAL = {
     line: { light: BP.gray[0], dark: BP.gray[4] }, // primary line
     line2: { light: BP.gray[1], dark: BP.gray[2] }, // secondary line
-    axis: { light: inkRgba(inkLight, 0.6), dark: 'rgba(255,255,255,0.6)' },
-    axisStroke: { light: inkRgba(inkLight, 0.12), dark: 'rgba(255,255,255,0.12)' },
-    grid: { light: inkRgba(inkLight, 0.07), dark: 'rgba(255,255,255,0.06)' },
-    crosshair: { light: inkRgba(inkLight, 0.32), dark: 'rgba(255,255,255,0.42)' },
+    axis: { light: inkRgba(inkLight, 0.6), dark: 'rgba(255, 255, 255, 0.6)' },
+    axisStroke: { light: inkRgba(inkLight, 0.12), dark: 'rgba(255, 255, 255, 0.12)' },
+    grid: { light: inkRgba(inkLight, 0.07), dark: 'rgba(255, 255, 255, 0.06)' },
+    crosshair: { light: inkRgba(inkLight, 0.32), dark: 'rgba(255, 255, 255, 0.42)' },
     dotStroke: { light: BP.white, dark: BP.darkGray[1] }, // matches chart-area bg
-    tooltipBg: { light: BP.white, dark: 'rgba(39,39,42,0.96)' },
-    tooltipText: { light: inkRgba(inkLight, 0.88), dark: 'rgba(255,255,255,0.88)' },
-    tooltipMuted: { light: inkRgba(inkLight, 0.5), dark: 'rgba(255,255,255,0.5)' },
+    tooltipBg: { light: BP.white, dark: 'rgba(39, 39, 42, 0.96)' },
+    tooltipText: { light: inkRgba(inkLight, 0.88), dark: 'rgba(255, 255, 255, 0.88)' },
+    tooltipMuted: { light: inkRgba(inkLight, 0.5), dark: 'rgba(255, 255, 255, 0.5)' },
     tooltipBorder: { light: `1px solid ${BP.lightGray[1]}`, dark: 'none' },
     tooltipShadow: {
       light: `0 2px 8px ${inkRgba(inkLight, 0.1)}`,
-      dark: '0 2px 8px rgba(0,0,0,0.35)',
+      dark: '0 2px 8px rgba(0, 0, 0, 0.35)',
     },
     // Chart legend text — same DERIVED-ink treatment as axis/grid/tooltip* above (light keys off
     // `inkLight`; dark stays flat white like every other neutral chart-chrome pair here).
-    legendText: { light: inkRgba(inkLight, 0.82), dark: 'rgba(255,255,255,0.92)' },
+    legendText: { light: inkRgba(inkLight, 0.82), dark: 'rgba(255, 255, 255, 0.92)' },
     // Base neutral for hairlines / muted / DIMMED text / overlays — apply opacity via alpha().
     // Binds to --mantine-color-dimmed, so it is THE dimmed-text lever. Equal to `INK.muted` (the
     // spec's "muted (secondary text)" row) — kept as its own pair for the pre-existing `--vx-neutral`

package/src/vite-color-mix.ts

@@ -28,8 +28,8 @@
  * what a color parser must never do.
  */
 const NAMED_COLORS: Record<string, string> = {
-  white: '#ffffff', // theme-allow — CSS keyword definition, not a design color
-  black: '#000000', // theme-allow — CSS keyword definition, not a design color
+  white: '#ffffff', // theme-allow raw-hex — the CSS keyword's definition, not a design color
+  black: '#000000', // theme-allow raw-hex — the CSS keyword's definition, not a design color
 }
 
 function normalizeHex(hex: string): string {