basalt-ui 1.26.0 → 1.28.0

package/src/dashboard/empty-state.tsx

@@ -1,8 +1,8 @@
 /**
  * EmptyState — a centered icon/title/description/action stack for empty data regions (no shipped
- * illustration assets — `icon` is a plain, faint-rendered `ReactNode` slot). `variant="page"` uses
- * generous vertical padding for a full-page empty state; `variant="section"` is compact, for an
- * empty card/panel region.
+ * illustration assets — `icon` is a plain, faint-rendered `ReactNode` slot). `tier="page"` uses
+ * generous vertical padding for a full-page empty state; `tier="section"` is compact, for an
+ * empty card/panel region (`variant` is the deprecated spelling of the same prop — audit B #19).
  *
  * @example
  * import { EmptyState } from 'basalt-ui'
@@ -12,48 +12,89 @@
  *   title="No results"
  *   description="Try adjusting your filters or search terms."
  *   action={<Button onClick={onReset}>Clear filters</Button>}
- *   variant="section"
+ *   tier="section"
  * />
  */
 import { Center, Stack } from '@mantine/core'
 import type { ReactNode } from 'react'
 import { VX } from '../tokens'
+import { cx } from '../common/props'
+import type { BasaltProps, SlotStylesProps } from '../common/props'
 
-export type EmptyStateProps = {
-  /** Optional glyph slot, rendered faint at ~28-32px. No shipped illustration assets. */
-  icon?: ReactNode
-  /** Head-font title (18px, weight 550, ink). */
-  title: string
-  /**
-   * Muted 15px description, capped at ~360px so it reads as a short explanation. Optional: a
-   * compact panel ("No data yet") should not have to invent a second sentence, and five argo
-   * features wrapped this component solely to avoid doing so.
-   */
-  description?: string
-  /** Optional call-to-action rendered below the description. */
-  action?: ReactNode
-  /** `'page'` (default) = generous padding for a full-page state; `'section'` = compact. */
-  variant?: 'page' | 'section'
-}
+/** The five boxes `EmptyState` paints, and the whole styling seam it offers (`common/props.ts`). */
+export type EmptyStateSlot = 'root' | 'icon' | 'title' | 'description' | 'action'
+
+export type EmptyStateProps = BasaltProps &
+  SlotStylesProps<EmptyStateSlot> & {
+    /** Optional glyph slot, rendered faint at ~28-32px. No shipped illustration assets. */
+    icon?: ReactNode
+    /** Head-font title (18px, weight 550, ink). */
+    title: string
+    /**
+     * Muted 15px description, capped at ~360px so it reads as a short explanation. Optional: a
+     * compact panel ("No data yet") should not have to invent a second sentence, and five argo
+     * features wrapped this component solely to avoid doing so.
+     */
+    description?: string
+    /** Optional call-to-action rendered below the description. */
+    action?: ReactNode
+    /** How loud this state is: `'page'` (default) = generous padding for a full-page state;
+     * `'section'` = compact. */
+    tier?: 'page' | 'section'
+    /** @deprecated Renamed to `tier` (audit B #19) — `tier` is the package's word for "how loud is
+     * this". Still honoured; `tier` wins when both are passed. */
+    variant?: 'page' | 'section'
+  }
+
+// The finest density-tracking rhythm step (`--vx-space-stack-xs`, 4px at level 0) scaled by an
+// exact integer, so the padding renders at today's px value at level 0 and rides the same
+// `1 + 0.1 * level` multiplier every other `--vx-space-*` token does at every other density level
+// (`docs/STATUS.md`'s density pass) — `LoadingState`'s `'page'` variant shares `PAGE_PADDING_Y`,
+// same concept: a page-level async/empty region's vertical padding.
+const STACK_XS = 'var(--vx-space-stack-xs, 0.25rem)'
+const PAGE_PADDING_Y = `calc(${STACK_XS} * 16)` // 64px at level 0
+const PAGE_PADDING_X = `calc(${STACK_XS} * 6)` // 24px at level 0
+const SECTION_PADDING_Y = `calc(${STACK_XS} * 8)` // 32px at level 0
+const SECTION_PADDING_X = `calc(${STACK_XS} * 5)` // 20px at level 0
 
 export function EmptyState({
   icon,
   title,
   description,
   action,
-  variant = 'page',
+  tier,
+  variant,
+  className,
+  style,
+  classNames,
 }: EmptyStateProps) {
+  const resolved = tier ?? variant ?? 'page'
   return (
     <Stack
       align="center"
       gap="xs"
+      className={cx(classNames?.root, className)}
       style={{
-        padding: variant === 'page' ? '64px 24px' : '32px 20px',
+        padding:
+          resolved === 'page'
+            ? `${PAGE_PADDING_Y} ${PAGE_PADDING_X}`
+            : `${SECTION_PADDING_Y} ${SECTION_PADDING_X}`,
         textAlign: 'center',
+        ...style,
       }}
     >
-      {icon && <Center style={{ width: 32, height: 32, color: VX.faint }}>{icon}</Center>}
+      {icon && (
+        // 32px is a fixed glyph-box size, not a density-tracking inset — no `--vx-icon-*` token
+        // exists for a generic (non-`WidgetHeader`-tiered) icon slot, so it stays a structural rem.
+        <Center
+          {...(classNames?.icon !== undefined && { className: classNames.icon })}
+          style={{ width: '2rem', height: '2rem', color: VX.faint }}
+        >
+          {icon}
+        </Center>
+      )}
       <span
+        className={classNames?.title}
         style={{
           fontFamily: 'var(--basalt-font-head)',
           fontStretch: '88%',
@@ -65,9 +106,15 @@ export function EmptyState({
         {title}
       </span>
       {description !== undefined && (
-        <span style={{ fontSize: VX.text.md, color: VX.muted, maxWidth: 360 }}>{description}</span>
+        // 360px (22.5rem) is a reading-width cap, not a density inset — kept structural.
+        <span
+          className={classNames?.description}
+          style={{ fontSize: VX.text.md, color: VX.muted, maxWidth: '22.5rem' }}
+        >
+          {description}
+        </span>
       )}
-      {action}
+      {action !== undefined && <div className={classNames?.action}>{action}</div>}
     </Stack>
   )
 }

package/src/dashboard/index.ts

@@ -1,11 +1,26 @@
 export { DeltaBadge, type DeltaBadgeProps } from './delta-badge'
-export { StatCard, type StatCardProps, type StatCardTone } from './stat-card'
-export { EmptyState, type EmptyStateProps } from './empty-state'
+export {
+  StatCard,
+  type StatCardBreakdownRow,
+  type StatCardProps,
+  type StatCardSlot,
+  type StatCardTone,
+} from './stat-card'
+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'
@@ -13,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 })}
     />
   )
 }