Open techfg opened 5 months ago
Thanks for the detailed issue @techfg! I agree, we should improve this.
I think to start with, the table of contents should have a scroll bar respecting user preferences in cases where it overflows. Thatβs important for accessibility.
A scroll listener keeping it in sync could also be an option, but it would be a follow-up/complement to a proper scrollbar, because even if it keeps things in sync, users may want to use the scrollbar to explore the table of contents.
Started experimenting a bit with this.
This is not as easy as removing the scrollbar-width: none;
in the .right-sidebar
class as the width of the fixed element is way larger than the actual right sidebar.
One decision that would also need to be made is the position of this scrollbar. For example, after experimenting with a sticky
approach rather than fixed
, the scrollbar would be on the right side of the screen next to the global page scrollbar (maybe too close?):
I guess another valid approach would be to have the scrollbar closer to the actual table of contents. For example, here the Docusaurus approach:
Not sure if there are any recommendations on this, I'll have to research a bit more.
@HiDeoo - Appreciate you looking in to this, funny, I was working on this last night and had some ideas/questions as well for final implementation π Should have a POC to share some thoughts later today!
@HiDeoo @delucis -
I was able to finish the POC, details below. As @HiDeoo mentions, there are some open questions that would need to be answered prior to finalizing. Apologize in the advance for the lengthy post, lots to cover π
css
expert so if there are better ways to approach this, I'm all earsThe POC is available at https://stackblitz.com/edit/withastro-starlight-5ct6eh.
/reference/example
page initially which has a longer toc
right sidebar
is visibleSelect
list (green
background), use this to toggle across the six (6) style options and see how the right sidebar
style changes. Make sure to scroll the window top to bottom using browser scrollbar and when right sidebar
is visible, scroll top to bottom there as well to see how everything plays togetherGetting Started
in left nav to see a page with a shorter toc
TOC
sidebar stylesoriginal
- This is the current style of Starlight 0.21.5sticky
- TOC is sticky and will scroll with the window, similar to VueJS.sticky scroll scrollbar standard
- TOC contains its own standard styled scrollbar but does not scroll with window, similar to React.dev.sticky scroll scrollbar webkit
- Same as above but using legacy webkit
scrollbar styling which offers more control of styling options (e.g., no top/bottom buttons, different hover color, etc.)sticky scroll listener scrollbar standard
- TOC contains its own scrollbar and will scroll with window, similar to Vercel and nextra.sticky scroll listener scrollbar webkit
- Same as above but using legacy webkit
scrollbar styling which offers more control of styling options (e.g., no top/bottom buttons, different hover color, etc.)TL;DR - Very little. For Style 1, 2, 3 & 4, the only change required was to right-sidebar
css class. For 6 & 7, the only additional change was in starlight-toc.js
to support syncing window scrolling with sidebar scroll position.
Each change made, is annotated in the code with the following:
/* POC Start */
// ...
/* POC End */
The POC has several files from Starlight but only a few were modified from original. In order to make it all work on StackBlitz without grabbing the entire repo, I had to pull in a few files that went unmodified. Here's the breakdown:
./src/components/starlight/TableOfContents/starlight-toc.ts
./src/components/starlight/TableOfContents/TableOfContentsList.astro
./src/components/starlight/MobileTableOfContents.astro
./src/components/starlight/TableOfContents.astro
./src/components/starlight/TwoColumnContent.astro
./src/components/starlight/SidebarStyleSelect.astro
Well, as @HiDeoo mentioned, there are questions to be answered and based on the input from @delucis previously, I wasn't sure where exactly to take this so wanted to gather some input/feedback first π
@delucis had mentioned implementing a scrollbar (POC sticky scroll scrollbar [standard|webkit]
) as a first step for accessibility, however my thoughts were that if we start simple, a sticky (POC sticky
) solution may be preferred as I felt the most common usage would be the window scrolling up/down and when doing so with a separate toc scrollbar
, you can't see the bottom of the toc
. For example, I felt the VueJS experience is preferrable to the React.dev experience. I did some research on accessibility of sidebars and couldn't find anything definitive stated. With that said, w3c's own website uses the sticky
approach without any scrollbar (granted, they don't have long toc's
) as does USWDS. The WCAG spec
, also on the w3c site, however, does use sticky scroll scrollbar
for its left navigation.
style
option to tableOfContents Configuration and let the user choose?
scrollbar
(Option 3, 4, 5, 6 from POC):
toc
) OR;webkit
POC options.
webkit
falling back to standard if not); OR;scroll listener
(Option 4 & 6 from POC), is it OK to take an external dependency (< 1kB) on scroll-into-view-if-needed
or should I roll my own implementation?right sidebar
or much of anything related to straight UI/UX in other tests nor the contributing guide . If just manual testing, what browsers, operating systems, mobile devices, etc. should be tested and is there anything available to support configurations I don't have?sticky scroll listener scrollbar webkit
(Option 6) as it blends everything together, is rather straightforward to implement and consistent with expressive code scrollbars. I think having a new config option would be ideal (and easy enough to implement) but it might be overkill (would be nice though and happy to include it!)webkit
style when availablesticky
(Option 2) to start with since I believe having the toc
move with the window is more desirable than sticky scrollbar scrollbar [standard|webkit]
as described above in background/thoughts section, while still supporting accessibility.@HiDeoo @delucis & others - Look forward to your thoughts/input!
Thanks a lot for your very thorough experimentations and explanations. Definitely way better than my small experiment just adding a sidebar without modifying any behavior or exploring more options. Super appreciated!
I'll try to give my thoughts about the different options and questions you raised, but of course, this is just my opinion and would love to hear more thoughts from others (and also more people experimenting with this).
I am personally in favor, at least to begin with, to not add any option and just fix the initial accessibility issue. Not sure that for this specific case, a lot of customization is required, people could still manually override this if they really want and supporting more than 1 behavior would definitely add a maintenance cost.
i. I personally lean towards the option 3 (sticky scroll scrollbar standard
).
Option 2 (sticky
) is pretty annoying to me when I cannot scroll to the bottom of the right sidebar without scrolling to the bottom of the page.
Option 4 (sticky scroll scrollbar webkit
) feels a bit weird as this would introduce a different scrollbar compared to the left sidebar and the main content.
Option 5 (sticky scroll listener scrollbar standard
) and 6 (sticky scroll listener scrollbar webkit
) feels very distracting to me visually (and I guess this could be toned down but still not sure it's worth it).
I'll still continue to think about this and play more with the amazing playground you provided but if anyone else has any thoughts, please share them!
HI @HiDeoo -
Thanks for the taking the time to review the POC and providing your thoughts, appreciated! Great to have a reference for the supported browsers, thank you!
You raise a very good point about the left sidebar scrollbar, agreed with you that if we end up with a scrollbar on the right sidebar, it should be identical in styling to the left. I do like how Docusaurus has their sidebar scrollbars styled thin
vs standard
as to not consume too much space (since its secondary nav) and also differentiate from the window scrollbar. I think it makes sense to modify the current left sidebar scroll to thin
along with whatever changes we make to right sidebar - thoughts?
Regarding adding a new config option, agreed, not needed - let's pick a single path and implement it, can always add config option in future if there's demand for it and that outweighs the increased maintenance cost.
Based on your input and the above, I updated the POC to provide some additional options and control. Here's the new control panel:
original
- This is the current style of Starlight 0.21.5 (standard browser scrollbar)use scrollbar settings
- Will apply whatever settings are specified in Scrollbar
options columnyes
- Show the filler itemsno
- Hide the filler itemsstandard
- Will use default browser scrollbarprefer webkit
- Will prefer custom style applied via -wekbit-scrollbar-*
if browser supports it, else falls back to standard
default
- browser default scrollbar widththin
- browser thin scrollbar widthoriginal
- This is the current style of Starlight 0.21.5sticky
- TOC is sticky and will scroll with the window, similar to VueJSscollbar
- TOC is sticky with a scrollbarStyle
is scrollbar
, the following applies:
The above changes provide a way to see how things would look if we treat the styling of the right & left sidebar the same, or different along with the different styles of scrollbars. One thing to note is that the webkit styled scrollbars have a hover color applied, forgot to mention that last night.
My preference currently sits:
--sl-sidebar-width
)However, based on the feedback from @HiDeoo & @delucis thus far, I think where things are heading is the following:
thin
scrollbars--sl-sidebar-width
)The changes required for this are very small, only CSS and about 5 lines of it. Given that, and the guidance you provided on browser compatibility & testing, I'll work up an initial PR and we can iterate as needed.
Of course, if anyone else has any input, feel free to share!
Regarding above, after reviewing the code more, I found several places that have scrollbars beyond left & (soon to be) right nav (e.g., dropdowns) so going to shelve the thin
style and stick to standard style to remain consistent. I do think implementing a proper thin
style makes sense but it should be across the board and only on devices that support pointer: fine
so will leave that for a separate PR on its own if there is an appetite from the team to introduce that.
For now, going with:
Look forward to any additional input, thanks!
What version of
starlight
are you using?0.21.5
What version of
astro
are you using?4.6.0
What package manager are you using?
pnpm
What operating system are you using?
Linux
What browser are you using?
Chrome, Edge, FIrefox
Describe the Bug
In desktop mode, the
toc
appears on the right side of the screen. When the number of items in the list exceeds the viewport height, a couple of issues arise:Steps to reproduce:
toc
Expected Result:
toc
should give some visual indication that it separately scrollable; ORtoc
should scroll with the windowActual Result: The
toc
does not move when scrolling, the bottom of thetoc
is not visible and there is no visual clue that it can be scrolled separately.Proposed Solutions:
main-pane
&starlight-toc
always in sync (e.g., https://vercel.com/docs/projects/overview)Link to Minimal Reproducible Example
https://starlight.astro.build/reference/overrides/
Participation