@tldraw/tlschema 4.6.0-next.1f489710ee41 → 4.6.0-next.4dde09fa17ab

package/src/migrations.test.ts

@@ -15,6 +15,7 @@ import { instancePageStateVersions } from './records/TLPageState'
 import { pointerVersions } from './records/TLPointer'
 import { instancePresenceVersions } from './records/TLPresence'
 import { TLShape, rootShapeVersions } from './records/TLShape'
+import { userVersions } from './records/TLUser'
 import { arrowShapeVersions } from './shapes/TLArrowShape'
 import { bookmarkShapeVersions } from './shapes/TLBookmarkShape'
 import { drawShapeVersions } from './shapes/TLDrawShape'
@@ -2603,6 +2604,27 @@ describe('LegacyPointsConversion migration for highlight shape', () => {
 	})
 })
 
+describe('Adding textFirstEditedBy to note shape', () => {
+	const { up, down } = getTestMigration(noteShapeVersions.AddFirstEditedBy)
+
+	test('up works as expected', () => {
+		expect(up({ props: {} })).toEqual({ props: { textFirstEditedBy: null } })
+	})
+
+	test('down works as expected', () => {
+		expect(down({ props: { textFirstEditedBy: null } })).toEqual({ props: {} })
+	})
+})
+
+describe('TLUser initial migration', () => {
+	const { up } = getTestMigration(userVersions.Initial)
+
+	test('up is a no-op', () => {
+		const record = { id: 'user:123', name: 'Test', color: '#000', imageUrl: '', meta: {} }
+		expect(up(record)).toEqual(record)
+	})
+})
+
 /* ---  PUT YOUR MIGRATIONS TESTS ABOVE HERE --- */
 
 // check that all migrator fns were called at least once

package/src/records/TLRecord.ts

@@ -8,6 +8,7 @@ import { TLInstancePageState } from './TLPageState'
 import { TLPointer } from './TLPointer'
 import { TLInstancePresence } from './TLPresence'
 import { TLShape } from './TLShape'
+import { TLUser } from './TLUser'
 
 /**
  * Interface for extending tldraw with custom record types via TypeScript module augmentation.
@@ -63,6 +64,7 @@ export type TLDefaultRecord =
 	| TLShape
 	| TLInstancePresence
 	| TLPointer
+	| TLUser
 
 /**
  * Index type that maps custom record type names to their record types.

package/src/records/TLUser.ts

@@ -0,0 +1,148 @@
+import {
+	BaseRecord,
+	createMigrationIds,
+	createRecordMigrationSequence,
+	createRecordType,
+	RecordId,
+} from '@tldraw/store'
+import { JsonObject } from '@tldraw/utils'
+import { T } from '@tldraw/validate'
+import { idValidator } from '../misc/id-validator'
+
+/**
+ * A user record in a tldraw store. User records are document-scoped and
+ * persist alongside shapes, assets, and pages. They are automatically
+ * included in snapshots, clipboard content, and `.tldr` files so that
+ * attribution display names survive across boards and sessions.
+ *
+ * User records are populated from the {@link @tldraw/tlschema#TLUserStore}
+ * when the editor stamps attribution metadata onto shapes.
+ *
+ * Extend user records with custom metadata by passing validators to
+ * {@link @tldraw/tlschema#createTLSchema} or {@link createUserRecordType}.
+ *
+ * @public
+ */
+export interface TLUser extends BaseRecord<'user', TLUserId> {
+	name: string
+	color: string
+	imageUrl: string
+	meta: JsonObject
+}
+
+/** @public */
+export type TLUserId = RecordId<TLUser>
+
+/** @public */
+export const userIdValidator = idValidator<TLUserId>('user')
+
+/** @public */
+export const userVersions = createMigrationIds('com.tldraw.user', {
+	Initial: 1,
+})
+
+/** @public */
+export const userMigrations = createRecordMigrationSequence({
+	sequenceId: 'com.tldraw.user',
+	recordType: 'user',
+	sequence: [
+		{
+			id: userVersions.Initial,
+			up: (_record: any) => {
+				// initial version — nothing to migrate
+			},
+		},
+	],
+})
+
+/**
+ * Creates a user record type with optional custom meta validation.
+ *
+ * When `meta` validators are provided, the user record's `meta` field will
+ * validate those specific fields (when present) while still allowing
+ * arbitrary additional JSON properties. Custom meta fields are treated as
+ * optional so that user records created without them remain valid.
+ *
+ * @param config - Optional configuration for custom meta validators
+ * @returns A configured user record type
+ *
+ * @example
+ * ```ts
+ * import { createUserRecordType } from '@tldraw/tlschema'
+ * import { T } from '@tldraw/validate'
+ *
+ * const CustomUserRecordType = createUserRecordType({
+ *   meta: {
+ *     isAdmin: T.boolean,
+ *     department: T.string,
+ *   },
+ * })
+ * ```
+ *
+ * @public
+ */
+export function createUserRecordType(config?: { meta?: Record<string, T.Validatable<any>> }) {
+	const metaConfig = config?.meta
+
+	const metaValidator = metaConfig
+		? T.object(
+				Object.fromEntries(
+					Object.entries(metaConfig).map(([key, v]) => [
+						key,
+						new T.Validator((value) => {
+							if (value === undefined) return undefined
+							return (v as T.Validator<unknown>).validate(value)
+						}),
+					])
+				)
+			).allowUnknownProperties()
+		: (T.jsonValue as T.ObjectValidator<JsonObject>)
+
+	const validator: T.Validator<TLUser> = T.model(
+		'user',
+		T.object({
+			typeName: T.literal('user'),
+			id: userIdValidator,
+			name: T.string,
+			color: T.string,
+			imageUrl: T.string,
+			meta: metaValidator as T.ObjectValidator<JsonObject>,
+		})
+	)
+
+	return createRecordType<TLUser>('user', {
+		validator,
+		scope: 'document',
+	}).withDefaultProperties(() => ({
+		name: '',
+		color: '',
+		imageUrl: '',
+		meta: {},
+	}))
+}
+
+/** @public */
+export const userValidator: T.Validator<TLUser> = T.model(
+	'user',
+	T.object({
+		typeName: T.literal('user'),
+		id: userIdValidator,
+		name: T.string,
+		color: T.string,
+		imageUrl: T.string,
+		meta: T.jsonValue as T.ObjectValidator<JsonObject>,
+	})
+)
+
+/** @public */
+export const UserRecordType = createUserRecordType()
+
+/** @public */
+export function isUserId(id: string): id is TLUserId {
+	return UserRecordType.isId(id)
+}
+
+/** @public */
+export function createUserId(id: string): TLUserId {
+	return UserRecordType.createId(id)
+}

package/src/shapes/TLNoteShape.ts

@@ -64,6 +64,8 @@ export interface TLNoteShapeProps {
 	richText: TLRichText
 	/** Scale factor applied to the note shape for display */
 	scale: number
+	/** User ID of the person who first edited the note text */
+	textFirstEditedBy: string | null
 }
 
 /**
@@ -130,6 +132,7 @@ export const noteShapeProps: RecordProps<TLNoteShape> = {
 	url: T.linkUrl,
 	richText: richTextValidator,
 	scale: T.nonZeroNumber,
+	textFirstEditedBy: T.string.nullable(),
 }
 
 const Versions = createShapePropsMigrationIds('note', {
@@ -143,6 +146,7 @@ const Versions = createShapePropsMigrationIds('note', {
 	AddLabelColor: 8,
 	AddRichText: 9,
 	AddRichTextAttrs: 10,
+	AddFirstEditedBy: 11,
 })
 
 /**
@@ -265,5 +269,14 @@ export const noteShapeMigrations = createShapePropsMigrationSequence({
 				}
 			},
 		},
+		{
+			id: Versions.AddFirstEditedBy,
+			up: (props) => {
+				props.textFirstEditedBy = null
+			},
+			down: (props) => {
+				delete props.textFirstEditedBy
+			},
+		},
 	],
 })