New addons UI: top-center bar with panel-based navigation#688
Draft
ericholscher wants to merge 28 commits into
Draft
New addons UI: top-center bar with panel-based navigation#688ericholscher wants to merge 28 commits into
ericholscher wants to merge 28 commits into
Conversation
…gration Adds the foundation for integrating search and file tree diff as panels inside the flyout menu, replacing the need for separate modals and floating elements. This creates the base architecture for the new addons UI (#574). New components: - SearchPanelElement: inline search with API integration for the flyout - FileTreeDiffPanelElement: inline changed files list with diff toggle Flyout changes: - Panel switching via icon buttons in the header - activePanel state to toggle between default content and panel content - EVENT_READTHEDOCS_FLYOUT_PANEL_SET event for programmatic panel control - Panel icons shown conditionally based on addon enabled state https://claude.ai/code/session_01GS43pv3hBjSE8BBLnyCSTE
Transforms the flyout from a bottom-right dropdown widget into a top-center horizontal bar matching the new addons UI design (#574). Key changes: - Position defaults to top-center instead of bottom-right - Header is a horizontal bar: [panel icons] [logo] [lang badge] [version badge] [caret] - Version and language badges are clickable panel selectors - Versions and languages render as dedicated panels (not inline dl/dt/dd sections) - Panel icons on the left for search and file tree diff - Individual click handlers instead of whole-header toggle - Old search input removed from default content (replaced by search panel) - Default content shows Downloads, RTD links, VCS only - Wider max-width (40em) for horizontal bar layout - Legacy position classes kept for backward compatibility https://claude.ai/code/session_01GS43pv3hBjSE8BBLnyCSTE
- Use wordmark logo consistently instead of swapping between icon and wordmark on open/close (the old behavior was for the bottom-right widget, not the new top bar) - Re-clicking the same panel badge now closes the flyout entirely instead of showing default content - Remove unused READTHEDOCS_LOGO import and readthedocsLogo property https://claude.ai/code/session_01GS43pv3hBjSE8BBLnyCSTE
- Use width: max-content so the bar expands to fit all header elements - Remove overflow-y: auto from container and :host > div which was clipping content on the sides - Move overflow-y: auto to just the main panel area (max-height: 60vh) so only panel content scrolls, not the entire widget https://claude.ai/code/session_01GS43pv3hBjSE8BBLnyCSTE
Use left:0/right:0 with auto margins and fit-content width for centering instead of transform: translateX(-50%). This ensures the container properly sizes to its content and the background color covers the full bar width. https://claude.ai/code/session_01GS43pv3hBjSE8BBLnyCSTE
The SVG logo has no explicit width/height attributes (only viewBox), so with max-height + width:auto the browser computed 0px intrinsic width for the image during max-content sizing. This made the container ~100px too narrow, causing version badge and caret to overflow outside the dark background. Fixes: - Use height (not max-height) on logo so the browser can resolve the SVG aspect ratio during intrinsic sizing - Use flex: 0 0 auto on logo (no shrink) to prevent it collapsing - Make container display:flex/column so it sizes from widest child - Use transform centering (simpler than left:0/right:0/fit-content) https://claude.ai/code/session_01GS43pv3hBjSE8BBLnyCSTE
- Remove the caret toggle and default content panel. The flyout only opens when a specific panel (search, versions, languages, filediff) is selected. No more ambiguous "default" content state. - Logo is now an <a> linking to the project home page instead of a toggle button. Users don't expect clicking a logo to open a dropdown. - Fold Downloads, RTD links, and VCS link into a compact footer that appears below every panel: Project Home · Builds · PDF · View source - Remove _toggleOpen, renderDefaultContent, renderDownloads, renderReadTheDocs, renderVCS, and unused faCaretDown import - Remove dl/dt/dd styles (no longer used) - Remove <hr> separator (footer has its own border-top) https://claude.ai/code/session_01GS43pv3hBjSE8BBLnyCSTE
ericholscher
force-pushed
the
claude/addon-ui-base-SS5M9
branch
from
f13dfb2 to
fc8e3b6
Compare
ericholscher
changed the title
- Add downloads as an icon panel in the header (faDownload icon), matching the same pattern as versions/languages - Logo is now a plain span (branding only), not a link that navigates away from the page - Footer simplified to just "Hosted by Read the Docs" - compact branding that doesn't blow out the panel width - Remove Project Home/Builds/View source from footer (logo was already linking to project home; these are secondary links) https://claude.ai/code/session_01GS43pv3hBjSE8BBLnyCSTE
Move version and language selectors into the nav.panel-icons as regular icon buttons with text labels, matching search/downloads/ filediff. Two nav groups flank the logo: left side has tool panels (search, filediff, downloads), right side has selector panels (language, version). Remove the separate button.badge CSS entirely. Also removes committed screenshot files from docs/screenshots/. https://claude.ai/code/session_01GS43pv3hBjSE8BBLnyCSTE
Main area now checks both opened and activePanel before displaying, so external FLYOUT_SHOW events don't show a bare footer with no panel content above it. https://claude.ai/code/session_01GS43pv3hBjSE8BBLnyCSTE
- Remove wordmark logo from header bar - all header elements are now icons in a single nav: [search] [filediff] [downloads] [lang] [version] - Move RTD logo branding to footer, matching the search modal pattern: "Hosted by [Read the Docs logo]" - Fix filetreediff-panel URL handling: use window.location.origin as base for new URL() to handle relative paths from the API - Fix current-page detection to compare pathnames instead of full URLs - Remove unused _getCurrentPageUrl method https://claude.ai/code/session_01GS43pv3hBjSE8BBLnyCSTE
Rewrite all flyout tests to match the new structure: - Test versions/languages/downloads panels instead of dl/dt/dd sections - Test icon button rendering in header nav - Test footer branding with logo image - Test panel closed by default, search disabled hides icon - Keep resolver filename tests (now open versions panel first) - Clear old snapshots (will auto-regenerate on first run) https://claude.ai/code/session_01GS43pv3hBjSE8BBLnyCSTE
CSS fixes (search-panel.css, filetreediff-panel.css): - Wrap all CSS variable definitions in @layer defaults { :root {} } to match every other CSS file in the project - Replace all hardcoded colors with CSS variables following the --readthedocs-{component}-{property} naming convention - Variables fall back to flyout variables where appropriate so panel theming inherits from the flyout JS fix (flyout.js): - Move FontAwesome library.add() and icon() calls from renderHeader() to constructor, matching the pattern in search.js, notification.js, and filetreediff.js where icons are created once https://claude.ai/code/session_01GS43pv3hBjSE8BBLnyCSTE
…e testing Creates flyout-v2.js/css as a separate component (readthedocs-flyout-v2) that can run alongside the original flyout. Toggle with URL parameter: ?readthedocs-flyout-v2=true When v2 is active, the original flyout is automatically disabled. When the param is absent, the original flyout works as before. Changes: - Restore original flyout.js/css from main (untouched) - Add isEnabled guard to original flyout: skip when v2 param is set - Create flyout-v2.js: FlyoutV2Element/FlyoutV2Addon with its own element name, isEnabled check for the URL param - Register FlyoutV2Addon in application.js addon list - Restore original flyout tests and snapshots from main https://claude.ai/code/session_01GS43pv3hBjSE8BBLnyCSTE
…anding Footer now has three elements: - Left: house icon (project home link) + external link icon (view source, if VCS configured) - Right: subtle RTD logo linking to readthedocs.com (50% opacity, no text) Replaces "Hosted by [RTD wordmark]" with a cleaner layout that puts useful links in the footer without taking up much space. https://claude.ai/code/session_01GS43pv3hBjSE8BBLnyCSTE
- Remove unused imports: ajv, render (from lit), SPHINX, MKDOCS_MATERIAL, EVENT_READTHEDOCS_SEARCH_SHOW - Remove showSearch() method which dispatched to the old search modal. In v2, search is an inline panel — this method was never called. https://claude.ai/code/session_01GS43pv3hBjSE8BBLnyCSTE
flyout-v2.js: - Cache config-derived flags (searchEnabled, hasVersions, etc.) in loadConfig() instead of recomputing on every render - Replace 5 inline arrow functions in template with bound class properties created in constructor (avoids Lit re-render churn) - Remove redundant comments that echo the code search-panel.js: - Change updated() to firstUpdated() so focus only fires on mount, not on every re-render (e.g. when results arrive) - Cache icon objects (_iconSpinner, _iconMagnifier, _iconListResult) in constructor instead of recreating on every fetch/render https://claude.ai/code/session_01GS43pv3hBjSE8BBLnyCSTE
humitos
reviewed
Apr 16, 2026
Member
humitos
left a comment
humitos
left a comment
There was a problem hiding this comment.
I pull this PR down and I tested it locally to feel the UX by myself. I also took a look at the code and I can say the JS code is probably pretty close to what I could write by myself, so in that regard is 👍🏼 There isn't anything new here and it seems it follows the patterns we have established.
On the other hand, the CSS is code is where I'm not able to evaluate this PR --and there is a ton of it because it's the most important part of what we want to build for the new addons UI.
That said, we are not covering what we designed here. Mainly the hamburger menu with the buttons and panes. Those buttons should make the whole UI to switch to that particular feature as shown in the video we have in the issue.
I'm not sure how much we can guide the AI to move in that direction, but it would be awesome if we can make the AI to build the HTML/CSS we've designed together in the offsite since the JS is pretty close to what we need I'd say --I mean, I would feel comfortable updating the JS code by myself with any required tweak, but not the HTML/CSS.
Addresses humitos' feedback that the design should be a hamburger menu with buttons and panes that switch the whole UI to each feature, as shown in the original mockups - not a compact toolbar with dropdowns. Layout changes: - Collapsed state: small hamburger button (bars icon) - Expanded state: left icon sidebar + right pane area - Each icon switches the WHOLE pane to that feature - Default pane is a "menu" view showing project info (logo, project, version, language, project home and VCS links) - Each pane has its own header (title + close button) and content area - Compact RTD branding in pane footer Other changes: - Register flyout-v2.css + panel CSS files in defaults.js so their :root variables get adopted at the document level. Without this, CSS variables weren't resolving and the dark theme didn't apply. - Panel name constants (PANEL_MENU, PANEL_SEARCH, etc) for clarity - Remove duplicate "Changed Files" header inside filetreediff-panel (pane header now provides the title) https://claude.ai/code/session_01GS43pv3hBjSE8BBLnyCSTE
The sidebar icon column is always visible, showing available features and current version/language at a glance. Clicking any icon expands the pane to the right; clicking the same icon again collapses back to sidebar-only. Removes the hamburger-only collapsed state. Fixes #574 https://claude.ai/code/session_01GS43pv3hBjSE8BBLnyCSTE
The collapsed state is a horizontal bar (like the original flyout) showing icon buttons on the left and RTD logo + version/language badges on the right. Clicking any icon opens its pane BELOW the bar. Clicking the same icon or the close button collapses back to just the bar. This matches the "minimized version" sketch from #574: [≡] [🔍] [📄] [⬇] Read the Docs [🌐 en] [⎇ latest] https://claude.ai/code/session_01GS43pv3hBjSE8BBLnyCSTE
Three states matching the sketches from #574: 1. Bar: hamburger on left + minimized active addon on right - Menu: [≡] Read the Docs [🌐 en] [⎇ latest] - Search: [≡] [🔍] Search docs - Filediff: [≡] [📄] Changed files - Versions: [≡] [⎇] latest 2. Hover hamburger: dropdown of addon icons appears below to switch 3. Click bar content: pane expands below with full detail + footer Each addon has its own minimized inline bar representation AND expanded pane content. The hamburger is just for switching between them. https://claude.ai/code/session_01GS43pv3hBjSE8BBLnyCSTE
Icons only exist in the hamburger dropdown for switching. The bar shows just the active addon's icon + its minimized content. Menu bar shows plain text badges for lang/version without icons. https://claude.ai/code/session_01GS43pv3hBjSE8BBLnyCSTE
The flyout is now a single horizontal bar that shows the active addon's UI inline. No pane expansion — the bar content switches entirely based on which addon is selected via the hamburger. - Menu (default): RTD logo + language dropdown + version dropdown - Search: inline search input - Filediff: show diff toggle + file list - Config: settings placeholder for future config options Version and language are native <select> dropdowns in the menu bar that navigate directly on change. Fixes #574 https://claude.ai/code/session_01GS43pv3hBjSE8BBLnyCSTE
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
3 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.
Summary
New addons UI redesign base. See #574 for design mockups and video.
Toggle:
?readthedocs-flyout-v2=trueDesign
The flyout is a single horizontal bar that shows the active addon's UI inline. No expanded pane — the bar switches content based on which addon is selected via the hamburger.
Menu (default) — version & language dropdowns
Hamburger — switch between addons
Search — inline input
File diff — inline controls
Settings — config placeholder
Files
src/flyout-v2.js/csssrc/search-panel.js/csssrc/filetreediff-panel.js/csssrc/defaults.jssrc/flyout.jshttps://claude.ai/code/session_01GS43pv3hBjSE8BBLnyCSTE