fix(website): repair and redesign the docs adapter picker - #911
Merged
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
blove
enabled auto-merge (squash)
September 1, 2026 02:27
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Contributor
Records the design agreed for the library picker in the docs control plane: keep it in Learn, group Adapters vs Libraries, taglines on the two adapters only, real links, and the lost flex-column rule that is currently colliding title and description in production. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The picker's title and description have been colliding into a single
run-on line in production ("LangGraphLangChain/LangGraph adapter for
Angular UI"). #892 moved the JSX off Tailwind onto semantic class names
and never ported the `flex flex-col`, so `.docs-sidebar-lib-item-text`
carried only `min-width: 0` and both spans fell back to `display:
inline`.
Repairs that, and gives the control the design pass the rest of the
sidebar got in #892:
- Split the menu into labelled Adapters / Libraries groups. Two of the
seven entries are adapters; flattening them made the picker read as a
library index rather than an adapter choice.
- Add a short `tagline` for the two adapters and drop the long
`description` from the menu, so rows stop wrapping ragged (heights
were 66/66/66/138/66/66/90, now 52/52/39/39/39/39/39). `description`
itself is untouched — it is still the fallback for each page's meta
description via resolveDocDescription().
- Cap the open menu to the room left below the trigger. It opens ~342px
down the pane, so it ran 182px past the fold at a 720px viewport; a
CSS `vh` cap cannot fix that (60vh still overflows a 600px window by
102px), so the cap is measured on open and on resize.
- Menu entries become real links, restoring cmd-click and new-tab, and
`menuitemradio` + `aria-checked` to match the single-select they are.
- Drop the duplicate Library row from Environment now the picker owns it.
The CSS-level guard is the notable test: jsdom does not apply the
stylesheet, so no component test could have caught the collision that
shipped.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
blove
force-pushed
the
blove/docs-adapter-dropdown-design-bbb6cc
branch
from
September 1, 2026 03:25
ba35bee to
731e9b4
Compare
Contributor
This was referenced Sep 1, 2026
blove
added a commit
that referenced
this pull request
Sep 1, 2026
/docs was the only /docs/* route without the control plane. That was a deliberate call in #920 — it is a designed landing page, and the prose column would flatten its card grids — but the inconsistency reads worse than that risk. It now renders the docs shell with activeLibrary={null}, reusing the library-neutral state from #920. The landing content sits inside docs-shell-body but outside the [slug] route's md:max-w-3xl article measure, so the grids keep their own width: verified still 2-up at 426px on desktop and single-column at 375px. The sidebar picker is kept even though the page's main content is itself a backend picker. #911 removed a duplication of exactly this shape, so to be explicit: that was two statements of the same fact, this is a statement plus a shortcut for a reader who already knows where they are going. Also renames the render library's display label to json-render. It is called that 85 times across docs content, on the marketing page, and on the /docs card; "Render" existed only in docsConfig, feeding the picker, breadcrumbs, structured data and search. With the control plane on this page both labels are on screen at once. The package stays @threadplane/render and the URL stays /docs/render/. Two drifts found while building this: - The page passed pageTitle="Overview" while Nav resolved the drawer's title independently and got "Documentation" — the same page named two ways by viewport width. Both now read a shared DOCS_INDEX_TITLE. - e2e asserted getByText('Render'), which passed on a substring of json-render and would now also pass on the sidebar. It asserts card titles instead, and covers the Chat card again. Every new guard was mutation-tested. The naming test initially passed against a reverted docsConfig: getAllByText is exact-match and the picker menu is closed on mount, so it only ever saw the index card. Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
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
1 participant
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.
The bug
The library picker's title and description have been colliding into one line in production:
#892 moved the picker's JSX off Tailwind onto semantic class names but never ported the
flex flex-col..docs-sidebar-lib-item-textcarried onlymin-width: 0, so both spans fell back todisplay: inline. Confirmed against deployed CSS, which serves.docs-sidebar-lib-item-text{min-width:0}.What else this fixes
The picker never got the design pass the rest of the sidebar got in #892. Measured against
main:66, 66, 66, 138, 66, 66, 9052, 52, 39, 39, 39, 39, 39<button>+router.push<a href>— ⌘-click and new-tab workmenuitemmenuitemradio+aria-checkedtaglineon the two adapters only. The five companion libraries are self-describing; a tagline there is the grey noise the current design already suffers from.descriptionis unchanged — it is still the fallback for each page's<meta name="description">viaresolveDocDescription(), so meta descriptions and JSON-LD are byte-identical tomain.vhcap cannot solve the clipping —60vhstill overflows a 600px window by 102px. The cap is measured from the trigger on open and on resize. Verified at 600px: caps to 245px, lands 12px inside the viewport, scrolls internally, last entry reachable.Libraryrow from Environment now the picker owns it.Testing
396 website tests pass, 0 lint errors, production build green.
The notable one is
src/styles/docs-sidebar-styles.spec.ts. jsdom doesn't apply the stylesheet, so no component test could have caught the collision that shipped — this asserts the CSS rules directly. It fails againstmainwithexpected '\n min-width: 0;\n' to match /display:\s*flex/.Also covers: title/tagline as separate elements, labelled groups, anchors with real hrefs,
aria-checked, keyboard traversal across the group boundary, and the measured cap. Three existing tests were updated — two inDocsControlPlane.spec.tsx, andNav.spec.tsx, since the mobile drawer renders the same menu.Design spec:
docs/superpowers/specs/2026-08-31-docs-adapter-picker-design.md.Deliberately out of scope
/docs/choosing-an-adapterrenders without the control plane, so following that link drops you into a page with no nav.lgbreakpoint.Both are real and worth doing; neither is about the picker.
🤖 Generated with Claude Code