jspreadsheet 11.18.2 → 11.18.4

package/dist/index.d.ts

@@ -96,7 +96,6 @@ declare namespace jspreadsheet {
 
     interface Picker {
         (el: HTMLElement, options: PickerOptions) : void;
-
         cancel: () => void;
         click: () => void;
         e: Record<string, any> | null | undefined;
@@ -114,7 +113,6 @@ declare namespace jspreadsheet {
 
     interface SetDictionary {
         (dictionary: object) : void;
-
         translate: (text: string, substitutions: string[]) => string;
     }
 
@@ -149,21 +147,117 @@ declare namespace jspreadsheet {
         reset(resetClipboard?: boolean): void,
     }
 
-    /** Images */
-    interface Media {
-        id: string,
-        type?: 'image' | 'chart' | 'shape',
-        src?: string,
-        top?: number,
-        left?: number,
-        width?: number,
-        height?: number,
-        zIndex?: number,
-        options?: object,
-        /** This media is anchor to a cell, so position will be relative to the cell otherwise absolute */
-        cellAnchor?: string,
+    /** Common properties for all media types */
+    interface MediaBase {
+        // GUID string
+        id: string;
+        type: 'image' | 'chart' | 'shape';
+        top?: number;
+        left?: number;
+        width?: number;
+        height?: number;
+        zIndex?: number;
+        // Cell anchor if applicable
+        cellAnchor?: string;
+    }
+
+    /** Options for image media */
+    interface MediaImageOptions {
+        src: string;
+        absolute?: boolean;
+    }
+
+    /** Options for chart media (unchanged) */
+    interface MediaChartOptions {
+        type: 'area' | 'bar' | 'column' | 'doughnut' | 'filledRadar' | 'histogram' | 'line' | 'pareto' |
+            'percentArea' | 'percentBar' | 'percentColumn' | 'pie' | 'radar' | 'scatter' |
+            'stackedArea' | 'stackedBar' | 'stackedColumn';
+        range: string; // e.g., "A1:B10"
+        headers?: boolean;
+        orientation?: 0 | 1;
+        labels?: number;
+        datasets?: number[];
+        title?: {
+            text: string;
+            align?: 'left' | 'center' | 'right';
+            font?: { size?: number; bold?: boolean };
+        };
+        subtitle?: {
+            text: string;
+            align?: 'left' | 'center' | 'right';
+        };
+        legend?: {
+            display?: boolean;
+            position?: 'top' | 'bottom' | 'left' | 'right';
+            align?: 'left' | 'center' | 'right';
+        };
+        series?: Array<{
+            color?: string;
+            borderColor?: string;
+            yAxis?: 'left' | 'right';
+        }>;
+        axis?: {
+            base?: { title?: { text: string } };
+            side?: { title?: { text: string } };
+        };
+        cutout?: number;
+        separation?: {
+            type: 'piece-width';
+            value: number;
+        };
+    }
+
+    /** Options for shape media (updated with your list) */
+    interface MediaShapeOptions {
+        type: 'simpleLine' | 'lineWithArrow' | 'doubleArrowLine' | 'elbowConnector' | 'elbowArrowConnector' |
+            'doubleArrowElbowConnector' | 'curvedElbowConnector' | 'curvedArrowConnector' | 'curvedDoubleArrowConnector' |
+            'rectangle' | 'rounded-rectangle' | 'singleCutCornerRectangle' | 'doubleCutCornerRectangle' |
+            'oppositeCutCornerRectangle' | 'roundedTopRightRectangle' | 'roundedTopLeftRectangle' |
+            'roundedTopRightBottomLeftRectangle' | 'ellipse' | 'triangle' | 'right-triangle' | 'parallelogram' |
+            'trapezium' | 'diamond' | 'pentagon' | 'hexagon' | 'heptagon' | 'octagon' | 'decagon' |
+            'ovalInterfaceIcon' | 'cutCircle' | 'circlewithtoprightoutsideangle' | 'doubleLineSquare' |
+            'doubledtoprighangle' | 'doubleLineShape' | 'mouldingCrown' | 'crossIcon' | 'plaqueShape' |
+            'cylinderShape' | 'cubeShape' | 'bevelShape' | 'donutShape' | 'blockShape' | 'blockArk' |
+            'smileyFace' | 'heart' | 'lightningBolt' | 'sun' | 'crescentMoon' | 'cloud' | 'arcCurve' |
+            'leftSquareBrackets' | 'rightSquareBrackets' | 'squareBracketsPair' | 'leftFlowerBracket' |
+            'rightFlowerBracket' | 'flowerBrackets' | 'rightBlockArrow' | 'leftBlockArrow' | 'upBlockArrow' |
+            'downBlockArrow' | 'upDownArrow' | 'leftRightArrow' | 'quadArrow' | 'leftRightUpArrow' |
+            'bentArrow' | 'uTurnArrow' | 'leftUpArrow' | 'bentUpArrow' | 'curvedRightArrow' | 'curvedLeftArrow' |
+            'curvedUpArrow' | 'curvedDownArrow' | 'stripedRightArrow' | 'notchedRightArrow' | 'pentagonArrow' |
+            'chevron' | 'rightArrowCallout' | 'downArrowCallout' | 'leftArrowCallout' | 'upArrowCallout' |
+            'leftRightArrowCallout' | 'quadArrowCallout' | 'circularArrow' | 'plus' | 'minus' | 'multiplication' |
+            'division' | 'equal' | 'notEqualTo' | 'predefinedTask' | 'internalStorage' | 'document' |
+            'multitaskingDocuments' | 'terminator' | 'preparation' | 'manualInput' | 'manualOperation' |
+            'offpageConnector' | 'card' | 'punchedTape' | 'swimmingJunction' | 'orShape' | 'collateShape' |
+            'sortShape' | 'extractShape' | 'mergeShape' | 'storedDataShape' | 'delayShape' |
+            'sequentialAccessStorageShape' | 'directAccessStorage' | 'displayShape';
+        backgroundColor?: string;
+        borderColor?: string;
+        fontColor?: string;
+        borderWidth?: number;
+        text?: string;
     }
 
+    /** Discriminated union for Media based on type */
+    interface MediaImage extends MediaBase {
+        type: 'image';
+        src: string;
+        options?: MediaImageOptions;
+    }
+
+    interface MediaChart extends MediaBase {
+        type: 'chart';
+        options?: MediaChartOptions;
+    }
+
+    interface MediaShape extends MediaBase {
+        type: 'shape';
+        options?: MediaShapeOptions;
+    }
+
+    /** Unified Media type */
+    type Media = MediaImage | MediaChart | MediaShape;
+
     /** New column object */
     interface newColumn {
         column?: number,
@@ -194,7 +288,6 @@ declare namespace jspreadsheet {
     /** Global History */
     interface History {
         (changes: Record<string, any>): void;
-
         /** History index cursor */
         index: number;
         /** History items */
@@ -213,7 +306,7 @@ declare namespace jspreadsheet {
         reset: () => void;
     }
 
-    /** Only available with the Validations extension */
+    /** Validation entry */
     interface Validation {
         /** Excel-like range format Sheet1!A1:A6 */
         range: string;
@@ -252,7 +345,7 @@ declare namespace jspreadsheet {
         dropdown: true,
     }
 
-    /** Only available with the Validations extension */
+    /** Validations update format */
     interface Validations {
         /** Index position in the array of validations */
         index?: number | null;
@@ -392,6 +485,10 @@ declare namespace jspreadsheet {
         items: Array<ToolbarItem>;
         /** Responsive toolbar. Default: true. */
         responsive?: boolean;
+        /** maxWidth */
+        maxWidth?: number;
+        /** Position of the extended hidden options when applicable */
+        bottom: boolean
     }
 
     interface ToolbarItem {
@@ -788,7 +885,7 @@ declare namespace jspreadsheet {
         /** Remote URL for the persistence server */
         server?: string;
         /** Enable the toolbars */
-        toolbar?: boolean | Toolbar | ToolbarItem[] | Function;
+        toolbar?: boolean | Toolbar | ToolbarItem[] | ((toolbarOptions: Toolbar) => Toolbar);
         /**  Allow table edition */
         editable?: boolean;
         /** Allow data export */
@@ -807,7 +904,7 @@ declare namespace jspreadsheet {
         parseFormulas?: boolean;
         /** Disable the formula editor. Default: true */
         editorFormulas?: boolean;
-        /** Disable formula picker with keyboard. Default: true */
+        /** Enable or disable formula picker with keyboard. Default: true */
         keyboardFormulas?: boolean;
         /** Auto increment cell data when using the corner copy, including formulas, numbers and dates. Default: true */
         autoIncrement?: boolean;
@@ -1021,7 +1118,7 @@ declare namespace jspreadsheet {
         /** Validations */
         validations?: Validation[];
         /** Plugins */
-        plugins?: Record<string, Function>;
+        plugins?: Record<string, Plugin>;
         /** Global style */
         style?: string[];
         /** Snap the cells to the grid when scrolling. Default: false */
@@ -1237,10 +1334,10 @@ declare namespace jspreadsheet {
         openWorksheet: (position: number, force?: boolean) => void;
         /** Create a new worksheet */
         createWorksheet: (worksheetOptions: Worksheet, position?: number) => worksheetInstance | false;
-        /** Delete an existing worksheet by its position */
-        deleteWorksheet: (position: number) => false | undefined;
-        /** Rename an existing worksheet by its position */
-        renameWorksheet: (position: number, title: string) => false | undefined;
+        /** Delete an existing worksheet by its position. When position is omitted delete based on the call context. */
+        deleteWorksheet: (position?: number) => false | undefined;
+        /** Rename an existing worksheet by its position. When position is omitted rename based on the call context. */
+        renameWorksheet: (position: number | null, title: string) => false | undefined;
         /** Move the position of a worksheet. ignoreDomUpdates: true will block updates to the DOM */
         moveWorksheet: (from: number, to: number, ignoreDomUpdates?: boolean) => false | undefined;
         /** Get the active worksheet when applicable */
@@ -1273,10 +1370,13 @@ declare namespace jspreadsheet {
         element: HTMLTableCellElement
     }
 
-    type DeleteMediaItem = string | { id: string, [key: string]: any };
+    type DeleteMediaItem = string | { id: string };
 
     type SetValueFirstArgument = string | { x: number, y: number, value: any, force?: boolean }[];
 
+    /** Maps cell names (e.g., "A1") to colspan and rowspan values (e.g., [3, 2]). */
+    type MergeConfig = Record<string, [number, number]>;
+
     interface worksheetInstance {
         /** Array with the borders information */
         borders: CustomArray<Border>;
@@ -1327,7 +1427,7 @@ declare namespace jspreadsheet {
         /** Internal footer controllers */
         footers: Record<string, any>;
         /** Get the border */
-        getBorder: (alias: string) => object;
+        getBorder: (alias: string) => Border;
         /** Get the cell element from the cellName or via its coordinates x,y */
         getCell(cellName: string): HTMLElement;
         getCell(columnNumber: number, y: number): HTMLElement;
@@ -1349,12 +1449,25 @@ declare namespace jspreadsheet {
         getComments: (cellName?: string) => string | Comment[] | Record<string, string | Comment[]> | undefined;
         /** Get the cached values from one cell or multiple cells. Example: getCache('A1') */
         getCache: (cellName?: string) => false | string | object;
-        /** Get the worksheet settings */
-        getConfig: () => Worksheet;
-        /** Get the worksheet data */
+        /** Get the worksheet settings. Default: false */
+        getConfig: (spreadsheetLevel?: boolean) => Worksheet | Spreadsheet;
+        /**
+         * Fetches all or selected worksheet data in array or JSON format.
+         * @intent get-sheet-data, export-data
+         * @param highlighted - If true, returns only highlighted cells; if RangeCoords, specific range; defaults to all data.
+         * @param processed - If true, returns formatted values; if false, raw values for example formulas or keys. Where processed result for formulas or labels Defaults to false.
+         * @param delimiter - Delimiter for string output (e.g., "," for CSV-like). Normally used on download operations.
+         * @param asJson - Recommended to be used on data operations, default will always respect the internal format. Defaults to false.
+         * @param includeFilteredRows - If true, includes rows hidden by filters. Defaults to false.
+         * @returns {Array<Array<any>> | Array<Record<string, any>> | string} - Worksheet data in specified format or respecting the internal values
+         * @example
+         * const allData = getData(); // [["1", "2"], ["3", "4"]]
+         * const jsonData = getData(false, true, ",", true); // [{ "A": "1", "B": "2" }, ...]
+         * const selectedData = getData([0, 0, 1, 1]); // [["1", "2"], ["3", "4"]]
+         */
         getData: (highlighted?: boolean | RangeCoords, processed?: boolean, delimiter?: string, asJson?: boolean, includeFilteredRows?: boolean) => Array<Array<any>> | Array<Record<string, any>> | string;
         /** Get the worksheet data from a range */
-        getDataFromRange: (range: string, processed?: boolean) => Array<Array<any>> | Array<Record<string, any>> | string | null;
+        getDataFromRange: (range: string, processed?: boolean) => Array<Array<any>> | Array<Record<string, any>>;
         /** Get the defined name or all defined names when key is null */
         getDefinedNames: (key?: string) => any;
         /** Internal method: Get the editor for one cell */
@@ -1382,7 +1495,7 @@ declare namespace jspreadsheet {
         /** Get the merged cells. Cell name: A1, A2, etc or null for all cells */
         getMerge: (cellName?: string) => [number, number] | Record<string, [number, number]> | undefined;
         /** Get one or all meta information for one cell. */
-        getMeta: (cellName: string, property: string) => object | undefined;
+        getMeta: (cellName: string) => object | undefined;
         /** Get the nested cells */
         getNestedCell: (x: number, y: number) => HTMLTableCellElement;
         /** Get the nested headers */
@@ -1419,7 +1532,16 @@ declare namespace jspreadsheet {
         /** Get the selected rows indexes. */
         getSelectedRows: (visibleOnly?: boolean) => number[];
 
-        /** Get the style from a cell or all cells. getStyle() or getStyle('A1') */
+        /**
+         * Retrieves CSS styles for a cell or all cells.
+         * @intent get-cell-style, read-formatting
+         * @param cellName - Cell name (e.g., "A1"); if omitted, returns all styles.
+         * @param onlyIndexes - If true, returns style indices instead of full styles.
+         * @returns {string | number | Record<string, string> | Record<string, number> | undefined} - Style value, index, or object of styles.
+         * @example
+         * getStyle("A1"); // "background-color: red"
+         * getStyle(); // { "A1": "background-color: red", "B2": "font-weight: bold" }
+         */
         getStyle: (cellName?: string | null, onlyIndexes?: boolean) => string | number | Record<string, string> | Record<string, number> | undefined;
         /** Get the style index from a cell or all cells */
         getStyleIndexes: (cellName?: string | null) => number | Record<string, number> | undefined;
@@ -1431,9 +1553,9 @@ declare namespace jspreadsheet {
         /** Get value by the coordinates. The value can be the source or processed value, including not formatted proceed data. */
         getValueFromCoords: (x: number, y: number, processed?: boolean, raw?: boolean) => any;
         /** Get the width of one column by index or all column width as an array when index is null. */
-        getWidth: (x?: number) => Array<number> | number;
+        getWidth: (column?: number) => Array<number> | number;
         /** Go to the row number, [col number] */
-        goto: (y?: number | null, x?: number | null) => void;
+        goto: (row?: number | null, column?: number | null) => void;
         /** Hold the header container */
         headerContainer: HTMLElement;
         /** Hide column */
@@ -1451,20 +1573,23 @@ declare namespace jspreadsheet {
          * @param column - number of columns or array with column information
          * @param columnNumber - reference when the first argument is a number
          * @param insertBefore - insertBefore when the first argument is a number
-         * @param properties - column properties
-         * @param data
-         * @param createSelection
          */
-        insertColumn: (column?: number | newColumn[], columnNumber?: number, insertBefore?: boolean, properties?: Column[], data?: any, createSelection?: boolean) => false | undefined;
+        insertColumn(column?: number, columnNumber?: number, insertBefore?: boolean) : false | undefined;
+        /** Add new columns in a batch */
+        insertColumn(columns: newColumn[]) : false | undefined;
         /**
-         * Add new row(s)
-         * @param row - number of rows or array with row information
-         * @param rowNumber - reference when the first argument is a number
-         * @param insertBefore - insertBefore when the first argument is a number
-         * @param data
-         * @param createSelection
+         * Inserts one or more rows at a specified position.
+         * @intent add-rows, insert-row
+         * @param row - Number of rows to add or array of row data/options.
+         * @param rowNumber - Insert position (zero-based), optional if `row` is array.
+         * @param insertBefore - If true, inserts before `rowNumber`; if false, after. Defaults to false.
+         * @returns {false | undefined} - False if invalid, undefined on success.
+         * @example
+         * insertRow(1, 0, true); // Add 1 row before row 0
+         * insertRow([{ row: 0, data: ["a", "b"] }]); // Insert row with data
          */
-        insertRow: (row?: number | newRow[], rowNumber?: number, insertBefore?: boolean, data?: any, createSelection?: boolean) => false | undefined;
+        insertRow(row?: number | newRow[], rowNumber?: number, insertBefore?: boolean) : false | undefined;
+        insertRow(rows: newRow[]) : false | undefined;
         /** Check if cell is attached to the DOM */
         isAttached: (x: number, y: number) => boolean;
         /** The worksheet is editable */
@@ -1502,11 +1627,11 @@ declare namespace jspreadsheet {
         orderBy: (column: number, direction?: boolean, internalValueController?: number[], internalPreviousStateController?: any) => void;
         /** Change page when using pagination */
         page: (pageNumber: number | null, callBack?: Function) => false | undefined;
-
+        /** Move the scroll page down */
         pageDown: () => void;
         /** Current page number */
         pageNumber: number;
-
+        /** Move the scroll page up */
         pageUp: () => void;
         /** Pagination DOM container */
         pagination: HTMLElement;
@@ -1514,7 +1639,7 @@ declare namespace jspreadsheet {
         parent: spreadsheetInstance;
         /** Paste */
         paste: (x: number, y: number, data: string | any[], selections?: boolean) => false | undefined;
-
+        /** Call the print extension when applicable */
         print: () => void;
         /** Get the quantity of pages when pagination is active */
         quantityOfPages?: () => number | false;
@@ -1526,8 +1651,14 @@ declare namespace jspreadsheet {
         refreshFooter: () => void;
         /** Remove the merged cells by the cell name or a object with all cells to be removed. */
         removeMerge: (cellName: string | Record<string, any>) => false | undefined;
-        /** Reset the borders by name border name */
-        resetBorders: (border?: string, resetPosition?: boolean) => void;
+        /**
+         * Removes borders by alias or all borders.
+         * @intent remove-borders, clear-highlighting
+         * @param border - Border identifier to remove (optional, null for all).
+         * @param permanent - If true, removes permanently; if false, temporary.
+         * @returns {boolean | undefined} - True if successful, false if no border found.
+         */
+        resetBorders: (border?: string, permanent?: boolean) => void;
         /** Reset the filter of one or all columns */
         resetFilters: (colNumber?: number, destroy?: boolean) => void;
         /** Destroy the footers */
@@ -1567,21 +1698,41 @@ declare namespace jspreadsheet {
         currentSelection: RangeCoords | null;
         /** Internal record id sequence */
         sequence: number;
-        /** Set borders with a border name and color. */
-        setBorder: (x1: number, y1: number, x2: number, y2: number, border?: string, color?: string) => void;
+        /**
+         * Adds a colored border to a cell range with a unique identifier.
+         * @intent highlight-cells, create-border
+         * @param x1 - Starting column index (0 or positive).
+         * @param y1 - Starting row index (0 or positive).
+         * @param x2 - Ending column index (≥ x1).
+         * @param y2 - Ending row index (≥ y1).
+         * @param border - Unique border identifier.
+         * @param color - Hex color code (e.g., "#FF0000"), defaults to random if omitted.
+         * @example
+         * setBorder(0, 1, 3, 5, "highlight1", "#FF0000"); // Red border A2:D6
+         */
+        setBorder: (x1: number, y1: number, x2: number, y2: number, border: string, color?: string) => void;
         /** Set attributes for one cell */
         setCells(cellName: Record<string, Cell>): false | undefined;
         setCells(cellName: string, settings: Cell): false | undefined;
         /** Set the column data from its number */
         setColumnData: (col: number, data: any[], force?: boolean) => void;
-        /** Set the comments for one or multiple cells */
-        setComments(cellName: Record<string, string>): false | undefined;
-        setComments(cellName: string, comments: string): false | undefined;
+        /**
+         * Adds or updates comments for one or more cells.
+         * @intent add-comment, set-note
+         * @param cells - Cell name (e.g., "A1") or object mapping cells to comments.
+         * @param comments - Comment text or object (required if `cells` is string).
+         * @returns {false | undefined} - False if read-only, undefined on success.
+         * @example
+         * setComments("A1", "Check this"); // Comment on A1
+         * setComments({ "A1": "Note 1", "B2": { comments: "Note 2", user_id: 1 } }); // Batch comments
+         */
+        setComments(cells: string, comments: string|Comment): false | undefined;
+        setComments(cells: Record<string, string|Comment>): false | undefined;
         /** Set the cache for one or multiple cells */
         setCache(cellName: Record<string, any>): false | undefined;
         setCache(cellName: string, values?: any): false | undefined;
         /** Change the worksheet settings */
-        setConfig: (config: Worksheet | Spreadsheet, spreadsheetLevel?: boolean) => void;
+        setConfig(config: Worksheet | Spreadsheet, spreadsheetLevel?: boolean) : void;
         /** Set the worksheet data */
         setData: (data: any[]) => void;
         /** Create or update names */
@@ -1596,25 +1747,38 @@ declare namespace jspreadsheet {
         setFooterValue: (col: number, row: number, value: any) => void;
         /** List of columns to freeze. Should be a number or an array of consecutive numbers. Example: [4,5,6] */
         setFreezeColumns: (num?: number | number[] | null) => void;
-        /** Set the header title. Empty or null to reset to the default header value. */
-        setHeader: (x: number, title?: string) => false | undefined;
+        /**
+         * Sets or resets a column header title.
+         * @intent set-column-title, rename-header
+         * @param colNumber - Column index (zero-based).
+         * @param title - New header title; if empty or null, resets to default (e.g., "A").
+         * @returns {false | undefined} - False if read-only, undefined on success.
+         * @example
+         * setHeader(0, "Name"); // Set column A to "Name"
+         * setHeader(1, ""); // Reset column B to "B"
+         */
+        setHeader: (colNumber: number, title?: string) => false | undefined;
         /** Set the height of one row by its position. currentHeight is for internal use only */
         setHeight: (row: number|number[], height: number|number[], currentHeight?: number|number[]) => void;
-        /** Create a merge cells based on a given cell, colspan and rowspan or an object multiple entries A1: [1,1], or null for the current selected cells */
-        setMerge(cellName: Record<string, [number, number]>): false | undefined;
+        /**
+         * Merges cell ranges based on a configuration or single cell specification.
+         * @intent merge-cells, combine-cells
+         * @param cellName - Cell name (e.g., "A1") or merge config (e.g., { "A1": [3, 2] }).
+         * @param colspan - Columns to span (required if `cellName` is string).
+         * @param rowspan - Rows to span (required if `cellName` is string).
+         * @returns {false | undefined} - False if invalid or overlapping, undefined on success.
+         * @example
+         * setMerge("A1", 3, 2); // Merge A1:C2
+         * setMerge({ "A1": [3, 2], "D4": [2, 4] }); // Merge A1:C2 and D4:E7
+         */
         setMerge(cellName: string, colspan: number, rowspan: number): false | undefined;
-        setMerge(): false | undefined;
+        setMerge(cells: MergeConfig): false | undefined;
         /** Get one or various meta information for one cell. */
         setMeta: (cell: string | Record<string, any>, property?: string, value?: string) => false | undefined;
         /** Set the nested headers */
         setNestedHeaders: (config: Nested[][]) => void;
         /** Deprecated. Alias for parent.setPlugins */
-        setPlugins: (plugins: Record<string, Function>) => void;
-        /** Alias for setProperty */
-        setProperties(columnNumber: number, rowNumber: number, cellSettings?: Cell): boolean;
-        setProperties(columnNumber: number, columnSettings: Column): boolean;
-        setProperties(changes: ({ x: number, value: Column } | { x: number, y: number, value: Cell })[]): boolean;
-        setProperties(changes: Record<string, Cell>): boolean;
+        setPlugins: (plugins: Record<string, Plugin>) => void;
         /** Add a new configuration settings for a column or cell */
         setProperty(columnNumber: number, rowNumber: number, cellSettings?: Cell): boolean;
         setProperty(columnNumber: number, columnSettings: Column): boolean;
@@ -1627,18 +1791,42 @@ declare namespace jspreadsheet {
         setReadOnly: (cellName: string|HTMLElement, state: boolean) => void;
         /** Set the data from one row */
         setRowData: (row: number, data: any[], force?: boolean) => void;
-        /** Set the row id from its position */
+        /**
+         * Assigns custom IDs to one or more rows for tracking or syncing.
+         * @intent update-row-ids, set-row-identifiers
+         * @param row - Row index or object mapping indices to IDs (e.g., { 0: 1000 }).
+         * @param newId - New ID for a single row (required if `row` is a number).
+         * @example
+         * setRowId(0, 1000); // Set row 0 to ID 1000
+         * setRowId({ 0: 1000, 1: 1001 }); // Batch update
+         */
         setRowId(row: Record<number, number>): void;
         setRowId(row: number, newId: number): void;
-        /** Set the style for one cell. Ex. setStyle('A1', 'background-color', 'red') */
+        /**
+         * Applies CSS styles to one or more cells.
+         * @intent format-cells, set-style
+         * @param cell - Cell name (e.g., "A1"), array of cells, or style object (e.g., { "A1": "color: red" }).
+         * @param property - CSS property (e.g., "background-color"), required if `cell` is not an object.
+         * @param value - CSS value (e.g., "red"), optional if `cell` is an object.
+         * @param forceOverwrite - If true, applies even to locked cells. Defaults to false.
+         * @returns {false | undefined} - False if invalid, undefined on success.
+         * @example
+         * setStyle("A1", "background-color", "red"); // Red background for A1
+         * setStyle({ "A1": "color: blue", "B2": "font-weight: bold" }); // Batch styling
+         */
         setStyle(cell: string | string[] | { x: number, y: number }[], property: string, value?: string, forceOverwrite?: boolean): false | undefined;
         setStyle(cell: Record<string, string>, property?: undefined, value?: undefined, forceOverwrite?: boolean): false | undefined;
         /**
-         * Set a cell value
-         *
-         * @param cell destination cell
-         * @param value
-         * @param force value over readonly cells
+         * Writes a value to a cell or range, optionally forcing over read-only cells.
+         * @intent set-cell-value, write-data
+         * @param cell - Cell identifier (e.g., "A1") or array of coordinate-value objects (e.g., [{ x: 0, y: 0, value: "test" }]).
+         * @param value - Value to set (required if `cell` is a string).
+         * @param forceOverwrite - If true, writes even to read-only cells. Defaults to false.
+         * @param origin - Source of change (e.g., "user", "script"). Optional.
+         * @returns {false | undefined} - False if operation fails (e.g., invalid cell), undefined on success.
+         * @example
+         * setValue("A1", "Hello"); // Set A1 to "Hello"
+         * setValue([{ x: 0, y: 0, value: "Test" }, { x: 1, y: 1, value: 42 }]); // Batch update
          */
         setValue: (cell: SetValueFirstArgument, value?: any, forceOverwrite?: boolean, origin?: string) => false | undefined;
         /**
@@ -1651,7 +1839,7 @@ declare namespace jspreadsheet {
          */
         setValueFromCoords: (x: number, y: number, value: any, force?: boolean) => void;
         /** Set viewport width and height */
-        setViewport: (width: number, height: number) => void;
+        setViewport: (width?: number, height?: number) => void;
         /** Set the width of one column by its position */
         setWidth: (col: number | number[], width: number | number[], oldWidth?: number | number[]) => void;
         /** Show column */
@@ -1686,7 +1874,7 @@ declare namespace jspreadsheet {
         /** Internal method: update cells in a batch */
         updateCells: (o: Record<string, any>[]) => void;
         /** Update the selection based on coordinates */
-        updateSelectionFromCoords: (x1: number | number, y1: number | number, x2?: number | number, y2?: number | number, origin?: boolean, type?: string, color?: string) => void;
+        updateSelectionFromCoords: (x1: number, y1: number, x2?: number, y2?: number, origin?: boolean, type?: string, color?: string) => void;
         /** Getter/setter the value by coordinates */
         value?: (x: number | string, y: number, value?: any, removeProperty?: boolean) => any;
         /** Current page or which page the row number is */
@@ -1748,18 +1936,19 @@ declare namespace jspreadsheet {
                 properties: Nested
             }[]
         ): false | undefined;
-        /** Get a validation object. Require the extension Validations. */
+        /** Get a validation object. */
         getValidations: (validationIndex?: number) => Validation | Validation[] | undefined;
-        /** Insert or update existing validations by index. Require the extension Validations. */
+        /** Insert or update existing validations by index. */
         setValidations: (validations: Validations | Validations[]) => false | undefined;
-        /** Reset validations by validation indexes. Require the extension Validations. Undefined will remove all validations */
+        /** Reset validations by validation indexes. Undefined will remove all validations */
         resetValidations: (validationIndex?: number | number[]) => false | undefined;
         /** Load all validations rules from a cell based on its coordinates. */
         loadValidations(xOrCell: Records, y?: undefined, includeIndexes?: boolean): Validation[] | { index: number, rules: Validation }[] | undefined;
         loadValidations(xOrCell: number, y: number, includeIndexes?: boolean): Validation[] | { index: number, rules: Validation }[] | undefined;
         /** This method returns true if a cell fails to meet all the defined validation criteria. If invoked without arguments, this method will scan the entire worksheet and return true if it detects validation errors. */
+        hasErrors(): boolean;
         hasErrors(col: string): boolean;
-        hasErrors(col?: number, row?: number): boolean;
+        hasErrors(col: number, row: number): boolean;
         /** Resize columns to match the visible content */
         autoWidth: (columns: number[]) => void;
         /** Show the column headers */
@@ -1799,12 +1988,26 @@ declare namespace jspreadsheet {
         hideToolbar: () => void;
         /** Refresh the toolbar based on the current worksheet */
         refreshToolbar: (worksheet?: worksheetInstance) => void;
-        /** Add, update or delete a worksheet media */
-        setMedia: (items: Partial<Media> | Partial<Media[]>) => void;
+        /**
+         * Adds or updates media elements (charts, images, shapes) in the worksheet.
+         * @intent add-charts, insert-images, create-shapes
+         * @param items - Array of media objects to add or update (e.g., charts, images).
+         * @returns {false | undefined} - False if invalid, undefined on success.
+         * @example
+         * setMedia([{ id: "random-guid", type: "chart", top: 50, options: { type: "bar", range: "A1:B10" } }]);
+         * setMedia([{ id: "random-guid", type: "image", src: "logo.png", top: 10, left: 10 }]);
+         */
+        setMedia: (items: Media[]) => false | undefined;
         /** Get a media element position or object by guid. */
         getMedia: (guid: string, position?: boolean) => number | Media | null;
-        /** List of all guids to delete. Can be charts and images */
-        deleteMedia: (items: DeleteMediaItem | DeleteMediaItem[]) => false | undefined;
+        /**
+         * Deletes media elements by their GUIDs.
+         * @intent delete-media, remove-chart
+         * @param items - Array of GUIDs or objects with id to delete.
+         * @example
+         * deleteMedia(["chart1", { id: "img1" }]);
+         */
+        deleteMedia: (items: DeleteMediaItem[]) => false | undefined;
         /** Add a global formula to the tracking system. Use from formula pro. Only use if necessary. */
         setTracking: () => void;
         /** Set a worksheet zoom value > 0 and <= 1. */