Repository navigation
refactor(places): Embed Taxonomy Explorer from web-tools - #596
Warren Ehrenfried (warrenehrenfried) merged 5 commits into
Conversation
Replace the in-repo TaxonomyBrowser component with an iframe embed of the Taxonomy Explorer published from OvertureMaps/web-tools, and remove the component, its tests, CSS, test mocks, d3 dependencies, and the static taxonomy data that moved with it. Closes #538 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Signed-off-by: Warren Ehrenfried <warrenehrenfried@gmail.com>
🗺️ Overture Docs preview is live!
Note ♻️ This preview updates automatically with each push to this PR. |
✅MegaLinter analysis: Success
See detailed reports in MegaLinter artifacts Your project could benefit from a custom flavor, which would allow you to run only the linters you need, and thus improve runtime performances. (Skip this info by defining
|
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Signed-off-by: Warren Ehrenfried <warrenehrenfried@gmail.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Signed-off-by: Warren Ehrenfried <warrenehrenfried@gmail.com>
There was a problem hiding this comment.
🔵 Needs a closer look
Removing the local tool requires coordination with the still-open OvertureMaps/web-tools#1 and verification that its production deployment permits cross-origin framing and serves the explorer and all three CSVs.
No open issues 🎉
What changed in this PR
Moves the Places Taxonomy Explorer out of the docs codebase and embeds the version hosted by OvertureMaps/web-tools, addressing #538 while retaining the existing documentation page.
Changes:
- Adds a theme-aware iframe, shared URL helpers, and helper tests.
- Provides a new-tab fallback and CSV links for the October release.
- Removes the local visualization, associated styles and tests, and unused D3 dependencies.
Deployment depends on the web-tools explorer and its downloads becoming available, as noted in the PR description.
| File | Description |
|---|---|
vitest.config.mjs |
Removes the obsolete Docusaurus mock alias. |
static/taxonomy/2026-09-23.0/basic_categories.csv |
Removes the locally hosted September CSV. |
src/css/taxonomyBrowser.css |
Removes local visualization styles. |
src/components/taxonomyViz.jsx |
Removes the local sunburst visualization. |
src/components/taxonomyExplorerEmbed.utils.js |
Centralizes explorer URLs and theme parameters. |
src/components/TaxonomyExplorerEmbed.module.css |
Defines iframe sizing and placeholder styles. |
src/components/TaxonomyExplorerEmbed.jsx |
Adds the theme-aware, hydration-gated embed. |
src/components/taxonomyBrowser.jsx |
Removes the local taxonomy browser. |
src/components/__tests__/taxonomyExplorerEmbed.utils.test.js |
Tests theme URL generation. |
src/components/__tests__/taxonomyBrowser.test.jsx |
Removes tests for the retired implementation. |
src/__mocks__/docusaurus-useBaseUrl.js |
Removes the unused test mock. |
package.json |
Removes direct D3 dependencies. |
package-lock.json |
Removes corresponding D3 dependency entries. |
docs/guides/places/taxonomy-explorer.mdx |
Uses the embed and adds fallback and download links. |
Review effort: Balanced
John McCall (lowlydba)
left a comment
John McCall (lowlydba)
left a comment
There was a problem hiding this comment.
Sweet! Explorer seems to embed and load fine for me on Chrome on the branch deploy 🚀
Alex Iannicelli (atiannicelli)
left a comment
Alex Iannicelli (atiannicelli)
left a comment
There was a problem hiding this comment.
Alex and Claude Conspired to review this PR
Two findings:
One must-fix (removing the September CSVs breaks external code that downloads them) and one should-fix (the LLM export drops this page's URLs). Details are inline.
Alex Iannicelli (atiannicelli)
left a comment
Alex Iannicelli (atiannicelli)
left a comment
There was a problem hiding this comment.
The Taxonomy Explorer packed its bags for web-tools. Smooth move, Warren!
OvertureMaestro and other external projects download these CSVs from docs.overturemaps.org/taxonomy/2026-09-23.0/, and OvertureMaestro falls back to listing static/taxonomy on main. Deleting them would break both. taxonomy.json stays removed because only the old explorer used it. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Signed-off-by: Warren Ehrenfried <warrenehrenfried@gmail.com>
docusaurus-plugin-llms strips imports, so the JSX links lost their URLs in llms-full.txt. Plain Markdown links keep them, still open in a new tab, and remove the duplicated release version in TAXONOMY_DOWNLOADS_URL. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Signed-off-by: Warren Ehrenfried <warrenehrenfried@gmail.com>
|
John McCall (@lowlydba) thanks for iframe idea! Glad we could keep the explorer without the overhead to the docs page 💯 |
GitHub Actions
Active
Pull Request
Closes #538
The Taxonomy Explorer added in #504 is moving to OvertureMaps/web-tools. With this PR, the docs site embeds the tool instead of hosting it.
What changes
docs/guides/places/taxonomy-explorer.mdx: keeps the page, its sidebar entry, the intro, and the link to Places Taxonomy. The<TaxonomyBrowser>component is replaced by<TaxonomyExplorerEmbed />, an iframe with an accessible title. Its height isclamp(600px, 80vh, 900px). Below the embed:Both use plain Markdown links so the URLs survive the
llms-full.txtexport.New
src/components/TaxonomyExplorerEmbed.jsx(+ CSS module). The embed's URL and theme param are intaxonomyExplorerEmbed.utils.js. The page passes the docs color mode as?theme=light|dark. The iframe renders after hydration so it loads once with the correct theme, and toggling the docs theme reloads it with the new value.The
/guides/places/taxonomy-browser→/guides/places/taxonomy-explorer/redirect is unchanged and still works.Removed (added in #504, now dead)
src/components/taxonomyBrowser.jsx,src/components/taxonomyViz.jsx,src/css/taxonomyBrowser.csssrc/components/__tests__/taxonomyBrowser.test.jsx,src/__mocks__/docusaurus-useBaseUrl.js, and the matching@docusaurus/useBaseUrlalias invitest.config.mjsd3-hierarchyandd3-shape(plus transitived3-path) frompackage.json/package-lock.json. Nothing else uses them.static/taxonomy/2026-09-23.0/taxonomy.json. web-tools hosts the taxonomy data now, for the 2026-10-21.0 release.The three September CSVs in
static/taxonomy/2026-09-23.0/stay. External projects download them fromdocs.overturemaps.org/taxonomy/2026-09-23.0/, including OvertureMaestro, which also falls back to listingstatic/taxonomyonmain.I kept the
eslint.config.mjschange from #504 (linting.mjswith the React config) because it isn't specific to the taxonomy tool.Contract with web-tools
Agreed in the review of OvertureMaps/web-tools#1:
?theme=light|dark.No other files in the repo (blog posts,
index.mdx,taxonomy.mdx) linked to/taxonomy/2026-09-23.0/or the removed components.Validation
npx vitest run: passed (5 files passed, 1 skipped; 122 tests passed, 7 skipped). Includes new unit tests for the embed URL helper.npx eslint .: passed (0 errors; 3 warnings, none in changed files)npx markdownlint docs/guides/places/taxonomy-explorer.mdx: passednpx prettier --checkon new/changed source files: passednpm run build: passed.build/taxonomy/2026-09-23.0/contains only the three CSVs,llms-full.txtincludes the fallback and download URLs, and the redirect page is still generated./guides/places/taxonomy-browser. It redirected to/guides/places/taxonomy-explorer/, and the iframe rendered withsrc=…/taxonomy-explorer/?theme=light. After toggling dark mode,srcchanged to?theme=dark.