Skip to content

chore(tabs): add @internal JSDoc tags to private and implementation-only properties#6328

Open
Rajdeepc wants to merge 3 commits into
mainfrom
rajdeepchandra/chore-tabs-internalize-private-properties
Open

chore(tabs): add @internal JSDoc tags to private and implementation-only properties#6328
Rajdeepc wants to merge 3 commits into
mainfrom
rajdeepchandra/chore-tabs-internalize-private-properties

Conversation

@Rajdeepc
Copy link
Copy Markdown
Contributor

@Rajdeepc Rajdeepc commented May 20, 2026

Description

Adds @internal JSDoc tags to 8 properties in TabsBase that were missing them. Without @internal, the CEM (Custom Elements Manifest) analyzer treats these as public API and Storybook surfaces them in the Controls panel alongside the real public properties.

Properties tagged:

Property Kind Why it leaked
_keyboardActivation Private backing field Duplicate of public keyboardActivation getter
_density Private backing field Duplicate of public density getter
_direction Private backing field Duplicate of public direction getter
INDICATOR_BASE_SIZE Private static constant No JSDoc at all
selectionIndicatorStyle @state() protected Render-only; not consumer API
shouldAnimate @state() protected Render-only; not consumer API
_tabs Private collection Internal cache
_resizeObserver Private instance Internal observer

Motivation and context

The Storybook playground for swc-tabs displayed 20 controls, including internal implementation details prefixed with _. TypeScript's private keyword is compile-time only and does not prevent the CEM analyzer from emitting these fields. The @internal JSDoc tag is the standard mechanism to exclude them.

After this change, only the 6 intended public properties remain in Controls: keyboardActivation, density, direction, disabled, accessibleLabel, and selected.

Author's checklist

  • I have read the CONTRIBUTING and PULL_REQUESTS documents.
  • I have reviewed at the Accessibility Practices for this feature, see: Aria Practices
  • I have added automated tests to cover my changes.
  • I have included a well-written changeset if my change needs to be published.
  • I have included updated documentation if my change required it.

Reviewer's checklist

  • Includes a Github Issue with appropriate flag or Jira ticket number without a link
  • Includes thoughtfully written changeset if changes suggested include patch, minor, or major features
  • Automated tests cover all use cases and follow best practices for writing
  • Validated on all supported browsers
  • All VRTs are approved before the author can update Golden Hash

Manual review test cases

  • Verify internal properties no longer appear in Storybook Controls
    1. Go to the Tabs Playground story
    2. Open the Controls panel
    3. Confirm that _density, _direction, _keyboardActivation, _tabs, _resizeObserver, INDICATOR_BASE_SIZE, selectionIndicatorStyle, and shouldAnimate are not listed
    4. Confirm that keyboardActivation, density, direction, disabled, accessibleLabel, and selected are listed

Device review

  • Did it pass in Desktop?
  • Did it pass in (emulated) Mobile?
  • Did it pass in (emulated) iPad?

Accessibility testing checklist

  • Keyboard — No interactive changes; this is a JSDoc-only change. No keyboard behavior is affected.
  • Screen reader — No ARIA or DOM changes; screen reader behavior is unchanged.

Made with Cursor

@cursoragent
chore(tabs): add @internal JSDoc tags to private and implementation-o…
4d3e3c9 
…nly properties

Private backing fields (_density, _direction, _keyboardActivation),
internal state (@State() selectionIndicatorStyle, shouldAnimate),
cached collections (_tabs), the ResizeObserver instance, and the
static INDICATOR_BASE_SIZE constant were all missing @internal tags.
The CEM analyzer picked them up and surfaced them in the Storybook
Controls panel as public API. Adding @internal ensures they are
excluded from the generated manifest and no longer appear as
consumer-facing controls.

Co-authored-by: Cursor <cursoragent@cursor.com>
@Rajdeepc Rajdeepc requested a review from a team as a code owner May 20, 2026 08:35
@changeset-bot
Copy link
Copy Markdown

changeset-bot Bot commented May 20, 2026 •
edited
Loading

⚠️ No Changeset found

Latest commit: 0c54dbb

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

@Rajdeepc Rajdeepc self-assigned this May 20, 2026
@Rajdeepc Rajdeepc added bug Something isn't working Component:Tabs Status:Ready for review PR ready for review or re-review. 2nd gen These issues or PRs map to our 2nd generation work to modernizing infrastructure. labels May 20, 2026
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented May 20, 2026 •
edited
Loading

📚 Branch Preview Links

🔍 First Generation Visual Regression Test Results

When a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:

Deployed to Azure Blob Storage: pr-6328

If the changes are expected, update the current_golden_images_cache hash in the circleci config to accept the new images. Instructions are included in that file.
If the changes are unexpected, you can investigate the cause of the differences and update the code accordingly.

rubencarvalho
rubencarvalho requested changes May 21, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

@rubencarvalho rubencarvalho left a comment

Choose a reason for hiding this comment

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

Image

Can you confirm if those are also expected?

@Rajdeepc
Copy link
Copy Markdown
Contributor Author

Rajdeepc commented May 22, 2026

Image Can you confirm if those are also expected?

Protected attributes. Should have been marked as internal. Good catch!

@cursoragent
chore(tabs): mark shadowRootOptions and updateSelectionIndicator as i…
3cbcdd0 
…nternal

Both are implementation details that should not appear in the
CEM manifest or Storybook Controls: shadowRootOptions configures
shadow DOM setup, and updateSelectionIndicator is a protected
method called automatically by lifecycle hooks.

Co-authored-by: Cursor <cursoragent@cursor.com>
@Rajdeepc Rajdeepc requested a review from rubencarvalho May 22, 2026 14:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@cdransf cdransf cdransf approved these changes

@rubencarvalho rubencarvalho Awaiting requested review from rubencarvalho

Requested changes must be addressed to merge this pull request.

Assignees

@Rajdeepc Rajdeepc

Labels

2nd gen These issues or PRs map to our 2nd generation work to modernizing infrastructure. bug Something isn't working Component:Tabs Status:Ready for review PR ready for review or re-review.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@Rajdeepc @cdransf @rubencarvalho