feat(api-reference): virtualized operations #7210

geoffgscott · 2025-10-30T20:05:42Z

Problem

When there is very large tags open we have too many DOM elements to handle elegantly.

Solution

Virtualizes operations with a fixed estimated height and a fairly long render window.

Checklist

I've gone through the following:

I've added an explanation why this change is needed.
I've added a changeset (pnpm changeset).
I've added tests for the regression or new feature.
I've updated the documentation.

Note

Lazily renders Operation.vue using a new useVirtual hook that shows a placeholder height and mounts content only when in view.

API Reference
- Operation virtualization:
  - features/Operation/Operation.vue: wraps layouts in a container with ref="virtual", applies minHeight from placeholderHeight, and conditionally renders when isVisible using useTemplateRef and useVirtual.
  - Preserves both ClassicLayout and ModernLayout rendering paths behind visibility check.
- New hook:
  - hooks/use-virtual.ts: adds useVirtual using IntersectionObserver (large rootMargin) to expose isVisible and placeholderHeight for lazy mounting.

^{Written by Cursor Bugbot for commit 012c286. This will update automatically on new commits. Configure here.}

changeset-bot · 2025-10-30T20:05:47Z

⚠️ No Changeset found

Latest commit: 012c286

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

cursor

Bug: Observer Cleanup Issue

The IntersectionObserver created in useVirtual isn't cleaned up when the component unmounts. The current watch only handles changes to the observed element, not component destruction. This leaves active observers holding references to DOM elements and callbacks, which can cause memory leaks.

packages/api-reference/src/hooks/use-virtual.ts#L7-L29

scalar/packages/api-reference/src/hooks/use-virtual.ts

Lines 7 to 29 in 012c286

    
           watch(el, () => { 
        
             if (el.value) { 
        
               observer.value?.disconnect() 
        
               observer.value = new IntersectionObserver( 
        
                 ([entry]) => { 
        
                   if (entry?.isIntersecting) { 
        
                     isVisible.value = true 
        
                     nextTick(() => { 
        
                       placeholderHeight.value = el.value?.offsetHeight || 1000 
        
                     }) 
        
                   } 
        
                 }, 
        
                 { 
        
                   rootMargin: '9000px', 
        
                 }, 
        
               ) 
        
               observer.value.observe(el.value) 
        
             } else { 
        
               observer.value?.disconnect() 
        
             } 
        
           })

Bug: Virtual Elements Fail to Unrender

The useVirtual hook's IntersectionObserver sets isVisible to true when an element enters the viewport but lacks logic to set it back to false when the element leaves. This causes elements to remain rendered permanently once visible, defeating the purpose of virtualization and negating its intended performance benefits.

packages/api-reference/src/hooks/use-virtual.ts#L12-L19

scalar/packages/api-reference/src/hooks/use-virtual.ts

Lines 12 to 19 in 012c286

    
           observer.value = new IntersectionObserver( 
        
             ([entry]) => { 
        
               if (entry?.isIntersecting) { 
        
                 isVisible.value = true 
        
                 nextTick(() => { 
        
                   placeholderHeight.value = el.value?.offsetHeight || 1000 
        
                 }) 
        
               }

github-actions · 2025-10-30T20:09:33Z

Preview Examples

https://62fe26a4-ce15-473f-824a-54a414746d82--scalar-deploy-preview.netlify.app

github-actions · 2025-10-30T20:09:50Z

Preview Storybook

https://d5d81aa3-fb52-447a-9315-47555a574358--scalar-components.netlify.app

github-actions · 2025-10-30T20:10:19Z

Scalar References End to End Test Results

3 failed
61 passed

Details

Open report ↗︎
64 tests across 29 suites
17 seconds
012c286

Failed tests

test/snapshots/models.e2e.ts › Scalar Galaxy (Classic Layout)
test/snapshots/operations.e2e.ts › Scalar Galaxy
test/snapshots/operations.e2e.ts › Scalar Galaxy (Classic Layout)

Important

These tests include snapshots that may need to be updated if there are intentional changes to the UI components. To update the snapshots run pnpm test:e2e:update in packages/api-reference and commit the changes.

github-actions · 2025-10-30T20:10:55Z

Scalar Components Snapshot Test Results

152 passed

Details

Open report ↗︎
152 tests across 19 suites
46.3 seconds
012c286

github-actions · 2025-10-30T20:10:56Z

Scalar CDN Snapshot Diff Results

17 failed
2 passed

Details

Open report ↗︎
19 tests across 1 suite
38.5 seconds
012c286
These tests are non-blocking and will not prevent merging of your PR.

Failed tests

test/snapshots-cdn/snapshot.e2e.ts › Diff with CDN - Scalar Galaxy
test/snapshots-cdn/snapshot.e2e.ts › Diff with CDN - Scalar Galaxy Registry
test/snapshots-cdn/snapshot.e2e.ts › Diff with CDN - Scalar Galaxy (Classic Layout)
test/snapshots-cdn/snapshot.e2e.ts › Diff with CDN - Stripe
test/snapshots-cdn/snapshot.e2e.ts › Diff with CDN - Swagger Petstore 2.0
test/snapshots-cdn/snapshot.e2e.ts › Diff with CDN - Swagger Petstore 3.0
test/snapshots-cdn/snapshot.e2e.ts › Diff with CDN - Swagger Petstore 3.1
test/snapshots-cdn/snapshot.e2e.ts › Diff with CDN - Hello World (string)
test/snapshots-cdn/snapshot.e2e.ts › Diff with CDN - Valtown
test/snapshots-cdn/snapshot.e2e.ts › Diff with CDN - Zoom
test/snapshots-cdn/snapshot.e2e.ts › Diff with CDN - Cloudinary
test/snapshots-cdn/snapshot.e2e.ts › Diff with CDN - Tailscale
test/snapshots-cdn/snapshot.e2e.ts › Diff with CDN - Maersk
test/snapshots-cdn/snapshot.e2e.ts › Diff with CDN - Bolt
test/snapshots-cdn/snapshot.e2e.ts › Diff with CDN - OpenStatus
test/snapshots-cdn/snapshot.e2e.ts › Diff with CDN - Spotify
test/snapshots-cdn/snapshot.e2e.ts › Diff with CDN - Circular

Important

These tests detect visual differences between the current PR and the latest CDN build which means they may be affected by other changes in main that haven't been released yet.

They can help determine if the changes in the PR are causing any unexpected visual regressions but may be less helpful in isolating the exact cause. For more details see the readme.

feat(api-refernece): Concept for virtualized operations.

012c286

geoffgscott requested review from hanspagel and marclave as code owners October 30, 2025 20:05

cursor bot reviewed Oct 30, 2025

View reviewed changes

geoffgscott marked this pull request as draft October 30, 2025 20:31

hanspagel changed the title ~~feat(api-refernece): Concept for virtualized operations.~~ feat(api-refernece): virtualized operations Oct 31, 2025

hanspagel changed the title ~~feat(api-refernece): virtualized operations~~ feat(api-reference): virtualized operations Oct 31, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(api-reference): virtualized operations #7210

feat(api-reference): virtualized operations #7210

Uh oh!

geoffgscott commented Oct 30, 2025 •

edited by cursor bot

Loading

Uh oh!

changeset-bot bot commented Oct 30, 2025

Uh oh!

cursor bot left a comment

Uh oh!

github-actions bot commented Oct 30, 2025

Uh oh!

github-actions bot commented Oct 30, 2025

Uh oh!

github-actions bot commented Oct 30, 2025

Uh oh!

github-actions bot commented Oct 30, 2025

Uh oh!

github-actions bot commented Oct 30, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


	watch(el, () => {
	if (el.value) {
	observer.value?.disconnect()

	observer.value = new IntersectionObserver(
	([entry]) => {
	if (entry?.isIntersecting) {
	isVisible.value = true
	nextTick(() => {
	placeholderHeight.value = el.value?.offsetHeight \|\| 1000
	})
	}
	},
	{
	rootMargin: '9000px',
	},
	)
	observer.value.observe(el.value)
	} else {
	observer.value?.disconnect()
	}
	})

feat(api-reference): virtualized operations #7210

Are you sure you want to change the base?

feat(api-reference): virtualized operations #7210

Uh oh!

Conversation

geoffgscott commented Oct 30, 2025 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Oct 30, 2025

⚠️ No Changeset found

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Bug: Observer Cleanup Issue

Bug: Virtual Elements Fail to Unrender

Uh oh!

github-actions bot commented Oct 30, 2025

Uh oh!

github-actions bot commented Oct 30, 2025

Uh oh!

github-actions bot commented Oct 30, 2025

Scalar References End to End Test Results

Details

Uh oh!

github-actions bot commented Oct 30, 2025

Scalar Components Snapshot Test Results

Details

Uh oh!

github-actions bot commented Oct 30, 2025

Scalar CDN Snapshot Diff Results

Details

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

geoffgscott commented Oct 30, 2025 •

edited by cursor bot

Loading