chati-dev 4.3.0 → 4.4.0

package/framework/scaffold/saas-dashboard/components/data/DataTable.tsx.template

@@ -0,0 +1,623 @@
+/**
+ * components/data/DataTable.tsx
+ * ============================================================
+ * WHY THIS COMPONENT EXISTS
+ * -------------------------
+ * SaaS dashboards are fundamentally about tabular data. A reusable,
+ * premium data table component eliminates the most common source of
+ * quality inconsistency in dashboard UIs: each feature team
+ * hand-rolling its own table with slightly different row heights,
+ * hover states, loading patterns, and accessibility implementations.
+ *
+ * ARCHITECTURE
+ * ------------
+ * DataTable<T> is a generic React component where T is the row
+ * datum type. This eliminates `any` casts in cell renderers and
+ * gives callers full type inference on the `onRowClick` callback.
+ *
+ * The component is intentionally server-friendly: it receives
+ * already-sorted, already-paginated data via props. Sort state
+ * changes call `onSort` so the parent can decide whether to sort
+ * client-side or re-fetch. This matches the most common dashboard
+ * pattern (server-side pagination + sort) without forcing it.
+ *
+ * ACCESSIBILITY APPROACH
+ * ----------------------
+ * - <table> with a mandatory `caption` prop (not aria-label) so
+ *   screen readers announce the table purpose before reading cells.
+ * - <th scope="col"> on all column headers (required for WCAG 1.3.1).
+ * - Sort buttons are real <button> elements with aria-sort on the
+ *   <th>, not just styled divs.
+ * - Selection checkboxes have visually hidden labels via aria-label.
+ * - Row click targets are keyboard accessible via tabIndex + Enter/Space.
+ * - Loading skeleton rows use aria-hidden to prevent screen readers
+ *   from announcing placeholder content.
+ *
+ * MOTION DESIGN
+ * -------------
+ * Row hover: background-color transition, duration-fast (120ms),
+ * ease-out. No transform on rows (layout-shift risk with variable
+ * row height and sticky header).
+ * Sort icon swap: opacity + transform (translateY 4px), duration-fast.
+ * Skeleton shimmer: translateX sweep on a pseudo-element, 1.4s
+ * ease-in-out infinite. Collapses to static bg on reduced-motion.
+ *
+ * SPACING DECISIONS
+ * -----------------
+ * Row height: min-height 44px (--space-11) via vertical cell padding
+ * of 12px (--space-3) top+bottom on a 14px font = ~40px + 4px border.
+ * Meets WCAG 2.5.5 target size guideline for interactive rows.
+ * Header: 40px (--space-10) via 10px v-padding, slightly denser than
+ * data rows to establish visual hierarchy without extra markup.
+ * ============================================================
+ */
+
+'use client';
+
+import React, { useState, useCallback, useId } from 'react';
+import { ChevronUp, ChevronDown, ChevronsUpDown } from 'lucide-react';
+import type { ColumnDef, SortState, SortDirection, PaginationState } from './DataTable.types';
+import { DataTablePagination } from './DataTablePagination';
+import { SkeletonBlock } from './SkeletonBlock';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface DataTableProps<T> {
+  /**
+   * Column definitions. Each column controls header label, cell renderer,
+   * sort capability, and optional fixed width.
+   */
+  columns: ColumnDef<T>[];
+
+  /** Row data. The component is display-only; sorting/paging is external. */
+  data: T[];
+
+  /**
+   * Required for screen reader announcement. Describes the table content
+   * (e.g., "Monthly revenue by customer").
+   * NOTE: visually hidden by default (className="sr-only"). Pass
+   * captionVisible to show it above the table.
+   */
+  caption: string;
+
+  /** When true, renders the caption as a visible heading above the table. */
+  captionVisible?: boolean;
+
+  /** When true, shows 6 skeleton rows instead of data rows. */
+  loading?: boolean;
+
+  /**
+   * Rendered when data is empty and loading is false.
+   * Defaults to a minimal "No results" message.
+   */
+  emptyState?: React.ReactNode;
+
+  /**
+   * Called when a sortable column header is clicked.
+   * The parent is responsible for sorting data and re-rendering.
+   */
+  onSort?: (sort: SortState) => void;
+
+  /**
+   * Current sort state. Controls the active sort indicator.
+   * When omitted, no sort indicator is shown.
+   */
+  sortState?: SortState;
+
+  /**
+   * Called when a data row is clicked. When provided, rows receive
+   * cursor-pointer and are keyboard-focusable (tabIndex=0).
+   */
+  onRowClick?: (row: T) => void;
+
+  /**
+   * When true, the header row is sticky (position: sticky, top: 0).
+   * Requires the table's scroll container to have overflow-y: auto.
+   * The AppShell main content area provides this automatically.
+   */
+  stickyHeader?: boolean;
+
+  /** Pagination props. When omitted, no pagination row is rendered. */
+  pagination?: PaginationState & {
+    onPageChange: (page: number) => void;
+    onPageSizeChange: (size: number) => void;
+  };
+
+  /**
+   * Row selection. When provided, adds a checkbox column as the first column.
+   * selectedKeys is a Set of string row keys.
+   */
+  selection?: {
+    selectedKeys: Set<string>;
+    getRowKey: (row: T) => string;
+    onSelectionChange: (keys: Set<string>) => void;
+  };
+
+  /** Additional className applied to the <div> wrapper. */
+  className?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Skeleton row count for loading state
+// ---------------------------------------------------------------------------
+const SKELETON_ROWS = 6;
+
+// ---------------------------------------------------------------------------
+// Sort icon helper
+// ---------------------------------------------------------------------------
+function SortIcon({
+  columnKey,
+  sortState,
+}: {
+  columnKey: string;
+  sortState?: SortState;
+}) {
+  const isActive = sortState?.key === columnKey;
+  const direction: SortDirection = isActive ? sortState!.direction : 'none';
+
+  return (
+    <span
+      aria-hidden="true"
+      style={{
+        display: 'inline-flex',
+        alignItems: 'center',
+        marginLeft: 'var(--space-1)',
+        opacity: isActive ? 1 : 0.35,
+        transition: `opacity var(--duration-fast) var(--ease-out),
+                     transform var(--duration-fast) var(--ease-out)`,
+        transform: isActive && direction === 'desc' ? 'translateY(1px)' : 'translateY(0)',
+      }}
+    >
+      {direction === 'asc' ? (
+        <ChevronUp size={13} />
+      ) : direction === 'desc' ? (
+        <ChevronDown size={13} />
+      ) : (
+        <ChevronsUpDown size={13} />
+      )}
+    </span>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Derive next sort direction in the 3-state cycle
+// ---------------------------------------------------------------------------
+function nextDirection(current: SortDirection): SortDirection {
+  if (current === 'none') return 'asc';
+  if (current === 'asc') return 'desc';
+  return 'none';
+}
+
+// ---------------------------------------------------------------------------
+// Main component
+// ---------------------------------------------------------------------------
+export function DataTable<T>(props: DataTableProps<T>) {
+  const {
+    columns,
+    data,
+    caption,
+    captionVisible = false,
+    loading = false,
+    emptyState,
+    onSort,
+    sortState,
+    onRowClick,
+    stickyHeader = false,
+    pagination,
+    selection,
+    className,
+  } = props;
+
+  const tableId = useId();
+  const captionId = `${tableId}-caption`;
+
+  // ------------------------------------------------------------------
+  // Row selection logic
+  // ------------------------------------------------------------------
+  const allKeys = selection
+    ? data.map((row) => selection.getRowKey(row))
+    : [];
+  const allSelected =
+    selection != null &&
+    allKeys.length > 0 &&
+    allKeys.every((k) => selection.selectedKeys.has(k));
+  const someSelected =
+    selection != null &&
+    allKeys.some((k) => selection.selectedKeys.has(k));
+
+  const handleSelectAll = useCallback(() => {
+    if (!selection) return;
+    if (allSelected) {
+      selection.onSelectionChange(new Set());
+    } else {
+      selection.onSelectionChange(new Set(allKeys));
+    }
+  }, [selection, allKeys, allSelected]);
+
+  const handleSelectRow = useCallback(
+    (key: string) => {
+      if (!selection) return;
+      const next = new Set(selection.selectedKeys);
+      if (next.has(key)) {
+        next.delete(key);
+      } else {
+        next.add(key);
+      }
+      selection.onSelectionChange(next);
+    },
+    [selection],
+  );
+
+  // ------------------------------------------------------------------
+  // Sort handler
+  // ------------------------------------------------------------------
+  const handleSort = useCallback(
+    (columnKey: string) => {
+      if (!onSort) return;
+      const currentDirection: SortDirection =
+        sortState?.key === columnKey ? sortState.direction : 'none';
+      onSort({ key: columnKey, direction: nextDirection(currentDirection) });
+    },
+    [onSort, sortState],
+  );
+
+  // ------------------------------------------------------------------
+  // Derived aria-sort value
+  // ------------------------------------------------------------------
+  function ariaSortFor(columnKey: string): React.AriaAttributes['aria-sort'] {
+    if (!sortState || sortState.key !== columnKey) return 'none';
+    if (sortState.direction === 'asc') return 'ascending';
+    if (sortState.direction === 'desc') return 'descending';
+    return 'none';
+  }
+
+  // ------------------------------------------------------------------
+  // Total columns count (including checkbox column)
+  // ------------------------------------------------------------------
+  const totalCols = columns.length + (selection ? 1 : 0);
+
+  // ------------------------------------------------------------------
+  // Styles (inline CSS custom properties -- no raw values)
+  // ------------------------------------------------------------------
+  const headerThStyle: React.CSSProperties = {
+    position: stickyHeader ? 'sticky' : undefined,
+    top: stickyHeader ? 0 : undefined,
+    zIndex: stickyHeader ? 1 : undefined,
+    backgroundColor: 'var(--color-bg-overlay)',
+    color: 'var(--color-text-secondary)',
+    fontSize: 'var(--type-caption)',
+    fontWeight: 'var(--font-weight-semibold)' as React.CSSProperties['fontWeight'],
+    letterSpacing: '0.04em',
+    textTransform: 'uppercase',
+    padding: 'var(--space-2) var(--space-4)',
+    borderBottom: '1px solid var(--color-border-default)',
+    whiteSpace: 'nowrap',
+    userSelect: 'none',
+  };
+
+  return (
+    <div
+      className={className}
+      style={{
+        borderRadius: 'var(--radius-default)',
+        border: '1px solid var(--color-border-default)',
+        overflow: 'hidden',
+        backgroundColor: 'var(--color-bg-raised)',
+      }}
+    >
+      {/* Table scroll container -- required for sticky header to work */}
+      <div style={{ overflowX: 'auto', overflowY: 'auto' }}>
+        <table
+          aria-labelledby={captionId}
+          style={{
+            width: '100%',
+            borderCollapse: 'collapse',
+            tableLayout: 'fixed',
+            fontFamily: 'var(--font-sans)',
+            fontSize: 'var(--type-small)',
+            color: 'var(--color-text-primary)',
+          }}
+        >
+          {/* Caption: always present for SR; optionally visible */}
+          <caption
+            id={captionId}
+            style={{
+              captionSide: 'top',
+              padding: captionVisible ? 'var(--space-4) var(--space-6)' : undefined,
+              fontSize: captionVisible ? 'var(--type-h4)' : undefined,
+              fontWeight: captionVisible ? 'var(--font-weight-semibold)' : undefined,
+              color: captionVisible ? 'var(--color-text-primary)' : undefined,
+              textAlign: captionVisible ? 'left' : undefined,
+              // visually hidden when captionVisible=false
+              ...(captionVisible
+                ? {}
+                : {
+                    position: 'absolute',
+                    width: '1px',
+                    height: '1px',
+                    padding: 0,
+                    margin: '-1px',
+                    overflow: 'hidden',
+                    clip: 'rect(0,0,0,0)',
+                    whiteSpace: 'nowrap',
+                    border: 0,
+                  }),
+            }}
+          >
+            {caption}
+          </caption>
+
+          {/* Column width hints */}
+          <colgroup>
+            {selection && (
+              <col style={{ width: '40px' }} />
+            )}
+            {columns.map((col) => (
+              <col
+                key={col.key}
+                style={{
+                  width:
+                    col.width != null
+                      ? typeof col.width === 'number'
+                        ? `${col.width}px`
+                        : col.width
+                      : undefined,
+                }}
+              />
+            ))}
+          </colgroup>
+
+          {/* Header */}
+          <thead>
+            <tr>
+              {/* Select-all checkbox */}
+              {selection && (
+                <th
+                  scope="col"
+                  style={{ ...headerThStyle, textAlign: 'center', padding: 'var(--space-2)' }}
+                >
+                  <input
+                    type="checkbox"
+                    aria-label="Select all rows"
+                    checked={allSelected}
+                    ref={(el) => {
+                      if (el) el.indeterminate = someSelected && !allSelected;
+                    }}
+                    onChange={handleSelectAll}
+                    style={checkboxStyle}
+                  />
+                </th>
+              )}
+
+              {columns.map((col) => (
+                <th
+                  key={col.key}
+                  scope="col"
+                  aria-sort={col.sortable ? ariaSortFor(col.key) : undefined}
+                  style={{
+                    ...headerThStyle,
+                    textAlign: col.align ?? 'left',
+                  }}
+                >
+                  {col.sortable ? (
+                    <button
+                      type="button"
+                      onClick={() => handleSort(col.key)}
+                      style={sortButtonStyle}
+                      aria-label={`Sort by ${col.header}${
+                        sortState?.key === col.key
+                          ? `, currently ${sortState.direction}ending`
+                          : ''
+                      }`}
+                    >
+                      {col.header}
+                      {col.srDescription && (
+                        <span
+                          style={{
+                            position: 'absolute',
+                            width: '1px',
+                            height: '1px',
+                            overflow: 'hidden',
+                            clip: 'rect(0,0,0,0)',
+                          }}
+                        >
+                          {col.srDescription}
+                        </span>
+                      )}
+                      <SortIcon columnKey={col.key} sortState={sortState} />
+                    </button>
+                  ) : (
+                    <>
+                      {col.header}
+                      {col.srDescription && (
+                        <span
+                          style={{
+                            position: 'absolute',
+                            width: '1px',
+                            height: '1px',
+                            overflow: 'hidden',
+                            clip: 'rect(0,0,0,0)',
+                          }}
+                        >
+                          {col.srDescription}
+                        </span>
+                      )}
+                    </>
+                  )}
+                </th>
+              ))}
+            </tr>
+          </thead>
+
+          {/* Body */}
+          <tbody>
+            {/* Loading skeleton */}
+            {loading &&
+              Array.from({ length: SKELETON_ROWS }).map((_, rowIdx) => (
+                <tr key={`skel-${rowIdx}`} aria-hidden="true">
+                  {selection && (
+                    <td style={cellStyle('left')}>
+                      <SkeletonBlock width={16} height={16} borderRadius="var(--radius-sm)" />
+                    </td>
+                  )}
+                  {columns.map((col, colIdx) => (
+                    <td key={col.key} style={cellStyle(col.align ?? 'left')}>
+                      <SkeletonBlock
+                        height={14}
+                        width={colIdx === 0 ? '70%' : colIdx % 3 === 0 ? '50%' : '80%'}
+                        borderRadius="var(--radius-sharp)"
+                      />
+                    </td>
+                  ))}
+                </tr>
+              ))}
+
+            {/* Empty state */}
+            {!loading && data.length === 0 && (
+              <tr>
+                <td
+                  colSpan={totalCols}
+                  style={{
+                    padding: 'var(--space-16) var(--space-6)',
+                    textAlign: 'center',
+                    color: 'var(--color-text-secondary)',
+                  }}
+                >
+                  {emptyState ?? (
+                    <span style={{ fontSize: 'var(--type-body)' }}>No results found.</span>
+                  )}
+                </td>
+              </tr>
+            )}
+
+            {/* Data rows */}
+            {!loading &&
+              data.map((row, rowIdx) => {
+                const rowKey = selection?.getRowKey(row) ?? String(rowIdx);
+                const isSelected = selection?.selectedKeys.has(rowKey) ?? false;
+                const isInteractive = !!onRowClick;
+
+                return (
+                  <tr
+                    key={rowKey}
+                    className="data-table-row"
+                    onClick={isInteractive ? () => onRowClick!(row) : undefined}
+                    onKeyDown={
+                      isInteractive
+                        ? (e) => {
+                            if (e.key === 'Enter' || e.key === ' ') {
+                              e.preventDefault();
+                              onRowClick!(row);
+                            }
+                          }
+                        : undefined
+                    }
+                    tabIndex={isInteractive ? 0 : undefined}
+                    role={isInteractive ? 'button' : undefined}
+                    aria-selected={selection ? isSelected : undefined}
+                    style={rowStyle(isSelected, isInteractive)}
+                  >
+                    {/* Selection checkbox */}
+                    {selection && (
+                      <td
+                        style={{ ...cellStyle('center'), padding: 'var(--space-2)' }}
+                        onClick={(e) => {
+                          e.stopPropagation();
+                          handleSelectRow(rowKey);
+                        }}
+                      >
+                        <input
+                          type="checkbox"
+                          aria-label={`Select row ${rowIdx + 1}`}
+                          checked={isSelected}
+                          onChange={() => handleSelectRow(rowKey)}
+                          style={checkboxStyle}
+                        />
+                      </td>
+                    )}
+
+                    {/* Data cells */}
+                    {columns.map((col) => {
+                      const content = col.render
+                        ? col.render(row)
+                        : String((row as Record<string, unknown>)[col.key] ?? '');
+                      return (
+                        <td key={col.key} style={cellStyle(col.align ?? 'left')}>
+                          {content}
+                        </td>
+                      );
+                    })}
+                  </tr>
+                );
+              })}
+          </tbody>
+        </table>
+      </div>
+
+      {/* Pagination */}
+      {pagination && !loading && (
+        <DataTablePagination
+          page={pagination.page}
+          pageSize={pagination.pageSize}
+          total={pagination.total}
+          onPageChange={pagination.onPageChange}
+          onPageSizeChange={pagination.onPageSizeChange}
+        />
+      )}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Style helpers (all values reference CSS custom properties)
+// ---------------------------------------------------------------------------
+
+function cellStyle(align: 'left' | 'center' | 'right'): React.CSSProperties {
+  return {
+    padding: 'var(--space-3) var(--space-4)',
+    borderBottom: '1px solid var(--color-border-default)',
+    textAlign: align,
+    verticalAlign: 'middle',
+    lineHeight: 'var(--type-body-lh)',
+    color: 'var(--color-text-primary)',
+  };
+}
+
+function rowStyle(isSelected: boolean, isInteractive: boolean): React.CSSProperties {
+  return {
+    backgroundColor: isSelected
+      ? 'var(--color-bg-highlight)'
+      : 'transparent',
+    cursor: isInteractive ? 'pointer' : 'default',
+    transition: `background-color var(--duration-fast) var(--ease-out)`,
+    outline: 'none',
+    // Hover is handled via CSS class in a companion stylesheet or via
+    // onMouseEnter/Leave state. Using inline style for the base state
+    // keeps the component self-contained. A global .data-table-row:hover
+    // rule in globals.css handles the hover affordance.
+  };
+}
+
+const sortButtonStyle: React.CSSProperties = {
+  background: 'none',
+  border: 'none',
+  padding: 0,
+  cursor: 'pointer',
+  color: 'inherit',
+  font: 'inherit',
+  letterSpacing: 'inherit',
+  textTransform: 'inherit',
+  display: 'inline-flex',
+  alignItems: 'center',
+  gap: 0,
+  width: '100%',
+};
+
+const checkboxStyle: React.CSSProperties = {
+  width: '16px',
+  height: '16px',
+  accentColor: 'var(--color-accent)',
+  cursor: 'pointer',
+};