@tldraw/editor 4.6.0-next.30b99cd52fc8 → 4.6.0-next.35cf541abcf9

package/dist-esm/lib/editor/Editor.mjs

@@ -65,6 +65,7 @@ import {
 } from "@tldraw/utils";
 import EventEmitter from "eventemitter3";
 import { createTLCurrentUser } from "../config/createTLCurrentUser.mjs";
+import { checkAssets } from "../config/defaultAssets.mjs";
 import { checkBindings } from "../config/defaultBindings.mjs";
 import { checkShapesAndAddCore } from "../config/defaultShapes.mjs";
 import {
@@ -115,10 +116,12 @@ import { FocusManager } from "./managers/FocusManager/FocusManager.mjs";
 import { FontManager } from "./managers/FontManager/FontManager.mjs";
 import { HistoryManager } from "./managers/HistoryManager/HistoryManager.mjs";
 import { InputsManager } from "./managers/InputsManager/InputsManager.mjs";
+import { PerformanceManager } from "./managers/PerformanceManager/PerformanceManager.mjs";
 import { ScribbleManager } from "./managers/ScribbleManager/ScribbleManager.mjs";
 import { SnapManager } from "./managers/SnapManager/SnapManager.mjs";
 import { SpatialIndexManager } from "./managers/SpatialIndexManager/SpatialIndexManager.mjs";
 import { TextManager } from "./managers/TextManager/TextManager.mjs";
+import { ThemeManager, resolveThemes } from "./managers/ThemeManager/ThemeManager.mjs";
 import { TickManager } from "./managers/TickManager/TickManager.mjs";
 import { UserPreferencesManager } from "./managers/UserPreferencesManager/UserPreferencesManager.mjs";
 import { RootState } from "./tools/RootState.mjs";
@@ -129,6 +132,7 @@ class Editor extends EventEmitter {
     user,
     shapeUtils,
     bindingUtils,
+    assetUtils: assetUtilConstructors,
     tools,
     getContainer,
     // needs to be here for backwards compatibility with TldrawEditor
@@ -136,13 +140,15 @@ class Editor extends EventEmitter {
     cameraOptions,
     initialState,
     autoFocus,
-    inferDarkMode,
     options: _options,
     // needs to be here for backwards compatibility with TldrawEditor
     // eslint-disable-next-line @typescript-eslint/no-deprecated
     textOptions: _textOptions,
     getShapeVisibility,
-    fontAssetUrls
+    colorScheme,
+    fontAssetUrls,
+    themes,
+    initialTheme
   }) {
     super();
     this._getShapeVisibility = getShapeVisibility;
@@ -165,19 +171,27 @@ class Editor extends EventEmitter {
       ...cameraOptions,
       ...options?.camera
     });
+    this.getContainer = getContainer;
     this._textOptions = atom("text options", options?.text ?? null);
-    this.user = new UserPreferencesManager(user ?? createTLCurrentUser(), inferDarkMode ?? false);
+    this.user = new UserPreferencesManager(user ?? createTLCurrentUser(), colorScheme ?? "light");
     this.disposables.add(() => this.user.dispose());
-    this.getContainer = getContainer;
     this.textMeasure = new TextManager(this);
     this.disposables.add(() => this.textMeasure.dispose());
-    this.fonts = new FontManager(this, fontAssetUrls);
+    this._themeManager = new ThemeManager(this, {
+      themes: resolveThemes(themes),
+      initial: initialTheme ?? "default"
+    });
+    this.disposables.add(() => this._themeManager.dispose());
     this._tickManager = new TickManager(this);
+    this.disposables.add(() => this._tickManager.dispose());
     this.disposables.add(() => {
       this.off("tick", this._decayCameraStateTimeout);
       this._setCameraState("idle");
     });
+    this.fonts = new FontManager(this, fontAssetUrls);
     this.inputs = new InputsManager(this);
+    this.performance = new PerformanceManager(this);
+    this.disposables.add(() => this.performance.dispose());
     class NewRoot extends RootState {
       static initial = initialState ?? "";
     }
@@ -205,6 +219,16 @@ class Editor extends EventEmitter {
     }
     this.shapeUtils = _shapeUtils;
     this.styleProps = _styleProps;
+    const _shapeUtilsByAssetType = {};
+    for (const Util of allShapeUtils) {
+      const assetTypes = Util.handledAssetTypes;
+      if (assetTypes) {
+        for (const assetType of assetTypes) {
+          _shapeUtilsByAssetType[assetType] = _shapeUtils[Util.type];
+        }
+      }
+    }
+    this._shapeUtilsByAssetType = _shapeUtilsByAssetType;
     const allBindingUtils = checkBindings(bindingUtils);
     const _bindingUtils = {};
     for (const Util of allBindingUtils) {
@@ -212,6 +236,15 @@ class Editor extends EventEmitter {
       _bindingUtils[Util.type] = util;
     }
     this.bindingUtils = _bindingUtils;
+    if (assetUtilConstructors) {
+      const allAssetUtils = checkAssets(assetUtilConstructors);
+      const _assetUtils = {};
+      for (const Util of allAssetUtils) {
+        const util = new Util(this);
+        _assetUtils[Util.type] = util;
+      }
+      this.assetUtils = _assetUtils;
+    }
     for (const Tool of [...tools]) {
       if (hasOwnProperty(this.root.children, Tool.id)) {
         throw Error(`Can't override tool with id "${Tool.id}"`);
@@ -652,6 +685,17 @@ class Editor extends EventEmitter {
    * @public
    */
   snaps;
+  /**
+   * A manager for performance measurement hooks.
+   *
+   * @public
+   */
+  performance;
+  /**
+   * A manager for the spatial index, tracking where shapes exist on the canvas.
+   *
+   * @internal
+   */
   _spatialIndex;
   /**
    * A manager for the any asynchronous events and making sure they're
@@ -666,6 +710,12 @@ class Editor extends EventEmitter {
    * @public
    */
   user;
+  /**
+   * A manager for the editor's themes.
+   *
+   * @internal
+   */
+  _themeManager;
   /**
    * A helper for measuring text.
    *
@@ -737,12 +787,117 @@ class Editor extends EventEmitter {
    * @public
    */
   dispose() {
+    this.stopCameraAnimation();
+    if (this.getInstanceState().followingUserId) {
+      this.stopFollowingUser();
+    }
     this.disposables.forEach((dispose) => dispose());
     this.disposables.clear();
+    this.menus.clearOpenMenus();
     this.store.dispose();
     this.isDisposed = true;
     this.emit("dispose");
   }
+  /* ------------------ Themes (shadowing the theme manager) ------------------ */
+  /**
+   * Get the current color mode (`'light'` or `'dark'`), based on the user's dark mode preference.
+   *
+   * @public
+   */
+  getColorMode() {
+    return this._themeManager.getColorMode();
+  }
+  /**
+   * Set the color mode. Note that this is a convenience method that passes the mode to
+   * `user.updateUserPreferences`, which is the source of truth for the user's color mode preference.
+   *
+   * @public
+   */
+  setColorMode(mode) {
+    this.user.updateUserPreferences({ colorScheme: mode });
+    return this;
+  }
+  /**
+   * Get the id of the current theme.
+   *
+   * @public
+   */
+  getCurrentThemeId() {
+    return this._themeManager.getCurrentThemeId();
+  }
+  /**
+   * Get the current theme definition.
+   *
+   * @public
+   */
+  getCurrentTheme() {
+    return this._themeManager.getCurrentTheme();
+  }
+  /**
+   * Set the current theme by id.
+   *
+   * @public
+   */
+  setCurrentTheme(id) {
+    this._themeManager.setCurrentTheme(id);
+    return this;
+  }
+  /**
+   * Get all registered theme definitions.
+   *
+   * @public
+   */
+  getThemes() {
+    return this._themeManager.getThemes();
+  }
+  /**
+   * Get a single theme definition by id.
+   *
+   * @public
+   */
+  getTheme(id) {
+    return this._themeManager.getTheme(id);
+  }
+  /**
+   * Replace all theme definitions, or update them via a callback that receives a deep copy.
+   * The `'default'` theme must always be present in the result.
+   *
+   * @example
+   * ```ts
+   * // Replace all themes
+   * editor.updateThemes({ default: myDefaultTheme, ocean: myOceanTheme })
+   *
+   * // Update via callback
+   * editor.updateThemes((themes) => {
+   *   delete themes.ocean
+   *   return themes
+   * })
+   * ```
+   *
+   * @public
+   */
+  updateThemes(themes) {
+    this._themeManager.updateThemes(themes);
+    return this;
+  }
+  /**
+   * Register or update a single theme definition. The theme is keyed by its `id` property.
+   *
+   * @example
+   * ```ts
+   * // Override a property on the default theme
+   * editor.updateTheme({ ...editor.getTheme('default')!, fontSize: 24 })
+   *
+   * // Register a new theme
+   * editor.updateTheme({ id: 'ocean', ...myOceanTheme })
+   * ```
+   *
+   * @public
+   */
+  updateTheme(theme) {
+    this._themeManager.updateTheme(theme);
+    return this;
+  }
   /* ------------------- Shape Utils ------------------ */
   /**
    * A map of shape utility classes (TLShapeUtils) by shape type.
@@ -750,6 +905,8 @@ class Editor extends EventEmitter {
    * @public
    */
   shapeUtils;
+  /** @internal */
+  _shapeUtilsByAssetType = {};
   styleProps;
   getShapeUtil(arg) {
     const type = typeof arg === "string" ? arg : arg.type;
@@ -761,6 +918,17 @@ class Editor extends EventEmitter {
     const type = typeof arg === "string" ? arg : arg.type;
     return hasOwnProperty(this.shapeUtils, type);
   }
+  /**
+   * Get the shape util that handles the given asset type.
+   * Returns the shape util whose {@link ShapeUtil.handledAssetTypes} includes
+   * the given asset type, or undefined if none matches.
+   *
+   * @param assetType - The asset type string.
+   * @public
+   */
+  getShapeUtilForAssetType(assetType) {
+    return getOwnProperty(this._shapeUtilsByAssetType, assetType);
+  }
   /* ------------------- Binding Utils ------------------ */
   /**
    * A map of shape utility classes (TLShapeUtils) by shape type.
@@ -774,6 +942,42 @@ class Editor extends EventEmitter {
     assert(bindingUtil, `No binding util found for type "${type}"`);
     return bindingUtil;
   }
+  /* ------------------- Asset Utils ------------------ */
+  /**
+   * A map of asset utility classes by asset type.
+   *
+   * @public
+   */
+  assetUtils = {};
+  getAssetUtil(arg) {
+    const type = typeof arg === "string" ? arg : arg.type;
+    const assetUtil = getOwnProperty(this.assetUtils, type);
+    assert(assetUtil, `No asset util found for type "${type}"`);
+    return assetUtil;
+  }
+  /**
+   * Returns true if the editor has an asset util for the given asset type.
+   *
+   * @public
+   */
+  hasAssetUtil(arg) {
+    const type = typeof arg === "string" ? arg : arg.type;
+    return hasOwnProperty(this.assetUtils, type);
+  }
+  /**
+   * Get the asset util that accepts the given MIME type.
+   * Returns null if no registered asset util accepts the MIME type.
+   *
+   * @public
+   */
+  getAssetUtilForMimeType(mimeType) {
+    for (const util of Object.values(this.assetUtils)) {
+      if (util && util.acceptsMimeType(mimeType)) {
+        return util;
+      }
+    }
+    return null;
+  }
   /* --------------------- History -------------------- */
   /**
    * A manager for the editor's history.
@@ -795,6 +999,7 @@ class Editor extends EventEmitter {
     this._flushEventsForTick(0);
     this.complete();
     this.history.undo();
+    this.performance._notifyUndoRedo("undo", this.history.getNumUndos(), this.history.getNumRedos());
     return this;
   }
   canUndo() {
@@ -817,6 +1022,7 @@ class Editor extends EventEmitter {
     this._flushEventsForTick(0);
     this.complete();
     this.history.redo();
+    this.performance._notifyUndoRedo("redo", this.history.getNumUndos(), this.history.getNumRedos());
     return this;
   }
   canRedo() {
@@ -3971,7 +4177,7 @@ class Editor extends EventEmitter {
     const searchMargin = Math.max(innerMargin, outerMargin, this.options.hitTestMargin / zoomLevel);
     const candidateIds = this._spatialIndex.getShapeIdsAtPoint(point, searchMargin);
     const shapesToCheck = (opts.renderingOnly ? this.getCurrentPageRenderingShapesSorted() : this.getCurrentPageShapesSorted()).filter((shape) => {
-      if (!candidateIds.has(shape.id) && !this.isShapeOfType(shape, "frame")) return false;
+      if (!candidateIds.has(shape.id) && !this.isShapeFrameLike(shape)) return false;
       if (shape.isLocked && !hitLocked || this.isShapeHidden(shape) || this.isShapeOfType(shape, "group"))
         return false;
       const pageMask = this.getShapeMask(shape);
@@ -3984,14 +4190,16 @@ class Editor extends EventEmitter {
       const geometry = this.getShapeGeometry(shape);
       const isGroup = geometry instanceof Group2d;
       const pointInShapeSpace = this.getPointInShapeSpace(shape, point);
-      if (this.isShapeOfType(shape, "frame") || (this.isShapeOfType(shape, "note") || this.isShapeOfType(shape, "arrow") || this.isShapeOfType(shape, "geo") && shape.props.fill === "none") && this.getShapeUtil(shape).getText(shape)?.trim()) {
+      const shapeUtil = this.getShapeUtil(shape);
+      const isShapeFrameLike = this.isShapeFrameLike(shape);
+      if (isShapeFrameLike || (this.isShapeOfType(shape, "note") || this.isShapeOfType(shape, "arrow") || this.isShapeOfType(shape, "geo") && shape.props.fill === "none") && shapeUtil.getText(shape)?.trim()) {
         for (const childGeometry of geometry.children) {
           if (childGeometry.isLabel && childGeometry.isPointInBounds(pointInShapeSpace)) {
             return shape;
           }
         }
       }
-      if (this.isShapeOfType(shape, "frame")) {
+      if (isShapeFrameLike) {
         const distance2 = geometry.distanceToPoint(pointInShapeSpace, hitFrameInside);
         if (hitFrameInside ? distance2 > 0 && distance2 <= outerMargin || distance2 <= 0 && distance2 > -innerMargin : distance2 > 0 && distance2 <= outerMargin) {
           return inMarginClosestToEdgeHit || shape;
@@ -4085,7 +4293,7 @@ class Editor extends EventEmitter {
     const candidateIds = this._spatialIndex.getShapeIdsAtPoint(point, margin);
     return this.getCurrentPageShapesSorted().filter((shape) => {
       if (this.isShapeHidden(shape)) return false;
-      if (!candidateIds.has(shape.id) && !this.isShapeOfType(shape, "frame")) return false;
+      if (!candidateIds.has(shape.id) && !this.isShapeFrameLike(shape)) return false;
       return this.isPointInShape(shape, point, opts);
     }).reverse();
   }
@@ -4198,6 +4406,24 @@ class Editor extends EventEmitter {
     if (!shape) return false;
     return shape.type === type;
   }
+  /**
+   * Get whether a shape behaves like a frame — a container that has child
+   * shapes, requires full-brush selection, blocks erasure from inside, etc.
+   *
+   * @example
+   * ```ts
+   * const isFrameLike = editor.isShapeFrameLike(someShape)
+   * ```
+   *
+   * @param shape - The shape (or shape id) to test.
+   *
+   * @public
+   */
+  isShapeFrameLike(shape) {
+    const _shape = typeof shape === "string" ? this.getShape(shape) : shape;
+    if (!_shape) return false;
+    return this.getShapeUtil(_shape).isFrameLike(_shape);
+  }
   /**
    * Get a shape by its id.
    *
@@ -7723,6 +7949,7 @@ class Editor extends EventEmitter {
               ),
               { immediate: true }
             );
+            this.performance._notifyCameraOperation("zooming");
             this.emit("event", info);
             return;
           }
@@ -7784,6 +8011,7 @@ class Editor extends EventEmitter {
                 immediate: true
               });
               this.maybeTrackPerformance("Zooming");
+              this.performance._notifyCameraOperation("zooming");
               this.root.handleEvent(info);
               this.emit("event", info);
               return;
@@ -7793,6 +8021,7 @@ class Editor extends EventEmitter {
                 immediate: true
               });
               this.maybeTrackPerformance("Panning");
+              this.performance._notifyCameraOperation("panning");
               this.root.handleEvent(info);
               this.emit("event", info);
               return;
@@ -7839,6 +8068,10 @@ class Editor extends EventEmitter {
               }
               this.inputs.setIsPanning(true);
               clearTimeout(this._longPressTimeout);
+            } else if (info.button === RIGHT_MOUSE_BUTTON && this.options.rightClickPanning) {
+              this.inputs.setIsRightPointing(true);
+              clearTimeout(this._longPressTimeout);
+              return this;
             }
             if (this.inputs.getIsPanning()) {
               this.stopCameraAnimation();
@@ -7850,6 +8083,22 @@ class Editor extends EventEmitter {
           case "pointer_move": {
             if (!isPen && isPenMode) return;
             const { x: cx, y: cy, z: cz } = unsafe__withoutCapture(() => this.getCamera());
+            if (this.inputs.getIsRightPointing() && !this.inputs.getIsPanning()) {
+              const currentScreenPoint = this.inputs.getCurrentScreenPoint();
+              const originScreenPoint = this.inputs.getOriginScreenPoint();
+              if (Vec.Dist2(originScreenPoint, currentScreenPoint) > this.options.dragDistanceSquared) {
+                this._prevCursor = this.getInstanceState().cursor.type;
+                this.inputs.setIsPanning(true);
+                this.setCursor({ type: "grabbing", rotation: 0 });
+                this.stopCameraAnimation();
+                const offset = Vec.Sub(currentScreenPoint, originScreenPoint);
+                this.setCamera(new Vec(cx + offset.x / cz, cy + offset.y / cz, cz), {
+                  immediate: true
+                });
+                this.maybeTrackPerformance("Panning");
+              }
+              return;
+            }
             if (this.inputs.getIsPanning() && this.inputs.getIsPointing()) {
               const currentScreenPoint = this.inputs.getCurrentScreenPoint();
               const previousScreenPoint = this.inputs.getPreviousScreenPoint();
@@ -7858,6 +8107,7 @@ class Editor extends EventEmitter {
                 immediate: true
               });
               this.maybeTrackPerformance("Panning");
+              this.performance._notifyCameraOperation("panning");
               return;
             }
             if (inputs.getIsPointing() && !inputs.getIsDragging() && Vec.Dist2(inputs.getOriginPagePoint(), inputs.getCurrentPagePoint()) * this.getZoomLevel() > (instanceState.isCoarsePointer ? this.options.coarseDragDistanceSquared : this.options.dragDistanceSquared) / cz) {
@@ -7872,6 +8122,12 @@ class Editor extends EventEmitter {
             clearTimeout(this._longPressTimeout);
             inputs.buttons.delete(info.button);
             if (instanceState.isPenMode && !isPen) return;
+            if (this.inputs.getIsRightPointing() && !this.inputs.getIsPanning()) {
+              this.inputs.setIsRightPointing(false);
+              this._selectedShapeIdsAtPointerDown = [];
+              break;
+            }
+            this.inputs.setIsRightPointing(false);
             if (this.capturedPointerId === info.pointerId) {
               this.capturedPointerId = null;
               info.button = 0;
@@ -7889,11 +8145,24 @@ class Editor extends EventEmitter {
                   break;
                 }
                 case MIDDLE_MOUSE_BUTTON: {
-                  if (this.inputs.keys.has(" ")) {
+                  if (this.inputs.keys.has("Space")) {
+                    this.setCursor({ type: "grab", rotation: 0 });
+                  } else {
+                    this.setCursor({ type: this._prevCursor, rotation: 0 });
+                  }
+                  break;
+                }
+                case RIGHT_MOUSE_BUTTON: {
+                  if (this.inputs.keys.has("Space")) {
                     this.setCursor({ type: "grab", rotation: 0 });
                   } else {
                     this.setCursor({ type: this._prevCursor, rotation: 0 });
                   }
+                  if (slideSpeed > 0) {
+                    this.slideCamera({ speed: slideSpeed, direction: slideDirection });
+                  }
+                  this._selectedShapeIdsAtPointerDown = [];
+                  return this;
                 }
               }
               if (slideSpeed > 0) {