@tldraw/tlschema 5.3.0-internal.fba91ed55f6c → 5.3.0-next.91d2a20b898c

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.
@@ -1,305 +0,0 @@
1
- import { BaseRecord, RecordId, createRecordMigrationSequence } from '@tldraw/store'
2
- import { JsonObject } from '@tldraw/utils'
3
- import { T } from '@tldraw/validate'
4
- import { idValidator } from '../misc/id-validator'
5
- import { richTextValidator, TLRichText } from '../misc/TLRichText'
6
- import { CustomRecordInfo, createCustomRecordId, isCustomRecordId } from './TLCustomRecord'
7
- import { TLPageId } from './TLPage'
8
- import { TLShapeId } from './TLShape'
9
-
10
- /**
11
- * Where a comment thread is anchored on the canvas. Modeled as a discriminated union so new
12
- * anchor kinds can be added without breaking existing threads:
13
- *
14
- * - `shape` — pinned to a shape. `x`/`y` are normalized (0–1) within the shape's page bounds, so
15
- * the pin keeps its spot as the shape moves and resizes. `isPrecise` mirrors arrow bindings: when
16
- * true the pin sits at exactly `x`/`y`; when false (the default) it sits at a consumer-defined
17
- * spot (top-right out of the box), and `x`/`y` are the remembered precise position
18
- * - `point` — pinned to a fixed point on the page, in page coordinates
19
- * - `region` — pinned to a rectangular area of the page, in page coordinates
20
- * - `page` — a page-level thread with no spatial anchor
21
- * - `text-range` — pinned to a character range inside a shape's text
22
- *
23
- * @public
24
- */
25
- export type TLCommentAnchor =
26
- | { type: 'shape'; shapeId: TLShapeId; x: number; y: number; isPrecise: boolean }
27
- | { type: 'point'; x: number; y: number }
28
- | { type: 'region'; x: number; y: number; w: number; h: number }
29
- | { type: 'page' }
30
- | { type: 'text-range'; shapeId: TLShapeId; from: number; to: number }
31
-
32
- /**
33
- * A comment thread. The thread owns the anchor (where the conversation lives on the canvas) and
34
- * the resolution state; the messages themselves are `TLComment` records pointing at the thread
35
- * via `threadId`, ordered by `createdAt`. v1 threads are flat — no nested replies.
36
- *
37
- * Threads and comments are document records, but they're intended to be served through the sync
38
- * server's object-store lane: gated by the session's `objectAccess` rather than `isReadonly`
39
- * (so "can comment but not edit" is expressible), excluded from document snapshots and `.tldr`
40
- * exports server-side, and persisted in a separate lane from the main document.
41
- *
42
- * Opt-in: register with `createTLSchema({ records: commentSchemaRecords })` on the server and
43
- * the matching `records` option on the client — neither type is part of the default schema, and
44
- * both sides must register them identically.
45
- *
46
- * @public
47
- */
48
- export interface TLCommentThread extends BaseRecord<'comment-thread', TLCommentThreadId> {
49
- /** The page the thread lives on. */
50
- pageId: TLPageId
51
- /** Where the thread is anchored on that page. */
52
- anchor: TLCommentAnchor
53
- /**
54
- * Who started the thread. Client-supplied for now; the sync server should stamp/verify this
55
- * from the session's authenticated identity once record-level authorization lands (the same
56
- * model presence already uses for self-ownership).
57
- */
58
- createdBy: string
59
- createdAt: number
60
- /** Resolution state: when and by whom the thread was resolved, or null while open. */
61
- resolved: { at: number; by: string } | null
62
- meta: JsonObject
63
- }
64
-
65
- /** @public */
66
- export type TLCommentThreadId = RecordId<TLCommentThread>
67
-
68
- /**
69
- * A single comment message within a thread. See `TLCommentThread` for the overall model and
70
- * sync/registration notes.
71
- *
72
- * Comment mutations are deliberately not undoable — create/edit them with
73
- * `{ history: 'ignore' }` to avoid multiplayer surprises like a comment reappearing after
74
- * someone else deleted it.
75
- *
76
- * @public
77
- */
78
- export interface TLComment extends BaseRecord<'comment', TLCommentId> {
79
- /** The thread this comment belongs to. */
80
- threadId: TLCommentThreadId
81
- /** Denormalized from the thread so per-page queries don't need a join. */
82
- pageId: TLPageId
83
- /** See `TLCommentThread.createdBy` — same server-stamping caveat applies. */
84
- authorId: string
85
- createdAt: number
86
- /** Null until the comment is first edited. */
87
- editedAt: number | null
88
- /** Rich text body. Use `toRichText(...)` for plaintext input. */
89
- body: TLRichText
90
- meta: JsonObject
91
- }
92
-
93
- /** @public */
94
- export type TLCommentId = RecordId<TLComment>
95
-
96
- const commentAnchorValidator: T.Validator<TLCommentAnchor> = T.union('type', {
97
- shape: T.object({
98
- type: T.literal('shape'),
99
- shapeId: idValidator<TLShapeId>('shape'),
100
- x: T.number,
101
- y: T.number,
102
- isPrecise: T.boolean,
103
- }),
104
- point: T.object({
105
- type: T.literal('point'),
106
- x: T.number,
107
- y: T.number,
108
- }),
109
- region: T.object({
110
- type: T.literal('region'),
111
- x: T.number,
112
- y: T.number,
113
- w: T.number,
114
- h: T.number,
115
- }),
116
- page: T.object({
117
- type: T.literal('page'),
118
- }),
119
- 'text-range': T.object({
120
- type: T.literal('text-range'),
121
- shapeId: idValidator<TLShapeId>('shape'),
122
- from: T.number,
123
- to: T.number,
124
- }),
125
- })
126
-
127
- /**
128
- * Guard migrations for the comment record types. Each sequence is retroactive and starts with an
129
- * identity migration that has no `down`: a sync server whose schema registers the comment types
130
- * cannot down-migrate records for a session whose schema predates them, so such sessions are
131
- * rejected with CLIENT_TOO_OLD (prompting a refresh) instead of being sent record types their
132
- * store cannot represent.
133
- */
134
- function createCommentGuardMigrations(
135
- typeName: 'comment' | 'comment-thread',
136
- extra: Parameters<typeof createRecordMigrationSequence>[0]['sequence'] = []
137
- ) {
138
- return createRecordMigrationSequence({
139
- sequenceId: `com.tldraw.${typeName}`,
140
- recordType: typeName,
141
- retroactive: true,
142
- sequence: [
143
- {
144
- id: `com.tldraw.${typeName}/1`,
145
- up: (record) => record,
146
- },
147
- ...extra,
148
- ],
149
- })
150
- }
151
-
152
- /**
153
- * Config for registering the `comment-thread` record type in a tldraw schema. Pass via
154
- * `commentSchemaRecords`; see `TLCommentThread`.
155
- *
156
- * @public
157
- */
158
- export const commentThreadRecordConfig: CustomRecordInfo = {
159
- scope: 'document',
160
- migrations: createCommentGuardMigrations('comment-thread', [
161
- {
162
- // Shape anchors gained normalized x/y + isPrecise; existing ones were imprecise (top-right).
163
- id: 'com.tldraw.comment-thread/2',
164
- up: (record) => {
165
- const anchor = (record as any).anchor
166
- if (anchor?.type === 'shape' && anchor.x === undefined) {
167
- ;(record as any).anchor = { ...anchor, x: 1, y: 0, isPrecise: false }
168
- }
169
- return record
170
- },
171
- down: (record) => {
172
- const anchor = (record as any).anchor
173
- if (anchor?.type === 'shape') {
174
- ;(record as any).anchor = { type: 'shape', shapeId: anchor.shapeId }
175
- }
176
- return record
177
- },
178
- },
179
- ]),
180
- validator: T.object({
181
- id: idValidator<TLCommentThreadId>('comment-thread'),
182
- typeName: T.literal('comment-thread'),
183
- pageId: idValidator<TLPageId>('page'),
184
- anchor: commentAnchorValidator,
185
- createdBy: T.string,
186
- createdAt: T.number,
187
- resolved: T.object({ at: T.number, by: T.string }).nullable(),
188
- meta: T.jsonValue,
189
- }),
190
- }
191
-
192
- /**
193
- * Config for registering the `comment` record type in a tldraw schema. Pass via
194
- * `commentSchemaRecords`; see `TLComment`.
195
- *
196
- * @public
197
- */
198
- export const commentRecordConfig: CustomRecordInfo = {
199
- scope: 'document',
200
- migrations: createCommentGuardMigrations('comment'),
201
- validator: T.object({
202
- id: idValidator<TLCommentId>('comment'),
203
- typeName: T.literal('comment'),
204
- threadId: idValidator<TLCommentThreadId>('comment-thread'),
205
- pageId: idValidator<TLPageId>('page'),
206
- authorId: T.string,
207
- createdAt: T.number,
208
- editedAt: T.number.nullable(),
209
- body: richTextValidator,
210
- meta: T.jsonValue,
211
- }),
212
- }
213
-
214
- /**
215
- * The `records` map to pass to `createTLSchema` / the client `records` option so comment
216
- * threads and comments sync. Register both types together — a comment without its thread type
217
- * (or vice versa) will fail schema validation on one side of the connection.
218
- *
219
- * @public
220
- */
221
- export const commentSchemaRecords = {
222
- 'comment-thread': commentThreadRecordConfig,
223
- comment: commentRecordConfig,
224
- }
225
-
226
- /** @public */
227
- export function createCommentThreadId(id?: string): TLCommentThreadId {
228
- return createCustomRecordId('comment-thread', id) as TLCommentThreadId
229
- }
230
-
231
- /** @public */
232
- export function createCommentId(id?: string): TLCommentId {
233
- return createCustomRecordId('comment', id) as TLCommentId
234
- }
235
-
236
- /**
237
- * Type guard for `TLCommentThreadId`. Note `isCommentId` does not accept these: the prefixes
238
- * are `comment-thread:` vs `comment:`, and the character after `comment` differs (`-` vs `:`),
239
- * so the two never overlap.
240
- *
241
- * @public
242
- */
243
- export function isCommentThreadId(id: string): id is TLCommentThreadId {
244
- return isCustomRecordId('comment-thread', id)
245
- }
246
-
247
- /**
248
- * Type guard for `TLCommentId`. See `isCommentThreadId` for why `comment-thread:...` ids are
249
- * correctly rejected here.
250
- *
251
- * @public
252
- */
253
- export function isCommentId(id: string): id is TLCommentId {
254
- return isCustomRecordId('comment', id)
255
- }
256
-
257
- /**
258
- * Create a new comment thread record. Pair with `createComment` for the thread's first message.
259
- *
260
- * @public
261
- */
262
- export function createCommentThread(props: {
263
- pageId: TLPageId
264
- anchor: TLCommentAnchor
265
- createdBy: string
266
- now?: number
267
- meta?: JsonObject
268
- }): TLCommentThread {
269
- return {
270
- id: createCommentThreadId(),
271
- typeName: 'comment-thread',
272
- pageId: props.pageId,
273
- anchor: props.anchor,
274
- createdBy: props.createdBy,
275
- createdAt: props.now ?? Date.now(),
276
- resolved: null,
277
- meta: props.meta ?? {},
278
- }
279
- }
280
-
281
- /**
282
- * Create a new comment record within a thread.
283
- *
284
- * @public
285
- */
286
- export function createComment(props: {
287
- threadId: TLCommentThreadId
288
- pageId: TLPageId
289
- authorId: string
290
- body: TLRichText
291
- now?: number
292
- meta?: JsonObject
293
- }): TLComment {
294
- return {
295
- id: createCommentId(),
296
- typeName: 'comment',
297
- threadId: props.threadId,
298
- pageId: props.pageId,
299
- authorId: props.authorId,
300
- createdAt: props.now ?? Date.now(),
301
- editedAt: null,
302
- body: props.body,
303
- meta: props.meta ?? {},
304
- }
305
- }