basalt-ui 1.27.0 → 1.29.0

package/src/shell/sidebar-blocks.tsx

@@ -21,7 +21,7 @@ import type {
   SidebarCustomBlock,
   SidebarListBlock,
   SidebarProgressBlock,
-} from '../nav/types'
+} from './nav-types'
 import { NavCountBadge } from './nav-count-badge'
 import { createPersistedState } from '../state'
 import {

package/src/shell/sidebar-search.module.css

@@ -61,7 +61,7 @@
 }
 
 /*
- * Collapsed rail button — mirrors app-sidebar.module.css's `.ghostIcon`: faint icon, radius 6,
+ * Collapsed rail button — mirrors app-brand.module.css's `.ghostIcon`: faint icon, radius 6,
  * hover ink-6% + ink. `!important` for the same reason as that rule: it competes with Mantine's
  * own compiled ActionIcon variant CSS.
  *

package/src/shell/sidebar-search.tsx

@@ -11,6 +11,8 @@ import { ActionIcon, Kbd, Text, UnstyledButton } from '@mantine/core'
 import type { ReactNode } from 'react'
 import { OverflowMenu } from '../controls/actions'
 import type { BarAction } from '../controls/actions'
+import { cx } from '../common/props'
+import type { BasaltProps } from '../common/props'
 import classes from './sidebar-search.module.css'
 
 /**
@@ -95,13 +97,18 @@ function SearchAction({ action }: { action: BarAction }): ReactNode {
   return <ActionIcon {...shared}>{body}</ActionIcon>
 }
 
+export type SidebarSearchProps = SidebarSearchConfig &
+  BasaltProps & { actions?: SidebarSearchActions; collapsed?: boolean }
+
 export function SidebarSearch({
   onOpen,
   placeholder = 'Search…',
   shortcut,
   actions,
   collapsed,
-}: SidebarSearchConfig & { actions?: SidebarSearchActions; collapsed?: boolean }) {
+  className,
+  style,
+}: SidebarSearchProps) {
   // SSR-safe mac detection, matching the shell's other shortcut-hint logic.
   const isMac = typeof navigator !== 'undefined' && /Mac|iPhone|iPod|iPad/i.test(navigator.platform)
   const hint = shortcut ?? (isMac ? '⌘K' : 'Ctrl K')
@@ -111,9 +118,10 @@ export function SidebarSearch({
       <ActionIcon
         variant="subtle"
         size="md"
-        className={classes.railBtn}
+        className={cx(classes.railBtn, className)}
         onClick={onOpen}
         aria-label="Open search"
+        {...(style !== undefined && { style })}
       >
         <IconSearch />
       </ActionIcon>
@@ -123,9 +131,10 @@ export function SidebarSearch({
   const trigger = (
     <UnstyledButton
       type="button"
-      className={classes.trigger}
+      className={cx(classes.trigger, actions === undefined && className)}
       onClick={onOpen}
       aria-label="Open search"
+      {...(actions === undefined && style !== undefined && { style })}
     >
       <IconSearch />
       <Text component="span" className={classes.label}>
@@ -139,7 +148,7 @@ export function SidebarSearch({
   if (actions === undefined) return trigger
 
   return (
-    <div className={classes.row}>
+    <div className={cx(classes.row, className)} {...(style !== undefined && { style })}>
       {trigger}
       {actions.map((action) => (
         <SearchAction key={action.key} action={action} />

package/src/shell/use-breakpoint.ts

@@ -0,0 +1,73 @@
+/**
+ * `useBreakpoint` — one media-query hook over the theme's own breakpoints, SSR/hydration-safe.
+ *
+ * Built on `useSyncExternalStore`, NOT `@mantine/hooks`' `useMediaQuery` — that hook reads
+ * `matchMedia` inside a `useState` initializer, so on the server it returns its `fallback` and on
+ * the client's very first render it returns the REAL match; when that render is a hydration pass
+ * the two disagree silently (a server-rendered desktop layout hydrating on a phone against a
+ * client tree that already moved). `useSyncExternalStore`'s `getServerSnapshot` makes React render
+ * the server's answer during hydration and correct itself immediately after — the documented,
+ * warning-free version of the same fix. `page-aside.tsx`'s own former private
+ * `useMediaQueryMatches` carried this exact rationale; it now lives here and page-aside composes
+ * this hook instead (C5 consolidation — one media-query hook, not two).
+ *
+ * `edge` defaults to `'min'` (`"at least this wide"`); pass `'max'` for `"narrower than"`. The
+ * `fallback` (what the server, and a shim with no `matchMedia`, sees) defaults to the answer that
+ * assumes the NARROW side of the query — `false` for `min`, `true` for `max` — since a component
+ * library cannot know a consumer's real device mix; a call site with its own rationale (e.g.
+ * `page-aside.tsx`'s desktop-first portal fallback) overrides it via `options.fallback`.
+ *
+ * @example
+ * import { useBreakpoint } from 'basalt-ui'
+ *
+ * const isDesktop = useBreakpoint('sm')            // >= theme.breakpoints.sm
+ * const isNarrow = !useBreakpoint('sm')             // < theme.breakpoints.sm
+ * const isWide = useBreakpoint('lg')                // >= theme.breakpoints.lg
+ */
+import { useCallback, useMemo, useSyncExternalStore } from 'react'
+import { useMantineTheme } from '@mantine/core'
+
+export type BreakpointName = 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+
+/** `window.matchMedia`, or `null` where there is no window and on a shim that does not ship it. */
+function mediaQueryList(query: string): MediaQueryList | null {
+  if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return null
+  return window.matchMedia(query)
+}
+
+/**
+ * Internal — the raw media-query read. Exported (not `default`) so `page-aside.tsx` can compose
+ * it directly for its `(min-width: theme.breakpoints.sm)` desktop check without re-deriving the
+ * query string `useBreakpoint` builds for the fixed `BreakpointName` union.
+ */
+export function useMediaQueryMatches(query: string, fallback: boolean): boolean {
+  // ONE `MediaQueryList` per query, held across renders — `matchMedia()` allocates a fresh live
+  // object on every call, and `getSnapshot` runs on every render AND after every store
+  // notification, so calling it there would churn an object per read while `subscribe` listened
+  // on a different instance than `getSnapshot` measured.
+  const list = useMemo(() => mediaQueryList(query), [query])
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      if (list === null) return () => {}
+      list.addEventListener('change', onStoreChange)
+      return () => {
+        list.removeEventListener('change', onStoreChange)
+      }
+    },
+    [list],
+  )
+  const getSnapshot = useCallback(() => list?.matches ?? fallback, [list, fallback])
+  const getServerSnapshot = useCallback(() => fallback, [fallback])
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot)
+}
+
+export function useBreakpoint(
+  name: BreakpointName,
+  edge: 'min' | 'max' = 'min',
+  options?: { fallback?: boolean },
+): boolean {
+  const theme = useMantineTheme()
+  const bp = theme.breakpoints[name]
+  const fallback = options?.fallback ?? edge === 'max'
+  return useMediaQueryMatches(`(${edge}-width: ${bp})`, fallback)
+}

package/src/state/fields.ts

@@ -140,6 +140,12 @@ export type NumberField<Ln extends ResolvedLane = ResolvedLane> = {
   readonly min: number | undefined
   readonly max: number | undefined
   readonly int: boolean
+  /**
+   * The declared grain, ALREADY resolved — `field.number` fills in `1` for an `int: true` field
+   * that declared none, so the "an integer field steps by one" rule lives at that one call site and
+   * every reader (the handle, `NumberFilter`, `SliderControl`) reads a single answer.
+   */
+  readonly step: number | undefined
   readonly lane: Ln
 }
 
@@ -250,8 +256,10 @@ type RangeHandleExtras<F> = F extends {
  * With them on the handle the input can bound its own stepper, which turns the clamp from a
  * correction the user watches happen into a value they cannot type in the first place.
  *
- * `int` is the third member because it is the same class of fact: it decides the stepper's grain
- * (`step` 1, decimals refused), and the codec already rejects a non-integer for that field.
+ * `int` is the third member because it is the same class of fact: it decides whether the stepper
+ * refuses decimals, and the codec already rejects a non-integer for that field. `step` is the
+ * fourth for the same reason, and it is where the "an `int` field steps by one" rule is RESOLVED —
+ * once, in `field.number`, rather than re-derived by every control that draws a stepper or a track.
  */
 type NumberHandleExtras<F> = F extends { kind: 'number' }
   ? {
@@ -261,8 +269,15 @@ type NumberHandleExtras<F> = F extends { kind: 'number' }
       readonly max: number | undefined
       /** `field.number({ int: true })` — a non-integer is refused by the codec, not rounded. */
       readonly int: boolean
+      /** The field's `step`, `1` for an `int` field that declared none, else `undefined`. */
+      readonly step: number | undefined
+    }
+  : {
+      readonly min?: undefined
+      readonly max?: undefined
+      readonly int?: undefined
+      readonly step?: undefined
     }
-  : { readonly min?: undefined; readonly max?: undefined; readonly int?: undefined }
 
 /**
  * The binding every basalt control takes instead of `value`/`onChange` (C2). One field, both lanes,
@@ -408,9 +423,22 @@ export const field = {
 
   range: rangeField,
 
-  /** A number — pagination, a threshold. Out-of-range input clamps to `min`/`max`. */
+  /**
+   * A number — pagination, a threshold, a weight. Out-of-range input clamps to `min`/`max`.
+   *
+   * `step` is the grain a stepper or a slider bound to this field moves by, and it is resolved
+   * HERE rather than at either control: an `int: true` field that declares no `step` steps by 1,
+   * which is the only sane grain for a field whose codec refuses a decimal — stating it once means
+   * `NumberFilter` and `SliderControl` cannot answer it differently.
+   */
   number<const L extends FieldLane = FieldLane>(
-    o: { fallback: FieldFallback<number>; min?: number; max?: number; int?: boolean },
+    o: {
+      fallback: FieldFallback<number>
+      min?: number
+      max?: number
+      int?: boolean
+      step?: number
+    },
     lane?: L,
   ): NumberField<ResolveLane<L>> {
     return {
@@ -419,6 +447,7 @@ export const field = {
       min: o.min,
       max: o.max,
       int: o.int === true,
+      step: o.step ?? (o.int === true ? 1 : undefined),
       lane: resolveLane(lane) as ResolveLane<L>,
     }
   },
@@ -530,14 +559,9 @@ export type FieldCodec = {
     readonly min: number | undefined
     readonly max: number | undefined
     readonly int: boolean
+    readonly step: number | undefined
   }
-  /**
-   * Validate a STORED (or caller-supplied) value. `null` = unusable.
-   *
-   * Deliberately a different function from `fromSearch` for one kind: the deprecated multi store
-   * reads an empty URL array as "absent", and reusing that rule on the storage side would turn a
-   * deliberately CLEARED filter into a miss and resurrect the fallback on upgrade.
-   */
+  /** Validate a STORED (or caller-supplied) value. `null` = unusable. */
   decode(raw: unknown): unknown
   /** Pull the field out of a router search object. `null` = absent or invalid. */
   fromSearch(search: Record<string, unknown>): unknown
@@ -584,17 +608,11 @@ function sameList(a: unknown, b: unknown): boolean {
 }
 
 /**
- * Build the codec for one field. `legacyMultiEmpty` restores the DEPRECATED multi-store's rule that
- * an EMPTY url array means "absent, fall through to storage" — the deprecated wrapper's contract,
- * never the new store's, where an empty selection is a value like any other.
+ * Build the codec for one field.
  *
  * @internal — see `FieldCodec`.
  */
-export function resolveFieldCodec(
-  name: string,
-  f: AnyField,
-  opts?: { legacyMultiEmpty?: boolean },
-): FieldCodec {
+export function resolveFieldCodec(name: string, f: AnyField): FieldCodec {
   switch (f.kind) {
     case 'enum': {
       const allowed = new Set<string>(f.values)
@@ -612,19 +630,9 @@ export function resolveFieldCodec(
         }
         return f.values.filter((value) => picked.has(value))
       }
-      // The legacy empty-array rule is a URL rule ONLY. A stored `[]` is what "I cleared every
-      // filter" looks like, and the deprecated store has always read it back as `[]`.
-      const decodeUrl =
-        opts?.legacyMultiEmpty === true
-          ? (raw: unknown): unknown => {
-              const value = decode(raw)
-              return Array.isArray(value) && value.length === 0 ? null : value
-            }
-          : decode
       return single(name, f, decode, {
         optionValues: f.values,
         equals: sameList,
-        decodeUrl,
       })
     }
     case 'range': {
@@ -690,11 +698,13 @@ export function resolveFieldCodec(
         if (f.max !== undefined && value > f.max) value = f.max
         return value
       }
-      // The same three values the clamp above reads, handed on so the CONTROL can bound its input
-      // rather than watch the clamp correct it after the fact. Threaded THROUGH `single` rather
-      // than spread onto its result: `fallback` is a getter, and a spread would evaluate it once
-      // here and freeze a thunk fallback at definition.
-      return single(name, f, decode, { bounds: { min: f.min, max: f.max, int: f.int } })
+      // The same values the clamp above reads (plus the already-resolved `step`), handed on so the
+      // CONTROL can bound its input rather than watch the clamp correct it after the fact. Threaded
+      // THROUGH `single` rather than spread onto its result: `fallback` is a getter, and a spread
+      // would evaluate it once here and freeze a thunk fallback at definition.
+      return single(name, f, decode, {
+        bounds: { min: f.min, max: f.max, int: f.int, step: f.step },
+      })
     }
     case 'boolean': {
       return single(name, f, decodeBoolean)
@@ -727,13 +737,10 @@ function single(
   extra?: {
     optionValues?: readonly string[]
     equals?: (a: unknown, b: unknown) => boolean
-    /** URL-side decoder when it differs from the storage-side one (multi, legacy layout only). */
-    decodeUrl?: (raw: unknown) => unknown
     /** Number only: the declared bounds and grain, republished onto the handle. */
     bounds?: FieldCodec['bounds']
   },
 ): FieldCodec {
-  const decodeUrl = extra?.decodeUrl ?? decode
   return {
     kind: f.kind,
     lane: f.lane,
@@ -744,7 +751,7 @@ function single(
     },
     ...(extra?.bounds !== undefined && { bounds: extra.bounds }),
     decode,
-    fromSearch: (search) => decodeUrl(search[name]),
+    fromSearch: (search) => decode(search[name]),
     toSearch: (value) => ({ [name]: value }),
     equals: extra?.equals ?? ((a, b) => a === b),
     optionValues: extra?.optionValues ?? [],
@@ -773,12 +780,6 @@ export type StoreCoreOptions = {
   readonly key: string
   readonly fields: Record<string, AnyField>
   readonly version?: number | undefined
-  /**
-   * Legacy single-value storage layout: the whole envelope value IS this field's value, the shape
-   * `createSearchParamStore` has written since 1.0.0. Set ONLY by the deprecated wrappers — a
-   * consumer's already-persisted selection has to keep resolving byte-for-byte.
-   */
-  readonly legacyValueField?: string
 }
 
 /**
@@ -935,10 +936,9 @@ function assertNoParamCollision(key: string, entries: readonly StoreEntry[]): vo
 /** @internal — the seam behind `createSearchStore` and `createLocalStore`. */
 export function createStoreCore(o: StoreCoreOptions): StoreCore {
   const version = o.version ?? 1
-  const legacy = o.legacyValueField
   const entries: StoreEntry[] = Object.entries(o.fields).map(([name, f]) => ({
     name,
-    codec: resolveFieldCodec(name, f, { legacyMultiEmpty: legacy !== undefined }),
+    codec: resolveFieldCodec(name, f),
   }))
   assertNoParamCollision(o.key, entries)
   const urlEntries = entries.filter((entry) => entry.codec.lane.url)
@@ -951,12 +951,8 @@ export function createStoreCore(o: StoreCoreOptions): StoreCore {
   const usePersistedRaw = createPersistedState<unknown>({ key: o.key, version, initial: null })
   const memory = createMemoryLane()
 
-  const toRecord = (raw: unknown): StoreRecord => {
-    if (legacy !== undefined) return raw === null || raw === undefined ? {} : { [legacy]: raw }
-    return isRecord(raw) ? raw : {}
-  }
-  const fromRecord = (record: StoreRecord): unknown =>
-    legacy !== undefined ? (record[legacy] ?? null) : record
+  const toRecord = (raw: unknown): StoreRecord => (isRecord(raw) ? raw : {})
+  const fromRecord = (record: StoreRecord): unknown => record
 
   const readRecord = (): StoreRecord => toRecord(readPersistedValue(o.key, version))
 
@@ -1013,6 +1009,7 @@ export function createStoreCore(o: StoreCoreOptions): StoreCore {
       built['min'] = bounds?.min
       built['max'] = bounds?.max
       built['int'] = bounds?.int ?? false
+      built['step'] = bounds?.step
     }
     // GETTERS, not snapshots, and installed with defineProperty rather than declared in the
     // literal: `labels()` runs on the store after the handles exist, and an object spread would

package/src/state/persisted-or-local.ts

@@ -0,0 +1,50 @@
+/**
+ * Internal — one disclosure flag that persists only when the caller named a key.
+ *
+ * `Section`'s collapse and `PageAside`'s fold are the same hook written twice: an optional
+ * `persistKey` decides whether the flag survives a reload, and both a `useState` and a
+ * `createPersistedState` hook are ALWAYS called so the hook order is stable across a key appearing
+ * or disappearing. Only the branch the caller asked for is returned, so an unpersisted surface
+ * never writes to storage.
+ *
+ * `scope` stays a parameter rather than being folded into `key`: it is what keeps
+ * `basalt:section:<key>` and `basalt:aside:<key>` from colliding when two surfaces on one page
+ * persist under the same name.
+ *
+ * Not exported from `../state` — this is an internal hook, not part of the `./state` surface.
+ */
+import { useMemo, useState } from 'react'
+import { createPersistedState } from './persisted'
+
+/** The key an unpersisted caller parks on — never read, because that branch returns local state. */
+const UNPERSISTED_KEY = '__local__'
+
+export function usePersistedOrLocal<T>({
+  scope,
+  persistKey,
+  initial,
+}: {
+  /** The storage namespace — `section`, `aside`. Prefixed onto `persistKey`. */
+  scope: string
+  /** Persist under `basalt:<scope>:<persistKey>`. Omitted → local state, nothing written. */
+  persistKey: string | undefined
+  /** First-render value, respected only while nothing is persisted. */
+  initial: T
+}): readonly [T, (next: T) => void] {
+  const [local, setLocal] = useState(initial)
+  // `createPersistedState` is a per-key module FACTORY, so it is memoized rather than called during
+  // render — the same reason `shell/index.tsx` memoizes its collapse store.
+  const usePersisted = useMemo(
+    () =>
+      createPersistedState<T>({
+        key: `${scope}:${persistKey ?? UNPERSISTED_KEY}`,
+        version: 1,
+        initial,
+      }),
+    [scope, persistKey, initial],
+  )
+  const [persisted, setPersisted] = usePersisted()
+
+  if (persistKey !== undefined) return [persisted, setPersisted] as const
+  return [local, setLocal] as const
+}

package/src/state.ts

@@ -46,13 +46,4 @@ export {
   type FieldHandle,
   type SearchValues,
   type StoredValues,
-  // @internal — the seam `createSearchStore` is built on, not a consumer API.
-  type FieldCodec,
-  type StoreEntry,
-  type StoreCoreOptions,
-  type StoreCore,
-  type FieldUse,
-  type FieldWrite,
-  resolveFieldCodec,
-  createStoreCore,
 } from './state/fields'

package/src/styles.css

@@ -40,6 +40,42 @@
 }
 
 @layer basalt {
+  /* Native/PWA chrome (C5 consolidation) — three of the five rules argo's own `styles/native.css`
+     carried, moved here so every consumer gets them for free instead of hand-copying a stylesheet.
+     The other two (safe-area padding on the sidebar/main) are CSS-module rules on those specific
+     regions, not global — see `shell/app-sidebar.module.css` and `shell/app-main.module.css`.
+     Overscroll containment and the footer's safe-area-bottom inset already ship
+     (`shell/app-main.module.css`, `shell/app-mobile-nav.module.css`) and are not repeated here. */
+
+  /* Stops iOS from inflating font sizes on a rotation into landscape — `text-size-adjust` governs
+     text INFLATION, a different failure mode than the input-zoom floor just below. */
+  html {
+    -webkit-text-size-adjust: 100%;
+    text-size-adjust: 100%;
+  }
+
+  /* Removes the grey tap-highlight flash on iOS/Android for anything actually tappable. Scoped to
+     the interactive roles/tags rather than `*` (argo's own rule): a highlight on non-interactive
+     content is not the flash this exists to remove, and `*` would also numb a consumer's own
+     custom interactive elements that don't match one of these. */
+  button,
+  a,
+  [role='button'],
+  [role='tab'] {
+    -webkit-tap-highlight-color: transparent;
+  }
+
+  /* A long-press on a control must not select its label or pop the iOS callout menu — inputs and
+     prose content stay selectable. Same Mantine class-hook targets argo's own rule used
+     (`.mantine-Button-root`/`.mantine-NavLink-root`/`.mantine-Burger-root`): the theme layer is
+     the one place allowed to reach for a Mantine class hook directly, per `basalt-mantine.md`. */
+  .mantine-Button-root,
+  .mantine-NavLink-root,
+  .mantine-Burger-root {
+    -webkit-touch-callout: none;
+    user-select: none;
+  }
+
   /* iOS input-zoom FLOOR. Safari zooms the viewport whenever a focused input computes below 16px,
      and never zooms back out on blur — the single worst mobile-form defect. 16px is the only clean
      fix: `maximum-scale=1` / `user-scalable=no` block pinch-zoom on Android (WCAG 1.4.4),