@worksheet-js/core 1.0.0

package/LICENSE

@@ -0,0 +1,44 @@
+# END USER LICENSE AGREEMENT (EULA)
+
+**Product:** @worksheet-js/core
+**Copyright:** (c) 2024-present Worksheet Systems <support@worksheet.js>
+**All Rights Reserved.**
+
+IMPORTANT: PLEASE READ THIS LICENSE AGREEMENT CAREFULLY BEFORE USING THE SOFTWARE.
+
+### 1. PROPRIETARY RIGHTS
+
+The @worksheet-js/core spreadsheet UI engine ("Software") is a proprietary product of Worksheet Systems and is protected by copyright laws and international treaty provisions. All intellectual property rights in and to the Software are and shall remain the exclusive property of Worksheet Systems.
+
+### 2. GRANT OF LICENSE
+
+Subject to the terms and conditions of this Agreement and any applicable commercial terms, Worksheet Systems grants you a non-exclusive, non-transferable license to use the Software solely for your internal business purposes or as expressly permitted in a separate written agreement.
+
+### 3. RESTRICTIONS
+
+You shall not, and shall not permit any third party to:
+
+- Copy, modify, or create derivative works of the Software.
+- Reverse engineer, decompile, or disassemble the Software, or otherwise attempt to derive the source code, except to the extent such restriction is expressly prohibited by applicable law.
+- Sublicense, rent, lease, or lend the Software to any third party.
+- Remove or alter any copyright, trademark, or other proprietary notices contained in the Software.
+
+### 4. CONFIDENTIALITY
+
+The Software, including its structure, organization, and source code, constitutes valuable trade secrets and confidential information of Worksheet Systems. You agree to hold such information in strict confidence and not to disclose it to any third party.
+
+### 5. TERMINATION
+
+This license is effective until terminated. Your rights under this License will terminate automatically without notice if you fail to comply with any term(s) of this Agreement. Upon termination, you shall cease all use of the Software and destroy all copies in your possession.
+
+### 6. NO WARRANTY
+
+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.
+
+### 7. LIMITATION OF LIABILITY
+
+IN NO EVENT SHALL WORKSHEET SYSTEMS BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR INABILITY TO USE THE SOFTWARE.
+
+### 8. GOVERNING LAW
+
+This Agreement shall be governed by and construed in accordance with the laws of the jurisdiction in which Worksheet Systems is established, without regard to its conflict of law principles.

package/README.md

@@ -0,0 +1,130 @@
+# @worksheet-js/core
+
+**Industrial-grade, high-performance spreadsheet engine for the modern web.**
+
+`@worksheet-js/core` is the foundational engine behind the Worksheet.js ecosystem. It provides a virtualization-driven grid, a robust state model, and a comprehensive set of APIs to build professional-grade spreadsheet applications.
+
+## ✨ Key Features
+
+- **Extreme Performance**: Virtualized rendering handles 1,000,000+ cells at 60 FPS.
+- **Rich Interaction**: In-cell editing, selection management, drag-to-fill, and context menus.
+- **Formula Engine Integration**: Seamlessly evaluates complex formulas via `@worksheet-js/formula`.
+- **Comprehensive I/O**: Import/Export XLSX, CSV, JSON, and HTML via `@worksheet-js/excel`.
+- **Extensible Architecture**: Custom cell overlays (checkboxes, images, charts) and plugin system.
+- **Fully Type-Safe**: Written in TypeScript with exhaustive type definitions.
+
+## 📦 Installation
+
+```bash
+pnpm add @worksheet-js/core
+```
+
+## 🚀 Quick Start
+
+```typescript
+import { Worksheet } from '@worksheet-js/core';
+
+// Create a new instance
+const sheet = await Worksheet.create({
+  container: document.getElementById('spreadsheet-container')!,
+  worksheets: [
+    {
+      worksheetName: 'Annual Report',
+      minDimensions: [26, 100], // A-Z, 100 rows
+    },
+  ],
+  toolbar: true,
+  formulaBar: true,
+});
+
+// Interact with the instance
+sheet.setValue('A1', 'Revenue');
+sheet.setValue('B1', '15000');
+```
+
+## 🛠️ API Reference
+
+### `Worksheet` Class
+
+#### Static Methods
+
+- `create(options: WorksheetOptions): Promise<Worksheet>`: Initializes and mounts the spreadsheet.
+- `loadXlsx(buffer: Uint8Array, options: ...): Promise<Worksheet>`: Creates an instance from an XLSX buffer.
+- `loadCsv(data: string | Uint8Array, options: ...): Promise<Worksheet>`: Creates an instance from CSV data.
+- `loadJson(data: any, options: ...): Promise<Worksheet>`: Creates an instance from JSON data.
+
+#### Instance Methods
+
+- `getValue(address: string): string`: Retrieves the value by address (e.g., `"A1"`).
+- `getValue(x: number, y: number): string`: Retrieves the value by coordinates.
+- `setValue(address: string, value: string): void`: Sets the value by address.
+- `setValue(x: number, y: number, value: string): void`: Sets the value by coordinates.
+- `setStyle(address: string, style: Partial<CellStyle>): void`: Sets cell style by address.
+- `setStyle(x: number, y: number, style: Partial<CellStyle>): void`: Sets cell style by coordinates.
+- `getStyle(address: string): Partial<CellStyle>`: Retrieves cell style.
+- `activeWorksheet: WorksheetModel | null`: Getter for the currently active sheet.
+- `setActiveWorksheet(index: number): void`: Switches active tabs (0-based).
+- `addWorksheet(options?: Partial<SheetMeta>): Promise<WorksheetModel | null>`: Adds a new sheet.
+- `deleteWorksheet(index: number): void`: Deletes a sheet by index.
+- `duplicateWorksheet(index: number): Promise<void>`: Duplicates a worksheet.
+- `moveWorksheet(fromIdx: number, toIdx: number): void`: Rearranges sheets.
+- `renameWorksheet(index: number, name: string): void`: Renames a sheet.
+- `importFromFile(file: File): Promise<void>`: Direct XLSX/CSV file import.
+- `exportXlsx(filename?: string): Promise<void>`: Triggers XLSX download.
+- `exportCsv(filename?: string): Promise<void>`: Triggers CSV download.
+- `on(event: string, callback: function): void`: Attaches event listeners.
+- `off(event: string, callback: function): void`: Removes event listeners.
+- `destroy(): void`: Cleans up DOM and releases memory.
+
+### `WorksheetOptions`
+
+| Option            | Type                | Description                                 |
+| :---------------- | :------------------ | :------------------------------------------ |
+| `container`       | `HTMLElement`       | **Required.** The mounting point.           |
+| `worksheets`      | `SheetMeta[]`       | Initial sheet configurations.               |
+| `toolbar`         | `boolean`           | Toggle ribbon visibility (Default: `true`). |
+| `formulaBar`      | `boolean`           | Toggle formula bar (Default: `true`).       |
+| `theme`           | `'light' \| 'dark'` | UI color theme (Default: `'light'`).        |
+| `defaultColWidth` | `number`            | Default column width in px.                 |
+| `frozenRows`      | `number`            | Number of fixed rows at the top.            |
+
+## 📐 Important Types
+
+### `CellAddress`
+
+```typescript
+interface CellAddress {
+  x: number; // 0-based column index
+  y: number; // 0-based row index
+}
+```
+
+### `SelectionRange`
+
+```typescript
+interface SelectionRange {
+  x1: number;
+  y1: number; // Top-left
+  x2: number;
+  y2: number; // Bottom-right
+}
+```
+
+## 🎨 Event System
+
+Subscribe to changes and interactions:
+
+```typescript
+sheet.on('onchange', (worksheet, cell, x, y, value, oldValue) => {
+  console.log(`Cell [${x},${y}] changed to ${value}`);
+});
+
+sheet.on('onselection', (worksheet, x1, y1, x2, y2) => {
+  // Handle selection updates
+});
+```
+
+## 📄 License
+
+Copyright (c) 2024-present Worksheet Systems. All rights reserved.
+Proprietary software. Usage is subject to the [EULA](LICENSE) terms.