y11n-spreadsheet 1.0.1 → 1.0.2

package/dist/types.d.ts

@@ -1,117 +1,198 @@
 /**
- * Coordinate System
- * Zero-indexed (0,0 is A1)
+ * A zero-indexed cell coordinate.
+ * (0, 0) corresponds to cell A1.
  */
 export interface CellCoord {
+    /** 0-indexed row number (0 = row 1) */
     row: number;
+    /** 0-indexed column number (0 = column A) */
     col: number;
 }
 /**
- * Cell-level formatting options
+ * Cell-level formatting options.
+ * All properties are optional; only set properties are applied.
  */
 export interface CellFormat {
+    /** Whether the cell text is bold */
     bold?: boolean;
+    /** Whether the cell text is italic */
     italic?: boolean;
+    /** Whether the cell text is underlined */
     underline?: boolean;
+    /** Whether the cell text has a strikethrough */
     strikethrough?: boolean;
+    /** CSS color string for text (e.g. "#ff0000", "red") */
     textColor?: string;
+    /** CSS color string for cell background */
     backgroundColor?: string;
+    /** Horizontal text alignment */
     textAlign?: 'left' | 'center' | 'right';
+    /** Font size in pixels */
     fontSize?: number;
+    /** Numeric display format (e.g. currency, percent) */
+    numberFormat?: NumberFormatOptions;
+}
+/** Available preset number format types */
+export type NumberFormatType = 'number' | 'currency' | 'percent' | 'scientific';
+/** Options for number formatting */
+export interface NumberFormatOptions {
+    type: NumberFormatType;
+    /** Number of decimal places (default: 2) */
+    decimals?: number;
+    /** Currency symbol (default: '$'), only used when type is 'currency' */
+    currencySymbol?: string;
+    /** Whether to use thousands separators (default: true for 'number' and 'currency') */
+    thousandsSep?: boolean;
 }
 /**
- * Data Structure for a Single Cell
+ * Data for a single cell in the grid.
  */
 export interface CellData {
+    /** The raw user-entered value (may be a formula starting with "=") */
     rawValue: string;
+    /** The computed display string shown in the cell */
     displayValue: string;
+    /** The resolved data type after evaluation */
     type: 'text' | 'number' | 'boolean' | 'error';
+    /** Optional visual formatting applied to the cell */
     format?: CellFormat;
 }
 /**
- * The Sparse Data Map
- * Key format: "${row}:${col}" (e.g., "0:0")
+ * Sparse data map for the entire grid.
+ * Keys use the format `"${row}:${col}"` (e.g. `"0:0"` for A1, `"2:3"` for D3).
+ * Only cells with content are stored; absent keys represent empty cells.
  */
 export type GridData = Map<string, CellData>;
 /**
- * Selection Range (normalized bounding box)
+ * A normalized rectangular selection range.
+ * `start` is always the top-left corner; `end` is always the bottom-right.
  */
 export interface SelectionRange {
+    /** Top-left corner of the selection (minimum row and column) */
     start: CellCoord;
+    /** Bottom-right corner of the selection (maximum row and column) */
     end: CellCoord;
 }
 /**
- * Formula Context
- * Passed to custom functions to allow them to access the grid
+ * Context object passed to custom formula functions, providing access to grid data.
  */
 export interface FormulaContext {
+    /** Retrieve the evaluated value of a single cell by reference (e.g. "A1"). */
     getCellValue: (ref: string) => unknown;
+    /** Retrieve a flat array of values for a rectangular range (e.g. "A1", "B5"). */
     getRangeValues: (start: string, end: string) => unknown[];
 }
 /**
- * A formula function that receives a context and arguments
+ * Signature for user-defined formula functions.
+ *
+ * @param ctx - Provides access to cell/range values from the grid.
+ * @param args - Variadic evaluated arguments passed to the function in the formula.
+ * @returns The computed result (number, string, boolean, or error string).
  */
 export type FormulaFunction = (ctx: FormulaContext, ...args: unknown[]) => unknown;
 /**
- * Cell change event detail
+ * Detail for the `cell-change` event, fired when a single cell is edited.
  */
 export interface CellChangeDetail {
+    /** Cell key in `"row:col"` format */
     cellId: string;
+    /** New raw value of the cell */
     value: string;
+    /** Previous raw value of the cell */
     oldValue: string;
 }
 /**
- * Selection change event detail
+ * Detail for the `selection-change` event, fired when the selected range changes.
  */
 export interface SelectionChangeDetail {
+    /** The current normalized selection range */
     range: SelectionRange;
 }
 /**
- * Data change event detail (bulk updates)
+ * Detail for the `data-change` event, fired on bulk updates (paste, cut, clear, undo/redo).
  */
 export interface DataChangeDetail {
+    /** Array of cell updates, each with a cell key and new raw value */
     updates: Array<{
         id: string;
         value: string;
     }>;
+    /** What triggered the change */
     source?: 'user' | 'undo' | 'redo' | 'programmatic';
+    /** The type of operation that caused the change */
     operation?: 'edit' | 'cut' | 'paste' | 'clear' | 'format';
 }
 /**
- * Format change event detail
+ * Detail for the `format-change` event, fired when cell formatting is modified.
  */
 export interface FormatChangeDetail {
+    /** Cell keys that were affected */
     cellIds: string[];
+    /** The format properties that were applied (empty object for clear) */
     format: CellFormat;
+    /** What triggered the format change */
     source: 'user' | 'undo' | 'redo' | 'programmatic';
 }
 /**
- * Shallow-compare two CellFormat objects (key-order independent)
+ * Compare two CellFormat objects for deep equality (key-order independent).
+ * Deep-compares the `numberFormat` sub-object.
+ *
+ * @param a - First format (or undefined)
+ * @param b - Second format (or undefined)
+ * @returns `true` if both formats are structurally equal
  */
 export declare function formatsEqual(a: CellFormat | undefined, b: CellFormat | undefined): boolean;
 /**
- * Creates a cell key from row and col indices
+ * Format a numeric value according to the given number format options.
+ *
+ * @param value - The numeric value to format
+ * @param opts - Formatting options (type, decimals, currency symbol, thousands separator)
+ * @returns The formatted string representation
+ */
+export declare function formatNumber(value: number, opts: NumberFormatOptions): string;
+/**
+ * Creates a cell key string from row and column indices.
+ *
+ * @param row - 0-indexed row number
+ * @param col - 0-indexed column number
+ * @returns A key in `"row:col"` format (e.g. `"0:0"`)
  */
 export declare function cellKey(row: number, col: number): string;
 /**
- * Parse a cell key back to coordinates
+ * Parse a cell key string back to row/col coordinates.
+ *
+ * @param key - A key in `"row:col"` format (e.g. `"0:0"`)
+ * @returns The parsed coordinate
  */
 export declare function parseKey(key: string): CellCoord;
 /**
- * Convert a column index (0-based) to a letter (A, B, ... Z, AA, AB...)
+ * Convert a 0-based column index to a column letter (A, B, ... Z, AA, AB...).
+ *
+ * @param col - 0-indexed column number
+ * @returns The column letter(s) (e.g. 0 -> "A", 25 -> "Z", 26 -> "AA")
  */
 export declare function colToLetter(col: number): string;
 /**
- * Convert a column letter (A, B, ... Z, AA, AB...) to 0-based index
+ * Convert a column letter (A, B, ... Z, AA, AB...) to a 0-based index.
+ *
+ * @param letter - Column letter(s) (e.g. "A", "Z", "AA")
+ * @returns 0-indexed column number (e.g. "A" -> 0, "Z" -> 25, "AA" -> 26)
  */
 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
+ * Convert a cell reference string to a CellCoord.
+ * Supports absolute/mixed references: `$A$1`, `$A1`, `A$1`.
+ *
+ * @param ref - Cell reference (e.g. "A1", "$B$3")
+ * @returns The 0-indexed coordinate
+ * @throws {Error} If the reference format is invalid
  */
 export declare function refToCoord(ref: string): CellCoord;
 /**
- * Convert a CellCoord to a cell reference like "A1"
+ * Convert a CellCoord to a cell reference string like "A1".
+ *
+ * @param coord - The 0-indexed coordinate
+ * @returns Cell reference string (e.g. `{row: 0, col: 0}` -> "A1")
  */
 export declare function coordToRef(coord: CellCoord): string;
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,uCAAuC;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,6CAA6C;IAC7C,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,oCAAoC;IACpC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,sCAAsC;IACtC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,gDAAgD;IAChD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gCAAgC;IAChC,SAAS,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;IACxC,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,YAAY,CAAC,EAAE,mBAAmB,CAAC;CACpC;AAED,2CAA2C;AAC3C,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,GAAG,YAAY,CAAC;AAEhF,oCAAoC;AACpC,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,gBAAgB,CAAC;IACvB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,sFAAsF;IACtF,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,YAAY,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;IAC9C,qDAAqD;IACrD,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AAE7C;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,KAAK,EAAE,SAAS,CAAC;IACjB,oEAAoE;IACpE,GAAG,EAAE,SAAS,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,8EAA8E;IAC9E,YAAY,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACvC,iFAAiF;IACjF,cAAc,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,EAAE,CAAC;CAC3D;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,cAAc,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;AAEnF;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,6CAA6C;IAC7C,KAAK,EAAE,cAAc,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,OAAO,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC9C,gCAAgC;IAChC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,cAAc,CAAC;IACnD,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAC;CAC3D;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,mCAAmC;IACnC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,uEAAuE;IACvE,MAAM,EAAE,UAAU,CAAC;IACnB,uCAAuC;IACvC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,cAAc,CAAC;CACnD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,UAAU,GAAG,SAAS,EAAE,CAAC,EAAE,UAAU,GAAG,SAAS,GAAG,OAAO,CAY1F;AAWD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,GAAG,MAAM,CAqB7E;AAaD;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAG/C;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAQ/C;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAMlD;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAOjD;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAEnD"}

package/dist/y11n-spreadsheet.d.ts

@@ -2,20 +2,41 @@ 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.
+ * `<y11n-spreadsheet>` -- An accessible spreadsheet web component.
  *
- * Implements the WAI-ARIA Grid pattern with roving tabindex,
- * keyboard navigation, formula support, and clipboard operations.
+ * Implements the WAI-ARIA Grid pattern with:
+ * - Roving tabindex and full keyboard navigation (arrows, Tab, Home/End, Ctrl+arrows)
+ * - Recursive-descent formula engine (`=SUM(A1:B5)`, `=IF(...)`, etc.)
+ * - Copy/cut/paste via the Clipboard API (HTML table + TSV formats)
+ * - Undo/redo command history (up to 100 entries)
+ * - Virtual rendering for large grids (only visible cells + buffer are in the DOM)
+ * - Cell formatting (bold, italic, colors, number formats, etc.)
+ *
+ * @fires cell-change - When a single cell value is edited
+ * @fires selection-change - When the selected range changes
+ * @fires data-change - On bulk updates (paste, cut, clear, undo/redo)
+ * @fires format-change - When cell formatting is modified
+ *
+ * @csspart editor - The inline cell editor input element
  */
 export declare class Y11nSpreadsheet extends LitElement {
+    /** Number of rows in the grid. Default: 100 */
     rows: number;
+    /** Number of columns in the grid. Default: 26 */
     cols: number;
+    /** The sparse grid data map. Set externally or via `setData()`. */
     data: GridData;
+    /** When true, all editing is disabled. Default: false */
     readOnly: boolean;
+    /** Accessible label for the grid. Default: 'Spreadsheet' */
+    gridLabel: string;
+    /** Record of custom formula functions to register, keyed by name. */
     functions: Record<string, FormulaFunction>;
     private _isEditing;
     private _editValue;
     private _formulaBarMode;
+    /** When true, the next render should reposition the editor cursor (set on edit start / ref mode) */
+    private _editorNeedsCursorReset;
     /** Whether arrow keys are currently selecting a cell reference in a formula */
     private _refMode;
     /** Screen reader announcement text for mode changes */
@@ -30,6 +51,7 @@ export declare class Y11nSpreadsheet extends LitElement {
     private _clipboardManager;
     /** Internal data store - we keep a separate mutable copy */
     private _internalData;
+    private _lastSyncedDataRef;
     /** Track which cell started editing for commit logic */
     private _editingCellKey;
     private _undoStack;
@@ -41,25 +63,73 @@ export declare class Y11nSpreadsheet extends LitElement {
     /** Start/end positions of the reference text within the formula string */
     private _refInsertStart;
     private _refInsertEnd;
-    connectedCallback(): void;
+    /** Whether an async paste operation is currently in progress */
+    private _pasteInProgress;
+    /** Number of cells to process per animation frame during large pastes */
+    private static readonly PASTE_CHUNK_SIZE;
+    private static readonly INITIAL_VIEW_ROWS;
+    private static readonly INITIAL_VIEW_COLS;
+    private static readonly ROW_HEADER_WIDTH;
     willUpdate(changedProps: Map<string, unknown>): void;
-    /** Returns the current state of the grid data */
+    /**
+     * Returns a shallow copy of the current grid data.
+     *
+     * @returns A new Map containing all cell data
+     */
     getData(): GridData;
-    /** Hard reset of the grid data */
+    /**
+     * Replaces the entire grid data and resets undo/redo history.
+     *
+     * @param data - The new sparse grid data map
+     */
     setData(data: GridData): void;
-    /** Dynamically register a formula function */
+    /**
+     * Register a custom formula function at runtime.
+     * Triggers a full recalculation of all formulas.
+     *
+     * @param name - Function name (will be uppercased for lookup)
+     * @param fn - The function implementation
+     */
     registerFunction(name: string, fn: FormulaFunction): void;
-    /** Returns the format for a cell, or undefined if unformatted */
+    /**
+     * Returns the format for a cell, or undefined if unformatted.
+     *
+     * @param cellId - Cell key in `"row:col"` format
+     * @returns The cell's format, or undefined
+     */
     getCellFormat(cellId: string): CellFormat | undefined;
-    /** Merges format into a cell (creates cell if needed). Pass undefined to unset a property. */
+    /**
+     * Merges format properties into a cell. Creates the cell if it does not exist.
+     *
+     * @param cellId - Cell key in `"row:col"` format
+     * @param format - Format properties to merge
+     */
     setCellFormat(cellId: string, format: CellFormat): void;
-    /** Applies format to all cells in a range (creates empty cells if needed) */
+    /**
+     * Applies format to all cells in a rectangular range.
+     *
+     * @param range - The selection range to format
+     * @param format - Format properties to apply
+     */
     setRangeFormat(range: SelectionRange, format: CellFormat): void;
-    /** Removes all formatting from a cell */
+    /**
+     * Removes all formatting from a single cell.
+     *
+     * @param cellId - Cell key in `"row:col"` format
+     */
     clearCellFormat(cellId: string): void;
-    /** Removes all formatting from a range */
+    /**
+     * Removes all formatting from every cell in a range.
+     *
+     * @param range - The selection range to clear formatting from
+     */
     clearRangeFormat(range: SelectionRange): void;
-    /** Toggles a boolean format property on the current selection */
+    /**
+     * Toggles a boolean format property on the current selection.
+     * If all selected cells have the property set, it is removed; otherwise it is applied to all.
+     *
+     * @param prop - The boolean format property to toggle
+     */
     toggleFormat(prop: 'bold' | 'italic' | 'underline' | 'strikethrough'): void;
     private _applyFormat;
     private _clearFormat;
@@ -69,6 +139,12 @@ export declare class Y11nSpreadsheet extends LitElement {
     private _syncData;
     private _recalcAll;
     private _recalcAffected;
+    /** Re-apply number formatting to all cells that have a numberFormat */
+    private _reapplyNumberFormats;
+    /** Re-apply number formatting only to the given set of cell keys */
+    private _applyNumberFormatsToKeys;
+    /** Apply number formatting to a single cell using rawValue for robustness */
+    private _applyNumberFormatToCell;
     private _getCell;
     private _getCellDisplay;
     private _getCellRaw;
@@ -117,11 +193,18 @@ export declare class Y11nSpreadsheet extends LitElement {
     private _focusActiveCell;
     private _handleGridKeydown;
     private _handleEditorKeydown;
+    private _handleSelectAll;
+    private _handleCornerKeydown;
     private _handleCellPointerDown;
     private _handleCellDblClick;
     private _handleCopy;
     private _handleCut;
     private _handlePaste;
+    /**
+     * Apply a command batch progressively in chunks, yielding to the event loop
+     * between chunks via requestAnimationFrame to keep the UI responsive.
+     */
+    private _applyBatchProgressive;
     private _clearSelectedCells;
     private _handleScroll;
     private _handleEditorInput;
@@ -137,12 +220,15 @@ export declare class Y11nSpreadsheet extends LitElement {
      * We add a buffer of extra rows/cols for smooth scrolling.
      */
     private _getVisibleRange;
+    private _ensureCellVisible;
     private _getCSSVarPx;
     private _getEditorStyle;
     static styles: import("lit").CSSResult;
     protected render(): import("lit-html").TemplateResult<1>;
+    private _renderColumnSpacer;
     private _renderHeaderRow;
     private _renderRows;
+    private _renderCell;
     private _renderRow;
     private _getAnnouncement;
     protected updated(): void;

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "y11n-spreadsheet",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Accessible spreadsheet web component built with Lit 3.0",
   "type": "module",
   "main": "dist/index.js",
@@ -53,18 +53,17 @@
     "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",
-    "@storybook/manager-api": "^8.6.17",
-    "@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",
-    "vitest": "^4.0.18"
+    "@axe-core/playwright": "^4.14.0",
+    "@playwright/test": "^1.65.0",
+    "@storybook/addon-a11y": "^10.6.6",
+    "@storybook/addon-docs": "^10.6.6",
+    "@storybook/web-components": "^10.6.6",
+    "@storybook/web-components-vite": "^10.6.6",
+    "jsdom": "^31.0.0",
+    "lit": "^3.3.3",
+    "storybook": "^10.6.6",
+    "typescript": "^7.0.2",
+    "vite": "^8.3.6",
+    "vitest": "^5.1.0"
   }
 }