10000 docs: implement on this page expand/collapse with useScrollspy by dwgray · Pull Request #2679 · bootstrap-vue-next/bootstrap-vue-next · GitHub
[go: up one dir, main page]

Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
May 11, 2025

Conversation

dwgray
Copy link
Member
@dwgray dwgray commented May 1, 2025

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)

  • Bugfix 🐛 - fix(...)
  • Feature - feat(...)
  • ARIA accessibility - fix(...)
  • Documentation update - docs(...)
  • Other (please describe)

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

      < 8000 li>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.

Copy link

Review PR in StackBlitz Codeflow Run & review this pull request in StackBlitz Codeflow.

Copy link
coderabbitai bot commented May 1, 2025

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
Loading

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.

Copy link
pkg-pr-new bot commented May 1, 2025

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

@dwgray dwgray marked this pull request as ready for review May 1, 2025 23:30
Copy link
@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🧹 Nitpick comments (1)
apps/docs/.vitepress/theme/Layout.vue (1)

301-311: Guard against non-heading tags and malformed ids

  1. parseInt(tag.replace('H', '')) can return NaN (e.g. if tag === 'H').
  2. 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:

  1. ScrollspyItem provides the base scrollspy data structure
  2. HeaderItem extends it with semantic information (tag and level)
  3. 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:

  1. Properly structured in the document outline
  2. Navigable through anchor links
  3. 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.

Copy link
@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@VividLemon VividLemon merged commit 34432d9 into bootstrap-vue-next:main May 11, 2025
5 checks passed
xvaara added a commit to xvaara/bootstrap-vue-next that referenced this pull request May 14, 2025
* 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)
xvaara pushed a commit to unstoppablecarl/bootstrap-vue-next that referenced this pull request May 22, 2025
xvaara added a commit to unstoppablecarl/bootstrap-vue-next that referenced this pull request May 22, 2025
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants
0