@beyondwork/docx-react-component 1.0.17 → 1.0.19

package/src/core/commands/section-layout-commands.ts

@@ -0,0 +1,680 @@
+/**
+ * Section layout authoring commands.
+ *
+ * Supports inserting and deleting section breaks, bounded section layout
+ * updates (page size, margins, gutter, orientation, columns, first-page /
+ * odd-even variants, page-numbering restart / format), and section break
+ * deletion with following-section merge semantics.
+ *
+ * All mutations are command-backed and export-safe.
+ */
+import type {
+  RuntimeRenderSnapshot,
+  SelectionSnapshot,
+} from "../../api/public-types";
+import type {
+  CanonicalDocument as CanonicalDocumentEnvelope,
+  ColumnProperties,
+  PageMargins,
+  PageNumbering,
+  PageSize,
+  SectionBreakNode,
+  SectionProperties,
+} from "../../model/canonical-document.ts";
+
+// ---- Public types ----
+
+export interface SectionLayoutCommandContext {
+  timestamp: string;
+}
+
+export interface SectionLayoutMutationResult {
+  document: CanonicalDocumentEnvelope;
+  selection: SelectionSnapshot;
+  changed: boolean;
+}
+
+export type SectionBreakType =
+  | "nextPage"
+  | "continuous"
+  | "evenPage"
+  | "oddPage"
+  | "nextColumn";
+
+export interface SectionLayoutPatch {
+  pageSize?: Partial<PageSize>;
+  pageMargins?: Partial<PageMargins>;
+  columns?: Partial<ColumnProperties>;
+  pageNumbering?: Partial<PageNumbering>;
+  titlePage?: boolean;
+  sectionType?: SectionBreakType;
+}
+
+export interface SectionLinkPatch {
+  kind: "header" | "footer";
+  variant: "default" | "first" | "even";
+  linkToPrevious: boolean;
+  relationshipId?: string | null;
+}
+
+// ---- Insert section break ----
+
+/**
+ * Insert a section break at the current selection position.
+ * The new section inherits properties from the section that contained the
+ * insertion point (the *following* section keeps its own properties).
+ */
+export function insertSectionBreak(
+  document: CanonicalDocumentEnvelope,
+  snapshot: RuntimeRenderSnapshot,
+  breakType: SectionBreakType,
+  _context: SectionLayoutCommandContext,
+): SectionLayoutMutationResult {
+  const cloned = structuredClone(document) as CanonicalDocumentEnvelope;
+  const surface = snapshot.surface;
+
+  if (!surface) {
+    return noopResult(document, snapshot.selection);
+  }
+
+  const position = snapshot.selection.head;
+  const blockIndex = resolveBlockIndexForPosition(surface.blocks, position);
+
+  if (blockIndex < 0) {
+    return noopResult(document, snapshot.selection);
+  }
+
+  const sectionTarget = resolveSectionTarget(cloned, surface.blocks, position);
+  const inheritedProperties = cloneSectionProperties(sectionTarget?.properties);
+  const sectionBreak: SectionBreakNode = {
+    type: "section_break",
+    sectionProperties: {
+      ...inheritedProperties,
+      sectionType: breakType,
+    },
+  };
+
+  cloned.content.children.splice(blockIndex + 1, 0, sectionBreak);
+  cloned.updatedAt = _context.timestamp;
+
+  return {
+    document: cloned,
+    selection: snapshot.selection,
+    changed: true,
+  };
+}
+
+export function insertSectionBreakAfterSectionIndex(
+  document: CanonicalDocumentEnvelope,
+  sectionIndex: number,
+  breakType: SectionBreakType,
+  context: SectionLayoutCommandContext,
+): SectionLayoutMutationResult {
+  const cloned = structuredClone(document) as CanonicalDocumentEnvelope;
+  const insertionIndex = findSectionInsertionIndex(cloned, sectionIndex);
+  if (insertionIndex < 0) {
+    return noopResult(document, createSelectionSnapshot(0, 0));
+  }
+
+  const inheritedProperties = cloneSectionProperties(
+    getSectionPropertiesAtIndex(cloned, sectionIndex),
+  );
+  const sectionBreak: SectionBreakNode = {
+    type: "section_break",
+    sectionProperties: {
+      ...inheritedProperties,
+      sectionType: breakType,
+    },
+  };
+
+  cloned.content.children.splice(insertionIndex, 0, sectionBreak);
+  cloned.updatedAt = context.timestamp;
+
+  return {
+    document: cloned,
+    selection: createSelectionSnapshot(0, 0),
+    changed: true,
+  };
+}
+
+// ---- Delete section break ----
+
+/**
+ * Delete the section break at or nearest to the current selection position.
+ * On deletion the *following* section's formatting and header/footer linkage
+ * are adopted (Word merge semantics).
+ */
+export function deleteSectionBreak(
+  document: CanonicalDocumentEnvelope,
+  snapshot: RuntimeRenderSnapshot,
+  _context: SectionLayoutCommandContext,
+): SectionLayoutMutationResult {
+  const cloned = structuredClone(document) as CanonicalDocumentEnvelope;
+
+  const breakIndex = findNearestSectionBreak(cloned, snapshot);
+  if (breakIndex < 0) {
+    return noopResult(document, snapshot.selection);
+  }
+
+  const breakNode = cloned.content.children[breakIndex];
+  if (!breakNode || breakNode.type !== "section_break") {
+    return noopResult(document, snapshot.selection);
+  }
+
+  // Remove the section break node
+  cloned.content.children.splice(breakIndex, 1);
+
+  cloned.updatedAt = _context.timestamp;
+
+  return {
+    document: cloned,
+    selection: snapshot.selection,
+    changed: true,
+  };
+}
+
+export function deleteSectionBreakAtSectionIndex(
+  document: CanonicalDocumentEnvelope,
+  sectionIndex: number,
+  context: SectionLayoutCommandContext,
+): SectionLayoutMutationResult {
+  if (sectionIndex <= 0) {
+    return noopResult(document, createSelectionSnapshot(0, 0));
+  }
+
+  const cloned = structuredClone(document) as CanonicalDocumentEnvelope;
+  const breakIndex = findSectionBreakNodeIndexForSection(cloned, sectionIndex);
+  if (breakIndex < 0) {
+    return noopResult(document, createSelectionSnapshot(0, 0));
+  }
+
+  cloned.content.children.splice(breakIndex, 1);
+  cloned.updatedAt = context.timestamp;
+
+  return {
+    document: cloned,
+    selection: createSelectionSnapshot(0, 0),
+    changed: true,
+  };
+}
+
+// ---- Update section layout ----
+
+/**
+ * Apply a bounded layout patch to the section containing the current selection.
+ * Supports: page size, margins, gutter, orientation, columns,
+ * first-page / odd-even variants, page-numbering restart / format.
+ */
+export function updateSectionLayout(
+  document: CanonicalDocumentEnvelope,
+  snapshot: RuntimeRenderSnapshot,
+  patch: SectionLayoutPatch,
+  _context: SectionLayoutCommandContext,
+): SectionLayoutMutationResult {
+  const cloned = structuredClone(document) as CanonicalDocumentEnvelope;
+  const surface = snapshot.surface;
+
+  if (!surface) {
+    return noopResult(document, snapshot.selection);
+  }
+
+  const position = snapshot.selection.head;
+  const sectionTarget = resolveSectionTarget(cloned, surface.blocks, position);
+
+  if (!sectionTarget) {
+    return noopResult(document, snapshot.selection);
+  }
+
+  const existing = sectionTarget.properties ?? {};
+  const updated = applySectionLayoutPatch(existing, patch);
+
+  if (sectionTarget.kind === "inline") {
+    const breakNode = cloned.content.children[sectionTarget.blockIndex];
+    if (breakNode && breakNode.type === "section_break") {
+      breakNode.sectionProperties = updated;
+      // Clear raw XML so the structured properties are used on export
+      delete breakNode.sectionPropertiesXml;
+      delete breakNode.propertiesXml;
+    }
+  } else {
+    // Final section: update subParts.finalSectionProperties
+    if (!cloned.subParts) {
+      return noopResult(document, snapshot.selection);
+    }
+    cloned.subParts.finalSectionProperties = updated;
+  }
+
+  cloned.updatedAt = _context.timestamp;
+
+  return {
+    document: cloned,
+    selection: snapshot.selection,
+    changed: true,
+  };
+}
+
+export function updateSectionLayoutAtSectionIndex(
+  document: CanonicalDocumentEnvelope,
+  sectionIndex: number,
+  patch: SectionLayoutPatch,
+  context: SectionLayoutCommandContext,
+): SectionLayoutMutationResult {
+  const cloned = structuredClone(document) as CanonicalDocumentEnvelope;
+  const target = resolveSectionPropertiesOwner(cloned, sectionIndex);
+  if (!target) {
+    return noopResult(document, createSelectionSnapshot(0, 0));
+  }
+
+  const updated = applySectionLayoutPatch(target.properties ?? {}, patch);
+  if (target.kind === "inline") {
+    const breakNode = cloned.content.children[target.blockIndex];
+    if (breakNode && breakNode.type === "section_break") {
+      breakNode.sectionProperties = updated;
+      delete breakNode.sectionPropertiesXml;
+      delete breakNode.propertiesXml;
+    }
+  } else {
+    cloned.subParts = {
+      ...(cloned.subParts ?? {
+        headers: [],
+        footers: [],
+      }),
+      finalSectionProperties: updated,
+    };
+  }
+
+  cloned.updatedAt = context.timestamp;
+  return {
+    document: cloned,
+    selection: createSelectionSnapshot(0, 0),
+    changed: true,
+  };
+}
+
+export function setSectionPageNumberingAtSectionIndex(
+  document: CanonicalDocumentEnvelope,
+  sectionIndex: number,
+  pageNumbering: Partial<PageNumbering> | null,
+  context: SectionLayoutCommandContext,
+): SectionLayoutMutationResult {
+  const cloned = structuredClone(document) as CanonicalDocumentEnvelope;
+  const target = resolveSectionPropertiesOwner(cloned, sectionIndex);
+  if (!target) {
+    return noopResult(document, createSelectionSnapshot(0, 0));
+  }
+
+  const nextProperties = cloneSectionProperties(target.properties);
+  if (pageNumbering === null) {
+    delete nextProperties.pageNumbering;
+  } else {
+    nextProperties.pageNumbering = {
+      ...(target.properties?.pageNumbering ?? {}),
+      ...pageNumbering,
+    };
+  }
+
+  if (target.kind === "inline") {
+    const breakNode = cloned.content.children[target.blockIndex];
+    if (breakNode && breakNode.type === "section_break") {
+      breakNode.sectionProperties = nextProperties;
+      delete breakNode.sectionPropertiesXml;
+      delete breakNode.propertiesXml;
+    }
+  } else {
+    cloned.subParts = {
+      ...(cloned.subParts ?? {
+        headers: [],
+        footers: [],
+      }),
+      finalSectionProperties: nextProperties,
+    };
+  }
+
+  cloned.updatedAt = context.timestamp;
+  return {
+    document: cloned,
+    selection: createSelectionSnapshot(0, 0),
+    changed: true,
+  };
+}
+
+export function setHeaderFooterLinkAtSectionIndex(
+  document: CanonicalDocumentEnvelope,
+  sectionIndex: number,
+  patch: SectionLinkPatch,
+  context: SectionLayoutCommandContext,
+): SectionLayoutMutationResult {
+  const cloned = structuredClone(document) as CanonicalDocumentEnvelope;
+  const target = resolveSectionPropertiesOwner(cloned, sectionIndex);
+  if (!target) {
+    return noopResult(document, createSelectionSnapshot(0, 0));
+  }
+
+  const referencesKey =
+    patch.kind === "header" ? "headerReferences" : "footerReferences";
+  const currentProperties = cloneSectionProperties(target.properties);
+  const currentReferences = [...(currentProperties?.[referencesKey] ?? [])];
+  const nextReferences = currentReferences.filter((entry) => entry.variant !== patch.variant);
+
+  if (!patch.linkToPrevious) {
+    const relationshipId =
+      normalizeRelationshipId(patch.relationshipId) ??
+      resolveInheritedRelationshipId(cloned, sectionIndex, patch.kind, patch.variant);
+    if (!relationshipId) {
+      return noopResult(document, createSelectionSnapshot(0, 0));
+    }
+
+    nextReferences.push({
+      variant: patch.variant,
+      relationshipId,
+    });
+  }
+
+  const nextProperties = {
+    ...(currentProperties ?? {}),
+    [referencesKey]: nextReferences.length > 0 ? nextReferences : undefined,
+  };
+
+  if (target.kind === "inline") {
+    const breakNode = cloned.content.children[target.blockIndex];
+    if (breakNode && breakNode.type === "section_break") {
+      breakNode.sectionProperties = nextProperties;
+      delete breakNode.sectionPropertiesXml;
+      delete breakNode.propertiesXml;
+    }
+  } else {
+    cloned.subParts = {
+      ...(cloned.subParts ?? {
+        headers: [],
+        footers: [],
+      }),
+      finalSectionProperties: nextProperties,
+    };
+  }
+
+  cloned.updatedAt = context.timestamp;
+  return {
+    document: cloned,
+    selection: createSelectionSnapshot(0, 0),
+    changed: true,
+  };
+}
+
+// ---- Helpers ----
+
+function noopResult(
+  document: CanonicalDocumentEnvelope,
+  selection: SelectionSnapshot,
+): SectionLayoutMutationResult {
+  return { document, selection, changed: false };
+}
+
+function createSelectionSnapshot(anchor: number, head: number): SelectionSnapshot {
+  return {
+    anchor,
+    head,
+    isCollapsed: anchor === head,
+    activeRange: {
+      kind: "range",
+      from: Math.min(anchor, head),
+      to: Math.max(anchor, head),
+      assoc: {
+        start: -1,
+        end: 1,
+      },
+    },
+  };
+}
+
+function resolveBlockIndexForPosition(
+  blocks: ReadonlyArray<{ from: number; to: number }>,
+  position: number,
+): number {
+  for (let i = blocks.length - 1; i >= 0; i--) {
+    const block = blocks[i];
+    if (block && position >= block.from) {
+      return i;
+    }
+  }
+  return blocks.length > 0 ? 0 : -1;
+}
+
+interface SectionTarget {
+  kind: "inline" | "final";
+  blockIndex: number;
+  properties?: SectionProperties;
+}
+
+function findSectionBreakNodeIndexForSection(
+  document: CanonicalDocumentEnvelope,
+  sectionIndex: number,
+): number {
+  if (sectionIndex <= 0) {
+    return -1;
+  }
+
+  let currentSection = 0;
+  for (let index = 0; index < document.content.children.length; index += 1) {
+    const block = document.content.children[index];
+    if (block?.type !== "section_break") {
+      continue;
+    }
+    currentSection += 1;
+    if (currentSection === sectionIndex) {
+      return index;
+    }
+  }
+
+  return -1;
+}
+
+function findSectionInsertionIndex(
+  document: CanonicalDocumentEnvelope,
+  sectionIndex: number,
+): number {
+  let currentSection = 0;
+  for (let index = 0; index < document.content.children.length; index += 1) {
+    const block = document.content.children[index];
+    if (block?.type !== "section_break") {
+      continue;
+    }
+    if (currentSection === sectionIndex) {
+      return index;
+    }
+    currentSection += 1;
+  }
+
+  return sectionIndex === currentSection ? document.content.children.length : -1;
+}
+
+function getSectionPropertiesAtIndex(
+  document: CanonicalDocumentEnvelope,
+  sectionIndex: number,
+): SectionProperties | undefined {
+  const target = resolveSectionPropertiesOwner(document, sectionIndex);
+  return target?.properties;
+}
+
+function resolveSectionPropertiesOwner(
+  document: CanonicalDocumentEnvelope,
+  sectionIndex: number,
+): SectionTarget | null {
+  if (sectionIndex < 0) {
+    return null;
+  }
+
+  let currentSection = 0;
+  for (let index = 0; index < document.content.children.length; index += 1) {
+    const block = document.content.children[index];
+    if (block?.type !== "section_break") {
+      continue;
+    }
+    if (currentSection === sectionIndex) {
+      return {
+        kind: "inline",
+        blockIndex: index,
+        properties: block.sectionProperties,
+      };
+    }
+    currentSection += 1;
+  }
+
+  return currentSection === sectionIndex
+    ? {
+        kind: "final",
+        blockIndex: document.content.children.length - 1,
+        properties: document.subParts?.finalSectionProperties,
+      }
+    : null;
+}
+
+function normalizeRelationshipId(value: string | null | undefined): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function resolveInheritedRelationshipId(
+  document: CanonicalDocumentEnvelope,
+  sectionIndex: number,
+  kind: "header" | "footer",
+  variant: "default" | "first" | "even",
+): string | undefined {
+  for (let candidateIndex = sectionIndex - 1; candidateIndex >= 0; candidateIndex -= 1) {
+    const properties = getSectionPropertiesAtIndex(document, candidateIndex);
+    const references =
+      kind === "header" ? properties?.headerReferences : properties?.footerReferences;
+    const directMatch = references?.find((entry) => entry.variant === variant);
+    if (directMatch?.relationshipId) {
+      return directMatch.relationshipId;
+    }
+  }
+
+  const documents = kind === "header"
+    ? document.subParts?.headers ?? []
+    : document.subParts?.footers ?? [];
+  return documents.find((entry) => entry.variant === variant)?.relationshipId;
+}
+
+function resolveSectionTarget(
+  document: CanonicalDocumentEnvelope,
+  blocks: ReadonlyArray<{ from: number; to: number }>,
+  position: number,
+): SectionTarget | null {
+  const blockIndex = resolveBlockIndexForPosition(blocks, position);
+  if (blockIndex < 0) {
+    return null;
+  }
+
+  // Walk forward from the resolved block to find the next section break
+  for (let i = blockIndex; i < document.content.children.length; i++) {
+    const block = document.content.children[i];
+    if (block && block.type === "section_break") {
+      return {
+        kind: "inline",
+        blockIndex: i,
+        properties: block.sectionProperties,
+      };
+    }
+  }
+
+  // No section break found; this is the final section
+  return {
+    kind: "final",
+    blockIndex: document.content.children.length - 1,
+    properties: document.subParts?.finalSectionProperties,
+  };
+}
+
+function findNearestSectionBreak(
+  document: CanonicalDocumentEnvelope,
+  snapshot: RuntimeRenderSnapshot,
+): number {
+  const surface = snapshot.surface;
+  if (!surface) {
+    return -1;
+  }
+
+  const position = snapshot.selection.head;
+  let bestIndex = -1;
+  let bestDistance = Number.POSITIVE_INFINITY;
+
+  for (let i = 0; i < document.content.children.length; i++) {
+    const block = document.content.children[i];
+    if (!block || block.type !== "section_break") {
+      continue;
+    }
+    const surfaceBlock = surface.blocks[i];
+    if (!surfaceBlock) {
+      continue;
+    }
+    const distance = Math.min(
+      Math.abs(position - surfaceBlock.from),
+      Math.abs(position - surfaceBlock.to),
+    );
+    if (distance < bestDistance) {
+      bestDistance = distance;
+      bestIndex = i;
+    }
+  }
+
+  return bestIndex;
+}
+
+function applySectionLayoutPatch(
+  existing: SectionProperties,
+  patch: SectionLayoutPatch,
+): SectionProperties {
+  const result: SectionProperties = { ...existing };
+
+  if (patch.pageSize) {
+    result.pageSize = {
+      ...(existing.pageSize ?? { width: 12240, height: 15840 }),
+      ...patch.pageSize,
+    };
+  }
+
+  if (patch.pageMargins) {
+    result.pageMargins = {
+      ...(existing.pageMargins ?? {
+        top: 1440,
+        right: 1440,
+        bottom: 1440,
+        left: 1440,
+      }),
+      ...patch.pageMargins,
+    };
+  }
+
+  if (patch.columns) {
+    result.columns = {
+      ...(existing.columns ?? {}),
+      ...patch.columns,
+    };
+  }
+
+  if (patch.pageNumbering) {
+    result.pageNumbering = {
+      ...(existing.pageNumbering ?? {}),
+      ...patch.pageNumbering,
+    };
+  }
+
+  if (patch.titlePage !== undefined) {
+    result.titlePage = patch.titlePage;
+  }
+
+  if (patch.sectionType !== undefined) {
+    result.sectionType = patch.sectionType;
+  }
+
+  return result;
+}
+
+function cloneSectionProperties(
+  properties: SectionProperties | undefined,
+): SectionProperties {
+  return properties ? structuredClone(properties) : {};
+}