@usetheo/ui 0.20.0 → 0.22.0

package/dist/components/composites/data-table/compare-values.d.ts

@@ -0,0 +1,2 @@
+/** Shared sort comparator for DataTable modes (default + virtualized). */
+export declare function compareValues(a: unknown, b: unknown): number;

package/dist/components/composites/data-table/data-table-loading.d.ts

@@ -0,0 +1,10 @@
+import type { ReactNode } from "react";
+import type { DataTableColumn } from "./data-table.js";
+/** Skeleton state shared by both DataTable modes (extracted — 300-line hook floor). */
+export declare function DataTableLoading<T>(props: {
+    columns: DataTableColumn<T>[];
+    hasExpandColumn: boolean;
+    hasActionsColumn: boolean;
+    stickyHeader: boolean;
+    className?: string;
+}): ReactNode;

package/dist/components/composites/data-table/data-table-parts.d.ts

@@ -0,0 +1,16 @@
+import type { ReactNode } from "react";
+import type { DataTableColumn, DataTableSort } from "./data-table.js";
+/** Header row shared by the default and virtualized DataTable bodies. */
+export declare function DataTableHeaderRow<T>(props: {
+    columns: DataTableColumn<T>[];
+    sort: DataTableSort | null;
+    onSortClick: (columnKey: string) => void;
+    hasExpandColumn?: boolean;
+    hasActionsColumn?: boolean;
+}): ReactNode;
+/** Row-actions dropdown cell shared by both DataTable bodies. */
+export declare function DataTableRowActionsCell(props: {
+    children: ReactNode;
+}): ReactNode;
+/** Renders a body cell's content per column definition (shared by both bodies). */
+export declare function renderCellContent<T>(row: T, col: DataTableColumn<T>): ReactNode;

package/dist/components/composites/data-table/data-table-virtualized.d.ts

@@ -0,0 +1,32 @@
+import type { VirtualizerOptions } from "@tanstack/react-virtual";
+import type { ReactNode } from "react";
+import type { DataTableBaseProps } from "./data-table.js";
+/**
+ * Virtualized body of DataTable — renders 10K+ rows over @tanstack/react-virtual
+ * (blueprint M6, ADR D1/D2 + review fix F-dom-1). Semantic `<table>` preserved
+ * with the SPACER-ROW technique: two fixed-height spacer `<tr>`s grow the
+ * table's real layout box to the full dataset height, so the sticky `<thead>`
+ * keeps its containing block for the whole scroll and the last row stays
+ * reachable — per-row transforms (the official example's pattern) do NOT grow
+ * the layout box and un-stick the header after ~one window.
+ *
+ * Limitations (documented contract — mutually exclusive at the type level):
+ * no pagination, no expandable rows (fixed row heights are required by
+ * estimateSize). Cell content must fit `rowHeight` (cells are clipped with
+ * reduced padding; keep rowHeight >= ~32px). A row-action dropdown unmounts
+ * when its row leaves the overscan window.
+ */
+export interface DataTableVirtualizedOptions {
+    /** Scroll container height (px or CSS length). */
+    height: number | string;
+    /** Fixed row height in px — required by the virtualizer's estimateSize. */
+    rowHeight: number;
+    /** Rows rendered beyond the viewport on each side. @default 5 */
+    overscan?: number;
+    /** @internal test-only — inject virtualizer options (e.g. observeElementRect). */
+    virtualizerOptions?: Partial<VirtualizerOptions<HTMLElement, Element>>;
+}
+export type DataTableVirtualizedBodyProps<T> = Omit<DataTableBaseProps<T>, "stickyHeader"> & {
+    virtualized: DataTableVirtualizedOptions;
+};
+export declare function DataTableVirtualizedBody<T>(props: DataTableVirtualizedBodyProps<T>): ReactNode;

package/dist/components/composites/data-table/data-table.d.ts

@@ -1,4 +1,5 @@
 import type { ReactNode } from "react";
+import type { DataTableVirtualizedOptions } from "./data-table-virtualized.js";
 /**
  * DataTable — generic, sortable, expandable composite over `<Table>`.
  *
@@ -9,6 +10,10 @@ import type { ReactNode } from "react";
  * pagination support controlled OR uncontrolled mode (consumer
  * passes onSortChange / onPageChange to take over state).
  *
+ * `virtualized` mode (M6) renders 10K+ rows over @tanstack/react-virtual.
+ * It is mutually exclusive with `pagination` and `expandable` at the type
+ * level — a virtualized list is one continuous scroll of fixed-height rows.
+ *
  * @example
  *   <DataTable
  *     columns={[
@@ -39,19 +44,12 @@ export interface DataTableSort {
     key: string;
     direction: "asc" | "desc";
 }
-export interface DataTableProps<T> {
+export interface DataTableBaseProps<T> {
     data: T[];
     columns: DataTableColumn<T>[];
     rowKey: (row: T) => string;
     stickyHeader?: boolean;
-    expandable?: (row: T) => ReactNode | null;
-    expandMode?: "single" | "multiple";
     rowActions?: (row: T) => ReactNode;
-    pagination?: {
-        pageSize: number;
-        controlledPage?: number;
-        onPageChange?: (page: number) => void;
-    } | null;
     defaultSort?: DataTableSort;
     sort?: DataTableSort | null;
     onSortChange?: (sort: DataTableSort | null) => void;
@@ -59,5 +57,26 @@ export interface DataTableProps<T> {
     emptyState?: ReactNode;
     className?: string;
 }
+/**
+ * Discriminated union: the default mode keeps pagination/expandable; the
+ * virtualized mode excludes them at the type level (fixed-height single
+ * scroll — see DataTableVirtualizedOptions for the documented limitations).
+ */
+export type DataTableProps<T> = DataTableBaseProps<T> & ({
+    virtualized?: never;
+    expandable?: (row: T) => ReactNode | null;
+    expandMode?: "single" | "multiple";
+    pagination?: {
+        pageSize: number;
+        controlledPage?: number;
+        onPageChange?: (page: number) => void;
+    } | null;
+} | {
+    virtualized: DataTableVirtualizedOptions;
+    expandable?: never;
+    expandMode?: never;
+    pagination?: never;
+    stickyHeader?: never;
+});
 declare function DataTable<T>(props: DataTableProps<T>): ReactNode;
 export { DataTable };

package/dist/components/composites/data-table/index.d.ts

@@ -1 +1,2 @@
 export { DataTable, type DataTableColumn, type DataTableProps, type DataTableSort, } from "./data-table.js";
+export type { DataTableVirtualizedOptions } from "./data-table-virtualized.js";

package/dist/components/composites/data-table/use-data-table-sort.d.ts

@@ -0,0 +1,19 @@
+import type { DataTableColumn, DataTableSort } from "./data-table.js";
+/**
+ * Shared controlled/uncontrolled sort state for both DataTable modes.
+ * Cycle: none → asc → desc → none. Client-side sorting applies only in
+ * uncontrolled mode (controlled consumers pre-sort their data).
+ */
+export declare function useDataTableSort<T>(opts: {
+    data: T[];
+    columns: DataTableColumn<T>[];
+    defaultSort?: DataTableSort;
+    sort?: DataTableSort | null;
+    onSortChange?: (sort: DataTableSort | null) => void;
+    /** Fired on uncontrolled sort change (EC-8: page reset in paginated mode). */
+    onUncontrolledSortChange?: () => void;
+}): {
+    sort: DataTableSort | null;
+    handleSort: (columnKey: string) => void;
+    sortedData: T[];
+};

package/dist/components/primitives/file-dropzone/file-dropzone.d.ts

@@ -0,0 +1,26 @@
+/**
+ * FileDropzone — drag-drop + file-picker primitive, dependency-free (HTML5
+ * DnD). The drag mechanics, the typed-rejection shape and the browser quirks
+ * are ported from the react-dropzone reference study (blueprint M5): nested
+ * dragenter/dragleave target counting, empty MIME type during drag (Chrome),
+ * and the all-or-nothing maxFiles rule.
+ *
+ * Boundary: this component SELECTS and VALIDATES files. Uploading (network,
+ * progress) belongs to the consumer — compose with `Progress` for that.
+ * Directory drops are out of scope (entries without a real File are skipped).
+ */
+import type { HTMLAttributes, ReactNode } from "react";
+import type { FileRejection, ValidateFilesOptions } from "./validate.js";
+export { matchesAccept, validateFiles, type FileDropzoneError, type FileDropzoneErrorCode, type FileRejection, type ValidateFilesOptions, } from "./validate.js";
+export type FileDropzoneState = "idle" | "drag-over" | "drag-reject" | "disabled";
+export interface FileDropzoneProps extends Omit<HTMLAttributes<HTMLDivElement>, "onDrop" | "children">, ValidateFilesOptions {
+    /** Accessible name for the dropzone (aria-label). */
+    label: string;
+    disabled?: boolean;
+    onFilesAccepted?: (files: File[]) => void;
+    onFilesRejected?: (rejections: FileRejection[]) => void;
+    /** Custom instructions content; defaults to a drag-or-click hint. */
+    instructions?: ReactNode;
+}
+declare const FileDropzone: import("react").ForwardRefExoticComponent<FileDropzoneProps & import("react").RefAttributes<HTMLDivElement>>;
+export { FileDropzone };

package/dist/components/primitives/file-dropzone/index.d.ts

@@ -0,0 +1 @@
+export { FileDropzone, matchesAccept, validateFiles, type FileDropzoneError, type FileDropzoneErrorCode, type FileDropzoneProps, type FileDropzoneState, type FileRejection, type ValidateFilesOptions, } from "./file-dropzone.js";

package/dist/components/primitives/file-dropzone/validate.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Pure validation core of FileDropzone — typed rejections, accept matching
+ * (MIME exact / wildcard / extension), size and collective count rules.
+ * Ported behaviors from the react-dropzone reference study (blueprint M5).
+ */
+export type FileDropzoneErrorCode = "file-invalid-type" | "file-too-large" | "file-too-small" | "too-many-files";
+export interface FileDropzoneError {
+    /** One of the four built-in codes, or a custom code from `validator`. */
+    code: FileDropzoneErrorCode | string;
+    message: string;
+}
+export interface FileRejection {
+    file: File;
+    errors: FileDropzoneError[];
+}
+export interface ValidateFilesOptions {
+    accept?: Record<string, string[]>;
+    maxSize?: number;
+    minSize?: number;
+    maxFiles?: number;
+    multiple?: boolean;
+    validator?: (file: File) => FileDropzoneError | FileDropzoneError[] | null;
+}
+/**
+ * Matches a file against an `accept` map ({mime: [ext...]}): exact MIME,
+ * `type/*` wildcard, or extension (case-insensitive). No accept → accepts
+ * everything. An empty `file.type` is accepted (Chrome reports "" for some
+ * types during drag) — real validation happens again on drop.
+ */
+export declare function matchesAccept(file: File, accept?: Record<string, string[]>): boolean;
+/**
+ * Validates files against accept/size/count rules plus an optional custom
+ * validator. Per-file errors accumulate; the maxFiles/multiple rule is
+ * COLLECTIVE and all-or-nothing: exceeding it rejects EVERY file with
+ * `too-many-files` (ported from the reference behavior).
+ */
+export declare function validateFiles(files: File[], options?: ValidateFilesOptions): {
+    accepted: File[];
+    rejections: FileRejection[];
+};

package/dist/index.d.ts

@@ -45,10 +45,11 @@ export { Pagination, computePageRange, type PaginationProps, } from "./component
 export { DropdownMenu } from "./components/primitives/dropdown-menu/index.js";
 export { ActionBar, type ActionBarProps } from "./components/primitives/action-bar/index.js";
 export { PinInput, type PinInputProps } from "./components/primitives/pin-input/index.js";
-export { DataTable, type DataTableColumn, type DataTableProps, type DataTableSort, } from "./components/composites/data-table/index.js";
+export { DataTable, type DataTableColumn, type DataTableProps, type DataTableSort, type DataTableVirtualizedOptions, } from "./components/composites/data-table/index.js";
 export { PageShell, type PageShellProps } from "./components/composites/page-shell/index.js";
 export { linScale, niceMax, seriesPath, TrendChart, type TrendChartProps, type TrendPoint, type TrendSeries, } from "./components/composites/trend-chart/index.js";
 export { Stepper, deriveSteps, type StepStatus, type StepperProps, type StepperStepData, } from "./components/composites/stepper/index.js";
+export { FileDropzone, matchesAccept, validateFiles, type FileDropzoneError, type FileDropzoneErrorCode, type FileDropzoneProps, type FileDropzoneState, type FileRejection, type ValidateFilesOptions, } from "./components/primitives/file-dropzone/index.js";
 export { MetricsPanel, type Metric } from "./components/primitives/metrics-panel/index.js";
 export { SocialAuthRow, type SocialProvider, } from "./components/primitives/social-auth-row/index.js";
 export { LoginSplit } from "./components/primitives/login-split/index.js";

package/dist/index.js

@@ -19,6 +19,7 @@ import * as CheckboxPrimitive from '@radix-ui/react-checkbox';
 import * as RadioGroupPrimitive from '@radix-ui/react-radio-group';
 import * as SwitchPrimitive from '@radix-ui/react-switch';
 import * as DropdownMenuPrimitive from '@radix-ui/react-dropdown-menu';
+import { useVirtualizer } from '@tanstack/react-virtual';
 
 // src/lib/cn.ts
 var twMerge = extendTailwindMerge({
@@ -4094,6 +4095,74 @@ var PinInput = forwardRef(
   }
 );
 PinInput.displayName = "PinInput";
+function DataTableHeaderRow(props) {
+  const { columns, sort, onSortClick, hasExpandColumn = false, hasActionsColumn = false } = props;
+  return /* @__PURE__ */ jsxs(Table.Row, { children: [
+    hasExpandColumn ? /* @__PURE__ */ jsx(Table.HeaderCell, { children: /* @__PURE__ */ jsx("span", { className: "sr-only", children: "Expand" }) }) : null,
+    columns.map((col) => {
+      const isSortable = col.sortable === true;
+      const isActive = sort?.key === col.key;
+      return /* @__PURE__ */ jsx(
+        Table.HeaderCell,
+        {
+          align: col.align,
+          onSort: isSortable ? () => onSortClick(col.key) : void 0,
+          sortDirection: isSortable ? isActive ? sort?.direction : "none" : void 0,
+          style: col.width ? { width: col.width } : void 0,
+          children: col.label
+        },
+        col.key
+      );
+    }),
+    hasActionsColumn ? /* @__PURE__ */ jsx(Table.HeaderCell, { children: /* @__PURE__ */ jsx("span", { className: "sr-only", children: "Actions" }) }) : null
+  ] });
+}
+function DataTableRowActionsCell(props) {
+  return /* @__PURE__ */ jsx(Table.Cell, { align: "right", children: /* @__PURE__ */ jsxs(DropdownMenu, { children: [
+    /* @__PURE__ */ jsx(
+      DropdownMenu.Trigger,
+      {
+        "aria-label": "Row actions",
+        className: cn(
+          "inline-flex size-7 items-center justify-center rounded-md",
+          "text-muted-foreground hover:bg-muted hover:text-foreground",
+          "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        ),
+        children: /* @__PURE__ */ jsx(MoreHorizontal, { "aria-hidden": "true", className: "size-4" })
+      }
+    ),
+    /* @__PURE__ */ jsx(DropdownMenu.Content, { align: "end", children: props.children })
+  ] }) });
+}
+function renderCellContent(row, col) {
+  return col.render ? col.render(row) : String(row[col.key] ?? "");
+}
+function DataTableLoading(props) {
+  const { columns, hasExpandColumn, hasActionsColumn, stickyHeader, className } = props;
+  const totalCols = columns.length + (hasExpandColumn ? 1 : 0) + (hasActionsColumn ? 1 : 0);
+  return /* @__PURE__ */ jsx("div", { "data-slot": "data-table", className: cn("w-full", className), children: /* @__PURE__ */ jsxs(Table, { children: [
+    /* @__PURE__ */ jsx(Table.Header, { className: stickyHeader ? "sticky top-0 bg-card" : void 0, children: /* @__PURE__ */ jsx(
+      DataTableHeaderRow,
+      {
+        columns: columns.map((col) => ({ ...col, sortable: false })),
+        sort: null,
+        onSortClick: () => {
+        },
+        hasExpandColumn,
+        hasActionsColumn
+      }
+    ) }),
+    /* @__PURE__ */ jsx(Table.Body, { children: Array.from({ length: 5 }, (_, i) => (
+      // biome-ignore lint/suspicious/noArrayIndexKey: skeleton rows are positional placeholders
+      /* @__PURE__ */ jsx(Table.Row, { children: Array.from({ length: totalCols }, (_2, j) => (
+        // biome-ignore lint/suspicious/noArrayIndexKey: skeleton cells are positional placeholders
+        /* @__PURE__ */ jsx(Table.Cell, { children: /* @__PURE__ */ jsx(Skeleton, { className: "h-4 w-full" }) }, `s-${i}-${j}`)
+      )) }, `skeleton-${i}`)
+    )) })
+  ] }) });
+}
+
+// src/components/composites/data-table/compare-values.ts
 function compareValues(a, b) {
   if (a === b) return 0;
   if (a === null || a === void 0) return -1;
@@ -4101,7 +4170,184 @@ function compareValues(a, b) {
   if (typeof a === "number" && typeof b === "number") return a - b;
   return String(a).localeCompare(String(b));
 }
+
+// src/components/composites/data-table/use-data-table-sort.ts
+function useDataTableSort(opts) {
+  const { data, columns, defaultSort, sort: controlledSort, onSortChange } = opts;
+  const isControlledSort = onSortChange !== void 0;
+  const [uncontrolledSort, setUncontrolledSort] = useState(
+    defaultSort ?? null
+  );
+  const sort = isControlledSort ? controlledSort ?? null : uncontrolledSort;
+  function handleSort(columnKey) {
+    let nextSort;
+    if (sort?.key !== columnKey) {
+      nextSort = { key: columnKey, direction: "asc" };
+    } else if (sort.direction === "asc") {
+      nextSort = { key: columnKey, direction: "desc" };
+    } else {
+      nextSort = null;
+    }
+    if (isControlledSort) {
+      onSortChange?.(nextSort);
+    } else {
+      setUncontrolledSort(nextSort);
+      opts.onUncontrolledSortChange?.();
+    }
+  }
+  const sortedData = useMemo(() => {
+    if (isControlledSort || sort === null) return data;
+    const col = columns.find((c) => c.key === sort.key);
+    if (!col) return data;
+    const sorted = [...data].sort((a, b) => {
+      const aVal = col.render ? null : a[sort.key];
+      const bVal = col.render ? null : b[sort.key];
+      const cmp = compareValues(aVal, bVal);
+      return sort.direction === "asc" ? cmp : -cmp;
+    });
+    return sorted;
+  }, [data, sort, isControlledSort, columns]);
+  return { sort, handleSort, sortedData };
+}
+var EXCLUSIVE_PROPS = ["pagination", "expandable"];
+function SpacerRow(props) {
+  if (props.height <= 0) return null;
+  return (
+    // biome-ignore lint/a11y/noInteractiveElementToNoninteractiveRole: spacer row is pure layout filler (no content, no interaction) inside a semantic table; presentation keeps SRs on the aria-rowcount contract
+    /* @__PURE__ */ jsx(
+      "tr",
+      {
+        "data-slot": `data-table-virtual-spacer-${props.slot}`,
+        role: "presentation",
+        style: { height: `${props.height}px` },
+        children: /* @__PURE__ */ jsx("td", { colSpan: props.colSpan, style: { padding: 0 } })
+      }
+    )
+  );
+}
+function DataTableVirtualizedBody(props) {
+  const {
+    data,
+    columns,
+    rowKey,
+    virtualized,
+    rowActions,
+    defaultSort,
+    sort: controlledSort,
+    onSortChange,
+    loading = false,
+    emptyState,
+    className
+  } = props;
+  if (isDev()) {
+    for (const key of EXCLUSIVE_PROPS) {
+      if (props[key]) {
+        console.warn(
+          `DataTable: \`${key}\` is ignored in virtualized mode \u2014 the modes are mutually exclusive.`
+        );
+      }
+    }
+    if (virtualized.rowHeight < 1) {
+      console.warn("DataTable: virtualized.rowHeight must be >= 1px \u2014 falling back to 1.");
+    }
+  }
+  const rowHeight = Math.max(1, virtualized.rowHeight);
+  const parentRef = useRef(null);
+  const { sort, handleSort, sortedData } = useDataTableSort({
+    data,
+    columns,
+    defaultSort,
+    sort: controlledSort,
+    onSortChange
+  });
+  const virtualizer = useVirtualizer({
+    // Injection first (review F-dom-6): the @internal test hook can add
+    // observeElementRect but can never override the core window contract.
+    ...virtualized.virtualizerOptions,
+    count: sortedData.length,
+    getScrollElement: () => parentRef.current,
+    estimateSize: () => rowHeight,
+    overscan: virtualized.overscan ?? 5
+  });
+  if (loading) {
+    return /* @__PURE__ */ jsx(
+      DataTableLoading,
+      {
+        columns,
+        hasExpandColumn: false,
+        hasActionsColumn: rowActions !== void 0,
+        stickyHeader: true,
+        className
+      }
+    );
+  }
+  if (sortedData.length === 0) {
+    return /* @__PURE__ */ jsx("div", { className: cn("w-full", className), children: emptyState ?? /* @__PURE__ */ jsx(EmptyState, { title: "No data", description: "There's nothing here yet." }) });
+  }
+  const items = virtualizer.getVirtualItems();
+  const totalSize = virtualizer.getTotalSize();
+  const firstItem = items[0];
+  const lastItem = items[items.length - 1];
+  const paddingTop = firstItem ? firstItem.start : 0;
+  const paddingBottom = lastItem ? totalSize - lastItem.end : totalSize;
+  const colSpan = columns.length + (rowActions ? 1 : 0);
+  return /* @__PURE__ */ jsx("div", { "data-slot": "data-table-virtual-body", className: cn("w-full", className), children: /* @__PURE__ */ jsx(
+    "section",
+    {
+      ref: parentRef,
+      "aria-label": "Table scroll area",
+      tabIndex: 0,
+      className: "overflow-auto focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+      style: { height: virtualized.height },
+      "data-slot": "data-table-virtual-scroll",
+      children: /* @__PURE__ */ jsxs(Table, { "aria-rowcount": sortedData.length + 1, children: [
+        /* @__PURE__ */ jsx(Table.Header, { className: "sticky top-0 z-10 bg-card", children: /* @__PURE__ */ jsx(
+          DataTableHeaderRow,
+          {
+            columns,
+            sort,
+            onSortClick: handleSort,
+            hasActionsColumn: rowActions !== void 0
+          }
+        ) }),
+        /* @__PURE__ */ jsxs(Table.Body, { children: [
+          /* @__PURE__ */ jsx(SpacerRow, { slot: "top", height: paddingTop, colSpan }),
+          items.map((vRow) => {
+            const row = sortedData[vRow.index];
+            return /* @__PURE__ */ jsxs(
+              Table.Row,
+              {
+                "aria-rowindex": vRow.index + 2,
+                style: { height: `${rowHeight}px` },
+                children: [
+                  columns.map((col) => /* @__PURE__ */ jsx(
+                    Table.Cell,
+                    {
+                      align: col.align,
+                      className: cn("overflow-hidden py-1.5", col.className),
+                      children: renderCellContent(row, col)
+                    },
+                    col.key
+                  )),
+                  rowActions ? /* @__PURE__ */ jsx(DataTableRowActionsCell, { children: rowActions(row) }) : null
+                ]
+              },
+              rowKey(row)
+            );
+          }),
+          /* @__PURE__ */ jsx(SpacerRow, { slot: "bottom", height: paddingBottom, colSpan })
+        ] })
+      ] })
+    }
+  ) });
+}
 function DataTable(props) {
+  if (props.virtualized) {
+    return /* @__PURE__ */ jsx(DataTableVirtualizedBody, { ...props, virtualized: props.virtualized });
+  }
+  return /* @__PURE__ */ jsx(DataTableDefaultBody, { ...props });
+}
+function DataTableDefaultBody(props) {
   const {
     data,
     columns,
@@ -4118,32 +4364,22 @@ function DataTable(props) {
     emptyState,
     className
   } = props;
-  const isControlledSort = onSortChange !== void 0;
-  const [uncontrolledSort, setUncontrolledSort] = useState(
-    defaultSort ?? null
-  );
-  const sort = isControlledSort ? controlledSort ?? null : uncontrolledSort;
   const isControlledPage = pagination?.controlledPage !== void 0;
   const [uncontrolledPage, setUncontrolledPage] = useState(0);
   const currentPage = isControlledPage ? pagination?.controlledPage ?? 0 : uncontrolledPage;
   const effectivePageSize = Math.max(1, pagination?.pageSize ?? 10);
   const [expanded, setExpanded] = useState(/* @__PURE__ */ new Set());
-  function handleSort(columnKey) {
-    let nextSort;
-    if (sort?.key !== columnKey) {
-      nextSort = { key: columnKey, direction: "asc" };
-    } else if (sort.direction === "asc") {
-      nextSort = { key: columnKey, direction: "desc" };
-    } else {
-      nextSort = null;
-    }
-    if (isControlledSort) {
-      onSortChange?.(nextSort);
-    } else {
-      setUncontrolledSort(nextSort);
+  const { sort, handleSort, sortedData } = useDataTableSort({
+    data,
+    columns,
+    defaultSort,
+    sort: controlledSort,
+    onSortChange,
+    // EC-8: sort change resets pagination to page 0
+    onUncontrolledSortChange: () => {
       if (!isControlledPage) setUncontrolledPage(0);
     }
-  }
+  });
   function handlePageChange(page) {
     const zeroIdx = page - 1;
     if (isControlledPage) {
@@ -4167,18 +4403,6 @@ function DataTable(props) {
       });
     }
   }
-  const sortedData = useMemo(() => {
-    if (isControlledSort || sort === null) return data;
-    const col = columns.find((c) => c.key === sort.key);
-    if (!col) return data;
-    const sorted = [...data].sort((a, b) => {
-      const aVal = col.render ? null : a[sort.key];
-      const bVal = col.render ? null : b[sort.key];
-      const cmp = compareValues(aVal, bVal);
-      return sort.direction === "asc" ? cmp : -cmp;
-    });
-    return sorted;
-  }, [data, sort, isControlledSort, columns]);
   const visibleData = useMemo(() => {
     if (!pagination) return sortedData;
     if (isControlledPage) return sortedData;
@@ -4187,22 +4411,17 @@ function DataTable(props) {
   }, [sortedData, pagination, isControlledPage, currentPage, effectivePageSize]);
   const extraCols = (expandable ? 1 : 0) + (rowActions ? 1 : 0);
   const expandedColSpan = columns.length + extraCols;
-  const totalCols = columns.length + extraCols;
   if (loading) {
-    return /* @__PURE__ */ jsx("div", { "data-slot": "data-table", className: cn("w-full", className), children: /* @__PURE__ */ jsxs(Table, { children: [
-      /* @__PURE__ */ jsx(Table.Header, { className: stickyHeader ? "sticky top-0 bg-card" : void 0, children: /* @__PURE__ */ jsxs(Table.Row, { children: [
-        expandable ? /* @__PURE__ */ jsx(Table.HeaderCell, { children: /* @__PURE__ */ jsx("span", { className: "sr-only", children: "Expand" }) }) : null,
-        columns.map((col) => /* @__PURE__ */ jsx(Table.HeaderCell, { align: col.align, children: col.label }, col.key)),
-        rowActions ? /* @__PURE__ */ jsx(Table.HeaderCell, { children: /* @__PURE__ */ jsx("span", { className: "sr-only", children: "Actions" }) }) : null
-      ] }) }),
-      /* @__PURE__ */ jsx(Table.Body, { children: Array.from({ length: 5 }, (_, i) => (
-        // biome-ignore lint/suspicious/noArrayIndexKey: skeleton rows are positional placeholders
-        /* @__PURE__ */ jsx(Table.Row, { children: Array.from({ length: totalCols }, (_2, j) => (
-          // biome-ignore lint/suspicious/noArrayIndexKey: skeleton cells are positional placeholders
-          /* @__PURE__ */ jsx(Table.Cell, { children: /* @__PURE__ */ jsx(Skeleton, { className: "h-4 w-full" }) }, `s-${i}-${j}`)
-        )) }, `skeleton-${i}`)
-      )) })
-    ] }) });
+    return /* @__PURE__ */ jsx(
+      DataTableLoading,
+      {
+        columns,
+        hasExpandColumn: expandable !== void 0,
+        hasActionsColumn: rowActions !== void 0,
+        stickyHeader,
+        className
+      }
+    );
   }
   if (sortedData.length === 0) {
     return /* @__PURE__ */ jsx("div", { className: cn("w-full", className), children: emptyState ?? /* @__PURE__ */ jsx(EmptyState, { title: "No data", description: "There's nothing here yet." }) });
@@ -4210,25 +4429,16 @@ function DataTable(props) {
   const totalPages = pagination ? Math.ceil(sortedData.length / effectivePageSize) : 1;
   return /* @__PURE__ */ jsxs("div", { className: cn("w-full", className), children: [
     /* @__PURE__ */ jsxs(Table, { children: [
-      /* @__PURE__ */ jsx(Table.Header, { className: stickyHeader ? "sticky top-0 z-10 bg-card" : void 0, children: /* @__PURE__ */ jsxs(Table.Row, { children: [
-        expandable ? /* @__PURE__ */ jsx(Table.HeaderCell, { children: /* @__PURE__ */ jsx("span", { className: "sr-only", children: "Expand" }) }) : null,
-        columns.map((col) => {
-          const isSortable = col.sortable === true;
-          const isActive = sort?.key === col.key;
-          return /* @__PURE__ */ jsx(
-            Table.HeaderCell,
-            {
-              align: col.align,
-              onSort: isSortable ? () => handleSort(col.key) : void 0,
-              sortDirection: isSortable ? isActive ? sort?.direction : "none" : void 0,
-              style: col.width ? { width: col.width } : void 0,
-              children: col.label
-            },
-            col.key
-          );
-        }),
-        rowActions ? /* @__PURE__ */ jsx(Table.HeaderCell, { children: /* @__PURE__ */ jsx("span", { className: "sr-only", children: "Actions" }) }) : null
-      ] }) }),
+      /* @__PURE__ */ jsx(Table.Header, { className: stickyHeader ? "sticky top-0 z-10 bg-card" : void 0, children: /* @__PURE__ */ jsx(
+        DataTableHeaderRow,
+        {
+          columns,
+          sort,
+          onSortClick: handleSort,
+          hasExpandColumn: expandable !== void 0,
+          hasActionsColumn: rowActions !== void 0
+        }
+      ) }),
       /* @__PURE__ */ jsx(Table.Body, { children: visibleData.map((row) => {
         const key = rowKey(row);
         const expandedContent = expandable ? expandable(row) : null;
@@ -4248,22 +4458,8 @@ function DataTable(props) {
                 children: isExpanded ? /* @__PURE__ */ jsx(ChevronDown, { "aria-hidden": "true", className: "size-4" }) : /* @__PURE__ */ jsx(ChevronRight, { "aria-hidden": "true", className: "size-4" })
               }
             ) : null }) : null,
-            columns.map((col) => /* @__PURE__ */ jsx(Table.Cell, { align: col.align, className: col.className, children: col.render ? col.render(row) : String(row[col.key] ?? "") }, col.key)),
-            rowActions ? /* @__PURE__ */ jsx(Table.Cell, { align: "right", children: /* @__PURE__ */ jsxs(DropdownMenu, { children: [
-              /* @__PURE__ */ jsx(
-                DropdownMenu.Trigger,
-                {
-                  "aria-label": "Row actions",
-                  className: cn(
-                    "inline-flex size-7 items-center justify-center rounded-md",
-                    "text-muted-foreground hover:bg-muted hover:text-foreground",
-                    "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
-                  ),
-                  children: /* @__PURE__ */ jsx(MoreHorizontal, { "aria-hidden": "true", className: "size-4" })
-                }
-              ),
-              /* @__PURE__ */ jsx(DropdownMenu.Content, { align: "end", children: rowActions(row) })
-            ] }) }) : null
+            columns.map((col) => /* @__PURE__ */ jsx(Table.Cell, { align: col.align, className: col.className, children: renderCellContent(row, col) }, col.key)),
+            rowActions ? /* @__PURE__ */ jsx(DataTableRowActionsCell, { children: rowActions(row) }) : null
           ] }),
           isExpanded && isExpandable ? /* @__PURE__ */ jsx("tr", { id: `expanded-${key}`, children: /* @__PURE__ */ jsx("td", { colSpan: expandedColSpan, className: "bg-muted/30 p-4", children: expandedContent }) }) : null
         ] }, key);
@@ -4628,6 +4824,223 @@ var Stepper = forwardRef(
   )
 );
 Stepper.displayName = "Stepper";
+
+// src/components/primitives/file-dropzone/validate.ts
+function matchesAccept(file, accept) {
+  const entries = Object.entries(accept ?? {});
+  if (entries.length === 0) return true;
+  if (file.type === "") {
+    const exts = entries.flatMap(([, e]) => e);
+    if (exts.length === 0) return true;
+    return exts.some((ext) => file.name.toLowerCase().endsWith(ext.toLowerCase()));
+  }
+  return entries.some(([mime, exts]) => {
+    if (mime === file.type) return true;
+    if (mime.endsWith("/*") && file.type.startsWith(mime.slice(0, -1))) return true;
+    return exts.some((ext) => file.name.toLowerCase().endsWith(ext.toLowerCase()));
+  });
+}
+function acceptedExtensions(accept) {
+  const exts = Object.values(accept).flat();
+  return exts.length > 0 ? exts.join(", ") : Object.keys(accept).join(", ");
+}
+function validateFiles(files, options = {}) {
+  const { accept, maxSize, minSize, maxFiles, multiple = true, validator } = options;
+  const accepted = [];
+  const rejections = [];
+  for (const file of files) {
+    const errors = [];
+    if (accept && !matchesAccept(file, accept)) {
+      errors.push({
+        code: "file-invalid-type",
+        message: `File type must be one of ${acceptedExtensions(accept)}`
+      });
+    }
+    if (maxSize !== void 0 && file.size > maxSize) {
+      errors.push({ code: "file-too-large", message: `File is larger than ${maxSize} bytes` });
+    }
+    if (minSize !== void 0 && file.size < minSize) {
+      errors.push({ code: "file-too-small", message: `File is smaller than ${minSize} bytes` });
+    }
+    const custom = validator?.(file);
+    if (custom) errors.push(...Array.isArray(custom) ? custom : [custom]);
+    if (errors.length > 0) {
+      rejections.push({ file, errors });
+    } else {
+      accepted.push(file);
+    }
+  }
+  const tooMany = !multiple && accepted.length > 1 || maxFiles !== void 0 && maxFiles >= 1 && accepted.length > maxFiles;
+  if (tooMany) {
+    const limit = !multiple ? 1 : maxFiles;
+    for (const file of accepted) {
+      rejections.push({
+        file,
+        errors: [{ code: "too-many-files", message: `Too many files \u2014 at most ${limit} allowed` }]
+      });
+    }
+    accepted.length = 0;
+  }
+  return { accepted, rejections };
+}
+function hasFiles(event) {
+  return Array.from(event.dataTransfer?.types ?? []).includes("Files");
+}
+var FileDropzone = forwardRef(
+  ({
+    label,
+    disabled = false,
+    accept,
+    maxSize,
+    minSize,
+    maxFiles,
+    multiple = true,
+    validator,
+    onFilesAccepted,
+    onFilesRejected,
+    instructions,
+    className,
+    ...props
+  }, ref) => {
+    const dragTargetsRef = useRef([]);
+    const inputRef = useRef(null);
+    const [dragState, setDragState] = useState("idle");
+    const [rejections, setRejections] = useState([]);
+    const validateOptions = {
+      accept,
+      maxSize,
+      minSize,
+      maxFiles,
+      multiple,
+      validator
+    };
+    const processFiles = (files) => {
+      if (files.length === 0) return;
+      const result = validateFiles(files, validateOptions);
+      setRejections(result.rejections);
+      if (result.accepted.length > 0) onFilesAccepted?.(result.accepted);
+      if (result.rejections.length > 0) onFilesRejected?.(result.rejections);
+    };
+    const openPicker = () => {
+      const input = inputRef.current;
+      if (!input || disabled) return;
+      input.value = "";
+      input.click();
+    };
+    const onKeyDown = (event) => {
+      if (event.target !== event.currentTarget) return;
+      if (event.key === "Enter" || event.key === " ") {
+        event.preventDefault();
+        openPicker();
+      }
+    };
+    const onDragEnter = (event) => {
+      event.preventDefault();
+      if (disabled || !hasFiles(event)) return;
+      dragTargetsRef.current = [...dragTargetsRef.current, event.target];
+      const items = Array.from(event.dataTransfer?.items ?? []).filter(
+        (item) => item.kind === "file"
+      );
+      const reject = accept !== void 0 && items.length > 0 && items.some(
+        (item) => item.type !== "" && !matchesAccept(
+          new File([], item.getAsFile?.()?.name ?? "", { type: item.type }),
+          accept
+        )
+      );
+      setDragState(reject ? "drag-reject" : "drag-over");
+    };
+    const onDragOver = (event) => {
+      event.preventDefault();
+      if (event.dataTransfer) {
+        try {
+          event.dataTransfer.dropEffect = "copy";
+        } catch {
+        }
+      }
+    };
+    const onDragLeave = (event) => {
+      event.preventDefault();
+      const root = event.currentTarget;
+      const targets = dragTargetsRef.current.filter((t) => root.contains(t));
+      const idx = targets.indexOf(event.target);
+      if (idx !== -1) targets.splice(idx, 1);
+      dragTargetsRef.current = targets;
+      if (targets.length === 0) setDragState("idle");
+    };
+    const onDrop = (event) => {
+      event.preventDefault();
+      dragTargetsRef.current = [];
+      setDragState("idle");
+      if (disabled || !hasFiles(event)) return;
+      processFiles(Array.from(event.dataTransfer?.files ?? []));
+    };
+    const state = disabled ? "disabled" : dragState;
+    return /* @__PURE__ */ jsxs("div", { className: "space-y-2", children: [
+      /* @__PURE__ */ jsx(
+        "div",
+        {
+          "data-slot": "file-dropzone",
+          "data-state": state,
+          ref,
+          role: "button",
+          "aria-label": label,
+          "aria-disabled": disabled || void 0,
+          tabIndex: disabled ? void 0 : 0,
+          onClick: () => openPicker(),
+          onKeyDown,
+          onDragEnter,
+          onDragOver,
+          onDragLeave,
+          onDrop,
+          className: cn(
+            "flex min-h-24 cursor-pointer flex-col items-center justify-center gap-1 rounded-md border border-border border-dashed p-4 text-center",
+            state === "drag-over" && "border-primary bg-primary/5",
+            state === "drag-reject" && "border-destructive bg-destructive/5",
+            state === "disabled" && "cursor-not-allowed opacity-50",
+            className
+          ),
+          ...props,
+          children: /* @__PURE__ */ jsx(
+            "div",
+            {
+              "data-slot": "file-dropzone-instructions",
+              className: "text-body-sm text-muted-foreground",
+              children: instructions ?? "Drag files here or click to browse."
+            }
+          )
+        }
+      ),
+      /* @__PURE__ */ jsx(
+        "input",
+        {
+          "data-slot": "file-dropzone-input",
+          ref: inputRef,
+          type: "file",
+          "aria-hidden": "true",
+          tabIndex: -1,
+          multiple,
+          accept: accept ? Object.entries(accept).flatMap(([m, e]) => [m, ...e]).join(",") : void 0,
+          disabled,
+          className: "sr-only",
+          onChange: (event) => processFiles(Array.from(event.target.files ?? []))
+        }
+      ),
+      rejections.length > 0 && /* @__PURE__ */ jsx(
+        "ul",
+        {
+          "data-slot": "file-dropzone-rejections",
+          className: "space-y-0.5 text-destructive text-label",
+          children: rejections.map((r) => /* @__PURE__ */ jsxs("li", { children: [
+            r.file.name,
+            " \u2014 ",
+            r.errors.map((e) => e.message).join("; ")
+          ] }, r.file.name))
+        }
+      )
+    ] });
+  }
+);
+FileDropzone.displayName = "FileDropzone";
 var MetricsPanel = forwardRef(
   ({ className, title, description, metrics, columns, ...props }, ref) => /* @__PURE__ */ jsxs(
     "div",
@@ -5558,4 +5971,4 @@ function CommandPalette({
   ] }) });
 }
 
-export { AccountMenu, ActionBar, Alert, Avatar, BadgeWithDot as Badge, Breadcrumb, Button, Card, Checkbox, CodeBlock, Combobox, CommandPalette, ConfirmDialog, CopyButton, DangerZone, DataTable, DeploymentRow, DescriptionList, Dialog, DomainConfig, DropdownMenu, EmptyState, EnvVarEditor, FormField, Input, JsonViewer, Label, LoginSplit, MetricCard, MetricsPanel, PageShell, Pagination, PinInput, PlanBadge, PreviewEnvCard, Progress, ProjectCard, RadioGroup, RollbackUI, ScrollArea, Select, Sheet, Sidebar, Skeleton, Slider, SocialAuthRow, StatTile, StatusDot, StatusIndicator, Stepper, Switch, Table, Tabs, TaskHeader, Textarea, Timestamp, Toast, Toaster, TooltipWithStatics as Tooltip, TopNav, TrendChart, UpdateBanner, avatarVariants, badgeVariants, buttonVariants, cn, computePageRange, deriveSteps, isNearBottom, linScale, niceMax, seriesPath, sheetVariants, useStickToBottom, useToast };
+export { AccountMenu, ActionBar, Alert, Avatar, BadgeWithDot as Badge, Breadcrumb, Button, Card, Checkbox, CodeBlock, Combobox, CommandPalette, ConfirmDialog, CopyButton, DangerZone, DataTable, DeploymentRow, DescriptionList, Dialog, DomainConfig, DropdownMenu, EmptyState, EnvVarEditor, FileDropzone, FormField, Input, JsonViewer, Label, LoginSplit, MetricCard, MetricsPanel, PageShell, Pagination, PinInput, PlanBadge, PreviewEnvCard, Progress, ProjectCard, RadioGroup, RollbackUI, ScrollArea, Select, Sheet, Sidebar, Skeleton, Slider, SocialAuthRow, StatTile, StatusDot, StatusIndicator, Stepper, Switch, Table, Tabs, TaskHeader, Textarea, Timestamp, Toast, Toaster, TooltipWithStatics as Tooltip, TopNav, TrendChart, UpdateBanner, avatarVariants, badgeVariants, buttonVariants, cn, computePageRange, deriveSteps, isNearBottom, linScale, matchesAccept, niceMax, seriesPath, sheetVariants, useStickToBottom, useToast, validateFiles };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usetheo/ui",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "type": "module",
   "license": "Apache-2.0",
   "description": "Violet Forge design system — generic React components + primitives (the non-AI foundation of @theokit/ui).",
@@ -40,6 +40,7 @@
     "@radix-ui/react-tabs": "^1.1.3",
     "@radix-ui/react-toast": "^1.2.15",
     "@radix-ui/react-tooltip": "^1.1.8",
+    "@tanstack/react-virtual": "^3.14.6",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",