@dxos/plugin-tldraw 0.10.0

package/src/hooks/adapter.ts

@@ -0,0 +1,83 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { transact } from '@tldraw/state';
+import { type TLRecord, createTLStore, defaultShapeUtils } from '@tldraw/tldraw';
+import { type TLStore } from '@tldraw/tlschema';
+
+import { AbstractStoreAdapter, type Batch, Modified } from '@dxos/echo-doc';
+import { invariant } from '@dxos/invariant';
+
+/**
+ * Ref:
+ * - https://tldraw.dev/docs/persistence#Listening-for-changes
+ * - https://github.com/tldraw/tldraw-yjs-example/blob/main/src/useYjsStore.ts
+ * - https://github.com/LiangrunDa/tldraw-with-automerge/blob/main/src/App.tsx
+ */
+const SAVE_DEBOUNCE = 250;
+
+export class TLDrawStoreAdapter extends AbstractStoreAdapter<TLRecord> {
+  private readonly _modified = new Modified<TLRecord>();
+  private _store?: TLStore;
+  private _saveTimeout?: ReturnType<typeof setTimeout>;
+
+  get store() {
+    return this._store;
+  }
+
+  override getElements(): TLRecord[] {
+    invariant(this._store);
+    return this._store.allRecords();
+  }
+
+  protected override onUpdate({ added = [], updated = [], deleted = [] }: Batch<TLRecord>): void {
+    // Replace the store records with the automerge doc records.
+    transact(() => {
+      invariant(this._store);
+      const elements = [...added, ...updated];
+      this._store.remove(deleted);
+      this._store.put(elements);
+    });
+  }
+
+  protected override onOpen(): () => void {
+    this._store = createTLStore({ shapeUtils: defaultShapeUtils });
+
+    // List for changes to the store.
+    // TODO(burdon): Upload images to WNFS.
+    const subscription = this._store.listen(
+      ({ changes: { added, updated, removed } }) => {
+        Object.values(added).forEach((record) => this._modified.added.set(record.id, record));
+        Object.values(updated).forEach(([_, record]) => this._modified.updated.set(record.id, record));
+        Object.values(removed).forEach((record) => this._modified.deleted.add(record.id));
+        // Debounced auto-save: tldraw batches listener notifications, so a save driven by
+        // pointer events can run before the final gesture is recorded and lose the last stroke.
+        clearTimeout(this._saveTimeout);
+        this._saveTimeout = setTimeout(() => this.save(), SAVE_DEBOUNCE);
+      },
+      // Only listen to local document changes.
+      {
+        scope: 'document',
+        source: 'user',
+      },
+    );
+
+    return () => {
+      clearTimeout(this._saveTimeout);
+      subscription();
+    };
+  }
+
+  protected override onClose(): void {
+    this._store = undefined;
+  }
+
+  save(): void {
+    if (!this.isOpen) {
+      return;
+    }
+    this.updateDatabase(this._modified.batch());
+    this._modified.clear();
+  }
+}

package/src/hooks/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export * from './useStoreAdapter';
+export * from './adapter';

package/src/hooks/useStoreAdapter.ts

@@ -0,0 +1,55 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { useState } from 'react';
+
+import { Doc } from '@dxos/echo-doc';
+import { log } from '@dxos/log';
+import { useAsyncEffect } from '@dxos/react-ui';
+
+import { Tldraw } from '#types';
+
+import { TLDrawStoreAdapter } from './adapter';
+
+/**
+ * Hook that manages the TLDraw store adapter lifecycle for a canvas object.
+ * Creates a doc accessor and opens the adapter.
+ *
+ * @param canvas - Optional canvas whose content will be synced.
+ * @returns The TLDrawStoreAdapter instance managing the tldraw store.
+ */
+export const useStoreAdapter = (canvas?: Tldraw.Canvas) => {
+  const [adapter] = useState(new TLDrawStoreAdapter());
+  const [_, forceUpdate] = useState({});
+  useAsyncEffect(
+    async (controller) => {
+      if (!canvas) {
+        return;
+      }
+
+      if (canvas.schema !== Tldraw.TLDRAW_SCHEMA) {
+        log.warn('invalid schema', { schema: canvas.schema });
+        return;
+      }
+
+      const accessor = Doc.createAccessor(canvas, ['content']);
+      await adapter.open(accessor);
+      if (controller.signal.aborted) {
+        void adapter.close();
+        return;
+      }
+
+      forceUpdate({});
+
+      return () => {
+        // Flush any gesture still pending from the deferred pointer_up save.
+        adapter.save();
+        void adapter.close();
+      };
+    },
+    [canvas],
+  );
+
+  return adapter;
+};

package/src/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export * from './meta';
+export * as TldrawModel from './model';
+export * from './types';

package/src/meta.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { Plugin } from '@dxos/app-framework';
+
+import config from '../dx.config';
+
+export const meta = Plugin.getMetaFromConfig(config);

package/src/migrations/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './migrate';
+export * from './schema';

package/src/migrations/migrate.ts

@@ -0,0 +1,49 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type SerializedStore } from '@tldraw/store';
+import { type TLRecord, createTLStore, defaultShapeUtils, loadSnapshot } from '@tldraw/tldraw';
+
+import { log } from '@dxos/log';
+
+import { CURRENT_VERSION, DEFAULT_VERSION, schema } from './schema';
+
+// TODO(burdon): Update version in package.json.
+// TODO(burdon): Try/catch around rendering component component.
+
+export type MigrateCanvas = (current: SerializedStore<TLRecord>, version?: number) => Promise<SerializedStore<any>>;
+
+/**
+ * Attempt to migrated data.
+ * https://tldraw.dev/reference/store/Store#migrateSnapshot
+ */
+export const migrateCanvas: MigrateCanvas = async (current, version = DEFAULT_VERSION) => {
+  log.info('migrating snapshot...', { from: version, to: CURRENT_VERSION });
+  try {
+    // Try one-shot migration.
+    const store = createTLStore({ shapeUtils: defaultShapeUtils });
+    const snapshot = store.migrateSnapshot({ schema: schema[version], store: current });
+
+    // Test loading.
+    loadSnapshot(store, snapshot);
+    return store.serialize();
+  } catch (err) {
+    log.warn('one-shot migration failed; trying individual records', { err });
+
+    // Try processing records individually.
+    const store = createTLStore({ shapeUtils: defaultShapeUtils });
+    for (const record of Object.values(current)) {
+      try {
+        // Migrate individual record.
+        const s1 = { [record.id]: record };
+        const s2 = store.migrateSnapshot({ schema: schema[version], store: s1 });
+        store.put(Object.values(s2.store));
+      } catch (err) {
+        log.warn('invalid record', { record, err });
+      }
+    }
+
+    return store.serialize();
+  }
+};

package/src/migrations/schema.ts

@@ -0,0 +1,98 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export const DEFAULT_VERSION = 1;
+export const CURRENT_VERSION = 2;
+
+/**
+ * TLDraw schema.
+ */
+export const schema: Record<number, any> = {
+  1: {
+    schemaVersion: 1,
+    storeVersion: 4,
+    recordVersions: {
+      asset: {
+        version: 1,
+        subTypeKey: 'type',
+        subTypeVersions: {
+          image: 2,
+          video: 2,
+          bookmark: 0,
+        },
+      },
+      camera: {
+        version: 1,
+      },
+      document: {
+        version: 2,
+      },
+      instance: {
+        version: 22,
+      },
+      instance_page_state: {
+        version: 5,
+      },
+      page: {
+        version: 1,
+      },
+      shape: {
+        version: 3,
+        subTypeKey: 'type',
+        subTypeVersions: {
+          group: 0,
+          text: 1,
+          bookmark: 1,
+          draw: 1,
+          geo: 7,
+          note: 4,
+          line: 1,
+          frame: 0,
+          arrow: 2,
+          highlight: 0,
+          embed: 4,
+          image: 2,
+          video: 1,
+        },
+      },
+      instance_presence: {
+        version: 5,
+      },
+      pointer: {
+        version: 1,
+      },
+    },
+  },
+  2: {
+    schemaVersion: 2,
+    sequences: {
+      'com.tldraw.store': 4,
+      'com.tldraw.asset': 1,
+      'com.tldraw.camera': 1,
+      'com.tldraw.document': 2,
+      'com.tldraw.instance': 24,
+      'com.tldraw.instance_page_state': 5,
+      'com.tldraw.page': 1,
+      'com.tldraw.instance_presence': 5,
+      'com.tldraw.pointer': 1,
+      'com.tldraw.shape': 4,
+      'com.tldraw.asset.bookmark': 1,
+      'com.tldraw.asset.image': 3,
+      'com.tldraw.asset.video': 3,
+      'com.tldraw.shape.group': 0,
+      'com.tldraw.shape.text': 1,
+      'com.tldraw.shape.bookmark': 2,
+      'com.tldraw.shape.draw': 1,
+      'com.tldraw.shape.geo': 8,
+      'com.tldraw.shape.note': 6,
+      'com.tldraw.shape.line': 4,
+      'com.tldraw.shape.frame': 0,
+      'com.tldraw.shape.arrow': 3,
+      'com.tldraw.shape.highlight': 0,
+      'com.tldraw.shape.embed': 4,
+      'com.tldraw.shape.image': 3,
+      'com.tldraw.shape.video': 2,
+    },
+  },
+};

package/src/model/TldrawBuilder.test.ts

@@ -0,0 +1,72 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { createTLSchema } from '@tldraw/tlschema';
+import { describe, test } from 'vitest';
+
+import { TldrawBuilder } from './TldrawBuilder';
+
+describe('TldrawBuilder', () => {
+  test('builds an empty canvas with document and page', ({ expect }) => {
+    const content = new TldrawBuilder().build();
+    expect(content['document:document'].typeName).to.eq('document');
+    expect(content['page:page'].typeName).to.eq('page');
+  });
+
+  test('chains shapes and connectors', ({ expect }) => {
+    const content = new TldrawBuilder()
+      .rectangle({ id: 'a', x: 0, y: 0, text: 'DXOS', color: 'blue' })
+      .ellipse({ id: 'b', x: 320, y: 0, text: 'ECHO', color: 'green' })
+      .text({ x: 0, y: 240, text: 'Hello', font: 'mono' })
+      .arrow({ from: 'a', to: 'b', text: 'links' })
+      .build();
+
+    const shapes = Object.values(content).filter((record: any) => record.typeName === 'shape');
+    const bindings = Object.values(content).filter((record: any) => record.typeName === 'binding');
+    expect(shapes).to.have.length(4);
+    expect(bindings).to.have.length(2);
+    expect((bindings[0] as any).toId).to.eq('shape:a');
+  });
+
+  test('connects via explicit points when shapes are not referenced', ({ expect }) => {
+    const content = new TldrawBuilder()
+      .arrow({ id: 'arrow', start: { x: 0, y: 0 }, end: { x: 200, y: 100 } })
+      .line({ id: 'line', start: { x: 0, y: 0 }, end: { x: 100, y: 0 } })
+      .build();
+
+    const arrow: any = content['shape:arrow'];
+    const line: any = content['shape:line'];
+    // Unbound connectors carry their geometry inline; no binding records are emitted.
+    expect(arrow.props.end).to.deep.eq({ x: 200, y: 100 });
+    expect(line.props.points.a2).to.deep.eq({ id: 'a2', index: 'a2', x: 100, y: 0 });
+    expect(Object.values(content).filter((record: any) => record.typeName === 'binding')).to.have.length(0);
+  });
+
+  test('throws on unknown connector handles and duplicate shape ids', ({ expect }) => {
+    expect(() => new TldrawBuilder().rectangle({ id: 'a' }).arrow({ from: 'a', to: 'missing' })).to.throw(
+      /unknown target shape/,
+    );
+    expect(() => new TldrawBuilder().rectangle({ id: 'dup' }).ellipse({ id: 'dup' })).to.throw(/duplicate shape id/);
+  });
+
+  test('produces records that pass tldraw schema validation', ({ expect }) => {
+    const content = new TldrawBuilder()
+      .rectangle({ id: 'a', x: 0, y: 0, text: 'A' })
+      .circle({ id: 'b', x: 320, y: 0, text: 'B' })
+      .geo('star', { id: 'c', x: 160, y: 240, color: 'yellow' })
+      .text({ x: 0, y: 400, text: 'label' })
+      .arrow({ from: 'a', to: 'b' })
+      .line({ from: 'b', to: 'c' })
+      .build();
+
+    const schema = createTLSchema();
+    // tldraw types its record map as a fixed-key object without an index signature;
+    // validating an arbitrary record requires a string-keyed view.
+    const validators = schema.types as Record<string, { validate: (record: unknown) => unknown }>;
+    for (const record of Object.values(content)) {
+      // `validate` throws on any invalid prop/shape/binding.
+      expect(() => validators[record.typeName].validate(record)).to.not.throw();
+    }
+  });
+});