open-agreements
Version:
Open-source legal template filling CLI and library
198 lines • 8.53 kB
TypeScript
/**
* In-Place AST Modifier
*
* Modifies the revised document's AST in-place to add track changes markup.
* This replaces the reconstruction-based approach with direct tree manipulation.
*/
import type { ComparisonUnitAtom } from '../../core-types.js';
import { type RevisionIdState } from './inPlaceModifier-shared.js';
export type TrackChangeTag = 'w:ins' | 'w:del' | 'w:moveFrom' | 'w:moveTo';
export declare const TRACK_CHANGE_WRAPPERS: Set<TrackChangeTag>;
export type AtomRunBoundary = 'start' | 'end';
/**
* Resolve the run associated with an atom boundary.
*
* For collapsed field atoms, sourceRunElement points at the first run in the
* field sequence. For insertion-point tracking we often need the trailing run,
* otherwise deleted/moved fragments can be inserted inside the field sequence.
*/
export declare function getAtomRunAtBoundary(atom: ComparisonUnitAtom, boundary: AtomRunBoundary): Element | undefined;
/**
* Resolve all run elements represented by an atom.
*
* For collapsed-field atoms, we must treat the entire field run sequence as a
* single logical unit. Wrapping only the first run leaves trailing field-code
* runs untracked, which can leak revised field text after Reject All.
*/
export declare function getAtomRuns(atom: ComparisonUnitAtom): Element[];
/**
* True iff `atom` represents a collapsed-field sequence (a complex field
* captured as a single logical atom). See {@link getAtomRuns} for the
* multi-run resolution.
*/
export declare function isCollapsedFieldAtom(atom: ComparisonUnitAtom): boolean;
/**
* Convert a run node to the correct insertion anchor.
*
* If the run is wrapped in a track-change container, the insertion anchor
* must be the wrapper (a paragraph child), not the nested run.
*/
export declare function getRunInsertionAnchor(run: Element): Element;
/**
* Options for wrapping a run with track change markup.
*/
export interface WrapRunOptions {
/** The run element to wrap */
run: Element;
/** The track change tag name */
tagName: TrackChangeTag;
/** Author name for track changes */
author: string;
/** Formatted date string */
dateStr: string;
/** Revision ID state */
state: RevisionIdState;
/** Whether to convert w:t to w:delText (for deleted/moveFrom content) */
convertTextToDelText?: boolean;
}
/**
* Wrap a run element with track change markup.
*
* This is the shared implementation for wrapAsInserted, wrapAsDeleted,
* and the inner wrapping logic of move operations.
*
* @param options - Wrapping options
* @returns true if wrapped, false if run was already wrapped or has no parent
*/
export declare function wrapRunWithTrackChange(options: WrapRunOptions): boolean;
/**
* Ensure w:pPr/w:rPr exists and add a paragraph-mark revision marker (w:ins/w:del)
* in the paragraph properties.
*
* This is the critical piece for whole-paragraph insert/delete idempotency:
* - Reject All should remove inserted paragraphs entirely (no stub breaks)
* - Accept All should remove deleted paragraphs entirely
*/
export declare function addParagraphMarkRevisionMarker(paragraph: Element, markerTag: 'w:ins' | 'w:del', author: string, dateStr: string, state: RevisionIdState): void;
/**
* Position a paragraph-mark revision marker in its schema-correct rPr slot.
*
* CT_ParaRPr ordering: the tracked-change group (w:ins, w:del, w:moveFrom,
* w:moveTo — in that order) comes before every formatting child (w:rStyle,
* w:rFonts, ...). So w:ins always goes first, and w:del goes right after a
* w:ins sibling when one exists, else first.
*/
export declare function placeParagraphMarkRevisionMarker(rPr: Element, marker: Element, markerTag: 'w:ins' | 'w:del'): void;
export declare function wrapAsInserted(run: Element, author: string, dateStr: string, state: RevisionIdState): boolean;
/**
* Wrap a run element with <w:del> to mark it as deleted.
* Also converts w:t to w:delText within the run.
*
* @param run - The w:r element to wrap
* @param author - Author name for track changes
* @param dateStr - Formatted date string
* @param state - Revision ID state
* @returns true if wrapped, false if run was already wrapped or has no parent
*/
export declare function wrapAsDeleted(run: Element, author: string, dateStr: string, state: RevisionIdState): boolean;
export type MoveDirection = 'from' | 'to';
/**
* Configuration for move wrapping based on direction.
*/
export interface MoveWrapConfig {
wrapperTag: 'w:moveFrom' | 'w:moveTo';
rangeStartTag: 'w:moveFromRangeStart' | 'w:moveToRangeStart';
rangeEndTag: 'w:moveFromRangeEnd' | 'w:moveToRangeEnd';
rangeIdKey: 'sourceRangeId' | 'destRangeId';
convertTextToDelText: boolean;
}
export declare const MOVE_CONFIG: Record<MoveDirection, MoveWrapConfig>;
/**
* Wrap a run element with move tracking (shared implementation for moveFrom/moveTo).
*
* @param run - The w:r element to wrap
* @param moveName - Name for linking source and destination
* @param direction - 'from' for moveFrom, 'to' for moveTo
* @param author - Author name
* @param dateStr - Formatted date
* @param state - Revision ID state
* @returns true if wrapped
*/
export declare function wrapAsMove(run: Element, moveName: string, direction: MoveDirection, author: string, dateStr: string, state: RevisionIdState): boolean;
/**
* Wrap a run element with <w:moveFrom> for moved-from content.
*
* @param run - The w:r element to wrap
* @param moveName - Name for linking source and destination
* @param author - Author name
* @param dateStr - Formatted date
* @param state - Revision ID state
* @returns true if wrapped
*/
export declare function wrapAsMoveFrom(run: Element, moveName: string, author: string, dateStr: string, state: RevisionIdState): boolean;
/**
* Wrap a run element with <w:moveTo> for moved-to content.
*
* @param run - The w:r element to wrap
* @param moveName - Name for linking source and destination
* @param author - Author name
* @param dateStr - Formatted date
* @param state - Revision ID state
* @returns true if wrapped
*/
export declare function wrapAsMoveTo(run: Element, moveName: string, author: string, dateStr: string, state: RevisionIdState): boolean;
/**
* Add format change tracking to a run's properties.
*
* @param run - The w:r element with changed formatting
* @param oldRunProperties - The original run properties (w:rPr)
* @param author - Author name
* @param dateStr - Formatted date
* @param state - Revision ID state
*/
export declare function addFormatChange(run: Element, oldRunProperties: Element | null, author: string, dateStr: string, state: RevisionIdState): void;
/**
* Add a paragraph property change element (w:pPrChange) to record the "before"
* state of paragraph properties. This is needed for Google Docs to display
* inserted paragraphs as tracked changes.
*
* The child `<w:pPr>` inside `w:pPrChange` must conform to CT_PPrBase — it
* MUST NOT contain w:rPr, w:sectPr, or w:pPrChange.
*
* @param paragraph - The w:p element
* @param author - Author name
* @param dateStr - Formatted date
* @param state - Revision ID state
*/
export declare function addParagraphPropertyChange(paragraph: Element, author: string, dateStr: string, state: RevisionIdState): void;
/**
* Tag names that represent visible content inside a w:r element.
* A run containing at least one of these is considered substantive (non-empty).
*/
export declare const RUN_VISIBLE_CONTENT_TAGS: ReadonlySet<string>;
/**
* Returns true if a w:r element contains at least one visible content child.
* Empty runs (containing only w:rPr or nothing) return false.
*/
export declare function runHasVisibleContent(run: Element): boolean;
/**
* Wrap an inserted empty paragraph with <w:ins>.
*
* For empty paragraphs (no content, only pPr), we wrap the entire paragraph.
*
* @param paragraph - The w:p element
* @param author - Author name
* @param dateStr - Formatted date
* @param state - Revision ID state
*/
export declare function wrapParagraphAsInserted(paragraph: Element, author: string, dateStr: string, state: RevisionIdState): boolean;
/**
* Wrap a deleted empty paragraph with <w:del>.
*
* @param paragraph - The w:p element
* @param author - Author name
* @param dateStr - Formatted date
* @param state - Revision ID state
*/
export declare function wrapParagraphAsDeleted(paragraph: Element, author: string, dateStr: string, state: RevisionIdState): boolean;
//# sourceMappingURL=inPlaceModifier-wrappers.d.ts.map