@univerjs/core 1.0.0-alpha.8 → 1.0.0-beta.1

package/lib/types/bases/formula-table-name.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 { IBaseSnapshot, ITableSnapshot } from './typedef';
+type BaseFormulaTable = Pick<ITableSnapshot, 'id' | 'name' | 'formulaName'>;
+interface IBaseFormulaSnapshot {
+    tables: Record<string, BaseFormulaTable>;
+}
+export declare function normalizeBaseFormulaTableName(displayName: string): string;
+export declare function createBaseFormulaTableNameMap(snapshot: IBaseFormulaSnapshot): ReadonlyMap<string, string>;
+export declare function allocateBaseFormulaTableName(displayName: string, existingNames: Iterable<string>, preferredName?: string): string;
+export declare function getBaseFormulaTableName(table: BaseFormulaTable, snapshot: IBaseFormulaSnapshot): string;
+export declare function normalizeBaseFormulaTableReferences(formula: string, snapshot: IBaseFormulaSnapshot): string;
+export declare function createBaseFormulaTableReferenceNormalizer(snapshot: IBaseFormulaSnapshot, formulaNames?: ReadonlyMap<string, string>): (formula: string) => string;
+export declare function migrateBaseFormulaTableNames(snapshot: IBaseSnapshot): void;
+export {};

package/lib/types/bases/index.d.ts

@@ -15,5 +15,7 @@
  */
 export { BaseDataModel } from './base-data-model';
 export { createDefaultBaseTableSnapshot, getEmptySnapshot as getBasesEmptySnapshot, type ICreateDefaultBaseTableSnapshotOptions, } from './empty-snapshot';
-export { BaseFieldType, BaseFilterConjunction, BaseFilterOperator, BaseSortDirection, BaseViewType } from './typedef';
-export type { BaseCellMatrix, BaseCellPrimitiveValue, CellValue as BaseCellValue, BaseCellValueType, BaseHitTestResult, BaseId, PrimitiveCellValue as BasePrimitiveCellValue, BaseSelection, BaseSnapshot, BaseViewProjection, FieldConfig, FieldId, FieldSnapshot, IBaseAttachment, IBaseCellData, IBaseInvalidation, IBaseRect, IBaseResources, IBaseSnapshot, IBaseViewColorCondition, IBaseViewport, ICalendarEventResizeSelection, ICalendarEventSelection, ICalendarProjection, ICalendarViewConfig, ICardLayoutConfig, IFieldCapabilities, IFieldSnapshot, IFilterCondition, IFilterConfig, IGalleryCardSelection, IGalleryProjection, IGalleryViewConfig, IGanttBarSelection, IGanttCellSelection, IGanttProjection, IGanttTimeColumn, IGanttViewConfig, IGridCellSelection, IGridFieldSelection, IGridGroupSelection, IGridProjection, IGridRecordSelection, IGridViewConfig, IGroupConfig, IInvalidViewProjection, IKanbanCardSelection, IKanbanColumnSetting, IKanbanFieldCardSetting, IKanbanProjection, IKanbanViewConfig, IProjectedField, IProjectedGroup, IProjectedRow, IRecordSnapshot, ISortConfig, ITableSnapshot, IValidationResult, IViewFieldSetting, IViewProjection, IViewSnapshot, KanbanCardLayoutMode, RecordId, RecordSnapshot, TableId, TableSnapshot, ViewId, ViewSnapshot, ViewSpecificConfig, } from './typedef';
+export { allocateBaseFormulaTableName, createBaseFormulaTableNameMap, createBaseFormulaTableReferenceNormalizer, getBaseFormulaTableName, migrateBaseFormulaTableNames, normalizeBaseFormulaTableName, normalizeBaseFormulaTableReferences, } from './formula-table-name';
+export { assertBaseTableRecordIdentity, BASE_RECORD_ID_FIELD_ID, BASE_RECORD_ID_FIELD_NAME, createBaseRecordIdField, isBaseRecordIdFieldName, isValidBaseRecordId, } from './record-identity';
+export { BaseConditionalColorOperator, BaseConditionalColorTarget, BaseConditionalDateMode, BaseFieldType, BaseFilterConjunction, BaseFilterOperator, BaseHierarchyInvalidReason, BaseRecordLinkRole, BaseSortDirection, BaseViewType, } from './typedef';
+export type { BaseCellMatrix, BaseCellPrimitiveValue, CellValue as BaseCellValue, BaseCellValueType, BaseDateHourCycle, BaseHitTestResult, BaseId, PrimitiveCellValue as BasePrimitiveCellValue, BaseSelection, BaseSnapshot, BaseViewProjection, FieldConfig, FieldId, FieldSnapshot, IBaseAttachment, IBaseCellData, IBaseConditionalColoringConfig, IBaseConditionalColorRule, IBaseDateFieldConfig, IBaseHierarchyNodeProjection, IBaseHierarchyProjection, IBaseInvalidation, IBaseRect, IBaseResources, IBaseSnapshot, IBaseViewColorCondition, IBaseViewCommonConfig, IBaseViewport, ICalendarEventResizeSelection, ICalendarEventSelection, ICalendarProjection, ICalendarViewConfig, ICardLayoutConfig, IFieldCapabilities, IFieldSnapshot, IFilterCondition, IFilterConfig, IGalleryCardSelection, IGalleryProjection, IGalleryViewConfig, IGanttBarSelection, IGanttCellSelection, IGanttProjection, IGanttTimeColumn, IGanttViewConfig, IGridCellSelection, IGridFieldSelection, IGridGroupSelection, IGridProjection, IGridRecordSelection, IGridViewConfig, IGroupConfig, IInvalidViewProjection, IKanbanCardSelection, IKanbanColumnSetting, IKanbanFieldCardSetting, IKanbanProjection, IKanbanViewConfig, IProjectedField, IProjectedGroup, IProjectedRow, IRecordLinkFieldConfig, IRecordSnapshot, ISortConfig, ITableSnapshot, IValidationResult, IViewFieldSetting, IViewProjection, IViewSnapshot, KanbanCardLayoutMode, RecordId, RecordSnapshot, TableId, TableSnapshot, ViewId, ViewSnapshot, ViewSpecificConfig, } from './typedef';

package/lib/types/bases/record-identity.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 { IFieldSnapshot, ITableSnapshot } from './typedef';
+export declare const BASE_RECORD_ID_FIELD_ID = "__record_id";
+export declare const BASE_RECORD_ID_FIELD_NAME = "record-id";
+export declare function createBaseRecordIdField(): IFieldSnapshot;
+export declare function isValidBaseRecordId(recordId: string): boolean;
+export declare function isBaseRecordIdFieldName(name: string): boolean;
+export declare function assertBaseTableRecordIdentity(table: ITableSnapshot): void;

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

@@ -41,23 +41,41 @@ export interface IBaseResources {
     attachments?: Record<string, Record<string, unknown>>;
 }
 export interface IBaseAttachment {
-    /** Stable attachment identifier. Use the uploaded file id for remote attachments. */
+    /**
+     * Stable attachment identifier.
+     *
+     * Keep this value unique within one attachment cell. For an uploaded attachment, use the
+     * identifier returned by the attachment service.
+     */
     id: string;
-    /** Display name, including the file extension when available. */
+    /** User-visible file name. Include the extension so clients can classify the file when `mimeType` is absent. */
     name: string;
-    /** MIME type used to classify and preview the attachment. */
+    /** MIME type used to classify and preview the attachment, for example `image/webp` or `application/pdf`. */
     mimeType?: string;
-    /** File size in bytes. */
+    /** File size in bytes. This is descriptive metadata and does not affect source loading. */
     size?: number;
-    /** Image width in pixels when known. */
+    /** Image width in pixels when known. This is descriptive metadata used to reserve preview space. */
     width?: number;
-    /** Image height in pixels when known. */
+    /** Image height in pixels when known. This is descriptive metadata used to reserve preview space. */
     height?: number;
-    /** How to interpret `source`, for example UUID, URL, or Base64 data. */
+    /**
+     * How clients should resolve `source`.
+     *
+     * Facade write APIs infer `BASE64` for data URLs and otherwise default to `URL`. Set this
+     * explicitly to `UUID` for identifiers managed by an attachment service.
+     */
     sourceType?: ImageSourceType;
-    /** Canonical attachment source: an uploaded file id, URL, or Base64 data URL. */
+    /**
+     * Canonical attachment source: an uploaded file id, URL, or Base64 data.
+     *
+     * Facade write APIs require a non-empty source for every non-empty attachment entry.
+     */
     source?: string;
-    /** Optional preview source when it is distinct from the canonical attachment source. */
+    /**
+     * Optional preview source when it differs from `source`.
+     *
+     * A data URL is treated as Base64; every other value is treated as a URL.
+     */
     thumbnail?: string;
 }
 export declare enum BaseFieldType {
@@ -72,24 +90,50 @@ export declare enum BaseFieldType {
     Checkbox = "checkbox",
     Link = "link",
     Formula = "formula",
-    Lookup = "lookup",
-    Flow = "flow",
-    Button = "button",
     Numbering = "numbering",
     Phone = "phone",
     Email = "email",
-    Location = "location",
-    Barcode = "barcode",
     Progress = "progress",
     Currency = "currency",
     Rating = "rating",
-    TwoWayLink = "twoWayLink",
+    RecordLink = "recordLink",
     RecordId = "recordId",
     CreatedBy = "createdBy",
     UpdatedBy = "updatedBy",
     CreatedAt = "createdAt",
-    UpdatedAt = "updatedAt",
-    Summary = "summary"
+    UpdatedAt = "updatedAt"
+}
+/** Semantic roles supported by Base RecordLink fields. */
+export declare enum BaseRecordLinkRole {
+    Parent = "parent"
+}
+/**
+ * Configuration for a RecordLink field.
+ *
+ * A RecordLink points to records in another table in the same Base. The cell
+ * stores target record IDs, while the UI resolves those IDs to the configured
+ * display field. Prefer the dedicated RecordLink Facade methods instead of
+ * reading or writing the canonical cell string directly.
+ */
+export interface IRecordLinkFieldConfig extends Record<string, unknown> {
+    /** ID of the target table. The table must belong to the same Base. */
+    targetTableId: TableId;
+    /** `false` allows one linked record; `true` allows an ordered list of linked records. */
+    multiple: boolean;
+    /**
+     * Target-table field used as the visible label in cells, cards, and record details.
+     * Defaults to the target table's primary field. The field must exist and must not
+     * be a system field such as `record-id`.
+     */
+    displayFieldId?: FieldId;
+    /**
+     * Ordered target-table fields shown as secondary context in the record picker.
+     * These fields help users distinguish records; they do not change the stored link
+     * or add more labels to the cell. IDs must be unique, existing, non-system fields.
+     */
+    pickerFieldIds?: FieldId[];
+    /** Optional table-level semantic role of this link. */
+    relationRole?: BaseRecordLinkRole;
 }
 export declare enum BaseViewType {
     Grid = "grid",
@@ -99,7 +143,123 @@ export declare enum BaseViewType {
     Gallery = "gallery"
 }
 export type FieldConfig = Record<string, unknown>;
-export type ViewSpecificConfig = IGridViewConfig | IKanbanViewConfig | ICalendarViewConfig | IGanttViewConfig | IGalleryViewConfig | Record<string, unknown>;
+export type BaseDateHourCycle = 'h12' | 'h24';
+/** Where a Base conditional color is painted when its condition matches. */
+export declare const BaseConditionalColorTarget: {
+    /** Paint only the cell in the rule's field. */
+    readonly CELL: "cell";
+    /** Paint the complete record row. */
+    readonly ROW: "row";
+    /** Paint the rule's field column unconditionally; operator, operand, and date mode are ignored. */
+    readonly COLUMN: "column";
+};
+export type BaseConditionalColorTarget = typeof BaseConditionalColorTarget[keyof typeof BaseConditionalColorTarget];
+/**
+ * Operators supported by Base conditional coloring rules.
+ *
+ * Text, select, person, and similar fields support equality, containment, and
+ * empty checks. Number, currency, progress, and rating fields support equality,
+ * numeric comparison, and empty checks. Date-like fields support equality,
+ * before/after, and empty checks. Checkbox fields support equality only.
+ */
+export declare const BaseConditionalColorOperator: {
+    readonly IS: "is";
+    readonly IS_NOT: "isNot";
+    readonly CONTAINS: "contains";
+    readonly NOT_CONTAINS: "notContains";
+    readonly IS_EMPTY: "isEmpty";
+    readonly IS_NOT_EMPTY: "isNotEmpty";
+    readonly GREATER_THAN: "greaterThan";
+    readonly LESS_THAN: "lessThan";
+    readonly BEFORE: "before";
+    readonly AFTER: "after";
+};
+export type BaseConditionalColorOperator = typeof BaseConditionalColorOperator[keyof typeof BaseConditionalColorOperator];
+/**
+ * Relative or exact date windows supported by date conditional coloring rules.
+ *
+ * With `IS`, dates inside the selected window match. `IS_NOT` matches dates
+ * outside it, `BEFORE` matches dates before its start, and `AFTER` matches
+ * dates after its end. Relative windows do not use an operand; `EXACT` does.
+ */
+export declare const BaseConditionalDateMode: {
+    readonly EXACT: "exact";
+    readonly TODAY: "today";
+    readonly TOMORROW: "tomorrow";
+    readonly YESTERDAY: "yesterday";
+    readonly THIS_WEEK: "thisWeek";
+    readonly LAST_WEEK: "lastWeek";
+    readonly THIS_MONTH: "thisMonth";
+    readonly LAST_MONTH: "lastMonth";
+    readonly PAST_7_DAYS: "past7";
+    readonly NEXT_7_DAYS: "next7";
+    readonly PAST_30_DAYS: "past30";
+    readonly NEXT_30_DAYS: "next30";
+};
+export type BaseConditionalDateMode = typeof BaseConditionalDateMode[keyof typeof BaseConditionalDateMode];
+/**
+ * A color condition stored by a Base view.
+ *
+ * Rules are evaluated in array order. Earlier matching rules are painted last
+ * and therefore have higher visual priority than later matching rules.
+ */
+export interface IBaseViewColorCondition {
+    /** Stable id unique within the view. */
+    id: string;
+    /** Valid CSS color rendered for a match, for example `#fde9e9` or `rgba(255, 0, 0, 0.2)`. */
+    color: string;
+    /** Paint target. Gantt color conditions may omit it for legacy snapshots. */
+    target?: BaseConditionalColorTarget;
+    /** Field whose value is evaluated for cell/row targets, or whose column is painted for a column target. */
+    fieldId: FieldId;
+    /** Comparison performed against the field value. Ignored for a column target. */
+    operator: BaseConditionalColorOperator;
+    /**
+     * Comparison value in the field's normal value shape: number for numeric
+     * fields, boolean for checkbox fields, text/option ids for text and select
+     * fields, or a date-compatible value for an exact date comparison. Ignored
+     * by empty checks, relative date modes, and column targets.
+     */
+    operand?: unknown;
+    /**
+     * Exact or relative date window for Date, CreatedAt, and UpdatedAt fields.
+     * Defaults to `EXACT` when omitted. Ignored for a column target.
+     */
+    dateMode?: BaseConditionalDateMode;
+}
+/** A complete Base conditional coloring rule used by Grid and other Base views. */
+export interface IBaseConditionalColorRule extends IBaseViewColorCondition {
+    /** Paint target for the matching rule. */
+    target: BaseConditionalColorTarget;
+}
+/** Persisted conditional coloring configuration for one Base view. */
+export interface IBaseConditionalColoringConfig {
+    /** Rules in descending visual-priority order. */
+    rules: IBaseConditionalColorRule[];
+}
+/** Configuration shared by every Base view type. */
+export interface IBaseViewCommonConfig {
+    /** Conditional coloring rules, or `null` when the feature is cleared. */
+    conditionalColoring?: IBaseConditionalColoringConfig | null;
+}
+/**
+ * Display options for Date, CreatedAt, and UpdatedAt fields.
+ */
+export interface IBaseDateFieldConfig extends FieldConfig {
+    /**
+     * Date-only display pattern, such as `yyyy/mm/dd`.
+     */
+    pattern?: string;
+    /**
+     * Whether to append a time to the formatted date.
+     */
+    includeTime?: boolean;
+    /**
+     * Explicit 12-hour or 24-hour time format.
+     */
+    hourCycle?: BaseDateHourCycle;
+}
+export type ViewSpecificConfig = IGridViewConfig | IKanbanViewConfig | ICalendarViewConfig | IGanttViewConfig | IGalleryViewConfig | (IBaseViewCommonConfig & Record<string, unknown>);
 export interface IBaseSnapshot {
     id: BaseId;
     name: string;
@@ -116,7 +276,19 @@ export interface IBaseSnapshot {
 }
 export interface ITableSnapshot {
     id: TableId;
+    /**
+     * Human-readable display name, subject to Excel worksheet name rules because
+     * each Base table is exported as a worksheet. Names must be unique within the
+     * Base, ignoring case. Do not use this value as a structured-reference identifier.
+     */
     name: string;
+    /**
+     * Persisted stable identifier used by formulas and exported structured references.
+     *
+     * Historical snapshots may omit this field. Use `getBaseFormulaTableName()` when a
+     * resolved formula identifier is required.
+     */
+    formulaName?: string;
     fields: Record<FieldId, IFieldSnapshot>;
     fieldOrder: FieldId[];
     records: Record<RecordId, IRecordSnapshot>;
@@ -232,7 +404,7 @@ export interface IGroupConfig {
     direction?: BaseSortDirection;
     hideEmptyGroup?: boolean;
 }
-export interface IGridViewConfig {
+export interface IGridViewConfig extends IBaseViewCommonConfig {
     frozenFieldCount?: number;
     showRecordIndex?: boolean;
     rowHeight?: 'short' | 'medium' | 'tall' | 'extraTall';
@@ -252,7 +424,7 @@ export interface IKanbanColumnSetting {
     color?: string;
     collapsed?: boolean;
 }
-export interface IKanbanViewConfig {
+export interface IKanbanViewConfig extends IBaseViewCommonConfig {
     groupFieldId: FieldId;
     coverFieldId?: FieldId | null;
     cardLayout?: KanbanCardLayoutMode;
@@ -261,7 +433,7 @@ export interface IKanbanViewConfig {
     columnSettings?: Record<string, IKanbanColumnSetting>;
     card?: ICardLayoutConfig;
 }
-export interface ICalendarViewConfig {
+export interface ICalendarViewConfig extends IBaseViewCommonConfig {
     startDateFieldId: FieldId;
     endDateFieldId?: FieldId;
     titleFieldId?: FieldId;
@@ -281,16 +453,7 @@ export interface ICalendarViewConfig {
         order?: number;
     }>;
 }
-export interface IBaseViewColorCondition {
-    id: string;
-    color: string;
-    target?: 'cell' | 'row' | 'column';
-    fieldId: FieldId;
-    operator: 'is' | 'isNot' | 'contains' | 'notContains' | 'isEmpty' | 'isNotEmpty' | 'greaterThan' | 'lessThan' | 'before' | 'after';
-    operand?: unknown;
-    dateMode?: 'exact' | 'today' | 'tomorrow' | 'yesterday' | 'thisWeek' | 'lastWeek' | 'thisMonth' | 'lastMonth' | 'past7' | 'next7' | 'past30' | 'next30';
-}
-export interface IGanttViewConfig {
+export interface IGanttViewConfig extends IBaseViewCommonConfig {
     startDateFieldId: FieldId;
     endDateFieldId: FieldId;
     titleFieldId?: FieldId;
@@ -326,7 +489,7 @@ export interface IGanttViewConfig {
         }>;
     };
 }
-export interface IGalleryViewConfig {
+export interface IGalleryViewConfig extends IBaseViewCommonConfig {
     card: ICardLayoutConfig;
     coverFieldId?: FieldId | null;
     cardLayout?: KanbanCardLayoutMode;
@@ -362,13 +525,37 @@ export interface IProjectedGroup {
     level?: number;
     children?: IProjectedGroup[];
 }
+/** Why a stored Parent link cannot participate in the effective hierarchy. */
+export declare enum BaseHierarchyInvalidReason {
+    MissingParent = "missingParent",
+    SelfParent = "selfParent",
+    Cycle = "cycle",
+    MaxDepth = "maxDepth"
+}
+export interface IBaseHierarchyNodeProjection {
+    recordId: RecordId;
+    parentRecordId: RecordId | null;
+    depth: number;
+    directChildCount: number;
+    subtreeHeight: number;
+    subtreeEndIndex: number;
+    invalidReason?: BaseHierarchyInvalidReason;
+}
+export interface IBaseHierarchyProjection {
+    fieldId: FieldId;
+    rootRecordIds: RecordId[];
+    orderedRecordIds: RecordId[];
+    nodes: Record<RecordId, IBaseHierarchyNodeProjection>;
+}
 export interface IGridProjection extends IViewProjection {
     type: BaseViewType.Grid;
     frozenFieldCount?: number;
+    hierarchy?: IBaseHierarchyProjection;
 }
 export interface IKanbanProjection extends IViewProjection {
     type: BaseViewType.Kanban;
     groupFieldId: FieldId;
+    titleFieldId?: FieldId;
     coverFieldId?: FieldId | null;
     cardLayout: KanbanCardLayoutMode;
     showFieldNames: boolean;
@@ -433,6 +620,7 @@ export interface IGanttProjection extends IViewProjection {
 }
 export interface IGalleryProjection extends IViewProjection {
     type: BaseViewType.Gallery;
+    titleFieldId?: FieldId;
     coverFieldId?: FieldId | null;
     cardLayout: KanbanCardLayoutMode;
     showFieldNames: boolean;
@@ -549,6 +737,18 @@ export type BaseHitTestResult = {
     type: 'empty';
     x: number;
     y: number;
+} | {
+    type: 'grid-text-preview';
+    tableId: TableId;
+    viewId: ViewId;
+    recordId: RecordId;
+    fieldId: FieldId;
+    virtual?: boolean;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    maxScroll: number;
 } | {
     type: 'grid-fill-handle';
     tableId: TableId;
@@ -572,6 +772,39 @@ export type BaseHitTestResult = {
     tableId: TableId;
     viewId: ViewId;
     recordId: RecordId;
+} | {
+    type: 'grid-hierarchy-toggle' | 'grid-hierarchy-add-child';
+    tableId: TableId;
+    viewId: ViewId;
+    recordId: RecordId;
+} | {
+    type: 'grid-cell-checkbox';
+    tableId: TableId;
+    viewId: ViewId;
+    recordId: RecordId;
+    fieldId: FieldId;
+} | {
+    type: 'grid-rating-icon';
+    tableId: TableId;
+    viewId: ViewId;
+    recordId: RecordId;
+    fieldId: FieldId;
+    value: number;
+} | {
+    type: 'grid-row-header' | 'grid-row-checkbox';
+    tableId: TableId;
+    viewId: ViewId;
+    recordId: RecordId;
+} | {
+    type: 'grid-row-header-select-all';
+    tableId: TableId;
+    viewId: ViewId;
+} | {
+    type: 'grid-row-drag-handle';
+    tableId: TableId;
+    viewId: ViewId;
+    recordId: RecordId;
+    disabled: boolean;
 } | {
     type: 'kanban-add-record';
     tableId: TableId;

package/lib/types/common/drawing-order.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 { ArrangeTypeEnum } from '../types/interfaces/i-drawing';
+/** Clamps a requested zero-based index to an available drawing order. */
+export declare function normalizeDrawingOrderIndex(index: number, length: number): number;
+/** Resolves a relative drawing arrangement to its zero-based target index. */
+export declare function getDrawingOrderIndex(currentIndex: number, length: number, arrangeType: ArrangeTypeEnum): number;

package/lib/types/docs/data-model/document-data-model.d.ts

@@ -14,6 +14,8 @@
  * limitations under the License.
  */
 import type { Nullable } from '../../shared';
+import type { ITextRangeParam } from '../../sheets/typedef';
+import type { LocaleType } from '../../types/enum';
 import type { IDocumentBody, IDocumentData, IDocumentRenderConfig, IDocumentStyle, IDrawings, IListData } from '../../types/interfaces/i-document-data';
 import type { IPaddingData } from '../../types/interfaces/i-style-data';
 import type { JSONXActions } from './json-x/json-x';
@@ -24,6 +26,19 @@ export declare const DEFAULT_DOC: {
     id: string;
     documentStyle: {};
 };
+export interface IDocumentStatistics {
+    words: number;
+    charactersWithoutSpaces: number;
+    charactersWithSpaces: number;
+    paragraphs: number;
+    nonAsianWords: number;
+    asianCharactersAndKoreanWords: number;
+}
+export interface IDocumentStatisticsOptions {
+    locale?: LocaleType;
+    ranges?: Readonly<ITextRangeParam[]>;
+    signal?: AbortSignal;
+}
 interface IDrawingUpdateConfig {
     left: number;
     top: number;
@@ -81,5 +96,6 @@ export declare class DocumentDataModel extends DocumentDataModelSimple {
     private _initializeHeaderFooterModel;
     updateDocumentId(unitId: string): void;
     getPlainText(): string;
+    getStatistics(options?: IDocumentStatisticsOptions): Promise<IDocumentStatistics>;
 }
 export {};

package/lib/types/{shared/object-matrix-query.d.ts → docs/data-model/document-statistics.d.ts}

@@ -13,10 +13,5 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import type { IRange } from '../sheets/typedef';
-import { ObjectMatrix } from './object-matrix';
-/**
- * @deprecated this function could cause memory out of use in large range.
- */
-export declare function queryObjectMatrix<T>(matrix: ObjectMatrix<T>, match: (value: T) => boolean): IRange[];
-export declare function multiSubtractMultiRanges(ranges1: IRange[], ranges2: IRange[]): IRange[];
+import type { IDocumentStatistics, IDocumentStatisticsOptions } from './document-data-model';
+export declare function calculateDocumentStatistics(dataStream: string, options: IDocumentStatisticsOptions): Promise<IDocumentStatistics>;

package/lib/types/docs/data-model/index.d.ts

@@ -27,7 +27,7 @@ export { DEFAULT_DOCUMENT_SUB_COMPONENT_ID } from './subdocument';
 export { ActionIterator } from './text-x/action-iterator';
 export { PRESERVE_INSERTED_PARAGRAPH_IDS, TextXActionType } from './text-x/action-types';
 export type { IDeleteAction, IInsertAction, IRetainAction, TextXAction } from './text-x/action-types';
-export { normalizeInsertedSectionIdsForDocument, normalizeTextRuns, RESTORE_INSERTED_PARAGRAPH_IDS } from './text-x/apply-utils/common';
+export { normalizeInsertedSectionIdsForDocument, normalizeTextRuns, RESTORE_INSERTED_PARAGRAPH_IDS, } from './text-x/apply-utils/common';
 export { updateAttributeByDelete } from './text-x/apply-utils/delete-apply';
 export { updateAttributeByInsert } from './text-x/apply-utils/insert-apply';
 export * from './text-x/build-utils';

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

@@ -1385,12 +1385,15 @@ export declare class RichTextBuilder extends RichTextValue {
     static create(data?: IDocumentData): RichTextBuilder;
     private _doc;
     private readonly _trackedRanges;
+    private _childHandleRevision;
     constructor(data: IDocumentData);
     /**
      * Returns editable paragraph handles backed by this detached rich-text builder.
      *
-     * Paragraph boundaries come from the document model rather than splitting plain text. Each handle stays aligned
-     * when text in this builder grows or shrinks, so callers can safely iterate from the first paragraph to the last.
+     * Paragraph boundaries come from the document model rather than splitting plain text. Handles stay aligned across
+     * edits made through their child run handles, so callers can safely iterate from the first paragraph to the last.
+     * Direct builder edits that change text or run boundaries invalidate previously returned paragraph and run handles;
+     * query them again after calling methods such as `insertText()`, `setStyle()`, `setLink()`, or `delete()`.
      *
      * @returns Editable paragraphs in document order.
      * @example
@@ -1426,6 +1429,7 @@ export declare class RichTextBuilder extends RichTextValue {
     private _createParagraphBuilder;
     private _trackRange;
     private _rebaseTrackedRanges;
+    private _invalidateChildHandles;
     /**
      * Appends plain text to the rich text.
      *
@@ -1497,14 +1501,15 @@ export declare class RichTextBuilder extends RichTextValue {
      */
     columns(options: IRichTextColumnsOptions): RichTextBuilder;
     /**
-     * Appends one text span with explicit style.
+     * Appends one text span with an optional style.
      *
      * Prefer this method when combining multiple styles, because the style object is local to the inserted text and does
      * not leak into following calls.
      *
      * @param text Text to append.
-     * @param style Text style for this span. Agent-friendly aliases such as `bold`, `italic`, `fontFamily`, `fontSize`,
-     * `color`, and `background` are supported alongside native document text style fields.
+     * @param style Optional text style for this span. When omitted, the span is appended as unstyled text. Agent-friendly
+     * aliases such as `bold`, `italic`, `fontFamily`, `fontSize`, `color`, and `background` are supported alongside native
+     * document text style fields.
      * @returns The current builder for chaining.
      * @example
      * ```ts
@@ -1513,7 +1518,7 @@ export declare class RichTextBuilder extends RichTextValue {
      *   .span('Important', { bold: true, italic: true, color: '#d92d20' });
      * ```
      */
-    span(text: string, style: IRichTextSpanStyle): RichTextBuilder;
+    span(text: string, style?: IRichTextSpanStyle): RichTextBuilder;
     /**
      * Appends bold text.
      *
@@ -1783,8 +1788,9 @@ export declare class RichTextParagraphBuilder extends RichTextValue {
     private readonly _owner;
     private readonly _paragraphId;
     private readonly _range;
+    private readonly _revision;
     /** @hideconstructor */
-    constructor(_owner: RichTextBuilder, _paragraphId: string, _range: IMutableRichTextRange);
+    constructor(_owner: RichTextBuilder, _paragraphId: string, _range: IMutableRichTextRange, _revision: number);
     /** Returns the persisted paragraph id. */
     getId(): string;
     /** Returns the current paragraph range without its trailing paragraph marker. */
@@ -1813,6 +1819,7 @@ export declare class RichTextParagraphBuilder extends RichTextValue {
     getData(): IDocumentData;
     copy(): RichTextBuilder;
     private _getParagraph;
+    private _assertActive;
 }
 /**
  * An editable text-run handle owned by a detached {@link RichTextBuilder}.
@@ -1826,9 +1833,10 @@ export declare class RichTextRunBuilder {
     private readonly _textStyle;
     private readonly _styleId;
     private readonly _hasExplicitTextStyle;
+    private readonly _revision;
     private _active;
     /** @hideconstructor */
-    constructor(_owner: RichTextBuilder, _range: IMutableRichTextRange, _textStyle: ITextStyle | undefined, _styleId: string | undefined, _hasExplicitTextStyle: boolean);
+    constructor(_owner: RichTextBuilder, _range: IMutableRichTextRange, _textStyle: ITextStyle | undefined, _styleId: string | undefined, _hasExplicitTextStyle: boolean, _revision: number);
     /** Inclusive start offset, kept for compatibility with existing `getTextRuns()` callers. */
     get st(): number;
     /** Exclusive end offset, automatically updated after text replacement. */
@@ -1870,5 +1878,6 @@ export declare class RichTextRunBuilder {
      * ```
      */
     setText(text: string): this;
+    private _assertActive;
 }
 export {};

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

@@ -39,13 +39,7 @@ export declare enum DataStreamTreeTokenType {
     COLUMN_GROUP_END = "\u0015",// column group end
     BLOCK_START = "\u0010",// block start
     BLOCK_END = "\u0011",// block end
-    /**
-     * @deprecated
-     */
     CUSTOM_RANGE_START = "\u001F",// custom range start
-    /**
-     * @deprecated
-     */
     CUSTOM_RANGE_END = "\u001E",// custom range end
     COLUMN_BREAK = "\v",// column break
     PAGE_BREAK = "\f",// page break