better auto-generated docs for Tldraw and TldrawEditor (#4012)

Simplify the types used by the props of the `Tldraw` and `TldrawEditor`
components. This doesn't make the docs perfect, but it makes them quite
a bit better than they were.


![image](https://github.com/tldraw/tldraw/assets/1489520/66c72e0e-c22b-4414-b194-f0598e4a3736)


### Change Type

- [x] `sdk` — Changes the tldraw SDK
- [x] `docs` — Changes to the documentation, examples, or templates.
- [x] `improvement` — Improving existing features

packages/editor/api-report.md

@@ -15,7 +15,6 @@ import { computed } from '@tldraw/state';
 import { EmbedDefinition } from '@tldraw/tlschema';
 import { EMPTY_ARRAY } from '@tldraw/state';
 import EventEmitter from 'eventemitter3';
-import { Expand } from '@tldraw/utils';
 import { HistoryEntry } from '@tldraw/store';
 import { IndexKey } from '@tldraw/utils';
 import { JsonObject } from '@tldraw/utils';
@@ -67,7 +66,6 @@ import { TLParentId } from '@tldraw/tlschema';
 import { TLPropsMigrations } from '@tldraw/tlschema';
 import { TLRecord } from '@tldraw/tlschema';
 import { TLScribble } from '@tldraw/tlschema';
-import { TLSerializedStore } from '@tldraw/tlschema';
 import { TLShape } from '@tldraw/tlschema';
 import { TLShapeId } from '@tldraw/tlschema';
 import { TLShapePartial } from '@tldraw/tlschema';
@@ -2539,17 +2537,26 @@ export interface TldrawEditorBaseProps {
 }
 
 // @public
-export type TldrawEditorProps = Expand<TldrawEditorBaseProps & ({
+export type TldrawEditorProps = TldrawEditorBaseProps & TldrawEditorStoreProps;
-    defaultName?: string;
+
-    initialData?: TLSerializedStore;
+// @public (undocumented)
+export type TldrawEditorStoreProps = TldrawEditorWithoutStoreProps | TldrawEditorWithStoreProps;
+
+// @public
+export interface TldrawEditorWithoutStoreProps extends TLStoreBaseOptions {
     migrations?: readonly MigrationSequence[];
     persistenceKey?: string;
+    // (undocumented)
     sessionId?: string;
     snapshot?: TLEditorSnapshot | TLStoreSnapshot;
+    // (undocumented)
     store?: undefined;
-} | {
+}
+
+// @public
+export interface TldrawEditorWithStoreProps {
     store: TLStore | TLStoreWithStatus;
-})>;
+}
 
 // @public
 export interface TldrawOptions {
@@ -3256,19 +3263,23 @@ export interface TLStateNodeConstructor {
     initial?: string;
 }
 
+// @public (undocumented)
+export interface TLStoreBaseOptions {
+    defaultName?: string;
+    initialData?: SerializedStore<TLRecord>;
+}
+
 // @public (undocumented)
 export type TLStoreEventInfo = HistoryEntry<TLRecord>;
 
 // @public (undocumented)
-export type TLStoreOptions = {
+export type TLStoreOptions = TLStoreBaseOptions & ({
-    defaultName?: string;
-    id?: string;
-    initialData?: SerializedStore<TLRecord>;
-} & ({
     bindingUtils?: readonly TLAnyBindingUtilConstructor[];
+    id?: string;
     migrations?: readonly MigrationSequence[];
     shapeUtils?: readonly TLAnyShapeUtilConstructor[];
 } | {
+    id?: string;
     schema?: StoreSchema<TLRecord, TLStoreProps>;
 });
 

packages/editor/src/index.ts

@@ -40,6 +40,9 @@ export {
 	type TLOnMountHandler,
 	type TldrawEditorBaseProps,
 	type TldrawEditorProps,
+	type TldrawEditorStoreProps,
+	type TldrawEditorWithStoreProps,
+	type TldrawEditorWithoutStoreProps,
 } from './lib/TldrawEditor'
 export {
 	ErrorBoundary,
@@ -117,6 +120,7 @@ export {
 } from './lib/config/TLUserPreferences'
 export {
 	createTLStore,
+	type TLStoreBaseOptions,
 	type TLStoreEventInfo,
 	type TLStoreOptions,
 } from './lib/config/createTLStore'

packages/editor/src/lib/TldrawEditor.tsx

@@ -1,6 +1,6 @@
 import { MigrationSequence, Store } from '@tldraw/store'
-import { TLSerializedStore, TLStore, TLStoreSnapshot } from '@tldraw/tlschema'
+import { TLStore, TLStoreSnapshot } from '@tldraw/tlschema'
-import { Expand, Required, annotateError } from '@tldraw/utils'
+import { Required, annotateError } from '@tldraw/utils'
 import React, {
 	ReactNode,
 	memo,
@@ -16,6 +16,7 @@ import classNames from 'classnames'
 import { OptionalErrorBoundary } from './components/ErrorBoundary'
 import { DefaultErrorFallback } from './components/default-components/DefaultErrorFallback'
 import { TLEditorSnapshot } from './config/TLEditorSnapshot'
+import { TLStoreBaseOptions } from './config/createTLStore'
 import { TLUser, createTLUser } from './config/createTLUser'
 import { TLAnyBindingUtilConstructor } from './config/defaultBindings'
 import { TLAnyShapeUtilConstructor } from './config/defaultShapes'
@@ -39,28 +40,59 @@ import { TldrawOptions } from './options'
 import { stopEventPropagation } from './utils/dom'
 import { TLStoreWithStatus } from './utils/sync/StoreWithStatus'
 
+/**
+ * Props for the {@link tldraw#Tldraw} and {@link TldrawEditor} components, when passing in a
+ * {@link store#TLStore} directly. If you would like tldraw to create a store for you, use
+ * {@link TldrawEditorWithoutStoreProps}.
+ *
+ * @public
+ */
+export interface TldrawEditorWithStoreProps {
+	/**
+	 * The store to use in the editor.
+	 */
+	store: TLStore | TLStoreWithStatus
+}
+
+/**
+ * Props for the {@link tldraw#Tldraw} and {@link TldrawEditor} components, when not passing in a
+ * {@link store#TLStore} directly. If you would like to pass in a store directly, use
+ * {@link TldrawEditorWithStoreProps}.
+ *
+ * @public
+ */
+export interface TldrawEditorWithoutStoreProps extends TLStoreBaseOptions {
+	store?: undefined
+
+	/**
+	 * Additional migrations to use in the store
+	 */
+	migrations?: readonly MigrationSequence[]
+
+	/**
+	 * A starting snapshot of data to pre-populate the store. Do not supply both this and
+	 * `initialData`.
+	 */
+	snapshot?: TLEditorSnapshot | TLStoreSnapshot
+
+	/**
+	 * If you would like to persist the store to the browser's local IndexedDB storage and sync it
+	 * across tabs, provide a key here. Each key represents a single tldraw document.
+	 */
+	persistenceKey?: string
+
+	sessionId?: string
+}
+
+/** @public */
+export type TldrawEditorStoreProps = TldrawEditorWithStoreProps | TldrawEditorWithoutStoreProps
+
 /**
  * Props for the {@link tldraw#Tldraw} and {@link TldrawEditor} components.
  *
  * @public
  **/
-export type TldrawEditorProps = Expand<
+export type TldrawEditorProps = TldrawEditorBaseProps & TldrawEditorStoreProps
-	TldrawEditorBaseProps &
-		(
-			| {
-					store: TLStore | TLStoreWithStatus
-			  }
-			| {
-					store?: undefined
-					migrations?: readonly MigrationSequence[]
-					snapshot?: TLEditorSnapshot | TLStoreSnapshot
-					initialData?: TLSerializedStore
-					persistenceKey?: string
-					sessionId?: string
-					defaultName?: string
-			  }
-		)
->
 
 /**
  * Base props for the {@link tldraw#Tldraw} and {@link TldrawEditor} components.

packages/editor/src/lib/config/createTLStore.ts

@@ -4,18 +4,28 @@ import { TLAnyBindingUtilConstructor, checkBindings } from './defaultBindings'
 import { TLAnyShapeUtilConstructor, checkShapesAndAddCore } from './defaultShapes'
 
 /** @public */
-export type TLStoreOptions = {
+export interface TLStoreBaseOptions {
+	/** The initial data for the store. */
 	initialData?: SerializedStore<TLRecord>
+
+	/** The default name for the store. */
 	defaultName?: string
-	id?: string
+}
-} & (
+
-	| {
+/** @public */
-			shapeUtils?: readonly TLAnyShapeUtilConstructor[]
+export type TLStoreOptions = TLStoreBaseOptions &
-			migrations?: readonly MigrationSequence[]
+	(
-			bindingUtils?: readonly TLAnyBindingUtilConstructor[]
+		| {
-	  }
+				id?: string
-	| { schema?: StoreSchema<TLRecord, TLStoreProps> }
+				shapeUtils?: readonly TLAnyShapeUtilConstructor[]
-)
+				migrations?: readonly MigrationSequence[]
+				bindingUtils?: readonly TLAnyBindingUtilConstructor[]
+		  }
+		| {
+				id?: string
+				schema?: StoreSchema<TLRecord, TLStoreProps>
+		  }
+	)
 
 /** @public */
 export type TLStoreEventInfo = HistoryEntry<TLRecord>

packages/tldraw/api-report.md

@@ -23,7 +23,6 @@ import { Editor } from '@tldraw/editor';
 import { EMBED_DEFINITIONS } from '@tldraw/editor';
 import { EmbedDefinition } from '@tldraw/editor';
 import { EnumStyleProp } from '@tldraw/editor';
-import { Expand } from '@tldraw/editor';
 import { Geometry2d } from '@tldraw/editor';
 import { Group2d } from '@tldraw/editor';
 import { HandleSnapGeometry } from '@tldraw/editor';
@@ -71,6 +70,7 @@ import { TLDefaultHorizontalAlignStyle } from '@tldraw/editor';
 import { TLDefaultSizeStyle } from '@tldraw/editor';
 import { TLDefaultVerticalAlignStyle } from '@tldraw/editor';
 import { TldrawEditorBaseProps } from '@tldraw/editor';
+import { TldrawEditorStoreProps } from '@tldraw/editor';
 import { TLDrawShape } from '@tldraw/editor';
 import { TLDrawShapeSegment } from '@tldraw/editor';
 import { TLEditorComponents } from '@tldraw/editor';
@@ -110,7 +110,6 @@ import { TLShapeUtilFlag } from '@tldraw/editor';
 import { TLStateNodeConstructor } from '@tldraw/editor';
 import { TLStore } from '@tldraw/editor';
 import { TLStoreSnapshot } from '@tldraw/editor';
-import { TLStoreWithStatus } from '@tldraw/editor';
 import { TLSvgOptions } from '@tldraw/editor';
 import { TLTextShape } from '@tldraw/editor';
 import { TLVideoShape } from '@tldraw/editor';
@@ -1614,7 +1613,8 @@ export interface TLArrowPoint {
 }
 
 // @public (undocumented)
-export type TLComponents = Expand<TLEditorComponents & TLUiComponents>;
+export interface TLComponents extends TLEditorComponents, TLUiComponents {
+}
 
 // @public (undocumented)
 export type TLCopyType = 'jpeg' | 'json' | 'png' | 'svg';
@@ -1625,6 +1625,12 @@ export function Tldraw(props: TldrawProps): JSX_2.Element;
 // @public (undocumented)
 export const TLDRAW_FILE_EXTENSION: ".tldr";
 
+// @public (undocumented)
+export interface TldrawBaseProps extends TldrawUiProps, TldrawEditorBaseProps, TLExternalContentProps {
+    // (undocumented)
+    components?: TLComponents;
+}
+
 // @public (undocumented)
 export interface TldrawFile {
     // (undocumented)
@@ -1669,18 +1675,7 @@ export interface TldrawImageProps extends TLSvgOptions {
 }
 
 // @public (undocumented)
-export type TldrawProps = Expand<(Omit<TldrawUiProps, 'components'> & Omit<TldrawEditorBaseProps, 'components'> & {
+export type TldrawProps = TldrawBaseProps & TldrawEditorStoreProps;
-    components?: TLComponents;
-}) & Partial<TLExternalContentProps> & ({
-    snapshot?: TLEditorSnapshot | TLStoreSnapshot;
-    defaultName?: string;
-    migrations?: readonly MigrationSequence[];
-    persistenceKey?: string;
-    sessionId?: string;
-    store?: undefined;
-} | {
-    store: TLStore | TLStoreWithStatus;
-})>;
 
 // @public (undocumented)
 export function TldrawScribble({ scribble, zoom, color, opacity, className }: TLScribbleProps): JSX_2.Element | null;
@@ -1838,14 +1833,10 @@ export type TLExportType = 'jpeg' | 'json' | 'png' | 'svg' | 'webp';
 
 // @public (undocumented)
 export interface TLExternalContentProps {
-    // (undocumented)
+    acceptedImageMimeTypes?: readonly string[];
-    acceptedImageMimeTypes: readonly string[];
+    acceptedVideoMimeTypes?: readonly string[];
-    // (undocumented)
+    maxAssetSize?: number;
-    acceptedVideoMimeTypes: readonly string[];
+    maxImageDimension?: number;
-    // (undocumented)
-    maxAssetSize: number;
-    // (undocumented)
-    maxImageDimension: number;
 }
 
 // @public (undocumented)

packages/tldraw/src/index.ts

@@ -3,7 +3,7 @@
 // eslint-disable-next-line local/no-export-star
 export * from '@tldraw/editor'
 export { getAssetFromIndexedDb, storeAssetInIndexedDb } from './lib/AssetBlobStore'
-export { Tldraw, type TLComponents, type TldrawProps } from './lib/Tldraw'
+export { Tldraw, type TLComponents, type TldrawBaseProps, type TldrawProps } from './lib/Tldraw'
 export { TldrawImage, type TldrawImageProps } from './lib/TldrawImage'
 export { ArrowBindingUtil } from './lib/bindings/arrow/ArrowBindingUtil'
 export { TldrawHandles } from './lib/canvas/TldrawHandles'

packages/tldraw/src/lib/Tldraw.tsx

@@ -4,17 +4,12 @@ import {
 	DefaultSpinner,
 	Editor,
 	ErrorScreen,
-	Expand,
 	LoadingScreen,
-	MigrationSequence,
 	TLEditorComponents,
-	TLEditorSnapshot,
 	TLOnMountHandler,
-	TLStore,
-	TLStoreSnapshot,
-	TLStoreWithStatus,
 	TldrawEditor,
 	TldrawEditorBaseProps,
+	TldrawEditorStoreProps,
 	useEditor,
 	useEditorComponents,
 	useEvent,
@@ -43,35 +38,19 @@ import { usePreloadAssets } from './ui/hooks/usePreloadAssets'
 import { useTranslation } from './ui/hooks/useTranslation/useTranslation'
 import { useDefaultEditorAssetsWithOverrides } from './utils/static-assets/assetUrls'
 
-/**@public */
+/** @public */
-export type TLComponents = Expand<TLEditorComponents & TLUiComponents>
+export interface TLComponents extends TLEditorComponents, TLUiComponents {}
 
 /** @public */
-export type TldrawProps = Expand<
+export interface TldrawBaseProps
-	// combine components from base editor and ui
+	extends TldrawUiProps,
-	(Omit<TldrawUiProps, 'components'> &
+		TldrawEditorBaseProps,
-		Omit<TldrawEditorBaseProps, 'components'> & {
+		TLExternalContentProps {
-			components?: TLComponents
+	components?: TLComponents
-		}) &
+}
-		// external content
+
-		Partial<TLExternalContentProps> &
+/** @public */
-		// store stuff
+export type TldrawProps = TldrawBaseProps & TldrawEditorStoreProps
-		(| {
-					store: TLStore | TLStoreWithStatus
-			  }
-			| {
-					store?: undefined
-					migrations?: readonly MigrationSequence[]
-					persistenceKey?: string
-					sessionId?: string
-					defaultName?: string
-					/**
-					 * A snapshot to load for the store's initial data / schema.
-					 */
-					snapshot?: TLEditorSnapshot | TLStoreSnapshot
-			  }
-		)
->
 
 /** @public @react */
 export function Tldraw(props: TldrawProps) {
@@ -171,7 +150,7 @@ function InsideOfEditorAndUiContext({
 	acceptedVideoMimeTypes = DEFAULT_SUPPORT_VIDEO_TYPES,
 	onMount,
 	persistenceKey,
-}: Partial<TLExternalContentProps & { onMount: TLOnMountHandler; persistenceKey?: string }>) {
+}: TLExternalContentProps & { onMount?: TLOnMountHandler; persistenceKey?: string }) {
 	const editor = useEditor()
 	const toasts = useToasts()
 	const msg = useTranslation()

packages/tldraw/src/lib/defaultExternalContentHandlers.ts

@@ -31,14 +31,26 @@ import { cleanupText, isRightToLeftLanguage } from './utils/text/text'
 
 /** @public */
 export interface TLExternalContentProps {
-	// The maximum dimension (width or height) of an image. Images larger than this will be rescaled to fit. Defaults to infinity.
+	/**
-	maxImageDimension: number
+	 * The maximum dimension (width or height) of an image. Images larger than this will be rescaled
-	// The maximum size (in bytes) of an asset. Assets larger than this will be rejected. Defaults to 10mb (10 * 1024 * 1024).
+	 * to fit. Defaults to infinity.
-	maxAssetSize: number
+	 */
-	// The mime types of images that are allowed to be handled. Defaults to DEFAULT_SUPPORTED_IMAGE_TYPES.
+	maxImageDimension?: number
-	acceptedImageMimeTypes: readonly string[]
+	/**
-	// The mime types of videos that are allowed to be handled. Defaults to DEFAULT_SUPPORT_VIDEO_TYPES.
+	 * The maximum size (in bytes) of an asset. Assets larger than this will be rejected. Defaults
-	acceptedVideoMimeTypes: readonly string[]
+	 * to 10mb (10 * 1024 * 1024).
+	 */
+	maxAssetSize?: number
+	/**
+	 * The mime types of images that are allowed to be handled. Defaults to
+	 * DEFAULT_SUPPORTED_IMAGE_TYPES.
+	 */
+	acceptedImageMimeTypes?: readonly string[]
+	/**
+	 * The mime types of videos that are allowed to be handled. Defaults to
+	 * DEFAULT_SUPPORT_VIDEO_TYPES.
+	 */
+	acceptedVideoMimeTypes?: readonly string[]
 }
 
 export function registerDefaultExternalContentHandlers(
@@ -48,7 +60,7 @@ export function registerDefaultExternalContentHandlers(
 		maxAssetSize,
 		acceptedImageMimeTypes,
 		acceptedVideoMimeTypes,
-	}: TLExternalContentProps,
+	}: Required<TLExternalContentProps>,
 	{ toasts, msg }: { toasts: TLUiToastsContextType; msg: ReturnType<typeof useTranslation> },
 	persistenceKey?: string
 ) {