Skip to main content

KanbanEventBridge

KanbanEventBridge keeps a board in sync with changes made by other users. It listens to a server-sent events (SSE) stream and replays each remote change on the board as a regular action. It works together with RestDataProvider. The provider sends local changes to the backend, and the bridge brings in changes from other clients.

The bridge skips events created by the current client, so a user doesn't see their own changes applied twice. Replayed actions run with skipProvider: true, so they aren't sent back to the backend.

The bridge replays received events; it does not resolve conflicting edits or recover missed events.

Reference backend implementation - https://github.com/svar-widgets/kanban-backend-go

Usage​

import { KanbanEventBridge } from "@svar-ui/kanban-provider";

const bridge = new KanbanEventBridge(
url: string,
clientId: string,
api: { exec },
provider: { getQueue },
events: Record<string, number | ((data: any) => void | boolean)>
);

bridge.close(): void;
ParameterTypeDescription
urlstringURL of the SSE stream. The bridge opens one EventSource on it.
clientIdstringId of the current client. Events whose client field equals this value are skipped.
apiKanbanInstanceApiThe kanban API (any object with exec works). The bridge runs remote changes on it.
providerRestDataProviderThe provider attached to the board. Its queue maps backend ids to local ids.
eventsRecord<string, number | (data) => void | boolean>SSE event names to listen to, each with an id kind or a custom handler (see below).

Event configuration​

Each key in events is an SSE event name. The value is one of:

  • An id kind constant (CARDS, COLUMNS, SWIMLANES from @svar-ui/kanban-provider). For CARDS, the bridge maps id, before, and card.id from backend ids to local ids through the provider queue, and converts a string card.deadline to a Date. Payloads for other kinds pass through unchanged.
  • A function (data) => void | boolean. It receives the event payload and can change it in place. Return false to drop the event.

Event format​

The server sends each event as JSON with these fields:

FieldTypeDescription
clientstringId of the client that made the change
opstringAction to execute on the board, e.g. "update-card"
dataobjectAction payload

The bridge calls api.exec(op, { skipProvider: true, ...data }).

close()​

Stops the stream and its automatic reconnect. A closed bridge can't be reopened. Create a new one instead.

Example​

import { useEffect, useRef, useState } from "react";
import { Kanban, Editor } from "@svar-ui/react-kanban";
import {
RestDataProvider,
CARDS,
KanbanEventBridge,
} from "@svar-ui/kanban-provider";

const url = "https://api.example.com/boards/1";
// unique per tab, so the client skips its own events
const clientId = crypto.randomUUID();

const provider = new RestDataProvider(url);
provider.setHeaders({ "X-Client-Id": clientId });

const columns = [
{ id: "todo", label: "To do" },
{ id: "done", label: "Done" },
];

function App() {
const [api, setApi] = useState();
const [cards, setCards] = useState([]);
const bridgeRef = useRef(null);

useEffect(() => {
provider.getData().then(data => setCards(data));
return () => bridgeRef.current?.close();
}, []);

function init(value) {
setApi(value);
bridgeRef.current = new KanbanEventBridge(
`${url}/events`,
clientId,
value,
provider,
{
"add-card": CARDS,
"update-card": CARDS,
"move-card": CARDS,
"delete-card": CARDS,
},
);
value.setNext(provider);
}

return (
<>
<Kanban init={init} cards={cards} columns={columns} />
{api && <Editor api={api} />}
</>
);
}

export default App;

The provider sends the client id in a request header so the backend can include it in the events it broadcasts.