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;
| Parameter | Type | Description |
|---|---|---|
url | string | URL of the SSE stream. The bridge opens one EventSource on it. |
clientId | string | Id of the current client. Events whose client field equals this value are skipped. |
api | KanbanInstanceApi | The kanban API (any object with exec works). The bridge runs remote changes on it. |
provider | RestDataProvider | The provider attached to the board. Its queue maps backend ids to local ids. |
events | Record<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,SWIMLANESfrom@svar-ui/kanban-provider). ForCARDS, the bridge mapsid,before, andcard.idfrom backend ids to local ids through the provider queue, and converts a stringcard.deadlineto aDate. Payloads for other kinds pass through unchanged. - A function
(data) => void | boolean. It receives the event payload and can change it in place. Returnfalseto drop the event.
Event format
The server sends each event as JSON with these fields:
| Field | Type | Description |
|---|---|---|
client | string | Id of the client that made the change |
op | string | Action to execute on the board, e.g. "update-card" |
data | object | Action 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.
Related
- RestDataProvider - sends local changes to the backend
- Working with server - loading, saving, and live sync
- setNext - attaches the provider to the board