@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.
Files changed (2) hide show
  1. package/README.md +349 -4
  2. 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 with frozen rows/columns, range selection, copy/paste as TSV, and in-cell editing — pairs with @molecule/api-formula-engine
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
- npm install @molecule/app-spreadsheet-grid-solid
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
- Part of the [Molecule](https://www.molecule.dev) package fleet. This page carries the manifest summary; the full generated documentation ships with the package's first committed version.
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
- License: Apache-2.0
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": "0.0.1-stage",
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.7.2",
60
- "@molecule/app-ui": "1.4.0",
61
- "@molecule/app-ui-solid": "1.1.5",
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",