npm package: @rg-grid/rg-grid
Description: RGGrid — a production-grade, feature-rich React data grid with sorting, filtering, pagination, column resizing, and drag-and-drop reordering.
Author: bprhub
Latest version: 2.0.12

# @rg-grid/rg-grid

**RGGrid** is a production-grade **React + TypeScript data grid** built for internal tools and business applications.

It follows an **API-first, logic-first architecture** — all behavior runs through deterministic feature plugins, while the UI remains a thin, replaceable render layer.

No wrapper components. No hidden magic. Fully extensible.

---

## 🌐 Live Demo

👉 https://rg-grid.vercel.app/

---

# 🚀 Quick Start

## Install

```bash
npm install @rg-grid/rg-grid
npm install react react-dom
```

## Import Styles

```ts
import "@rg-grid/rg-grid/styles.css";
```

Tailwind is **not required** in consumer applications.

---

## Basic Usage

```tsx
import "@rg-grid/rg-grid/styles.css";
import { RGGrid } from "@rg-grid/rg-grid";
import type { Column } from "@rg-grid/rg-grid";

type Account = {
  id: number;
  company: string;
  owner: string;
  mrr: number;
  status: "draft" | "review" | "approved" | "rejected";
};

const columns: Column<Account>[] = [
  { key: "id", label: "ID", sortable: true, width: 80, align: "center" },
  { key: "company", label: "Company", sortable: true, showFilter: true },
  { key: "owner", label: "Owner", sortable: true },
  { key: "mrr", label: "MRR", sortable: true, align: "right" },
  { key: "status", label: "Status", sortable: true, showFilter: true },
];

const data: Account[] = [
  { id: 1, company: "Northwind", owner: "Ava", mrr: 12000, status: "review" },
  { id: 2, company: "Nimbus", owner: "Noah", mrr: 5200, status: "draft" },
];

export default function Page() {
  return (
    <RGGrid
      data={data}
      columns={columns}
      defaultPageSize={10}
      sortable
      resizable
      pagination
      rowReorderable
      showRowDragHandle
      getRowId={(row) => row.id}
    />
  );
}
```

---

# ✨ Feature Highlights

### Core Grid

- Sorting
- Column + global filtering
- Pagination
- Column resizing
- Column reordering (drag & drop)
- Row reordering
- Editable cells
- URL state sync (`page`, `pageSize`)
- SSR-safe behavior

### Advanced Features

- Deterministic plugin system
- Rules engine (sync + async)
- Audit trail
- Workflow states + transitions
- Tree / hierarchical rows (accordion)
- Light / Dark theme
- Token-based design system
- Imperative plugin API registry

---

# 🧠 Architecture

Full guide:  
📄 `docs/architecture.md`

### Deterministic Data Pipeline

```
Raw Data
   ↓
CoreRow
   ↓
Feature Plugins (ordered, priority-based)
   ↓
ViewRow
   ↓
Render Layer
```

RGGrid is designed so **features compose cleanly without wrappers**.

---

# 🔎 Common Usage Patterns

## Rules Engine

```tsx
import type { Rule } from "@rg-grid/rg-grid";

const rules: Rule<Account>[] = [
  {
    column: "mrr",
    condition: (value) => Number(value) < 0,
    action: "error",
    message: "MRR cannot be negative",
  },
];

<RGGrid data={data} columns={columns} rules={rules} />;
```

Supports sync + async validations.

---

## Audit + Imperative API

```tsx
import { useRef } from "react";
import { RGGrid } from "@rg-grid/rg-grid";
import type { RGGridHandle } from "@rg-grid/rg-grid";

const gridRef = useRef<RGGridHandle>(null);

<RGGrid
  ref={gridRef}
  data={data}
  columns={columns}
  editable
  audit={{ enabled: true, getUser: () => "ops@rggrid.com" }}
  showRecentEdits
/>;

const logs = gridRef.current?.getAuditLogs?.() ?? [];
const auditApi = gridRef.current?.getPlugin?.("audit");
const sameLogs = auditApi?.getAuditLogs?.() ?? [];
```

---

## Workflow

```tsx
const workflow = {
  column: "status",
  states: ["draft", "review", "approved", "rejected"],
  transitions: {
    draft: ["review"],
    review: ["approved", "rejected"],
    rejected: ["review"],
  },
};

<RGGrid
  data={data}
  columns={columns}
  workflow={workflow}
  onStateChange={(row, state) => {
    console.log("workflow changed", row, state);
  }}
/>;
```

---

# 🌳 Tree / Hierarchical Rows

Fully compatible with sorting, filtering, pagination, and row reordering.

## Flat Structure (Manager → Employee)

```tsx
type Employee = {
  id: number;
  managerId?: number;
  name: string;
  role: string;
};

<RGGrid
  data={employees}
  columns={columns}
  tree={{
    getId: (row) => row.id,
    getParentId: (row) => row.managerId,
    defaultExpanded: false,
  }}
/>;
```

## Nested Structure (Album → Tracks)

```tsx
<RGGrid
  data={albums}
  columns={columns}
  tree={{
    childrenKey: "tracks",
    getId: (row) => row.id,
    defaultExpanded: true,
    indentSize: 16,
  }}
/>
```

---

# 🎨 Theming

### Options

- `theme="light"` or `theme="dark"`
- Wrapper classes: `.rg-theme-light` / `.rg-theme-dark`
- Disable built-in switch: `showThemeSwitch={false}`

```tsx
<div className="rg-theme-dark">
  <RGGrid data={data} columns={columns} showThemeSwitch={false} />
</div>
```

---

# 📦 Main Exports

```ts
import { RGGrid, AdvancedTable, DarkLightModeSwitch } from "@rg-grid/rg-grid";

import {
  useFeaturePipeline,
  useTreeFeaturePlugin,
  useFilteringFeaturePlugin,
  useSortingFeaturePlugin,
  useRowReorderFeaturePlugin,
  usePaginationFeaturePlugin,
  useRulesPlugin,
  useAuditPlugin,
  useWorkflowPlugin,
} from "@rg-grid/rg-grid";

import type {
  RGGridProps,
  RGGridHandle,
  Column,
  FeaturePlugin,
  TreeConfig,
  Rule,
  AuditLog,
  WorkflowConfig,
} from "@rg-grid/rg-grid";
```

---

# 🛡 SSR & Framework Support

- SSR safe (Next.js compatible)
- No hard dependency on router
- URL sync uses `window.history.replaceState`
- Browser APIs guarded (`window`, `localStorage`)

---

# 💡 Design Principles

- API-first
- Logic-first
- Deterministic behavior
- No wrapper components
- Plugin extensibility
- Enterprise-ready
- Composable features

---

# ☕ Support Development

If RGGrid helps your team:

👉 https://buymeacoffee.com/rajugundu