Feat: Add sidebar state persistence

[kitschpatrol]

Description

• Closes Preserve navigation scroll position/toggle state on page change #971
• Sidebar now persists its scroll position and expanded / contracted section state across page navigations. It also scrolls the active sidebar item into view if necessary.

Builds on an initial implementation by @duncanwerner.

I grabbed the most salient bits of the issue thread below:

Feature criteria

• Respect the default "collapsed" state of the sidebar specified by SidebarItem config on first page navigations.
• Retain user's sidebar scroll position across page navigations.
• Retain user's sidebar sub-section detail expand / collapsed states across page navigations.
• Expand all ancestor detail elements of the active item (regardless of user's sidebar state changes).
• Ensure that the active item is visible after a page navigation (regardless of user's sidebar state changes).
• No Flash of Un-Scrolled Content (FLOUSC).

Possible improvements

• Track the initial expand / collapse state (from SidebarItem config) on first load before sessionStorage is set, and then apply this as the default if users don't actively change expand / collapse state of sections. (For example, the page is defined with all sections collapsed, the user navigates through several sections using the "next" buttons, this would collapse sections in the sidebar behind them once they're out of that section.)
• Maybe consider an intersection observer instead getBoundingClientRect() to determine if scrolling the sidebar is necessary. (Note that trusting scrollIntoView() on its own without checking bounds first can result in unnecessary scrolling.)
• Allow some padding when auto-scrolling a sidebar item into view. Currently, the sidebar scrolls the minimum amount necessary, leaving the item right on the edge of the scroll area.

Still to do

• Check implications of possible view transitions feature.
• Check implications of possible multiple sidebar feature.
• Strip comments. (I left these in to clarify any discussion around the PR, I assume we'll want to strip these since inline scripts aren't processed.)
• Verify that JS used meets browserlist criteria.

[changeset-bot]

🦋 Changeset detected

Latest commit: 7a96a92

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@astrojs/starlight	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
starlight	✅ Ready (Inspect)	Visit Preview	Mar 14, 2024 4:15pm

[astrobot-houston]

Hello! Thank you for opening your first PR to Starlight! ✨

Here’s what will happen next:

1. Our GitHub bots will run to check your changes.
   If they spot any issues you will see some error messages on this PR.
   Don’t hesitate to ask any questions if you’re not sure what these mean!

2. In a few minutes, you’ll be able to see a preview of your changes on Vercel 🤩

3. One or more of our maintainers will take a look and may ask you to make changes.
   We try to be responsive, but don’t worry if this takes a few days.

[delucis]

Hey @kitschpatrol! Sorry for the extremely long wait for a response here. Are you still interested in working on this PR or would you like me to take over? Looking into this functionality now and would have some feedback/suggestions if you’re interested!

[kitschpatrol]

Hey! No worries on the delay. I'm happy to work on it and of course would want any and all feedback and suggestions — but unfortunately time-wise I would have to delay picking it back up for a few weeks (Feb 26th), so no issues at all if you would rather take it over and get it released more quickly. 👍

[delucis]

Thanks — good to know! In that case, I’ll try to at least leave a round of feedback out of politeness, and if I have the chance before you do to address that, I’ll be happy to jump in 🙌

[kitschpatrol]

Hey @delucis, I'm back online. 👋

Happy to dig back into this PR if you have bandwidth for feedback.

[bdenham]

@delucis, @kitschpatrol: I'd love to see this get merged soon if it's ready. I added the fix to one of my sites and had to override several files 😅:

• Sidebar.astro
• SidebarSublist.astro
• navigation.ts
• schemas/badge.ts
• schemas/prevNextLink.ts
• schemas/sidebar.ts
• createPathFormatter.ts
• format-path.ts
• i18n.ts
• path.ts
• routing.ts
• slug.ts
• base.ts
• validateLogoImports.ts

Let me know if I can help. Thanks.

[kitschpatrol]

Hi @bdenham, yes I'm definitely standing by to respond to any feedback from the maintainers to keep this moving! (I think they're having a busy week. 😅)

And hmm can you give any more info on all the overrides you said you needed? I just merged up this PR with main and it seems to still be working fine without additional changes / overrides?

[bdenham]

No, your PR is fine. I'm referring to what you need to do right now, outside the Starlight codebase. That is, when you're just using the Starlight integration in your site. The dependencies stack up when you need to override the sidebar from the outside to add the change you're committing to the sidebar on the inside. :)

[delucis]

Thanks again for this PR and your patience on this feature. In the end we realised there were quite a few additional considerations that meant we wanted to do this differently, so ended up implementing a separate approach in #2150. Nevertheless, appreciate you getting the ball rolling! The new feature will be available in v0.26 releasing later today 🚀