@univerjs/sheets-ui 0.6.1 → 0.6.2-nightly.202503031606

package/lib/types/facade/f-range.d.ts

@@ -1,7 +1,7 @@
 import { ICellWithCoord, IDisposable, ISelectionCell, Nullable, DisposableCollection } from '@univerjs/core';
 import { ISelectionStyle } from '@univerjs/sheets';
-import { ComponentType, ComponentManager } from '@univerjs/ui';
 import { ICanvasPopup, ICellAlert } from '@univerjs/sheets-ui';
+import { ComponentType, ComponentManager } from '@univerjs/ui';
 import { FRange } from '@univerjs/sheets/facade';
 export interface IFComponentKey {
     /**
@@ -25,28 +25,39 @@ interface IFRangeSheetsUIMixin {
      * Return this cell information, including whether it is merged and cell coordinates
      * @returns {ICellWithCoord} cell location and coordinate.
      * @example
-     * ``` ts
-     * let sheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * sheet.getRange(5, 7).getCell();
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fRange = fWorksheet.getRange('H6');
+     * console.log(fRange.getCell());
      * ```
      */
     getCell(this: FRange): ICellWithCoord;
     /**
      * Returns the coordinates of this cell,does not include units
-     * @returns coordinates of the cell， top, right, bottom, left
+     * @returns {DOMRect} coordinates of the cell， top, right, bottom, left
      * @example
-     * ``` ts
-     * let sheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * sheet.getRange(5, 7).getCellRect();
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fRange = fWorksheet.getRange('H6');
+     * console.log(fRange.getCellRect());
      * ```
      */
     getCellRect(this: FRange): DOMRect;
     /**
      * Generate HTML content for the range.
+     * @returns {string} HTML content of the range.
      * @example
-     * ``` ts
-     * let sheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * sheet.getRange(5, 7).generateHTML();
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fRange = fWorksheet.getRange('A1:B2');
+     * fRange.setValues([
+     *   [1, 2],
+     *   [3, 4]
+     * ]);
+     * console.log(fRange.generateHTML());
      * ```
      */
     generateHTML(this: FRange): string;
@@ -54,76 +65,110 @@ interface IFRangeSheetsUIMixin {
      * Attach a popup to the start cell of current range.
      * If current worksheet is not active, the popup will not be shown.
      * Be careful to manager the detach disposable object, if not dispose correctly, it might memory leaks.
-     * @param popup The popup to attach
-     * @returns The disposable object to detach the popup, if the popup is not attached, return `null`.
+     * @param {IFCanvasPopup} popup The popup to attach
+     * @returns {Nullable<IDisposable>} The disposable object to detach the popup, if the popup is not attached, return `null`.
      * @example
-    ```
-        univerAPI.getComponentManager().register(
-            'myPopup',
-            () => React.createElement('div', {
-                style: {
-                    color: 'red',
-                    fontSize: '14px'
-                }
-            }, 'Custom Popup')
-        );
-
-        let sheet = univerAPI.getActiveWorkbook().getActiveSheet();
-        let range = sheet.getRange(2, 2, 3, 3);
-        univerAPI.getActiveWorkbook().setActiveRange(range);
-        let disposable = range.attachPopup({
-            componentKey: 'myPopup'
-        });
-    ```
+     * ```ts
+     * // Register a custom popup component
+     * univerAPI.registerComponent(
+     *   'myPopup',
+     *   () => React.createElement('div', {
+     *     style: {
+     *       color: 'red',
+     *       fontSize: '14px'
+     *     }
+     *   }, 'Custom Popup')
+     * );
+     *
+     * // Attach the popup to the start cell of range C3:E5
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fRange = fWorksheet.getRange('C3:E5');
+     * const disposable = fRange.attachPopup({
+     *   componentKey: 'myPopup'
+     * });
+     *
+     * // Detach the popup after 5 seconds
+     * setTimeout(() => {
+     *   disposable.dispose();
+     * }, 5000);
+     * ```
      */
     attachPopup(popup: IFCanvasPopup): Nullable<IDisposable>;
     /**
      * Attach an alert popup to the start cell of current range.
-     * @param alert The alert to attach
-     * @returns The disposable object to detach the alert.
+     * @param {Omit<ICellAlert, 'location'>} alert The alert to attach
+     * @returns {IDisposable} The disposable object to detach the alert.
      * @example
      * ```ts
-     * let sheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * let range = sheet.getRange(2, 2, 3, 3);
-     * range.attachAlertPopup({ message: 'This is an alert', type: 'warning' });
+     * // Attach an alert popup to the start cell of range C3:E5
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fRange = fWorksheet.getRange('C3:E5');
+     *
+     * const disposable = fRange.attachAlertPopup({
+     *   title: 'Warning',
+     *   message: 'This is an warning message',
+     *   type: 1
+     * });
+     *
+     * // Detach the alert after 5 seconds
+     * setTimeout(() => {
+     *   disposable.dispose();
+     * }, 5000);
      * ```
      */
     attachAlertPopup(alert: Omit<ICellAlert, 'location'>): IDisposable;
     /**
      * Attach a DOM popup to the current range.
-     * @param alert The alert to attach
-     * @returns The disposable object to detach the alert.
+     * @param {IFCanvasPopup} alert The alert to attach
+     * @returns {Nullable<IDisposable>} The disposable object to detach the alert.
      * @example
      * ```ts
-        let sheet = univerAPI.getActiveWorkbook().getActiveSheet();
-        let range = sheet.getRange(2, 2, 3, 3);
-        univerAPI.getActiveWorkbook().setActiveRange(range);
-
-        univerAPI.getComponentManager().register(
-            'myPopup',
-            () => React.createElement('div', {
-                style: {
-                    background: 'red',
-                    fontSize: '14px'
-                }
-            }, 'Custom Popup')
-        );
-        let disposable = range.attachRangePopup({
-            componentKey: 'myPopup',
-            direction: 'top' // 'vertical' | 'horizontal' | 'top' | 'right' | 'left' | 'bottom' | 'bottom-center' | 'top-center';
-        });
+     * // Register a custom popup component
+     * univerAPI.registerComponent(
+     *   'myPopup',
+     *   () => React.createElement('div', {
+     *     style: {
+     *       background: 'red',
+     *       fontSize: '14px'
+     *     }
+     *   }, 'Custom Popup')
+     * );
+     *
+     * // Attach the popup to the range C3:E5
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fRange = fWorksheet.getRange('C3:E5');
+     * const disposable = fRange.attachRangePopup({
+     *   componentKey: 'myPopup',
+     *   direction: 'top' // 'vertical' | 'horizontal' | 'top' | 'right' | 'left' | 'bottom' | 'bottom-center' | 'top-center'
+     * });
      * ```
      */
     attachRangePopup(popup: IFCanvasPopup): Nullable<IDisposable>;
     /**
-     *  Highlight the range with the specified style and primary cell.
-     * @param style - style for highlight range.
-     * @param primary - primary cell for highlight range.
+     * Highlight the range with the specified style and primary cell.
+     * @param {Nullable<Partial<ISelectionStyle>>} style - style for highlight range.
+     * @param {Nullable<ISelectionCell>} primary - primary cell for highlight range.
+     * @returns {IDisposable} The disposable object to remove the highlight.
      * @example
      * ```ts
-     * let sheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * let range = sheet.getRange(2, 2, 3, 3);
-     * range.highlight({ stroke: 'red' }, { startRow: 2, startColumn: 2 });
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Highlight the range C3:E5 with default style
+     * const fRange = fWorksheet.getRange('C3:E5');
+     * fRange.highlight();
+     *
+     * // Highlight the range C7:E9 with custom style
+     * const fRange2 = fWorksheet.getRange('C7:E9');
+     * const disposable = fRange2.highlight({ stroke: 'red', fill: 'yellow' });
+     *
+     * // Remove the range C7:E9 highlight after 5 seconds
+     * setTimeout(() => {
+     *   disposable.dispose();
+     * }, 5000);
      * ```
      */
     highlight(style?: Nullable<Partial<ISelectionStyle>>, primary?: Nullable<ISelectionCell>): IDisposable;

package/lib/types/facade/f-sheet-hooks.d.ts

@@ -7,6 +7,7 @@ import { FSheetHooks } from '@univerjs/sheets/facade';
 export interface IFSheetHooksUIMixin {
     /**
      * The onCellPointerMove event is fired when a pointer changes coordinates.
+     * @deprecated use `univerAPI.addEvent(univerAPI.Event.CellPointerMove, (params) => {})` instead
      * @param {function(Nullable<IHoverCellPosition>): void} callback - function that will be called when the event is fired
      * @returns {IDisposable} A disposable object that can be used to unsubscribe from the event
      * @example
@@ -17,6 +18,7 @@ export interface IFSheetHooksUIMixin {
     onCellPointerMove(callback: (cellPos: Nullable<IHoverCellPosition>) => void): IDisposable;
     /**
      * The onCellPointerOver event is fired when a pointer is moved into a cell's hit test boundaries.
+     * @deprecated use `univerAPI.addEvent(univerAPI.Event.CellHover, (params) => {})` instead
      * @param {function(Nullable<IHoverCellPosition>): void} callback - function that will be called when the event is fired
      * @returns {IDisposable} A disposable object that can be used to unsubscribe from the event
      * @example
@@ -27,6 +29,7 @@ export interface IFSheetHooksUIMixin {
     onCellPointerOver(callback: (cellPos: Nullable<IHoverCellPosition>) => void): IDisposable;
     /**
      * The onCellDragOver event is fired when an element or text selection is being dragged into a cell's hit test boundaries.
+     * @deprecated use `univerAPI.addEvent(univerAPI.Event.DragOver, (params) => {})` instead
      * @param {function (Nullable<IDragCellPosition>): void} callback Callback function that will be called when the event is fired
      * @returns {IDisposable} A disposable object that can be used to unsubscribe from the event
      * @example
@@ -37,6 +40,7 @@ export interface IFSheetHooksUIMixin {
     onCellDragOver(callback: (cellPos: Nullable<IDragCellPosition>) => void): IDisposable;
     /**
      * The onCellDrop event is fired when an element or text selection is being dropped on the cell.
+     * @deprecated use `univerAPI.addEvent(univerAPI.Event.Drop, (params) => {})` instead
      * @param {function(Nullable<IDragCellPosition>): void} callback Callback function that will be called when the event is fired
      * @returns {IDisposable} A disposable object that can be used to unsubscribe from the event
      * @example
@@ -69,6 +73,7 @@ export interface IFSheetHooksUIMixin {
     onCellRender(customRender: Nullable<ICellCustomRender[]>, effect?: InterceptorEffectEnum, priority?: number): IDisposable;
     /**
      * The onBeforeCellEdit event is fired before a cell is edited.
+     * @deprecated use `univerAPI.addEvent(univerAPI.Event.BeforeSheetEditStart, (params) => {})` instead
      * @param callback Callback function that will be called when the event is fired
      * @returns A disposable object that can be used to unsubscribe from the event
      * @example
@@ -79,6 +84,7 @@ export interface IFSheetHooksUIMixin {
     onBeforeCellEdit(callback: (params: IEditorBridgeServiceVisibleParam) => void): IDisposable;
     /**
      * The onAfterCellEdit event is fired after a cell is edited.
+     * @deprecated use `univerAPI.addEvent(univerAPI.Event.SheetEditEnded, (params) => {})` instead
      * @param callback Callback function that will be called when the event is fired
      * @returns A disposable object that can be used to unsubscribe from the event
      * @example

package/lib/types/facade/f-workbook.d.ts

@@ -1,61 +1,107 @@
 import { IDisposable, Nullable } from '@univerjs/core';
 import { IMouseEvent, IPointerEvent } from '@univerjs/engine-render';
 import { ICellPosWithEvent, IDragCellPosition, IHoverRichTextInfo, IHoverRichTextPosition, IScrollState } from '@univerjs/sheets-ui';
+import { IDialogPartMethodOptions, ISidebarMethodOptions } from '@univerjs/ui';
 import { ICellEventParam } from './f-event';
 import { FWorkbook } from '@univerjs/sheets/facade';
-import { IDialogPartMethodOptions, ISidebarMethodOptions } from '@univerjs/ui';
 /**
  * @ignore
  */
 export interface IFWorkbookSheetsUIMixin {
     /**
      * Open a sidebar.
-     * @deprecated
-     * @param params the sidebar options
-     * @returns the disposable object
+     * @deprecated use `univerAPI.openSidebar` instead
+     * @param {ISidebarMethodOptions} params the sidebar options
+     * @returns {IDisposable} the disposable object
+     * @example
+     * ```ts
+     * univerAPI.openSidebar({
+     *   id: 'mock-sidebar-id',
+     *   width: 300,
+     *   header: {
+     *     label: 'Sidebar Header',
+     *   },
+     *   children: {
+     *     label: 'Sidebar Content',
+     *   },
+     *   footer: {
+     *     label: 'Sidebar Footer',
+     *   },
+     *   onClose: () => {
+     *     console.log('Sidebar closed')
+     *   },
+     * });
+     * ```
      */
     openSiderbar(params: ISidebarMethodOptions): IDisposable;
     /**
      * Open a dialog.
-     * @deprecated
-     * @param dialog the dialog options
-     * @returns the disposable object
+     * @deprecated use `univerAPI.openDialog` instead
+     * @param {IDialogPartMethodOptions} dialog the dialog options
+     * @returns {IDisposable} the disposable object
+     * @example
+     * ```ts
+     * import { Button } from '@univerjs/design';
+     *
+     * univerAPI.openDialog({
+     *   id: 'mock-dialog-id',
+     *   width: 500,
+     *   title: {
+     *     label: 'Dialog Title',
+     *   },
+     *   children: {
+     *     label: 'Dialog Content',
+     *   },
+     *   footer: {
+     *     title: (
+     *       <>
+     *         <Button onClick={() => { console.log('Cancel clicked') }}>Cancel</Button>
+     *         <Button type="primary" onClick={() => { console.log('Confirm clicked') }} style={{marginLeft: '10px'}}>Confirm</Button>
+     *       </>
+     *     )
+     *   },
+     *   draggable: true,
+     *   mask: true,
+     *   maskClosable: true,
+     * });
+     * ```
      */
     openDialog(dialog: IDialogPartMethodOptions): IDisposable;
     /**
-     * @deprecated use `univerAPI.addEvent(univerAPI.Event.CellClick, () => {})` instead
+     * @deprecated use `univerAPI.addEvent(univerAPI.Event.CellClicked, (params) => {})` instead
      */
     onCellClick(callback: (cell: IHoverRichTextInfo) => void): IDisposable;
     /**
-     * @deprecated use `univerAPI.addEvent(univerAPI.Event.CellHover, () => {})` instead
+     * @deprecated use `univerAPI.addEvent(univerAPI.Event.CellHover, (params) => {})` instead
      */
     onCellHover(callback: (cell: IHoverRichTextPosition) => void): IDisposable;
     /**
-     * @deprecated use `univerAPI.addEvent(univerAPI.Event.CellPointerMove, () => {})` instead
+     * @deprecated use `univerAPI.addEvent(univerAPI.Event.CellPointerMove, (params) => {})` instead
      */
     onCellPointerMove(callback: (cell: ICellPosWithEvent, event: IPointerEvent | IMouseEvent) => void): IDisposable;
     /**
-     * @deprecated use `univerAPI.addEvent(univerAPI.Event.CellPointerDown, () => {})` instead
+     * @deprecated use `univerAPI.addEvent(univerAPI.Event.CellPointerDown, (params) => {})` instead
      */
     onCellPointerDown(callback: (cell: ICellPosWithEvent) => void): IDisposable;
     /**
-     * @deprecated use `univerAPI.addEvent(univerAPI.Event.CellPointerUp, () => {})` instead
+     * @deprecated use `univerAPI.addEvent(univerAPI.Event.CellPointerUp, (params) => {})` instead
      */
     onCellPointerUp(callback: (cell: ICellPosWithEvent) => void): IDisposable;
     /**
-     * @deprecated use `univerAPI.addEvent(univerAPI.Event.DragOver, () => {})` instead
+     * @deprecated use `univerAPI.addEvent(univerAPI.Event.DragOver, (params) => {})` instead
      */
     onDragOver(callback: (cell: IDragCellPosition) => void): IDisposable;
     /**
-     * @deprecated use `univerAPI.addEvent(univerAPI.Event.Drop, () => {})` instead
+     * @deprecated use `univerAPI.addEvent(univerAPI.Event.Drop, (params) => {})` instead
      */
     onDrop(callback: (cell: IDragCellPosition) => void): IDisposable;
     /**
-     * Start the editing process
-     * @returns A boolean value
+     * Start the editing process of the current active cell
+     * @returns {boolean} Whether the editing process is started successfully
      * @example
      * ```ts
-     * univerAPI.getActiveWorkbook().startEditing();
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * fWorkbook.startEditing();
      * ```
      */
     startEditing(): boolean;
@@ -65,46 +111,72 @@ export interface IFWorkbookSheetsUIMixin {
     endEditing(save?: boolean): Promise<boolean>;
     /**
      * @async
-     * End the editing process
+     * End the editing process of the current active cell
      * @param {boolean} save - Whether to save the changes, default is true
-     * @returns {Promise<boolean>} A promise that resolves to a boolean value
+     * @returns {Promise<boolean>} Whether the editing process is ended successfully
      * @example
      * ```ts
-     * await univerAPI.getActiveWorkbook().endEditingAsync(false);
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * await fWorkbook.endEditingAsync(false);
      * ```
      */
     endEditingAsync(save?: boolean): Promise<boolean>;
+    /**
+     * Get scroll state of specified sheet.
+     * @param {string} sheetId - sheet id
+     * @returns {IScrollState} scroll state
+     * @example
+     * ``` ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // scroll to cell D10
+     * fWorksheet.scrollToCell(9, 3);
+     *
+     * // get scroll state
+     * const scrollState = fWorkbook.getScrollStateBySheetId(fWorksheet.getSheetId());
+     * const { offsetX, offsetY, sheetViewStartRow, sheetViewStartColumn } = scrollState;
+     * console.log(scrollState); // sheetViewStartRow: 9, sheetViewStartColumn: 3, offsetX: 0, offsetY: 0
+     * ```
+     */
     getScrollStateBySheetId(sheetId: string): Nullable<IScrollState>;
     /**
      * Disable selection. After disabled, there would be no response for selection.
-     * @returns {FWorkbook} FWorkbook instance
+     * @returns {FWorkbook} FWorkbook instance for chaining
      * @example
      * ```ts
-     * univerAPI.getActiveWorkbook().disableSelection();
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * fWorkbook.disableSelection();
      * ```
      */
     disableSelection(): FWorkbook;
     /**
      * Enable selection. After this you can select range.
+     * @returns {FWorkbook} FWorkbook instance for chaining
      * @example
      * ```ts
-     * univerAPI.getActiveWorkbook().enableSelection();
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * fWorkbook.enableSelection();
      * ```
      */
     enableSelection(): FWorkbook;
     /**
      * Set selection invisible, Unlike disableSelection, selection still works, you just can not see them.
+     * @returns {FWorkbook} FWorkbook instance for chaining
      * @example
      * ```ts
-     * univerAPI.getActiveWorkbook().transparentSelection();
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * fWorkbook.transparentSelection();
      * ```
      */
     transparentSelection(): FWorkbook;
     /**
      * Set selection visible.
+     * @returns {FWorkbook} FWorkbook instance for chaining
      * @example
      * ```ts
-     * univerAPI.getActiveWorkbook().showSelection();
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * fWorkbook.showSelection();
      * ```
      */
     showSelection(): FWorkbook;