0
# RevoGrid
1

2
RevoGrid is a powerful virtual data grid component built with StencilJS that efficiently handles millions of cells through virtual scrolling and intelligent viewport management. It provides comprehensive data grid functionality including Excel-like features, advanced cell editing, custom templates, sorting, filtering, export capabilities, and extensive customization options.
3

4
## Package Information
5

6
- **Package Name**: @revolist/revogrid
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @revolist/revogrid`
10

11
## Core Imports
12

13
```typescript
14
import { RevoGrid, Selection, Edition, RevoPlugin } from "@revolist/revogrid";
15
```
16

17
For framework-specific usage:
18

19
```typescript
20
// Vue
21
import { VueRevoGrid } from "@revolist/revogrid/vue";
22
// React  
23
import RevoGrid from "@revolist/revogrid/react";
24
// Angular
25
import { RevoGridModule } from "@revolist/revogrid/angular";
26
// Svelte
27
import RevoGrid from "@revolist/revogrid/svelte";
28
```
29

30
## Basic Usage
31

32
```typescript
33
import { RevoGrid } from "@revolist/revogrid";
34

35
// Define columns
36
const columns = [
37
  { prop: "name", name: "Name" },
38
  { prop: "age", name: "Age", columnType: "number" },
39
  { prop: "email", name: "Email" },
40
];
41

42
// Define data
43
const source = [
44
  { name: "John Doe", age: 30, email: "john@example.com" },
45
  { name: "Jane Smith", age: 25, email: "jane@example.com" },
46
];
47

48
// Use in HTML
49
<revo-grid 
50
  columns={columns} 
51
  source={source}
52
  theme="material"
53
  resize={true}
54
  range={true}
55
  canFocus={true}>
56
</revo-grid>
57
```
58

59
## Architecture
60

61
RevoGrid is built around several key architectural components:
62

63
- **Virtual Scrolling Engine**: Renders only visible cells for performance with large datasets
64
- **Viewport Management**: Intelligent coordinate system handling pinned rows/columns and scrolling
65
- **Plugin System**: Extensible architecture with built-in plugins for filtering, sorting, export, etc.
66
- **Framework Agnostic Core**: StencilJS-based web components with dedicated framework bindings
67
- **Observable State Management**: Reactive stores for data, columns, selection, and viewport state
68
- **Type System**: Full TypeScript support with comprehensive type definitions
69

70
## Capabilities
71

72
### Core Grid Component
73

74
The main `<revo-grid>` component provides the complete data grid functionality with virtual scrolling, data binding, and extensive customization options.
75

76
```typescript { .api }
77
interface RevoGridComponent {
78
  // Data properties
79
  source: RevoGrid.DataType[];
80
  columns: (RevoGrid.ColumnRegular | RevoGrid.ColumnGrouping)[];
81
  pinnedTopSource: RevoGrid.DataType[];
82
  pinnedBottomSource: RevoGrid.DataType[];
83
  
84
  // Display properties  
85
  theme: ThemeSpace.Theme;
86
  rowSize: number;
87
  colSize: number;
88
  frameSize: number;
89
  
90
  // Interaction properties
91
  readonly: boolean;
92
  resize: boolean;
93
  range: boolean;
94
  canFocus: boolean;
95
  useClipboard: boolean;
96
}
97
```
98

99
[Core Grid Component](./core-grid.md)
100

101
### Data Management
102

103
Comprehensive data handling including CRUD operations, data binding, reactive updates, and multi-source support for pinned rows.
104

105
```typescript { .api }
106
interface DataManagement {
107
  getSource(type?: RevoGrid.DimensionRows): Promise<RevoGrid.DataType[]>;
108
  getVisibleSource(type?: RevoGrid.DimensionRows): Promise<any[]>;
109
  refresh(type?: RevoGrid.DimensionRows | 'all'): Promise<void>;
110
  addTrimmed(trimmed: Record<number, boolean>, trimmedType?: string, type?: RevoGrid.DimensionRows): Promise<CustomEvent>;
111
}
112
```
113

114
[Data Management](./data-management.md)
115

116
### Column System
117

118
Flexible column definitions supporting grouping, pinning, custom templates, sorting, filtering, and advanced column operations.
119

120
```typescript { .api }
121
interface ColumnSystem {
122
  getColumns(): Promise<RevoGrid.ColumnRegular[]>;
123
  updateColumns(cols: RevoGrid.ColumnRegular[]): Promise<void>;
124
  getColumnStore(type?: RevoGrid.DimensionCols): Promise<ColumnSource>;
125
  updateColumnSorting(column: RevoGrid.ColumnRegular, index: number, order: 'asc'|'desc', additive: boolean): Promise<RevoGrid.ColumnRegular>;
126
}
127

128
interface RevoGrid.ColumnRegular {
129
  prop?: RevoGrid.ColumnProp;
130
  name?: RevoGrid.DataFormat;
131
  size?: number;
132
  readonly?: RevoGrid.ReadOnlyFormat;
133
  sortable?: boolean;
134
  filter?: boolean | string | string[];
135
  cellTemplate?: RevoGrid.CellTemplateFunc<VNode>;
136
  columnTemplate?: RevoGrid.ColumnTemplateFunc<VNode>;
137
}
138
```
139

140
[Column System](./column-system.md)
141

142
### Selection and Focus
143

144
Advanced selection capabilities including cell focus, range selection, keyboard navigation, and programmatic selection control.
145

146
```typescript { .api }
147
interface SelectionFocus {
148
  setCellsFocus(cellStart?: Selection.Cell, cellEnd?: Selection.Cell, colType?: string, rowType?: string): Promise<void>;
149
  getFocused(): Promise<FocusedData|null>;
150
  clearFocus(): Promise<void>;
151
  getSelectedRange(): Promise<Selection.RangeArea|null>;
152
}
153

154
interface Selection.Cell {
155
  x: number; // Column index
156
  y: number; // Row index
157
}
158

159
interface Selection.RangeArea {
160
  x: number;   // Start column
161
  y: number;   // Start row  
162
  x1: number;  // End column
163
  y1: number;  // End row
164
}
165
```
166

167
[Selection and Focus](./selection-focus.md)
168

169
### Cell Editing
170

171
Rich editing system with custom editors, validation, batch editing, and comprehensive edit lifecycle management.
172

173
```typescript { .api }
174
interface CellEditing {
175
  setCellEdit(rgRow: number, prop: RevoGrid.ColumnProp, rowSource?: RevoGrid.DimensionRows): Promise<void>;
176
  editors: Edition.Editors;
177
}
178

179
interface Edition.EditorBase {
180
  element?: Element | null;
181
  editCell?: Edition.EditCell;
182
  render(createElement?: HyperFunc<VNode>): VNode | VNode[] | string | void;
183
}
184

185
interface Edition.Editors {
186
  [name: string]: Edition.EditorCtr;
187
}
188
```
189

190
[Cell Editing](./cell-editing.md)
191

192
### Navigation and Scrolling
193

194
Programmatic navigation with virtual scrolling support, coordinate-based scrolling, and viewport management.
195

196
```typescript { .api }
197
interface NavigationScrolling {
198
  scrollToRow(coordinate?: number): Promise<void>;
199
  scrollToColumnIndex(coordinate?: number): Promise<void>;
200
  scrollToColumnProp(prop: RevoGrid.ColumnProp): Promise<void>;
201
  scrollToCoordinate(cell: Partial<Selection.Cell>): Promise<void>;
202
}
203
```
204

205
[Navigation and Scrolling](./navigation-scrolling.md)
206

207
### Plugin System
208

209
Extensible plugin architecture with built-in plugins for filtering, sorting, export, grouping, and auto-sizing.
210

211
```typescript { .api }
212
interface PluginSystem {
213
  plugins: RevoPlugin.PluginClass[];
214
  getPlugins(): Promise<RevoPlugin.Plugin[]>;
215
  
216
  // Built-in plugin configurations
217
  autoSizeColumn: boolean | AutoSizeColumnConfig;
218
  filter: boolean | ColumnFilterConfig;
219
  exporting: boolean;
220
  grouping: GroupingOptions;
221
}
222

223
abstract class RevoPlugin.Plugin {
224
  constructor(revogrid: HTMLRevoGridElement);
225
  addEventListener(name: string, func: (e: CustomEvent) => void): void;
226
  removeEventListener(type: string): void;
227
  emit(eventName: string, detail?: any): CustomEvent;
228
  destroy(): void;
229
}
230
```
231

232
[Plugin System](./plugin-system.md)
233

234
### Event System
235

236
Comprehensive event system covering all grid operations including data changes, column operations, selection, editing, and user interactions.
237

238
```typescript { .api }
239
interface EventSystem {
240
  // Edit events
241
  beforeedit: Edition.BeforeSaveDataDetails;
242
  afteredit: Edition.BeforeSaveDataDetails | Edition.BeforeRangeSaveDataDetails;
243
  
244
  // Selection events  
245
  beforecellfocus: Edition.BeforeSaveDataDetails;
246
  afterfocus: {model: any, column: RevoGrid.ColumnRegular};
247
  
248
  // Data events
249
  beforesourceset: {type: RevoGrid.DimensionRows, source: RevoGrid.DataType[]};
250
  aftersourceset: {type: RevoGrid.DimensionRows, source: RevoGrid.DataType[]};
251
  
252
  // Column events
253
  aftercolumnresize: Record<RevoGrid.ColumnProp, RevoGrid.ColumnRegular>;
254
  headerclick: RevoGrid.ColumnRegular;
255
}
256
```
257

258
[Event System](./event-system.md)
259

260
### Types and Interfaces
261

262
Complete type system with comprehensive interfaces for all grid components, data structures, and configuration options.
263

264
```typescript { .api }
265
namespace RevoGrid {
266
  type DataType = {[T in ColumnProp]: DataFormat};
267
  type ColumnProp = string | number;
268
  type DimensionRows = 'rgRow' | 'rowPinStart' | 'rowPinEnd';
269
  type DimensionCols = 'colPinStart' | 'rgCol' | 'colPinEnd';
270
  
271
  interface ViewportState {
272
    items: VirtualPositionItem[];
273
    realCount: number;
274
    virtualSize: number;
275
    lastCoordinate: number;
276
  }
277
}
278
```
279

280
[Types and Interfaces](./types-interfaces.md)