@univerjs/core 1.0.0-rc.0 → 1.0.0

package/lib/types/docs/data-model/text-x/action-types.d.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 import type { UpdateDocsAttributeType } from '../../../shared/command-enum';
-import type { IDocumentBody } from '../../../types/interfaces/i-document-data';
+import type { ICustomRange, IDocumentBody } from '../../../types/interfaces/i-document-data';
 export declare const PRESERVE_INSERTED_PARAGRAPH_IDS = "__textXPreserveParagraphIds";
 export declare enum TextXActionType {
     RETAIN = "r",
@@ -30,6 +30,20 @@ export interface IRetainAction {
     body?: IDocumentBody;
     oldBody?: IDocumentBody;
     coverType?: UpdateDocsAttributeType;
+    /**
+     * Identity edits applied after the text operation, with absolute result-document offsets.
+     * nextRangeId restores array order by identity (null means the end), including coincident SDT nesting.
+     * Collaboration peers must support this extension; legacy TextX implementations ignore it.
+     */
+    rangeUpdates?: Array<{
+        rangeId: string;
+        range: ICustomRange | null;
+        nextRangeId?: string | null;
+        /** Only these property paths are written; missing values remove properties. Arrays are atomic. */
+        propertyPaths?: string[][];
+    }>;
+    /** Before-document values captured by makeInvertible; never persisted in a document body. */
+    oldRangeUpdates?: IRetainAction['rangeUpdates'];
 }
 /**
  * Insert mutation is used to insert text (maybe with rich text properties) at the given position.
@@ -38,6 +52,8 @@ export interface IInsertAction {
     t: TextXActionType.INSERT;
     body: IDocumentBody;
     len: number;
+    /** Scalar selection intent, not snapshot data. All collaboration peers must support this extension. */
+    valueRangeId?: string;
 }
 /**
  * Delete mutation is used to delete text at the given position.
@@ -46,5 +62,7 @@ export interface IDeleteAction {
     t: TextXActionType.DELETE;
     len: number;
     body?: IDocumentBody;
+    /** Preserved through inversion so undo participates in scalar conflict resolution. */
+    valueRangeId?: string;
 }
 export type TextXAction = IRetainAction | IInsertAction | IDeleteAction;

package/lib/types/docs/data-model/text-x/apply-utils/common.d.ts

@@ -32,7 +32,7 @@ export declare function insertTextRuns(body: IDocumentBody, insertBody: IDocumen
  * @param textLength The length of the inserted content text.
  * @param currentIndex Determining the index where the content will be inserted into the current content.
  */
-export declare function insertParagraphs(body: IDocumentBody, insertBody: IDocumentBody, textLength: number, currentIndex: number, preserveMissingParagraphIds?: boolean, originalDataStream?: string): void;
+export declare function insertParagraphs(body: IDocumentBody, insertBody: IDocumentBody, textLength: number, currentIndex: number, isUpdate?: boolean, originalDataStream?: string): void;
 export declare function normalizeInsertedParagraphIdsForDocument(paragraphs: IParagraph[] | undefined, insertParagraphs: IParagraph[] | undefined, currentIndex: number, options: {
     freshenSplitParagraph: boolean;
     preserveExplicitSplitParagraphIds?: boolean;

package/lib/types/docs/data-model/text-x/apply-utils/delete-apply.d.ts

@@ -13,5 +13,5 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import type { IDocumentBody } from '../../../../types/interfaces';
+import type { IDocumentBody } from '../../../../types/interfaces/i-document-data';
 export declare function updateAttributeByDelete(body: IDocumentBody, textLength: number, currentIndex: number): IDocumentBody;

package/lib/types/docs/data-model/text-x/apply-utils/insert-apply.d.ts

@@ -13,5 +13,5 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import type { IDocumentBody } from '../../../../types/interfaces';
+import type { IDocumentBody } from '../../../../types/interfaces/i-document-data';
 export declare function updateAttributeByInsert(body: IDocumentBody, insertBody: IDocumentBody, textLength: number, currentIndex: number): void;

package/lib/types/docs/data-model/text-x/apply.d.ts

@@ -13,6 +13,6 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import type { IDocumentBody } from '../../../types/interfaces';
+import type { IDocumentBody } from '../../../types/interfaces/i-document-data';
 import type { TextXAction } from './action-types';
 export declare function textXApply(doc: IDocumentBody, actions: TextXAction[]): IDocumentBody;

package/lib/types/docs/data-model/text-x/build-utils/text-x-utils.d.ts

@@ -20,6 +20,7 @@ import type { CustomRangeType, IDocumentBody } from '../../../../types/interface
 import type { DocumentDataModel } from '../../document-data-model';
 import type { TextXAction } from '../action-types';
 import type { TextXSelection } from '../text-x';
+import { DocumentFlavor } from '../../../../types/interfaces/i-document-data';
 import { TextX } from '../text-x';
 export interface IDeleteCustomRangeParam {
     rangeId: string;
@@ -40,7 +41,7 @@ export interface IAddCustomRangeTextXParam {
 export declare function addCustomRangeTextX(param: IAddCustomRangeTextXParam): false | (TextX & {
     selections?: ITextRange[];
 });
-export declare function deleteSelectionTextX(selections: ITextRange[], body: IDocumentBody, memoryCursor?: number, insertBody?: Nullable<IDocumentBody>, keepBullet?: boolean): Array<TextXAction>;
+export declare function deleteSelectionTextX(selections: ITextRange[], body: IDocumentBody, memoryCursor?: number, insertBody?: Nullable<IDocumentBody>, keepBullet?: boolean, documentFlavor?: DocumentFlavor): Array<TextXAction>;
 export declare function retainSelectionTextX(selections: ITextRange[], body: IDocumentBody, memoryCursor?: number): TextXAction[];
 export interface IReplaceSelectionTextXParams {
     /**

package/lib/types/docs/data-model/text-x/custom-range-update.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Copyright 2023-present DreamNum Co., Ltd.
+ *
+ * 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.
+ */
+import type { ICustomRange, IDocumentBody } from '../../../types/interfaces/i-document-data';
+import type { IRetainAction, TextXAction } from './action-types';
+export declare function getChangedPropertyPaths(before: unknown, after: unknown, path?: string[]): string[][];
+export declare function composeRangeUpdate(first: NonNullable<IRetainAction['rangeUpdates']>[number] | undefined, second: NonNullable<IRetainAction['rangeUpdates']>[number]): NonNullable<IRetainAction['rangeUpdates']>[number];
+export declare function transformRangeUpdate(update: NonNullable<IRetainAction['rangeUpdates']>[number], concurrent: NonNullable<IRetainAction['rangeUpdates']>[number] | undefined, priority: 'left' | 'right'): NonNullable<IRetainAction['rangeUpdates']>;
+export declare function getRangeUpdates(actions: TextXAction[]): NonNullable<IRetainAction['rangeUpdates']>;
+export declare function withoutRangeUpdates(actions: TextXAction[]): TextXAction[];
+export declare function appendRangeUpdates(actions: TextXAction[], updates: IRetainAction['rangeUpdates']): TextXAction[];
+export declare function validateRangeUpdates(updates: IRetainAction['rangeUpdates'], resultLength: number): void;
+export declare function applyRangeUpdates(doc: IDocumentBody, updates: IRetainAction['rangeUpdates']): void;
+export declare function moveRangeUpdates(updates: NonNullable<IRetainAction['rangeUpdates']>, actions: TextXAction[], preserveProperties?: boolean): NonNullable<IRetainAction['rangeUpdates']>;
+/** A concurrent metadata payload must not resurrect an explicitly removed identity. */
+export declare function reconcileRangeUpdates(actions: TextXAction[], updates: IRetainAction['rangeUpdates']): TextXAction[];
+/** Dropping a concurrent restoration also drops its delimiters, not its text. */
+export declare function dropRemovedRangeAnchors(actions: TextXAction[], suppressed: ICustomRange[], updates: NonNullable<IRetainAction['rangeUpdates']>): TextXAction[];

package/lib/types/docs/data-model/text-x/structure-validator.d.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 import type { IDocumentBody, IDocumentData } from '../../../types/interfaces/i-document-data';
-export type DocStructureIssueCode = 'missing-note' | 'invalid-note-reference' | 'nested-note' | 'invalid-note-body' | 'invalid-note-id' | 'duplicate-note-reference' | 'missing-root-paragraph' | 'missing-root-section-break' | 'paragraph-token-mismatch' | 'duplicate-paragraph-metadata' | 'section-break-token-mismatch' | 'duplicate-section-break-metadata' | 'missing-section-id' | 'duplicate-section-id' | 'table-start-token-mismatch' | 'table-end-token-mismatch' | 'missing-table-metadata' | 'overlapping-table' | 'block-range-token-mismatch' | 'missing-block-range-metadata' | 'overlapping-block-range' | 'unbalanced-block' | 'column-group-range-token-mismatch' | 'missing-column-group-metadata' | 'overlapping-column-group' | 'column-group-column-count-mismatch' | 'custom-block-token-mismatch' | 'missing-custom-block-metadata' | 'duplicate-custom-block-metadata' | 'empty-column' | 'empty-table-cell' | 'unbalanced-column-group' | 'unbalanced-table';
+export type DocStructureIssueCode = 'missing-note' | 'invalid-note-reference' | 'nested-note' | 'invalid-note-body' | 'invalid-note-id' | 'duplicate-note-reference' | 'missing-root-paragraph' | 'missing-root-section-break' | 'paragraph-token-mismatch' | 'duplicate-paragraph-metadata' | 'section-break-token-mismatch' | 'duplicate-section-break-metadata' | 'missing-section-id' | 'duplicate-section-id' | 'table-start-token-mismatch' | 'table-end-token-mismatch' | 'missing-table-metadata' | 'overlapping-table' | 'block-range-token-mismatch' | 'missing-block-range-metadata' | 'overlapping-block-range' | 'unbalanced-block' | 'column-group-range-token-mismatch' | 'missing-column-group-metadata' | 'overlapping-column-group' | 'column-group-column-count-mismatch' | 'custom-block-token-mismatch' | 'missing-custom-block-metadata' | 'duplicate-custom-block-metadata' | 'custom-range-token-mismatch' | 'missing-custom-range-metadata' | 'duplicate-custom-range-id' | 'crossing-custom-range' | 'unbalanced-custom-range' | 'empty-column' | 'empty-table-cell' | 'unbalanced-column-group' | 'unbalanced-table';
 export interface IDocStructureIssue {
     code: DocStructureIssueCode;
     segmentType: 'body' | 'header' | 'footer' | 'note';

package/lib/types/docs/data-model/text-x/text-x.d.ts

@@ -14,8 +14,8 @@
  * limitations under the License.
  */
 import type { ITextRange } from '../../../sheets/typedef';
-import type { IDocumentBody } from '../../../types/interfaces/i-document-data';
-import type { TextXAction } from './action-types';
+import type { ICustomRange, IDocumentBody } from '../../../types/interfaces/i-document-data';
+import type { IRetainAction, TextXAction } from './action-types';
 import { UpdateDocsAttributeType } from '../../../shared/command-enum';
 export type TPriority = 'left' | 'right';
 export declare class TextX {
@@ -48,7 +48,7 @@ export declare class TextX {
      *      2) If the other body property exists, then execute the TransformBody logic to override it
      */
     static transform(thisActions: TextXAction[], otherActions: TextXAction[], priority?: TPriority): TextXAction[];
-    static _transform(thisActions: TextXAction[], otherActions: TextXAction[], priority?: TPriority): TextXAction[];
+    static _transform(thisActions: TextXAction[], otherActions: TextXAction[], priority?: TPriority, rangeAnchorAffinity?: boolean): TextXAction[];
     /**
      * Used to transform selection. Why not named transformSelection?
      * Because Univer Doc supports multiple Selections in one document, user need to encapsulate transformSelections at the application layer.
@@ -58,6 +58,10 @@ export declare class TextX {
     static invert(actions: TextXAction[]): TextXAction[];
     static makeInvertible(actions: TextXAction[], doc: IDocumentBody): TextXAction[];
     private _actions;
+    /** Edits only changed property leaves; does not replace range identity, bounds or peer properties. */
+    updateCustomRangeProperties(range: ICustomRange, properties: NonNullable<ICustomRange['properties']>): this;
+    /** Updates identities after all text edits; range positions refer to the resulting document. */
+    updateCustomRanges(updates: NonNullable<IRetainAction['rangeUpdates']>): this;
     insert(len: number, body: IDocumentBody): this;
     retain(len: number, body?: IDocumentBody, coverType?: UpdateDocsAttributeType): this;
     delete(len: number): this;

package/lib/types/docs/data-model/text-x/utils.d.ts

@@ -17,6 +17,7 @@ import type { ICustomColumnGroup, ICustomDecoration, IDocumentBlockRange, IDocum
 import type { DocumentDataModel } from '../../data-model';
 import type { IRetainAction } from './action-types';
 import { UpdateDocsAttributeType } from '../../../shared/command-enum';
+import { CustomRangeType } from '../../../types/interfaces/i-document-data';
 export declare enum SliceBodyType {
     copy = 0,
     cut = 1
@@ -40,10 +41,13 @@ export declare function getParagraphsSlice(body: IDocumentBody, startOffset: num
     styleId?: string;
     paragraphStyle?: import("../../..").IParagraphStyle;
     bullet?: import("../../..").IBullet;
+    sourceBullet?: import("../../..").IBullet | null;
+    directBullet?: import("../../..").IBullet | null;
 }[] | undefined;
 export declare function getSectionBreakSlice(body: IDocumentBody, startOffset: number, endOffset: number): {
     startIndex: number;
     sectionId: string;
+    pageBorders?: import("../../..").IPageBorders;
     pageNumberStart?: number;
     pageSize?: import("../../..").ISize;
     pageOrient?: import("../../..").PageOrientType;
@@ -79,6 +83,8 @@ export declare function getCustomBlockSlice(body: IDocumentBody, startOffset: nu
     startIndex: number;
     blockType?: import("../../..").BlockType;
     blockId: string;
+    noteType?: "footnote" | "endnote" | "separator" | "continuationSeparator";
+    noteId?: string;
     docxRawXml?: string;
     docxExportTs?: import("../../..").ITextStyle;
 }[] | undefined;
@@ -95,7 +101,7 @@ export declare function getCustomRangeSlice(body: IDocumentBody, startOffset: nu
         startIndex: number;
         endIndex: number;
         rangeId: string;
-        rangeType: import("../../..").CustomRangeType | number;
+        rangeType: CustomRangeType | number;
         wholeEntity?: boolean;
         properties?: Record<string, any> | undefined;
     }[];

package/lib/types/docs/sdt-binding.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Copyright 2023-present DreamNum Co., Ltd.
+ *
+ * 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.
+ */
+import type { IDocumentBody, ISdtCustomRange } from '../types/interfaces/i-document-data';
+export declare function getSdtBindingKey(range: ISdtCustomRange): string | undefined;
+/** Scalar XML values, independent of the control's display label or date format. */
+export declare function getSdtBindingValue(body: IDocumentBody, range: ISdtCustomRange): string | undefined;

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

@@ -22,7 +22,7 @@ export interface IFBlobSource {
      */
     getBlob(): FBlob;
     /**
-     * Return the data inside this object as a blob converted to the specified content type.
+     * Returns a copy labeled with the specified MIME type. The data bytes are not converted or re-encoded.
      * @param contentType the content type refer to https://developer.mozilla.org/en-US/docs/Web/HTTP/MIME_types/Common_types
      */
     getAs(contentType: string): FBlob;
@@ -46,9 +46,9 @@ export declare class FBlob extends FBase {
      */
     copyBlob(): FBlob;
     /**
-     * Return the data inside this object as a blob converted to the specified content type.
+     * Returns a copy labeled with the specified MIME type. The data bytes are not converted or re-encoded.
      * @param contentType the content type refer to https://developer.mozilla.org/en-US/docs/Web/HTTP/MIME_types/Common_types
-     * @returns a new blob by converting the current blob to the specified content type
+     * @returns {FBlob} A new facade containing the same data with the specified MIME type.
      * @example
      * ```ts
      * const blob = univerAPI.newBlob();
@@ -59,7 +59,7 @@ export declare class FBlob extends FBase {
     getAs(contentType: string): FBlob;
     /**
      * Get the blob as a string.
-     * @returns
+     * @returns {Promise<string>} A promise resolving to decoded text; an unset blob returns an empty string.
      * @example
      * ```ts
      * const blob = univerAPI.newBlob();
@@ -70,8 +70,8 @@ export declare class FBlob extends FBase {
     getDataAsString(): Promise<string>;
     /**
      * Get the blob as a string.
-     * @param charset the charset
-     * @returns the blob content as a string
+     * @param {string} [charset] TextDecoder encoding label. Defaults to UTF-8.
+     * @returns {Promise<string>} A promise resolving to decoded text; an unset blob returns an empty string.
      * @example
      * ```ts
      * const blob = univerAPI.newBlob();
@@ -82,10 +82,10 @@ export declare class FBlob extends FBase {
     getDataAsString(charset?: string): Promise<string>;
     /**
      * Gets the data stored in this blob.
-     * @returns the blob content as a byte array
+     * @returns {Promise<Uint8Array>} A promise resolving to the bytes; rejects if no blob data is set.
      * @example
      * ```ts
-     * const blob = univerAPI.newBlob();
+     * const blob = univerAPI.newBlob().setDataFromString('Hello, World!');
      * const bytes = await blob.getBytes();
      * console.log(bytes);
      * ```
@@ -117,7 +117,7 @@ export declare class FBlob extends FBase {
     /**
      * Sets the data stored in this blob.
      * @param data a string
-     * @param contentType the content type refer to https://developer.mozilla.org/en-US/docs/Web/HTTP/MIME_types/Common_types
+     * @param [contentType] the content type refer to https://developer.mozilla.org/en-US/docs/Web/HTTP/MIME_types/Common_types
      * @returns the blob object
      * @example
      * ```ts
@@ -128,7 +128,7 @@ export declare class FBlob extends FBase {
     setDataFromString(data: string, contentType?: string): FBlob;
     /**
      * Gets the content type of the data stored in this blob.
-     * @returns the content type
+     * @returns {string | undefined} The MIME type, or `undefined` if no blob data is set.
      * @example
      * ```ts
      * const blob = univerAPI.newBlob();
@@ -138,7 +138,7 @@ export declare class FBlob extends FBase {
      */
     getContentType(): string | undefined;
     /**
-     * Sets the content type of the data stored in this blob.
+     * Sets the MIME type without converting or re-encoding the data bytes. Has no effect when no blob data is set.
      * @param contentType the content type refer to https://developer.mozilla.org/en-US/docs/Web/HTTP/MIME_types/Common_types
      * @returns the blob object
      * @example

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

@@ -13,15 +13,23 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { AbsoluteRefType, AutoFillSeries, BaselineOffset, BooleanNumber, BorderStyleTypes, BorderType, ColorType, CommandType, CommonHideTypes, CopyPasteType, DataValidationErrorStyle, DataValidationOperator, DataValidationRenderMode, DataValidationStatus, DataValidationType, DeleteDirection, DeveloperMetadataVisibility, Dimension, Direction, HorizontalAlign, ImageSourceType, InterpolationPointType, LifecycleStages, LocaleType, MentionType, NamedStyleType, NumberUnitType, PresetListType, ProtectionType, RelativeDate, SheetTypes, SpacingRule, TextDecoration, TextDirection, ThemeColorType, UniverInstanceType, VerticalAlign, WrapStrategy } from '@univerjs/core';
+import { AbsoluteRefType, AutoFillSeries, BaselineOffset, BooleanNumber, BorderStyleTypes, BorderType, ColorType, CommandType, CommonHideTypes, CopyPasteType, DataValidationErrorStyle, DataValidationOperator, DataValidationRenderMode, DataValidationStatus, DataValidationType, DeleteDirection, DeveloperMetadataVisibility, Dimension, Direction, FormulaType, HorizontalAlign, ImageSourceType, InterpolationPointType, LifecycleStages, LocaleType, MentionType, NamedStyleType, NumberUnitType, PresetListType, ProtectionType, RelativeDate, SheetTypes, SpacingRule, TextDecoration, TextDirection, ThemeColorType, UniverInstanceType, VerticalAlign, WorksheetHiddenState, WrapStrategy } from '@univerjs/core';
 /**
  * @hideconstructor
  */
 export declare class FEnum {
+    /** SpreadsheetML formula types. */
+    get FormulaType(): typeof FormulaType;
+    /** Worksheet hiding states: VISIBLE (0), HIDDEN (1), VERY_HIDDEN (2). */
+    get WorksheetHiddenState(): typeof WorksheetHiddenState;
     /**
      * @ignore
      */
     static _instance: FEnum | null;
+    /**
+     * Returns the shared registry of Facade enum values.
+     * @returns {FEnum} The registry also exposed by `univerAPI.Enum`.
+     */
     static get(): FEnum;
     /**
      * @ignore

package/lib/types/facade/f-event-registry.d.ts

@@ -22,14 +22,26 @@ export declare class FEventRegistry {
     protected _eventHandlerMap: Map<string, Set<() => IDisposable | Subscription>>;
     protected _eventHandlerRegisted: Map<string, Map<() => IDisposable | Subscription, IDisposable>>;
     protected _ensureEventRegistry(event: string): Registry<(param: any) => void>;
+    /**
+     * Registers a factory for the underlying subscription that produces an event.
+     * The factory starts when the event has listeners; its subscription is disposed when the last listener is removed.
+     * @param {string} event The event name.
+     * @param {() => IDisposable | Subscription} handler Creates the underlying event subscription.
+     * @returns {IDisposable} Unregisters the factory and disposes its active subscription.
+     */
     registerEventHandler(event: string, handler: () => IDisposable | Subscription): IDisposable;
+    /**
+     * Removes one event listener and stops underlying subscriptions when no listeners remain.
+     * @param {T} event The event name.
+     * @param {(params: IEventParamConfig[T]) => void} callback The previously registered callback.
+     */
     removeEvent<T extends keyof IEventParamConfig>(event: T, callback: (params: IEventParamConfig[T]) => void): void;
     private _initEventHandler;
     /**
      * Add an event listener
-     * @param {string} event key of event
-     * @param {(params: IEventParamConfig[typeof event]) => void} callback callback when event triggered
-     * @returns {Disposable} The Disposable instance, for remove the listener
+     * @param {T} event key of event
+     * @param {(params: IEventParamConfig[T]) => void} callback callback when event triggered
+     * @returns {IDisposable} A disposable that removes the event listener.
      * @example
      * ```ts
      * univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, (params) => {
@@ -41,9 +53,9 @@ export declare class FEventRegistry {
     addEvent<T extends keyof IEventParamConfig>(event: T, callback: (params: IEventParamConfig[T]) => void): IDisposable;
     /**
      * Fire an event, used in internal only.
-     * @param {string} event key of event
-     * @param {any} params params of event
-     * @returns {boolean} should cancel
+     * @param {T} event key of event
+     * @param {IEventParamConfig[T]} params params of event
+     * @returns {boolean | undefined} The event's `cancel` value after listeners run; `undefined` if it was not set.
      * @example
      * ```ts
      * this.fireEvent(univerAPI.Event.LifeCycleChanged, params);

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

@@ -84,6 +84,10 @@ export declare class FEventName {
      * @ignore
      */
     static _instance: FEventName | null;
+    /**
+     * Returns the shared registry of Facade event names.
+     * @returns {FEventName} The registry also exposed by `univerAPI.Event`.
+     */
     static get(): FEventName;
     /**
      * @ignore

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

@@ -40,7 +40,7 @@ export declare class FUniver extends Disposable {
     protected readonly _univerInstanceService: IUniverInstanceService;
     protected readonly _lifecycleService: LifecycleService;
     /**
-     * Create an FUniver instance, if the injector is not provided, it will create a new Univer instance.
+     * Creates a Facade API instance for an existing Univer instance or its injector.
      * @static
      * @param {Univer | Injector} wrapped - The Univer instance or injector instance.
      * @returns {FUniver} - The FUniver instance.
@@ -63,14 +63,21 @@ export declare class FUniver extends Disposable {
         prototype: object;
     }): void;
     protected _eventRegistry: FEventRegistry;
+    /**
+     * Registers a factory for the subscription that produces an event.
+     * The factory starts when listeners exist and its subscription is disposed when the last listener is removed.
+     * @param event The event name.
+     * @param handler Creates the underlying event subscription.
+     * @returns A disposable that unregisters the factory and disposes its active subscription.
+     */
     registerEventHandler: (event: string, handler: () => IDisposable | Subscription) => IDisposable;
     constructor(_injector: Injector, _commandService: ICommandService, _univerInstanceService: IUniverInstanceService, _lifecycleService: LifecycleService);
     private _initCommandEvent;
     private _initBeforeCommandEvent;
     private _initUnitEvent;
     /**
-     * Dispose the UniverSheet by the `unitId`. The UniverSheet would be unload from the application.
-     * @param unitId The unit id of the UniverSheet.
+     * Disposes the document, workbook, or other Univer unit identified by `unitId`, unloading it from the application.
+     * @param unitId The ID of the unit to dispose.
      * @returns Whether the Univer instance is disposed successfully.
      *
      * @example
@@ -233,9 +240,9 @@ export declare class FUniver extends Disposable {
     /**
      * 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.
+     * @param [params] Parameters of this execution.
+     * @param [options] Options of this execution.
+     * @returns {Promise<R>} The result of the execution. It is a boolean value by default which indicates the command is executed.
      *
      * @example
      * ```ts
@@ -249,8 +256,8 @@ export declare class FUniver extends Disposable {
     /**
      * 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.
+     * @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.
      *
      * @example
@@ -262,14 +269,23 @@ export declare class FUniver extends Disposable {
      * ```
      */
     syncExecuteCommand<P extends object = object, R = boolean>(id: string, params?: P, options?: IExecutionOptions): R;
+    /**
+     * Enums exposed by the registered Facade extensions.
+     */
     get Enum(): FEnum;
+    /**
+     * Event names to use with `addEvent`.
+     */
     get Event(): FEventName;
+    /**
+     * Utility functions exposed by the registered Facade extensions.
+     */
     get Util(): FUtil;
     /**
      * Add an event listener
-     * @param {string} event key of event
-     * @param {(params: IEventParamConfig[typeof event]) => void} callback callback when event triggered
-     * @returns {Disposable} The Disposable instance, for remove the listener
+     * @param {T} event key of event
+     * @param {(params: IEventParamConfig[T]) => void} callback callback when event triggered
+     * @returns {IDisposable} A disposable that removes the event listener.
      * @example
      * ```ts
      * // Add life cycle changed event listener
@@ -284,15 +300,23 @@ export declare class FUniver extends Disposable {
     addEvent<T extends keyof IEventParamConfig>(event: T, callback: (params: IEventParamConfig[T]) => void): IDisposable;
     /**
      * Fire an event, used in internal only.
-     * @param {string} event key of event
-     * @param {any} params params of event
-     * @returns {boolean} should cancel
+     * @param {T} event key of event
+     * @param {IEventParamConfig[T]} params params of event
+     * @returns {boolean | undefined} The event's `cancel` value after listeners run; `undefined` if it was not set.
      * @example
      * ```ts
      * this.fireEvent(univerAPI.Event.LifeCycleChanged, params);
      * ```
      */
     fireEvent<T extends keyof IEventParamConfig>(event: T, params: IEventParamConfig[T]): boolean | undefined;
+    /**
+     * Gets the facade for reading the current user.
+     * @returns {FUserManager} The user manager facade.
+     * @example
+     * ```ts
+     * const user = univerAPI.getUserManager().getCurrentUser();
+     * ```
+     */
     getUserManager(): FUserManager;
     /**
      * Create a new blob.
@@ -343,14 +367,14 @@ export declare class FUniver extends Disposable {
      * This is an advanced document-model API. Application and agent code should normally use
      * `newRichText().paragraph({ ... })`.
      *
-     * @param {IParagraphStyle} style The paragraph style
+     * @param {IParagraphStyle} [style] The paragraph style
      * @returns {ParagraphStyleBuilder} The new paragraph style instance
      * @advanced
      */
     newParagraphStyle(style?: IParagraphStyle): ParagraphStyleBuilder;
     /**
      * Create a new paragraph style value.
-     * @param {IParagraphStyle} style - The paragraph style
+     * @param {IParagraphStyle} [style] - The paragraph style
      * @returns {ParagraphStyleValue} The new paragraph style value instance
      * @example
      * ```ts
@@ -360,7 +384,7 @@ export declare class FUniver extends Disposable {
     newParagraphStyleValue(style?: IParagraphStyle): ParagraphStyleValue;
     /**
      * Create a new text style.
-     * @param {ITextStyle} style - The text style
+     * @param {ITextStyle} [style] - The text style
      * @returns {TextStyleBuilder} The new text style instance
      * @example
      * ```ts
@@ -370,7 +394,7 @@ export declare class FUniver extends Disposable {
     newTextStyle(style?: ITextStyle): TextStyleBuilder;
     /**
      * Create a new text style value.
-     * @param {ITextStyle} style - The text style
+     * @param {ITextStyle} [style] - The text style
      * @returns {TextStyleValue} The new text style value instance
      * @example
      * ```ts
@@ -380,7 +404,7 @@ export declare class FUniver extends Disposable {
     newTextStyleValue(style?: ITextStyle): TextStyleValue;
     /**
      * Create a new text decoration.
-     * @param {ITextDecoration} decoration - The text decoration
+     * @param {ITextDecoration} [decoration] - The text decoration
      * @returns {TextDecorationBuilder} The new text decoration instance
      * @example
      * ```ts

package/lib/types/index.d.ts

@@ -42,6 +42,7 @@ export { mergeSets } from './common/set';
 export { UnitModel, UniverInstanceType } from './common/unit';
 export { isSafeUrl, normalizeUrl, resolveWithBasePath } from './common/url';
 export * from './docs';
+export { getSdtBindingKey, getSdtBindingValue } from './docs/sdt-binding';
 export { EventState, EventSubject, fromEventSubject } from './observer/observable';
 export type { IEventObserver } from './observer/observable';
 export { AuthzIoLocalService } from './services/authz-io/authz-io-local.service';
@@ -115,6 +116,7 @@ export { DataValidationOperator } from './types/enum/data-validation-operator';
 export { DataValidationRenderMode } from './types/enum/data-validation-render-mode';
 export { DataValidationStatus } from './types/enum/data-validation-status';
 export { DataValidationType } from './types/enum/data-validation-type';
+export { FilterSelectionMode, RecordValueType } from './types/enum/record-filter';
 export * from './types/interfaces';
 export type { ICellCustomRender, ICellRenderContext } from './types/interfaces/i-cell-custom-render';
 export type { IDataValidationRule, IDataValidationRuleBase, IDataValidationRuleInfo, IDataValidationRuleOptions, ISheetDataValidationRule, } from './types/interfaces/i-data-validation';