Skip to content

Latest commit

 

History

History
104 lines (82 loc) · 5.02 KB

README.md

File metadata and controls

104 lines (82 loc) · 5.02 KB

DocSync Presence for React

Private, optional React 19 bindings. Supply one headless PresenceStore from @barocss/doc-sync/presence and a projector from @barocss/doc-sync-presence-ui. The shared DOM renderer owns avatar, cursor, selection, and draft visuals. Names appear on hover. This package adds no transport or editor geometry.

Installation and package status

This package is private, version 0.0.0, and not published to npm. Use the repository workspaces or local tarballs, not a registry install of this name. Node 22.18 or later is required for repository tooling. From the repository root:

npm ci
npm run build
npm run test --workspace @barocss/doc-sync-presence-react

For a separate application, pack the required workspaces from this checkout:

mkdir -p artifacts
npm pack --workspace @barocss/doc-sync --pack-destination artifacts
npm pack --workspace @barocss/doc-sync-presence-ui --pack-destination artifacts
npm pack --workspace @barocss/doc-sync-presence-react --pack-destination artifacts

Install those generated .tgz files together in the consuming application. Required peers are @barocss/doc-sync >=0.0.0 <0.1.0, @barocss/doc-sync-presence-ui >=0.0.0 <0.1.0, and react ^19.2.0 (and react-dom in a browser application). Use your framework’s normal build setup; these are ESM packages.

Usage

import {PresenceOverlay, PresenceProvider} from '@barocss/doc-sync-presence-react';

function EditorPresence({store, projector}) {
  return <PresenceProvider store={store}>
    <PresenceOverlay options={{projector}} style={{position: 'relative', height: 320}} />
  </PresenceProvider>;
}

PresenceOverlay accepts store directly, or gets it from PresenceProvider. options is PresenceUIOptions; projection rectangles use viewport CSS pixels. Place the host in your editor's overlay container and set className or style as needed. AvatarStack, CursorLayer, SelectionLayer, and DraftPreview accept the same props and enable only their own visual layer.

usePresence(store?) uses useSyncExternalStore and returns the stable store snapshot. usePresenceStore(store?) resolves the explicit or provided store. Imports and initial rendering do not read browser globals. Effects mount the DOM renderer and dispose it on unmount or store replacement. React Strict Mode can mount again without retaining the old subscription. The caller owns the store and network client; these bindings never dispose or disconnect them.

Store, geometry and security contract

Create the store once per client actor in your application, not on each render:

import {createPresenceStore} from '@barocss/doc-sync/presence';
import {createPresenceProjector} from '@barocss/doc-sync-presence-ui';

const store = createPresenceStore({actor: 'demo-replica', ttlMs: 30_000});
store.updateLocal({profile: {name: 'Demo'}, activity: 'active'});
// Avatar-only setup: deliberately no geometry adapters.
const projector = createPresenceProjector({});

Pass this store and projector to the example above. This local example opens no network connection. For real collaboration, use connectClientPresence from @barocss/doc-sync/presence with your synchronized client. Give concurrently active replicas distinct actor IDs. The store starts no expiry timer: the application must call expire() if it needs time-based removal. Dispose the UI first, then the bridge and store when their owning application closes. Never dispose a shared store merely because one view unmounts.

The empty projector renders avatars but intentionally draws no document targets. Supply document-anchor, canvas-object or sheet-cell adapters for cursors, selections and drafts. Each adapter must return viewport CSS-pixel rectangles or null for hidden, deleted, offscreen or unresolved targets. These geometry adapters belong to your editor; they are not supplied by this package. Give the overlay a nonzero size matching the editor viewport.

Presence is ephemeral display state, not document persistence, edit authorization or an acknowledgement protocol. Names and bot labels grant no authority. Draft text can reveal uncommitted input to other participants: publish it only when your application intends to share it. No wrapper commits text, installs an editor, or creates undo history. The shared renderer uses text nodes rather than interpreting participant names or drafts as HTML.

Documentation and verification

Package tests exercise renderer or framework lifecycle/SSR behavior; they do not prove your editor’s coordinate mapping, network authorization, production deployment or real IME behavior. Validate those integrations separately.