@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.
- package/README.md +144 -31
- package/api/editor.d.ts +178 -0
- package/api/whiteboard.d.ts +104 -0
- package/dist/editor.cjs +38733 -0
- package/dist/editor.css +9953 -0
- package/dist/editor.d.cts +178 -0
- package/dist/editor.d.ts +178 -0
- package/dist/editor.js +38974 -0
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +26 -4
- package/dist/index.d.ts +26 -4
- package/dist/index.js.map +1 -1
- package/dist/whiteboard.cjs +4540 -0
- package/dist/whiteboard.css +7913 -0
- package/dist/whiteboard.d.cts +104 -0
- package/dist/whiteboard.d.ts +104 -0
- package/dist/whiteboard.js +4568 -0
- package/package.json +198 -14
- package/src/SynapProvider.tsx +1 -1
- package/src/editor/SynapEditor.tsx +288 -0
- package/src/editor/SynapMarkdown.tsx +11 -0
- package/src/editor/adapter-source.ts +97 -0
- package/src/editor/api.ts +30 -0
- package/src/editor/copy.ts +18 -0
- package/src/editor/drag.ts +14 -0
- package/src/editor/editor-base.css +28 -0
- package/src/editor/http-adapter.ts +87 -0
- package/src/editor/index.ts +22 -0
- package/src/editor/no-default-source.ts +7 -0
- package/src/editor/provider.tsx +79 -0
- package/src/editor/types.ts +162 -0
- package/src/index.ts +3 -3
- package/src/shared/read-cache.ts +76 -0
- package/src/trpc.ts +3 -2
- package/src/whiteboard/SynapBoard.tsx +139 -0
- package/src/whiteboard/adapter-source.ts +138 -0
- package/src/whiteboard/api.ts +22 -0
- package/src/whiteboard/copy.ts +24 -0
- package/src/whiteboard/http-adapter.ts +57 -0
- package/src/whiteboard/index.ts +17 -0
- package/src/whiteboard/no-default-source.ts +7 -0
- package/src/whiteboard/provider.tsx +14 -0
- package/src/whiteboard/shapes.tsx +157 -0
- package/src/whiteboard/types.ts +99 -0
- 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
|
-
|
|
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
|
|
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
|
|
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
|
-
| `
|
|
80
|
-
| `
|
|
81
|
-
| `
|
|
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
|
-
|
|
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
|
|
90
|
-
useSynap
|
|
91
|
-
useSynap
|
|
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
|
|
95
|
-
useSynap
|
|
96
|
-
useSynap
|
|
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);
|
|
118
|
-
const { data: links } = useLinks(id);
|
|
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 });
|
|
124
|
-
return
|
|
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);
|
|
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
|
|
134
|
-
|
|
|
135
|
-
| `useEntity(id, opts?)`
|
|
136
|
-
| `useEntities(slug?, opts?)`
|
|
137
|
-
| `useLinks(entityId, opts?)`
|
|
138
|
-
| `useView(viewId, opts?)`
|
|
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
|
|
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: [
|
|
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.
|
package/api/editor.d.ts
ADDED
|
@@ -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
|
+
}
|