@beyondwork/docx-react-component 1.0.0

package/src/core/state/text-transaction.ts

@@ -0,0 +1,276 @@
+import { createSelectionSnapshot, type CanonicalDocumentEnvelope, type SelectionSnapshot } from "./editor-state.ts";
+import type { TransactionMapping } from "../selection/mapping.ts";
+import {
+  cloneParagraphProperties,
+  cloneStoryUnit,
+  createPlainText,
+  parseTextStory,
+  serializeTextStory,
+  type ParagraphProperties,
+  type StoryUnit,
+  type TextStory,
+} from "../schema/text-schema.ts";
+
+export type TextInsertion =
+  | {
+      type: "text";
+      text: string;
+    }
+  | {
+      type: "tab";
+    }
+  | {
+      type: "hard_break";
+    }
+  | {
+      type: "paragraph_break";
+    };
+
+export type TextTransactionIntent =
+  | {
+      type: "replace";
+      range?: {
+        from: number;
+        to: number;
+      };
+      insertion: TextInsertion[];
+    }
+  | {
+      type: "delete_backward";
+    }
+  | {
+      type: "delete_forward";
+    };
+
+export interface TextTransactionResult {
+  document: CanonicalDocumentEnvelope;
+  selection: SelectionSnapshot;
+  mapping: TransactionMapping;
+  storyText: string;
+}
+
+export class TextTransactionError extends Error {
+  readonly code: "invalid_selection" | "unsupported_content";
+
+  constructor(
+    code: TextTransactionError["code"],
+    message: string,
+  ) {
+    super(message);
+    this.name = "TextTransactionError";
+    this.code = code;
+  }
+}
+
+export function applyTextTransaction(
+  document: CanonicalDocumentEnvelope,
+  selection: SelectionSnapshot,
+  intent: TextTransactionIntent,
+  options: {
+    timestamp: string;
+  },
+): TextTransactionResult {
+  const story = parseTextStory(document.content);
+  const normalizedRange = resolveRange(selection, story.size, intent);
+  const insertionUnits = createInsertionUnits(intent, story, normalizedRange.from);
+
+  ensureEditableRange(story.units.slice(normalizedRange.from, normalizedRange.to));
+
+  const nextUnits = [
+    ...story.units.slice(0, normalizedRange.from).map(cloneStoryUnit),
+    ...insertionUnits.map(cloneStoryUnit),
+    ...story.units.slice(normalizedRange.to).map(cloneStoryUnit),
+  ];
+
+  const nextStory: TextStory = {
+    firstParagraph: cloneParagraphProperties(story.firstParagraph),
+    units: normalizeStoryUnits(nextUnits),
+    size: 0,
+  };
+  nextStory.size = nextStory.units.length;
+
+  const caret = normalizedRange.from + insertionUnits.length;
+
+  return {
+    document: {
+      ...document,
+      updatedAt: options.timestamp,
+      content: serializeTextStory(nextStory),
+    },
+    selection: createSelectionSnapshot(caret, caret),
+    mapping: {
+      steps: [
+        {
+          from: normalizedRange.from,
+          to: normalizedRange.to,
+          insertSize: insertionUnits.length,
+        },
+      ],
+      metadata: {
+        affectsComments: true,
+        affectsRevisions: true,
+        ...(containsParagraphBoundaryChange(story, normalizedRange, insertionUnits)
+          ? { invalidatesStructures: true }
+          : {}),
+      },
+    },
+    storyText: createPlainText(nextStory),
+  };
+}
+
+function resolveRange(
+  selection: SelectionSnapshot,
+  storySize: number,
+  intent: TextTransactionIntent,
+): { from: number; to: number } {
+  const from = Math.max(0, Math.min(selection.anchor, selection.head));
+  const to = Math.max(0, Math.max(selection.anchor, selection.head));
+
+  if (from > storySize || to > storySize) {
+    throw new TextTransactionError(
+      "invalid_selection",
+      `Selection ${from}-${to} exceeds story size ${storySize}.`,
+    );
+  }
+
+  if (intent.type === "replace") {
+    if (intent.range) {
+      const explicitFrom = Math.max(0, Math.min(intent.range.from, intent.range.to));
+      const explicitTo = Math.max(0, Math.max(intent.range.from, intent.range.to));
+      if (explicitFrom > storySize || explicitTo > storySize) {
+        throw new TextTransactionError(
+          "invalid_selection",
+          `Explicit range ${explicitFrom}-${explicitTo} exceeds story size ${storySize}.`,
+        );
+      }
+
+      return {
+        from: explicitFrom,
+        to: explicitTo,
+      };
+    }
+
+    return { from, to };
+  }
+
+  if (from !== to) {
+    return { from, to };
+  }
+
+  if (intent.type === "delete_backward") {
+    return {
+      from: Math.max(0, from - 1),
+      to: from,
+    };
+  }
+
+  return {
+    from,
+    to: Math.min(storySize, from + 1),
+  };
+}
+
+function createInsertionUnits(
+  intent: TextTransactionIntent,
+  story: TextStory,
+  position: number,
+): StoryUnit[] {
+  if (intent.type !== "replace") {
+    return [];
+  }
+
+  const inheritedProps = resolveParagraphPropertiesAtPosition(story, position);
+
+  return intent.insertion.flatMap((entry) => {
+    switch (entry.type) {
+      case "text":
+        return Array.from(entry.text).map<StoryUnit>((character) => ({
+          kind: "text",
+          value: character,
+        }));
+      case "tab":
+        return [{ kind: "tab" }];
+      case "hard_break":
+        return [{ kind: "hard_break" }];
+      case "paragraph_break":
+        return [
+          {
+            kind: "paragraph_break",
+            nextParagraph: cloneParagraphProperties(inheritedProps),
+          },
+        ];
+    }
+  });
+}
+
+function resolveParagraphPropertiesAtPosition(
+  story: TextStory,
+  position: number,
+): ParagraphProperties {
+  let current = cloneParagraphProperties(story.firstParagraph);
+
+  for (let index = 0; index < Math.min(position, story.units.length); index += 1) {
+    const unit = story.units[index];
+    if (unit.kind === "paragraph_break") {
+      current = cloneParagraphProperties(unit.nextParagraph);
+    } else if (unit.kind === "opaque_block" && unit.nextParagraph) {
+      current = cloneParagraphProperties(unit.nextParagraph);
+    }
+  }
+
+  return current;
+}
+
+function normalizeStoryUnits(units: StoryUnit[]): StoryUnit[] {
+  if (units.length === 0) {
+    return [];
+  }
+
+  const normalized: StoryUnit[] = [];
+
+  for (const unit of units) {
+    if (
+      unit.kind === "paragraph_break" &&
+      normalized[normalized.length - 1]?.kind === "paragraph_break"
+    ) {
+      normalized.push({
+        kind: "paragraph_break",
+        nextParagraph: cloneParagraphProperties(unit.nextParagraph),
+      });
+      continue;
+    }
+
+    normalized.push(cloneStoryUnit(unit));
+  }
+
+  return normalized;
+}
+
+function ensureEditableRange(units: StoryUnit[]): void {
+  const protectedUnit = units.find(
+    (unit) => unit.kind === "opaque_inline" || unit.kind === "opaque_block" || unit.kind === "image",
+  );
+
+  if (!protectedUnit) {
+    return;
+  }
+
+  throw new TextTransactionError(
+    "unsupported_content",
+    `Text transaction crosses protected ${protectedUnit.kind} content.`,
+  );
+}
+
+function containsParagraphBoundaryChange(
+  story: TextStory,
+  range: { from: number; to: number },
+  insertionUnits: StoryUnit[],
+): boolean {
+  if (insertionUnits.some((unit) => unit.kind === "paragraph_break")) {
+    return true;
+  }
+
+  return story.units
+    .slice(range.from, range.to)
+    .some((unit) => unit.kind === "paragraph_break");
+}

package/src/formats/xlsx/io/parse-shared-strings.ts

@@ -0,0 +1,41 @@
+/**
+ * Parses xl/sharedStrings.xml and returns the shared string table as an ordered array.
+ *
+ * Handles both simple text (<si><t>...</t></si>) and rich text runs
+ * (<si><r><t>...</t></r></si>) by concatenating all <t> content within each <si>.
+ */
+export function parseSharedStringsXml(xml: string): string[] {
+  const result: string[] = [];
+  const siPattern = /<si>([\s\S]*?)<\/si>/g;
+  let siMatch: RegExpExecArray | null;
+
+  while ((siMatch = siPattern.exec(xml)) !== null) {
+    const siContent = siMatch[1] ?? "";
+    result.push(extractSharedStringText(siContent));
+  }
+
+  return result;
+}
+
+function extractSharedStringText(siContent: string): string {
+  // Collect text from all <t> elements (handles plain and rich text runs).
+  // The xml:space="preserve" attribute is not significant for the string value.
+  const tPattern = /<t(?:\s[^>]*)?>([^<]*)<\/t>/g;
+  const parts: string[] = [];
+  let tMatch: RegExpExecArray | null;
+
+  while ((tMatch = tPattern.exec(siContent)) !== null) {
+    parts.push(decodeXmlEntities(tMatch[1] ?? ""));
+  }
+
+  return parts.join("");
+}
+
+export function decodeXmlEntities(value: string): string {
+  return value
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&amp;/g, "&");
+}

package/src/formats/xlsx/io/parse-sheet.ts

@@ -0,0 +1,289 @@
+import { decodeXmlEntities, parseSharedStringsXml as _unused } from "./parse-shared-strings.ts";
+import { parseXmlAttributes } from "./parse-styles.ts";
+
+// Re-export for external use
+export { decodeXmlEntities };
+
+/**
+ * A parsed cell from a SpreadsheetML worksheet.
+ *
+ * Row and col are zero-based indices. The value discriminated union covers all
+ * SpreadsheetML cell type codes: s (shared string), inlineStr, n/absent (number),
+ * b (boolean), e (error), str (formula string result), and blank.
+ */
+export type XlsxParsedCellValue =
+  | { type: "blank" }
+  | { type: "text"; value: string }
+  | { type: "number"; value: number }
+  | { type: "boolean"; value: boolean }
+  | { type: "formula"; formula: string; cachedValue: string | null }
+  | { type: "error"; errorCode: string };
+
+export interface XlsxParsedCell {
+  row: number;
+  col: number;
+  value: XlsxParsedCellValue;
+  styleIndex: number | null;
+}
+
+/**
+ * A parsed merge range from the <mergeCells> section.
+ * All indices are zero-based.
+ */
+export interface XlsxParsedMerge {
+  startRow: number;
+  startCol: number;
+  endRow: number;
+  endCol: number;
+}
+
+export interface SheetParseResult {
+  cells: XlsxParsedCell[];
+  merges: XlsxParsedMerge[];
+}
+
+/**
+ * Parses xl/worksheets/sheetN.xml.
+ *
+ * @param xml - Raw XML string of the worksheet part.
+ * @param sharedStrings - The shared string table from parseSharedStringsXml.
+ */
+export function parseSheetXml(
+  xml: string,
+  sharedStrings: readonly string[],
+): SheetParseResult {
+  const cells: XlsxParsedCell[] = [];
+  const merges: XlsxParsedMerge[] = [];
+
+  const sheetDataMatch = /<sheetData>([\s\S]*?)<\/sheetData>/i.exec(xml);
+  if (sheetDataMatch) {
+    parseSheetData(sheetDataMatch[1] ?? "", sharedStrings, cells);
+  }
+
+  const mergeCellsMatch = /<mergeCells\b[^>]*>([\s\S]*?)<\/mergeCells>/i.exec(xml);
+  if (mergeCellsMatch) {
+    parseMergeCells(mergeCellsMatch[1] ?? "", merges);
+  }
+
+  return { cells, merges };
+}
+
+function parseSheetData(
+  sheetDataXml: string,
+  sharedStrings: readonly string[],
+  out: XlsxParsedCell[],
+): void {
+  // Match non-empty rows (<row ...>...</row>)
+  const rowPattern = /<row\b([^>]*)>([\s\S]*?)<\/row>/g;
+  let rowMatch: RegExpExecArray | null;
+
+  while ((rowMatch = rowPattern.exec(sheetDataXml)) !== null) {
+    const rowContent = rowMatch[2] ?? "";
+    parseRowCells(rowContent, sharedStrings, out);
+  }
+}
+
+function parseRowCells(
+  rowXml: string,
+  sharedStrings: readonly string[],
+  out: XlsxParsedCell[],
+): void {
+  // Match cells: both non-empty (<c ...>...</c>) and self-closing (<c .../>)
+  const cellPattern = /<c\b([^>]*)(?:>([\s\S]*?)<\/c>|\/>)/g;
+  let cellMatch: RegExpExecArray | null;
+
+  while ((cellMatch = cellPattern.exec(rowXml)) !== null) {
+    const attrs = parseXmlAttributes(cellMatch[1] ?? "");
+    const content = cellMatch[2] ?? "";
+    const cell = parseCell(attrs, content, sharedStrings);
+    if (cell !== null) {
+      out.push(cell);
+    }
+  }
+}
+
+function parseCell(
+  attrs: Record<string, string>,
+  content: string,
+  sharedStrings: readonly string[],
+): XlsxParsedCell | null {
+  const ref = attrs["r"];
+  if (!ref) {
+    return null;
+  }
+
+  const cellRef = parseCellRef(ref);
+  if (cellRef === null) {
+    return null;
+  }
+
+  const styleIndexAttr = attrs["s"];
+  const styleIndex =
+    styleIndexAttr !== undefined ? parseInt(styleIndexAttr, 10) : null;
+
+  const typeCode = attrs["t"] ?? "n";
+  const rawValue = extractTextContent(content, "v");
+  const formulaText = extractTextContent(content, "f");
+  const inlineText = extractInlineStringText(content);
+
+  const value = resolveCellValue(typeCode, rawValue, formulaText, inlineText, sharedStrings);
+
+  return {
+    row: cellRef.row,
+    col: cellRef.col,
+    value,
+    styleIndex: styleIndex !== null && !Number.isNaN(styleIndex) ? styleIndex : null,
+  };
+}
+
+function resolveCellValue(
+  typeCode: string,
+  rawValue: string | null,
+  formulaText: string | null,
+  inlineText: string | null,
+  sharedStrings: readonly string[],
+): XlsxParsedCellValue {
+  // Formula cells may have any result type; store formula + cached value.
+  if (formulaText !== null) {
+    return {
+      type: "formula",
+      formula: decodeXmlEntities(formulaText),
+      cachedValue: rawValue !== null ? decodeXmlEntities(rawValue) : null,
+    };
+  }
+
+  switch (typeCode) {
+    case "s": {
+      // Shared string reference
+      const index = rawValue !== null ? parseInt(rawValue, 10) : NaN;
+      const text =
+        !Number.isNaN(index) && index >= 0 && index < sharedStrings.length
+          ? (sharedStrings[index] ?? "")
+          : "";
+      return { type: "text", value: text };
+    }
+
+    case "inlineStr": {
+      return { type: "text", value: inlineText ?? "" };
+    }
+
+    case "str": {
+      // Formula result is a string; formula text would have been captured above.
+      // Here the cell carries only the cached string value (no formula tag).
+      return {
+        type: "text",
+        value: rawValue !== null ? decodeXmlEntities(rawValue) : "",
+      };
+    }
+
+    case "b": {
+      return { type: "boolean", value: rawValue === "1" };
+    }
+
+    case "e": {
+      return {
+        type: "error",
+        errorCode:
+          rawValue !== null ? decodeXmlEntities(rawValue) : "#ERROR!",
+      };
+    }
+
+    default: {
+      // "n" or absent — numeric value
+      if (rawValue === null || rawValue === "") {
+        return { type: "blank" };
+      }
+
+      const numericValue = parseFloat(rawValue);
+      return Number.isNaN(numericValue)
+        ? { type: "blank" }
+        : { type: "number", value: numericValue };
+    }
+  }
+}
+
+function extractTextContent(xml: string, tagName: string): string | null {
+  const pattern = new RegExp(`<${tagName}(?:\\s[^>]*)?>([^<]*)</${tagName}>`, "i");
+  const match = pattern.exec(xml);
+  return match ? (match[1] ?? null) : null;
+}
+
+function extractInlineStringText(cellContent: string): string | null {
+  // <is> contains rich text identical to shared string runs
+  const isMatch = /<is>([\s\S]*?)<\/is>/i.exec(cellContent);
+  if (!isMatch) {
+    return null;
+  }
+
+  const tPattern = /<t(?:\s[^>]*)?>([^<]*)<\/t>/g;
+  const parts: string[] = [];
+  let tMatch: RegExpExecArray | null;
+
+  while ((tMatch = tPattern.exec(isMatch[1] ?? "")) !== null) {
+    parts.push(decodeXmlEntities(tMatch[1] ?? ""));
+  }
+
+  return parts.join("");
+}
+
+function parseMergeCells(mergeCellsXml: string, out: XlsxParsedMerge[]): void {
+  const mergePattern = /<mergeCell\b([^>]*?)(?:\/>|>[\s\S]*?<\/mergeCell>)/g;
+  let match: RegExpExecArray | null;
+
+  while ((match = mergePattern.exec(mergeCellsXml)) !== null) {
+    const attrs = parseXmlAttributes(match[1] ?? "");
+    const ref = attrs["ref"] ?? "";
+    const merge = parseMergeRef(ref);
+    if (merge !== null) {
+      out.push(merge);
+    }
+  }
+}
+
+function parseMergeRef(ref: string): XlsxParsedMerge | null {
+  const parts = ref.split(":");
+  if (parts.length !== 2) {
+    return null;
+  }
+
+  const start = parseCellRef(parts[0] ?? "");
+  const end = parseCellRef(parts[1] ?? "");
+  if (start === null || end === null) {
+    return null;
+  }
+
+  return {
+    startRow: start.row,
+    startCol: start.col,
+    endRow: end.row,
+    endCol: end.col,
+  };
+}
+
+function parseCellRef(ref: string): { row: number; col: number } | null {
+  const match = /^([A-Z]+)([0-9]+)$/i.exec(ref.trim());
+  if (!match) {
+    return null;
+  }
+
+  return {
+    col: colLettersToIndex(match[1] ?? ""),
+    row: parseInt(match[2] ?? "1", 10) - 1,
+  };
+}
+
+/**
+ * Converts a column letter sequence to a zero-based column index.
+ * "A" -> 0, "Z" -> 25, "AA" -> 26, "AZ" -> 51, "BA" -> 52.
+ */
+function colLettersToIndex(letters: string): number {
+  let result = 0;
+
+  for (const char of letters.toUpperCase()) {
+    result = result * 26 + (char.charCodeAt(0) - 64);
+  }
+
+  return result - 1;
+}
+
+export { parseCellRef, colLettersToIndex };

package/src/formats/xlsx/io/parse-styles.ts

@@ -0,0 +1,57 @@
+/**
+ * Parses xl/styles.xml for the cellXfs table (cell format entries).
+ *
+ * Each entry provides style references (numFmtId, fontId, fillId, borderId)
+ * that cells reference by zero-based index via the s= attribute.
+ */
+export interface XlsxStyleEntry {
+  numFmtId: number;
+  fontId: number;
+  fillId: number;
+  borderId: number;
+}
+
+export function parseStylesXml(xml: string): XlsxStyleEntry[] {
+  const cellXfsMatch = /<cellXfs\b[^>]*>([\s\S]*?)<\/cellXfs>/i.exec(xml);
+  if (!cellXfsMatch) {
+    return [];
+  }
+
+  const cellXfsContent = cellXfsMatch[1] ?? "";
+  const xfPattern = /<xf\b([^>]*?)(?:\/>|>[\s\S]*?<\/xf>)/g;
+  const entries: XlsxStyleEntry[] = [];
+  let xfMatch: RegExpExecArray | null;
+
+  while ((xfMatch = xfPattern.exec(cellXfsContent)) !== null) {
+    const attrs = parseXmlAttributes(xfMatch[1] ?? "");
+    entries.push({
+      numFmtId: parseIntAttr(attrs["numFmtId"], 0),
+      fontId: parseIntAttr(attrs["fontId"], 0),
+      fillId: parseIntAttr(attrs["fillId"], 0),
+      borderId: parseIntAttr(attrs["borderId"], 0),
+    });
+  }
+
+  return entries;
+}
+
+function parseIntAttr(value: string | undefined, defaultValue: number): number {
+  if (value === undefined || value === "") {
+    return defaultValue;
+  }
+
+  const parsed = parseInt(value, 10);
+  return Number.isNaN(parsed) ? defaultValue : parsed;
+}
+
+export function parseXmlAttributes(rawAttributes: string): Record<string, string> {
+  const attributes: Record<string, string> = {};
+  const attributePattern = /([A-Za-z_][\w:.-]*)="([^"]*)"/g;
+  let match: RegExpExecArray | null;
+
+  while ((match = attributePattern.exec(rawAttributes)) !== null) {
+    attributes[match[1]] = match[2];
+  }
+
+  return attributes;
+}