@synap-core/react 1.0.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. package/README.md +144 -31
  2. package/api/editor.d.ts +178 -0
  3. package/api/whiteboard.d.ts +104 -0
  4. package/dist/editor.cjs +38733 -0
  5. package/dist/editor.css +9953 -0
  6. package/dist/editor.d.cts +178 -0
  7. package/dist/editor.d.ts +178 -0
  8. package/dist/editor.js +38974 -0
  9. package/dist/index.cjs.map +1 -1
  10. package/dist/index.d.cts +26 -4
  11. package/dist/index.d.ts +26 -4
  12. package/dist/index.js.map +1 -1
  13. package/dist/whiteboard.cjs +4540 -0
  14. package/dist/whiteboard.css +7913 -0
  15. package/dist/whiteboard.d.cts +104 -0
  16. package/dist/whiteboard.d.ts +104 -0
  17. package/dist/whiteboard.js +4568 -0
  18. package/package.json +198 -14
  19. package/src/SynapProvider.tsx +1 -1
  20. package/src/editor/SynapEditor.tsx +288 -0
  21. package/src/editor/SynapMarkdown.tsx +11 -0
  22. package/src/editor/adapter-source.ts +97 -0
  23. package/src/editor/api.ts +30 -0
  24. package/src/editor/copy.ts +18 -0
  25. package/src/editor/drag.ts +14 -0
  26. package/src/editor/editor-base.css +28 -0
  27. package/src/editor/http-adapter.ts +87 -0
  28. package/src/editor/index.ts +22 -0
  29. package/src/editor/no-default-source.ts +7 -0
  30. package/src/editor/provider.tsx +79 -0
  31. package/src/editor/types.ts +162 -0
  32. package/src/index.ts +3 -3
  33. package/src/shared/read-cache.ts +76 -0
  34. package/src/trpc.ts +3 -2
  35. package/src/whiteboard/SynapBoard.tsx +139 -0
  36. package/src/whiteboard/adapter-source.ts +138 -0
  37. package/src/whiteboard/api.ts +22 -0
  38. package/src/whiteboard/copy.ts +24 -0
  39. package/src/whiteboard/http-adapter.ts +57 -0
  40. package/src/whiteboard/index.ts +17 -0
  41. package/src/whiteboard/no-default-source.ts +7 -0
  42. package/src/whiteboard/provider.tsx +14 -0
  43. package/src/whiteboard/shapes.tsx +157 -0
  44. package/src/whiteboard/types.ts +99 -0
  45. package/src/whiteboard/whiteboard-base.css +87 -0
package/README.md CHANGED
@@ -21,7 +21,7 @@ export default function App() {
21
21
  return (
22
22
  <SynapProvider
23
23
  podUrl="https://your-pod.synap.live"
24
- apiKey="sk_live_..." // from Workspace → Settings → API Keys
24
+ sessionToken="..." // Kratos session token; omit in a signed-in browser (cookie)
25
25
  workspaceId="ws_..."
26
26
  >
27
27
  <YourApp />
@@ -36,7 +36,7 @@ export default function App() {
36
36
  import { useSynap } from "@synap-core/react";
37
37
 
38
38
  function EntityList() {
39
- const { data, isLoading } = useSynap().entities.list.useQuery({ limit: 20 });
39
+ const { data, isLoading } = useSynap.entities.list.useQuery({ limit: 20 });
40
40
 
41
41
  if (isLoading) return <p>Loading...</p>;
42
42
 
@@ -50,7 +50,7 @@ function EntityList() {
50
50
  }
51
51
 
52
52
  function CreateNote() {
53
- const create = useSynap().entities.create.useMutation();
53
+ const create = useSynap.entities.create.useMutation();
54
54
 
55
55
  return (
56
56
  <button
@@ -72,28 +72,29 @@ function CreateNote() {
72
72
 
73
73
  ### `<SynapProvider>`
74
74
 
75
- | Prop | Type | Required | Description |
76
- | -------------- | ------------------------ | -------- | ---------------------------------------- |
77
- | `podUrl` | `string` | ✓ | Data pod base URL (no trailing slash) |
78
- | `workspaceId` | `string` | ✓ | Workspace ID |
79
- | `apiKey` | `string` | — | Bearer token. Omit for cookie-based auth |
80
- | `extraHeaders` | `Record<string, string>` | — | Extra request headers |
81
- | `queryClient` | `QueryClient` | — | Reuse an existing TanStack Query client |
75
+ | Prop | Type | Required | Description |
76
+ | -------------- | ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
77
+ | `podUrl` | `string` | ✓ | Data pod base URL (no trailing slash) |
78
+ | `workspaceId` | `string` | ✓ | Workspace ID |
79
+ | `sessionToken` | `string` | — | Kratos session token. Omit for cookie-based auth |
80
+ | `apiKey` | `string` | — | Local-mode token only. Hub / user API keys (`synap_hub_*`, `synap_user_*`) are refused by `/trpc`; use `@synap-core/hub-rest-client` |
81
+ | `extraHeaders` | `Record<string, string>` | — | Extra request headers |
82
+ | `queryClient` | `QueryClient` | — | Reuse an existing TanStack Query client |
82
83
 
83
- ### `useSynap()`
84
+ ### `useSynap`
84
85
 
85
- Returns the full tRPC hook tree. Every procedure is available:
86
+ The full tRPC hook tree (the object `createTRPCReact()` returns). Do not call it — `useSynap()` returns `undefined`; call a procedure's hook on it directly, e.g. `useSynap.entities.list.useQuery(input)`. Every procedure is available, plus `useSynap.useUtils()` for cache helpers:
86
87
 
87
88
  ```typescript
88
89
  // Queries
89
- useSynap().entities.list.useQuery(input);
90
- useSynap().workspaces.get.useQuery();
91
- useSynap().channels.list.useQuery({ workspaceId });
90
+ useSynap.entities.list.useQuery(input);
91
+ useSynap.workspaces.get.useQuery({ id: workspaceId });
92
+ useSynap.workspaces.list.useQuery();
92
93
 
93
94
  // Mutations
94
- useSynap().entities.create.useMutation();
95
- useSynap().entities.update.useMutation();
96
- useSynap().chat.sendMessage.useMutation();
95
+ useSynap.entities.create.useMutation();
96
+ useSynap.entities.update.useMutation();
97
+ useSynap.chat.sendMessage.useMutation();
97
98
  ```
98
99
 
99
100
  ### `useSynapContext()`
@@ -114,30 +115,36 @@ procedure paths. They are plain TanStack-Query hooks (accept `enabled`,
114
115
  import { useEntity, useEntities, useLinks, useView } from "@synap-core/react";
115
116
 
116
117
  function Profile({ id }: { id: string }) {
117
- const { data: entity } = useEntity(id); // entities.get
118
- const { data: links } = useLinks(id); // relations.get (both directions)
118
+ const { data: entity } = useEntity(id); // entities.get
119
+ const { data: links } = useLinks(id); // relations.get (both directions)
119
120
  return <h1>{entity?.entity?.title}</h1>;
120
121
  }
121
122
 
122
123
  function People() {
123
- const { data } = useEntities("person", { limit: 50 }); // entities.list
124
- return <ul>{data?.items.map((e) => <li key={e.id}>{e.title}</li>)}</ul>;
124
+ const { data } = useEntities("person", { limit: 50 }); // entities.list
125
+ return (
126
+ <ul>
127
+ {data?.items.map((e) => (
128
+ <li key={e.id}>{e.title}</li>
129
+ ))}
130
+ </ul>
131
+ );
125
132
  }
126
133
 
127
134
  function MyView({ viewId }: { viewId: string }) {
128
- const { data: view } = useView(viewId); // views.get
135
+ const { data: view } = useView(viewId); // views.get
129
136
  return <pre>{JSON.stringify(view, null, 2)}</pre>;
130
137
  }
131
138
  ```
132
139
 
133
- | Hook | Procedure | Notes |
134
- | ----------------------------- | --------------- | --------------------------------------- |
135
- | `useEntity(id, opts?)` | `entities.get` | `opts.includeProfile?: boolean` |
136
- | `useEntities(slug?, opts?)` | `entities.list` | `opts: { workspaceId?, projectId?, limit? }` |
137
- | `useLinks(entityId, opts?)` | `relations.get` | `opts.direction?: "source" \| "target" \| "both"` (default `both`) |
138
- | `useView(viewId, opts?)` | `views.get` | — |
140
+ | Hook | Procedure | Notes |
141
+ | --------------------------- | --------------- | ------------------------------------------------------------------ |
142
+ | `useEntity(id, opts?)` | `entities.get` | `opts.includeProfile?: boolean` |
143
+ | `useEntities(slug?, opts?)` | `entities.list` | `opts: { workspaceId?, projectId?, limit? }` |
144
+ | `useLinks(entityId, opts?)` | `relations.get` | `opts.direction?: "source" \| "target" \| "both"` (default `both`) |
145
+ | `useView(viewId, opts?)` | `views.get` | — |
139
146
 
140
- For anything else, drop down to `useSynap()` (the full tRPC tree).
147
+ For anything else, drop down to `useSynap` (the full tRPC tree).
141
148
 
142
149
  ## Type helpers
143
150
 
@@ -154,4 +161,110 @@ For non-React apps use [`@synap-core/sdk`](https://www.npmjs.com/package/@synap-
154
161
 
155
162
  ## API reference
156
163
 
157
- Full procedure reference: [docs.synap.live/reference/api-reference](https://docs.synap.live/reference/api-reference)
164
+ Full procedure reference: [doc.synap.live/docs/reference/hub-api](https://doc.synap.live/docs/reference/hub-api)
165
+
166
+ ## The pod's editor in a pod app: `@synap-core/react/editor` (1.1)
167
+
168
+ The pod's markdown editor and reader (reference chips `[[entity:id|label]]`, `:::synap-*` embeds, sections,
169
+ columns, the `/` menu and `@` mentions) for an app signed in with `@synap-core/sdk/connect`. The pod token stays on
170
+ the app's server: the editor calls the app's own routes.
171
+
172
+ ```bash
173
+ npm i @synap-core/react @synap-core/sdk @synap-core/markdown-core react-dom \
174
+ @tiptap/core @tiptap/pm @tiptap/react @tiptap/starter-kit @tiptap/markdown @tiptap/suggestion \
175
+ @tiptap/extension-collaboration @tiptap/extension-collaboration-caret @tiptap/y-tiptap yjs \
176
+ @tiptap/extension-code-block-lowlight @tiptap/extension-color @tiptap/extension-drag-handle-react \
177
+ @tiptap/extension-highlight @tiptap/extension-image @tiptap/extension-placeholder @tiptap/extension-table \
178
+ @tiptap/extension-task-item @tiptap/extension-task-list @tiptap/extension-text-style @tiptap/extension-underline \
179
+ @tiptap/extension-drag-handle @tiptap/extension-node-range \
180
+ @floating-ui/react react-aria-components react-markdown lucide-react lowlight turndown katex mermaid zod \
181
+ --legacy-peer-deps # Tiptap extensions pin exact peer versions
182
+ ```
183
+
184
+ (All optional peers: an app that only uses the root hooks installs none of them.)
185
+
186
+ ```ts
187
+ // app/api/synap/editor/[...path]/route.ts — the server half
188
+ import { createEditorHandlers } from "@synap-core/sdk/connect";
189
+ import { auth } from "@/lib/synap";
190
+ export const { GET, PATCH, POST } = createEditorHandlers({
191
+ client: async (req) => {
192
+ const connection = await auth.readConnection(req);
193
+ return connection ? auth.client(connection) : null;
194
+ },
195
+ });
196
+ ```
197
+
198
+ ```tsx
199
+ "use client";
200
+ import "@synap-core/react/editor.css";
201
+ import { EditorDataProvider, SynapEditor, createHttpEditorAdapter, setSynapObjectDrag } from "@synap-core/react/editor";
202
+
203
+ const adapter = createHttpEditorAdapter(); // calls /api/synap/editor/*
204
+
205
+ <EditorDataProvider adapter={adapter}>
206
+ <SynapEditor documentId={piece.documentId} subjectId={piece.id} />
207
+ </EditorDataProvider>
208
+
209
+ // A pod object the person drags onto the editor becomes a chip AND a relation from `subjectId`:
210
+ <li draggable onDragStart={(e) => setSynapObjectDrag(e.dataTransfer, { id, kind: "person", label: "Ada" })}>Ada</li>
211
+ ```
212
+
213
+ - **Saves are governed.** `<SynapEditor>` saves after a pause with the revision it read and says what the pod did:
214
+ "Saved", "Waiting for review" (with the review link: an app connection's edits may be proposals), or "changed
215
+ elsewhere, reload". It never claims a save the pod did not apply.
216
+ - **Embeds**: a `:::synap-*` embed shows its author's fallback, or a chip naming the embedded object. Draw them
217
+ yourself with `renderEmbed` on the provider (return null for the default).
218
+ - **Not yet**: live collaboration (a Yjs room needs a room ticket, slice S3) and the desktop's cell catalog in `/`.
219
+ - The editor's `--synap-*` tokens come first in `editor.css`; override any of them after it.
220
+
221
+ ## The pod's board in a pod app: `@synap-core/react/whiteboard` (1.2)
222
+
223
+ The pod's tldraw board (tldraw 2.4.6, the desktop's engine) on one board document, joined LIVE: the same room, the
224
+ same records and the same sync as the desktop, so what one person draws, everyone on the board sees, and the pod keeps
225
+ it. The pod token stays on the app's server; the browser only holds a single-use room ticket per connect.
226
+
227
+ ```bash
228
+ npm i @synap-core/react @synap-core/sdk react-dom @tldraw/tldraw@2.4.6 yjs y-socket.io y-indexeddb \
229
+ react-aria-components --legacy-peer-deps # tldraw 2.4.6 declares react ^18 as its peer
230
+ ```
231
+
232
+ ```ts
233
+ // app/api/synap/board/[...path]/route.ts — the server half (needs a pod with the room ticket door)
234
+ import { createBoardHandlers } from "@synap-core/sdk/connect";
235
+ import { auth } from "@/lib/synap";
236
+ export const { GET, POST } = createBoardHandlers({
237
+ client: async (req) => {
238
+ const connection = await auth.readConnection(req);
239
+ return connection ? auth.client(connection) : null;
240
+ },
241
+ });
242
+ ```
243
+
244
+ ```tsx
245
+ "use client"; // tldraw draws in the browser only: in Next, load this component with `dynamic(..., { ssr: false })`
246
+ import "@tldraw/tldraw/tldraw.css";
247
+ import "@synap-core/react/whiteboard.css";
248
+ import { BoardDataProvider, SynapBoard, createHttpBoardAdapter } from "@synap-core/react/whiteboard";
249
+
250
+ const adapter = createHttpBoardAdapter(); // calls /api/synap/board/*
251
+
252
+ <BoardDataProvider adapter={adapter}>
253
+ <SynapBoard
254
+ documentId={board.documentId} // a whiteboard view's document (Hub `POST /views` makes one)
255
+ user={{ id: me.id, name: me.name, color: "#3B82F6" }}
256
+ licenseKey={process.env.NEXT_PUBLIC_TLDRAW_LICENSE_KEY} // optional; forwarded to tldraw as is
257
+ onObjectClick={(id, kind) => openInApp(id, kind)} // double-click on an entity card
258
+ />
259
+ </BoardDataProvider>
260
+ ```
261
+
262
+ - **Honest states**: "Opening the board…", a room that could not be opened says why (no access, connect again)
263
+ with Try again, a board whose saved content could not be loaded is never shown empty, and the board is read-only
264
+ when the room takes no writes from this person (a `read` ticket) or before the store is hydrated.
265
+ - **What a stored board holds, the app keeps**: entity cards read their entity through the adapter; a live view, a
266
+ cell or an artboard placed on the desktop shows as a named placeholder ("Opens in Synap") and is written back
267
+ untouched.
268
+ - **Not yet (v1)**: the desktop's toolbar and panels (the board draws tldraw's own), version history (no Hub door
269
+ yet), brand projection, AI placement, the session stream, inline card editing.
270
+ - **Licence**: tldraw's licence key is the host's. `licenseKey` is the one seam; nothing is bundled.
@@ -0,0 +1,178 @@
1
+ // api.d.ts
2
+ /**
3
+ * The declared API of `@synap-core/react/editor`: what `dist/editor.d.ts` is
4
+ * built from (tsup `dts.entry`). `index.ts` binds each value to its type here,
5
+ * so the implementation cannot drift from it without a type error, and the
6
+ * snapshot test (`api/editor.d.ts`) makes every change to it deliberate.
7
+ */
8
+ import type { ReactElement } from "react";
9
+ import type { EditorDataAdapter, EditorDataProviderProps, HttpEditorAdapterOptions, SynapDraggedObject, SynapEditorProps, SynapMarkdownProps } from "./types";
10
+ export * from "./types";
11
+ /** Every Synap editor and reader below it reads through `adapter`. */
12
+ export declare function EditorDataProvider(props: EditorDataProviderProps): ReactElement;
13
+ /** The pod's markdown editor on one document: load, autosave with `baseRevision`, drop-to-link. */
14
+ export declare function SynapEditor(props: SynapEditorProps): ReactElement | null;
15
+ /** The pod's markdown reader. */
16
+ export declare function SynapMarkdown(props: SynapMarkdownProps): ReactElement | null;
17
+ /** The adapter over the app's own routes (`createEditorHandlers`, `@synap-core/sdk/connect`). */
18
+ export declare function createHttpEditorAdapter(options?: HttpEditorAdapterOptions): EditorDataAdapter;
19
+ /** The drag payload type `<SynapEditor>` takes: JSON `{ id, kind, label }`. */
20
+ export declare const SYNAP_OBJECT_MIME: "text/x-synap-object";
21
+ /** Set a pod object on a drag, so `<SynapEditor>` takes the drop. */
22
+ export declare function setSynapObjectDrag(dataTransfer: DataTransfer, object: SynapDraggedObject): void;
23
+
24
+ // types.d.ts
25
+ /**
26
+ * The public types of `@synap-core/react/editor`. Self-contained on purpose:
27
+ * the published `editor.d.ts` is built from THIS module (tsup `dts.entry`), so
28
+ * a refactor inside the bundled editor cannot change the API an app compiles
29
+ * against without a change here (snapshot: `api/editor.d.ts`).
30
+ */
31
+ import type { ReactNode } from "react";
32
+ /**
33
+ * What an id names, as the pod's `GET /api/hub/resolve/:id` answers it.
34
+ * `type: "unknown"` = nothing this reader can see has the id (not a failure).
35
+ */
36
+ export interface ResolvedRef {
37
+ type: string;
38
+ displayName?: string | null;
39
+ openable?: boolean | null;
40
+ profileSlug?: string | null;
41
+ }
42
+ /** An entity row the `@` picker searches. */
43
+ export interface EditorEntity {
44
+ id: string;
45
+ title?: string | null;
46
+ profileSlug?: string;
47
+ }
48
+ /** A view row the `@` picker and the `/` menu's "Saved views" list. */
49
+ export interface EditorView {
50
+ id: string;
51
+ name?: string;
52
+ type?: string;
53
+ }
54
+ /** A document as the editor loads it. */
55
+ export interface EditorDocument {
56
+ id: string;
57
+ title: string;
58
+ content: string;
59
+ /** Pass back as `baseRevision` when saving. */
60
+ revision: number;
61
+ workspaceId: string | null;
62
+ }
63
+ /** Why a call failed. `code` is what to do (`conflict`: reload; `unauthorized`: connect again). */
64
+ export interface EditorError {
65
+ code: string;
66
+ /** The HTTP status, or null when nothing answered. */
67
+ status: number | null;
68
+ /** For logs only, never a headline. */
69
+ detail?: string;
70
+ }
71
+ /** What the pod did with a write: applied, filed for the person's review, or refused. */
72
+ export type EditorWriteResult = {
73
+ ok: true;
74
+ status: "applied";
75
+ } | {
76
+ ok: true;
77
+ status: "proposed";
78
+ reviewUrl: string;
79
+ } | {
80
+ ok: false;
81
+ error: EditorError;
82
+ };
83
+ /** A read that failed: thrown by an adapter's reads, so it is never shown as empty. */
84
+ export declare class EditorReadError extends Error {
85
+ readonly error: EditorError;
86
+ constructor(error: EditorError);
87
+ }
88
+ /**
89
+ * The editor's data calls. Reads throw (`EditorReadError`) on failure; writes
90
+ * answer what the pod did. `createHttpEditorAdapter` implements it against the
91
+ * app's own routes (`createEditorHandlers` in `@synap-core/sdk/connect`); a test
92
+ * or a story can implement it in memory.
93
+ */
94
+ export interface EditorDataAdapter {
95
+ /** What an id names, for a reference chip. */
96
+ resolveRef(id: string): Promise<ResolvedRef>;
97
+ /** The entities of a space, for the `@` picker. */
98
+ listEntities(workspaceId: string): Promise<EditorEntity[]>;
99
+ /** The views of a space, for the `@` picker and the `/` menu. */
100
+ listViews(workspaceId: string): Promise<EditorView[]>;
101
+ getDocument(id: string): Promise<EditorDocument>;
102
+ /** Replace the document's markdown, guarded by `baseRevision`. */
103
+ saveDocument(id: string, markdown: string, baseRevision: number): Promise<EditorWriteResult>;
104
+ /** Write a relation `sourceId --type--> targetId` (a dropped object). */
105
+ linkObjects(input: {
106
+ sourceId: string;
107
+ targetId: string;
108
+ type: string;
109
+ }): Promise<EditorWriteResult>;
110
+ }
111
+ /** A pod object being dragged onto the editor (`text/x-synap-object`). */
112
+ export interface SynapDraggedObject {
113
+ id: string;
114
+ /** `entity`, `view`, `document`, or a profile slug (`post`, `person`…). */
115
+ kind: string;
116
+ label: string;
117
+ }
118
+ /** A `:::synap-*` embed, for a host that draws embeds itself (`renderEmbed`). */
119
+ export interface SynapEmbed {
120
+ directive: "synap-cell" | "synap-entity" | "synap-view";
121
+ /** Reference attributes as authored (`id`, `viewId`, `cellKey`, `instanceId`). */
122
+ reference: Record<string, string>;
123
+ props?: Record<string, unknown> | null;
124
+ /** The author's fallback, rendered. */
125
+ fallback?: ReactNode;
126
+ }
127
+ export interface EditorDataProviderProps {
128
+ adapter: EditorDataAdapter;
129
+ /**
130
+ * Draws a `:::synap-*` embed. Omitted: the author's fallback, or a chip
131
+ * naming the embedded object. Return null to draw the default.
132
+ */
133
+ renderEmbed?: (embed: SynapEmbed) => ReactNode;
134
+ children?: ReactNode;
135
+ }
136
+ export interface SynapEditorProps {
137
+ documentId: string;
138
+ /**
139
+ * The entity this document belongs to (e.g. the content piece). A dropped
140
+ * object is linked FROM it (`linkObjects`). Omitted: a drop inserts the chip
141
+ * and links nothing.
142
+ */
143
+ subjectId?: string;
144
+ /** The relation a drop writes. Default `"references"`. */
145
+ relationType?: string;
146
+ /** The space the `@` picker searches. Default: the document's own. */
147
+ workspaceId?: string;
148
+ /** Save this long after the last keystroke, in ms. Default 1500. */
149
+ autoSaveMs?: number;
150
+ editable?: boolean;
151
+ /** Opens an object a chip names (`id`, its kind). Omitted: chips are not buttons. */
152
+ onObjectClick?: (id: string, kind: string) => void;
153
+ /**
154
+ * The mounted editor's handle, for edits made from beside it (dictation, a
155
+ * quoted idea); null when it unmounts. Its edits save like typing.
156
+ */
157
+ onReady?: (handle: SynapEditorHandle | null) => void;
158
+ className?: string;
159
+ }
160
+ /** Edits a host makes from beside `<SynapEditor>`: each is the person's own, saved like typing. */
161
+ export interface SynapEditorHandle {
162
+ /** The document as markdown, as the next save would send it. */
163
+ getMarkdown(): string;
164
+ /** Plain text at the caret (never parsed as markdown). */
165
+ insertText(text: string): void;
166
+ /** Markdown blocks after the last one. */
167
+ appendMarkdown(markdown: string): void;
168
+ }
169
+ export interface SynapMarkdownProps {
170
+ content: string;
171
+ onObjectClick?: (id: string, kind: string) => void;
172
+ className?: string;
173
+ }
174
+ export interface HttpEditorAdapterOptions {
175
+ /** Where the app mounted `createEditorHandlers`. Default `/api/synap/editor`. */
176
+ basePath?: string;
177
+ fetch?: typeof fetch;
178
+ }
@@ -0,0 +1,104 @@
1
+ // api.d.ts
2
+ /**
3
+ * The declared API of `@synap-core/react/whiteboard`: what `dist/whiteboard.d.ts`
4
+ * is built from (tsup `dts.entry`). `index.ts` binds each value to its type
5
+ * here, so the implementation cannot drift from it without a type error, and
6
+ * the snapshot test (`api/whiteboard.d.ts`) makes every change to it deliberate.
7
+ */
8
+ import type { ReactElement } from "react";
9
+ import type { BoardDataAdapter, BoardDataProviderProps, HttpBoardAdapterOptions, SynapBoardProps } from "./types";
10
+ export * from "./types";
11
+ /** Every Synap board below it reads through `adapter`. */
12
+ export declare function BoardDataProvider(props: BoardDataProviderProps): ReactElement;
13
+ /** The pod's tldraw board on one board document, joined live through a room ticket. */
14
+ export declare function SynapBoard(props: SynapBoardProps): ReactElement;
15
+ /** The adapter over the app's own routes (`createBoardHandlers`, `@synap-core/sdk/connect`). */
16
+ export declare function createHttpBoardAdapter(options?: HttpBoardAdapterOptions): BoardDataAdapter;
17
+
18
+ // types.d.ts
19
+ /**
20
+ * The public types of `@synap-core/react/whiteboard`. Self-contained on
21
+ * purpose: the published `whiteboard.d.ts` is built from THIS module (tsup
22
+ * `dts.entry`), so a refactor inside the bundled board cannot change the API an
23
+ * app compiles against without a change here (snapshot: `api/whiteboard.d.ts`).
24
+ */
25
+ import type { ReactNode } from "react";
26
+ /**
27
+ * A short-lived, single-use pass into one board's live room, as the pod mints
28
+ * it (`POST /api/hub/realtime/room-ticket`) for the connection's person.
29
+ */
30
+ export interface BoardRoomTicket {
31
+ ticket: string;
32
+ /** ISO 8601. A ticket is used once, before this. */
33
+ expiresAt: string;
34
+ /** The person the ticket opens the room as (the handshake's `userId`). */
35
+ userId: string;
36
+ /** What the room will take from this person: `edit`, or `read` (the board is read-only). */
37
+ access: "read" | "edit";
38
+ /** The pod's realtime server, where the room socket connects. */
39
+ url: string;
40
+ }
41
+ /** An entity as a board card shows it. */
42
+ export interface BoardEntity {
43
+ id: string;
44
+ title: string | null;
45
+ profileSlug: string | null;
46
+ status: string | null;
47
+ }
48
+ /** Why a call failed. `code` is what to do (`unauthorized`: connect again; `forbidden`: no access). */
49
+ export interface BoardError {
50
+ code: string;
51
+ /** The HTTP status, or null when nothing answered. */
52
+ status: number | null;
53
+ /** For logs only, never a headline. */
54
+ detail?: string;
55
+ }
56
+ /** A read that failed: thrown by an adapter's calls, so it is never shown as an empty board. */
57
+ export declare class BoardReadError extends Error {
58
+ readonly error: BoardError;
59
+ constructor(error: BoardError);
60
+ }
61
+ /**
62
+ * The board's data calls. Each throws `BoardReadError` on failure.
63
+ * `createHttpBoardAdapter` implements it against the app's own routes
64
+ * (`createBoardHandlers` in `@synap-core/sdk/connect`); a test or a story can
65
+ * implement it in memory.
66
+ */
67
+ export interface BoardDataAdapter {
68
+ /** A fresh ticket for the board document's room; asked before every (re)connect. */
69
+ roomTicket(documentId: string): Promise<BoardRoomTicket>;
70
+ /** One entity, for a card placed on the board. */
71
+ getEntity(id: string): Promise<BoardEntity>;
72
+ }
73
+ export interface BoardDataProviderProps {
74
+ adapter: BoardDataAdapter;
75
+ children?: ReactNode;
76
+ }
77
+ /** Who this browser is on the board: a name and colour for the cursor others see. */
78
+ export interface BoardUser {
79
+ id: string;
80
+ name: string;
81
+ /** A CSS colour. */
82
+ color: string;
83
+ }
84
+ export interface SynapBoardProps {
85
+ /** The board's document (a whiteboard view's `documentId`). */
86
+ documentId: string;
87
+ /** This person's cursor. Omitted: an anonymous id kept on this device, named "You". */
88
+ user?: BoardUser;
89
+ /**
90
+ * The tldraw licence key, forwarded to tldraw as it is. Omitted: tldraw runs
91
+ * as it does with no key. The host owns the key; it is never bundled.
92
+ */
93
+ licenseKey?: string;
94
+ /** Keep the board read-only even when the room takes this person's writes. */
95
+ readOnly?: boolean;
96
+ /** Opens an object a card names (`id`, its kind). Omitted: double-clicking a card does nothing. */
97
+ onObjectClick?: (id: string, kind: string) => void;
98
+ className?: string;
99
+ }
100
+ export interface HttpBoardAdapterOptions {
101
+ /** Where the app mounted `createBoardHandlers`. Default `/api/synap/board`. */
102
+ basePath?: string;
103
+ fetch?: typeof fetch;
104
+ }