basalt-ui 1.23.0 → 1.24.0

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 (3 of image-share's 10 call sites are), 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 })}
+    />
+  )
+}

package/src/data/data-table.test.tsx

@@ -0,0 +1,158 @@
+/**
+ * The three body-chrome props argo's round-6/7 feedback kept 341 hand-rolled lines for, asserted
+ * against real markup rather than against props:
+ *
+ *  1. `maxHeight` renders Mantine's NATIVE scroll container — the same node the docs sanction as
+ *     the raw escape. `type="scrollarea"` would silently break a sticky header (ScrollArea's
+ *     viewport becomes the positioning context), so the emitted `--table-max-height` var and the
+ *     absence of a ScrollArea root are both asserted.
+ *  2. `stickyHeader` reaches the `<table>`.
+ *  3. `meta.align` reaches BOTH the `<th>` and the `<td>` — a right-aligned header over
+ *     left-aligned money is the defect this replaces.
+ *  4. A misspelled alignment VALUE throws. The key is a compile error
+ *     (`apps/playground/src/data-table-align.type-guard.ts`); the value can only be caught here,
+ *     and a silent fallback to left-aligned would look correct in review.
+ */
+import { MantineProvider } from '@mantine/core'
+import { render, screen } from '@testing-library/react'
+import { describe, expect, test } from 'bun:test'
+import { BasaltDataTable } from './data-table'
+import { createColumnHelper } from './table'
+import type { BasaltDataTableProps } from './data-table'
+
+type Row = { project: string; cost: number }
+const col = createColumnHelper<Row>()
+
+const ROWS: Row[] = [
+  { project: 'argo', cost: 12 },
+  { project: 'linewatch', cost: 3 },
+]
+
+const COLUMNS = [
+  col.accessor('project', { header: 'Project' }),
+  col.accessor('cost', { header: 'Cost', meta: { align: 'right' } }),
+]
+
+function renderTable(props: Partial<BasaltDataTableProps<Row>> = {}) {
+  return render(
+    <MantineProvider>
+      <BasaltDataTable data={ROWS} columns={COLUMNS} {...props} />
+    </MantineProvider>,
+  )
+}
+
+describe('maxHeight — the capped body', () => {
+  test('no maxHeight renders no scroll container at all', () => {
+    const { container } = renderTable()
+    expect(container.querySelector('.mantine-TableScrollContainer-scrollContainer')).toBeNull()
+  })
+
+  test('maxHeight renders a native scroll container carrying the cap', () => {
+    const { container } = renderTable({ maxHeight: 480 })
+    const scroller = container.querySelector('.mantine-TableScrollContainer-scrollContainer')
+    if (!scroller) throw new Error('expected a Table.ScrollContainer')
+    // Mantine converts px → rem against --mantine-scale; 480 / 16 = 30rem.
+    expect(scroller.getAttribute('style') ?? '').toContain('--table-max-height: calc(30rem')
+    // type="native" — a ScrollArea viewport would be the wrong positioning context for a
+    // sticky <thead>, which is exactly why argo's hand-rolled version spelled the type out.
+    expect(container.querySelector('.mantine-ScrollArea-root')).toBeNull()
+  })
+
+  test('minWidth alone also opens the scroll container', () => {
+    const { container } = renderTable({ minWidth: 640 })
+    const scroller = container.querySelector('.mantine-TableScrollContainer-scrollContainer')
+    if (!scroller) throw new Error('expected a Table.ScrollContainer')
+    expect(scroller.getAttribute('style') ?? '').toContain('--table-min-width: calc(40rem')
+  })
+})
+
+describe('stickyHeader and table chrome', () => {
+  test('stickyHeader reaches the table element', () => {
+    const { container } = renderTable({ maxHeight: 480, stickyHeader: true })
+    expect(container.querySelector('thead')?.getAttribute('data-sticky')).toBe('true')
+    expect(renderTable().container.querySelector('thead')?.getAttribute('data-sticky')).toBeNull()
+  })
+
+  test('withTableBorder defaults on and can be turned off for a table inside a card', () => {
+    expect(
+      renderTable().container.querySelector('table')?.getAttribute('data-with-table-border'),
+    ).toBe('true')
+    expect(
+      renderTable({ withTableBorder: false })
+        .container.querySelector('table')
+        ?.getAttribute('data-with-table-border'),
+    ).toBeNull()
+  })
+})
+
+describe('per-column alignment', () => {
+  test('meta.align lands on the header AND every cell of that column', () => {
+    const { container } = renderTable()
+    const headers = [...container.querySelectorAll('th')]
+    const costHeader = headers.find((th) => th.textContent?.includes('Cost'))
+    expect(costHeader?.getAttribute('style') ?? '').toContain('text-align: right')
+
+    const costCells = [...container.querySelectorAll('tbody tr')].map((tr) => tr.children[1])
+    expect(costCells).toHaveLength(2)
+    for (const cell of costCells) {
+      expect(cell?.getAttribute('style') ?? '').toContain('text-align: right')
+    }
+  })
+
+  test('an unaligned column stays unstyled — the prop is opt-in, not a default', () => {
+    const { container } = renderTable()
+    const projectCell = container.querySelector('tbody tr')?.children[0]
+    expect(projectCell?.getAttribute('style') ?? '').not.toContain('text-align')
+  })
+
+  test('a misspelled alignment value throws rather than quietly left-aligning', () => {
+    const bad = [
+      col.accessor('project', { header: 'Project' }),
+      // The key is compile-checked; the VALUE can only fail here.
+      col.accessor('cost', { header: 'Cost', meta: { align: 'end' as 'right' } }),
+    ]
+    expect(() =>
+      render(
+        <MantineProvider>
+          <BasaltDataTable data={ROWS} columns={bad} />
+        </MantineProvider>,
+      ),
+    ).toThrow(/meta\.align="end"/)
+  })
+})
+
+describe('the auto mono-numeral style has an opt-out', () => {
+  const styled = [
+    col.accessor('project', { header: 'Project' }),
+    col.accessor('cost', { header: 'Cost' }),
+  ]
+  const opted = [
+    col.accessor('project', { header: 'Project' }),
+    col.accessor('cost', { header: 'Cost', meta: { numeral: false } }),
+  ]
+
+  const costStyle = (columns: typeof styled) =>
+    render(
+      <MantineProvider>
+        <BasaltDataTable data={ROWS} columns={columns} />
+      </MantineProvider>,
+    )
+      .container.querySelector('tbody tr')
+      ?.children[1]?.getAttribute('style') ?? ''
+
+  test('a numeric cell is mono by default', () => {
+    expect(costStyle(styled)).toContain('font-family: var(--mantine-font-family-monospace)')
+  })
+
+  test('meta.numeral=false leaves a bespoke cell renderer in charge of its own font', () => {
+    expect(costStyle(opted)).not.toContain('font-family')
+  })
+})
+
+describe('regression — the bare table is unchanged', () => {
+  test('renders rows with no new chrome', () => {
+    renderTable()
+    expect(screen.getByText('argo')).toBeTruthy()
+    expect(screen.getByText('linewatch')).toBeTruthy()
+  })
+})

package/src/data/data-table.tsx

@@ -42,6 +42,7 @@ import {
   Text,
   TextInput,
 } from '@mantine/core'
+import type { MantineSpacing } from '@mantine/core'
 import type {
   Column,
   ColumnDef,
@@ -49,6 +50,7 @@ import type {
   ColumnPinningState,
   FilterFn,
   PaginationState,
+  RowData,
   SortingState,
   Table as TanstackTable,
   Updater,
@@ -65,6 +67,50 @@ import type { CSSProperties, ReactNode } from 'react'
 import { useCallback, useMemo, useState } from 'react'
 import { alpha, VX } from '../tokens'
 
+// ── Column alignment ──────────────────────────────────────────────────────────
+
+/** Horizontal alignment of a column's header AND its cells. */
+export type DataTableAlign = 'left' | 'center' | 'right'
+
+/**
+ * Alignment lives on the column def's `meta`, not on a parallel prop array, so it travels with the
+ * column it describes and survives reordering.
+ *
+ * Declared as a module augmentation of TanStack's own `ColumnMeta` so `meta: { aling: 'right' }` is
+ * a TYPE error (excess-property check on the object literal) rather than a silently ignored key —
+ * and a wrong VALUE (`'end'`, `'centre'`) throws at render. A misspelled alignment that quietly
+ * left-aligns a money column is the class of defect that looks correct in review.
+ */
+declare module '@tanstack/react-table' {
+  // TData/TValue are TanStack's own parameters — required to match its declaration, unused here.
+  // oxlint-disable-next-line no-unused-vars
+  interface ColumnMeta<TData extends RowData, TValue> {
+    align?: DataTableAlign
+    /**
+     * Opt OUT of the automatic mono-numeral cell style. The table applies it whenever the cell's
+     * raw value is a number — which is right for a plain figure and wrong for a numeric accessor
+     * whose `cell` renders its own chrome (a coloured `Text`, a `Badge`, a sparkline), because the
+     * `<td>`'s mono font then overrides what the cell asked for.
+     */
+    numeral?: boolean
+  }
+}
+
+const ALIGNMENTS: ReadonlySet<string> = new Set<DataTableAlign>(['left', 'center', 'right'])
+
+/** Reads `meta.align` off a column, throwing on a value that is not one of the three. */
+function resolveAlign<T>(column: Column<T, unknown>): DataTableAlign | undefined {
+  const align = column.columnDef.meta?.align
+  if (align === undefined) return undefined
+  if (!ALIGNMENTS.has(align)) {
+    throw new Error(
+      `BasaltDataTable: column "${column.id}" has meta.align=${JSON.stringify(align)} — ` +
+        "expected 'left' | 'center' | 'right'.",
+    )
+  }
+  return align
+}
+
 // ── Facets ────────────────────────────────────────────────────────────────────
 
 /** A single selectable option inside a {@link DataTableFacet}'s Select/MultiSelect. */
@@ -129,8 +175,8 @@ export type BasaltDataTableProps<T> = {
    * @default true
    */
   enableSorting?: boolean
-  /** Stripe alternate rows. Forwarded to Mantine `Table`. */
-  striped?: boolean
+  /** Stripe alternate rows. Forwarded to Mantine `Table` — `'odd'`/`'even'` pick the phase. */
+  striped?: boolean | 'odd' | 'even'
   /** Highlight hovered rows. Forwarded to Mantine `Table`. */
   highlightOnHover?: boolean
   /** Rendered when `data` is empty. Falls back to a simple message when omitted. */
@@ -257,6 +303,42 @@ export type BasaltDataTableProps<T> = {
   enablePinning?: boolean
   /** Initial column-pinning state — which column ids stick to the left/right edge. */
   initialColumnPinning?: ColumnPinningState
+
+  // ── Body chrome ─────────────────────────────────────────────────────────────
+
+  /**
+   * Caps the scrolling body (px number or CSS length) so a long table cannot blow a card out
+   * vertically — the header stays put and the rows scroll under it. Renders Mantine's
+   * `Table.ScrollContainer type="native"`, which is the same node the docs sanction as the raw
+   * escape for a bespoke table: the blessed lane and the escape hatch produce identical DOM, so
+   * adopting one does not contradict the other.
+   *
+   * `type="native"` is required rather than preferred: `ScrollArea`'s custom viewport is the
+   * positioning context a sticky `<thead>` resolves against, so the default `'scrollarea'` type
+   * pins the header to the page viewport instead of the table's box.
+   */
+  maxHeight?: number | string
+  /**
+   * `min-width` below which the body scrolls horizontally. Setting either this or `maxHeight`
+   * turns on the scroll container; `maxHeight` alone implies `minWidth: 0`.
+   */
+  minWidth?: number | string
+  /** Sticky header row. Pair with `maxHeight` to stick within the table rather than the page. */
+  stickyHeader?: boolean
+  /** Offset for a sticky header sitting under a fixed app header (px number or CSS length). */
+  stickyHeaderOffset?: number | string
+  /** Vertical cell padding. Forwarded to Mantine `Table`. */
+  verticalSpacing?: MantineSpacing
+  /** Horizontal cell padding. Forwarded to Mantine `Table`. */
+  horizontalSpacing?: MantineSpacing
+  /** Row separators. Forwarded to Mantine `Table`. @default true (Mantine's own default) */
+  withRowBorders?: boolean
+  /**
+   * Outer table border. Turn it OFF for a table that already sits inside a `Card`/`ChartCard`,
+   * where the card owns the frame and a second one reads as a nested box.
+   * @default true
+   */
+  withTableBorder?: boolean
 }
 
 // ── Sort indicator ────────────────────────────────────────────────────────────
@@ -390,6 +472,14 @@ export function BasaltDataTable<T>({
   pageCount,
   enablePinning = false,
   initialColumnPinning,
+  maxHeight,
+  minWidth,
+  stickyHeader,
+  stickyHeaderOffset,
+  verticalSpacing,
+  horizontalSpacing,
+  withRowBorders,
+  withTableBorder = true,
 }: BasaltDataTableProps<T>) {
   const [sorting, setSorting] = useState<SortingState>(initialSorting ?? [])
   const [globalFilter, setGlobalFilter] = useState(initialGlobalFilter ?? '')
@@ -496,7 +586,12 @@ export function BasaltDataTable<T>({
     <Table
       {...(striped !== undefined && { striped })}
       {...(highlightOnHover !== undefined && { highlightOnHover })}
-      withTableBorder
+      {...(stickyHeader !== undefined && { stickyHeader })}
+      {...(stickyHeaderOffset !== undefined && { stickyHeaderOffset })}
+      {...(verticalSpacing !== undefined && { verticalSpacing })}
+      {...(horizontalSpacing !== undefined && { horizontalSpacing })}
+      {...(withRowBorders !== undefined && { withRowBorders })}
+      withTableBorder={withTableBorder}
     >
       <Table.Thead>
         {headerGroups.map((headerGroup) => (
@@ -508,6 +603,7 @@ export function BasaltDataTable<T>({
               const pinnedStyle = enablePinning
                 ? getPinnedCellStyle(table, header.column)
                 : undefined
+              const align = resolveAlign(header.column)
               return (
                 <Table.Th
                   key={header.id}
@@ -533,6 +629,7 @@ export function BasaltDataTable<T>({
                   }
                   style={{
                     ...(canSort ? { cursor: 'pointer', userSelect: 'none' } : undefined),
+                    ...(align !== undefined && { textAlign: align }),
                     ...pinnedStyle,
                   }}
                 >
@@ -582,11 +679,16 @@ export function BasaltDataTable<T>({
                   const pinnedStyle = enablePinning
                     ? getPinnedCellStyle(table, cell.column)
                     : undefined
+                  const align = resolveAlign(cell.column)
                   return (
                     <Table.Td
                       key={cell.id}
                       style={{
-                        ...(typeof cell.getValue() === 'number' ? NUMERIC_CELL_STYLE : undefined),
+                        ...(typeof cell.getValue() === 'number' &&
+                        cell.column.columnDef.meta?.numeral !== false
+                          ? NUMERIC_CELL_STYLE
+                          : undefined),
+                        ...(align !== undefined && { textAlign: align }),
                         ...pinnedStyle,
                       }}
                     >
@@ -602,6 +704,10 @@ export function BasaltDataTable<T>({
     </Table>
   )
 
+  // A capped body or a horizontal floor both need the same native scroll node; pinning keeps its
+  // simpler overflow-x Box when neither is set.
+  const scrolls = maxHeight !== undefined || minWidth !== undefined
+
   const paginationState = table.getState().pagination
   const total = table.getRowCount()
   const rangeStart = total === 0 ? 0 : paginationState.pageIndex * paginationState.pageSize + 1
@@ -661,7 +767,19 @@ export function BasaltDataTable<T>({
           {toolbarActions}
         </Group>
       )}
-      {enablePinning ? <Box style={{ overflowX: 'auto' }}>{tableNode}</Box> : tableNode}
+      {scrolls ? (
+        <Table.ScrollContainer
+          type="native"
+          minWidth={minWidth ?? 0}
+          {...(maxHeight !== undefined && { maxHeight })}
+        >
+          {tableNode}
+        </Table.ScrollContainer>
+      ) : enablePinning ? (
+        <Box style={{ overflowX: 'auto' }}>{tableNode}</Box>
+      ) : (
+        tableNode
+      )}
       {enablePagination && (
         <Group justify="space-between" mt="xs" wrap="wrap" gap="xs" align="center">
           <Text style={RANGE_LABEL_STYLE}>

package/src/data/table.ts

@@ -21,7 +21,12 @@
 
 // ── BasaltDataTable ───────────────────────────────────────────────────────────
 export { BasaltDataTable } from './data-table'
-export type { BasaltDataTableProps, DataTableFacet, DataTableFacetOption } from './data-table'
+export type {
+  BasaltDataTableProps,
+  DataTableAlign,
+  DataTableFacet,
+  DataTableFacetOption,
+} from './data-table'
 
 // ── @tanstack/react-table convenience re-exports ──────────────────────────────
 // These are the handful of table primitives a consumer needs at the call site;