@tldraw/editor 3.8.0-canary.c5f3975feaab → 3.8.0-canary.c738f8c4d6db

package/dist-esm/index.d.mts

@@ -68,6 +68,7 @@ import { TLPropsMigrations } from '@tldraw/tlschema';
 import { TLRecord } from '@tldraw/tlschema';
 import { TLScribble } from '@tldraw/tlschema';
 import { TLShape } from '@tldraw/tlschema';
+import { TLShapeCrop } from '@tldraw/tlschema';
 import { TLShapeId } from '@tldraw/tlschema';
 import { TLShapePartial } from '@tldraw/tlschema';
 import { TLStore } from '@tldraw/tlschema';
@@ -90,6 +91,8 @@ import { useValue } from '@tldraw/state-react';
 import { VecModel } from '@tldraw/tlschema';
 import { whyAmIRunning } from '@tldraw/state';
 
+/* Excluded from this release type: activeElementShouldCaptureKeys */
+
 /**
  * Get the angle of a point on an arc.
  * @param fromAngle - The angle from center to arc's start point (A) on the circle
@@ -536,6 +539,8 @@ export declare type BoxLike = Box | BoxModel;
  */
 export declare function canonicalizeRotation(a: number): number;
 
+/* Excluded from this release type: CanvasMaxSize */
+
 /**
  * Get the center of a circle from three points.
  *
@@ -615,6 +620,8 @@ export declare function clamp(n: number, min: number, max: number): number;
  */
 export declare function clampRadians(r: number): number;
 
+/* Excluded from this release type: clampToBrowserMaxCanvasSize */
+
 /** @public */
 export declare class ClickManager {
     editor: Editor;
@@ -847,6 +854,7 @@ export declare const defaultTldrawOptions: {
     readonly edgeScrollDistance: 8;
     readonly edgeScrollEaseDuration: 200;
     readonly edgeScrollSpeed: 25;
+    readonly enableToolbarKeyboardShortcuts: true;
     readonly exportProvider: ExoticComponent<    {
     children?: ReactNode;
     }>;
@@ -877,7 +885,6 @@ export declare const defaultTldrawOptions: {
     readonly maxExportDelayMs: 5000;
     readonly maxFilesAtOnce: 100;
     readonly maxPages: 40;
-    readonly maxPointsPerDrawShape: 500;
     readonly maxShapesPerPage: 4000;
     readonly multiClickDurationMs: 200;
     readonly temporaryAssetPreviewLifetimeMs: 180000;
@@ -1113,6 +1120,14 @@ export declare class Editor extends EventEmitter<TLEventMap> {
     getShapeUtil<S extends TLUnknownShape>(shape: S | TLShapePartial<S>): ShapeUtil<S>;
     getShapeUtil<S extends TLUnknownShape>(type: S['type']): ShapeUtil<S>;
     getShapeUtil<T extends ShapeUtil>(type: T extends ShapeUtil<infer R> ? R['type'] : string): T;
+    /**
+     * Returns true if the editor has a shape util for the given shape / shape type.
+     *
+     * @param shape - A shape, shape partial, or shape type.
+     */
+    hasShapeUtil<S extends TLUnknownShape>(shape: S | TLShapePartial<S>): boolean;
+    hasShapeUtil<S extends TLUnknownShape>(type: S['type']): boolean;
+    hasShapeUtil<T extends ShapeUtil>(type: T extends ShapeUtil<infer R> ? R['type'] : string): boolean;
     /**
      * A map of shape utility classes (TLShapeUtils) by shape type.
      *
@@ -1365,8 +1380,8 @@ export declare class Editor extends EventEmitter<TLEventMap> {
      *
      * @example
      * ```ts
-     * state.getStateDescendant('select')
-     * state.getStateDescendant('select.brushing')
+     * editor.getStateDescendant('select')
+     * editor.getStateDescendant('select.brushing')
      * ```
      *
      * @param path - The descendant's path of state ids, separated by periods.
@@ -2348,6 +2363,7 @@ export declare class Editor extends EventEmitter<TLEventMap> {
      */
     getAsset<T extends TLAsset>(asset: T | T['id']): T | undefined;
     resolveAssetUrl(assetId: null | TLAssetId, context: {
+        dpr?: number;
         screenScale?: number;
         shouldResolveToOriginal?: boolean;
     }): Promise<null | string>;
@@ -2355,7 +2371,10 @@ export declare class Editor extends EventEmitter<TLEventMap> {
      * Upload an asset to the store's asset service, returning a URL that can be used to resolve the
      * asset.
      */
-    uploadAsset(asset: TLAsset, file: File, abortSignal?: AbortSignal): Promise<string>;
+    uploadAsset(asset: TLAsset, file: File, abortSignal?: AbortSignal): Promise<{
+        meta?: JsonObject;
+        src: string;
+    }>;
     private _getShapeGeometryCache;
     /**
      * Get the geometry of a shape.
@@ -3426,7 +3445,7 @@ export declare class Editor extends EventEmitter<TLEventMap> {
      *
      * @public
      */
-    registerExternalAssetHandler<T extends TLExternalAssetContent['type']>(type: T, handler: ((info: TLExternalAssetContent & {
+    registerExternalAssetHandler<T extends TLExternalAsset['type']>(type: T, handler: ((info: TLExternalAsset & {
         type: T;
     }) => Promise<TLAsset>) | null): this;
     /**
@@ -3472,8 +3491,8 @@ export declare class Editor extends EventEmitter<TLEventMap> {
      * @param info - Info about the external content.
      * @returns The asset.
      */
-    getAssetForExternalContent(info: TLExternalAssetContent): Promise<TLAsset | undefined>;
-    hasExternalAssetHandler(type: TLExternalAssetContent['type']): boolean;
+    getAssetForExternalContent(info: TLExternalAsset): Promise<TLAsset | undefined>;
+    hasExternalAssetHandler(type: TLExternalAsset['type']): boolean;
     /* Excluded from this release type: externalContentHandlers */
     /**
      * Register an external content handler. This handler will be called when the editor receives
@@ -3494,9 +3513,9 @@ export declare class Editor extends EventEmitter<TLEventMap> {
      *
      * @public
      */
-    registerExternalContentHandler<T extends TLExternalContent<E>['type'], E>(type: T, handler: ((info: T extends TLExternalContent<E>['type'] ? TLExternalContent<E> & {
+    registerExternalContentHandler<T extends TLExternalContent<E>['type'], E>(type: T, handler: ((info: T extends TLExternalContent<E>['type'] ? Extract<TLExternalContent<E>, {
         type: T;
-    } : TLExternalContent<E>) => void) | null): this;
+    }> : TLExternalContent<E>) => void) | null): this;
     /**
      * Handle external content, such as files, urls, embeds, or plain text which has been put into the app, for example by pasting external text or dropping external images onto canvas.
      *
@@ -3538,7 +3557,7 @@ export declare class Editor extends EventEmitter<TLEventMap> {
      *
      * @public
      */
-    getSvgElement(shapes: TLShape[] | TLShapeId[], opts?: TLImageExportOptions): Promise<{
+    getSvgElement(shapes: TLShape[] | TLShapeId[], opts?: TLSvgExportOptions): Promise<{
         height: number;
         svg: SVGSVGElement;
         width: number;
@@ -3553,13 +3572,27 @@ export declare class Editor extends EventEmitter<TLEventMap> {
      *
      * @public
      */
-    getSvgString(shapes: TLShape[] | TLShapeId[], opts?: TLImageExportOptions): Promise<{
+    getSvgString(shapes: TLShape[] | TLShapeId[], opts?: TLSvgExportOptions): Promise<{
         height: number;
         svg: string;
         width: number;
     } | undefined>;
     /** @deprecated Use {@link Editor.getSvgString} or {@link Editor.getSvgElement} instead. */
-    getSvg(shapes: TLShape[] | TLShapeId[], opts?: TLImageExportOptions): Promise<SVGSVGElement | undefined>;
+    getSvg(shapes: TLShape[] | TLShapeId[], opts?: TLSvgExportOptions): Promise<SVGSVGElement | undefined>;
+    /**
+     * Get an exported image of the given shapes.
+     *
+     * @param shapes - The shapes (or shape ids) to export.
+     * @param opts - Options for the export.
+     *
+     * @returns A blob of the image.
+     * @public
+     */
+    toImage(shapes: TLShape[] | TLShapeId[], opts?: TLImageExportOptions): Promise<{
+        blob: Blob;
+        height: number;
+        width: number;
+    }>;
     /**
      * The app's current input state.
      *
@@ -4073,6 +4106,15 @@ export declare function getPolygonVertices(width: number, height: number, sides:
 /** @public */
 export declare function getSnapshot(store: TLStore): TLEditorSnapshot;
 
+/** @public */
+export declare function getSvgAsImage(svgString: string, options: {
+    height: number;
+    pixelRatio?: number;
+    quality?: number;
+    type: 'jpeg' | 'png' | 'webp';
+    width: number;
+}): Promise<Blob | null>;
+
 /**
  * Turn an array of points into a path of quadradic curves.
  *
@@ -4652,6 +4694,23 @@ export declare interface ResizeBoxOptions {
     maxHeight?: number;
 }
 
+/**
+ * Resize a shape that has a scale prop.
+ *
+ * @param shape - The shape to resize
+ * @param info - The resize info
+ *
+ * @public */
+export declare function resizeScaled(shape: TLBaseShape<any, {
+    scale: number;
+}>, { initialBounds, scaleX, scaleY, newPoint, handle }: TLResizeInfo<any>): {
+    props: {
+        scale: number;
+    };
+    x: number;
+    y: number;
+};
+
 /** @public */
 export declare const ROTATE_CORNER_TO_SELECTION_CORNER: {
     readonly bottom_left_rotate: "bottom_left";
@@ -4755,7 +4814,17 @@ export declare function setUserPreferences(user: TLUserPreferences): void;
 /** @public */
 export declare abstract class ShapeUtil<Shape extends TLUnknownShape = TLUnknownShape> {
     editor: Editor;
+    /** Configure this shape utils {@link ShapeUtil.options | `options`}. */
+    static configure<T extends TLShapeUtilConstructor<any, any>>(this: T, options: T extends new (...args: any[]) => {
+        options: infer Options;
+    } ? Partial<Options> : never): T;
     constructor(editor: Editor);
+    /**
+     * Options for this shape util. If you're implementing a custom shape util, you can override
+     * this to provide customization options for your shape. If using an existing shape util, you
+     * can customizing this by calling {@link ShapeUtil.configure}.
+     */
+    options: {};
     /**
      * Props allow you to define the shape's properties in a way that the editor can understand.
      * This has two main uses:
@@ -5023,6 +5092,15 @@ export declare abstract class ShapeUtil<Shape extends TLUnknownShape = TLUnknown
      * @public
      */
     onBeforeUpdate?(prev: Shape, next: Shape): Shape | void;
+    /**
+     * A callback called when a shape changes from a crop.
+     *
+     * @param shape - The shape at the start of the crop.
+     * @param info - Info about the crop.
+     * @returns A change to apply to the shape, or void.
+     * @public
+     */
+    onCrop?(shape: Shape, info: TLCropInfo<Shape>): Omit<TLShapePartial<Shape>, 'id' | 'type'> | undefined | void;
     /**
      * A callback called when some other shapes are dragged over this one.
      *
@@ -5404,10 +5482,27 @@ export declare interface SvgExportContext {
      * method depending on your use-case.
      */
     waitUntil(promise: Promise<void>): void;
+    /**
+     * Resolve an asset URL in the context of this export. Supply the asset ID and the width in
+     * shape-pixels it'll be displayed at, and this will resolve the asset according to the export
+     * options.
+     */
+    resolveAssetUrl(assetId: TLAssetId, width: number): Promise<null | string>;
     /**
      * Whether the export should be in dark mode.
      */
     readonly isDarkMode: boolean;
+    /**
+     * The scale of the export - how much CSS pixels will be scaled up/down by.
+     */
+    readonly scale: number;
+    /**
+     * Use this value to optionally downscale images in the export. If we're exporting directly to
+     * an SVG, this will usually be null, and you shouldn't downscale images. If the export is to a
+     * raster format like PNG, this will be the number of raster pixels in the resulting bitmap per
+     * CSS pixel in the resulting SVG.
+     */
+    readonly pixelRatio: null | number;
 }
 
 /** @public */
@@ -5498,6 +5593,12 @@ export declare interface TLBaseEventInfo {
     accelKey: boolean;
 }
 
+/** @public */
+export declare interface TLBaseExternalContent {
+    sources?: TLExternalContentSource[];
+    point?: VecLike;
+}
+
 /** @public */
 export declare interface TLBindingUtilConstructor<T extends TLUnknownBinding, U extends BindingUtil<T> = BindingUtil<T>> {
     new (editor: Editor): U;
@@ -5663,6 +5764,24 @@ export declare interface TLContent {
     schema: SerializedSchema;
 }
 
+/**
+ * Info about a crop.
+ * @param handle - The handle being dragged.
+ * @param change - The distance the handle is moved.
+ * @param initialShape - The shape at the start of the resize.
+ * @public
+ */
+export declare interface TLCropInfo<T extends TLShape> {
+    handle: SelectionHandle;
+    change: Vec;
+    crop: TLShapeCrop;
+    uncroppedSize: {
+        h: number;
+        w: number;
+    };
+    initialShape: T;
+}
+
 /** @public */
 export declare interface TLCursorProps {
     className?: string;
@@ -5876,7 +5995,6 @@ export declare interface TldrawOptions {
     readonly dragDistanceSquared: number;
     readonly defaultSvgPadding: number;
     readonly cameraSlideFriction: number;
-    readonly maxPointsPerDrawShape: number;
     readonly gridSteps: readonly {
         readonly mid: number;
         readonly min: number;
@@ -5915,6 +6033,10 @@ export declare interface TldrawOptions {
     readonly exportProvider: ComponentType<{
         children: React.ReactNode;
     }>;
+    /**
+     * By default, the toolbar items are accessible via number shortcuts according to their order. To disable this, set this option to false.
+     */
+    readonly enableToolbarKeyboardShortcuts: boolean;
 }
 
 /** @public */
@@ -6016,6 +6138,13 @@ export declare interface TLEditorSnapshot {
     session: TLSessionStateSnapshot;
 }
 
+/** @public */
+export declare interface TLEmbedExternalContent<EmbedDefinition> extends TLBaseExternalContent {
+    type: 'embed';
+    url: string;
+    embed: EmbedDefinition;
+}
+
 /** @public */
 export declare type TLEnterEventHandler = (info: any, from: string) => void;
 
@@ -6041,6 +6170,13 @@ export declare interface TLErrorBoundaryProps {
     fallback: TLErrorFallbackComponent;
 }
 
+/** @public */
+export declare interface TLErrorExternalContentSource {
+    type: 'error';
+    data: null | string;
+    reason: string;
+}
+
 /** @public */
 export declare type TLErrorFallbackComponent = ComponentType<{
     editor?: Editor;
@@ -6086,6 +6222,7 @@ export declare interface TLEventMap {
     }];
     'stop-camera-animation': [];
     'stop-following': [];
+    'before-event': [TLEventInfo];
     event: [TLEventInfo];
     tick: [number];
     frame: [number];
@@ -6100,58 +6237,46 @@ export declare type TLEventMapHandler<T extends keyof TLEventMap> = (...args: TL
 /** @public */
 export declare type TLEventName = 'cancel' | 'complete' | 'interrupt' | 'tick' | 'wheel' | TLCLickEventName | TLKeyboardEventName | TLPinchEventName | TLPointerEventName;
 
+/** @public */
+export declare interface TLExcalidrawExternalContent extends TLBaseExternalContent {
+    type: 'excalidraw';
+    content: any;
+}
+
+/** @public */
+export declare interface TLExcalidrawExternalContentSource {
+    type: 'excalidraw';
+    data: any;
+}
+
 /** @public */
 export declare type TLExitEventHandler = (info: any, to: string) => void;
 
 /** @public */
-export declare type TLExternalAssetContent = {
-    assetId?: TLAssetId;
-    file: File;
+export declare type TLExportType = 'jpeg' | 'png' | 'svg' | 'webp';
+
+/** @public */
+export declare type TLExternalAsset = TLFileExternalAsset | TLUrlExternalAsset;
+
+/** @public */
+export declare type TLExternalContent<EmbedDefinition> = TLEmbedExternalContent<EmbedDefinition> | TLExcalidrawExternalContent | TLFilesExternalContent | TLSvgTextExternalContent | TLTextExternalContent | TLTldrawExternalContent | TLUrlExternalContent;
+
+/** @public */
+export declare type TLExternalContentSource = TLErrorExternalContentSource | TLExcalidrawExternalContentSource | TLTextExternalContentSource | TLTldrawExternalContentSource;
+
+/** @public */
+export declare interface TLFileExternalAsset {
     type: 'file';
-} | {
-    type: 'url';
-    url: string;
-};
+    file: File;
+    assetId?: TLAssetId;
+}
 
 /** @public */
-export declare type TLExternalContent<EmbedDefinition> = {
-    point?: VecLike;
-    sources?: TLExternalContentSource[];
-} & ({
-    embed: EmbedDefinition;
-    type: 'embed';
-    url: string;
-} | {
+export declare interface TLFilesExternalContent extends TLBaseExternalContent {
+    type: 'files';
     files: File[];
     ignoreParent: boolean;
-    type: 'files';
-} | {
-    text: string;
-    type: 'svg-text';
-} | {
-    text: string;
-    type: 'text';
-} | {
-    type: 'url';
-    url: string;
-});
-
-/** @public */
-export declare type TLExternalContentSource = {
-    data: any;
-    type: 'excalidraw';
-} | {
-    data: null | string;
-    reason: string;
-    type: 'error';
-} | {
-    data: string;
-    subtype: 'html' | 'json' | 'text' | 'url';
-    type: 'text';
-} | {
-    data: TLContent;
-    type: 'tldraw';
-};
+}
 
 /** @public */
 export declare interface TLGridProps {
@@ -6209,15 +6334,16 @@ export declare interface TLHistoryMark {
 }
 
 /** @public */
-export declare interface TLImageExportOptions {
-    bounds?: Box;
-    scale?: number;
+export declare interface TLImageExportOptions extends TLSvgExportOptions {
+    /**
+     * If the export is being converted to a lossy bitmap format (e.g. jpeg), this is the quality of
+     * the export. This is a number between 0 and 1.
+     */
     quality?: number;
-    pixelRatio?: number;
-    background?: boolean;
-    padding?: number;
-    darkMode?: boolean;
-    preserveAspectRatio?: React.SVGAttributes<SVGSVGElement>['preserveAspectRatio'];
+    /**
+     * The format to export as. Defaults to 'png'.
+     */
+    format?: TLExportType;
 }
 
 /** @public */
@@ -6721,12 +6847,75 @@ export declare type TLStoreWithStatus = {
     readonly store: TLStore;
 };
 
+/** @public */
+export declare interface TLSvgExportOptions {
+    /**
+     * The bounding box, in page coordinates, of the area being exported.
+     */
+    bounds?: Box;
+    /**
+     * The logical scale of the export. This scales the resulting size of the SVG being generated.
+     */
+    scale?: number;
+    /**
+     * When exporting an SVG, the expected pixel ratio of the export will be passed in to
+     * {@link @tldraw/tlschema#TLAssetStore.resolve} as the `dpr` property, so that assets can be
+     * downscaled to the appropriate resolution.
+     *
+     * When exporting to a bitmap image format, the size of the resulting image will be multiplied
+     * by this number.
+     *
+     * For SVG exports, this defaults to undefined - which means we'll request original-quality
+     * assets. For bitmap exports, this defaults to 2.
+     */
+    pixelRatio?: number;
+    /**
+     * Should the background color be included in the export? If false, the generated image will be
+     * transparent (if exporting to a format that supports transparency).
+     */
+    background?: boolean;
+    /**
+     * How much padding to include around the bounds of exports? Defaults to 32px.
+     */
+    padding?: number;
+    /**
+     * Should the export be rendered in dark mode (true) or light mode (false)? Defaults to the
+     * current instance's dark mode setting.
+     */
+    darkMode?: boolean;
+    /**
+     * The
+     * {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/preserveAspectRatio | `preserveAspectRatio` }
+     * attribute of the SVG element.
+     */
+    preserveAspectRatio?: React.SVGAttributes<SVGSVGElement>['preserveAspectRatio'];
+}
+
 /**
  * @public
  * @deprecated use {@link TLImageExportOptions} instead
  */
 export declare type TLSvgOptions = TLImageExportOptions;
 
+/** @public */
+export declare interface TLSvgTextExternalContent extends TLBaseExternalContent {
+    type: 'svg-text';
+    text: string;
+}
+
+/** @public */
+export declare interface TLTextExternalContent extends TLBaseExternalContent {
+    type: 'text';
+    text: string;
+}
+
+/** @public */
+export declare interface TLTextExternalContentSource {
+    type: 'text';
+    data: string;
+    subtype: 'html' | 'json' | 'text' | 'url';
+}
+
 /** @public */
 export declare type TLTickEvent = (info: TLTickEventInfo) => void;
 
@@ -6744,6 +6933,30 @@ export declare interface TLTickEventInfo {
  */
 export declare const tltime: Timers;
 
+/** @public */
+export declare interface TLTldrawExternalContent extends TLBaseExternalContent {
+    type: 'tldraw';
+    content: TLContent;
+}
+
+/** @public */
+export declare interface TLTldrawExternalContentSource {
+    type: 'tldraw';
+    data: TLContent;
+}
+
+/** @public */
+export declare interface TLUrlExternalAsset {
+    type: 'url';
+    url: string;
+}
+
+/** @public */
+export declare interface TLUrlExternalContent extends TLBaseExternalContent {
+    type: 'url';
+    url: string;
+}
+
 /** @public */
 export declare interface TLUser {
     readonly userPreferences: Signal<TLUserPreferences>;

package/dist-esm/index.mjs

@@ -23,6 +23,7 @@ import {
   useStateTracking,
   useValue
 } from "@tldraw/state-react";
+import { resizeScaled } from "./lib/editor/shapes/shared/resizeScaled.mjs";
 import { LocalIndexedDb, Table } from "./lib/utils/sync/LocalIndexedDb.mjs";
 export * from "@tldraw/store";
 export * from "@tldraw/tlschema";
@@ -142,6 +143,7 @@ import {
 import {
   EVENT_NAME_MAP
 } from "./lib/editor/types/event-types.mjs";
+import { getSvgAsImage } from "./lib/exports/getSvgAsImage.mjs";
 import { tlenv } from "./lib/globals/environment.mjs";
 import { tlmenus } from "./lib/globals/menus.mjs";
 import { tltime } from "./lib/globals/time.mjs";
@@ -250,6 +252,7 @@ import {
   SharedStyleMap
 } from "./lib/utils/SharedStylesMap.mjs";
 import { dataUrlToFile, getDefaultCdnBaseUrl } from "./lib/utils/assets.mjs";
+import { clampToBrowserMaxCanvasSize } from "./lib/utils/browserCanvasMaxSize.mjs";
 import {
   debugFlags,
   featureFlags
@@ -259,6 +262,7 @@ import {
   parseDeepLinkString
 } from "./lib/utils/deepLinks.mjs";
 import {
+  activeElementShouldCaptureKeys,
   loopToHtmlElement,
   preventDefault,
   releasePointerCapture,
@@ -285,7 +289,7 @@ function debugEnableLicensing() {
 }
 registerTldrawLibraryVersion(
   "@tldraw/editor",
-  "3.8.0-canary.c5f3975feaab",
+  "3.8.0-canary.c738f8c4d6db",
   "esm"
 );
 export {
@@ -367,6 +371,7 @@ export {
   USER_COLORS,
   UserPreferencesManager,
   Vec,
+  activeElementShouldCaptureKeys,
   angleDistance,
   applyRotationToSnapshotShapes,
   approximately,
@@ -377,6 +382,7 @@ export {
   centerOfCircleFromThreePoints,
   clamp,
   clampRadians,
+  clampToBrowserMaxCanvasSize,
   clockwiseAngleDist,
   computed,
   coreShapes,
@@ -407,6 +413,7 @@ export {
   getPolygonVertices,
   getRotationSnapshot,
   getSnapshot,
+  getSvgAsImage,
   getSvgPathFromPoints,
   getUserPreferences,
   hardReset,
@@ -443,6 +450,7 @@ export {
   refreshPage,
   releasePointerCapture,
   resizeBox,
+  resizeScaled,
   rotateSelectionHandle,
   runtime,
   sanitizeId,