basalt-ui 1.32.1 → 1.33.0

package/src/router-tanstack/search-store.ts

@@ -43,6 +43,24 @@ export type CreateSearchStoreOptions<S extends Record<string, AnyField>> = {
   fields: S
   /** Envelope version — bump when the field set changes to discard stale localStorage. */
   version?: number
+  /**
+   * Search params this store does NOT own that a URL-lane write drops, in the SAME navigate —
+   * `['page']` on a paginated list, so narrowing the set on page 5 lands on page 1 and Back restores
+   * both together. Dropped, not written: the route's own `validateSearch` resolves the default
+   * (`page` → 1), so the store never has to know it. Applies to a URL-lane field's setter and
+   * `clear()` when the value moves, and to `useReset()` when any field moves; an explicit `patch`
+   * naming the same key wins.
+   *
+   * **URL-lane writes only.** A `url: false` field (mirror-only or memory) makes no navigate, so it
+   * has none to ride — and a `useReset()` on a store with no URL-lane field keeps the page too.
+   *
+   * Store-wide by design: every filter of a list narrows the same list. A param the store owns is
+   * refused at definition — reset a field with `useReset()` or its own `clear()`.
+   *
+   * @example
+   * createSearchStore({ key: 'shares', fields: { q: field.string({}), sort: … }, resets: ['page'] })
+   */
+  resets?: readonly string[]
 }
 
 export type SearchStore<S extends Record<string, AnyField>> = {
@@ -205,6 +223,28 @@ function assertNoLazyUrlFallback(key: string, fields: Record<string, AnyField>):
   }
 }
 
+/**
+ * `resets` exists for keys the store does NOT own; one it owns would be dropped from the URL while
+ * the mirror kept its value — the same URL/mirror split `patch` refuses. Static, so thrown at
+ * definition.
+ */
+function assertResetsNotOwned(input: {
+  key: string
+  resets: readonly string[]
+  paramOwners: ReadonlyMap<string, string>
+}): void {
+  const { key, resets, paramOwners } = input
+  for (const param of resets) {
+    const owner = paramOwners.get(param)
+    if (owner === undefined) continue
+    throw new Error(
+      `basalt-ui: createSearchStore('${key}'): \`resets\` names \`${param}\`, which this store's ` +
+        `field '${owner}' owns. \`resets\` is for sibling params the store does not own (a ` +
+        '`page`); a field of the store is reset through `useReset()` or its own `clear()`.',
+    )
+  }
+}
+
 /** The memory-only lane: neither the URL nor the mirror, so the value lives in the store's own
  * session-scoped external store (`StoreCore.memoryUse`) — the lane `createLocalStore` also uses. */
 function isMemoryLane(entry: StoreEntry): boolean {
@@ -240,6 +280,25 @@ export function buildSearchStore<const S extends Record<string, AnyField>>(
   for (const entry of core.urlEntries) {
     for (const param of entry.codec.params) paramOwners.set(param, entry.name)
   }
+  const resets = o.resets ?? []
+  assertResetsNotOwned({ key: o.key, resets, paramOwners })
+  /** Spread right after `prev` in every store navigate, so a `patch` or the field itself wins. */
+  const resetPatch: Record<string, undefined> = Object.fromEntries(
+    resets.map((param) => [param, undefined]),
+  )
+  /**
+   * `resetPatch` when `next` moves the field off what the URL holds NOW — read from the navigate's
+   * own `prev`, never the render-captured value, which a second `set()` in the same tick would
+   * misjudge against a value the first one already replaced.
+   */
+  const resetsFor = (
+    entry: StoreEntry,
+    prev: Record<string, unknown>,
+    next: unknown,
+  ): Record<string, undefined> | undefined => {
+    const current = core.resolve(entry, prev, core.readRecord())
+    return entry.codec.equals(next, current) ? undefined : resetPatch
+  }
   const persistedNames = new Set(
     core.entries.filter((entry) => entry.codec.lane.persist).map((entry) => entry.name),
   )
@@ -326,8 +385,10 @@ export function buildSearchStore<const S extends Record<string, AnyField>>(
       if (!validated) return
       navigate({
         to: '.',
+        // Gated like the setter: clearing a field already at its fallback keeps the page.
         search: (prev: Record<string, unknown>) => ({
           ...prev,
+          ...resetsFor(entry, prev, entry.codec.fallback),
           ...entry.codec.toSearch(entry.codec.fallback),
         }),
         replace: true,
@@ -356,8 +417,11 @@ export function buildSearchStore<const S extends Record<string, AnyField>>(
             // `patch` FIRST, the field's own params last: a patch is for keys the store does not
             // own (clearing a sibling `detailDate` with `undefined`), so it must never be able to
             // overwrite the value this very call is setting.
+            // `resets` only when the value moves: a no-op write (a debounced box settling back on
+            // what it held) must not throw the reader off the page they are on.
             search: (prev: Record<string, unknown>) => ({
               ...prev,
+              ...resetsFor(entry, prev, next),
               ...opts?.patch,
               ...entry.codec.toSearch(next),
             }),
@@ -464,7 +528,15 @@ export function buildSearchStore<const S extends Record<string, AnyField>>(
         }
         navigate({
           to: '.',
-          search: (prev: Record<string, unknown>) => ({ ...prev, ...patch }),
+          // `resets` only when some field actually moves — the same gate as the setter and
+          // `clear()`. A `Reset all` with everything already at its fallback must keep the page:
+          // this navigate REPLACES, so a page dropped here could not be got back with Back.
+          search: (prev: Record<string, unknown>) => {
+            const moved = validatedEntries.some(
+              (entry) => resetsFor(entry, prev, entry.codec.fallback) !== undefined,
+            )
+            return { ...prev, ...(moved ? resetPatch : undefined), ...patch }
+          },
           replace: true,
           // Same reason as a single field's write above — a `Reset all` pressed from the mobile
           // sheet must not also scroll the page it was pressed on.

package/src/shell/mobile-nav-model.ts

@@ -87,8 +87,6 @@ export function blockRowCount(blocks: readonly SidebarBlock[] | undefined): numb
   }).length
 }
 
-const DEV = process.env['NODE_ENV'] !== 'production'
-
 /**
  * §2.3 rule 1. A section's `mobile: false` wins over every item inside it; otherwise the item's own
  * field decides, with the shorthand booleans normalized and `undefined` meaning "reachable, but not
@@ -351,7 +349,7 @@ function buildCandidates(
   /** Rule 11 — `mobile: 'tab'` on a disabled destination is a configuration mistake, not a slot. */
   const tabbable = (item: SidebarItem): boolean => {
     if (!item.disabled) return true
-    if (DEV) {
+    if (process.env.NODE_ENV !== 'production') {
       console.warn(
         `[basalt] MobileNav: "${item.key}" asks for a bar slot but is disabled — a disabled destination never becomes a tab. It still renders, disabled, in the More surface.`,
       )
@@ -373,7 +371,7 @@ function buildCandidates(
         candidates.push(sectionCandidate(section, menuMax))
         continue
       }
-      if (DEV) {
+      if (process.env.NODE_ENV !== 'production') {
         console.warn(
           `[basalt] MobileNav: mobileNav.tabs names "${id}", which is neither a destination key nor a visible section label — ignoring it.`,
         )
@@ -464,7 +462,7 @@ export function projectMobileNav(
   const limit = needsMore ? maxTabs - 1 : maxTabs
   const kept = candidates.slice(0, limit)
   const dropped = candidates.slice(limit)
-  if (DEV && dropped.length > 0) {
+  if (process.env.NODE_ENV !== 'production' && dropped.length > 0) {
     // Rule 13 wants the NAMES, not a tally: "2 candidates dropped" tells a consumer their bar is
     // wrong, while the keys tell them which `mobile: 'tab'` to move or which section to reorder.
     console.warn(

package/src/shell/page-bar.tsx

@@ -46,9 +46,6 @@ import asideClasses from './page-aside.module.css'
 /** The custom property row 2's measured height is published on. */
 export const PAGE_BAR_HEIGHT_VAR = '--basalt-page-bar-h'
 
-/** Dev-only diagnostics, constant-folded out of a production bundle — see {@link useAsidePanelSlot}. */
-const DEV = process.env['NODE_ENV'] !== 'production'
-
 /**
  * What a `PageAside` publishes when it projects itself into row 2 below `sm`
  * (`docs/ASIDE-SPEC.md` §0 "Desktop and mobile are one declaration"). Metadata only — the aside's
@@ -236,7 +233,7 @@ export function useAsidePanelSlot(): {
     setSettled(true)
   }, [])
   useEffect(() => {
-    if (!DEV || !settled || !inShell || panelHost) return
+    if (process.env.NODE_ENV === 'production' || !settled || !inShell || panelHost) return
     console.warn(
       "[basalt] PageAside: this page's PageBar renders no row 2 (no `tabs`, no `filters`, no `filtersEnd`), so below `sm` there is no pill to open the aside — it renders in flow at the bottom of the page instead. Give the bar a row 2, or expect the in-flow form on a phone.",
     )

package/src/surfaces.ts

@@ -355,6 +355,8 @@ export const SURFACES = {
       'inline-font-size',
       'css-raw-surface',
       'surface-shadow-override',
+      // A `var(--vx-*)` naming a token basalt no longer (or never) emits.
+      'unknown-vx-token',
       // Not a token kind — the kind that judges the ANNOTATION rather than the code. It lands here
       // because `agent/rules/basalt-tokens.md` is where the `theme-allow` grammar is documented
       // (said once, on purpose), so this is the header that must name its enforcement.

package/src/tokens/index.ts

@@ -54,7 +54,12 @@ export type { SpaceValues } from './palette'
 
 // The two responsive tables — MIGRATING recipes and the raw-breakpoint guard messages send
 // consumers here for them; `migrating-imports.test.ts` pins that every documented import resolves.
-export { CONTAINER_CLASSES, resolveContainerClass, SIZE_CLASSES } from './size-classes'
+export {
+  CONTAINER_CLASSES,
+  CONTAINER_GRID_BREAKPOINTS,
+  resolveContainerClass,
+  SIZE_CLASSES,
+} from './size-classes'
 export type { ContainerClass } from './size-classes'
 
 /** A per-theme color pair: a hue keeps its identity but shifts shade across schemes. */

package/src/tokens/size-classes.ts

@@ -14,6 +14,20 @@ export const CONTAINER_CLASSES = { micro: 0, compact: 240, regular: 480, wide: 8
 
 export type ContainerClass = keyof typeof CONTAINER_CLASSES
 
+/**
+ * `CONTAINER_CLASSES` as the five-key map `<Grid type="container" breakpoints={…}>` takes (Mantine
+ * types it `Record<MantineSize, string>`), so `Grid.Col` keys resolve onto the grid's own width:
+ * `xs` opens compact, `sm` regular, `md`/`lg`/`xl` wide. `basalt/raw-breakpoint` trusts this import
+ * by name (from `basalt-ui/tokens`) — any other imported map is unreadable to it and flagged.
+ */
+export const CONTAINER_GRID_BREAKPOINTS = {
+  xs: `${CONTAINER_CLASSES.compact}px`,
+  sm: `${CONTAINER_CLASSES.regular}px`,
+  md: `${CONTAINER_CLASSES.wide}px`,
+  lg: `${CONTAINER_CLASSES.wide}px`,
+  xl: `${CONTAINER_CLASSES.wide}px`,
+} as const
+
 /** The class a MEASURED inline size falls in (`px` is a min-width boundary, so 240 is `compact`). */
 export function resolveContainerClass(px: number): ContainerClass {
   if (px >= CONTAINER_CLASSES.wide) return 'wide'

package/dist/common/is-dev.d.ts

@@ -1,3 +0,0 @@
-/** Dev-mode gate. Bundlers constant-fold `process.env.NODE_ENV` so the branch disappears in production builds. */
-export declare function isDev(): boolean;
-//# sourceMappingURL=is-dev.d.ts.map

package/dist/common/is-dev.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"is-dev.d.ts","sourceRoot":"","sources":["../../src/common/is-dev.ts"],"names":[],"mappings":"AAAA,kHAAkH;AAClH,wBAAgB,KAAK,IAAI,OAAO,CAE/B"}

package/dist/common/is-dev.js

@@ -1,6 +0,0 @@
-function isDev() {
-  return process.env["NODE_ENV"] !== "production";
-}
-export {
-  isDev
-};

package/src/common/is-dev.ts

@@ -1,4 +0,0 @@
-/** Dev-mode gate. Bundlers constant-fold `process.env.NODE_ENV` so the branch disappears in production builds. */
-export function isDev(): boolean {
-  return process.env['NODE_ENV'] !== 'production'
-}