@molecule/app-spreadsheet-grid-angular 0.0.0-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 CHANGED
@@ -1,3 +1,533 @@
1
- # Temporary Holding Version
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.268Z
7
+ -->
2
8
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
9
+ # @molecule/app-spreadsheet-grid-angular
10
+
11
+ High-performance virtualized spreadsheet cell grid for Angular.
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 { Component, signal } from '@angular/core'
35
+ import { SpreadsheetGrid } from '@molecule/app-spreadsheet-grid-angular'
36
+ import type { CellMap, SpreadsheetSelection } from '@molecule/app-spreadsheet-grid-angular'
37
+
38
+ @Component({
39
+ selector: 'app-sheet',
40
+ standalone: true,
41
+ imports: [SpreadsheetGrid],
42
+ template: `
43
+ <div
44
+ mol-spreadsheet-grid
45
+ [rows]="1000"
46
+ [columns]="26"
47
+ [cells]="cells()"
48
+ [frozenRows]="1"
49
+ [frozenCols]="1"
50
+ [selection]="selection()"
51
+ [onCellChange]="onCellChange"
52
+ [onSelectionChange]="onSelectionChange"
53
+ ></div>
54
+ `,
55
+ })
56
+ export class Sheet {
57
+ readonly cells = signal<CellMap>(new Map())
58
+ readonly selection = signal<SpreadsheetSelection>({ r1: 0, c1: 0, r2: 0, c2: 0 })
59
+
60
+ readonly onCellChange = (ref: string, value: string | number | boolean | null): void => {
61
+ const next = new Map(this.cells())
62
+ if (value === null) next.delete(ref)
63
+ else next.set(ref, value)
64
+ this.cells.set(next)
65
+ }
66
+
67
+ readonly onSelectionChange = (next: SpreadsheetSelection): void => {
68
+ this.selection.set(next)
69
+ }
70
+ }
71
+ ```
72
+
73
+ ## Type
74
+
75
+ `feature`
76
+
77
+ ## Installation
78
+
79
+ ```bash
80
+ npm install @molecule/app-spreadsheet-grid-angular @angular/common @angular/core @angular/platform-browser @molecule/app-angular @molecule/app-clipboard @molecule/app-i18n @molecule/app-ui @molecule/app-ui-angular
81
+ ```
82
+
83
+ ## API
84
+
85
+ ### Interfaces
86
+
87
+ #### `SpreadsheetSelection`
88
+
89
+ Inclusive rectangular selection — `r1`/`c1` is the anchor (where the
90
+ drag started) and `r2`/`c2` is the focus (where it ended). Both are
91
+ 0-indexed. A single-cell selection has `r1 === r2 && c1 === c2`.
92
+
93
+ ```typescript
94
+ interface SpreadsheetSelection {
95
+ r1: number
96
+ c1: number
97
+ r2: number
98
+ c2: number
99
+ }
100
+ ```
101
+
102
+ #### `SpreadsheetGridProps`
103
+
104
+ Props accepted by {@link SpreadsheetGrid} — the same props
105
+ `@molecule/app-spreadsheet-grid-react` accepts. React's `renderCell` render
106
+ prop is an `ng-template` receiving the value as `$implicit`/`a0` and the A1
107
+ reference as `a1`.
108
+
109
+ ```typescript
110
+ interface SpreadsheetGridProps {
111
+ /** Total number of rows in the grid. */
112
+ rows: number
113
+ /** Total number of columns in the grid. */
114
+ columns: number
115
+ /** Sparse cell-data map. Cells not present render as empty. */
116
+ cells: CellMap
117
+ /** Called when the user commits an edit (Enter, Tab, or focus loss). */
118
+ onCellChange: (ref: CellRef, value: CellValue) => void
119
+ /** Current selection. */
120
+ selection: SpreadsheetSelection
121
+ /** Called when the user changes the selection (click, drag, Shift+click). */
122
+ onSelectionChange: (selection: SpreadsheetSelection) => void
123
+ /** Number of rows frozen at the top (default `0`). */
124
+ frozenRows?: number
125
+ /** Number of columns frozen on the left (default `0`). */
126
+ frozenCols?: number
127
+ /** Per-cell width in pixels (default `96`). */
128
+ cellWidth?: number
129
+ /** Per-cell height in pixels (default `28`). */
130
+ cellHeight?: number
131
+ /** Width of the row-number gutter on the left (default `48`). */
132
+ gutterWidth?: number
133
+ /** Height of the column-letter header (default `28`). */
134
+ headerHeight?: number
135
+ /** Visible viewport width in pixels (default `720`). */
136
+ viewportWidth?: number
137
+ /** Visible viewport height in pixels (default `360`). */
138
+ viewportHeight?: number
139
+ /** `data-mol-id` for AI-agent selectors. */
140
+ dataMolId?: string
141
+ /**
142
+ * Optional cell renderer (`ng-template`): `$implicit`/`a0` is the raw value,
143
+ * `a1` the A1 reference. Defaults to plain text.
144
+ */
145
+ renderCell?: TemplateRef<unknown> | null
146
+ }
147
+ ```
148
+
149
+ ### Types
150
+
151
+ #### `CellRef`
152
+
153
+ Cell reference in A1 notation (e.g. `'A1'`, `'AB17'`). Column letters are
154
+ uppercase; row numbers are 1-indexed.
155
+
156
+ ```typescript
157
+ type CellRef = string
158
+ ```
159
+
160
+ #### `CellValue`
161
+
162
+ Primitive value stored in a cell. Formula strings start with `'='` —
163
+ evaluation is the host application's responsibility (typically wired
164
+ through `@molecule/api-formula-engine`).
165
+
166
+ ```typescript
167
+ type CellValue = string | number | boolean | null
168
+ ```
169
+
170
+ #### `CellMap`
171
+
172
+ Sparse map from `CellRef` to value. Cells not present in the map render
173
+ as empty. Using a `Map` keeps update cost O(1) regardless of grid size.
174
+
175
+ ```typescript
176
+ type CellMap = Map<CellRef, CellValue>
177
+ ```
178
+
179
+ ### Classes
180
+
181
+ #### `SpreadsheetGrid`
182
+
183
+ SpreadsheetGrid component.
184
+
185
+ High-performance virtualized spreadsheet cell grid: the host IS React's root
186
+ `<div role="grid">` (`div[mol-spreadsheet-grid]`), so no wrapper element
187
+ exists. Renders an `rows × columns` grid backed by a sparse
188
+ `Map<cellRef, value>`, with frozen rows/columns, range selection (click +
189
+ drag, Shift+click), copy/paste through the system clipboard as TSV, and
190
+ in-cell editing (double-click → input; Enter commits, Escape cancels).
191
+ Only the cells inside the visible viewport (plus a small overscan margin)
192
+ are rendered.
193
+
194
+ React's callbacks are inputs (they keep their React names and their argument
195
+ lists); React's `renderCell` render prop is an `ng-template`.
196
+
197
+ ```typescript
198
+ @Component({
199
+ selector: 'div[mol-spreadsheet-grid]',
200
+ standalone: true,
201
+ imports: [NgTemplateOutlet],
202
+ inputs: [
203
+ 'rows',
204
+ 'columns',
205
+ 'cells',
206
+ 'onCellChange',
207
+ 'selection',
208
+ 'onSelectionChange',
209
+ 'frozenRows',
210
+ 'frozenCols',
211
+ 'cellWidth',
212
+ 'cellHeight',
213
+ 'gutterWidth',
214
+ 'headerHeight',
215
+ 'viewportWidth',
216
+ 'viewportHeight',
217
+ 'dataMolId',
218
+ 'renderCell',
219
+ ],
220
+ host: {
221
+ role: 'grid',
222
+ '[attr.tabindex]': '0',
223
+ '[attr.data-mol-id]': 'dataMolId ?? "spreadsheet-grid"',
224
+ '[attr.aria-rowcount]': 'rows',
225
+ '[attr.aria-colcount]': 'columns',
226
+ '[attr.aria-label]': 'label()',
227
+ '[class]': 'plan.rootClasses',
228
+ '[style]': 'plan.rootStyle',
229
+ '(keydown)': 'onKeydown($event)',
230
+ '(paste)': 'onPaste($event)',
231
+ '(mouseup)': 'onMouseUp()',
232
+ },
233
+ template: `<ng-template #cellTpl let-cell><div role="gridcell" [attr.data-mol-id]="'spreadsheet-grid-cell-' + cell.ref" [attr.tabindex]="cell.anchor ? 0 : -1" [attr.aria-selected]="cell.selected ? 'true' : null" [class]="cell.classes" [style]="cell.style" (mousedown)="onCellMouseDown(cell, $event)" (mouseenter)="onCellMouseEnter(cell, $event)" (dblclick)="beginEdit(cell.row, cell.col)">@if (editorAt(cell.row, cell.col); as open) {<input [attr.data-mol-id]="'spreadsheet-grid-editor-' + cell.ref" [class]="plan.editorClasses" [attr.value]="open.draft" (input)="onDraftInput($event)" (blur)="commitEdit()" (keydown)="onEditorKeydown($event)" [attr.aria-label]="cellEditorLabel(cell.ref)" />} @else {<div [class]="plan.contentClasses">@if (renderCellTemplate(); as cellRenderer) {<ng-container [ngTemplateOutlet]="cellRenderer" [ngTemplateOutletContext]="cellContext(cell)"></ng-container>} @else {<ng-container>{{ cell.text }}</ng-container>}</div>}</div></ng-template><div aria-hidden="true" [class]="plan.cornerClasses" [style]="plan.cornerStyle"></div><div role="row" aria-rowindex="1" [class]="plan.headerLaneClasses" [style]="plan.headerLaneStyle">@for (header of plan.frozenHeaderCells; track header.key) {<div role="columnheader" [attr.aria-colindex]="header.index + 1" [class]="header.classes" [style]="header.style">{{ header.text }}</div>}<div [style]="plan.headerScrollerStyle">@for (header of plan.scrollingHeaderCells; track header.key) {<div role="columnheader" [attr.aria-colindex]="header.index + 1" [class]="header.classes" [style]="header.style">{{ header.text }}</div>}</div></div><div aria-hidden="true" [class]="plan.gutterLaneClasses" [style]="plan.gutterLaneStyle">@for (label of plan.frozenGutterCells; track label.key) {<div [class]="label.classes" [style]="label.style">{{ label.text }}</div>}<div [style]="plan.gutterScrollerStyle">@for (label of plan.scrollingGutterCells; track label.key) {<div [class]="label.classes" [style]="label.style">{{ label.text }}</div>}</div></div>@if (plan.showFrozenRows) {<div [style]="plan.frozenRowsRegionStyle"><div [style]="plan.frozenRowsInnerStyle">@for (cell of plan.frozenRowsCells; track cell.ref) {<ng-container [ngTemplateOutlet]="cellTpl" [ngTemplateOutletContext]="{ $implicit: cell }"></ng-container>}</div></div>}@if (plan.showFrozenCols) {<div [style]="plan.frozenColsRegionStyle"><div [style]="plan.frozenColsInnerStyle">@for (cell of plan.frozenColsCells; track cell.ref) {<ng-container [ngTemplateOutlet]="cellTpl" [ngTemplateOutletContext]="{ $implicit: cell }"></ng-container>}</div></div>}@if (plan.showFrozenCorner) {<div [style]="plan.frozenCornerStyle">@for (cell of plan.frozenCornerCells; track cell.ref) {<ng-container [ngTemplateOutlet]="cellTpl" [ngTemplateOutletContext]="{ $implicit: cell }"></ng-container>}</div>}<div data-mol-id="spreadsheet-grid-scroll" [style]="plan.scrollRegionStyle" (scroll)="onScroll($event)"><div [style]="plan.scrollSpacerStyle">@for (cell of plan.mainCells; track cell.ref) {<ng-container [ngTemplateOutlet]="cellTpl" [ngTemplateOutletContext]="{ $implicit: cell }"></ng-container>}</div></div><span [class]="plan.totalClasses" [style]="plan.totalStyle" aria-hidden="true">{{ plan.totalText }}</span>`,
234
+ })
235
+ export class SpreadsheetGrid implements DoCheck {
236
+ rows!: number
237
+ columns!: number
238
+ cells!: CellMap
239
+ onCellChange?: (ref: string, value: CellValue) => void
240
+ selection!: SpreadsheetSelection
241
+ onSelectionChange?: (selection: SpreadsheetSelection) => void
242
+ frozenRows?: number
243
+ frozenCols?: number
244
+ cellWidth?: number
245
+ cellHeight?: number
246
+ gutterWidth?: number
247
+ headerHeight?: number
248
+ viewportWidth?: number
249
+ viewportHeight?: number
250
+ dataMolId?: string
251
+ renderCell?: TemplateRef<unknown> | null
252
+
253
+ protected readonly scrollLeft = signal(0)
254
+ protected readonly scrollTop = signal(0)
255
+ protected readonly editing = signal<Editing | null>(null)
256
+
257
+ private readonly host = inject<ElementRef<HTMLElement>>(ElementRef)
258
+ private readonly injector = inject(Injector)
259
+ private readonly i18n = useTranslation()
260
+
261
+ private dragAnchor: { row: number; col: number } | null = null
262
+ private currentPlan: GridLayout | null = null
263
+
264
+ protected get plan(): GridLayout {
265
+ if (!this.currentPlan) this.currentPlan = computeLayout(this.geometry(), this.cm())
266
+ return this.currentPlan
267
+ }
268
+
269
+ ngDoCheck(): void {
270
+ this.currentPlan = computeLayout(this.geometry(), this.cm())
271
+ const open = this.editing()
272
+ const field = this.host.nativeElement.querySelector('input')
273
+ if (open && field instanceof HTMLInputElement && field.value !== open.draft)
274
+ field.value = open.draft
275
+ }
276
+
277
+ cm(): UIClassMap {
278
+ return getClassMap()
279
+ }
280
+
281
+ label(): string {
282
+ return this.i18n.t('spreadsheetGrid.label', undefined, { defaultValue: 'Spreadsheet' })
283
+ }
284
+
285
+ cellEditorLabel(ref: string): string {
286
+ return this.i18n.t(
287
+ 'spreadsheetGrid.cellEditor',
288
+ { ref },
289
+ {
290
+ defaultValue: 'Edit cell {{ref}}',
291
+ },
292
+ )
293
+ }
294
+
295
+ editorAt(row: number, col: number): Editing | null {
296
+ const current = this.editing()
297
+ return current && current.row === row && current.col === col ? current : null
298
+ }
299
+
300
+ renderCellTemplate(): TemplateRef<unknown> | null {
301
+ return isTemplate(this.renderCell) ? this.renderCell : null
302
+ }
303
+
304
+ cellContext(cell: GridCell): Record<string, unknown> {
305
+ return { $implicit: cell.value, a0: cell.value, a1: cell.ref, a2: undefined }
306
+ }
307
+
308
+ private geometry(): GridGeometry {
309
+ return {
310
+ rows: this.rows,
311
+ columns: this.columns,
312
+ cells: this.cells,
313
+ selection: this.selection,
314
+ frozenRows: this.frozenRows ?? 0,
315
+ frozenCols: this.frozenCols ?? 0,
316
+ cellWidth: this.cellWidth ?? 96,
317
+ cellHeight: this.cellHeight ?? 28,
318
+ gutterWidth: this.gutterWidth ?? 48,
319
+ headerHeight: this.headerHeight ?? 28,
320
+ viewportWidth: this.viewportWidth ?? 720,
321
+ viewportHeight: this.viewportHeight ?? 360,
322
+ scrollLeft: this.scrollLeft(),
323
+ scrollTop: this.scrollTop(),
324
+ editing: this.editing(),
325
+ }
326
+ }
327
+
328
+ beginEdit(row: number, col: number): void {
329
+ this.editing.set({
330
+ row,
331
+ col,
332
+ draft: formatCellValue(this.cells.get(cellRef(row, col))),
333
+ })
334
+ afterNextRender(
335
+ () => {
336
+ const field = this.host.nativeElement.querySelector('input')
337
+ if (field instanceof HTMLInputElement) {
338
+ field.focus()
339
+ field.select()
340
+ }
341
+ },
342
+ { injector: this.injector },
343
+ )
344
+ }
345
+
346
+ commitEdit(): void {
347
+ const current = this.editing()
348
+ if (!current) return
349
+ const ref = cellRef(current.row, current.col)
350
+ const trimmed = current.draft
351
+ let next: CellValue
352
+ if (trimmed === '') next = null
353
+ else if (/^-?\d+(\.\d+)?$/.test(trimmed)) next = Number(trimmed)
354
+ else next = trimmed
355
+ this.onCellChange?.(ref, next)
356
+ this.editing.set(null)
357
+ }
358
+
359
+ cancelEdit(): void {
360
+ this.editing.set(null)
361
+ }
362
+ // … truncated — 10 more members: onCellMouseDown, onCellMouseEnter, onMouseUp, onKeydown, onEditorKeydown, onDraftInput, onPaste, onScroll, handleCopy, handlePaste; the full declaration is in node_modules/@molecule/app-spreadsheet-grid-angular/dist/spreadsheet-grid.component.d.ts
363
+ ```
364
+
365
+ _(Member comments are left out to fit; the full declaration is in `node_modules/@molecule/app-spreadsheet-grid-angular/dist/spreadsheet-grid.component.d.ts`.)_
366
+
367
+ ### Functions
368
+
369
+ #### `columnLetter(col)`
370
+
371
+ Convert a 0-indexed column number to its A1 letter (`0` → `'A'`, `25` →
372
+ `'Z'`, `26` → `'AA'`, `701` → `'ZZ'`, `702` → `'AAA'`).
373
+
374
+ ```typescript
375
+ function columnLetter(col: number): string
376
+ ```
377
+
378
+ - `col` — 0-indexed column number.
379
+
380
+ **Returns:** Uppercase A1 column letter.
381
+
382
+ #### `cellRef(row, col)`
383
+
384
+ Build an A1 reference from 0-indexed row and column numbers.
385
+
386
+ ```typescript
387
+ function cellRef(row: number, col: number): CellRef
388
+ ```
389
+
390
+ - `row` — 0-indexed row number.
391
+ - `col` — 0-indexed column number.
392
+
393
+ **Returns:** A1-style cell reference (e.g. `'B3'`).
394
+
395
+ #### `normalizeSelection(sel)`
396
+
397
+ Normalize a possibly-inverted selection so `r1 <= r2 && c1 <= c2`.
398
+
399
+ ```typescript
400
+ function normalizeSelection(sel: SpreadsheetSelection): SpreadsheetSelection
401
+ ```
402
+
403
+ - `sel` — Raw selection (anchor and focus).
404
+
405
+ **Returns:** Selection with `r1`/`c1` as top-left and `r2`/`c2` as bottom-right.
406
+
407
+ #### `isInSelection(sel, row, col)`
408
+
409
+ Test whether `(row, col)` is inside the selection.
410
+
411
+ ```typescript
412
+ function isInSelection(sel: SpreadsheetSelection, row: number, col: number): boolean
413
+ ```
414
+
415
+ - `sel` — Selection to test against.
416
+ - `row` — 0-indexed row number.
417
+ - `col` — 0-indexed column number.
418
+
419
+ **Returns:** `true` when the cell is in the selection.
420
+
421
+ #### `formatCellValue(value)`
422
+
423
+ Format a cell value for display. `null`/`undefined` render as the empty
424
+ string; booleans become `TRUE`/`FALSE` (matching common spreadsheet
425
+ tools); numbers and strings stringify as-is.
426
+
427
+ ```typescript
428
+ function formatCellValue(value: CellValue | undefined): string
429
+ ```
430
+
431
+ - `value` — The raw cell value.
432
+
433
+ **Returns:** Display string.
434
+
435
+ #### `parseClipboardTsv(text)`
436
+
437
+ Parse a TSV (tab-separated values) string into a 2D array of strings.
438
+ Empty trailing lines are ignored. Used to ingest clipboard paste data.
439
+
440
+ ```typescript
441
+ function parseClipboardTsv(text: string): string[][]
442
+ ```
443
+
444
+ - `text` — Clipboard text (typically TSV).
445
+
446
+ **Returns:** 2D array of cell strings — `rows[r][c]`.
447
+
448
+ #### `serializeSelectionTsv(cells, sel)`
449
+
450
+ Serialize a rectangular selection to TSV (tab-separated values) so it
451
+ can round-trip with Excel/Google Sheets via the system clipboard.
452
+
453
+ ```typescript
454
+ function serializeSelectionTsv(cells: CellMap, sel: SpreadsheetSelection): string
455
+ ```
456
+
457
+ - `cells` — Source cell map.
458
+ - `sel` — Selection to serialize.
459
+
460
+ **Returns:** TSV-formatted string with `\n` row separators.
461
+
462
+ #### `computeVisibleRange(scroll, viewport, itemSize, total, overscan)`
463
+
464
+ Compute the inclusive `[start, end]` window of indices to render given
465
+ the scroll offset, viewport size, item size, and total count. Adds an
466
+ `overscan` margin on each side so newly-visible cells are pre-rendered
467
+ during fast scrolls.
468
+
469
+ ```typescript
470
+ function computeVisibleRange(
471
+ scroll: number,
472
+ viewport: number,
473
+ itemSize: number,
474
+ total: number,
475
+ overscan?: number,
476
+ ): [number, number]
477
+ ```
478
+
479
+ - `scroll` — Current scroll position (px).
480
+ - `viewport` — Viewport size (px) along the scroll axis.
481
+ - `itemSize` — Per-item size (px) along the scroll axis.
482
+ - `total` — Total number of items.
483
+ - `overscan` — Extra items to render on each side (default `2`).
484
+
485
+ **Returns:** `[startIndex, endIndex]` (both inclusive, clamped to `[0, total)`).
486
+
487
+ ## Injection Notes
488
+
489
+ ### Requirements
490
+
491
+ Peer dependencies:
492
+
493
+ - `@angular/common` ^22.0.0
494
+ - `@angular/core` ^22.0.0
495
+ - `@angular/platform-browser` ^22.0.0
496
+ - `@molecule/app-angular` ^3.5.0
497
+ - `@molecule/app-clipboard` ^1.0.1
498
+ - `@molecule/app-i18n` ^1.0.1
499
+ - `@molecule/app-ui` ^1.3.11
500
+ - `@molecule/app-ui-angular` ^1.1.0
501
+
502
+ ### Runtime Dependencies
503
+
504
+ - `@angular/common`
505
+ - `@angular/core`
506
+ - `@angular/platform-browser`
507
+ - `@molecule/app-angular`
508
+ - `@molecule/app-clipboard`
509
+ - `@molecule/app-i18n`
510
+ - `@molecule/app-ui`
511
+ - `@molecule/app-ui-angular`
512
+
513
+ - Must render with a ClassMap bond wired (`getClassMap()` throws
514
+ otherwise), and inside the app's i18n provider (or with the bonded one).
515
+ - The viewport is FIXED-PIXEL: `viewportWidth`/`viewportHeight`
516
+ (defaults 720×360) — the grid does not auto-size to its container.
517
+ Measure the container and pass px if you need it to fill.
518
+ - Copy (Ctrl/Cmd+C) writes TSV through `copyTextWithFallback()` from
519
+ `@molecule/app-clipboard`, which uses the bonded clipboard provider with
520
+ a selection-and-copy fallback and never throws. Paste is handled through
521
+ the native paste event, so the grid container must have focus (click a
522
+ cell first). Keyboard support is Enter/F2 (edit) + copy/paste only; there
523
+ is NO arrow-key cell navigation.
524
+ - Committed edits and pasted cells auto-coerce number-like strings to
525
+ numbers (`'42'` → `42`); empty string clears the cell (`null`).
526
+ - Gridlines/selection/header styling uses Material-3 design-token
527
+ utilities (`bg-surface`, `border-outline-variant`, …). Apps whose
528
+ Tailwind theme does not define those tokens (the minimal scaffold
529
+ theme does not) get a functional but unstyled grid.
530
+
531
+ ## Translations
532
+
533
+ Translation strings are provided by `@molecule/app-locales-spreadsheet-grid`.
@@ -0,0 +1,82 @@
1
+ /**
2
+ * High-performance virtualized spreadsheet cell grid for Angular.
3
+ *
4
+ * Exports:
5
+ * - `<SpreadsheetGrid>` — the grid component (virtualized cells, frozen
6
+ * rows/columns, range selection, copy/paste as TSV, in-cell editing).
7
+ * - Types: `SpreadsheetGridProps`, `SpreadsheetSelection`, `CellMap`,
8
+ * `CellRef`, `CellValue`.
9
+ * - Helpers: `cellRef()`, `columnLetter()`, `normalizeSelection()`,
10
+ * `isInSelection()`, `formatCellValue()`, `parseClipboardTsv()`,
11
+ * `serializeSelectionTsv()`, `computeVisibleRange()`.
12
+ *
13
+ * Pairs with `@molecule/api-formula-engine` for formula evaluation —
14
+ * pass evaluated `cells` plus an optional `renderCell` to display
15
+ * formula results.
16
+ *
17
+ * @example
18
+ * ```ts
19
+ * import { Component, signal } from '@angular/core'
20
+ * import { SpreadsheetGrid } from '@molecule/app-spreadsheet-grid-angular'
21
+ * import type { CellMap, SpreadsheetSelection } from '@molecule/app-spreadsheet-grid-angular'
22
+ *
23
+ * @Component({
24
+ * selector: 'app-sheet',
25
+ * standalone: true,
26
+ * imports: [SpreadsheetGrid],
27
+ * template: `
28
+ * <div
29
+ * mol-spreadsheet-grid
30
+ * [rows]="1000"
31
+ * [columns]="26"
32
+ * [cells]="cells()"
33
+ * [frozenRows]="1"
34
+ * [frozenCols]="1"
35
+ * [selection]="selection()"
36
+ * [onCellChange]="onCellChange"
37
+ * [onSelectionChange]="onSelectionChange"
38
+ * ></div>
39
+ * `,
40
+ * })
41
+ * export class Sheet {
42
+ * readonly cells = signal<CellMap>(new Map())
43
+ * readonly selection = signal<SpreadsheetSelection>({ r1: 0, c1: 0, r2: 0, c2: 0 })
44
+ *
45
+ * readonly onCellChange = (ref: string, value: string | number | boolean | null): void => {
46
+ * const next = new Map(this.cells())
47
+ * if (value === null) next.delete(ref)
48
+ * else next.set(ref, value)
49
+ * this.cells.set(next)
50
+ * }
51
+ *
52
+ * readonly onSelectionChange = (next: SpreadsheetSelection): void => {
53
+ * this.selection.set(next)
54
+ * }
55
+ * }
56
+ * ```
57
+ *
58
+ * @remarks
59
+ * - Must render with a ClassMap bond wired (`getClassMap()` throws
60
+ * otherwise), and inside the app's i18n provider (or with the bonded one).
61
+ * - The viewport is FIXED-PIXEL: `viewportWidth`/`viewportHeight`
62
+ * (defaults 720×360) — the grid does not auto-size to its container.
63
+ * Measure the container and pass px if you need it to fill.
64
+ * - Copy (Ctrl/Cmd+C) writes TSV through `copyTextWithFallback()` from
65
+ * `@molecule/app-clipboard`, which uses the bonded clipboard provider with
66
+ * a selection-and-copy fallback and never throws. Paste is handled through
67
+ * the native paste event, so the grid container must have focus (click a
68
+ * cell first). Keyboard support is Enter/F2 (edit) + copy/paste only; there
69
+ * is NO arrow-key cell navigation.
70
+ * - Committed edits and pasted cells auto-coerce number-like strings to
71
+ * numbers (`'42'` → `42`); empty string clears the cell (`null`).
72
+ * - Gridlines/selection/header styling uses Material-3 design-token
73
+ * utilities (`bg-surface`, `border-outline-variant`, …). Apps whose
74
+ * Tailwind theme does not define those tokens (the minimal scaffold
75
+ * theme does not) get a functional but unstyled grid.
76
+ *
77
+ * @module
78
+ */
79
+ export * from './spreadsheet-grid.component.js';
80
+ export * from './types.js';
81
+ export * from './utilities.js';
82
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EG;AAEH,cAAc,iCAAiC,CAAA;AAC/C,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}