basalt-ui 1.28.0 → 1.29.1

package/src/query/index.ts

@@ -1,97 +0,0 @@
-/**
- * ./query — thin TanStack Query adapter + transport-agnostic Eden unwrap.
- * Optional peer: @tanstack/react-query.
- */
-import { QueryClient } from '@tanstack/react-query'
-import type { QueryClientConfig } from '@tanstack/react-query'
-
-// ── createBasaltQueryClient ───────────────────────────────────────────────────────────────────────
-
-const BASALT_QUERY_DEFAULTS = {
-  staleTime: 30_000,
-  gcTime: 5 * 60 * 1000,
-  retry: 2,
-  refetchOnWindowFocus: false,
-} as const
-
-/**
- * Wraps QueryClient with basalt dashboard defaults. All options are mergeable — consumer
- * overrides win per-query, framework defaults are the fallback.
- *
- * @example
- * import { createBasaltQueryClient, QueryClientProvider } from 'basalt-ui/query'
- * import { useState } from 'react'
- *
- * function Root({ children }: { children: React.ReactNode }) {
- *   const [client] = useState(() => createBasaltQueryClient())
- *   return <QueryClientProvider client={client}>{children}</QueryClientProvider>
- * }
- */
-export function createBasaltQueryClient(config?: QueryClientConfig): QueryClient {
-  return new QueryClient({
-    ...config,
-    defaultOptions: {
-      ...config?.defaultOptions,
-      queries: { ...BASALT_QUERY_DEFAULTS, ...config?.defaultOptions?.queries },
-    },
-  })
-}
-
-// ── unwrap ────────────────────────────────────────────────────────────────────────────────────────
-
-/**
- * Transport-agnostic unwrap for any `{ data, error }` envelope (Eden Treaty, raw fetch wrappers,
- * etc.). TData is inferred from the data field. Throws on the error branch so failures surface
- * to the nearest error boundary or TanStack Query's error state.
- *
- * Null guard: if `error` is falsy but `data` is `null`, unwrap throws with a descriptive message.
- * This catches 204 No Content responses and silent transport failures that return `{ data: null,
- * error: null }` — both signal an unexpected absence of data and should not silently resolve.
- *
- * @example
- * import { unwrap } from 'basalt-ui/query'
- *
- * queryFn: () => unwrap(api.users.get({ query: params }))
- * // mutation:
- * mutationFn: (body) => unwrap(api.resource.post({ body }))
- * // manual:
- * const rows = await unwrap(api.users.get())
- */
-export async function unwrap<TData>(
-  response: Promise<{ data: TData | null; error: unknown }>,
-): Promise<TData> {
-  const { data, error } = await response
-  if (error) throw error
-  if (data === null)
-    throw new Error(
-      'unwrap: null data with no error — check for a 204 response or a transport failure',
-    )
-  return data as TData
-}
-
-// ── Error decoding ────────────────────────────────────────────────────────────────────────────────
-
-export { toErrorMessage, errorStatus } from './error-message'
-
-// ── Re-exports from @tanstack/react-query ────────────────────────────────────────────────────────
-
-// Provider + boundary helpers
-export {
-  QueryClientProvider,
-  QueryErrorResetBoundary,
-  useQueryErrorResetBoundary,
-} from '@tanstack/react-query'
-
-// Primary fetch hooks — import from basalt-ui/query rather than dual-importing @tanstack/react-query
-export {
-  useQuery,
-  useSuspenseQuery,
-  useMutation,
-  useQueryClient,
-  useInfiniteQuery,
-  queryOptions,
-} from '@tanstack/react-query'
-
-// ── Re-export devtools helper ─────────────────────────────────────────────────────────────────────
-
-export { BasaltQueryDevtools } from './devtools'

package/src/router-tanstack/field.ts

@@ -1,36 +0,0 @@
-/**
- * `field.*` — the field vocabulary `createSearchStore` takes, re-exported at the surface a consumer
- * imports it from (`basalt-ui/router-tanstack`, beside the store factory).
- *
- * The builders and their codecs LIVE in `../state` on purpose: a field is declarative data with no
- * router in it, and `createLocalStore` — the router-free lane, published on `basalt-ui/state` —
- * has to build the same fields without pulling in `@tanstack/react-router`. One definition, two
- * surfaces, no second description of the same param.
- *
- * Full field reference: the JSDoc on `field` itself, and `docs/CONTROLS-SPEC.md` §4.
- */
-export { field } from '../state'
-export type {
-  AnyField,
-  BooleanField,
-  EnumField,
-  FieldFallback,
-  FieldHandle,
-  FieldLane,
-  FieldOption,
-  FieldSetOptions,
-  FieldValue,
-  MultiField,
-  NumberField,
-  RangeField,
-  RangeParams,
-  RangePresets,
-  RangeWindow,
-  RangeWindows,
-  RangeValue,
-  ResolvedLane,
-  ResolveLane,
-  SearchValues,
-  StoredValues,
-  StringField,
-} from '../state'

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

@@ -1,106 +0,0 @@
-/**
- * @deprecated `createMultiSearchParamStore` is a thin wrapper over `createSearchStore`
- * and is removed in 1.29.0. Replace it with `field.multi`:
- *
- *     const store = createSearchStore({
- *       key: 'article-tags',
- *       fields: { tags: field.multi(['api', 'design', 'guide'], []) },
- *     })
- *
- * Two differences to know when you migrate:
- *
- * - **An empty URL array is a VALUE in the new store**, not "absent". This wrapper keeps the old
- *   rule (`?tags=[]` falls through to localStorage, then to `fallback`) so an existing consumer's
- *   links behave identically; `field.multi` treats a cleared selection as a cleared selection.
- * - `useStore` is localStorage-only. `store.field.tags.use()` reads the URL first (A8).
- *
- * Encoding is unchanged and array-native: TanStack Router's default
- * `stringifySearchWith(JSON.stringify, JSON.parse)` round-trips `{ tags: ['a', 'b'] }` losslessly,
- * so there is no CSV step to intercept — a consumer wanting `?tags=a,b` configures router-global
- * `parseSearch`/`stringifySearch` and this store keeps working untouched, because it hands the
- * router an array rather than an encoding.
- *
- * Decoding is unchanged too: array-only input, allowlist-filtered, deduped, then re-sorted into
- * `values` DECLARATION order — so `['api', 'design']` and `['design', 'api']` normalize to the same
- * array, and one logical selection has one URL.
- *
- * The four returned members (`validateSearch`, `useStore`, `readStored`, `linkSearch`), their
- * signatures and the single-value localStorage envelope are preserved byte-for-byte.
- */
-import { createPersistedState, field } from '../state'
-import { buildSearchStore } from './search-store'
-
-// ── Types ──────────────────────────────────────────────────────────────────
-
-export type MultiSearchParamStoreOptions<T extends string, P extends string = string> = {
-  /** localStorage key (namespaced `basalt:<key>` automatically). */
-  key: string
-  /** URL search-param name (e.g. `"tags"`, `"categories"`). */
-  param: P
-  /** Allowed values — `as const` for best type inference. Also the canonical sort order. */
-  values: readonly T[]
-  /** Factory default when nothing is in the URL or localStorage. Default `[]` (unfiltered). */
-  fallback?: readonly T[]
-  /** Envelope version — bump when `values` change to discard stale localStorage. */
-  version?: number
-}
-
-export type MultiSearchParamStore<T extends string, P extends string = string> = {
-  /**
-   * validateSearch — pass directly to `createFileRoute({ validateSearch })`.
-   * Falls back to localStorage, then to `fallback`.
-   */
-  validateSearch: (search: Record<string, unknown>) => { [K in P]: readonly T[] }
-  /**
-   * React hook: `const [current, persist] = store.useStore()`.
-   * localStorage only — it does NOT read or write the URL.
-   */
-  useStore: () => readonly [readonly T[], (next: readonly T[]) => void]
-  /** Plain read — for use outside React (tests, guards, fallback reads). */
-  readStored: () => readonly T[] | null
-  /**
-   * The click-time `search:` thunk for a nav link — `() => ({ [param]: readStored() ?? fallback })`.
-   * Pass it BY REFERENCE (`search: store.linkSearch`), never call it; see `createSearchParamStore`
-   * for why a module-scope literal silently defeats the store.
-   *
-   * No dev warning rides on this one, unlike the single-value store: an empty array in the URL is
-   * indistinguishable from an absent param here, so a link declaring `{ tags: [] }` restores
-   * correctly and there is no broken state to detect.
-   */
-  linkSearch: () => { [K in P]: readonly T[] }
-}
-
-// ── Implementation ─────────────────────────────────────────────────────────
-
-/** @deprecated Use `createSearchStore` + `field.multi`. Removed in 1.29.0. */
-export function createMultiSearchParamStore<const T extends string, const P extends string>(
-  opts: MultiSearchParamStoreOptions<T, P>,
-): MultiSearchParamStore<T, P> {
-  const version = opts.version ?? 1
-  const fallback = opts.fallback ?? []
-  const store = buildSearchStore({
-    key: opts.key,
-    version,
-    fields: { [opts.param]: field.multi(opts.values, fallback) },
-    legacyValueField: opts.param,
-  })
-
-  const persisted = createPersistedState<readonly T[]>({
-    key: opts.key,
-    version,
-    initial: fallback,
-  })
-  // A reader, like the single-value wrapper's — see the note there.
-  const useStore = (): readonly [readonly T[], (next: readonly T[]) => void] => {
-    store.markReaderWired()
-    return persisted()
-  }
-
-  return {
-    validateSearch: (search) => store.validateSearch(search) as { [K in P]: readonly T[] },
-    useStore,
-    readStored: () =>
-      (store.readStored() as Record<string, readonly T[] | undefined>)[opts.param] ?? null,
-    linkSearch: () => store.linkSearch() as { [K in P]: readonly T[] },
-  }
-}

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

@@ -1,100 +0,0 @@
-/**
- * @deprecated `createSearchParamStore` is a thin wrapper over `createSearchStore` and is
- * removed in 1.29.0. It can express exactly one closed string enum on one param; the store it
- * delegates to expresses six field kinds, per-field lanes, and a range's three params.
- *
- * Migration is mechanical:
- *
- *     // before
- *     const range = createSearchParamStore({
- *       key: 'dashboard-range', param: 'range', values: ['1d', '7d', '30d'] as const, fallback: '30d',
- *     })
- *     const [, persist] = range.useStore()          // localStorage only — never the URL
- *
- *     // after
- *     const dash = createSearchStore({
- *       key: 'dashboard-range',
- *       fields: { range: field.enum(['1d', '7d', '30d'], '30d') },
- *     })
- *     const [value, set] = dash.field.range.use()    // reads the URL, writes both lanes
- *
- * The two are NOT equivalent in the one way that matters: `useStore` reads localStorage, so a deep
- * link `?range=7d` rendered `30d` (A8). `field.range.use()` reads the URL first. See
- * `docs/CONTROLS-SPEC.md` §4 and `MIGRATING.md`.
- *
- * What the wrapper preserves byte-for-byte, because `basalt-ui-obsidian` consumes it two hops
- * downstream: the four returned members (`validateSearch`, `useStore`, `readStored`, `linkSearch`),
- * their signatures, and the single-value localStorage envelope an existing browser already holds.
- */
-import { createPersistedState, field } from '../state'
-import { buildSearchStore } from './search-store'
-
-// ── Types ──────────────────────────────────────────────────────────────────
-
-export type SearchParamStoreOptions<T extends string, P extends string = string> = {
-  /** localStorage key (namespaced `basalt:<key>` automatically). */
-  key: string
-  /** URL search-param name (e.g. `"range"`, `"tab"`, `"filter"`). */
-  param: P
-  /** Allowed values — `as const` for best type inference. */
-  values: readonly T[]
-  /** Factory default when nothing is in the URL or localStorage. */
-  fallback: T
-  /** Envelope version — bump when `values` change to discard stale localStorage. */
-  version?: number
-}
-
-export type SearchParamStore<T extends string, P extends string = string> = {
-  /**
-   * validateSearch — pass directly to `createFileRoute({ validateSearch })`.
-   * Falls back to localStorage, then to `fallback`.
-   */
-  validateSearch: (search: Record<string, unknown>) => { [K in P]: T }
-  /**
-   * React hook: `const [current, persist] = store.useStore()`.
-   * localStorage only — it does NOT read or write the URL. `createSearchStore`'s
-   * `field.<name>.use()` is the replacement that does both.
-   */
-  useStore: () => readonly [T, (next: T) => void]
-  /** Plain read — for use outside React (tests, guards, fallback reads). */
-  readStored: () => T | null
-  /**
-   * The click-time `search:` thunk for a nav link — `() => ({ [param]: readStored() ?? fallback })`.
-   *
-   * Pass it BY REFERENCE (`search: store.linkSearch`), never call it: `<Link>` re-evaluates the
-   * thunk on every click, so arriving from outside the sub-tree restores the last selection,
-   * whereas a value computed once at module scope goes stale immediately and pins the fallback.
-   */
-  linkSearch: () => { [K in P]: T }
-}
-
-// ── Implementation ─────────────────────────────────────────────────────────
-
-/** @deprecated Use `createSearchStore` + `field.enum`. Removed in 1.29.0. */
-export function createSearchParamStore<const T extends string, const P extends string>(
-  opts: SearchParamStoreOptions<T, P>,
-): SearchParamStore<T, P> {
-  const version = opts.version ?? 1
-  const store = buildSearchStore({
-    key: opts.key,
-    version,
-    fields: { [opts.param]: field.enum(opts.values, opts.fallback) },
-    legacyValueField: opts.param,
-  })
-
-  const persisted = createPersistedState<T>({ key: opts.key, version, initial: opts.fallback })
-  // `useStore` is a reader too. Without this, a consumer whose ONLY reader is `useStore()` — the
-  // documented wiring for this factory — would start seeing the pinned-link warning it never saw
-  // before, purely because the wrapper now delegates.
-  const useStore = (): readonly [T, (next: T) => void] => {
-    store.markReaderWired()
-    return persisted()
-  }
-
-  return {
-    validateSearch: (search) => store.validateSearch(search) as { [K in P]: T },
-    useStore,
-    readStored: () => (store.readStored() as Record<string, T | undefined>)[opts.param] ?? null,
-    linkSearch: () => store.linkSearch() as { [K in P]: T },
-  }
-}

package/src/section/index.ts

@@ -1 +0,0 @@
-export { Section, type SectionProps, type SectionSlot } from './section'

package/src/widget-header/delta-badge.tsx

@@ -1,77 +0,0 @@
-/**
- * DeltaBadge — the KPI trend chip (docs/DESIGN-SPEC.md §5): mono 11.5px weight 600, status-color
- * text on a status-13% tint, control radius, 2px/7px padding, optional ▲/▼ glyph at 9px.
- * `polarity` decides the TONE the sign maps to — `'up-good'` (default) reads a rise as success and
- * a fall as danger; `'up-bad'` inverts that for a metric where a rise is the worse reading (a
- * cycle-top index, latency, error rate); `'neutral'` renders every sign in a faint, non-verdict
- * tint. Zero is always faint with no glyph, under every polarity. The label never carries a
- * leading "+"; pass `format` to control the magnitude string (defaults to a one-decimal percentage
- * of the absolute value). The ▲/▼ glyph is DIRECTION, not verdict, and stays polarity-independent —
- * governed only by `withGlyph` and the sign.
- *
- * Mantine-free (plain `<span>` + this folder's CSS module, docs/CONTROLS-SPEC.md §2.2) so
- * `WidgetHeader` can compose it from inside `charts/` without tripping `basalt/token-layer-
- * boundary` or `check-dist-layering.mjs`.
- *
- * @example
- * import { DeltaBadge } from 'basalt-ui'
- *
- * <DeltaBadge value={12.4} />                          // ▲ 12.4%, success tint
- * <DeltaBadge value={-3.1} />                           // ▼ 3.1%, danger tint
- * <DeltaBadge value={0} />                              // 0.0%, neutral faint tint, no glyph
- * <DeltaBadge value={182} format={(v) => `${Math.abs(v)}ms`} withGlyph={false} />
- * <DeltaBadge value={35.9} polarity="up-bad" />         // ▲ 35.9%, danger tint — a rise is bad here
- */
-import { alpha, VX } from '../tokens'
-import classes from './widget-header.module.css'
-
-export type DeltaPolarity = 'up-good' | 'up-bad' | 'neutral'
-
-export type DeltaBadgeProps = {
-  /** Signed delta driving tone (positive/negative/zero) and, by default, the label magnitude. */
-  value: number
-  /** Which sign reads as the good verdict. `'up-good'` (default) is today's behaviour — positive
-   * success, negative danger. `'up-bad'` inverts it for a metric where a rise is the worse reading.
-   * `'neutral'` renders every sign in the faint tint — a change with no verdict attached. Zero is
-   * always faint regardless. */
-  polarity?: DeltaPolarity
-  /** Formats the value into the label text. Defaults to `${Math.abs(value).toFixed(1)}%`. */
-  format?: (value: number) => string
-  /** Render the ▲/▼ direction glyph. Defaults to `true`; a zero value never shows a glyph. */
-  withGlyph?: boolean
-  /** Optional comparison timeframe rendered directly after the value in a dimmer shade of the same
-   * tone (e.g. `MoM`, `WoW`, `YTD`) — states what the delta is measured against without a hover. */
-  period?: string | undefined
-}
-
-const defaultFormat = (value: number): string => `${Math.abs(value).toFixed(1)}%`
-
-function resolveTone(value: number, polarity: DeltaPolarity): string {
-  if (value === 0 || polarity === 'neutral') return VX.faint
-  const rose = value > 0
-  const good = polarity === 'up-good' ? rose : !rose
-  return good ? VX.status.good : VX.status.bad
-}
-
-export function DeltaBadge({
-  value,
-  polarity = 'up-good',
-  format = defaultFormat,
-  withGlyph = true,
-  period,
-}: DeltaBadgeProps) {
-  const tone = resolveTone(value, polarity)
-  const glyph = value > 0 ? '▲' : value < 0 ? '▼' : undefined
-  const showGlyph = withGlyph && glyph !== undefined
-
-  return (
-    <span
-      className={classes.deltaBadge}
-      style={{ backgroundColor: alpha(tone, 0.13), color: tone }}
-    >
-      {showGlyph && <span className={classes.deltaGlyph}>{glyph}</span>}
-      {format(value)}
-      {period !== undefined && <span className={classes.deltaPeriod}>{period}</span>}
-    </span>
-  )
-}

package/src/widget-header/index.ts

@@ -1,10 +0,0 @@
-export {
-  WidgetHeader,
-  type WidgetHeaderDeltaProps,
-  type WidgetHeaderMetricProps,
-  type WidgetHeaderProps,
-  type WidgetHeaderSlot,
-  type WidgetHeaderTier,
-  type WidgetHeaderTitleProps,
-} from './widget-header'
-export { DeltaBadge, type DeltaBadgeProps, type DeltaPolarity } from './delta-badge'