@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,178 @@
1
+ import { ReactNode, ReactElement } from 'react';
2
+
3
+ /**
4
+ * The public types of `@synap-core/react/editor`. Self-contained on purpose:
5
+ * the published `editor.d.ts` is built from THIS module (tsup `dts.entry`), so
6
+ * a refactor inside the bundled editor cannot change the API an app compiles
7
+ * against without a change here (snapshot: `api/editor.d.ts`).
8
+ */
9
+
10
+ /**
11
+ * What an id names, as the pod's `GET /api/hub/resolve/:id` answers it.
12
+ * `type: "unknown"` = nothing this reader can see has the id (not a failure).
13
+ */
14
+ interface ResolvedRef {
15
+ type: string;
16
+ displayName?: string | null;
17
+ openable?: boolean | null;
18
+ profileSlug?: string | null;
19
+ }
20
+ /** An entity row the `@` picker searches. */
21
+ interface EditorEntity {
22
+ id: string;
23
+ title?: string | null;
24
+ profileSlug?: string;
25
+ }
26
+ /** A view row the `@` picker and the `/` menu's "Saved views" list. */
27
+ interface EditorView {
28
+ id: string;
29
+ name?: string;
30
+ type?: string;
31
+ }
32
+ /** A document as the editor loads it. */
33
+ interface EditorDocument {
34
+ id: string;
35
+ title: string;
36
+ content: string;
37
+ /** Pass back as `baseRevision` when saving. */
38
+ revision: number;
39
+ workspaceId: string | null;
40
+ }
41
+ /** Why a call failed. `code` is what to do (`conflict`: reload; `unauthorized`: connect again). */
42
+ interface EditorError {
43
+ code: string;
44
+ /** The HTTP status, or null when nothing answered. */
45
+ status: number | null;
46
+ /** For logs only, never a headline. */
47
+ detail?: string;
48
+ }
49
+ /** What the pod did with a write: applied, filed for the person's review, or refused. */
50
+ type EditorWriteResult = {
51
+ ok: true;
52
+ status: "applied";
53
+ } | {
54
+ ok: true;
55
+ status: "proposed";
56
+ reviewUrl: string;
57
+ } | {
58
+ ok: false;
59
+ error: EditorError;
60
+ };
61
+ /** A read that failed: thrown by an adapter's reads, so it is never shown as empty. */
62
+ declare class EditorReadError extends Error {
63
+ readonly error: EditorError;
64
+ constructor(error: EditorError);
65
+ }
66
+ /**
67
+ * The editor's data calls. Reads throw (`EditorReadError`) on failure; writes
68
+ * answer what the pod did. `createHttpEditorAdapter` implements it against the
69
+ * app's own routes (`createEditorHandlers` in `@synap-core/sdk/connect`); a test
70
+ * or a story can implement it in memory.
71
+ */
72
+ interface EditorDataAdapter {
73
+ /** What an id names, for a reference chip. */
74
+ resolveRef(id: string): Promise<ResolvedRef>;
75
+ /** The entities of a space, for the `@` picker. */
76
+ listEntities(workspaceId: string): Promise<EditorEntity[]>;
77
+ /** The views of a space, for the `@` picker and the `/` menu. */
78
+ listViews(workspaceId: string): Promise<EditorView[]>;
79
+ getDocument(id: string): Promise<EditorDocument>;
80
+ /** Replace the document's markdown, guarded by `baseRevision`. */
81
+ saveDocument(id: string, markdown: string, baseRevision: number): Promise<EditorWriteResult>;
82
+ /** Write a relation `sourceId --type--> targetId` (a dropped object). */
83
+ linkObjects(input: {
84
+ sourceId: string;
85
+ targetId: string;
86
+ type: string;
87
+ }): Promise<EditorWriteResult>;
88
+ }
89
+ /** A pod object being dragged onto the editor (`text/x-synap-object`). */
90
+ interface SynapDraggedObject {
91
+ id: string;
92
+ /** `entity`, `view`, `document`, or a profile slug (`post`, `person`…). */
93
+ kind: string;
94
+ label: string;
95
+ }
96
+ /** A `:::synap-*` embed, for a host that draws embeds itself (`renderEmbed`). */
97
+ interface SynapEmbed {
98
+ directive: "synap-cell" | "synap-entity" | "synap-view";
99
+ /** Reference attributes as authored (`id`, `viewId`, `cellKey`, `instanceId`). */
100
+ reference: Record<string, string>;
101
+ props?: Record<string, unknown> | null;
102
+ /** The author's fallback, rendered. */
103
+ fallback?: ReactNode;
104
+ }
105
+ interface EditorDataProviderProps {
106
+ adapter: EditorDataAdapter;
107
+ /**
108
+ * Draws a `:::synap-*` embed. Omitted: the author's fallback, or a chip
109
+ * naming the embedded object. Return null to draw the default.
110
+ */
111
+ renderEmbed?: (embed: SynapEmbed) => ReactNode;
112
+ children?: ReactNode;
113
+ }
114
+ interface SynapEditorProps {
115
+ documentId: string;
116
+ /**
117
+ * The entity this document belongs to (e.g. the content piece). A dropped
118
+ * object is linked FROM it (`linkObjects`). Omitted: a drop inserts the chip
119
+ * and links nothing.
120
+ */
121
+ subjectId?: string;
122
+ /** The relation a drop writes. Default `"references"`. */
123
+ relationType?: string;
124
+ /** The space the `@` picker searches. Default: the document's own. */
125
+ workspaceId?: string;
126
+ /** Save this long after the last keystroke, in ms. Default 1500. */
127
+ autoSaveMs?: number;
128
+ editable?: boolean;
129
+ /** Opens an object a chip names (`id`, its kind). Omitted: chips are not buttons. */
130
+ onObjectClick?: (id: string, kind: string) => void;
131
+ /**
132
+ * The mounted editor's handle, for edits made from beside it (dictation, a
133
+ * quoted idea); null when it unmounts. Its edits save like typing.
134
+ */
135
+ onReady?: (handle: SynapEditorHandle | null) => void;
136
+ className?: string;
137
+ }
138
+ /** Edits a host makes from beside `<SynapEditor>`: each is the person's own, saved like typing. */
139
+ interface SynapEditorHandle {
140
+ /** The document as markdown, as the next save would send it. */
141
+ getMarkdown(): string;
142
+ /** Plain text at the caret (never parsed as markdown). */
143
+ insertText(text: string): void;
144
+ /** Markdown blocks after the last one. */
145
+ appendMarkdown(markdown: string): void;
146
+ }
147
+ interface SynapMarkdownProps {
148
+ content: string;
149
+ onObjectClick?: (id: string, kind: string) => void;
150
+ className?: string;
151
+ }
152
+ interface HttpEditorAdapterOptions {
153
+ /** Where the app mounted `createEditorHandlers`. Default `/api/synap/editor`. */
154
+ basePath?: string;
155
+ fetch?: typeof fetch;
156
+ }
157
+
158
+ /**
159
+ * The declared API of `@synap-core/react/editor`: what `dist/editor.d.ts` is
160
+ * built from (tsup `dts.entry`). `index.ts` binds each value to its type here,
161
+ * so the implementation cannot drift from it without a type error, and the
162
+ * snapshot test (`api/editor.d.ts`) makes every change to it deliberate.
163
+ */
164
+
165
+ /** Every Synap editor and reader below it reads through `adapter`. */
166
+ declare function EditorDataProvider(props: EditorDataProviderProps): ReactElement;
167
+ /** The pod's markdown editor on one document: load, autosave with `baseRevision`, drop-to-link. */
168
+ declare function SynapEditor(props: SynapEditorProps): ReactElement | null;
169
+ /** The pod's markdown reader. */
170
+ declare function SynapMarkdown(props: SynapMarkdownProps): ReactElement | null;
171
+ /** The adapter over the app's own routes (`createEditorHandlers`, `@synap-core/sdk/connect`). */
172
+ declare function createHttpEditorAdapter(options?: HttpEditorAdapterOptions): EditorDataAdapter;
173
+ /** The drag payload type `<SynapEditor>` takes: JSON `{ id, kind, label }`. */
174
+ declare const SYNAP_OBJECT_MIME: "text/x-synap-object";
175
+ /** Set a pod object on a drag, so `<SynapEditor>` takes the drop. */
176
+ declare function setSynapObjectDrag(dataTransfer: DataTransfer, object: SynapDraggedObject): void;
177
+
178
+ export { type EditorDataAdapter, EditorDataProvider, type EditorDataProviderProps, type EditorDocument, type EditorEntity, type EditorError, EditorReadError, type EditorView, type EditorWriteResult, type HttpEditorAdapterOptions, type ResolvedRef, SYNAP_OBJECT_MIME, type SynapDraggedObject, SynapEditor, type SynapEditorHandle, type SynapEditorProps, type SynapEmbed, SynapMarkdown, type SynapMarkdownProps, createHttpEditorAdapter, setSynapObjectDrag };
@@ -0,0 +1,178 @@
1
+ import { ReactNode, ReactElement } from 'react';
2
+
3
+ /**
4
+ * The public types of `@synap-core/react/editor`. Self-contained on purpose:
5
+ * the published `editor.d.ts` is built from THIS module (tsup `dts.entry`), so
6
+ * a refactor inside the bundled editor cannot change the API an app compiles
7
+ * against without a change here (snapshot: `api/editor.d.ts`).
8
+ */
9
+
10
+ /**
11
+ * What an id names, as the pod's `GET /api/hub/resolve/:id` answers it.
12
+ * `type: "unknown"` = nothing this reader can see has the id (not a failure).
13
+ */
14
+ interface ResolvedRef {
15
+ type: string;
16
+ displayName?: string | null;
17
+ openable?: boolean | null;
18
+ profileSlug?: string | null;
19
+ }
20
+ /** An entity row the `@` picker searches. */
21
+ interface EditorEntity {
22
+ id: string;
23
+ title?: string | null;
24
+ profileSlug?: string;
25
+ }
26
+ /** A view row the `@` picker and the `/` menu's "Saved views" list. */
27
+ interface EditorView {
28
+ id: string;
29
+ name?: string;
30
+ type?: string;
31
+ }
32
+ /** A document as the editor loads it. */
33
+ interface EditorDocument {
34
+ id: string;
35
+ title: string;
36
+ content: string;
37
+ /** Pass back as `baseRevision` when saving. */
38
+ revision: number;
39
+ workspaceId: string | null;
40
+ }
41
+ /** Why a call failed. `code` is what to do (`conflict`: reload; `unauthorized`: connect again). */
42
+ interface EditorError {
43
+ code: string;
44
+ /** The HTTP status, or null when nothing answered. */
45
+ status: number | null;
46
+ /** For logs only, never a headline. */
47
+ detail?: string;
48
+ }
49
+ /** What the pod did with a write: applied, filed for the person's review, or refused. */
50
+ type EditorWriteResult = {
51
+ ok: true;
52
+ status: "applied";
53
+ } | {
54
+ ok: true;
55
+ status: "proposed";
56
+ reviewUrl: string;
57
+ } | {
58
+ ok: false;
59
+ error: EditorError;
60
+ };
61
+ /** A read that failed: thrown by an adapter's reads, so it is never shown as empty. */
62
+ declare class EditorReadError extends Error {
63
+ readonly error: EditorError;
64
+ constructor(error: EditorError);
65
+ }
66
+ /**
67
+ * The editor's data calls. Reads throw (`EditorReadError`) on failure; writes
68
+ * answer what the pod did. `createHttpEditorAdapter` implements it against the
69
+ * app's own routes (`createEditorHandlers` in `@synap-core/sdk/connect`); a test
70
+ * or a story can implement it in memory.
71
+ */
72
+ interface EditorDataAdapter {
73
+ /** What an id names, for a reference chip. */
74
+ resolveRef(id: string): Promise<ResolvedRef>;
75
+ /** The entities of a space, for the `@` picker. */
76
+ listEntities(workspaceId: string): Promise<EditorEntity[]>;
77
+ /** The views of a space, for the `@` picker and the `/` menu. */
78
+ listViews(workspaceId: string): Promise<EditorView[]>;
79
+ getDocument(id: string): Promise<EditorDocument>;
80
+ /** Replace the document's markdown, guarded by `baseRevision`. */
81
+ saveDocument(id: string, markdown: string, baseRevision: number): Promise<EditorWriteResult>;
82
+ /** Write a relation `sourceId --type--> targetId` (a dropped object). */
83
+ linkObjects(input: {
84
+ sourceId: string;
85
+ targetId: string;
86
+ type: string;
87
+ }): Promise<EditorWriteResult>;
88
+ }
89
+ /** A pod object being dragged onto the editor (`text/x-synap-object`). */
90
+ interface SynapDraggedObject {
91
+ id: string;
92
+ /** `entity`, `view`, `document`, or a profile slug (`post`, `person`…). */
93
+ kind: string;
94
+ label: string;
95
+ }
96
+ /** A `:::synap-*` embed, for a host that draws embeds itself (`renderEmbed`). */
97
+ interface SynapEmbed {
98
+ directive: "synap-cell" | "synap-entity" | "synap-view";
99
+ /** Reference attributes as authored (`id`, `viewId`, `cellKey`, `instanceId`). */
100
+ reference: Record<string, string>;
101
+ props?: Record<string, unknown> | null;
102
+ /** The author's fallback, rendered. */
103
+ fallback?: ReactNode;
104
+ }
105
+ interface EditorDataProviderProps {
106
+ adapter: EditorDataAdapter;
107
+ /**
108
+ * Draws a `:::synap-*` embed. Omitted: the author's fallback, or a chip
109
+ * naming the embedded object. Return null to draw the default.
110
+ */
111
+ renderEmbed?: (embed: SynapEmbed) => ReactNode;
112
+ children?: ReactNode;
113
+ }
114
+ interface SynapEditorProps {
115
+ documentId: string;
116
+ /**
117
+ * The entity this document belongs to (e.g. the content piece). A dropped
118
+ * object is linked FROM it (`linkObjects`). Omitted: a drop inserts the chip
119
+ * and links nothing.
120
+ */
121
+ subjectId?: string;
122
+ /** The relation a drop writes. Default `"references"`. */
123
+ relationType?: string;
124
+ /** The space the `@` picker searches. Default: the document's own. */
125
+ workspaceId?: string;
126
+ /** Save this long after the last keystroke, in ms. Default 1500. */
127
+ autoSaveMs?: number;
128
+ editable?: boolean;
129
+ /** Opens an object a chip names (`id`, its kind). Omitted: chips are not buttons. */
130
+ onObjectClick?: (id: string, kind: string) => void;
131
+ /**
132
+ * The mounted editor's handle, for edits made from beside it (dictation, a
133
+ * quoted idea); null when it unmounts. Its edits save like typing.
134
+ */
135
+ onReady?: (handle: SynapEditorHandle | null) => void;
136
+ className?: string;
137
+ }
138
+ /** Edits a host makes from beside `<SynapEditor>`: each is the person's own, saved like typing. */
139
+ interface SynapEditorHandle {
140
+ /** The document as markdown, as the next save would send it. */
141
+ getMarkdown(): string;
142
+ /** Plain text at the caret (never parsed as markdown). */
143
+ insertText(text: string): void;
144
+ /** Markdown blocks after the last one. */
145
+ appendMarkdown(markdown: string): void;
146
+ }
147
+ interface SynapMarkdownProps {
148
+ content: string;
149
+ onObjectClick?: (id: string, kind: string) => void;
150
+ className?: string;
151
+ }
152
+ interface HttpEditorAdapterOptions {
153
+ /** Where the app mounted `createEditorHandlers`. Default `/api/synap/editor`. */
154
+ basePath?: string;
155
+ fetch?: typeof fetch;
156
+ }
157
+
158
+ /**
159
+ * The declared API of `@synap-core/react/editor`: what `dist/editor.d.ts` is
160
+ * built from (tsup `dts.entry`). `index.ts` binds each value to its type here,
161
+ * so the implementation cannot drift from it without a type error, and the
162
+ * snapshot test (`api/editor.d.ts`) makes every change to it deliberate.
163
+ */
164
+
165
+ /** Every Synap editor and reader below it reads through `adapter`. */
166
+ declare function EditorDataProvider(props: EditorDataProviderProps): ReactElement;
167
+ /** The pod's markdown editor on one document: load, autosave with `baseRevision`, drop-to-link. */
168
+ declare function SynapEditor(props: SynapEditorProps): ReactElement | null;
169
+ /** The pod's markdown reader. */
170
+ declare function SynapMarkdown(props: SynapMarkdownProps): ReactElement | null;
171
+ /** The adapter over the app's own routes (`createEditorHandlers`, `@synap-core/sdk/connect`). */
172
+ declare function createHttpEditorAdapter(options?: HttpEditorAdapterOptions): EditorDataAdapter;
173
+ /** The drag payload type `<SynapEditor>` takes: JSON `{ id, kind, label }`. */
174
+ declare const SYNAP_OBJECT_MIME: "text/x-synap-object";
175
+ /** Set a pod object on a drag, so `<SynapEditor>` takes the drop. */
176
+ declare function setSynapObjectDrag(dataTransfer: DataTransfer, object: SynapDraggedObject): void;
177
+
178
+ export { type EditorDataAdapter, EditorDataProvider, type EditorDataProviderProps, type EditorDocument, type EditorEntity, type EditorError, EditorReadError, type EditorView, type EditorWriteResult, type HttpEditorAdapterOptions, type ResolvedRef, SYNAP_OBJECT_MIME, type SynapDraggedObject, SynapEditor, type SynapEditorHandle, type SynapEditorProps, type SynapEmbed, SynapMarkdown, type SynapMarkdownProps, createHttpEditorAdapter, setSynapObjectDrag };