Skip to content

Build your own AI office with Univer Office SDK. Bring editing, calculation, collaboration, and file processing into your product for people and AI agents. Built on an extensible open-source core.

feat(docs): add agent-friendly text range lookup (#7329)

Univerb273f475e176
diff --git a/packages/docs/src/facade/__tests__/f-document-paragraph.spec.ts b/packages/docs/src/facade/__tests__/f-document-paragraph.spec.ts
index 53beef0416..6579bcc1b8 100644
--- a/packages/docs/src/facade/__tests__/f-document-paragraph.spec.ts
+++ b/packages/docs/src/facade/__tests__/f-document-paragraph.spec.ts
@@ -166,6 +166,82 @@ describe('FDocumentParagraph', () => {
});
});
+ it('finds literal text ranges inside a paragraph', () => {
+ createDocumentFacade(createSimpleDocument());
+
+ const paragraph = document.getParagraphs()[0];
+
+ expect(paragraph.findText('pha')?.describe()).toMatchObject({
+ startOffset: 2,
+ endOffset: 5,
+ segmentId: '',
+ text: 'pha',
+ });
+ expect(paragraph.findText('PHA')).toBeNull();
+ expect(paragraph.findText('PHA', { matchCase: false })?.getText()).toBe('pha');
+ expect(paragraph.findAllText('a').map((range) => range.getRange())).toEqual([
+ { startOffset: 4, endOffset: 5, segmentId: '' },
+ ]);
+ expect(paragraph.findText('missing')).toBeNull();
+ expect(() => paragraph.findText('', { occurrence: 0 })).toThrow(TypeError);
+ expect(() => paragraph.findText('a', { occurrence: -1 })).toThrow(RangeError);
+ });
+
+ it('resolves repeated text occurrences and keeps header matches scoped to their segment', () => {
+ const headerId = 'header-find';
+ createDocumentFacade({
+ ...createDocumentData('doc-find-repeated', {
+ dataStream: 'x plus x\r\n',
+ paragraphs: [{ startIndex: 8, paragraphId: 'para_body_repeated' }],
+ sectionBreaks: [{ sectionId: 'section_body_repeated', startIndex: 9 }],
+ }),
+ headers: {
+ [headerId]: {
+ headerId,
+ body: {
+ dataStream: 'X and x\r\n',
+ paragraphs: [{ startIndex: 7, paragraphId: 'para_header_repeated' }],
+ sectionBreaks: [{ sectionId: 'section_header_repeated', startIndex: 8 }],
+ },
+ },
+ },
+ });
+
+ const bodyParagraph = document.getParagraphs()[0];
+ const headerParagraph = document.getParagraphs(headerId)[0];
+
+ expect(bodyParagraph.findAllText('x').map((range) => range.getRange())).toEqual([
+ { startOffset: 0, endOffset: 1, segmentId: '' },
+ { startOffset: 7, endOffset: 8, segmentId: '' },
+ ]);
+ expect(bodyParagraph.findText('x', { occurrence: 1 })?.getText()).toBe('x');
+ expect(headerParagraph.findAllText('x', { matchCase: false }).map((range) => range.getRange())).toEqual([
+ { startOffset: 0, endOffset: 1, segmentId: headerId },
+ { startOffset: 6, endOffset: 7, segmentId: headerId },
+ ]);
+ });
+
+ it('keeps original document offsets when case folding changes string length', () => {
+ createDocumentFacade(createDocumentData('doc-find-unicode', {
+ dataStream: 'İx and a.b\r\n',
+ paragraphs: [{ startIndex: 10, paragraphId: 'para_unicode' }],
+ sectionBreaks: [{ sectionId: 'section_unicode', startIndex: 11 }],
+ }));
+
+ const paragraph = document.getParagraphs()[0];
+
+ expect(paragraph.findText('x', { matchCase: false })?.describe()).toMatchObject({
+ startOffset: 1,
+ endOffset: 2,
+ text: 'x',
+ });
+ expect(paragraph.findText('A.B', { matchCase: false })?.describe()).toMatchObject({
+ startOffset: 7,
+ endOffset: 10,
+ text: 'a.b',
+ });
+ });
+
it('rejects invalid document text ranges', () => {
createDocumentFacade(createSimpleDocument());
diff --git a/packages/docs/src/facade/f-document-paragraph.ts b/packages/docs/src/facade/f-document-paragraph.ts
index f86859dc83..df7e607c6d 100644
--- a/packages/docs/src/facade/f-document-paragraph.ts
+++ b/packages/docs/src/facade/f-document-paragraph.ts
@@ -17,7 +17,8 @@
import type { IDocumentBody, Injector, IParagraph, IParagraphStyle } from '@univerjs/core';
import type { FDocument } from './f-document';
import type { IFDocumentTextRange } from './utils';
-import { getParagraphContentStartOffset, PresetListType, RESTORE_INSERTED_PARAGRAPH_IDS, UpdateDocsAttributeType } from '@univerjs/core';
+import { getParagraphContentStartOffset, PresetListType, regexp, RESTORE_INSERTED_PARAGRAPH_IDS, UpdateDocsAttributeType } from '@univerjs/core';
+import { FBaseInitialable } from '@univerjs/core/facade';
import { FDocumentTextRange } from './f-document-text-range';
import { buildPlainTextInsertBody, replaceBodyRange, retainBodyRange } from './utils';
@@ -35,6 +36,23 @@ export interface IFDocumentParagraphInfo {
endOffset: number;
}
+/**
+ * Options for locating text inside a document paragraph.
+ */
+export interface IFDocumentFindTextOptions {
+ /**
+ * Whether matching is case-sensitive.
+ * @default true
+ */
+ matchCase?: boolean;
+
+ /**
+ * Zero-based occurrence to return from {@link FDocumentParagraph.findText}.
+ * @default 0
+ */
+ occurrence?: number;
+}
+
/**
* A paragraph facade wrapper.
*
@@ -44,13 +62,15 @@ export interface IFDocumentParagraphInfo {
*
* @hideconstructor
*/
-export class FDocumentParagraph {
+export class FDocumentParagraph extends FBaseInitialable {
constructor(
- private readonly _document: FDocument,
- private readonly _paragraphId: string,
- private readonly _segmentId = '',
- private readonly _injector: Injector
- ) {}
+ protected readonly _document: FDocument,
+ protected readonly _paragraphId: string,
+ protected readonly _segmentId = '',
+ protected override readonly _injector: Injector
+ ) {
+ super(_injector);
+ }
/**
* Get the persisted paragraph id.
@@ -149,6 +169,91 @@ export class FDocumentParagraph {
return this._injector.createInstance(FDocumentTextRange, this._document, startOffset, endOffset, this._segmentId, this._injector);
}
+ /**
+ * Finds one literal text occurrence inside this paragraph.
+ *
+ * The returned text range is fixed when it is created. Resolve a new range
+ * after edits that insert or remove content before the match.
+ *
+ * @param {string} text Literal text to find. It must not be empty.
+ * @param {IFDocumentFindTextOptions} [options] Case sensitivity and zero-based occurrence.
+ * @returns {FDocumentTextRange | null} The matching fixed text range, or `null` when no such occurrence exists.
+ * @example
+ * ```ts
+ * const univerAPI = FUniver.newAPI(univer);
+ * const document = univerAPI.getActiveDocument();
+ * if (!document) throw new Error('No active document');
+ *
+ * const paragraph = document.findParagraphByText('Launch formula');
+ * if (!paragraph) throw new Error('Target paragraph not found');
+ *
+ * const range = paragraph.findText('formula');
+ * if (!range) throw new Error('Target text not found');
+ *
+ * console.log(range.describe());
+ * ```
+ */
+ findText(text: string, options: IFDocumentFindTextOptions = {}): FDocumentTextRange | null {
+ const occurrence = options.occurrence ?? 0;
+ if (!Number.isInteger(occurrence) || occurrence < 0) {
+ throw new RangeError('Text occurrence must be a non-negative integer.');
+ }
+
+ return this.findAllText(text, options)[occurrence] ?? null;
+ }
+
+ /**
+ * Finds every non-overlapping literal text occurrence inside this paragraph.
+ *
+ * Results are ordered from the start of the paragraph. The returned ranges
+ * are fixed when created; use them immediately and resolve new ranges after
+ * edits that change earlier document content.
+ *
+ * @param {string} text Literal text to find. It must not be empty.
+ * @param {Omit<IFDocumentFindTextOptions, 'occurrence'>} [options] Case-sensitivity option.
+ * @returns {FDocumentTextRange[]} All matching fixed text ranges, or an empty array when no matches exist.
+ * @example
+ * ```ts
+ * const univerAPI = FUniver.newAPI(univer);
+ * const document = univerAPI.getActiveDocument();
+ * if (!document) throw new Error('No active document');
+ *
+ * const paragraph = document.findParagraphByText('x plus x');
+ * if (!paragraph) throw new Error('Target paragraph not found');
+ *
+ * const matches = paragraph.findAllText('x');
+ * console.log(matches.map((range) => range.describe()));
+ * ```
+ */
+ findAllText(
+ text: string,
+ options: Omit<IFDocumentFindTextOptions, 'occurrence'> = {}
+ ): FDocumentTextRange[] {
+ if (text.length === 0) {
+ throw new TypeError('Text to find must not be empty.');
+ }
+
+ const matchCase = options.matchCase ?? true;
+ const paragraphText = this.getText();
+ const matcher = regexp.createLiteralRegExp(text, matchCase ? 'gu' : 'giu');
+ const { startOffset } = this.getInfo();
+ const matches: FDocumentTextRange[] = [];
+
+ for (const match of paragraphText.matchAll(matcher)) {
+ const matchStartOffset = startOffset + match.index;
+ matches.push(this._injector.createInstance(
+ FDocumentTextRange,
+ this._document,
+ matchStartOffset,
+ matchStartOffset + match[0].length,
+ this._segmentId,
+ this._injector
+ ));
+ }
+
+ return matches;
+ }
+
/**
* Get this paragraph's plain text.
* @returns {string} The paragraph text without the trailing paragraph break.
diff --git a/packages/docs/src/facade/f-document-text-range.ts b/packages/docs/src/facade/f-document-text-range.ts
index 9891299e10..7eddbba635 100644
--- a/packages/docs/src/facade/f-document-text-range.ts
+++ b/packages/docs/src/facade/f-document-text-range.ts
@@ -18,6 +18,7 @@ import type { Injector, ITextStyle } from '@univerjs/core';
import type { FDocument } from './f-document';
import type { IFDocumentTextRange } from './utils';
import { Tools, UpdateDocsAttributeType } from '@univerjs/core';
+import { FBaseInitialable } from '@univerjs/core/facade';
import { buildPlainTextInsertBody, replaceBodyRange, retainBodyRange } from './utils';
/** A clipped text-style run in document offsets. */
@@ -51,14 +52,15 @@ export interface IFDocumentTextRangeDescription extends IFDocumentTextRange {
* that insert or remove content before it.
* @hideconstructor
*/
-export class FDocumentTextRange {
+export class FDocumentTextRange extends FBaseInitialable {
constructor(
- private readonly _document: FDocument,
- private readonly _startOffset: number,
- private readonly _endOffset: number,
- private readonly _segmentId: string,
- private readonly _injector: Injector
+ protected readonly _document: FDocument,
+ protected readonly _startOffset: number,
+ protected readonly _endOffset: number,
+ protected readonly _segmentId: string,
+ protected override readonly _injector: Injector
) {
+ super(_injector);
this._validateRange();
}
diff --git a/packages/docs/src/facade/index.ts b/packages/docs/src/facade/index.ts
index ce451b1091..f5364c879d 100644
--- a/packages/docs/src/facade/index.ts
+++ b/packages/docs/src/facade/index.ts
@@ -19,7 +19,7 @@ import './f-enum';
export { FDocument } from './f-document';
export { FDocumentParagraph, isParagraphFacade } from './f-document-paragraph';
-export type { IFDocumentParagraphInfo } from './f-document-paragraph';
+export type { IFDocumentFindTextOptions, IFDocumentParagraphInfo } from './f-document-paragraph';
export { DocsSectionUnsupportedDocumentFlavorError, FDocumentSection } from './f-document-section';
export type { FDocumentSectionPageSetup, IFDocumentSectionColumnOptions, IFDocumentSectionDescription } from './f-document-section';
export { FDocumentTextRange } from './f-document-text-range';
diff --git a/packages/engine-render/src/components/docs/layout/block/paragraph/__tests__/shaping.spec.ts b/packages/engine-render/src/components/docs/layout/block/paragraph/__tests__/shaping.spec.ts
index d69f91b425..07ad9cdd1f 100644
--- a/packages/engine-render/src/components/docs/layout/block/paragraph/__tests__/shaping.spec.ts
+++ b/packages/engine-render/src/components/docs/layout/block/paragraph/__tests__/shaping.spec.ts
@@ -14,7 +14,8 @@
* limitations under the License.
*/
-import { BooleanNumber, DataStreamTreeTokenType, PositionedObjectLayoutType } from '@univerjs/core';
+import type { ICustomRangeForInterceptor } from '@univerjs/core';
+import { BooleanNumber, CustomRangeType, DataStreamTreeTokenType, PositionedObjectLayoutType } from '@univerjs/core';
import { describe, expect, it, vi } from 'vitest';
import { Lang } from '../../../hyphenation/lang';
import { createSkeletonLetterGlyph } from '../../../model/glyph';
@@ -44,6 +45,138 @@ describe('shaping', () => {
expect(allGlyphs.length).toBeGreaterThan(0);
});
+ it('shapes a hidden measured whole entity as one atomic glyph', () => {
+ const source = String.raw`\sqrt{x^2 + 1}+\sum_{i=1}^{n} i^2`;
+ const prefix = 'Formula: ';
+ const content = `${prefix}${source} after`;
+ const range: ICustomRangeForInterceptor = {
+ startIndex: prefix.length,
+ endIndex: prefix.length + source.length - 1,
+ rangeId: 'formula-1',
+ rangeType: CustomRangeType.CUSTOM,
+ wholeEntity: true,
+ show: false,
+ glyphAscentEm: 1.75,
+ glyphDescentEm: 1.25,
+ glyphWidthEm: 7.25,
+ };
+ const { viewModel, ctx, paragraphNode, sectionBreakConfig } = createParagraphLayoutTestBed(content, {
+ body: { customRanges: [range] },
+ });
+ vi.spyOn(viewModel, 'getCustomRange').mockImplementation((index) =>
+ index >= range.startIndex && index <= range.endIndex ? range : undefined
+ );
+
+ const result = shaping(ctx, paragraphNode.content!, viewModel, paragraphNode, sectionBreakConfig);
+ const allGlyphs = result.flatMap((item) => item.glyphs);
+ const formulaGlyph = allGlyphs.find((glyph) => glyph.raw === source);
+ let breakPosition = 0;
+ const breakPositions = result.map((item) => {
+ breakPosition += item.text.length;
+ return breakPosition;
+ });
+
+ expect(formulaGlyph).toBeDefined();
+ if (!formulaGlyph?.fontStyle) {
+ throw new Error('Expected the measured whole entity to produce a font-backed glyph.');
+ }
+ const emSize = formulaGlyph.fontStyle.originFontSize / 0.75;
+ expect(formulaGlyph.content).toBe('\u200B');
+ expect(formulaGlyph.count).toBe(source.length);
+ expect(formulaGlyph.width).toBeCloseTo(emSize * 7.25);
+ expect(formulaGlyph.bBox.ba).toBeCloseTo(emSize * 1.75);
+ expect(formulaGlyph.bBox.bd).toBeCloseTo(emSize * 1.25);
+ expect(allGlyphs.filter((glyph) => glyph.raw === source)).toHaveLength(1);
+ expect(breakPositions.some((position) =>
+ position > range.startIndex && position <= range.endIndex
+ )).toBe(false);
+ });
+
+ it('preserves the model text for a one-character measured whole entity', () => {
+ const content = 'axb';
+ const range: ICustomRangeForInterceptor = {
+ startIndex: 1,
+ endIndex: 1,
+ rangeId: 'formula-1',
+ rangeType: CustomRangeType.CUSTOM,
+ wholeEntity: true,
+ show: false,
+ glyphAscentEm: 1,
+ glyphDescentEm: 0,
+ glyphWidthEm: 1,
+ };
+ const { viewModel, ctx, paragraphNode, sectionBreakConfig } = createParagraphLayoutTestBed(content, {
+ body: { customRanges: [range] },
+ });
+ vi.spyOn(viewModel, 'getCustomRange').mockImplementation((index) =>
+ index === range.startIndex ? range : undefined
+ );
+
+ const result = shaping(ctx, paragraphNode.content!, viewModel, paragraphNode, sectionBreakConfig);
+
+ expect(result.map((item) => item.text).join('')).toBe(`${content}${DataStreamTreeTokenType.PARAGRAPH}`);
+ expect(result.flatMap((item) => item.glyphs).filter((glyph) => glyph.raw === 'x')).toHaveLength(1);
+ });
+
+ it('keeps a hidden whole entity on the normal path until all glyph metrics are ready', () => {
+ const source = 'abc';
+ const range: ICustomRangeForInterceptor = {
+ startIndex: 0,
+ endIndex: source.length - 1,
+ rangeId: 'formula-1',
+ rangeType: CustomRangeType.CUSTOM,
+ wholeEntity: true,
+ show: false,
+ glyphWidthEm: 3,
+ };
+ const { viewModel, ctx, paragraphNode, sectionBreakConfig } = createParagraphLayoutTestBed(source, {
+ body: { customRanges: [range] },
+ });
+ vi.spyOn(viewModel, 'getCustomRange').mockImplementation((index) =>
+ index >= range.startIndex && index <= range.endIndex ? range : undefined
+ );
+
+ const result = shaping(ctx, paragraphNode.content!, viewModel, paragraphNode, sectionBreakConfig);
+ const sourceGlyphs = result.flatMap((item) => item.glyphs).filter((glyph) => source.includes(glyph.raw));
+
+ expect(sourceGlyphs.map((glyph) => glyph.raw).join('')).toBe(source);
+ expect(sourceGlyphs).toHaveLength(source.length);
+ });
+
+ it('keeps visible whole-entity text on the normal shaping path', () => {
+ const source = 'abc';
+ const range: ICustomRangeForInterceptor = {
+ startIndex: 0,
+ endIndex: source.length - 1,
+ rangeId: 'mention-1',
+ rangeType: CustomRangeType.CUSTOM,
+ wholeEntity: true,
+ glyphWidthEm: 3,
+ };
+ const { viewModel, ctx, paragraphNode, sectionBreakConfig } = createParagraphLayoutTestBed(source, {
+ body: { customRanges: [range] },
+ });
+ vi.spyOn(viewModel, 'getCustomRange').mockImplementation((index) =>
+ index >= range.startIndex && index <= range.endIndex ? range : undefined
+ );
+
+ const result = shaping(ctx, paragraphNode.content!, viewModel, paragraphNode, sectionBreakConfig);
+ const sourceGlyphs = result.flatMap((item) => item.glyphs).filter((glyph) => source.includes(glyph.raw));
+
+ expect(sourceGlyphs.map((glyph) => glyph.raw).join('')).toBe(source);
+ expect(sourceGlyphs).toHaveLength(source.length);
+ });
+
+ it('does not add per-character custom-range discovery reads for plain text', () => {
+ const content = 'a'.repeat(200);
+ const { viewModel, ctx, paragraphNode, sectionBreakConfig } = createParagraphLayoutTestBed(content);
+ const getCustomRange = vi.spyOn(viewModel, 'getCustomRange');
+
+ shaping(ctx, paragraphNode.content!, viewModel, paragraphNode, sectionBreakConfig);
+
+ expect(getCustomRange.mock.calls.length).toBeLessThanOrEqual(paragraphNode.content!.length * 2);
+ });
+
it('shapes text with tab characters', () => {
const { viewModel, ctx, paragraphNode, sectionBreakConfig } = createParagraphLayoutTestBed('Hello\tworld');
@@ -314,6 +447,54 @@ describe('shaping', () => {
}
});
+ it('shapes a measured whole entity atomically with useOpenType', () => {
+ const source = String.raw`x+y`;
+ const prefix = 'A ';
+ const content = `${prefix}${source} B`;
+ const range: ICustomRangeForInterceptor = {
+ startIndex: prefix.length,
+ endIndex: prefix.length + source.length - 1,
+ rangeId: 'formula-1',
+ rangeType: CustomRangeType.CUSTOM,
+ wholeEntity: true,
+ show: false,
+ glyphAscentEm: 1,
+ glyphDescentEm: 0.25,
+ glyphWidthEm: 2,
+ };
+ const { viewModel, ctx, paragraphNode, sectionBreakConfig } = createParagraphLayoutTestBed(content, {
+ body: { customRanges: [range] },
+ });
+ vi.spyOn(viewModel, 'getCustomRange').mockImplementation((index) =>
+ index >= range.startIndex && index <= range.endIndex ? range : undefined
+ );
+ const originalIsReady = fontLibrary.isReady;
+ fontLibrary.isReady = true;
+ const spy = vi.spyOn(textShapingModule, 'textShape').mockReturnValue(
+ `${content}${DataStreamTreeTokenType.PARAGRAPH}`.split('').map((char, start) => ({
+ char,
+ start,
+ end: start + 1,
+ glyph: null,
+ font: null,
+ kerning: 0,
+ boundingBox: null,
+ }))
+ );
+
+ try {
+ const result = shaping(ctx, paragraphNode.content!, viewModel, paragraphNode, sectionBreakConfig, true);
+ const formulaGlyphs = result.flatMap((item) => item.glyphs).filter((glyph) => glyph.raw === source);
+
+ expect(formulaGlyphs).toHaveLength(1);
+ expect(formulaGlyphs[0].count).toBe(source.length);
+ expect(formulaGlyphs[0].content).toBe('\u200B');
+ } finally {
+ spy.mockRestore();
+ fontLibrary.isReady = originalIsReady;
+ }
+ });
+
it('shapes tab with useOpenType when font library is ready', () => {
const { viewModel, ctx, paragraphNode, sectionBreakConfig } = createParagraphLayoutTestBed('Hello\tworld');
const originalIsReady = fontLibrary.isReady;
diff --git a/packages/engine-render/src/components/docs/layout/block/paragraph/shaping.ts b/packages/engine-render/src/components/docs/layout/block/paragraph/shaping.ts
index ef5934d9a0..841b1a6268 100644
--- a/packages/engine-render/src/components/docs/layout/block/paragraph/shaping.ts
+++ b/packages/engine-render/src/components/docs/layout/block/paragraph/shaping.ts
@@ -14,15 +14,17 @@
* limitations under the License.
*/
-import type { IParagraphStyle, Nullable } from '@univerjs/core';
+import type { ICustomRangeForInterceptor, IParagraph, IParagraphStyle, Nullable } from '@univerjs/core';
import type { IDocumentSkeletonGlyph } from '../../../../../basics/i-document-skeleton-cached';
import type { ISectionBreakConfig } from '../../../../../basics/interfaces';
import type { DataStreamTreeNode } from '../../../view-model/data-stream-tree-node';
import type { DocumentViewModel } from '../../../view-model/document-view-model';
+import type { IBreakPoints } from '../../line-breaker/line-breaker';
import type { IOpenTypeGlyphInfo } from '../../shaping-engine/text-shaping';
import type { ILayoutContext } from '../../tools';
import { BooleanNumber, DataStreamTreeTokenType, GridType, PositionedObjectLayoutType } from '@univerjs/core';
import { cjk } from '../../../../../basics/cjk-regexp';
+import { GlyphType } from '../../../../../basics/i-document-skeleton-cached';
import {
hasArabic,
hasThai,
@@ -35,12 +37,14 @@ import { LineBreaker } from '../../line-breaker';
import { BreakPointType } from '../../line-breaker/break';
import { LineBreakerHyphenEnhancer } from '../../line-breaker/enhancers/hyphen-enhancer';
import { LineBreakerLinkEnhancer } from '../../line-breaker/enhancers/link-enhancer';
+import { LineBreakerWholeEntityEnhancer } from '../../line-breaker/enhancers/whole-entity-enhancer';
import { customBlockLineBreakExtension } from '../../line-breaker/extensions/custom-block-linebreak-extension';
import { tabLineBreakExtension } from '../../line-breaker/extensions/tab-linebreak-extension';
import {
createSkeletonCustomBlockGlyph,
createSkeletonLetterGlyph,
createSkeletonTabGlyph,
+ createSkeletonWholeEntityGlyph,
glyphShrinkLeft,
glyphShrinkRight,
} from '../../model/glyph';
@@ -48,7 +52,13 @@ import { getBoundingBox } from '../../model/line';
import { fontLibrary } from '../../shaping-engine/font-library';
import { textShape } from '../../shaping-engine/text-shaping';
import { prepareParagraphBody } from '../../shaping-engine/utils';
-import { getCharSpaceApply, getCustomRangeGlyphMetrics, getFontCreateConfig } from '../../tools';
+import {
+ getCharSpaceApply,
+ getCustomRangeGlyphMetrics,
+ getCustomRangeGlyphMetricsFromRange,
+ getFontCreateConfig,
+ isMeasuredWholeEntityRange,
+} from '../../tools';
import { ArabicHandler, emojiHandler, otherHandler, ThaiHandler, TibetanHandler } from './language-ruler';
// Now we apply consecutive punctuation adjustment, specified in Chinese Layout
@@ -119,6 +129,73 @@ export interface IShapedText {
breakPointType: BreakPointType;
}
+function collectMeasuredWholeEntityRanges(
+ content: string,
+ viewModel: DocumentViewModel,
+ paragraphNode: DataStreamTreeNode
+): ICustomRangeForInterceptor[] {
+ const ranges: ICustomRangeForInterceptor[] = [];
+ const contentStartIndex = paragraphNode.startIndex;
+ const contentEndIndex = contentStartIndex + content.length - 1;
+ const customRanges = viewModel.getBody()?.customRanges ?? [];
+
+ for (const customRange of customRanges) {
+ if (
+ !customRange.wholeEntity ||
+ customRange.startIndex < contentStartIndex ||
+ customRange.endIndex < customRange.startIndex ||
+ customRange.endIndex > contentEndIndex
+ ) {
+ continue;
+ }
+
+ const interceptedRange = viewModel.getCustomRange(customRange.startIndex);
+ if (
+ interceptedRange?.rangeId === customRange.rangeId &&
+ interceptedRange.startIndex === customRange.startIndex &&
+ interceptedRange.endIndex === customRange.endIndex &&
+ isMeasuredWholeEntityRange(interceptedRange)
+ ) {
+ ranges.push(interceptedRange);
+ }
+ }
+
+ return ranges.sort((a, b) => a.startIndex - b.startIndex);
+}
+
+function createMeasuredWholeEntityGlyph(
+ content: string,
+ range: ICustomRangeForInterceptor,
+ viewModel: DocumentViewModel,
+ paragraphNode: DataStreamTreeNode,
+ sectionBreakConfig: ISectionBreakConfig,
+ paragraph: IParagraph
+): IDocumentSkeletonGlyph | undefined {
+ const relativeStartIndex = range.startIndex - paragraphNode.startIndex;
+ const relativeEndIndex = range.endIndex - paragraphNode.startIndex + 1;
+ const raw = content.slice(relativeStartIndex, relativeEndIndex);
+ const config = getFontCreateConfig(relativeStartIndex, viewModel, paragraphNode, sectionBreakConfig, paragraph);
+ const metrics = getCustomRangeGlyphMetricsFromRange(range, config);
+
+ if (!raw || !metrics) {
+ return undefined;
+ }
+
+ return createSkeletonWholeEntityGlyph(raw, config, metrics);
+}
+
+function getShapedGlyphText(glyph: IDocumentSkeletonGlyph): string {
+ if (
+ glyph.glyphType === GlyphType.PLACEHOLDER &&
+ glyph.streamType === DataStreamTreeTokenType.LETTER &&
+ glyph.raw !== glyph.content
+ ) {
+ return glyph.raw;
+ }
+
+ return glyph.content;
+}
+
export function shaping(
ctx: ILayoutContext,
content: string,
@@ -134,11 +211,20 @@ export function shaping(
drawings = {},
} = sectionBreakConfig;
const shapedTextList: IShapedText[] = [];
- let breaker = new LineBreaker(content);
+ const lineBreaker = new LineBreaker(content);
const { endIndex } = paragraphNode;
const paragraph = viewModel.getParagraph(endIndex) || { startIndex: 0, paragraphId: 'para_render_fallback' };
const { paragraphStyle = {} } = paragraph;
const { snapToGrid = BooleanNumber.TRUE } = paragraphStyle;
+ const measuredWholeEntityRanges = collectMeasuredWholeEntityRanges(content, viewModel, paragraphNode);
+ const measuredWholeEntityRangeByStart = new Map(measuredWholeEntityRanges.map((range) => [
+ range.startIndex - paragraphNode.startIndex,
+ range,
+ ]));
+ const measuredWholeEntityRangeStarts = measuredWholeEntityRanges.map(
+ (range) => range.startIndex - paragraphNode.startIndex
+ );
+ let measuredWholeEntityRangeIndex = 0;
let last = 0;
let bk;
let lastGlyphIndex = 0;
@@ -156,10 +242,10 @@ export function shaping(
// console.log('Text Shaping Time:', +new Date() - now);
// Add custom extension for linebreak.
- tabLineBreakExtension(breaker);
- customBlockLineBreakExtension(breaker);
+ tabLineBreakExtension(lineBreaker);
+ customBlockLineBreakExtension(lineBreaker);
- breaker = new LineBreakerLinkEnhancer(breaker) as unknown as LineBreaker;
+ let breaker: IBreakPoints = new LineBreakerLinkEnhancer(lineBreaker);
const lang = languageDetector.detect(content);
@@ -169,11 +255,16 @@ export function shaping(
if (lang !== Lang.UNKNOWN && needHyphen) {
// Use hyphen enhancer when the lang pattern is loaded.
if (hyphen.hasPattern(lang)) {
- breaker = new LineBreakerHyphenEnhancer(breaker, hyphen, lang, doNotHyphenateCaps) as unknown as LineBreaker;
+ breaker = new LineBreakerHyphenEnhancer(breaker, hyphen, lang, doNotHyphenateCaps);
} else {
hyphen.loadPattern(lang);
}
}
+ breaker = new LineBreakerWholeEntityEnhancer(
+ breaker,
+ measuredWholeEntityRanges,
+ paragraphNode.startIndex
+ );
// eslint-disable-next-line no-cond-assign
while ((bk = breaker.nextBreakPoint())) {
@@ -197,8 +288,33 @@ export function shaping(
}
lastGlyphIndex = i;
- for (const glyphInfo of glyphInfosInWord) {
+ for (let glyphInfoIndex = 0; glyphInfoIndex < glyphInfosInWord.length; glyphInfoIndex++) {
+ const glyphInfo = glyphInfosInWord[glyphInfoIndex];
const { start, char } = glyphInfo;
+ const measuredRange = measuredWholeEntityRangeByStart.get(start);
+
+ if (measuredRange) {
+ const glyph = createMeasuredWholeEntityGlyph(
+ content,
+ measuredRange,
+ viewModel,
+ paragraphNode,
+ sectionBreakConfig,
+ paragraph
+ );
+ if (glyph) {
+ shapedGlyphs.push(glyph);
+ const relativeEndIndex = measuredRange.endIndex - paragraphNode.startIndex + 1;
+ while (
+ glyphInfoIndex + 1 < glyphInfosInWord.length &&
+ glyphInfosInWord[glyphInfoIndex + 1].start < relativeEndIndex
+ ) {
+ glyphInfoIndex++;
+ }
+ continue;
+ }
+ }
+
const config = getFontCreateConfig(start, viewModel, paragraphNode, sectionBreakConfig, paragraph);
if (char === DataStreamTreeTokenType.TAB) {
@@ -222,12 +338,40 @@ export function shaping(
let src = word;
let i = last;
while (src.length > 0) {
+ while (
+ measuredWholeEntityRangeIndex < measuredWholeEntityRangeStarts.length &&
+ measuredWholeEntityRangeStarts[measuredWholeEntityRangeIndex] < i
+ ) {
+ measuredWholeEntityRangeIndex++;
+ }
+
const char = src.match(/^[\s\S]/gu)?.[0];
if (char == null) {
break;
}
+ const measuredRange = measuredWholeEntityRangeByStart.get(i);
+ if (measuredRange) {
+ const glyph = createMeasuredWholeEntityGlyph(
+ content,
+ measuredRange,
+ viewModel,
+ paragraphNode,
+ sectionBreakConfig,
+ paragraph
+ );
+ if (glyph) {
+ shapedGlyphs.push(glyph);
+ const count = measuredRange.endIndex - measuredRange.startIndex + 1;
+ i += count;
+ src = src.substring(count);
+ measuredWholeEntityRangeIndex++;
+ continue;
+ }
+ measuredWholeEntityRangeIndex++;
+ }
+
if (char === DataStreamTreeTokenType.CUSTOM_BLOCK) {
const config = getFontCreateConfig(i, viewModel, paragraphNode, sectionBreakConfig, paragraph);
let newGlyph: Nullable<IDocumentSkeletonGlyph> = null;
@@ -348,9 +492,13 @@ export function shaping(
src = src.substring(step);
} else {
+ const nextMeasuredRangeStart = measuredWholeEntityRangeStarts[measuredWholeEntityRangeIndex];
+ const sourceBeforeMeasuredRange = nextMeasuredRangeStart == null
+ ? src
+ : src.slice(0, nextMeasuredRangeStart - i);
const { step, glyphGroup } = otherHandler(
i,
- src,
+ sourceBeforeMeasuredRange,
viewModel,
paragraphNode,
sectionBreakConfig,
@@ -387,7 +535,7 @@ export function shaping(
const lastShapedGlyphs = shapedGlyphsList[shapedGlyphsList.length - 1];
for (const shapedGlyphs of shapedGlyphsList) {
- const word = shapedGlyphs.map((g) => g.content).join('');
+ const word = shapedGlyphs.map(getShapedGlyphText).join('');
shapedTextList.push({
text: word,
diff --git a/packages/engine-render/src/components/docs/layout/line-breaker/enhancers/__tests__/whole-entity-enhancer.spec.ts b/packages/engine-render/src/components/docs/layout/line-breaker/enhancers/__tests__/whole-entity-enhancer.spec.ts
new file mode 100644
index 0000000000..cfdda5f591
--- /dev/null
+++ b/packages/engine-render/src/components/docs/layout/line-breaker/enhancers/__tests__/whole-entity-enhancer.spec.ts
@@ -0,0 +1,92 @@
+/**
+ * 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 } from '@univerjs/core';
+import { CustomRangeType } from '@univerjs/core';
+import { describe, expect, it } from 'vitest';
+import { LineBreaker } from '../../line-breaker';
+import { LineBreakerWholeEntityEnhancer } from '../whole-entity-enhancer';
+
+function collectBreakPositions(content: string, ranges: readonly ICustomRange[], contentStartIndex = 0): number[] {
+ const enhancer = new LineBreakerWholeEntityEnhancer(
+ new LineBreaker(content),
+ ranges,
+ contentStartIndex
+ );
+ const positions: number[] = [];
+
+ while (true) {
+ const breakPoint = enhancer.nextBreakPoint();
+ if (!breakPoint) {
+ return positions;
+ }
+ positions.push(breakPoint.position);
+ }
+}
+
+describe('LineBreakerWholeEntityEnhancer', () => {
+ it('removes break opportunities inside a whole entity but preserves surrounding breaks', () => {
+ const source = String.raw`\ce{Zn^2+ <=>[+ 2OH-] Zn(OH)2}`;
+ const prefix = 'before ';
+ const content = `${prefix}${source} after`;
+ const startIndex = prefix.length;
+ const endIndex = startIndex + source.length - 1;
+ const positions = collectBreakPositions(content, [{
+ startIndex,
+ endIndex,
+ rangeId: 'formula-1',
+ rangeType: CustomRangeType.CUSTOM,
+ }]);
+
+ expect(positions.some((position) => position > startIndex && position <= endIndex)).toBe(false);
+ expect(positions).toContain(content.length);
+ });
+
+ it('supports document offsets when shaping a paragraph segment', () => {
+ const contentStartIndex = 20;
+ const content = 'A B C';
+ const positions = collectBreakPositions(content, [{
+ startIndex: contentStartIndex + 2,
+ endIndex: contentStartIndex + 4,
+ rangeId: 'formula-1',
+ rangeType: CustomRangeType.CUSTOM,
+ }], contentStartIndex);
+
+ expect(positions.some((position) => position > 2 && position <= 4)).toBe(false);
+ });
+
+ it('handles multiple ranges in model order even when the input is unsorted', () => {
+ const content = 'A B C D E';
+ const positions = collectBreakPositions(content, [
+ {
+ startIndex: 6,
+ endIndex: 8,
+ rangeId: 'formula-2',
+ rangeType: CustomRangeType.CUSTOM,
+ },
+ {
+ startIndex: 2,
+ endIndex: 4,
+ rangeId: 'formula-1',
+ rangeType: CustomRangeType.CUSTOM,
+ },
+ ]);
+
+ expect(positions.some((position) => position > 2 && position <= 4)).toBe(false);
+ expect(positions.some((position) => position > 6 && position <= 8)).toBe(false);
+ expect(positions).toContain(content.length);
+ });
+});
diff --git a/packages/engine-render/src/components/docs/layout/line-breaker/enhancers/hyphen-enhancer.ts b/packages/engine-render/src/components/docs/layout/line-breaker/enhancers/hyphen-enhancer.ts
index 682285e712..507bf5702c 100644
--- a/packages/engine-render/src/components/docs/layout/line-breaker/enhancers/hyphen-enhancer.ts
+++ b/packages/engine-render/src/components/docs/layout/line-breaker/enhancers/hyphen-enhancer.ts
@@ -17,7 +17,7 @@
import type { Nullable } from '@univerjs/core';
import type { Hyphen } from '../../hyphenation/hyphen';
import type { Lang } from '../../hyphenation/lang';
-import type { IBreakPoints, LineBreaker } from '../line-breaker';
+import type { IBreakPoints } from '../line-breaker';
import { Break, BreakPointType } from '../break';
import { getSlicePosition, getWord } from './utils';
@@ -41,7 +41,7 @@ export class LineBreakerHyphenEnhancer implements IBreakPoints {
public content = '';
constructor(
- private _lineBreaker: LineBreaker,
+ private _lineBreaker: IBreakPoints,
private _hyphen: Hyphen,
private _lang: Lang,
private _doNotHyphenateCaps = false
diff --git a/packages/engine-render/src/components/docs/layout/line-breaker/enhancers/link-enhancer.ts b/packages/engine-render/src/components/docs/layout/line-breaker/enhancers/link-enhancer.ts
index f96b1952db..6851a85712 100644
--- a/packages/engine-render/src/components/docs/layout/line-breaker/enhancers/link-enhancer.ts
+++ b/packages/engine-render/src/components/docs/layout/line-breaker/enhancers/link-enhancer.ts
@@ -15,7 +15,7 @@
*/
import type { Nullable } from '@univerjs/core';
-import type { IBreakPoints, LineBreaker } from '../line-breaker';
+import type { IBreakPoints } from '../line-breaker';
import { Break, BreakPointType } from '../break';
import { getSlicePosition } from './utils';
@@ -114,7 +114,7 @@ export class LineBreakerLinkEnhancer implements IBreakPoints {
public content = '';
constructor(
- private _lineBreaker: LineBreaker
+ private _lineBreaker: IBreakPoints
) {
this.content = _lineBreaker.content;
}
diff --git a/packages/engine-render/src/components/docs/layout/line-breaker/enhancers/whole-entity-enhancer.ts b/packages/engine-render/src/components/docs/layout/line-breaker/enhancers/whole-entity-enhancer.ts
new file mode 100644
index 0000000000..305ef24c00
--- /dev/null
+++ b/packages/engine-render/src/components/docs/layout/line-breaker/enhancers/whole-entity-enhancer.ts
@@ -0,0 +1,64 @@
+/**
+ * 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, Nullable } from '@univerjs/core';
+import type { Break } from '../break';
+import type { IBreakPoints } from '../line-breaker';
+
+/**
+ * Removes line-break opportunities from the interior of measured whole
+ * entities. The model keeps the entity's complete source text, while shaping
+ * treats the inclusive custom range as one unbreakable inline object.
+ */
+export class LineBreakerWholeEntityEnhancer implements IBreakPoints {
+ readonly content: string;
+
+ private readonly _ranges: readonly ICustomRange[];
+ private _rangeIndex = 0;
+
+ constructor(
+ private readonly _lineBreaker: IBreakPoints,
+ ranges: readonly ICustomRange[],
+ private readonly _contentStartIndex: number
+ ) {
+ this.content = _lineBreaker.content;
+ this._ranges = [...ranges].sort((a, b) => a.startIndex - b.startIndex);
+ }
+
+ nextBreakPoint(): Nullable<Break> {
+ let breakPoint = this._lineBreaker.nextBreakPoint();
+
+ while (breakPoint && this._isInsideWholeEntity(breakPoint.position)) {
+ breakPoint = this._lineBreaker.nextBreakPoint();
+ }
+
+ return breakPoint;
+ }
+
+ private _isInsideWholeEntity(position: number): boolean {
+ const absolutePosition = this._contentStartIndex + position;
+ let range = this._ranges[this._rangeIndex];
+
+ while (range && absolutePosition > range.endIndex) {
+ this._rangeIndex++;
+ range = this._ranges[this._rangeIndex];
+ }
+
+ return range != null &&
+ absolutePosition > range.startIndex &&
+ absolutePosition <= range.endIndex;
+ }
+}
diff --git a/packages/engine-render/src/components/docs/layout/line-breaker/line-breaker.ts b/packages/engine-render/src/components/docs/layout/line-breaker/line-breaker.ts
index d78df91881..65dab9278d 100644
--- a/packages/engine-render/src/components/docs/layout/line-breaker/line-breaker.ts
+++ b/packages/engine-render/src/components/docs/layout/line-breaker/line-breaker.ts
@@ -64,6 +64,7 @@ function mapFirst(c: number) {
}
export interface IBreakPoints {
+ readonly content: string;
nextBreakPoint(): Nullable<Break>;
}
diff --git a/packages/engine-render/src/components/docs/layout/model/glyph.ts b/packages/engine-render/src/components/docs/layout/model/glyph.ts
index 933d45c52d..4cdff65efa 100644
--- a/packages/engine-render/src/components/docs/layout/model/glyph.ts
+++ b/packages/engine-render/src/components/docs/layout/model/glyph.ts
@@ -112,6 +112,35 @@ export function createSkeletonLetterGlyph(
return glyph;
}
+const WHOLE_ENTITY_RENDER_MARKER = '\u200B';
+
+/**
+ * Creates one non-text skeleton glyph for a whole entity whose source spans
+ * multiple model characters. `raw` and `count` retain the source mapping.
+ *
+ * The zero-width marker keeps the glyph in the document paint loop so a
+ * component extension can render the entity, without painting its model
+ * source as ordinary text.
+ */
+export function createSkeletonWholeEntityGlyph(
+ raw: string,
+ config: IFontCreateConfig,
+ glyphMetrics: { ascent?: number; descent?: number; width?: number }
+): IDocumentSkeletonGlyph {
+ const glyph = createSkeletonLetterGlyph(raw, config, glyphMetrics);
+
+ glyph.adjustability = baseAdjustability(WHOLE_ENTITY_RENDER_MARKER, glyph.width);
+ glyph.bBox.width = glyph.width;
+ glyph.content = WHOLE_ENTITY_RENDER_MARKER;
+ glyph.count = raw.length;
+ glyph.glyphType = GlyphType.PLACEHOLDER;
+ glyph.isJustifiable = false;
+ glyph.raw = raw;
+ glyph.streamType = DataStreamTreeTokenType.LETTER;
+
+ return glyph;
+}
+
export function createSkeletonTabGlyph(config: IFontCreateConfig, glyphWidth?: number): IDocumentSkeletonGlyph {
return _createSkeletonWordOrLetter(GlyphType.TAB, DataStreamTreeTokenType.TAB, config, glyphWidth);
}
diff --git a/packages/engine-render/src/components/docs/layout/tools.ts b/packages/engine-render/src/components/docs/layout/tools.ts
index fad2235e75..2f69ee8b80 100644
--- a/packages/engine-render/src/components/docs/layout/tools.ts
+++ b/packages/engine-render/src/components/docs/layout/tools.ts
@@ -17,6 +17,7 @@
import type {
DocumentDataModel,
IBullet,
+ ICustomRangeForInterceptor,
IDocumentStyle,
INumberUnit,
IObjectPositionH,
@@ -1525,6 +1526,28 @@ export function getCustomRangeGlyphWidth(
return getCustomRangeGlyphMetrics(index, viewModel, paragraphNode, config)?.width;
}
+/**
+ * Returns whether a custom range should occupy one measured glyph in the
+ * document skeleton while preserving its complete source text in the model.
+ *
+ * Visible whole-entity ranges such as mentions keep their existing shaping.
+ * The atomic behavior is reserved for hidden ranges whose renderer provides
+ * explicit glyph metrics, such as an inline formula.
+ */
+export function isMeasuredWholeEntityRange(
+ customRange: Nullable<ICustomRangeForInterceptor>
+): customRange is ICustomRangeForInterceptor {
+ if (!customRange?.wholeEntity || customRange.show !== false) {
+ return false;
+ }
+
+ return [
+ customRange.glyphAscentEm,
+ customRange.glyphDescentEm,
+ customRange.glyphWidthEm,
+ ].every((value) => typeof value === 'number' && Number.isFinite(value) && value >= 0);
+}
+
export function getCustomRangeGlyphMetrics(
index: number,
viewModel: DocumentViewModel,
@@ -1536,6 +1559,13 @@ export function getCustomRangeGlyphMetrics(
return undefined;
}
+ return getCustomRangeGlyphMetricsFromRange(customRange, config);
+}
+
+export function getCustomRangeGlyphMetricsFromRange(
+ customRange: ICustomRangeForInterceptor,
+ config: IFontCreateConfig
+): { ascent?: number; descent?: number; width?: number } | undefined {
const fontSize = ptToPixel(config.fontStyle.originFontSize);
const toPixels = (value: unknown) =>
typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value * fontSize : undefined;