Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

13.7 KB
Raw Blame
"use client";

import * as React from "react";
import { ArrowDown, ArrowUp } from "lucide-react";
import { cn } from "../../lib/cn";
import { useVirtualRows } from "../virtualized-table/use-virtual-rows";

/**
 * ResponsiveTable — shared table primitive with a column-priority API.
 *
 * Every column declares a `priority`:
 *   1 — always visible (identity / primary metric columns)
 *   2 — hidden below `md` (768px)
 *   3 — hidden below `lg` (1024px)
 *
 * The wrapper always provides `overflow-x-auto` as a fallback so nothing is
 * ever clipped. With `stacked`, the table additionally collapses to a
 * stacked card list below the given breakpoint: the first priority-1 column
 * renders as the card title and the remaining columns render as label/value
 * rows (via `mobileRender` when provided, else `render`).
 *
 * With `virtualize`, both the row body and the stacked card list are windowed
 * through {@link useVirtualRows}. Stacked mode keeps both trees in the DOM (CSS
 * picks one), so a long list has to window both or it only pays half the saving.
 * Below the hook's threshold nothing is windowed and the markup is unchanged.
 *
 * Purely presentational: rows in, callbacks out. No routing, no data fetching.
 */

export type ColumnPriority = 1 | 2 | 3;

export interface ResponsiveColumn<T> {
  /** Stable identifier; doubles as the sort key passed to `onSort`. */
  key: string;
  header: React.ReactNode;
  /** Short label used in stacked-card mode; falls back to `header` when it is a string. */
  mobileLabel?: string | undefined;
  align?: "left" | "right" | "center" | undefined;
  priority?: ColumnPriority | undefined;
  sortable?: boolean | undefined;
  headerClassName?: string | undefined;
  cellClassName?: string | undefined;
  render: (row: T) => React.ReactNode;
  /** Override rendering inside stacked cards (e.g. drop icons, shorten text). */
  mobileRender?: ((row: T) => React.ReactNode) | undefined;
  /** Skip this column entirely in stacked-card mode. */
  hideInCard?: boolean | undefined;
}

/** Windowing knobs; presence of the object is what turns virtualization on. */
export interface ResponsiveTableVirtualization {
  /** Estimated `<tr>` height in px. Default 44. */
  estimateRowHeight?: number | undefined;
  /** Estimated stacked-card height in px. Default 76 (title + one meta line). */
  estimateCardHeight?: number | undefined;
  /** Below this many rows, render everything. Default 60 (the hook's own). */
  threshold?: number | undefined;
  /** Max height of the scroll viewport. Default 600. */
  maxHeight?: number | string | undefined;
}

export interface ResponsiveTableProps<T> {
  columns: ResponsiveColumn<T>[];
  rows: T[];
  rowKey: (row: T) => string;
  onRowClick?: ((row: T) => void) | undefined;
  /**
   * Pointer entered a row, for tables paired with a view that highlights it.
   * Pointer-only, so never make it the sole route to information: pair it with
   * `onRowClick`, which also works on touch.
   */
  onRowHover?: ((row: T) => void) | undefined;
  selectedKey?: string | null | undefined;
  /** Extra per-row classes — e.g. a multi-select highlight `selectedKey` can't express. */
  rowClassName?: ((row: T) => string | undefined) | undefined;
  /** Window the rows (and the stacked cards) instead of rendering all of them. */
  virtualize?: ResponsiveTableVirtualization | undefined;
  sortField?: string | undefined;
  sortOrder?: "asc" | "desc" | undefined;
  onSort?: ((key: string) => void) | undefined;
  /** Rendered instead of the table when `rows` is empty (use EmptyState). */
  empty?: React.ReactNode | undefined;
  /** Screen-reader-only `<caption>` describing the table. */
  caption?: string | undefined;
  /** Collapse to stacked cards below this breakpoint. Default: no collapse. */
  stacked?: "sm" | "md" | undefined;
  /** Extra classes on the outer wrapper. */
  className?: string | undefined;
  /** Omit the default rounded border + surface background. */
  bare?: boolean | undefined;
}

const PRIORITY_CELL_CLS: Record<ColumnPriority, string> = {
  1: "",
  2: "max-md:hidden",
  3: "max-lg:hidden",
};

const STACKED_TABLE_CLS: Record<NonNullable<ResponsiveTableProps<unknown>["stacked"]>, string> = {
  sm: "max-sm:hidden",
  md: "max-md:hidden",
};

const STACKED_CARDS_CLS: Record<NonNullable<ResponsiveTableProps<unknown>["stacked"]>, string> = {
  sm: "sm:hidden",
  md: "md:hidden",
};

function alignCls(align?: "left" | "right" | "center"): string {
  return align === "right" ? "text-right" : align === "center" ? "text-center" : "text-left";
}

/**
 * Keyboard/focus props for a clickable row. Keeps the native row semantics
 * (no role override, which would detach the row from the table for assistive
 * tech) while making the row tabbable and activatable with Enter/Space.
 */
export function clickableRowProps<E extends HTMLElement>(activate: () => void) {
  return {
    tabIndex: 0,
    onClick: activate,
    onKeyDown: (event: React.KeyboardEvent<E>) => {
      if (event.key !== "Enter" && event.key !== " ") return;
      if (event.target !== event.currentTarget) return;
      event.preventDefault();
      activate();
    },
  };
}

export const CLICKABLE_ROW_CLS =
  "cursor-pointer focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-[var(--color-focus-ring)]";

const NOOP_MEASURE = () => {};

/** The window of rows to render plus the spacer heights standing in for the rest. */
interface Window<T> {
  items: { row: T; index: number }[];
  paddingTop: number;
  paddingBottom: number;
  measure: (el: HTMLElement | null) => void;
}

export function ResponsiveTable<T>({
  columns,
  rows,
  rowKey,
  onRowClick,
  onRowHover,
  selectedKey,
  rowClassName,
  virtualize,
  sortField,
  sortOrder = "desc",
  onSort,
  empty,
  caption,
  stacked,
  className,
  bare,
}: ResponsiveTableProps<T>) {
  // Hooks run unconditionally, so `count: 0` (not an early return) is how the
  // non-virtualized path opts out.
  const count = virtualize ? rows.length : 0;
  const shared = {
    ...(virtualize?.threshold !== undefined ? { threshold: virtualize.threshold } : {}),
  };
  const rowWindow = useVirtualRows<HTMLDivElement>({
    count,
    estimateSize: virtualize?.estimateRowHeight ?? 44,
    ...shared,
  });
  const cardWindow = useVirtualRows<HTMLDivElement>({
    count,
    estimateSize: virtualize?.estimateCardHeight ?? 76,
    ...shared,
  });

  const windowFor = (w: typeof rowWindow): Window<T> =>
    virtualize
      ? {
          items: w.virtualRows.flatMap((vr) => {
            const row = rows[vr.index];
            return row === undefined ? [] : [{ row, index: vr.index }];
          }),
          paddingTop: w.paddingTop,
          paddingBottom: w.paddingBottom,
          measure: w.measureElement,
        }
      : {
          items: rows.map((row, index) => ({ row, index })),
          paddingTop: 0,
          paddingBottom: 0,
          // Module-level, not a fresh closure: a new ref identity per render
          // makes React detach and re-attach every row's ref on every render,
          // and most consumers never virtualize.
          measure: NOOP_MEASURE,
        };

  if (rows.length === 0 && empty) {
    return <>{empty}</>;
  }

  const maxHeight = virtualize?.maxHeight ?? 600;
  const tableWindow = windowFor(rowWindow);
  const cardsWindow = windowFor(cardWindow);

  const table = (
    <div
      ref={virtualize ? rowWindow.scrollRef : undefined}
      className={cn(
        virtualize ? "overflow-auto" : "overflow-x-auto",
        stacked && STACKED_TABLE_CLS[stacked],
      )}
      style={virtualize ? { maxHeight } : undefined}
    >
      <table className="w-full text-sm">
        {caption ? <caption className="sr-only">{caption}</caption> : null}
        <thead className="bg-[var(--color-bg-surface)] text-[var(--color-text-tertiary)] text-2xs uppercase tracking-wider sticky top-0 z-10 border-b border-[var(--color-border-default)]">
          <tr>
            {columns.map((c) => {
              const isActive = c.sortable && c.key === sortField;
              const label = (
                <span className="inline-flex items-center gap-1">
                  {c.header}
                  {isActive ? (
                    sortOrder === "asc" ? (
                      <ArrowUp className="h-3 w-3" />
                    ) : (
                      <ArrowDown className="h-3 w-3" />
                    )
                  ) : null}
                </span>
              );
              return (
                <th
                  key={c.key}
                  scope="col"
                  className={cn(
                    "px-3 py-2.5 font-medium whitespace-nowrap",
                    alignCls(c.align),
                    PRIORITY_CELL_CLS[c.priority ?? 1],
                    c.headerClassName,
                  )}
                  aria-sort={
                    isActive ? (sortOrder === "asc" ? "ascending" : "descending") : undefined
                  }
                >
                  {c.sortable && onSort ? (
                    <button
                      type="button"
                      className="inline-flex cursor-pointer select-none items-center font-medium uppercase tracking-wider focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-focus-ring)] rounded"
                      onClick={() => onSort(c.key)}
                    >
                      {label}
                    </button>
                  ) : (
                    label
                  )}
                </th>
              );
            })}
          </tr>
        </thead>
        <tbody>
          {tableWindow.paddingTop > 0 && (
            <tr aria-hidden>
              <td style={{ height: tableWindow.paddingTop, padding: 0, border: 0 }} />
            </tr>
          )}
          {tableWindow.items.map(({ row, index }) => {
            const key = rowKey(row);
            const isSelected = selectedKey != null && selectedKey === key;
            return (
              <tr
                key={key}
                ref={tableWindow.measure}
                data-index={index}
                data-selected={isSelected || undefined}
                className={cn(
                  "group/row border-t border-[var(--color-table-divider)] hover:bg-[var(--color-bg-elevated)]",
                  isSelected && "bg-[var(--color-selection-wash)]",
                  onRowClick && CLICKABLE_ROW_CLS,
                  rowClassName?.(row),
                )}
                onMouseEnter={onRowHover ? () => onRowHover(row) : undefined}
                {...(onRowClick ? clickableRowProps(() => onRowClick(row)) : {})}
              >
                {columns.map((c) => (
                  <td
                    key={c.key}
                    className={cn(
                      "px-3 py-2.5",
                      alignCls(c.align),
                      PRIORITY_CELL_CLS[c.priority ?? 1],
                      c.cellClassName,
                    )}
                  >
                    {c.render(row)}
                  </td>
                ))}
              </tr>
            );
          })}
          {tableWindow.paddingBottom > 0 && (
            <tr aria-hidden>
              <td style={{ height: tableWindow.paddingBottom, padding: 0, border: 0 }} />
            </tr>
          )}
        </tbody>
      </table>
    </div>
  );

  const cards = stacked ? (
    <div
      ref={virtualize ? cardWindow.scrollRef : undefined}
      className={cn(virtualize && "overflow-auto", STACKED_CARDS_CLS[stacked])}
      style={virtualize ? { maxHeight } : undefined}
    >
      {cardsWindow.paddingTop > 0 && <div style={{ height: cardsWindow.paddingTop }} aria-hidden />}
      <ul className="divide-y divide-[var(--color-table-divider)]">
        {cardsWindow.items.map(({ row, index }) => {
          const key = rowKey(row);
          const isSelected = selectedKey != null && selectedKey === key;
          const [titleCol, ...rest] = columns.filter((c) => !c.hideInCard);
          if (!titleCol) return null;
          return (
            <li
              key={key}
              ref={cardsWindow.measure}
              data-index={index}
              data-selected={isSelected || undefined}
              className={cn(
                "group/row px-3 py-2.5",
                isSelected && "bg-[var(--color-selection-wash)]",
                onRowClick && cn("hover:bg-[var(--color-bg-elevated)]", CLICKABLE_ROW_CLS),
                rowClassName?.(row),
              )}
              onMouseEnter={onRowHover ? () => onRowHover(row) : undefined}
              {...(onRowClick ? clickableRowProps(() => onRowClick(row)) : {})}
            >
              <div className="text-sm text-[var(--color-text-primary)]">
                {(titleCol.mobileRender ?? titleCol.render)(row)}
              </div>
              <dl className="mt-1.5 flex flex-wrap gap-x-4 gap-y-1">
                {rest.map((c) => {
                  const value = (c.mobileRender ?? c.render)(row);
                  if (value == null || value === "") return null;
                  return (
                    <div key={c.key} className="flex items-baseline gap-1.5 text-xs">
                      <dt className="text-[var(--color-text-tertiary)]">
                        {c.mobileLabel ?? (typeof c.header === "string" ? c.header : c.key)}
                      </dt>
                      <dd className="text-[var(--color-text-secondary)] tabular-nums">{value}</dd>
                    </div>
                  );
                })}
              </dl>
            </li>
          );
        })}
      </ul>
      {cardsWindow.paddingBottom > 0 && (
        <div style={{ height: cardsWindow.paddingBottom }} aria-hidden />
      )}
    </div>
  ) : null;

  return (
    <div
      className={cn(
        !bare && "overflow-hidden border border-[var(--color-border-default)]",
        className,
      )}
    >
      {table}
      {cards}
    </div>
  );
}