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 7:12pm UTC
swingset	Ready	Preview	Nov 2, 2026 7:12pm UTC

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

🦋 Changeset detected

Latest commit: 5a19370

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

No actionable comments were generated in the recent review.

Recent review info

Run configuration

Source mode: Auto
Repository: clerk/javascript
Branch: carp/mosaic-compsite
File: .coderabbit.yaml
Commit: 5a19370
Layers: Repository YAML (base), Organization UI (inherited)
Review profile: ASSERTIVE
Plan: Team
Run ID: fca1e756-cee8-4e10-807a-8e55edca7555

Commits

Reviewing files that changed from the base of the PR and between a3a893f and 5a19370.

Files selected for processing: 2

.changeset/mosaic-composite-navigation.md
packages/mosaic/src/primitives/accordion/accordion.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/cli (auto-detected)
clerk/clerk-ios (auto-detected)

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

Walkthrough

The changes add a shared composite-navigation hook and item registry for tab-stop management, focus handling, and keyboard navigation. Action bar, accordion, segmented control, tabs, table navigation, and tag input adopt the hook. Tests cover navigation, tab stops, focus recovery, and key handling. Documentation, reuse guidance, and a patch changeset are also updated.

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

Suggested reviewers: austincalvelage

Merge Risk: Minimal · up to 5a193

The reviewed changes add focused regression coverage and a changeset without an established merge-blocking defect.

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 identifies the main change: replacing Floating UI Composite with the new useComposite implementation.
Description check		The description directly explains the useComposite refactor, affected components, behavior changes, and validation results. It is related to the changeset.
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.

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. (1 skipped: 1 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: 5a19370

coderabbitai

Fix comments: Fix CodeRabbit comments on this PR

…r lint rules

# Conflicts: # packages/mosaic/AGENTS.md

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

alexcarpenter added 2 commits November 2, 2026 12:07

fix(mosaic): keep action bar focus handlers and satisfy React Compile…

808f471

…r lint rules

Merge remote-tracking branch 'origin/main' into carp/mosaic-compsite

a3a893f

# Conflicts: # packages/mosaic/AGENTS.md

vercel Bot deployed to Preview – clerk-js-sandbox November 2, 2026 18:10

View deployment

vercel Bot deployed to Preview – swingset November 2, 2026 18:14

View deployment

coderabbitai Bot reviewed Nov 2, 2026

View reviewed changes

Comment thread packages/mosaic/src/primitives/accordion/accordion.test.tsx Resolved

test(mosaic): assert arrow keys in accordion fields are not canceled

5a19370

vercel Bot deployed to Preview – clerk-js-sandbox November 2, 2026 19:10

View deployment

vercel Bot deployed to Preview – swingset November 2, 2026 19:12

View deployment

alexcarpenter requested a review from austincalvelage November 2, 2026 19:29

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 4 commits 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 •

edited

Loading

Uh oh!

coderabbitai Bot commented Nov 2, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Nov 2, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot left a comment •

edited

Loading

Uh oh!

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 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 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 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

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!

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

changeset-bot Bot commented Nov 2, 2026 •

edited

Loading

coderabbitai Bot commented Nov 2, 2026 •

edited

Loading

pkg-pr-new Bot commented Nov 2, 2026 •

edited

Loading

coderabbitai Bot left a comment •

edited

Loading

coderabbitai Bot left a comment •

edited

Loading