@rovula/ui 0.1.28 → 0.1.30

package/src/components/DataTable/DataTable.stories.tsx

@@ -1,22 +1,51 @@
 import React from "react";
 import type { Meta, StoryObj } from "@storybook/react";
+import { ColumnDef, Row } from "@tanstack/react-table";
 import { DataTable } from "./DataTable";
-import { ColumnDef } from "@tanstack/react-table";
+import type { EditableColumnDef } from "./DataTable.editing.types";
+import {
+  EllipsisVertical,
+  ChevronRight,
+  FileDown,
+  FileUp,
+  Trash2,
+} from "lucide-react";
+import ActionButton from "@/components/ActionButton/ActionButton";
+import Button from "@/components/Button/Button";
+import { Badge, type BadgeColor } from "@/components/Badge/Badge";
+import { type Options } from "@/components/Dropdown/Dropdown";
+import { cn } from "@/utils/cn";
 
 const meta = {
   title: "Components/DataTable",
   component: DataTable,
   tags: ["autodocs"],
-  parameters: {
-    layout: "fullscreen",
+  parameters: { layout: "fullscreen" },
+  argTypes: {
+    bordered: { control: "boolean" },
+    surface: {
+      control: "radio",
+      options: ["default", "panel"],
+    },
+    divided: { control: "boolean" },
+    striped: { control: "boolean" },
+    fetchingMore: { control: "boolean" },
+    loading: { control: "boolean" },
   },
   decorators: [
     (Story) => (
       <div
-        className="p-5 flex flex-1 h-full w-full "
+        className="p-5 flex flex-1 h-full w-full min-h-0 bg-page-bg-main items-stretch"
         style={{ height: "100vh" }}
       >
-        <Story />
+        {/*
+         * Never add data-surface="panel" on this root: it pairs table panel
+         * tokens with bg-page-bg-main (wrong surface). Use story "OnPanelSurface"
+         * or a wrapper with bg-modal-surface + data-surface="panel".
+         */}
+        <div className="w-full min-h-0 flex-1">
+          <Story />
+        </div>
       </div>
     ),
   ],
@@ -24,49 +53,2299 @@ const meta = {
 
 export default meta;
 
-const columns: ColumnDef<any>[] = [
+// ---------------------------------------------------------------------------
+// Shared fixtures — Project
+// ---------------------------------------------------------------------------
+
+type Project = {
+  id: string;
+  name: string;
+  type: "Drone" | "ROV" | "AUV";
+  subtype: string;
+  createdDate: string;
+  status: "To do" | "In Progress" | "Completed";
+};
+
+/* prettier-ignore */
+const projectData: Project[] = [
+  { id: "1", name: "Drone inspection",          type: "Drone", subtype: "Visual inspection",          createdDate: "15 Mar 2026", status: "To do"      },
+  { id: "2", name: "ROV Structure inspection",  type: "ROV",   subtype: "Text",                       createdDate: "01 Jan 2026", status: "In Progress" },
+  { id: "3", name: "ROV Structure inspection",  type: "ROV",   subtype: "Structure Inspection",       createdDate: "15 Feb 2026", status: "Completed"   },
+  { id: "4", name: "AUV Pipeline inspection",   type: "AUV",   subtype: "Subsea pipeline Inspection", createdDate: "30 Jan 2026", status: "In Progress" },
+  { id: "5", name: "ROV Structure inspection",  type: "ROV",   subtype: "Structure Inspection",       createdDate: "01 Jan 2026", status: "Completed"   },
+];
+
+/** Same rows repeated for pagination demos — each row needs a unique `id` (React `key` + TanStack row id). */
+const projectDataCopies = (copies: number): Project[] =>
+  Array.from({ length: copies }, (_, copy) =>
+    projectData.map((r) => ({ ...r, id: `${r.id}-c${copy}` })),
+  ).flat();
+
+/** Large pool for infinite-scroll load-more demos. */
+const infiniteScrollPool = projectDataCopies(30);
+
+/* prettier-ignore */
+const statusCls: Record<Project["status"], string> = {
+  "To do":       "bg-transparent-grey2-8 text-text-contrast-max",
+  "In Progress": "bg-warning-500/20      text-warning-400",
+  "Completed":   "bg-success-500/20      text-success-400",
+};
+
+const StatusBadge = ({ status }: { status: Project["status"] }) => (
+  <span
+    className={`inline-flex items-center px-3 py-1 rounded-lg typography-body3 ${statusCls[status]}`}
+  >
+    {status}
+  </span>
+);
+
+/* prettier-ignore */
+const projectColumns: ColumnDef<Project>[] = [
+  { accessorKey: "name",        header: "Project name" },
+  { accessorKey: "type",        header: "Type"},
+  { accessorKey: "subtype",     header: "Subtype" },
+  { accessorKey: "createdDate", header: "Created date" },
+  { accessorKey: "status",      header: "Status", cell: ({ row }) => <StatusBadge status={row.original.status} /> },
+];
+
+const ProjectRowActions = ({ row }: { row: Row<Project> }) => (
+  <>
+    <ActionButton
+      variant="icon"
+      size="sm"
+      onClick={() => console.log("menu", row.original)}
+      aria-label="More options"
+    >
+      <EllipsisVertical />
+    </ActionButton>
+    <ActionButton
+      variant="icon"
+      size="sm"
+      onClick={() => console.log("open", row.original)}
+      aria-label="Open"
+    >
+      <ChevronRight />
+    </ActionButton>
+  </>
+);
+
+// ---------------------------------------------------------------------------
+// Shared fixtures — Inspection (column-management / resize stories)
+// ---------------------------------------------------------------------------
+
+type InspectionRow = {
+  id: string;
+  code: string;
+  assetName: string;
+  type: string;
+  subtype: string;
+  severity: "Highest" | "High" | "Medium" | "Low" | "Lowest";
+  inspector: string;
+  location: string;
+  capturedAt: string;
+  status: "To do" | "In Progress" | "Completed";
+  kpi: number;
+  notes: string;
+};
+
+/* prettier-ignore */
+const inspectionData: InspectionRow[] = [
+  { id: "1", code: "INS-001", assetName: "Pipeline A",  type: "ROV",   subtype: "Structural",  severity: "Highest", inspector: "John D.",  location: "Block A", capturedAt: "01 Jan 2026", status: "Completed",   kpi: 98,  notes: "Crack detected"     },
+  { id: "2", code: "INS-002", assetName: "Pipeline B",  type: "AUV",   subtype: "Corrosion",   severity: "High",    inspector: "Sarah K.", location: "Block B", capturedAt: "05 Jan 2026", status: "In Progress", kpi: 72,  notes: "Corrosion spreading"},
+  { id: "3", code: "INS-003", assetName: "Riser C",     type: "Drone", subtype: "Visual",      severity: "Medium",  inspector: "Mike L.",  location: "Block C", capturedAt: "10 Jan 2026", status: "To do",       kpi: 0,   notes: "-"                 },
+  { id: "4", code: "INS-004", assetName: "Wellhead D",  type: "ROV",   subtype: "Structural",  severity: "Low",     inspector: "Anna T.",  location: "Block A", capturedAt: "15 Jan 2026", status: "Completed",   kpi: 100, notes: "No issues found"   },
+  { id: "5", code: "INS-005", assetName: "Flowline E",  type: "AUV",   subtype: "Leak detect", severity: "Lowest",  inspector: "John D.",  location: "Block D", capturedAt: "20 Jan 2026", status: "In Progress", kpi: 55,  notes: "Minor seepage"     },
+  { id: "6", code: "INS-006", assetName: "Manifold F",  type: "Drone", subtype: "Visual",      severity: "High",    inspector: "Sarah K.", location: "Block B", capturedAt: "22 Jan 2026", status: "To do",       kpi: 0,   notes: "-"                 },
+  { id: "7", code: "INS-007", assetName: "Subsea G",    type: "ROV",   subtype: "Structural",  severity: "Medium",  inspector: "Mike L.",  location: "Block E", capturedAt: "25 Jan 2026", status: "In Progress", kpi: 44,  notes: "Under review"      },
+];
+
+/* prettier-ignore */
+const severityCls: Record<InspectionRow["severity"], string> = {
+  Highest: "bg-error-500/20   text-error-400",
+  High:    "bg-orange-500/20  text-orange-400",
+  Medium:  "bg-warning-500/20 text-warning-400",
+  Low:     "bg-success-500/20 text-success-400",
+  Lowest:  "bg-info-500/20    text-info-400",
+};
+
+/* prettier-ignore */
+const inspectionStatusCls: Record<InspectionRow["status"], string> = {
+  "To do":       "bg-transparent text-text-contrast-max border border-white/20",
+  "In Progress": "bg-warning-500/20 text-warning-400",
+  Completed:     "bg-success-500/20 text-success-400",
+};
+
+const inspectionColumns: ColumnDef<InspectionRow>[] = [
+  { accessorKey: "code", header: "Code", size: 100 },
+  { accessorKey: "assetName", header: "Asset name" },
+  { accessorKey: "type", header: "Type", size: 90 },
+  { accessorKey: "subtype", header: "Subtype" },
   {
-    accessorKey: "amount",
+    accessorKey: "severity",
+    header: "Severity",
+    size: 120,
+    cell: ({ row }) => (
+      <span
+        className={`inline-flex items-center px-2 py-0.5 rounded-lg typography-small2 ${
+          severityCls[row.original.severity]
+        }`}
+      >
+        {row.original.severity}
+      </span>
+    ),
   },
+  { accessorKey: "inspector", header: "Inspector" },
+  { accessorKey: "location", header: "Location", size: 100 },
+  { accessorKey: "capturedAt", header: "Captured date", size: 140 },
   {
     accessorKey: "status",
+    header: "Status",
+    size: 130,
+    cell: ({ row }) => (
+      <span
+        className={`inline-flex items-center px-3 py-1 rounded-lg typography-body3 ${
+          inspectionStatusCls[row.original.status]
+        }`}
+      >
+        {row.original.status}
+      </span>
+    ),
+  },
+  { accessorKey: "kpi", header: "KPI (%)", size: 90 },
+  { accessorKey: "notes", header: "Notes" },
+];
+
+// ---------------------------------------------------------------------------
+// Shared fixtures — Event (expandable rows)
+// ---------------------------------------------------------------------------
+
+type EventRow = {
+  id: string;
+  code: string;
+  name: string;
+  severity: "Highest" | "High" | "Medium" | "Low" | "Lowest" | null;
+  children?: EventRow[];
+};
+
+/* prettier-ignore */
+const eventSeverityCls: Record<NonNullable<EventRow["severity"]>, string> = {
+  Highest: "bg-error-500   text-white",
+  High:    "bg-orange-500  text-white",
+  Medium:  "bg-warning-500 text-black",
+  Low:     "bg-success-500 text-white",
+  Lowest:  "bg-info-500    text-white",
+};
+
+const eventData: EventRow[] = [
+  {
+    id: "1",
+    code: "EV-001",
+    name: "Structural anomaly",
+    severity: "Highest",
+    children: [
+      {
+        id: "1-1",
+        code: "EV-001-A",
+        name: "Crack detected",
+        severity: "Highest",
+        children: [
+          {
+            id: "1-1-1",
+            code: "EV-001-A-1",
+            name: "Sub-crack detected",
+            severity: "Highest",
+          },
+        ],
+      },
+      {
+        id: "1-2",
+        code: "EV-001-B",
+        name: "Corrosion detected",
+        severity: "High",
+      },
+    ],
+  },
+  {
+    id: "2",
+    code: "EV-002",
+    name: "Pipeline leak",
+    severity: "Low",
+    children: [
+      {
+        id: "2-1",
+        code: "EV-002-A",
+        name: "Minor seepage",
+        severity: "Lowest",
+      },
+    ],
   },
+  { id: "3", code: "EV-003", name: "Obstruction", severity: "Medium" },
+];
+
+const eventColumns: ColumnDef<EventRow>[] = [
+  { accessorKey: "code", header: "Code" },
+  { accessorKey: "name", header: "Name" },
   {
-    accessorKey: "email",
+    accessorKey: "severity",
+    header: "Severity level",
+    cell: ({ row }) =>
+      row.original.severity ? (
+        <span
+          className={`inline-flex items-center px-2 py-0.5 rounded typography-small3 ${
+            eventSeverityCls[row.original.severity]
+          }`}
+        >
+          {row.original.severity}
+        </span>
+      ) : (
+        <span className="text-text-g-contrast-medium">–</span>
+      ),
   },
 ];
 
-export const Default = {
-  args: {},
-  render: (args) => {
-    console.log("args ", args);
-    const props: typeof args = {
-      ...args,
+// ---------------------------------------------------------------------------
+// 1. Basics
+// ---------------------------------------------------------------------------
+
+/** Default — striped rows + column dividers, all columns sortable. */
+export const Default: StoryObj = {
+  render: () => (
+    <DataTable
+      columns={projectColumns}
+      data={projectData}
+      striped
+      divided
+      onSorting={(s) => console.log("sort", s)}
+    />
+  ),
+};
+
+/**
+ * Matches the Figma "Projects" page design — striped alternating rows,
+ * column dividers, row actions (more + navigate), client pagination,
+ * and a rounded bordered frame.
+ *
+ * Design ref: Xspector-New / node 11786-14865
+ */
+export const FigmaProjectsPage: StoryObj = {
+  render: () => {
+    const figmaProjectColumns: ColumnDef<Project>[] = [
+      { accessorKey: "name", header: "Project name" },
+      { accessorKey: "type", header: "Type", size: 120 },
+      { accessorKey: "subtype", header: "Subtype" },
+      { accessorKey: "createdDate", header: "Created date", size: 180 },
+      {
+        accessorKey: "status",
+        header: "Status",
+        size: 200,
+        cell: ({ row }) => <StatusBadge status={row.original.status} />,
+      },
+    ];
+
+    return (
+      <DataTable
+        columns={figmaProjectColumns}
+        data={projectData}
+        bordered
+        striped
+        divided
+        tableLayout="fixed"
+        paginationMode="client"
+        pageSizeOptions={[5, 10, 20]}
+        rowActions={(row) => <ProjectRowActions row={row} />}
+        onSorting={(s) => console.log("sort", s)}
+      />
+    );
+  },
+};
+
+/** Empty state — displayed when `data` is an empty array. */
+export const Empty: StoryObj = {
+  render: () => (
+    <DataTable columns={projectColumns} data={[]} striped divided />
+  ),
+};
+
+/** Non-striped with column dividers only. */
+export const Divided: StoryObj = {
+  render: () => (
+    <DataTable columns={projectColumns} data={projectData} divided />
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// Panel surface (Modal / Drawer / Panel)
+// ---------------------------------------------------------------------------
+//
+// Wrapper uses data-surface="panel" so --table-* tokens from table.css apply
+// (same pattern as Table stories). You can instead set surface="panel" on
+// DataTable when the panel root is not a DOM ancestor of the table.
+
+/** Simulates a Modal / Drawer / Panel chrome around the table. */
+const DataTablePanelDecorator = ({
+  children,
+  className,
+}: {
+  children: React.ReactNode;
+  className?: string;
+}) => (
+  <div
+    data-surface="panel"
+    className={cn(
+      "rounded-lg bg-modal-surface p-6 w-full max-w-4xl mx-auto shadow-[0px_12px_24px_-4px_rgba(0,0,0,0.12)]",
+      className,
+    )}
+  >
+    <p className="typography-subtitle4 text-text-g-contrast-medium mb-4">
+      Modal / Panel surface
+    </p>
+    {children}
+  </div>
+);
+
+/**
+ * DataTable inside a panel — matches modal spec: horizontal row separators only
+ * (no vertical column rules), compact height without a stretched empty body.
+ */
+export const OnPanelSurface: StoryObj = {
+  render: () => (
+    <div className="flex w-full justify-center items-start">
+      <DataTablePanelDecorator className="self-start">
+        <DataTable
+          className="h-auto"
+          columns={projectColumns}
+          data={projectData}
+          striped={false}
+          divided={false}
+          onSorting={(s) => console.log("sort", s)}
+        />
+      </DataTablePanelDecorator>
+    </div>
+  ),
+};
+
+/** Panel + client pagination — footer sits in the same surface scope as the table body. */
+export const OnPanelSurfaceWithPagination: StoryObj = {
+  render: () => (
+    <div className="flex w-full justify-center items-start">
+      <DataTablePanelDecorator className="self-start">
+        <DataTable
+          className="h-auto max-h-[min(520px,70vh)]"
+          columns={projectColumns}
+          data={projectDataCopies(4)}
+          paginationMode="client"
+          pageSizeOptions={[5, 10, 20]}
+          striped={true}
+          divided={true}
+          columnManagement
+        />
+      </DataTablePanelDecorator>
+    </div>
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// 2. Pagination
+// ---------------------------------------------------------------------------
+
+/** Client-side pagination — DataTable manages page index & size internally. */
+export const WithClientPagination: StoryObj = {
+  render: () => (
+    <DataTable
+      columns={projectColumns}
+      data={projectDataCopies(4)}
+      paginationMode="client"
+      pageSizeOptions={[5, 10, 20]}
+      striped
+      divided
+    />
+  ),
+};
+
+/**
+ * Server-side pagination — the caller controls `pageIndex` / `pageSize` and
+ * slices data accordingly. `totalCount` drives the page-count calculation.
+ */
+export const WithServerPagination: StoryObj = {
+  render: () => {
+    const [pageIndex, setPageIndex] = React.useState(0);
+    const [pageSize, setPageSize] = React.useState(3);
+    const pagedData = projectData.slice(
+      pageIndex * pageSize,
+      (pageIndex + 1) * pageSize,
+    );
+    return (
+      <DataTable
+        columns={projectColumns}
+        data={pagedData}
+        paginationMode="server"
+        totalCount={projectData.length}
+        pageIndex={pageIndex}
+        pageSize={pageSize}
+        onPaginationChange={({ pageIndex: pi, pageSize: ps }) => {
+          setPageIndex(pi);
+          setPageSize(ps);
+        }}
+        pageSizeOptions={[3, 5]}
+        striped
+        divided
+      />
+    );
+  },
+};
+
+/**
+ * Infinite mode (default) — no pagination bar; the table body scrolls inside a
+ * fixed height. Use when the caller already passes the full (or windowed) dataset.
+ */
+export const WithInfiniteScrollStatic: StoryObj = {
+  render: () => (
+    <div className="flex w-full flex-col gap-3">
+      <p className="typography-body2 text-text-g-contrast-medium">
+        <code className="typography-mono">
+          paginationMode=&quot;infinite&quot;
+        </code>{" "}
+        (default) — no footer; scroll the body. Height capped via{" "}
+        <code className="typography-mono">className</code>.
+      </p>
+      <DataTable
+        className="h-[min(420px,55vh)] w-full"
+        columns={projectColumns}
+        data={projectDataCopies(8)}
+        paginationMode="infinite"
+        striped
+        divided
+      />
+    </div>
+  ),
+};
+
+/**
+ * Infinite scroll + load more — DataTable calls{" "}
+ * <code className="typography-mono">fetchMoreData</code> when the scroll position
+ * is within 10px of the bottom (see <code className="typography-mono">DataTable</code>{" "}
+ * <code className="typography-mono">useEffect</code> on <code className="typography-mono">scrollRef</code>).
+ * This story simulates an async page append.
+ */
+export const WithInfiniteScrollLoadMore: StoryObj = {
+  render: () => {
+    const pageSize = 10;
+    const [rows, setRows] = React.useState<Project[]>(() =>
+      infiniteScrollPool.slice(0, pageSize),
+    );
+    const [loading, setLoading] = React.useState(false);
+    const loadingRef = React.useRef(false);
+    const hasMore = rows.length < infiniteScrollPool.length;
+
+    const fetchMoreData = React.useCallback(() => {
+      if (loadingRef.current) return;
+      setRows((prev) => {
+        if (prev.length >= infiniteScrollPool.length) return prev;
+        const startLen = prev.length;
+        loadingRef.current = true;
+        queueMicrotask(() => setLoading(true));
+        window.setTimeout(() => {
+          setRows(
+            infiniteScrollPool.slice(
+              0,
+              Math.min(startLen + pageSize, infiniteScrollPool.length),
+            ),
+          );
+          loadingRef.current = false;
+          setLoading(false);
+        }, 650);
+        return prev;
+      });
+    }, []);
+
+    return (
+      <div className="flex w-full flex-col gap-3">
+        <p className="typography-body2 text-text-g-contrast-medium">
+          Scroll to the bottom to trigger{" "}
+          <code className="typography-mono">fetchMoreData</code>. Built-in{" "}
+          <code className="typography-mono">fetchingMore</code> shows a spinner
+          row inside the table. Loaded {rows.length} /{" "}
+          {infiniteScrollPool.length} rows.
+          {!hasMore ? " (end of list)" : ""}
+        </p>
+        <DataTable
+          className="h-[min(380px,50vh)] w-full"
+          columns={projectColumns}
+          data={rows}
+          paginationMode="infinite"
+          fetchMoreData={fetchMoreData}
+          fetchingMore={loading}
+          striped
+          divided
+        />
+      </div>
+    );
+  },
+};
+
+/**
+ * Initial load — pass `loading={true}` with `data={[]}` until the first page
+ * arrives; then set `loading={false}` and pass rows. Infinite `fetchMoreData`
+ * does not run while `loading` is true.
+ */
+export const WithInfiniteScrollInitialLoading: StoryObj = {
+  render: () => {
+    const pageSize = 10;
+    const [rows, setRows] = React.useState<Project[]>([]);
+    const [loading, setLoading] = React.useState(true);
+
+    React.useEffect(() => {
+      const t = window.setTimeout(() => {
+        setRows(infiniteScrollPool.slice(0, pageSize));
+        setLoading(false);
+      }, 1200);
+      return () => window.clearTimeout(t);
+    }, []);
+
+    const [fetchingMore, setFetchingMore] = React.useState(false);
+    const loadingMoreRef = React.useRef(false);
+    const [highlightId, setHighlightId] = React.useState<string | undefined>();
+
+    const fetchMoreData = React.useCallback(() => {
+      if (loadingMoreRef.current) return;
+      setRows((prev) => {
+        if (prev.length >= infiniteScrollPool.length) return prev;
+        loadingMoreRef.current = true;
+        queueMicrotask(() => setFetchingMore(true));
+        const startLen = prev.length;
+        window.setTimeout(() => {
+          setRows(
+            infiniteScrollPool.slice(
+              0,
+              Math.min(startLen + pageSize, infiniteScrollPool.length),
+            ),
+          );
+          loadingMoreRef.current = false;
+          setFetchingMore(false);
+        }, 550);
+        return prev;
+      });
+    }, []);
+
+    return (
+      <div className="flex w-full flex-col gap-3">
+        <div className="flex items-center justify-between gap-4">
+          <p className="typography-body2 text-text-g-contrast-medium">
+            Simulated first fetch (~1.2s) with{" "}
+            <code className="typography-mono">loading</code> + empty{" "}
+            <code className="typography-mono">data</code>, then infinite scroll
+            loads more with{" "}
+            <code className="typography-mono">fetchingMore</code>. Click{" "}
+            <span className="typography-mono">Scroll to last row</span> to jump
+            + highlight.
+          </p>
+          <Button
+            size="sm"
+            variant="outline"
+            onClick={() => {
+              if (!rows.length) return;
+              setHighlightId(rows[rows.length - 1]!.id);
+            }}
+            disabled={!rows.length}
+          >
+            Scroll to last row
+          </Button>
+        </div>
+        <DataTable
+          className="h-[min(380px,50vh)] w-full"
+          columns={projectColumns}
+          data={rows}
+          paginationMode="infinite"
+          loading={loading}
+          fetchMoreData={fetchMoreData}
+          fetchingMore={fetchingMore}
+          highlightRowId={highlightId}
+          striped
+          divided
+        />
+      </div>
+    );
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Performance (expectations + stress demo)
+// ---------------------------------------------------------------------------
+
+/**
+ * **What this library does *not* do:** `DataTable` has **no built-in row
+ * virtualization** — every row in `data` is rendered in the DOM (TanStack
+ * `getRowModel`). Very large `data.length` will cost more paint/layout work.
+ *
+ * **What to use instead:**
+ * - `paginationMode="client"` or `"server"` to cap rows per page
+ * - `paginationMode="infinite"` + `fetchMoreData` and **slice/window data in the parent**
+ * - Or wrap your own virtualizer (e.g. `@tanstack/react-virtual`) if you need
+ *   millions of rows in one scroll view
+ *
+ * This story mounts **800** synthetic rows so you can feel scroll/render cost
+ * in Storybook (dev builds are slower than production).
+ */
+export const PerformanceLargeDataset: StoryObj = {
+  render: () => {
+    const bigData = React.useMemo((): Project[] => {
+      const rowCount = 800;
+      const statuses: Project["status"][] = [
+        "To do",
+        "In Progress",
+        "Completed",
+      ];
+      return Array.from({ length: rowCount }, (_, i) => ({
+        id: `perf-${i}`,
+        name: `Project ${i + 1}`,
+        type: (i % 3 === 0
+          ? "Drone"
+          : i % 3 === 1
+          ? "ROV"
+          : "AUV") as Project["type"],
+        subtype: "Visual inspection",
+        createdDate: "15 Mar 2026",
+        status: statuses[i % 3]!,
+      }));
+    }, []);
+
+    return (
+      <div className="flex w-full flex-col gap-3">
+        <p className="typography-body2 text-text-g-contrast-medium max-w-4xl">
+          <strong>{bigData.length}</strong> rows in{" "}
+          <code className="typography-mono">data</code> — no virtualization.
+          Prefer pagination or infinite + parent-side windowing for production
+          lists.
+        </p>
+        <DataTable
+          className="h-[min(520px,70vh)] w-full"
+          columns={projectColumns}
+          data={bigData}
+          paginationMode="infinite"
+          striped
+          divided
+        />
+      </div>
+    );
+  },
+};
+
+/**
+ * Built-in **`virtualized`** — only a vertical window of rows is mounted; the
+ * rest are represented by spacer rows. Tune **`virtualRowEstimate`** (px) to
+ * match your row height so scroll position stays aligned.
+ *
+ * Limitations: fixed-height assumption; incompatible with **`reorderable`** in
+ * the virtualized path (use non-virtualized mode for drag-reorder).
+ */
+export const WithVirtualizedRows: StoryObj = {
+  render: () => {
+    const bigData = React.useMemo((): Project[] => {
+      const rowCount = 5000;
+      const statuses: Project["status"][] = [
+        "To do",
+        "In Progress",
+        "Completed",
+      ];
+      return Array.from({ length: rowCount }, (_, i) => ({
+        id: `virt-${i}`,
+        name: `Project ${i + 1}`,
+        type: (i % 3 === 0
+          ? "Drone"
+          : i % 3 === 1
+          ? "ROV"
+          : "AUV") as Project["type"],
+        subtype: "Visual inspection",
+        createdDate: "15 Mar 2026",
+        status: statuses[i % 3]!,
+      }));
+    }, []);
+
+    return (
+      <div className="flex w-full flex-col gap-3">
+        <p className="typography-body2 text-text-g-contrast-medium max-w-4xl">
+          <strong>{bigData.length}</strong> rows with{" "}
+          <code className="typography-mono">virtualized</code> — compare scroll
+          smoothness vs{" "}
+          <code className="typography-mono">PerformanceLargeDataset</code> (800
+          rows, no virtualization).
+        </p>
+        <DataTable
+          className="h-[min(520px,70vh)] w-full"
+          columns={projectColumns}
+          data={bigData}
+          paginationMode="infinite"
+          virtualized
+          virtualRowEstimate={52}
+          striped
+          divided
+        />
+      </div>
+    );
+  },
+};
+
+// ---------------------------------------------------------------------------
+// 3. Selection
+// ---------------------------------------------------------------------------
+
+/** Checkbox selection — header checkbox selects all; row checkboxes select individually. */
+export const WithSelection: StoryObj = {
+  render: () => {
+    const [selected, setSelected] = React.useState<Record<string, boolean>>({});
+    return (
+      <div className="flex flex-col gap-3 w-full h-full">
+        <p className="typography-small2 text-text-g-contrast-high px-1">
+          Selected IDs:{" "}
+          {Object.keys(selected)
+            .filter((k) => selected[k])
+            .join(", ") || "–"}
+        </p>
+        <DataTable
+          columns={projectColumns}
+          data={projectData}
+          selectable
+          onRowSelectionChange={setSelected}
+          striped
+          divided
+        />
+      </div>
+    );
+  },
+};
+
+/**
+ * Row highlight + scroll — use `highlightRowId` to visually mark important rows
+ * (uses the same token as selected rows) and automatically scroll them into view.
+ */
+export const WithRowHighlightAndScroll: StoryObj = {
+  render: () => {
+    const rowsForDemo = React.useMemo(() => projectDataCopies(4), []);
+    const [highlightIds, setHighlightIds] = React.useState<string[]>([]);
+
+    const toggleId = (id: string) => {
+      setHighlightIds((prev) =>
+        prev.includes(id) ? prev.filter((x) => x !== id) : [...prev, id],
+      );
+    };
+
+    const scrollToFirst = () => {
+      if (!highlightIds.length) return;
+      // Re-setting the same array instance won't re-run the effect; nudge it.
+      setHighlightIds((prev) => [...prev]);
     };
 
-    const data = new Array(20).fill(0).map((__, i) => ({
-      id: "m5gr84i9",
-      amount: i + 1,
-      status: "success",
-      email: "ken99@yahoo.com",
-      email1: "ken99@yahoo.com",
-      email2: "ken99@yahoo.com",
-      email3: "ken99@yahoo.com",
-    }));
+    return (
+      <div className="flex w-full flex-col gap-4">
+        <div className="flex flex-wrap items-center gap-3">
+          <p className="typography-body2 text-text-g-contrast-medium">
+            Click IDs to highlight rows (uses{" "}
+            <code className="typography-mono">highlightRowId</code> +
+            scroll-into-view). Highlight shares the selected token but with a
+            softer overlay + outline.
+          </p>
+          <div className="flex flex-wrap items-center gap-2">
+            {rowsForDemo.map((row) => {
+              const active = highlightIds.includes(row.id);
+              return (
+                <Button
+                  key={row.id}
+                  size="sm"
+                  variant={active ? "solid" : "outline"}
+                  color={active ? "primary" : "secondary"}
+                  onClick={() => toggleId(row.id)}
+                >
+                  #{row.id}
+                </Button>
+              );
+            })}
+            <Button
+              size="sm"
+              variant="text"
+              onClick={() => setHighlightIds([])}
+            >
+              Clear
+            </Button>
+            <Button
+              size="sm"
+              variant="outline"
+              onClick={scrollToFirst}
+              disabled={!highlightIds.length}
+            >
+              Scroll to first
+            </Button>
+          </div>
+        </div>
+        <DataTable
+          className="h-[320px] w-full"
+          columns={[{ accessorKey: "id", header: "ID" }, ...projectColumns]}
+          data={rowsForDemo}
+          highlightRowId={highlightIds}
+          striped
+          divided
+          scrollToHighlightOnMouseLeave
+        />
+      </div>
+    );
+  },
+};
+
+/**
+ * Censor-style list — large, virtualized table where `highlightRowId` moves
+ * automatically over time (e.g. matching the latest event / time).
+ */
+export const WithVirtualizedCensorTimeline: StoryObj = {
+  render: () => {
+    type CensorRow = Project & { time: string };
+
+    const rows: CensorRow[] = React.useMemo(() => {
+      const base: CensorRow[] = [];
+      const now = Date.now();
+      for (let i = 0; i < 2000; i += 1) {
+        const t = new Date(now + i * 60_000);
+        const hh = t.getHours().toString().padStart(2, "0");
+        const mm = t.getMinutes().toString().padStart(2, "0");
+        const status: Project["status"] =
+          i % 3 === 0 ? "To do" : i % 3 === 1 ? "In Progress" : "Completed";
+        base.push({
+          id: `censor-${i}`,
+          name: `Censor task #${i + 1}`,
+          type: (i % 3 === 0
+            ? "Drone"
+            : i % 3 === 1
+            ? "ROV"
+            : "AUV") as Project["type"],
+          subtype: "Automated check",
+          createdDate: `${hh}:${mm}`,
+          status,
+          time: `${hh}:${mm}`,
+        });
+      }
+      return base;
+    }, []);
+
+    const [activeId, setActiveId] = React.useState<string | null>(
+      rows[0]?.id ?? null,
+    );
+
+    React.useEffect(() => {
+      if (!rows.length) return undefined;
+      let index = 0;
+      const handle = setInterval(() => {
+        index = (index + 1) % rows.length;
+        setActiveId(rows[index]!.id);
+      }, 500);
+      return () => clearInterval(handle);
+    }, [rows]);
+
+    const censorColumns: ColumnDef<CensorRow>[] = React.useMemo(
+      () =>
+        [
+          { accessorKey: "time", header: "Time" },
+          ...projectColumns,
+        ] as ColumnDef<CensorRow>[],
+      [],
+    );
+
+    return (
+      <div className="flex w-full flex-col gap-3">
+        <p className="typography-body2 text-text-g-contrast-medium max-w-4xl">
+          Virtualized censor list (~{rows.length} rows). The active row moves
+          every 0.5s via <code className="typography-mono">highlightRowId</code>{" "}
+          to simulate matching incoming events over time.
+        </p>
+        <DataTable
+          className="h-[min(480px,70vh)] w-full"
+          columns={censorColumns}
+          data={rows}
+          paginationMode="infinite"
+          virtualized
+          virtualRowEstimate={52}
+          highlightRowId={activeId ?? undefined}
+          striped
+          divided
+          scrollToHighlightOnMouseLeave
+        />
+      </div>
+    );
+  },
+};
+
+// ---------------------------------------------------------------------------
+// 4. Row actions
+// ---------------------------------------------------------------------------
+
+/** Fixed actions column at the far right — rendered via `rowActions` prop. */
+export const WithRowActions: StoryObj = {
+  render: () => (
+    <DataTable
+      columns={projectColumns}
+      data={projectData}
+      striped
+      divided
+      rowActions={(row) => <ProjectRowActions row={row} />}
+    />
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// 5. Expandable rows
+// ---------------------------------------------------------------------------
+
+/**
+ * Uncontrolled tree rows — `defaultExpanded={true}` opens all nodes on mount.
+ * The user can collapse/expand rows freely; state is managed internally.
+ */
+export const WithExpandableRows: StoryObj = {
+  render: () => (
+    <DataTable
+      columns={eventColumns}
+      data={eventData}
+      getSubRows={(row) => row.children}
+      striped
+      divided
+      defaultExpanded
+      rowActions={(row: Row<EventRow>) => (
+        <ActionButton
+          variant="icon"
+          size="sm"
+          onClick={() => console.log("menu", row.original)}
+          aria-label="More options"
+        >
+          <EllipsisVertical />
+        </ActionButton>
+      )}
+    />
+  ),
+};
+
+/**
+ * Controlled expand — the caller owns `expanded` state via `expanded` +
+ * `onExpandedChange`. Collapsing a row in the table calls `onExpandedChange`;
+ * if the parent doesn't update the state, the row "springs back" open.
+ */
+export const WithControlledExpand: StoryObj = {
+  render: () => {
+    const allIds = React.useMemo(
+      () =>
+        eventData.reduce<Record<string, boolean>>((acc, row) => {
+          acc[row.id] = true;
+          row.children?.forEach((c) => {
+            acc[c.id] = true;
+          });
+          return acc;
+        }, {}),
+      [],
+    );
+    const [expanded, setExpanded] = React.useState<Record<string, boolean>>({});
+    const allExpanded = Object.keys(allIds).every((id) => expanded[id]);
+    return (
+      <div className="flex flex-col gap-3 w-full h-full">
+        <div className="flex items-center gap-2 px-1">
+          <button
+            type="button"
+            className="px-3 py-1 rounded border border-white/20 typography-body3 text-text-contrast-max hover:bg-white/5"
+            onClick={() => setExpanded(allExpanded ? {} : { ...allIds })}
+          >
+            {allExpanded ? "Collapse all" : "Expand all"}
+          </button>
+          <span className="typography-small2 text-text-g-contrast-medium">
+            Expanded: {Object.keys(expanded).join(", ") || "–"}
+          </span>
+        </div>
+        <DataTable
+          columns={eventColumns}
+          data={eventData}
+          getSubRows={(row) => row.children}
+          striped
+          divided
+          expanded={expanded}
+          onExpandedChange={(next) =>
+            setExpanded(next as Record<string, boolean>)
+          }
+        />
+      </div>
+    );
+  },
+};
+
+// ---------------------------------------------------------------------------
+// 6. Column management
+// ---------------------------------------------------------------------------
+
+/**
+ * Column management panel — click ⋮ on any column header.
+ *  - Toggle per-column visibility with the Switch
+ *  - "Hide all" hides everything except one column
+ *  - "Show all" restores all columns
+ *  - Drag the ⠿ grip to reorder columns
+ */
+export const WithColumnManagement: StoryObj = {
+  render: () => (
+    <DataTable
+      columns={inspectionColumns}
+      data={inspectionData}
+      striped
+      divided
+      columnManagement
+      paginationMode="client"
+      pageSizeOptions={[5, 10]}
+    />
+  ),
+};
+
+/**
+ * Column management with restricted options:
+ *  - `reorder: false` — drag handle hidden, column order is fixed
+ *  - `hideAll: false` — "Hide all" button removed
+ *
+ * Pass any subset of `ColumnManagementOptions` to tailor the panel.
+ */
+export const WithColumnManagementOptions: StoryObj = {
+  render: () => (
+    <DataTable
+      columns={inspectionColumns}
+      data={inspectionData}
+      striped
+      divided
+      columnManagement={{ reorder: false, hideAll: false }}
+      paginationMode="client"
+      pageSizeOptions={[5, 10]}
+    />
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// 7. Column resize
+// ---------------------------------------------------------------------------
+
+/**
+ * Resizable columns — drag the right edge of any column header.
+ *
+ * Global bounds via `columnMinSize` / `columnMaxSize`.
+ * Per-column overrides in the column def (`minSize`, `maxSize`):
+ *  - "Asset name": `minSize: 120`
+ *  - "KPI (%)": `maxSize: 160`
+ */
+export const WithColumnResize: StoryObj = {
+  render: () => (
+    <DataTable
+      columns={
+        [
+          { accessorKey: "code", header: "Code", size: 100 },
+          { accessorKey: "assetName", header: "Asset name", minSize: 120 },
+          { accessorKey: "type", header: "Type", size: 90 },
+          { accessorKey: "subtype", header: "Subtype" },
+          {
+            accessorKey: "severity",
+            header: "Severity",
+            size: 120,
+            cell: ({ row }: { row: Row<InspectionRow> }) => (
+              <span
+                className={`inline-flex items-center px-2 py-0.5 rounded-lg typography-small2 ${
+                  severityCls[row.original.severity]
+                }`}
+              >
+                {row.original.severity}
+              </span>
+            ),
+          },
+          { accessorKey: "inspector", header: "Inspector" },
+          { accessorKey: "location", header: "Location", size: 100 },
+          { accessorKey: "capturedAt", header: "Captured date", size: 140 },
+          {
+            accessorKey: "status",
+            header: "Status",
+            size: 130,
+            cell: ({ row }: { row: Row<InspectionRow> }) => (
+              <span
+                className={`inline-flex items-center px-3 py-1 rounded-lg typography-body3 ${
+                  inspectionStatusCls[row.original.status]
+                }`}
+              >
+                {row.original.status}
+              </span>
+            ),
+          },
+          { accessorKey: "kpi", header: "KPI (%)", size: 90, maxSize: 160 },
+          { accessorKey: "notes", header: "Notes" },
+        ] as ColumnDef<InspectionRow>[]
+      }
+      data={inspectionData}
+      striped
+      divided
+      resizable
+      columnMinSize={60}
+      columnMaxSize={400}
+      paginationMode="client"
+      pageSizeOptions={[5, 10]}
+    />
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// 8. Kitchen Sink
+// ---------------------------------------------------------------------------
+
+/**
+ * All features combined:
+ *  - Checkbox selection
+ *  - Sortable columns
+ *  - Client-side pagination
+ *  - Column management (visibility + reorder)
+ *  - Column resize
+ *  - Row actions
+ */
+export const KitchenSink: StoryObj = {
+  render: () => {
+    const [selected, setSelected] = React.useState<Record<string, boolean>>({});
+    return (
+      <DataTable
+        columns={inspectionColumns}
+        data={[...inspectionData, ...inspectionData]}
+        paginationMode="client"
+        pageSizeOptions={[5, 10]}
+        selectable
+        onRowSelectionChange={setSelected}
+        striped
+        divided
+        resizable
+        columnMinSize={60}
+        columnManagement
+        onSorting={(s) => console.log("sort", s)}
+        rowActions={(row: Row<InspectionRow>) => (
+          <>
+            <ActionButton
+              variant="icon"
+              size="sm"
+              onClick={() => console.log("menu", row.original)}
+              aria-label="More options"
+            >
+              <EllipsisVertical />
+            </ActionButton>
+            <ActionButton
+              variant="icon"
+              size="sm"
+              onClick={() => console.log("open", row.original)}
+              aria-label="Open"
+            >
+              <ChevronRight />
+            </ActionButton>
+          </>
+        )}
+      />
+    );
+  },
+};
+
+// ---------------------------------------------------------------------------
+// 9. Row reorder
+// ---------------------------------------------------------------------------
+
+/**
+ * Drag-to-reorder rows — a grip handle is prepended automatically.
+ * `onRowReorder` fires with the new data array after a drop.
+ */
+export const WithRowReorder: StoryObj = {
+  render: () => {
+    const [rows, setRows] = React.useState(projectData);
+    return (
+      <div className="flex flex-col gap-3 w-full h-full">
+        <p className="typography-small2 text-text-g-contrast-high px-1">
+          Order:{" "}
+          <span className="text-text-contrast-max font-medium">
+            {rows.map((r) => r.name.split(" ")[0]).join(", ")}
+          </span>
+        </p>
+        <DataTable
+          tableLayout="fixed"
+          columns={projectColumns}
+          data={rows}
+          divided
+          reorderable
+          onRowReorder={setRows}
+        />
+      </div>
+    );
+  },
+};
+
+// ---------------------------------------------------------------------------
+// 10. Row & cell click
+// ---------------------------------------------------------------------------
+
+/** Row click — clicking any row fires `onRowClick`. Rows show `cursor-pointer`. */
+export const WithRowClick: StoryObj = {
+  render: () => {
+    const [clicked, setClicked] = React.useState<string | null>(null);
+    return (
+      <div className="flex flex-col gap-3 w-full h-full">
+        <p className="typography-small2 text-text-g-contrast-high px-1">
+          Last clicked row:{" "}
+          <span className="text-text-contrast-max font-medium">
+            {clicked ?? "–"}
+          </span>
+        </p>
+        <DataTable
+          columns={projectColumns}
+          data={projectData}
+          striped
+          divided
+          onRowClick={(row) =>
+            setClicked(`${row.original.name} (id: ${row.original.id})`)
+          }
+        />
+      </div>
+    );
+  },
+};
+
+/**
+ * Cell click — `onCellClick` fires for individual cells.
+ * Use `event.stopPropagation()` to prevent `onRowClick` from also firing.
+ */
+export const WithCellClick: StoryObj = {
+  render: () => {
+    const [info, setInfo] = React.useState<{
+      column: string;
+      value: string;
+    } | null>(null);
+    return (
+      <div className="flex flex-col gap-3 w-full h-full">
+        <p className="typography-small2 text-text-g-contrast-high px-1">
+          Last clicked cell:{" "}
+          <span className="text-text-contrast-max font-medium">
+            {info ? `[${info.column}] ${info.value}` : "–"}
+          </span>
+        </p>
+        <DataTable
+          columns={projectColumns}
+          data={projectData}
+          striped
+          divided
+          onRowClick={(row) => console.log("row", row.original.id)}
+          onCellClick={(cell, _row, e) => {
+            e.stopPropagation();
+            setInfo({
+              column: cell.column.id,
+              value: String(cell.getValue() ?? ""),
+            });
+          }}
+        />
+      </div>
+    );
+  },
+};
+
+// ---------------------------------------------------------------------------
+// 11. Sort indicator visibility
+// ---------------------------------------------------------------------------
+
+/**
+ * Sort indicator always visible — `sortIndicatorVisibility="always"` shows the
+ * sort icon on every sortable column, not just on hover.
+ */
+export const SortIndicatorAlwaysVisible: StoryObj = {
+  render: () => (
+    <DataTable
+      columns={projectColumns}
+      data={projectData}
+      striped
+      divided
+      sortIndicatorVisibility="always"
+      onSorting={(s) => console.log("sort", s)}
+    />
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// 12. Table layout comparison
+// ---------------------------------------------------------------------------
+
+/* prettier-ignore */
+const layoutCompareColumns: ColumnDef<Project>[] = [
+  { accessorKey: "name",        header: "Project name", size: 280 },
+  { accessorKey: "type",        header: "Type",         size: 100 },
+  { accessorKey: "subtype",     header: "Subtype" },
+  { accessorKey: "createdDate", header: "Created date", size: 140 },
+  { accessorKey: "status",      header: "Status",       size: 130, cell: ({ row }) => <StatusBadge status={row.original.status} /> },
+];
+
+/**
+ * Side-by-side comparison of `tableLayout="auto"` vs `"fixed"` vs `"equal"`.
+ *
+ * - **auto** — browser distributes width based on cell content; `size` is ignored.
+ * - **fixed** — `size` is used as px per column; the last non-exact column grows
+ *   so the table stays full-width (here: Status absorbs the remainder).
+ * - **equal** — all columns without `meta.exactWidth` share the remaining width equally.
+ *   With `resizable`, drag handles are off for this row so equal widths are preserved.
+ */
+export const TableLayoutComparison: StoryObj = {
+  render: () => (
+    <div className="flex flex-col gap-8 w-full h-full">
+      <div className="flex flex-col gap-2 flex-1 min-h-0">
+        <p className="typography-subtitle1 text-text-contrast-max px-1">
+          tableLayout=&quot;auto&quot;{" "}
+          <span className="typography-small2 text-text-g-contrast-medium">
+            — browser decides widths from content (size ignored)
+          </span>
+        </p>
+        <DataTable
+          columns={layoutCompareColumns}
+          data={projectData}
+          striped
+          divided
+          selectable
+          resizable={false}
+          tableLayout="auto"
+        />
+      </div>
+
+      <div className="flex flex-col gap-2 flex-1 min-h-0">
+        <p className="typography-subtitle1 text-text-contrast-max px-1">
+          tableLayout=&quot;fixed&quot;{" "}
+          <span className="typography-small2 text-text-g-contrast-medium">
+            — columns honour size (280 / 100 / default / 140 / 130)
+          </span>
+        </p>
+        <DataTable
+          columns={layoutCompareColumns}
+          data={projectData}
+          striped
+          divided
+          selectable
+          resizable={false}
+          tableLayout="fixed"
+        />
+      </div>
+
+      <div className="flex flex-col gap-2 flex-1 min-h-0">
+        <p className="typography-subtitle1 text-text-contrast-max px-1">
+          tableLayout=&quot;equal&quot;{" "}
+          <span className="typography-small2 text-text-g-contrast-medium">
+            — non-exactWidth columns share remaining space equally
+          </span>
+        </p>
+        <DataTable
+          columns={layoutCompareColumns}
+          data={projectData}
+          striped
+          divided
+          selectable
+          resizable={false}
+          tableLayout="equal"
+        />
+      </div>
+    </div>
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// 13. Custom row & cell className
+// ---------------------------------------------------------------------------
+
+/**
+ * `rowClassName` and `cellClassName` let you style individual rows and cells
+ * based on their data.
+ *
+ * - Rows with status **"Completed"** get a green-tinted background.
+ * - Rows with status **"To do"** get a subtle white/opacity background.
+ * - The **"Status"** column cells are bold.
+ * - The **"Type"** cells for ROV are highlighted with an info tint.
+ */
+export const WithCustomRowAndCellClassName: StoryObj = {
+  render: () => (
+    <DataTable
+      columns={projectColumns}
+      data={projectData}
+      divided
+      rowClassName={(row) => {
+        if (row.original.status === "Completed") return "!bg-success-500/10";
+        if (row.original.status === "To do") return "!bg-white/5";
+        return undefined;
+      }}
+      cellClassName={(cell) => {
+        if (cell.column.id === "status") return "font-semibold";
+        if (cell.column.id === "type" && cell.getValue() === "ROV")
+          return "!bg-info-500/10 text-info-400";
+        return undefined;
+      }}
+    />
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// 13b. Custom body row size and header size
+// ---------------------------------------------------------------------------
+
+/**
+ * Showcase overriding header and body row heights via className props.
+ *
+ * The base `TableHead` uses `h-[44px] typography-body2` and `TableCell`
+ * uses `h-[42px] typography-body3`.
+ *
+ * `cn()` is configured with a custom `typography` class-group so
+ * `tailwind-merge` correctly deduplicates conflicting `typography-*`
+ * utilities (e.g. `typography-small2` replaces `typography-body2`).
+ *
+ * **Note:** `<th>` / `<td>` elements treat `height` as a minimum —
+ * to go smaller than the default, internal content (sort icon, badges)
+ * must also fit. Compact swaps to `typography-small2` (12px) text and
+ * reduces padding to reclaim space.
+ *
+ * Three sizes: **Compact**, **Default**, **Comfortable**.
+ */
+export const CustomRowAndHeaderSize: StoryObj = {
+  render: () => {
+    const compactColumns: ColumnDef<Project>[] = [
+      { accessorKey: "name", header: "Project name" },
+      { accessorKey: "type", header: "Type" },
+      { accessorKey: "subtype", header: "Subtype" },
+      { accessorKey: "createdDate", header: "Created date" },
+      {
+        accessorKey: "status",
+        header: "Status",
+        cell: ({ row }) => (
+          <span
+            className={`inline-flex items-center px-2 py-0.5 rounded typography-small2 ${
+              statusCls[row.original.status]
+            }`}
+          >
+            {row.original.status}
+          </span>
+        ),
+      },
+    ];
+
+    return (
+      <div className="flex flex-col gap-8 h-full">
+        <div className="flex flex-col gap-2 flex-1 min-h-0">
+          <p className="typography-subtitle1 text-text-contrast-max px-1">
+            Compact{" "}
+            <span className="typography-small2 text-text-g-contrast-medium">
+              — Header 32px · Row 28px · typography-small2 (12px)
+            </span>
+          </p>
+          <DataTable
+            columns={compactColumns}
+            data={projectData}
+            striped
+            divided
+            headerCellClassName="h-[32px] typography-small2"
+            cellClassName="h-[28px] typography-small2"
+            onSorting={(s) => console.log("sort", s)}
+          />
+        </div>
+
+        <div className="flex flex-col gap-2 flex-1 min-h-0">
+          <p className="typography-subtitle1 text-text-contrast-max px-1">
+            Default{" "}
+            <span className="typography-small2 text-text-g-contrast-medium">
+              — Header 44px · Row 42px · typography-body2 / body3
+            </span>
+          </p>
+          <DataTable
+            columns={projectColumns}
+            data={projectData}
+            striped
+            divided
+            onSorting={(s) => console.log("sort", s)}
+          />
+        </div>
+
+        <div className="flex flex-col gap-2 flex-1 min-h-0">
+          <p className="typography-subtitle1 text-text-contrast-max px-1">
+            Comfortable{" "}
+            <span className="typography-small2 text-text-g-contrast-medium">
+              — Header 56px · Row 50px · typography-subtitle2 / subtitle4 (16px
+              / 14px)
+            </span>
+          </p>
+          <DataTable
+            columns={projectColumns}
+            data={projectData}
+            striped
+            divided
+            headerCellClassName="h-[56px] typography-subtitle2"
+            cellClassName="h-[50px] typography-subtitle4"
+            onSorting={(s) => console.log("sort", s)}
+          />
+        </div>
+      </div>
+    );
+  },
+};
+
+// ---------------------------------------------------------------------------
+// 14. Real-world example — Data Management (Figma: Xspector-New → Data management)
+// ---------------------------------------------------------------------------
+//
+// Matches the “add row” pattern: `meta.colSpan` merges “Default value” + action
+// into one `<td>` with “Add option” + primary Add (see DataTable `ColumnMeta.colSpan`).
+//
+
+type DataManagementRow = {
+  id: string;
+  /** Footer row — inputs + merged default/actions cell; not draggable. */
+  kind?: "add";
+  columnName: string;
+  dataCategory: string;
+  dataType: string;
+  format: string;
+  source: string;
+  defaultValue: string;
+};
+
+type DmEditTrigger = "click" | "doubleClick";
+type DmEditScope = "row" | "cell";
+
+const DM_DATA_CATEGORY_LABELS = [
+  "Sequence",
+  "Date",
+  "Multiple choice",
+  "KP",
+  "Data",
+] as const;
+
+const DM_DATA_TYPES_BY_CATEGORY: Record<string, string[]> = {
+  Sequence: ["Integer", "Text"],
+  Date: ["Text"],
+  "Multiple choice": ["Text"],
+  KP: ["Decimals", "Text"],
+  Data: ["Text", "Integer", "Decimals"],
+};
+
+const DM_FORMAT_BY_DATA_TYPE: Record<string, string[]> = {
+  Integer: ["-", "0", "Grouped"],
+  Text: ["-", "dd/mm/yyyy"],
+  Decimals: ["-", "5", "2"],
+  Date: ["-", "ISO"],
+};
+
+const DM_SOURCE_LABELS = ["-", "Q6", "Manual"];
+
+function dmDepsParentsReady(o: DataManagementRow) {
+  return o.columnName.trim().length > 0 && o.dataCategory.trim().length > 0;
+}
+
+function dmDepsDataTypePicked(o: DataManagementRow) {
+  return o.dataType.trim().length > 0;
+}
+
+function dmDepsFormatPicked(o: DataManagementRow) {
+  return o.format.trim().length > 0;
+}
+
+function dmOptionsFromLabels(
+  placeholderLabel: string,
+  labels: readonly string[] | string[],
+): Options[] {
+  return [
+    { value: `__ph__:${placeholderLabel}`, label: placeholderLabel },
+    ...Array.from(labels).map((l) => ({ value: l, label: l })),
+  ];
+}
+
+const dmAddRow: DataManagementRow = {
+  id: "__dm_add__",
+  kind: "add",
+  columnName: "",
+  dataCategory: "",
+  dataType: "",
+  format: "",
+  source: "",
+  defaultValue: "",
+};
+
+function isDmAddRow(row: Row<DataManagementRow>) {
+  return row.original.kind === "add" || row.id === "__dm_add__";
+}
+
+/* prettier-ignore */
+const dmData: DataManagementRow[] = [
+  { id: "1", columnName: "Sequence",  dataCategory: "Sequence",        dataType: "Integer", format: "-", source: "-", defaultValue: "-" },
+  { id: "2", columnName: "Date",      dataCategory: "Date",            dataType: "Text",    format: "dd/mm/yyyy", source: "Q6", defaultValue: "-" },
+  { id: "3", columnName: "Anomaly",   dataCategory: "Multiple choice", dataType: "Text",    format: "-", source: "-", defaultValue: "2 options" },
+  { id: "4", columnName: "Data",      dataCategory: "KP",              dataType: "Decimals", format: "5", source: "Q6", defaultValue: "-" },
+  { id: "5", columnName: "Data",      dataCategory: "Data",            dataType: "Text",    format: "-", source: "-", defaultValue: "-" },
+  { id: "6", columnName: "Data",      dataCategory: "Data",            dataType: "Text",    format: "-", source: "-", defaultValue: "-" },
+  { id: "7", columnName: "Data",      dataCategory: "Data",            dataType: "Text",    format: "-", source: "-", defaultValue: "-" },
+  { id: "8", columnName: "Data",      dataCategory: "Data",            dataType: "Text",    format: "-", source: "-", defaultValue: "-" },
+  { id: "9", columnName: "Data",      dataCategory: "Data",            dataType: "Text",    format: "-", source: "-", defaultValue: "-" },
+];
+
+const DmToolbar = ({ count }: { count: number }) => (
+  <div className="flex flex-wrap items-center gap-3">
+    <div className="flex min-w-0 flex-1 items-center gap-2">
+      <span className="typography-h6 text-text-contrast-max">
+        Data management
+      </span>
+      <span className="typography-subtitle1 text-text-contrast-max">
+        ({count})
+      </span>
+    </div>
+    <button
+      type="button"
+      className="flex items-center gap-1.5 rounded-md border border-state-primary-stroke px-3 py-1 typography-button-ms text-state-primary-text-outline"
+    >
+      <FileDown className="size-4 shrink-0 opacity-90" aria-hidden />
+      Import file
+    </button>
+    <button
+      type="button"
+      className="flex items-center gap-1.5 rounded-md border border-state-primary-stroke px-3 py-1 typography-button-ms text-state-primary-text-outline"
+    >
+      <FileUp className="size-4 shrink-0 opacity-90" aria-hidden />
+      Export file
+    </button>
+    <button
+      type="button"
+      className="flex items-center gap-1.5 rounded-md bg-state-primary-default px-3 py-1 typography-button-ms text-state-primary-text-solid"
+    >
+      Save changes
+    </button>
+  </div>
+);
+
+const dashPreview = (value: string) =>
+  !value || value === "-" ? (
+    <span className="text-text-g-contrast-medium">-</span>
+  ) : (
+    <span>{value}</span>
+  );
+
+const dmColumns: EditableColumnDef<DataManagementRow>[] = [
+  {
+    id: "#",
+    header: () => null,
+    cell: ({ row }) => (
+      <span className="typography-small2 text-text-g-contrast-medium">
+        {row.index + 1}
+      </span>
+    ),
+    enableSorting: false,
+    enableHiding: false,
+    enableResizing: false,
+    size: 50,
+    maxSize: 50,
+    minSize: 50,
+    meta: { align: "center", exactWidth: 50 },
+  },
+  {
+    accessorKey: "columnName",
+    header: "Column name",
+    size: 200,
+    enableEditing: true,
+    editVariant: "text",
+    editTextProps: { placeholder: "Column name" },
+    onCommit: (_row, v) => ({
+      columnName: v,
+      dataType: "",
+      format: "",
+      source: "",
+    }),
+  },
+  {
+    accessorKey: "dataCategory",
+    header: "Data Category",
+    size: 200,
+    enableEditing: true,
+    editVariant: "select",
+    editSelectProps: {
+      options: () =>
+        dmOptionsFromLabels("Data Category", DM_DATA_CATEGORY_LABELS),
+      placeholder: "Data Category",
+    },
+    onCommit: (_row, v) => ({
+      dataCategory: v,
+      dataType: "",
+      format: "",
+      source: "",
+    }),
+  },
+  {
+    accessorKey: "dataType",
+    header: "Data type",
+    size: 150,
+    enableEditing: (row) => dmDepsParentsReady(row.original),
+    editVariant: "select",
+    // editShowDisabledField: true,
+    editSelectProps: {
+      options: (row) =>
+        dmOptionsFromLabels(
+          "Data type",
+          DM_DATA_TYPES_BY_CATEGORY[row.original.dataCategory] ?? ["Text"],
+        ),
+      placeholder: "Data type",
+    },
+    onCommit: (_row, v) => ({
+      dataType: v,
+      format: "",
+      source: "",
+    }),
+    displayCell: (row) => dashPreview(row.original.dataType),
+  },
+  {
+    accessorKey: "format",
+    header: "Format",
+    size: 150,
+    enableEditing: (row) =>
+      dmDepsParentsReady(row.original) && dmDepsDataTypePicked(row.original),
+    editVariant: "select",
+    // editShowDisabledField: true,
+    editSelectProps: {
+      options: (row) =>
+        dmOptionsFromLabels(
+          "Format",
+          DM_FORMAT_BY_DATA_TYPE[row.original.dataType] ?? ["-"],
+        ),
+      placeholder: "Format",
+    },
+    onCommit: (_row, v) => ({ format: v, source: "" }),
+    displayCell: (row) => dashPreview(row.original.format),
+  },
+  {
+    accessorKey: "source",
+    header: "Source",
+    size: 150,
+    enableEditing: (row) =>
+      dmDepsParentsReady(row.original) &&
+      dmDepsDataTypePicked(row.original) &&
+      dmDepsFormatPicked(row.original),
+    editVariant: "select",
+    // editShowDisabledField: true,
+    editSelectProps: {
+      options: () => dmOptionsFromLabels("Source", DM_SOURCE_LABELS),
+      placeholder: "Source",
+    },
+    displayCell: (row) => dashPreview(row.original.source),
+  },
+  {
+    accessorKey: "defaultValue",
+    header: "Default value",
+    size: 200,
+    enableSorting: false,
+    enableEditing: true,
+    editVariant: "text",
+    editTextProps: { placeholder: "Default value" },
+    onCommit: (_row, v) => ({ defaultValue: v || "-" }),
+    displayCell: (row) => {
+      const v = row.original.defaultValue;
+      return v === "-" ? (
+        <span className="text-text-g-contrast-medium">-</span>
+      ) : (
+        <button
+          type="button"
+          className="typography-button-ms text-state-secondary-text-outline"
+        >
+          {v}
+        </button>
+      );
+    },
+  },
+  {
+    id: "__actions__",
+    accessorFn: (row) => row.id,
+    header: () => null,
+    cell: ({ row }) =>
+      isDmAddRow(row) ? (
+        <Button size="sm" variant="solid" color="primary">
+          Add
+        </Button>
+      ) : (
+        <ActionButton
+          variant="icon"
+          size="sm"
+          aria-label="Delete row"
+          onClick={() => console.log("delete", row.original.id)}
+        >
+          <Trash2 className="size-4" />
+        </ActionButton>
+      ),
+    enableSorting: false,
+    enableHiding: false,
+    enableResizing: false,
+    size: 100,
+    maxSize: 100,
+    minSize: 100,
+    meta: { exactWidth: 100, align: "center" },
+  },
+];
+
+/**
+ * Data management table — Figma **Xspector-New**:
+ * [full frame](https://www.figma.com/design/99rq6FbfPx6hgPS0VCvHJh/Xspector-New?node-id=11965-17125),
+ * [row / field spec](https://www.figma.com/design/99rq6FbfPx6hgPS0VCvHJh/Xspector-New?node-id=11965-17883).
+ *
+ * Uses the **DataTable editing API** (`enableEditing` + `editDisplayMode` +
+ * `editVariant` per column). Edit scope and trigger are toggleable via the
+ * toolbar at the top of the story.
+ */
+export const DataManagement: StoryObj = {
+  render: () => {
+    const [rows, setRows] = React.useState<DataManagementRow[]>(() => [
+      ...dmData,
+      dmAddRow,
+    ]);
+    const [editScope, setEditScope] = React.useState<DmEditScope>("row");
+    const [editTrigger, setEditTrigger] =
+      React.useState<DmEditTrigger>("click");
+
+    const dataRowCount = rows.filter(
+      (r) => r.kind !== "add" && r.id !== "__dm_add__",
+    ).length;
 
     return (
-      <div className="flex flex-1 h-full flex-row gap-4 w-full">
+      <div
+        data-surface="panel"
+        className="flex h-full min-h-0 w-full max-w-7xl flex-col gap-6 self-center rounded-xl bg-modal-surface p-8 shadow-[0px_12px_24px_-4px_rgba(0,0,0,0.12)]"
+      >
+        <DmToolbar count={dataRowCount} />
+        <div className="flex flex-wrap items-center gap-4 rounded-lg border border-table-c-col-line bg-table-c-header-bg px-4 py-3">
+          <span className="typography-small2 text-text-g-contrast-medium">
+            Cell edit demo
+          </span>
+          <label className="flex cursor-pointer items-center gap-2 typography-small2 text-text-contrast-high">
+            <input
+              type="radio"
+              name="dm-scope"
+              checked={editScope === "row"}
+              onChange={() => setEditScope("row")}
+            />
+            Whole row
+          </label>
+          <label className="flex cursor-pointer items-center gap-2 typography-small2 text-text-contrast-high">
+            <input
+              type="radio"
+              name="dm-scope"
+              checked={editScope === "cell"}
+              onChange={() => setEditScope("cell")}
+            />
+            Single cell (blur → preview, Tab → next field in row)
+          </label>
+          <span className="mx-2 hidden h-4 w-px bg-table-c-col-line sm:inline-block" />
+          <label className="flex cursor-pointer items-center gap-2 typography-small2 text-text-contrast-high">
+            <input
+              type="radio"
+              name="dm-trig"
+              checked={editTrigger === "click"}
+              onChange={() => setEditTrigger("click")}
+            />
+            Activate on click
+          </label>
+          <label className="flex cursor-pointer items-center gap-2 typography-small2 text-text-contrast-high">
+            <input
+              type="radio"
+              name="dm-trig"
+              checked={editTrigger === "doubleClick"}
+              onChange={() => setEditTrigger("doubleClick")}
+            />
+            Activate on double-click
+          </label>
+        </div>
         <DataTable
-          columns={columns}
-          data={data}
-          onSorting={(sorting) => {
-            console.log("sorting ", sorting);
+          className="min-h-0"
+          columns={dmColumns}
+          data={rows}
+          divided
+          striped={false}
+          surface="panel"
+          tableLayout="equal"
+          reorderable
+          getRowId={(r) => r.id}
+          isRowReorderLocked={(row) => isDmAddRow(row)}
+          onRowReorder={(reordered) => {
+            const add =
+              reordered.find(
+                (r) => r.kind === "add" || r.id === "__dm_add__",
+              ) ?? dmAddRow;
+            const rest = reordered.filter(
+              (r) => r.kind !== "add" && r.id !== "__dm_add__",
+            );
+            setRows([...rest, add]);
           }}
-          fetchMoreData={() => {
-            console.log("fetchMoreData");
+          enableEditing
+          editDisplayMode={editScope}
+          editTrigger={editTrigger}
+          alwaysEditing={(row) => isDmAddRow(row)}
+          onCellCommit={(rowId, _columnId, patch) => {
+            setRows((prev) =>
+              prev.map((r) => (r.id === rowId ? { ...r, ...patch } : r)),
+            );
+          }}
+          headerCellClassName={(header) =>
+            header.column.id === "__reorder__" ? "!border-r-0" : undefined
+          }
+          cellClassName={(cell, row) =>
+            cn(
+              isDmAddRow(row) && "!py-2",
+              cell.column.id === "__reorder__" && "!border-r-0",
+            )
+          }
+        />
+      </div>
+    );
+  },
+};
+
+/** Data Management — empty state when no columns have been configured yet. */
+export const DataManagementEmpty: StoryObj = {
+  render: () => (
+    <div className="flex flex-col gap-6 w-full h-full">
+      <DmToolbar count={0} />
+      <DataTable columns={dmColumns} data={[]} divided />
+    </div>
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// 15. Editing Field Showcase — all variants, error, testId
+// ---------------------------------------------------------------------------
+
+type EditShowcaseRow = {
+  id: string;
+  name: string;
+  category: string;
+  quantity: number;
+  price: number;
+  active: boolean;
+  priority: "critical" | "high" | "medium" | "low" | "none";
+  notes: string;
+};
+
+const CATEGORY_OPTIONS: Options[] = [
+  { value: "electronics", label: "Electronics" },
+  { value: "clothing", label: "Clothing" },
+  { value: "food", label: "Food & Beverage" },
+  { value: "furniture", label: "Furniture" },
+  { value: "other", label: "Other" },
+];
+
+const PRIORITY_OPTIONS: Options[] = [
+  { value: "critical", label: "Critical" },
+  { value: "high", label: "High" },
+  { value: "medium", label: "Medium" },
+  { value: "low", label: "Low" },
+  { value: "none", label: "None" },
+];
+
+const PRIORITY_BADGE_COLOR: Record<string, BadgeColor> = {
+  critical: "error",
+  high: "warning",
+  medium: "info",
+  low: "success",
+  none: "default",
+};
+
+/* prettier-ignore */
+const editShowcaseData: EditShowcaseRow[] = [
+  { id: "1", name: "Laptop Pro 16",    category: "Electronics",    quantity: 25,  price: 1299.99, active: true,  priority: "critical", notes: "Flagship model" },
+  { id: "2", name: "Winter Jacket",    category: "Clothing",       quantity: 100, price: 89.50,   active: true,  priority: "medium",   notes: "" },
+  { id: "3", name: "Organic Coffee",   category: "Food & Beverage",quantity: 500, price: 12.99,   active: false, priority: "low",      notes: "Fair trade certified" },
+  { id: "4", name: "Standing Desk",    category: "Furniture",      quantity: 0,   price: 449.00,  active: true,  priority: "high",     notes: "Adjustable height" },
+  { id: "5", name: "Wireless Mouse",   category: "Electronics",    quantity: 200, price: 29.99,   active: true,  priority: "none",     notes: "" },
+  { id: "6", name: "",                 category: "",               quantity: 0,   price: 0,       active: false, priority: "none",     notes: "Draft item" },
+];
+
+const editShowcaseColumns: EditableColumnDef<EditShowcaseRow>[] = [
+  {
+    id: "#",
+    header: "#",
+    cell: ({ row }) => (
+      <span className="typography-small2 text-text-g-contrast-medium">
+        {row.index + 1}
+      </span>
+    ),
+    enableSorting: false,
+    size: 50,
+    meta: { exactWidth: 50, align: "center" },
+  },
+  {
+    accessorKey: "name",
+    header: "Product name",
+    size: 200,
+    enableEditing: true,
+    editVariant: "text",
+    editTextProps: { placeholder: "Product name" },
+    editError: (row) => {
+      if (!row.original.name.trim()) return "Name is required";
+      if (row.original.name.length < 3) return "Min 3 characters";
+      return undefined;
+    },
+  },
+  {
+    accessorKey: "category",
+    header: "Category",
+    size: 180,
+    enableEditing: true,
+    editVariant: "select",
+    editSelectProps: {
+      options: CATEGORY_OPTIONS,
+      placeholder: "Select category",
+    },
+    editError: (row) => {
+      if (!row.original.category.trim()) return "Category is required";
+      return undefined;
+    },
+  },
+  {
+    accessorKey: "quantity",
+    header: "Quantity",
+    size: 130,
+    enableEditing: true,
+    editVariant: "number",
+    editNumberProps: {
+      placeholder: "Qty",
+      min: 0,
+      max: 99999,
+      step: 1,
+      allowDecimal: false,
+      allowNegative: false,
+    },
+    onCommit: (_row, v) => ({ quantity: Number(v) || 0 }),
+    editError: (row) => {
+      if (row.original.quantity < 0) return "Cannot be negative";
+      return undefined;
+    },
+  },
+  {
+    accessorKey: "price",
+    header: "Price ($)",
+    size: 130,
+    enableEditing: true,
+    editVariant: "number",
+    editNumberProps: {
+      placeholder: "0.00",
+      min: 0,
+      step: 0.01,
+      precision: 2,
+      allowDecimal: true,
+      allowNegative: false,
+    },
+    onCommit: (_row, v) => ({ price: parseFloat(v) || 0 }),
+    displayCell: (row) => (
+      <span className="typography-small2 tabular-nums">
+        ${Number(row.original.price).toFixed(2)}
+      </span>
+    ),
+    editError: (row) => {
+      if (Number(row.original.price) <= 0) return "Price must be > 0";
+      return undefined;
+    },
+  },
+  {
+    accessorKey: "active",
+    header: "Active",
+    size: 100,
+    enableEditing: true,
+    editVariant: "checkbox",
+    editCheckboxProps: { label: "Active" },
+    onCommit: (_row, v) => ({ active: v === "true" }),
+    displayCell: (row) => (
+      <span
+        className={cn(
+          "inline-flex items-center px-2 py-0.5 rounded-lg typography-small2",
+          row.original.active
+            ? "bg-success-500/20 text-success-400"
+            : "bg-transparent-grey2-8 text-text-g-contrast-medium",
+        )}
+      >
+        {row.original.active ? "Yes" : "No"}
+      </span>
+    ),
+  },
+  {
+    accessorKey: "priority",
+    header: "Priority",
+    size: 200,
+    enableEditing: true,
+    editVariant: "custom",
+    editCustomCell: (row, { commit, blur, onKeyDown }) => {
+      const current = row.original.priority;
+      const handleKey = (e: React.KeyboardEvent<HTMLElement>) => {
+        if (e.key === "Escape") {
+          e.preventDefault();
+          blur();
+          return;
+        }
+        onKeyDown?.(e);
+      };
+      return (
+        <div className="flex flex-wrap items-center gap-1">
+          {PRIORITY_OPTIONS.map((opt) => (
+            <button
+              key={opt.value}
+              type="button"
+              className={cn(
+                "rounded-md px-2 py-0.5 typography-small2 border transition-colors",
+                current === opt.value
+                  ? "border-primary-500 bg-primary-500/15 text-primary-400"
+                  : "border-transparent bg-transparent-grey2-8 text-text-g-contrast-medium hover:text-text-contrast-high hover:bg-transparent-grey2-12",
+              )}
+              onClick={() => {
+                commit(opt.value);
+                blur();
+              }}
+              onKeyDown={handleKey}
+            >
+              {opt.label}
+            </button>
+          ))}
+        </div>
+      );
+    },
+    onCommit: (_row, value) => ({
+      priority: (PRIORITY_OPTIONS.find((o) => o.value === value)
+        ? value
+        : "none") as EditShowcaseRow["priority"],
+    }),
+    displayCell: (row) => {
+      const p = row.original.priority;
+      const label = PRIORITY_OPTIONS.find((o) => o.value === p)?.label ?? p;
+      return (
+        <Badge label={label} color={PRIORITY_BADGE_COLOR[p] ?? "default"} />
+      );
+    },
+  },
+  {
+    accessorKey: "notes",
+    header: "Notes",
+    size: 200,
+    enableEditing: true,
+    editVariant: "text",
+    editTextProps: { placeholder: "Add notes…" },
+    displayCell: (row) =>
+      row.original.notes ? (
+        <span>{row.original.notes}</span>
+      ) : (
+        <span className="text-text-g-contrast-medium italic">—</span>
+      ),
+  },
+];
+
+/**
+ * **Editing Field Showcase** — demonstrates every editing feature:
+ *
+ * | Feature | Where |
+ * |---|---|
+ * | `editVariant: "text"` | Product name, Notes |
+ * | `editVariant: "select"` | Category |
+ * | `editVariant: "number"` | Quantity, Price |
+ * | `editVariant: "checkbox"` | Active |
+ * | `editVariant: "custom"` + `editCustomCell` | Priority (inline button picker → Badge display) |
+ * | `editError` | Name (required + min length), Category (required), Price (> 0) |
+ * | `displayCell` | Price (formatted), Active (badge), Notes (italic placeholder) |
+ * | `testId` | Root container has `data-testid="edit-showcase"` |
+ * | Row / Cell mode toggle | Toolbar radio buttons |
+ * | Click / Double-click trigger | Toolbar radio buttons |
+ * | Tab traversal | Tab/Shift+Tab moves between editable fields |
+ */
+export const EditingFieldShowcase: StoryObj = {
+  render: () => {
+    const [rows, setRows] = React.useState<EditShowcaseRow[]>(
+      () => editShowcaseData,
+    );
+    const [editScope, setEditScope] = React.useState<"row" | "cell">("row");
+    const [editTrigger, setEditTrigger] = React.useState<
+      "click" | "doubleClick"
+    >("click");
+
+    return (
+      <div className="flex h-full min-h-0 w-full flex-col gap-4">
+        <div className="flex flex-col gap-2">
+          <h2 className="typography-h6 text-text-contrast-max">
+            Editing Field Showcase
+          </h2>
+          <p className="typography-body3 text-text-g-contrast-medium max-w-3xl">
+            All built-in edit variants: <strong>text</strong>,{" "}
+            <strong>select</strong>, <strong>number</strong>,{" "}
+            <strong>checkbox</strong>, and a <strong>custom</strong> field
+            (Priority — inline button picker). Inline validation errors appear
+            on Name, Category, and Price. Uses{" "}
+            <code className="typography-mono">
+              testId=&quot;edit-showcase&quot;
+            </code>{" "}
+            for automated testing.
+          </p>
+        </div>
+
+        <div className="flex flex-wrap items-center gap-4 rounded-lg border border-table-c-col-line bg-table-c-header-bg px-4 py-3">
+          <span className="typography-small2 text-text-g-contrast-medium font-medium">
+            Edit mode
+          </span>
+          <label className="flex cursor-pointer items-center gap-2 typography-small2 text-text-contrast-high">
+            <input
+              type="radio"
+              name="showcase-scope"
+              checked={editScope === "row"}
+              onChange={() => setEditScope("row")}
+            />
+            Row
+          </label>
+          <label className="flex cursor-pointer items-center gap-2 typography-small2 text-text-contrast-high">
+            <input
+              type="radio"
+              name="showcase-scope"
+              checked={editScope === "cell"}
+              onChange={() => setEditScope("cell")}
+            />
+            Cell
+          </label>
+          <span className="mx-2 hidden h-4 w-px bg-table-c-col-line sm:inline-block" />
+          <span className="typography-small2 text-text-g-contrast-medium font-medium">
+            Trigger
+          </span>
+          <label className="flex cursor-pointer items-center gap-2 typography-small2 text-text-contrast-high">
+            <input
+              type="radio"
+              name="showcase-trig"
+              checked={editTrigger === "click"}
+              onChange={() => setEditTrigger("click")}
+            />
+            Click
+          </label>
+          <label className="flex cursor-pointer items-center gap-2 typography-small2 text-text-contrast-high">
+            <input
+              type="radio"
+              name="showcase-trig"
+              checked={editTrigger === "doubleClick"}
+              onChange={() => setEditTrigger("doubleClick")}
+            />
+            Double-click
+          </label>
+        </div>
+
+        <DataTable
+          testId="edit-showcase"
+          className="min-h-0"
+          columns={editShowcaseColumns}
+          data={rows}
+          divided
+          striped={false}
+          bordered
+          tableLayout="equal"
+          enableEditing
+          editDisplayMode={editScope}
+          editTrigger={editTrigger}
+          onCellCommit={(rowId, _colId, patch) => {
+            setRows((prev) =>
+              prev.map((r) => (r.id === rowId ? { ...r, ...patch } : r)),
+            );
           }}
+          rowActions={(row: Row<EditShowcaseRow>) => (
+            <ActionButton
+              variant="icon"
+              size="sm"
+              aria-label="Delete row"
+              onClick={() =>
+                setRows((prev) => prev.filter((r) => r.id !== row.original.id))
+              }
+            >
+              <Trash2 className="size-4" />
+            </ActionButton>
+          )}
         />
       </div>
     );
   },
-} satisfies StoryObj;
+};