refactor(mosaic): replace Floating UI Composite with useComposite by alexcarpenter · Pull Request #10573 · clerk/javascript

alexcarpenter · 2026-11-02T12:56:37Z

Description

Replaces Floating UI's Composite/CompositeItem with an in-house useComposite hook, so tabs, segmented control, accordion, action bar, tag input and the table's grid navigation share one roving-tabindex implementation. This removes the render-prop wrappers and is a step towards using Floating UI only for positioning.

Fixes: the tab stop now lands on a selected tab that isn't first, and arrow keys in a field inside an accordion panel stay with that field.
Item registration: items register through context and sort by document position, following FloatingList/useListItem. It uses a ref-backed Map rather than state, because no index is needed.
Unchanged: popup lists keep useListNavigation, OTP keeps its own handling, and the table keeps its DOM lookups for cells and widgets.
Behaviour difference: before hydration, server-rendered tabs now have no tabindex, where CompositeItem rendered them all as -1. The hook writes tabindex in a layout effect, which doesn't run on the server. After hydration there is one tab stop, as before.

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

vercel · 2026-11-02T12:56:41Z

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

Project	Deployment	Actions	Updated
clerk-js-sandbox	Ready	Preview	Nov 2, 2026 1:00pm UTC
swingset	Ready	Preview	Nov 2, 2026 1:00pm UTC

changeset-bot · 2026-11-02T12:56:42Z

🦋 Changeset detected

Latest commit: 64251fc

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

This PR includes changesets to release 2 packages

Name	Type
@clerk/mosaic	Patch
@clerk/swingset	Patch

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

coderabbitai · 2026-11-02T12:57:04Z

Recent review info

Run configuration

Source mode: Auto
Repository: clerk/javascript
Branch: carp/mosaic-compsite
File: .coderabbit.yaml
Commit: 64251fc
Layers: Repository YAML (base), Organization UI (inherited)
Review profile: ASSERTIVE
Plan: Team
Run ID: 149bfa57-7d48-41ab-b7e3-c7c2278f52d5

Commits

Reviewing files that changed from the base of the PR and between c44d34a and 64251fc.

Files selected for processing: 21

.changeset/mosaic-composite-navigation.md
packages/mosaic/AGENTS.md
packages/mosaic/docs/headless.md
packages/mosaic/src/components/action-bar/action-bar.test.tsx
packages/mosaic/src/components/action-bar/action-bar.tsx
packages/mosaic/src/primitives/accordion/accordion-root.tsx
packages/mosaic/src/primitives/accordion/accordion-trigger.tsx
packages/mosaic/src/primitives/accordion/accordion.test.tsx
packages/mosaic/src/primitives/hooks/__tests__/use-composite.test.tsx
packages/mosaic/src/primitives/hooks/index.ts
packages/mosaic/src/primitives/hooks/use-composite.ts
packages/mosaic/src/primitives/segmented-control/segmented-control-item.tsx
packages/mosaic/src/primitives/segmented-control/segmented-control-root.tsx
packages/mosaic/src/primitives/table/table.test.tsx
packages/mosaic/src/primitives/table/use-grid-navigation.ts
packages/mosaic/src/primitives/tabs/tabs-list.tsx
packages/mosaic/src/primitives/tabs/tabs-tab.tsx
packages/mosaic/src/primitives/tabs/tabs.test.tsx
packages/mosaic/src/primitives/tag-input/tag-input-root.tsx
packages/mosaic/src/primitives/tag-input/tag-input-tag.tsx
packages/mosaic/src/primitives/tag-input/tag-input.test.tsx

Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

clerk/clerk_go (manual)
clerk/dashboard (manual)
clerk/accounts (manual)
clerk/backoffice (manual)
clerk/clerk (manual)
clerk/clerk-docs (manual)
clerk/cloudflare-workers (manual)
clerk/clerk-android (auto-detected)
clerk/clerk-ios (auto-detected)
clerk/cli (auto-detected)

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 2 remain after this review.

Walkthrough

The changes add a shared composite-navigation hook with item registration, focus management, and configurable keyboard handling. Action bar, accordion, segmented control, tabs, table navigation, and tag input adopt the hook. New tests cover navigation, tab stops, focus recovery, and key handling. Documentation and a patch changeset are also updated.

Estimated code review effort: 4 (Complex) | ~45 minutes

Suggested reviewers: maxyinger, austincalvelage

Merge Risk: Low · up to 64251

Consumer onFocus and onBlur handlers passed to ActionBar.Root are silently dropped. The fix is small, and the rest of the composite-navigation refactor looks safe to merge.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentat…	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Title check		The title clearly and concisely describes the main change: replacing Floating UI Composite components with the in-house useComposite hook.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Description check		The description states that the PR replaces Floating UI's Composite/CompositeItem with an in-house useComposite hook, shared by tabs, segmented control, accordion, action bar, tag input, and table gri…

Full details: Description check

Explanation

The description states that the PR replaces Floating UI's Composite/CompositeItem with an in-house useComposite hook, shared by tabs, segmented control, accordion, action bar, tag input, and table grid navigation. It also lists the bug fixes, item registration approach, unchanged areas, and a server-rendering behaviour difference. This matches the changeset, so the description is related and specific enough to pass.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 14 functions across 18 files. (3 skipped: 3 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Warning

Linked repositories: Some configured repositories could not be included in this review. Cross-repository analysis may be incomplete. Please check linked-repository access and settings.

pkg-pr-new · 2026-11-02T12:59:46Z

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@10573

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@10573

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@10573

@clerk/expo

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

@clerk/expo-biometrics

npm i https://pkg.pr.new/@clerk/expo-biometrics@10573

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@10573

@clerk/expo-native-components

npm i https://pkg.pr.new/@clerk/expo-native-components@10573

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/mosaic

npm i https://pkg.pr.new/@clerk/mosaic@10573

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 64251fc

coderabbitai

Fix comments: Fix CodeRabbit comments on this PR

refactor(mosaic): replace Floating UI Composite with useComposite

64251fc

github-actions Bot added the mosaic label Nov 2, 2026

vercel Bot deployed to Preview – clerk-js-sandbox November 2, 2026 12:57

View deployment

vercel Bot deployed to Preview – swingset November 2, 2026 13:00

View deployment

coderabbitai Bot reviewed Nov 2, 2026

View reviewed changes

Comment thread packages/mosaic/src/components/action-bar/action-bar.tsx Resolved

Navigation Menu

Repository navigation

refactor(mosaic): replace Floating UI Composite with useComposite - #10573

refactor(mosaic): replace Floating UI Composite with useComposite#10573
alexcarpenter wants to merge 1 commit into
mainfrom
carp/mosaic-compsite

alexcarpenter commented Nov 2, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Nov 2, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Nov 2, 2026

Uh oh!

coderabbitai Bot commented Nov 2, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Nov 2, 2026

Uh oh!

coderabbitai Bot left a comment •

edited

Loading

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

alexcarpenter commented Nov 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Type of change

Uh oh!

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

Uh oh!

Uh oh!

changeset-bot Bot commented Nov 2, 2026

🦋 Changeset detected

Uh oh!

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

Uh oh!

Uh oh!

pkg-pr-new Bot commented Nov 2, 2026

Uh oh!

coderabbitai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

alexcarpenter commented Nov 2, 2026 •

edited

Loading

vercel Bot commented Nov 2, 2026 •

edited

Loading

coderabbitai Bot commented Nov 2, 2026 •

edited

Loading

coderabbitai Bot left a comment •

edited

Loading