feat(ui): browse collections by folder with a card grid, drag-and-drop moves, and nav redesign

[tylandavis]

What

Stacked work across the hierarchy/folder views, the list view, and the nav sidebar. Grouped by theme since it's a large branch (41 commits, 136 files).

Browse a collection by folder

• New "By Folder" tab on any collection that belongs to a hierarchy, scoping that collection's documents to one folder tree
• Folder navigation stays inside the collection being browsed rather than redirecting to the hierarchy view
• Folders and documents share one selectable plane in grid mode
• Breadcrumbs end on the current folder as plain text
• At the root, related-collection documents are no longer listed — "everything unfiled, from everywhere" isn't a meaningful grouping

Drag and drop

• Drag documents and folders onto folder cards, sidebar tree nodes, and breadcrumbs (to move up a level or out to root)
• Drag preview is a staggered stack of 40px thumbnails with a count pill, snapped to the cursor
• Cards being dragged fade to 50%
• moveDocuments extracted so drag-drop and the Move button share one path
• DndContext gets an explicit useId so aria-describedby matches across hydration ("Warning: Prop aria-describedby did not match." in Next.js clauderic/dnd-kit#926)

Grid view

• Grid/table view mode toggle on the standard list view, persisted as a documentViewMode list preference (defaults to table)
• New admin.useAsThumbnail collection option names the upload field a card renders as its thumbnail, validated like useAsTitle and defaulting to the collection's first upload field — so non-upload collections get previews too
• Visible heading on the root band of documents not filed under a hierarchy item
• Per-collection pagination controls are labelled, which the merged band otherwise leaves ambiguous
• Cards on the plain collection grid are select-only, since there's nowhere to drop

Nav and account menu

• Sidebar rows are full-bleed and match the Figma row metrics
• User menu moved to the sidebar footer; account menu redesigned with hover submenus and a scrim
• Admin layout constrained to viewport height, overscroll containment, nav toggle/close fixes
• Active sidebar rows no longer change background on hover

Fixes and cleanup

• Card selection handlers no longer shadow the dnd-kit activators
• Deduped hierarchy sidebar tree children, which were rendering twice
• Checkbox visuals driven by CSS state instead of React
• Submenu hover uses :has() instead of JS
• Hierarchy modal selection model and field input reworked; hasMany hierarchy fields now validate per-ID
• Hierarchy card/modal styling matched to Figma; new link button style

Breaking changes

1. useNav() / NavContext no longer expose navRef — publicly exported from @payloadcms/ui, so consumers destructuring it break. The mobile overscroll lock it powered is now handled in CSS.
2. hierarchy:itemsMovedTo / itemsMovedToRoot changed placeholders — {{title}} → {{count}} {{label}}. Every non-English locale still carries the old form and needs a translateNewKeys pass.
3. HierarchyViewData.hierarchySlug is now required — new non-optional field on an exported type, so anything constructing it fails to typecheck. Could be made optional if that matters.

Deep-import-only breaks: HierarchyColumnBrowserProps (ancestorsWithSelections → required selectedDescendantCounts), HierarchySearchProps (dropped collectionSpecificOptions / onFilterChange / selectedFilters, added required parentId), ColumnItemProps (hasSelectedDescendants → selectedDescendantCount), TreeNodeProps (dropped icon). None are in exports/client.

Notes

• Draft, because the branch is large enough that it may be worth splitting — the nav/account-menu redesign is independent of the folder-browsing work — and because the translation strings above still need retranslating.
• The list view now always selects useAsTitle and updatedAt, even when those columns are hidden, since the grid cards always render both.

🤖 Generated with Claude Code