react-shadcn-table 1.0.0

package/README.md

@@ -0,0 +1,219 @@
+# react-shadcn-table
+
+A feature-rich, headless-powered data grid for React — built on [TanStack Table v9](https://tanstack.com/table) and [shadcn/ui](https://ui.shadcn.com/). Sorting, filtering, pagination, row selection, column/row pinning, resizing, drag-and-drop column ordering, expandable rows, and split (frozen) columns — all out of the box.
+
+**Live Demo:** [https://react-shadcn-table.jsdevs.xyz/](https://react-shadcn-table.jsdevs.xyz/)
+
+## Features
+
+- Global search + per-column filtering (text, range)
+- Multi-column sorting
+- Client-side & manual (server-side) pagination
+- Row selection with checkboxes
+- Column pinning (left / right) and row pinning (top / bottom)
+- Resizable & drag-to-reorder columns (`@dnd-kit`)
+- Split view for frozen left/right columns
+- Expandable rows with custom sub-components
+- Cell selection and cell spanning support
+- Persists per-grid layout (column order, sizing, visibility, pinning) via a storage key
+- Built-in loading, error, and empty states
+- Fully styled with Tailwind CSS + shadcn/ui — themeable out of the box
+- Export to Excel and PDF (`xlsx`, `jspdf`)
+- Bring your own toolbar actions via `topRightSlot`
+
+## Installation
+
+```bash
+npm install react-shadcn-table
+```
+
+### Peer Dependencies
+
+Make sure the following are installed in your project:
+
+```bash
+npm install react react-dom
+```
+
+Tailwind CSS must also be configured in your project, since the grid ships unstyled utility classes rather than a separate CSS bundle.
+
+## Quick Start
+
+```tsx
+import { useMemo } from 'react';
+import {
+  Grid,
+  useGridState,
+  type GridFeatures,
+  type ColumnDef,
+} from 'react-shadcn-table';
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+const columns = useMemo<ColumnDef<GridFeatures, User, unknown>[]>(
+  () => [
+    { id: 'id', accessorKey: 'id', header: () => 'ID' },
+    { id: 'name', accessorKey: 'name', header: () => 'Name' },
+    { id: 'email', accessorKey: 'email', header: () => 'Email' },
+  ],
+  [],
+);
+
+const App = () => {
+  const { state, handlers } = useGridState();
+
+  return (
+    <Grid
+      payload={{ data: users, total: users.length }}
+      columns={columns}
+      state={state}
+      {...handlers}
+    />
+  );
+};
+```
+
+## Server-Side (Manual) Pagination, Sorting & Filtering
+
+```tsx
+const { state, handlers, rowSelection } = useGridState();
+
+const { data, isLoading, isError, refetch, isFetching } = useUsersQuery({
+  queryString: URLSearch(state),
+});
+
+<Grid
+  payload={{ data: data?.rows ?? [], total: data?.total ?? 0 }}
+  columns={columns}
+  manualPagination
+  manualFiltering
+  manualSorting
+  isLoading={isLoading}
+  isError={isError}
+  isFetching={isFetching}
+  refetch={refetch}
+  state={state}
+  {...handlers}
+  height="55vh"
+/>;
+```
+
+## Toolbar Actions
+
+Add custom action buttons to the toolbar via `topRightSlot`:
+
+```tsx
+import { Plus, RefreshCw } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+
+<Grid
+  columns={columns}
+  payload={{ data, total }}
+  state={state}
+  {...handlers}
+  topRightSlot={
+    <div className="flex items-center gap-2">
+      <Button variant="ghost" size="icon" onClick={refetch}>
+        <RefreshCw className="size-4" />
+      </Button>
+      <Button variant="default" size="icon" onClick={handleAdd}>
+        <Plus className="size-4" />
+      </Button>
+    </div>
+  }
+/>;
+```
+
+## Working with Row Selection
+
+Use the `pluckSelected` utility to extract a field from all selected rows:
+
+```tsx
+import { pluckSelected } from 'react-shadcn-table';
+
+const { rowSelection } = useGridState();
+
+const selectedIds = pluckSelected(data, rowSelection, 'id');
+// => ["V001", "V003", "V004"]
+```
+
+## API Reference
+
+### `<Grid />` Props
+
+| Prop                    | Type                                                         | Default   | Description                                                      |
+| ----------------------- | ------------------------------------------------------------ | --------- | ---------------------------------------------------------------- |
+| `payload`               | `{ data: TData[]; total: number }`                           | —         | Row data and total row count                                     |
+| `columns`               | `ColumnDef<GridFeatures, TData, unknown>[]`                  | —         | Column definitions (required)                                    |
+| `state`                 | `Partial<TableState<GridFeatures>>`                          | —         | Controlled table state (from `useGridState`)                     |
+| `onColumnFiltersChange` | `OnChangeFn<ColumnFiltersState>`                             | —         | Column filter change handler                                     |
+| `onPaginationChange`    | `OnChangeFn<PaginationState>`                                | —         | Pagination change handler                                        |
+| `onSortingChange`       | `OnChangeFn<SortingState>`                                   | —         | Sorting change handler                                           |
+| `onRowSelectionChange`  | `OnChangeFn<RowSelectionState>`                              | —         | Row selection change handler                                     |
+| `setGlobalFilter`       | `Dispatch<SetStateAction<string>>`                           | —         | Global search setter                                             |
+| `manualPagination`      | `boolean`                                                    | `false`   | Enables server-side pagination                                   |
+| `manualFiltering`       | `boolean`                                                    | `false`   | Enables server-side column filtering                             |
+| `manualSorting`         | `boolean`                                                    | `false`   | Enables server-side sorting                                      |
+| `isLoading`             | `boolean`                                                    | —         | Shows skeleton loading rows                                      |
+| `isError`               | `boolean`                                                    | —         | Shows the error state                                            |
+| `isFetching`            | `boolean`                                                    | —         | Shows a background refetch indicator                             |
+| `refetch`               | `() => void`                                                 | —         | Retry/refresh callback                                           |
+| `renderSubComponent`    | `(props: { row: Row<GridFeatures, TData> }) => ReactElement` | —         | Custom content for expanded rows                                 |
+| `getRowCanExpand`       | `(row: Row<GridFeatures, TData>) => boolean`                 | —         | Controls whether a row can expand                                |
+| `enableCellSelection`   | `boolean`                                                    | `false`   | Enables Excel-like cell range selection                          |
+| `enableCellSpanning`    | `boolean`                                                    | `false`   | Enables merged/spanning cells                                    |
+| `enableRowSelection`    | `boolean`                                                    | `true`    | Enables/disables row selection                                   |
+| `height`                | `string`                                                     | `'65vh'`  | Fixed height of the scrollable table body                        |
+| `name`                  | `string`                                                     | `'munza'` | Storage key for persisting per-grid layout                       |
+| `topRightSlot`          | `React.ReactNode`                                            | —         | Custom content on the right of the toolbar (e.g. action buttons) |
+
+### `useGridState()`
+
+Manages all controlled state required by `<Grid />`.
+
+```tsx
+const { state, handlers, rowSelection } = useGridState();
+```
+
+Returns:
+
+- `state` — `{ columnFilters, globalFilter, pagination, sorting, rowSelection }`
+- `handlers` — `{ onColumnFiltersChange, onPaginationChange, onSortingChange, setGlobalFilter, onRowSelectionChange }`
+- `rowSelection` — the current selection map, exposed directly for convenience
+
+### `pluckSelected(data, rowSelection, field)`
+
+Extracts a field's value from every currently selected row.
+
+```tsx
+pluckSelected(data, rowSelection, 'id'); // => string[]
+```
+
+### `URLSearch(queryArgs)`
+
+Serializes TanStack Table state into a MongoDB/Express-style query string.
+
+```tsx
+URLSearch({
+  pagination: { pageIndex: 0, pageSize: 20 },
+  columnFilters: [{ id: 'status', value: 'active' }],
+  sorting: [{ id: 'year', desc: true }],
+  globalFilter: 'toyota',
+});
+// => "?page=1&limit=20&status=active&sort=-year&q=toyota"
+```
+
+## Peer Dependency Versions
+
+| Package               | Version      |
+| --------------------- | ------------ |
+| `react` / `react-dom` | `^18 \| ^19` |
+| `tailwindcss`         | `^4.x`       |
+
+## License
+
+MIT

package/dist/components/ui/button-group.d.ts

@@ -0,0 +1,11 @@
+import { VariantProps } from 'class-variance-authority';
+import { Separator } from './separator';
+declare const buttonGroupVariants: (props?: ({
+    orientation?: "horizontal" | "vertical" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+declare function ButtonGroup({ className, orientation, ...props }: React.ComponentProps<"div"> & VariantProps<typeof buttonGroupVariants>): import("react").JSX.Element;
+declare function ButtonGroupText({ className, asChild, ...props }: React.ComponentProps<"div"> & {
+    asChild?: boolean;
+}): import("react").JSX.Element;
+declare function ButtonGroupSeparator({ className, orientation, ...props }: React.ComponentProps<typeof Separator>): import("react").JSX.Element;
+export { ButtonGroup, ButtonGroupSeparator, ButtonGroupText, buttonGroupVariants, };

package/dist/components/ui/button.d.ts

@@ -0,0 +1,10 @@
+import { VariantProps } from 'class-variance-authority';
+import * as React from "react";
+declare const buttonVariants: (props?: ({
+    variant?: "link" | "default" | "outline" | "secondary" | "ghost" | "destructive" | null | undefined;
+    size?: "sm" | "lg" | "default" | "xs" | "icon" | "icon-xs" | "icon-sm" | "icon-lg" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+declare function Button({ className, variant, size, asChild, ...props }: React.ComponentProps<"button"> & VariantProps<typeof buttonVariants> & {
+    asChild?: boolean;
+}): React.JSX.Element;
+export { Button, buttonVariants };

package/dist/components/ui/checkbox.d.ts

@@ -0,0 +1,4 @@
+import { Checkbox as CheckboxPrimitive } from 'radix-ui';
+import * as React from "react";
+declare function Checkbox({ className, ...props }: React.ComponentProps<typeof CheckboxPrimitive.Root>): React.JSX.Element;
+export { Checkbox };

package/dist/components/ui/collapsible.d.ts

@@ -0,0 +1,5 @@
+import { Collapsible as CollapsiblePrimitive } from 'radix-ui';
+declare function Collapsible({ ...props }: React.ComponentProps<typeof CollapsiblePrimitive.Root>): import("react").JSX.Element;
+declare function CollapsibleTrigger({ ...props }: React.ComponentProps<typeof CollapsiblePrimitive.CollapsibleTrigger>): import("react").JSX.Element;
+declare function CollapsibleContent({ ...props }: React.ComponentProps<typeof CollapsiblePrimitive.CollapsibleContent>): import("react").JSX.Element;
+export { Collapsible, CollapsibleTrigger, CollapsibleContent };

package/dist/components/ui/debounced-input.d.ts

@@ -0,0 +1,6 @@
+import { default as React } from 'react';
+export declare function DebouncedInput({ value: initialValue, onChange, debounce, ...props }: {
+    value: string | number;
+    onChange: (value: string | number) => void;
+    debounce?: number;
+} & Omit<React.InputHTMLAttributes<HTMLInputElement>, 'onChange'>): React.JSX.Element;

package/dist/components/ui/dropdown-menu.d.ts

@@ -0,0 +1,29 @@
+import { DropdownMenu as DropdownMenuPrimitive } from 'radix-ui';
+import * as React from "react";
+declare function DropdownMenu({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Root>): React.JSX.Element;
+declare function DropdownMenuPortal({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Portal>): React.JSX.Element;
+declare function DropdownMenuTrigger({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Trigger>): React.JSX.Element;
+declare function DropdownMenuContent({ className, align, sideOffset, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Content>): React.JSX.Element;
+declare function DropdownMenuGroup({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Group>): React.JSX.Element;
+declare function DropdownMenuItem({ className, inset, variant, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Item> & {
+    inset?: boolean;
+    variant?: "default" | "destructive";
+}): React.JSX.Element;
+declare function DropdownMenuCheckboxItem({ className, children, checked, inset, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.CheckboxItem> & {
+    inset?: boolean;
+}): React.JSX.Element;
+declare function DropdownMenuRadioGroup({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.RadioGroup>): React.JSX.Element;
+declare function DropdownMenuRadioItem({ className, children, inset, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.RadioItem> & {
+    inset?: boolean;
+}): React.JSX.Element;
+declare function DropdownMenuLabel({ className, inset, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Label> & {
+    inset?: boolean;
+}): React.JSX.Element;
+declare function DropdownMenuSeparator({ className, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Separator>): React.JSX.Element;
+declare function DropdownMenuShortcut({ className, ...props }: React.ComponentProps<"span">): React.JSX.Element;
+declare function DropdownMenuSub({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Sub>): React.JSX.Element;
+declare function DropdownMenuSubTrigger({ className, inset, children, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.SubTrigger> & {
+    inset?: boolean;
+}): React.JSX.Element;
+declare function DropdownMenuSubContent({ className, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.SubContent>): React.JSX.Element;
+export { DropdownMenu, DropdownMenuPortal, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuGroup, DropdownMenuLabel, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubTrigger, DropdownMenuSubContent, };

package/dist/components/ui/empty.d.ts

@@ -0,0 +1,11 @@
+import { VariantProps } from 'class-variance-authority';
+declare function Empty({ className, ...props }: React.ComponentProps<"div">): import("react").JSX.Element;
+declare function EmptyHeader({ className, ...props }: React.ComponentProps<"div">): import("react").JSX.Element;
+declare const emptyMediaVariants: (props?: ({
+    variant?: "default" | "icon" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+declare function EmptyMedia({ className, variant, ...props }: React.ComponentProps<"div"> & VariantProps<typeof emptyMediaVariants>): import("react").JSX.Element;
+declare function EmptyTitle({ className, ...props }: React.ComponentProps<"div">): import("react").JSX.Element;
+declare function EmptyDescription({ className, ...props }: React.ComponentProps<"p">): import("react").JSX.Element;
+declare function EmptyContent({ className, ...props }: React.ComponentProps<"div">): import("react").JSX.Element;
+export { Empty, EmptyHeader, EmptyTitle, EmptyDescription, EmptyContent, EmptyMedia, };

package/dist/components/ui/input-group.d.ts

@@ -0,0 +1,16 @@
+import { VariantProps } from 'class-variance-authority';
+import { Button } from './button';
+import * as React from "react";
+declare function InputGroup({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+declare const inputGroupAddonVariants: (props?: ({
+    align?: "inline-start" | "inline-end" | "block-start" | "block-end" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+declare function InputGroupAddon({ className, align, ...props }: React.ComponentProps<"div"> & VariantProps<typeof inputGroupAddonVariants>): React.JSX.Element;
+declare const inputGroupButtonVariants: (props?: ({
+    size?: "sm" | "xs" | "icon-xs" | "icon-sm" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+declare function InputGroupButton({ className, type, variant, size, ...props }: Omit<React.ComponentProps<typeof Button>, "size"> & VariantProps<typeof inputGroupButtonVariants>): React.JSX.Element;
+declare function InputGroupText({ className, ...props }: React.ComponentProps<"span">): React.JSX.Element;
+declare function InputGroupInput({ className, ...props }: React.ComponentProps<"input">): React.JSX.Element;
+declare function InputGroupTextarea({ className, ...props }: React.ComponentProps<"textarea">): React.JSX.Element;
+export { InputGroup, InputGroupAddon, InputGroupButton, InputGroupText, InputGroupInput, InputGroupTextarea, };

package/dist/components/ui/input.d.ts

@@ -0,0 +1,3 @@
+import * as React from "react";
+declare function Input({ className, type, ...props }: React.ComponentProps<"input">): React.JSX.Element;
+export { Input };

package/dist/components/ui/item.d.ts

@@ -0,0 +1,23 @@
+import { VariantProps } from 'class-variance-authority';
+import { Separator } from './separator';
+import * as React from "react";
+declare function ItemGroup({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+declare function ItemSeparator({ className, ...props }: React.ComponentProps<typeof Separator>): React.JSX.Element;
+declare const itemVariants: (props?: ({
+    variant?: "default" | "outline" | "muted" | null | undefined;
+    size?: "sm" | "default" | "xs" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+declare function Item({ className, variant, size, asChild, ...props }: React.ComponentProps<"div"> & VariantProps<typeof itemVariants> & {
+    asChild?: boolean;
+}): React.JSX.Element;
+declare const itemMediaVariants: (props?: ({
+    variant?: "default" | "icon" | "image" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+declare function ItemMedia({ className, variant, ...props }: React.ComponentProps<"div"> & VariantProps<typeof itemMediaVariants>): React.JSX.Element;
+declare function ItemContent({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+declare function ItemTitle({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+declare function ItemDescription({ className, ...props }: React.ComponentProps<"p">): React.JSX.Element;
+declare function ItemActions({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+declare function ItemHeader({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+declare function ItemFooter({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+export { Item, ItemMedia, ItemContent, ItemActions, ItemGroup, ItemSeparator, ItemTitle, ItemDescription, ItemHeader, ItemFooter, };

package/dist/components/ui/label.d.ts

@@ -0,0 +1,4 @@
+import { Label as LabelPrimitive } from 'radix-ui';
+import * as React from "react";
+declare function Label({ className, ...props }: React.ComponentProps<typeof LabelPrimitive.Root>): React.JSX.Element;
+export { Label };

package/dist/components/ui/native-select.d.ts

@@ -0,0 +1,8 @@
+import * as React from "react";
+type NativeSelectProps = Omit<React.ComponentProps<"select">, "size"> & {
+    size?: "sm" | "default";
+};
+declare function NativeSelect({ className, size, ...props }: NativeSelectProps): React.JSX.Element;
+declare function NativeSelectOption({ className, ...props }: React.ComponentProps<"option">): React.JSX.Element;
+declare function NativeSelectOptGroup({ className, ...props }: React.ComponentProps<"optgroup">): React.JSX.Element;
+export { NativeSelect, NativeSelectOptGroup, NativeSelectOption };

package/dist/components/ui/select.d.ts

@@ -0,0 +1,15 @@
+import { Select as SelectPrimitive } from 'radix-ui';
+import * as React from "react";
+declare function Select({ ...props }: React.ComponentProps<typeof SelectPrimitive.Root>): React.JSX.Element;
+declare function SelectGroup({ className, ...props }: React.ComponentProps<typeof SelectPrimitive.Group>): React.JSX.Element;
+declare function SelectValue({ ...props }: React.ComponentProps<typeof SelectPrimitive.Value>): React.JSX.Element;
+declare function SelectTrigger({ className, size, children, ...props }: React.ComponentProps<typeof SelectPrimitive.Trigger> & {
+    size?: "sm" | "default";
+}): React.JSX.Element;
+declare function SelectContent({ className, children, position, align, ...props }: React.ComponentProps<typeof SelectPrimitive.Content>): React.JSX.Element;
+declare function SelectLabel({ className, ...props }: React.ComponentProps<typeof SelectPrimitive.Label>): React.JSX.Element;
+declare function SelectItem({ className, children, ...props }: React.ComponentProps<typeof SelectPrimitive.Item>): React.JSX.Element;
+declare function SelectSeparator({ className, ...props }: React.ComponentProps<typeof SelectPrimitive.Separator>): React.JSX.Element;
+declare function SelectScrollUpButton({ className, ...props }: React.ComponentProps<typeof SelectPrimitive.ScrollUpButton>): React.JSX.Element;
+declare function SelectScrollDownButton({ className, ...props }: React.ComponentProps<typeof SelectPrimitive.ScrollDownButton>): React.JSX.Element;
+export { Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, };

package/dist/components/ui/separator.d.ts

@@ -0,0 +1,4 @@
+import { Separator as SeparatorPrimitive } from 'radix-ui';
+import * as React from "react";
+declare function Separator({ className, orientation, decorative, ...props }: React.ComponentProps<typeof SeparatorPrimitive.Root>): React.JSX.Element;
+export { Separator };

package/dist/components/ui/skeleton.d.ts

@@ -0,0 +1,2 @@
+declare function Skeleton({ className, ...props }: React.ComponentProps<"div">): import("react").JSX.Element;
+export { Skeleton };

package/dist/components/ui/spinner.d.ts

@@ -0,0 +1,2 @@
+declare function Spinner({ className, ...props }: React.ComponentProps<"svg">): import("react").JSX.Element;
+export { Spinner };

package/dist/components/ui/table.d.ts

@@ -0,0 +1,10 @@
+import * as React from 'react';
+declare function Table({ className, ...props }: React.ComponentProps<'table'>): React.JSX.Element;
+declare function TableHeader({ className, ...props }: React.ComponentProps<'thead'>): React.JSX.Element;
+declare function TableBody({ className, ...props }: React.ComponentProps<'tbody'>): React.JSX.Element;
+declare function TableFooter({ className, ...props }: React.ComponentProps<'tfoot'>): React.JSX.Element;
+declare function TableRow({ className, ...props }: React.ComponentProps<'tr'>): React.JSX.Element;
+declare function TableHead({ className, ...props }: React.ComponentProps<'th'>): React.JSX.Element;
+declare function TableCell({ className, ...props }: React.ComponentProps<'td'>): React.JSX.Element;
+declare function TableCaption({ className, ...props }: React.ComponentProps<'caption'>): React.JSX.Element;
+export { Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, };

package/dist/components/ui/textarea.d.ts

@@ -0,0 +1,3 @@
+import * as React from "react";
+declare function Textarea({ className, ...props }: React.ComponentProps<"textarea">): React.JSX.Element;
+export { Textarea };