basalt-ui 1.41.0 → 2.0.0

package/agent/rules/basalt-state.md

@@ -1,6 +1,6 @@
 ---
 source: basalt-ui
-description: Where each kind of state lives in a basalt-ui app — createSearchStore over typed fields (URL > localStorage > fallback), the lanes, FieldHandle, linkSearch by reference, defineNav/useNav, createPersistedState. Partly enforced by basalt/search-literal-link, basalt/use-search-from-literal and the localstorage-theme guard kind.
+description: Where state lives — search stores over typed fields, nav links by reference, defineNav, persisted state.
 paths:
   - 'src/**'
   - 'apps/**/src/**'
@@ -12,110 +12,28 @@ paths:
 <!-- not guarded: — -->
 <!-- /basalt:coverage -->
 
-# Basalt State — stores, lanes, nav
+# Basalt State
 
-A store is defined wherever the feature lives (`src/lib/`, `src/features/…`), not only under
-`src/routes/**` — which is why this rule loads across the whole source tree.
+State a control reads or writes is a field on a store; the URL wins over localStorage over the fallback.
 
-## Where state goes
+## Stores
 
-| Kind                                                                | Home                                                                     |
-| ------------------------------------------------------------------- | ------------------------------------------------------------------------ |
-| server data                                                         | TanStack Query (basalt-batteries.md)                                     |
-| anything a control reads or writes — filter, tab, range, pagination | a **field** on `createSearchStore` / `createLocalStore`                  |
-| color scheme                                                        | `useMantineColorScheme()` — never a store, never `localStorage['theme']` |
-| a preference that must survive navigation but is not URL-worthy     | `createPersistedState` (`basalt-ui/state`)                               |
-| network status                                                      | `useConnectivity()` — auto-mounted by `BasaltProvider`                   |
+- Define filters, tabs, ranges and pagination as fields of `createSearchStore` (URL) or `createLocalStore` (no router), with `field.range|multi|enum|boolean`. [type createSearchStore]
+- Never `useState` for a filter, tab, range or view; a basalt control takes a `field` and has no `value` or `onChange`. [check-theme raw-selection-control]
+- Declare lanes once at definition: `{ url, persist, history }`; `url: false` is local-only, `persist: false` is URL-only. [type field]
+- Option labels come from `.labels()` at definition, never a control prop. [type createSearchStore]
+- Route `validateSearch` is `store.validateSearch`; a wider search shape spreads `...store.validateSearch(raw)`. [type createSearchStore]
+- Read with `store.useValues()` or take the value as a prop; never `useSearch({ from: '<literal>' })`. [basalt/use-search-from-literal]
+- A handle's `use()` returns `[value, setValue]`; the setter owns the navigate and the persist. [type field]
+- Count active filters and reset them with the store's `useActiveCount()` and `useReset()`; a reset unsets, it does not write the fallback. [type createSearchStore]
+- A color scheme is `useMantineColorScheme()`, never a store or `localStorage['theme']`. [check-theme localstorage-theme]
+- A preference that must survive navigation but is not URL-worthy uses `createPersistedState`, called once at module scope. [type createPersistedState]
 
-**Never `useState` for a filter, a tab, a range or a view** (law C3). It resets on navigation, it
-cannot be linked, and it is the state a basalt control refuses to take (`value`/`onChange` do not
-exist on one). Reach for a third-party store only for genuinely shared mutable state with no owning
-component; basalt ships and depends on none.
+## Nav
 
-## `createSearchStore` — one factory over typed fields
-
-```ts
-import { createSearchStore, field } from 'basalt-ui/router-tanstack'
-
-export const analytics = createSearchStore({
-  key: 'analytics',
-  fields: {
-    range: field.range({ presets: ['7d', '30d', '90d'], fallback: '30d', custom: true }),
-    channels: field.multi(CHANNELS, []),
-    tab: field.enum(['overview', 'detail'], 'overview', { persist: false }),
-    compact: field.boolean(false, { url: false }),
-  },
-}).labels({ range: { '7d': 'Last 7 days', '30d': 'Last 30 days', '90d': 'Last 90 days' } })
-```
-
-- **The URL is the truth; the localStorage mirror is a fallback UNDER it.** Every field resolves
-  URL ⊳ localStorage ⊳ fallback, identically for every field kind (law C4) — a deep link wins over
-  the mirror.
-- **Lanes are declared once, at definition**: `{ url, persist, history }`. `url: false` is
-  local-only (a per-card select); `persist: false` is URL-only (pagination, a tab that shouldn't
-  follow you elsewhere). `createLocalStore` is the same field vocabulary with no router.
-- **Option LABELS come from `.labels()`, once, at definition** — never a per-control prop.
-- **`validateSearch: store.validateSearch`** on the route, function form — it returns every
-  URL-lane param unconditionally. A route with a wider search shape COMPOSES the store instead
-  (`{ ...store.validateSearch(raw), ...rest }`) — there is no schema-backed store variant.
-- **A write from outside the owning route persists only**; `validateSearch` picks it up next visit.
-- **`field.range` keeps its three URL params** (preset + from/to); `handle.toWindow(value)` is the
-  projection into query params — never a hand-written `presetToParams`.
-
-## Reading and writing
-
-- **A page reads `store.useValues()`, or takes the value as a PROP.** Never
-  `useSearch({ from: '<literal>' })` (`basalt/use-search-from-literal`) — a sibling/child route
-  fails that `from`. Basalt controls read through `FieldHandle`, which uses the non-strict search
-  internally.
-- **A `FieldHandle` is the whole read/write surface**: `use()` returns `[value, setValue]` and the
-  setter owns the navigate AND the persist — a control never receives `value`/`onChange` (law C2).
-  Hand-writing a navigate (a route with its own search shape) uses the reducer form,
-  `navigate({ search: (prev) => ({ ...prev, … }) })`, so unrelated params survive.
-- **`useActiveCount()`/`useReset()`** back a `Filters (n)` pill and its `Reset all` — never
-  hand-count either.
-- **A reset UNSETS.** `useReset()`/`field.clear()` DELETE the persisted key, never write
-  `fallback` (which would pin a thunk fallback as a value nobody chose).
-- **`set(next, { patch })`** merges params the store does NOT own into the same navigate; store-level
-  `resets: ['page']` does it on every URL-lane write (never a `useEffect`: it snaps Back/Forward).
-
-## Nav links carry the store BY REFERENCE
-
-```ts
-link: linkOptions({ to: '/dashboard', search: analytics.linkSearch })
-```
-
-**Pass the function, never call it, never inline an object.** It is a click-time thunk, so arriving
-from anywhere restores the last selection; a module-scope literal (`search: { range: '30d' }`)
-pins the fallback on every click — `basalt/search-literal-link` catches it. `search: true` is a
-type error against a store-backed route.
-
-## The typed nav definition
-
-The whole navigation — desktop sidebar and mobile bar — is declared ONCE with `defineNav` /
-`navGroup` in a **leaf** module (`src/lib/nav.tsx`) that never imports `routeTree.gen` or
-`__root.tsx`, so palettes and redirects can import it without closing a cycle. `useNav(NAV)` resolves
-it against the live router and returns `{ sections, mobileNav }` — both `BasaltShell` props, so
-spread it. `navTarget(NAV, id)` is one destination's link options, typed per id, for a `<Link>`, a
-`navigate()` or a `redirect()`. `flattenNav` is the leaf every other surface reads (e.g. projecting
-the nav into Spotlight in one `.map()`).
-
-- **Route options live under `link:`, wrapped in TanStack's own `linkOptions`** — never spread flat
-  onto the item (a flat shape validates `to` by assignability, no excess-property checking, so a
-  typo'd metadata key compiles silently). `id`/`label`/`short`/`icon`/`mobile`/`disabled`/`exact`
-  ride outside `link`.
-- **Nesting is `children`**; `mobile` places the destination on the bar (basalt-mantine.md).
-- **Without the `Register` module augmentation, `defineNav` validates NOTHING and reports zero
-  errors** — `RegisteredRouter` falls back to `AnyRouter`, every `to` widens to `string`. Verify
-  once by changing a `to` to garbage and confirming the compile error. **Never reach for
-  `as never`** to quiet one — the checking is the entire point.
-- `staticData` (`title`/`icon`/`navSection`) drives `useRouterBreadcrumbs` and needs the generated
-  route tree.
-
-## `createPersistedState` — the localStorage primitive
-
-Call it once at module scope; use the returned hook anywhere, no provider. SSR-safe, cross-tab via
-the `storage` event, versioned (bump `version` on a shape change, stale values fall back to
-`initial`). Keys are namespaced `basalt:<key>` automatically; `readPersistedValue(key, v)` is the
-non-React read. Every basalt module that persists — shell collapse, `Section` fold, a sidebar
-block, a form draft, notification history — goes through this one primitive.
+- Declare the whole navigation once with `defineNav` and `navGroup`. [type defineNav]
+- Pass it as `<BasaltShell nav={NAV} />`; use `navTarget(NAV, id)` for a `<Link>`, `navigate()` or `redirect()`. [type navTarget]
+- Route options sit under `link: linkOptions({ ... })`, never flat on the item. [type defineNav]
+- Link a store-backed route with `search: store.linkSearch`, by reference; never call it or inline `{ range: '30d' }`. [basalt/search-literal-link]
+- Declare `interface Register { router: typeof router }` in `main.tsx`, or `to` is not checked; never silence a nav type error with `as never`. [type defineNav]
+- Turn nav into other surfaces (Spotlight) with `flattenNav`. [type flattenNav]

package/agent/rules/basalt-tokens.md

@@ -1,6 +1,6 @@
 ---
 source: basalt-ui
-description: Color, spacing, radius and type discipline — route every value through the basalt-ui token system. Enforced by `basalt-ui check-theme` plus the oxlint type-scale rules.
+description: Color, spacing, radius and type — route every value through the --vx-* token system.
 paths:
   - 'src/**'
   - 'apps/**/src/**'
@@ -9,131 +9,50 @@ paths:
 
 <!-- basalt:coverage -->
 <!-- GENERATED from src/surfaces.ts — `bun scripts/check-coverage.ts --write`. Do not hand-edit. -->
-<!-- backed by: guard kinds — css-raw-surface, inline-font-size, off-identity-accent, off-system-surface-var, raw-color-fn, raw-font-family, raw-hex, raw-radius, raw-surface, surface-shadow-override, theme-allow-unscoped, unknown-vx-token · oxlint rules — basalt/no-raw-font-size, basalt/raw-size-literal, basalt/token-layer-boundary -->
+<!-- backed by: guard kinds — css-raw-surface, inline-font-size, off-identity-accent, off-system-surface-var, raw-color-fn, raw-font-family, raw-hex, raw-radius, raw-surface, surface-shadow-override, theme-allow-unscoped, unknown-vx-token · oxlint rules — basalt/no-raw-font-size, basalt/raw-size-literal -->
 <!-- not guarded: — -->
 <!-- /basalt:coverage -->
 
-# Basalt Tokens — color, spacing, radius, type
+# Basalt Tokens
 
-## The identity (stated once, here)
+Every value is a `VX.*` reference or a theme prop; the palette is derived, never authored.
 
-basalt-ui ships ONE identity shared by the Mantine chrome and the visx charts: **cool-neutral zinc
-surfaces on both schemes**, a page slightly darker than its panels, depth from a whisper shadow with
-a 1px ring baked in rather than a hairline border, and **one saturated sky-blue accent** that only
-points. Neutrals carry ~90% of the surface.
+## Color
 
-The accent is **split by ROLE**, and this is the one thing an author gets wrong:
+- Write no `#hex`, `rgb()` or `hsl()`; use `VX.*` (`basalt-ui/tokens`) or Mantine `c`/`bg`. [check-theme raw-hex] [check-theme raw-color-fn]
+- Opacity is `alpha(token, a)`, never `rgba()`. [check-theme raw-color-fn]
+- Mantine hues are `blue`, `gray`, `red`, `green`, `orange`, `yellow` only; a positive delta is `green`, not `teal`. [check-theme off-identity-accent]
+- Never pin a shade (`c="yellow.7"`, `var(--mantine-color-red-6)`); use `VX.status.*` or the bare hue. [check-theme mantine-shade-index]
+- Never read a raw ramp var (`--mantine-color-gray-N`); use `VX.surface.*`. [check-theme off-system-surface-var]
+- Fill a control with `VX.accentFill` labelled `VX.onAccent`, never `VX.accent` (that is ink). [type VX]
+- Name only `--vx-*` vars that basalt emits. [check-theme unknown-vx-token]
+- Series color is app data: `defineSeries` → `seriesTokens`/`groupTokens`, each entry a `{ light, dark }` pair, in one file that `check-theme` exempts. [type defineSeries]
+- `groupTokens` returns the group to pass to `buildPaletteCss` or `BasaltProvider` `paletteOptions`; never retype its key. [type groupTokens]
 
-- **As ink** — links, active-nav icon, chart lines, focus ring — it is read against the page, so it
-  inverts across schemes. `VX.accent`.
-- **As a filled surface** — a control carrying a white label — it cannot invert: it is squeezed
-  between the label's contrast and the page's, which leaves one narrow luminance band. `VX.accentFill`,
-  labelled with `VX.onAccent`. Every Mantine family's fill sits in that same band, so a filled
-  control always reads white on either page. **Never fill with `VX.accent`.**
+## Surfaces, radius, depth
 
-**The palette is DERIVED, not authored** (`tokens/derive.ts` from one seed + five bounded knobs), and
-a consumer retunes it through `createBasaltTheme(overrides?, { derive, fonts, radius, density })` —
-no hex, shade index or pixel constant belongs in a rule, doc or component. Read values off `VX.*`
-and the theme; read raw numbers, if you need them, off `tokens/palette.ts`.
-
-## Color — never a raw literal
-
-- **No raw `#hex` / `rgb()` / `rgba()` / `hsl()` in scanned source.** Route color through `VX.*`
-  (from `basalt-ui/tokens` or `basalt-ui/charts` — they are CSS vars, so they work in components AND
-  in non-component files) or through the Mantine theme (`color` / `c` / `bg`, `theme.colors`).
-- **Opacity is `alpha(token, a)`** (`color-mix`), never `rgba()` — so the hue keeps resolving per
-  scheme.
-- **No off-identity Mantine accents** — allowed: **`blue`** (the earned hue), **`gray`**, and the
-  status names `red`/`green`/`orange`/`yellow`. A positive delta is `color="green"`, never `teal`.
-- **Never pin a shade index** (`c="yellow.7"`, `var(--mantine-color-red-6)`) — one fixed swatch is
-  identical in both schemes, so what's legible on dark fails on light. Use `VX.status.*` or the
-  bare hue name.
-- **"Ink earns its color."** Default to neutral. A hue is justified by trend, signal/status, or
-  genuine multi-series separation. The accent lands on the single primary CTA per view, focus rings,
-  links and small status pops — never on borders, large fills, routine icons or secondary buttons.
-- **Categorical/series color is consumer data**, declared once through `defineSeries` →
-  `seriesTokens`/`groupTokens` and wired into `buildPaletteCss`, never a Mantine accent prop.
-  `groupTokens(GROUP, MAP)` assumes the map reaches `BasaltProvider`'s `paletteOptions.groups`
-  under the key `` `${GROUP}-` `` — **with the trailing dash**. Derive both from one `GROUP`
-  constant; a mismatch emits refs to variables the stylesheet never declares, silently.
-
-## Surfaces — one collapsed token set
-
-`VX.surface` is exactly: `bg` · `panel` · `panelHover` · `elevated` · `subtle` · `overlay` ·
-`field` · `border` · `hairline`. `VX.divider` is NOT a surface — the one seam/line token (every
-`AppShell` region edge + between-rows rule); `hairline` is the card ring, `border` the
-control/overlay line — neither is ever a seam.
-
-The theme **collapses Mantine's raw ramp steps onto those tokens** (`cssVariablesResolver` + theme
-`styles`), so every Mantine component — AppShell, Table, Input, Divider, Tabs, Popover, Accordion,
-Card — renders one border shade, one card background and one radius. Never inline a surface color
-and never reach for a raw ramp-step var (`var(--mantine-color-gray-N)`).
-
-## Spacing & radius — prefer the scale token
-
-- `baseTheme` owns both scales and both are DERIVED (`deriveSpacing(level)` / `deriveRadius(level)`
-  move them with the `density` / `radius` knobs). **Use the token, not the number**: `p="md"`, not
-  the integer that happens to equal `md` today; `radius="sm"`, never a numeric radius.
-- **Card radius has one source**, `VX.radiusCard` / `--vx-radius-card`: the Mantine chrome and the
-  Mantine-free `ChartCard` resolve to the same token. Cards must never diverge.
-- **Sub-scale micro-spacing is legitimate and allowed raw** — below the scale's first step, use the
-  raw number rather than inventing a micro-token. A CSS-module declaration whose every literal is
-  micro does not fire; one non-micro value makes it a finding, and an inline style OBJECT in TSX
-  still fires (there the Mantine prop existed).
-- **Dense by default** — reach for the tighter step. Icons size through their own `size` prop,
-  which is not spacing.
+- Surfaces are `VX.surface.{bg,panel,panelHover,elevated,subtle,overlay,field,border,hairline}`; the seam between shell regions is `VX.divider`. [type VX]
+- Never set border, radius or shadow on a card; the theme owns them (`VX.shadowCard`, `VX.radiusCard`). [check-theme raw-surface]
+- Never replace a surface's shadow with your own `boxShadow`; compose with the depth token. [check-theme surface-shadow-override]
+- In CSS, corners and depth are `var(--vx-radius-card)` (cards) or `var(--vx-radius-ctrl)` (controls) and `var(--vx-shadow-card)`. [check-theme css-raw-surface]
+- Radius is a token (`radius="md"`), never a number. [check-theme raw-radius]
+- Never build a component named like a basalt export (`StatCard`, `Section`); import it. [basalt/shadow-basalt-export]
 
 ## Type
 
-Three fonts: sans (body), a condensed head font (headings, brand, card titles), mono (every numeral,
-micro-label, kbd, axis tick). They ship as exact-pinned `@fontsource-variable/*` peers imported by
-`basalt-ui/styles.css`; `createBasaltTheme(_, { fonts })` is the ONE override seam, writing the
-`--basalt-font-*` vars. Size and weight come from the theme's `fontSizes` / `headings` / named
-`fontWeights` ladder (`fw="semibold"`) — never a hardcoded `fontSize`, and never a CSS-length string
-on `size`/`fz`.
-
-## `theme-allow` — the escape hatch and its grammar (stated once, here)
-
-```text
-theme-allow                                  → this node/line, EVERY rule   (reports theme-allow-unscoped)
-theme-allow <id>[, <id>…] [— <why>]          → this node/line, those rules  (unscoped without a why)
-theme-allow-file <id>[, <id>…] — <why>       → the WHOLE FILE, those rules; a bare one waives NOTHING
-"basalt:theme-allow[-file]": "<id>… — <why>" → the same two, for JSON / .webmanifest
-```
-
-An id is a guard kind (`raw-surface`, `inline-spacing`, …) or an oxlint plugin rule
-(`hand-rolled-plot`, `hand-rolled-filter`, …), with or without the `basalt/` prefix.
-
-```tsx
-// theme-allow raw-surface — third-party widget needs a literal corner
-<Widget style={{ borderRadius: 3 }} />
-```
-
-- **An annotation must START its comment** (`//`, `/*`, `<!--`, a `*` gutter, or bare whitespace) —
-  a mention mid-prose waives nothing.
-- **File scope is spelled, never inferred**: `theme-allow-file <id>… — <why>`, anywhere in the
-  file; a bare one waives nothing.
-- **A typo waives nothing** — an unrecognized id is recorded unknown, the rest of the annotation
-  still covers the ids it got right.
-- **Three placements agree in both engines**: the reported line, a comment-only line directly
-  above it, and (CSS) a trailing annotation reaching back over the declaration it terminates. A
-  blank line ends the reach.
-- **JSON/`.webmanifest` take a member key** — first remedy is `basaltAppPlugin`, not a waiver.
-- **The three import-boundary rules honour no escape at all**; the agent-chat guards honour
-  `basalt-agent-allow`, a separate token that never waives a `theme-allow` finding, or the reverse.
+- Font size is `VX.text.*`, `--vx-text-*` or Mantine `fz`; never a literal. [check-theme inline-font-size] [basalt/no-raw-font-size]
+- Size props take theme tokens, never a CSS length string. [basalt/raw-size-literal]
+- Fonts change only through `createBasaltTheme(_, { fonts })`; never write `fontFamily`. [check-theme raw-font-family]
 
-**Audit them**: `basalt-ui check-theme --audit-allows` re-runs the scan with each waiver
-neutralized and **exits 1 on a waiver that suppresses nothing**; it judges plugin-rule waivers too
-by re-running oxlint. Scope is part of the report — `0 dead` is not `0 dead anywhere`.
+## Theme config
 
-## Wiring the guard
+- Retune the identity with `createBasaltTheme(overrides?, { derive, fonts, radius, density })`; `radius` is -5..5 and `density` is -3..3. [type createBasaltTheme]
 
-`check-theme` reads `package.json`'s `"basalt"` key (`roots`, `exempt`, `include`, `profile`,
-`severity`, `exemptRules`). **`roots` is not optional in practice** — omitted, it falls back to
-`src` relative to cwd (zero files under `apps/*/src`); `init` writes a real one. Wire it as
-`oxlint . && basalt-ui check-theme` — what `init` seeds as `lint:basalt`.
+## Escape hatch
 
-**When it fires, fix the source** — the right token first; a palette-definition file belongs in
-`exempt`, not behind a comment. **The guard sees palette, not vocabulary** — a token-fluent fork
-uses exactly the right tokens, so `basalt/shadow-basalt-export` (an exact name collision) is a
-tripwire, not coverage. Check whether basalt already ships the thing before building it.
+- `theme-allow <id>[, <id>…] — <why>` waives those rules on its line; bare `theme-allow` or a missing why is itself a finding. [check-theme theme-allow-unscoped]
+- An `<id>` is a guard kind or an oxlint plugin rule, with or without the `basalt/` prefix; an unknown id waives nothing. [check-theme theme-allow-unscoped]
+- The annotation must start its comment and sits on the line, on a comment-only line directly above it, or (CSS) trailing the declaration; a blank line ends the reach. [check-theme theme-allow-unscoped]
+- `theme-allow-file <id> — <why>` waives a whole file; a bare one waives nothing. [check-theme theme-allow-unscoped]
+- JSON and `.webmanifest` take the member form `"basalt:theme-allow": "<id> — <why>"` (`"basalt:theme-allow-file"` for the file). [check-theme theme-allow-unscoped]
+- `basalt-ui check-theme --audit-allows` exits 1 on a waiver that suppresses nothing. [check-theme theme-allow-unscoped]