@molecule/app-spreadsheet-grid-solid 0.0.1-stage → 1.1.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 +349 -4
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -1,11 +1,356 @@
|
|
|
1
|
+
<!--
|
|
2
|
+
AUTO-GENERATED — DO NOT EDIT THIS FILE.
|
|
3
|
+
Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
|
|
4
|
+
Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
|
|
5
|
+
To change this document, edit the module-level JSDoc in src/index.ts.
|
|
6
|
+
Generated: 2026-11-21T12:47:24.577Z
|
|
7
|
+
-->
|
|
8
|
+
|
|
1
9
|
# @molecule/app-spreadsheet-grid-solid
|
|
2
10
|
|
|
3
|
-
High-performance virtualized spreadsheet cell grid
|
|
11
|
+
High-performance virtualized spreadsheet cell grid for Solid.
|
|
12
|
+
|
|
13
|
+
Exports:
|
|
14
|
+
|
|
15
|
+
- `<SpreadsheetGrid>` — the grid component (virtualized cells, frozen
|
|
16
|
+
rows/columns, range selection, copy/paste as TSV, in-cell editing).
|
|
17
|
+
- Types: `SpreadsheetGridProps`, `SpreadsheetSelection`, `CellMap`,
|
|
18
|
+
`CellRef`, `CellValue`.
|
|
19
|
+
- Helpers: `cellRef()`, `columnLetter()`, `normalizeSelection()`,
|
|
20
|
+
`isInSelection()`, `formatCellValue()`, `parseClipboardTsv()`,
|
|
21
|
+
`serializeSelectionTsv()`, `computeVisibleRange()`.
|
|
22
|
+
|
|
23
|
+
Pairs with `@molecule/api-formula-engine` for formula evaluation —
|
|
24
|
+
pass evaluated `cells` plus an optional `renderCell` to display
|
|
25
|
+
formula results.
|
|
26
|
+
|
|
27
|
+
> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
|
|
28
|
+
> It is written to be read by coding agents as much as by people, and is generated from this
|
|
29
|
+
> package's source — edit `src/index.ts` JSDoc, not this file.
|
|
30
|
+
|
|
31
|
+
## Quick Start
|
|
32
|
+
|
|
33
|
+
```tsx
|
|
34
|
+
import { createSignal } from 'solid-js'
|
|
35
|
+
|
|
36
|
+
import {
|
|
37
|
+
SpreadsheetGrid,
|
|
38
|
+
type CellMap,
|
|
39
|
+
type SpreadsheetSelection,
|
|
40
|
+
} from '@molecule/app-spreadsheet-grid-solid'
|
|
41
|
+
|
|
42
|
+
export function Sheet() {
|
|
43
|
+
const [cells, setCells] = createSignal<CellMap>(new Map())
|
|
44
|
+
const [selection, setSelection] = createSignal<SpreadsheetSelection>({
|
|
45
|
+
r1: 0,
|
|
46
|
+
c1: 0,
|
|
47
|
+
r2: 0,
|
|
48
|
+
c2: 0,
|
|
49
|
+
})
|
|
50
|
+
return (
|
|
51
|
+
<SpreadsheetGrid
|
|
52
|
+
rows={1000}
|
|
53
|
+
columns={26}
|
|
54
|
+
cells={cells()}
|
|
55
|
+
selection={selection()}
|
|
56
|
+
frozenRows={1}
|
|
57
|
+
frozenCols={1}
|
|
58
|
+
onCellChange={(ref, value) => {
|
|
59
|
+
const next = new Map(cells())
|
|
60
|
+
if (value === null) next.delete(ref)
|
|
61
|
+
else next.set(ref, value)
|
|
62
|
+
setCells(next)
|
|
63
|
+
}}
|
|
64
|
+
onSelectionChange={(next) => setSelection(next)}
|
|
65
|
+
/>
|
|
66
|
+
)
|
|
67
|
+
}
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## Type
|
|
71
|
+
|
|
72
|
+
`feature`
|
|
73
|
+
|
|
74
|
+
## Installation
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
npm install @molecule/app-spreadsheet-grid-solid @molecule/app-clipboard @molecule/app-i18n @molecule/app-solid @molecule/app-ui @molecule/app-ui-solid solid-js
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
## API
|
|
81
|
+
|
|
82
|
+
### Interfaces
|
|
83
|
+
|
|
84
|
+
#### `SpreadsheetSelection`
|
|
85
|
+
|
|
86
|
+
Inclusive rectangular selection — `r1`/`c1` is the anchor (where the
|
|
87
|
+
drag started) and `r2`/`c2` is the focus (where it ended). Both are
|
|
88
|
+
0-indexed. A single-cell selection has `r1 === r2 && c1 === c2`.
|
|
89
|
+
|
|
90
|
+
```typescript
|
|
91
|
+
interface SpreadsheetSelection {
|
|
92
|
+
r1: number
|
|
93
|
+
c1: number
|
|
94
|
+
r2: number
|
|
95
|
+
c2: number
|
|
96
|
+
}
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
#### `SpreadsheetGridProps`
|
|
100
|
+
|
|
101
|
+
Props accepted by the {@link SpreadsheetGrid} component.
|
|
102
|
+
|
|
103
|
+
```typescript
|
|
104
|
+
interface SpreadsheetGridProps {
|
|
105
|
+
/** Total number of rows in the grid. */
|
|
106
|
+
rows: number
|
|
107
|
+
/** Total number of columns in the grid. */
|
|
108
|
+
columns: number
|
|
109
|
+
/** Sparse cell-data map. Cells not present render as empty. */
|
|
110
|
+
cells: CellMap
|
|
111
|
+
/** Called when the user commits an edit (Enter, Tab, or focus loss). */
|
|
112
|
+
onCellChange: (ref: CellRef, value: CellValue) => void
|
|
113
|
+
/** Current selection. */
|
|
114
|
+
selection: SpreadsheetSelection
|
|
115
|
+
/** Called when the user changes the selection (click, drag, Shift+click). */
|
|
116
|
+
onSelectionChange: (selection: SpreadsheetSelection) => void
|
|
117
|
+
/** Number of rows frozen at the top (default `0`). */
|
|
118
|
+
frozenRows?: number
|
|
119
|
+
/** Number of columns frozen on the left (default `0`). */
|
|
120
|
+
frozenCols?: number
|
|
121
|
+
/** Per-cell width in pixels (default `96`). */
|
|
122
|
+
cellWidth?: number
|
|
123
|
+
/** Per-cell height in pixels (default `28`). */
|
|
124
|
+
cellHeight?: number
|
|
125
|
+
/** Width of the row-number gutter on the left (default `48`). */
|
|
126
|
+
gutterWidth?: number
|
|
127
|
+
/** Height of the column-letter header (default `28`). */
|
|
128
|
+
headerHeight?: number
|
|
129
|
+
/** Visible viewport width in pixels (default `720`). */
|
|
130
|
+
viewportWidth?: number
|
|
131
|
+
/** Visible viewport height in pixels (default `360`). */
|
|
132
|
+
viewportHeight?: number
|
|
133
|
+
/** `data-mol-id` for AI-agent selectors. */
|
|
134
|
+
dataMolId?: string
|
|
135
|
+
/**
|
|
136
|
+
* Optional cell renderer. Receives the cached display string plus the
|
|
137
|
+
* raw value. Defaults to plain text. Use to render formula results
|
|
138
|
+
* (`'=A1+B1'` → evaluated number) or custom formatting.
|
|
139
|
+
*/
|
|
140
|
+
renderCell?: (value: CellValue | undefined, ref: CellRef) => JSX.Element
|
|
141
|
+
}
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
### Types
|
|
145
|
+
|
|
146
|
+
#### `CellRef`
|
|
4
147
|
|
|
148
|
+
Cell reference in A1 notation (e.g. `'A1'`, `'AB17'`). Column letters are
|
|
149
|
+
uppercase; row numbers are 1-indexed.
|
|
150
|
+
|
|
151
|
+
```typescript
|
|
152
|
+
type CellRef = string
|
|
5
153
|
```
|
|
6
|
-
|
|
154
|
+
|
|
155
|
+
#### `CellValue`
|
|
156
|
+
|
|
157
|
+
Primitive value stored in a cell. Formula strings start with `'='` —
|
|
158
|
+
evaluation is the host application's responsibility (typically wired
|
|
159
|
+
through `@molecule/api-formula-engine`).
|
|
160
|
+
|
|
161
|
+
```typescript
|
|
162
|
+
type CellValue = string | number | boolean | null
|
|
7
163
|
```
|
|
8
164
|
|
|
9
|
-
|
|
165
|
+
#### `CellMap`
|
|
166
|
+
|
|
167
|
+
Sparse map from `CellRef` to value. Cells not present in the map render
|
|
168
|
+
as empty. Using a `Map` keeps update cost O(1) regardless of grid size.
|
|
169
|
+
|
|
170
|
+
```typescript
|
|
171
|
+
type CellMap = Map<CellRef, CellValue>
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
### Functions
|
|
175
|
+
|
|
176
|
+
#### `SpreadsheetGrid(props)`
|
|
177
|
+
|
|
178
|
+
High-performance virtualized spreadsheet cell grid.
|
|
179
|
+
|
|
180
|
+
Renders an `rows × columns` grid backed by a sparse `Map<cellRef, value>`,
|
|
181
|
+
with frozen rows/columns, range selection (click + drag, Shift+click),
|
|
182
|
+
copy/paste through the system clipboard as TSV, and in-cell editing
|
|
183
|
+
(double-click → input; Enter commits, Escape cancels).
|
|
184
|
+
|
|
185
|
+
Only the cells inside the visible viewport (plus a small overscan margin)
|
|
186
|
+
are rendered, so 10k × 10k grids stay responsive.
|
|
187
|
+
|
|
188
|
+
```typescript
|
|
189
|
+
function SpreadsheetGrid(props: SpreadsheetGridProps): JSX.Element
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
- `props` — Component props (see {@link SpreadsheetGridProps}).
|
|
193
|
+
|
|
194
|
+
**Returns:** The rendered spreadsheet grid.
|
|
195
|
+
|
|
196
|
+
#### `columnLetter(col)`
|
|
197
|
+
|
|
198
|
+
Convert a 0-indexed column number to its A1 letter (`0` → `'A'`, `25` →
|
|
199
|
+
`'Z'`, `26` → `'AA'`, `701` → `'ZZ'`, `702` → `'AAA'`).
|
|
200
|
+
|
|
201
|
+
```typescript
|
|
202
|
+
function columnLetter(col: number): string
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
- `col` — 0-indexed column number.
|
|
206
|
+
|
|
207
|
+
**Returns:** Uppercase A1 column letter.
|
|
208
|
+
|
|
209
|
+
#### `cellRef(row, col)`
|
|
210
|
+
|
|
211
|
+
Build an A1 reference from 0-indexed row and column numbers.
|
|
212
|
+
|
|
213
|
+
```typescript
|
|
214
|
+
function cellRef(row: number, col: number): CellRef
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
- `row` — 0-indexed row number.
|
|
218
|
+
- `col` — 0-indexed column number.
|
|
219
|
+
|
|
220
|
+
**Returns:** A1-style cell reference (e.g. `'B3'`).
|
|
221
|
+
|
|
222
|
+
#### `normalizeSelection(sel)`
|
|
223
|
+
|
|
224
|
+
Normalize a possibly-inverted selection so `r1 <= r2 && c1 <= c2`.
|
|
225
|
+
|
|
226
|
+
```typescript
|
|
227
|
+
function normalizeSelection(sel: SpreadsheetSelection): SpreadsheetSelection
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
- `sel` — Raw selection (anchor and focus).
|
|
231
|
+
|
|
232
|
+
**Returns:** Selection with `r1`/`c1` as top-left and `r2`/`c2` as bottom-right.
|
|
233
|
+
|
|
234
|
+
#### `isInSelection(sel, row, col)`
|
|
235
|
+
|
|
236
|
+
Test whether `(row, col)` is inside the selection.
|
|
237
|
+
|
|
238
|
+
```typescript
|
|
239
|
+
function isInSelection(sel: SpreadsheetSelection, row: number, col: number): boolean
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
- `sel` — Selection to test against.
|
|
243
|
+
- `row` — 0-indexed row number.
|
|
244
|
+
- `col` — 0-indexed column number.
|
|
245
|
+
|
|
246
|
+
**Returns:** `true` when the cell is in the selection.
|
|
247
|
+
|
|
248
|
+
#### `formatCellValue(value)`
|
|
249
|
+
|
|
250
|
+
Format a cell value for display. `null`/`undefined` render as the empty
|
|
251
|
+
string; booleans become `TRUE`/`FALSE` (matching common spreadsheet
|
|
252
|
+
tools); numbers and strings stringify as-is.
|
|
253
|
+
|
|
254
|
+
```typescript
|
|
255
|
+
function formatCellValue(value: CellValue | undefined): string
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
- `value` — The raw cell value.
|
|
259
|
+
|
|
260
|
+
**Returns:** Display string.
|
|
261
|
+
|
|
262
|
+
#### `parseClipboardTsv(text)`
|
|
263
|
+
|
|
264
|
+
Parse a TSV (tab-separated values) string into a 2D array of strings.
|
|
265
|
+
Empty trailing lines are ignored. Used to ingest clipboard paste data.
|
|
266
|
+
|
|
267
|
+
```typescript
|
|
268
|
+
function parseClipboardTsv(text: string): string[][]
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
- `text` — Clipboard text (typically TSV).
|
|
272
|
+
|
|
273
|
+
**Returns:** 2D array of cell strings — `rows[r][c]`.
|
|
274
|
+
|
|
275
|
+
#### `serializeSelectionTsv(cells, sel)`
|
|
276
|
+
|
|
277
|
+
Serialize a rectangular selection to TSV (tab-separated values) so it
|
|
278
|
+
can round-trip with Excel/Google Sheets via the system clipboard.
|
|
279
|
+
|
|
280
|
+
```typescript
|
|
281
|
+
function serializeSelectionTsv(cells: CellMap, sel: SpreadsheetSelection): string
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
- `cells` — Source cell map.
|
|
285
|
+
- `sel` — Selection to serialize.
|
|
286
|
+
|
|
287
|
+
**Returns:** TSV-formatted string with `\n` row separators.
|
|
288
|
+
|
|
289
|
+
#### `computeVisibleRange(scroll, viewport, itemSize, total, overscan)`
|
|
290
|
+
|
|
291
|
+
Compute the inclusive `[start, end]` window of indices to render given
|
|
292
|
+
the scroll offset, viewport size, item size, and total count. Adds an
|
|
293
|
+
`overscan` margin on each side so newly-visible cells are pre-rendered
|
|
294
|
+
during fast scrolls.
|
|
295
|
+
|
|
296
|
+
```typescript
|
|
297
|
+
function computeVisibleRange(
|
|
298
|
+
scroll: number,
|
|
299
|
+
viewport: number,
|
|
300
|
+
itemSize: number,
|
|
301
|
+
total: number,
|
|
302
|
+
overscan?: number,
|
|
303
|
+
): [number, number]
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
- `scroll` — Current scroll position (px).
|
|
307
|
+
- `viewport` — Viewport size (px) along the scroll axis.
|
|
308
|
+
- `itemSize` — Per-item size (px) along the scroll axis.
|
|
309
|
+
- `total` — Total number of items.
|
|
310
|
+
- `overscan` — Extra items to render on each side (default `2`).
|
|
311
|
+
|
|
312
|
+
**Returns:** `[startIndex, endIndex]` (both inclusive, clamped to `[0, total)`).
|
|
313
|
+
|
|
314
|
+
## Injection Notes
|
|
315
|
+
|
|
316
|
+
### Requirements
|
|
317
|
+
|
|
318
|
+
Peer dependencies:
|
|
319
|
+
|
|
320
|
+
- `@molecule/app-clipboard` ^1.0.1
|
|
321
|
+
- `@molecule/app-i18n` ^1.0.1
|
|
322
|
+
- `@molecule/app-solid` ^3.5.0
|
|
323
|
+
- `@molecule/app-ui` ^1.3.11
|
|
324
|
+
- `@molecule/app-ui-solid` ^1.1.0
|
|
325
|
+
- `solid-js` ^1.8.0
|
|
326
|
+
|
|
327
|
+
### Runtime Dependencies
|
|
328
|
+
|
|
329
|
+
- `@molecule/app-clipboard`
|
|
330
|
+
- `@molecule/app-i18n`
|
|
331
|
+
- `@molecule/app-solid`
|
|
332
|
+
- `@molecule/app-ui`
|
|
333
|
+
- `@molecule/app-ui-solid`
|
|
334
|
+
- `solid-js`
|
|
335
|
+
|
|
336
|
+
- Must render with a ClassMap bond wired (`getClassMap()` throws
|
|
337
|
+
otherwise), and inside the app's i18n provider (or with the bonded one).
|
|
338
|
+
- The viewport is FIXED-PIXEL: `viewportWidth`/`viewportHeight`
|
|
339
|
+
(defaults 720×360) — the grid does not auto-size to its container.
|
|
340
|
+
Measure the container and pass px if you need it to fill.
|
|
341
|
+
- Copy (Ctrl/Cmd+C) writes TSV through `copyTextWithFallback()` from
|
|
342
|
+
`@molecule/app-clipboard`, which uses the bonded clipboard provider with
|
|
343
|
+
a selection-and-copy fallback and never throws. Paste is handled through
|
|
344
|
+
the native paste event, so the grid container must have focus (click a
|
|
345
|
+
cell first). Keyboard support is Enter/F2 (edit) + copy/paste only; there
|
|
346
|
+
is NO arrow-key cell navigation.
|
|
347
|
+
- Committed edits and pasted cells auto-coerce number-like strings to
|
|
348
|
+
numbers (`'42'` → `42`); empty string clears the cell (`null`).
|
|
349
|
+
- Gridlines/selection/header styling uses Material-3 design-token
|
|
350
|
+
utilities (`bg-surface`, `border-outline-variant`, …). Apps whose
|
|
351
|
+
Tailwind theme does not define those tokens (the minimal scaffold
|
|
352
|
+
theme does not) get a functional but unstyled grid.
|
|
353
|
+
|
|
354
|
+
## Translations
|
|
10
355
|
|
|
11
|
-
|
|
356
|
+
Translation strings are provided by `@molecule/app-locales-spreadsheet-grid`.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@molecule/app-spreadsheet-grid-solid",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "1.1.0",
|
|
4
4
|
"description": "High-performance virtualized spreadsheet cell grid with frozen rows/columns, range selection, copy/paste as TSV, and in-cell editing — pairs with @molecule/api-formula-engine",
|
|
5
5
|
"homepage": "https://www.molecule.dev/packages/app-spreadsheet-grid-solid",
|
|
6
6
|
"type": "module",
|
|
@@ -56,9 +56,9 @@
|
|
|
56
56
|
"@molecule/app-framework-conformance": "0.0.0",
|
|
57
57
|
"@molecule/app-i18n": "1.2.2",
|
|
58
58
|
"@molecule/app-icons": "1.0.4",
|
|
59
|
-
"@molecule/app-solid": "3.
|
|
60
|
-
"@molecule/app-ui": "1.
|
|
61
|
-
"@molecule/app-ui-solid": "1.1
|
|
59
|
+
"@molecule/app-solid": "3.9.0",
|
|
60
|
+
"@molecule/app-ui": "1.5.0",
|
|
61
|
+
"@molecule/app-ui-solid": "1.2.1",
|
|
62
62
|
"@molecule/app-ui-tailwind": "1.3.0",
|
|
63
63
|
"@types/node": "26.6.5",
|
|
64
64
|
"jsdom": "30.1.3",
|