@patterninc/pattern-ui 0.0.0-main.20260929.db2f8e8fde0d

package/src/components/DataGrid/DataGridStatusBar.tsx

@@ -0,0 +1,186 @@
+import { plural } from '@lingui/core/macro'
+import { useLingui } from '@lingui/react/macro'
+import { cn } from 'cn'
+import * as React from 'react'
+
+import { ButtonInset } from '../ButtonInset/ButtonInset'
+import ChevronLeftIcon from '../icons/ChevronLeftIcon'
+import ChevronRightIcon from '../icons/ChevronRightIcon'
+import DotsHorizontalAlt from '../icons/DotsHorizontalAlt'
+import PlusIcon from '../icons/PlusIcon'
+import { useOptionalDataGridContext } from './DataGridContext'
+import { setDataGridSlot } from './dataGridSlots'
+import type { DataGridVariant } from './dataGridTypes'
+
+/**
+ * The bar below the grid: row count + add-row action on the left, pagination honestly centred, and
+ * the overflow menu far right. When `selectedCount` > 0 the count switches from the total ("248
+ * rows") to the selection ("12 of 248 selected"). `variant` matches the grid — `inverse` sits
+ * flush, `weak` paints the Depth/Black/4 band. Rendered as a `DataGrid` child, omitted `variant` /
+ * `rowCount` / `selectedCount` / `options` inherit from the grid context (the Columns / Row-height
+ * menu is injected that way). It draws no top border: whatever sits above already carries a bottom
+ * gridline, so a top rule here would stack two 1px lines. Bulk actions on a selection live in the
+ * floating Action Bar, not here.
+ */
+interface DataGridStatusBarBaseProps extends React.ComponentProps<'div'> {
+  /** Surface treatment: `inverse` (flush) or `weak` (tinted band). */
+  variant?: DataGridVariant
+  /**
+   * Total number of rows for the count label. Omit it inside `DataGrid` and the bar inherits the
+   * grid's `rowCount` (the dataset total when the grid was given one, otherwise `data.length`).
+   */
+  rowCount?: number
+  /** Selected row count; when > 0 the readout becomes "N of {rowCount} selected". */
+  selectedCount?: number
+  /** Show the add-row (+) action. Hide it for read-only grids. */
+  showNewRow?: boolean
+  /** Called when the add-row action is activated. */
+  onAddRow?: () => void
+  /** 1-based current page. */
+  currentPage?: number
+  /** Total number of pages. */
+  totalPages?: number
+  /** Go to the previous / next page. */
+  onPreviousPage?: () => void
+  onNextPage?: () => void
+  /** Optional test id rendered as the `qa-test-id` attribute for QA testing */
+  qaTestId?: string
+}
+
+/** Bring your own control for the bottom-right corner. */
+interface DataGridStatusBarOptionsProps extends DataGridStatusBarBaseProps {
+  /**
+   * Trailing options control shown in the bottom-right corner — typically a `Menu` whose trigger is
+   * the dots button, so the options open from this corner. It takes the place of the default
+   * overflow button entirely.
+   */
+  options: React.ReactNode
+  /** Unavailable alongside `options` — your node owns the click. */
+  onMenuOpen?: never
+}
+
+/** Use the default overflow button and handle its click. */
+interface DataGridStatusBarMenuButtonProps extends DataGridStatusBarBaseProps {
+  options?: never
+  /**
+   * Called when the default overflow button is activated. The button is disabled without it.
+   * Passing this inside a `DataGrid` overrides the grid's own Columns / Row-height menu.
+   */
+  onMenuOpen?: () => void
+}
+
+/**
+ * A union rather than two optional props: `options` used to silently win over `onMenuOpen`, so
+ * passing both compiled and dropped the handler without a word.
+ */
+export type DataGridStatusBarProps =
+  | DataGridStatusBarOptionsProps
+  | DataGridStatusBarMenuButtonProps
+
+export function DataGridStatusBar({
+  variant: variantProp,
+  rowCount: rowCountProp,
+  selectedCount: selectedCountProp,
+  showNewRow = true,
+  onAddRow,
+  currentPage,
+  totalPages,
+  onPreviousPage,
+  onNextPage,
+  onMenuOpen,
+  options: optionsProp,
+  className,
+  qaTestId = 'data-grid-status-bar',
+  ...props
+}: DataGridStatusBarProps) {
+  const { t } = useLingui()
+  const grid = useOptionalDataGridContext()
+  // Each prop wins over the value inherited from the grid. The props are aliased on the way in so
+  // these keep the plain names: Lingui bakes the interpolated variable name into the message id,
+  // so a `resolvedRowCount` here would silently fork "{rowCount} rows" into a new, untranslated
+  // message.
+  const variant = variantProp ?? grid?.variant ?? 'inverse'
+  const rowCount = rowCountProp ?? grid?.rowCount ?? 0
+  const selectedCount = selectedCountProp ?? grid?.selectedCount ?? 0
+  // Precedence: an explicit node, then an explicit handler, then whatever the grid supplies. The
+  // inherited menu used to win over an `onMenuOpen` passed right here, which read as the prop
+  // simply not working.
+  const options = optionsProp ?? (onMenuOpen ? undefined : grid?.footerOptions)
+  const hasSelection = selectedCount > 0
+  const countLabel = hasSelection
+    ? t`${selectedCount} of ${rowCount} selected`
+    : plural(rowCount, { one: '# row', other: '# rows' })
+
+  const hasPagination = currentPage != null && totalPages != null
+
+  return (
+    <div
+      className={cn(
+        'grid h-12 shrink-0 grid-cols-[1fr_auto_1fr] items-center gap-2 px-3',
+        variant === 'weak' && 'bg-base-weak',
+        className,
+      )}
+      qa-test-id={qaTestId}
+      {...props}
+    >
+      {/* Left: add-row action + count. */}
+      <div className='flex min-w-0 items-center gap-2.5'>
+        {showNewRow && (
+          <ButtonInset
+            icon={PlusIcon}
+            variant='inverse'
+            aria-label={t`Add row`}
+            disabled={!onAddRow}
+            onClick={onAddRow}
+          />
+        )}
+        <span className='pui-text-mono-small truncate text-text-sub'>{countLabel}</span>
+      </div>
+
+      {/* Centre: pagination. */}
+      {hasPagination ? (
+        <div className='flex items-center justify-center gap-2'>
+          <ButtonInset
+            icon={ChevronLeftIcon}
+            variant='inverse'
+            aria-label={t`Previous page`}
+            // Keep the disabled stepper transparent (muted icon only) — the default disabled white
+            // fill would show as a box on the `weak` band.
+            className='disabled:bg-transparent'
+            disabled={!onPreviousPage || currentPage <= 1}
+            onClick={onPreviousPage}
+          />
+          <span className='pui-text-mono-small text-text-sub tabular-nums'>
+            {currentPage} of {totalPages}
+          </span>
+          <ButtonInset
+            icon={ChevronRightIcon}
+            variant='inverse'
+            aria-label={t`Next page`}
+            className='disabled:bg-transparent'
+            disabled={!onNextPage || currentPage >= totalPages}
+            onClick={onNextPage}
+          />
+        </div>
+      ) : (
+        <div />
+      )}
+
+      {/* Right: options menu (Columns / Row height). A consumer-supplied `options` node (a `Menu`)
+          takes the place of the default button so the menu opens from this corner. */}
+      <div className='flex items-center justify-end'>
+        {options ?? (
+          <ButtonInset
+            icon={DotsHorizontalAlt}
+            variant='inverse'
+            aria-label={t`More options`}
+            disabled={!onMenuOpen}
+            onClick={onMenuOpen}
+          />
+        )}
+      </div>
+    </div>
+  )
+}
+
+setDataGridSlot(DataGridStatusBar, 'footer')

package/src/components/DataGrid/DataGridToolbar.tsx

@@ -0,0 +1,90 @@
+import { cva, type VariantProps } from 'class-variance-authority'
+import { cn } from 'cn'
+import * as React from 'react'
+
+import { ScrollGradientWrapper } from '../shared/ScrollGradientWrapper/ScrollGradientWrapper'
+import { useOptionalDataGridContext } from './DataGridContext'
+import { setDataGridSlot } from './dataGridSlots'
+import type { DataGridVariant } from './dataGridTypes'
+
+/**
+ * The bar above the grid. Per Figma this is a container, not a control — it fixes the arrangement,
+ * spacing and the 1px Depth/Black/4 bottom rule (the same rule the header row uses); every child is
+ * an existing component the consumer supplies. Layout: title, a left action cluster (`children` —
+ * app-owned controls such as a Filter), a flexible spacer, then a right cluster (`actions` —
+ * typically `DataGridFind`). Grid sort / pin / hide live on each column header; Columns and Row
+ * height live in the status-bar overflow. `variant` matches the grid: `inverse` sits flush; `weak`
+ * paints the Depth/Black/4 band shared with the header/status bar.
+ */
+const toolbarVariants = cva(
+  'flex h-12 shrink-0 items-center gap-2 border-b border-depth-black-4 px-3',
+  {
+    variants: {
+      variant: {
+        inverse: '',
+        weak: 'bg-base-weak',
+      },
+    },
+    defaultVariants: { variant: 'inverse' },
+  },
+)
+
+export interface DataGridToolbarProps
+  extends Omit<React.ComponentProps<'div'>, 'title'>, VariantProps<typeof toolbarVariants> {
+  /** Grid title shown at the start (Label/Medium, strong). */
+  title?: React.ReactNode
+  /** Surface treatment: `inverse` (flush) or `weak` (tinted band). */
+  variant?: DataGridVariant
+  /** Left action cluster — app-owned controls (a Filter, a saved-view picker). */
+  children?: React.ReactNode
+  /** Right action cluster — typically `DataGridFind`. */
+  actions?: React.ReactNode
+  /** Optional test id rendered as the `qa-test-id` attribute for QA testing */
+  qaTestId?: string
+}
+
+export function DataGridToolbar({
+  title,
+  variant: variantProp,
+  children,
+  actions,
+  className,
+  qaTestId = 'data-grid-toolbar',
+  ...props
+}: DataGridToolbarProps) {
+  // Mounted as a `DataGrid` child, the surface is already decided by the grid — matching it by
+  // hand was the most common way to get a toolbar that did not sit flush with the rows.
+  const grid = useOptionalDataGridContext()
+  const variant = variantProp ?? grid?.variant ?? 'inverse'
+
+  return (
+    <div className={cn(toolbarVariants({ variant }), className)} qa-test-id={qaTestId} {...props}>
+      {title != null && (
+        <span className='pui-text-label-medium shrink-0 text-text-strong'>{title}</span>
+      )}
+      {children != null ? (
+        // The left action cluster takes the flexible middle and scrolls horizontally when its buttons
+        // don't fit (narrow / mobile widths), so the title stays pinned at the start and the right
+        // actions (search) stay reachable at the end instead of the whole bar overflowing + clipping.
+        // `ScrollGradientWrapper` adds the shared edge fade (matching Tabs / Dropdown) so off-screen
+        // buttons read as "more to scroll"; `[&>*]:shrink-0` keeps the buttons at their natural width.
+        <ScrollGradientWrapper
+          direction='horizontal'
+          gradientSurface={variant}
+          className='min-w-0 flex-1'
+          scrollClassName='items-center gap-2 [&>*]:shrink-0'
+        >
+          {children}
+        </ScrollGradientWrapper>
+      ) : (
+        // No left cluster: a plain spacer still pushes the right actions to the trailing edge.
+        <div className='min-w-0 flex-1' />
+      )}
+      {actions != null && (
+        <div className='flex shrink-0 items-center justify-end gap-2'>{actions}</div>
+      )}
+    </div>
+  )
+}
+
+setDataGridSlot(DataGridToolbar, 'header')

package/src/components/DataGrid/DataGridTreeCell.tsx

@@ -0,0 +1,84 @@
+import { useLingui } from '@lingui/react/macro'
+import { cn } from 'cn'
+import * as React from 'react'
+
+import { ButtonInset } from '../ButtonInset/ButtonInset'
+import ChevronRightIcon from '../icons/ChevronRightIcon'
+
+/**
+ * Nested-row cell content: a disclosure caret (when the row has children and `onToggle`) plus depth
+ * indent, then the cell's value. Expansion state is controlled — pair with `useDataGridTree` and
+ * put this inside a `DataGridCell` (typically via `column.render` on the composed grid). It does
+ * not own the tree or fetch children.
+ */
+export interface DataGridTreeCellProps extends Omit<React.ComponentProps<'div'>, 'children'> {
+  /** 0 for a root row, +1 per level. Indents the caret + value 24px per level. */
+  depth?: number
+  /**
+   * The row has children. A disclosure caret is shown only when this is true _and_ `onToggle` is
+   * passed — a lazy-load parent with no callback yet looks like a leaf (spacer, no caret).
+   */
+  hasChildren?: boolean
+  /** Whether the caret is in its open state. Ignored when no caret is shown. */
+  isExpanded?: boolean
+  /**
+   * Called when the caret is activated. Required to show the caret; without it `hasChildren` is
+   * ignored. The caret does not select the row or open an editor.
+   */
+  onToggle?: () => void
+  /** The cell's value — typically a `DataGridCellValue`. */
+  children?: React.ReactNode
+  /** Optional test id rendered as the `qa-test-id` attribute for QA testing */
+  qaTestId?: string
+}
+
+export function DataGridTreeCell({
+  depth = 0,
+  hasChildren = false,
+  isExpanded = false,
+  onToggle,
+  className,
+  children,
+  style,
+  qaTestId = 'data-grid-tree-cell',
+  ...props
+}: DataGridTreeCellProps) {
+  const { t } = useLingui()
+  const showCaret = hasChildren && onToggle != null
+
+  return (
+    <div
+      className={cn('flex min-w-0 items-center gap-1', className)}
+      // 24px per depth so nesting is not capped at 2 levels (no dynamic Tailwind `pl-*`).
+      style={{ paddingInlineStart: `${depth * 24}px`, ...style }}
+      qa-test-id={qaTestId}
+      {...props}
+    >
+      {showCaret ? (
+        <ButtonInset
+          icon={ChevronRightIcon}
+          variant='inverse'
+          // The cell already exposes the value; the button only names the disclosure. A sibling
+          // sr-only + aria-labelledby would announce Expand/Collapse twice plus the value.
+          aria-label={isExpanded ? t`Collapse` : t`Expand`}
+          aria-expanded={isExpanded}
+          // One caret, rotated: LTR rest points end-ward, 90° is open (down). RTL rest flips.
+          className={
+            isExpanded
+              ? '[&_svg]:rotate-90 [&_svg]:transition-transform [&_svg]:duration-200'
+              : '[&_svg]:transition-transform [&_svg]:duration-200 rtl:[&_svg]:rotate-180'
+          }
+          onPointerDown={(event) => event.stopPropagation()}
+          onClick={(event) => {
+            event.stopPropagation()
+            onToggle?.()
+          }}
+        />
+      ) : (
+        // Matches `ButtonInset` (`h-6 w-6`) so leaf labels line up with parent labels.
+        <span className='inline-block w-6 shrink-0' />
+      )}
+      <div className='min-w-0 flex-1'>{children}</div>
+    </div>
+  )
+}

package/src/components/DataGrid/dataGridSlots.tsx

@@ -0,0 +1,72 @@
+import * as React from 'react'
+
+/** Which band of the grid a chrome part renders in: above the rows, or below them. */
+export type DataGridSlot = 'header' | 'footer'
+
+/** A chrome part that declares which band it belongs to, so a consumer never names a slot. */
+interface SlottedComponent {
+  dataGridSlot?: DataGridSlot
+}
+
+/**
+ * Tag a chrome part with the band it renders in. `DataGrid` reads this off its children, which is
+ * what lets `<DataGridToolbar />` and `<DataGridStatusBar />` be written in the order they appear
+ * on screen rather than threaded through `header` / `footer` props.
+ */
+export function setDataGridSlot<T extends React.ComponentType<never>>(
+  component: T,
+  slot: DataGridSlot,
+): T {
+  ;(component as SlottedComponent).dataGridSlot = slot
+  return component
+}
+
+/**
+ * Wrap custom chrome that should sit above the rows. Only needed for content the grid does not
+ * recognise — the built-in parts already declare their own band. Slotting keys off `child.type`, so
+ * a wrapper around `DataGridToolbar` is unrecognised and lands in the footer; put the part itself
+ * as a child, or wrap that wrapper in `DataGridHeader`.
+ */
+export function DataGridHeader({ children }: { children?: React.ReactNode }) {
+  return <>{children}</>
+}
+setDataGridSlot(DataGridHeader, 'header')
+
+/**
+ * Split `DataGrid`'s children into the band above the scroll body and the band below it.
+ *
+ * Parts declare their own band, so the common case needs no wrapper. Anything unrecognised renders
+ * below the rows: custom chrome is nearly always a summary or a pager, and guessing the other way
+ * would drop a stray node between the toolbar and the column headers. Wrap it in `DataGridHeader`
+ * to put it above instead.
+ */
+function flattenDataGridChildren(children: React.ReactNode): React.ReactNode[] {
+  const out: React.ReactNode[] = []
+  // `toArray` keys children and flattens arrays, but a Fragment is still one element — recurse so
+  // `<><DataGridToolbar /></>` is classified as header chrome rather than an opaque footer node.
+  for (const child of React.Children.toArray(children)) {
+    if (React.isValidElement(child) && child.type === React.Fragment) {
+      out.push(...flattenDataGridChildren((child.props as { children?: React.ReactNode }).children))
+    } else {
+      out.push(child)
+    }
+  }
+  return out
+}
+
+export function partitionDataGridChildren(children: React.ReactNode): {
+  header: React.ReactNode[]
+  footer: React.ReactNode[]
+} {
+  const header: React.ReactNode[] = []
+  const footer: React.ReactNode[] = []
+
+  for (const child of flattenDataGridChildren(children)) {
+    const slot = React.isValidElement(child)
+      ? ((child.type as SlottedComponent).dataGridSlot ?? 'footer')
+      : 'footer'
+    ;(slot === 'header' ? header : footer).push(child)
+  }
+
+  return { header, footer }
+}

package/src/components/DataGrid/dataGridTypes.ts

@@ -0,0 +1,190 @@
+import type * as React from 'react'
+
+import type { RestrictedIconProps } from '../../lib/utils/icon-helpers'
+
+/** Surface treatment. `weak` is the light zebra surface; `inverse` is the flat white surface. */
+export type DataGridVariant = 'weak' | 'inverse'
+
+/** A stable row identifier — the type of `DataGridRowData.id` and of every selection id. */
+export type DataGridRowId = string | number
+
+/** Row height density. `small` = 40px rows, `medium` = 56px rows. */
+export type DataGridDensity = 'small' | 'medium'
+
+/** Interaction/validation state of a single cell. */
+export type DataGridCellState = 'default' | 'hover' | 'selected' | 'editing' | 'error' | 'disabled'
+
+/** Interaction state of a whole row. `loading` renders skeleton cells. */
+export type DataGridRowState = 'default' | 'hover' | 'selected' | 'loading' | 'disabled'
+
+/**
+ * State of the row gutter (Row Header). `default` shows the row number; `hover`/`selected` show the
+ * selection checkbox. Per Figma the gutter has no loading/disabled state — those rows keep
+ * `default`.
+ */
+export type DataGridRowHeaderState = 'default' | 'hover' | 'selected'
+
+/** Column header state, including the sort indicator and menu-open affordance. */
+export type DataGridColumnHeaderState =
+  | 'default'
+  | 'hover'
+  | 'sorted-ascending'
+  | 'sorted-descending'
+  | 'menu-open'
+
+/** The kind of value a cell renders. Drives which primitive `DataGridCellValue` composes. */
+export type DataGridCellValueType =
+  | 'text'
+  | 'number'
+  | 'currency'
+  | 'select'
+  | 'tags'
+  | 'checkbox'
+  | 'date'
+  | 'url'
+  | 'long-text'
+  | 'file'
+  | 'skeleton'
+
+/** Fill state of a value. `empty` shows an em-dash placeholder; `disabled` mutes the content. */
+export type DataGridValueState = 'filled' | 'empty' | 'disabled'
+
+/** Horizontal alignment of a column's content. Numbers/currency conventionally align to `end`. */
+export type DataGridAlign = 'start' | 'end'
+
+/** Sort direction for a column. */
+export type DataGridSortDirection = 'asc' | 'desc'
+
+/** Edge a column is pinned (frozen) to while the grid scrolls horizontally. */
+export type DataGridPinSide = 'left' | 'right'
+
+/**
+ * How a grid is arranged: which columns are hidden, which edge each pinned column sits on, and the
+ * row height. This is the unit a "save this view" / "reset layout" feature persists, and the shape
+ * `DataGrid`'s `layout` / `onLayoutChange` pass back and forth.
+ */
+export interface DataGridLayout {
+  /** Edge each pinned column sits on, keyed by column key. A column absent here is not pinned. */
+  pinned: Record<string, DataGridPinSide>
+  /** Keys of the hidden columns. */
+  hidden: string[]
+  /** Row height. */
+  density: DataGridDensity
+}
+
+/**
+ * Pagination stepper state for `DataGridStatusBar`. The consumer owns the page and slices the data;
+ * the status bar only renders the steppers and reports intent.
+ */
+export interface DataGridPaginationProps {
+  /** 1-based current page. */
+  currentPage: number
+  /** Total number of pages. */
+  totalPages: number
+  /** Go to the previous / next page. */
+  onPreviousPage?: () => void
+  onNextPage?: () => void
+}
+
+/**
+ * The committed value from an inline cell edit. Text-based editors (text/long-text/number/currency/
+ * url/date) commit a `string`; a `checkbox` cell commits its toggled `boolean`; a `select` / `tags`
+ * cell commits the chosen option value(s) as a `string[]` (one entry for `select`).
+ */
+export type DataGridCellEditValue = string | boolean | string[]
+
+/** A choice for a `select` / `tags` column's inline picker editor. */
+export interface DataGridSelectOption {
+  /** Stable value stored on the row. */
+  value: string
+  /** Display label (defaults to `value` when omitted). */
+  label?: React.ReactNode
+}
+
+/** A single inline-edit commit: which row + column changed and its new value. */
+export interface DataGridCellEdit {
+  /** Id of the edited row. */
+  rowId: DataGridRowId
+  /** `key` of the edited column. */
+  columnKey: string
+  /** The committed value. */
+  value: DataGridCellEditValue
+}
+
+/** Addresses a single cell by its row id and column key. */
+export interface DataGridCellPosition {
+  /** Id of the cell's row. */
+  rowId: DataGridRowId
+  /** `key` of the cell's column. */
+  columnKey: string
+}
+
+export interface DataGridCellRange {
+  /** The fixed corner where the selection began. */
+  anchor: DataGridCellPosition
+  /** The moving corner (updated as the selection is dragged / shift-extended). */
+  focus: DataGridCellPosition
+}
+
+/**
+ * A column definition for the composed `DataGrid`. `key` accesses the row's value; `type` selects
+ * the cell renderer; the header shows `header` (plus optional `typeIcon`). One column def drives
+ * the header type-icon, alignment, and cell renderer together.
+ */
+export interface DataGridColumn {
+  /** Stable id; also the key used to read each row's value. */
+  key: string
+  /** Header label content. */
+  header: React.ReactNode
+  /** Value type used to render each cell in this column. Defaults to `text`. */
+  type?: DataGridCellValueType
+  /** Horizontal alignment of the column's cells and header. */
+  align?: DataGridAlign
+  /** Whether the column can be sorted. */
+  sortable?: boolean
+  /** Whether the column's cells can be edited inline (click / Enter to open the editor). */
+  editable?: boolean
+  /**
+   * Options for a `select` / `tags` column's inline picker editor. Required to make those types
+   * editable — without options there is nothing to pick, so the cell stays read-only.
+   */
+  options?: DataGridSelectOption[]
+  /** Whether the column can be resized by dragging its header's trailing edge. */
+  resizable?: boolean
+  /** Fixed column width (number = px, or any CSS width string); unsized columns share the space. */
+  width?: number | string
+  /** Minimum width in px when the column is resized. Defaults to 64. */
+  minWidth?: number
+  /**
+   * Live pin for sticky rendering — `useStickyColumns` reads this, and the composed DataGrid stamps
+   * it from `layout.pinned`. Setting it on a column definition does **not** seed the composed grid:
+   * pass `defaultLayout.pinned` (or controlled `layout.pinned`) instead. Give pinned columns a
+   * fixed `width`; an unsized one falls back to the default width for the sticky offset.
+   */
+  pinned?: DataGridPinSide
+  /**
+   * Leading type-marker icon for the header. `undefined` (omitted) uses the icon for `type`; pass
+   * `null` to hide the icon entirely.
+   */
+  typeIcon?: React.ComponentType<RestrictedIconProps> | null
+  /**
+   * Custom cell content for this column. When set, the grid renders this instead of the typed
+   * `DataGridCellValue` — used for rich cells (links, badges, actions) and for nested-row carets
+   * (`DataGridTreeCell`). The cell chrome (gridlines, pin, selection paint, find) still comes from
+   * `DataGridCell`.
+   *
+   * Setting `render` also opts this column out of built-in editors and of _starting_ a cell-range
+   * drag (`pointerdown` is left to the custom content, which may be a link or button). A range
+   * started on a neighbour can still extend into the cell. Do not set `editable: true` and `render`
+   * on the same column expecting the typed editor to open.
+   */
+  render?: (value: unknown, row: DataGridRowData) => React.ReactNode
+}
+
+/** A row of data for the composed `DataGrid`. Keys match column `key`s; `id` is the stable row id. */
+export interface DataGridRowData {
+  /** Stable row id. */
+  id: DataGridRowId
+  /** Cell values keyed by column key. */
+  [key: string]: unknown
+}