@a3s-lab/office 0.24.0 → 0.26.0

package/dist/internal/features/work/editors/spreadsheet-rich-text-selection-format.d.ts

@@ -0,0 +1,26 @@
+import type { Cell } from '@fortune-sheet/core';
+import type { WorkSpreadsheetContent } from '../work-types';
+export type SpreadsheetRichTextFormatAttribute = 'bl' | 'cl' | 'fc' | 'ff' | 'fs' | 'it' | 'un';
+export type SpreadsheetRichTextToggleAttribute = 'bl' | 'cl' | 'it' | 'un';
+export interface SpreadsheetTextSelection {
+    end: number;
+    start: number;
+}
+export interface SpreadsheetRichTextSelectionFormatRequest {
+    attribute: SpreadsheetRichTextFormatAttribute;
+    column: number;
+    row: number;
+    selection: SpreadsheetTextSelection;
+    sheetId: string;
+    /**
+     * A cell reconstructed from the live editor before focus moves into a
+     * ribbon popover. It is intentionally internal and still passes through all
+     * text, run-count, coordinate, and formatting bounds below.
+     */
+    sourceCell?: Cell;
+    value: unknown;
+}
+export declare function canApplySpreadsheetRichTextSelectionFormat(content: WorkSpreadsheetContent, request: SpreadsheetRichTextSelectionFormatRequest): boolean;
+export declare function applySpreadsheetRichTextSelectionFormat(content: WorkSpreadsheetContent, request: SpreadsheetRichTextSelectionFormatRequest): WorkSpreadsheetContent | null;
+export declare function formatSpreadsheetRichTextSelection(cell: Cell, selection: SpreadsheetTextSelection, attribute: SpreadsheetRichTextFormatAttribute, value: unknown): Cell | null;
+export declare function spreadsheetRichTextSelectionToggleValue(cell: Cell, selection: SpreadsheetTextSelection, attribute: SpreadsheetRichTextToggleAttribute): 0 | 1 | null;

package/dist/internal/features/work/work-css-color.d.ts

@@ -0,0 +1 @@
+export declare function normalizeCssColor(source: string | null | undefined): 'transparent' | `#${string}` | null;

package/dist/internal/features/work/work-document-paragraph-shading.d.ts

@@ -1,4 +1,5 @@
 import { type DocxThemeColorReference } from './work-docx-theme-reference';
+export { normalizeCssColor } from './work-css-color';
 export type DocumentParagraphShadingPattern = 'nil' | 'clear' | 'solid' | 'horzStripe' | 'vertStripe' | 'reverseDiagStripe' | 'diagStripe' | 'horzCross' | 'diagCross' | 'thinHorzStripe' | 'thinVertStripe' | 'thinReverseDiagStripe' | 'thinDiagStripe' | 'thinHorzCross' | 'thinDiagCross' | 'pct5' | 'pct10' | 'pct12' | 'pct15' | 'pct20' | 'pct25' | 'pct30' | 'pct35' | 'pct37' | 'pct40' | 'pct45' | 'pct50' | 'pct55' | 'pct60' | 'pct62' | 'pct65' | 'pct70' | 'pct75' | 'pct80' | 'pct85' | 'pct87' | 'pct90' | 'pct95';
 export interface DocumentParagraphShadingColor {
     value: 'auto' | `#${string}`;
@@ -15,4 +16,3 @@ export declare function parseDocumentParagraphShading(source: unknown): Document
 export declare function serializeDocumentParagraphShading(source: unknown): string | undefined;
 export declare function parseDocumentParagraphShadingElement(element: HTMLElement): DocumentParagraphShading | null;
 export declare function documentParagraphShadingDomAttributes(source: unknown): Record<string, string>;
-export declare function normalizeCssColor(source: string | null | undefined): 'transparent' | `#${string}` | null;

package/dist/internal/features/work/work-xlsx-cell-style-origin.d.ts

@@ -42,3 +42,4 @@ export declare function applyXlsxSemanticColorOrigin(element: Element, origin: X
 export declare function xlsxSemanticColorOriginKey(origin: XlsxSemanticColorOrigin | undefined): string;
 export declare function xlsxSemanticColorOriginSupported(origin: XlsxSemanticColorOrigin, palette: XlsxSemanticPalette | undefined): boolean;
 export declare function prepareXlsxSemanticPalette(styles: Document, theme: Document | null, origins: Iterable<XlsxCellStyleOrigin>): PreparedXlsxSemanticPalette;
+export declare function normalizeXlsxSemanticColorOrigin(value: unknown): XlsxSemanticColorOrigin | undefined;

package/dist/internal/features/work/work-xlsx-colors.d.ts

@@ -2,5 +2,5 @@ export interface XlsxColorResolver {
     indexed: readonly string[];
     theme: readonly string[];
 }
-export declare function createXlsxColorResolver(styles: Document, theme: Document | null): XlsxColorResolver;
+export declare function createXlsxColorResolver(styles: Document | null, theme: Document | null): XlsxColorResolver;
 export declare function resolveXlsxColor(element: Element | undefined, resolver: XlsxColorResolver): string | undefined;

package/dist/internal/features/work/work-xlsx-interop.d.ts

@@ -9,6 +9,7 @@ import { type XlsxManualPageBreaks } from './work-xlsx-page-breaks';
 import { type XlsxPageSetup } from './work-xlsx-page-setup';
 import { type XlsxProtectionFeatures } from './work-xlsx-protection';
 import { type XlsxWorksheetXmlScan } from './work-xlsx-worksheet-scan';
+import { type XlsxRichTextCell } from './work-xlsx-rich-text';
 import type { WorkSpreadsheetTable } from './work-types';
 type FrozenPane = NonNullable<Sheet['frozen']>;
 export interface XlsxDataValidation {
@@ -26,6 +27,7 @@ export interface XlsxSheetFeatures {
     images: XlsxWorksheetImage[];
     charts: XlsxWorksheetChart[];
     tables: WorkSpreadsheetTable[];
+    richTextCells: XlsxRichTextCell[];
 }
 export type FortuneDataValidationItem = WorkSpreadsheetDataValidationItem;
 export declare function readXlsxSheetFeatures(buffer: ArrayBuffer): Promise<Map<string, XlsxSheetFeatures>>;

package/dist/internal/features/work/work-xlsx-rich-text-edit.d.ts

@@ -0,0 +1,28 @@
+import type { Cell } from '@fortune-sheet/core';
+import { type XlsxRichTextRun } from './work-xlsx-rich-text-model';
+export interface SpreadsheetRichTextPasteIntent {
+    end: number;
+    runs: readonly XlsxRichTextRun[];
+    start: number;
+    text: string;
+}
+/**
+ * Reconciles a text edit emitted by Fortune with the previous native XLSX
+ * rich-text cell. Formula-bar edits may arrive as a plain string, while the
+ * in-cell editor emits visible runs without A3S-only semantic color metadata.
+ * This bounded model restores only style and metadata justified by the prior
+ * controlled value and the exact text replacement.
+ */
+export declare function reconcileSpreadsheetRichTextCellEdit(previous: Cell | null | undefined, current: Cell, formattedPaste?: SpreadsheetRichTextPasteIntent): Cell;
+/**
+ * Restores the controlled runs when an unauthenticated Fortune callback keeps
+ * the exact visible text but drops native run metadata. Callers must reserve
+ * this for non-structural batches without an exact cell-operation coordinate.
+ */
+export declare function restoreSpreadsheetRichTextCellRuns(previous: Cell | null | undefined, current: Cell): Cell;
+/**
+ * Proves that Fortune retained the visible text of a controlled native
+ * rich-text cell. This permits metadata-only callbacks to restore lost run
+ * structure without guessing across a text or structural edit.
+ */
+export declare function sameSpreadsheetRichTextCellText(previous: Cell | null | undefined, current: Cell): boolean;

package/dist/internal/features/work/work-xlsx-rich-text-model.d.ts

@@ -0,0 +1,40 @@
+import type { Cell } from '@fortune-sheet/core';
+import { type XlsxSemanticColorOrigin } from './work-xlsx-cell-style-origin';
+import type { SpreadsheetUnderlineCellValue } from './work-spreadsheet-underline';
+export declare const MAX_XLSX_RICH_TEXT_CELL_CHARACTERS = 32767;
+export declare const MAX_XLSX_RICH_TEXT_RUNS_PER_CELL = 512;
+export declare const MAX_XLSX_RICH_TEXT_CELLS = 10000;
+export declare const MAX_XLSX_RICH_TEXT_RUNS = 100000;
+export declare const MAX_XLSX_RICH_TEXT_FONT_NAME_CHARACTERS = 128;
+export declare const MAX_XLSX_RICH_TEXT_FONT_SIZE = 409;
+export interface XlsxRichTextRun {
+    a3sXlsxColorOrigin?: XlsxSemanticColorOrigin;
+    bl?: 0 | 1;
+    cl?: 0 | 1;
+    fc?: string;
+    ff?: string;
+    fs?: number;
+    it?: 0 | 1;
+    un?: SpreadsheetUnderlineCellValue;
+    v: string;
+}
+export interface NormalizedXlsxRichTextCell {
+    runs: XlsxRichTextRun[];
+    text: string;
+}
+/**
+ * Normalizes the text state that may participate in caret-level rich-text
+ * authoring. Native runs remain authoritative; bounded plain strings receive
+ * one run derived from the cell-wide font so partial formatting and formatted
+ * paste share the same conversion contract.
+ */
+export declare function normalizeXlsxRichTextEditSource(cell: Cell | null | undefined): NormalizedXlsxRichTextCell | null;
+export declare function xlsxRichTextBaseRun(cell: Cell | null | undefined, text: string): XlsxRichTextRun;
+export declare function normalizeXlsxRichTextCell(cell: Cell): NormalizedXlsxRichTextCell | null;
+export declare function normalizeXlsxRichTextRun(value: unknown): XlsxRichTextRun | null;
+export declare function normalizeXlsxRichTextColor(value: unknown): string | null;
+export declare function coalesceXlsxRichTextRuns(source: readonly XlsxRichTextRun[]): XlsxRichTextRun[];
+export declare function sameXlsxRichTextRunStyle(left: XlsxRichTextRun, right: XlsxRichTextRun): boolean;
+export declare function validXlsxRichText(value: string): boolean;
+export declare function isHighSurrogate(value: number): boolean;
+export declare function isLowSurrogate(value: number): boolean;

package/dist/internal/features/work/work-xlsx-rich-text.d.ts

@@ -0,0 +1,41 @@
+import type { Cell, Sheet } from '@fortune-sheet/core';
+import { type SpreadsheetUnderlineStyle } from './work-spreadsheet-underline';
+import { type XlsxCellStyleOrigin, type XlsxSemanticPalette } from './work-xlsx-cell-style-origin';
+import { type XlsxColorResolver } from './work-xlsx-colors';
+import { type XlsxRichTextRun } from './work-xlsx-rich-text-model';
+export { MAX_XLSX_RICH_TEXT_CELL_CHARACTERS, MAX_XLSX_RICH_TEXT_CELLS, MAX_XLSX_RICH_TEXT_RUNS, MAX_XLSX_RICH_TEXT_RUNS_PER_CELL, type XlsxRichTextRun, } from './work-xlsx-rich-text-model';
+export interface XlsxRichTextCell {
+    column: number;
+    row: number;
+    runs: XlsxRichTextRun[];
+    text: string;
+}
+export interface XlsxRichTextReadContext {
+    readonly colors: XlsxColorResolver;
+    readonly hasRichSharedStrings: boolean;
+    readonly sharedStrings: ReadonlyMap<number, readonly XlsxRichTextRun[]>;
+    remainingCells: number;
+    remainingRuns: number;
+}
+interface XlsxRichTextContextOptions {
+    sharedStrings: Document | null;
+    styles: Document | null;
+    theme: Document | null;
+}
+interface SpreadsheetRichTextFontPatch {
+    bold?: boolean;
+    fontColor?: string;
+    fontFamily?: string;
+    fontSize?: number;
+    italic?: boolean;
+    strike?: boolean;
+    underline?: SpreadsheetUnderlineStyle;
+}
+export declare function createXlsxRichTextReadContext(options: XlsxRichTextContextOptions): XlsxRichTextReadContext;
+export declare function readXlsxRichTextCells(worksheet: Document, context: XlsxRichTextReadContext): XlsxRichTextCell[];
+export declare function applyImportedXlsxRichText(cell: Cell, richText: XlsxRichTextCell | undefined): Cell;
+export declare function patchSpreadsheetRichTextFontRuns(cell: Cell, patch: SpreadsheetRichTextFontPatch): Cell;
+export declare function xlsxRichTextCellText(cell: Cell): string | null;
+export declare function sheetHasXlsxRichTextCells(sheet: Sheet): boolean;
+export declare function xlsxRichTextStyleOrigins(sheet: Sheet): XlsxCellStyleOrigin[];
+export declare function writeXlsxRichTextCells(worksheet: Document, sheet: Sheet, semanticPalette?: XlsxSemanticPalette): void;

package/dist/internal/features/work/work-xlsx-worksheet-scan.d.ts

@@ -3,6 +3,7 @@ export interface XlsxWorksheetXmlScan {
     hasDiagnosticFeatures: boolean;
     hasFormulaFeatures: boolean;
     hasImportedFeatures: boolean;
+    hasRichTextCells: boolean;
     requiresSheetJsCellStyles: boolean;
 }
 /**

package/dist/internal/features/work/work-xlsx-worksheet.d.ts

@@ -10,3 +10,8 @@ export interface XlsxWorksheetCellEntry {
  * materializing a second list of every worksheet cell.
  */
 export declare function xlsxWorksheetCellEntries(worksheet: WorkSheet): Generator<XlsxWorksheetCellEntry>;
+export declare function xlsxCellAddress(row: number, column: number): string;
+export declare function decodeXlsxCellAddress(address: string): {
+    column: number;
+    row: number;
+} | null;

package/dist/work-spreadsheet-package-scan.worker.js

@@ -4012,22 +4012,24 @@ https://github.com/nodeca/pako/blob/main/LICENSE
             'rowBreaks',
             'colBreaks'
         ]);
-        const WORKSHEET_SCAN_PATTERN = /<(?:[A-Za-z_][\w.-]*:)?(?:(cols|f|pane|dataValidation|conditionalFormatting|sheetProtection|protectedRange|rowBreaks|colBreaks|pageSetup|pageMargins|printOptions|headerFooter|pageSetUpPr|drawing|tableParts)(?=[\s/>])|(row)(?=[\s/>])[^>]*\s(?:collapsed|customFormat|customHeight|hidden|ht|outlineLevel|thickBot|thickTop)\s*=|(c)(?=[\s/>])[^>]*\ss\s*=)/g;
+        const WORKSHEET_SCAN_PATTERN = /<(?:[A-Za-z_][\w.-]*:)?(?:(cols|f|pane|dataValidation|conditionalFormatting|sheetProtection|protectedRange|rowBreaks|colBreaks|pageSetup|pageMargins|printOptions|headerFooter|pageSetUpPr|drawing|tableParts)(?=[\s/>])|(row)(?=[\s/>])[^>]*\s(?:collapsed|customFormat|customHeight|hidden|ht|outlineLevel|thickBot|thickTop)\s*=|(c)(?=[\s/>])[^>]*\ss\s*=|(r)(?=[\s/>]))/g;
         function scanXlsxWorksheetXml(source) {
             let hasDirectCellStyles = false;
             let hasDiagnosticFeatures = false;
             let hasFormulaFeatures = false;
             let hasImportedFeatures = false;
+            let hasRichTextCells = false;
             let requiresSheetJsCellStyles = false;
             WORKSHEET_SCAN_PATTERN.lastIndex = 0;
             for(let match = WORKSHEET_SCAN_PATTERN.exec(source); match;){
                 const element = match[1];
                 if (match[3]) hasDirectCellStyles = true;
+                if (match[4]) hasRichTextCells = true;
                 if (match[2] || match[3] || 'cols' === element) requiresSheetJsCellStyles = true;
                 if ('f' === element) hasFormulaFeatures = true;
                 if (element && IMPORTED_WORKSHEET_ELEMENTS.has(element)) hasImportedFeatures = true;
                 if (element && DIAGNOSTIC_WORKSHEET_ELEMENTS.has(element)) hasDiagnosticFeatures = true;
-                if (hasDirectCellStyles && hasDiagnosticFeatures && hasFormulaFeatures && hasImportedFeatures && requiresSheetJsCellStyles) break;
+                if (hasDirectCellStyles && hasDiagnosticFeatures && hasFormulaFeatures && hasImportedFeatures && hasRichTextCells && requiresSheetJsCellStyles) break;
                 match = WORKSHEET_SCAN_PATTERN.exec(source);
             }
             WORKSHEET_SCAN_PATTERN.lastIndex = 0;
@@ -4036,6 +4038,7 @@ https://github.com/nodeca/pako/blob/main/LICENSE
                 hasDiagnosticFeatures,
                 hasFormulaFeatures,
                 hasImportedFeatures,
+                hasRichTextCells,
                 requiresSheetJsCellStyles
             };
         }
@@ -4131,6 +4134,7 @@ https://github.com/nodeca/pako/blob/main/LICENSE
             hasDiagnosticFeatures: false,
             hasFormulaFeatures: false,
             hasImportedFeatures: false,
+            hasRichTextCells: false,
             requiresSheetJsCellStyles: false
         };
         async function plainWorkbookPlan(zip, packagePaths) {

package/docs/latest/en/browser-editor-architecture.md

@@ -319,6 +319,33 @@ materialization. Fortune row/column operations are reconciled back into table
 ranges, column identities, filter offsets, and canonical header cells, while
 merge and worksheet AutoFilter commands reject intersecting ownership.
 
+Native XLSX rich-text editing is reconciled at the controlled Fortune boundary,
+not inside the rendering engine. A pure model normalizes at most 512 runs and
+32,767 UTF-16 code units, derives one contiguous replacement, uses binary run
+lookup for inherited styles, and coalesces only semantically identical adjacent
+runs. Authenticated `data[row][column]` operations permit text changes at exact
+coordinates. In the full-projection compatibility path, a non-structural batch
+without a cell coordinate may restore prior runs only when the visible text is
+exactly unchanged; structural operations disable coordinate inference. This
+keeps formula-bar and F2 commits to one host revision and one Undo record while
+discarding Fortune focus callbacks that merely flatten or strip run metadata.
+
+Formatted paste adds a separate one-shot authority instead of trusting live
+DOM markup. A paste event in the formula bar or F2 editor records the exact
+sheet object, coordinate, controlled source text, UTF-16 selection, sanitized
+clipboard runs, and plain text before the browser mutates the editor. The
+incremental and full projection paths may consume that authority only when an
+authenticated cell operation emits the exact predicted replacement. Prefix
+and suffix runs always come from the controlled source; only the inserted
+range may use clipboard font family, point size, RGB color, bold, italic,
+strikethrough, or underline. This also converts eligible plain or empty cells
+to native inline strings without granting structural callbacks a coordinate.
+The parser never retains clipboard HTML, ignores active/non-content elements,
+and rejects mismatched text, invalid UTF-16, more than 256,000 HTML characters,
+32,767 cell characters, or 512 resulting runs. Imported semantic color
+identities remain attached to untouched runs; pasted colors are explicit RGB
+unless a future package-level source can prove a native palette identity.
+
 The table is a fidelity statement, not a marketing capability list. The
 current Document path shapes text-flow paragraphs in Rust/WASM when every
 explicit CSS family resolves to an exact registered face. Each run may carry up

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a3s-lab/office",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "Open-source collaborative browser editors for documents, Markdown, spreadsheets, presentations, and PDFs.",
   "keywords": [
     "office",
@@ -95,6 +95,7 @@
     "playground:visual:spreadsheet-font-colors-shortcuts": "playwright test visual-tests/spreadsheet-font-colors-shortcuts.functional.spec.ts --config playwright.config.ts",
     "playground:visual:spreadsheet-hyperlink": "playwright test visual-tests/spreadsheet-hyperlink.functional.spec.ts --config playwright.config.ts",
     "playground:visual:spreadsheet-ribbon": "playwright test visual-tests/spreadsheet-ribbon.functional.spec.ts --config playwright.config.ts",
+    "playground:visual:spreadsheet-rich-text": "playwright test visual-tests/spreadsheet-rich-text.functional.spec.ts --config playwright.config.ts",
     "playground:visual:spreadsheet-underline": "playwright test visual-tests/spreadsheet-underline.functional.spec.ts --config playwright.config.ts",
     "playground:visual:spreadsheet-table": "playwright test visual-tests/spreadsheet-table.functional.spec.ts --config playwright.config.ts",
     "playground:visual:update": "playwright test --config playwright.config.ts --update-snapshots",
@@ -169,6 +170,8 @@
     "test:e2e:spreadsheet-copy-from-above:check": "a3s-test check tests/e2e/spreadsheet-copy-from-above.acl --json",
     "test:e2e:spreadsheet-font-dialog-shortcuts": "A3S_TEST_SUITE=tests/e2e/spreadsheet-font-dialog-shortcuts.acl bash scripts/run-a3s-test-web-gate.sh",
     "test:e2e:spreadsheet-font-dialog-shortcuts:check": "a3s-test check tests/e2e/spreadsheet-font-dialog-shortcuts.acl --json",
+    "test:e2e:spreadsheet-rich-text": "A3S_TEST_SUITE=tests/e2e/spreadsheet-rich-text.acl bash scripts/run-a3s-test-web-gate.sh",
+    "test:e2e:spreadsheet-rich-text:check": "a3s-test check tests/e2e/spreadsheet-rich-text.acl --json",
     "test:e2e:spreadsheet-hyperlink": "a3s-test run tests/e2e/spreadsheet-hyperlink.acl --json",
     "test:e2e:spreadsheet-hyperlink:check": "a3s-test check tests/e2e/spreadsheet-hyperlink.acl --json",
     "test:e2e:spreadsheet-maximum-sparse": "a3s-test run tests/e2e/spreadsheet-maximum-sparse.acl --json",