react-table-dnd 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sami Odeh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,256 @@
+<div align="center">
+
+# react-table-dnd
+
+<p>
+  <img src="./docs/desktop.gif" alt="react-table-dnd — drag rows and columns" width="680" />
+</p>
+
+<p><strong>Drag-and-drop row & column reordering for React tables.</strong></p>
+
+<p>60fps animations &middot; Auto-scroll &middot; Mobile long-press &middot; Virtual scrolling &middot; Zero UI deps</p>
+
+<p>
+  <a href="https://www.npmjs.com/package/react-table-dnd"><img src="https://img.shields.io/npm/v/react-table-dnd?color=6366f1&label=npm" alt="npm" /></a>
+  <a href="https://bundlephobia.com/package/react-table-dnd"><img src="https://img.shields.io/bundlephobia/minzip/react-table-dnd?color=6366f1&label=size" alt="bundle size" /></a>
+  <a href="https://www.npmjs.com/package/react-table-dnd"><img src="https://img.shields.io/npm/dm/react-table-dnd?color=6366f1" alt="downloads" /></a>
+  <a href="https://github.com/samiodeh1337/react-table-dnd/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/react-table-dnd?color=6366f1" alt="license" /></a>
+</p>
+
+<p>
+  <a href="https://samiodeh1337.github.io/react-table-dnd/"><strong>Live Demos & Docs</strong></a>
+  &nbsp;&middot;&nbsp;
+  <a href="#quick-start">Quick Start</a>
+  &nbsp;&middot;&nbsp;
+  <a href="#api">API</a>
+  &nbsp;&middot;&nbsp;
+  <a href="https://github.com/samiodeh1337/react-table-dnd">GitHub</a>
+</p>
+
+</div>
+
+---
+
+## Why react-table-dnd?
+
+- **Rows & columns** — reorder both independently, automatic direction detection
+- **60fps** — direct DOM transforms during drag, no React re-renders until drop
+- **Mobile** — long-press to drag on touch devices, optimized for Chrome Android & Safari iOS
+- **Auto-scroll** — accelerates when dragging near container edges
+- **100k+ rows** — works with `@tanstack/react-virtual`
+- **Drag handles** — restrict drag to a grip icon with `<DragHandle>`
+- **Constraints** — lock specific rows or columns via drag range options
+- **Drop animation** — clone smoothly flies to the drop target
+- **Fully styleable** — `className` + `style` on every component — Tailwind, styled-components, CSS modules
+- **TypeScript** — full type definitions out of the box
+- **Tiny** — only peer dependency is React
+
+## Install
+
+```bash
+npm install react-table-dnd
+```
+
+> Requires `react` and `react-dom` >= 17.0.0
+
+## Quick Start
+
+```jsx
+import {
+  TableContainer, TableHeader, ColumnCell,
+  TableBody, BodyRow, RowCell,
+} from "react-table-dnd";
+
+function arrayMove(arr, from, to) {
+  const next = [...arr];
+  const [item] = next.splice(from, 1);
+  next.splice(to, 0, item);
+  return next;
+}
+
+export default function App() {
+  const [cols, setCols] = useState([
+    { id: "name", label: "Name", width: 150 },
+    { id: "age",  label: "Age",  width: 100 },
+    { id: "city", label: "City", width: 160 },
+  ]);
+  const [rows, setRows] = useState([
+    { id: "1", name: "Alice", age: 28, city: "NYC" },
+    { id: "2", name: "Bob",   age: 34, city: "LA" },
+    { id: "3", name: "Carol", age: 22, city: "SF" },
+  ]);
+
+  return (
+    <TableContainer
+      onDragEnd={({ sourceIndex, targetIndex, dragType }) => {
+        if (dragType === "column") setCols(arrayMove(cols, sourceIndex, targetIndex));
+        else setRows(arrayMove(rows, sourceIndex, targetIndex));
+      }}
+    >
+      <TableHeader>
+        {cols.map((col, i) => (
+          <ColumnCell key={col.id} id={col.id} index={i} style={{ width: col.width }}>
+            {col.label}
+          </ColumnCell>
+        ))}
+      </TableHeader>
+      <TableBody>
+        {rows.map((row, ri) => (
+          <BodyRow key={row.id} id={row.id} index={ri}>
+            {cols.map((col, ci) => (
+              <RowCell key={col.id} index={ci}>
+                {row[col.id]}
+              </RowCell>
+            ))}
+          </BodyRow>
+        ))}
+      </TableBody>
+    </TableContainer>
+  );
+}
+```
+
+## API
+
+### Components
+
+| Component | Props | Description |
+|---|---|---|
+| **`TableContainer`** | `onDragEnd`, `options`, `renderPlaceholder`, `className`, `style` | Root wrapper — provides drag context |
+| **`TableHeader`** | `className`, `style` | Header row container |
+| **`ColumnCell`** | **`id`**, **`index`**, `className`, `style` | Draggable column header cell |
+| **`TableBody`** | `className`, `style` | Scrollable body — pass `ref` for virtual scrolling |
+| **`BodyRow`** | **`id`**, **`index`**, `className`, `style` | Draggable row |
+| **`RowCell`** | **`index`**, `className`, `style` | Cell within a row |
+| **`DragHandle`** | `className`, `style` | Wrap inside BodyRow/ColumnCell to restrict drag to this element |
+
+Bold props are required.
+
+### Column Width
+
+Pass `width` inside the `style` prop on `ColumnCell`. Columns grow proportionally by default to fill available space. To fix a column at exactly its pixel size, also pass `flex`:
+
+```jsx
+{/* Flex — grows proportionally to fill container (default) */}
+<ColumnCell style={{ width: 150 }}>Name</ColumnCell>
+
+{/* Fixed — stays exactly 150px regardless of container width */}
+<ColumnCell style={{ width: 150, flex: "0 0 150px" }}>Name</ColumnCell>
+```
+
+### Types
+
+```typescript
+interface DragEndResult {
+  sourceIndex: number;
+  targetIndex: number;
+  dragType: "row" | "column";
+}
+
+interface DragRange {
+  start?: number;  // first draggable index
+  end?: number;    // last draggable index (exclusive)
+}
+```
+
+### Options
+
+```jsx
+<TableContainer
+  options={{
+    rowDragRange: { start: 1 },        // lock first row
+    columnDragRange: { start: 1, end: 5 }, // lock first col, only 1-4 draggable
+  }}
+/>
+```
+
+### Drag Handle
+
+```jsx
+import { DragHandle } from "react-table-dnd";
+
+<BodyRow id="1" index={0}>
+  <RowCell index={0}>
+    <DragHandle><GripIcon /></DragHandle>
+    Content here
+  </RowCell>
+</BodyRow>
+```
+
+### Custom Placeholder
+
+```jsx
+<TableContainer
+  renderPlaceholder={() => (
+    <div style={{
+      background: "#6366f122",
+      border: "2px dashed #6366f1",
+      height: "100%",
+    }} />
+  )}
+/>
+```
+
+## Styling
+
+Every component accepts `className` and `style`. No opinionated styles on cells.
+
+<table>
+<tr>
+<td><strong>Inline</strong></td>
+<td><strong>Tailwind</strong></td>
+<td><strong>styled-components</strong></td>
+</tr>
+<tr>
+<td>
+
+```jsx
+<ColumnCell style={{
+  padding: "0 16px",
+  fontWeight: 700,
+}} />
+```
+
+</td>
+<td>
+
+```jsx
+<ColumnCell className="px-4
+  font-bold text-sm" />
+```
+
+</td>
+<td>
+
+```jsx
+const Col = styled(ColumnCell)`
+  padding: 0 16px;
+  font-weight: 700;
+`;
+```
+
+</td>
+</tr>
+</table>
+
+## Browser Support
+
+| | Chrome | Firefox | Safari | Edge |
+|---|---|---|---|---|
+| **Desktop** | ✅ | ✅ | ✅ | ✅ |
+| **Mobile** | ✅ | ✅ | ✅ | ✅ |
+
+Mobile uses long-press to initiate drag.
+
+## Contributing
+
+```bash
+git clone https://github.com/samiodeh1337/react-table-dnd.git
+cd react-table-dnd
+npm install
+npm run dev    # docs site at localhost:5173
+```
+
+## License
+
+[MIT](LICENSE) &copy; [Sami Odeh](https://github.com/samiodeh1337)

package/dist/Components/BodyRow.d.ts

@@ -0,0 +1,9 @@
+import { default as React, CSSProperties, ReactNode } from 'react';
+interface BodyRowProps {
+    children: ReactNode;
+    style?: CSSProperties;
+    className?: string;
+    [propName: string]: any;
+}
+declare const BodyRow: React.FC<BodyRowProps>;
+export default BodyRow;

package/dist/Components/ColumnCell.d.ts

@@ -0,0 +1,9 @@
+import { default as React, ReactNode } from 'react';
+interface ColumnCellProps {
+    children: ReactNode;
+    style?: React.CSSProperties;
+    className?: string;
+    [propName: string]: any;
+}
+declare const ColumnCell: React.FC<ColumnCellProps>;
+export default ColumnCell;

package/dist/Components/DragHandle.d.ts

@@ -0,0 +1,8 @@
+import { default as React, ReactNode, CSSProperties } from 'react';
+interface DragHandleProps {
+    children: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}
+declare const DragHandle: React.FC<DragHandleProps>;
+export default DragHandle;

package/dist/Components/Draggable.d.ts

@@ -0,0 +1,12 @@
+import { default as React, CSSProperties, ReactNode } from 'react';
+import { DragType } from '../hooks/types';
+export interface DraggableProps {
+    children: ReactNode;
+    id: number | string;
+    index: number;
+    type: DragType;
+    styles: CSSProperties;
+    disabled?: boolean;
+}
+declare const Draggable: React.FC<DraggableProps>;
+export default Draggable;

package/dist/Components/RowCell.d.ts

@@ -0,0 +1,11 @@
+import { default as React } from 'react';
+interface RowCellProps {
+    children?: React.ReactNode;
+    width?: number;
+    index: number;
+    style?: React.CSSProperties;
+    className?: string;
+    [propName: string]: any;
+}
+declare const RowCell: React.FC<RowCellProps>;
+export default RowCell;

package/dist/Components/TableBody.d.ts

@@ -0,0 +1,8 @@
+import { default as React, ReactNode } from 'react';
+interface TableBodyProps {
+    children: ReactNode;
+    style?: React.CSSProperties;
+    className?: string;
+}
+declare const TableBody: React.ForwardRefExoticComponent<TableBodyProps & React.RefAttributes<HTMLDivElement>>;
+export default TableBody;

package/dist/Components/TableContainer/index.d.ts

@@ -0,0 +1,15 @@
+import { default as React, ReactNode } from 'react';
+import { DragEndResult, DragRange } from '../../hooks/types';
+interface TableProviderProps {
+    children: React.ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+    onDragEnd?: (result: DragEndResult) => void;
+    renderPlaceholder?: () => ReactNode;
+    options?: {
+        columnDragRange: DragRange;
+        rowDragRange: DragRange;
+    };
+}
+declare const TableProvider: React.ForwardRefExoticComponent<TableProviderProps & React.RefAttributes<HTMLDivElement>>;
+export default TableProvider;

package/dist/Components/TableContainer/store.d.ts

@@ -0,0 +1,7 @@
+import { TableState, TableAction } from '../../hooks/types';
+export interface TableStore {
+    getState: () => TableState;
+    dispatch: (action: TableAction) => void;
+    subscribe: (listener: () => void) => () => void;
+}
+export declare function createTableStore(reducer: (state: TableState, action: TableAction) => TableState, initialState: TableState): TableStore;

package/dist/Components/TableContainer/styles.d.ts

@@ -0,0 +1,7 @@
+import { ReactNode } from 'react';
+interface StylesProps {
+    children: ReactNode;
+    className?: string;
+}
+export declare const Styles: ({ children, className }: StylesProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/Components/TableContainer/useTable.d.ts

@@ -0,0 +1,9 @@
+import { TableStore } from './store';
+import { TableState, TableAction } from '../../hooks/types';
+export declare const StoreContext: import('react').Context<TableStore | null>;
+export declare const useTableStore: <T>(selector: (state: TableState) => T) => T;
+export declare const useTableDispatch: () => ((action: TableAction) => void);
+export declare const useTable: () => {
+    state: TableState;
+    dispatch: (action: TableAction) => void;
+};

package/dist/Components/TableHeader.d.ts

@@ -0,0 +1,8 @@
+import { default as React, ReactNode } from 'react';
+interface TableHeaderProps {
+    children: ReactNode;
+    style?: React.CSSProperties;
+    className?: string;
+}
+declare const TableHeader: React.ForwardRefExoticComponent<TableHeaderProps & React.RefAttributes<HTMLDivElement>>;
+export default TableHeader;

package/dist/Components/index.d.ts

@@ -0,0 +1,11 @@
+import { default as TableContainer } from './TableContainer';
+import { default as TableHeader } from './TableHeader';
+import { default as ColumnCell } from './ColumnCell';
+import { default as TableBody } from './TableBody';
+import { default as BodyRow } from './BodyRow';
+import { default as RowCell } from './RowCell';
+import { default as DragHandle } from './DragHandle';
+export { useTable, useTableStore, useTableDispatch } from './TableContainer/useTable';
+export { TableContainer, TableHeader, ColumnCell, TableBody, BodyRow, RowCell, DragHandle };
+export type { DragEndResult, DragRange, DragType } from '../hooks/types';
+export type { DraggableProps } from './Draggable';

package/dist/Components/utils.d.ts

@@ -0,0 +1,5 @@
+import { ColumnItem, RowItem } from '../hooks/types';
+export declare const binarySearchDropIndex: (mouseY: number, items: RowItem[]) => number;
+export declare const binarySearchDropIndexHeader: (mouseX: number, items: ColumnItem[]) => number;
+export declare function isScrollbarClick(clientX: number, clientY: number, target: HTMLElement): boolean;
+export declare const isIndexOutOfRange: (index: string | number, start?: number, end?: number) => boolean;

package/dist/hooks/types.d.ts

@@ -0,0 +1,125 @@
+import { MutableRefObject, RefObject } from 'react';
+export type DragType = 'row' | 'column';
+export interface DragEndResult {
+    sourceIndex: number;
+    targetIndex: number;
+    dragType: DragType;
+}
+export interface DraggedState {
+    initial: {
+        x: number;
+        y: number;
+    };
+    translate: {
+        x: number;
+        y: number;
+    };
+    isDragging: boolean;
+    draggedID: string | null;
+    targetIndex: number | null;
+    sourceIndex: number | null;
+}
+export interface RectState {
+    draggedItemWidth: number;
+    draggedItemHeight: number;
+}
+export interface TableDimensions {
+    width: number;
+    height: number;
+}
+export interface DragRange {
+    start?: number;
+    end?: number;
+}
+export interface Options {
+    columnDragRange: DragRange;
+    rowDragRange: DragRange;
+    defaultSizing: number;
+}
+export interface HookRefs {
+    tableRef: RefObject<HTMLDivElement | null>;
+    bodyRef: RefObject<HTMLDivElement | null>;
+    headerRef: RefObject<HTMLDivElement | null>;
+    cloneRef: RefObject<HTMLDivElement | null>;
+    placeholderRef: RefObject<HTMLDivElement | null>;
+}
+export interface TableState {
+    dragged: DraggedState;
+    dragType: DragType | null;
+    rect: RectState;
+    tableDimensions: TableDimensions;
+    refs: HookRefs;
+    bodyScrollBarWidth: number;
+    options: Options;
+    widths: number[];
+    columnIds: string[];
+}
+export type TableAction = {
+    type: 'setDragged';
+    value: Partial<DraggedState>;
+} | {
+    type: 'setDragType';
+    value: DragType | null;
+} | {
+    type: 'setTableDimensions';
+    value: TableDimensions;
+} | {
+    type: 'setRef';
+    refName: keyof HookRefs;
+    value: MutableRefObject<HTMLDivElement | null> | null;
+} | {
+    type: 'setBodyScrollBarWidth';
+    value: number;
+} | {
+    type: 'setWidths';
+    value: number[];
+} | {
+    type: 'setColumnIds';
+    value: string[];
+} | {
+    type: 'setOptions';
+    value: Partial<Options>;
+} | {
+    type: 'dragStart';
+    value: {
+        rect: RectState;
+        dragged: {
+            initial: {
+                x: number;
+                y: number;
+            };
+            translate: {
+                x: number;
+                y: number;
+            };
+            draggedID: string | null;
+            isDragging: boolean;
+            sourceIndex: number;
+        };
+        dragType: DragType | null;
+        tableDimensions: TableDimensions;
+    };
+} | {
+    type: 'dragEnd';
+    value: {
+        targetIndex: number | null;
+        sourceIndex: number | null;
+    };
+};
+export interface RowItem {
+    height: number;
+    itemTop: number;
+    itemBottom: number;
+    index: string;
+}
+export interface ColumnItem {
+    left: number;
+    width: number;
+    itemLeft: number;
+    itemRight: number;
+    index: string;
+}
+export interface Point {
+    x: number;
+    y: number;
+}

package/dist/hooks/useAutoScroll.d.ts

@@ -0,0 +1,15 @@
+import { HookRefs } from './types';
+declare const useAutoScroll: (refs: HookRefs) => {
+    startAutoScroll: (speed: number, ref: HTMLDivElement, dir: "horizontal" | "vertical") => void;
+    stopAutoScroll: () => void;
+    setContainerRect: (rect: DOMRect) => void;
+    isAutoScrollingVertical: import('react').RefObject<boolean>;
+    isAutoScrollingHorizontal: import('react').RefObject<boolean>;
+    pointerRef: import('react').RefObject<{
+        x: number;
+        y: number;
+    }>;
+    BodyScrollHandle: import('react').UIEventHandler<HTMLDivElement>;
+    HeaderScrollHandle: import('react').UIEventHandler<HTMLDivElement>;
+};
+export default useAutoScroll;

package/dist/hooks/useDragContextEvents.d.ts

@@ -0,0 +1,7 @@
+import { Dispatch } from 'react';
+import { HookRefs, DraggedState, DragType, Options, DragEndResult, TableAction } from './types';
+declare const useDragContextEvents: (refs: HookRefs, dragged: DraggedState, dispatch: Dispatch<TableAction>, dragType: DragType | null, options: Options, onDragEnd: ((result: DragEndResult) => void) | undefined) => {
+    dragStart: (e: React.MouseEvent<HTMLDivElement>) => void;
+    touchStart: (e: React.TouchEvent<HTMLDivElement>) => void;
+};
+export default useDragContextEvents;

package/dist/hooks/useDropTarget.d.ts

@@ -0,0 +1,13 @@
+import { HookRefs, Options, RowItem, ColumnItem, DragType, Point } from './types';
+interface DropTargetResult {
+    computeRowItems: () => RowItem[] | null;
+    computeColumnItems: () => ColumnItem[] | null;
+    resolveDropIndex: (clientX: number, clientY: number, dtype: DragType | null, rect: DOMRect, bodyScrollTop: number, initial: Point, size: {
+        width: number;
+        height: number;
+    }) => number;
+    cachedItemsRef: React.RefObject<RowItem[] | ColumnItem[] | null>;
+    cachedContainerRef: React.RefObject<DOMRect | null>;
+}
+declare const useDropTarget: (refs: HookRefs, options: Options) => DropTargetResult;
+export default useDropTarget;

package/dist/hooks/useIndexMaps.d.ts

@@ -0,0 +1,15 @@
+import { HookRefs } from './types';
+import { IndexMap } from './useShiftTransforms';
+interface IndexMapsResult {
+    rowIndexMapRef: React.RefObject<IndexMap>;
+    colIndexMapRef: React.RefObject<IndexMap>;
+    cellIndexMapRef: React.RefObject<Map<number, HTMLElement[]>>;
+    mapStaleRef: React.RefObject<boolean>;
+    buildMaps: (dtype: string | null | undefined, body: HTMLElement | null) => void;
+    rebuildRowMap: (container: HTMLElement) => void;
+    rebuildColumnMaps: (container: HTMLElement, header: HTMLElement | null) => void;
+    checkStaleness: () => void;
+    clearMaps: () => void;
+}
+declare const useIndexMaps: (refs: HookRefs) => IndexMapsResult;
+export default useIndexMaps;

package/dist/hooks/useLongPress.d.ts

@@ -0,0 +1,14 @@
+import { HookRefs } from './types';
+/**
+ * Mobile long-press-to-drag.
+ * this hook implements JS-based scrolling with momentum/inertia when
+ * the long press is cancelled (user is scrolling, not dragging).
+ *
+ * preventDefault() is called on touchmove to stop any residual
+ * browser behavior during the 300ms detection window.
+ */
+export default function useLongPress(refs: HookRefs, beginDrag: (e: React.TouchEvent<HTMLDivElement>, clientX: number, clientY: number) => void, dragEnd: () => void, onDragMove: (clientX: number, clientY: number) => void): {
+    touchStart: (e: React.TouchEvent<HTMLDivElement>) => void;
+    cancelLongPress: () => void;
+    isTouchActiveRef: import('react').RefObject<boolean>;
+};

package/dist/hooks/useShiftTransforms.d.ts

@@ -0,0 +1,16 @@
+import { HookRefs, DragType } from './types';
+export type IndexMap = Map<number, {
+    outer: HTMLElement;
+    inner: HTMLElement;
+}>;
+interface ShiftTransformsResult {
+    applyShiftTransforms: (sourceIndex: number | null, targetIndex: number | null, dtype: DragType | null) => void;
+    clearShiftTransforms: () => void;
+    prevTargetIndexRef: React.RefObject<number | null>;
+    draggedSizeRef: React.RefObject<{
+        width: number;
+        height: number;
+    }>;
+}
+declare const useShiftTransforms: (refs: HookRefs, rowIndexMapRef: React.RefObject<IndexMap>, colIndexMapRef: React.RefObject<IndexMap>, cellIndexMapRef: React.RefObject<Map<number, HTMLElement[]>>) => ShiftTransformsResult;
+export default useShiftTransforms;