feat: filter the content list by taxonomy term - #3046
Open
eisenbruch wants to merge 5 commits into
Open
Conversation
A collection's list can be filtered by status, author, byline, date range, free text and any indexed custom field, but not by a taxonomy term — in the admin or over the API — even where a taxonomy is attached and every entry carries one. Adds `termFilters`, keyed by taxonomy name and valued by term slugs: OR within a taxonomy, AND across taxonomies. That mirrors `fieldFilters`, which ANDs its keys, and matches how the controls read in a UI, where two terms of one taxonomy widen a search and two taxonomies narrow it. Resolution is an EXISTS subquery per key, applied in both `findMany` and `countWithResolvedFilters` so totals and pages agree. Two details the junction imposes, both of which match nothing rather than erroring when got wrong: `content_taxonomies.entry_id` stores the ec_* row's translation_group rather than its id, unlike the byline junction alongside it; and it points at `taxonomies.translation_group`, so a term matches through any locale variant unless the list is locale-scoped. A taxonomy not attached to the collection is rejected as a validation error rather than ignored, and a key that resolves to no slugs matches nothing rather than degrading to "no filter". Both are deliberate: a silently dropped filter returns a complete, plausible, unfiltered list with a 200, which is the hardest kind of wrong answer to notice. Refs emdash-cms#3043
Adds one dropdown per taxonomy applied to the collection, beside the status, author and byline filters, driving the `termFilters` parameter added to the content list in the previous commit. Nothing is configured per site. A collection already declares which taxonomies apply to it, so the controls are derived from that: a collection with no taxonomy renders nothing new, and one that gains a taxonomy gains its filter. Terms load per taxonomy and only for the ones on screen, so a site with several does not pay for all of them at once. A hierarchical taxonomy is flattened depth-first and indented, matching how the entry editor's picker reads. "No selection" is represented by the absence of a key rather than an empty array, at every layer. An empty array means "match nothing" to the server, and an untouched control must not mean that. Refs emdash-cms#3043
🦋 Changeset detectedLatest commit: e13a7f6 The changes in this PR will be included in the next version bump. This PR includes changesets to release 17 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
github-actions
Bot
added
review/needs-review
Contributor
Scope checkThis PR changes 506 lines across 11 files. Large PRs are harder to review and more likely to be closed without review. If this scope is intentional, no action needed. A maintainer will review it. If not, please consider splitting this into smaller PRs. See CONTRIBUTING.md for contribution guidelines. |
Contributor
Overlapping PRsThis PR modifies files that are also changed by other open PRs:
This may cause merge conflicts or duplicated work. A maintainer will coordinate. |
applyTermFilters had been inserted between applyBylineFilter's doc comment and the method, so the byline docs sat on the wrong function. Also tidies punctuation and spelling in the new comments and changeset.
17 tasks
@emdash-cms/admin
@emdash-cms/auth
@emdash-cms/auth-atproto
@emdash-cms/blocks
@emdash-cms/cloudflare
@emdash-cms/contentful-to-portable-text
emdash
create-emdash
@emdash-cms/gutenberg-to-portable-text
@emdash-cms/plugin-cli
@emdash-cms/plugin-types
@emdash-cms/registry-client
@emdash-cms/registry-lexicons
@emdash-cms/registry-moderation
@emdash-cms/registry-verification
@emdash-cms/sandbox-workerd
@emdash-cms/x402
@emdash-cms/plugin-ai-moderation
@emdash-cms/plugin-atproto
@emdash-cms/plugin-audit-log
@emdash-cms/plugin-color
@emdash-cms/plugin-embeds
@emdash-cms/plugin-field-kit
@emdash-cms/plugin-forms
@emdash-cms/plugin-webhook-notifier
commit: |
Contributor
Visual regression: 10 screens changedThese admin screens render differently on this PR. Confirm every change below is intended before accepting.
Maintainers: if every change above is intended, comment Measured head: |
Author
|
Two notes on the CI run, to save a reviewer the digging:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What does this PR do?
Adds
termFiltersto the content list and a dropdown per applied taxonomy in the admin, so a collection organized by a taxonomy can be filtered by it, in the screen editors work in, and over the API.Related: #3043 (closed in favor of Discussion #3055)
Why this shape
fieldFiltersalready ANDs its keys over indexed columns. Terms are not columns, so this is a sibling parameter rather than an extension of that one: it keeps "column" and "term" distinguishable, and avoids a collision when a field and a taxonomy share a name.OR within a taxonomy, AND across taxonomies, which is how the controls read: two terms of one taxonomy widen a search, two taxonomies narrow it.
Core
One
EXISTSsubquery per key, applied in bothfindManyandcountWithResolvedFiltersso totals and pages agree.Two details the junction imposes, both of which match nothing rather than erroring when got wrong, so they are worth stating:
content_taxonomies.entry_idstores the ec_* row'stranslation_group, not its id, unlike_emdash_content_bylines.content_idalongside it, which stores the row id.taxonomies.translation_group, so a term matches through any of its locale variants unless the list is locale-scoped.Two deliberate failure choices
Both are the same principle: a filter that silently matches everything returns a complete, plausible, unfiltered list with a 200, which is the hardest kind of wrong answer to notice.
VALIDATION_ERROR, not an empty result and not a no-op.At the API-client and UI layers the same idea appears as: "no selection" is the absence of a key, never an empty array.
Admin
Nothing is configured per site. A collection already declares which taxonomies apply to it, so the controls derive from that: a collection with no taxonomy renders nothing new, and one that gains a taxonomy gains its filter. Terms load per taxonomy and only for those on screen. A hierarchical taxonomy is flattened depth-first and indented, matching the entry editor's picker.
Not included
Sorting by a term, and multi-select within a taxonomy. Both fit the shape (the parameter already takes an array), but neither is needed for the filtering case and I would rather not guess at the UI for them.
Discussion
Discussion: #3055. I opened this PR before it, which was the wrong order; the Discussion sets out the shape, the two failure choices, how this relates to #1928 and #2799, and a separate question about unknown query parameters being stripped.
Type of change
Checklist
pnpm typecheckpasses:packages/coreandpackages/adminboth clean.packages/adminhas one pre-existing error insrc/components/editor/ordered-list.ts, present identically on a cleanorigin/mainin my environment.pnpm lintpasses:oxlint --type-awareclean on every changed filepnpm testpasses (or targeted tests for my change): see the note belowpnpm formathas been runuseLingui; nomessages.pochanges includedAI-generated code disclosure
Screenshots / test output
The new control, on a collection with the
categorytaxonomy applied, and opened to show that taxonomy's terms. Captured onpnpm ux:site:startwith theeditorial-smallprofile.Verified against a running site (
pnpm ux:site:start,editorial-small, patched core and admin), which is the more useful evidence anyway:The admin request carries it correctly:
…&termFilters=%7B%22category%22%3A%5B%22opinion%22%5D%7D→ 200.Worth recording that the middle case is exactly the bug being fixed: before rebuilding core, that same request returned all three rows, because the unknown parameter was dropped silently.
Unit tests: seven added, covering OR within a taxonomy, AND across taxonomies, an empty filter matching nothing, an unknown slug matching nothing, totals staying stable across cursor pages, and combining with an indexed field filter. They seed
content_taxonomiesby hand precisely to pin the two junction details above.On the wider suite, stated plainly rather than hidden:
tests/unit tests/databasereports 36 failed files / 458 failed tests on this branch, and exactly the same 36 / 458 on a cleanorigin/mainin my environment, from what looks like a localbetter-sqlite3native module problem. Same run: 3,954 passing here against 3,947 on main, i.e. the seven added. I could not get a green baseline to compare against, so I am flagging it rather than claiming green.tests/database/repositories/content.test.tsalso passes on Node 22.23.2 (77 passed), after a follow-up commit that movesapplyTermFiltersbelowapplyBylineFilterso the byline method keeps its own doc comment.