focus: rework and untangle existing focus management logic in the sdk

apps/dotcom/src/components/BoardHistorySnapshot/BoardHistorySnapshot.tsx

@@ -67,7 +67,6 @@ export function BoardHistorySnapshot({
 					}}
 					overrides={[fileSystemUiOverrides]}
 					inferDarkMode
-					autoFocus
 				/>
 			</div>
 			<div className="board-history__restore">

apps/dotcom/src/components/CursorChatBubble.tsx

@@ -9,7 +9,7 @@ import {
 	useRef,
 	useState,
 } from 'react'
-import { preventDefault, track, useContainer, useEditor, useTranslation } from 'tldraw'
+import { preventDefault, track, useEditor, useTranslation } from 'tldraw'
 
 // todo:
 // - not cleaning up
@@ -18,7 +18,6 @@ const CHAT_MESSAGE_TIMEOUT_CHATTING = 5000
 
 export const CursorChatBubble = track(function CursorChatBubble() {
 	const editor = useEditor()
-	const container = useContainer()
 	const { isChatting, chatMessage } = editor.getInstanceState()
 
 	const rTimeout = useRef<any>(-1)
@@ -31,14 +30,14 @@ export const CursorChatBubble = track(function CursorChatBubble() {
 			rTimeout.current = setTimeout(() => {
 				editor.updateInstanceState({ chatMessage: '', isChatting: false })
 				setValue('')
-				container.focus()
+				editor.focus()
 			}, duration)
 		}
 
 		return () => {
 			clearTimeout(rTimeout.current)
 		}
-	}, [container, editor, chatMessage, isChatting])
+	}, [editor, chatMessage, isChatting])
 
 	if (isChatting)
 		return <CursorChatInput value={value} setValue={setValue} chatMessage={chatMessage} />
@@ -101,7 +100,6 @@ const CursorChatInput = track(function CursorChatInput({
 }) {
 	const editor = useEditor()
 	const msg = useTranslation()
-	const container = useContainer()
 
 	const ref = useRef<HTMLInputElement>(null)
 	const placeholder = chatMessage || msg('cursor-chat.type-to-chat')
@@ -126,11 +124,9 @@ const CursorChatInput = track(function CursorChatInput({
 	}, [editor, value, placeholder])
 
 	useLayoutEffect(() => {
-		// Focus the editor
-		let raf = requestAnimationFrame(() => {
-			raf = requestAnimationFrame(() => {
-				ref.current?.focus()
-			})
+		// Focus the input
+		const raf = requestAnimationFrame(() => {
+			ref.current?.focus()
 		})
 
 		return () => {
@@ -140,8 +136,8 @@ const CursorChatInput = track(function CursorChatInput({
 
 	const stopChatting = useCallback(() => {
 		editor.updateInstanceState({ isChatting: false })
-		container.focus()
-	}, [editor, container])
+		editor.focus()
+	}, [editor])
 
 	// Update the chat message as the user types
 	const handleChange = useCallback(

apps/dotcom/src/components/LocalEditor.tsx

@@ -102,7 +102,6 @@ export function LocalEditor() {
 				assetUrls={assetUrls}
 				persistenceKey={SCRATCH_PERSISTENCE_KEY}
 				onMount={handleMount}
-				autoFocus
 				overrides={[sharingUiOverrides, fileSystemUiOverrides]}
 				onUiEvent={handleUiEvent}
 				components={components}

apps/dotcom/src/components/MultiplayerEditor.tsx

@@ -158,7 +158,6 @@ export function MultiplayerEditor({
 				initialState={isReadonly ? 'hand' : 'select'}
 				onUiEvent={handleUiEvent}
 				components={components}
-				autoFocus
 				inferDarkMode
 			>
 				<UrlStateSync />

apps/dotcom/src/components/PeopleMenu/UserPresenceEditor.tsx

@@ -52,8 +52,8 @@ export function UserPresenceEditor() {
 					onCancel={toggleEditingName}
 					onBlur={handleBlur}
 					shouldManuallyMaintainScrollPositionWhenFocused
-					autofocus
-					autoselect
+					autoFocus
+					autoSelect
 				/>
 			) : (
 				<>

apps/dotcom/src/components/SnapshotsEditor.tsx

@@ -89,7 +89,6 @@ export function SnapshotsEditor(props: SnapshotEditorProps) {
 				}}
 				components={components}
 				renderDebugMenuItems={() => <DebugMenuItems />}
-				autoFocus
 				inferDarkMode
 			>
 				<UrlStateSync />

apps/examples/src/examples/external-content-sources/ExternalContentSourcesExample.tsx

@@ -67,7 +67,7 @@ export default function ExternalContentSourcesExample() {
 
 	return (
 		<div className="tldraw__editor">
-			<Tldraw autoFocus onMount={handleMount} shapeUtils={[DangerousHtmlExample]} />
+			<Tldraw onMount={handleMount} shapeUtils={[DangerousHtmlExample]} />
 		</div>
 	)
 }

apps/examples/src/examples/scroll/ScrollExample.tsx

@@ -14,10 +14,7 @@ export default function ScrollExample() {
 			}}
 		>
 			<div style={{ width: '60vw', height: '80vh' }}>
-				<Tldraw
-					persistenceKey="scroll-example"
-					// autoFocus={false}
-				/>
+				<Tldraw persistenceKey="scroll-example" />
 			</div>
 		</div>
 	)

apps/vscode/editor/src/app.tsx

@@ -126,7 +126,6 @@ function TldrawInner({ uri, assetSrc, isDarkMode, fileContents }: TLDrawInnerPro
 			persistenceKey={uri}
 			onMount={handleMount}
 			components={components}
-			autoFocus
 		>
 			{/* <DarkModeHandler themeKind={themeKind} /> */}
 

packages/editor/api-report.md

@@ -585,7 +585,7 @@ export class Edge2d extends Geometry2d {
 
 // @public (undocumented)
 export class Editor extends EventEmitter<TLEventMap> {
-    constructor({ store, user, shapeUtils, tools, getContainer, initialState, inferDarkMode, }: TLEditorOptions);
+    constructor({ store, user, shapeUtils, tools, getContainer, initialState, autoFocus, inferDarkMode, }: TLEditorOptions);
     addOpenMenu(id: string): this;
     alignShapes(shapes: TLShape[] | TLShapeId[], operation: 'bottom' | 'center-horizontal' | 'center-vertical' | 'left' | 'right' | 'top'): this;
     animateShape(partial: null | TLShapePartial | undefined, animationOptions?: TLAnimationOptions): this;
@@ -671,6 +671,8 @@ export class Editor extends EventEmitter<TLEventMap> {
     findCommonAncestor(shapes: TLShape[] | TLShapeId[], predicate?: (shape: TLShape) => boolean): TLShapeId | undefined;
     findShapeAncestor(shape: TLShape | TLShapeId, predicate: (parent: TLShape) => boolean): TLShape | undefined;
     flipShapes(shapes: TLShape[] | TLShapeId[], operation: 'horizontal' | 'vertical'): this;
+    focus(): this;
+    readonly focusManager: FocusManager;
     getAncestorPageId(shape?: TLShape | TLShapeId): TLPageId | undefined;
     getArrowInfo(shape: TLArrowShape | TLShapeId): TLArrowInfo | undefined;
     getArrowsBoundTo(shapeId: TLShapeId): {
@@ -1027,6 +1029,19 @@ export function extractSessionStateFromLegacySnapshot(store: Record<string, Unkn
 // @internal (undocumented)
 export const featureFlags: Record<string, DebugFlag<boolean>>;
 
+// @public
+export class FocusManager {
+    constructor(editor: Editor, autoFocus?: boolean);
+    // (undocumented)
+    blur(): void;
+    // (undocumented)
+    dispose(): void;
+    // (undocumented)
+    editor: Editor;
+    // (undocumented)
+    focus(): void;
+}
+
 // @public (undocumented)
 export type GapsSnapIndicator = {
     direction: 'horizontal' | 'vertical';
@@ -2171,6 +2186,7 @@ export type TLEditorComponents = Partial<{
 
 // @public (undocumented)
 export interface TLEditorOptions {
+    autoFocus?: boolean;
     getContainer: () => HTMLElement;
     inferDarkMode?: boolean;
     initialState?: string;

packages/editor/src/index.ts

@@ -130,6 +130,7 @@ export {
 	type TLEditorOptions,
 	type TLResizeShapeOptions,
 } from './lib/editor/Editor'
+export type { FocusManager } from './lib/editor/managers/FocusManager'
 export { HistoryManager } from './lib/editor/managers/HistoryManager'
 export type {
 	SideEffectManager,

packages/editor/src/lib/TldrawEditor.tsx

@@ -28,10 +28,8 @@ import {
 	useEditorComponents,
 } from './hooks/useEditorComponents'
 import { useEvent } from './hooks/useEvent'
-import { useFocusEvents } from './hooks/useFocusEvents'
 import { useForceUpdate } from './hooks/useForceUpdate'
 import { useLocalStore } from './hooks/useLocalStore'
-import { useSafariFocusOutFix } from './hooks/useSafariFocusOutFix'
 import { useZoomCss } from './hooks/useZoomCss'
 import { stopEventPropagation } from './utils/dom'
 import { TLStoreWithStatus } from './utils/sync/StoreWithStatus'
@@ -285,14 +283,15 @@ function TldrawEditorWithReadyStore({
 			getContainer: () => container,
 			user,
 			initialState,
+			autoFocus,
 			inferDarkMode,
 		})
 		setEditor(editor)
 
 		return () => {
 			editor.dispose()
 		}
-	}, [container, shapeUtils, tools, store, user, initialState, inferDarkMode])
+	}, [container, shapeUtils, tools, store, user, initialState, autoFocus, inferDarkMode])
 
 	const crashingError = useSyncExternalStore(
 		useCallback(
@@ -333,30 +332,18 @@ function TldrawEditorWithReadyStore({
 				<Crash crashingError={crashingError} />
 			) : (
 				<EditorContext.Provider value={editor}>
-					<Layout autoFocus={autoFocus} onMount={onMount}>
-						{children ?? (Canvas ? <Canvas /> : null)}
-					</Layout>
+					<Layout onMount={onMount}>{children ?? (Canvas ? <Canvas /> : null)}</Layout>
 				</EditorContext.Provider>
 			)}
 		</OptionalErrorBoundary>
 	)
 }
 
-function Layout({
-	children,
-	onMount,
-	autoFocus,
-}: {
-	children: ReactNode
-	autoFocus: boolean
-	onMount?: TLOnMountHandler
-}) {
+function Layout({ children, onMount }: { children: ReactNode; onMount?: TLOnMountHandler }) {
 	useZoomCss()
 	useCursor()
 	useDarkMode()
-	useSafariFocusOutFix()
 	useForceUpdate()
-	useFocusEvents(autoFocus)
 	useOnMount(onMount)
 
 	return <>{children}</>

packages/editor/src/lib/editor/Editor.ts

@@ -105,6 +105,7 @@ import { deriveShapeIdsInCurrentPage } from './derivations/shapeIdsInCurrentPage
 import { getSvgJsx } from './getSvgJsx'
 import { ClickManager } from './managers/ClickManager'
 import { EnvironmentManager } from './managers/EnvironmentManager'
+import { FocusManager } from './managers/FocusManager'
 import { HistoryManager } from './managers/HistoryManager'
 import { ScribbleManager } from './managers/ScribbleManager'
 import { SideEffectManager } from './managers/SideEffectManager'
@@ -178,6 +179,10 @@ export interface TLEditorOptions {
 	 * The editor's initial active tool (or other state node id).
 	 */
 	initialState?: string
+	/**
+	 * Whether to automatically focus the editor when it mounts.
+	 */
+	autoFocus?: boolean
 	/**
 	 * Whether to infer dark mode from the user's system preferences. Defaults to false.
 	 */
@@ -193,6 +198,7 @@ export class Editor extends EventEmitter<TLEventMap> {
 		tools,
 		getContainer,
 		initialState,
+		autoFocus,
 		inferDarkMode,
 	}: TLEditorOptions) {
 		super()
@@ -656,6 +662,9 @@ export class Editor extends EventEmitter<TLEventMap> {
 
 		this.root.enter(undefined, 'initial')
 
+		this.focusManager = new FocusManager(this, autoFocus)
+		this.disposables.add(this.focusManager.dispose)
+
 		if (this.getInstanceState().followingUserId) {
 			this.stopFollowingUser()
 		}
@@ -747,6 +756,13 @@ export class Editor extends EventEmitter<TLEventMap> {
 	 */
 	readonly sideEffects: SideEffectManager<this>
 
+	/**
+	 * A manager for ensuring correct focus. See {@link FocusManager} for details.
+	 *
+	 * @public
+	 */
+	readonly focusManager: FocusManager
+
 	/**
 	 * Dispose the editor.
 	 *
@@ -7947,6 +7963,21 @@ export class Editor extends EventEmitter<TLEventMap> {
 		return this
 	}
 
+	/**
+	 * Dispatch a focus event.
+	 *
+	 * @example
+	 * ```ts
+	 * editor.focus()
+	 * ```
+	 *
+	 * @public
+	 */
+	focus(): this {
+		this.focusManager.focus()
+		return this
+	}
+
 	/**
 	 * A manager for recording multiple click events.
 	 *

packages/editor/src/lib/editor/managers/EnvironmentManager.ts

@@ -4,7 +4,7 @@ export class EnvironmentManager {
 	constructor(public editor: Editor) {
 		if (typeof window !== 'undefined' && 'navigator' in window) {
 			this.isSafari = /^((?!chrome|android).)*safari/i.test(navigator.userAgent)
-			this.isIos = !!navigator.userAgent.match(/iPad/i) || !!navigator.userAgent.match(/iPhone/i)
+			this.isIos = true //!!navigator.userAgent.match(/iPad/i) || !!navigator.userAgent.match(/iPhone/i)
 			this.isChromeForIos = /crios.*safari/i.test(navigator.userAgent)
 			this.isFirefox = /firefox/i.test(navigator.userAgent)
 			this.isAndroid = /android/i.test(navigator.userAgent)

packages/editor/src/lib/editor/managers/FocusManager.ts

@@ -0,0 +1,50 @@
+import type { Editor } from '../Editor'
+
+/**
+ * A manager for ensuring correct focus across the editor.
+ * It will listen for changes in the instance state to make sure the
+ * container is focused when the editor is focused.
+ * Also, it will make sure that the focus is on things like text
+ * labels when the editor is in editing mode.
+ *
+ * @public
+ */
+export class FocusManager {
+	private disposeStoreListener?: () => void
+
+	constructor(
+		public editor: Editor,
+		autoFocus?: boolean
+	) {
+		this.disposeStoreListener = editor.store.listen(
+			({ changes }) => {
+				for (const [prev, next] of Object.values(changes.updated)) {
+					if (prev.typeName !== 'instance' || next.typeName !== 'instance') continue
+
+					if (prev.isFocused !== next.isFocused) {
+						next.isFocused ? this.focus() : this.blur()
+					}
+				}
+			},
+			{ scope: 'session' }
+		)
+
+		const currentFocusState = editor.getInstanceState().isFocused
+		if (autoFocus !== currentFocusState) {
+			editor.updateInstanceState({ isFocused: autoFocus })
+		}
+	}
+
+	focus() {
+		this.editor.getContainer().focus()
+	}
+
+	blur() {
+		this.editor.complete() // stop any interaction
+		this.editor.getContainer().blur() // blur the container
+	}
+
+	dispose() {
+		this.disposeStoreListener?.()
+	}
+}