@univerjs/core 1.0.0-alpha.2 → 1.0.0-alpha.4

package/lib/es/facade.js

@@ -1,4 +1,4 @@
-import { AbsoluteRefType, AutoFillSeries, BaselineOffset, BooleanNumber, BorderStyleTypes, BorderType, CanceledError, ColorType, CommandType, CommonHideTypes, CopyPasteType, DataValidationErrorStyle, DataValidationOperator, DataValidationRenderMode, DataValidationStatus, DataValidationType, DeleteDirection, DeveloperMetadataVisibility, Dimension, Direction, Disposable, HorizontalAlign, ICommandService, IUndoRedoService, IUniverInstanceService, Inject, Injector, InterpolationPointType, LifecycleService, LifecycleStages, LocaleService, LocaleType, MentionType, ParagraphStyleBuilder, ParagraphStyleValue, ProtectionType, Rectangle, RedoCommand, Registry, RelativeDate, RichTextBuilder, RichTextValue, SheetTypes, TextDecoration, TextDecorationBuilder, TextDirection, TextStyleBuilder, TextStyleValue, ThemeColorType, ThemeService, Tools, UndoCommand, Univer, UniverInstanceType, UserManagerService, VerticalAlign, WrapStrategy, numfmt, toDisposable } from "@univerjs/core";
+import { AbsoluteRefType, AutoFillSeries, BaselineOffset, BooleanNumber, BorderStyleTypes, BorderType, CanceledError, ColorType, CommandType, CommonHideTypes, CopyPasteType, DataValidationErrorStyle, DataValidationOperator, DataValidationRenderMode, DataValidationStatus, DataValidationType, DeleteDirection, DeveloperMetadataVisibility, Dimension, Direction, Disposable, HorizontalAlign, ICommandService, IUndoRedoService, IUniverInstanceService, ImageSourceType, Inject, Injector, InterpolationPointType, LifecycleService, LifecycleStages, LocaleService, LocaleType, MentionType, NumberUnitType, ParagraphStyleBuilder, ParagraphStyleValue, PresetListType, ProtectionType, Rectangle, RedoCommand, Registry, RelativeDate, RichTextBuilder, RichTextValue, SheetTypes, SpacingRule, TextDecoration, TextDecorationBuilder, TextDirection, TextStyleBuilder, TextStyleValue, ThemeColorType, ThemeService, Tools, UndoCommand, Univer, UniverInstanceType, UserManagerService, VerticalAlign, WrapStrategy, numfmt, toDisposable } from "@univerjs/core";
 import { filter } from "rxjs";
 
 //#region src/facade/f-base.ts
@@ -428,6 +428,42 @@ var FEnum = class FEnum {
 		return HorizontalAlign;
 	}
 	/**
+	* Paragraph line-height interpretation modes
+	*
+	* @example
+	* ```ts
+	* console.log(univerAPI.Enum.SpacingRule.EXACT);
+	* ```
+	*/
+	get SpacingRule() {
+		return SpacingRule;
+	}
+	/**
+	* Units accepted by document lengths such as paragraph indentation and spacing
+	*
+	* Agent-facing rich-text helpers accept plain numbers as document points, so this enum is only needed when an
+	* explicit alternative unit is required.
+	*
+	* @example
+	* ```ts
+	* console.log(univerAPI.Enum.NumberUnitType.POINT);
+	* ```
+	*/
+	get NumberUnitType() {
+		return NumberUnitType;
+	}
+	/**
+	* Preset ordered, unordered, and checklist styles used by rich-text list items
+	*
+	* @example
+	* ```ts
+	* console.log(univerAPI.Enum.PresetListType.BULLET_LIST);
+	* ```
+	*/
+	get PresetListType() {
+		return PresetListType;
+	}
+	/**
 	* Different text decoration styles
 	*
 	* @example
@@ -658,6 +694,17 @@ var FEnum = class FEnum {
 	get ThemeColorType() {
 		return ThemeColorType;
 	}
+	/**
+	* Image source types
+	*
+	* @example
+	* ```ts
+	* console.log(univerAPI.Enum.ImageSourceType.URL);
+	* ```
+	*/
+	get ImageSourceType() {
+		return ImageSourceType;
+	}
 };
 _defineProperty(FEnum, "_instance", void 0);
 
@@ -853,6 +900,7 @@ let FHooks = class FHooks extends FBase {
 	}
 	/**
 	* @param callback
+	* @returns {IDisposable} A disposable used to remove the listener.
 	* @deprecated use `univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, ({ stage }) => {})` as instead
 	*/
 	onStarting(callback) {
@@ -860,6 +908,7 @@ let FHooks = class FHooks extends FBase {
 	}
 	/**
 	* @param callback
+	* @returns {IDisposable} A disposable used to remove the listener.
 	* @deprecated use `univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, ({ stage }) => {})` as instead
 	*/
 	onReady(callback) {
@@ -867,6 +916,7 @@ let FHooks = class FHooks extends FBase {
 	}
 	/**
 	* @param callback
+	* @returns {IDisposable} A disposable used to remove the listener.
 	* @deprecated use `univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, ({ stage }) => {})` as instead
 	*/
 	onRendered(callback) {
@@ -874,6 +924,7 @@ let FHooks = class FHooks extends FBase {
 	}
 	/**
 	* @param callback
+	* @returns {IDisposable} A disposable used to remove the listener.
 	* @deprecated use `univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, ({ stage }) => {})` as instead
 	*/
 	onSteady(callback) {
@@ -881,6 +932,7 @@ let FHooks = class FHooks extends FBase {
 	}
 	/**
 	* @param callback
+	* @returns {IDisposable} A disposable used to remove the listener.
 	* @deprecated use `univerAPI.addEvent(univerAPI.Event.BeforeUndo, (event) => {})` as instead
 	*/
 	onBeforeUndo(callback) {
@@ -893,6 +945,7 @@ let FHooks = class FHooks extends FBase {
 	}
 	/**
 	* @param callback
+	* @returns {IDisposable} A disposable used to remove the listener.
 	* @deprecated use `univerAPI.addEvent(univerAPI.Event.Undo, (event) => {})` as instead
 	*/
 	onUndo(callback) {
@@ -905,6 +958,7 @@ let FHooks = class FHooks extends FBase {
 	}
 	/**
 	* @param callback
+	* @returns {IDisposable} A disposable used to remove the listener.
 	* @deprecated use `univerAPI.addEvent(univerAPI.Event.BeforeRedo, (event) => {})` as instead
 	*/
 	onBeforeRedo(callback) {
@@ -917,6 +971,7 @@ let FHooks = class FHooks extends FBase {
 	}
 	/**
 	* @param callback
+	* @returns {IDisposable} A disposable used to remove the listener.
 	* @deprecated use `univerAPI.addEvent(univerAPI.Event.Redo, (event) => {})` as instead
 	*/
 	onRedo(callback) {
@@ -1536,50 +1591,53 @@ let FUniver = _FUniver = class FUniver extends Disposable {
 	}
 	/**
 	* Create a new rich text.
-	* @param {IDocumentData} data
 	* @returns {RichTextBuilder} The new rich text instance
 	* @example
 	* ```ts
-	* const richText = univerAPI.newRichText({ body: { dataStream: 'Hello World\r\n' } });
-	* const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1');
-	* if (!fWorksheet) return;
-	* const range = fWorksheet.getRange('A1');
-	* range.setRichTextValueForCell(richText);
+	* const richText = univerAPI.newRichText()
+	*   .align({ horizontal: univerAPI.Enum.HorizontalAlign.CENTER })
+	*   .text('Status: ')
+	*   .span('Ready', { bold: true, color: '#16a34a' });
 	* ```
 	*/
-	newRichText(data) {
+	newRichText() {
+		return RichTextBuilder.create();
+	}
+	/**
+	* Create a rich-text builder from raw Univer document data.
+	*
+	* This is an advanced integration escape hatch for importers and adapters. Application and agent code should use
+	* the fluent builder returned by `newRichText()`.
+	*
+	* @param data Raw Univer document data.
+	* @returns A rich-text builder initialized with the supplied document data.
+	* @advanced
+	*/
+	newRichTextFromDocumentData(data) {
 		return RichTextBuilder.create(data);
 	}
 	/**
 	* Create a new rich text value.
-	* @param {IDocumentData} data - The rich text data
+	*
+	* This is an advanced integration escape hatch for callers that already own Univer document data. Application and
+	* agent code should prefer the fluent value returned by `newRichText()`.
+	*
+	* @param {IDocumentData} data The raw Univer document data.
 	* @returns {RichTextValue} The new rich text value instance
-	* @example
-	* ```ts
-	* const richTextValue = univerAPI.newRichTextValue({ body: { dataStream: 'Hello World\r\n' } });
-	* const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1');
-	* if (!fWorksheet) return;
-	* const range = fWorksheet.getRange('A1');
-	* range.setRichTextValueForCell(richTextValue);
-	* ```
+	* @advanced
 	*/
 	newRichTextValue(data) {
 		return RichTextValue.create(data);
 	}
 	/**
 	* Create a new paragraph style.
-	* @param {IParagraphStyle} style - The paragraph style
+	*
+	* This is an advanced document-model API. Application and agent code should normally use
+	* `newRichText().paragraph({ ... })`.
+	*
+	* @param {IParagraphStyle} style The paragraph style
 	* @returns {ParagraphStyleBuilder} The new paragraph style instance
-	* @example
-	* ```ts
-	* const richText = univerAPI.newRichText({ body: { dataStream: 'Hello World\r\n' } });
-	* const paragraphStyle = univerAPI.newParagraphStyle({ textStyle: { ff: 'Arial', fs: 12, it: univerAPI.Enum.BooleanNumber.TRUE, bl: univerAPI.Enum.BooleanNumber.TRUE } });
-	* richText.insertParagraph(paragraphStyle);
-	* const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1');
-	* if (!fWorksheet) return;
-	* const range = fWorksheet.getRange('A1');
-	* range.setRichTextValueForCell(richText);
-	* ```
+	* @advanced
 	*/
 	newParagraphStyle(style) {
 		return ParagraphStyleBuilder.create(style);