@emara/ui 1.1.0

package/components/ui/data-table.tsx

@@ -0,0 +1,539 @@
+"use client";
+
+import { forwardRef, Fragment, useId, useMemo, useState, type ReactNode } from "react";
+import {
+  flexRender,
+  getCoreRowModel,
+  getExpandedRowModel,
+  getFilteredRowModel,
+  getPaginationRowModel,
+  getSortedRowModel,
+  useReactTable,
+  type ColumnDef,
+  type ExpandedState,
+  type RowSelectionState,
+  type SortingState,
+  type VisibilityState,
+} from "@tanstack/react-table";
+import {
+  RiArrowDownLine,
+  RiArrowUpDownLine,
+  RiArrowUpLine,
+  RiSearchLine,
+  RiSettings3Line,
+} from "@remixicon/react";
+
+import { cn } from "@/lib/utils";
+import { Button } from "./button";
+import { Checkbox } from "./checkbox";
+import { DataPagination } from "./pagination";
+import {
+  DropdownMenu,
+  DropdownMenuCheckboxItem,
+  DropdownMenuContent,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "./dropdown-menu";
+import { EmptyState } from "./empty-state";
+import { Input } from "./input";
+import { Skeleton } from "./skeleton";
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+  type TableDensity,
+} from "./table";
+
+// Per docs/emara-ui-phase-4-components.md §1.2. v1 features:
+// - data + columns
+// - sorting / multi-sort
+// - selection (none/single/multi)
+// - global search
+// - column visibility toggle
+// - row expand
+// - loading / empty / error states
+// - pagination integration via DataPagination
+//
+// Deferred to v1.1 of DataTable: column filtering UI in headers, column
+// resize, column pinning, virtualization. The TanStack feature flags wire up
+// the same way when those land.
+
+// --- Emara column meta extensions ------------------------------------------
+
+type EmaraAlign = "start" | "center" | "end";
+
+declare module "@tanstack/react-table" {
+  // The TData/TValue type params are required by TanStack's module
+  // declaration; we don't use them directly here.
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  interface ColumnMeta<TData, TValue> {
+    /** Logical alignment for header + cells. RTL-aware. */
+    align?: EmaraAlign;
+    /** Fixed/min width. */
+    width?: number | string;
+    /** Single-line with ellipsis. */
+    truncate?: boolean;
+    /** Pin column to start/end. (Visual style only in v1; pin layout deferred.) */
+    sticky?: "start" | "end";
+  }
+}
+
+// --- Props -----------------------------------------------------------------
+
+type SelectionMode = "none" | "single" | "multi";
+
+interface DataTableProps<T> {
+  data: T[];
+  columns: ColumnDef<T, unknown>[];
+
+  loading?: boolean;
+  error?: ReactNode;
+  empty?: ReactNode;
+
+  density?: TableDensity;
+  striped?: boolean;
+  bordered?: boolean;
+  hoverable?: boolean;
+  stickyHeader?: boolean;
+
+  enableSorting?: boolean;
+  enableMultiSort?: boolean;
+
+  enableGlobalSearch?: boolean;
+  /** Placeholder for the global search input. */
+  searchPlaceholder?: string;
+
+  enableSelection?: SelectionMode;
+  onSelectionChange?: (rows: T[]) => void;
+  getRowId?: (row: T, index: number) => string;
+
+  enablePagination?: boolean;
+  pageSize?: number;
+  pageSizeOptions?: number[];
+
+  enableColumnVisibility?: boolean;
+
+  enableRowExpand?: boolean;
+  renderExpandedRow?: (row: T) => ReactNode;
+
+  toolbar?: ReactNode;
+  toolbarActions?: ReactNode;
+  rowClassName?: (row: T) => string;
+
+  className?: string;
+}
+
+// --- Helpers ---------------------------------------------------------------
+
+function alignClass(align: EmaraAlign | undefined): string {
+  switch (align) {
+    case "center":
+      return "text-center";
+    case "end":
+      return "text-end";
+    case "start":
+    case undefined:
+    default:
+      return "text-start";
+  }
+}
+
+function widthStyle(w: number | string | undefined): React.CSSProperties | undefined {
+  if (w === undefined) return undefined;
+  return { width: typeof w === "number" ? `${w}px` : w };
+}
+
+// --- DataTable -------------------------------------------------------------
+
+function DataTableInner<T>(props: DataTableProps<T>, ref: React.Ref<HTMLDivElement>) {
+  const {
+    data,
+    columns,
+    loading = false,
+    error,
+    empty,
+    density,
+    striped,
+    bordered,
+    hoverable,
+    stickyHeader,
+    enableSorting = false,
+    enableMultiSort = false,
+    enableGlobalSearch = false,
+    searchPlaceholder = "Search…",
+    enableSelection = "none",
+    onSelectionChange,
+    getRowId,
+    enablePagination = false,
+    pageSize = 25,
+    pageSizeOptions = [10, 25, 50, 100],
+    enableColumnVisibility = false,
+    enableRowExpand = false,
+    renderExpandedRow,
+    toolbar,
+    toolbarActions,
+    rowClassName,
+    className,
+  } = props;
+
+  const searchInputId = useId();
+
+  const [sorting, setSorting] = useState<SortingState>([]);
+  const [rowSelection, setRowSelection] = useState<RowSelectionState>({});
+  const [columnVisibility, setColumnVisibility] = useState<VisibilityState>({});
+  const [globalFilter, setGlobalFilter] = useState("");
+  const [expanded, setExpanded] = useState<ExpandedState>({});
+  const [pagination, setPagination] = useState({ pageIndex: 0, pageSize });
+
+  // Inject selection column if needed.
+  const augmentedColumns = useMemo<ColumnDef<T, unknown>[]>(() => {
+    const cols: ColumnDef<T, unknown>[] = [...columns];
+    if (enableSelection !== "none") {
+      cols.unshift({
+        id: "__select",
+        size: 36,
+        header: ({ table }) =>
+          enableSelection === "multi" ? (
+            <Checkbox
+              aria-label="Select all rows"
+              checked={
+                table.getIsAllPageRowsSelected()
+                  ? true
+                  : table.getIsSomePageRowsSelected()
+                    ? "indeterminate"
+                    : false
+              }
+              onCheckedChange={(v) => table.toggleAllPageRowsSelected(Boolean(v))}
+            />
+          ) : null,
+        cell: ({ row }) => (
+          <Checkbox
+            aria-label={`Select row ${row.index + 1}`}
+            checked={row.getIsSelected()}
+            onCheckedChange={(v) => {
+              if (enableSelection === "single") {
+                row.toggleSelected(Boolean(v));
+              } else {
+                row.toggleSelected(Boolean(v));
+              }
+            }}
+          />
+        ),
+        enableSorting: false,
+        enableHiding: false,
+        meta: { align: "center" },
+      });
+    }
+    return cols;
+  }, [columns, enableSelection]);
+
+  const table = useReactTable({
+    data,
+    columns: augmentedColumns,
+    state: {
+      sorting,
+      rowSelection,
+      columnVisibility,
+      globalFilter,
+      expanded,
+      ...(enablePagination ? { pagination } : {}),
+    },
+    enableSorting,
+    enableMultiSort,
+    enableRowSelection: enableSelection !== "none",
+    enableMultiRowSelection: enableSelection === "multi",
+    onSortingChange: setSorting,
+    onRowSelectionChange: (next) => {
+      setRowSelection((prev) => {
+        const nextState = typeof next === "function" ? next(prev) : next;
+        // Single-mode: keep at most one selected row.
+        if (enableSelection === "single") {
+          const keys = Object.keys(nextState).filter((k) => nextState[k]);
+          const lastKey = keys[keys.length - 1];
+          const cleaned: RowSelectionState = lastKey ? { [lastKey]: true } : {};
+          queueMicrotask(() => {
+            const rows = table
+              .getRowModel()
+              .rows.filter((r) => cleaned[r.id])
+              .map((r) => r.original);
+            onSelectionChange?.(rows);
+          });
+          return cleaned;
+        }
+        queueMicrotask(() => {
+          const rows = table
+            .getRowModel()
+            .rows.filter((r) => nextState[r.id])
+            .map((r) => r.original);
+          onSelectionChange?.(rows);
+        });
+        return nextState;
+      });
+    },
+    onColumnVisibilityChange: setColumnVisibility,
+    onGlobalFilterChange: setGlobalFilter,
+    onExpandedChange: setExpanded,
+    ...(enablePagination ? { onPaginationChange: setPagination } : {}),
+    getCoreRowModel: getCoreRowModel(),
+    ...(enableSorting ? { getSortedRowModel: getSortedRowModel() } : {}),
+    ...(enableGlobalSearch ? { getFilteredRowModel: getFilteredRowModel() } : {}),
+    ...(enablePagination ? { getPaginationRowModel: getPaginationRowModel() } : {}),
+    ...(enableRowExpand ? { getExpandedRowModel: getExpandedRowModel() } : {}),
+    ...(getRowId ? { getRowId } : {}),
+  });
+
+  const visibleColumnCount = table.getVisibleLeafColumns().length;
+  const showSkeletonRows = loading;
+  const showError = !loading && error !== undefined;
+  const showEmpty = !loading && !showError && table.getRowModel().rows.length === 0;
+  const skeletonRows = pageSize > 0 ? Math.min(pageSize, 8) : 5;
+
+  // Toolbar
+  const showColumnToggle = enableColumnVisibility;
+  const showSearch = enableGlobalSearch;
+  const showToolbar = toolbar !== undefined || showSearch || showColumnToggle || toolbarActions;
+
+  // Polite live-region announcement for sort changes. `aria-sort` on each
+  // <th> exposes per-column state at focus time, but state CHANGES are
+  // silent without a live region. Per spec phase-4 §118 (sort announcements).
+  const sortAnnouncement =
+    sorting.length > 0
+      ? `Sorted by ${sorting[0]!.id}, ${sorting[0]!.desc ? "descending" : "ascending"}`
+      : "";
+
+  return (
+    <div ref={ref} className={cn("space-y-3", className)}>
+      <div role="status" aria-live="polite" aria-atomic="true" className="sr-only">
+        {sortAnnouncement}
+      </div>
+      {showToolbar ? (
+        <div className="flex flex-wrap items-center gap-2">
+          {toolbar ?? (
+            <>
+              {showSearch ? (
+                <div className="w-72">
+                  <Input
+                    id={searchInputId}
+                    type="search"
+                    placeholder={searchPlaceholder}
+                    value={globalFilter}
+                    onChange={(e) => setGlobalFilter(e.target.value)}
+                    startAdornment={<RiSearchLine />}
+                    clearable
+                    onClear={() => setGlobalFilter("")}
+                    aria-label="Search rows"
+                  />
+                </div>
+              ) : null}
+              <div className="ms-auto flex items-center gap-2">
+                {toolbarActions}
+                {showColumnToggle ? (
+                  <DropdownMenu>
+                    <DropdownMenuTrigger asChild>
+                      <Button variant="outline" size="sm" leftIcon={<RiSettings3Line />}>
+                        Columns
+                      </Button>
+                    </DropdownMenuTrigger>
+                    <DropdownMenuContent align="end">
+                      <DropdownMenuLabel>Toggle columns</DropdownMenuLabel>
+                      <DropdownMenuSeparator />
+                      {table
+                        .getAllLeafColumns()
+                        .filter((c) => c.id !== "__select" && c.getCanHide())
+                        .map((col) => (
+                          <DropdownMenuCheckboxItem
+                            key={col.id}
+                            checked={col.getIsVisible()}
+                            onCheckedChange={(v) => col.toggleVisibility(Boolean(v))}
+                          >
+                            {String(col.columnDef.header ?? col.id)}
+                          </DropdownMenuCheckboxItem>
+                        ))}
+                    </DropdownMenuContent>
+                  </DropdownMenu>
+                ) : null}
+              </div>
+            </>
+          )}
+        </div>
+      ) : null}
+
+      <Table
+        {...(density !== undefined ? { density } : {})}
+        {...(striped !== undefined ? { striped } : {})}
+        {...(bordered !== undefined ? { bordered } : {})}
+        {...(hoverable !== undefined ? { hoverable } : {})}
+        {...(stickyHeader !== undefined ? { stickyHeader } : {})}
+      >
+        <TableHeader>
+          {table.getHeaderGroups().map((headerGroup) => (
+            <TableRow key={headerGroup.id}>
+              {headerGroup.headers.map((header) => {
+                const meta = header.column.columnDef.meta;
+                const align = meta?.align;
+                const sortDir = header.column.getIsSorted();
+                const canSort = header.column.getCanSort();
+                return (
+                  <TableHead
+                    key={header.id}
+                    style={widthStyle(meta?.width)}
+                    aria-sort={
+                      canSort
+                        ? sortDir === "asc"
+                          ? "ascending"
+                          : sortDir === "desc"
+                            ? "descending"
+                            : "none"
+                        : undefined
+                    }
+                    className={cn(alignClass(align), meta?.truncate && "truncate")}
+                  >
+                    {header.isPlaceholder ? null : canSort ? (
+                      <button
+                        type="button"
+                        onClick={(e) =>
+                          header.column.toggleSorting(undefined, e.shiftKey && enableMultiSort)
+                        }
+                        className={cn(
+                          "inline-flex cursor-pointer items-center gap-1 rounded-sm select-none",
+                          "hover:text-foreground",
+                          "focus-visible:ring-ring focus-visible:ring-offset-background focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none",
+                          "[&_svg]:size-3.5 [&_svg]:shrink-0",
+                        )}
+                      >
+                        <span>
+                          {flexRender(header.column.columnDef.header, header.getContext())}
+                        </span>
+                        {sortDir === "asc" ? (
+                          <RiArrowUpLine className="rtl-mirror" />
+                        ) : sortDir === "desc" ? (
+                          <RiArrowDownLine className="rtl-mirror" />
+                        ) : (
+                          <RiArrowUpDownLine className="rtl-mirror opacity-50" />
+                        )}
+                      </button>
+                    ) : (
+                      flexRender(header.column.columnDef.header, header.getContext())
+                    )}
+                  </TableHead>
+                );
+              })}
+            </TableRow>
+          ))}
+        </TableHeader>
+
+        <TableBody>
+          {showSkeletonRows ? (
+            Array.from({ length: skeletonRows }, (_, i) => (
+              <TableRow key={`skeleton-${i}`}>
+                {Array.from({ length: visibleColumnCount }, (__, c) => (
+                  <TableCell key={c}>
+                    <Skeleton className="h-4 w-full" />
+                  </TableCell>
+                ))}
+              </TableRow>
+            ))
+          ) : showError ? (
+            <TableRow>
+              <TableCell colSpan={visibleColumnCount} className="p-0">
+                <div className="p-6">{error}</div>
+              </TableCell>
+            </TableRow>
+          ) : showEmpty ? (
+            <TableRow>
+              <TableCell colSpan={visibleColumnCount} className="p-0">
+                {empty ?? (
+                  <EmptyState
+                    size="sm"
+                    title="No results"
+                    description="There are no rows to display."
+                  />
+                )}
+              </TableCell>
+            </TableRow>
+          ) : (
+            table.getRowModel().rows.map((row) => (
+              <Fragment key={row.id}>
+                <TableRow
+                  data-state={row.getIsSelected() ? "selected" : undefined}
+                  aria-selected={row.getIsSelected() || undefined}
+                  className={rowClassName?.(row.original)}
+                >
+                  {row.getVisibleCells().map((cell, cellIdx) => {
+                    const meta = cell.column.columnDef.meta;
+                    const expandCellIdx = enableSelection !== "none" ? 1 : 0;
+                    return (
+                      <TableCell
+                        key={cell.id}
+                        style={widthStyle(meta?.width)}
+                        className={cn(alignClass(meta?.align), meta?.truncate && "truncate")}
+                      >
+                        {enableRowExpand && cellIdx === expandCellIdx ? (
+                          <div className="flex items-center gap-2">
+                            <button
+                              type="button"
+                              onClick={() => row.toggleExpanded()}
+                              aria-label={row.getIsExpanded() ? "Collapse row" : "Expand row"}
+                              aria-expanded={row.getIsExpanded()}
+                              className={cn(
+                                "inline-flex size-6 items-center justify-center rounded",
+                                "hover:bg-accent cursor-pointer",
+                                "focus-visible:ring-ring focus-visible:ring-offset-background focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none",
+                                "[&_svg]:size-4 [&_svg]:shrink-0",
+                              )}
+                            >
+                              {row.getIsExpanded() ? (
+                                <RiArrowDownLine />
+                              ) : (
+                                <RiArrowUpDownLine className="rtl-mirror" />
+                              )}
+                            </button>
+                            {flexRender(cell.column.columnDef.cell, cell.getContext())}
+                          </div>
+                        ) : (
+                          flexRender(cell.column.columnDef.cell, cell.getContext())
+                        )}
+                      </TableCell>
+                    );
+                  })}
+                </TableRow>
+                {enableRowExpand && row.getIsExpanded() ? (
+                  <TableRow>
+                    <TableCell colSpan={row.getVisibleCells().length} className="bg-muted/30">
+                      {renderExpandedRow?.(row.original) ?? null}
+                    </TableCell>
+                  </TableRow>
+                ) : null}
+              </Fragment>
+            ))
+          )}
+        </TableBody>
+      </Table>
+
+      {enablePagination && !loading && !showError ? (
+        <DataPagination
+          page={table.getState().pagination.pageIndex + 1}
+          pageCount={Math.max(1, table.getPageCount())}
+          onPageChange={(p) => table.setPageIndex(p - 1)}
+          pageSize={table.getState().pagination.pageSize}
+          pageSizeOptions={pageSizeOptions}
+          onPageSizeChange={(s) => table.setPageSize(s)}
+          totalItems={table.getFilteredRowModel().rows.length}
+        />
+      ) : null}
+    </div>
+  );
+}
+
+const DataTable = forwardRef(DataTableInner) as <T>(
+  props: DataTableProps<T> & { ref?: React.Ref<HTMLDivElement> },
+) => React.ReactElement;
+
+(DataTable as unknown as { displayName: string }).displayName = "DataTable";
+
+export { DataTable };
+export type { DataTableProps, SelectionMode };