basalt-ui 1.27.0 → 1.28.0

package/src/dashboard/index.ts

@@ -3,14 +3,24 @@ export {
   StatCard,
   type StatCardBreakdownRow,
   type StatCardProps,
+  type StatCardSlot,
   type StatCardTone,
 } from './stat-card'
-export { EmptyState, type EmptyStateProps } from './empty-state'
+export {
+  WidgetGrid,
+  type WidgetGridCols,
+  type WidgetGridItemProps,
+  type WidgetGridProps,
+} from './widget-grid'
+export { StatGroup, type StatGroupCols, type StatGroupProps } from './stat-group'
+export { EmptyState, type EmptyStateProps, type EmptyStateSlot } from './empty-state'
 export {
   SettingsSection,
   type SettingsSectionProps,
+  type SettingsSectionSlot,
   SettingsRow,
   type SettingsRowProps,
+  type SettingsRowSlot,
   DangerZone,
   type DangerZoneProps,
 } from './settings-section'
@@ -18,6 +28,8 @@ export {
   QueryState,
   type QueryStateProps,
   type QueryStateLike,
+  type QueryStateSlot,
+  type QueryStateTier,
   type QueryStateVariant,
   type QueryEmptyCopy,
   LoadingState,

package/src/dashboard/query-state.tsx

@@ -15,31 +15,35 @@
  * escape hatch for a page that must place its branches in different DOM positions.
  */
 import { Alert, Button, Center, Group, Loader, Stack, Text } from '@mantine/core'
-import type { ReactNode } from 'react'
+import type { CSSProperties, ReactNode } from 'react'
 import { toErrorMessage } from '../query/error-message'
+import { cx } from '../common/props'
+import type { BasaltProps, SlotStylesProps } from '../common/props'
 import { EmptyState } from './empty-state'
-
-/** `'page'` = a full route body (generous padding). `'section'` = a card/panel region (compact). */
-export type QueryStateVariant = 'page' | 'section'
+import { assertQueryStateLike } from '../common/query-state-like'
+import type { QueryStateLike } from '../common/query-state-like'
 
 /**
- * The structural subset of a TanStack `UseQueryResult` these components read.
+ * How loud this state is: `'page'` = a full route body (generous padding), `'section'` = a
+ * card/panel region (compact).
  *
- * Typed as a SUBSET rather than as `UseQueryResult<T>` on purpose: a composed, derived or
- * hand-rolled result must be passable without a cast, and
- * these components stay independent of which `@tanstack/react-query` major a consumer pins. This
- * is NOT a claim that the root barrel is free of that package — `./connectivity` imports
- * `onlineManager` as a value and is re-exported from `src/index.ts`. The cost of the subset is
- * that the compiler stops policing the shape — which is why {@link QueryState} asserts it at
- * runtime.
+ * Named `tier`, not `variant` (audit B #19): `tier` is already the package's word for "how loud is
+ * this" on `WidgetHeader` and `CtlSlot`, and `'section'` meant two different things across the two
+ * spellings. {@link QueryStateVariant} stays exported as an alias — nothing is renamed out from
+ * under a consumer.
  */
-export type QueryStateLike<TData> = {
-  data: TData | undefined
-  isError: boolean
-  error: unknown
-  fetchStatus: 'fetching' | 'paused' | 'idle'
-  refetch: () => unknown
-}
+export type QueryStateTier = 'page' | 'section'
+
+/** The former name of {@link QueryStateTier}. Kept as an alias; prefer `QueryStateTier`. */
+export type QueryStateVariant = QueryStateTier
+
+/**
+ * The structural subset of a TanStack `UseQueryResult` these components read — defined in
+ * `common/query-state-like.ts` and re-exported here, where consumers have always imported it from.
+ * The runtime assertion over it lives beside the type, because `./data`'s containers read the same
+ * envelope and a second copy of the check had already drifted to a weaker one.
+ */
+export type { QueryStateLike }
 
 /** Copy for the empty branch. Rendered through `EmptyState`, so it looks like every other one. */
 export type QueryEmptyCopy = {
@@ -54,25 +58,50 @@ export type QueryEmptyCopy = {
 
 // ── LoadingState ──────────────────────────────────────────────────────────────────────────────────
 
-export type LoadingStateProps = {
-  variant?: QueryStateVariant
+export type LoadingStateProps = BasaltProps & {
+  /** How loud this state is. Default `'page'`. */
+  tier?: QueryStateTier
+  /** @deprecated Renamed to `tier` — see {@link QueryStateTier}. Still honoured; `tier` wins. */
+  variant?: QueryStateTier
   /** Accessible name for the spinner. Say what is loading. */
   label?: string
 }
 
-/** A spinner on its own — `variant="page"` centres it in a generous block, `'section'` is bare. */
+/** A spinner on its own — `tier="page"` centres it in a generous block, `'section'` is bare. */
 export function LoadingState({
-  variant = 'page',
+  tier,
+  variant,
   label = 'Loading',
+  className,
+  style,
 }: LoadingStateProps): ReactNode {
-  const loader = <Loader size="sm" aria-label={label} />
-  if (variant === 'section') return loader
-  return <Center py={64}>{loader}</Center>
+  const resolved = tier ?? variant ?? 'page'
+  if (resolved === 'section') {
+    return (
+      <Loader
+        size="sm"
+        aria-label={label}
+        {...(className !== undefined && { className })}
+        {...(style !== undefined && { style })}
+      />
+    )
+  }
+  // Same page-level vertical inset `EmptyState`'s `'page'` variant uses (`empty-state.tsx`'s
+  // `PAGE_PADDING_Y`) — the finest density-tracking rhythm step scaled by an exact integer, so this
+  // renders at today's 64px at level 0 and tracks every other density level with it.
+  return (
+    <Center
+      {...(className !== undefined && { className })}
+      style={{ paddingBlock: 'calc(var(--vx-space-stack-xs, 0.25rem) * 16)', ...style }}
+    >
+      <Loader size="sm" aria-label={label} />
+    </Center>
+  )
 }
 
 // ── ErrorState ────────────────────────────────────────────────────────────────────────────────────
 
-export type ErrorStateProps = {
+export type ErrorStateProps = BasaltProps & {
   /** Whatever was thrown — the raw Eden/fetch envelope is fine, it gets decoded. */
   error: unknown
   /** Alert heading. Say what failed, e.g. `Could not load images`. */
@@ -82,7 +111,10 @@ export type ErrorStateProps = {
   onRetry?: () => void
   /** Disables/spins the retry button while a refetch is in flight. */
   retrying?: boolean
-  variant?: QueryStateVariant
+  /** How loud this state is. Default `'page'`. */
+  tier?: QueryStateTier
+  /** @deprecated Renamed to `tier` — see {@link QueryStateTier}. Still honoured; `tier` wins. */
+  variant?: QueryStateTier
   /** Extra controls beside Retry (e.g. a "Back to shares" link). */
   action?: ReactNode
 }
@@ -97,11 +129,21 @@ export function ErrorState({
   fallback = 'The request failed.',
   onRetry,
   retrying = false,
-  variant = 'page',
+  tier,
+  variant,
   action,
+  className,
+  style,
 }: ErrorStateProps): ReactNode {
+  const resolved = tier ?? variant ?? 'page'
   const alert = (
-    <Alert color="red" variant="light" title={title}>
+    <Alert
+      color="red"
+      variant="light"
+      title={title}
+      {...(resolved === 'section' && className !== undefined && { className })}
+      {...(resolved === 'section' && style !== undefined && { style })}
+    >
       <Stack gap="sm">
         <Text size="sm">{toErrorMessage(error, fallback)}</Text>
         {(onRetry ?? action) !== undefined && (
@@ -117,8 +159,16 @@ export function ErrorState({
       </Stack>
     </Alert>
   )
-  if (variant === 'section') return alert
-  return <Stack py="md">{alert}</Stack>
+  if (resolved === 'section') return alert
+  return (
+    <Stack
+      py="md"
+      {...(className !== undefined && { className })}
+      {...(style !== undefined && { style })}
+    >
+      {alert}
+    </Stack>
+  )
 }
 
 // ── QueryState ────────────────────────────────────────────────────────────────────────────────────
@@ -133,51 +183,40 @@ function defaultIsEmpty(data: unknown): boolean {
   return false
 }
 
-const FETCH_STATUSES = new Set(['fetching', 'paused', 'idle'])
-
 /**
- * `QueryStateLike` is a structural subset, so TypeScript cannot protect a hand-composed result the
- * way it protects a real `UseQueryResult` — and every field it drops fails SILENTLY in the exact
- * direction this component exists to prevent. A missing `isError` renders "no data" over a 500. A
- * misspelled `fetchStatus` never leaves the spinner. A missing `refetch` renders a Retry button
- * that does nothing. Each of those is a false claim about the data, so it throws.
+ * ONE slot, and the single-member union is the statement (`common/props.ts` lists this among the
+ * composites): `root` is whichever branch is live — the error alert's stack, the spinner's centre,
+ * the empty state, or the cached-data wrapper. `QueryState` renders exactly one of them at a time
+ * and never two boxes at once, so there is no second slot to name; `className` and `classNames.root`
+ * both land on it, joined rather than one replacing the other.
+ *
+ * A branch a consumer wants styled DIFFERENTLY from its siblings is `LoadingState`/`ErrorState`/
+ * `EmptyState` placed by hand — that escape hatch is why they ship.
  */
-function assertQueryStateLike(query: unknown): asserts query is QueryStateLike<unknown> {
-  const bad = (detail: string): never => {
-    throw new Error(
-      `QueryState: \`query\` ${detail}. It must carry { data, isError, error, fetchStatus, refetch } — ` +
-        'a TanStack UseQueryResult does; a hand-composed one must spell every field, because a ' +
-        'missing branch flag renders a false claim about the data instead of an error.',
-    )
-  }
-  if (query === null || typeof query !== 'object')
-    bad(`is ${query === null ? 'null' : typeof query}`)
-  const q = query as Record<string, unknown>
-  if (!('data' in q)) bad('has no `data` key')
-  if (typeof q['isError'] !== 'boolean') bad('has no boolean `isError`')
-  if (typeof q['fetchStatus'] !== 'string' || !FETCH_STATUSES.has(q['fetchStatus']))
-    bad(`has fetchStatus=${JSON.stringify(q['fetchStatus'])}, not 'fetching' | 'paused' | 'idle'`)
-  if (typeof q['refetch'] !== 'function') bad('has no `refetch()`')
-}
+export type QueryStateSlot = 'root'
 
-export type QueryStateProps<TData> = {
-  query: QueryStateLike<TData>
-  /** A render function gets `data` narrowed to non-undefined; a plain node also works. */
-  children: ReactNode | ((data: TData) => ReactNode)
-  /** Omit to render nothing when the result is empty. */
-  empty?: QueryEmptyCopy
-  /** Override the default `[]` / `{ data: [] }` emptiness test — `() => false` disables it. */
-  isEmpty?: (data: TData) => boolean
-  /** Alert heading on the error branch — say what failed. */
-  errorTitle?: string
-  /** Shown only when the server body carries no readable message. */
-  errorFallback?: string
-  /** Extra controls beside Retry on the error branch. */
-  errorAction?: ReactNode
-  variant?: QueryStateVariant
-  /** Replace the default spinner (e.g. with a skeleton grid). */
-  loading?: ReactNode
-}
+export type QueryStateProps<TData> = BasaltProps &
+  SlotStylesProps<QueryStateSlot> & {
+    query: QueryStateLike<TData>
+    /** A render function gets `data` narrowed to non-undefined; a plain node also works. */
+    children: ReactNode | ((data: TData) => ReactNode)
+    /** Omit to render nothing when the result is empty. */
+    empty?: QueryEmptyCopy
+    /** Override the default `[]` / `{ data: [] }` emptiness test — `() => false` disables it. */
+    isEmpty?: (data: TData) => boolean
+    /** Alert heading on the error branch — say what failed. */
+    errorTitle?: string
+    /** Shown only when the server body carries no readable message. */
+    errorFallback?: string
+    /** Extra controls beside Retry on the error branch. */
+    errorAction?: ReactNode
+    /** How loud every branch is. Default `'page'`. */
+    tier?: QueryStateTier
+    /** @deprecated Renamed to `tier` — see {@link QueryStateTier}. Still honoured; `tier` wins. */
+    variant?: QueryStateTier
+    /** Replace the default spinner (e.g. with a skeleton grid). */
+    loading?: ReactNode
+  }
 
 /**
  * Renders loading / error-with-retry / empty / children for a query result, in that order.
@@ -206,10 +245,19 @@ export function QueryState<TData>({
   errorTitle = 'Could not load',
   errorFallback = 'The request failed.',
   errorAction,
-  variant = 'page',
+  tier,
+  variant,
   loading,
+  className,
+  style,
+  classNames,
 }: QueryStateProps<TData>): ReactNode {
-  assertQueryStateLike(query)
+  assertQueryStateLike('QueryState', query)
+  const resolvedTier = tier ?? variant ?? 'page'
+  // One class for every branch — see {@link QueryStateSlot}. `cx` returns `''` when both are
+  // absent, and an empty `className` on a branch that previously carried none would be a DOM diff,
+  // so it collapses back to `undefined`.
+  const rootClassName = cx(classNames?.root, className) || undefined
   const { data, isError, error, fetchStatus } = query
   const retrying = fetchStatus === 'fetching'
   const retry = (): void => void query.refetch()
@@ -222,21 +270,32 @@ export function QueryState<TData>({
         fallback={errorFallback}
         onRetry={retry}
         retrying={retrying}
-        variant={variant}
+        tier={resolvedTier}
         {...(errorAction !== undefined && { action: errorAction })}
+        {...(rootClassName !== undefined && { className: rootClassName })}
+        {...(style !== undefined && { style })}
       />
     )
   }
 
   if (data === undefined) {
-    if (fetchStatus === 'idle' && !isError) return empty ? renderEmpty(empty, variant) : null
-    return loading ?? <LoadingState variant={variant} />
+    if (fetchStatus === 'idle' && !isError)
+      return empty ? renderEmpty(empty, resolvedTier, rootClassName, style) : null
+    return (
+      loading ?? (
+        <LoadingState
+          tier={resolvedTier}
+          {...(rootClassName !== undefined && { className: rootClassName })}
+          {...(style !== undefined && { style })}
+        />
+      )
+    )
   }
 
   const emptyNow = isEmpty ? isEmpty(data) : defaultIsEmpty(data)
   const body = emptyNow
     ? empty
-      ? renderEmpty(empty, variant)
+      ? renderEmpty(empty, resolvedTier, rootClassName, style)
       : null
     : typeof children === 'function'
       ? children(data)
@@ -245,28 +304,39 @@ export function QueryState<TData>({
   if (!isError) return body
 
   return (
-    <Stack gap="sm">
+    <Stack
+      gap="sm"
+      {...(rootClassName !== undefined && { className: rootClassName })}
+      {...(style !== undefined && { style })}
+    >
       <ErrorState
         error={error}
         title="Showing cached data"
         fallback="The last refresh failed."
         onRetry={retry}
         retrying={retrying}
-        variant="section"
+        tier="section"
       />
       {body}
     </Stack>
   )
 }
 
-function renderEmpty(empty: QueryEmptyCopy, variant: QueryStateVariant): ReactNode {
+function renderEmpty(
+  empty: QueryEmptyCopy,
+  tier: QueryStateTier,
+  className?: string,
+  style?: CSSProperties,
+): ReactNode {
   return (
     <EmptyState
       title={empty.title}
-      variant={variant}
+      tier={tier}
       {...(empty.description !== undefined && { description: empty.description })}
       {...(empty.icon !== undefined && { icon: empty.icon })}
       {...(empty.action !== undefined && { action: empty.action })}
+      {...(className !== undefined && { className })}
+      {...(style !== undefined && { style })}
     />
   )
 }

package/src/dashboard/settings-section.tsx

@@ -31,8 +31,11 @@
 import { Card, Stack } from '@mantine/core'
 import type { ReactNode } from 'react'
 import { WidgetHeader } from '../widget-header'
+import type { WidgetHeaderTitleProps } from '../widget-header'
 import { CtlSlot } from '../theme'
 import { alpha, VX } from '../tokens'
+import { cx } from '../common/props'
+import type { BasaltProps, SlotStylesProps } from '../common/props'
 import classes from './settings-section.module.css'
 
 const eyebrowStyle = {
@@ -44,78 +47,131 @@ const eyebrowStyle = {
   color: VX.status.bad,
 }
 
-export type SettingsSectionProps = {
-  /** Head-font section title, rendered via `WidgetHeader tier="section"`. */
-  title: string
-  /** Optional 13px muted description below the title. */
-  subtitle?: string
-  /** Header-right slot — wrapped in `CtlSlot` (C1/C5). */
-  actions?: ReactNode
-  /** Section body — typically a stack of `SettingsRow`s. */
-  children: ReactNode
-}
+/** The three boxes `SettingsSection`/`DangerZone` paint (`common/props.ts`). */
+export type SettingsSectionSlot = 'root' | 'header' | 'body'
+
+/**
+ * Composed from the named `WidgetHeaderTitleProps` slice (audit B #2) rather than a hand-picked
+ * `title`/`subtitle` pair — which is why `icon` and `info` now reach the header too. `value`/`delta`
+ * are deliberately NOT taken: a settings section groups controls, it states no metric.
+ *
+ * `Section` and `ChartCard` still cut their own ad-hoc subsets; both should move onto the same
+ * slices.
+ */
+export type SettingsSectionProps = BasaltProps &
+  SlotStylesProps<SettingsSectionSlot> &
+  WidgetHeaderTitleProps & {
+    /** Header-right slot — wrapped in `CtlSlot` (C1/C5). */
+    actions?: ReactNode
+    /** Section body — typically a stack of `SettingsRow`s. */
+    children: ReactNode
+  }
 
-export function SettingsSection({ title, subtitle, actions, children }: SettingsSectionProps) {
+export function SettingsSection({
+  title,
+  icon,
+  subtitle,
+  info,
+  actions,
+  children,
+  className,
+  style,
+  classNames,
+}: SettingsSectionProps) {
   return (
-    <Card style={{ padding: 'var(--mantine-spacing-xs) var(--mantine-spacing-sm)' }}>
-      <div className={classes.header}>
+    <Card
+      className={cx(classNames?.root, className)}
+      style={{ padding: 'var(--mantine-spacing-xs) var(--mantine-spacing-sm)', ...style }}
+    >
+      <div className={cx(classes.header, classNames?.header)}>
         <WidgetHeader
           tier="section"
           title={title}
+          {...(icon !== undefined && { icon })}
           {...(subtitle !== undefined && { subtitle })}
+          {...(info !== undefined && { info })}
           {...(actions !== undefined && { actions: <CtlSlot>{actions}</CtlSlot> })}
         />
       </div>
-      <div className={classes.rows}>{children}</div>
+      <div className={cx(classes.rows, classNames?.body)}>{children}</div>
     </Card>
   )
 }
 
-export type SettingsRowProps = {
-  /** 13px ink label on the left. */
-  label: string
-  /** Optional 12.5px muted description under the label. */
-  description?: string
-  /** Right-aligned control (input/switch/button). */
-  control?: ReactNode
-  /** Alternative to `control` for a fully custom right-hand region. */
-  children?: ReactNode
-}
+/** The three boxes `SettingsRow` paints (`common/props.ts`). */
+export type SettingsRowSlot = 'root' | 'label' | 'control'
 
-export function SettingsRow({ label, description, control, children }: SettingsRowProps) {
+export type SettingsRowProps = BasaltProps &
+  SlotStylesProps<SettingsRowSlot> & {
+    /** 13px ink label on the left. */
+    label: string
+    /** Optional 12.5px muted description under the label. */
+    description?: string
+    /** Right-aligned control (input/switch/button). */
+    control?: ReactNode
+    /** Alternative to `control` for a fully custom right-hand region. */
+    children?: ReactNode
+  }
+
+export function SettingsRow({
+  label,
+  description,
+  control,
+  children,
+  className,
+  style,
+  classNames,
+}: SettingsRowProps) {
   return (
-    <div className={classes.row}>
-      <Stack gap={2}>
+    <div
+      className={cx(classes.row, classNames?.root, className)}
+      {...(style !== undefined && { style })}
+    >
+      <Stack gap={2} {...(classNames?.label !== undefined && { className: classNames.label })}>
         <span style={{ fontSize: VX.text.md, color: VX.ink }}>{label}</span>
         {description && (
           <span style={{ fontSize: VX.text.sm, color: VX.muted }}>{description}</span>
         )}
       </Stack>
-      <div className={classes.control}>{control ?? children}</div>
+      <div className={cx(classes.control, classNames?.control)}>{control ?? children}</div>
     </div>
   )
 }
 
 export type DangerZoneProps = SettingsSectionProps
 
-export function DangerZone({ title, subtitle, actions, children }: DangerZoneProps) {
+export function DangerZone({
+  title,
+  icon,
+  subtitle,
+  info,
+  actions,
+  children,
+  className,
+  style,
+  classNames,
+}: DangerZoneProps) {
   return (
     <Card
+      className={cx(classNames?.root, className)}
       style={{
         padding: 'var(--mantine-spacing-xs) var(--mantine-spacing-sm)',
         boxShadow: `${VX.shadowCard}, 0 0 0 1px ${alpha(VX.status.bad, 0.25)}`,
+        ...style,
       }}
     >
-      <div className={classes.header}>
+      <div className={cx(classes.header, classNames?.header)}>
         <span style={eyebrowStyle}>Danger Zone</span>
         <WidgetHeader
           tier="section"
           title={title}
+          {...(icon !== undefined && { icon })}
           {...(subtitle !== undefined && { subtitle })}
+          {...(info !== undefined && { info })}
           {...(actions !== undefined && { actions: <CtlSlot>{actions}</CtlSlot> })}
         />
       </div>
-      <div className={classes.rows}>{children}</div>
+      <div className={cx(classes.rows, classNames?.body)}>{children}</div>
     </Card>
   )
 }