docs: implement on this page expand/collapse with useScrollspy #2679

dwgray · 2025-05-01T23:19:02Z

Describe the PR

This PR gets the on this page table of contents up to parity with the BSV version by driving the OTP off of the scrollspy data rather than the page data.

This is a clean way to get the component reference sub-nodes, which can be important for larger component complexes like BTable
I am using the active node to show sub-nodes in the tree only if they are part of the currently active branch, which makes it easier to see where you are in larger components and migration, where having everything expanded was unwieldy
I can show a single node as active rather than the funky state where the parents of the active node were also being shown

Small replication

docs

PR checklist

What kind of change does this PR introduce? (check at least one)

The PR fulfills these requirements:

Pull request title and all commits follow the Conventional Commits convention or has an override in this pull request body This is very important, as the CHANGELOG is generated from these messages, and determines the next version type. Pull requests that do not follow conventional commits or do not have an override will be denied

Summary by CodeRabbit

New Features
- Enhanced the "On this page" sidebar with a structured, hierarchical navigation of page headers, providing improved overview and navigation for documentation pages.
- Sidebar now highlights the currently active section as you scroll.
Improvements
- Component references in documentation now display as anchorable headings, making it easier to link directly to specific components.
- Sidebar navigation dynamically expands to show nested sections related to the active header.
Refactor
- Improved sidebar navigation logic for better accuracy and maintainability.

bolt-new-by-stackblitz · 2025-05-01T23:19:04Z

Run & review this pull request in StackBlitz Codeflow.

coderabbitai · 2025-05-01T23:19:08Z

Walkthrough

The updates refactor the documentation site's sidebar navigation by introducing hierarchical header structures and explicit active state tracking. New types are defined to support these structures. The sidebar now receives structured header data and the active header ID as props, enabling improved rendering and navigation for nested content, including component references.

Changes

Files	Change Summary
apps/docs/.vitepress/theme/Layout.vue	Enhanced sidebar logic to compute and pass hierarchical header structures (`contents`) and the current active header ID (`active-id`) to `PageContents`. Updated scrollspy logic to support these features.
apps/docs/src/components/ComponentReference.vue	Changed component name rendering from a `<code>` element to an `<h3>` with an anchorable ID for semantic structure and navigation.
apps/docs/src/components/PageContents.vue	Refactored to accept `contents` and `activeId` as props, removing internal page data dependencies and conditional logic. Now renders navigation based on passed-in hierarchical data.
apps/docs/src/components/PageContentsItem.vue	Updated to use `ContentsItem` type, added `activeId` prop, and implemented recursive logic for active state and nested navigation visibility.
apps/docs/src/types/index.ts	Added new type definitions (`ScrollspyItem`, `HeaderItem`, `ContentsItem`) to support hierarchical, typed sidebar content structures.

Sequence Diagram(s)

sequenceDiagram
    participant Layout
    participant useScrollspy
    participant PageContents
    participant PageContentsItem

    Layout->>useScrollspy: Get headers and activeId
    Layout->>Layout: Build hierarchical contents structure
    Layout->>PageContents: Pass contents and activeId as props
    PageContents->>PageContentsItem: Render items recursively with activeId
    PageContentsItem->>PageContentsItem: Check active state and visibility for children

Poem

🐇
In the docs a sidebar grew,
With headers nested, clear and true.
Active links now light the way,
Through components on display.
Types and props now guide the dance—
Hop along, enhance your glance!

Tip

⚡️ Faster reviews with caching

CodeRabbit now supports caching for code and dependencies, helping speed up reviews. This means quicker feedback, reduced wait times, and a smoother review experience overall. Cached data is encrypted and stored securely. This feature will be automatically enabled for all accounts on May 16th. To opt out, configure Review - Disable Cache at either the organization or repository level. If you prefer to disable all data retention across your organization, simply turn off the Data Retention setting under your Organization Settings.

Enjoy the performance boost—your workflow just got faster.

📜 Recent review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 64f29c2 and 8f3d3a2.

📒 Files selected for processing (2)

apps/docs/src/components/PageContents.vue (1 hunks)
apps/docs/src/components/PageContentsItem.vue (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (2)

apps/docs/src/components/PageContents.vue
apps/docs/src/components/PageContentsItem.vue

⏰ Context from checks skipped due to timeout of 90000ms (1)

GitHub Check: build

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

Review comments: Directly reply to a review comment made by CodeRabbit. Example:
- I pushed a fix in commit <commit_id>, please review it.
- Generate unit testing code for this file.
- Open a follow-up GitHub issue for this discussion.
Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
- @coderabbitai generate unit testing code for this file.
- @coderabbitai modularize this function.
PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
- @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
- @coderabbitai read src/utils.ts and generate unit testing code.
- @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
- @coderabbitai help me debug CodeRabbit configuration file.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

@coderabbitai pause to pause the reviews on a PR.
@coderabbitai resume to resume the paused reviews.
@coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
@coderabbitai full review to do a full review from scratch and review all the files again.
@coderabbitai summary to regenerate the summary of the PR.
@coderabbitai generate docstrings to generate docstrings for this PR.
@coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
@coderabbitai resolve resolve all the CodeRabbit review comments.
@coderabbitai configuration to show the current CodeRabbit configuration for the repository.
@coderabbitai help to get help.

Other keywords and placeholders

Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (`.coderabbit.yaml`)

You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
Please see the configuration documentation for more information.
If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

Visit our Documentation for detailed information on how to use CodeRabbit.
Join our Discord Community to get help, request features, and share feedback.
Follow us on X/Twitter for updates and announcements.

pkg-pr-new · 2025-05-01T23:21:25Z

bsvn-vite-ts

npm i https://pkg.pr.new/bootstrap-vue-next/bootstrap-vue-next@2679

npm i https://pkg.pr.new/bootstrap-vue-next/bootstrap-vue-next/@bootstrap-vue-next/nuxt@2679

commit: 8f3d3a2

coderabbitai

Actionable comments posted: 2

🧹 Nitpick comments (1)

apps/docs/.vitepress/theme/Layout.vue (1)
301-311: Guard against non-heading tags and malformed ids

parseInt(tag.replace('H', '')) can return NaN (e.g. if tag === 'H').

Non-heading elements will yield a default level of 3, but their tag is still coerced to 'H0', which is semantically misleading.
-const tag = item.el?.tagName.toUpperCase() ?? 'H0'
-const level = tag.startsWith('H') ? parseInt(tag.replace('H', '')) : 3
+const rawTag = item.el?.tagName?.toUpperCase() ?? ''
+const isHeading = /^H[1-6]$/.test(rawTag)
+const tag = isHeading ? rawTag : 'DIV'
+const level = isHeading ? Number(rawTag.slice(1)) : 3
This avoids NaN levels and keeps the tag consistent with the real element.

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between c1645a9 and eccd099.

📒 Files selected for processing (5)

apps/docs/.vitepress/theme/Layout.vue (4 hunks)
apps/docs/src/components/ComponentReference.vue (1 hunks)
apps/docs/src/components/PageContents.vue (1 hunks)
apps/docs/src/components/PageContentsItem.vue (1 hunks)
apps/docs/src/types/index.ts (2 hunks)

🔇 Additional comments (10)

apps/docs/src/types/index.ts (2)

1-1: Import looks good

The useScrollspy import provides the necessary type information for the scrollspy-related types defined later in this file.

100-102: Well-structured type hierarchy for scrollspy navigation

The type definitions establish a clear hierarchy:

ScrollspyItem provides the base scrollspy data structure

HeaderItem extends it with semantic information (tag and level)

ContentsItem adds recursive structure for hierarchical navigation

This approach provides good type safety while maintaining a clean separation of concerns.

apps/docs/src/components/ComponentReference.vue (1)

13-15: Good semantic improvement for component references

Wrapping the component name in an <h3> with a kebab-cased ID makes these references:

Properly structured in the document outline

Navigable through anchor links

Discoverable by the scrollspy system

This change enables component references to appear in the "On this page" navigation, improving documentation usability.

apps/docs/src/components/PageContents.vue (2)

3-8: Clean prop-driven implementation

The component now renders its children directly from the hierarchical data structure provided via props, replacing previous reliance on global state. This is a significant improvement in component design.

13-15: Proper type definition and props interface

The component now clearly defines its interface with proper TypeScript types:

contents: Optional hierarchical structure of type ContentsItem

activeId: Current active header ID for highlighting

This makes the component more predictable and easier to use.

apps/docs/src/components/PageContentsItem.vue (4)

2-3: Improved active state handling

The NavItem now properly:

Builds links dynamically based on item IDs

Sets the active state by comparing the current item ID with the active ID

Displays the item text correctly

This creates a more responsive and accurate navigation experience.

5-11: Smart recursive visibility logic

Child items are now conditionally displayed based on intelligent visibility logic rather than simply checking if children exist. This implements the expand/collapse behavior requested in the PR objectives.

18-24: Well-defined component interface

The component now has a clear interface with proper TypeScript types:

item: The navigation item of type ContentsItem

activeId: The currently active item ID

This improves component reusability and maintainability.

26-32: Elegant recursive visibility implementation

The implementation includes:

A simple buildLink function for consistent URL generation

A recursive childrenVisible function that properly handles deeply nested structures

A computed property that efficiently determines visibility based on the active state

This handles complex hierarchical navigation structures seamlessly.
apps/docs/.vitepress/theme/Layout.vue (1)

196-210: Verify useScrollspy options – manual: true requires an explicit update()

manual: true disables the library’s internal IntersectionObserver updates; you must now call items.update() (or the exposed update() function) whenever the DOM changes or on route navigation, otherwise the list will be frozen on the first render.

If you intended the default behaviour, simply remove the flag.
-const {current: currentItem, list: items} = useScrollspy(content, target, {
+const {current: currentItem, list: items} = useScrollspy(content, target, {
   contentQuery: ':scope > div > [id], #component-reference, .component-reference h3',
   targetQuery: ':scope [href]',
   rootMargin: '0px 0px -25%',
-  manual: true,
+  // manual: true, // ← uncomment only if you call items.update() yourself
 })
If you keep manual: true, remember to invoke items.update() inside a watchEffect on route.path and after the page content finishes rendering.

apps/docs/.vitepress/theme/Layout.vue

apps/docs/src/components/PageContentsItem.vue

coderabbitai

Actionable comments posted: 0

🧹 Nitpick comments (3)

apps/docs/src/utils/filter-active-id.ts (3)
11-18: Consider adding a null check for item parameter

While the code handles null activeId values, it might be worth adding a guard clause for when item is null/undefined to make the function more robust against potential runtime errors.
export const filteredActiveId = (item: ContentsItem, activeId: string | null): string | null => {
+  if (item === null || item === undefined) {
+    return null;
+  }
  if (activeId === null) {
    return null
  }
  // rest of code...
}
1-1: Consider using a more specific import path

The import path 'src/types' might work in the current context, but for better maintainability, consider using a relative path like '../types' or an absolute path that follows the project's convention.

4-4: Consider a more descriptive function name

While filteredActiveId works, a more descriptive name like findActiveIdInSubtree or isActiveIdInSubtree might better communicate the function's purpose to future developers.

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d82136a and 64f29c2.

📒 Files selected for processing (4)

apps/docs/src/components/PageContents.vue (1 hunks)
apps/docs/src/components/PageContentsItem.vue (1 hunks)
apps/docs/src/utils/filter-active-id.ts (1 hunks)
apps/docs/src/utils/index.ts (1 hunks)

✅ Files skipped from review due to trivial changes (1)

apps/docs/src/utils/index.ts

🚧 Files skipped from review as they are similar to previous changes (2)

apps/docs/src/components/PageContentsItem.vue
apps/docs/src/components/PageContents.vue

🧰 Additional context used

🧬 Code Graph Analysis (1)

apps/docs/src/utils/filter-active-id.ts (2)

apps/docs/src/utils/index.ts (1)

filteredActiveId (8-8)

apps/docs/src/types/index.ts (1)

ContentsItem (102-102)

⏰ Context from checks skipped due to timeout of 90000ms (1)

GitHub Check: build

🔇 Additional comments (1)

apps/docs/src/utils/filter-active-id.ts (1)

3-20: Well-implemented recursive utility function!

This function elegantly traverses the navigation tree to determine if the active ID exists within a subtree. The implementation uses clear recursion with appropriate early returns for handling edge cases.

This approach effectively supports the expand/collapse functionality in the documentation's "on this page" table of contents by determining which branches contain the active section.

This reverts commit 64f29c2.

* upstream/main: chore: release main (bootstrap-vue-next#2690) docs(BProgress): Parity pass (bootstrap-vue-next#2689) fix(BTableSimple): fixed and nobordercollapse to work fixes bootstrap-vue-next#2685 docs: fix incorrect references and missed script sections (bootstrap-vue-next#2686) docs: implement on this page expand/collapse with useScrollspy (bootstrap-vue-next#2679) chore: release main (bootstrap-vue-next#2683) feat(BTable): implement 'fixed' and 'noBorderCollapse' props (bootstrap-vue-next#2681) chore: release main (bootstrap-vue-next#2678) Update package.json fix(BFormSelect): prevent options with label from being treated as groups (bootstrap-vue-next#2666) fix: patch regression issue in bootstrap-vue-next#2665 (bootstrap-vue-next#2670) Update release-main.yaml chore: release main (bootstrap-vue-next#2660) chore: update depencies fix(BTabs): corrent classes on ssr (bootstrap-vue-next#2664) Changes to public composables (bootstrap-vue-next#2425) docs(BTable): parity pass (bootstrap-vue-next#2669)

…trap-vue-next#2679)

commit 2a9e30b Author: Jukka Raimovaara <roska@mentalhouse.fi> Date: Thu May 15 18:24:07 2025 +0300 doc data commit 08c89fd Author: Jukka Raimovaara <roska@mentalhouse.fi> Date: Thu May 15 17:57:29 2025 +0300 feat(BPopover): add titleClass and bodyClass, remove unneeded customClass prop since class is inherited to the same place commit 90b578d Author: Jukka Raimovaara <roska@mentalhouse.fi> Date: Wed May 14 11:39:42 2025 +0300 feat(BToast): add noProgress prop, make progress show as default if modelValue is number. fix(useToastController): if using the deprecated show method the countdown didn't start. commit dc85d94 Author: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Date: Sun May 11 09:53:25 2025 -0500 chore: release main (bootstrap-vue-next#2690) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> commit 070cb8c Author: David W. Gray <dwgray67@hotmail.com> Date: Sun May 11 07:52:30 2025 -0700 docs(BProgress): Parity pass (bootstrap-vue-next#2689) commit c61f532 Author: Thierry Blind <tbl0605@gmail.com> Date: Sun May 11 16:52:14 2025 +0200 fix(BTableSimple): fixed and nobordercollapse to work fixes bootstrap-vue-next#2685 commit beae36f Author: David W. Gray <dwgray67@hotmail.com> Date: Sun May 11 07:43:58 2025 -0700 docs: fix incorrect references and missed script sections (bootstrap-vue-next#2686) commit 34432d9 Author: David W. Gray <dwgray67@hotmail.com> Date: Sun May 11 07:42:02 2025 -0700 docs: implement on this page expand/collapse with useScrollspy (bootstrap-vue-next#2679) commit ce869f0 Author: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed May 7 11:16:08 2025 -0500 chore: release main (bootstrap-vue-next#2683) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> commit 9486276 Author: Mohamed Nasri <51300752+mhn147@users.noreply.github.com> Date: Wed May 7 09:44:38 2025 -0600 feat(BTable): implement 'fixed' and 'noBorderCollapse' props (bootstrap-vue-next#2681) commit a4a9294 Author: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Date: Mon May 5 09:16:09 2025 -0500 chore: release main (bootstrap-vue-next#2678) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> commit 0165e94 Author: Jukka Raimovaara <roska@mentalhouse.fi> Date: Mon May 5 16:24:04 2025 +0300 Update package.json commit c1645a9 Author: Rajitha <rajithaeye@gmail.com> Date: Wed Apr 30 23:49:23 2025 +0530 fix(BFormSelect): prevent options with label from being treated as groups (bootstrap-vue-next#2666) commit 59ddc39 Author: Thierry Blind <tbl0605@gmail.com> Date: Wed Apr 30 20:17:34 2025 +0200 fix: patch regression issue in bootstrap-vue-next#2665 (bootstrap-vue-next#2670) commit d82091b Author: Jukka Raimovaara <roska@mentalhouse.fi> Date: Wed Apr 30 06:01:10 2025 +0300 Update release-main.yaml commit 31cb4bf Author: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed Apr 30 04:51:31 2025 +0300 chore: release main (bootstrap-vue-next#2660) Co-Authored-By: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> commit 6733770 Author: Jukka Raimovaara <roska@mentalhouse.fi> Date: Wed Apr 30 05:15:02 2025 +0300 chore: update depencies commit 2b37c18 Author: Jukka Raimovaara <roska@mentalhouse.fi> Date: Wed Apr 30 04:36:46 2025 +0300 fix(BTabs): corrent classes on ssr (bootstrap-vue-next#2664) fix(BTabs): corrent classes on ssr fix(BTabs): fix another recursion error commit 99718eb Author: Jukka Raimovaara <roska@mentalhouse.fi> Date: Wed Apr 30 04:20:00 2025 +0300 Changes to public composables (bootstrap-vue-next#2425) feat(BAlert)!: make act like toast, useShowHide. feat(useShowHide): create triggerRegistry for adding external triggers (like in vBToggle) fix: type popoverController fix(useShowHide): focustrap off at the begining of leave, pass down the trigger to other hide emits. fix(vBToggle): keep track of targets fix(BPopover)!: change prop content to body to align with other components fix(BTooltip)!: change prop content to body to align with other components feat(usePopoverController): allow more options fix(vBToggle): find late components, ie. inside ClientOnly fix(useModalController)!: move props to main level, add slots feat(usePopoverController): add slots feat(useToastController)!: remove props obj, the parameters are flat now. Add slots, rename pos -> position feat(useShowHide): show returns a promise, resolve on show or hide. feat(useToggle): toggle any show/hide component feat!: controller composables functions return promise, with chainable functions feat(useModalController): add support for using syntax in ts feat(BModal): add okClass and cancelClass to add classes to the buttons. feat(useModalController)!: change of api, check the docs fix: inline functional style to show toast,modal and dropdown feat(useToggle): add trigger to promise resolve on hide. fix(BCarousel): fix v-for updates commit 340edfd Author: David W. Gray <dwgray67@hotmail.com> Date: Mon Apr 28 18:39:44 2025 -0700 docs(BTable): parity pass (bootstrap-vue-next#2669) commit 4dd6c89 Author: Jukka Raimovaara <roska@mentalhouse.fi> Date: Mon Apr 28 22:46:31 2025 +0300 fix(BDropdown): don't calulcate the position when dropdown is not shown.

docs: implement otp expand/collapse with useScrollspy

8c5855b

dwgray added 2 commits May 1, 2025 16:24

docs: implement otp expand/collapse with useScrollspy

3baa7c9

docs: clean up contents building computed

eccd099

dwgray marked this pull request as ready for review May 1, 2025 23:30

coderabbitai bot reviewed May 1, 2025

View reviewed changes

apps/docs/.vitepress/theme/Layout.vue Outdated Show resolved Hide resolved

apps/docs/.vitepress/theme/Layout.vue Show resolved Hide resolved

dwgray added 2 commits May 1, 2025 16:38

docs: change currentItem to activeId to make avoid confusion

9a177f8

docs: make tag parsing slightly more robust

d82136a

VividLemon requested changes May 7, 2025

View reviewed changes

apps/docs/src/components/PageContentsItem.vue Show resolved Hide resolved

docs: improve stability of props in otp contents tree

64f29c2

coderabbitai bot reviewed May 7, 2025

View reviewed changes

Revert "docs: improve stability of props in otp contents tree"

8f3d3a2

This reverts commit 64f29c2.

VividLemon merged commit 34432d9 into bootstrap-vue-next:main May 11, 2025
5 checks passed

xvaara pushed a commit to unstoppablecarl/bootstrap-vue-next that referenced this pull request May 22, 2025

docs: implement on this page expand/collapse with useScrollspy (boots…

a681e20

…trap-vue-next#2679)

coderabbitai bot mentioned this pull request May 22, 2025

fix(scss) moved all scss styles out of components #2671

Merged

6 tasks

coderabbitai bot mentioned this pull request Jun 9, 2025

docs: fix on-this-page for composable and directives pages #2742

Merged

6 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

docs: implement on this page expand/collapse with useScrollspy #2679

docs: implement on this page expand/collapse with useScrollspy #2679

Uh oh!

Uh oh!

Uh oh!

Chat

Support

CodeRabbit Commands (Invoked using PR comments)

Other keywords and placeholders

CodeRabbit Configuration File (`.coderabbit.yaml`)

Documentation and Community

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

docs: implement on this page expand/collapse with useScrollspy #2679

docs: implement on this page expand/collapse with useScrollspy #2679

Uh oh!

Conversation

Uh oh!

Describe the PR

Small replication

PR checklist

Summary by CodeRabbit

Uh oh!

Uh oh!

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Poem

Chat

Support

CodeRabbit Commands (Invoked using PR comments)

Other keywords and placeholders

CodeRabbit Configuration File (.coderabbit.yaml)

Documentation and Community

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

CodeRabbit Configuration File (`.coderabbit.yaml`)