From 4ccac5da96d55e3d3fbceb37a7ee65a1901939fc Mon Sep 17 00:00:00 2001 From: alex Date: Mon, 24 Jun 2024 16:55:46 +0100 Subject: [PATCH] better auto-generated docs for Tldraw and TldrawEditor (#4012) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 | 35 ++++++---- packages/editor/src/index.ts | 4 ++ packages/editor/src/lib/TldrawEditor.tsx | 70 ++++++++++++++----- .../editor/src/lib/config/createTLStore.ts | 30 +++++--- packages/tldraw/api-report.md | 37 ++++------ packages/tldraw/src/index.ts | 2 +- packages/tldraw/src/lib/Tldraw.tsx | 47 ++++--------- .../src/lib/defaultExternalContentHandlers.ts | 30 +++++--- 8 files changed, 147 insertions(+), 108 deletions(-) diff --git a/packages/editor/api-report.md b/packages/editor/api-report.md index 5043255dd..91912d7a7 100644 --- a/packages/editor/api-report.md +++ b/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; +} // @public export interface TldrawOptions { @@ -3256,19 +3263,23 @@ export interface TLStateNodeConstructor { initial?: string; } +// @public (undocumented) +export interface TLStoreBaseOptions { + defaultName?: string; + initialData?: SerializedStore; +} + // @public (undocumented) export type TLStoreEventInfo = HistoryEntry; // @public (undocumented) -export type TLStoreOptions = { - defaultName?: string; - id?: string; - initialData?: SerializedStore; -} & ({ +export type TLStoreOptions = TLStoreBaseOptions & ({ bindingUtils?: readonly TLAnyBindingUtilConstructor[]; + id?: string; migrations?: readonly MigrationSequence[]; shapeUtils?: readonly TLAnyShapeUtilConstructor[]; } | { + id?: string; schema?: StoreSchema; }); diff --git a/packages/editor/src/index.ts b/packages/editor/src/index.ts index 49183b250..373a6f14b 100644 --- a/packages/editor/src/index.ts +++ b/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' diff --git a/packages/editor/src/lib/TldrawEditor.tsx b/packages/editor/src/lib/TldrawEditor.tsx index efbebdaaf..e64985b2c 100644 --- a/packages/editor/src/lib/TldrawEditor.tsx +++ b/packages/editor/src/lib/TldrawEditor.tsx @@ -1,6 +1,6 @@ import { MigrationSequence, Store } from '@tldraw/store' -import { TLSerializedStore, TLStore, TLStoreSnapshot } from '@tldraw/tlschema' -import { Expand, Required, annotateError } from '@tldraw/utils' +import { TLStore, TLStoreSnapshot } from '@tldraw/tlschema' +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< - TldrawEditorBaseProps & - ( - | { - store: TLStore | TLStoreWithStatus - } - | { - store?: undefined - migrations?: readonly MigrationSequence[] - snapshot?: TLEditorSnapshot | TLStoreSnapshot - initialData?: TLSerializedStore - persistenceKey?: string - sessionId?: string - defaultName?: string - } - ) -> +export type TldrawEditorProps = TldrawEditorBaseProps & TldrawEditorStoreProps /** * Base props for the {@link tldraw#Tldraw} and {@link TldrawEditor} components. diff --git a/packages/editor/src/lib/config/createTLStore.ts b/packages/editor/src/lib/config/createTLStore.ts index d7669f34e..3fe446a2b 100644 --- a/packages/editor/src/lib/config/createTLStore.ts +++ b/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 + + /** The default name for the store. */ defaultName?: string - id?: string -} & ( - | { - shapeUtils?: readonly TLAnyShapeUtilConstructor[] - migrations?: readonly MigrationSequence[] - bindingUtils?: readonly TLAnyBindingUtilConstructor[] - } - | { schema?: StoreSchema } -) +} + +/** @public */ +export type TLStoreOptions = TLStoreBaseOptions & + ( + | { + id?: string + shapeUtils?: readonly TLAnyShapeUtilConstructor[] + migrations?: readonly MigrationSequence[] + bindingUtils?: readonly TLAnyBindingUtilConstructor[] + } + | { + id?: string + schema?: StoreSchema + } + ) /** @public */ export type TLStoreEventInfo = HistoryEntry diff --git a/packages/tldraw/api-report.md b/packages/tldraw/api-report.md index 460331631..3cdbcc6d9 100644 --- a/packages/tldraw/api-report.md +++ b/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; +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 & Omit & { - components?: TLComponents; -}) & Partial & ({ - snapshot?: TLEditorSnapshot | TLStoreSnapshot; - defaultName?: string; - migrations?: readonly MigrationSequence[]; - persistenceKey?: string; - sessionId?: string; - store?: undefined; -} | { - store: TLStore | TLStoreWithStatus; -})>; +export type TldrawProps = TldrawBaseProps & TldrawEditorStoreProps; // @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[]; - // (undocumented) - acceptedVideoMimeTypes: readonly string[]; - // (undocumented) - maxAssetSize: number; - // (undocumented) - maxImageDimension: number; + acceptedImageMimeTypes?: readonly string[]; + acceptedVideoMimeTypes?: readonly string[]; + maxAssetSize?: number; + maxImageDimension?: number; } // @public (undocumented) diff --git a/packages/tldraw/src/index.ts b/packages/tldraw/src/index.ts index bdfde9bb5..5e4dd78a8 100644 --- a/packages/tldraw/src/index.ts +++ b/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' diff --git a/packages/tldraw/src/lib/Tldraw.tsx b/packages/tldraw/src/lib/Tldraw.tsx index ebe4ae7b9..07825b80a 100644 --- a/packages/tldraw/src/lib/Tldraw.tsx +++ b/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 */ -export type TLComponents = Expand +/** @public */ +export interface TLComponents extends TLEditorComponents, TLUiComponents {} /** @public */ -export type TldrawProps = Expand< - // combine components from base editor and ui - (Omit & - Omit & { - components?: TLComponents - }) & - // external content - Partial & - // store stuff - (| { - 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 - } - ) -> +export interface TldrawBaseProps + extends TldrawUiProps, + TldrawEditorBaseProps, + TLExternalContentProps { + components?: TLComponents +} + +/** @public */ +export type TldrawProps = TldrawBaseProps & TldrawEditorStoreProps /** @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 }) { const editor = useEditor() const toasts = useToasts() const msg = useTranslation() diff --git a/packages/tldraw/src/lib/defaultExternalContentHandlers.ts b/packages/tldraw/src/lib/defaultExternalContentHandlers.ts index 8e9efef54..856511e3d 100644 --- a/packages/tldraw/src/lib/defaultExternalContentHandlers.ts +++ b/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 size (in bytes) of an asset. Assets larger than this will be rejected. Defaults 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[] + /** + * 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 size (in bytes) of an asset. Assets larger than this will be rejected. Defaults + * 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, { toasts, msg }: { toasts: TLUiToastsContextType; msg: ReturnType }, persistenceKey?: string ) {