@lovett/ui 0.0.1 → 0.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lovett/ui",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "private": false,
   "publishConfig": {
     "access": "restricted"

package/src/data-grid/data-grid.tsx

@@ -44,6 +44,7 @@ import { DrawerPanel } from './drawer-panel'
 import { DataGridTableView } from './table-view'
 import { useGridColumns } from './use-grid-columns'
 import { useGridEditing } from './use-grid-editing'
+import { SCROLL_EDGES_AT_REST, type ScrollEdges } from './sticky'
 import type {
   DataGridDrawerPanelProps,
   DataGridProps,
@@ -86,6 +87,8 @@ export function DataGrid<Row extends DataGridRowBase, ColumnId extends string>({
   drawerModal = false,
   drawerSize,
   stickySummaryFooter = false,
+  stickyHeader = false,
+  fillWidth = false,
   fillAvailableHeight = false,
   tableContainerClassName,
   onRowsChange,
@@ -96,6 +99,8 @@ export function DataGrid<Row extends DataGridRowBase, ColumnId extends string>({
   const [drawerCell, setDrawerCell] =
     useState<EditingCell<ColumnId> | null>(null)
   const [selectedRowIds, setSelectedRowIds] = useState<string[]>([])
+  const [scrollEdges, setScrollEdges] =
+    useState<ScrollEdges>(SCROLL_EDGES_AT_REST)
   const reactInstanceId = useId()
   const instanceId = useMemo(
     () => reactInstanceId.replace(/:/g, ''),
@@ -317,6 +322,53 @@ export function DataGrid<Row extends DataGridRowBase, ColumnId extends string>({
     onToolbarPropsChange?.(toolbarProps)
   }, [onToolbarPropsChange, toolbarProps])
 
+  // Track which edges of the scroll viewport are at rest, so sticky/pinned
+  // cells can show a scroll-shadow only when content is scrolled past them.
+  const hasPinnedColumn = useMemo(
+    () => columns.some((column) => column.pin),
+    [columns],
+  )
+  useEffect(() => {
+    if (!stickyHeader && !stickySummaryFooter && !hasPinnedColumn) return
+    const scroller = tableRef.current?.parentElement
+    if (!scroller) return
+
+    let frame = 0
+    const measure = () => {
+      frame = 0
+      const next: ScrollEdges = {
+        atTop: scroller.scrollTop <= 0,
+        atBottom:
+          scroller.scrollTop + scroller.clientHeight >= scroller.scrollHeight - 1,
+        atLeft: scroller.scrollLeft <= 0,
+        atRight:
+          scroller.scrollLeft + scroller.clientWidth >= scroller.scrollWidth - 1,
+      }
+      setScrollEdges((prev) =>
+        prev.atTop === next.atTop &&
+        prev.atBottom === next.atBottom &&
+        prev.atLeft === next.atLeft &&
+        prev.atRight === next.atRight
+          ? prev
+          : next,
+      )
+    }
+    const onScroll = () => {
+      if (!frame) frame = requestAnimationFrame(measure)
+    }
+
+    measure()
+    scroller.addEventListener('scroll', onScroll, { passive: true })
+    const observer = new ResizeObserver(measure)
+    observer.observe(scroller)
+
+    return () => {
+      scroller.removeEventListener('scroll', onScroll)
+      observer.disconnect()
+      if (frame) cancelAnimationFrame(frame)
+    }
+  }, [stickyHeader, stickySummaryFooter, hasPinnedColumn, rows.length, columnWidths])
+
   return (
     <>
       <div
@@ -361,6 +413,9 @@ export function DataGrid<Row extends DataGridRowBase, ColumnId extends string>({
             showSummaries={showSummaries}
             renderSummary={renderSummary}
             stickySummaryFooter={stickySummaryFooter}
+            stickyHeader={stickyHeader}
+            fillWidth={fillWidth}
+            scrollEdges={scrollEdges}
             tableContainerClassName={tableContainerClassName}
             isEmptyValue={isEmptyValue}
             onResizeStart={beginResize}

package/src/data-grid/sortable-parts.tsx

@@ -16,6 +16,7 @@
  */
 
 import type {
+  CSSProperties,
   KeyboardEvent as ReactKeyboardEvent,
   PointerEvent as ReactPointerEvent,
 } from 'react'
@@ -43,6 +44,9 @@ type SortableHeaderCellProps<ColumnId extends string> = {
   /** ADR-027 — header click handler. When omitted the header is non-
    * interactive for sort (column reorder + resize still work). */
   onSortChange: ((columnId: ColumnId) => void) | undefined
+  /** Extra style merged onto the <th> (sticky/pinned positioning, opaque
+   * background + scroll-shadow). Spread last so it wins over the base. */
+  cellStyle?: CSSProperties
 }
 
 type SortableColumnOptionItemProps<ColumnId extends string> = {
@@ -130,6 +134,7 @@ export function SortableHeaderCell<ColumnId extends string>({
   onResize,
   sortDir,
   onSortChange,
+  cellStyle,
 }: SortableHeaderCellProps<ColumnId>) {
   // ADR-027 — column sortability: explicit `sortable: false` opts out;
   // missing `onSortChange` also disables (no parent handler).
@@ -173,6 +178,7 @@ export function SortableHeaderCell<ColumnId extends string>({
         borderRight: '1px solid rgb(var(--border))',
         background: 'rgb(var(--surface-overlay-soft))',
         color: 'rgb(var(--foreground))',
+        ...cellStyle,
       }}
     >
       <div className="flex h-full min-w-0 items-center justify-between gap-1 overflow-hidden">

package/src/data-grid/sticky.ts

@@ -0,0 +1,152 @@
+/**
+ * Sticky / pinned-column helpers for DataGrid.
+ *
+ * Centralizes the styling for the grid's three sticky surfaces so they
+ * behave consistently:
+ *   • sticky header (top) and sticky summary footer (bottom)
+ *   • pinned columns (`column.pin: 'left' | 'right'`), with the built-in
+ *     select/control column implicitly pinned left
+ *   • a trailing flex "spacer" column (`fillWidth`) so the table fills
+ *     100% width while real columns keep their exact widths (resize stays
+ *     independent — the spacer gives/takes the slack)
+ *
+ * Two correctness rules every sticky cell must follow:
+ *   1. it MUST be opaque, or scrolled content bleeds through it; and
+ *   2. it shows a soft "scroll shadow" on its inner edge ONLY while there
+ *      is content scrolled past that edge — so there's visual separation
+ *      while pinned, and it disappears flush when snapped back.
+ */
+
+import type { CSSProperties } from 'react'
+
+import type { DataGridColumn } from './types'
+
+export const CONTROL_COLUMN_WIDTH = 40
+
+/** Which edges of the scroll viewport are currently AT rest (not scrolled
+ * away from). A shadow on a given side shows when its edge is NOT `at*`. */
+export type ScrollEdges = {
+  atTop: boolean
+  atBottom: boolean
+  atLeft: boolean
+  atRight: boolean
+}
+
+/** Default = everything at rest → no shadows (used before first scroll). */
+export const SCROLL_EDGES_AT_REST: ScrollEdges = {
+  atTop: true,
+  atBottom: true,
+  atLeft: true,
+  atRight: true,
+}
+
+const SHADOW_RIGHT = '6px 0 8px -6px rgba(2, 6, 23, 0.22)' // pinned-left edge
+const SHADOW_LEFT = '-6px 0 8px -6px rgba(2, 6, 23, 0.22)' // pinned-right edge
+const SHADOW_DOWN = '0 6px 8px -6px rgba(2, 6, 23, 0.22)' //  sticky header
+const SHADOW_UP = '0 -6px 8px -6px rgba(2, 6, 23, 0.22)' //   sticky footer
+
+export type PinInfo = { side: 'left' | 'right'; offset: number }
+
+/** Map each pinned column → its side + cumulative sticky offset (px), so
+ * multiple pinned columns on the same side stack correctly. The control
+ * column occupies the first `CONTROL_COLUMN_WIDTH` on the left. */
+export function computePinOffsets<ColumnId extends string>(
+  visibleColumns: DataGridColumn<ColumnId>[],
+  columnWidths: Record<ColumnId, number>,
+): Map<ColumnId, PinInfo> {
+  const map = new Map<ColumnId, PinInfo>()
+  const widthOf = (c: DataGridColumn<ColumnId>) =>
+    columnWidths[c.id] ?? c.defaultWidth
+
+  let leftOffset = CONTROL_COLUMN_WIDTH
+  for (const c of visibleColumns) {
+    if (c.pin !== 'left') continue
+    map.set(c.id, { side: 'left', offset: leftOffset })
+    leftOffset += widthOf(c)
+  }
+
+  let rightOffset = 0
+  const rightPinned = visibleColumns.filter((c) => c.pin === 'right')
+  for (let i = rightPinned.length - 1; i >= 0; i -= 1) {
+    const c = rightPinned[i]
+    if (!c) continue
+    map.set(c.id, { side: 'right', offset: rightOffset })
+    rightOffset += widthOf(c)
+  }
+
+  return map
+}
+
+/** Split a column list at the first right-pinned column, so renderers can
+ * drop the flex spacer immediately before the right-pinned group (or at
+ * the end when nothing is pinned right). */
+export function splitAtRightPinned<ColumnId extends string>(
+  visibleColumns: DataGridColumn<ColumnId>[],
+): {
+  leading: DataGridColumn<ColumnId>[]
+  rightPinned: DataGridColumn<ColumnId>[]
+} {
+  const firstRight = visibleColumns.findIndex((c) => c.pin === 'right')
+  if (firstRight === -1) {
+    return { leading: visibleColumns, rightPinned: [] }
+  }
+  return {
+    leading: visibleColumns.slice(0, firstRight),
+    rightPinned: visibleColumns.slice(firstRight),
+  }
+}
+
+type Role = 'header' | 'body' | 'footer'
+
+/** Opaque background. Header composites its translucent tint over an
+ * opaque base so it still reads tinted but never lets content through. */
+function opaqueBg(role: Role): CSSProperties {
+  if (role === 'header') {
+    return {
+      backgroundColor: 'rgb(var(--bg-card))',
+      backgroundImage:
+        'linear-gradient(rgb(var(--surface-overlay-soft)), rgb(var(--surface-overlay-soft)))',
+    }
+  }
+  return { backgroundColor: 'rgb(var(--bg-card))' }
+}
+
+/**
+ * Compute the inline style for a (possibly) sticky cell. Returns `{}` when
+ * the cell isn't sticky in any axis, so callers can spread it
+ * unconditionally.
+ */
+export function stickyCellStyle(opts: {
+  role: Role
+  pin?: PinInfo | null
+  edges: ScrollEdges
+  stickyHeader: boolean
+  stickyFooter: boolean
+}): CSSProperties {
+  const { role, pin, edges, stickyHeader, stickyFooter } = opts
+  const verticalSticky =
+    (role === 'header' && stickyHeader) || (role === 'footer' && stickyFooter)
+  if (!verticalSticky && !pin) return {}
+
+  const style: CSSProperties = { position: 'sticky' }
+
+  if (role === 'header' && stickyHeader) style.top = 0
+  if (role === 'footer' && stickyFooter) style.bottom = 0
+  if (pin?.side === 'left') style.left = pin.offset
+  if (pin?.side === 'right') style.right = pin.offset
+
+  Object.assign(style, opaqueBg(role))
+
+  // Corners (vertical-sticky ∩ pinned) must sit above both axes.
+  const vertZ = role === 'header' ? 30 : role === 'footer' ? 20 : 0
+  style.zIndex = vertZ + (pin ? 10 : 0) || (pin ? 10 : undefined)
+
+  const shadows: string[] = []
+  if (role === 'header' && stickyHeader && !edges.atTop) shadows.push(SHADOW_DOWN)
+  if (role === 'footer' && stickyFooter && !edges.atBottom) shadows.push(SHADOW_UP)
+  if (pin?.side === 'left' && !edges.atLeft) shadows.push(SHADOW_RIGHT)
+  if (pin?.side === 'right' && !edges.atRight) shadows.push(SHADOW_LEFT)
+  if (shadows.length) style.boxShadow = shadows.join(', ')
+
+  return style
+}

package/src/data-grid/table-body.tsx

@@ -18,6 +18,8 @@
  *    rather than the Input primitive — the input is intentionally
  *    compact (h-7) and edge-to-edge inside the cell, not a typical
  *    form input.
+ *  • Pinned columns + fill-width spacer (workspace addition) via the
+ *    shared sticky helper.
  */
 
 import type {
@@ -33,6 +35,12 @@ import { Button } from '../button'
 import { Checkbox } from '../checkbox'
 import { TableBody, TableCell, TableRow } from './table-elements'
 
+import {
+  splitAtRightPinned,
+  stickyCellStyle,
+  type PinInfo,
+  type ScrollEdges,
+} from './sticky'
 import type {
   DataGridColumn,
   DataGridRowBase,
@@ -68,6 +76,9 @@ type DataGridTableBodyProps<
   onToggleRowSelection: (rowId: string, checked: boolean) => void
   columnWidths: Record<ColumnId, number>
   draggingColumnId: ColumnId | null
+  pinOffsets: Map<ColumnId, PinInfo>
+  scrollEdges: ScrollEdges
+  fillWidth: boolean
 }
 
 export function DataGridTableBody<
@@ -93,14 +104,161 @@ export function DataGridTableBody<
   onToggleRowSelection,
   columnWidths,
   draggingColumnId,
+  pinOffsets,
+  scrollEdges,
+  fillWidth,
 }: DataGridTableBodyProps<Row, ColumnId>) {
+  const { leading, rightPinned } = splitAtRightPinned(visibleColumns)
+
+  const controlStyle = stickyCellStyle({
+    role: 'body',
+    pin: { side: 'left', offset: 0 },
+    edges: scrollEdges,
+    stickyHeader: false,
+    stickyFooter: false,
+  })
+
+  const renderDataCell = (
+    row: Row,
+    rowIndex: number,
+    column: DataGridColumn<ColumnId>,
+    colIndex: number,
+  ) => {
+    const isEditing =
+      editingCell?.rowId === row.id && editingCell.columnId === column.id
+    const editable = isEditableColumn(column.id)
+    const showDrawerAction = canOpenDrawer(column.id)
+    const isDraggingThisColumn = draggingColumnId === column.id
+    const sticky = stickyCellStyle({
+      role: 'body',
+      pin: pinOffsets.get(column.id) ?? null,
+      edges: scrollEdges,
+      stickyHeader: false,
+      stickyFooter: false,
+    })
+
+    return (
+      <TableCell
+        key={`${row.id}-${column.id}`}
+        data-grid-cell="true"
+        data-row-index={rowIndex}
+        data-col-index={colIndex}
+        tabIndex={isEditing ? -1 : 0}
+        className={cn(
+          'group/cell relative h-10 overflow-hidden px-2 py-1 whitespace-nowrap outline-none',
+          editable && 'cursor-text',
+        )}
+        style={{
+          width: columnWidths[column.id],
+          minWidth: columnWidths[column.id],
+          borderRight: '1px solid rgb(var(--border))',
+          ...sticky,
+          ...(isDraggingThisColumn
+            ? { background: 'rgb(var(--surface-overlay-soft))' }
+            : null),
+        }}
+        onDoubleClick={() => {
+          if (editable) startEditing(row, column.id)
+        }}
+        onKeyDown={(event) =>
+          onCellKeyDown(event, row, rowIndex, column, colIndex)
+        }
+      >
+        {isEditing ? (
+          <input
+            ref={inputRef}
+            value={draftValue}
+            onChange={(event) => setDraftValue(event.target.value)}
+            onBlur={commitEdit}
+            onKeyDown={(event) => {
+              if (event.key === 'Enter') {
+                event.preventDefault()
+                commitEdit()
+              }
+
+              if (event.key === 'Escape') {
+                event.preventDefault()
+                cancelEdit()
+              }
+            }}
+            className="h-7 w-full px-2 text-xs outline-none rounded-[var(--radius-sm)]"
+            style={{
+              background: 'rgb(var(--bg-input))',
+              border: '1px solid rgb(var(--border-strong))',
+              color: 'rgb(var(--foreground))',
+            }}
+          />
+        ) : (
+          <>
+            <span
+              aria-hidden
+              className="pointer-events-none absolute inset-0 transition-colors duration-150"
+              style={{ border: '1px solid transparent' }}
+            />
+            <div
+              className={cn(
+                'min-w-0 truncate transition-[padding] duration-150',
+                showDrawerAction &&
+                  'group-hover/cell:pr-16 group-focus-within/cell:pr-16',
+              )}
+              style={{ color: 'rgb(var(--foreground))' }}
+            >
+              {renderCell(row, column)}
+            </div>
+            {showDrawerAction ? (
+              <div className="pointer-events-none absolute top-1/2 right-1.5 z-10 -translate-y-1/2 opacity-0 transition-all group-focus-within/cell:pointer-events-auto group-focus-within/cell:opacity-100 group-hover/cell:pointer-events-auto group-hover/cell:opacity-100">
+                <Button
+                  type="button"
+                  variant="outline"
+                  size="sm"
+                  aria-label={`Open details for ${getRowLabel(row)} ${column.label}`}
+                  title="Open drawer"
+                  className="h-7 px-2.5"
+                  onPointerDown={(event) => {
+                    event.stopPropagation()
+                  }}
+                  onDoubleClick={(event) => {
+                    event.stopPropagation()
+                  }}
+                  onClick={(event) => {
+                    event.stopPropagation()
+                    const originElement =
+                      event.currentTarget.closest('td') ?? event.currentTarget
+                    const originRect = originElement.getBoundingClientRect()
+
+                    onOpenDrawer({
+                      rowId: row.id,
+                      columnId: column.id,
+                      originRect: {
+                        x: originRect.x,
+                        y: originRect.y,
+                        width: originRect.width,
+                        height: originRect.height,
+                      },
+                    })
+                  }}
+                  leadingIcon={<ExternalLink className="h-3.5 w-3.5" />}
+                >
+                  Open
+                </Button>
+              </div>
+            ) : null}
+          </>
+        )}
+      </TableCell>
+    )
+  }
+
   return (
     <TableBody>
       {visibleRows.map((row, rowIndex) => (
         <TableRow key={row.id}>
           <TableCell
             className="h-10 px-0 text-center"
-            style={{ borderRight: '1px solid rgb(var(--border))' }}
+            style={{
+              borderRight: '1px solid rgb(var(--border))',
+              ...controlStyle,
+            }}
           >
             <Checkbox
               aria-label={`Select ${getRowLabel(row)}`}
@@ -111,126 +269,15 @@ export function DataGridTableBody<
               className="mx-auto"
             />
           </TableCell>
-          {visibleColumns.map((column, colIndex) => {
-            const isEditing =
-              editingCell?.rowId === row.id &&
-              editingCell.columnId === column.id
-            const editable = isEditableColumn(column.id)
-            const showDrawerAction = canOpenDrawer(column.id)
-            const isDraggingThisColumn = draggingColumnId === column.id
-
-            return (
-              <TableCell
-                key={`${row.id}-${column.id}`}
-                data-grid-cell="true"
-                data-row-index={rowIndex}
-                data-col-index={colIndex}
-                tabIndex={isEditing ? -1 : 0}
-                className={cn(
-                  'group/cell relative h-10 overflow-hidden px-2 py-1 whitespace-nowrap outline-none',
-                  editable && 'cursor-text',
-                )}
-                style={{
-                  width: columnWidths[column.id],
-                  minWidth: columnWidths[column.id],
-                  borderRight: '1px solid rgb(var(--border))',
-                  background: isDraggingThisColumn
-                    ? 'rgb(var(--surface-overlay-soft))'
-                    : undefined,
-                }}
-                onDoubleClick={() => {
-                  if (editable) startEditing(row, column.id)
-                }}
-                onKeyDown={(event) =>
-                  onCellKeyDown(event, row, rowIndex, column, colIndex)
-                }
-              >
-                {isEditing ? (
-                  <input
-                    ref={inputRef}
-                    value={draftValue}
-                    onChange={(event) => setDraftValue(event.target.value)}
-                    onBlur={commitEdit}
-                    onKeyDown={(event) => {
-                      if (event.key === 'Enter') {
-                        event.preventDefault()
-                        commitEdit()
-                      }
-
-                      if (event.key === 'Escape') {
-                        event.preventDefault()
-                        cancelEdit()
-                      }
-                    }}
-                    className="h-7 w-full px-2 text-xs outline-none rounded-[var(--radius-sm)]"
-                    style={{
-                      background: 'rgb(var(--bg-input))',
-                      border: '1px solid rgb(var(--border-strong))',
-                      color: 'rgb(var(--foreground))',
-                    }}
-                  />
-                ) : (
-                  <>
-                    <span
-                      aria-hidden
-                      className="pointer-events-none absolute inset-0 transition-colors duration-150"
-                      style={{ border: '1px solid transparent' }}
-                    />
-                    <div
-                      className={cn(
-                        'min-w-0 truncate transition-[padding] duration-150',
-                        showDrawerAction &&
-                          'group-hover/cell:pr-16 group-focus-within/cell:pr-16',
-                      )}
-                      style={{ color: 'rgb(var(--foreground))' }}
-                    >
-                      {renderCell(row, column)}
-                    </div>
-                    {showDrawerAction ? (
-                      <div className="pointer-events-none absolute top-1/2 right-1.5 z-10 -translate-y-1/2 opacity-0 transition-all group-focus-within/cell:pointer-events-auto group-focus-within/cell:opacity-100 group-hover/cell:pointer-events-auto group-hover/cell:opacity-100">
-                        <Button
-                          type="button"
-                          variant="outline"
-                          size="sm"
-                          aria-label={`Open details for ${getRowLabel(row)} ${column.label}`}
-                          title="Open drawer"
-                          className="h-7 px-2.5"
-                          onPointerDown={(event) => {
-                            event.stopPropagation()
-                          }}
-                          onDoubleClick={(event) => {
-                            event.stopPropagation()
-                          }}
-                          onClick={(event) => {
-                            event.stopPropagation()
-                            const originElement =
-                              event.currentTarget.closest('td') ??
-                              event.currentTarget
-                            const originRect =
-                              originElement.getBoundingClientRect()
-
-                            onOpenDrawer({
-                              rowId: row.id,
-                              columnId: column.id,
-                              originRect: {
-                                x: originRect.x,
-                                y: originRect.y,
-                                width: originRect.width,
-                                height: originRect.height,
-                              },
-                            })
-                          }}
-                          leadingIcon={<ExternalLink className="h-3.5 w-3.5" />}
-                        >
-                          Open
-                        </Button>
-                      </div>
-                    ) : null}
-                  </>
-                )}
-              </TableCell>
-            )
-          })}
+          {leading.map((column, colIndex) =>
+            renderDataCell(row, rowIndex, column, colIndex),
+          )}
+          {fillWidth ? (
+            <td aria-hidden style={{ width: 'auto', padding: 0 }} />
+          ) : null}
+          {rightPinned.map((column, i) =>
+            renderDataCell(row, rowIndex, column, leading.length + i),
+          )}
         </TableRow>
       ))}
     </TableBody>

package/src/data-grid/table-header.tsx

@@ -11,6 +11,8 @@
  *  • Token reskin per ADR-025 D7
  *  • Checkbox imported from workspace BUILD_FRESH primitive (DEV-2)
  *  • Table sub-components from local table-elements (DEV-1)
+ *  • Sticky header + pinned columns + fill-width spacer (workspace
+ *    addition) via the shared sticky helper.
  */
 
 import type { PointerEvent as ReactPointerEvent } from 'react'
@@ -19,10 +21,15 @@ import { Checkbox } from '../checkbox'
 import { TableHead, TableHeader, TableRow } from './table-elements'
 
 import { SortableHeaderCell } from './sortable-parts'
+import {
+  CONTROL_COLUMN_WIDTH,
+  splitAtRightPinned,
+  stickyCellStyle,
+  type PinInfo,
+  type ScrollEdges,
+} from './sticky'
 import type { DataGridColumn, DataGridSortState } from './types'
 
-const CONTROL_COLUMN_WIDTH = 40
-
 type DataGridTableHeaderProps<ColumnId extends string> = {
   visibleColumns: DataGridColumn<ColumnId>[]
   columnWidths: Record<ColumnId, number>
@@ -35,6 +42,10 @@ type DataGridTableHeaderProps<ColumnId extends string> = {
   ) => void
   sort: DataGridSortState<ColumnId> | null
   onSortChange: ((columnId: ColumnId) => void) | undefined
+  pinOffsets: Map<ColumnId, PinInfo>
+  scrollEdges: ScrollEdges
+  stickyHeader: boolean
+  fillWidth: boolean
 }
 
 export function DataGridTableHeader<ColumnId extends string>({
@@ -46,16 +57,60 @@ export function DataGridTableHeader<ColumnId extends string>({
   onResizeStart,
   sort,
   onSortChange,
+  pinOffsets,
+  scrollEdges,
+  stickyHeader,
+  fillWidth,
 }: DataGridTableHeaderProps<ColumnId>) {
+  const { leading, rightPinned } = splitAtRightPinned(visibleColumns)
+
+  const styleFor = (column: DataGridColumn<ColumnId>) =>
+    stickyCellStyle({
+      role: 'header',
+      pin: pinOffsets.get(column.id) ?? null,
+      edges: scrollEdges,
+      stickyHeader,
+      stickyFooter: false,
+    })
+
+  const controlStyle = stickyCellStyle({
+    role: 'header',
+    pin: { side: 'left', offset: 0 },
+    edges: scrollEdges,
+    stickyHeader,
+    stickyFooter: false,
+  })
+
+  const spacerStyle = stickyCellStyle({
+    role: 'header',
+    pin: null,
+    edges: scrollEdges,
+    stickyHeader,
+    stickyFooter: false,
+  })
+
+  const renderHeadCell = (column: DataGridColumn<ColumnId>) => (
+    <SortableHeaderCell
+      key={column.id}
+      column={column}
+      width={columnWidths[column.id]}
+      onResize={onResizeStart}
+      sortDir={sort?.columnId === column.id ? sort.dir : null}
+      onSortChange={onSortChange}
+      cellStyle={styleFor(column)}
+    />
+  )
+
   return (
     <>
       <colgroup>
         <col style={{ width: CONTROL_COLUMN_WIDTH }} />
-        {visibleColumns.map((column) => (
-          <col
-            key={`col-${column.id}`}
-            style={{ width: columnWidths[column.id] }}
-          />
+        {leading.map((column) => (
+          <col key={`col-${column.id}`} style={{ width: columnWidths[column.id] }} />
+        ))}
+        {fillWidth ? <col style={{ width: 'auto' }} /> : null}
+        {rightPinned.map((column) => (
+          <col key={`col-${column.id}`} style={{ width: columnWidths[column.id] }} />
         ))}
       </colgroup>
 
@@ -66,6 +121,7 @@ export function DataGridTableHeader<ColumnId extends string>({
             style={{
               borderRight: '1px solid rgb(var(--border))',
               background: 'rgb(var(--surface-overlay-soft))',
+              ...controlStyle,
             }}
           >
             <Checkbox
@@ -76,18 +132,11 @@ export function DataGridTableHeader<ColumnId extends string>({
               className="mx-auto"
             />
           </TableHead>
-          {visibleColumns.map((column) => (
-            <SortableHeaderCell
-              key={column.id}
-              column={column}
-              width={columnWidths[column.id]}
-              onResize={onResizeStart}
-              sortDir={
-                sort?.columnId === column.id ? sort.dir : null
-              }
-              onSortChange={onSortChange}
-            />
-          ))}
+          {leading.map(renderHeadCell)}
+          {fillWidth ? (
+            <th aria-hidden style={{ width: 'auto', padding: 0, ...spacerStyle }} />
+          ) : null}
+          {rightPinned.map(renderHeadCell)}
         </TableRow>
       </TableHeader>
     </>

package/src/data-grid/table-summary-footer.tsx

@@ -6,14 +6,21 @@
  * License: MIT (see packages/ui/licenses/gray-ui-csm-LICENSE.txt)
  * Workspace ADR: ADR-025
  *
- * BRING_WITH_REFACTOR: token reskin per ADR-025 D7.
+ * BRING_WITH_REFACTOR: token reskin per ADR-025 D7; sticky footer +
+ * pinned columns + fill-width spacer via the shared sticky helper.
  */
 
-import type { CSSProperties, ReactNode } from 'react'
+import type { ReactNode } from 'react'
 
 import { cn } from '../lib/utils'
 import { TableCell, TableFooter, TableRow } from './table-elements'
 
+import {
+  splitAtRightPinned,
+  stickyCellStyle,
+  type PinInfo,
+  type ScrollEdges,
+} from './sticky'
 import type { DataGridColumn, DataGridRowBase } from './types'
 
 type DataGridSummaryFooterProps<
@@ -33,6 +40,9 @@ type DataGridSummaryFooterProps<
   columnWidths: Record<ColumnId, number>
   draggingColumnId: ColumnId | null
   isEmptyValue: (value: ReactNode) => boolean
+  pinOffsets: Map<ColumnId, PinInfo>
+  scrollEdges: ScrollEdges
+  fillWidth: boolean
 }
 
 export function DataGridSummaryFooter<
@@ -47,18 +57,48 @@ export function DataGridSummaryFooter<
   columnWidths,
   draggingColumnId,
   isEmptyValue,
+  pinOffsets,
+  scrollEdges,
+  fillWidth,
 }: DataGridSummaryFooterProps<Row, ColumnId>) {
   if (!showSummaries || !renderSummary) return null
 
-  const stickyCellStyle: CSSProperties | undefined = stickySummaryFooter
-    ? {
-        position: 'sticky',
-        bottom: 0,
-        zIndex: 10,
-        background: 'rgb(var(--bg-card))',
-        borderTop: '1px solid rgb(var(--border))',
-      }
-    : undefined
+  const { leading, rightPinned } = splitAtRightPinned(visibleColumns)
+
+  const footerStyle = (pin: PinInfo | null) =>
+    stickyCellStyle({
+      role: 'footer',
+      pin,
+      edges: scrollEdges,
+      stickyHeader: false,
+      stickyFooter: stickySummaryFooter,
+    })
+
+  const renderSummaryCell = (column: DataGridColumn<ColumnId>) => {
+    const summaryContent = renderSummary(column, visibleRows)
+    const isDraggingThisColumn = draggingColumnId === column.id
+
+    return (
+      <TableCell
+        key={`summary-${column.id}`}
+        className={cn('h-10 px-2 py-1 text-left text-xs whitespace-nowrap')}
+        style={{
+          width: columnWidths[column.id],
+          minWidth: columnWidths[column.id],
+          color: 'rgb(var(--text-muted))',
+          borderRight: '1px solid rgb(var(--border))',
+          ...footerStyle(pinOffsets.get(column.id) ?? null),
+          ...(isDraggingThisColumn
+            ? { background: 'rgb(var(--surface-overlay-soft))' }
+            : null),
+        }}
+      >
+        {!isEmptyValue(summaryContent) ? (
+          <span className="inline-block">{summaryContent}</span>
+        ) : null}
+      </TableCell>
+    )
+  }
 
   return (
     <TableFooter>
@@ -67,34 +107,17 @@ export function DataGridSummaryFooter<
           className={cn('h-10 px-2 py-1')}
           style={{
             borderRight: '1px solid rgb(var(--border))',
-            ...stickyCellStyle,
+            ...footerStyle({ side: 'left', offset: 0 }),
           }}
         />
-        {visibleColumns.map((column) => {
-          const summaryContent = renderSummary(column, visibleRows)
-          const isDraggingThisColumn = draggingColumnId === column.id
-
-          return (
-            <TableCell
-              key={`summary-${column.id}`}
-              className={cn('h-10 px-2 py-1 text-left text-xs whitespace-nowrap')}
-              style={{
-                width: columnWidths[column.id],
-                minWidth: columnWidths[column.id],
-                color: 'rgb(var(--text-muted))',
-                borderRight: '1px solid rgb(var(--border))',
-                background: isDraggingThisColumn
-                  ? 'rgb(var(--surface-overlay-soft))'
-                  : stickyCellStyle?.background,
-                ...stickyCellStyle,
-              }}
-            >
-              {!isEmptyValue(summaryContent) ? (
-                <span className="inline-block">{summaryContent}</span>
-              ) : null}
-            </TableCell>
-          )
-        })}
+        {leading.map(renderSummaryCell)}
+        {fillWidth ? (
+          <td
+            aria-hidden
+            style={{ width: 'auto', padding: 0, ...footerStyle(null) }}
+          />
+        ) : null}
+        {rightPinned.map(renderSummaryCell)}
       </TableRow>
     </TableFooter>
   )

package/src/data-grid/table-view.tsx

@@ -25,6 +25,7 @@ import {
   DataGridTableBody,
   DataGridTableHeader,
 } from './table-parts'
+import { computePinOffsets, type ScrollEdges } from './sticky'
 import type {
   DataGridColumn,
   DataGridRowBase,
@@ -73,6 +74,9 @@ type DataGridTableViewProps<
       ) => ReactNode)
     | undefined
   stickySummaryFooter: boolean
+  stickyHeader: boolean
+  fillWidth: boolean
+  scrollEdges: ScrollEdges
   tableContainerClassName: string | undefined
   isEmptyValue: (value: ReactNode) => boolean
   onResizeStart: (
@@ -114,6 +118,9 @@ export function DataGridTableView<
   showSummaries,
   renderSummary,
   stickySummaryFooter,
+  stickyHeader,
+  fillWidth,
+  scrollEdges,
   tableContainerClassName,
   isEmptyValue,
   onResizeStart,
@@ -121,6 +128,7 @@ export function DataGridTableView<
   sort,
   onSortChange,
 }: DataGridTableViewProps<Row, ColumnId>) {
+  const pinOffsets = computePinOffsets(visibleColumns, columnWidths)
   return (
     <Table
       ref={tableRef}
@@ -137,6 +145,10 @@ export function DataGridTableView<
         onResizeStart={onResizeStart}
         sort={sort}
         onSortChange={onSortChange}
+        pinOffsets={pinOffsets}
+        scrollEdges={scrollEdges}
+        stickyHeader={stickyHeader}
+        fillWidth={fillWidth}
       />
 
       <DataGridTableBody
@@ -159,6 +171,9 @@ export function DataGridTableView<
         onToggleRowSelection={onToggleRowSelection}
         columnWidths={columnWidths}
         draggingColumnId={draggingColumnId}
+        pinOffsets={pinOffsets}
+        scrollEdges={scrollEdges}
+        fillWidth={fillWidth}
       />
 
       <DataGridSummaryFooter
@@ -170,6 +185,9 @@ export function DataGridTableView<
         columnWidths={columnWidths}
         draggingColumnId={draggingColumnId}
         isEmptyValue={isEmptyValue}
+        pinOffsets={pinOffsets}
+        scrollEdges={scrollEdges}
+        fillWidth={fillWidth}
       />
     </Table>
   )

package/src/data-grid/types.ts

@@ -31,6 +31,12 @@ export type DataGridColumn<ColumnId extends string> = {
    * `onSortChange` is provided; false when not. Set explicitly to disable
    * sorting for columns that don't have a meaningful comparator. */
   sortable?: boolean
+  /** Pin this column to the left or right edge so it stays visible while
+   * the grid scrolls horizontally. Pinned columns render opaque with a
+   * soft scroll-shadow on their inner edge. Place left-pinned columns
+   * first and right-pinned columns last. The built-in select column is
+   * always pinned left. */
+  pin?: 'left' | 'right'
 }
 
 /** Row-sort state (ADR-027). DataGrid renders the chevron + ARIA per
@@ -115,6 +121,15 @@ export type DataGridProps<
    * Defaults to 520 (the FloatingDrawer side="right" default). */
   drawerSize?: number
   stickySummaryFooter?: boolean
+  /** Keep the header row pinned to the top while the body scrolls. Renders
+   * opaque with a scroll-shadow once scrolled. Default false. */
+  stickyHeader?: boolean
+  /** Stretch the table to fill its container width via a trailing flex
+   * "spacer" column that absorbs leftover space — real columns keep their
+   * exact widths, so column resize stays independent. When the columns
+   * outgrow the viewport the spacer collapses to 0 and the grid scrolls.
+   * Default false. */
+  fillWidth?: boolean
   fillAvailableHeight?: boolean
   tableContainerClassName?: string
   onRowsChange?: (rows: Row[]) => void