Clipboard

Module Extensions

ClipboardConfig (Extended from @revolist/revogrid)

interface ClipboardConfig {
  /** Additional rich clipboard formats used by ClipboardPlugin. */
      formats?: readonly ClipboardFormatHandler[];
  /** Maximum decoded cells. Defaults to 1,000,000. */
      maxCells?: number;
  /** Maximum bytes inspected in one text representation. Defaults to 16 MiB. */
      maxBytes?: number
}

---

HTMLRevoGridElementEventMap (Extended from global)

interface HTMLRevoGridElementEventMap {
  clipboardformaterror: ClipboardFormatDiagnostic
}

Plugin API

ClipboardPlugin

Browser-rich, Excel-compatible clipboard orchestration for RevoGrid Pro.

Dependencies

• Optional DataGridFormattingPlugin: Uses DataGridFormattingPlugin when available to import and apply rich formatting.

class ClipboardPlugin {
  registerFormat(handler: ClipboardFormatHandler): () => void;

  registerMetadataContributor(contributor: ClipboardMetadataContributor): () => void;
}

---

matrixToClipboardDocument

Converts a value matrix into one dense clipboard-document range.

export function matrixToClipboardDocument(
  matrix: readonly (readonly DataFormat[])[],
  source = 'revogrid',
): ClipboardDocument;

---

clipboardDocumentToMatrix

Materializes positioned clipboard ranges as one dense value matrix.

export function clipboardDocumentToMatrix(document: ClipboardDocument): DataFormat[][];

---

countClipboardCells

Counts the rectangular cell capacity declared by a clipboard document.

export function countClipboardCells(document: ClipboardDocument);

---

isClipboardDocument

Validates the supported clipboard document wire shape.

export function isClipboardDocument(value: unknown): value is ClipboardDocument;

---

createExcelHtmlClipboardFormat

export function createExcelHtmlClipboardFormat(
  formatting?: ClipboardExcelFormattingAdapter,
): ClipboardFormatHandler;

---

createGenericHtmlClipboardFormat

export function createGenericHtmlClipboardFormat(
  formatting?: ClipboardExcelFormattingAdapter,
): ClipboardFormatHandler;

---

extractCfHtml

export function extractCfHtml(value: string): string;

---

parseHtmlClipboard

export function parseHtmlClipboard(
  raw: string,
  options: {
    source: string;
    maxBytes: number;
    maxCells: number;
    formatting?: ClipboardExcelFormattingAdapter;
  },
): ClipboardDocument | null;

---

serializeExcelHtml

export function serializeExcelHtml(
  document: ClipboardDocument,
  formatting?: ClipboardExcelFormattingAdapter,
): string;

---

ClipboardExcelFormattingAdapter

interface ClipboardExcelFormattingAdapter {
  importFormat(declarations: readonly string[]): ClipboardCell['format'];
  importValue(displayText: string, format?: ClipboardCell['format']): unknown;
  exportFormat(format: NonNullable<ClipboardCell['format']>): string | undefined;
  exportValue(
      value: unknown,
      format: NonNullable<ClipboardCell['format']>,
    ): { readonly value: unknown; readonly displayText: string }
}

---

excelHtmlClipboardFormat

Value-only default. ClipboardPlugin supplies the formatting runtime adapter.

excelHtmlClipboardFormat: ClipboardFormatHandler<any>;

---

genericHtmlClipboardFormat

Value-only default. ClipboardPlugin supplies the formatting runtime adapter.

genericHtmlClipboardFormat: ClipboardFormatHandler<any>;

---

parseDelimitedText

export function parseDelimitedText(value: string, delimiter: string): string[][];

---

serializeDelimitedText

export function serializeDelimitedText(
  matrix: readonly (readonly unknown[])[],
  delimiter: string,
): string;

---

plainTextClipboardFormat

plainTextClipboardFormat: {
  id: string;
  mimeTypes: string[];
  priority: number;
  read: ({ transfer, maxBytes, maxCells }: ClipboardFormatReadContext) => ClipboardDocument<any>;
  write: ({ document }: ClipboardFormatWriteContext<any>) => { type: string; data: string; }[];
};

---

ClipboardFormatRegistry

class ClipboardFormatRegistry {
  register(handler: ClipboardFormatHandler): () => void;

  read(transfer: ClipboardDataReader, limits: { maxCells: number; maxBytes: number });

  write(document: ClipboardDocument, transfer: ClipboardDataWriter): void;
}

---

resolveClipboardPluginConfig

Resolves clipboard limits and custom formats from the grid configuration.

export function resolveClipboardPluginConfig(
  useClipboard: boolean | ClipboardConfig | undefined,
): ResolvedClipboardPluginConfig;

---

REVOGRID_CLIPBOARD_MIME

REVOGRID_CLIPBOARD_MIME: string;

---

REVOGRID_CLIPBOARD_VERSION

REVOGRID_CLIPBOARD_VERSION: 2;

---

ClipboardCell

interface ClipboardCell {
  readonly value: T;
  readonly displayText?: string;
  readonly formula?: string;
  /** `null` explicitly copies an ordinary RevoGrid cell with no effective format. */
    readonly format?: DataGridCellFormat | null;
  readonly metadata?: Readonly<Record<string, unknown>>
}

---

ClipboardRange

interface ClipboardRange {
  readonly row: number;
  readonly col: number;
  readonly width: number;
  readonly height: number;
  readonly cells: readonly ClipboardCell<T>[];
  readonly merges?: readonly MergeData[];
  readonly columnWidths?: readonly (number | undefined)[];
  readonly rowHeights?: readonly (number | undefined)[];
  readonly rowType?: DimensionRows;
  readonly colType?: DimensionCols;
  readonly metadata?: Readonly<Record<string, unknown>>
}

---

ClipboardDocument

interface ClipboardDocument {
  readonly version: typeof REVOGRID_CLIPBOARD_VERSION;
  readonly source: string;
  readonly ranges: readonly ClipboardRange<T>[];
  readonly metadata?: Readonly<Record<string, unknown>>
}

---

ClipboardDataReader

interface ClipboardDataReader {
  readonly types: readonly string[];
  getData(type: string): string
}

---

ClipboardDataWriter

interface ClipboardDataWriter {
  setData(type: string, value: string): void
}

---

ClipboardFormatReadContext

interface ClipboardFormatReadContext {
  readonly transfer: ClipboardDataReader;
  readonly maxCells: number;
  readonly maxBytes: number
}

---

ClipboardFormatWriteContext

interface ClipboardFormatWriteContext {
  readonly document: ClipboardDocument<T>
}

---

ClipboardRepresentation

interface ClipboardRepresentation {
  readonly type: string;
  readonly data: string
}

---

ClipboardFormatHandler

interface ClipboardFormatHandler {
  readonly id: string;
  readonly mimeTypes: readonly string[];
  readonly priority?: number;
  canRead?(context: ClipboardFormatReadContext): boolean;
  read(context: ClipboardFormatReadContext): ClipboardDocument<T> | null;
  write?(context: ClipboardFormatWriteContext<T>): readonly ClipboardRepresentation[]
}

---

ClipboardMetadataCaptureContext

interface ClipboardMetadataCaptureContext {
  readonly document: ClipboardDocument<T>;
  readonly providers: PluginProviders
}

---

ClipboardMetadataApplyContext

interface ClipboardMetadataApplyContext {
  readonly document: ClipboardDocument<T>;
  readonly providers: PluginProviders
}

---

ClipboardMetadataContributor

interface ClipboardMetadataContributor {
  readonly id: string;
  capture?(context: ClipboardMetadataCaptureContext<T>): unknown;
  apply?(metadata: unknown, context: ClipboardMetadataApplyContext<T>): void
}

---

ClipboardFormatDiagnostic

interface ClipboardFormatDiagnostic {
  readonly phase: 'read' | 'write' | 'metadata';
  readonly handlerId: string;
  readonly error: unknown
}

---

ClipboardPluginConfig

interface ClipboardPluginConfig {
  readonly formats?: readonly ClipboardFormatHandler[];
  readonly maxCells?: number;
  readonly maxBytes?: number
}

---

ResolvedClipboardPluginConfig

interface ResolvedClipboardPluginConfig {
  readonly formats: readonly ClipboardFormatHandler[];
  readonly maxCells: number;
  readonly maxBytes: number
}

---

captureClipboardSelection

Captures current grid selections as a rich clipboard document.

export function captureClipboardSelection(
  context: ClipboardCaptureContext,
  matrix?: DataFormat[][],
): ClipboardDocument | null;

---

getActiveClipboardSelection

Reads the active provider-backed selection as normalized clipboard coordinates.

export function getActiveClipboardSelection(
  providers: PluginProviders,
): ClipboardSelection[] | null;

---

getClipboardPasteStart

Returns the focused viewport cell used as the paste origin.

export function getClipboardPasteStart(
  providers: PluginProviders,
): ClipboardPasteStart | null;

---

getClipboardSelectionOffsets

Converts viewport selections into offsets from their shared whole-grid origin.

export function getClipboardSelectionOffsets(
  selections: readonly ClipboardSelection[],
  providers: PluginProviders,
);

---

createClipboardCoordinateResolver

Creates a cached coordinate resolver for one copy or paste operation.

export function createClipboardCoordinateResolver(
  providers: PluginProviders,
  start: ClipboardPasteStart,
): ClipboardCoordinateResolver;

---

forEachClipboardDocumentCell

Visits every valid cell stored in a clipboard document without an intermediate array.

export function forEachClipboardDocumentCell(
  document: ClipboardDocument,
  visit: (entry: ClipboardDocumentCell) => boolean | void,
): boolean;

---

getSingleClipboardDocumentCell

Returns the only stored document cell, or null when the count is not one.

export function getSingleClipboardDocumentCell(document: ClipboardDocument);

---

getClipboardRangeCellOffset

Resolves one row-major range cell into its document-relative offset.

export function getClipboardRangeCellOffset(
  range: ClipboardRange,
  index: number,
): ClipboardCellOffset | null;

---

getClipboardDocumentBounds

Computes clipboard-document bounds in one pass.

export function getClipboardDocumentBounds(document: ClipboardDocument);

---

getClipboardCellCount

Counts the rectangular capacity declared by all clipboard ranges.

export function getClipboardCellCount(document: ClipboardDocument);

---

getClipboardMatrixData

Flattens a matrix into a dense row-major clipboard range.

export function getClipboardMatrixData(
  matrix: readonly (readonly DataFormat[])[],
);

---

createClipboardMatrix

Builds a dense value matrix from positioned clipboard ranges.

export function createClipboardMatrix(document: ClipboardDocument): DataFormat[][];

---

getClipboardFormulaDestination

Resolves the absolute destination used to restore an Excel formula.

export function getClipboardFormulaDestination(
  resolver: ClipboardCoordinateResolver,
  range: ClipboardRange,
  cellIndex: number,
);

---

forEachClipboardRangeFillCell

Visits every projected destination for a one-cell range-fill paste.

export function forEachClipboardRangeFillCell(
  selection: ClipboardSelection,
  start: ClipboardPasteStart,
  cell: ClipboardCell,
  visit: (entry: ClipboardDocumentCell) => boolean | void,
): boolean;

---

clipboardOutcomeIncludesTarget

Checks whether a managed paste outcome includes one resolved target.

export function clipboardOutcomeIncludesTarget(
  detail: {
    type?: DimensionRows;
    data?: Record<number, Record<string, unknown>>;
  } | undefined,
  target: ClipboardResolvedPasteTarget,
);

---

createClipboardTargetMerge

Repositions clipboard merge metadata at a resolved viewport target.

export function createClipboardTargetMerge(
  merge: MergeData,
  target: ClipboardPasteStart,
): MergeData;

---

captureClipboardMerge

Converts an in-selection merge into clipboard-relative coordinates.

export function captureClipboardMerge(
  merge: MergeData,
  area: RangeArea,
  rowType: DimensionRows,
  colType: DimensionCols,
): MergeData | null;

---

getClipboardMergeOffsets

Returns the inclusive paste bounds of a clipboard merge.

export function getClipboardMergeOffsets(
  range: ClipboardRange,
  merge: MergeData,
);

---

forEachClipboardMergeCell

Visits every document-relative cell covered by a clipboard merge.

export function forEachClipboardMergeCell(
  range: ClipboardRange,
  merge: MergeData,
  visit: (offset: ClipboardCellOffset) => boolean | void,
): boolean;

---

clipboardMergesOverlap

Checks whether two same-viewport merge rectangles overlap.

export function clipboardMergesOverlap(left: MergeData, right: MergeData);

---

ClipboardPasteStart

export type ClipboardPasteStart = ViewportCellAddress;

---

ClipboardResolvedPasteTarget

export type ClipboardResolvedPasteTarget = ResolvedViewportCell;

---

ClipboardMetadataTargetFilter

export type ClipboardMetadataTargetFilter = (target: ClipboardResolvedPasteTarget) => boolean;

---

ClipboardSelection

interface ClipboardSelection {
  readonly rowType: DimensionRows;
  readonly colType: DimensionCols;
  readonly range: RangeArea
}

---

ClipboardCellOffset

interface ClipboardCellOffset {
  readonly rowOffset: number;
  readonly colOffset: number
}

---

ClipboardDocumentCell (Extended from coordinates.ts)

interface ClipboardDocumentCell {
  readonly cell: ClipboardCell
}

---

ClipboardCoordinateResolver

Resolves clipboard offsets through one cached provider-coordinate snapshot.

interface ClipboardCoordinateResolver {
  /** Converts a document offset into a whole-grid row and column. */
    getAbsoluteCell(offset: ClipboardCellOffset): { readonly row: number; readonly column: number };
  /** Reads cached source and item mappings for one viewport pair. */
    getViewportSources(rowType: DimensionRows, colType: DimensionCols): ClipboardViewportSources | null;
  /** Resolves a document offset to its model-backed grid cell. */
    resolveTarget(offset: ClipboardCellOffset): ClipboardResolvedPasteTarget | null;
  /** Resolves a document offset to its viewport-local address. */
    resolveTargetAddress(offset: ClipboardCellOffset): ClipboardPasteStart | null;
  /** Converts a resolved cell from visible indexes to physical source indexes. */
    getPhysicalCellAddress(target: ClipboardResolvedPasteTarget): {
      readonly row: number;
      readonly column: number;
      readonly rowType: DimensionRows;
      readonly colType: DimensionCols;
    };
  /** Converts a resolved column from its visible index to its physical source index. */
    getPhysicalColumnAddress(target: ClipboardResolvedPasteTarget): {
      readonly column: number;
      readonly colType: DimensionCols;
    };
  /** Returns the cached physical row source for readonly evaluation. */
    getTargetRowSource(target: ClipboardResolvedPasteTarget): DataType[]
}

---

resolveClipboardFormattingRuntime

Finds the installed data-grid formatting runtime, when available.

export function resolveClipboardFormattingRuntime(
  providers: PluginProviders,
): DataGridFormattingRuntime | undefined;

---

applyClipboardFormatting

Applies rich clipboard formats to every accepted destination cell.

export function applyClipboardFormatting(
  context: ClipboardFormattingContext,
  document: ClipboardDocument,
  start: ClipboardPasteStart,
  targetFilter?: ClipboardMetadataTargetFilter,
): void;

---

isClipboardPasteValueCompatible

Checks that pasted values match every effective destination editor domain.

export function isClipboardPasteValueCompatible(
  context: ClipboardFormattingContext,
  document: ClipboardDocument,
  start: ClipboardPasteStart,
): boolean;

---

resolveClipboardPasteFormulas

Rebases stored Excel R1C1 formulas against the current paste destination.

export function resolveClipboardPasteFormulas(
  providers: PluginProviders,
  document: ClipboardDocument,
  start: ClipboardPasteStart,
): ClipboardDocument;

---

isWritableClipboardTarget

Checks provider readonly policy for one resolved clipboard destination.

export function isWritableClipboardTarget(
  resolver: ClipboardCoordinateResolver,
  target: ClipboardResolvedPasteTarget,
): boolean;

---

clipboardDocumentToSparsePayload

Converts multi-range rich data into the legacy sparse clipboard payload.

export function clipboardDocumentToSparsePayload(
  document: ClipboardDocument,
): MultiRangeClipboardPayload | null;

---

captureClipboardMerges

Captures merges fully contained by one copied viewport range.

export function captureClipboardMerges(
  revogrid: HTMLRevoGridElement,
  area: RangeArea,
  rowType: DimensionRows,
  colType: DimensionCols,
);

---

applyClipboardStructure

Applies valid, writable clipboard merges at the paste destination.

export function applyClipboardStructure(
  context: ClipboardStructureContext,
  document: ClipboardDocument,
  start: ClipboardPasteStart,
  targetFilter?: ClipboardMetadataTargetFilter,
): void;

---

normalizeExcelClipboardFormula

Convert browser-visible Excel R1C1 references into FormulaPlugin-compatible A1 references.

export function normalizeExcelClipboardFormula(
  value: string,
  rowIndex: number,
  columnIndex: number,
): string;

---

toExcelClipboardFormula

Convert FormulaPlugin-compatible A1 references into Excel HTML R1C1 references.

export function toExcelClipboardFormula(
  value: string,
  rowIndex: number,
  columnIndex: number,
): string;

---

cloneClipboardDocument

export function cloneClipboardDocument(document: ClipboardDocument): ClipboardDocument;

---

revogridJsonClipboardFormat

revogridJsonClipboardFormat: {
  id: string;
  mimeTypes: string[];
  priority: number;
  read: ({ transfer, maxBytes, maxCells }: ClipboardFormatReadContext) => ClipboardDocument<any> | null;
  write: ({ document }: ClipboardFormatWriteContext<any>) => { type: string; data: string; }[];
};