@langeditor/plugin-spreadsheet 0.0.0-stage → 1.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present TyCoding and LangEditor contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PRD.md

@@ -0,0 +1,72 @@
+# Spreadsheet Document Mode PRD
+
+## Purpose
+
+Provide a permissively licensed spreadsheet editor as the independently
+installable `@langeditor/plugin-spreadsheet` package. Importing the package
+registers `mode="spreadsheet"`; the grid and format runtimes are downloaded only
+when that mode is mounted.
+
+## License and dependencies
+
+The package itself is MIT. Runtime dependencies are restricted to permissive
+licenses:
+
+- official `@ironcalc/wasm` under MIT/Apache-2.0 for workbook calculation;
+- `@e965/xlsx` under Apache-2.0 for XLSX/ODS import;
+- ExcelJS under MIT for style-preserving XLSX export;
+- Papa Parse under MIT for CSV serialization.
+
+Univer, Handsontable, and any dependency requiring a commercial web-use license
+are explicitly out of scope.
+
+## Current scope
+
+- editable cell grid with keyboard navigation and range selection;
+- formulas calculated by IronCalc;
+- basic cell formatting: font family and size, emphasis, text/fill color,
+  horizontal alignment, and wrapping;
+- merge and unmerge selected cell ranges;
+- multiple worksheet tabs with double-click rename;
+- XLSX and CSV import/export;
+- serializable workbook snapshot for `v-model`;
+- spreadsheet selection, AI context, and operation support through
+  `LcDocumentSession`;
+- shared LangEditor toolbar/statusbar slots;
+- shared blue document title bar without Word page chrome;
+- Chinese and English UI.
+
+## Non-goals
+
+The plugin does not claim complete Excel fidelity. Macros, pivot tables,
+embedded charts/images, external workbook links, protected/encrypted workbooks,
+and advanced print areas are not editable. Import returns diagnostics for features
+that cannot be represented safely.
+
+## UI placement
+
+- `toolbar`: import/export, font formatting, colors, alignment, wrapping,
+  merge/unmerge, clear formatting, add row/column, and add sheet.
+- `statusbar-left`: active worksheet and selected range.
+- document surface: formula bar, row/column headers, virtual scrolling grid, and
+  worksheet tabs.
+- document title bar: host-owned blue title bar shared with Word and future
+  document modes; spreadsheet print metadata does not render Word page chrome.
+
+No second toolbar row is created. The grid releases all listeners and the WASM
+model when its document session is destroyed.
+
+## AI and collaboration
+
+`getAIContext()` returns a bounded snapshot of the selected range including raw
+formula input and formatted values. AI or collaboration changes use validated
+spreadsheet operations rather than direct DOM or engine mutation. Provider
+credentials and document authorization remain outside this browser package.
+
+## Failure states
+
+- WASM initialization failure: surface error with retry available from the host.
+- unsupported/corrupt import: localized actionable error plus diagnostics.
+- oversized range: AI context is truncated and marked in metadata.
+- unsupported operation: rejected with an explicit error; document state is not
+  partially mutated.

package/README.md

@@ -1,3 +1,83 @@
-# Temporary Holding Version
+# @langeditor/plugin-spreadsheet
 
-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.
+Open-source spreadsheet mode for LangEditor. It uses IronCalc for formula
+calculation and keeps XLSX/CSV code behind the document surface's dynamic import.
+
+The built-in toolbar supports font family and size, bold/italic/underline,
+text and fill colors, alignment, wrapping, merged cells, row/column insertion,
+worksheet creation, and clearing cell formatting. These changes are persisted in
+the workbook snapshot and included in XLSX export.
+
+Double-click a worksheet tab to rename it. Press Enter or move focus away to
+save, and press Escape to cancel. Worksheet renames use the same validated
+document-operation path as toolbar, AI, collaboration, and host changes.
+
+## Install
+
+```bash
+pnpm add @langeditor/core @langeditor/plugin-spreadsheet
+```
+
+```ts
+import '@langeditor/plugin-spreadsheet'
+import '@langeditor/plugin-spreadsheet/style.css'
+```
+
+## Vue
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { LangEditor } from '@langeditor/core'
+import type { SpreadsheetWorkbookSnapshot } from '@langeditor/plugin-spreadsheet'
+import '@langeditor/plugin-spreadsheet'
+import '@langeditor/plugin-spreadsheet/style.css'
+
+const workbook = ref<SpreadsheetWorkbookSnapshot>()
+const source = ref<File>()
+</script>
+
+<template>
+  <LangEditor
+    v-model="workbook"
+    :document-source="source"
+    mode="spreadsheet"
+    :min-height="680"
+  />
+</template>
+```
+
+The same `mode`, `documentSource`, `lc-session-ready`, and `getSession()` contract
+works through `@langeditor/core/element` and the React adapter.
+
+Formatting and merge commands also use the public document-operation path, so AI,
+collaboration, and host integrations do not need to mutate grid DOM:
+
+```ts
+await session.applyOperations([
+  { type: 'spreadsheet.set-style', payload: { font: { bold: true, size: 14 } } },
+  { type: 'spreadsheet.rename-sheet', payload: { name: 'Budget 2027' } },
+  { type: 'spreadsheet.merge-cells' },
+])
+```
+
+Programmatic serializers are asynchronous so importing the registration entry
+does not eagerly load XLSX or CSV code:
+
+```ts
+import { exportSpreadsheet, importSpreadsheet } from '@langeditor/plugin-spreadsheet'
+
+const { value, diagnostics } = await importSpreadsheet(file)
+const xlsx = await exportSpreadsheet(value, 'xlsx')
+```
+
+## Supported input
+
+- `.xlsx`, `.xlsm` without macro execution, and `.ods` where the serializer can
+  read the workbook;
+- `.csv`, `.tsv`, and plain delimited text;
+- `SpreadsheetWorkbookSnapshot` through `v-model`;
+- URL, File, Blob, ArrayBuffer, or Uint8Array through `documentSource`.
+
+See [PRD.md](./PRD.md) for fidelity limits and failure behavior. The package is
+MIT and contains no commercial-license dependency.