@zentauri-ui/zentauri-components 2.1.5 → 2.1.7

package/src/ui/data-table/data-table.test.tsx

@@ -0,0 +1,389 @@
+import { act, fireEvent, render, screen, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+
+import { DataTable } from "./data-table";
+import type { DataTableColumn } from "./types";
+
+type Person = {
+  id: string;
+  name: string;
+  email: string;
+  role: string;
+  status: "Active" | "Invited";
+  score: number;
+};
+
+const people: Person[] = [
+  {
+    id: "ada",
+    name: "Ada Lovelace",
+    email: "ada@example.com",
+    role: "Engineer",
+    status: "Active",
+    score: 92,
+  },
+  {
+    id: "grace",
+    name: "Grace Hopper",
+    email: "grace@example.com",
+    role: "Architect",
+    status: "Invited",
+    score: 98,
+  },
+  {
+    id: "katherine",
+    name: "Katherine Johnson",
+    email: "katherine@example.com",
+    role: "Analyst",
+    status: "Active",
+    score: 95,
+  },
+];
+
+const columns: DataTableColumn<Person>[] = [
+  {
+    id: "name",
+    header: "Name",
+    accessor: "name",
+    sortable: true,
+    filterable: true,
+    cell: ({ value }) => <strong>{String(value)}</strong>,
+  },
+  {
+    id: "email",
+    header: "Email",
+    accessor: "email",
+    filterable: true,
+  },
+  {
+    id: "role",
+    header: "Role",
+    accessor: "role",
+    filterable: true,
+  },
+  {
+    id: "score",
+    header: "Score",
+    accessor: "score",
+    sortable: true,
+    textAlign: "right",
+  },
+];
+
+function renderPeopleTable(
+  props: Partial<React.ComponentProps<typeof DataTable<Person>>> = {},
+) {
+  return render(
+    <DataTable
+      aria-label="People"
+      columns={columns}
+      data={people}
+      getRowId={(row) => row.id}
+      {...props}
+    />,
+  );
+}
+
+function getBodyRows() {
+  return screen
+    .getAllByRole("row")
+    .filter((row) => within(row).queryAllByRole("cell").length > 0);
+}
+
+describe("DataTable", () => {
+  it("should expose a stable displayName", () => {
+    expect(DataTable.displayName).toBe("DataTable");
+  });
+
+  it("should render typed columns and rows with custom cells", () => {
+    renderPeopleTable();
+
+    expect(screen.getByRole("table", { name: "People" })).toBeVisible();
+    expect(screen.getByRole("columnheader", { name: "Name" })).toBeVisible();
+    expect(screen.getByRole("columnheader", { name: "Email" })).toBeVisible();
+    expect(
+      screen.getByRole("rowheader", { name: "Ada Lovelace" }),
+    ).toContainHTML("strong");
+    expect(screen.getByRole("cell", { name: "Engineer" })).toBeVisible();
+  });
+
+  it("should filter rows through the built-in search control", async () => {
+    const user = userEvent.setup();
+    renderPeopleTable({ search: { placeholder: "Search people" } });
+
+    await user.type(
+      screen.getByRole("searchbox", { name: "Search table" }),
+      "grace",
+    );
+
+    expect(
+      screen.getByRole("rowheader", { name: "Grace Hopper" }),
+    ).toBeVisible();
+    expect(
+      screen.queryByRole("rowheader", { name: "Ada Lovelace" }),
+    ).toBeNull();
+    expect(
+      screen.queryByRole("rowheader", { name: "Katherine Johnson" }),
+    ).toBeNull();
+  });
+
+  it("should warn and fall back to all filterable columns when filterColumnIds is empty", async () => {
+    const user = userEvent.setup();
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    renderPeopleTable({
+      search: { filterColumnIds: [], placeholder: "Search people" },
+    });
+
+    await user.type(
+      screen.getByRole("searchbox", { name: "Search table" }),
+      "grace",
+    );
+
+    expect(warn).toHaveBeenCalledWith(
+      "DataTable search.filterColumnIds is empty. It should include at least one column id.",
+    );
+    expect(
+      screen.getByRole("rowheader", { name: "Grace Hopper" }),
+    ).toBeVisible();
+    expect(
+      screen.queryByRole("rowheader", { name: "Ada Lovelace" }),
+    ).toBeNull();
+
+    warn.mockRestore();
+  });
+
+  it("should sort rows when sortable headers are activated", async () => {
+    const user = userEvent.setup();
+    renderPeopleTable();
+
+    await user.click(screen.getByRole("columnheader", { name: "Score" }));
+    expect(getBodyRows().map((row) => row.textContent)).toEqual([
+      expect.stringContaining("Ada Lovelace"),
+      expect.stringContaining("Katherine Johnson"),
+      expect.stringContaining("Grace Hopper"),
+    ]);
+
+    await user.click(screen.getByRole("columnheader", { name: "Score" }));
+    expect(getBodyRows().map((row) => row.textContent)).toEqual([
+      expect.stringContaining("Grace Hopper"),
+      expect.stringContaining("Katherine Johnson"),
+      expect.stringContaining("Ada Lovelace"),
+    ]);
+  });
+
+  it("should give duplicate rows distinct ids so selection does not collapse", async () => {
+    const user = userEvent.setup();
+    const handleSelectionChange = vi.fn();
+    const dup: Person = {
+      id: "dup",
+      name: "Dup",
+      email: "dup@example.com",
+      role: "Engineer",
+      status: "Active",
+      score: 1,
+    };
+    render(
+      <DataTable
+        aria-label="Duplicates"
+        columns={columns}
+        data={[dup, dup]}
+        enableRowSelection
+        onRowSelectionChange={handleSelectionChange}
+      />,
+    );
+
+    const checkboxes = screen.getAllByRole("checkbox", { name: "Select Dup" });
+    expect(checkboxes).toHaveLength(2);
+
+    const [firstCheckbox, secondCheckbox] = checkboxes;
+
+    await user.click(firstCheckbox!);
+
+    expect(firstCheckbox).toBeChecked();
+    expect(secondCheckbox).not.toBeChecked();
+    expect(handleSelectionChange).toHaveBeenLastCalledWith(["0"], [dup]);
+  });
+
+  it("should support row selection and bulk actions", async () => {
+    const user = userEvent.setup();
+    const handleArchive = vi.fn();
+    renderPeopleTable({
+      enableRowSelection: true,
+      bulkActions: [{ label: "Archive selected", onSelect: handleArchive }],
+    });
+
+    await user.click(
+      screen.getByRole("checkbox", { name: "Select Ada Lovelace" }),
+    );
+    await user.click(screen.getByRole("button", { name: "Archive selected" }));
+
+    expect(handleArchive).toHaveBeenCalledWith([
+      expect.objectContaining({ id: "ada", name: "Ada Lovelace" }),
+    ]);
+  });
+
+  it("should keep row selection stable across paginated fallback row ids", async () => {
+    const user = userEvent.setup();
+    const handleSelectionChange = vi.fn();
+    const handleArchive = vi.fn();
+    render(
+      <DataTable
+        aria-label="People"
+        columns={columns}
+        data={people}
+        enableRowSelection
+        pagination={{ pageSize: 2 }}
+        onRowSelectionChange={handleSelectionChange}
+        bulkActions={[{ label: "Archive selected", onSelect: handleArchive }]}
+      />,
+    );
+
+    await user.click(
+      screen.getByRole("checkbox", { name: "Select Ada Lovelace" }),
+    );
+    await user.click(screen.getByRole("button", { name: "Page 2" }));
+
+    expect(
+      screen.getByRole("checkbox", { name: "Select Katherine Johnson" }),
+    ).not.toBeChecked();
+
+    await user.click(screen.getByRole("button", { name: "Archive selected" }));
+
+    expect(handleSelectionChange).toHaveBeenLastCalledWith(
+      ["0"],
+      [expect.objectContaining({ name: "Ada Lovelace" })],
+    );
+    expect(handleArchive).toHaveBeenCalledWith([
+      expect.objectContaining({ name: "Ada Lovelace" }),
+    ]);
+  });
+
+  it("should let users hide optional columns", async () => {
+    const user = userEvent.setup();
+    renderPeopleTable({ enableColumnVisibility: true });
+
+    await user.click(screen.getByRole("button", { name: "Columns" }));
+    await user.click(screen.getByRole("checkbox", { name: "Email column" }));
+
+    expect(screen.queryByRole("columnheader", { name: "Email" })).toBeNull();
+    expect(screen.queryByRole("cell", { name: "ada@example.com" })).toBeNull();
+    expect(screen.getByRole("columnheader", { name: "Name" })).toBeVisible();
+  });
+
+  it("should paginate processed rows", async () => {
+    const user = userEvent.setup();
+    renderPeopleTable({ pagination: { pageSize: 2 } });
+
+    expect(
+      screen.getByRole("rowheader", { name: "Ada Lovelace" }),
+    ).toBeVisible();
+    expect(
+      screen.queryByRole("rowheader", { name: "Katherine Johnson" }),
+    ).toBeNull();
+
+    await user.click(screen.getByRole("button", { name: "Page 2" }));
+
+    expect(
+      screen.getByRole("rowheader", { name: "Katherine Johnson" }),
+    ).toBeVisible();
+    expect(
+      screen.queryByRole("rowheader", { name: "Ada Lovelace" }),
+    ).toBeNull();
+  });
+
+  it("should hide the row count when showRowCount is false", () => {
+    renderPeopleTable({ pagination: { pageSize: 2 }, showRowCount: false });
+
+    expect(screen.queryByText("Showing 2 of 3")).toBeNull();
+    expect(screen.getByRole("button", { name: "Page 2" })).toBeVisible();
+  });
+
+  it("should offset virtualized rows while scrolling", () => {
+    const descriptor = Object.getOwnPropertyDescriptor(
+      HTMLElement.prototype,
+      "clientHeight",
+    );
+    Object.defineProperty(HTMLElement.prototype, "clientHeight", {
+      configurable: true,
+      get() {
+        return this.getAttribute("data-slot") === "data-table-virtual-scroll"
+          ? 80
+          : 0;
+      },
+    });
+    const rows = Array.from({ length: 20 }, (_, index) => ({
+      id: `person-${index}`,
+      name: `Person ${index}`,
+      email: `person-${index}@example.com`,
+      role: "Engineer",
+      status: "Active" as const,
+      score: index,
+    }));
+
+    try {
+      render(
+        <DataTable
+          aria-label="People"
+          columns={columns}
+          data={rows}
+          getRowId={(row) => row.id}
+          virtualization={{
+            enabled: true,
+            rowHeight: 40,
+            height: 80,
+            overscan: 0,
+          }}
+        />,
+      );
+      const scrollArea = document.querySelector(
+        '[data-slot="data-table-virtual-scroll"]',
+      );
+      expect(scrollArea).not.toBeNull();
+
+      act(() => {
+        if (scrollArea) {
+          scrollArea.scrollTop = 200;
+          fireEvent.scroll(scrollArea);
+        }
+      });
+
+      const offset = document.querySelector(
+        '[data-slot="data-table-virtual-offset"]',
+      );
+      expect(offset).toHaveStyle({ transform: "translateY(200px)" });
+      expect(screen.getByRole("rowheader", { name: "Person 5" })).toBeVisible();
+    } finally {
+      if (descriptor) {
+        Object.defineProperty(
+          HTMLElement.prototype,
+          "clientHeight",
+          descriptor,
+        );
+      } else {
+        delete (HTMLElement.prototype as { clientHeight?: number })
+          .clientHeight;
+      }
+    }
+  });
+
+  it("should render loading and empty states", () => {
+    const { rerender } = render(
+      <DataTable
+        columns={columns}
+        data={[]}
+        loading
+        loadingContent="Loading people"
+      />,
+    );
+
+    expect(screen.getByText("Loading people")).toBeVisible();
+
+    rerender(
+      <DataTable columns={columns} data={[]} emptyContent="No people found" />,
+    );
+
+    expect(screen.getByText("No people found")).toBeVisible();
+  });
+});

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

@@ -0,0 +1,11 @@
+// data-table.tsx — default static entry (no framer-motion)
+import { DataTableBase } from "./data-table-base";
+import type { DataTableProps } from "./types";
+
+export function DataTable<TData, TKey extends string = string>(
+  props: DataTableProps<TData, TKey>,
+) {
+  return <DataTableBase {...props} />;
+}
+
+DataTable.displayName = "DataTable";

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

@@ -0,0 +1,24 @@
+"use client";
+
+export { DataTable } from "./data-table";
+export type {
+  DataTableBulkAction,
+  DataTableCellContext,
+  DataTableColumn,
+  DataTableColumnTextAlign,
+  DataTableColumnValue,
+  DataTableHeaderContext,
+  DataTablePaginationOptions,
+  DataTableProps,
+  DataTableSearchOptions,
+  DataTableVirtualizationOptions,
+} from "./types";
+export {
+  dataTableColumnPanelVariants,
+  dataTableRootVariants,
+  dataTableStateCellVariants,
+  dataTableStatusVariants,
+  dataTableToolbarGroupVariants,
+  dataTableToolbarVariants,
+  dataTableVirtualScrollVariants,
+} from "./variants";

package/src/ui/data-table/types.ts

@@ -0,0 +1,121 @@
+import type {
+  ComponentPropsWithRef,
+  ReactNode,
+  Ref,
+  TdHTMLAttributes,
+  ThHTMLAttributes,
+} from "react";
+
+import type { TableProps, TableSortDirection } from "../table";
+
+export type DataTableColumnValue =
+  | string
+  | number
+  | boolean
+  | Date
+  | null
+  | undefined;
+
+export type DataTableColumnTextAlign = NonNullable<TableProps["textAlign"]>;
+
+export type DataTableCellContext<TData> = {
+  row: TData;
+  value: unknown;
+  column: DataTableColumn<TData>;
+  rowIndex: number;
+};
+
+export type DataTableHeaderContext<TData> = {
+  column: DataTableColumn<TData>;
+};
+
+export type DataTableColumn<TData, TKey extends string = string> = {
+  id: TKey;
+  header: ReactNode | ((context: DataTableHeaderContext<TData>) => ReactNode);
+  accessor?: keyof TData | ((row: TData) => unknown);
+  cell?: (context: DataTableCellContext<TData>) => ReactNode;
+  sortable?: boolean;
+  sortValue?: (row: TData) => DataTableColumnValue;
+  filterable?: boolean;
+  filterValue?: (row: TData) => DataTableColumnValue;
+  visible?: boolean;
+  enableHiding?: boolean;
+  textAlign?: DataTableColumnTextAlign;
+  className?: string;
+  headerClassName?: string;
+  cellClassName?: string;
+  headerProps?: ThHTMLAttributes<HTMLTableCellElement>;
+  cellProps?: TdHTMLAttributes<HTMLTableCellElement>;
+};
+
+export type DataTableSearchOptions<TKey extends string = string> = {
+  value?: string;
+  defaultValue?: string;
+  onValueChange?: (value: string) => void;
+  placeholder?: string;
+  label?: string;
+  filterColumnIds?: readonly TKey[];
+};
+
+export type DataTablePaginationOptions = {
+  pageSize?: number;
+  page?: number;
+  defaultPage?: number;
+  onPageChange?: (page: number) => void;
+  siblingCount?: number;
+  boundaryCount?: number;
+};
+
+export type DataTableBulkAction<TData> = {
+  label: ReactNode;
+  onSelect: (selectedRows: TData[]) => void;
+  disabled?: boolean;
+};
+
+export type DataTableVirtualizationOptions = {
+  enabled?: boolean;
+  rowHeight: number;
+  height: number;
+  overscan?: number;
+};
+
+export type DataTableProps<TData, TKey extends string = string> = Omit<
+  ComponentPropsWithRef<"section">,
+  "children" | "onChange"
+> &
+  Pick<TableProps, "appearance" | "size" | "stickyHeader" | "textAlign"> & {
+    data: readonly TData[];
+    columns: readonly DataTableColumn<TData, TKey>[];
+    getRowId?: (row: TData, index: number) => string;
+    caption?: ReactNode;
+    tableClassName?: string;
+    tableScrollAreaAriaLabel?: string;
+    search?: boolean | DataTableSearchOptions<TKey>;
+    sortKey?: TKey;
+    defaultSortKey?: TKey;
+    sortDirection?: TableSortDirection;
+    defaultSortDirection?: TableSortDirection;
+    onSortChange?: (sort: {
+      sortKey?: TKey;
+      sortDirection: TableSortDirection;
+    }) => void;
+    enableRowSelection?: boolean;
+    selectedRowIds?: readonly string[];
+    defaultSelectedRowIds?: readonly string[];
+    onRowSelectionChange?: (
+      selectedRowIds: string[],
+      selectedRows: TData[],
+    ) => void;
+    enableColumnVisibility?: boolean;
+    visibleColumnIds?: readonly TKey[];
+    defaultVisibleColumnIds?: readonly TKey[];
+    onColumnVisibilityChange?: (visibleColumnIds: TKey[]) => void;
+    bulkActions?: readonly DataTableBulkAction<TData>[];
+    pagination?: boolean | DataTablePaginationOptions;
+    virtualization?: DataTableVirtualizationOptions;
+    showRowCount?: boolean;
+    loading?: boolean;
+    loadingContent?: ReactNode;
+    emptyContent?: ReactNode;
+    ref?: Ref<HTMLElement>;
+  };

package/src/ui/data-table/variants.ts

@@ -0,0 +1,21 @@
+import { cva } from "class-variance-authority";
+
+import {
+  zuiDataTableColumnPanelBase,
+  zuiDataTableRootBase,
+  zuiDataTableStateCellBase,
+  zuiDataTableStatusBase,
+  zuiDataTableToolbarBase,
+  zuiDataTableToolbarGroupBase,
+  zuiDataTableVirtualScrollBase,
+} from "../../design-system/data-table";
+
+export const dataTableRootVariants = cva(zuiDataTableRootBase);
+export const dataTableToolbarVariants = cva(zuiDataTableToolbarBase);
+export const dataTableToolbarGroupVariants = cva(zuiDataTableToolbarGroupBase);
+export const dataTableColumnPanelVariants = cva(zuiDataTableColumnPanelBase);
+export const dataTableStatusVariants = cva(zuiDataTableStatusBase);
+export const dataTableStateCellVariants = cva(zuiDataTableStateCellBase);
+export const dataTableVirtualScrollVariants = cva(
+  zuiDataTableVirtualScrollBase,
+);