feat(dtpr-ai): taxonomy catalog + element/category pages + Cmd-K + locale

[pichot]

Summary

Builds out the DTPR-AI documentation site's schema-browsing surface from scratch. Two plans land together — the catalog (/taxonomy) and the per-element / per-category pages plus unified Cmd-K search and a ?locale= URL convention.

What ships

• /taxonomy catalog: every element grouped by category, sticky category sidebar with scroll-spy, copy-link anchors, schema version selector (?v=), per-row + per-category "Open page" affordances.
• /taxonomy/elements/<id>: hero via <DtprElementDetail> with an interactive Playground (Variables form, Context chip row, Default/Dark style toggle) backed by deriveElementDisplay.
• /taxonomy/categories/<id>: title, description, read-only context palette, elements list linking to element pages.
• Editorial overlays: drop a content/taxonomy/{elements,categories}/<id>.md to add authored narrative; Cmd-K indexes it automatically; real markdown wins on collisions with the synthetic group.
• Cmd-K: shadowed app.vue injects two synthetic groups (Elements + Categories) into <UContentSearch>, scoped to the active version + locale.
• Locale: shared useDtprState composable wires ?v= and ?locale= consistently across catalog, element pages, category pages, and Cmd-K. DTPR-derived surfaces only — docus prose stays English-only.
• Top-nav Taxonomy link via shadowed AppHeaderCTA (left of the dark-mode toggle).

Plans

• docs/plans/2026-04-27-001-feat-dtpr-ai-taxonomy-view-plan.md — catalog (U1–U7).
• docs/plans/2026-05-05-001-feat-dtpr-taxonomy-pages-and-search-plan.md — element/category pages, Cmd-K, locale (U1–U7).

Test plan

• /taxonomy renders all categories grouped, sidebar scroll-spy works, copy-link button copies #element-<id> URL.
• /taxonomy/elements/<id> renders hero + Playground; typing in a variable input live-updates the rendered title/description; clicking a context chip recolors the icon; Default/Dark toggle swaps the icon variant.
• /taxonomy/categories/<id> renders description, context palette swatches, and the elements list; clicking an element row navigates with ?v= and ?locale= carried forward.
• Cmd-K shows "Elements" and "Categories" groups alongside prose docs; selecting an item routes to its page.
• Switching locale updates the URL and re-renders schema strings (or falls back to en per field).
• Switching version updates the URL; pinned ?v=ai@2026-04-16-beta deep links resolve correctly; unknown versions show the inline alert.
• Drop a fixture md at content/taxonomy/elements/<known_id>.md — body renders below the playground; Cmd-K dedupes the synthetic entry.

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	dtpr-ai	a383f4d	May 05 2026, 07:58 PM

[greptile-apps]

Greptile Summary

This PR builds out the DTPR-AI documentation site's schema-browsing surface: a /taxonomy catalog with scroll-spy sidebar, per-element and per-category detail pages, a Cmd-K search overlay that injects synthetic DTPR groups, and a ?v= / ?locale= URL convention wired through a shared useDtprState composable.

• New pages (taxonomy/index.vue, elements/[id].vue, categories/[id].vue): each surfaces versioned DTPR schema data with an interactive playground (element page), context palette (category page), and forwarded ?v=/?locale= query params derived from validated state rather than raw route params.
• New composables (useDtprState, useDtprSearchOverlay): useDtprState centralises version + locale resolution; useDtprSearchOverlay builds Cmd-K groups client-side, includes a truncation warning when a schema exceeds 200 elements, and deduplicates synthetic entries against authored markdown.
• App shell changes: shadowed app.vue wires dtprGroups into <LazyUContentSearch>, and a shadowed AppHeaderCTA adds the Taxonomy nav link.

Confidence Score: 5/5

The PR adds a large but self-contained documentation surface; all new code paths are read-only API fetches and UI rendering with no mutations to shared state outside the router.

The core concerns raised in earlier review rounds — stale payload on SPA navigation, raw query param propagation, limit=200 truncation, and the context chip dark-mode override — have each been addressed in this revision. The element page now uses a dynamic useAsyncData key keyed on element ID; queryString in all three pages is derived from validated activeVersion/activeLocale rather than raw route params; truncation warnings are in place in both taxonomy/index.vue and useDtprSearchOverlay; and DtprPlayground uses effectiveContextId/chipsLocked to correctly reflect the dark-mode override in chip visual state. No new correctness gaps were found across the composables, pages, or components.

No files require special attention. The categories/[id].vue elements fetch still omits a meta truncation check (unlike the catalog and Cmd-K composable), but that was already noted in a prior review thread.

Important Files Changed

Filename	Overview
dtpr-ai/app/composables/useDtprState.ts	New composable: centralises version/locale resolution from route query params, validates against a fetched schemas list, exposes writable computeds that call router.replace. Clean design, correct deduplication key for useFetch.
dtpr-ai/app/composables/useDtprSearchOverlay.ts	New composable: synthesises Cmd-K groups from DTPR API, correctly guards against truncation with a console warning when meta.total exceeds ELEMENTS_PAGE_LIMIT, and deduplicates against authored md paths.
dtpr-ai/app/pages/taxonomy/index.vue	New catalog page: scroll-spy sidebar, hash anchor copy, queryString built from validated state. Truncation alert mirrors the composable. Unused route variable declared but never read — cosmetic dead code.
dtpr-ai/app/pages/taxonomy/elements/[id].vue	New element detail page: dynamic useAsyncData key eliminates stale payload on SPA navigation; queryString derived from validated activeVersion/activeLocale; notFound detection via elementError.
dtpr-ai/app/pages/taxonomy/categories/[id].vue	New category detail page: static key for all-categories fetch is intentional (data covers all categories, client-side find handles filtering); dynamic key for per-category elements fetch; elements response omits meta/truncation check unlike other consumers.
dtpr-ai/app/components/DtprPlayground.vue	New playground component: effectiveContextId correctly mirrors chip visual state to the dark-mode override; variableValues reset on element.id change handles key diffing correctly.
dtpr-ai/app/app.vue	Shadowed docus app.vue: single intentional divergence (dtprGroups prop on LazyUContentSearch), well-documented sync requirement for upstream upgrades.
dtpr-ai/app/components/DtprPageHeader.vue	New shared sticky header component: version/locale selectors emitted as update events, version-missing alert, slot-based composition for page-specific headings and actions.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    AppVue["app.vue (shadowed)"]
    useDtprSearchOverlay["useDtprSearchOverlay\n(Cmd-K groups)"]
    useDtprState["useDtprState\n(?v= / ?locale= resolver)"]
    DTPR_API["DTPR API\n/schemas/{version}/..."]

    AppVue -->|"passes files ref"| useDtprSearchOverlay
    useDtprSearchOverlay -->|"calls"| useDtprState
    useDtprSearchOverlay -->|"fetches elements + categories\n(server:false, watches activeVersion/Locale)"| DTPR_API

    TaxonomyIndex["/taxonomy\n(catalog + scroll-spy)"]
    ElementPage["/taxonomy/elements/[id]\n(hero + DtprPlayground)"]
    CategoryPage["/taxonomy/categories/[id]\n(palette + elements list)"]

    TaxonomyIndex -->|"calls"| useDtprState
    ElementPage -->|"calls"| useDtprState
    CategoryPage -->|"calls"| useDtprState

    TaxonomyIndex -->|"fetches categories + elements\n(dynamic key, limit=200)"| DTPR_API
    ElementPage -->|"fetches element + categories\n(key = id, watches id+version+locale)"| DTPR_API
    CategoryPage -->|"fetches all categories\n(static key)\nfetches elements by category\n(dynamic key, limit=200)"| DTPR_API

    useDtprState -->|"reads ?v= ?locale=\nwrites via router.replace"| RouteQuery["Route query params"]

    DtprPageHeader["DtprPageHeader\n(sticky version/locale selectors)"]
    TaxonomyIndex --> DtprPageHeader
    ElementPage --> DtprPageHeader
    CategoryPage --> DtprPageHeader

    DtprPlayground["DtprPlayground\n(variables form + context chips)"]
    ElementPage --> DtprPlayground

Loading

_{Reviews (2): Last reviewed commit: "fix(dtpr-ai): address greptile review (s..." | Re-trigger Greptile}

[pichot]

@greptile