Make some missing tsdocs appear on the docs site (#1706)

🚨 Note 🚨
This PR has changed! See my [newer
comment](https://github.com/tldraw/tldraw/pull/1706#issuecomment-1623451709)
for what the PR does now.
This description is kept here to show the original intention of the PR.

---

This PR fixes the tsdocs formatting of `TldrawEditorProps`, so that they
appears on the docs site.

We have docs already written, but they weren't appearing. There are
probably others like this too.


![image](https://github.com/tldraw/tldraw/assets/15892272/8d8940b3-983f-48b3-9804-7ac88116ca9d)

### Change Type

- [x] `documentation` — Changes to the documentation only[^2]

[^1]: publishes a `patch` release, for devDependencies use `internal`
[^2]: will not publish a new version

### Test Plan

1. Navigate to `/gen/editor/TldrawEditorProps`
2. Make sure that that the parameters are listed out with descriptions.

- [ ] Unit Tests
- [ ] End to end tests

### Release Notes

- Docs: Fixed some missing docs for the TldrawEditor component.

packages/editor/api-report.md

@@ -2293,16 +2293,19 @@ export type TLCopyType = 'jpeg' | 'json' | 'png' | 'svg';
 // @public (undocumented)
 export const TldrawEditor: React_2.NamedExoticComponent<TldrawEditorProps>;
 
-// @public (undocumented)
-export type TldrawEditorProps = {
-    children?: any;
-    shapes?: readonly AnyTLShapeInfo[];
-    tools?: readonly TLStateNodeConstructor[];
+// @public
+export interface TldrawEditorBaseProps {
     assetUrls?: RecursivePartial<TLEditorAssetUrls>;
     autoFocus?: boolean;
+    children?: any;
     components?: Partial<TLEditorComponents>;
-    onMount?: (editor: Editor) => (() => void) | undefined | void;
-} & ({
+    onMount?: TLOnMountHandler;
+    shapes?: readonly AnyTLShapeInfo[];
+    tools?: readonly TLStateNodeConstructor[];
+}
+
+// @public
+export type TldrawEditorProps = TldrawEditorBaseProps & ({
     store: TLStore | TLStoreWithStatus;
 } | {
     store?: undefined;
@@ -2579,6 +2582,9 @@ export type TLOnHandleChangeHandler<T extends TLShape> = (shape: T, info: {
     isPrecise: boolean;
 }) => TLShapePartial<T> | void;
 
+// @public
+export type TLOnMountHandler = (editor: Editor) => (() => void) | undefined | void;
+
 // @public (undocumented)
 export type TLOnResizeEndHandler<T extends TLShape> = TLEventChangeHandler<T>;
 

packages/editor/src/index.ts

@@ -22,6 +22,8 @@ export {
 	ErrorScreen,
 	LoadingScreen,
 	TldrawEditor,
+	type TLOnMountHandler,
+	type TldrawEditorBaseProps,
 	type TldrawEditorProps,
 } from './lib/TldrawEditor'
 export {

packages/editor/src/lib/TldrawEditor.tsx

@@ -9,6 +9,7 @@ import React, {
 	useState,
 	useSyncExternalStore,
 } from 'react'
+
 import { TLEditorAssetUrls, useDefaultEditorAssetsWithOverrides } from './assetUrls'
 import { DefaultErrorFallback } from './components/DefaultErrorFallback'
 import { OptionalErrorBoundary } from './components/ErrorBoundary'
@@ -33,65 +34,78 @@ import { useSafariFocusOutFix } from './hooks/useSafariFocusOutFix'
 import { useZoomCss } from './hooks/useZoomCss'
 import { TLStoreWithStatus } from './utils/sync/StoreWithStatus'
 
-/** @public */
-export type TldrawEditorProps = {
+/**
+ * Props for the {@link @tldraw/tldraw#Tldraw} and {@link TldrawEditor} components.
+ *
+ * @public
+ **/
+export type TldrawEditorProps = TldrawEditorBaseProps &
+	(
+		| {
+				store: TLStore | TLStoreWithStatus
+		  }
+		| {
+				store?: undefined
+				initialData?: SerializedStore<TLRecord>
+				persistenceKey?: string
+				sessionId?: string
+				defaultName?: string
+		  }
+	)
+
+/**
+ * Base props for the {@link @tldraw/tldraw#Tldraw} and {@link TldrawEditor} components.
+ *
+ * @public
+ */
+export interface TldrawEditorBaseProps {
+	/**
+	 * The component's children.
+	 */
 	children?: any
-	/** An array of shape utils to use in the editor. */
+
+	/**
+	 * An array of shapes definitions to make available to the editor.
+	 */
 	shapes?: readonly AnyTLShapeInfo[]
-	/** An array of tools to use in the editor. */
+
+	/**
+	 * An array of tools to add to the editor's state chart.
+	 */
 	tools?: readonly TLStateNodeConstructor[]
-	/** Urls for where to find fonts and other assets. */
+
+	/**
+	 * Urls for the editor to find fonts and other assets.
+	 */
 	assetUrls?: RecursivePartial<TLEditorAssetUrls>
-	/** Whether to automatically focus the editor when it mounts. */
+
+	/**
+	 * Whether to automatically focus the editor when it mounts.
+	 */
 	autoFocus?: boolean
-	/** Overrides for the tldraw user interface components. */
+
+	/**
+	 * Overrides for the editor's components, such as handles, collaborator cursors, etc.
+	 */
 	components?: Partial<TLEditorComponents>
+
 	/**
 	 * Called when the editor has mounted.
-	 * @example
-	 * ```ts
-	 * function TldrawEditor() {
-	 * 	return <Editor onMount={(editor) => editor.selectAll()} />
-	 * }
-	 * ```
-	 * @param editor - The editor instance.
 	 */
-	onMount?: (editor: Editor) => (() => void) | undefined | void
-} & (
-	| {
-			/**
-			 * The Store instance to use for keeping the editor's data. This may be prepopulated, e.g. by loading
-			 * from a server or database.
-			 */
-			store: TLStore | TLStoreWithStatus
-	  }
-	| {
-			store?: undefined
-			/**
-			 * The editor's initial data.
-			 */
-			initialData?: SerializedStore<TLRecord>
-			/**
-			 * The id under which to sync and persist the editor's data. If none is given tldraw will not sync or persist
-			 * the editor's data.
-			 */
-			persistenceKey?: string
-			/**
-			 * When tldraw reloads a document from local persistence, it will try to bring back the
-			 * editor UI state (e.g. camera position, which shapes are selected). It does this using a sessionId,
-			 * which by default is unique per browser tab. If you wish to have more fine-grained
-			 * control over this behavior, you can provide your own sessionId.
-			 *
-			 * If it can't find saved UI state for the given sessionId, it will use the most recently saved
-			 * UI state for the given persistenceKey if available.
-			 */
-			sessionId?: string
-			/**
-			 * The default initial document name. e.g. 'Untitled Document'
-			 */
-			defaultName?: string
-	  }
-)
+	onMount?: TLOnMountHandler
+}
+
+/**
+ * Called when the editor has mounted.
+ * @example
+ * ```ts
+ * <Tldraw onMount={(editor) => editor.selectAll()} />
+ * ```
+ * @param editor - The editor instance.
+ *
+ * @public
+ */
+export type TLOnMountHandler = (editor: Editor) => (() => void) | undefined | void
 
 declare global {
 	interface Window {

packages/ui/api-report.md

@@ -211,37 +211,30 @@ function Title({ className, children }: {
 }): JSX.Element;
 
 // @public (undocumented)
-export const TldrawUi: React_2.NamedExoticComponent<{
+export const TldrawUi: React_2.NamedExoticComponent<TldrawUiBaseProps & TldrawUiContextProviderProps>;
+
+// @public
+export interface TldrawUiBaseProps {
     children?: ReactNode;
-    hideUi?: boolean | undefined;
+    hideUi?: boolean;
+    renderDebugMenuItems?: () => React_2.ReactNode;
     shareZone?: ReactNode;
     topZone?: ReactNode;
-    renderDebugMenuItems?: (() => React_2.ReactNode) | undefined;
-} & TldrawUiContextProviderProps>;
+}
 
 // @public (undocumented)
 export function TldrawUiContextProvider({ overrides, assetUrls, onUiEvent, children, }: TldrawUiContextProviderProps): JSX.Element;
 
 // @public
 export interface TldrawUiContextProviderProps {
-    // (undocumented)
     assetUrls?: RecursivePartial<TLUiAssetUrls>;
-    // (undocumented)
     children?: any;
-    // (undocumented)
     onUiEvent?: TLUiEventHandler;
-    // (undocumented)
     overrides?: TLUiOverrides | TLUiOverrides[];
 }
 
 // @public
-export type TldrawUiProps = {
-    children?: ReactNode;
-    hideUi?: boolean;
-    shareZone?: ReactNode;
-    topZone?: ReactNode;
-    renderDebugMenuItems?: () => React_2.ReactNode;
-} & TldrawUiContextProviderProps;
+export type TldrawUiProps = TldrawUiBaseProps & TldrawUiContextProviderProps;
 
 // @public (undocumented)
 export interface TLUiActionItem {

packages/ui/src/index.ts

@@ -1,7 +1,7 @@
 import * as Dialog from './lib/components/primitives/Dialog'
 import * as DropdownMenu from './lib/components/primitives/DropdownMenu'
 
-export { TldrawUi, type TldrawUiProps } from './lib/TldrawUi'
+export { TldrawUi, type TldrawUiBaseProps, type TldrawUiProps } from './lib/TldrawUi'
 export {
 	TldrawUiContextProvider,
 	type TldrawUiContextProviderProps,

packages/ui/src/lib/TldrawUi.tsx

@@ -25,23 +25,43 @@ import { useKeyboardShortcuts } from './hooks/useKeyboardShortcuts'
 import { useTranslation } from './hooks/useTranslation/useTranslation'
 
 /**
- * Attributes for the {@link @tldraw/tldraw#Tldraw} and {@link TldrawUi} components.
- *
- * @param children - The component's children.
- * @param hideUi - Whether to hide the interface and only display the canvas.
- * @param shareZone - A component to use for the share zone (will be deprecated)
- * @param topZone - A component to use for the top zone (will be deprecated)
- * @param renderDebugMenuItems - Additional items to add to the debug menu (will be deprecated)
+ * Props for the {@link @tldraw/tldraw#Tldraw} and {@link TldrawUi} components.
  *
  * @public
  */
-export type TldrawUiProps = {
+export type TldrawUiProps = TldrawUiBaseProps & TldrawUiContextProviderProps
+
+/**
+ * Base props for the {@link @tldraw/tldraw#Tldraw} and {@link TldrawUi} components.
+ *
+ * @public
+ */
+export interface TldrawUiBaseProps {
+	/**
+	 * The component's children.
+	 */
 	children?: ReactNode
+
+	/**
+	 * Whether to hide the user interface and only display the canvas.
+	 */
 	hideUi?: boolean
+
+	/**
+	 * A component to use for the share zone (will be deprecated)
+	 */
 	shareZone?: ReactNode
+
+	/**
+	 * A component to use for the top zone (will be deprecated)
+	 */
 	topZone?: ReactNode
+
+	/**
+	 * Additional items to add to the debug menu (will be deprecated)
+	 */
 	renderDebugMenuItems?: () => React.ReactNode
-} & TldrawUiContextProviderProps
+}
 
 /**
  * @public

packages/ui/src/lib/TldrawUiContextProvider.tsx

@@ -17,19 +17,29 @@ import { TranslationProvider } from './hooks/useTranslation/useTranslation'
 import { TLUiOverrides, useMergedOverrides, useMergedTranslationOverrides } from './overrides'
 
 /**
- * Attributes for the {@link @tldraw/tldraw#Tldraw} and {@link TldrawUi} components.
- *
- * @param assetUrls - Urls for where to find fonts and other assets for the UI.
- * @param overrides - Overrides for the UI.
- * @param onUiEvent - Callback for when UI events occur.
- * @param children - The component's children.
+ * Props for the {@link @tldraw/tldraw#Tldraw} and {@link TldrawUi} components.
  *
  * @public
  **/
 export interface TldrawUiContextProviderProps {
+	/**
+	 * Urls for where to find fonts and other assets for the UI.
+	 */
 	assetUrls?: RecursivePartial<TLUiAssetUrls>
+
+	/**
+	 * Overrides for the UI.
+	 */
 	overrides?: TLUiOverrides | TLUiOverrides[]
+
+	/**
+	 * Callback for when an event occurs in the UI.
+	 */
 	onUiEvent?: TLUiEventHandler
+
+	/**
+	 * The component's children.
+	 */
 	children?: any
 }