open-agreements
Version:
Open-source legal template filling CLI and library
148 lines • 6.05 kB
TypeScript
/**
* State for allocating monotonically increasing revision IDs.
*
* `moveRangeIds` exists so comparison-time emitters can reserve paired source
* and destination IDs for move ranges while sharing the same counter.
*/
export interface RevisionIdState {
nextId: number;
moveRangeIds: Map<string, {
sourceRangeId: number;
destRangeId: number;
}>;
}
/**
* Create a revision ID allocator.
*
* @param startId - First ID to allocate. Defaults to `1`.
*/
export declare function createRevisionIdState(startId?: number): RevisionIdState;
/**
* Allocate the next revision ID from a shared state object.
*/
export declare function allocateRevisionId(state: RevisionIdState): number;
/**
* Serialized metadata shared by tracked-change emitters.
*/
export interface RevisionContext {
author: string;
date: string;
idState: RevisionIdState;
}
/**
* Options for constructing a revision context.
*/
export interface RevisionContextOptions {
author: string;
date?: Date | string;
idState?: RevisionIdState;
}
/**
* Format a revision timestamp as OOXML-friendly ISO 8601.
*/
export declare function formatDate(date: Date): string;
/**
* Escape XML attribute text used in serialized revision markup.
*/
export declare function escapeXmlAttr(text: string): string;
/**
* Create a reusable revision context for tracked-change emission.
*/
export declare function createRevisionContext(options: RevisionContextOptions): RevisionContext;
/**
* Create a fresh tracked-change container (`<w:ins>` or `<w:del>`) into which
* the caller appends owned child nodes.
*
* Use this when wrapping multiple sibling elements under one revision marker.
* For single-element wrapping, prefer `wrapElementWithIns` / `wrapElementWithDel`.
*/
export declare function createRevisionContainer(doc: Document, kind: 'ins' | 'del', ctx: RevisionContext): Element;
/**
* Rewrite `<w:t>` → `<w:delText>` and `<w:instrText>` → `<w:delInstrText>`
* on the given element and all its descendants, for use inside a `<w:del>`
* container.
*
* **CALLERS MUST USE THE RETURN VALUE.** When the input element itself is a
* root `<w:t>` or `<w:instrText>`, this helper creates a renamed replacement
* node (you cannot rename a DOM element in place); the input element is
* detached from the tree and the new node is returned. Pattern:
*
* const ready = prepareElementForDeletion(detachedElement);
* wrapper.appendChild(ready);
*
* The element MUST already be detached from any parent. Calling on an
* attached element will leave the original tree in an inconsistent state.
*/
export declare function prepareElementForDeletion(element: Element): Element;
/**
* Wrap an xmldom element in `<w:ins>`.
*
* The source element is cloned; the original DOM node is left untouched.
*/
export declare function wrapElementWithIns(element: Element, ctx: RevisionContext): Element;
/**
* Wrap an xmldom element in `<w:del>`.
*
* Any descendant `<w:t>` and `<w:instrText>` nodes are converted to the OOXML
* deletion equivalents before the cloned element is appended.
*/
export declare function wrapElementWithDel(element: Element, ctx: RevisionContext): Element;
/**
* Build a `<w:pPrChange>` wrapper containing the previous paragraph properties.
*
* The nested snapshot excludes children that are not valid in `CT_PPrBase`.
*/
export declare function buildPPrChangeElement(oldPPr: Element | null, ctx: RevisionContext): Element;
/**
* Build a `<w:trPrChange>` wrapper containing the previous row properties.
*
* The nested snapshot excludes children that are not valid in `CT_TrPrBase`.
*/
export declare function buildTrPrChangeElement(oldTrPr: Element | null, ctx: RevisionContext): Element;
/**
* Build a `<w:tcPrChange>` wrapper containing the previous cell properties.
*
* The nested snapshot excludes children that are not valid in `CT_TcPrBase`.
*/
export declare function buildTcPrChangeElement(oldTcPr: Element | null, ctx: RevisionContext): Element;
/**
* Build a `<w:rPrChange>` wrapper containing the previous run properties.
*
* The nested snapshot excludes any existing `w:rPrChange` child. This filtering
* is intentional: OOXML does not permit recursively nested `w:rPrChange` (a
* change-of-a-change is undefined), so the helper drops it. Note this is a
* stricter contract than the legacy reconstructor's per-child loop, which
* would have passed a nested `w:rPrChange` through verbatim. The reconstructor
* still uses its own per-child path; this helper is for new primitive code
* (#136 onward).
*/
export declare function buildRPrChangeElement(oldRPr: Element | null, ctx: RevisionContext): Element;
/**
* Wrap serialized OOXML content in a `<w:ins>` element.
*
* This keeps the reconstructor on its string-based emission path while sharing
* revision metadata handling with the DOM-aware helpers above.
*/
export declare function wrapSerializedContentWithIns(content: string, ctx: RevisionContext): string;
/**
* Wrap serialized OOXML content in a `<w:del>` element.
*
* Visible text nodes are rewritten to their deletion-tag equivalents before
* the wrapper is serialized.
*/
export declare function wrapSerializedContentWithDel(content: string, ctx: RevisionContext): string;
/**
* Convert serialized run content from insertion-style text tags to deletion
* equivalents (`w:t` -> `w:delText`, `w:instrText` -> `w:delInstrText`).
*
* The fragment is parsed into a DOM and renamed via the same traversal as
* `prepareElementForDeletion`, so attribute order is preserved and shapes a
* regex sweep mishandles (self-closing `<w:t/>`, attribute values containing
* `>`) convert correctly. Namespace prefixes the fragment uses without an
* inline declaration are bound on a temporary wrapper root that is stripped
* from the returned serialization.
*
* @see https://github.com/UseJunior/safe-docx/issues/102
*/
export declare function convertSerializedDeletionContent(content: string): string;
//# sourceMappingURL=track-changes-emitter.d.ts.map