@tldraw/tlschema 5.3.0-internal.fba91ed55f6c → 5.3.0-next.2fa9c61a8de6

package/src/records/TLComment.ts

@@ -11,23 +11,32 @@ import { TLShapeId } from './TLShape'
  * Where a comment thread is anchored on the canvas. Modeled as a discriminated union so new
  * anchor kinds can be added without breaking existing threads:
  *
- * - `shape` — pinned to a shape. `x`/`y` are normalized (0–1) within the shape's page bounds, so
- *   the pin keeps its spot as the shape moves and resizes. `isPrecise` mirrors arrow bindings: when
+ * - `shape` — pinned to a shape. `x`/`y` are normalized (0–1) within the shape's own bounds and
+ *   resolved through the shape's page transform, so the pin keeps its spot as the shape moves,
+ *   resizes, and rotates. `isPrecise` mirrors arrow bindings: when
  *   true the pin sits at exactly `x`/`y`; when false (the default) it sits at a consumer-defined
  *   spot (top-right out of the box), and `x`/`y` are the remembered precise position
  * - `point` — pinned to a fixed point on the page, in page coordinates
  * - `region` — pinned to a rectangular area of the page, in page coordinates
  * - `page` — a page-level thread with no spatial anchor
- * - `text-range` — pinned to a character range inside a shape's text
  *
  * @public
  */
 export type TLCommentAnchor =
 	| { type: 'shape'; shapeId: TLShapeId; x: number; y: number; isPrecise: boolean }
 	| { type: 'point'; x: number; y: number }
-	| { type: 'region'; x: number; y: number; w: number; h: number }
+	| {
+			type: 'region'
+			x: number
+			y: number
+			w: number
+			h: number
+			/** The normalized (0–1) corner the pin sits on — where the creating drag was released.
+			 *  Absent on older records; consumers fall back to a corner of their own choosing. */
+			pinX?: number
+			pinY?: number
+	  }
 	| { type: 'page' }
-	| { type: 'text-range'; shapeId: TLShapeId; from: number; to: number }
 
 /**
  * A comment thread. The thread owns the anchor (where the conversation lives on the canvas) and
@@ -59,6 +68,13 @@ export interface TLCommentThread extends BaseRecord<'comment-thread', TLCommentT
 	createdAt: number
 	/** Resolution state: when and by whom the thread was resolved, or null while open. */
 	resolved: { at: number; by: string } | null
+	/**
+	 * Whether the thread is soft-deleted. Clients delete a thread by setting this flag and
+	 * leaving the record (and its comments) in place, hidden from rendering. Sync servers are
+	 * expected to enforce the flag as write-once and creator-only, reject hard deletes from
+	 * clients, and drop flagged threads from future room loads.
+	 */
+	isDeleted: boolean
 	meta: JsonObject
 }
 
@@ -87,12 +103,64 @@ export interface TLComment extends BaseRecord<'comment', TLCommentId> {
 	editedAt: number | null
 	/** Rich text body. Use `toRichText(...)` for plaintext input. */
 	body: TLRichText
+	/**
+	 * Whether the comment is soft-deleted. Same model as `TLCommentThread.isDeleted` — clients
+	 * delete a comment by setting this flag and leaving the record in place, hidden from
+	 * rendering. Sync servers are expected to enforce the flag as write-once and author-only,
+	 * reject hard deletes from clients, and drop flagged comments from future room loads.
+	 */
+	isDeleted: boolean
 	meta: JsonObject
 }
 
 /** @public */
 export type TLCommentId = RecordId<TLComment>
 
+/**
+ * One person's emoji reaction to one comment.
+ *
+ * A reaction is its own record rather than a field on the comment, for the same reason read
+ * receipts are their own row: it's one person's data about someone else's comment. Comment records
+ * are owner-only for updates, so a reaction could never be written onto them; and holding
+ * everyone's reactions in one shared field would mean each write carried the whole set, so two
+ * people reacting at once would race to overwrite each other. A record per person keeps every
+ * write to its own record, which is what lets concurrent reactions coexist.
+ *
+ * A user holds at most one record per (comment, emoji) pair — so one user can react with several
+ * different emoji to the same comment. That's enforced by the id: see `createCommentReactionId`.
+ * Restricting a user to a single reaction overall is a client-side policy layered on top (see the
+ * commenting package's `reactionMode`), not a property of this record.
+ *
+ * @public
+ */
+export interface TLCommentReaction extends BaseRecord<'comment-reaction', TLCommentReactionId> {
+	/** The comment being reacted to. */
+	commentId: TLCommentId
+	/** Denormalized from the comment, so a thread's reactions can be found without a join. */
+	threadId: TLCommentThreadId
+	/** Denormalized from the comment — see `TLComment.pageId`. */
+	pageId: TLPageId
+	/** Who reacted. See `TLCommentThread.createdBy` — same server-stamping caveat applies. */
+	userId: string
+	/** The emoji itself, as a string (e.g. `'👍'`), not a shortcode. */
+	emoji: string
+	createdAt: number
+	meta: JsonObject
+}
+
+/** @public */
+export type TLCommentReactionId = RecordId<TLCommentReaction>
+
+/**
+ * An emoji shortcode or literal. Bounded because reaction ids embed the emoji verbatim
+ * (see {@link createCommentReactionId}), so an unbounded value means an unbounded record id.
+ */
+const emojiValidator = T.string.check((value) => {
+	if (value.length === 0 || value.length > 64) {
+		throw new T.ValidationError(`Expected an emoji of 1-64 characters, got ${value.length}`)
+	}
+})
+
 const commentAnchorValidator: T.Validator<TLCommentAnchor> = T.union('type', {
 	shape: T.object({
 		type: T.literal('shape'),
@@ -112,16 +180,12 @@ const commentAnchorValidator: T.Validator<TLCommentAnchor> = T.union('type', {
 		y: T.number,
 		w: T.number,
 		h: T.number,
+		pinX: T.number.optional(),
+		pinY: T.number.optional(),
 	}),
 	page: T.object({
 		type: T.literal('page'),
 	}),
-	'text-range': T.object({
-		type: T.literal('text-range'),
-		shapeId: idValidator<TLShapeId>('shape'),
-		from: T.number,
-		to: T.number,
-	}),
 })
 
 /**
@@ -132,7 +196,7 @@ const commentAnchorValidator: T.Validator<TLCommentAnchor> = T.union('type', {
  * store cannot represent.
  */
 function createCommentGuardMigrations(
-	typeName: 'comment' | 'comment-thread',
+	typeName: 'comment' | 'comment-thread' | 'comment-reaction',
 	extra: Parameters<typeof createRecordMigrationSequence>[0]['sequence'] = []
 ) {
 	return createRecordMigrationSequence({
@@ -176,6 +240,19 @@ export const commentThreadRecordConfig: CustomRecordInfo = {
 				return record
 			},
 		},
+		{
+			// Region anchors gained an optional pin corner (where the creating drag released).
+			id: 'com.tldraw.comment-thread/3',
+			up: (record) => record,
+			down: (record) => {
+				const anchor = (record as any).anchor
+				if (anchor?.type === 'region') {
+					const { pinX: _pinX, pinY: _pinY, ...rest } = anchor
+					;(record as any).anchor = rest
+				}
+				return record
+			},
+		},
 	]),
 	validator: T.object({
 		id: idValidator<TLCommentThreadId>('comment-thread'),
@@ -185,6 +262,7 @@ export const commentThreadRecordConfig: CustomRecordInfo = {
 		createdBy: T.string,
 		createdAt: T.number,
 		resolved: T.object({ at: T.number, by: T.string }).nullable(),
+		isDeleted: T.boolean,
 		meta: T.jsonValue,
 	}),
 }
@@ -207,20 +285,44 @@ export const commentRecordConfig: CustomRecordInfo = {
 		createdAt: T.number,
 		editedAt: T.number.nullable(),
 		body: richTextValidator,
+		isDeleted: T.boolean,
+		meta: T.jsonValue,
+	}),
+}
+
+/**
+ * Config for registering the `comment-reaction` record type in a tldraw schema. Pass via
+ * `commentSchemaRecords`; see `TLCommentReaction`.
+ *
+ * @public
+ */
+export const commentReactionRecordConfig: CustomRecordInfo = {
+	scope: 'document',
+	migrations: createCommentGuardMigrations('comment-reaction'),
+	validator: T.object({
+		id: idValidator<TLCommentReactionId>('comment-reaction'),
+		typeName: T.literal('comment-reaction'),
+		commentId: idValidator<TLCommentId>('comment'),
+		threadId: idValidator<TLCommentThreadId>('comment-thread'),
+		pageId: idValidator<TLPageId>('page'),
+		userId: T.string,
+		emoji: emojiValidator,
+		createdAt: T.number,
 		meta: T.jsonValue,
 	}),
 }
 
 /**
  * The `records` map to pass to `createTLSchema` / the client `records` option so comment
- * threads and comments sync. Register both types together — a comment without its thread type
- * (or vice versa) will fail schema validation on one side of the connection.
+ * threads, comments, and reactions sync. Register the types together — one without the others
+ * will fail schema validation on one side of the connection.
  *
  * @public
  */
 export const commentSchemaRecords = {
 	'comment-thread': commentThreadRecordConfig,
 	comment: commentRecordConfig,
+	'comment-reaction': commentReactionRecordConfig,
 }
 
 /** @public */
@@ -233,6 +335,32 @@ export function createCommentId(id?: string): TLCommentId {
 	return createCustomRecordId('comment', id) as TLCommentId
 }
 
+/**
+ * The id of one user's reaction to one comment, derived from the (comment, user, emoji) triple
+ * rather than random. This is what makes reaction identity structural: the same triple always
+ * addresses the same record, so re-picking an emoji toggles that one record and two tabs converge
+ * instead of racing to create duplicates. A user can hold one record per emoji on a comment
+ * (multiple reactions); enforcing "at most one reaction total" is a client concern layered on top,
+ * not a property of the id. The sync authorizer leans on this derivation, so it must be injective.
+ *
+ * `emoji` here is the reaction's token — the emoji glyph for the default palette, or whatever
+ * opaque string a consumer's palette uses. All three parts are URI-encoded before joining, so a
+ * `:` in any of them can't shift the boundary and collapse two different triples onto one id. The
+ * id is only ever recomputed for comparison, never parsed back, so the encoding needs no inverse.
+ *
+ * @public
+ */
+export function createCommentReactionId(
+	commentId: TLCommentId,
+	userId: string,
+	emoji: string
+): TLCommentReactionId {
+	return createCustomRecordId(
+		'comment-reaction',
+		`${encodeURIComponent(commentId)}:${encodeURIComponent(userId)}:${encodeURIComponent(emoji)}`
+	) as TLCommentReactionId
+}
+
 /**
  * Type guard for `TLCommentThreadId`. Note `isCommentId` does not accept these: the prefixes
  * are `comment-thread:` vs `comment:`, and the character after `comment` differs (`-` vs `:`),
@@ -254,6 +382,16 @@ export function isCommentId(id: string): id is TLCommentId {
 	return isCustomRecordId('comment', id)
 }
 
+/**
+ * Type guard for `TLCommentReactionId`. As with `isCommentThreadId`, the `comment-reaction:`
+ * prefix never overlaps `comment:` — the character after `comment` differs (`-` vs `:`).
+ *
+ * @public
+ */
+export function isCommentReactionId(id: string): id is TLCommentReactionId {
+	return isCustomRecordId('comment-reaction', id)
+}
+
 /**
  * Create a new comment thread record. Pair with `createComment` for the thread's first message.
  *
@@ -274,6 +412,7 @@ export function createCommentThread(props: {
 		createdBy: props.createdBy,
 		createdAt: props.now ?? Date.now(),
 		resolved: null,
+		isDeleted: false,
 		meta: props.meta ?? {},
 	}
 }
@@ -300,6 +439,35 @@ export function createComment(props: {
 		createdAt: props.now ?? Date.now(),
 		editedAt: null,
 		body: props.body,
+		isDeleted: false,
+		meta: props.meta ?? {},
+	}
+}
+
+/**
+ * Create a reaction record for one user's reaction to one comment. The id is derived from the
+ * comment and user (see `createCommentReactionId`), so re-reacting overwrites rather than adding.
+ *
+ * @public
+ */
+export function createCommentReaction(props: {
+	commentId: TLCommentId
+	threadId: TLCommentThreadId
+	pageId: TLPageId
+	userId: string
+	emoji: string
+	now?: number
+	meta?: JsonObject
+}): TLCommentReaction {
+	return {
+		id: createCommentReactionId(props.commentId, props.userId, props.emoji),
+		typeName: 'comment-reaction',
+		commentId: props.commentId,
+		threadId: props.threadId,
+		pageId: props.pageId,
+		userId: props.userId,
+		emoji: props.emoji,
+		createdAt: props.now ?? Date.now(),
 		meta: props.meta ?? {},
 	}
 }

package/src/shapes/TLGeoShape.ts

@@ -90,6 +90,10 @@ export interface TLGeoShapeProps {
 	growY: number
 	/** Scale factor applied to the shape */
 	scale: number
+	/** Whether to mirror the shape horizontally */
+	flipX: boolean
+	/** Whether to mirror the shape vertically */
+	flipY: boolean
 
 	/** Color style for text label */
 	labelColor: TLDefaultColorStyle
@@ -142,7 +146,9 @@ export interface TLGeoShapeProps {
  *     labelColor: 'black',
  *     url: '',
  *     growY: 0,
- *     scale: 1
+ *     scale: 1,
+ *     flipX: false,
+ *     flipY: false
  *   },
  *   meta: {}
  * }
@@ -170,6 +176,8 @@ export const geoShapeProps: RecordProps<TLGeoShape> = {
 	h: T.nonZeroNumber,
 	growY: T.positiveNumber,
 	scale: T.nonZeroNumber,
+	flipX: T.boolean,
+	flipY: T.boolean,
 
 	// Text properties
 	labelColor: DefaultLabelColorStyle,
@@ -194,6 +202,7 @@ const geoShapeVersions = createShapePropsMigrationIds('geo', {
 	AddScale: 9,
 	AddRichText: 10,
 	AddRichTextAttrs: 11,
+	AddFlipProps: 12,
 })
 
 /**
@@ -318,5 +327,16 @@ export const geoShapeMigrations = createShapePropsMigrationSequence({
 				}
 			},
 		},
+		{
+			id: geoShapeVersions.AddFlipProps,
+			up: (props) => {
+				props.flipX = false
+				props.flipY = false
+			},
+			down: (props) => {
+				delete props.flipX
+				delete props.flipY
+			},
+		},
 	],
 })