y11n-spreadsheet 0.1.0 → 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Coordinate System
+ * Zero-indexed (0,0 is A1)
+ */
+export interface CellCoord {
+    row: number;
+    col: number;
+}
+/**
+ * Cell-level formatting options
+ */
+export interface CellFormat {
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strikethrough?: boolean;
+    textColor?: string;
+    backgroundColor?: string;
+    textAlign?: 'left' | 'center' | 'right';
+    fontSize?: number;
+}
+/**
+ * Data Structure for a Single Cell
+ */
+export interface CellData {
+    rawValue: string;
+    displayValue: string;
+    type: 'text' | 'number' | 'boolean' | 'error';
+    format?: CellFormat;
+}
+/**
+ * The Sparse Data Map
+ * Key format: "${row}:${col}" (e.g., "0:0")
+ */
+export type GridData = Map<string, CellData>;
+/**
+ * Selection Range (normalized bounding box)
+ */
+export interface SelectionRange {
+    start: CellCoord;
+    end: CellCoord;
+}
+/**
+ * Formula Context
+ * Passed to custom functions to allow them to access the grid
+ */
+export interface FormulaContext {
+    getCellValue: (ref: string) => unknown;
+    getRangeValues: (start: string, end: string) => unknown[];
+}
+/**
+ * A formula function that receives a context and arguments
+ */
+export type FormulaFunction = (ctx: FormulaContext, ...args: unknown[]) => unknown;
+/**
+ * Cell change event detail
+ */
+export interface CellChangeDetail {
+    cellId: string;
+    value: string;
+    oldValue: string;
+}
+/**
+ * Selection change event detail
+ */
+export interface SelectionChangeDetail {
+    range: SelectionRange;
+}
+/**
+ * Data change event detail (bulk updates)
+ */
+export interface DataChangeDetail {
+    updates: Array<{
+        id: string;
+        value: string;
+    }>;
+    source?: 'user' | 'undo' | 'redo' | 'programmatic';
+    operation?: 'edit' | 'cut' | 'paste' | 'clear' | 'format';
+}
+/**
+ * Format change event detail
+ */
+export interface FormatChangeDetail {
+    cellIds: string[];
+    format: CellFormat;
+    source: 'user' | 'undo' | 'redo' | 'programmatic';
+}
+/**
+ * Shallow-compare two CellFormat objects (key-order independent)
+ */
+export declare function formatsEqual(a: CellFormat | undefined, b: CellFormat | undefined): boolean;
+/**
+ * Creates a cell key from row and col indices
+ */
+export declare function cellKey(row: number, col: number): string;
+/**
+ * Parse a cell key back to coordinates
+ */
+export declare function parseKey(key: string): CellCoord;
+/**
+ * Convert a column index (0-based) to a letter (A, B, ... Z, AA, AB...)
+ */
+export declare function colToLetter(col: number): string;
+/**
+ * Convert a column letter (A, B, ... Z, AA, AB...) to 0-based index
+ */
+export declare function letterToCol(letter: string): number;
+/**
+ * Convert a cell reference like "A1" to a CellCoord
+ * Supports absolute/mixed references: $A$1, $A1, A$1
+ */
+export declare function refToCoord(ref: string): CellCoord;
+/**
+ * Convert a CellCoord to a cell reference like "A1"
+ */
+export declare function coordToRef(coord: CellCoord): string;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/y11n-spreadsheet.d.ts

@@ -0,0 +1,155 @@
+import { LitElement } from 'lit';
+import { type CellFormat, type GridData, type SelectionRange, type FormulaFunction } from './types.js';
+import './components/y11n-formula-bar.js';
+/**
+ * <y11n-spreadsheet> - An accessible spreadsheet web component.
+ *
+ * Implements the WAI-ARIA Grid pattern with roving tabindex,
+ * keyboard navigation, formula support, and clipboard operations.
+ */
+export declare class Y11nSpreadsheet extends LitElement {
+    rows: number;
+    cols: number;
+    data: GridData;
+    readOnly: boolean;
+    functions: Record<string, FormulaFunction>;
+    private _isEditing;
+    private _editValue;
+    private _formulaBarMode;
+    /** Whether arrow keys are currently selecting a cell reference in a formula */
+    private _refMode;
+    /** Screen reader announcement text for mode changes */
+    private _modeAnnouncement;
+    /** Track scroll position for virtual rendering */
+    private _scrollTop;
+    private _scrollLeft;
+    private _editor;
+    private _grid;
+    private _selection;
+    private _formulaEngine;
+    private _clipboardManager;
+    /** Internal data store - we keep a separate mutable copy */
+    private _internalData;
+    /** Track which cell started editing for commit logic */
+    private _editingCellKey;
+    private _undoStack;
+    private _redoStack;
+    private readonly _maxHistory;
+    /** Reference mode cursor position */
+    private _refCursorRow;
+    private _refCursorCol;
+    /** Start/end positions of the reference text within the formula string */
+    private _refInsertStart;
+    private _refInsertEnd;
+    connectedCallback(): void;
+    willUpdate(changedProps: Map<string, unknown>): void;
+    /** Returns the current state of the grid data */
+    getData(): GridData;
+    /** Hard reset of the grid data */
+    setData(data: GridData): void;
+    /** Dynamically register a formula function */
+    registerFunction(name: string, fn: FormulaFunction): void;
+    /** Returns the format for a cell, or undefined if unformatted */
+    getCellFormat(cellId: string): CellFormat | undefined;
+    /** Merges format into a cell (creates cell if needed). Pass undefined to unset a property. */
+    setCellFormat(cellId: string, format: CellFormat): void;
+    /** Applies format to all cells in a range (creates empty cells if needed) */
+    setRangeFormat(range: SelectionRange, format: CellFormat): void;
+    /** Removes all formatting from a cell */
+    clearCellFormat(cellId: string): void;
+    /** Removes all formatting from a range */
+    clearRangeFormat(range: SelectionRange): void;
+    /** Toggles a boolean format property on the current selection */
+    toggleFormat(prop: 'bold' | 'italic' | 'underline' | 'strikethrough'): void;
+    private _applyFormat;
+    private _clearFormat;
+    private _buildFormatBatch;
+    /** Convert CellFormat to inline styles for styleMap */
+    private _getCellStyles;
+    private _syncData;
+    private _recalcAll;
+    private _recalcAffected;
+    private _getCell;
+    private _getCellDisplay;
+    private _getCellRaw;
+    private _getActiveCellKey;
+    private _getActiveCellRef;
+    private _setCellRaw;
+    private _applyRawValueByString;
+    private _snapshotSelection;
+    private _restoreSelection;
+    private _buildCommandBatch;
+    private _pushHistory;
+    private _finalizeBatch;
+    private _applyBatch;
+    private _revertBatch;
+    /** Low-level: set or remove format on a cell */
+    private _applyCellFormat;
+    private _executeUserBatch;
+    private _commitRawValue;
+    private _undo;
+    private _redo;
+    /** Dispatch format-change for any batch that contains format deltas.
+     *  NOTE: The event carries the format from the first delta only. For heterogeneous
+     *  batches (e.g., paste with varied per-cell formatting), this is an approximation —
+     *  the cellIds are accurate but the format may not represent every cell. Consumers
+     *  that need per-cell accuracy should read cell data directly. */
+    private _dispatchFormatChangeForBatch;
+    private _startEditing;
+    private _commitEdit;
+    private _cancelEdit;
+    /**
+     * Check if the cursor is at a position in the formula where a cell reference
+     * can be inserted (after =, +, -, *, /, &, (, ,, or comparison operators).
+     */
+    private _isRefPositionInFormula;
+    /**
+     * Handle an arrow key press during formula editing to insert or move
+     * a cell reference.
+     */
+    private _handleRefArrow;
+    private _exitRefMode;
+    /**
+     * Cycle the cell reference at/before the cursor through reference modes:
+     * A1 → $A$1 → A$1 → $A1 → A1
+     */
+    private _cycleReferenceMode;
+    private _focusActiveCell;
+    private _handleGridKeydown;
+    private _handleEditorKeydown;
+    private _handleCellPointerDown;
+    private _handleCellDblClick;
+    private _handleCopy;
+    private _handleCut;
+    private _handlePaste;
+    private _clearSelectedCells;
+    private _handleScroll;
+    private _handleEditorInput;
+    private _handleEditorBlur;
+    private _handleFormulaBarModeChange;
+    private _handleFormulaBarCommit;
+    private _dispatchCellChange;
+    private _dispatchSelectionChange;
+    private _dispatchDataChange;
+    private _dispatchFormatChange;
+    /**
+     * Compute which rows and columns are visible based on scroll position.
+     * We add a buffer of extra rows/cols for smooth scrolling.
+     */
+    private _getVisibleRange;
+    private _getCSSVarPx;
+    private _getEditorStyle;
+    static styles: import("lit").CSSResult;
+    protected render(): import("lit-html").TemplateResult<1>;
+    private _renderHeaderRow;
+    private _renderRows;
+    private _renderRow;
+    private _getAnnouncement;
+    protected updated(): void;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'y11n-spreadsheet': Y11nSpreadsheet;
+    }
+}
+//# sourceMappingURL=y11n-spreadsheet.d.ts.map

package/dist/y11n-spreadsheet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"y11n-spreadsheet.d.ts","sourceRoot":"","sources":["../src/y11n-spreadsheet.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,17 +1,23 @@
 {
   "name": "y11n-spreadsheet",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "Accessible spreadsheet web component built with Lit 3.0",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
   "files": [
     "dist"
   ],
   "scripts": {
     "dev": "vite",
-    "build": "tsc && vite build",
+    "build": "tsc --noEmit && vite build && tsc -p tsconfig.build.json --emitDeclarationOnly",
     "preview": "vite preview",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
@@ -20,20 +26,34 @@
     "test:e2e:ui": "playwright test --ui",
     "test:e2e:headed": "playwright test --headed",
     "storybook": "storybook dev -p 6006",
-    "build-storybook": "storybook build"
+    "build-storybook": "storybook build",
+    "prepublishOnly": "npm run build && npm test"
   },
   "keywords": [
     "spreadsheet",
     "accessible",
     "web-component",
     "lit",
-    "aria"
+    "aria",
+    "a11y",
+    "wai-aria",
+    "grid"
   ],
+  "author": "Ege Ozcan <egecan@gmail.com>",
   "license": "MIT",
-  "dependencies": {
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/egeozcan/accessible-spreadsheet-component.git"
+  },
+  "homepage": "https://github.com/egeozcan/accessible-spreadsheet-component#readme",
+  "bugs": {
+    "url": "https://github.com/egeozcan/accessible-spreadsheet-component/issues"
+  },
+  "peerDependencies": {
     "lit": "^3.0.0"
   },
   "devDependencies": {
+    "lit": "^3.0.0",
     "@playwright/test": "^1.56.1",
     "@storybook/addon-essentials": "^8.6.17",
     "@storybook/blocks": "^8.6.17",
@@ -41,6 +61,7 @@
     "@storybook/test": "8.6.17",
     "@storybook/web-components": "^8.6.17",
     "@storybook/web-components-vite": "^8.6.17",
+    "jsdom": "^28.1.0",
     "storybook": "^8.6.17",
     "typescript": "^5.3.0",
     "vite": "^5.0.0",