feat(tldraw): redesign page menu (tldraw#8836)

This is a clean-history reimplementation of tldraw#8827 (branch
[`steve/page-menu-no-edit-mode`](https://github.com/tldraw/tldraw/tree/steve/page-menu-no-edit-mode))
— the final diff is byte-identical, but the work is split into three
reviewable commits instead of 24 incremental updates. Please review
here; tldraw#8827 has been closed in favor of this PR.

The page menu used to require flipping into an explicit edit mode to
rename pages or reorder them. This PR removes that mode entirely.
Reordering happens by dragging the row itself, renaming happens inline
(double-click, Enter, or the row submenu), and the popover gains a
draggable resize handle so the list height can be adjusted and persisted
across sessions.


https://github.com/user-attachments/assets/c9e0a4fc-e644-4134-b261-58c0515cf4a2

Closes tldraw#8814.

### Interactions

| Interaction | Before | After |
| ------------------ | ------------------------------------------ |
------------------------------------------- |
| Reorder a page | Toggle Edit, drag the dedicated handle | Drag the row
itself |
| Rename a page | Toggle Edit, click the field | Double-click the row,
press Enter, or use the kebab submenu |
| Current page mark | Checkmark icon | Subtle background pill (matches
dotcom sidebar) |
| Submenu trigger | Always visible | Hidden until row hover (and hidden
while renaming or dragging) |
| List height | Fixed | Drag the resize handle to adjust; double-click
it to reset to default. Persisted to localStorage. |
| Create page button | Header | Pinned to the bottom of the popover |

Renaming a non-current page no longer silently navigates to it. The
rename input matches the row's vertical metrics so the label doesn't
shift when editing, and blur commits the change.

### Commit storyline

1. **`feat(tldraw): redesign page menu`** — drop the edit-mode toggle,
switch to inline rename, move "Create new page" to a footer button,
replace the checkmark with a current-row pill, and add the
auto-scrolling drag-from-row reorder behavior (plus the coarse-pointer
drag handle).
2. **`feat(tldraw): make page menu list resizable and persist height`**
— add the resize handle, localStorage persistence, double-click to
reset, and the Radix-available-height cap.
3. **`test(e2e): extend overlay snapshot timeout for cold preview
runs`** — small unrelated stability tweak that the original branch
picked up along the way.

### Change type

- [x] `improvement`

### Test plan

1. Open the page menu with multiple pages.
2. Drag a row by its body — it should reorder without entering any mode.
3. Double-click a row's label (or press Enter / use the kebab menu) — it
should rename inline. Blur should commit.
4. Confirm the current page shows the highlight pill and renaming a
non-current page does not navigate.
5. Drag the resize handle at the bottom of the popover up and down;
reopen the menu and confirm the height is remembered.
6. Double-click the resize handle — the list should snap back to its
default height and forget the saved preference.
7. Open the page menu when the current page is far down the list — it
should scroll into view.

- [x] End to end tests

### Release notes

- Redesigned the page menu: reorder rows by dragging them directly,
rename inline by double-clicking or pressing Enter, and resize the page
list to remember your preferred height (double-click the resize handle
to reset it). The explicit edit mode has been removed.

### API changes

- Added `page-menu.resize` translation key for the resize handle's
accessible label.
- Removed unused `page-menu.max-page-count-reached` translation key.

### Code changes

| Section         | LOC change   |
| --------------- | ------------ |
| Core code       | +663 / -498  |
| Tests           | +115 / -69   |
| Automated files | +1 / -1      |

Author: steveruizok

apps/examples/e2e/fixtures/menus/PageMenu.ts

@@ -4,16 +4,15 @@ export class PageMenu {
 	readonly pagemenuButton: Locator
 	readonly header: Locator
 	readonly createButton: Locator
-	readonly editButton: Locator
 	readonly pageList: Locator
 	readonly pageItems: Locator
 
 	constructor(public readonly page: Page) {
 		this.page = page
 		this.pagemenuButton = this.page.getByTestId('page-menu.button')
-		this.header = this.page.getByRole('dialog').getByText('Pages')
+		// The popover no longer has a title row — use the list as the "is the menu open" anchor.
+		this.header = this.page.getByTestId('page-menu.list')
 		this.createButton = this.page.getByTestId('page-menu.create')
-		this.editButton = this.page.getByTestId('page-menu.edit')
 		this.pageList = this.page.getByTestId('page-menu.list')
 		this.pageItems = this.page.getByTestId('page-menu.item')
 	}

apps/examples/e2e/tests/test-overlay-snapshots.spec.ts

@@ -39,7 +39,12 @@ async function snapshotCanvas(page: Page) {
 	// Allow a small tolerance to absorb sub-pixel anti-aliasing variance on
 	// rotated or curved overlay strokes. A real overlay regression (missing
 	// handle, wrong color, moved stroke) changes far more than 0.5% of pixels.
-	await expect(page.locator('.tl-canvas')).toHaveScreenshot({ maxDiffPixelRatio: 0.005 })
+	// Screenshot capture also waits for the canvas element to become stable,
+	// which can exceed the global 2s expect timeout on cold preview runs.
+	await expect(page.locator('.tl-canvas')).toHaveScreenshot({
+		maxDiffPixelRatio: 0.005,
+		timeout: 10_000,
+	})
 }
 
 test.describe('Overlay snapshots', () => {

apps/examples/e2e/tests/test-page-menu.spec.ts

@@ -1,7 +1,35 @@
-import { expect } from '@playwright/test'
+import { expect, type Locator, type Page } from '@playwright/test'
+import { type Editor } from 'tldraw'
 import test from '../fixtures/fixtures'
 import { setupOrReset, sleep } from '../shared-e2e'
 
+declare const editor: Editor
+
+const isMobileProject = () => test.info().project.name.includes('Mobile')
+
+async function expectPageItemToBeCurrent(pageItem: Locator, isCurrent: boolean) {
+	await expect(pageItem).toHaveAttribute('data-iscurrent', isCurrent ? 'true' : 'false')
+}
+
+async function createPagesForReordering(page: Page) {
+	await page.evaluate(() => {
+		editor.createPage({ name: 'Page 2' })
+		editor.createPage({ name: 'Page 3' })
+	})
+}
+
+async function useCoarsePointer(page: Page) {
+	await page.evaluate(() => {
+		window.dispatchEvent(new PointerEvent('pointerdown', { pointerType: 'touch' }))
+		editor.updateInstanceState({ isCoarsePointer: true })
+	})
+	await expect.poll(() => page.evaluate(() => editor.getInstanceState().isCoarsePointer)).toBe(true)
+}
+
+async function getPageNames(page: Page) {
+	return await page.evaluate(() => editor.getPages().map((p) => p.name))
+}
+
 test.describe('page menu', () => {
 	test.beforeEach(setupOrReset)
 
@@ -49,31 +77,19 @@ test.describe('page menu', () => {
 			await expect(firstPage).toBeVisible()
 			await expect(secondPage).toBeVisible()
 
-			await expect(
-				firstPage.locator('.tlui-page-menu__item__button > .tlui-button__icon')
-			).toHaveAttribute('data-checked', 'false')
-			await expect(
-				secondPage.locator('.tlui-page-menu__item__button > .tlui-button__icon')
-			).toHaveAttribute('data-checked', 'true')
+			await expectPageItemToBeCurrent(firstPage, false)
+			await expectPageItemToBeCurrent(secondPage, true)
 
 			// Click on second page
 			await secondPage.locator('button').first().click()
-			await expect(
-				firstPage.locator('.tlui-page-menu__item__button > .tlui-button__icon')
-			).toHaveAttribute('data-checked', 'false')
-			await expect(
-				secondPage.locator('.tlui-page-menu__item__button > .tlui-button__icon')
-			).toHaveAttribute('data-checked', 'true')
+			await expectPageItemToBeCurrent(firstPage, false)
+			await expectPageItemToBeCurrent(secondPage, true)
 
 			// Click on first page
 			await firstPage.locator('button').first().click()
 
-			await expect(
-				firstPage.locator('.tlui-page-menu__item__button > .tlui-button__icon')
-			).toHaveAttribute('data-checked', 'true')
-			await expect(
-				secondPage.locator('.tlui-page-menu__item__button > .tlui-button__icon')
-			).toHaveAttribute('data-checked', 'false')
+			await expectPageItemToBeCurrent(firstPage, true)
+			await expectPageItemToBeCurrent(secondPage, false)
 		})
 	})
 
@@ -100,6 +116,27 @@ test.describe('page menu', () => {
 		})
 	})
 
+	test('On coarse pointers, canceling the new page prompt does not create a page', async ({
+		page,
+		pageMenu,
+	}) => {
+		test.skip(!isMobileProject(), 'Coarse-pointer page menu behavior')
+
+		const { pagemenuButton, createButton } = pageMenu
+
+		await pagemenuButton.click()
+		await useCoarsePointer(page)
+		expect(await getPageNames(page)).toEqual(['Page 1'])
+
+		page.once('dialog', async (dialog) => {
+			expect(dialog.type()).toBe('prompt')
+			await dialog.dismiss()
+		})
+		await createButton.tap()
+
+		expect(await getPageNames(page)).toEqual(['Page 1'])
+	})
+
 	test.describe('You can rename a page', () => {
 		test('You can rename a page by double clicking its name', async ({ page, pageMenu }) => {
 			const { pagemenuButton, pageItems } = pageMenu
@@ -246,16 +283,12 @@ test.describe('page menu', () => {
 
 				// The new page (last one) should be the active/focused page
 				const newPageItem = await pageMenu.getPageItem(initialCount)
-				await expect(
-					newPageItem.locator('.tlui-page-menu__item__button > .tlui-button__icon')
-				).toHaveAttribute('data-checked', 'true')
+				await expectPageItemToBeCurrent(newPageItem, true)
 
 				// All other pages should not be active
 				for (let i = 0; i < initialCount; i++) {
 					const otherPageItem = await pageMenu.getPageItem(i)
-					await expect(
-						otherPageItem.locator('.tlui-page-menu__item__button > .tlui-button__icon')
-					).toHaveAttribute('data-checked', 'false')
+					await expectPageItemToBeCurrent(otherPageItem, false)
 				}
 			})
 		})
@@ -289,9 +322,7 @@ test.describe('page menu', () => {
 				await expect(firstPage).toBeInViewport()
 
 				// Also verify it's marked as checked/active
-				await expect(
-					firstPage.locator('.tlui-page-menu__item__button > .tlui-button__icon')
-				).toHaveAttribute('data-checked', 'true')
+				await expectPageItemToBeCurrent(firstPage, true)
 			})
 		})
 
@@ -322,59 +353,70 @@ test.describe('page menu', () => {
 				await pagemenuButton.click()
 
 				// Verify the middle page is marked as the current/focused page
-				await expect(
-					middlePage.locator('.tlui-page-menu__item__button > .tlui-button__icon')
-				).toHaveAttribute('data-checked', 'true')
+				await expectPageItemToBeCurrent(middlePage, true)
 
 				// Verify other pages are not focused
 				const firstPage = await pageMenu.getPageItem(0)
 				const lastPage = await pageMenu.getPageItem(2)
-				await expect(
-					firstPage.locator('.tlui-page-menu__item__button > .tlui-button__icon')
-				).toHaveAttribute('data-checked', 'false')
-				await expect(
-					lastPage.locator('.tlui-page-menu__item__button > .tlui-button__icon')
-				).toHaveAttribute('data-checked', 'false')
+				await expectPageItemToBeCurrent(firstPage, false)
+				await expectPageItemToBeCurrent(lastPage, false)
 			})
 		})
 	})
 
 	test.describe('You can drag and drop pages to reorder them', () => {
-		test('You can enter drag and drop mode and drag a page to a new position', async ({
+		test('Pages can be reordered by dragging the row itself', async ({ page, pageMenu }) => {
+			test.skip(isMobileProject(), 'Mobile page rows can only be reordered from the drag handle')
+
+			const { pagemenuButton } = pageMenu
+
+			await test.step('create multiple pages for reordering', async () => {
+				await createPagesForReordering(page)
+			})
+
+			await test.step('drag page to new position by its row', async () => {
+				await pagemenuButton.click()
+				await expect(pageMenu.pageItems).toHaveCount(3)
+				const firstItem = await pageMenu.getPageItem(0)
+				const secondItem = await pageMenu.getPageItem(1)
+				const firstButton = firstItem.locator('.tlui-page-menu__item__button')
+
+				await firstButton.dragTo(secondItem)
+				await expect.poll(() => getPageNames(page)).toEqual(['Page 2', 'Page 1', 'Page 3'])
+			})
+		})
+
+		test('On coarse pointers, pages can only be reordered by dragging the handle', async ({
 			page,
 			pageMenu,
 		}) => {
-			const { pagemenuButton, editButton } = pageMenu
+			test.skip(!isMobileProject(), 'Coarse-pointer page menu behavior')
+
+			const { pagemenuButton } = pageMenu
 
 			await test.step('create multiple pages for reordering', async () => {
-				await pagemenuButton.click()
-				await pageMenu.createButton.click()
-				await sleep(100)
-				await page.keyboard.press('Enter')
-				await pageMenu.createButton.click()
-				await sleep(100)
-				await page.keyboard.press('Enter')
-				await page.keyboard.press('Escape')
+				await createPagesForReordering(page)
 			})
 
-			await test.step('enter edit mode', async () => {
+			await test.step('dragging the row itself does not reorder pages', async () => {
 				await pagemenuButton.click()
-				await editButton.click()
-				// Should see drag handles
-				await expect(page.locator('.tlui-page_menu__item__sortable__handle').first()).toBeVisible()
-			})
-
-			await test.step('drag page to new position', async () => {
-				const dragHandle = page.locator('.tlui-page_menu__item__sortable__handle').first()
+				await useCoarsePointer(page)
+				await expect(pageMenu.pageItems).toHaveCount(3)
+				const firstItem = await pageMenu.getPageItem(0)
 				const secondItem = await pageMenu.getPageItem(1)
 
-				// Perform drag operation
-				await dragHandle.dragTo(secondItem)
+				await expect(firstItem.getByTestId('page-menu.item-drag-handle')).toBeVisible()
+				await firstItem.locator('.tlui-page-menu__item__button').dragTo(secondItem)
+				expect(await getPageNames(page)).toEqual(['Page 1', 'Page 2', 'Page 3'])
 			})
 
-			await test.step('exit edit mode', async () => {
-				await editButton.click()
-				await expect(page.locator('.tlui-page_menu__item__sortable__handle').first()).toBeHidden()
+			await test.step('dragging the handle reorders pages', async () => {
+				await useCoarsePointer(page)
+				const firstItem = await pageMenu.getPageItem(0)
+				const secondItem = await pageMenu.getPageItem(1)
+
+				await firstItem.getByTestId('page-menu.item-drag-handle').dragTo(secondItem)
+				await expect.poll(() => getPageNames(page)).toEqual(['Page 2', 'Page 1', 'Page 3'])
 			})
 		})
 	})
@@ -399,7 +441,7 @@ test.describe('page menu', () => {
 
 			await test.step('access page submenu and delete', async () => {
 				const pageItem = await pageMenu.getPageItem(1)
-				const submenuButton = pageItem.locator('.tlui-page_menu__item__submenu button')
+				const submenuButton = pageItem.getByTestId('page-menu.item-submenu')
 				await submenuButton.click()
 
 				// Click delete option
@@ -427,7 +469,7 @@ test.describe('page menu', () => {
 				const pageItem = await pageMenu.getPageItem(0)
 
 				// Click the submenu button (three dots)
-				const submenuButton = pageItem.locator('.tlui-page_menu__item__submenu button')
+				const submenuButton = pageItem.getByTestId('page-menu.item-submenu')
 				await submenuButton.click()
 
 				// Click duplicate option
@@ -459,7 +501,7 @@ test.describe('page menu', () => {
 				const pageItem = await pageMenu.getPageItem(1)
 
 				// Click the submenu button
-				const submenuButton = pageItem.locator('.tlui-page_menu__item__submenu button')
+				const submenuButton = pageItem.getByTestId('page-menu.item-submenu')
 				await submenuButton.click()
 
 				// Click delete option
@@ -495,7 +537,7 @@ test.describe('page menu', () => {
 				const lastPageItem = await pageMenu.getPageItem(2)
 
 				// Click the submenu button
-				const submenuButton = lastPageItem.locator('.tlui-page_menu__item__submenu button')
+				const submenuButton = lastPageItem.getByTestId('page-menu.item-submenu')
 				await submenuButton.click()
 
 				// Click move up option
@@ -538,7 +580,7 @@ test.describe('page menu', () => {
 				const firstPageItem = await pageMenu.getPageItem(0)
 
 				// Click the submenu button
-				const submenuButton = firstPageItem.locator('.tlui-page_menu__item__submenu button')
+				const submenuButton = firstPageItem.getByTestId('page-menu.item-submenu')
 				await submenuButton.click()
 
 				// Click move down option

assets/translations/main.json

@@ -331,11 +331,11 @@
 	"context-menu.reorder": "Reorder",
 	"page-menu.title": "Pages",
 	"page-menu.create-new-page": "Create new page",
-	"page-menu.max-page-count-reached": "Max pages reached",
 	"page-menu.new-page-initial-name": "Page 1",
 	"page-menu.edit-start": "Edit",
 	"page-menu.edit-done": "Done",
 	"page-menu.go-to-page": "Go to page",
+	"page-menu.resize": "Resize page list",
 	"page-menu.submenu.rename": "Rename",
 	"page-menu.submenu.duplicate-page": "Duplicate",
 	"page-menu.submenu.title": "Menu",
@@ -493,4 +493,4 @@
 	"ui.close": "Close",
 	"ui.checked": "Checked",
 	"ui.unchecked": "Unchecked"
-}
+}