prototype: responsive TOC redesign (Panel vs Drawer)

[lboehling]

Summary

• WIP prototype for design/dev feedback — not intended to merge as-is.
• Responsive TOC behaviors by breakpoint:
  • ≥1450px: existing sidebar JumpLinks
  • 992–1449px: MenuToggle in sticky tabs
  • <992px: floating MenuToggle (below tabs, or fixed on overview pages)
• Bottom-left TOC surface switcher to compare Panel (raised + Popper) vs pill overlay Drawer (PF defaults for width/min-width; full-bleed overlay under 768px).
• Choice persists in localStorage (ws-toc-surface).

Preview / review notes

• Use the fixed TOC surface control (bottom-left) to switch Panel vs Drawer.
• Hard refresh if HMR misses CSS.
• Figma: https://www.figma.com/design/Q6aimf2M8cfoA3C7aOnlgD/pf.org---Responsive-TOC-redesign?node-id=123-526

Test plan

• Component page with tabs (e.g. Accordion): Lg toggle in tabs; Md floating toggle; XL+ sidebar unchanged
• Overview / no-tabs page: fixed toggle placement vs Give feedback; no horizontal jump on scroll
• Drawer surface: opens with PF default width; md inset top/bottom/end; <768px full page-main overlay
• Drawer closed: no blank gutter; sticky tabs still stick
• Panel surface still works as before
• Surface choice survives reload

Made with Cursor

[lboehling]

added another prototype vid of panel vs drawer in the figma file since i'm having a hard time troubleshooting the pre preview build failure.

https://www.figma.com/design/Q6aimf2M8cfoA3C7aOnlgD/pf.org---Responsive-TOC-redesign?node-id=196-521&t=YVGqIH88HIEXZgJ7-4

[thatblindgeye]

Some general comments, either stuff wew should resolve in a final implementation or just stuff to look out for:

• For a non-tabbed page (components > Overview), shrinking the viewport down the ToC toggle is misaligned a bit, until I juuuuust barely scroll a teensy bit then it jumps into a more "correct" position:
  
• For the drawer approach, we'd just need to adjust how it's rendered a bit, right now some of the drawer gets cutoff for me
• Not sure if it's more just the example approach for the purposes of this PR or if there'd be an issue in final implementation, but when I'm at 125% zoom in Chrome, that triggers the ToC to be inside the toggle (vs a sidebar at 100% zoom), but the ToC changer in the bottom left doesnt render until I shrink my viewport down. I assume it's just a minor thing with how the changer is being rendered, but maybe something to look out for in final implementation
• With either approach, we'd need to shift focus into the ToC nav items when opening and shift focus back to the toggle button when closing (unless clicking a ToC item, then we'd want to set focus on the heading that was clicked). Right now via keyboard there's no way to actually get into the ToC at smaller viewports unless you Tab through the entire page

Personally, I think I lean slightly more towards the Popper/Dropdown approach vs the drawer. For some reason it feels a little "off" for me that the ToC would cover pretty much the entire screen when open at a certain width and lower, when the main navigation doesn't really do that. Probably a super nitpicky thing, though.

[thatblindgeye]

Not 100% if it'll resolve the issue, but you could try updating this line to:

Suggested change

	typeof document !== 'undefined' ? document.getElementById('ws-toc-menu-slot') : null;
	typeof document !== 'undefined' ? document.getElementById?.('ws-toc-menu-slot') ?? null;

[lboehling]

Some general comments, either stuff wew should resolve in a final implementation or just stuff to look out for:

• For a non-tabbed page (components > Overview), shrinking the viewport down the ToC toggle is misaligned a bit, until I juuuuust barely scroll a teensy bit then it jumps into a more "correct" position:
  
• For the drawer approach, we'd just need to adjust how it's rendered a bit, right now some of the drawer gets cutoff for me
• Not sure if it's more just the example approach for the purposes of this PR or if there'd be an issue in final implementation, but when I'm at 125% zoom in Chrome, that triggers the ToC to be inside the toggle (vs a sidebar at 100% zoom), but the ToC changer in the bottom left doesnt render until I shrink my viewport down. I assume it's just a minor thing with how the changer is being rendered, but maybe something to look out for in final implementation
• With either approach, we'd need to shift focus into the ToC nav items when opening and shift focus back to the toggle button when closing (unless clicking a ToC item, then we'd want to set focus on the heading that was clicked). Right now via keyboard there's no way to actually get into the ToC at smaller viewports unless you Tab through the entire page

Personally, I think I lean slightly more towards the Popper/Dropdown approach vs the drawer. For some reason it feels a little "off" for me that the ToC would cover pretty much the entire screen when open at a certain width and lower, when the main navigation doesn't really do that. Probably a super nitpicky thing, though.

Thanks for the feedback and comments, @thatblindgeye ! This PR is definitely not proposed code (just trying to get a somewhat close prototype of the behavior) so agree this should be fine tuned for implementation. After reviewing with the design we also decided that the popper/floating panel was the preferred approach. I shall open a follow up issue to let the experts put together the actual implementation :)