Collapsible sidebar groups for collections, taxonomies and plugin admin pages (first slice of the roadmap item #1763)

[swissky]

Where this sits

Sidebar grouping is on the 1.0 roadmap (#1023 / roadmap mirror #1763) and has been asked for since April, in several shapes:

• Feature: Collection grouping support for plugin organization #291 + PR feat(core): add group and sortOrder to collections for admin UI organization #292 (April): group and sortOrder columns on _emdash_collections. Stale, closed without CLA. sortOrder has since shipped separately (Feature: Collection sort order in admin sidebar #474).
• Admin sidebar menu tree with collection grouping, plugin subgroups, and public menu sync #1027 + PR feat(admin): sidebar menu tree with collection grouping, plugin subgroups, and public menu sync #1024 (May): grouping plus nested submenus, public menu sync and a reorder UI in one 1,800-line PR. @ascorbic: "collection grouping is an interesting idea, but this is more than one feature". Closed by the author.
• Proposal: Admin sidebar collection grouping and plugin admin page grouping #1151 (May): the promised smaller restart, closed in June waiting for someone to implement it.
• Collection sidebar folders (group collections under a collapsible header) #1615 (June): group on a collection rendering as a collapsible folder, 3 upvotes, no maintainer reply; a comment asked for taxonomies to follow. Covered below, including taxonomies.
• Feature: hierarchical plugin admin navigation separate from admin.pages #1002 (May), Feature Request: Declarative Admin Sidebar Navigation (Grouping & Role Guards) #2317 (August), Let a plugin admin page declare a minimum role, so the sidebar hides it from roles that cannot open it #3034 (September): plugin pages as one parent with children; declarative nav with role guards; a minimum role on plugin pages.
• Contextual collection workflows in the admin sidebar (small first slice of #1763) #2047 (July): collection submenus with All / Add new / taxonomies. @masonjames's rule for taxonomies there (nest when assigned to one collection, keep shared ones under Manage) is what the taxonomy behaviour below generalises.

This proposal is the slice ascorbic asked for in #1027: grouping only. No menu sync, no reorder UI (reorder exists already), no nested submenus beyond one level, no config-file nav. It is additive on top of sort_order, icon and hidden, which are all in the schema today.

The problem

The admin sidebar renders one flat entry per collection, taxonomy and plugin page. That works for a blog with posts and pages. It stops working the moment a site has real structure: a WordPress import brings 10–20 content types, and plugins that manage data provision helper collections of their own.

This is our production site (17 collections, one plugin that syncs a club calendar from an external source and needs seven collections plus three admin pages to do it):

Left is today. Editors scroll past seven "Kalender: …" entries to reach Team or Sponsors, and the plugin's own pages sit in a different section from the data they operate on.

The proposal

Give the sidebar the structure the Cloudflare dashboard already uses: top-level entries that expand into a sub-menu, with the chevron, indentation and active-state handling from Kumo's Sidebar.Collapsible / Sidebar.MenuSub / Sidebar.MenuChevron. The components are already in the admin bundle; nothing new is imported.

Three additive pieces make it configurable per site, without touching how collections work:

1. group on a collection (new nullable nav_group column on _emdash_collections, one migration). Collections with the same group render as one collapsible entry labelled with the group, positioned where the first member sits. An empty group is today's behaviour.
2. icon and hidden surfaced. Both columns already exist; hidden is honoured by the sidebar, icon is stored but never shown. The manifest now publishes both, and the content type editor gets a "Navigation" block: group, icon, hide from sidebar, dashboard quick action.
3. group on plugin adminPages. A plugin page whose group matches a visible collection group renders inside that folder, next to the data it manages. Otherwise it groups within the Plugins section.

Taxonomies need no configuration: a taxonomy joins a folder when every collection it is assigned to shares that group.

Behaviour details (decisions, not gaps)

• Folder open/closed state is stored per browser (localStorage). The folder containing the current route opens on load, matching the Cloudflare dashboard.
• Collapsed rail: a folder is a single icon linking to its first member, highlighted while any member is active.
• Order inside a folder: collections, then taxonomies, then plugin pages; each in their existing order.
• Group is free text. A typo makes a second folder; a picker of existing groups is a UI refinement that needs no data change.
• Role filtering runs before grouping, so a folder never shows for a user who cannot see any of its members. A minRole on plugin pages (Let a plugin admin page declare a minimum role, so the sidebar hides it from roles that cannot open it #3034) would plug into the same step.
• A plugin page declared with path / gets the active state inside a folder (the flat Plugins section still has the bug from Plugin admin page declared with path "/" never gets the sidebar active state (hits the official forms plugin) #2988; that is a separate fix).
• Dashboard quick actions: admin.quickCreate (in the existing admin_config JSON, no migration) removes the "New …" button for collections that are machine-managed. Hidden collections keeping their quick action today is a bug on its own; fixed separately in fix(admin): hide dashboard quick actions for hidden collections #3060.

What it does not touch

No change to logged-out routes, queries or the manifest shape for existing fields; everything is additive with defaults that reproduce current behaviour. Config-defined collections are untouched. i18n through Lingui, logical Tailwind classes throughout.

Where it is

Built on 0.37 and running on a fork build of the site above; rolling out to its production this week. The grouping rules live in one pure function with tests; the manifest, registry and API changes have tests. If there is appetite, I would split it into: the sidebar groups (migration + API + manifest + admin), the editor's Navigation block with quickCreate, and group on plugin admin pages.

The PRs are ready to open in that order once the direction is confirmed.

[ascorbic]

This looks like a good solution.

[swissky]

Thanks. First slice is up as #3062 (collection groups + taxonomies); the editor navigation settings and plugin-page groups follow as separate PRs once it lands.

[marks-zyz]

Field data for the second slice, from a site shaped exactly like the problem you describe, plus two things I measured in 0.38.0 that the follow-up PR will run into.

The site

Engineering firm, one editor, no blog, 16 collections. The client could not tell which page each collection feeds. I grepped the Astro sources for which file reads which collection:

Where it shows up	Collections
sobre.astro	fundadores, socios, timeline, certificacoes, numeros, valores
index.astro (home)	slides_home, depoimentos, diferenciais
inovacao.astro	inovacoes, etapas, depoimentos_central
own route	projetos (33 entries), projetos_internos, paginas
the whole site	configuracoes, one entry: phone, address, social links

Six of the sixteen exist only to fill one page. Grouping turns that flat list into five folders and changes the editor's question from "what is a Diferencial" to "what am I editing on the About page". Worth the upgrade on its own.

Two measurements for the follow-up

Three consumers read manifest.collections, and they disagree. In 0.38.0 the sidebar and the dashboard both go through visibleCollectionEntries (Sidebar.tsx:80, Dashboard.tsx:147), but the command palette still iterates Object.entries(manifest.collections) directly (AdminCommandPalette.tsx:138). A hidden collection is gone from the sidebar and from the quick actions after #3060, and still listed in the palette. Whatever shape quickCreate lands in, it needs the same three call sites, and the palette is the one that gets forgotten.

hidden is one axis and the editor needs two. To drop "+ Configuração" from the dashboard today I have to hide configuracoes from the sidebar, and the client does need to open it to change the phone number. That is why a quick action flag separate from hidden is the right call, not a refinement of it.

Related, since the Navigation block covers it: icon on a collection is accepted and stored, and the sidebar never reads it. getCollectionNavIcon (admin-navigation-icons.ts:73) maps only pages and posts, so all 16 of ours render the same generic document glyph although the seed declares award, settings, lightbulb and so on. Users are already writing the field.

One thing the group field cannot express, worth a line in the docs rather than a schema change: a group is 1:1, reuse is 1:N. certificacoes renders on the About page and in the footer, projetos on the home, the portfolio index and the contact page. The group tells the editor where to find it, not everywhere it renders.

Also: routable already distinguishes a collection with its own route from one that only fills a section of a page. If a default group is ever wanted for sites that set nothing, that column is already there.

Happy to take the editor Navigation block (group, icon, hidden, quick action) as a PR, covering the three call sites, if it is still unclaimed after eleven days. I will follow CONTRIBUTING on tests and AI disclosure. I run this panel in Portuguese in front of a real client, so I can check the Lingui strings in a non English locale too.

Measured against emdash@0.38.0 and @emdash-cms/admin@0.38.0 from npm; the client site is still on 0.37.0.

[swissky]

Thank you so much for writing this up, @marks-zyz. A real 16-collection site with the grep of which page reads what is exactly the evidence this slice needed, and I'm sorry you waited eleven days for an answer.

Your three measurements are all covered in #3440, which I had queued before I saw your offer:

• Command palette: it now goes through visibleCollectionEntries, so a hidden collection is gone from all three places. There's a regression test for the palette.
• Two axes: admin.quickCreate (defaults to true) is a separate "Quick action on the dashboard" switch. configuracoes can keep its sidebar entry and lose only its "+ New" button.
• Icons: the sidebar and palette now render the declared icon (any Phosphor name, like award, settings or lightbulb). A folder takes the icon of its first collection that declares one.

Since you already have the site, would you be up for trying the PR against it and reviewing? Two things would help most: whether the Navigation block reads clearly for your client, and, once the catalogs are extracted after merge, whether the Portuguese strings make sense in front of a real editor. Your note that a group is 1:1 while reuse is 1:N is a good docs point too, and I'm happy to add it there.

[marks-zyz]

Thanks, @swissky, and no apology needed. I ran #3440 on the 16-collection site after moving it to emdash 1.1.0: declared icons render in the sidebar and the palette, folders take the first icon, hidden removes a collection from the sidebar, the dashboard and the palette, and quickCreate: false drops only the "+ New" button. That covers everything we asked for.

The Navigation block reads clearly. Two small things: with "Hide from navigation" on, the "Quick action on the dashboard" switch stays active although it no longer does anything, and the Group placeholder "Calendar" reads like a suggestion to file the collection under the new Calendar item.

The block's strings are still empty in the pt-BR catalog; they will go in the pt-BR translation PR we are preparing. And yes, please add the group (1:1) versus reuse (1:N) note to the docs.