docs(history): optimize api doc for model/history, and fix related lint issues

docs/docs/api/model/history.md

@@ -12,47 +12,113 @@ sidebar_position: 5
 ## 方法签名
 ### go
 
-go(cursor: number)
-
 历史记录跳转到指定位置
 
+```typescript
+/**
+ * 历史记录跳转到指定位置
+ * go to a specific history
+ * @param cursor
+ */
+go(cursor: number): void;
+```
+
 ### back
 
-back()
-
 历史记录后退
 
+```typescript
+/**
+ * 历史记录后退
+ * go backward in history
+ */
+back(): void;
+```
+
 ### forward
 
 forward()
 
 历史记录前进
+
+```typescript
+/**
+ * 历史记录前进
+ * go forward in history
+ */
+forward(): void;
+```
+
 ### savePoint
 
-savePoint()
-
 保存当前状态
-### isSavePoint
 
-isSavePoint()
+```typescript
+/**
+ * 保存当前状态
+ * do save current change as a record in history
+ */
+savePoint(): void;
+```
+
+### isSavePoint
 
 当前是否是「保存点」，即是否有状态变更但未保存
 
+```typescript
+/**
+ * 当前是否是「保存点」，即是否有状态变更但未保存
+ * check if there is unsaved change for history
+ */
+isSavePoint(): boolean;
+```
+
 ### getState
 
-getState()
-
 获取 state，判断当前是否为「可回退」、「可前进」的状态
 
+```typescript
+/**
+ * 获取 state，判断当前是否为「可回退」、「可前进」的状态
+ * get flags in number which indicat current change state
+ *
+ *  |    1     |     1    |    1     |
+ *  | -------- | -------- | -------- |
+ *  | modified | redoable | undoable |
+ * eg:
+ *  7 means : modified && redoable && undoable
+ *  5 means : modified && undoable
+ */
+getState(): number;
+```
+
 ## 事件
 ### onChangeState
 
-onChangeState(func: () => any)
-
 监听 state 变更事件
 
+```typescript
+/**
+ * 监听 state 变更事件
+ * monitor on stateChange event
+ * @param func
+ */
+onChangeState(func: () => any): IPublicTypeDisposable;
+```
+
+相关类型：[IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts)
+
 ### onChangeCursor
 
-onChangeCursor(func: () => any)
-
 监听历史记录游标位置变更事件
+
+```typescript
+/**
+ * 监听历史记录游标位置变更事件
+ * monitor on cursorChange event
+ * @param func
+ */
+onChangeCursor(func: () => any): IPublicTypeDisposable;
+```
+
+相关类型：[IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts)

packages/designer/src/document/history.ts

@@ -1,5 +1,8 @@
 import { reaction, untracked, globalContext, IEventBus, createModuleEventBus } from '@alilc/lowcode-editor-core';
 import { IPublicTypeNodeSchema, IPublicModelHistory } from '@alilc/lowcode-types';
+import { Logger } from '@alilc/lowcode-utils';
+
+const logger = new Logger({ level: 'warn', bizName: 'history' });
 
 export interface Serialization<K = IPublicTypeNodeSchema, T = string> {
   serialize(data: K): T;
@@ -30,11 +33,15 @@ export class History<T = IPublicTypeNodeSchema> implements IHistory {
     },
   };
 
-  setSerialization(serialization: Serialization<T, string>) {
+  get hotData() {
-    this.currentSerialization = serialization;
+    return this.session.data;
   }
 
-  constructor(dataFn: () => T | null, private redoer: (data: T) => void, private timeGap: number = 1000) {
+  constructor(
+      dataFn: () => T | null,
+      private redoer: (data: T) => void,
+      private timeGap: number = 1000,
+    ) {
     this.session = new Session(0, null, this.timeGap);
     this.records = [this.session];
 
@@ -68,8 +75,8 @@ export class History<T = IPublicTypeNodeSchema> implements IHistory {
     }, { fireImmediately: true });
   }
 
-  get hotData() {
+  setSerialization(serialization: Serialization<T, string>) {
-    return this.session.data;
+    this.currentSerialization = serialization;
   }
 
   isSavePoint(): boolean {
@@ -84,16 +91,18 @@ export class History<T = IPublicTypeNodeSchema> implements IHistory {
     this.asleep = false;
   }
 
-  go(cursor: number) {
+  go(originalCursor: number) {
     this.session.end();
 
-    const currentCursor = this.session.cursor;
+    let cursor = originalCursor;
     cursor = +cursor;
     if (cursor < 0) {
       cursor = 0;
     } else if (cursor >= this.records.length) {
       cursor = this.records.length - 1;
     }
+
+    const currentCursor = this.session.cursor;
     if (cursor === currentCursor) {
       return;
     }
@@ -106,7 +115,7 @@ export class History<T = IPublicTypeNodeSchema> implements IHistory {
       this.redoer(this.currentSerialization.unserialize(hotData));
       this.emitter.emit('cursor', hotData);
     } catch (e) /* istanbul ignore next */ {
-      console.error(e);
+      logger.error(e);
     }
 
     this.wakeup();
@@ -174,6 +183,7 @@ export class History<T = IPublicTypeNodeSchema> implements IHistory {
     }
     return state;
   }
+
   /**
    * 监听 state 变更事件
    * @param func
@@ -209,6 +219,7 @@ export class History<T = IPublicTypeNodeSchema> implements IHistory {
     this.emitter.removeAllListeners();
     this.records = [];
   }
+
   /**
    *
    * @deprecated

packages/editor-core/src/utils/preference.ts

@@ -2,15 +2,12 @@ import store from 'store';
 import { getLogger } from './logger';
 import { IPublicModelPreference } from '@alilc/lowcode-types';
 
-const logger = getLogger({ level: 'log', bizName: 'Preference' });
+const logger = getLogger({ level: 'warn', bizName: 'Preference' });
 const STORAGE_KEY_PREFIX = 'ale';
 
-
 /**
  * used to store user preferences, such as pinned status of a pannel.
  * save to local storage.
- *
- * @class PreferenceStore
  */
 export default class Preference implements IPublicModelPreference {
   getStorageKey(key: string, module?: string): string {
@@ -24,7 +21,7 @@ export default class Preference implements IPublicModelPreference {
       return;
     }
     const storageKey = this.getStorageKey(key, module);
-    logger.log('storageKey:', storageKey, 'set with value:', value);
+    logger.debug('storageKey:', storageKey, 'set with value:', value);
     store.set(storageKey, value);
   }
 
@@ -35,16 +32,15 @@ export default class Preference implements IPublicModelPreference {
     }
     const storageKey = this.getStorageKey(key, module);
     const result = store.get(storageKey);
-    logger.log('storageKey:', storageKey, 'get with result:', result);
+    logger.debug('storageKey:', storageKey, 'get with result:', result);
     return result;
   }
+
   /**
    * check if local storage contain certain key
    *
    * @param {string} key
    * @param {string} module
-   * @returns {boolean}
-   * @memberof Preference
    */
   contains(key: string, module: string): boolean {
     if (!key || typeof key !== 'string' || key.length === 0) {

packages/shell/src/model/history.ts

@@ -1,6 +1,6 @@
 import { DocumentModel as InnerDocumentModel } from '@alilc/lowcode-designer';
 import { historySymbol, documentSymbol } from '../symbols';
-import { IPublicModelHistory } from '@alilc/lowcode-types';
+import { IPublicModelHistory, IPublicTypeDisposable } from '@alilc/lowcode-types';
 
 export class History implements IPublicModelHistory {
   private readonly [documentSymbol]: InnerDocumentModel;
@@ -54,7 +54,7 @@ export class History implements IPublicModelHistory {
    * 获取 state，判断当前是否为「可回退」、「可前进」的状态
    * @returns
    */
-  getState(): any {
+  getState(): number {
     return this[historySymbol].getState();
   }
 
@@ -63,7 +63,7 @@ export class History implements IPublicModelHistory {
    * @param func
    * @returns
    */
-  onChangeState(func: () => any): () => void {
+  onChangeState(func: () => any): IPublicTypeDisposable {
     return this[historySymbol].onStateChange(func);
   }
 
@@ -72,7 +72,7 @@ export class History implements IPublicModelHistory {
    * @param func
    * @returns
    */
-  onChangeCursor(func: () => any): () => void {
+  onChangeCursor(func: () => any): IPublicTypeDisposable {
     return this[historySymbol].onCursor(func);
   }
 }

packages/types/src/shell/model/history.ts

@@ -1,49 +1,62 @@
+import { IPublicTypeDisposable } from '../type';
+
 export interface IPublicModelHistory {
 
   /**
    * 历史记录跳转到指定位置
+   * go to a specific history
    * @param cursor
    */
   go(cursor: number): void;
 
   /**
    * 历史记录后退
+   * go backward in history
    */
   back(): void;
 
   /**
    * 历史记录前进
+   * go forward in history
    */
   forward(): void;
 
   /**
    * 保存当前状态
+   * do save current change as a record in history
    */
   savePoint(): void;
 
   /**
    * 当前是否是「保存点」，即是否有状态变更但未保存
-   * @returns
+   * check if there is unsaved change for history
    */
   isSavePoint(): boolean;
 
   /**
    * 获取 state，判断当前是否为「可回退」、「可前进」的状态
-   * @returns
+   * get flags in number which indicat current change state
+   *
+   *  |    1     |     1    |    1     |
+   *  | -------- | -------- | -------- |
+   *  | modified | redoable | undoable |
+   * eg:
+   *  7 means : modified && redoable && undoable
+   *  5 means : modified && undoable
    */
-  getState(): any;
+  getState(): number;
 
   /**
    * 监听 state 变更事件
+   * monitor on stateChange event
    * @param func
-   * @returns
    */
-  onChangeState(func: () => any): () => void;
+  onChangeState(func: () => any): IPublicTypeDisposable;
 
   /**
    * 监听历史记录游标位置变更事件
+   * monitor on cursorChange event
    * @param func
-   * @returns
    */
-  onChangeCursor(func: () => any): () => void;
+  onChangeCursor(func: () => any): IPublicTypeDisposable;
 }