Collaborative Presence

Module Extensions

HTMLRevoGridElement (Extended from @revolist/revogrid)

interface HTMLRevoGridElement {
  collaborativePresence?: CollaborativePresenceConfig;
  'collaborative-presence'?: CollaborativePresenceConfig
}

---

AdditionalData (Extended from @revolist/revogrid)

interface AdditionalData {
  collaborativePresence?: CollaborativePresenceConfig
}

Plugin API

CollaborativePresencePlugin

Renders remote collaborator focus and range presence without mutating local grid focus, selection, data, or history.

Dependencies

• Config integration additionalData.collaborativePresence: Reads remote collaborator presence from grid.collaborativePresence or additionalData.collaborativePresence.
• Event integration afterrender: Refreshes visible remote focus and range markers after grid render updates.

class CollaborativePresencePlugin {
  destroy();
}

---

CollaborativePresenceActivity

export type CollaborativePresenceActivity = 'viewing' | 'editing' | 'idle';

---

CollaborativePresenceCellRef

interface CollaborativePresenceCellRef {
  x: number;
  y: number;
  colType?: DimensionCols;
  rowType?: DimensionRows
}

---

CollaborativePresenceRangeRef (Extended from index.ts)

interface CollaborativePresenceRangeRef {
  colType?: DimensionCols;
  rowType?: DimensionRows
}

---

CollaborativePresenceUser

interface CollaborativePresenceUser {
  id: string;
  name: string;
  initials?: string;
  color?: string;
  activity?: CollaborativePresenceActivity;
  focus?: CollaborativePresenceCellRef | null;
  range?: CollaborativePresenceRangeRef | null;
  lastActiveAt?: number | string | Date
}

---

CollaborativePresenceRowPatch

interface CollaborativePresenceRowPatch {
  rowIndex: number;
  data: Record<string, unknown>;
  rowType?: DimensionRows
}

---

CollaborativePresenceConfig

interface CollaborativePresenceConfig {
  enabled?: boolean;
  showLabels?: boolean;
  staleAfterMs?: number;
  users?: CollaborativePresenceUser[];
  remoteEdits?: CollaborativePresenceRowPatch[]
}

---

ResolvedCollaborativePresenceConfig

interface ResolvedCollaborativePresenceConfig {
  enabled: boolean;
  showLabels: boolean;
  staleAfterMs?: number;
  users: CollaborativePresenceUser[];
  remoteEdits: CollaborativePresenceRowPatch[]
}

---

CollaborativePresenceRect

interface CollaborativePresenceRect {
  left: number;
  top: number;
  width: number;
  height: number
}

---

CollaborativePresenceMarker

interface CollaborativePresenceMarker {
  kind: 'focus' | 'range';
  user: CollaborativePresenceUser;
  rect: CollaborativePresenceRect;
  colType: DimensionCols;
  rowType: DimensionRows
}

---

normalizeCollaborativePresenceCell

export function normalizeCollaborativePresenceCell(
  cell: CollaborativePresenceCellRef,
): Required<CollaborativePresenceCellRef>;

---

normalizeCollaborativePresenceRange

export function normalizeCollaborativePresenceRange(
  range: CollaborativePresenceRangeRef,
): Required<CollaborativePresenceRangeRef>;

---

resolveCollaborativePresenceConfig

export function resolveCollaborativePresenceConfig(
  config?: CollaborativePresenceConfig,
): ResolvedCollaborativePresenceConfig;

---

getVisibleCollaborativePresenceUsers

export function getVisibleCollaborativePresenceUsers(
  config: ResolvedCollaborativePresenceConfig,
  now = Date.now(),
): CollaborativePresenceUser[];

---

resolveCollaborativePresenceMarkers

export function resolveCollaborativePresenceMarkers(
  _grid: HTMLElement,
  users: CollaborativePresenceUser[],
  providers?: PluginProviders,
): CollaborativePresenceMarker[];

---

applyCollaborativePresenceRowPatches

Applies row patches directly into the RevoGrid data store without triggering a full source reset or plugin re-initialization.

rowIndex is treated as a source (physical) index — the position in the original data array — so patches always target the correct row regardless of the current sort or reorder state.

Per rowType:

1. Mutate source[rowIndex] directly for each patch
2. store.set(‘source’, […]) once — triggers a single targeted reactive update

Mirrors the low-level write pattern in spreadsheet.simulation.ts.

export function applyCollaborativePresenceRowPatches(
  providers: PluginProviders,
  patches: CollaborativePresenceRowPatch[],
): void;

---

CollaborativePresenceLayer

Manages per-viewport slot overlay elements and draws presence markers into them. Each viewport type combination (colType × rowType) gets its own slot div so markers clip and scroll correctly within their viewport.

class CollaborativePresenceLayer {
  render(markers: CollaborativePresenceMarker[], showLabels: boolean): void;

  destroy(): void;
}

---

resolveCollaborativePresenceCellRect

export function resolveCollaborativePresenceCellRect(
  providers: PluginProviders | undefined,
  cell: PresenceCell,
): CollaborativePresenceRect | undefined;

---

resolveCollaborativePresenceRangeRect

export function resolveCollaborativePresenceRangeRect(
  providers: PluginProviders | undefined,
  range: PresenceRange,
): CollaborativePresenceRect | undefined;