basalt-ui 1.23.1 → 1.25.0

package/src/dashboard/index.ts

@@ -9,3 +9,14 @@ export {
   DangerZone,
   type DangerZoneProps,
 } from './settings-section'
+export {
+  QueryState,
+  type QueryStateProps,
+  type QueryStateLike,
+  type QueryStateVariant,
+  type QueryEmptyCopy,
+  LoadingState,
+  type LoadingStateProps,
+  ErrorState,
+  type ErrorStateProps,
+} from './query-state'

package/src/dashboard/query-state.test.tsx

@@ -0,0 +1,152 @@
+/**
+ * `QueryState` exists because shipping only `EmptyState` produced a correctness bug in a real
+ * consumer: a 500 rendered "No images", a dropped connection rendered "Share not found — it may
+ * have been deleted". Every assertion here is aimed at that failure mode rather than at chrome.
+ *
+ *  1. A FAILED query never renders the empty copy. This is the bug, stated as a test.
+ *  2. A failed query WITH cached data keeps the page and adds a banner — a background refetch
+ *     failing must not blank a screen that already works.
+ *  3. `fetchStatus: 'idle'` with no data is EMPTY, not loading (the `enabled: false` case);
+ *     `'fetching'` with no data is loading.
+ *  4. A result missing a branch flag THROWS. `QueryStateLike` is a structural subset on purpose,
+ *     so the compiler stops policing it — and every field it can lose fails silently in the
+ *     direction of a false claim about the data.
+ */
+import { MantineProvider } from '@mantine/core'
+import { render, screen } from '@testing-library/react'
+import { describe, expect, test } from 'bun:test'
+import type { ReactNode } from 'react'
+import { QueryState } from './query-state'
+import type { QueryStateLike } from './query-state'
+
+type Row = { id: number }
+
+function result(over: Partial<QueryStateLike<Row[]>>): QueryStateLike<Row[]> {
+  return {
+    data: undefined,
+    isError: false,
+    error: null,
+    fetchStatus: 'idle',
+    refetch: () => undefined,
+    ...over,
+  }
+}
+
+const EMPTY = { title: 'No images match', description: 'Widen the capture dates.' }
+
+function renderState(query: QueryStateLike<Row[]>, extra?: ReactNode): HTMLElement {
+  const { container } = render(
+    <MantineProvider>
+      <QueryState query={query} empty={EMPTY} errorTitle="Could not load images">
+        {(rows) => <div data-testid="body">{rows.length} rows</div>}
+      </QueryState>
+      {extra}
+    </MantineProvider>,
+  )
+  return container
+}
+
+describe('the branch a 500 must not take', () => {
+  test('an errored query renders the server message, never the empty copy', () => {
+    renderState(
+      result({ isError: true, error: { status: 500, value: { message: 'index is rebuilding' } } }),
+    )
+    expect(screen.getByText('index is rebuilding')).toBeTruthy()
+    expect(screen.queryByText('No images match')).toBeNull()
+    expect(screen.getByRole('button', { name: 'Retry' })).toBeTruthy()
+  })
+
+  test('an opaque 500 envelope falls back to the errorTitle copy plus the status', () => {
+    render(
+      <MantineProvider>
+        <QueryState
+          query={result({ isError: true, error: { status: 500, value: {} } })}
+          errorTitle="Could not load images"
+          errorFallback="The library did not answer."
+        >
+          {() => null}
+        </QueryState>
+      </MantineProvider>,
+    )
+    expect(screen.getByText('The library did not answer. (HTTP 500)')).toBeTruthy()
+  })
+
+  test('retry calls refetch', () => {
+    let calls = 0
+    renderState(result({ isError: true, error: new Error('down'), refetch: () => ++calls }))
+    ;(screen.getByRole('button', { name: 'Retry' }) as HTMLButtonElement).click()
+    expect(calls).toBe(1)
+  })
+})
+
+describe('cached data survives a failed refresh', () => {
+  test('error WITH data renders the body plus a banner, not the error page', () => {
+    renderState(result({ data: [{ id: 1 }], isError: true, error: new Error('refresh failed') }))
+    expect(screen.getByTestId('body').textContent).toBe('1 rows')
+    expect(screen.getByText('Showing cached data')).toBeTruthy()
+  })
+})
+
+describe('empty vs loading', () => {
+  test('no data + idle is EMPTY (the enabled:false case)', () => {
+    renderState(result({ fetchStatus: 'idle' }))
+    expect(screen.getByText('No images match')).toBeTruthy()
+  })
+
+  test('no data + fetching is LOADING', () => {
+    renderState(result({ fetchStatus: 'fetching' }))
+    expect(screen.queryByText('No images match')).toBeNull()
+    expect(screen.getByLabelText('Loading')).toBeTruthy()
+  })
+
+  test('an empty array is empty; a populated one renders children', () => {
+    renderState(result({ data: [] }))
+    expect(screen.getByText('No images match')).toBeTruthy()
+  })
+
+  test('isEmpty overrides the default test', () => {
+    render(
+      <MantineProvider>
+        <QueryState query={result({ data: [] })} empty={EMPTY} isEmpty={() => false}>
+          {(rows) => <div data-testid="body">{rows.length} rows</div>}
+        </QueryState>
+      </MantineProvider>,
+    )
+    expect(screen.getByTestId('body').textContent).toBe('0 rows')
+  })
+
+  test('omitting `empty` renders nothing rather than inventing copy', () => {
+    render(
+      <MantineProvider>
+        <QueryState query={result({ data: [] })}>{() => <div>rows</div>}</QueryState>
+      </MantineProvider>,
+    )
+    expect(screen.queryByText('rows')).toBeNull()
+  })
+})
+
+describe('a malformed result throws instead of asserting absence', () => {
+  const cases: [string, unknown][] = [
+    ['missing isError', { data: undefined, error: null, fetchStatus: 'idle', refetch: () => 0 }],
+    [
+      'misspelled fetchStatus',
+      { data: undefined, isError: false, error: null, fetchStatus: 'pending', refetch: () => 0 },
+    ],
+    ['missing refetch', { data: undefined, isError: false, error: null, fetchStatus: 'idle' }],
+    ['not an object at all', ['a', 'b']],
+  ]
+
+  for (const [name, bad] of cases) {
+    test(name, () => {
+      expect(() =>
+        render(
+          <MantineProvider>
+            <QueryState query={bad as QueryStateLike<Row[]>} empty={EMPTY}>
+              {() => null}
+            </QueryState>
+          </MantineProvider>,
+        ),
+      ).toThrow(/QueryState: `query`/)
+    })
+  }
+})

package/src/dashboard/query-state.tsx

@@ -0,0 +1,272 @@
+/**
+ * QueryState — the one wrapper a page puts around an async result, and the sibling `EmptyState`
+ * shipped without.
+ *
+ * The argument is correctness, not convenience. A framework that ships only the EMPTY branch
+ * steers every consumer into rendering "nothing here" for "the server failed": image-share's
+ * library rendered *No images* on a 500, and a share detail rendered *Share not found — it may
+ * have been deleted* on a dropped connection, until 204 hand-rolled lines were written to stop it.
+ * basalt already owned both ends of that file — `EmptyState` and `toErrorMessage` — and nothing in
+ * between.
+ *
+ * Component, not a hook: the product IS the branch precedence below. A hook returning
+ * `{ status, data }` would hand every call site the same four-way switch back, which is exactly
+ * the re-derivation this exists to delete. `LoadingState` / `ErrorState` ship alongside as the
+ * 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 { toErrorMessage } from '../query/error-message'
+import { EmptyState } from './empty-state'
+
+/** `'page'` = a full route body (generous padding). `'section'` = a card/panel region (compact). */
+export type QueryStateVariant = 'page' | 'section'
+
+/**
+ * The structural subset of a TanStack `UseQueryResult` these components read.
+ *
+ * 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.
+ */
+export type QueryStateLike<TData> = {
+  data: TData | undefined
+  isError: boolean
+  error: unknown
+  fetchStatus: 'fetching' | 'paused' | 'idle'
+  refetch: () => unknown
+}
+
+/** Copy for the empty branch. Rendered through `EmptyState`, so it looks like every other one. */
+export type QueryEmptyCopy = {
+  title: string
+  /** Optional — a one-word empty panel should not have to invent a sentence. */
+  description?: string
+  /** Optional glyph slot, rendered faint. */
+  icon?: ReactNode
+  /** Call-to-action below the copy (e.g. "Reset filters"). */
+  action?: ReactNode
+}
+
+// ── LoadingState ──────────────────────────────────────────────────────────────────────────────────
+
+export type LoadingStateProps = {
+  variant?: QueryStateVariant
+  /** 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. */
+export function LoadingState({
+  variant = 'page',
+  label = 'Loading',
+}: LoadingStateProps): ReactNode {
+  const loader = <Loader size="sm" aria-label={label} />
+  if (variant === 'section') return loader
+  return <Center py={64}>{loader}</Center>
+}
+
+// ── ErrorState ────────────────────────────────────────────────────────────────────────────────────
+
+export type ErrorStateProps = {
+  /** 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`. */
+  title?: string
+  /** Shown only when the server body carries no readable message. */
+  fallback?: string
+  onRetry?: () => void
+  /** Disables/spins the retry button while a refetch is in flight. */
+  retrying?: boolean
+  variant?: QueryStateVariant
+  /** Extra controls beside Retry (e.g. a "Back to shares" link). */
+  action?: ReactNode
+}
+
+/**
+ * The error branch: the REAL server message (via `toErrorMessage`) plus a retry. Usable on its own,
+ * outside a query — an auth gate or a boundary fallback renders it directly.
+ */
+export function ErrorState({
+  error,
+  title = 'Something went wrong',
+  fallback = 'The request failed.',
+  onRetry,
+  retrying = false,
+  variant = 'page',
+  action,
+}: ErrorStateProps): ReactNode {
+  const alert = (
+    <Alert color="red" variant="light" title={title}>
+      <Stack gap="sm">
+        <Text size="sm">{toErrorMessage(error, fallback)}</Text>
+        {(onRetry ?? action) !== undefined && (
+          <Group gap="xs">
+            {onRetry && (
+              <Button size="xs" variant="default" loading={retrying} onClick={onRetry}>
+                Retry
+              </Button>
+            )}
+            {action}
+          </Group>
+        )}
+      </Stack>
+    </Alert>
+  )
+  if (variant === 'section') return alert
+  return <Stack py="md">{alert}</Stack>
+}
+
+// ── QueryState ────────────────────────────────────────────────────────────────────────────────────
+
+/** `[]`, `{ data: [], total }` (the common pagination envelope) and null all count as empty. */
+function defaultIsEmpty(data: unknown): boolean {
+  if (data === null || data === undefined) return true
+  if (Array.isArray(data)) return data.length === 0
+  if (typeof data === 'object' && Array.isArray((data as { data?: unknown }).data)) {
+    return (data as { data: unknown[] }).data.length === 0
+  }
+  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.
+ */
+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 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
+}
+
+/**
+ * Renders loading / error-with-retry / empty / children for a query result, in that order.
+ * Branch precedence is the whole point, and it is deliberate:
+ *
+ *  - error AND no cached data → the full error state (the page cannot render)
+ *  - error WITH cached data   → children, plus a compact "showing cached data" banner on top
+ *    (a background refetch failing must not blank a page that already works)
+ *  - no data, fetch idle      → empty (this is an `enabled: false` query, not a pending one)
+ *  - no data, fetching        → `loading` (or the default spinner)
+ *
+ * @example
+ * <QueryState
+ *   query={q}
+ *   errorTitle="Could not load images"
+ *   empty={{ title: 'No images match', description: 'Widen the capture dates.' }}
+ * >
+ *   {(data) => <ImageGrid images={data.rows} />}
+ * </QueryState>
+ */
+export function QueryState<TData>({
+  query,
+  children,
+  empty,
+  isEmpty,
+  errorTitle = 'Could not load',
+  errorFallback = 'The request failed.',
+  errorAction,
+  variant = 'page',
+  loading,
+}: QueryStateProps<TData>): ReactNode {
+  assertQueryStateLike(query)
+  const { data, isError, error, fetchStatus } = query
+  const retrying = fetchStatus === 'fetching'
+  const retry = (): void => void query.refetch()
+
+  if (isError && data === undefined) {
+    return (
+      <ErrorState
+        error={error}
+        title={errorTitle}
+        fallback={errorFallback}
+        onRetry={retry}
+        retrying={retrying}
+        variant={variant}
+        {...(errorAction !== undefined && { action: errorAction })}
+      />
+    )
+  }
+
+  if (data === undefined) {
+    if (fetchStatus === 'idle' && !isError) return empty ? renderEmpty(empty, variant) : null
+    return loading ?? <LoadingState variant={variant} />
+  }
+
+  const emptyNow = isEmpty ? isEmpty(data) : defaultIsEmpty(data)
+  const body = emptyNow
+    ? empty
+      ? renderEmpty(empty, variant)
+      : null
+    : typeof children === 'function'
+      ? children(data)
+      : children
+
+  if (!isError) return body
+
+  return (
+    <Stack gap="sm">
+      <ErrorState
+        error={error}
+        title="Showing cached data"
+        fallback="The last refresh failed."
+        onRetry={retry}
+        retrying={retrying}
+        variant="section"
+      />
+      {body}
+    </Stack>
+  )
+}
+
+function renderEmpty(empty: QueryEmptyCopy, variant: QueryStateVariant): ReactNode {
+  return (
+    <EmptyState
+      title={empty.title}
+      variant={variant}
+      {...(empty.description !== undefined && { description: empty.description })}
+      {...(empty.icon !== undefined && { icon: empty.icon })}
+      {...(empty.action !== undefined && { action: empty.action })}
+    />
+  )
+}