feat(mosaic): simplify Item and add radio cards

.changeset/item-one-look.md

@@ -0,0 +1,18 @@
+---
+'@clerk/mosaic': minor
+---
+
+**Breaking:** Simplify `Item` to one size and one look. Rows are always bordered and size to their content. TypeScript flags the removed props.
+
+| Before                                       | After                       |
+| -------------------------------------------- | --------------------------- |
+| `<Item.Root size='xs' \| 'md' \| 'lg'>`      | `<Item.Root>`               |
+| `<Item.Root variant='outline' \| 'default'>` | `<Item.Root>` (bordered)    |
+| `<Item.Group variant='outline' \| 'default'>`| `<Item.Group>`              |
+| `<Item.Separator />`                         | Removed                     |
+| `.cl-item[data-size]`, `.cl-item-media[data-size]` | Removed               |
+| `.cl-item[data-variant]`, `.cl-item-group[data-variant]` | Removed         |
+
+`Item.Label`'s `variant` is unchanged.
+
+Find usages with `git grep -nE "Item\.(Root|Group)[^>]*(size|variant)=|Item\.Separator|cl-item(-media|-group)?\[data-(size|variant)"`.

.changeset/radio-cards.md

@@ -0,0 +1,5 @@
+---
+'@clerk/mosaic': patch
+---
+
+Add `Radio.Card`, a radio laid out as an `Item` row that picks its `value` when clicked anywhere. Fill it with `Radio.Media` and `Radio.Content`, which holds `Radio.Label` and an optional `Radio.Description`. `Radio.Group` takes `layout='stack' | 'grid'`, and `Radio.Section` splits a group into titled sets.

packages/mosaic/docs/stylex.md

@@ -222,7 +222,7 @@ device, while touch devices look correct.
 
   ```tsx
   // item.tsx — the ring is an atom in the chain, not a property in the styles file
-  stylex.props(reset.base, focusOutline.visible, slots.item.base, slots.item[size]);
+  stylex.props(reset.base, focusOutline.visible, slots.item.base, xstyle);
   ```
 
   It uses `:focus-visible`, never bare `:focus`, and `:has(:focus-visible)` for the

packages/mosaic/src/components/item/item.styles.ts

@@ -10,8 +10,12 @@ export const item = stylex.create({
     // `interactive` rather than gaining a hover branch here: StyleX resolves a property to the
     // last style that declares it, so the two can't merge.
     '--_cl-icon-color': colorVars['--cl-color-foreground-secondary'],
+    padding: space['3'],
+    borderColor: colorVars['--cl-color-border-subtle'],
     borderRadius: radiusVars['--cl-radius-lg'],
-    paddingInline: space['1.5'],
+    borderStyle: 'solid',
+    borderWidth: '1px',
+    gap: space['3'],
     alignItems: 'center',
     color: colorVars['--cl-color-foreground-secondary'],
     display: 'flex',
@@ -22,69 +26,56 @@ export const item = stylex.create({
     width: '100%',
   },
 
-  // interactive rows (rendered as a link/button via `render`) gain hover + cursor. Only these
-  // promote on hover: a static row is not pointing at anything, so its icon and label hold.
-  // A row that is standing down while another action runs keeps its look rather than dimming, so
-  // it holds its opacity where `Button` drops to 0.5. The pointer still reaches it, which is what
-  // shows `not-allowed`, so every hover branch has to exclude a standing-down row itself. Both
-  // spellings count: a row that has to stay focusable while it waits carries `aria-disabled`
-  // instead of the native attribute.
+  // interactive rows (rendered as a link, button or radio card via `render`) gain hover + cursor.
+  // Only these promote on hover: a static row is not pointing at anything, so its icon and label
+  // hold. A row that is standing down while another action runs keeps its look rather than
+  // dimming, so it holds its opacity where `Button` drops to 0.5. The pointer still reaches it,
+  // which is what shows `not-allowed`, so every hover branch has to exclude a standing-down row
+  // itself. Both spellings count: a row that has to stay focusable while it waits carries
+  // `aria-disabled` instead of the native attribute. A radio card reflects its own state as
+  // `data-checked` and `data-disabled`; only a `data-disabled` row dims.
   interactive: {
     '--_cl-icon-color': {
       default: colorVars['--cl-color-foreground-secondary'],
       '@media (hover: hover)': {
         default: null,
-        ':hover:not(:disabled, [aria-disabled="true"])': colorVars['--cl-color-neutral'],
+        ':hover:not(:disabled, [aria-disabled="true"], [data-disabled])': colorVars['--cl-color-neutral'],
+      },
+    },
+    borderColor: {
+      default: colorVars['--cl-color-border-subtle'],
+      ':where([data-checked])': colorVars['--cl-color-foreground'],
+      '@media (hover: hover)': {
+        default: null,
+        ':hover:not(:disabled, [aria-disabled="true"], [data-disabled], [data-checked])':
+          colorVars['--cl-color-border'],
       },
     },
     backgroundColor: {
       default: null,
-      ':active:not(:disabled, [aria-disabled="true"])': colorVars['--cl-color-neutral-alpha-200'],
+      ':active:not(:disabled, [aria-disabled="true"], [data-disabled])': colorVars['--cl-color-neutral-alpha-200'],
+      ':where([data-checked])': colorVars['--cl-color-neutral-alpha-100'],
       '@media (hover: hover)': {
-        ':hover:not(:disabled, [aria-disabled="true"])': colorVars['--cl-color-neutral-alpha-100'],
+        ':hover:not(:disabled, [aria-disabled="true"], [data-disabled], [data-checked])':
+          colorVars['--cl-color-neutral-alpha-100'],
       },
     },
     color: {
       default: colorVars['--cl-color-foreground-secondary'],
       '@media (hover: hover)': {
         default: null,
-        ':hover:not(:disabled, [aria-disabled="true"])': colorVars['--cl-color-foreground'],
+        ':hover:not(:disabled, [aria-disabled="true"], [data-disabled])': colorVars['--cl-color-foreground'],
       },
     },
     cursor: {
       default: 'pointer',
-      ':is(:disabled, [aria-disabled="true"])': 'not-allowed',
+      ':is(:disabled, [aria-disabled="true"], [data-disabled])': 'not-allowed',
     },
-  },
-
-  outline: {
-    borderColor: colorVars['--cl-color-border-subtle'],
-    borderStyle: 'solid',
-    borderWidth: '1px',
-  },
-
-  interactiveOutline: {
-    borderColor: {
+    opacity: {
       default: null,
-      '@media (hover: hover)': {
-        default: null,
-        ':hover:not(:disabled, [aria-disabled="true"])': colorVars['--cl-color-border'],
-      },
+      ':where([data-disabled])': 0.5,
     },
-  },
-
-  xs: {
-    gap: space['1.5'],
-    height: space['8'],
-  },
-  md: {
-    gap: space['3'],
-    height: space['13'],
-  },
-  lg: {
-    gap: space['3'],
-    paddingInline: space['3'],
-    height: space['16'],
+    position: 'relative',
   },
 });
 
@@ -95,11 +86,8 @@ export const media = stylex.create({
     display: 'flex',
     flexShrink: 0,
     justifyContent: 'center',
+    width: space['10'],
   },
-
-  xs: { width: space['5'] },
-  md: { width: space['10'] },
-  lg: { width: space['10'] },
 });
 
 export const content = stylex.create({
@@ -149,28 +137,9 @@ export const actions = stylex.create({
 
 export const group = stylex.create({
   base: {
-    width: '100%',
-  },
-
-  // The gutter belongs to the variant rather than `base`: `outline` has none, and holding it here
-  // keeps the two from overriding each other.
-  default: {
-    padding: space['1.5'],
-  },
-  // Bordered rows read as separate cards, so the group drops its gutter and spaces them instead.
-  outline: {
     gap: space['2'],
     display: 'flex',
     flexDirection: 'column',
-  },
-});
-
-export const separator = stylex.create({
-  base: {
-    borderStyle: 'none',
-    backgroundColor: colorVars['--cl-color-border-subtle'],
-    flexShrink: 0,
-    height: '1px',
     width: '100%',
   },
 });

packages/mosaic/src/components/item/item.test.tsx

@@ -25,33 +25,6 @@ describe('Mosaic Item', () => {
     expect(item).not.toHaveAttribute('data-interactive');
   });
 
-  it('reflects the size prop as a data attribute, defaulting to md', () => {
-    const { rerender } = render(<Item.Root>Hi</Item.Root>);
-    expect(screen.getByText('Hi')).toHaveAttribute('data-size', 'md');
-    rerender(<Item.Root size='xs'>Hi</Item.Root>);
-    expect(screen.getByText('Hi')).toHaveAttribute('data-size', 'xs');
-  });
-
-  it('reads the size from the root in media', () => {
-    const { rerender } = render(
-      <Item.Root size='xs'>
-        <Item.Media data-testid='media' />
-      </Item.Root>,
-    );
-    expect(screen.getByTestId('media')).toHaveAttribute('data-size', 'xs');
-    rerender(
-      <Item.Root size='md'>
-        <Item.Media data-testid='media' />
-      </Item.Root>,
-    );
-    expect(screen.getByTestId('media')).toHaveAttribute('data-size', 'md');
-  });
-
-  it('falls back to the default size when media renders outside a root', () => {
-    render(<Item.Media data-testid='media' />);
-    expect(screen.getByTestId('media')).toHaveAttribute('data-size', 'md');
-  });
-
   it('reflects the label variant as a data attribute, defaulting to default', () => {
     const { rerender } = render(<Item.Label>Clerk</Item.Label>);
     expect(screen.getByText('Clerk')).toHaveAttribute('data-variant', 'default');
@@ -138,80 +111,16 @@ describe('Mosaic Item', () => {
     expect(screen.getByRole('button', { name: 'Manage' }).parentElement).toHaveClass('cl-item-actions');
   });
 
-  it('renders a group and a separator without imposing a role', () => {
+  it('renders a group without imposing a role', () => {
     render(
       <Item.Group data-testid='group'>
         <Item.Root>One</Item.Root>
-        <Item.Separator data-testid='sep' />
         <Item.Root>Two</Item.Root>
       </Item.Group>,
     );
     const group = screen.getByTestId('group');
     expect(group).toHaveClass('cl-item-group');
     expect(group).not.toHaveAttribute('role');
-    expect(screen.getByTestId('sep')).toHaveClass('cl-item-separator');
-  });
-
-  it('reflects the group variant as a data attribute, defaulting to default', () => {
-    const { rerender } = render(<Item.Group data-testid='group'>One</Item.Group>);
-    expect(screen.getByTestId('group')).toHaveAttribute('data-variant', 'default');
-    rerender(
-      <Item.Group
-        data-testid='group'
-        variant='outline'
-      >
-        One
-      </Item.Group>,
-    );
-    expect(screen.getByTestId('group')).toHaveAttribute('data-variant', 'outline');
-  });
-
-  it('reads the variant from the group in its rows', () => {
-    render(
-      <Item.Group variant='outline'>
-        <Item.Root>Outlined</Item.Root>
-      </Item.Group>,
-    );
-    expect(screen.getByText('Outlined')).toHaveAttribute('data-variant', 'outline');
-  });
-
-  it('falls back to the default variant when a row renders outside a group', () => {
-    render(<Item.Root>Hi</Item.Root>);
-    expect(screen.getByText('Hi')).toHaveAttribute('data-variant', 'default');
-  });
-
-  it('gives an outlined row a border atom a default row does not carry', () => {
-    render(
-      <>
-        <Item.Root>Plain</Item.Root>
-        <Item.Group variant='outline'>
-          <Item.Root>Outlined</Item.Root>
-        </Item.Group>
-      </>,
-    );
-
-    const atoms = (text: string) => screen.getByText(text).className.split(' ');
-    expect(atoms('Outlined').filter(atom => !atoms('Plain').includes(atom))).not.toHaveLength(0);
-  });
-
-  it('takes a variant of its own, outside any group', () => {
-    render(<Item.Root variant='outline'>Hi</Item.Root>);
-    expect(screen.getByText('Hi')).toHaveAttribute('data-variant', 'outline');
-  });
-
-  it('lets a row override the variant its group provides, in both directions', () => {
-    render(
-      <>
-        <Item.Group variant='outline'>
-          <Item.Root variant='default'>Opted out</Item.Root>
-        </Item.Group>
-        <Item.Group>
-          <Item.Root variant='outline'>Opted in</Item.Root>
-        </Item.Group>
-      </>,
-    );
-    expect(screen.getByText('Opted out')).toHaveAttribute('data-variant', 'default');
-    expect(screen.getByText('Opted in')).toHaveAttribute('data-variant', 'outline');
   });
 
   it('forwards the ref to the root element', () => {