sheetnext 0.2.0 → 0.2.1

package/docs/enums.md

@@ -0,0 +1,171 @@
+# Enum API
+
+> Generated: 2026-03-17
+
+## Enum Types
+
+> Access via `SN.Enum.XXX`, or import from `sheetnext/enum`.
+
+### EventPriority
+- Event priority. Lower values run earlier.
+
+| Key | Value | Description |
+| --- | --- | --- |
+| SYSTEM | -2000 | Internal system |
+| PROTECTION | -1000 | Protection checks |
+| PLUGIN | -500 | Plugin |
+| NORMAL | 0 | Default |
+| LATE | 500 | Post-processing |
+| AUDIT | 1000 | Audit log |
+
+### PasteMode
+- Paste mode.
+
+| Key | Value | Description |
+| --- | --- | --- |
+| ALL | all | All (default) |
+| VALUE | value | Values only |
+| FORMULA | formula | Formulas only |
+| FORMAT | format | Formats only |
+| NO_BORDER | noBorder | Without borders |
+| COLUMN_WIDTH | colWidth | Column widths |
+| COMMENT | comment | Comment |
+| VALIDATION | validation | Data validation |
+| TRANSPOSE | transpose | Transpose |
+| VALUE_NUMBER_FORMAT | valueNumberFormat | Values and number formats |
+| ALL_MERGE_CONDITIONAL | allMergeConditional | All with source theme |
+| FORMULA_NUMBER_FORMAT | formulaNumberFormat | Formulas and number formats |
+
+### PasteOperation
+- Paste operation mode.
+
+| Key | Value | Description |
+| --- | --- | --- |
+| NONE | none | None |
+| ADD | add | Add |
+| SUBTRACT | sub | Subtract |
+| MULTIPLY | mul | Multiply |
+| DIVIDE | div | Divide |
+
+### AnchorType
+- Drawing anchor type.
+
+| Key | Value | Description |
+| --- | --- | --- |
+| TWO_CELL | twoCell | Move and resize with cells |
+| ONE_CELL | oneCell | Move with cells only |
+| ABSOLUTE | absolute | Fixed position |
+
+### DrawingType
+- Drawing type.
+
+| Key | Value | Description |
+| --- | --- | --- |
+| CHART | chart | - |
+| IMAGE | image | - |
+| SHAPE | shape | - |
+| SLICER | slicer | - |
+
+### ValidationType
+- Data validation type.
+
+| Key | Value | Description |
+| --- | --- | --- |
+| LIST | list | Dropdown list |
+| WHOLE | whole | Integer |
+| DECIMAL | decimal | Decimal |
+| DATE | date | Date |
+| TIME | time | Time |
+| TEXT_LENGTH | textLength | Text length |
+| CUSTOM | custom | Custom formula |
+
+### ValidationOperator
+- Data validation operator.
+
+| Key | Value | Description |
+| --- | --- | --- |
+| BETWEEN | between | Between |
+| NOT_BETWEEN | notBetween | Not between |
+| EQUAL | equal | Equal |
+| NOT_EQUAL | notEqual | Not equal |
+| GREATER_THAN | greaterThan | Greater than |
+| GREATER_THAN_OR_EQUAL | greaterThanOrEqual | Greater than or equal |
+| LESS_THAN | lessThan | Less than |
+| LESS_THAN_OR_EQUAL | lessThanOrEqual | Less than or equal |
+
+### FilterOperator
+- Filter condition operator.
+
+| Key | Value | Description |
+| --- | --- | --- |
+| EQUAL | equal | Equal |
+| NOT_EQUAL | notEqual | Not equal |
+| GREATER_THAN | greaterThan | Greater than |
+| GREATER_THAN_OR_EQUAL | greaterThanOrEqual | Greater than or equal |
+| LESS_THAN | lessThan | Less than |
+| LESS_THAN_OR_EQUAL | lessThanOrEqual | Less than or equal |
+| BEGINS_WITH | beginsWith | Begins with |
+| ENDS_WITH | endsWith | Ends with |
+| CONTAINS | contains | Contains |
+| NOT_CONTAINS | notContains | Does not contain |
+
+### CFType
+- Conditional formatting type.
+
+| Key | Value | Description |
+| --- | --- | --- |
+| CELL_VALUE | cellIs | Cell Value |
+| TEXT_CONTAINS | containsText | Text contains |
+| DATE_OCCURRING | timePeriod | Date occurring |
+| TOP_BOTTOM | top10 | Top/bottom N |
+| ABOVE_AVERAGE | aboveAverage | Above/below average |
+| DUPLICATE | duplicateValues | Duplicate values |
+| UNIQUE | uniqueValues | Unique values |
+| DATA_BAR | dataBar | DATA BAR |
+| COLOR_SCALE | colorScale | COLOUR STEP |
+| ICON_SET | iconSet | ICON SET |
+| EXPRESSION | expression | FORMULA |
+
+### SortOrder
+- Sort direction.
+
+| Key | Value | Description |
+| --- | --- | --- |
+| ASC | asc | Ascending |
+| DESC | desc | Descending |
+
+### HorizontalAlign
+- Horizontal alignment.
+
+| Key | Value | Description |
+| --- | --- | --- |
+| LEFT | left | - |
+| CENTER | center | - |
+| RIGHT | right | - |
+| JUSTIFY | justify | Justify |
+| FILL | fill | Fill |
+| DISTRIBUTED | distributed | Distributed |
+
+### VerticalAlign
+- Vertical alignment.
+
+| Key | Value | Description |
+| --- | --- | --- |
+| TOP | top | - |
+| CENTER | center | - |
+| BOTTOM | bottom | - |
+| JUSTIFY | justify | - |
+| DISTRIBUTED | distributed | - |
+
+### BorderStyle
+- Border Style
+
+| Key | Value | Description |
+| --- | --- | --- |
+| NONE | none | - |
+| THIN | thin | - |
+| MEDIUM | medium | - |
+| THICK | thick | - |
+| DASHED | dashed | - |
+| DOTTED | dotted | - |
+| DOUBLE | double | - |

package/docs/events.md

@@ -0,0 +1,331 @@
+# Event API
+
+> Generated: 2026-03-17
+
+## Subscription surface
+
+Use `SN.Event` for registration and dispatch. `SN.Event` is an `EventEmitter` instance exposed on the root workbook object.
+
+```js
+SN.Event.on('beforeCellEdit', (e) => {
+  if (e.data.cell?.locked) e.cancel('Cell is locked')
+})
+
+SN.Event.once('afterSheetAdd', (e) => {
+  console.log(e.data.sheet)
+})
+```
+
+## EventEmitter
+- Event Transmitter
+
+### Methods
+#### `on(event, handler, options = {}): EventEmitter`
+- Register Event Listener
+
+**Parameters**
+| Name | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| event | string | Yes | - | Event Name |
+| handler | Function | Yes | - | Handling function |
+| options | Object | No | {} | Options |
+| options.id | string | Yes | - | Unique identity (anti duplicate binding) |
+| options.priority | number | Yes | - | Priority (execute as soon as possible) |
+| options.once | boolean | Yes | - | Whether to execute only once |
+
+**Returns**
+- Type: `EventEmitter`
+- Chain Calls Supported
+
+#### `once(event, handler, options = {}): EventEmitter`
+- Sign up for a one-time event listener
+
+**Parameters**
+| Name | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| event | string | Yes | - | Event Name |
+| handler | Function | Yes | - | Handling function |
+| options | Object | No | {} | Options |
+
+**Returns**
+- Type: `EventEmitter`
+
+#### `off(event, idOrHandler): EventEmitter`
+- Remove Event Listener
+
+**Parameters**
+| Name | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| event | string | Yes | - | Event Name |
+| idOrHandler | string \| Function | Yes | - | id or handler reference |
+
+**Returns**
+- Type: `EventEmitter`
+
+#### `offAll(): EventEmitter`
+- Remove all event listeners
+
+**Returns**
+- Type: `EventEmitter`
+
+#### `emit(event, data = {}): SheetEvent`
+- Trigger event
+
+**Parameters**
+| Name | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| event | string | Yes | - | Event Name |
+| data | Object | No | {} | Event Data |
+
+**Returns**
+- Type: `SheetEvent`
+- Event object (canceled status can be checked)
+
+#### `async emitAsync(event, data = {}): Promise<SheetEvent>`
+- Trigger event with async hooks support.
+
+**Parameters**
+| Name | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| event | string | Yes | - | event name |
+| data | Object | No | {} | event data |
+
+**Returns**
+- Type: `Promise<SheetEvent>`
+
+#### `hasListeners(event): boolean`
+- Check for listeners
+
+**Parameters**
+| Name | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| event | string | Yes | - | Event Name |
+
+**Returns**
+- Type: `boolean`
+
+#### `listenerCount(event): number`
+- Get the number of listeners
+
+**Parameters**
+| Name | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| event | string | Yes | - | Event name (optional, return total if not passed) |
+
+**Returns**
+- Type: `number`
+
+#### `listEvents(): Array<{event: string, count: number}>`
+- Get all event names and number of monitors
+
+**Returns**
+- Type: `Array<{event: string, count: number}>`
+
+## SheetEvent
+- Event object
+
+### Props
+| Name | Type | Static | Default | Description |
+| --- | --- | --- | --- | --- |
+| type | string | No | type | - |
+| data | Object | No | data | - |
+| target | Object | No | target | - |
+| canceled | boolean | No | false | - |
+| stopped | boolean | No | false | - |
+| cancelReason | null | No | null | - |
+| timestamp | number | No | Date.now() | - |
+
+### Methods
+#### `cancel(reason = '')`
+- Cancel event (block default behavior)
+
+**Parameters**
+| Name | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| reason | string | No | '' | Reason for canceling (optional, used as a reminder) |
+
+#### `stopPropagation()`
+- Stop event propagation (no longer performing follow-up listener)
+
+#### `waitUntil(promise)`
+- Register async work for emitAsync to await.
+
+**Parameters**
+| Name | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| promise | Promise | Yes | - | - |
+
+## Emitted events
+
+- Total detected events: 114
+- Dynamic event patterns: 7
+
+### Col
+| Event | Mode | Cancelable | Payload Keys |
+| --- | --- | --- | --- |
+| after${eventBase} | emit | No | col, newHidden, oldHidden, row, sheet |
+| afterColResize | emit | No | col, newWidth, oldWidth, sheet |
+| before${eventBase} | emit | No | col, newHidden, oldHidden, row, sheet |
+| beforeColResize | emit | No | col, newWidth, oldWidth, sheet |
+
+### Sheet
+| Event | Mode | Cancelable | Payload Keys |
+| --- | --- | --- | --- |
+| after${eventSuffix} | emit | No | [indexKey], changedCount, limitedCount, maxLevel, sheet |
+| afterClearDataValidation | emit | No | ...summary, sheet |
+| afterConsolidate | emit | No | ...summary, sheet |
+| afterDeleteColumns | emit | No | col, count, sheet |
+| afterDeleteRows | emit | No | count, row, sheet |
+| afterFlashFill | emit | No | exampleCount, filledCount, sheet, sourceRange, strategy, targetRange |
+| afterInsertColumns | emit | No | col, count, sheet |
+| afterInsertRows | emit | No | count, row, sheet |
+| afterMerge | emit | No | areas, mode, sheet |
+| afterMoveArea | emit | No | moveArea, sheet, targetArea |
+| afterSelectionChange | emit | No | newAreas, newCell, oldAreas, oldCell, sheet, type |
+| afterSetDataValidation | emit | No | ...summary, sheet |
+| afterSheetRename | emit | No | newName, oldName, sheet |
+| afterSort | emit | No | range, sheet, sortKeys, success |
+| afterSubtotal | emit | No | ...summary, options, sheet |
+| afterTextToColumns | emit | No | columnCount, rowCount, sheet, sourceRange, targetRange |
+| afterUnmerge | emit | No | cellAd, sheet |
+| afterZoomChange | emit | No | newZoom, oldZoom, sheet |
+| before${eventSuffix} | emit | No | [indexKey], areas, maxLevel, sheet |
+| beforeClearDataValidation | emit | No | areas, sheet |
+| beforeConsolidate | emit | No | functionName, sheet, skipBlanks, sourceRanges, targetRange |
+| beforeDeleteColumns | emit | No | col, count, sheet |
+| beforeDeleteRows | emit | No | count, row, sheet |
+| beforeFlashFill | emit | No | exampleCount, sheet, sourceRange, strategy, targetRange |
+| beforeInsertColumns | emit | No | col, count, sheet |
+| beforeInsertRows | emit | No | count, row, sheet |
+| beforeMerge | emit | No | areas, mode, sheet |
+| beforeMoveArea | emit | No | moveArea, sheet, targetArea |
+| beforeSelectionChange | emit | No | newAreas, newCell, oldAreas, oldCell, sheet, type |
+| beforeSetDataValidation | emit | No | areas, rule, sheet |
+| beforeSheetRename | emit | No | newName, oldName, sheet |
+| beforeSort | emit | No | range, sheet, sortKeys |
+| beforeSubtotal | emit | No | options, range, sheet |
+| beforeTextToColumns | emit | No | options, sheet, sourceRange, targetRange |
+| beforeUnmerge | emit | No | cellAd, sheet |
+| beforeZoomChange | emit | No | newZoom, oldZoom, sheet |
+
+### Workbook
+| Event | Mode | Cancelable | Payload Keys |
+| --- | --- | --- | --- |
+| afterActiveSheetChange | emit | No | newSheet, oldSheet |
+| afterOperation | emitAsync | No | - |
+| afterOperation:${op.type} | emitAsync | No | - |
+| afterSheetAdd | emit | No | name, sheet |
+| afterSheetDelete | emit | No | index, name, sheet |
+| afterWorkbookRename | emit | No | newName, oldName |
+| beforeActiveSheetChange | emit | No | newSheet, oldSheet |
+| beforeOperation | emit | No | ...data, operation |
+| beforeOperation:${type} | emit | No | ...data, operation |
+| beforeSheetAdd | emit | No | name |
+| beforeSheetDelete | emit | No | index, name, sheet |
+| beforeWorkbookRename | emit | No | newName, oldName |
+
+### AI
+| Event | Mode | Cancelable | Payload Keys |
+| --- | --- | --- | --- |
+| afterAIRequest | emitAsync | No | durationMs, request, response, result, status, textBlock, ui |
+| aiRequestChunk | emit | No | chunk, chunkIndex, request, textBlock, ui |
+| aiRequestError | emitAsync | No | durationMs, error, request, response, status, textBlock, ui |
+| aiRequestFinally | emitAsync | No | durationMs, error, request, response, result, status, textBlock, ui |
+| aiRequestStart | emit | No | request, textBlock, ui |
+| beforeAIRequest | emitAsync | No | request, textBlock, ui |
+
+### AutoFilter
+| Event | Mode | Cancelable | Payload Keys |
+| --- | --- | --- | --- |
+| afterAutoFilterApply | emit | No | ...eventBase, allHiddenRowsAdded, allHiddenRowsRemoved, hiddenRowsAdded, hiddenRowsRemoved, range, sheet |
+| afterAutoFilterClear | emit | No | ...eventBase, range, ref, sheet |
+| afterAutoFilterClearAllFilters | emit | No | ...eventBase, sheet |
+| afterAutoFilterClearColumnFilter | emit | No | ...eventBase, colIndex, prevFilter, sheet |
+| afterAutoFilterSetColumnFilter | emit | No | ...eventBase, colIndex, filter, prevFilter, sheet |
+| afterAutoFilterSetRange | emit | No | ...eventBase, range, sheet |
+| beforeAutoFilter | emit | No | ...eventBase, action, colIndex, filter, range, sheet |
+| beforeAutoFilterApply | emit | No | ...eventBase, columns, range, sheet |
+| beforeAutoFilterClear | emit | No | ...eventBase, range, ref, sheet |
+| beforeAutoFilterClearAllFilters | emit | No | ...eventBase, filters, sheet |
+| beforeAutoFilterClearColumnFilter | emit | No | ...eventBase, colIndex, prevFilter, sheet |
+| beforeAutoFilterSetColumnFilter | emit | No | ...eventBase, colIndex, filter, prevFilter, sheet |
+| beforeAutoFilterSetRange | emit | No | ...eventBase, range, sheet |
+
+### Cell
+| Event | Mode | Cancelable | Payload Keys |
+| --- | --- | --- | --- |
+| afterCellEdit | emit | No | cell, col, newValue, oldValue, row, sheet |
+| afterCellStyleChange | emit | No | cell, col, newStyle, oldStyle, row, sheet |
+| afterHyperlinkInsert | emit | No | cell, col, hyperlink, row, sheet |
+| beforeCellEdit | emit | No | cell, col, newValue, oldValue, row, sheet |
+| beforeCellStyleChange | emit | No | cell, col, newStyle, oldStyle, row, sheet |
+| beforeHyperlinkInsert | emit | No | cell, col, hyperlink, row, sheet |
+
+### Drawing
+| Event | Mode | Cancelable | Payload Keys |
+| --- | --- | --- | --- |
+| afterDrawingAdd | emit | No | config, drawing, sheet |
+| afterDrawingRemove | emit | No | drawing, id, sheet |
+| beforeDrawingAdd | emit | No | config, sheet |
+| beforeDrawingRemove | emit | No | drawing, id, sheet |
+
+### PivotTable
+| Event | Mode | Cancelable | Payload Keys |
+| --- | --- | --- | --- |
+| afterPivotTableAdd | emit | No | config, pivotTable, sheet |
+| afterPivotTableChange | emit | No | action, pivotTable, sheet, sourceRangeRef, sourceSheet |
+| beforePivotTableAdd | emit | No | config, sheet |
+| beforePivotTableChange | emit | No | action, pivotTable, sheet, sourceRangeRef, sourceSheet |
+
+### UndoRedo
+| Event | Mode | Cancelable | Payload Keys |
+| --- | --- | --- | --- |
+| afterRedo | emit | No | tx |
+| afterUndo | emit | No | tx |
+| beforeRedo | emit | No | tx |
+| beforeUndo | emit | No | tx |
+
+### Row
+| Event | Mode | Cancelable | Payload Keys |
+| --- | --- | --- | --- |
+| afterRowResize | emit | No | newHeight, oldHeight, row, sheet |
+| beforeRowResize | emit | No | newHeight, oldHeight, row, sheet |
+
+### Slicer
+| Event | Mode | Cancelable | Payload Keys |
+| --- | --- | --- | --- |
+| afterSlicerAdd | emit | No | config, sheet, slicer |
+| afterSlicerRemove | emit | No | id, sheet, slicer |
+| beforeSlicerAdd | emit | No | config, sheet |
+| beforeSlicerRemove | emit | No | id, sheet, slicer |
+
+### Sparkline
+| Event | Mode | Cancelable | Payload Keys |
+| --- | --- | --- | --- |
+| afterSparklineAdd | emit | No | config, sheet, sparkline |
+| afterSparklineRemove | emit | No | c, r, sheet, sparkline |
+| beforeSparklineAdd | emit | No | config, sheet |
+| beforeSparklineRemove | emit | No | c, r, sheet, sparkline |
+
+### Table
+| Event | Mode | Cancelable | Payload Keys |
+| --- | --- | --- | --- |
+| afterTableAdd | emit | No | options, sheet, table |
+| afterTableAutoFilterToggle | emit | No | newValue, oldValue, sheet, table |
+| afterTableRemove | emit | No | id, sheet, table |
+| afterTableRename | emit | No | newName, oldName, sheet, table |
+| afterTableResize | emit | No | newRef, oldRef, sheet, table |
+| afterTableStyleChange | emit | No | newStyle, oldStyle, sheet, table |
+| afterTableTotalsRowToggle | emit | No | newValue, oldValue, sheet, table |
+| beforeTableAdd | emit | No | options, sheet |
+| beforeTableAutoFilterToggle | emit | No | newValue, oldValue, sheet, table |
+| beforeTableRemove | emit | No | id, sheet, table |
+| beforeTableRename | emit | No | newName, oldName, sheet, table |
+| beforeTableResize | emit | No | newRef, oldRef, sheet, table |
+| beforeTableStyleChange | emit | No | newStyle, oldStyle, sheet, table |
+| beforeTableTotalsRowToggle | emit | No | newValue, oldValue, sheet, table |
+
+### Comment
+| Event | Mode | Cancelable | Payload Keys |
+| --- | --- | --- | --- |
+| event | emit | No | - |