@univerjs/core 0.2.9 → 0.2.10

package/lib/types/index.d.ts

@@ -88,13 +88,6 @@ export { SlideDataModel } from './slides/slide-model';
 export * from './types/const';
 export * from './types/enum';
 export * from './types/interfaces';
-export { ISnapshotServerService } from './services/snapshot/snapshot-server.service';
-export { transformSnapshotToWorkbookData, transformWorkbookDataToSnapshot, transformDocumentDataToSnapshot, transformSnapshotToDocumentData, generateTemporarySnap, generateTempDocumentSnapshot, } from './services/snapshot/snapshot-transform';
-export { textEncoder, textDecoder } from './services/snapshot/snapshot-utils';
-export { type ILogContext } from './services/log/context';
-export { b64DecodeUnicode, b64EncodeUnicode } from './shared/coder';
-export { ClientSnapshotServerService } from './services/snapshot/snapshot-server.service';
-export { getSheetBlocksFromSnapshot } from './services/snapshot/snapshot-transform';
 export { isBlackColor, isWhiteColor } from './shared/color/color-kit';
 export { cellToRange } from './shared/common';
 export type { IDataValidationRule, IDataValidationRuleBase, IDataValidationRuleInfo, IDataValidationRuleOptions, ISheetDataValidationRule } from './types/interfaces/i-data-validation';

package/lib/types/services/authz-io/type.d.ts

@@ -1,5 +1,5 @@
-import { ILogContext } from '@univerjs/core';
 import { IAllowedRequest, IAllowedResponse, IBatchAllowedResponse, ICreateCollaboratorRequest, ICreateRequest, ICreateResponse, IDeleteCollaboratorRequest, IListCollaboratorRequest, IListCollaboratorResponse, IListPermPointRequest, IListPermPointResponse, IListRolesRequest, IListRolesResponse, IPutCollaboratorsRequest, IUpdateCollaboratorRequest, IUpdatePermPointRequest } from '@univerjs/protocol';
+import { ILogContext } from '../log/context';
 export interface IAuthzIoService {
     create(config: ICreateRequest, context?: ILogContext): Promise<ICreateResponse['objectID']>;
     allowed(config: IAllowedRequest, context?: ILogContext): Promise<IAllowedResponse['actions']>;
@@ -16,4 +16,4 @@ export interface IAuthzIoService {
     createCollaborator(config: ICreateCollaboratorRequest, context?: ILogContext): Promise<void>;
     putCollaborators(config: IPutCollaboratorsRequest, context?: ILogContext): Promise<void>;
 }
-export declare const IAuthzIoService: import('@univerjs/core').IdentifierDecorator<IAuthzIoService>;
+export declare const IAuthzIoService: import('../../common/di').IdentifierDecorator<IAuthzIoService>;

package/lib/types/services/command/command.service.d.ts

@@ -2,106 +2,192 @@ import { IAccessor, IDisposable, Injector } from '../../common/di';
 import { Disposable } from '../../shared/lifecycle';
 import { IContextService } from '../context/context.service';
 import { ILogService } from '../log/log.service';
+/**
+ * The type of a command.
+ */
 export declare enum CommandType {
-    /** Command could generate some operations or mutations. */
+    /**
+     * Responsible for creating, orchestrating, and executing MUTATION or OPERATION according to specific business
+     * logic. For example, a delete row COMMAND will generate a delete row MUTATION, an insert row MUTATION for undo,
+     * and a set cell content MUTATION.
+     */
     COMMAND = 0,
-    /** An operation that do not require conflict resolve.  */
+    /**
+     * MUTATION is the change made to the data saved to snapshot, such as inserting rows and columns,
+     * modifying cell content, modifying filter ranges, etc. If you want to add collaborative editing capabilities to
+     * Univer, it is the smallest unit of conflict resolution.
+     */
     OPERATION = 1,
-    /** An operation that need to be resolved before applied on peer client. */
+    /**
+     * OPERATION is the change made to data that is not saved to snapshot, without conflict resolution,
+     * such as modifying scroll position, modifying sidebar state, etc.
+     */
     MUTATION = 2
 }
+/**
+ * In Univer, all data modifications need to be executed through commands. The command-based approach can better track
+ * changes in values, implement functions such as undo, redo, and collaborative editing, handle complex associated
+ * logic between functions, etc.
+ *
+ * All commands should implements this interface or related {@link IMutation} or {@link IOperation} interface, and
+ * should be registered in the {@link ICommandService}.
+ */
 export interface ICommand<P extends object = object, R = boolean> {
     /**
-     * ${businessName}.${type}.${name}
+     * Identifier of the command. It should be unique in the application unless it is a {@link IMultiCommand}.
+     * Its pattern should be like `<namespace>.<type>.<command-name>`.
+     *
+     * @example { id: 'sheet.command.set-selection-frozen' }
      */
     readonly id: string;
+    /**
+     * The type of the command.
+     */
     readonly type: CommandType;
-    handler(accessor: IAccessor, params?: P, options?: IExecutionOptions): Promise<R> | R;
     /**
-     * When this command is unregistered, this function would be called.
-     *
-     * @deprecated
+     * The handler of the command.
+     * @param accessor The accessor to the dependency injection container.
+     * @param params Params of the command. Params should be serializable.
+     * @param options Options of the command.
+     * @returns The result of the command. By default it should be a boolean value which indicates the command is
+     * executed successfully or not.
      */
-    onDispose?: () => void;
+    handler(accessor: IAccessor, params?: P, options?: IExecutionOptions): Promise<R> | R;
 }
+/**
+ * A command that may have multiple implementations. Each implementation should have different `priority`
+ * and `preconditions` callback to determine which implementation should be executed.
+ */
 export interface IMultiCommand<P extends object = object, R = boolean> extends ICommand<P, R> {
+    /** The name of the multi command. It should be unique in the application. */
     name: string;
+    /** @ignore */
     multi: true;
+    /** Priority of this implementation. Implementation with higher priority will be checked first. */
     priority: number;
+    /**
+     * A callback function that tells `ICommandService` if this implementation should be executed.
+     * @param contextService The context service.
+     * @returns If this implementation should be executed, return `true`, otherwise return `false`.
+     */
     preconditions?: (contextService: IContextService) => boolean;
 }
 export interface IMutationCommonParams {
+    /**
+     * It is used to indicate which {@link CommandType.COMMAND} triggers the mutation.
+     */
     trigger?: string;
 }
 /**
- * Mutation would change the model of Univer applications.
+ * {@link CommandType.MUTATION} should implement this interface.
  */
 export interface IMutation<P extends object, R = boolean> extends ICommand<P, R> {
     type: CommandType.MUTATION;
     /**
-     * Mutations must be a sync process.
-     * @param accessor
-     * @param params Params of the mutation. A mutation must has params.
+     * The handler of the mutation.
+     * @param accessor The accessor to the dependency injection container.
+     * @param params Params of the mutation. Params should be serializable.
+     * @returns The result of the mutation. By default it should be a boolean value which indicates the mutation is
+     * executed successfully or not.
      */
     handler(accessor: IAccessor, params: P): R;
 }
 /**
- * Operation would change the state of Univer applications. State should only be in memory and does not
- * require conflicting resolution.
+ * {@link CommandType.OPERATION} should implement this interface.
  */
 export interface IOperation<P extends object = object, R = boolean> extends ICommand<P, R> {
     type: CommandType.OPERATION;
     /**
-     * Operations must be a sync process.
-     * @param accessor
-     * @param params Params of the operation. A operation must has params.
+     * The handler of the operation.
+     * @param accessor The accessor to the dependency injection container.
+     * @param params Params of the operation. Params should be serializable.
+     * @returns The result of the operation. By default it should be a boolean value which indicates the operation is
+     * executed successfully or not.
      */
     handler(accessor: IAccessor, params: P): R;
 }
 /**
- * The command info, only a command id and responsible params
+ * This object represents an execution of a command.
  */
 export interface ICommandInfo<T extends object = object> {
+    /**
+     * Id of the command being executed.
+     */
     id: string;
+    /**
+     * Type of the command.
+     */
     type?: CommandType;
     /**
-     * Args should be serializable.
+     * Parameters of this execution.
      */
     params?: T;
 }
+/** This object represents an execution of a {@link CommandType.MUTATION} */
 export interface IMutationInfo<T extends object = object> {
     id: string;
     type?: CommandType.MUTATION;
     params: T;
 }
+/** This object represents an execution of a {@link CommandType.OPERATION} */
 export interface IOperationInfo<T extends object = object> {
     id: string;
     type?: CommandType.OPERATION;
     params: T;
 }
 export interface IExecutionOptions {
-    /** This mutation should only be executed on the local machine, and not synced to replicas. */
+    /** This mutation should only be executed on the local machine, and should not be synced to replicas. */
     onlyLocal?: boolean;
     /** This command is from collaboration peers. */
     fromCollab?: boolean;
+    /** @deprecated */
     fromChangeset?: boolean;
     [key: PropertyKey]: string | number | boolean | undefined;
 }
 export type CommandListener = (commandInfo: Readonly<ICommandInfo>, options?: IExecutionOptions) => void;
+/**
+ * The identifier of the command service.
+ */
+export declare const ICommandService: import('../../common/di').IdentifierDecorator<ICommandService>;
+/**
+ * The service to register and execute commands.
+ */
 export interface ICommandService {
     /**
      * Check if a command is already registered at the current command service.
-     *
      * @param commandId The id of the command.
+     * @returns If the command is registered, return `true`, otherwise return `false`.
      */
     hasCommand(commandId: string): boolean;
+    /**
+     * Register a command to the command service.
+     * @param command The command to register.
+     */
     registerCommand(command: ICommand<object, unknown>): IDisposable;
+    /**
+     * Register a command as a multi command.
+     * @param command The command to register as a multi command.
+     */
     registerMultipleCommand(command: ICommand<object, unknown>): IDisposable;
+    /**
+     * Execute a command with the given id and parameters.
+     * @param id Identifier of the command.
+     * @param params Parameters of this execution.
+     * @param options Options of this execution.
+     * @returns The result of the execution. It is a boolean value by default which indicates the command is executed.
+     */
     executeCommand<P extends object = object, R = boolean>(id: string, params?: P, options?: IExecutionOptions): Promise<R>;
-    hasCommand(id: string): boolean;
+    /**
+     * Execute a command with the given id and parameters synchronously.
+     * @param id Identifier of the command.
+     * @param params Parameters of this execution.
+     * @param options Options of this execution.
+     * @returns The result of the execution. It is a boolean value by default which indicates the command is executed.
+     */
     syncExecuteCommand<P extends object = object, R = boolean>(id: string, params?: P, options?: IExecutionOptions): R;
     /**
      * Register a callback function that will be executed after a command is executed.
+     * @param listener
      */
     onCommandExecuted(listener: CommandListener): IDisposable;
     /**
@@ -110,11 +196,7 @@ export interface ICommandService {
      */
     beforeCommandExecuted(listener: CommandListener): IDisposable;
 }
-export declare const ICommandService: import('../../common/di').IdentifierDecorator<ICommandService>;
-/**
- * The registry of commands.
- */
-export declare class CommandRegistry {
+declare class CommandRegistry {
     private readonly _commands;
     private readonly _commandTypes;
     registerCommand(command: ICommand): IDisposable;
@@ -149,3 +231,4 @@ export declare class CommandService extends Disposable implements ICommandServic
 }
 export declare function sequenceExecute(tasks: ICommandInfo[], commandService: ICommandService, options?: IExecutionOptions): import('../../common/sequence').ISequenceExecuteResult;
 export declare function sequenceExecuteAsync(tasks: ICommandInfo[], commandService: ICommandService, options?: IExecutionOptions): Promise<import('../../common/sequence').ISequenceExecuteResult>;
+export {};

package/lib/types/shared/numfmt.d.ts

@@ -1,2 +1,3 @@
-import { default as numfmt } from 'numfmt';
+import { INumfmt } from './types/numfmt.type';
+declare const numfmt: INumfmt;
 export { numfmt };

package/lib/types/shared/types/numfmt.type.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Copyright 2023-present DreamNum Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+type FormatType = 'currency' | 'date' | 'datetime' | 'error' | 'fraction' | 'general' | 'grouped' | 'number' | 'percent' | 'scientific' | 'text' | 'time';
+/**
+ * An arbirarty number that represents the format's specificity if you want to compare one to another. Integer comparisons roughly match Excel's resolutions when it determines which format wins out.
+ *
+ * text: 15
+ * datetime: 10.8
+ * date: 10.8
+ * time: 10.8
+ * percent: 10.6
+ * currency: 10.4
+ * grouped: 10.2
+ * scientific: 6
+ * number: 4
+ * fraction: 2
+ * general: 0
+ * error: 0
+ */
+type Level = 15 | 10.8 | 10.6 | 10.4 | 10.2 | 6 | 4 | 2 | 0;
+interface Info {
+    type: FormatType;
+    /**
+     * Correspond to the output from same named functions found on the formatters.
+     */
+    isDate: boolean;
+    isText: boolean;
+    isPercent: boolean;
+    /** The maximum number of decimals this format will emit. */
+    maxDecimals: number;
+    /**
+     * 1 if the format uses color on the negative portion of the string, else a 0. This replicates Excel's CELL("color") functionality.
+     */
+    color: 0 | 1;
+    /**
+     * 1 if the positive portion of the number format contains an open parenthesis, else a 0. This is replicates Excel's CELL("parentheses") functionality.
+     */
+    parentheses: 0 | 1;
+    /**
+     * 1 if the positive portion of the format uses a thousands separator, else a 0.
+     */
+    grouped: 1;
+    /**
+     * Corresponds to Excel's CELL("format") functionality. It is should match Excel's quirky behaviour fairly well.
+     */
+    code: string;
+    /**
+     * The multiplier used when formatting the number (100 for percentages).
+     */
+    scale: 1;
+    /**
+     * An arbirarty number that represents the format's specificity if you want to compare one to another. Integer comparisons roughly match Excel's resolutions when it determines which format wins out.
+     */
+    level: Level;
+    _partitions: Array<{
+        color: string;
+        tokens: Array<{
+            type: 'num';
+            num: string;
+        } | {
+            type: 'point';
+            value: string;
+        } | {
+            type: 'frac';
+            num: string;
+        }>;
+    }>;
+}
+interface DateInfo {
+    /** If any `y` or `b` operator was found in the pattern. */
+    year: boolean;
+    /** If any `m` operator was found in the pattern. */
+    month: boolean;
+    /** If any `d` operator was found in the pattern (including ones that emit weekday). */
+    day: boolean;
+    /** If any `h` operator was found in the pattern. */
+    hours: boolean;
+    /** If any `:m` operator was found in the pattern. */
+    minutes: boolean;
+    /** If any `s` operator was found in the pattern. */
+    seconds: boolean;
+    /** Will be set to `12` if AM/PM operators are being used in the formatting string, else it will be set to `24`. */
+    clockType: 24 | 12;
+}
+interface Options {
+    /**
+     * A [BCP 47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) string tag. Locale default is english with a \u00a0 grouping symbol
+     *
+     * @default ""
+     */
+    locale: LocaleTag;
+    /**
+     * Should the formatter throw an error if a provided pattern is invalid. If not, a formatter will be constructed which only ever outputs an error string (see invalid in this table).
+     * @default true
+     */
+    throws: boolean;
+    /**
+     * The string emitted when no-throw mode fails to parse a pattern.
+     * @default "######"
+     */
+    invalid: string;
+    /**
+     * By default the formatters will emit [non-breaking-space](https://en.wikipedia.org/wiki/Non-breaking_space) rather than a regular space when emitting the formatted number. Setting this to false will make it use regular spaces instead.
+     * @default true
+     */
+    nbsp: boolean;
+    /**
+     * Simulate the Lotus 1-2-3 [1900 leap year bug](https://docs.microsoft.com/en-us/office/troubleshoot/excel/wrongly-assumes-1900-is-leap-year). It is a requirement in the Ecma OOXML specification so it is on by default.
+     *
+     * @default false
+     */
+    leap1900: boolean;
+    /**
+     * Should the formatter throw an error when trying to format a date that is out of bounds?
+     *
+     * @default false
+     */
+    dateErrorThrows: boolean;
+    /**
+     * Should the formatter switch to a General number format when trying to format a date that is out of bounds?
+     * @default true
+     */
+    dateErrorNumber: boolean;
+    /**
+     * The string emitted when a formatter fails to format a date that is out of bounds.
+     * @default "######"
+     */
+    overflow: string;
+    /**
+     * Extends the allowed range of dates from Excel bounds (1900–9999) to Google Sheet bounds (0–99999).
+     * @default true
+     */
+    dateSpanLarge: boolean;
+    /**
+     * Normally when date objects are used with the formatter, time zone is taken into account. This makes the formatter ignore the timezone offset.
+     * @default false
+     */
+    ignoreTimezone: boolean;
+    /**
+     * when using the numfmt.parseDate, numfmt.parseValue and numfmt.dateFromSerial functions, the output will be a Date object.
+     * @default false
+     */
+    nativeDate: boolean;
+}
+interface LocaleData {
+    group: string;
+    decimal: string;
+    positive: string;
+    negative: string;
+    percent: string;
+    exponent: string;
+    nan: string;
+    infinity: string;
+    ampm: [string, string];
+    mmmm: string[];
+    mmm: string[];
+    dddd: string[];
+    ddd: string[];
+    mmmm6: string[];
+    mmm6: string[];
+}
+interface Formatter {
+    isDate(): boolean;
+    isPercent(): boolean;
+    isText(): boolean;
+    color(value: number): string;
+    info: Info;
+    dateInfo: DateInfo;
+    (value: number): string;
+}
+type LocaleTag = 'zh-CN' | 'zh' | 'zh-TW' | 'cs' | 'da' | 'nl' | 'en' | 'fi' | 'fr' | 'de' | 'el' | 'hu' | 'is' | 'id' | 'it' | 'ja' | 'ko' | 'nb' | 'pl' | 'pt' | 'ru' | 'sk' | 'es' | 'sv' | 'th' | 'tr';
+export interface ParsedReturnType {
+    /**
+     * The parsed value. For dates, this will be an Excel style serial date unless the nativeDate option is used.
+     */
+    v: number | string | boolean | Date;
+    /**
+     * (Optionally) the number format string of the input. This property will not be present if it amounts to the General format.
+     */
+    z?: string;
+}
+type _Year = number;
+type _MonthIndex = number;
+type _Date = number | undefined;
+type _Hours = number | undefined;
+type _Minutes = number | undefined;
+type _Seconds = number | undefined;
+type _Ms = number | undefined;
+type DateValue = [_Year, _MonthIndex, _Date, _Hours, _Minutes, _Seconds, _Ms];
+type ParseValue = number | boolean | DateValue | Date | null;
+export interface INumfmt {
+    (value: string, opt?: Options): Formatter;
+    format(pattern: string, value: ParseValue, opt?: Partial<Options>): string;
+    round(value: number, places?: number): number;
+    /**
+     * @internal
+     */
+    parseLocale(tag: LocaleTag): void;
+    getLocale(tag: LocaleTag): LocaleData | null;
+    addLocale(data: Partial<LocaleData>, tag: LocaleTag): void;
+    isDate(format: string): boolean;
+    isPercent(format: string): boolean;
+    isText(format: string): boolean;
+    getInfo(format: string): Info;
+    parseValue(value: string, op?: Options): ParsedReturnType;
+    parseNumber(value: string, op?: Options): ParsedReturnType;
+    parseDate(value: string, op?: Options): ParsedReturnType;
+    parseTime(value: string, op?: Options): ParsedReturnType;
+    parseBool(value: string, op?: Options): ParsedReturnType;
+    dateToSerial(value: Date | [number, number, number], opt?: Options): number | string;
+    dateFromSerial(value: number, opt?: Options): Date;
+    options(op: Partial<Options>): void;
+}
+export {};

package/lib/types/shared/types.d.ts

@@ -30,3 +30,6 @@ export interface IKeyValue {
 export interface IKeyType<T> {
     [key: string]: T;
 }
+export type DeepReadonly<T> = {
+    readonly [P in keyof T]: DeepReadonly<T[P]>;
+};

package/lib/types/sheets/typedef.d.ts

@@ -184,7 +184,7 @@ export interface ICellDataForSheetInterceptor extends ICellData {
     dataValidation?: Nullable<ICellValidationData>;
     markers?: ICellMarks;
     customRender?: Nullable<ICellCustomRender[]>;
-    interceptorAutoHeight?: number;
+    interceptorAutoHeight?: () => number | undefined;
     /**
      * can cell be covered when sibling is overflow
      */

package/lib/types/types/const/const.d.ts

@@ -136,3 +136,7 @@ export declare const DEFAULT_SLIDE: {
         height: number;
     };
 };
+/**
+ * Univer internal key on cellData.custom to save some internal values
+ */
+export declare const UNIVER_INTERNAL = "__univer_internal__";