@atlaskit/editor-plugin-show-diff/dist/types/showDiffPluginType.d.ts

ShowDiff plugin for @atlaskit/editor-core

import type { StepJson } from '@atlaskit/editor-common/collab';
import type { NextEditorPlugin, EditorCommand, OptionalPlugin } from '@atlaskit/editor-common/types';
import type { JSONDocNode } from '@atlaskit/editor-json-transformer/types';
import type { AnalyticsPlugin } from '@atlaskit/editor-plugin-analytics';
import type { UserIntentPlugin } from '@atlaskit/editor-plugin-user-intent';
import type { Node } from '@atlaskit/editor-prosemirror/model';
import type { Step } from '@atlaskit/editor-prosemirror/transform-override';
import type { SmartDiffThresholds as SmartDiffThresholdsInternal } from './pm-plugins/calculateDiff/smart/thresholds';
export type ColorScheme = 'standard' | 'traditional';
export type DiffType = 'inline' | 'block' | 'step' | 'smart';
/**
 * Where node/paragraph-level deleted content is rendered relative to the new (replacement)
 * content in the `smart` diffType:
 * - `'top'` (default): the deleted content is anchored above the new content.
 * - `'bottom'`: the deleted content is anchored below the new content.
 */
export type DeletedDiffPlacement = 'top' | 'bottom';
/**
 * Where inline-level (and sentence-level) deleted content is rendered relative to the new
 * (replacement) content in the `smart` diffType. This is independent of the node/paragraph-level
 * `deletedDiffPlacement` option:
 * - `'before'` (default): the deleted content is anchored before the new content.
 * - `'after'`: the deleted content is anchored after the new content.
 */
export type InlineDeletedDiffPlacement = 'before' | 'after';
/**
 * A rendered deleted-content widget: the DOM element show-diff renders for a piece of deleted
 * content, together with the document position it is anchored at. Deleted content is rendered as
 * widget decorations rather than document nodes, so this is how consumers recover the element and
 * its position — via the `getDeletedWidgets` action — without reaching into the plugin's internal
 * state.
 */
export type DeletedDiffWidget = {
    element: HTMLElement;
    position: number;
};
export type SmartDiffThresholds = SmartDiffThresholdsInternal;
export type DiffDescriptor = {
    id: string;
    type: 'inline' | 'block' | 'widget';
};
export type DiffParams = {
    /**
     * Color scheme to use for displaying diffs.
     * 'standard' (default) uses purple for highlighting changes
     * 'traditional' uses green for additions and red for deletions
     */
    colorScheme?: ColorScheme;
    originalDoc: JSONDocNode;
    /**
     * Prosemirror steps. This is used to calculate and show the diff in the editor
     */
    steps: StepJson[];
};
export type PMDiffParams = {
    /**
     * For the `smart` diffType, where node/paragraph-level deleted content is rendered relative to
     * the new content. Defaults to `'top'`. Ignored for other diff types.
     */
    deletedDiffPlacement?: DeletedDiffPlacement;
    diffType?: DiffType;
    /**
     * When true, removes only the dark-purple underline (`border-bottom`) from added/updated
     * (inserted) diff content, keeping the purple background highlight and all other styling.
     * Only affects the extended (`smart`) styles. Defaults to `false`, and is a no-op unless the
     * relevant gate is enabled.
     */
    hideAddedDiffsUnderline?: boolean;
    hideDeletedDiffs?: boolean;
    /**
     * For the `smart` diffType, where inline-level (and sentence-level) deleted content is rendered
     * relative to the new content. Defaults to `'before'`. Independent of `deletedDiffPlacement`
     * (which controls node/paragraph-level placement). Ignored for other diff types, and a no-op
     * unless the relevant gate is enabled.
     */
    inlineDeletedDiffPlacement?: InlineDeletedDiffPlacement;
    isInverted?: boolean;
    originalDoc: Node;
    /**
     * When true, the editor will scroll to bring the first diff decoration into view
     * after the diff is shown.
     */
    scrollIntoView?: boolean;
    /**
     * Whether to show indicators at the doc margin for the diffs.
     */
    showIndicators?: boolean;
    /**
     * Optional overrides for the `smart` diffType density thresholds. Ignored for other
     * diff types. Partial — omitted fields fall back to defaults.
     */
    smartThresholds?: Partial<SmartDiffThresholds>;
    /**
     * Prosemirror steps. This is used to calculate and show the diff in the editor
     */
    steps: Step[];
};
export type ACTION = 'SHOW_DIFF' | 'HIDE_DIFF' | 'SCROLL_TO_NEXT' | 'SCROLL_TO_PREVIOUS';
export type ShowDiffPlugin = NextEditorPlugin<'showDiff', {
    actions: {
        /**
         * The rendered deleted-content widgets currently displayed, optionally restricted to a
         * document range, ordered by position. This is the safe, read-only way to recover deleted
         * content's element and position (e.g. to position UI relative to it) without access to the
         * plugin's internal decoration set. Returns an empty array when no diff is displayed.
         */
        getDeletedWidgets: (range?: {
            from: number;
            to: number;
        }) => DeletedDiffWidget[];
    };
    commands: {
        hideDiff: EditorCommand;
        scrollToNext: EditorCommand;
        scrollToPrevious: EditorCommand;
        showDiff: (config: PMDiffParams) => EditorCommand;
    };
    dependencies: [OptionalPlugin<AnalyticsPlugin>, OptionalPlugin<UserIntentPlugin>];
    pluginConfiguration: DiffParams | undefined;
    sharedState: {
        /**
         * The index of the current diff being viewed.
         */
        activeIndex?: number;
        /**
         * The diff descriptors of the diff decorations currently being displayed.
         * Only set when `platform_editor_diff_plugin_extended` is on.
         */
        diffDescriptors?: DiffDescriptor[];
        /**
         * Whether the show diff feature is currently displaying changes.
         * Defaults to false.
         */
        isDisplayingChanges: boolean;
        /**
         * The number of changes being displayed
         */
        numberOfChanges?: number;
        /**
         * Whether to show indicators at the doc margin for the diffs.
         */
        showIndicators?: boolean;
    };
}>;