Skip to content

Commit ba29c56

Browse files
maxyingerclaude
andcommitted
feat(ui): rename the Dialog size prop to variant
`card` and `profile` are different surfaces, not one surface at two widths, so `size` was the wrong axis for them to sit on: a second card width — a wide card, say — would be a size OF the card variant, and adding it to a `size` union would conflate the two questions. `Dialog.Popup` takes `variant`, `DialogSize` becomes `DialogVariant`, and the popup, viewport and track reflect `data-variant`. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
1 parent b3291c1 commit ba29c56

17 files changed

Lines changed: 149 additions & 134 deletions

‎packages/swingset/src/stories/dialog.component.mdx‎

Lines changed: 17 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ import * as DialogStories from './dialog.component.stories';
2121
]}
2222
/>
2323

24-
`size` and `compactPlacement` belong to `Dialog.Popup`; the rest belong to `Dialog.Root`.
24+
`variant` and `compactPlacement` belong to `Dialog.Popup`; the rest belong to `Dialog.Root`.
2525

2626
## Usage
2727

@@ -66,7 +66,11 @@ Every close the dialog owns — Escape, outside press, `Dialog.Close`, `Dialog.C
6666
`handle.close()` — goes through `onOpenChange`, so a controlled consumer can veto one by not
6767
committing.
6868

69-
### Size
69+
### Variant
70+
71+
Which surface the dialog holds, and so the geometry it is given. Not a `size`, because these are
72+
different surfaces rather than one surface at two widths — a second card width would be a size of
73+
the `card` variant, with nowhere to sit on this axis.
7074

7175
| Value | Width | For |
7276
| --------- | ---------------------------------------- | -------------------------------------------------------------------- |
@@ -94,7 +98,7 @@ import { UserProfileView } from '@clerk/ui/mosaic/features/user-profile/user-pro
9498

9599
<Dialog.Root>
96100
<Dialog.Trigger render={<Button />}>Manage account</Dialog.Trigger>
97-
<Dialog.Popup size='profile'>
101+
<Dialog.Popup variant='profile'>
98102
<UserProfileView
99103
activePage={activePage}
100104
pages={pages}
@@ -211,13 +215,13 @@ action as its submit.
211215

212216
## Parts
213217

214-
| Part | Slot | Description |
215-
| -------------------- | --------------------- | -------------------------------------------------------------------------------------- |
216-
| `Dialog.Root` | — | State: open/close, `role`, `dismissOn`, `modal`, `handle`. |
217-
| `Dialog.Trigger` | — | Opens the dialog; `render`, and `handle` + `payload` when detached. |
218-
| `Dialog.Popup` | `dialog-popup` | The box the surface sits in; `size`, `compactPlacement`, `initialFocus`, `finalFocus`. |
219-
| `Dialog.Close` | — | Unstyled dismiss; accepts `render`. |
220-
| `Dialog.CloseButton` | `dialog-close-button` | The styled corner X, for a surface that anchors its own dismiss. |
218+
| Part | Slot | Description |
219+
| -------------------- | --------------------- | ----------------------------------------------------------------------------------------- |
220+
| `Dialog.Root` | — | State: open/close, `role`, `dismissOn`, `modal`, `handle`. |
221+
| `Dialog.Trigger` | — | Opens the dialog; `render`, and `handle` + `payload` when detached. |
222+
| `Dialog.Popup` | `dialog-popup` | The box the surface sits in; `variant`, `compactPlacement`, `initialFocus`, `finalFocus`. |
223+
| `Dialog.Close` | — | Unstyled dismiss; accepts `render`. |
224+
| `Dialog.CloseButton` | `dialog-close-button` | The styled corner X, for a surface that anchors its own dismiss. |
221225

222226
The name, the description and the button row come from the surface — `Card.Title`,
223227
`Card.Description` and `Card.Footer` — not from the dialog.
@@ -233,7 +237,7 @@ Override by targeting the `.cl-*` slot from a layer that wins over `@clerk/ui/st
233237
@import '@clerk/ui/styles.css' layer(components);
234238

235239
@layer overrides {
236-
.cl-dialog-popup[data-size='profile'] {
240+
.cl-dialog-popup[data-variant='profile'] {
237241
max-width: 60rem;
238242
}
239243
}
@@ -245,13 +249,13 @@ State attributes:
245249
| ------------------------------------------- | ---------------------------------- | ------------------------------------- |
246250
| `data-open` / `data-closed` | Trigger, Backdrop, Viewport, Popup | Open state (`closed` during the exit) |
247251
| `data-starting-style` / `data-ending-style` | Backdrop, Viewport, Popup | Entering frame / exit animation |
248-
| `data-size` | Viewport, Track, Popup | Resolved size |
252+
| `data-variant` | Viewport, Track, Popup | Resolved variant |
249253
| `data-nested` | Backdrop, Viewport, Popup | Opened inside another overlay |
250254
| `data-stacked` / `data-stack-base` | Popup | On top of / beneath another dialog |
251255

252256
### Nested dialogs and stacks
253257

254-
A dialog opened inside another is one of two relationships, decided by the size beneath it:
258+
A dialog opened inside another is one of two relationships, decided by the variant beneath it:
255259

256260
| | Nested | Stack |
257261
| ------------------- | -------------------------- | ---------------------------------- |

‎packages/swingset/src/stories/dialog.component.stories.tsx‎

Lines changed: 13 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import type { RenderProps } from '@clerk/headless/utils';
22
import { Button } from '@clerk/ui/mosaic/components/button';
33
import { Card } from '@clerk/ui/mosaic/components/card';
4-
import type { DialogCompactPlacement, DialogSize } from '@clerk/ui/mosaic/components/dialog';
4+
import type { DialogCompactPlacement, DialogVariant } from '@clerk/ui/mosaic/components/dialog';
55
import { Dialog } from '@clerk/ui/mosaic/components/dialog';
66
import { Heading } from '@clerk/ui/mosaic/components/heading';
77
import { Input } from '@clerk/ui/mosaic/components/input';
@@ -24,11 +24,11 @@ export const meta: StoryMeta = {
2424
source: 'packages/ui/src/mosaic/components/dialog/dialog.tsx',
2525
styles: {
2626
_variants: {
27-
size: { card: {}, profile: {} },
27+
variant: { card: {}, profile: {} },
2828
compactPlacement: { center: {}, sheet: {} },
2929
},
3030
_defaultVariants: {
31-
size: 'card',
31+
variant: 'card',
3232
compactPlacement: 'center',
3333
},
3434
},
@@ -37,7 +37,7 @@ export const meta: StoryMeta = {
3737
const dialogTrigger = (props: RenderProps) => <Button {...props}>Open dialog</Button>;
3838

3939
// A stand-in for a surface, painted by the story rather than by a component, so the playground
40-
// shows the DIALOG's own box — what each `size` measures and where `compactPlacement` puts it.
40+
// shows the DIALOG's own box — what each `variant` measures and where `compactPlacement` puts it.
4141
// Every real dialog holds a `Card` or a `Profile` instead; see the examples below.
4242
const surface: React.CSSProperties = {
4343
background: 'var(--cl-color-card)',
@@ -54,19 +54,22 @@ const surface: React.CSSProperties = {
5454
/**
5555
* The dialog paints nothing: it brings the geometry, the motion and the floating tree, and the
5656
* SURFACE comes from what is rendered inside it. This example draws its own box so the two are
57-
* visible apart — the dashed edge is the popup, and `size` is what it measures.
57+
* visible apart — the dashed edge is the popup, and `variant` is what it measures.
5858
*
5959
* Every real dialog holds a `Card` (see [the surface section](#every-dialog-brings-its-own-surface))
6060
* or a `Profile` (see [A profile](#a-profile)), which is also where the name and the dismiss come
6161
* from — hence the `aria-label` and the corner `Dialog.CloseButton` standing in for them here.
6262
*/
6363
export function Default(args: Record<string, unknown>) {
64-
const { size, compactPlacement } = args as { size?: DialogSize; compactPlacement?: DialogCompactPlacement };
64+
const { variant, compactPlacement } = args as {
65+
variant?: DialogVariant;
66+
compactPlacement?: DialogCompactPlacement;
67+
};
6568
return (
6669
<Dialog.Root>
6770
<Dialog.Trigger render={dialogTrigger} />
6871
<Dialog.Popup
69-
size={size}
72+
variant={variant}
7073
compactPlacement={compactPlacement}
7174
aria-label='Dialog surface'
7275
>
@@ -443,7 +446,7 @@ export function Nested() {
443446
return (
444447
<Dialog.Root>
445448
<Dialog.Trigger render={accountTrigger} />
446-
<Dialog.Popup size='profile'>
449+
<Dialog.Popup variant='profile'>
447450
<UserProfileView
448451
activePage={activePage}
449452
pages={pages}
@@ -584,7 +587,7 @@ export function CardSurface() {
584587
return (
585588
<Dialog.Root>
586589
<Dialog.Trigger render={props => <Button {...props}>Sign in</Button>} />
587-
<Dialog.Popup size='card'>
590+
<Dialog.Popup variant='card'>
588591
<Card.Root elevation='overlay'>
589592
<Card.Header>
590593
<Card.Title>Sign in</Card.Title>
@@ -626,7 +629,7 @@ export function OutsideScroll() {
626629
return (
627630
<Dialog.Root>
628631
<Dialog.Trigger render={props => <Button {...props}>Review terms</Button>} />
629-
<Dialog.Popup size='card'>
632+
<Dialog.Popup variant='card'>
630633
<Card.Root elevation='overlay'>
631634
<Card.Header>
632635
<Card.Title>Terms of service</Card.Title>

‎packages/swingset/src/stories/drawer.component.stories.tsx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ export function InsideProfile() {
5454
return (
5555
<Dialog.Root>
5656
<Dialog.Trigger render={<Button />}>Manage account</Dialog.Trigger>
57-
<Dialog.Popup size='profile'>
57+
<Dialog.Popup variant='profile'>
5858
<UserProfileView
5959
activePage={activePage}
6060
pages={pages}

‎packages/swingset/src/stories/user-profile.stories.tsx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ export function Overlay() {
4343
return (
4444
<Dialog.Root>
4545
<Dialog.Trigger render={<Button />}>Manage account</Dialog.Trigger>
46-
<Dialog.Popup size='profile'>
46+
<Dialog.Popup variant='profile'>
4747
<UserProfileView
4848
activePage={activePage}
4949
pages={pages}

‎packages/ui/src/mosaic/blocks/destructive/destructive.tsx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,7 @@ export function Destructive({
102102
onOpenChange={onOpenChange}
103103
>
104104
{trigger ? <Dialog.Trigger render={trigger} /> : null}
105-
<Dialog.Popup size='card'>
105+
<Dialog.Popup variant='card'>
106106
<Card.Root
107107
elevation='overlay'
108108
renderBranding={false}

‎packages/ui/src/mosaic/components/dialog/alert-dialog.test.tsx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -82,7 +82,7 @@ describe('role="alertdialog"', () => {
8282
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
8383
render(<Confirm />);
8484

85-
expect(document.querySelector('.cl-dialog-popup')).toHaveAttribute('data-size', 'card');
85+
expect(document.querySelector('.cl-dialog-popup')).toHaveAttribute('data-variant', 'card');
8686
expect(warn).not.toHaveBeenCalled();
8787
warn.mockRestore();
8888
});

‎packages/ui/src/mosaic/components/dialog/dialog.styles.ts‎

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,11 @@ import * as stylex from '@stylexjs/stylex';
33
import { colorVars, durationVars, easingVars, radiusVars, space } from '../../tokens.stylex';
44

55
// How far the contents of a surface beneath a stacked dialog are veiled toward its own background.
6-
// Declared up here rather than beside `STACK_SCALE` further down because `sizes` reads it, and
6+
// Declared up here rather than beside `STACK_SCALE` further down because `variants` reads it, and
77
// StyleX requires a referenced constant to be declared before the `create()` call that reads it.
88
const STACK_VEIL_OPACITY = 0.4;
99

10-
// The card's width cap, read by `sizes.card` and restated by `compactPlacements.sheet` — which
10+
// The card's width cap, read by `variants.card` and restated by `compactPlacements.sheet` — which
1111
// has to declare `max-width` itself to lift it in the compact band, and would otherwise fork the
1212
// value.
1313
const CARD_MAX_WIDTH = '25rem';
@@ -31,7 +31,7 @@ const BASE_SCRIM = 'color-mix(in oklab, oklch(0 0 0) 40%, transparent)';
3131
* winner to source order, which `@stylexjs/sort-keys` reorders on autofix — and its string sort
3232
* would put a future `100rem` band BEFORE `48rem`, silently inverting the ladder.
3333
*
34-
* `prefers-reduced-motion` and `forced-colors` stay `@media`: they are preferences, not sizes.
34+
* `prefers-reduced-motion` and `forced-colors` stay `@media`: they are preferences, not widths.
3535
*/
3636
// `48rem` is also the Profile's compact band (`compact` in `profile.styles.ts`); the two must agree.
3737
const PHONE = '@container cl-dialog (width < 48rem)';
@@ -81,16 +81,16 @@ export const styles = stylex.create({
8181
/**
8282
* The headless viewport element, inside the `FloatingOverlay` that owns the fixed positioning
8383
* and the scroll lock. Two jobs: it is the query container every band reads — see `PHONE` and
84-
* friends above — and it is the box the sizes measure against. Whether that box is a fixed
85-
* height or grows with its content is the whole outside-scroll question, and it differs per
86-
* size — see `viewportSizes` below.
84+
* friends above — and it is the box each variant is measured against. Whether that box is a
85+
* fixed height or grows with its content is the whole outside-scroll question, and it differs
86+
* per variant — see `viewportVariants` below.
8787
*
8888
* It carries NO band of its own, and cannot: an element is never its own query container, so a
8989
* `@container cl-dialog` rule on this element would resolve against some OUTER dialog's viewport
9090
* — or nothing. Everything width-dependent lives on `track`, the padded grid inside it.
9191
*
9292
* `inline-size` rather than `size`: block-size containment would stop the box growing with its
93-
* content, which is exactly what the outside-scroll sizes need it to do, and no band queries
93+
* content, which is exactly what the outside-scroll variants need it to do, and no band queries
9494
* height. A grid so the track fills it: an `auto` row stretches to the container's used height,
9595
* `min-height` included, which is what hands the track a definite box to centre within.
9696
*/
@@ -143,7 +143,7 @@ export const styles = stylex.create({
143143
// so it is inert until `acquireKeyboardInset` has something to report.
144144
paddingBlockEnd: 'calc(var(--_cl-dialog-inset) + var(--_cl-keyboard-inset, 0px))',
145145
// A grid item's automatic minimum would otherwise hold this to its content and defeat the
146-
// definite row `viewportSizes.profile` pins.
146+
// definite row `viewportVariants.profile` pins.
147147
minHeight: 0,
148148
width: '100%',
149149
},
@@ -172,7 +172,7 @@ export const styles = stylex.create({
172172
* paint over it and stay undimmed. Never interactive: the whole subtree is inert while a
173173
* stacked dialog holds focus, and `pointer-events: none` keeps it that way regardless.
174174
*
175-
* The variable itself is set per size — only `card` sets it, in `sizes` below — so this
175+
* The variable itself is set per variant — only `card` sets it, in `variants` below — so this
176176
* reads `0` on a `profile`, which gets a scrim of its own between it and what it hosts and
177177
* would otherwise dim as well as darken.
178178
*/
@@ -189,7 +189,7 @@ export const styles = stylex.create({
189189
borderColor: { default: null, '@media (forced-colors: active)': 'CanvasText' },
190190
// No paint of its own, but the radius is what the HCM border above and the veil below trace,
191191
// and both are standing in for a surface. Matches `Card`'s own radius, which is what they
192-
// trace in practice; `sizes.profile` nulls it, since a profile owns its corners at every band.
192+
// trace in practice; `variants.profile` nulls it, since a profile owns its corners at every band.
193193
borderRadius: radiusVars['--cl-radius-xl'],
194194
borderStyle: { default: null, '@media (forced-colors: active)': 'solid' },
195195
borderWidth: { default: null, '@media (forced-colors: active)': '1px' },
@@ -232,7 +232,7 @@ export const styles = stylex.create({
232232
* participates in the column's `gap` and a consumer can render it anywhere in the children
233233
* without the layout moving.
234234
*
235-
* It stays put on a `profile` because the popup itself never scrolls — see `sizes.profile`. An
235+
* It stays put on a `profile` because the popup itself never scrolls — see `variants.profile`. An
236236
* absolutely positioned child of a scroll container scrolls away with the content, so the
237237
* scroll region has to live in the profile's children, not on the popup.
238238
*
@@ -306,19 +306,19 @@ export const closeInsets = stylex.create({
306306
* instead: the padding travels with the content, and short dialogs still fill the overlay so the
307307
* track has something to centre against.
308308
*/
309-
export const viewportSizes = stylex.create({
309+
export const viewportVariants = stylex.create({
310310
card: { minHeight: '100%' },
311311
profile: {
312312
// A definite container height is NOT enough on its own: an `auto` grid row still sizes to its
313313
// content and happily exceeds the container, which is how a profile of rows measured 2208px
314314
// inside a 1251px overlay. `minmax(0, 1fr)` pins the single row to the content box, so the row
315315
// is what an item stretches to and what its overflow is measured against.
316316
//
317-
// Deliberately NOT applied to the scrolling sizes: it would clamp the row there too, which is
317+
// Deliberately NOT applied to the scrolling variants: it would clamp the row there too, which is
318318
// exactly what has to stop happening for the popup to grow past the fold.
319319
gridTemplateRows: 'minmax(0, 1fr)',
320320
// A DEFINITE height, taken from the overlay (`position: fixed; inset: 0`), which makes the
321-
// single grid row definite too. That is what lets `sizes.profile` fill the content box with
321+
// single grid row definite too. That is what lets `variants.profile` fill the content box with
322322
// `align-self: stretch` alone — no `dvh` arithmetic, so nothing can disagree with the box a
323323
// bottom-anchored sheet aligns to. They genuinely do diverge: on an emulated iPhone the
324324
// overlay measures 1251px while `100dvh` reports 844.
@@ -327,7 +327,7 @@ export const viewportSizes = stylex.create({
327327
});
328328

329329
/** The per-size half of `styles.track` — the rules that need the band, and so must sit inside the container. */
330-
export const trackSizes = stylex.create({
330+
export const trackVariants = stylex.create({
331331
card: {},
332332
profile: {
333333
// Under the phone band a profile takes the whole screen: it is the page there, not a surface
@@ -346,7 +346,7 @@ export const trackSizes = stylex.create({
346346
},
347347
});
348348

349-
export const sizes = stylex.create({
349+
export const variants = stylex.create({
350350
// The surface is a `Card` — so it comes from `Card`'s own `elevations.overlay`, and the popup
351351
// contributes geometry and motion. Compose it by rendering the card INSIDE the popup:
352352
//
@@ -437,7 +437,7 @@ export const compactPlacements = stylex.create({
437437
// shared: bottom-aligning there would drag a centred dialog down with it.
438438
//
439439
// The popup's own cap is lifted at the same time so it spans the width the inset leaves, and
440-
// the surface inside decides how much of that it takes. `default` restates `sizes.card`'s cap
440+
// the surface inside decides how much of that it takes. `default` restates `variants.card`'s cap
441441
// rather than leaving it to the cascade: this cell is spread after that one in the same
442442
// `stylex.props` call, so StyleX dedupes `max-width` to whatever is written here. Both read
443443
// the same constant, so there is one value to retune.
@@ -446,7 +446,7 @@ export const compactPlacements = stylex.create({
446446
},
447447
});
448448

449-
/** The per-placement half of `styles.track` — the rules that need the band. See `trackSizes`. */
449+
/** The per-placement half of `styles.track` — the rules that need the band. See `trackVariants`. */
450450
export const trackCompactPlacements = stylex.create({
451451
center: {},
452452
sheet: {

0 commit comments

Comments
 (0)