@a3s-lab/office 0.25.0 → 0.26.0

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-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

@@ -1,22 +1,9 @@
 import type { Cell, Sheet } from '@fortune-sheet/core';
-import { type SpreadsheetUnderlineCellValue, type SpreadsheetUnderlineStyle } from './work-spreadsheet-underline';
-import { type XlsxCellStyleOrigin, type XlsxSemanticColorOrigin, type XlsxSemanticPalette } from './work-xlsx-cell-style-origin';
+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';
-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 interface XlsxRichTextRun {
-    a3sXlsxColorOrigin?: XlsxSemanticColorOrigin;
-    bl?: 0 | 1;
-    cl?: 0 | 1;
-    fc?: string;
-    ff?: string;
-    fs?: number;
-    it?: 0 | 1;
-    un?: SpreadsheetUnderlineCellValue;
-    v: string;
-}
+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;
@@ -52,4 +39,3 @@ 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;
-export {};

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.25.0",
+  "version": "0.26.0",
   "description": "Open-source collaborative browser editors for documents, Markdown, spreadsheets, presentations, and PDFs.",
   "keywords": [
     "office",