Skip to content

feat(headless): dialog stacking state and alertdialog role - #9427

Open
maxyinger wants to merge 3 commits into
mainfrom
max/dialog-stacking-state
Open

feat(headless): dialog stacking state and alertdialog role#9427
maxyinger wants to merge 3 commits into
mainfrom
max/dialog-stacking-state

Conversation

@maxyinger

@maxyinger maxyinger commented Aug 13, 2026

Copy link
Copy Markdown
Collaborator

Description

  • updates ARIA role to accept 'dialog' or 'alertdialog' and defaults to 'dialog'
  • Adds data-stacked data-stack-base
    • needed for panel → prompt → alert stack
    • allows for styling deviations for nested modals beyond data-nested
    • data-nested still exists with existing behavior

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

  • 🐛 Bug fix
  • 🌟 New feature
  • 🔨 Breaking change
  • 📖 Refactoring / dependency upgrade / documentation
  • other:

@changeset-bot

changeset-bot Bot commented Aug 13, 2026

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: a33c2bb

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

vercel Bot commented Aug 13, 2026

Copy link
Copy Markdown

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

Project Deployment Actions Updated (UTC)
clerk-js-sandbox Ready Ready Preview Aug 13, 2026 11:11pm
swingset Ready Ready Preview Aug 13, 2026 11:11pm

Request Review

@coderabbitai

coderabbitai Bot commented Aug 13, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro Plus

Run ID: 4ee24454-c9d6-4afd-b403-7ff527ec792f

📥 Commits

Reviewing files that changed from the base of the PR and between 3e567d0 and 677b258.

📒 Files selected for processing (1)
  • .changeset/dialog-stacking-state.md
🔗 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-ios (auto-detected)
  • clerk/cli (auto-detected)
  • clerk/clerk-android (auto-detected)
🚧 Files skipped from review as they are similar to previous changes (1)
  • .changeset/dialog-stacking-state.md

📝 Walkthrough

Walkthrough

The Dialog primitive supports dialog and alertdialog roles. It tracks open and mounted nested dialogs. Dialog popups and backdrops expose stacking and exit-state data attributes. Documentation and tests cover nested stacks, closing dialogs, exit transitions, three-level stacks, and dialogs inside popovers.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Mergeability Score: ⚪ Minimal · up to 677b2

This PR updates headless dialog semantics and stacking state; no actionable merge-blocking risk remains beyond normal checks and review.

Suggested reviewers: austincalvelage

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly summarizes the two main changes: dialog stacking state and support for the alertdialog role.
Description check ✅ Passed The description directly explains the new ARIA role support, stacking attributes, tests, build status, and feature classification.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

Comment @coderabbitai help to get the list of available commands.

@pkg-pr-new

pkg-pr-new Bot commented Aug 13, 2026

Copy link
Copy Markdown

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

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

@clerk/electron-passkeys

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

@clerk/eslint-plugin

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

@clerk/expo

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

@clerk/expo-google-signin

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: a33c2bb

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🧹 Nitpick comments (1)
packages/headless/src/primitives/drawer/drawer-context.ts (1)

33-38: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Shorten the rationale comment.

The Omit change is correct, but the multi-line rationale is longer than needed. Keep the explanation to one terse line that states why drawer context excludes dialog stacking state.

As per coding guidelines, “Keep code comments minimal. Add comments only when critical to explain why a non-obvious change was made; never restate code behavior, and keep warranted comments to one terse line rather than a verbose multi-line block.”

Suggested change
-//
-//
-// The stacking pair goes with them. A drawer already counts its own nesting as
-// `nestedOpenCount` / `onNested`, which is a different question from the dialog's: `isStacked`
-// asks whether a DIALOG sits above, and a drawer's stacked-child styling has nothing to read it
-// from. Inheriting them would oblige every drawer root to publish two values no drawer part uses.
+// Drawer nesting uses `nestedOpenCount`; dialog stacking state does not belong in this context.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/headless/src/primitives/drawer/drawer-context.ts` around lines 33 -
38, Shorten the comment immediately above DrawerContextValue to one terse line
explaining that drawer context excludes dialog-only stacking state. Keep the
existing Omit<DialogContextValue, 'isStacked' | 'stackedChildCount' | 'store'>
declaration unchanged.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@packages/headless/src/primitives/drawer/drawer-context.ts`:
- Around line 33-38: Shorten the comment immediately above DrawerContextValue to
one terse line explaining that drawer context excludes dialog-only stacking
state. Keep the existing Omit<DialogContextValue, 'isStacked' |
'stackedChildCount' | 'store'> declaration unchanged.

ℹ️ Review info
⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro Plus

Run ID: 5d2e396e-5086-4c87-9364-d1a7a3719544

📥 Commits

Reviewing files that changed from the base of the PR and between b39c5a1 and fb78cab.

📒 Files selected for processing (1)
  • packages/headless/src/primitives/drawer/drawer-context.ts
🔗 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-ios (auto-detected)
  • clerk/cli (auto-detected)
  • clerk/clerk-android (auto-detected)

maxyinger added a commit that referenced this pull request Aug 13, 2026
Publish "still covering" rather than the raw `open` flag from
`DialogNestingContext`, so a stacked child keeps `data-stacked` for the
length of the parent's exit instead of painting a second scrim over the
parent's fading one.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@maxyinger
maxyinger force-pushed the max/dialog-stacking-state branch from fb78cab to 3e567d0 Compare August 13, 2026 19:58
Comment thread packages/headless/src/primitives/dialog/dialog-backdrop.tsx
maxyinger added a commit that referenced this pull request Aug 13, 2026
Publish "still covering" rather than the raw `open` flag from
`DialogNestingContext`, so a stacked child keeps `data-stacked` for the
length of the parent's exit instead of painting a second scrim over the
parent's fading one.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@maxyinger
maxyinger force-pushed the max/dialog-stacking-state branch from 3e567d0 to 677b258 Compare August 13, 2026 22:24
maxyinger and others added 3 commits August 13, 2026 17:08
Adds the two signals the Mosaic stacking styles need, and the role an
AlertDialog preset needs.

`data-stacked` / `data-stack-base` describe dialog-on-dialog specifically,
in both directions of the relationship. `data-nested` could not: it reports
any floating ancestor, so a dialog opened from a menu item reads as nested
while sitting on the bare page. Under the incoming rule that a stacked
dialog paints no backdrop, styling off `data-nested` would leave that
dialog with no scrim at all.

The child registers with its parent while OPEN rather than while mounted,
so a dialog beneath comes forward with its child's exit transition rather
than after it. The count is of direct children only, which is enough for
the single recede step that exists.
`DrawerContextValue` inherits from `DialogContextValue`, so adding `isStacked`
and `stackedChildCount` there made every drawer root fail to satisfy its own
context — `tsc --noEmit` was red for the whole package, and for swingset, which
typechecks headless from source.

They belong in the same `Omit` as `store`. A drawer already tracks its nesting
as `nestedOpenCount`, and `isStacked` asks a question about DIALOGS that a
drawer has nothing to answer with.
Publish "still covering" rather than the raw `open` flag from
`DialogNestingContext`, so a stacked child keeps `data-stacked` for the
length of the parent's exit instead of painting a second scrim over the
parent's fading one.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@maxyinger
maxyinger force-pushed the max/dialog-stacking-state branch from 677b258 to a33c2bb Compare August 13, 2026 23:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants