Types

interface TrackedChangeMetadata extends ChangeMetadata {
  id: string
  type: 'add' | 'delete' | 'replace' | 'markChange'
  userId: string | null
  createdAt: string | null
  updatedAt: string | null
  userMetadata: unknown
  markChanges?: TrackedChangeMarkMutation[]
}

interface TrackedChangeData {
  metadata: TrackedChangeMetadata
  range: Range
}

interface TrackedChangesDocumentFactoryResult {
  doc: JSONContent
  trackedChanges: TrackedChangeData[]
}

type JSONFragment = JSONContent[] | null

interface ChangesetJSON {
  fragmentA: JSONFragment
  fragmentB: JSONFragment
  changes: Change[]
}

/**
 * Arbitrary non-null metadata attached to a step.
 *
 * The metadata is treated as a shallow object when comparing adjacent steps.
 */
type ChangeMetadata = Record<string, unknown>

/**
 * Represents a single change between two documents.
 */
interface Change {
  /** The range in the original document (`docA`) that changed. */
  rangeA: Range
  /** The matching range in the changed document (`docB`). */
  rangeB: Range
  /** The content scope. Default: `'inline'`. */
  scope?: ChangeScope
  /** Whether multiple inline changes were grouped into one block-level change. */
  isInlineGroup?: boolean
  /** Metadata associated with the step that produced this change. */
  metadata?: ChangeMetadata
  /** Later changes contained inside this change. */
  nestedChanges?: NestedChange[]
}

type ChangeScope = 'inline' | 'block'

interface NestedChange {
  range: Range
  metadata: ChangeMetadata
  scope: ChangeScope
}

/** Options that control filtering and diff behavior. */
type DiffOptions = {
  /** Simplify nearby changes in inline mode. Default: `false`. */
  simplifyChanges?: boolean
  /** Attributes to remove before comparison. Default: `['id', 'data-thread-id', '_hash']`. */
  ignoreAttributes?: string[]
  /** Marks to remove before comparison. Default: `['inlineThread']`. */
  ignoreMarks?: string[]
  /** Node types to unwrap or remove before comparison. */
  ignoreNodes?: string[]
  /** Minimum unchanged range that separates changes. Default: `5`. */
  changeMergeDistance?: number | null
  /** Threshold for grouping inline changes into a block-level change in smart mode. Default: `2`. */
  groupInlineChanges?: number
  /** Comparison mode. Default: `'smart'`. */
  mode?: 'inline' | 'block' | 'smart'
  /** Node types whose full inline changes should become block changes. */
  expandBlockChanges?: string[]
}

/** A proposed change to a range of editor content. */
interface DiffSuggestion {
  /** A unique identifier for the suggestion. */
  id: string
  /** The range of editor content affected by the suggestion. */
  range: Range
  /** The replacement content. */
  content: Slice
  /** Optional custom metadata. */
  metadata?: Record<string, any>
  /** Options for rendering the suggestion. */
  displayOptions?: DisplayOptions
  /** Whether the suggestion groups multiple inline changes. */
  isInlineGroup?: boolean
  /** A range that can be mapped through document transactions. */
  mappableRange?: MappableRange
  /** Informational changes displayed inside this suggestion. */
  nestedChanges?: DiffSuggestionNestedChange[]
}

interface DiffSuggestionNestedChange extends NestedChange {
  mappableRange?: MappableRange
}

/** Options for how to display a diff suggestion in the editor. */
interface DisplayOptions {
  /** Whether to show replacement content. Default: `true`. */
  showReplacement?: boolean
  /** Whether to show sub-changes in inline groups. Default: `true`. */
  showSubChanges?: boolean
  /** Extra HTML attributes for the original-content decoration. */
  attributes?: Record<string, any>
  /** Extra HTML attributes for the replacement decoration. */
  replacementAttributes?: Record<string, any>
  /** Extra HTML attributes for inline sub-change decorations. */
  subChangeAttributes?: Record<string, any>
  /** Extra HTML attributes for sub-changes inside replacement content. */
  replacementSubChangeAttributes?: Record<string, any>
  /** Returns HTML attributes for an explicit nested change. */
  getNestedChangeAttributes?: (options: NestedChangeAttributesOptions) => Record<string, string>
  /** A function that renders the suggestion as ProseMirror decorations. */
  renderDecorations?: RenderDecorations
}

interface NestedChangeAttributesOptions {
  nestedChange: DiffSuggestionNestedChange
  suggestion: DiffSuggestion
  isSelected: boolean
}

/** Options passed to `defaultRenderDecorations`. */
interface DefaultRenderDecorationsOptions {
  /** Whether to render the main content and sub-change decorations. Default: `true`. */
  showMainDecorations?: boolean
  /** Whether to render replacement content. Default: `true`. */
  showReplacement?: boolean
  /** Whether to render sub-changes in inline groups. Default: `true`. */
  showSubChanges?: boolean
  /** Extra HTML attributes for the original-content decoration. */
  attributes?: Record<string, any>
  /** Extra HTML attributes for the replacement decoration. */
  replacementAttributes?: Record<string, any>
  /** Extra HTML attributes for inline sub-change decorations. */
  subChangeAttributes?: Record<string, any>
  /** Extra HTML attributes for sub-changes inside replacement content. */
  replacementSubChangeAttributes?: Record<string, any>
}

/** Values passed to a custom diff-suggestion renderer. */
interface RenderDecorationsOptions {
  /** The range occupied by the suggestion. */
  range: Range
  /** Whether the suggestion is selected. */
  isSelected: boolean
  /** The suggestion being rendered. */
  suggestion: DiffSuggestion
  /** Renders the default decorations, optionally with overridden options. */
  defaultRenderDecorations: (options?: DefaultRenderDecorationsOptions) => Decoration[]
}

/** A function that renders a suggestion as ProseMirror decorations. */
type RenderDecorations = (options: RenderDecorationsOptions) => Decoration[]

/** One document transition in a step sequence. */
interface Step {
  /** Document state before the step was applied. */
  before: Node
  /** Document state after the step was applied. */
  after: Node
  /** Metadata associated with the step. */
  metadata: ChangeMetadata
  /** Cached changes, or `null` when they need to be computed. */
  changes: Change[] | null
  /** Cached affected area, or `null` when unavailable. */
  changedArea: Change | null
}

/** JSON-serializable state for a step sequence. */
type StepSequenceJSON = {
  /** Document state before any steps were applied. */
  before: ReturnType<Node['toJSON']>
  /** Document states after each recorded step. */
  docs: Array<ReturnType<Node['toJSON']>>
  /** Metadata for each recorded step. */
  metadata: ChangeMetadata[]
  /** Cached changes for each recorded step. */
  changes: Array<Change[] | null>
  /** Cached affected areas for each recorded step. */
  changedAreas: Array<Change | null>
}