@univerjs-pro/docs-formula 1.0.0-alpha.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,291 @@
1
+ import type { IDocFormulaConfig, IDocFormulaResult } from '@univerjs-pro/docs-formula';
2
+ import type { IDocFormulaInfo, IDocFormulaRange, IDocFormulaUpdateFacadeOptions } from './types';
3
+ import { DocFormulaModel, DocFormulaService } from '@univerjs-pro/docs-formula';
4
+ import { ICommandService, IUniverInstanceService } from '@univerjs/core';
5
+ /**
6
+ * Facade handle for one inline data formula in a Univer document.
7
+ *
8
+ * The handle is identified by `rangeId`. It remains usable across recalculation,
9
+ * but mutating methods return `false` after the underlying custom range is
10
+ * removed. All writes execute public Doc Formula Commands; this class never
11
+ * mutates document or Resource state directly.
12
+ *
13
+ * @example
14
+ * ```ts
15
+ * import type { FUniver } from '@univerjs/core/facade';
16
+ * import '@univerjs-pro/docs-formula/facade';
17
+ *
18
+ * export function inspectFirstDocFormula(univerAPI: FUniver) {
19
+ * const document = univerAPI.getActiveDocument();
20
+ * if (!document) throw new Error('No active document');
21
+ *
22
+ * const formula = document.getFormulas()[0];
23
+ * if (!formula) throw new Error('No Doc Formula');
24
+ *
25
+ * const info = formula.describe();
26
+ * if (!info) throw new Error('The formula was removed');
27
+ * return info;
28
+ * }
29
+ * ```
30
+ */
31
+ export declare class FDocumentFormula {
32
+ private readonly _unitId;
33
+ private readonly _rangeId;
34
+ private readonly _commandService;
35
+ private readonly _model;
36
+ private readonly _service;
37
+ private readonly _univerInstanceService;
38
+ constructor(_unitId: string, _rangeId: string, _commandService: ICommandService, _model: DocFormulaModel, _service: DocFormulaService, _univerInstanceService: IUniverInstanceService);
39
+ /**
40
+ * Returns the stable identity shared by the custom range, Resource entry,
41
+ * Other Formula registration, and this Facade handle.
42
+ *
43
+ * @returns The formula's stable `rangeId`.
44
+ * @example
45
+ * ```ts
46
+ * import type { FUniver } from '@univerjs/core/facade';
47
+ * import '@univerjs-pro/docs-formula/facade';
48
+ * export function readFormulaId(univerAPI: FUniver) {
49
+ * const formula = univerAPI.getActiveDocument()?.getFormulas()[0];
50
+ * if (!formula) throw new Error('No Doc Formula');
51
+ * return formula.getId();
52
+ * }
53
+ * ```
54
+ */
55
+ getId(): string;
56
+ /**
57
+ * Returns the current main-body data-stream range.
58
+ *
59
+ * The formula occupies exactly one U+FFFC object token internally, so
60
+ * `endOffset` is exclusive and normally equals `startOffset + 1`.
61
+ *
62
+ * @returns The live range, or `null` after the custom range is removed.
63
+ * @example
64
+ * ```ts
65
+ * import type { FUniver } from '@univerjs/core/facade';
66
+ * import '@univerjs-pro/docs-formula/facade';
67
+ * export function readFormulaRange(univerAPI: FUniver) {
68
+ * const formula = univerAPI.getActiveDocument()?.getFormulas()[0];
69
+ * const range = formula?.getRange();
70
+ * if (!range) throw new Error('Formula range is unavailable');
71
+ * return range;
72
+ * }
73
+ * ```
74
+ */
75
+ getRange(): IDocFormulaRange | null;
76
+ /**
77
+ * Returns the editable formula text from the unit-scoped Doc Formula
78
+ * Resource.
79
+ *
80
+ * @returns Formula text, or an empty string when the Resource entry is gone.
81
+ * @example
82
+ * ```ts
83
+ * import type { FUniver } from '@univerjs/core/facade';
84
+ * import '@univerjs-pro/docs-formula/facade';
85
+ * export function readFormulaText(univerAPI: FUniver) {
86
+ * const formula = univerAPI.getActiveDocument()?.getFormulas()[0];
87
+ * if (!formula) throw new Error('No Doc Formula');
88
+ * return formula.getFormula();
89
+ * }
90
+ * ```
91
+ */
92
+ getFormula(): string;
93
+ /**
94
+ * Returns a detached copy of the persisted formula configuration.
95
+ *
96
+ * `lastValue` is the last successful scalar result. It is saved as Host
97
+ * content, inherits the document's read permissions, and may be stale until
98
+ * the current calculation session succeeds.
99
+ *
100
+ * @returns The configuration, or `null` when its Resource entry is gone.
101
+ * @example
102
+ * ```ts
103
+ * import type { FUniver } from '@univerjs/core/facade';
104
+ * import '@univerjs-pro/docs-formula/facade';
105
+ * export function readFormulaConfig(univerAPI: FUniver) {
106
+ * const formula = univerAPI.getActiveDocument()?.getFormulas()[0];
107
+ * const config = formula?.getConfig();
108
+ * if (!config) throw new Error('Formula config is unavailable');
109
+ * return config;
110
+ * }
111
+ * ```
112
+ */
113
+ getConfig(): IDocFormulaConfig | null;
114
+ /**
115
+ * Returns the latest calculated or persisted presentation.
116
+ *
117
+ * `source: 'calculated'` identifies a live result. During reload or Source
118
+ * unavailability, the API can return the previous successful value with
119
+ * `source: 'persisted'` and `stale: true`. Formula errors and timeouts never
120
+ * overwrite that persisted value.
121
+ *
122
+ * @returns The current result, or `null` when the formula is not registered.
123
+ * @example
124
+ * ```ts
125
+ * import type { FUniver } from '@univerjs/core/facade';
126
+ * import '@univerjs-pro/docs-formula/facade';
127
+ * export function readFormulaResult(univerAPI: FUniver) {
128
+ * const formula = univerAPI.getActiveDocument()?.getFormulas()[0];
129
+ * const result = formula?.getResult();
130
+ * if (!result) throw new Error('Formula result is unavailable');
131
+ * return result;
132
+ * }
133
+ * ```
134
+ * @example Wait through the shared Formula facade, then read this result
135
+ * ```ts
136
+ * import type { FUniver } from '@univerjs/core/facade';
137
+ * import '@univerjs/engine-formula/facade';
138
+ * import '@univerjs-pro/docs-formula/facade';
139
+ *
140
+ * export async function insertAndReadFormula(univerAPI: FUniver) {
141
+ * const document = univerAPI.getActiveDocument();
142
+ * if (!document) throw new Error('No active document');
143
+ * const paragraph = document.getParagraphs()[0];
144
+ * if (!paragraph) throw new Error('No target paragraph');
145
+ *
146
+ * // Start watching before the write so a fast calculation cannot be missed.
147
+ * const applied = univerAPI.getFormula().onCalculationResultApplied(5_000);
148
+ * const formula = paragraph.appendFormula('=SUM(1,2,3)');
149
+ * if (!formula) throw new Error('Doc Formula insertion failed');
150
+ *
151
+ * await applied;
152
+ * const result = formula.getResult();
153
+ * if (!result) throw new Error('Formula result is unavailable');
154
+ * return result;
155
+ * }
156
+ * ```
157
+ */
158
+ getResult(): IDocFormulaResult | null;
159
+ /**
160
+ * Returns an agent-friendly snapshot of identity, range, persisted config,
161
+ * and current presentation.
162
+ *
163
+ * @returns A detached description, or `null` if either side of the
164
+ * custom-range/Resource pair no longer exists.
165
+ * @example
166
+ * ```ts
167
+ * import type { FUniver } from '@univerjs/core/facade';
168
+ * import '@univerjs-pro/docs-formula/facade';
169
+ * export function describeFormulas(univerAPI: FUniver) {
170
+ * const formulas = univerAPI.getActiveDocument()?.getFormulas() ?? [];
171
+ * return formulas
172
+ * .map((formula) => formula.describe())
173
+ * .filter((value) => value !== null);
174
+ * }
175
+ * ```
176
+ */
177
+ describe(): IDocFormulaInfo | null;
178
+ /**
179
+ * Replaces the formula binding through `UpdateDocFormulaCommand`.
180
+ *
181
+ * The command validates and persists all external Source bindings, clears
182
+ * the previous `lastValue`, and records one undo item. The caller should
183
+ * provide every newly selected external Source in `externalReferences`.
184
+ *
185
+ * @param options Replacement formula, optional number format, and stable
186
+ * external Source bindings.
187
+ * @returns Whether the command committed successfully.
188
+ * @example
189
+ * ```ts
190
+ * import type { FUniver } from '@univerjs/core/facade';
191
+ * import '@univerjs-pro/docs-formula/facade';
192
+ * export function updateFormula(univerAPI: FUniver) {
193
+ * const formula = univerAPI.getActiveDocument()?.getFormulas()[0];
194
+ * if (!formula) throw new Error('No Doc Formula');
195
+ * const updated = formula.update({
196
+ * formula: '=SUM(1, 2, 3)',
197
+ * numberFormat: { pattern: '0.00' },
198
+ * });
199
+ * if (!updated) throw new Error('Failed to update Doc Formula');
200
+ * }
201
+ * ```
202
+ */
203
+ update(options: IDocFormulaUpdateFacadeOptions): boolean;
204
+ /**
205
+ * Updates only the explicit number format through a Command.
206
+ *
207
+ * Passing `undefined` removes the explicit format. This operation preserves
208
+ * the raw `lastValue`, immediately re-formats the current presentation, and
209
+ * participates in normal undo/redo and collaboration.
210
+ *
211
+ * @param numberFormat New format, or `undefined` to inherit/default.
212
+ * @param numberFormat.pattern Univer number-format pattern.
213
+ * @returns Whether the command committed successfully.
214
+ * @example
215
+ * ```ts
216
+ * import type { FUniver } from '@univerjs/core/facade';
217
+ * import '@univerjs-pro/docs-formula/facade';
218
+ * export function formatFormula(univerAPI: FUniver) {
219
+ * const formula = univerAPI.getActiveDocument()?.getFormulas()[0];
220
+ * if (!formula) throw new Error('No Doc Formula');
221
+ * if (!formula.setNumberFormat({ pattern: '$#,##0.00' })) {
222
+ * throw new Error('Failed to format Doc Formula');
223
+ * }
224
+ * }
225
+ * ```
226
+ */
227
+ setNumberFormat(numberFormat?: {
228
+ pattern: string;
229
+ }): boolean;
230
+ /**
231
+ * Removes the formula object and its one-character token.
232
+ *
233
+ * @returns Whether the remove command committed successfully.
234
+ * @example
235
+ * ```ts
236
+ * import type { FUniver } from '@univerjs/core/facade';
237
+ * import '@univerjs-pro/docs-formula/facade';
238
+ * export function removeFormula(univerAPI: FUniver) {
239
+ * const formula = univerAPI.getActiveDocument()?.getFormulas()[0];
240
+ * if (!formula) throw new Error('No Doc Formula');
241
+ * if (!formula.remove()) throw new Error('Failed to remove Doc Formula');
242
+ * }
243
+ * ```
244
+ */
245
+ remove(): boolean;
246
+ /**
247
+ * Replaces the formula object with caller-provided plain text.
248
+ *
249
+ * Use `convertToText()` when the desired text is the current formatted
250
+ * formula presentation.
251
+ *
252
+ * @param text Plain replacement text.
253
+ * @returns Whether the replace command committed successfully.
254
+ * @example
255
+ * ```ts
256
+ * import type { FUniver } from '@univerjs/core/facade';
257
+ * import '@univerjs-pro/docs-formula/facade';
258
+ * export function replaceFormula(univerAPI: FUniver) {
259
+ * const formula = univerAPI.getActiveDocument()?.getFormulas()[0];
260
+ * if (!formula) throw new Error('No Doc Formula');
261
+ * if (!formula.replaceWithText('Total: 42')) {
262
+ * throw new Error('Failed to replace Doc Formula');
263
+ * }
264
+ * }
265
+ * ```
266
+ */
267
+ replaceWithText(text: string): boolean;
268
+ /**
269
+ * Converts the formula to its current formatted display text.
270
+ *
271
+ * The Command resolves the presentation; the Facade does not duplicate
272
+ * formatting business logic. A stale persisted presentation is permitted
273
+ * and is converted exactly as displayed. The operation is undoable.
274
+ *
275
+ * @returns Whether conversion committed successfully.
276
+ * @example
277
+ * ```ts
278
+ * import type { FUniver } from '@univerjs/core/facade';
279
+ * import '@univerjs-pro/docs-formula/facade';
280
+ * export function convertFormula(univerAPI: FUniver) {
281
+ * const formula = univerAPI.getActiveDocument()?.getFormulas()[0];
282
+ * if (!formula) throw new Error('No Doc Formula');
283
+ * if (!formula.convertToText()) {
284
+ * throw new Error('No presentation was available to convert');
285
+ * }
286
+ * }
287
+ * ```
288
+ */
289
+ convertToText(): boolean;
290
+ private _getCustomRange;
291
+ }
@@ -0,0 +1,91 @@
1
+ import type { Injector } from '@univerjs/core';
2
+ import type { IDocFormulaCreateFacadeOptions } from './types';
3
+ import { FDocumentParagraph } from '@univerjs/docs/facade';
4
+ import { FDocumentFormula } from './f-document-formula';
5
+ /** Formula insertion methods added to main-body `FDocumentParagraph` handles. */
6
+ export interface IFDocumentParagraphFormulaMixin {
7
+ /**
8
+ * Inserts one Formula at a paragraph-relative UTF-16 offset.
9
+ *
10
+ * The paragraph handle is backed by its persisted `paragraphId`. The
11
+ * Command resolves that id against the latest document snapshot and only
12
+ * then converts `offset` to a document position. Edits before this paragraph
13
+ * therefore do not invalidate the insertion anchor.
14
+ *
15
+ * Use `0` to insert at the content start. Prefer `appendFormula()` for the
16
+ * current content end because it resolves the semantic `'end'` position
17
+ * without requiring the caller to measure UTF-16 text length.
18
+ *
19
+ * @param offset Zero-based UTF-16 offset relative to this paragraph's text.
20
+ * @param formula Formula text.
21
+ * @param options Optional number format and stable external Source bindings.
22
+ * @returns The inserted formula, or `null` when the paragraph is missing,
23
+ * outside the main body, the offset is invalid, or Command validation fails.
24
+ * @example Insert between a stable label and its suffix
25
+ * ```ts
26
+ * import type { FUniver } from '@univerjs/core/facade';
27
+ * import '@univerjs-pro/docs-formula/facade';
28
+ *
29
+ * export function insertFormulaInsideParagraph(univerAPI: FUniver) {
30
+ * const document = univerAPI.getActiveDocument();
31
+ * if (!document) throw new Error('No active document');
32
+ *
33
+ * const paragraph = document.appendParagraph('Revenue: USD');
34
+ * const paragraphId = paragraph.getId();
35
+ *
36
+ * // This edit changes every following absolute document offset.
37
+ * document.insertParagraph(0, 'Quarterly report');
38
+ *
39
+ * const stableParagraph = document.getParagraph(paragraphId);
40
+ * if (!stableParagraph) throw new Error('Revenue paragraph was removed');
41
+ * const formula = stableParagraph.insertFormula('Revenue: '.length, '=1000/4', {
42
+ * numberFormat: { pattern: '#,##0.00' },
43
+ * });
44
+ * if (!formula) throw new Error('Failed to insert Doc Formula');
45
+ * return formula.describe();
46
+ * }
47
+ * ```
48
+ */
49
+ insertFormula(offset: number, formula: string, options?: IDocFormulaCreateFacadeOptions): FDocumentFormula | null;
50
+ /**
51
+ * Appends one Formula before this paragraph's trailing paragraph token.
52
+ *
53
+ * The Command resolves the persisted `paragraphId` and the semantic `'end'`
54
+ * position together. It does not capture an absolute document offset or a
55
+ * paragraph length in advance. Header/footer paragraphs are rejected because
56
+ * Doc Formula v1 supports the main body only.
57
+ *
58
+ * @param formula Formula text.
59
+ * @param options Optional number format and stable external Source bindings.
60
+ * @returns The inserted formula, or `null` when the paragraph is missing,
61
+ * outside the main body, or the command validation fails.
62
+ * @example
63
+ * ```ts
64
+ * import type { FUniver } from '@univerjs/core/facade';
65
+ * import '@univerjs-pro/docs-formula/facade';
66
+ *
67
+ * export function appendParagraphFormula(univerAPI: FUniver) {
68
+ * const document = univerAPI.getActiveDocument();
69
+ * if (!document) throw new Error('No active document');
70
+ * const paragraph = document.appendParagraph('Revenue: ');
71
+ * const formula = paragraph.appendFormula('=1000/4', {
72
+ * numberFormat: { pattern: '$#,##0.00' },
73
+ * });
74
+ * if (!formula) throw new Error('Failed to append Doc Formula');
75
+ * return formula.describe();
76
+ * }
77
+ * ```
78
+ */
79
+ appendFormula(formula: string, options?: IDocFormulaCreateFacadeOptions): FDocumentFormula | null;
80
+ }
81
+ export declare class FDocumentParagraphFormulaMixin extends FDocumentParagraph implements IFDocumentParagraphFormulaMixin {
82
+ private _docsFormulaCommandService;
83
+ _initialize(injector: Injector): void;
84
+ insertFormula(offset: number, formula: string, options?: IDocFormulaCreateFacadeOptions): FDocumentFormula | null;
85
+ appendFormula(formula: string, options?: IDocFormulaCreateFacadeOptions): FDocumentFormula | null;
86
+ private _insert;
87
+ }
88
+ declare module '@univerjs/docs/facade' {
89
+ interface FDocumentParagraph extends IFDocumentParagraphFormulaMixin {
90
+ }
91
+ }
@@ -0,0 +1,44 @@
1
+ import type { Injector } from '@univerjs/core';
2
+ import type { IDocFormulaCreateFacadeOptions } from './types';
3
+ import { FDocumentTextRange } from '@univerjs/docs/facade';
4
+ import { FDocumentFormula } from './f-document-formula';
5
+ /** Formula insertion methods added to fixed `FDocumentTextRange` handles. */
6
+ export interface IFDocumentTextRangeFormulaMixin {
7
+ /**
8
+ * Replaces this complete text range with one whole-entity Doc Formula.
9
+ *
10
+ * The fixed range must be in the main body and must not cross paragraph,
11
+ * table-cell, section, column, or protected structural boundaries.
12
+ *
13
+ * @param formula Formula text.
14
+ * @param options Optional number format and complete external Source bindings.
15
+ * @returns The inserted formula, or `null` when range/binding validation fails.
16
+ * @example
17
+ * ```ts
18
+ * import type { FUniver } from '@univerjs/core/facade';
19
+ * import '@univerjs-pro/docs-formula/facade';
20
+ *
21
+ * export function replacePlaceholderWithFormula(univerAPI: FUniver) {
22
+ * const document = univerAPI.getActiveDocument();
23
+ * if (!document) throw new Error('No active document');
24
+ * const paragraph = document.findParagraphByText('FORMULA_PLACEHOLDER');
25
+ * const range = paragraph?.findText('FORMULA_PLACEHOLDER');
26
+ * if (!range) throw new Error('Formula placeholder not found');
27
+ * const formula = range.replaceWithFormula('=SUM(10,20)');
28
+ * if (!formula) throw new Error('Failed to replace the range');
29
+ * return formula.describe();
30
+ * }
31
+ * ```
32
+ */
33
+ replaceWithFormula(formula: string, options?: IDocFormulaCreateFacadeOptions): FDocumentFormula | null;
34
+ }
35
+ export declare class FDocumentTextRangeFormulaMixin extends FDocumentTextRange implements IFDocumentTextRangeFormulaMixin {
36
+ private _docsFormulaCommandService;
37
+ _initialize(injector: Injector): void;
38
+ replaceWithFormula(formula: string, options?: IDocFormulaCreateFacadeOptions): FDocumentFormula | null;
39
+ private _insert;
40
+ }
41
+ declare module '@univerjs/docs/facade' {
42
+ interface FDocumentTextRange extends IFDocumentTextRangeFormulaMixin {
43
+ }
44
+ }
@@ -0,0 +1,178 @@
1
+ import type { IDocumentData, Injector } from '@univerjs/core';
2
+ import type { IDocFormulaInsertFacadeOptions } from './types';
3
+ import { FDocument } from '@univerjs/docs/facade';
4
+ import { FDocumentFormula } from './f-document-formula';
5
+ /**
6
+ * Doc Formula methods added to `FDocument` after importing
7
+ * `@univerjs-pro/docs-formula/facade`.
8
+ */
9
+ export interface IFDocumentFormulaMixin {
10
+ /**
11
+ * Lists complete Formula custom-range/Resource pairs in the main body.
12
+ *
13
+ * Incomplete or unsupported persisted data remains preserved by the core
14
+ * plugin but is intentionally omitted from calculation and this list.
15
+ *
16
+ * @returns Formula handles in document order, or an empty array.
17
+ * @example
18
+ * ```ts
19
+ * import type { FUniver } from '@univerjs/core/facade';
20
+ * import '@univerjs-pro/docs-formula/facade';
21
+ *
22
+ * export function listDocFormulas(univerAPI: FUniver) {
23
+ * const document = univerAPI.getActiveDocument();
24
+ * if (!document) throw new Error('No active document');
25
+ * return document.getFormulas().map((formula) => formula.describe());
26
+ * }
27
+ * ```
28
+ */
29
+ getFormulas(): FDocumentFormula[];
30
+ /**
31
+ * Resolves one complete Doc Formula by stable `rangeId`.
32
+ *
33
+ * @param rangeId Identity returned by insertion or `FDocumentFormula.getId`.
34
+ * @returns A handle, or `null` when either the range or Resource entry is absent.
35
+ * @example
36
+ * ```ts
37
+ * import type { FUniver } from '@univerjs/core/facade';
38
+ * import '@univerjs-pro/docs-formula/facade';
39
+ *
40
+ * export function getDocFormula(univerAPI: FUniver, rangeId: string) {
41
+ * const document = univerAPI.getActiveDocument();
42
+ * if (!document) throw new Error('No active document');
43
+ * const formula = document.getFormula(rangeId);
44
+ * if (!formula) throw new Error(`Doc Formula ${rangeId} was not found`);
45
+ * return formula;
46
+ * }
47
+ * ```
48
+ */
49
+ getFormula(rangeId: string): FDocumentFormula | null;
50
+ /**
51
+ * Resolves the whole-entity Doc Formula containing a main-body offset.
52
+ *
53
+ * @param offset Document data-stream offset.
54
+ * @returns A handle, or `null` when the offset is not a complete Doc Formula.
55
+ * @example
56
+ * ```ts
57
+ * import type { FUniver } from '@univerjs/core/facade';
58
+ * import '@univerjs-pro/docs-formula/facade';
59
+ *
60
+ * export function getDocFormulaAt(univerAPI: FUniver, offset: number) {
61
+ * const document = univerAPI.getActiveDocument();
62
+ * if (!document) throw new Error('No active document');
63
+ * return document.getFormulaAt(offset);
64
+ * }
65
+ * ```
66
+ */
67
+ getFormulaAt(offset: number): FDocumentFormula | null;
68
+ /**
69
+ * Saves a detached external-format projection of this document.
70
+ *
71
+ * Native `save()` preserves Formula custom ranges and Resource entries.
72
+ * This method instead replaces every main-body Doc Formula object with its
73
+ * persisted `lastValue` display text and removes the Doc Formula Resource from
74
+ * the returned snapshot. It never mutates the live document and is intended
75
+ * for Markdown, HTML, TXT, DOCX, and other non-native exporters.
76
+ *
77
+ * Export never triggers calculation, waits for a result, or reads the
78
+ * current in-memory presentation. The last successful persisted value is
79
+ * emitted with its inherited or explicit number format. A missing or empty
80
+ * `lastValue` becomes an empty string; U+FFFC is never returned.
81
+ *
82
+ * @returns A detached `IDocumentData` projection safe for external export.
83
+ * @example
84
+ * ```ts
85
+ * import type { FUniver } from '@univerjs/core/facade';
86
+ * import '@univerjs-pro/docs-formula/facade';
87
+ *
88
+ * export function saveForExternalExporter(univerAPI: FUniver) {
89
+ * const document = univerAPI.getActiveDocument();
90
+ * if (!document) throw new Error('No active document');
91
+ * const snapshot = document.saveFormulaDisplayTextSnapshot();
92
+ * if (snapshot.body?.dataStream.includes('\uFFFC')) {
93
+ * throw new Error('External snapshot contains an object token');
94
+ * }
95
+ * return snapshot;
96
+ * }
97
+ * ```
98
+ */
99
+ saveFormulaDisplayTextSnapshot(): IDocumentData;
100
+ /**
101
+ * Replaces an explicit main-body range with one inline Doc Formula.
102
+ *
103
+ * The offsets are snapshot-relative and resolved immediately. This API is
104
+ * suitable when the caller already owns a current range in the same
105
+ * synchronous workflow. Agent and delayed headless workflows should prefer
106
+ * a stable `FDocumentParagraph` handle with `insertFormula()` or
107
+ * `appendFormula()`.
108
+ *
109
+ * The Command validates the range, formula syntax, and complete external
110
+ * Source bindings before it commits TextX, Host External Reference, and Doc
111
+ * Formula Resource mutations as one undoable user action.
112
+ *
113
+ * @param options Formula, half-open replacement range, number format, and
114
+ * any stable external Source bindings.
115
+ * @returns The inserted handle, or `null` if validation or a mutation fails.
116
+ * @example
117
+ * ```ts
118
+ * import type { FUniver } from '@univerjs/core/facade';
119
+ * import '@univerjs-pro/docs-formula/facade';
120
+ *
121
+ * export function insertConstantFormula(univerAPI: FUniver) {
122
+ * const document = univerAPI.getActiveDocument();
123
+ * if (!document) throw new Error('No active document');
124
+ * const formula = document.insertFormula({
125
+ * formula: '=1+2',
126
+ * startOffset: 0,
127
+ * endOffset: 0,
128
+ * numberFormat: { pattern: '0.00' },
129
+ * });
130
+ * if (!formula) throw new Error('Doc Formula insertion failed');
131
+ * return formula.getId();
132
+ * }
133
+ * ```
134
+ * @example
135
+ * ```ts
136
+ * import { UniverInstanceType } from '@univerjs/core';
137
+ * import type { FUniver } from '@univerjs/core/facade';
138
+ * import '@univerjs-pro/docs-formula/facade';
139
+ *
140
+ * export function insertBoundFormula(univerAPI: FUniver) {
141
+ * const document = univerAPI.getActiveDocument();
142
+ * if (!document) throw new Error('No active document');
143
+ * const formula = document.insertFormula({
144
+ * formula: "='[Sales Source]Data'!A1",
145
+ * startOffset: 0,
146
+ * endOffset: 0,
147
+ * externalReferences: [{
148
+ * qualifier: 'Sales Source',
149
+ * sourceUnitId: 'sales-source-v1',
150
+ * sourceUnitType: UniverInstanceType.UNIVER_SHEET,
151
+ * }],
152
+ * });
153
+ * if (!formula) throw new Error('Source binding or range was invalid');
154
+ * return formula.getId();
155
+ * }
156
+ * ```
157
+ */
158
+ insertFormula(options: IDocFormulaInsertFacadeOptions): FDocumentFormula | null;
159
+ }
160
+ export declare class FDocumentFormulaMixin extends FDocument implements IFDocumentFormulaMixin {
161
+ private _docsFormulaCommandService;
162
+ private _docsFormulaDisplayTextService;
163
+ private _docsFormulaModel;
164
+ private _docsFormulaResourceLoaderService;
165
+ _initialize(injector: Injector): void;
166
+ getFormulas(): FDocumentFormula[];
167
+ getFormula(rangeId: string): FDocumentFormula | null;
168
+ getFormulaAt(offset: number): FDocumentFormula | null;
169
+ saveFormulaDisplayTextSnapshot(): IDocumentData;
170
+ insertFormula(options: IDocFormulaInsertFacadeOptions): FDocumentFormula | null;
171
+ private _insert;
172
+ private _getCompleteRanges;
173
+ private _createFormula;
174
+ }
175
+ declare module '@univerjs/docs/facade' {
176
+ interface FDocument extends IFDocumentFormulaMixin {
177
+ }
178
+ }
@@ -0,0 +1,8 @@
1
+ import './f-document';
2
+ import './f-document-paragraph';
3
+ import './f-document-text-range';
4
+ export type { IFDocumentFormulaMixin } from './f-document';
5
+ export { FDocumentFormula } from './f-document-formula';
6
+ export type { IFDocumentParagraphFormulaMixin } from './f-document-paragraph';
7
+ export type { IFDocumentTextRangeFormulaMixin } from './f-document-text-range';
8
+ export type { IDocFormulaCreateFacadeOptions, IDocFormulaInfo, IDocFormulaInsertFacadeOptions, IDocFormulaRange, IDocFormulaUpdateFacadeOptions, } from './types';