@chassis-ui/react 0.0.0-20260831090525 → 0.1.1

package/src/components/datagrid/DataGrid.scss

@@ -0,0 +1,203 @@
+@use "@chassis-ui/css/scss/config" as *;
+@use "@chassis-ui/css/scss/mixins" as *;
+
+// DataGrid renders react-aria-components' Virtualizer output: <div>s carrying grid/row/gridcell
+// roles, not a real <table> — native table layout can't support windowed rows (see this component's
+// entry under THEMING.md's "Component-scoped CSS"). chassis-css has no equivalent for that markup
+// shape, so unlike Table's two sm Table.css overrides, this stylesheet owns the whole visual
+// surface. It reads the SAME `--table-*` public custom properties `_table.scss` defines instead of
+// inventing `--datagrid-*` duplicates, so a consumer who's already re-themed `.table` globally (on
+// `:root`/`body`) gets a visually consistent `DataGrid` for free — a scoped override applied
+// directly on a `<Table>` element's own subtree won't reach a separate `<DataGrid>` instance
+// elsewhere in the DOM, since custom properties only cascade downward through shared ancestors.
+@layer components {
+  .datagrid {
+    // scss-docs-start datagrid-variables
+    --fg-color: var(--table-td-fg-color, #{$table-td-fg-color});
+    --bg-color: var(--table-td-bg-color, #{$table-td-bg-color});
+    --th-fg-color: var(--table-th-fg-color, #{$table-th-fg-color});
+    --th-bg-color: var(--table-th-bg-color, #{$table-th-bg-color});
+    --hover-fg-color: var(--table-hover-fg-color, #{$table-hover-fg-color});
+    --hover-bg-color: var(--table-hover-bg-color, #{$table-hover-bg-color});
+    --active-fg-color: var(--table-active-fg-color, #{$table-active-fg-color});
+    --active-bg-color: var(--table-active-bg-color, #{$table-active-bg-color});
+    --border-width: var(--table-border-width, #{$table-border-width});
+    --border-color: var(--table-border-color, #{$table-border-color});
+    --cue-color: var(--table-cue-color, #{$table-cue-color});
+    --cell-padding-y: var(--table-cell-padding-y, #{$table-cell-padding-y});
+    --cell-padding-x: var(--table-cell-padding-x, #{$table-cell-padding-x});
+    // scss-docs-start datagrid-pin-cue-variables
+    // Read by DataGridPinBehavior's generated stylesheet — not exposed via `--table-*` since
+    // pinned columns have no `Table` equivalent to stay consistent with.
+    --datagrid-pin-cue-shadow-start: inset 6px 0 6px -6px rgb(0 0 0 / 30%);
+    --datagrid-pin-cue-shadow-end: inset -6px 0 6px -6px rgb(0 0 0 / 30%);
+    // scss-docs-end datagrid-pin-cue-variables
+
+    @if $enable-table-font-tokens {
+      // Same public `--table-*` override namespace Table's own `.table` uses (passing `table` as
+      // the component name, not `datagrid`) — see this file's top comment.
+      @include map-font($table-td-font, table, td);
+      @include map-font($table-th-font, table, th);
+    }
+    // scss-docs-end datagrid-variables
+
+    position: relative;
+    display: block;
+    width: 100%;
+    // A virtualizer needs a bounded viewport to know when to stop rendering rows — without an
+    // explicit height it lays out its full scroll content, defeating windowing entirely. This is
+    // a floor so the component isn't broken out of the box; callers size it for their own layout.
+    height: 400px;
+    overflow: auto;
+    vertical-align: var(--table-cell-vertical-align, $table-cell-vertical-align);
+    border-color: var(--border-color);
+
+    // `[role="rowheader"]` is the identifying cell of a *data* row (the `isRowHeader` column,
+    // ARIA's analog of `<th scope="row">`) — a plain data cell, not header chrome. Only
+    // `.datagrid-header`'s own `[role="columnheader"]` cells get the th treatment; which
+    // rowgroup a cell belongs to (not its role) decides styling here, same as `_table.scss`'s
+    // `.table > thead` override applying regardless of `<td>`/`<th>`.
+    [role="columnheader"],
+    [role="gridcell"],
+    [role="rowheader"] {
+      box-sizing: border-box;
+      height: 100%;
+      padding: var(--cell-padding-y) var(--cell-padding-x);
+      color: var(--fg-color);
+      background-color: var(--bg-color);
+      // Style/color unconditional, width per-side — `border-width` alone is a no-op (a browser
+      // computes an unstyled edge's width as 0 regardless of the declared value), so `.bordered`/
+      // `.borderless` below only ever touch `border-width`, never style or color.
+      border-color: var(--border-color);
+      border-style: solid;
+      border-width: 0 0 var(--border-width) 0;
+      @include font(td);
+    }
+
+    .datagrid-header [role="columnheader"] {
+      --fg-color: var(--th-fg-color);
+      --bg-color: var(--th-bg-color);
+      @include font(th);
+    }
+
+    [role="row"][data-selected] > * {
+      --fg-color: var(--active-fg-color);
+      --bg-color: var(--active-bg-color);
+    }
+
+    &.hoverable [role="row"]:not([data-selected]):hover > *{
+      --fg-color: var(--hover-fg-color);
+      --bg-color: var(--hover-bg-color);
+    }
+
+    &.bordered {
+      border: var(--border-width) solid var(--border-color);
+
+      [role="columnheader"],
+      [role="gridcell"],
+      [role="rowheader"] {
+        border-width: 0 var(--border-width) var(--border-width) 0;
+      }
+    }
+
+    &.borderless {
+      [role="columnheader"],
+      [role="gridcell"],
+      [role="rowheader"] {
+        border-width: 0;
+      }
+    }
+
+    [role="row"]:focus-visible,
+    [role="gridcell"]:focus-visible,
+    [role="columnheader"]:focus-visible,
+    [role="rowheader"]:focus-visible {
+      outline: var(--cx-border-width-xl) solid var(--cx-primary);
+      outline-offset: -2px;
+    }
+
+    [role="columnheader"][data-allows-sorting] {
+      cursor: pointer;
+      user-select: none;
+    }
+
+    .datagrid-sort-icon {
+      display: inline-block;
+      margin-inline-start: var(--cx-space-2xs);
+      @include font-size(.75em);
+      opacity: .6;
+    }
+
+    [data-sort-direction] .datagrid-sort-icon {
+      opacity: 1;
+    }
+
+    // react-aria-components' internal virtualizer wraps BOTH the `.datagrid-header` and
+    // `.datagrid-body` rowgroups in their own auto-generated positioning divs (role=
+    // "presentation", no class hook of their own) that default to `overflow: hidden` — every
+    // OTHER auto-generated wrapper this virtualizer produces (rows, individual cells) already
+    // defaults to `overflow: visible`, so these two are outliers. Left alone, this would clip
+    // `pin="start"`'s sticky-positioned cells (see `DataGridTableLayout`) and `pin="end"`'s
+    // scroll-driven `transform` (see `DataGridPinBehavior`) alike whenever either moves beyond
+    // this wrapper's own box. Nothing under here is meant to be clipped in the first place — rows
+    // are windowed by the virtualizer's own JS, not by this rule — so force both to match every
+    // other wrapper's own default. `!important` is required here — it's the only way to win
+    // against that wrapper's own inline style, which has higher specificity than any plain rule.
+    :has(> .datagrid-header),
+    :has(> .datagrid-body) {
+      // stylelint-disable-next-line declaration-no-important
+      overflow: visible !important;
+    }
+
+    // `pin="start"` is handled by DataGridTableLayout (the layout engine's own sticky
+    // positioning, reused from what already keeps the header row pinned to the top) — no CSS of
+    // ours is needed for the positioning itself, in either the header or body row group.
+    // `pin="end"` has no engine-level equivalent — its sticky mechanism is hardcoded to the
+    // leading edge, and a pure-CSS `position: sticky; right: 0` doesn't work for a trailing pin
+    // either (see `DataGridPinBehavior`'s doc comment for why) — so it's positioned imperatively
+    // by that component instead, via a scroll-driven `transform` (and the `z-index` that goes
+    // with it) on each `pin="end"` cell. The scroll-cue `box-shadow` is generated there too, as a
+    // per-instance-scoped stylesheet keyed on `aria-colindex`, applied uniformly to both row groups
+    // since a header row and a body row share the same rendered shape. Nothing about pinning is in
+    // this file — only the custom properties those generated rules read, above.
+
+    // No `width: 1%` here, unlike `.table-selection-cell` — that's a native `<table>` auto-layout
+    // trick (an unstyled cell shrinks to content, so `1%` beats the browser down to the
+    // checkbox's own width) that has no equivalent in this virtualized, JS-sized layout. Give a
+    // `DataGridColumn` carrying this class an explicit `defaultWidth`/`minWidth` instead — see
+    // `DataGridColumn`'s own doc comment.
+    .datagrid-selection-cell {
+      padding-inline-end: 0;
+      text-align: center;
+    }
+  }
+
+  // Rendered as a sibling of `.datagrid`, not a descendant of it (see DataGrid.tsx's own doc
+  // comment on `footer`) — it has to live outside the scrollable/virtualized element so it never
+  // scrolls away with the body rows, which means it can't read `.datagrid`'s own custom
+  // properties via inheritance. Re-reads the same `--table-*` fallback chain independently rather
+  // than duplicating `.datagrid`'s variable block onto a shared ancestor for this alone. One
+  // consequence, documented in datagrid.mdx's Scope section: a consumer override scoped directly
+  // to a specific `DataGrid` instance's own class won't reach the footer, only a global
+  // `--table-*` override will.
+  .datagrid-footer {
+    --fg-color: var(--table-td-fg-color, #{$table-td-fg-color});
+    --bg-color: var(--table-td-bg-color, #{$table-td-bg-color});
+    --border-width: var(--table-border-width, #{$table-border-width});
+    --border-color: var(--table-border-color, #{$table-border-color});
+    --cell-padding-y: var(--table-cell-padding-y, #{$table-cell-padding-y});
+    --cell-padding-x: var(--table-cell-padding-x, #{$table-cell-padding-x});
+
+    box-sizing: border-box;
+    padding: var(--cell-padding-y) var(--cell-padding-x);
+    color: var(--fg-color);
+    background-color: var(--bg-color);
+    border-color: var(--border-color);
+    border-style: solid;
+    border-width: var(--border-width) 0 0 0;
+
+    &.borderless {
+      border-width: 0;
+    }
+  }
+}

package/src/components/datagrid/DataGrid.tsx

@@ -0,0 +1,259 @@
+import React, {
+  ReactElement,
+  ReactNode,
+  Ref,
+  forwardRef,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState
+} from 'react'
+import classNames from 'classnames'
+import {
+  Key,
+  Selection,
+  SortDescriptor,
+  Table as AriaTable,
+  Virtualizer
+} from 'react-aria-components'
+
+import { useForkedRef } from '../../hooks/useForkedRef'
+import { ContextColor } from '../../types'
+import { DataGridBodyProps } from './DataGridBody'
+import { DataGridHeaderProps } from './DataGridHeader'
+import { DataGridPinBehavior } from './DataGridPinBehavior'
+import { DataGridTableLayout } from './DataGridTableLayout'
+import './DataGrid.scss'
+
+// No `striped`/`stacked` props: zebra-striping via CSS `:nth-of-type` (Table's approach) isn't
+// virtualization-safe — a windowed row's DOM siblings are only the currently-mounted rows, not
+// every logical row, so the stripe parity would flip as the mounted window's starting index
+// changes during scroll. A correct implementation needs the row's real index at render time, not
+// a pure-CSS trick; deferred rather than shipped broken.
+interface DataGridOwnProps<T extends object> {
+  /**
+   * An accessible label for the grid, used when there's no visible heading.
+   */
+  'aria-label'?: string
+  /**
+   * Identifies a visible heading element for the grid.
+   */
+  'aria-labelledby'?: string
+  /**
+   * Set the vertical alignment of cell content. Mirrors `Table`'s prop of the same name for API
+   * parity — same as `Table`, this awaits chassis-css adding the matching `.align-*` styles.
+   */
+  align?: 'bottom' | 'middle' | 'top'
+  /**
+   * Add borders on all sides of the grid and cells.
+   */
+  bordered?: boolean
+  /**
+   * Remove borders on all sides of the grid and cells.
+   */
+  borderless?: boolean
+  /**
+   * A `DataGridHeader` and a `DataGridBody`, each built from `DataGridColumn`/`DataGridRow`/
+   * `DataGridCell`.
+   */
+  children: [ReactElement<DataGridHeaderProps<T>>, ReactElement<DataGridBodyProps<T>>]
+  /**
+   * A string of all className you want applied to the component.
+   */
+  className?: string
+  /**
+   * Sets the color of the component.
+   */
+  color?: ContextColor
+  /**
+   * A list of row keys to disable. Disabled rows cannot be selected, focused, or interacted with.
+   */
+  disabledKeys?: Iterable<Key>
+  /**
+   * Content shown below the grid, e.g. a totals row or a "load more" control. Rendered as plain
+   * markup outside the grid's own scrollable/virtualized region — not part of the
+   * keyboard-navigable grid, and never scrolls out of view along with the body rows. Mirrors
+   * `Table`'s `footer` prop for API parity.
+   */
+  footer?: ReactNode
+  /**
+   * Enable a hover state on grid rows.
+   */
+  hover?: boolean
+  /**
+   * Handler that is called when the selection changes.
+   */
+  onSelectionChange?: (keys: Selection) => void
+  /**
+   * Handler that is called when a column is sorted.
+   */
+  onSortChange?: (descriptor: SortDescriptor) => void
+  /**
+   * The currently selected row keys (controlled).
+   */
+  selectedKeys?: Selection
+  /**
+   * The type of selection that is allowed.
+   */
+  selectionMode?: 'none' | 'single' | 'multiple'
+  /**
+   * Make the grid more compact by cutting all cell padding.
+   */
+  sm?: boolean
+  /**
+   * The current sort column and direction.
+   */
+  sortDescriptor?: SortDescriptor
+}
+
+type DataGridRowHeightProps =
+  | {
+      /**
+       * Row height in pixels, or `"auto"` to measure each row from its own rendered content
+       * instead of a single fixed height shared by every row (pair it with a required
+       * `estimatedRowHeight`, and see the docs site's "Variable row height" section for the
+       * tradeoffs). A fixed number renders every row, including the header, at that exact
+       * height; content taller than it visually overflows rather than growing the row.
+       */
+      rowHeight: number
+      estimatedRowHeight?: never
+    }
+  | {
+      rowHeight: 'auto'
+      /**
+       * Seeds the virtualizer's scroll-position math for rows that haven't been measured yet.
+       * Required when `rowHeight="auto"` — pick a value close to the typical row's real height
+       * to minimize scroll-jump on first measurement. A row's real height can still turn out far
+       * from this estimate once it renders, which can cause a visible scroll-jump for rows the
+       * viewport hasn't reached yet.
+       */
+      estimatedRowHeight: number
+    }
+
+export type DataGridProps<T extends object> = DataGridOwnProps<T> & DataGridRowHeightProps
+
+const DataGridInner = <T extends object>(
+  {
+    align,
+    bordered,
+    borderless,
+    children,
+    className,
+    color,
+    disabledKeys,
+    estimatedRowHeight,
+    footer,
+    hover,
+    onSelectionChange,
+    onSortChange,
+    rowHeight,
+    selectedKeys,
+    selectionMode = 'none',
+    sm,
+    sortDescriptor,
+    ...rest
+  }: DataGridProps<T>,
+  forwardedRef: Ref<HTMLDivElement>
+) => {
+  const isVariableRowHeight = rowHeight === 'auto'
+  const layout = useMemo(
+    () =>
+      new DataGridTableLayout<T>(
+        // `headingHeight` is pinned to `estimatedRowHeight` (fixed, not itself an estimate) in
+        // variable-height mode — leaving it unset falls back to `estimatedRowHeight` as an
+        // *estimate* for the header too, which sounds harmless but isn't: the header's own
+        // sticky-positioned outer wrapper (built once in `buildTableHeader`, see
+        // `DataGridTableLayout`'s doc comment for why the header is sticky at all) is never
+        // recomputed when a column-header cell's later real measurement corrects its height, so
+        // the outer wrapper's stale height desyncs from the cell's real one, spilling header
+        // content into the body's first row instead of the header growing to fit it. Fixing the
+        // header's height sidesteps that gap instead of shipping it.
+        isVariableRowHeight
+          ? { estimatedRowHeight, headingHeight: estimatedRowHeight }
+          : { rowHeight }
+      ),
+    [isVariableRowHeight, rowHeight, estimatedRowHeight]
+  )
+  const gridRef = useRef<HTMLDivElement>(null)
+  const ref = useForkedRef(forwardedRef, gridRef)
+
+  // A stable per-instance class, scoping DataGridPinBehavior's generated CSS so multiple grids on
+  // the same page (each with their own pinned columns) don't collide.
+  const rawId = useId()
+  const instanceClassName = `datagrid-${rawId.replace(/[^a-zA-Z0-9]/g, '')}`
+
+  // Drives the pin=start/pin=end scroll-cue box-shadow — see DataGridPinBehavior — which should
+  // only appear once there's actually hidden content under the pinned column to cue.
+  const [scrolledStart, setScrolledStart] = useState(false)
+  const [scrolledEnd, setScrolledEnd] = useState(false)
+
+  useEffect(() => {
+    const grid = gridRef.current
+    if (!grid) return
+
+    const updateScrollState = () => {
+      setScrolledStart(grid.scrollLeft > 0)
+      setScrolledEnd(Math.ceil(grid.scrollLeft + grid.clientWidth) < grid.scrollWidth)
+    }
+
+    updateScrollState()
+    grid.addEventListener('scroll', updateScrollState, { passive: true })
+    const observer =
+      typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(updateScrollState)
+    observer?.observe(grid)
+    return () => {
+      grid.removeEventListener('scroll', updateScrollState)
+      observer?.disconnect()
+    }
+  }, [])
+
+  const _className = classNames(
+    'datagrid',
+    instanceClassName,
+    color,
+    {
+      [`align-${align}`]: align,
+      bordered,
+      borderless,
+      hoverable: hover,
+      sm,
+      'datagrid-scrolled-start': scrolledStart,
+      'datagrid-scrolled-end': scrolledEnd
+    },
+    className
+  )
+
+  return (
+    <Virtualizer layout={layout} shouldObserveItemSize={isVariableRowHeight}>
+      <AriaTable
+        aria-label={rest['aria-label']}
+        aria-labelledby={rest['aria-labelledby']}
+        className={_className || undefined}
+        disabledKeys={disabledKeys}
+        onSelectionChange={onSelectionChange}
+        onSortChange={onSortChange}
+        ref={ref}
+        selectedKeys={selectedKeys}
+        selectionMode={selectionMode}
+        sortDescriptor={sortDescriptor}
+      >
+        {children}
+      </AriaTable>
+      {footer && <div className={classNames('datagrid-footer', { borderless })}>{footer}</div>}
+      <DataGridPinBehavior
+        containerRef={gridRef}
+        header={children[0]}
+        instanceClassName={instanceClassName}
+      />
+    </Virtualizer>
+  )
+}
+
+// `forwardRef` erases type parameters, so the generic component is cast back to a generic
+// signature for callers — same pattern `Table` uses.
+export const DataGrid = forwardRef(DataGridInner) as <T extends object>(
+  props: DataGridProps<T> & { ref?: Ref<HTMLDivElement> }
+) => ReactElement
+
+;(DataGrid as { displayName?: string }).displayName = 'DataGrid'

package/src/components/datagrid/DataGridBody.tsx

@@ -0,0 +1,162 @@
+import React, { ReactElement, ReactNode, useMemo } from 'react'
+import classNames from 'classnames'
+import {
+  TableBody as AriaTableBody,
+  TableBodyRenderProps,
+  TableLoadMoreItem
+} from 'react-aria-components'
+
+// A unique value appended to `items` internally to represent the trailing "load more" row in
+// react-aria-components' collection. `TableLoadMoreItem` has to be returned from the per-item
+// render function like any other row — react-aria-components' `useCachedChildren` only supports
+// EITHER `items` + a render function OR static `children`, never a mix of both in the same
+// `children` prop, so a `<TableLoadMoreItem>` placed as a plain JSX sibling inside `<TableBody>`
+// is silently dropped (or crashes, if `children` becomes an array mixing the render function in).
+// Checked by reference (`item === LOADER_ITEM`), so it can never collide with a real `T` the way a
+// `{ __loader: true }` marker object might if compared structurally. Its `id` matters too, not
+// just its identity: react-aria-components derives each rendered item's React key from
+// `rendered.props.id ?? item?.key ?? item?.id ?? <positional index>` (`useCachedChildren`) —
+// `TableLoadMoreItem` doesn't accept an `id` prop itself, so without this object's own `id` the
+// loader's key falls back to its position in the array, which collides with a real row whenever a
+// row's own `id` happens to equal that count (e.g. a 2-item list with a row literally id `"2"`).
+const LOADER_ITEM = { id: '__datagrid-body-loader__' }
+
+interface DataGridBodyOwnProps {
+  /**
+   * A string of all className you want applied to the body row group.
+   */
+  className?: string
+  /**
+   * Values that should invalidate the row cache when using the `items`/render-function form of
+   * `children` — e.g. a value from outside `items` that the render function reads. Without this,
+   * changing that outside value won't re-render already-cached rows, since dynamic rows are only
+   * rebuilt when `items` or `dependencies` change by reference, not on every parent re-render.
+   */
+  dependencies?: ReadonlyArray<unknown>
+  /**
+   * Content shown in place of rows when `items` is empty.
+   */
+  renderEmptyState?: (props: TableBodyRenderProps) => React.ReactNode
+}
+
+/**
+ * The `items` + render-function form. `isLoading`/`loadingContent`/`onLoadMore` live here rather
+ * than alongside the static form because the loader row is generated by appending to `items` and
+ * rendering through that same function — there's no growing dataset to load more of, and nothing
+ * to render the loader with, in a hand-written list of `DataGridRow` elements.
+ */
+interface DataGridBodyDynamicProps<T> {
+  /**
+   * A render function called once per item in `items`, returning that row's `DataGridRow`.
+   */
+  children: (item: T) => ReactElement
+  /**
+   * Whether more items are currently being fetched. Shows `loadingContent` in the loader row while
+   * true, and — until this goes back to `false` — suppresses further `onLoadMore` calls, so one
+   * scroll-into-view doesn't fire the callback again before the in-flight fetch resolves.
+   */
+  isLoading?: boolean
+  /**
+   * A list of row data objects, rendered via the function form of `children`.
+   */
+  items: Iterable<T>
+  /**
+   * Content rendered inside the loader row while `isLoading` is true, e.g. a spinner. Only takes
+   * effect alongside `onLoadMore`.
+   */
+  loadingContent?: ReactNode
+  /**
+   * Called when the grid scrolls near its last row, so more data can be fetched and appended to
+   * `items`. Pair with `isLoading` so a fetch already in flight isn't triggered again before it
+   * resolves.
+   */
+  onLoadMore?: () => void
+}
+
+/** The static form: `DataGridRow` elements written out directly. */
+interface DataGridBodyStaticProps {
+  /**
+   * `DataGridRow` elements.
+   */
+  children: ReactElement | ReactElement[]
+  isLoading?: never
+  items?: never
+  loadingContent?: never
+  onLoadMore?: never
+}
+
+/**
+ * Split into a static and a dynamic form so the two can't be mixed: the loader row is appended to
+ * `items` and rendered through `children`, so `onLoadMore` alongside a static list of elements used
+ * to type-check and then throw at render ("children is not a function") the moment the loader row
+ * came up.
+ */
+export type DataGridBodyProps<T> = DataGridBodyOwnProps &
+  (DataGridBodyDynamicProps<T> | DataGridBodyStaticProps)
+
+/**
+ * Body row group for `DataGrid`, containing `DataGridRow`s. Unlike `Table`'s sub-parts, this
+ * renders directly — it's a thin wrapper over react-aria-components' own `TableBody`.
+ *
+ * Always carries the `datagrid-body` class — see `DataGridHeader`'s equivalent note.
+ */
+export const DataGridBody = <T extends object>({
+  children,
+  className,
+  dependencies,
+  isLoading,
+  items,
+  loadingContent,
+  onLoadMore,
+  renderEmptyState
+}: DataGridBodyProps<T>) => {
+  const hasLoader = onLoadMore != null && items != null
+
+  const itemsWithLoader = useMemo(() => {
+    if (!hasLoader) return items
+    return [...(items as Iterable<T>), LOADER_ITEM] as Iterable<T>
+  }, [hasLoader, items])
+
+  // react-aria-components caches each rendered row by item identity (see `dependencies`'s own doc
+  // comment above) — the loader branch below reads `isLoading`/`onLoadMore`/`loadingContent`, none
+  // of which are part of `items`, so without surfacing them here the cached loader row would keep
+  // whatever `isLoading` value (and stale `onLoadMore` closure) was in scope the first time it
+  // rendered, never picking up a later change.
+  const dependenciesWithLoader = useMemo(
+    () =>
+      hasLoader ? [...(dependencies ?? []), isLoading, onLoadMore, loadingContent] : dependencies,
+    [dependencies, hasLoader, isLoading, onLoadMore, loadingContent]
+  )
+
+  const bodyChildren = hasLoader
+    ? (item: T) =>
+        (item as unknown) === LOADER_ITEM ? (
+          <TableLoadMoreItem
+            className="datagrid-loader"
+            isLoading={isLoading}
+            // Suppresses re-triggering onLoadMore while a fetch is already in flight — the
+            // underlying sentinel has no built-in debounce of its own and calls onLoadMore again
+            // whenever it (re-)observes the sentinel still intersecting, e.g. after the collection
+            // changes but the loader row hasn't yet scrolled out of view.
+            onLoadMore={isLoading ? undefined : onLoadMore}
+          >
+            {loadingContent}
+          </TableLoadMoreItem>
+        ) : (
+          // `hasLoader` implies the dynamic form of the props union, whose `children` is the
+          // render function — `onLoadMore` isn't assignable alongside static children.
+          (children as (item: T) => ReactElement)(item)
+        )
+    : children
+
+  return (
+    <AriaTableBody
+      className={classNames('datagrid-body', className)}
+      dependencies={dependenciesWithLoader}
+      items={itemsWithLoader}
+      renderEmptyState={renderEmptyState}
+    >
+      {bodyChildren}
+    </AriaTableBody>
+  )
+}

package/src/components/datagrid/DataGridCell.tsx

@@ -0,0 +1,47 @@
+import React, { ReactNode } from 'react'
+import { Key, Cell as AriaCell } from 'react-aria-components'
+import classNames from 'classnames'
+
+export interface DataGridCellProps {
+  /**
+   * The contents of the cell.
+   */
+  children: ReactNode
+  /**
+   * A string of all className you want applied to the cell.
+   */
+  className?: string
+  /**
+   * Indicates how many columns the cell spans.
+   */
+  colSpan?: number
+  /**
+   * The unique id of the cell.
+   */
+  id?: Key
+  /**
+   * A string representation of the cell's contents, used for typeahead.
+   */
+  textValue?: string
+}
+
+/**
+ * A cell within a `DataGrid` row. Unlike `Table`'s sub-parts, this renders directly — it's a
+ * thin wrapper over react-aria-components' own `Cell`.
+ */
+export const DataGridCell = ({
+  children,
+  className,
+  colSpan,
+  id,
+  textValue
+}: DataGridCellProps) => (
+  <AriaCell
+    className={classNames('datagrid-cell', className)}
+    colSpan={colSpan}
+    id={id}
+    textValue={textValue}
+  >
+    {children}
+  </AriaCell>
+)