@reforgium/data-grid 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
ADDED
|
@@ -0,0 +1,219 @@
|
|
|
1
|
+
# @reforgium/data-grid
|
|
2
|
+
|
|
3
|
+
**High-performance data grid for Angular (20+).**
|
|
4
|
+
|
|
5
|
+
`@reforgium/data-grid` provides a flexible and performant component for displaying large tabular datasets.
|
|
6
|
+
It focuses on smooth scrolling, predictable layout, and full control over rendering via templates and signals.
|
|
7
|
+
|
|
8
|
+
Designed for **real-world datasets**, not demo tables.
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## Features
|
|
13
|
+
|
|
14
|
+
- Horizontal and vertical scrolling
|
|
15
|
+
- Virtual row rendering (smooth, no jumps)
|
|
16
|
+
- Infinity scroll (loads data when reaching the bottom)
|
|
17
|
+
- Jitter-free fixed (sticky) columns
|
|
18
|
+
- Two-line headers max, with ellipsis + tooltip
|
|
19
|
+
- Column expanders (hidden columns via toggler)
|
|
20
|
+
- Scrollable overlay scrollbar
|
|
21
|
+
- Pinned rows (top and bottom)
|
|
22
|
+
- Custom templates for headers, cells, pinned rows
|
|
23
|
+
- Row selection (single / multi)
|
|
24
|
+
- Signals-based API (`signal()` first)
|
|
25
|
+
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
## Installation
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
npm install @reforgium/data-grid
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
```ts
|
|
35
|
+
import { DataGrid } from '@reforgium/data-grid';
|
|
36
|
+
|
|
37
|
+
@Component({ imports: [DataGrid]})
|
|
38
|
+
export class SomeComponent {}
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
```html
|
|
42
|
+
<re-data-grid
|
|
43
|
+
[data]="users"
|
|
44
|
+
[columns]="columns"
|
|
45
|
+
[pageSize]="50"
|
|
46
|
+
[loading]="loading"
|
|
47
|
+
(loadData)="loadMore($event)"
|
|
48
|
+
/>
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
---
|
|
52
|
+
|
|
53
|
+
## Configuration
|
|
54
|
+
|
|
55
|
+
### Inputs
|
|
56
|
+
|
|
57
|
+
| Parameter | Type | Default | Description |
|
|
58
|
+
|-------------------|----------------------------------------------|-------------|---------------------------------|
|
|
59
|
+
| data | `T[]` | `[]` | Data array to render |
|
|
60
|
+
| columns | `GridColumns<T>` | `[]` | Column configuration |
|
|
61
|
+
| pinnedRows | `GridPinnedRows<T>` | `undefined` | Top / bottom pinned rows |
|
|
62
|
+
| mode | `'default' \| 'infinity' \| 'none'` | `'default'` | Grid operation mode |
|
|
63
|
+
| pageSize | `number` | `20` | Page size |
|
|
64
|
+
| pageStartFromZero | `boolean` | `false` | Start page index from 0 |
|
|
65
|
+
| hasIndexColumn | `boolean` | `false` | Show index column |
|
|
66
|
+
| selection | `{ mode: 'single' \| 'multi', key: string }` | `undefined` | Row selection configuration |
|
|
67
|
+
| fillHeight | `boolean` | `false` | Fill available container height |
|
|
68
|
+
| loading | `boolean` | `false` | Loading state |
|
|
69
|
+
| rowKey | `(item: T) => string` | `undefined` | Unique row key resolver |
|
|
70
|
+
|
|
71
|
+
### Outputs
|
|
72
|
+
|
|
73
|
+
| Event | Type | Description |
|
|
74
|
+
|--------------|-------------------------|------------------|
|
|
75
|
+
| cellClick | `GridCellClickEvent<T>` | Cell click |
|
|
76
|
+
| rowClick | `GridRowClickEvent<T>` | Row click |
|
|
77
|
+
| sortChange | `GridSortEvent<T>` | Sort change |
|
|
78
|
+
| pageChange | `GridPageChangeEvent` | Page change |
|
|
79
|
+
| selectChange | `GridSelectEvent<T>` | Selection change |
|
|
80
|
+
|
|
81
|
+
### Templates
|
|
82
|
+
|
|
83
|
+
| Directive | Parameters | Description |
|
|
84
|
+
|--------------------|--------------------|----------------------------------------|
|
|
85
|
+
| ssDataGridHeader | value: string | Column header template |
|
|
86
|
+
| ssDataGridTypeCell | value: any, row: T | Cell template for specific column type |
|
|
87
|
+
| ssDataGridEmpty | - | Empty state template |
|
|
88
|
+
| ssDataGridLoading | - | Loading state template |
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
### CSS Variables
|
|
92
|
+
|
|
93
|
+
Layout / Appearance:
|
|
94
|
+
- `--re-data-grid-height` — component height / max-height (`400px`).
|
|
95
|
+
- `--re-data-grid-rounded` — border radius (`var(--radius-md, 6px)`).
|
|
96
|
+
- `--re-data-grid-surface` — table background (`#fff`).
|
|
97
|
+
- `--re-data-grid-active` — active color (`#2a90f4`).
|
|
98
|
+
|
|
99
|
+
Empty / Loading States:
|
|
100
|
+
- `--re-data-grid-empty-color` — empty text color (`#777`)
|
|
101
|
+
- `--re-data-grid-loading-color` — loading indicator color (`#444`)
|
|
102
|
+
- `--re-data-grid-loading-surface` — loading overlay (`rgba(255,255,255,0.5)`)
|
|
103
|
+
|
|
104
|
+
Scrollbar:
|
|
105
|
+
- `--re-data-grid-scrollbar-size` — track size (`10px`)
|
|
106
|
+
- `--re-data-grid-scrollbar-offset` — inner offset (`2px`)
|
|
107
|
+
- `--re-data-grid-scrollbar-thumb-size` — thumb size (`8px`)
|
|
108
|
+
- `--re-data-grid-scrollbar-thumb-color` — thumb color (`rgba(0,0,0,0.35)`)
|
|
109
|
+
- `--re-data-grid-scrollbar-thumb-rounded` — thumb radius (`4px`)
|
|
110
|
+
|
|
111
|
+
Header:
|
|
112
|
+
- `--re-data-grid-header-height` — header row height (`40px`)
|
|
113
|
+
- `--re-data-grid-header-separator-color` — separator color (`#ccc`)
|
|
114
|
+
- `--re-data-grid-header-separator` — separator line
|
|
115
|
+
- `--re-data-grid-header-surface` — header background (`#fff`)
|
|
116
|
+
|
|
117
|
+
Header Cells:
|
|
118
|
+
|
|
119
|
+
- `--re-data-grid-header-cell-font-weight` — font weight; `600`.
|
|
120
|
+
- `--re-data-grid-header-cell-font-size` — font size; `0.8rem`.
|
|
121
|
+
- `--re-data-grid-header-cell-color` — text color; `#000`.
|
|
122
|
+
- `--re-data-grid-header-cell-surface` — cell background; `#fafafa`.
|
|
123
|
+
|
|
124
|
+
Footer:
|
|
125
|
+
|
|
126
|
+
- `--re-data-grid-footer-separator-color` — separator color; `#ccc`.
|
|
127
|
+
- `--re-data-grid-footer-separator` — separator line; `1px solid var(--re-data-grid-footer-separator-color)`.
|
|
128
|
+
- `--re-data-grid-footer-surface` — footer background; `#fff`.
|
|
129
|
+
|
|
130
|
+
Rows:
|
|
131
|
+
|
|
132
|
+
- `--re-data-grid-row-separator-color` — row separator color; `#bbb`.
|
|
133
|
+
- `--re-data-grid-row-separator` — separator line; `1px solid var(--re-data-grid-row-separator-color)`.
|
|
134
|
+
- `--re-data-grid-row-odd-surface` — odd rows background; `var(--re-data-grid-cell-surface)`.
|
|
135
|
+
|
|
136
|
+
Columns:
|
|
137
|
+
- `--re-data-grid-column-separator-color` — column divider color `transparent`.
|
|
138
|
+
- `--re-data-grid-column-separator` — column divider `1px solid var(--re-data-grid-column-separator-color)`.
|
|
139
|
+
- `--re-data-grid-column-odd-surface` — odd column background `var(--re-data-grid-cell-surface)`.
|
|
140
|
+
|
|
141
|
+
Cells:
|
|
142
|
+
|
|
143
|
+
- `--re-data-grid-cell-paddings` — inner paddings; `0.4rem 0.625rem`.
|
|
144
|
+
- `--re-data-grid-cell-font-weight` — font weight; `400`.
|
|
145
|
+
- `--re-data-grid-cell-font-size` — font size; `0.75rem`.
|
|
146
|
+
- `--re-data-grid-cell-color` — text color; `#000`.
|
|
147
|
+
- `--re-data-grid-cell-surface` — cell background; `#fff`.
|
|
148
|
+
|
|
149
|
+
Sticky Cells:
|
|
150
|
+
|
|
151
|
+
- `--re-data-grid-sticky-cell-surface` — sticky cells background; `#fdfdfd`.
|
|
152
|
+
- `--re-data-grid-sticky-cell-left-shadow` — left shadow; `2px 0 2px rgba(0, 0, 0, 0.03)`.
|
|
153
|
+
- `--re-data-grid-sticky-cell-right-shadow` — right shadow; `-2px 0 2px rgba(0, 0, 0, 0.03)`.
|
|
154
|
+
|
|
155
|
+
Pinned Sections:
|
|
156
|
+
|
|
157
|
+
- `--re-data-grid-pinned-surface` — pinned sections background; `#fcfcfc`.
|
|
158
|
+
- `--re-data-grid-pinned-separator-color` — separator color; `#eee`.
|
|
159
|
+
- `--re-data-grid-pinned-separator` — separator line; `1px solid var(--re-data-grid-pinned-separator-color)`.
|
|
160
|
+
|
|
161
|
+
Misc:
|
|
162
|
+
|
|
163
|
+
- `--re-data-grid-expander-color` — expander indicator color; `var(--primary-color, currentColor)`.
|
|
164
|
+
|
|
165
|
+
## Theming via CSS Variables
|
|
166
|
+
|
|
167
|
+
Variables can be overridden globally (`:root`) or per grid container.
|
|
168
|
+
|
|
169
|
+
### Quick Theming Examples
|
|
170
|
+
|
|
171
|
+
Dark Theme Example:
|
|
172
|
+
```css
|
|
173
|
+
.dark .data-grid {
|
|
174
|
+
--re-data-grid-surface: #121416;
|
|
175
|
+
--re-data-grid-header-cell-surface: #161a1d;
|
|
176
|
+
--re-data-grid-cell-color: #eef2f6;
|
|
177
|
+
--re-data-grid-row-separator-color: #262a2e;
|
|
178
|
+
--re-data-grid-column-separator-color: #1e2226;
|
|
179
|
+
}
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
Compact Mode Example:
|
|
183
|
+
```css
|
|
184
|
+
.compact-grid {
|
|
185
|
+
--re-data-grid-header-height: 32px;
|
|
186
|
+
--re-data-grid-cell-font-size: 12px;
|
|
187
|
+
--re-data-grid-cell-paddings: 2px 8px;
|
|
188
|
+
}
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
## Custom Template Examples
|
|
192
|
+
|
|
193
|
+
Cell Template by Type
|
|
194
|
+
```html
|
|
195
|
+
<ng-template ssDataGridTypeCell type="link" let-value let-row="row">
|
|
196
|
+
<a [href]="value" target="_blank">{{ value }}</a>
|
|
197
|
+
</ng-template>
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
Custom Header Template:
|
|
201
|
+
```html
|
|
202
|
+
<ng-template ssDataGridHeader key="name" let-value>
|
|
203
|
+
<span class="header-with-icon">
|
|
204
|
+
<re-icon name="user"></re-icon>
|
|
205
|
+
{{ value }}
|
|
206
|
+
</span>
|
|
207
|
+
</ng-template>
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
## Compatibility
|
|
211
|
+
|
|
212
|
+
- Angular: 20+
|
|
213
|
+
- Rendering: ESM
|
|
214
|
+
- Signals: required
|
|
215
|
+
- Zone.js: optional
|
|
216
|
+
|
|
217
|
+
|
|
218
|
+
## License
|
|
219
|
+
MIT
|