tldraw 3.16.0-next.c30b1b5e551a → 3.16.0-next.eafb52d15064

package/src/lib/ui/components/primitives/TldrawUiTooltip.tsx

@@ -0,0 +1,313 @@
+import { Editor, uniqueId, useMaybeEditor, Vec } from '@tldraw/editor'
+import { Tooltip as _Tooltip } from 'radix-ui'
+import React, { createContext, useContext, useEffect, useRef, useState } from 'react'
+import { usePrefersReducedMotion } from '../../../shapes/shared/usePrefersReducedMotion'
+
+const DEFAULT_TOOLTIP_DELAY_MS = 700
+
+/** @public */
+export interface TldrawUiTooltipProps {
+	children: React.ReactNode
+	content?: string | React.ReactNode
+	side?: 'top' | 'right' | 'bottom' | 'left'
+	sideOffset?: number
+	disabled?: boolean
+}
+
+// Singleton tooltip manager
+class TooltipManager {
+	private static instance: TooltipManager | null = null
+	private currentTooltipId: string | null = null
+	private currentContent: string | React.ReactNode = ''
+	private currentSide: 'top' | 'right' | 'bottom' | 'left' = 'bottom'
+	private currentSideOffset: number = 5
+	private destroyTimeoutId: number | null = null
+	private subscribers: Set<() => void> = new Set()
+	private activeElement: HTMLElement | null = null
+	private editor: Editor | null = null
+
+	static getInstance(): TooltipManager {
+		if (!TooltipManager.instance) {
+			TooltipManager.instance = new TooltipManager()
+		}
+		return TooltipManager.instance
+	}
+
+	setEditor(editor: Editor | null) {
+		this.editor = editor
+	}
+
+	subscribe(callback: () => void): () => void {
+		this.subscribers.add(callback)
+		return () => this.subscribers.delete(callback)
+	}
+
+	private notify() {
+		this.subscribers.forEach((callback) => callback())
+	}
+
+	showTooltip(
+		tooltipId: string,
+		content: string | React.ReactNode,
+		element: HTMLElement,
+		side: 'top' | 'right' | 'bottom' | 'left' = 'bottom',
+		sideOffset: number = 5
+	) {
+		// Clear any existing destroy timeout
+		if (this.destroyTimeoutId) {
+			clearTimeout(this.destroyTimeoutId)
+			this.destroyTimeoutId = null
+		}
+
+		// Update current tooltip
+		this.currentTooltipId = tooltipId
+		this.currentContent = content
+		this.currentSide = side
+		this.currentSideOffset = sideOffset
+		this.activeElement = element
+
+		this.notify()
+	}
+
+	hideTooltip(tooltipId: string) {
+		// Only hide if this is the current tooltip
+		if (this.currentTooltipId === tooltipId) {
+			// Start destroy timeout (1 second)
+			if (this.editor) {
+				this.destroyTimeoutId = this.editor.timers.setTimeout(() => {
+					this.currentTooltipId = null
+					this.currentContent = ''
+					this.activeElement = null
+					this.destroyTimeoutId = null
+					this.notify()
+				}, 300)
+			}
+		}
+	}
+
+	getCurrentTooltipData() {
+		return {
+			id: this.currentTooltipId,
+			content: this.currentContent,
+			side: this.currentSide,
+			sideOffset: this.currentSideOffset,
+			element: this.activeElement,
+		}
+	}
+}
+
+const tooltipManager = TooltipManager.getInstance()
+
+// Context for the tooltip singleton
+const TooltipSingletonContext = createContext<boolean>(false)
+
+/** @public */
+export interface TldrawUiTooltipProviderProps {
+	children: React.ReactNode
+}
+
+/** @public @react */
+export function TldrawUiTooltipProvider({ children }: TldrawUiTooltipProviderProps) {
+	return (
+		<_Tooltip.Provider skipDelayDuration={700}>
+			<TooltipSingletonContext.Provider value={true}>
+				{children}
+				<TooltipSingleton />
+			</TooltipSingletonContext.Provider>
+		</_Tooltip.Provider>
+	)
+}
+
+// The singleton tooltip component that renders once
+function TooltipSingleton() {
+	const editor = useMaybeEditor()
+	const [, forceUpdate] = useState({})
+	const [isOpen, setIsOpen] = useState(false)
+	const triggerRef = useRef<HTMLDivElement>(null)
+	const previousPositionRef = useRef<{ x: number; y: number } | null>(null)
+	const prefersReducedMotion = usePrefersReducedMotion()
+	const [shouldAnimate, setShouldAnimate] = useState(false)
+	const isFirstShowRef = useRef(true)
+	const showTimeoutRef = useRef<number | null>(null)
+
+	// Set editor in tooltip manager
+	useEffect(() => {
+		tooltipManager.setEditor(editor)
+	}, [editor])
+
+	// Subscribe to tooltip manager updates
+	useEffect(() => {
+		const unsubscribe = tooltipManager.subscribe(() => {
+			forceUpdate({})
+		})
+		return unsubscribe
+	}, [])
+
+	const tooltipData = tooltipManager.getCurrentTooltipData()
+
+	// Update open state and trigger position
+	useEffect(() => {
+		const shouldBeOpen = Boolean(tooltipData.id && tooltipData.element)
+
+		// Clear any existing show timeout
+		if (showTimeoutRef.current) {
+			clearTimeout(showTimeoutRef.current)
+			showTimeoutRef.current = null
+		}
+
+		if (shouldBeOpen && tooltipData.element && triggerRef.current) {
+			// Position the invisible trigger element over the active element
+			const activeRect = tooltipData.element.getBoundingClientRect()
+			const trigger = triggerRef.current
+
+			const newPosition = {
+				x: activeRect.left + activeRect.width / 2,
+				y: activeRect.top + activeRect.height / 2,
+			}
+
+			// Determine if we should animate
+			let shouldAnimateCheck = false
+			if (previousPositionRef.current) {
+				const isNearPrevious = Vec.DistMin(previousPositionRef.current, newPosition, 200)
+				// Only animate if the distance is less than 200px (nearby tooltips)
+				shouldAnimateCheck =
+					!prefersReducedMotion &&
+					isNearPrevious &&
+					Math.abs(newPosition.y - previousPositionRef.current.y) < 50
+			}
+			// Don't animate on initial show (previousPositionRef.current is null)
+
+			setShouldAnimate(isFirstShowRef.current ? false : shouldAnimateCheck)
+			previousPositionRef.current = newPosition
+
+			trigger.style.position = 'fixed'
+			trigger.style.left = `${activeRect.left}px`
+			trigger.style.top = `${activeRect.top}px`
+			trigger.style.width = `${activeRect.width}px`
+			trigger.style.height = `${activeRect.height}px`
+			trigger.style.pointerEvents = 'none'
+			trigger.style.zIndex = '9999'
+
+			// Handle delay for first show
+			if (isFirstShowRef.current && editor) {
+				showTimeoutRef.current = editor.timers.setTimeout(() => {
+					setIsOpen(true)
+					isFirstShowRef.current = false
+				}, editor.options.tooltipDelayMs)
+			} else {
+				// Subsequent tooltips show immediately
+				setIsOpen(true)
+			}
+		} else if (!shouldBeOpen) {
+			// Hide tooltip immediately
+			setIsOpen(false)
+			// Reset position tracking when tooltip closes
+			previousPositionRef.current = null
+			setShouldAnimate(false)
+			// Reset first show state after tooltip is hidden
+			isFirstShowRef.current = true
+		}
+	}, [tooltipData.id, tooltipData.element, editor, prefersReducedMotion])
+
+	if (!tooltipData.id) {
+		return null
+	}
+
+	return (
+		<_Tooltip.Root open={isOpen} delayDuration={0}>
+			<_Tooltip.Trigger asChild>
+				<div ref={triggerRef} />
+			</_Tooltip.Trigger>
+			<_Tooltip.Content
+				className="tlui-tooltip"
+				data-should-animate={shouldAnimate}
+				side={tooltipData.side}
+				sideOffset={tooltipData.sideOffset}
+				avoidCollisions
+				collisionPadding={8}
+				dir="ltr"
+			>
+				{tooltipData.content}
+				<_Tooltip.Arrow className="tlui-tooltip__arrow" />
+			</_Tooltip.Content>
+		</_Tooltip.Root>
+	)
+}
+
+/** @public @react */
+export function TldrawUiTooltip({
+	children,
+	content,
+	side = 'bottom',
+	sideOffset = 5,
+	disabled = false,
+}: TldrawUiTooltipProps) {
+	const editor = useMaybeEditor()
+	const tooltipId = useRef<string>(uniqueId())
+	const hasProvider = useContext(TooltipSingletonContext)
+
+	// Don't show tooltip if disabled, no content, or UI labels are disabled
+	if (disabled || !content) {
+		return <>{children}</>
+	}
+
+	// Fallback to old behavior if no provider
+	if (!hasProvider) {
+		return (
+			<_Tooltip.Root
+				delayDuration={editor?.options.tooltipDelayMs || DEFAULT_TOOLTIP_DELAY_MS}
+				disableHoverableContent
+			>
+				<_Tooltip.Trigger asChild>{children}</_Tooltip.Trigger>
+				<_Tooltip.Content
+					className="tlui-tooltip"
+					side={side}
+					sideOffset={sideOffset}
+					avoidCollisions
+					collisionPadding={8}
+					dir="ltr"
+				>
+					{content}
+					<_Tooltip.Arrow className="tlui-tooltip__arrow" />
+				</_Tooltip.Content>
+			</_Tooltip.Root>
+		)
+	}
+
+	const handleMouseEnter = (event: React.MouseEvent<HTMLElement>) => {
+		tooltipManager.showTooltip(
+			tooltipId.current,
+			content,
+			event.currentTarget as HTMLElement,
+			side,
+			sideOffset
+		)
+	}
+
+	const handleMouseLeave = () => {
+		tooltipManager.hideTooltip(tooltipId.current)
+	}
+
+	const handleFocus = (event: React.FocusEvent<HTMLElement>) => {
+		tooltipManager.showTooltip(
+			tooltipId.current,
+			content,
+			event.currentTarget as HTMLElement,
+			side,
+			sideOffset
+		)
+	}
+
+	const handleBlur = () => {
+		tooltipManager.hideTooltip(tooltipId.current)
+	}
+
+	const childrenWithHandlers = React.cloneElement(children as React.ReactElement, {
+		onMouseEnter: handleMouseEnter,
+		onMouseLeave: handleMouseLeave,
+		onFocus: handleFocus,
+		onBlur: handleBlur,
+	})
+
+	return childrenWithHandlers
+}

package/src/lib/ui/context/TldrawUiContextProvider.tsx

@@ -1,6 +1,7 @@
 import { RecursivePartial, defaultUserPreferences, track, useMaybeEditor } from '@tldraw/editor'
 import { ReactNode } from 'react'
 import { TLUiAssetUrls, useDefaultUiAssetUrlsWithOverrides } from '../assetUrls'
+import { TldrawUiTooltipProvider } from '../components/primitives/TldrawUiTooltip'
 import { ToolsProvider } from '../hooks/useTools'
 import { TldrawUiTranslationProvider } from '../hooks/useTranslation/useTranslation'
 import {
@@ -72,26 +73,28 @@ export const TldrawUiContextProvider = track(function TldrawUiContextProvider({
 	const editor = useMaybeEditor()
 	return (
 		<MimeTypeContext.Provider value={mediaMimeTypes}>
-			<AssetUrlsProvider assetUrls={useDefaultUiAssetUrlsWithOverrides(assetUrls)}>
-				<TldrawUiTranslationProvider
-					overrides={useMergedTranslationOverrides(overrides)}
-					locale={editor?.user.getLocale() ?? defaultUserPreferences.locale}
-				>
-					<TldrawUiEventsProvider onEvent={onUiEvent}>
-						<TldrawUiToastsProvider>
-							<TldrawUiDialogsProvider context={'tla'}>
-								<TldrawUiA11yProvider>
-									<BreakPointProvider forceMobile={forceMobile}>
-										<TldrawUiComponentsProvider overrides={components}>
-											<InternalProviders overrides={overrides}>{children}</InternalProviders>
-										</TldrawUiComponentsProvider>
-									</BreakPointProvider>
-								</TldrawUiA11yProvider>
-							</TldrawUiDialogsProvider>
-						</TldrawUiToastsProvider>
-					</TldrawUiEventsProvider>
-				</TldrawUiTranslationProvider>
-			</AssetUrlsProvider>
+			<TldrawUiTooltipProvider>
+				<AssetUrlsProvider assetUrls={useDefaultUiAssetUrlsWithOverrides(assetUrls)}>
+					<TldrawUiTranslationProvider
+						overrides={useMergedTranslationOverrides(overrides)}
+						locale={editor?.user.getLocale() ?? defaultUserPreferences.locale}
+					>
+						<TldrawUiEventsProvider onEvent={onUiEvent}>
+							<TldrawUiToastsProvider>
+								<TldrawUiDialogsProvider context={'tla'}>
+									<TldrawUiA11yProvider>
+										<BreakPointProvider forceMobile={forceMobile}>
+											<TldrawUiComponentsProvider overrides={components}>
+												<InternalProviders overrides={overrides}>{children}</InternalProviders>
+											</TldrawUiComponentsProvider>
+										</BreakPointProvider>
+									</TldrawUiA11yProvider>
+								</TldrawUiDialogsProvider>
+							</TldrawUiToastsProvider>
+						</TldrawUiEventsProvider>
+					</TldrawUiTranslationProvider>
+				</AssetUrlsProvider>
+			</TldrawUiTooltipProvider>
 		</MimeTypeContext.Provider>
 	)
 })

package/src/lib/ui/context/actions.tsx

@@ -1266,6 +1266,21 @@ export function ActionsProvider({ overrides, children }: ActionsProviderProps) {
 				},
 				checkbox: true,
 			},
+			{
+				id: 'toggle-ui-labels',
+				label: {
+					default: 'action.toggle-ui-labels',
+					menu: 'action.toggle-ui-labels.menu',
+				},
+				readonlyOk: true,
+				onSelect(source) {
+					trackEvent('toggle-ui-labels', { source })
+					editor.user.updateUserPreferences({
+						showUiLabels: !editor.user.getShowUiLabels(),
+					})
+				},
+				checkbox: true,
+			},
 			{
 				id: 'toggle-edge-scrolling',
 				label: {

package/src/lib/ui/context/events.tsx

@@ -108,6 +108,7 @@ export interface TLUiEventMap {
 	'toggle-lock': null
 	'toggle-reduce-motion': null
 	'toggle-keyboard-shortcuts': null
+	'toggle-ui-labels': null
 	'toggle-edge-scrolling': null
 	'color-scheme': { value: string }
 	'exit-pen-mode': null

package/src/lib/ui/hooks/useTranslation/TLUiTranslationKey.ts

@@ -93,6 +93,8 @@ export type TLUiTranslationKey =
 	| 'action.toggle-reduce-motion'
 	| 'action.toggle-keyboard-shortcuts.menu'
 	| 'action.toggle-keyboard-shortcuts'
+	| 'action.toggle-ui-labels.menu'
+	| 'action.toggle-ui-labels'
 	| 'action.toggle-edge-scrolling.menu'
 	| 'action.toggle-edge-scrolling'
 	| 'action.toggle-debug-mode.menu'
@@ -298,6 +300,7 @@ export type TLUiTranslationKey =
 	| 'a11y.open-keyboard-shortcuts'
 	| 'menu.title'
 	| 'menu.theme'
+	| 'menu.accessibility'
 	| 'menu.copy-as'
 	| 'menu.edit'
 	| 'menu.export-as'

package/src/lib/ui/hooks/useTranslation/defaultTranslation.ts

@@ -94,6 +94,8 @@ export const DEFAULT_TRANSLATION = {
 	'action.toggle-reduce-motion': 'Toggle reduce motion',
 	'action.toggle-keyboard-shortcuts.menu': 'Keyboard shortcuts',
 	'action.toggle-keyboard-shortcuts': 'Toggle keyboard shortcuts',
+	'action.toggle-ui-labels.menu': 'UI labels',
+	'action.toggle-ui-labels': 'Toggle UI labels',
 	'action.toggle-edge-scrolling.menu': 'Edge scrolling',
 	'action.toggle-edge-scrolling': 'Toggle edge scrolling',
 	'action.toggle-debug-mode.menu': 'Debug mode',
@@ -299,6 +301,7 @@ export const DEFAULT_TRANSLATION = {
 	'a11y.open-keyboard-shortcuts': 'Open keyboard shortcuts',
 	'menu.title': 'Menu',
 	'menu.theme': 'Theme',
+	'menu.accessibility': 'Accessibility',
 	'menu.copy-as': 'Copy as',
 	'menu.edit': 'Edit',
 	'menu.export-as': 'Export as',

package/src/lib/ui/version.ts

@@ -1,9 +1,9 @@
 // This file is automatically generated by internal/scripts/refresh-assets.ts.
 // Do not edit manually. Or do, I'm a comment, not a cop.
 
-export const version = '3.16.0-next.c30b1b5e551a'
+export const version = '3.16.0-next.eafb52d15064'
 export const publishDates = {
 	major: '2024-09-13T14:36:29.063Z',
-	minor: '2025-07-30T09:52:11.036Z',
-	patch: '2025-07-30T09:52:11.036Z',
+	minor: '2025-08-08T12:19:11.878Z',
+	patch: '2025-08-08T12:19:11.878Z',
 }

package/src/lib/ui.css

@@ -97,7 +97,7 @@
 	opacity: 1;
 }
 
-.tlui-button[aria-expanded='true'][data-direction='left']::after {
+.tlui-button[aria-expanded='true'][data-direction='left'] {
 	background: linear-gradient(270deg, rgba(144, 144, 144, 0) 0%, var(--color-muted-2) 100%);
 	opacity: 1;
 }
@@ -1000,6 +1000,12 @@
 	max-width: 148px;
 }
 
+.tlui-style-panel[data-show-ui-labels='true'] .tlui-button[data-isactive='true'] {
+	border-radius: 10px;
+	outline: 2px solid var(--color-text);
+	outline-offset: -5px;
+}
+
 .tlui-style-panel::-webkit-scrollbar {
 	display: none;
 }
@@ -1064,6 +1070,26 @@
 	}
 }
 
+/* Accessibility subheadings */
+
+.tlui-style-panel__section .tlui-style-panel__subheading,
+.tlui-style-panel__section__common .tlui-style-panel__subheading,
+.tlui-style-panel__subheading + .tlui-slider__container {
+	margin: 0;
+	padding: var(--space-2) var(--space-3) 0px var(--space-4);
+	font-size: 12px;
+	font-weight: inherit;
+	line-height: inherit;
+}
+
+.tlui-style-panel .tlui-style-panel__subheading:nth-of-type(1) {
+	padding-top: var(--space-3);
+}
+
+.tlui-style-panel__subheading + .tlui-slider__container {
+	padding-top: 0px;
+}
+
 /* --------------------- Bottom --------------------- */
 
 .tlui-layout__bottom {
@@ -1222,6 +1248,36 @@
 	transition: transform 0.15s ease-out 0.05s;
 }
 
+/* ------------------- Tooltip -------------------- */
+
+.tlui-tooltip {
+	font-size: 12px;
+	padding: 2px 8px;
+	border-radius: 4px;
+	background-color: var(--color-tooltip);
+	box-shadow: none;
+	color: var(--color-text-shadow);
+	max-width: 400px;
+	width: fit-content;
+	text-align: center;
+	pointer-events: none;
+	will-change: transform, opacity;
+	z-index: 2;
+}
+
+.tlui-tooltip__arrow {
+	fill: var(--color-tooltip);
+	will-change: opacity;
+}
+
+[data-radix-popper-content-wrapper]:has(.tlui-tooltip) {
+	z-index: var(--layer-toasts) !important;
+}
+
+[data-radix-popper-content-wrapper]:has(.tlui-tooltip[data-should-animate='true']) {
+	transition: all 0.1s ease-out;
+}
+
 /* ------------------- Debug panel ------------------ */
 
 .tlui-debug-panel {

package/src/test/arrows-megabus.test.tsx

@@ -288,11 +288,13 @@ describe('When shapes are overlapping', () => {
 		editor.pointerDown(0, 50) // over nothing
 		editor.pointerMove(125, 50) // over box1 only
 		expect(bindings().end).toMatchObject({ toId: ids.box1 })
-		editor.pointerMove(175, 50) // box2 is higher but box1 is filled?
+		editor.pointerMove(175, 50) // box2 is higher but box1 is filled, but we're on the edge ofd box 2
+		expect(bindings().end).toMatchObject({ toId: ids.box2 })
+		editor.pointerMove(175, 70) // box2 is higher but box1 is filled, and we're inside of box2
 		expect(bindings().end).toMatchObject({ toId: ids.box1 })
-		editor.pointerMove(225, 50) // box3 is higher
+		editor.pointerMove(225, 70) // box3 is higher
 		expect(bindings().end).toMatchObject({ toId: ids.box3 })
-		editor.pointerMove(275, 50) // box4 is higher but box 3 is filled
+		editor.pointerMove(275, 70) // box4 is higher but box 3 is filled
 		expect(bindings().end).toMatchObject({ toId: ids.box3 })
 	})
 
@@ -304,14 +306,18 @@ describe('When shapes are overlapping', () => {
 		])
 		editor.setCurrentTool('arrow')
 		editor.pointerDown(0, 50)
-		editor.pointerMove(175, 50) // box1 is smaller even though it's behind box2
+		editor.pointerMove(175, 50) // box1 is smaller even though it's behind box2, but we're on the edge of box 2
+		expect(bindings().end).toMatchObject({ toId: ids.box2 })
+		editor.pointerMove(175, 70) // box1 is smaller even though it's behind box2
 		expect(bindings().end).toMatchObject({ toId: ids.box1 })
-		editor.pointerMove(150, 90) // box3 is smaller and at the front
+		editor.pointerMove(150, 90) // box3 is smaller and at the front but we're on the edge of box 2
+		expect(bindings().end).toMatchObject({ toId: ids.box2 })
+		editor.pointerMove(160, 90) // box3 is smaller and at the front and we're in box1 and box 3 and box 2
 		expect(bindings().end).toMatchObject({ toId: ids.box3 })
 		editor.sendToBack([ids.box3])
 		editor.pointerMove(149, 90) // box3 is smaller, even when at the back
 		expect(bindings().end).toMatchObject({ toId: ids.box3 })
-		editor.pointerMove(175, 50)
+		editor.pointerMove(175, 60) // inside of box1 and box 2, but box 1 is smaller
 		expect(bindings().end).toMatchObject({ toId: ids.box1 })
 	})
 })