-
-
Notifications
You must be signed in to change notification settings - Fork 151
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
Conversation
|
WalkthroughThe 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
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
Tip ⚡️ Faster reviews with caching
Enjoy the performance boost—your workflow just got faster. 📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (2)
🚧 Files skipped from review as they are similar to previous changes (2)
⏰ Context from checks skipped due to timeout of 90000ms (1)
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. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed 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)
Other keywords and placeholders
CodeRabbit Configuration File (
|
commit: |
There was a problem hiding this 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
parseInt(tag.replace('H', ''))
can returnNaN
(e.g. iftag === '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)) : 3This avoids
NaN
levels and keeps thetag
consistent with the real element.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 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 goodThe
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 navigationThe type definitions establish a clear hierarchy:
ScrollspyItem
provides the base scrollspy data structureHeaderItem
extends it with semantic information (tag and level)ContentsItem
adds recursive structure for hierarchical navigationThis 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 referencesWrapping 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 implementationThe 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 interfaceThe component now clearly defines its interface with proper TypeScript types:
contents
: Optional hierarchical structure of typeContentsItem
activeId
: Current active header ID for highlightingThis makes the component more predictable and easier to use.
apps/docs/src/components/PageContentsItem.vue (4)
2-3
: Improved active state handlingThe 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 logicChild 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 interfaceThe component now has a clear interface with proper TypeScript types:
item
: The navigation item of typeContentsItem
activeId
: The currently active item IDThis improves component reusability and maintainability.
26-32
: Elegant recursive visibility implementationThe 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
: VerifyuseScrollspy
options –manual: true
requires an explicitupdate()
manual: true
disables the library’s internalIntersectionObserver
updates; you must now callitems.update()
(or the exposedupdate()
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 invokeitems.update()
inside awatchEffect
onroute.path
and after the page content finishes rendering.
There was a problem hiding this 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 parameterWhile the code handles null
activeId
values, it might be worth adding a guard clause for whenitem
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 pathThe 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 nameWhile
filteredActiveId
works, a more descriptive name likefindActiveIdInSubtree
orisActiveIdInSubtree
might better communicate the function's purpose to future developers.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 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)
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.
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.
Small replication
docs
PR checklist
What kind of change does this PR introduce? (check at least one)
fix(...)
feat(...)
fix(...)
docs(...)
The PR fulfills these requirements:
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 deniedSummary by CodeRabbit
New Features
Improvements
< 8000 li>Component references in documentation now display as anchorable headings, making it easier to link directly to specific components.
Refactor