@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
@@ -0,0 +1,138 @@
1
+ /**
2
+ * An app's async `BoardDataAdapter` as the board's data source (the hooks the
3
+ * bundled live-room sync reads through, `@synap-core/web/whiteboard/embeddable`).
4
+ *
5
+ * The room: one ticket is asked on mount (it names the realtime URL, and a
6
+ * refused ticket is said before any socket opens); that ticket serves the
7
+ * first connect, and every later connect or reconnect asks a fresh one (a
8
+ * ticket is single-use). A ticket that cannot be had is a FAILED room, never
9
+ * a silent empty board.
10
+ */
11
+ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
12
+ import type {
13
+ BoardDataSource,
14
+ BoardEntityRead,
15
+ BoardRoomConnection,
16
+ BoardRoomFailure,
17
+ BoardRoomTarget,
18
+ } from "@synap-core/web/whiteboard/embeddable";
19
+ import { useRead, type ReadCache } from "../shared/read-cache";
20
+ import { BoardReadError, type BoardDataAdapter, type BoardEntity, type BoardRoomTicket } from "./types";
21
+
22
+ const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
23
+ /** A ticket this close to its expiry is not spent on a connect: a fresh one is asked. */
24
+ const TICKET_MARGIN_MS = 5_000;
25
+
26
+ /**
27
+ * The `/yjs` handshake that presents a room ticket: `{ userId, token }`, the
28
+ * same shape as a session's (backend realtime `session-auth.ts`, lane wb-room):
29
+ * the server reads the ticket's person, requires it to be `userId`, and claims
30
+ * the ticket for this one room.
31
+ */
32
+ export function ticketHandshake(ticket: BoardRoomTicket): Record<string, unknown> {
33
+ return { userId: ticket.userId, token: ticket.ticket };
34
+ }
35
+
36
+ export function failureOf(error: unknown): BoardRoomFailure {
37
+ if (error instanceof BoardReadError) return { code: error.error.code, status: error.error.status };
38
+ return { code: "unreachable", status: null };
39
+ }
40
+
41
+ function usable(ticket: BoardRoomTicket, now: number): boolean {
42
+ const expires = Date.parse(ticket.expiresAt);
43
+ return Number.isFinite(expires) && expires - now > TICKET_MARGIN_MS;
44
+ }
45
+
46
+ interface RoomState {
47
+ documentId: string;
48
+ url: string | null;
49
+ failure: BoardRoomFailure | null;
50
+ }
51
+
52
+ export function adapterSource(adapter: BoardDataAdapter, cache: ReadCache): BoardDataSource {
53
+ function useRoomConnection(
54
+ documentId: string,
55
+ options: { serverUrl?: string | null; enabled: boolean },
56
+ ): BoardRoomConnection {
57
+ const { serverUrl, enabled } = options;
58
+ const [state, setState] = useState<RoomState>({ documentId, url: null, failure: null });
59
+ const [asked, setAsked] = useState(0);
60
+ /** The ticket asked on mount, kept for the first connect. */
61
+ const spare = useRef<BoardRoomTicket | null>(null);
62
+ const ask = enabled && !!documentId && serverUrl !== null;
63
+
64
+ useEffect(() => {
65
+ if (!ask) return;
66
+ let live = true;
67
+ spare.current = null;
68
+ setState({ documentId, url: null, failure: null });
69
+ adapter.roomTicket(documentId).then(
70
+ (ticket) => {
71
+ if (!live) return;
72
+ spare.current = ticket;
73
+ setState({ documentId, url: serverUrl ?? ticket.url, failure: null });
74
+ },
75
+ (error: unknown) => {
76
+ if (live) setState({ documentId, url: null, failure: failureOf(error) });
77
+ },
78
+ );
79
+ return () => {
80
+ live = false;
81
+ };
82
+ }, [ask, documentId, serverUrl, asked]);
83
+
84
+ const handshake = useCallback(
85
+ () => (send: (auth: Record<string, unknown>) => void) => {
86
+ const kept = spare.current;
87
+ spare.current = null;
88
+ if (kept && usable(kept, Date.now())) {
89
+ send(ticketHandshake(kept));
90
+ return;
91
+ }
92
+ adapter.roomTicket(documentId).then(
93
+ (ticket) => send(ticketHandshake(ticket)),
94
+ (error: unknown) => {
95
+ // The socket is told no (the server refuses an empty handshake and
96
+ // the board turns read-only); the board says WHY from `failure`.
97
+ setState((s) => ({ ...s, failure: failureOf(error) }));
98
+ send({});
99
+ },
100
+ );
101
+ },
102
+ [documentId],
103
+ );
104
+ const retry = useCallback(() => setAsked((n) => n + 1), []);
105
+
106
+ const current = state.documentId === documentId ? state : { documentId, url: null, failure: null };
107
+ const target: BoardRoomTarget =
108
+ serverUrl === null
109
+ ? { kind: "offline" }
110
+ : current.url
111
+ ? { kind: "online", url: current.url }
112
+ : current.failure
113
+ ? { kind: "unavailable" }
114
+ : { kind: "pending" };
115
+ const failure = current.failure;
116
+ return useMemo<BoardRoomConnection>(
117
+ () => ({ target, handshake, failure, retry }),
118
+ // `target` is rebuilt every render; its kind and url are what it says.
119
+ // eslint-disable-next-line react-hooks/exhaustive-deps
120
+ [target.kind, current.url, failure, handshake, retry],
121
+ );
122
+ }
123
+
124
+ function useEntityCard(id: string, options: { enabled: boolean }): BoardEntityRead {
125
+ const ask = options.enabled && UUID_RE.test(id);
126
+ const load = useCallback(() => adapter.getEntity(id), [id]);
127
+ const { entry, refetch } = useRead(cache, ask ? `entity:${id}` : null, load);
128
+ const entity = entry.status === "ready" ? ((entry.data as BoardEntity | undefined) ?? null) : null;
129
+ return {
130
+ entity,
131
+ isLoading: entry.status === "loading",
132
+ error: entry.status === "failed" ? entry.error : null,
133
+ refetch,
134
+ };
135
+ }
136
+
137
+ return { useRoomConnection, useEntityCard };
138
+ }
@@ -0,0 +1,22 @@
1
+ /**
2
+ * The declared API of `@synap-core/react/whiteboard`: what `dist/whiteboard.d.ts`
3
+ * is built from (tsup `dts.entry`). `index.ts` binds each value to its type
4
+ * here, so the implementation cannot drift from it without a type error, and
5
+ * the snapshot test (`api/whiteboard.d.ts`) makes every change to it deliberate.
6
+ */
7
+ import type { ReactElement } from "react";
8
+ import type {
9
+ BoardDataAdapter,
10
+ BoardDataProviderProps,
11
+ HttpBoardAdapterOptions,
12
+ SynapBoardProps,
13
+ } from "./types";
14
+
15
+ export * from "./types";
16
+
17
+ /** Every Synap board below it reads through `adapter`. */
18
+ export declare function BoardDataProvider(props: BoardDataProviderProps): ReactElement;
19
+ /** The pod's tldraw board on one board document, joined live through a room ticket. */
20
+ export declare function SynapBoard(props: SynapBoardProps): ReactElement;
21
+ /** The adapter over the app's own routes (`createBoardHandlers`, `@synap-core/sdk/connect`). */
22
+ export declare function createHttpBoardAdapter(options?: HttpBoardAdapterOptions): BoardDataAdapter;
@@ -0,0 +1,24 @@
1
+ /** The words `<SynapBoard>` writes (chrome; what people draw is content). */
2
+ export const BOARD_COPY = {
3
+ opening: "Opening the board…",
4
+ retry: "Try again",
5
+ /** The room could not be opened: by `BoardError.code`, then the default. */
6
+ roomFailed: {
7
+ unauthorized: "Your connection to the pod has ended. Connect again, then open the board.",
8
+ expired: "Your connection to the pod has ended. Connect again, then open the board.",
9
+ forbidden: "This app's connection can't open live boards.",
10
+ not_found: "This board doesn't exist, or isn't shared with you.",
11
+ default: "The board's live room couldn't be opened, so its content can't be shown.",
12
+ } as Record<string, string>,
13
+ unavailable: "Nothing here knows where your pod's live server is, so the board's content can't be loaded.",
14
+ loadFailed: "Your saved board is safe: nothing was changed. If it's open in another tab or window, close that first, then try again.",
15
+ readOnly: "View only",
16
+ placeholder: "Opens in Synap",
17
+ cardFailed: "Couldn’t read this card.",
18
+ noProvider: "<SynapBoard> needs a <BoardDataProvider adapter={…}> above it.",
19
+ noun: "this board",
20
+ } as const;
21
+
22
+ export function roomFailedWords(code: string): string {
23
+ return BOARD_COPY.roomFailed[code] ?? BOARD_COPY.roomFailed.default!;
24
+ }
@@ -0,0 +1,57 @@
1
+ /**
2
+ * `createHttpBoardAdapter()`: the board's data calls against the app's own
3
+ * routes (`createBoardHandlers` from `@synap-core/sdk/connect`, mounted at
4
+ * `basePath`). Same-origin, cookies included: the pod token stays on the app's
5
+ * server; the browser only ever holds a single-use room ticket.
6
+ */
7
+ import {
8
+ BoardReadError,
9
+ type BoardDataAdapter,
10
+ type BoardEntity,
11
+ type BoardError,
12
+ type BoardRoomTicket,
13
+ type HttpBoardAdapterOptions,
14
+ } from "./types";
15
+
16
+ function errorOf(body: unknown, status: number): BoardError {
17
+ const e = (body as { error?: Partial<BoardError> } | null)?.error;
18
+ return {
19
+ code: typeof e?.code === "string" ? e.code : "server",
20
+ // The route's own `status` wins, null included (nothing answered: the SDK refused).
21
+ status: e && "status" in e ? (typeof e.status === "number" ? e.status : null) : status,
22
+ ...(typeof e?.detail === "string" ? { detail: e.detail } : {}),
23
+ };
24
+ }
25
+
26
+ export function createHttpBoardAdapter(options: HttpBoardAdapterOptions = {}): BoardDataAdapter {
27
+ const base = (options.basePath ?? "/api/synap/board").replace(/\/+$/, "");
28
+ const doFetch = () => options.fetch ?? fetch;
29
+
30
+ async function call<T>(method: "GET" | "POST", path: string, payload?: unknown): Promise<T> {
31
+ let res: Response;
32
+ try {
33
+ res = await doFetch()(`${base}${path}`, {
34
+ method,
35
+ credentials: "same-origin",
36
+ headers: payload === undefined ? { accept: "application/json" } : { accept: "application/json", "content-type": "application/json" },
37
+ ...(payload === undefined ? {} : { body: JSON.stringify(payload) }),
38
+ });
39
+ } catch (err) {
40
+ throw new BoardReadError({ code: "unreachable", status: null, detail: err instanceof Error ? err.message : String(err) });
41
+ }
42
+ let body: unknown = null;
43
+ try {
44
+ body = await res.json();
45
+ } catch {
46
+ body = null;
47
+ }
48
+ const b = body as { ok?: boolean; data?: T } | null;
49
+ if (res.status !== 200 || b?.ok !== true || b.data === undefined) throw new BoardReadError(errorOf(body, res.status));
50
+ return b.data;
51
+ }
52
+
53
+ return {
54
+ roomTicket: (documentId) => call<BoardRoomTicket>("POST", "/room-ticket", { documentId }),
55
+ getEntity: (id) => call<BoardEntity>("GET", `/entities/${encodeURIComponent(id)}`),
56
+ };
57
+ }
@@ -0,0 +1,17 @@
1
+ /**
2
+ * `@synap-core/react/whiteboard`: the pod's tldraw board for a pod app, over a
3
+ * data adapter (`BoardDataProvider`). Import the styles once:
4
+ * `import "@tldraw/tldraw/tldraw.css"` and `import "@synap-core/react/whiteboard.css"`.
5
+ *
6
+ * Every export is typed by `./api` (the published declarations).
7
+ */
8
+ import "./whiteboard-base.css";
9
+ import type * as Api from "./api";
10
+ import { BoardDataProvider as Provider } from "./provider";
11
+ import { SynapBoard as Board } from "./SynapBoard";
12
+ import { createHttpBoardAdapter as httpAdapter } from "./http-adapter";
13
+
14
+ export * from "./types";
15
+ export const BoardDataProvider: typeof Api.BoardDataProvider = Provider;
16
+ export const SynapBoard: typeof Api.SynapBoard = Board;
17
+ export const createHttpBoardAdapter: typeof Api.createHttpBoardAdapter = httpAdapter;
@@ -0,0 +1,7 @@
1
+ /**
2
+ * Stands in for `@synap-core/web`'s `whiteboard/data/default-source` in this
3
+ * package's whiteboard build (tsup.config.ts): a pod app has no default data
4
+ * source, it mounts `<BoardDataProvider>`. Keeping the desktop's out of the
5
+ * graph is what keeps `@synap-core/hooks` and the pod client out of the bundle.
6
+ */
7
+ export const defaultBoardData = (): null => null;
@@ -0,0 +1,14 @@
1
+ /**
2
+ * `<BoardDataProvider adapter>`: the app's data calls, for every Synap board
3
+ * below it.
4
+ */
5
+ import React, { useMemo } from "react";
6
+ import { BoardDataContext } from "@synap-core/web/whiteboard/embeddable";
7
+ import { createReadCache } from "../shared/read-cache";
8
+ import { adapterSource } from "./adapter-source";
9
+ import type { BoardDataProviderProps } from "./types";
10
+
11
+ export function BoardDataProvider({ adapter, children }: BoardDataProviderProps) {
12
+ const source = useMemo(() => adapterSource(adapter, createReadCache()), [adapter]);
13
+ return <BoardDataContext.Provider value={source}>{children}</BoardDataContext.Provider>;
14
+ }
@@ -0,0 +1,157 @@
1
+ /**
2
+ * The board's shapes as a pod app draws them. A board saved on the desktop
3
+ * holds records of the pod's own shape types (`entityCard`, `view`, `cell`,
4
+ * `artboard`, `sticky`, `synap-frame`; pinned in web
5
+ * `whiteboard/__tripwires__/persisted-names.tripwire.test.ts`). tldraw refuses a
6
+ * record whose type has no util, so an app registers EVERY one of them: the
7
+ * data-free ones as the desktop draws them (sticky, legacy frame), an entity
8
+ * card read through the board's data source, and a named placeholder for what
9
+ * only the desktop can draw (a live view, a cell, an artboard). Nothing is
10
+ * dropped, and the app writes those records back untouched.
11
+ *
12
+ * Out of v1 (plan 7bc196a7 S): inline editing of a card, brand projection,
13
+ * placement, the session stream.
14
+ */
15
+ import React, { useContext } from "react";
16
+ import {
17
+ BaseBoxShapeUtil,
18
+ HTMLContainer,
19
+ Rectangle2d,
20
+ type TLBaseShape,
21
+ type TLShapeUtilConstructor,
22
+ } from "@tldraw/tldraw";
23
+ import {
24
+ BoardDataContext,
25
+ FrameShapeUtil,
26
+ StickyShapeUtil,
27
+ } from "@synap-core/web/whiteboard/embeddable";
28
+ import { BOARD_COPY } from "./copy";
29
+
30
+ /** The desktop's entity card footprint (web `ENTITY_CARD_SIZE`; pinned by whiteboard-shapes.test.ts). */
31
+ export const APP_ENTITY_CARD_SIZE = { w: 240, h: 160 } as const;
32
+
33
+ export type AppEntityCardShape = TLBaseShape<
34
+ "entityCard",
35
+ {
36
+ w: number;
37
+ h: number;
38
+ entityId: string;
39
+ entityType: string;
40
+ title: string;
41
+ properties: Record<string, unknown>;
42
+ [key: string]: unknown;
43
+ }
44
+ >;
45
+
46
+ /** What a card names, for `onObjectClick`. */
47
+ export function cardTarget(shape: { type: string; props: Record<string, unknown> }): { id: string; kind: string } | null {
48
+ if (shape.type !== "entityCard") return null;
49
+ const id = shape.props.entityId;
50
+ if (typeof id !== "string" || !id) return null;
51
+ const kind = typeof shape.props.entityType === "string" && shape.props.entityType ? shape.props.entityType : "entity";
52
+ return { id, kind };
53
+ }
54
+
55
+ function AppEntityCard({ shape }: { shape: AppEntityCardShape }) {
56
+ const source = useContext(BoardDataContext);
57
+ if (!source) throw new Error(BOARD_COPY.noProvider);
58
+ const { entityId, title, entityType } = shape.props;
59
+ const read = source.useEntityCard(entityId, { enabled: !!entityId });
60
+ const shownTitle = read.entity?.title || title || BOARD_COPY.placeholder;
61
+ const kind = read.entity?.profileSlug ?? entityType;
62
+ return (
63
+ <HTMLContainer
64
+ className="synap-board__card"
65
+ data-failed={read.error ? "" : undefined}
66
+ style={{ width: shape.props.w, height: shape.props.h }}
67
+ >
68
+ {kind ? <span className="synap-board__card-kind">{kind}</span> : null}
69
+ <span className="synap-board__card-title">{shownTitle}</span>
70
+ {read.entity?.status ? <span className="synap-board__card-status">{read.entity.status}</span> : null}
71
+ {read.error ? (
72
+ <span className="synap-board__card-failed" role="status">
73
+ {BOARD_COPY.cardFailed}
74
+ </span>
75
+ ) : null}
76
+ </HTMLContainer>
77
+ );
78
+ }
79
+
80
+ export class AppEntityCardShapeUtil extends BaseBoxShapeUtil<AppEntityCardShape> {
81
+ static override type = "entityCard" as const;
82
+
83
+ // As the desktop's: no props validator, so no key may hold `undefined`.
84
+ override getDefaultProps(): AppEntityCardShape["props"] {
85
+ return {
86
+ w: APP_ENTITY_CARD_SIZE.w,
87
+ h: APP_ENTITY_CARD_SIZE.h,
88
+ entityId: "",
89
+ entityType: "task",
90
+ profileId: null,
91
+ title: "New Card",
92
+ properties: {},
93
+ progress: 0,
94
+ };
95
+ }
96
+
97
+ override getGeometry(shape: AppEntityCardShape) {
98
+ return new Rectangle2d({ width: shape.props.w, height: shape.props.h, isFilled: true });
99
+ }
100
+
101
+ override component(shape: AppEntityCardShape) {
102
+ return <AppEntityCard shape={shape} />;
103
+ }
104
+
105
+ override indicator(shape: AppEntityCardShape) {
106
+ return <rect width={shape.props.w} height={shape.props.h} rx={12} />;
107
+ }
108
+
109
+ override canEdit = () => false;
110
+ }
111
+
112
+ type PlaceholderShape<T extends string> = TLBaseShape<T, { w: number; h: number; title?: string; [key: string]: unknown }>;
113
+
114
+ /** What only the desktop draws: the shape keeps its place and its record; the app names it. */
115
+ function placeholderUtil<T extends string>(type: T) {
116
+ return class AppPlaceholderShapeUtil extends BaseBoxShapeUtil<PlaceholderShape<T>> {
117
+ static override type = type;
118
+
119
+ override getDefaultProps(): PlaceholderShape<T>["props"] {
120
+ return { w: 300, h: 200 };
121
+ }
122
+
123
+ override getGeometry(shape: PlaceholderShape<T>) {
124
+ return new Rectangle2d({ width: shape.props.w, height: shape.props.h, isFilled: true });
125
+ }
126
+
127
+ override component(shape: PlaceholderShape<T>) {
128
+ const title = typeof shape.props.title === "string" ? shape.props.title : "";
129
+ return (
130
+ <HTMLContainer className="synap-board__placeholder" data-shape-type={type} style={{ width: shape.props.w, height: shape.props.h }}>
131
+ {title ? <span className="synap-board__card-title">{title}</span> : null}
132
+ <span className="synap-board__card-kind">{BOARD_COPY.placeholder}</span>
133
+ </HTMLContainer>
134
+ );
135
+ }
136
+
137
+ override indicator(shape: PlaceholderShape<T>) {
138
+ return <rect width={shape.props.w} height={shape.props.h} rx={12} />;
139
+ }
140
+
141
+ override canEdit = () => false;
142
+ };
143
+ }
144
+
145
+ export const AppViewShapeUtil = placeholderUtil("view");
146
+ export const AppCellShapeUtil = placeholderUtil("cell");
147
+ export const AppArtboardShapeUtil = placeholderUtil("artboard");
148
+
149
+ /** Every custom shape type a stored board may hold, as the app draws it. */
150
+ export const APP_SHAPE_UTILS: TLShapeUtilConstructor<any>[] = [
151
+ AppEntityCardShapeUtil,
152
+ AppViewShapeUtil,
153
+ AppCellShapeUtil,
154
+ AppArtboardShapeUtil,
155
+ StickyShapeUtil,
156
+ FrameShapeUtil,
157
+ ];
@@ -0,0 +1,99 @@
1
+ /**
2
+ * The public types of `@synap-core/react/whiteboard`. Self-contained on
3
+ * purpose: the published `whiteboard.d.ts` is built from THIS module (tsup
4
+ * `dts.entry`), so a refactor inside the bundled board cannot change the API an
5
+ * app compiles against without a change here (snapshot: `api/whiteboard.d.ts`).
6
+ */
7
+ import type { ReactNode } from "react";
8
+
9
+ /**
10
+ * A short-lived, single-use pass into one board's live room, as the pod mints
11
+ * it (`POST /api/hub/realtime/room-ticket`) for the connection's person.
12
+ */
13
+ export interface BoardRoomTicket {
14
+ ticket: string;
15
+ /** ISO 8601. A ticket is used once, before this. */
16
+ expiresAt: string;
17
+ /** The person the ticket opens the room as (the handshake's `userId`). */
18
+ userId: string;
19
+ /** What the room will take from this person: `edit`, or `read` (the board is read-only). */
20
+ access: "read" | "edit";
21
+ /** The pod's realtime server, where the room socket connects. */
22
+ url: string;
23
+ }
24
+
25
+ /** An entity as a board card shows it. */
26
+ export interface BoardEntity {
27
+ id: string;
28
+ title: string | null;
29
+ profileSlug: string | null;
30
+ status: string | null;
31
+ }
32
+
33
+ /** Why a call failed. `code` is what to do (`unauthorized`: connect again; `forbidden`: no access). */
34
+ export interface BoardError {
35
+ code: string;
36
+ /** The HTTP status, or null when nothing answered. */
37
+ status: number | null;
38
+ /** For logs only, never a headline. */
39
+ detail?: string;
40
+ }
41
+
42
+ /** A read that failed: thrown by an adapter's calls, so it is never shown as an empty board. */
43
+ export class BoardReadError extends Error {
44
+ readonly error: BoardError;
45
+ constructor(error: BoardError) {
46
+ super(`Synap board read failed: ${error.code}${error.status ? ` (${error.status})` : ""}`);
47
+ this.name = "BoardReadError";
48
+ this.error = error;
49
+ }
50
+ }
51
+
52
+ /**
53
+ * The board's data calls. Each throws `BoardReadError` on failure.
54
+ * `createHttpBoardAdapter` implements it against the app's own routes
55
+ * (`createBoardHandlers` in `@synap-core/sdk/connect`); a test or a story can
56
+ * implement it in memory.
57
+ */
58
+ export interface BoardDataAdapter {
59
+ /** A fresh ticket for the board document's room; asked before every (re)connect. */
60
+ roomTicket(documentId: string): Promise<BoardRoomTicket>;
61
+ /** One entity, for a card placed on the board. */
62
+ getEntity(id: string): Promise<BoardEntity>;
63
+ }
64
+
65
+ export interface BoardDataProviderProps {
66
+ adapter: BoardDataAdapter;
67
+ children?: ReactNode;
68
+ }
69
+
70
+ /** Who this browser is on the board: a name and colour for the cursor others see. */
71
+ export interface BoardUser {
72
+ id: string;
73
+ name: string;
74
+ /** A CSS colour. */
75
+ color: string;
76
+ }
77
+
78
+ export interface SynapBoardProps {
79
+ /** The board's document (a whiteboard view's `documentId`). */
80
+ documentId: string;
81
+ /** This person's cursor. Omitted: an anonymous id kept on this device, named "You". */
82
+ user?: BoardUser;
83
+ /**
84
+ * The tldraw licence key, forwarded to tldraw as it is. Omitted: tldraw runs
85
+ * as it does with no key. The host owns the key; it is never bundled.
86
+ */
87
+ licenseKey?: string;
88
+ /** Keep the board read-only even when the room takes this person's writes. */
89
+ readOnly?: boolean;
90
+ /** Opens an object a card names (`id`, its kind). Omitted: double-clicking a card does nothing. */
91
+ onObjectClick?: (id: string, kind: string) => void;
92
+ className?: string;
93
+ }
94
+
95
+ export interface HttpBoardAdapterOptions {
96
+ /** Where the app mounted `createBoardHandlers`. Default `/api/synap/board`. */
97
+ basePath?: string;
98
+ fetch?: typeof fetch;
99
+ }
@@ -0,0 +1,87 @@
1
+ /*
2
+ * @synap-core/react/whiteboard.css: the board's chrome and card styles, bundled
3
+ * into one file with the component CSS they import. The `--synap-*` tokens come
4
+ * first, so a host overrides any of them after this file. tldraw's own styles
5
+ * are the host's import: `import "@tldraw/tldraw/tldraw.css"`.
6
+ */
7
+ @import "@synap-core/design-tokens/synap-tokens.css";
8
+ @import "@synap-core/web/spatial-ui/styles.css";
9
+
10
+ /* A full-bleed canvas IS the ground (ui-rules "Canvas surfaces"). */
11
+ .synap-board {
12
+ position: relative;
13
+ display: flex;
14
+ flex-direction: column;
15
+ align-items: center;
16
+ justify-content: center;
17
+ gap: var(--synap-space-150);
18
+ width: 100%;
19
+ height: 100%;
20
+ min-height: 320px;
21
+ background: var(--synap-background);
22
+ }
23
+ .synap-board > .tl-container {
24
+ position: absolute;
25
+ inset: 0;
26
+ }
27
+ .synap-board__note {
28
+ font-family: var(--synap-type-caption-family);
29
+ font-size: var(--synap-type-caption-size);
30
+ font-weight: var(--synap-type-caption-weight);
31
+ line-height: var(--synap-type-caption-leading);
32
+ color: var(--synap-muted);
33
+ }
34
+ .synap-board__banner {
35
+ position: absolute;
36
+ inset-block-start: var(--synap-space-200);
37
+ inset-inline-end: var(--synap-space-200);
38
+ padding: var(--synap-space-075) var(--synap-space-125);
39
+ border: 1px solid var(--synap-border-color);
40
+ border-radius: var(--synap-radius-chip);
41
+ background: var(--synap-background);
42
+ font-family: var(--synap-type-caption-family);
43
+ font-size: var(--synap-type-caption-size);
44
+ font-weight: var(--synap-type-caption-weight);
45
+ line-height: var(--synap-type-caption-leading);
46
+ color: var(--synap-muted);
47
+ pointer-events: none;
48
+ }
49
+
50
+ /* A card on the board: an island (card ring + resting elevation). */
51
+ .synap-board__card,
52
+ .synap-board__placeholder {
53
+ display: flex;
54
+ flex-direction: column;
55
+ gap: var(--synap-space-075);
56
+ padding: var(--synap-space-150);
57
+ border-radius: var(--synap-radius-card);
58
+ background: var(--synap-paper);
59
+ box-shadow: var(--synap-shadow-card);
60
+ overflow: hidden;
61
+ pointer-events: all;
62
+ }
63
+ .synap-board__placeholder {
64
+ align-items: center;
65
+ justify-content: center;
66
+ border: 1px dashed var(--synap-border-color);
67
+ box-shadow: none;
68
+ }
69
+ .synap-board__card-kind,
70
+ .synap-board__card-status,
71
+ .synap-board__card-failed {
72
+ font-family: var(--synap-type-label-family);
73
+ font-size: var(--synap-type-label-size);
74
+ font-weight: var(--synap-type-label-weight);
75
+ line-height: var(--synap-type-label-leading);
76
+ color: var(--synap-muted);
77
+ }
78
+ .synap-board__card-title {
79
+ font-family: var(--synap-type-heading-family);
80
+ font-size: var(--synap-type-heading-size);
81
+ font-weight: var(--synap-type-heading-weight);
82
+ line-height: var(--synap-type-heading-leading);
83
+ color: var(--synap-foreground);
84
+ }
85
+ .synap-board__card-failed {
86
+ color: var(--synap-tone-error-ink);
87
+ }