@molecule/app-spreadsheet-grid-vue 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 +421 -4
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -1,11 +1,428 @@
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:25.055Z
7
+ -->
8
+
1
9
  # @molecule/app-spreadsheet-grid-vue
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 Vue.
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
+ ```ts
34
+ import { createApp, defineComponent, h, ref } from 'vue'
35
+
36
+ import {
37
+ SpreadsheetGrid,
38
+ type CellMap,
39
+ type SpreadsheetSelection,
40
+ } from '@molecule/app-spreadsheet-grid-vue'
41
+
42
+ const Sheet = defineComponent({
43
+ setup() {
44
+ const cells = ref<CellMap>(new Map())
45
+ const selection = ref<SpreadsheetSelection>({ r1: 0, c1: 0, r2: 0, c2: 0 })
46
+ return () =>
47
+ h(SpreadsheetGrid, {
48
+ rows: 1000,
49
+ columns: 26,
50
+ cells: cells.value,
51
+ selection: selection.value,
52
+ frozenRows: 1,
53
+ frozenCols: 1,
54
+ onCellChange: (ref, value) => {
55
+ const next = new Map(cells.value)
56
+ if (value === null) next.delete(ref)
57
+ else next.set(ref, value)
58
+ cells.value = next
59
+ },
60
+ onSelectionChange: (next) => {
61
+ selection.value = next
62
+ },
63
+ })
64
+ },
65
+ })
66
+
67
+ createApp(Sheet).mount('#app')
68
+ ```
69
+
70
+ ## Type
71
+
72
+ `feature`
4
73
 
74
+ ## Installation
75
+
76
+ ```bash
77
+ npm install @molecule/app-spreadsheet-grid-vue @molecule/app-clipboard @molecule/app-i18n @molecule/app-ui @molecule/app-ui-vue @molecule/app-vue vue
5
78
  ```
6
- npm install @molecule/app-spreadsheet-grid-vue
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
+ }
7
97
  ```
8
98
 
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.
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) => VNodeChild
141
+ }
142
+ ```
143
+
144
+ ### Types
145
+
146
+ #### `CellRef`
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
153
+ ```
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
163
+ ```
164
+
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
+ #### `columnLetter(col)`
177
+
178
+ Convert a 0-indexed column number to its A1 letter (`0` → `'A'`, `25` →
179
+ `'Z'`, `26` → `'AA'`, `701` → `'ZZ'`, `702` → `'AAA'`).
180
+
181
+ ```typescript
182
+ function columnLetter(col: number): string
183
+ ```
184
+
185
+ - `col` — 0-indexed column number.
186
+
187
+ **Returns:** Uppercase A1 column letter.
188
+
189
+ #### `cellRef(row, col)`
190
+
191
+ Build an A1 reference from 0-indexed row and column numbers.
192
+
193
+ ```typescript
194
+ function cellRef(row: number, col: number): CellRef
195
+ ```
196
+
197
+ - `row` — 0-indexed row number.
198
+ - `col` — 0-indexed column number.
199
+
200
+ **Returns:** A1-style cell reference (e.g. `'B3'`).
201
+
202
+ #### `normalizeSelection(sel)`
203
+
204
+ Normalize a possibly-inverted selection so `r1 <= r2 && c1 <= c2`.
205
+
206
+ ```typescript
207
+ function normalizeSelection(sel: SpreadsheetSelection): SpreadsheetSelection
208
+ ```
209
+
210
+ - `sel` — Raw selection (anchor and focus).
211
+
212
+ **Returns:** Selection with `r1`/`c1` as top-left and `r2`/`c2` as bottom-right.
213
+
214
+ #### `isInSelection(sel, row, col)`
215
+
216
+ Test whether `(row, col)` is inside the selection.
217
+
218
+ ```typescript
219
+ function isInSelection(sel: SpreadsheetSelection, row: number, col: number): boolean
220
+ ```
221
+
222
+ - `sel` — Selection to test against.
223
+ - `row` — 0-indexed row number.
224
+ - `col` — 0-indexed column number.
225
+
226
+ **Returns:** `true` when the cell is in the selection.
227
+
228
+ #### `formatCellValue(value)`
229
+
230
+ Format a cell value for display. `null`/`undefined` render as the empty
231
+ string; booleans become `TRUE`/`FALSE` (matching common spreadsheet
232
+ tools); numbers and strings stringify as-is.
233
+
234
+ ```typescript
235
+ function formatCellValue(value: CellValue | undefined): string
236
+ ```
237
+
238
+ - `value` — The raw cell value.
239
+
240
+ **Returns:** Display string.
241
+
242
+ #### `parseClipboardTsv(text)`
243
+
244
+ Parse a TSV (tab-separated values) string into a 2D array of strings.
245
+ Empty trailing lines are ignored. Used to ingest clipboard paste data.
246
+
247
+ ```typescript
248
+ function parseClipboardTsv(text: string): string[][]
249
+ ```
250
+
251
+ - `text` — Clipboard text (typically TSV).
252
+
253
+ **Returns:** 2D array of cell strings — `rows[r][c]`.
254
+
255
+ #### `serializeSelectionTsv(cells, sel)`
256
+
257
+ Serialize a rectangular selection to TSV (tab-separated values) so it
258
+ can round-trip with Excel/Google Sheets via the system clipboard.
259
+
260
+ ```typescript
261
+ function serializeSelectionTsv(cells: CellMap, sel: SpreadsheetSelection): string
262
+ ```
263
+
264
+ - `cells` — Source cell map.
265
+ - `sel` — Selection to serialize.
266
+
267
+ **Returns:** TSV-formatted string with `\n` row separators.
268
+
269
+ #### `computeVisibleRange(scroll, viewport, itemSize, total, overscan)`
270
+
271
+ Compute the inclusive `[start, end]` window of indices to render given
272
+ the scroll offset, viewport size, item size, and total count. Adds an
273
+ `overscan` margin on each side so newly-visible cells are pre-rendered
274
+ during fast scrolls.
275
+
276
+ ```typescript
277
+ function computeVisibleRange(
278
+ scroll: number,
279
+ viewport: number,
280
+ itemSize: number,
281
+ total: number,
282
+ overscan?: number,
283
+ ): [number, number]
284
+ ```
285
+
286
+ - `scroll` — Current scroll position (px).
287
+ - `viewport` — Viewport size (px) along the scroll axis.
288
+ - `itemSize` — Per-item size (px) along the scroll axis.
289
+ - `total` — Total number of items.
290
+ - `overscan` — Extra items to render on each side (default `2`).
291
+
292
+ **Returns:** `[startIndex, endIndex]` (both inclusive, clamped to `[0, total)`).
293
+
294
+ ### Constants
295
+
296
+ #### `SpreadsheetGrid`
297
+
298
+ High-performance virtualized spreadsheet cell grid.
299
+
300
+ Renders an `rows × columns` grid backed by a sparse `Map<cellRef, value>`,
301
+ with frozen rows/columns, range selection (click + drag, Shift+click),
302
+ copy/paste through the system clipboard as TSV, and in-cell editing
303
+ (double-click → input; Enter commits, Escape cancels).
304
+
305
+ Only the cells inside the visible viewport (plus a small overscan margin)
306
+ are rendered, so 10k × 10k grids stay responsive.
307
+
308
+ ```typescript
309
+ const SpreadsheetGrid: DefineComponent<
310
+ ExtractPropTypes<{
311
+ rows: { type: NumberConstructor; required: true }
312
+ columns: { type: NumberConstructor; required: true }
313
+ cells: { type: PropType<CellMap>; required: true }
314
+ onCellChange: { type: PropType<SpreadsheetGridProps['onCellChange']>; required: true }
315
+ selection: { type: PropType<SpreadsheetSelection>; required: true }
316
+ onSelectionChange: { type: PropType<SpreadsheetGridProps['onSelectionChange']>; required: true }
317
+ frozenRows: { type: NumberConstructor; default: number }
318
+ frozenCols: { type: NumberConstructor; default: number }
319
+ cellWidth: { type: NumberConstructor; default: number }
320
+ cellHeight: { type: NumberConstructor; default: number }
321
+ gutterWidth: { type: NumberConstructor; default: number }
322
+ headerHeight: { type: NumberConstructor; default: number }
323
+ viewportWidth: { type: NumberConstructor; default: number }
324
+ viewportHeight: { type: NumberConstructor; default: number }
325
+ dataMolId: StringConstructor
326
+ renderCell: PropType<SpreadsheetGridProps['renderCell']>
327
+ }>,
328
+ () => VNode,
329
+ {},
330
+ {},
331
+ {},
332
+ ComponentOptionsMixin,
333
+ ComponentOptionsMixin,
334
+ {},
335
+ string,
336
+ PublicProps,
337
+ Readonly<
338
+ ExtractPropTypes<{
339
+ rows: { type: NumberConstructor; required: true }
340
+ columns: { type: NumberConstructor; required: true }
341
+ cells: { type: PropType<CellMap>; required: true }
342
+ onCellChange: { type: PropType<SpreadsheetGridProps['onCellChange']>; required: true }
343
+ selection: { type: PropType<SpreadsheetSelection>; required: true }
344
+ onSelectionChange: {
345
+ type: PropType<SpreadsheetGridProps['onSelectionChange']>
346
+ required: true
347
+ }
348
+ frozenRows: { type: NumberConstructor; default: number }
349
+ frozenCols: { type: NumberConstructor; default: number }
350
+ cellWidth: { type: NumberConstructor; default: number }
351
+ cellHeight: { type: NumberConstructor; default: number }
352
+ gutterWidth: { type: NumberConstructor; default: number }
353
+ headerHeight: { type: NumberConstructor; default: number }
354
+ viewportWidth: { type: NumberConstructor; default: number }
355
+ viewportHeight: { type: NumberConstructor; default: number }
356
+ dataMolId: StringConstructor
357
+ renderCell: PropType<SpreadsheetGridProps['renderCell']>
358
+ }>
359
+ > &
360
+ Readonly<{}>,
361
+ {
362
+ frozenRows: number
363
+ frozenCols: number
364
+ cellWidth: number
365
+ cellHeight: number
366
+ gutterWidth: number
367
+ headerHeight: number
368
+ viewportWidth: number
369
+ viewportHeight: number
370
+ },
371
+ {},
372
+ {},
373
+ {},
374
+ string,
375
+ ComponentProvideOptions,
376
+ true,
377
+ {},
378
+ any
379
+ >
380
+ ```
381
+
382
+ - `props` — Component props (see {@link SpreadsheetGridProps}).
383
+
384
+ **Returns:** The spreadsheet grid component.
385
+
386
+ ## Injection Notes
387
+
388
+ ### Requirements
389
+
390
+ Peer dependencies:
391
+
392
+ - `@molecule/app-clipboard` ^1.0.1
393
+ - `@molecule/app-i18n` ^1.0.1
394
+ - `@molecule/app-ui` ^1.3.11
395
+ - `@molecule/app-ui-vue` ^1.1.0
396
+ - `@molecule/app-vue` ^3.5.0
397
+ - `vue` ^3.4.0
398
+
399
+ ### Runtime Dependencies
400
+
401
+ - `@molecule/app-clipboard`
402
+ - `@molecule/app-i18n`
403
+ - `@molecule/app-ui`
404
+ - `@molecule/app-ui-vue`
405
+ - `@molecule/app-vue`
406
+ - `vue`
407
+
408
+ - Must render with a ClassMap bond wired (`getClassMap()` throws
409
+ otherwise), and inside the app's i18n provider (or with the bonded one).
410
+ - The viewport is FIXED-PIXEL: `viewportWidth`/`viewportHeight`
411
+ (defaults 720×360) — the grid does not auto-size to its container.
412
+ Measure the container and pass px if you need it to fill.
413
+ - Copy (Ctrl/Cmd+C) writes TSV through `copyTextWithFallback()` from
414
+ `@molecule/app-clipboard`, which uses the bonded clipboard provider with
415
+ a selection-and-copy fallback and never throws. Paste is handled through
416
+ the native paste event, so the grid container must have focus (click a
417
+ cell first). Keyboard support is Enter/F2 (edit) + copy/paste only; there
418
+ is NO arrow-key cell navigation.
419
+ - Committed edits and pasted cells auto-coerce number-like strings to
420
+ numbers (`'42'` → `42`); empty string clears the cell (`null`).
421
+ - Gridlines/selection/header styling uses Material-3 design-token
422
+ utilities (`bg-surface`, `border-outline-variant`, …). Apps whose
423
+ Tailwind theme does not define those tokens (the minimal scaffold
424
+ theme does not) get a functional but unstyled grid.
425
+
426
+ ## Translations
10
427
 
11
- License: Apache-2.0
428
+ 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-vue",
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-vue",
6
6
  "type": "module",
@@ -56,10 +56,10 @@
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-ui": "1.4.0",
59
+ "@molecule/app-ui": "1.5.0",
60
60
  "@molecule/app-ui-tailwind": "1.3.0",
61
- "@molecule/app-ui-vue": "1.1.5",
62
- "@molecule/app-vue": "3.7.2",
61
+ "@molecule/app-ui-vue": "1.2.1",
62
+ "@molecule/app-vue": "3.9.0",
63
63
  "@types/node": "26.6.5",
64
64
  "jsdom": "30.1.3",
65
65
  "typescript": "6.0.3",