@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,104 @@
1
+ import { ReactNode, ReactElement } from 'react';
2
+
3
+ /**
4
+ * The public types of `@synap-core/react/whiteboard`. Self-contained on
5
+ * purpose: the published `whiteboard.d.ts` is built from THIS module (tsup
6
+ * `dts.entry`), so a refactor inside the bundled board cannot change the API an
7
+ * app compiles against without a change here (snapshot: `api/whiteboard.d.ts`).
8
+ */
9
+
10
+ /**
11
+ * A short-lived, single-use pass into one board's live room, as the pod mints
12
+ * it (`POST /api/hub/realtime/room-ticket`) for the connection's person.
13
+ */
14
+ interface BoardRoomTicket {
15
+ ticket: string;
16
+ /** ISO 8601. A ticket is used once, before this. */
17
+ expiresAt: string;
18
+ /** The person the ticket opens the room as (the handshake's `userId`). */
19
+ userId: string;
20
+ /** What the room will take from this person: `edit`, or `read` (the board is read-only). */
21
+ access: "read" | "edit";
22
+ /** The pod's realtime server, where the room socket connects. */
23
+ url: string;
24
+ }
25
+ /** An entity as a board card shows it. */
26
+ interface BoardEntity {
27
+ id: string;
28
+ title: string | null;
29
+ profileSlug: string | null;
30
+ status: string | null;
31
+ }
32
+ /** Why a call failed. `code` is what to do (`unauthorized`: connect again; `forbidden`: no access). */
33
+ interface BoardError {
34
+ code: string;
35
+ /** The HTTP status, or null when nothing answered. */
36
+ status: number | null;
37
+ /** For logs only, never a headline. */
38
+ detail?: string;
39
+ }
40
+ /** A read that failed: thrown by an adapter's calls, so it is never shown as an empty board. */
41
+ declare class BoardReadError extends Error {
42
+ readonly error: BoardError;
43
+ constructor(error: BoardError);
44
+ }
45
+ /**
46
+ * The board's data calls. Each throws `BoardReadError` on failure.
47
+ * `createHttpBoardAdapter` implements it against the app's own routes
48
+ * (`createBoardHandlers` in `@synap-core/sdk/connect`); a test or a story can
49
+ * implement it in memory.
50
+ */
51
+ interface BoardDataAdapter {
52
+ /** A fresh ticket for the board document's room; asked before every (re)connect. */
53
+ roomTicket(documentId: string): Promise<BoardRoomTicket>;
54
+ /** One entity, for a card placed on the board. */
55
+ getEntity(id: string): Promise<BoardEntity>;
56
+ }
57
+ interface BoardDataProviderProps {
58
+ adapter: BoardDataAdapter;
59
+ children?: ReactNode;
60
+ }
61
+ /** Who this browser is on the board: a name and colour for the cursor others see. */
62
+ interface BoardUser {
63
+ id: string;
64
+ name: string;
65
+ /** A CSS colour. */
66
+ color: string;
67
+ }
68
+ interface SynapBoardProps {
69
+ /** The board's document (a whiteboard view's `documentId`). */
70
+ documentId: string;
71
+ /** This person's cursor. Omitted: an anonymous id kept on this device, named "You". */
72
+ user?: BoardUser;
73
+ /**
74
+ * The tldraw licence key, forwarded to tldraw as it is. Omitted: tldraw runs
75
+ * as it does with no key. The host owns the key; it is never bundled.
76
+ */
77
+ licenseKey?: string;
78
+ /** Keep the board read-only even when the room takes this person's writes. */
79
+ readOnly?: boolean;
80
+ /** Opens an object a card names (`id`, its kind). Omitted: double-clicking a card does nothing. */
81
+ onObjectClick?: (id: string, kind: string) => void;
82
+ className?: string;
83
+ }
84
+ interface HttpBoardAdapterOptions {
85
+ /** Where the app mounted `createBoardHandlers`. Default `/api/synap/board`. */
86
+ basePath?: string;
87
+ fetch?: typeof fetch;
88
+ }
89
+
90
+ /**
91
+ * The declared API of `@synap-core/react/whiteboard`: what `dist/whiteboard.d.ts`
92
+ * is built from (tsup `dts.entry`). `index.ts` binds each value to its type
93
+ * here, so the implementation cannot drift from it without a type error, and
94
+ * the snapshot test (`api/whiteboard.d.ts`) makes every change to it deliberate.
95
+ */
96
+
97
+ /** Every Synap board below it reads through `adapter`. */
98
+ declare function BoardDataProvider(props: BoardDataProviderProps): ReactElement;
99
+ /** The pod's tldraw board on one board document, joined live through a room ticket. */
100
+ declare function SynapBoard(props: SynapBoardProps): ReactElement;
101
+ /** The adapter over the app's own routes (`createBoardHandlers`, `@synap-core/sdk/connect`). */
102
+ declare function createHttpBoardAdapter(options?: HttpBoardAdapterOptions): BoardDataAdapter;
103
+
104
+ export { type BoardDataAdapter, BoardDataProvider, type BoardDataProviderProps, type BoardEntity, type BoardError, BoardReadError, type BoardRoomTicket, type BoardUser, type HttpBoardAdapterOptions, SynapBoard, type SynapBoardProps, createHttpBoardAdapter };
@@ -0,0 +1,104 @@
1
+ import { ReactNode, ReactElement } from 'react';
2
+
3
+ /**
4
+ * The public types of `@synap-core/react/whiteboard`. Self-contained on
5
+ * purpose: the published `whiteboard.d.ts` is built from THIS module (tsup
6
+ * `dts.entry`), so a refactor inside the bundled board cannot change the API an
7
+ * app compiles against without a change here (snapshot: `api/whiteboard.d.ts`).
8
+ */
9
+
10
+ /**
11
+ * A short-lived, single-use pass into one board's live room, as the pod mints
12
+ * it (`POST /api/hub/realtime/room-ticket`) for the connection's person.
13
+ */
14
+ interface BoardRoomTicket {
15
+ ticket: string;
16
+ /** ISO 8601. A ticket is used once, before this. */
17
+ expiresAt: string;
18
+ /** The person the ticket opens the room as (the handshake's `userId`). */
19
+ userId: string;
20
+ /** What the room will take from this person: `edit`, or `read` (the board is read-only). */
21
+ access: "read" | "edit";
22
+ /** The pod's realtime server, where the room socket connects. */
23
+ url: string;
24
+ }
25
+ /** An entity as a board card shows it. */
26
+ interface BoardEntity {
27
+ id: string;
28
+ title: string | null;
29
+ profileSlug: string | null;
30
+ status: string | null;
31
+ }
32
+ /** Why a call failed. `code` is what to do (`unauthorized`: connect again; `forbidden`: no access). */
33
+ interface BoardError {
34
+ code: string;
35
+ /** The HTTP status, or null when nothing answered. */
36
+ status: number | null;
37
+ /** For logs only, never a headline. */
38
+ detail?: string;
39
+ }
40
+ /** A read that failed: thrown by an adapter's calls, so it is never shown as an empty board. */
41
+ declare class BoardReadError extends Error {
42
+ readonly error: BoardError;
43
+ constructor(error: BoardError);
44
+ }
45
+ /**
46
+ * The board's data calls. Each throws `BoardReadError` on failure.
47
+ * `createHttpBoardAdapter` implements it against the app's own routes
48
+ * (`createBoardHandlers` in `@synap-core/sdk/connect`); a test or a story can
49
+ * implement it in memory.
50
+ */
51
+ interface BoardDataAdapter {
52
+ /** A fresh ticket for the board document's room; asked before every (re)connect. */
53
+ roomTicket(documentId: string): Promise<BoardRoomTicket>;
54
+ /** One entity, for a card placed on the board. */
55
+ getEntity(id: string): Promise<BoardEntity>;
56
+ }
57
+ interface BoardDataProviderProps {
58
+ adapter: BoardDataAdapter;
59
+ children?: ReactNode;
60
+ }
61
+ /** Who this browser is on the board: a name and colour for the cursor others see. */
62
+ interface BoardUser {
63
+ id: string;
64
+ name: string;
65
+ /** A CSS colour. */
66
+ color: string;
67
+ }
68
+ interface SynapBoardProps {
69
+ /** The board's document (a whiteboard view's `documentId`). */
70
+ documentId: string;
71
+ /** This person's cursor. Omitted: an anonymous id kept on this device, named "You". */
72
+ user?: BoardUser;
73
+ /**
74
+ * The tldraw licence key, forwarded to tldraw as it is. Omitted: tldraw runs
75
+ * as it does with no key. The host owns the key; it is never bundled.
76
+ */
77
+ licenseKey?: string;
78
+ /** Keep the board read-only even when the room takes this person's writes. */
79
+ readOnly?: boolean;
80
+ /** Opens an object a card names (`id`, its kind). Omitted: double-clicking a card does nothing. */
81
+ onObjectClick?: (id: string, kind: string) => void;
82
+ className?: string;
83
+ }
84
+ interface HttpBoardAdapterOptions {
85
+ /** Where the app mounted `createBoardHandlers`. Default `/api/synap/board`. */
86
+ basePath?: string;
87
+ fetch?: typeof fetch;
88
+ }
89
+
90
+ /**
91
+ * The declared API of `@synap-core/react/whiteboard`: what `dist/whiteboard.d.ts`
92
+ * is built from (tsup `dts.entry`). `index.ts` binds each value to its type
93
+ * here, so the implementation cannot drift from it without a type error, and
94
+ * the snapshot test (`api/whiteboard.d.ts`) makes every change to it deliberate.
95
+ */
96
+
97
+ /** Every Synap board below it reads through `adapter`. */
98
+ declare function BoardDataProvider(props: BoardDataProviderProps): ReactElement;
99
+ /** The pod's tldraw board on one board document, joined live through a room ticket. */
100
+ declare function SynapBoard(props: SynapBoardProps): ReactElement;
101
+ /** The adapter over the app's own routes (`createBoardHandlers`, `@synap-core/sdk/connect`). */
102
+ declare function createHttpBoardAdapter(options?: HttpBoardAdapterOptions): BoardDataAdapter;
103
+
104
+ export { type BoardDataAdapter, BoardDataProvider, type BoardDataProviderProps, type BoardEntity, type BoardError, BoardReadError, type BoardRoomTicket, type BoardUser, type HttpBoardAdapterOptions, SynapBoard, type SynapBoardProps, createHttpBoardAdapter };