@proteos/ui 0.31.0

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

@@ -0,0 +1,556 @@
+import { monitorForElements } from '@atlaskit/pragmatic-drag-and-drop/element/adapter'
+import { extractClosestEdge } from '@atlaskit/pragmatic-drag-and-drop-hitbox/closest-edge'
+import { reorderWithEdge } from '@atlaskit/pragmatic-drag-and-drop-hitbox/util/reorder-with-edge'
+import {
+  type ColumnDef,
+  flexRender,
+  getCoreRowModel,
+  type OnChangeFn,
+  type Row,
+  type SortingState,
+  useReactTable,
+} from '@tanstack/react-table'
+import { useVirtualizer } from '@tanstack/react-virtual'
+import {
+  type CSSProperties,
+  type KeyboardEvent,
+  type MouseEvent,
+  type ReactNode,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
+
+import { cn } from '../../lib/cn'
+import {
+  isColumnDragData,
+  type SortDirection,
+  Table,
+  TableCell,
+  TableHeader,
+  TableHeaderCell,
+  TableHeaderSpacer,
+  TableRow,
+  TableScroller,
+  type TableVariants,
+} from '../table'
+import { DataTableEmpty } from './states/data-table-empty'
+import { DataTableError } from './states/data-table-error'
+import { DataTableSkeleton } from './states/data-table-skeleton'
+import { useInfiniteScrollSentinel } from './use-infinite-scroll-sentinel'
+
+/* =========================================================================
+   DataTable — generic virtualized infinite-scroll table.
+   - TanStack Table v8 owns the column model and sorting state.
+   - TanStack Virtual virtualizes the body against an internal scroller ref.
+   - An IntersectionObserver sentinel triggers `query.fetchNextPage()` ~200 px
+     before the user reaches the bottom. Visuals (loader, end marker, empty,
+     error) match the Anthropic design's `pt-loader`/`pt-end`/`pt-empty`.
+   - The component is data-fetching-shape-agnostic: it accepts anything
+     conforming to InfiniteQueryLike (matches @tanstack/react-query's
+     useInfiniteQuery return shape).
+   ========================================================================= */
+
+type InfinitePage<TRow> = { data: TRow[]; meta?: { items_total?: number } }
+
+export type InfiniteQueryLike<TRow> = {
+  data?: { pages: InfinitePage<TRow>[] } | undefined
+  isLoading: boolean
+  isFetchingNextPage: boolean
+  hasNextPage: boolean | undefined
+  error: Error | null
+  fetchNextPage: () => void
+  refetch?: () => void
+}
+
+export type DataTableProps<TRow> = {
+  query: InfiniteQueryLike<TRow>
+  columns: ColumnDef<TRow>[]
+  sorting?: SortingState
+  onSortingChange?: OnChangeFn<SortingState>
+  rowHeight?: number
+  overscan?: number
+  /**
+   * Called when a row is clicked. Provides both the original data row and
+   * the underlying event so consumers can inspect modifier keys.
+   */
+  onRowClick?: (
+    row: TRow,
+    event: MouseEvent<HTMLDivElement> | KeyboardEvent<HTMLDivElement>,
+  ) => void
+  zebra?: boolean
+  emptyState?: ReactNode
+  errorState?: ReactNode
+  loadingState?: ReactNode
+  /**
+   * Optional accessor used as the React key for each row. Defaults to a
+   * row's `id` field (if present), then `slug`, then index.
+   */
+  getRowId?: (row: TRow, index: number) => string
+  className?: string
+  ariaLabel?: string
+  /**
+   * Enable horizontal drag-and-drop reordering of columns. When on, a grip
+   * handle and `monitorForElements` are wired up; on a successful reorder
+   * `onReorderColumn` fires with the moved column's id and its new index.
+   * Each `ColumnDef` must carry a stable `id` for events to be routable.
+   */
+  enableColumnReordering?: boolean
+  /**
+   * Enable an `×` remove affordance on each column header. The handler is
+   * called with the column's id; the parent decides what removal means
+   * (e.g. filter the displayed `columns` array).
+   */
+  enableColumnRemoval?: boolean
+  onReorderColumn?: (params: { id: string; toIndex: number }) => void
+  onRemoveColumn?: (id: string) => void
+  /**
+   * Visual chrome around the table. `panel` (default) wraps the table in a
+   * bordered, rounded, soft-shadowed card. `bare` strips that chrome so the
+   * table can sit flush with its container — used when the surrounding
+   * surface already supplies borders (e.g. the Query Builder's results pane).
+   */
+  variant?: TableVariants['variant']
+  /**
+   * Optional per-row wrapper. When provided, the row's cell content is
+   * passed through this function, which may render context providers (e.g.
+   * a row-scoped TanStack Form for inline editing) around the cells. The
+   * default is identity — cells render directly inside the `<TableRow>`.
+   */
+  rowWrapper?: (row: Row<TRow>, cells: ReactNode) => ReactNode
+  /**
+   * Extra rows rendered alongside the server data. Used for inline-editable
+   * draft rows that are not yet persisted. `start` rows render above the
+   * server data, `end` rows below. They participate in the same column
+   * model, virtualization, and `rowWrapper` as server rows.
+   */
+  extraRows?: { start?: TRow[]; end?: TRow[] }
+  /**
+   * Slot rendered ABOVE the body (above the virtualized region). Used for
+   * controls like an Add row button at slot='start'. Stays put when the
+   * body scrolls (sits inside the header sticky region or just below it).
+   */
+  bodyBefore?: ReactNode
+  /**
+   * Slot rendered BELOW the body. Used for controls like an Add row button
+   * at slot='end'. Sits inside the scrollable area below the rows.
+   */
+  bodyAfter?: ReactNode
+  /**
+   * Draw vertical gridlines between body cells. The header always has them;
+   * the body opts in (e.g. inline-edit mode wants the full Excel-style grid).
+   * Default false — read-only tables stay borderless in the body.
+   */
+  columnBorders?: boolean
+}
+
+const DEFAULT_ROW_HEIGHT = 32
+
+export function DataTable<TRow>({
+  query,
+  columns,
+  sorting,
+  onSortingChange,
+  rowHeight = DEFAULT_ROW_HEIGHT,
+  overscan = 8,
+  onRowClick,
+  zebra = true,
+  emptyState,
+  errorState,
+  loadingState,
+  getRowId,
+  className,
+  ariaLabel,
+  enableColumnReordering = false,
+  enableColumnRemoval = false,
+  onReorderColumn,
+  onRemoveColumn,
+  variant = 'panel',
+  rowWrapper,
+  extraRows,
+  bodyBefore,
+  bodyAfter,
+  columnBorders = false,
+}: DataTableProps<TRow>) {
+  const rows = useMemo<TRow[]>(() => {
+    const pages = query.data?.pages
+    const dataRows = pages && pages.length > 0 ? pages.flatMap((p) => p.data) : []
+    const startExtras = extraRows?.start ?? []
+    const endExtras = extraRows?.end ?? []
+    if (startExtras.length === 0 && endExtras.length === 0) return dataRows
+    return [...startExtras, ...dataRows, ...endExtras]
+  }, [query.data, extraRows])
+
+  const table = useReactTable({
+    data: rows,
+    columns,
+    state: { sorting: sorting ?? [] },
+    ...(onSortingChange ? { onSortingChange } : {}),
+    manualSorting: true,
+    getCoreRowModel: getCoreRowModel(),
+    getRowId: getRowId
+      ? (row, index) => getRowId(row, index)
+      : (row, index) => {
+          const r = row as Record<string, unknown>
+          if (typeof r.id === 'string' || typeof r.id === 'number') return String(r.id)
+          if (typeof r.slug === 'string') return r.slug
+          return String(index)
+        },
+  })
+
+  const tableRows = table.getRowModel().rows
+  const tableRowCount = tableRows.length
+
+  // Reset scroll to top when sorting changes — without this, the user is
+  // staring at a different slice of a freshly-sorted dataset.
+  const scrollerRef = useRef<HTMLDivElement | null>(null)
+  // biome-ignore lint/correctness/useExhaustiveDependencies: intentional — scroll resets on sort change only
+  useEffect(() => {
+    scrollerRef.current?.scrollTo({ top: 0 })
+  }, [sorting])
+
+  // The sticky header lives inside the scroller, ABOVE the row list, so the
+  // list starts at an offset (the header's height, plus any `bodyBefore`).
+  // Feed that offset to the virtualizer as `scrollMargin` so its visible
+  // window math accounts for it; render rows at `start - scrollMargin`.
+  const listRef = useRef<HTMLDivElement | null>(null)
+  const [listOffset, setListOffset] = useState(0)
+  // biome-ignore lint/correctness/useExhaustiveDependencies: re-measure every render; cheap offsetTop read, guarded setState
+  useLayoutEffect(() => {
+    const top = listRef.current?.offsetTop ?? 0
+    setListOffset((prev) => (prev === top ? prev : top))
+  })
+
+  const virtualizer = useVirtualizer({
+    count: tableRowCount,
+    getScrollElement: () => scrollerRef.current,
+    estimateSize: () => rowHeight,
+    overscan,
+    scrollMargin: listOffset,
+  })
+
+  const sentinelRef = useInfiniteScrollSentinel<HTMLDivElement>({
+    onIntersect: () => {
+      if (query.hasNextPage && !query.isFetchingNextPage && !query.isLoading) {
+        query.fetchNextPage()
+      }
+    },
+    rootMargin: '200px',
+    root: scrollerRef.current,
+    enabled: !!query.hasNextPage,
+  })
+
+  const totalColumnWidth = useMemo(
+    () => columns.reduce((sum, c) => sum + (c.size ?? 140), 0),
+    [columns],
+  )
+
+  // Single global pragmatic-dnd monitor for column reorder. We mirror the
+  // entity-designer pattern: read the latest columns + handler via refs so
+  // the monitor doesn't re-register on every render. Gated on
+  // `enableColumnReordering` so it's a no-op when the feature is off.
+  const columnsRef = useRef(columns)
+  columnsRef.current = columns
+  const onReorderRef = useRef(onReorderColumn)
+  onReorderRef.current = onReorderColumn
+
+  useEffect(() => {
+    if (!enableColumnReordering) return
+    return monitorForElements({
+      canMonitor: ({ source }) => isColumnDragData(source.data),
+      onDrop: ({ source, location }) => {
+        const target = location.current.dropTargets[0]
+        if (!target) return
+        if (!isColumnDragData(source.data) || !isColumnDragData(target.data)) return
+        if (source.data.columnId === target.data.columnId) return
+
+        const ids = columnsRef.current.map((c) => c.id).filter((id): id is string => !!id)
+        const startIndex = ids.indexOf(source.data.columnId)
+        const indexOfTarget = ids.indexOf(target.data.columnId)
+        if (startIndex === -1 || indexOfTarget === -1) return
+
+        const closestEdge = extractClosestEdge(target.data)
+        const reordered = reorderWithEdge({
+          list: ids,
+          startIndex,
+          indexOfTarget,
+          closestEdgeOfTarget: closestEdge,
+          axis: 'horizontal',
+        })
+        if (reordered === ids) return
+
+        const sourceId = source.data.columnId
+        onReorderRef.current?.({ id: sourceId, toIndex: reordered.indexOf(sourceId) })
+      },
+    })
+  }, [enableColumnReordering])
+
+  const showEmpty =
+    !query.isLoading && !query.error && tableRowCount === 0 && !query.isFetchingNextPage
+  const showInitialLoading = query.isLoading && tableRowCount === 0
+  const showError = !!query.error && tableRowCount === 0
+  const showEndMarker =
+    !query.isLoading && !query.isFetchingNextPage && !query.hasNextPage && tableRowCount > 0
+
+  const totalSize = virtualizer.getTotalSize()
+  const virtualItems = virtualizer.getVirtualItems()
+
+  const headerGroups = table.getHeaderGroups()
+  const minPanelWidth = totalColumnWidth + 24
+
+  return (
+    <Table
+      {...(ariaLabel !== undefined ? { 'aria-label': ariaLabel } : {})}
+      variant={variant}
+      className={cn('flex-1 min-h-0', className)}
+    >
+      {/* Single both-axes scroll container. Horizontal wheel/trackpad scrolls
+          the columns; vertical scrolls the rows. The sticky header pins to the
+          top, and any `sticky left-0` gutter column freezes to the left. */}
+      <TableScroller ref={scrollerRef}>
+        {/* Content track — owns the horizontal min-width so the header + rows
+            scroll horizontally together as one unit. */}
+        <div className="flex flex-col" style={{ minWidth: minPanelWidth }}>
+          {/* Header row(s) — sticky-top so they pin while the rows scroll. */}
+          {headerGroups.map((group) => (
+            <TableHeader key={group.id} sticky>
+              {group.headers.map((header) => {
+                const meta = header.column.columnDef.meta as
+                  | {
+                      align?: 'left' | 'right' | 'center'
+                      sticky?: 'left' | 'right' | false
+                      cellClassName?: string
+                    }
+                  | undefined
+                const align = meta?.align ?? 'left'
+                const sticky = meta?.sticky ?? false
+                const headerSize = header.getSize() || undefined
+                const headerNode = header.isPlaceholder
+                  ? null
+                  : flexRender(header.column.columnDef.header, header.getContext())
+
+                const sorted = header.column.getIsSorted()
+                const direction: SortDirection = sorted === false ? null : sorted
+                const canSort = header.column.getCanSort()
+                const handleSort = header.column.getToggleSortingHandler()
+                const ariaLabel =
+                  typeof header.column.columnDef.header === 'string'
+                    ? header.column.columnDef.header
+                    : header.column.id
+
+                return (
+                  <TableHeaderCell
+                    key={header.id}
+                    align={align}
+                    ariaLabel={ariaLabel}
+                    draggable={enableColumnReordering && !!header.column.id}
+                    {...(header.column.id ? { columnId: header.column.id } : {})}
+                    {...(headerSize !== undefined ? { width: headerSize } : {})}
+                    {...(sticky !== false ? { sticky } : {})}
+                    {...(meta?.cellClassName ? { className: meta.cellClassName } : {})}
+                    {...(canSort
+                      ? {
+                          sortDirection: direction,
+                          onSortToggle: () => handleSort?.({} as never),
+                        }
+                      : {})}
+                    {...(enableColumnRemoval && onRemoveColumn && header.column.id
+                      ? { onRemove: () => onRemoveColumn(header.column.id) }
+                      : {})}
+                  >
+                    {headerNode}
+                  </TableHeaderCell>
+                )
+              })}
+              <TableHeaderSpacer />
+            </TableHeader>
+          ))}
+
+          {bodyBefore}
+
+          {showInitialLoading ? (
+            (loadingState ?? <DataTableSkeleton rowHeight={rowHeight} />)
+          ) : showError ? (
+            <div role="rowgroup">
+              {errorState ?? (query.error ? <DataTableError error={query.error} /> : null)}
+            </div>
+          ) : (
+            <div role="rowgroup">
+              {showEmpty ? (
+                (emptyState ?? <DataTableEmpty />)
+              ) : (
+                <div
+                  ref={listRef}
+                  role="presentation"
+                  style={{ height: totalSize, position: 'relative', width: '100%' }}
+                >
+                  {virtualItems.map((vRow) => {
+                    const row = tableRows[vRow.index]
+                    if (!row) return null
+                    const rowStyle: CSSProperties = {
+                      // Items' `start` includes the virtualizer's scrollMargin
+                      // (the list's offset below the sticky header); subtract
+                      // it to position relative to the list container.
+                      transform: `translateY(${vRow.start - listOffset}px)`,
+                      height: vRow.size,
+                    }
+                    return (
+                      <DataRow
+                        key={row.id}
+                        row={row}
+                        index={vRow.index}
+                        zebra={zebra}
+                        onRowClick={onRowClick}
+                        style={rowStyle}
+                        columnBorders={columnBorders}
+                        {...(rowWrapper ? { rowWrapper } : {})}
+                      />
+                    )
+                  })}
+                </div>
+              )}
+
+              {/* Sentinel — visually empty, positioned just above the loader/end
+                  marker so it intersects ~200 px before the bottom. */}
+              {!showEmpty && (
+                <div ref={sentinelRef} aria-hidden="true" style={{ height: 1, width: '100%' }} />
+              )}
+
+              {query.isFetchingNextPage ? <LoaderRow /> : null}
+              {showEndMarker ? <EndMarker count={tableRowCount} /> : null}
+            </div>
+          )}
+
+          {bodyAfter}
+        </div>
+      </TableScroller>
+    </Table>
+  )
+}
+
+/* ---------- Row ---------------------------------------------------------- */
+
+type DataRowProps<TRow> = {
+  row: Row<TRow>
+  index: number
+  zebra: boolean
+  onRowClick?: DataTableProps<TRow>['onRowClick']
+  style: CSSProperties
+  rowWrapper?: (row: Row<TRow>, cells: ReactNode) => ReactNode
+  columnBorders?: boolean
+}
+
+function DataRow<TRow>({
+  row,
+  index,
+  zebra,
+  onRowClick,
+  style,
+  rowWrapper,
+  columnBorders = false,
+}: DataRowProps<TRow>) {
+  const isAlt = zebra && index % 2 === 1
+  const interactive = !!onRowClick
+
+  const cells = row.getVisibleCells().map((cell) => {
+    const meta = cell.column.columnDef.meta as
+      | {
+          align?: 'left' | 'right' | 'center'
+          mono?: boolean
+          ink?: boolean
+          sticky?: 'left' | 'right' | false
+          /** Extra classes merged onto the cell — e.g. to drop the default
+           *  horizontal padding for a narrow fixed-width gutter column. */
+          cellClassName?: string
+        }
+      | undefined
+    const cellSize = cell.column.getSize() || undefined
+    const cellClassName = cn(
+      columnBorders ? 'border-r border-rule-2' : undefined,
+      meta?.cellClassName,
+    )
+    return (
+      <TableCell
+        key={cell.id}
+        {...(cellSize !== undefined ? { width: cellSize } : {})}
+        align={meta?.align ?? 'left'}
+        {...(meta?.mono !== undefined ? { mono: meta.mono } : {})}
+        {...(meta?.ink !== undefined ? { ink: meta.ink } : {})}
+        {...(meta?.sticky ? { sticky: meta.sticky } : {})}
+        {...(cellClassName ? { className: cellClassName } : {})}
+      >
+        {flexRender(cell.column.columnDef.cell, cell.getContext())}
+      </TableCell>
+    )
+  })
+
+  const body = rowWrapper ? rowWrapper(row, cells) : cells
+
+  return (
+    <TableRow
+      absolute
+      alt={isAlt}
+      interactive={interactive}
+      style={style}
+      data-row-id={row.id}
+      tabIndex={interactive ? 0 : undefined}
+      onClick={interactive ? (e) => onRowClick?.(row.original, e) : undefined}
+      onKeyDown={
+        interactive
+          ? (e) => {
+              if (e.key === 'Enter' || e.key === ' ') {
+                e.preventDefault()
+                onRowClick?.(row.original, e)
+              }
+            }
+          : undefined
+      }
+    >
+      {body}
+    </TableRow>
+  )
+}
+
+/* ---------- Loader & end marker ----------------------------------------- */
+
+function LoaderRow() {
+  return (
+    <div
+      className={cn(
+        'flex items-center justify-center gap-3',
+        'h-8 font-mono text-[11px] tracking-[0.04em]',
+        'text-ink-4',
+      )}
+    >
+      <span
+        aria-hidden="true"
+        className="relative inline-block h-[2px] w-24 overflow-hidden rounded-pill bg-rule"
+      >
+        <span className="absolute inset-0 w-[30%] rounded-pill bg-accent animate-[pt-slide_1.1s_ease-in-out_infinite]" />
+      </span>
+      <span>loading more</span>
+      <style>{`
+        @keyframes pt-slide {
+          0%   { transform: translateX(-110%); }
+          100% { transform: translateX(360%); }
+        }
+      `}</style>
+    </div>
+  )
+}
+
+function EndMarker({ count }: { count: number }) {
+  return (
+    <div
+      className={cn(
+        'flex items-center justify-center',
+        'h-8 font-mono text-[10.5px] uppercase tracking-[0.08em]',
+        'text-ink-4',
+      )}
+    >
+      end · {count.toLocaleString()} rows
+    </div>
+  )
+}

package/src/components/data-table/index.ts

@@ -0,0 +1,22 @@
+export type {
+  BooleanCellProps,
+  DateCellProps,
+  DateTimeCellProps,
+  LinkCellProps,
+  TruncateCellProps,
+} from './cells'
+export { BooleanCell, DateCell, DateTimeCell, LinkCell, TruncateCell } from './cells'
+export type { DataTableProps, InfiniteQueryLike } from './data-table'
+export { DataTable } from './data-table'
+
+export type { ActionsColumnOptions } from './make-actions-column'
+export { makeActionsColumn } from './make-actions-column'
+export type { DataTableEmptyProps } from './states/data-table-empty'
+export { DataTableEmpty } from './states/data-table-empty'
+export type { DataTableErrorProps } from './states/data-table-error'
+export { DataTableError } from './states/data-table-error'
+export type { DataTableSkeletonProps } from './states/data-table-skeleton'
+export { DataTableSkeleton } from './states/data-table-skeleton'
+
+export type { UseInfiniteScrollSentinelOptions } from './use-infinite-scroll-sentinel'
+export { useInfiniteScrollSentinel } from './use-infinite-scroll-sentinel'

package/src/components/data-table/make-actions-column.ts

@@ -0,0 +1,30 @@
+import type { ColumnDef } from '@tanstack/react-table'
+import type { ReactNode } from 'react'
+
+export type ActionsColumnOptions<TData> = {
+  id?: string
+  header?: string
+  width?: number
+  cell: (row: TData) => ReactNode
+}
+
+/**
+ * Convenience builder for a non-sortable, right-aligned actions column.
+ * Carries `meta.align: 'right'` so DataTable renders the header/cell
+ * end-aligned even though the column has no value to sort by.
+ */
+export function makeActionsColumn<TData>({
+  id = 'actions',
+  header = '',
+  width = 80,
+  cell,
+}: ActionsColumnOptions<TData>): ColumnDef<TData> {
+  return {
+    id,
+    header,
+    size: width,
+    enableSorting: false,
+    meta: { align: 'right' as const },
+    cell: ({ row }) => cell(row.original),
+  }
+}

package/src/components/data-table/states/data-table-empty.tsx

@@ -0,0 +1,40 @@
+import type { ReactNode } from 'react'
+
+import { cn } from '../../../lib/cn'
+
+export type DataTableEmptyProps = {
+  title?: string
+  message?: string
+  icon?: ReactNode
+  action?: ReactNode
+  className?: string
+}
+
+/**
+ * Empty state shown when the query returns zero rows.
+ * Mirrors the design's `pt-empty` block.
+ */
+export function DataTableEmpty({
+  title = 'No results',
+  message,
+  icon,
+  action,
+  className,
+}: DataTableEmptyProps) {
+  return (
+    <div
+      role="status"
+      className={cn(
+        'flex flex-col items-center justify-center gap-2',
+        'px-5 py-16 text-center',
+        'font-sans text-[13px] text-ink-3',
+        className,
+      )}
+    >
+      {icon ? <div className="text-ink-4">{icon}</div> : null}
+      <div className="text-ink text-[14px]">{title}</div>
+      {message ? <div className="text-ink-3 max-w-[36ch]">{message}</div> : null}
+      {action ? <div className="mt-3">{action}</div> : null}
+    </div>
+  )
+}

package/src/components/data-table/states/data-table-error.tsx

@@ -0,0 +1,30 @@
+import { cn } from '../../../lib/cn'
+import { Button } from '../../button'
+
+export type DataTableErrorProps = {
+  error: Error
+  onRetry?: () => void
+  className?: string
+}
+
+export function DataTableError({ error, onRetry, className }: DataTableErrorProps) {
+  return (
+    <div
+      role="alert"
+      className={cn(
+        'flex flex-col items-center justify-center gap-3',
+        'px-5 py-16 text-center',
+        'font-sans text-[13px] text-ink-3',
+        className,
+      )}
+    >
+      <div className="text-danger text-[14px]">Something went wrong</div>
+      <div className="text-ink-3 max-w-[48ch] font-mono text-[12px]">{error.message}</div>
+      {onRetry ? (
+        <Button variant="ghost" size="sm" onPress={onRetry}>
+          Retry
+        </Button>
+      ) : null}
+    </div>
+  )
+}