docs(swingset): document headless primitives by kylemac · Pull Request #8819 · clerk/javascript

kylemac · 2026-06-10T22:38:43Z

TLDR

Documents the rest of the "primitives":

Description

Builds out the @clerk/swingset component explorer for the Mosaic/headless system. Documents every remaining @clerk/headless primitive (accordion, autocomplete, dialog, menu, popover, select, tabs, tooltip) as single-page overviews — each with an unstyled <Story> demo plus Parts/Props/Styling tables sourced directly from the primitive's parts — mirroring the existing Collapsible page, and wires them into the sidebar registry and the DocsViewer MDX map. Also includes the earlier inline-playground work this branch is stacked on: single-page component overviews with a live <Preview> + interactive <PropTable> knobs, plus an a11y lint fix dropping a redundant click-to-copy handler. To test: pnpm run dev:swingset and visit each /components/<primitive> page to confirm the docs render and the demos are interactive.

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

Summary by CodeRabbit

New Features
- Introduced documentation and interactive examples for eight new headless primitives: Accordion, Autocomplete, Dialog, Menu, Popover, Select, Tabs, and Tooltip.
Documentation
- Added complete implementation guides including component parts, props references, usage patterns, and comprehensive styling instructions using data attributes and CSS variables.

Replace the per-story knob sub-pages with one overview page per component. The interactive playground now lives inline in the MDX overview, with shared per-page state (PlaygroundContext) driving a live <Preview> whose props are edited through controls embedded in the <PropTable> Value column. Design-token overrides move into a VariablesPanel attached to the preview, the sidebar is flattened to a single link per component under section labels, and each page gains a GitHub 'View source' link and a generated Usage snippet derived from the story source. Docs (CLAUDE.md, README) updated to match.

The whole-codeblock <div onClick> tripped jsx-a11y/click-events-have-key-events and no-static-element-interactions, failing 'next build'. The accessible Copy button already covers the copy action, so remove the div handler (and its now misleading cursor-pointer).

Add single-page overviews for the remaining @clerk/headless primitives (accordion, autocomplete, dialog, menu, popover, select, tabs, tooltip), mirroring the existing Collapsible page: an unstyled `<Story>` demo plus Parts/Props/Styling tables sourced from each primitive's parts. Wired into the sidebar registry and the DocsViewer MDX map.

changeset-bot · 2026-06-10T22:38:47Z

🦋 Changeset detected

Latest commit: 7462024

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

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

Not sure what this means? Click here to learn what changesets are.

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

vercel · 2026-06-10T22:38:49Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jun 10, 2026 10:43pm
swingset	Ready	Preview, Comment	Jun 10, 2026 10:43pm

coderabbitai · 2026-06-10T22:39:08Z

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Repository UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: 68cedc6a-324f-4d61-beda-568e8d5db294

📥 Commits

Reviewing files that changed from the base of the PR and between 5dc5cd4 and 7462024.

📒 Files selected for processing (19)

.changeset/document-headless-primitives.md
packages/swingset/src/components/DocsViewer.tsx
packages/swingset/src/lib/registry.ts
packages/swingset/src/stories/accordion.mdx
packages/swingset/src/stories/accordion.stories.tsx
packages/swingset/src/stories/autocomplete.mdx
packages/swingset/src/stories/autocomplete.stories.tsx
packages/swingset/src/stories/dialog.mdx
packages/swingset/src/stories/dialog.stories.tsx
packages/swingset/src/stories/menu.mdx
packages/swingset/src/stories/menu.stories.tsx
packages/swingset/src/stories/popover.mdx
packages/swingset/src/stories/popover.stories.tsx
packages/swingset/src/stories/select.mdx
packages/swingset/src/stories/select.stories.tsx
packages/swingset/src/stories/tabs.mdx
packages/swingset/src/stories/tabs.stories.tsx
packages/swingset/src/stories/tooltip.mdx
packages/swingset/src/stories/tooltip.stories.tsx

Disabled knowledge base sources:

Linear integration is disabled

You can enable these sources in your CodeRabbit configuration.

📝 Walkthrough

Walkthrough

This PR extends Swingset's documentation and story library with comprehensive interactive guides and Storybook demos for eight headless UI primitives (accordion, autocomplete, dialog, menu, popover, select, tabs, tooltip), wiring them into the core module registry and dynamic documentation viewer.

Changes

Headless primitives documentation and story expansion

Layer / File(s)	Summary
Module registry and documentation viewer wiring `packages/swingset/src/lib/registry.ts`, `packages/swingset/src/components/DocsViewer.tsx`	Imports story metadata for all eight primitives in alphabetical order and registers their MDX documentation paths for dynamic module resolution in the interactive viewer.
Accordion primitive documentation and story `packages/swingset/src/stories/accordion.mdx`, `accordion.stories.tsx`	MDX guide covers usage modes, parts structure, controlled/uncontrolled behavior, and CSS animation via `--cl-accordion-panel-height`; story renders unstyled single-mode accordion with two items.
Autocomplete primitive documentation and story `packages/swingset/src/stories/autocomplete.mdx`, `autocomplete.stories.tsx`	MDX documents controlled input, external filtering, parts, props, and styling; story implements case-insensitive filtering demo with fruit dataset and portal-based option rendering.
Dialog primitive documentation and story `packages/swingset/src/stories/dialog.mdx`, `dialog.stories.tsx`	MDX covers modal behavior, focus trapping, dismissal, uncontrolled/controlled patterns, and enter/exit transitions with `data-cl-starting-style`/`data-cl-ending-style`; story demonstrates full dialog flow with trigger, backdrop, content, and close.
Menu primitive documentation and story `packages/swingset/src/stories/menu.mdx`, `menu.stories.tsx`	MDX documents trigger/positioner/popup structure, controlled open state, separator support, and styling via `data-cl-*` attributes; story renders "Actions" menu with Edit/Duplicate/Delete items.
Popover primitive documentation and story `packages/swingset/src/stories/popover.mdx`, `popover.stories.tsx`	MDX covers trigger/portal/positioner structure, controlled patterns, arrow positioning, and geometry CSS variables; story composes trigger, portal, and popup with title/description/close.
Select primitive documentation and story `packages/swingset/src/stories/select.mdx`, `select.stories.tsx`	MDX documents value control, option labeling, disabled behavior, positioning props, and styling states (open/closed/selected/active); story renders portalized dropdown with three fruit options.
Tabs primitive documentation and story `packages/swingset/src/stories/tabs.mdx`, `tabs.stories.tsx`	MDX covers uncontrolled/controlled value, indicator animation using CSS geometry variables, and indicator positioning setup; story demonstrates three tabs (account/profile/settings) with matching panels.
Tooltip primitive documentation and story `packages/swingset/src/stories/tooltip.mdx`, `tooltip.stories.tsx`	MDX documents trigger/portal/positioner structure, delay grouping via Tooltip.Group, and styling via `data-cl-*` attributes; story renders single unstyled tooltip with portal-based positioning.
Release changeset `.changeset/document-headless-primitives.md`	Records documentation and story additions as a release note entry.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

clerk/javascript#8809: Both PRs extend the same registry and DocsViewer infrastructure for headless primitive module registration—docs(swingset): document Collapsible headless primitive #8809 adds collapsible while this PR expands the system to eight additional primitives.
clerk/javascript#8797: Both PRs build on the Swingset documentation scaffold by extending registry.ts and DocsViewer.tsx to register and dynamically import MDX modules for multiple headless component primitives.
clerk/javascript#8818: Both PRs modify the same core Swingset wiring in registry.ts and DocsViewer.tsx to enable metadata-driven documentation rendering for headless primitives, with this PR adding the eight new primitive story/documentation pairs.

Suggested labels

react, ui

Suggested reviewers

alexcarpenter
prestonwebdev

Poem

🐰 Eight new primitives hop into view,
With docs and stories fresh and true,
Accordion, Menu, Tabs take flight,
Dialog and Select shining bright,
Swingset's garden grows anew!

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

…itives-to-swingset # Conflicts: # packages/swingset/src/lib/registry.ts

pkg-pr-new · 2026-06-10T22:45:10Z

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@8819

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@8819

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@8819

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@8819

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@8819

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@8819

@clerk/express

npm i https://pkg.pr.new/@clerk/express@8819

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@8819

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@8819

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@8819

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@8819

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@8819

@clerk/react

npm i https://pkg.pr.new/@clerk/react@8819

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@8819

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@8819

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@8819

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@8819

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@8819

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@8819

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@8819

commit: 7462024

kylemac and others added 4 commits June 10, 2026 17:19

Merge branch 'main' into kylemac/swingset-preview-knobs

6059d49

Merge remote-tracking branch 'origin/main' into kylemac/headless-prim…

7462024

…itives-to-swingset # Conflicts: # packages/swingset/src/lib/registry.ts

vercel Bot deployed to Preview – clerk-js-sandbox June 10, 2026 22:42 View deployment

vercel Bot deployed to Preview – swingset June 10, 2026 22:43 View deployment

kylemac requested review from alexcarpenter and prestonwebdev June 10, 2026 22:47

kylemac enabled auto-merge (squash) June 10, 2026 22:47

alexcarpenter approved these changes Jun 10, 2026

View reviewed changes

kylemac merged commit be44bae into main Jun 10, 2026
46 of 47 checks passed

kylemac deleted the kylemac/headless-primitives-to-swingset branch June 10, 2026 22:47

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(swingset): document headless primitives#8819

docs(swingset): document headless primitives#8819
kylemac merged 5 commits into
mainfrom
kylemac/headless-primitives-to-swingset

kylemac commented Jun 10, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

changeset-bot Bot commented Jun 10, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jun 10, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jun 10, 2026 •

edited

Loading

Review failed

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Suggested reviewers

Poem

Uh oh!

pkg-pr-new Bot commented Jun 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

kylemac commented Jun 10, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

TLDR

Description

Checklist

Type of change

Summary by CodeRabbit

Uh oh!

changeset-bot Bot commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel Bot commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review failed

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Suggested reviewers

Poem

Uh oh!

pkg-pr-new Bot commented Jun 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

kylemac commented Jun 10, 2026 •

edited by coderabbitai Bot

Loading

changeset-bot Bot commented Jun 10, 2026 •

edited

Loading

vercel Bot commented Jun 10, 2026 •

edited

Loading

coderabbitai Bot commented Jun 10, 2026 •

edited

Loading