feat(ui): Introduce mosaic recipes and conditions (#8830)

Author: alexcarpenter

.changeset/mosaic-slot-recipes.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/primitives/dialog/README.md

@@ -97,10 +97,11 @@ No additional props beyond standard HTML attributes and the `render` prop.
 
 ## Data Attributes
 
-| Attribute                         | Applies To                         | Description                             |
-| --------------------------------- | ---------------------------------- | --------------------------------------- |
-| `data-cl-slot`                    | All parts                          | Part identifier (e.g. `"dialog-popup"`) |
-| `data-cl-open` / `data-cl-closed` | Trigger, Backdrop, Viewport, Popup | Open state                              |
+| Attribute                         | Applies To                         | Description |
+| --------------------------------- | ---------------------------------- | ----------- |
+| `data-cl-open` / `data-cl-closed` | Trigger, Backdrop, Viewport, Popup | Open state  |
+
+Slot identity (`data-cl-slot`) is applied by the styled (mosaic) layer, not by the headless parts.
 
 ## Important Notes
 

packages/headless/src/primitives/dialog/dialog-backdrop.tsx

@@ -21,7 +21,6 @@ export const DialogBackdrop = React.forwardRef<HTMLDivElement, DialogBackdropPro
     const state = { open };
 
     const defaultProps = {
-      'data-cl-slot': 'dialog-backdrop',
       ref,
       ...transitionProps,
     } satisfies DefaultProps<'div'>;

packages/headless/src/primitives/dialog/dialog-close.tsx

@@ -15,7 +15,6 @@ export const DialogClose = React.forwardRef<HTMLButtonElement, DialogCloseProps>
 
   const defaultProps = {
     type: 'button' as const,
-    'data-cl-slot': 'dialog-close',
     ref,
     onClick() {
       setOpen(false);

packages/headless/src/primitives/dialog/dialog-description.tsx

@@ -15,7 +15,6 @@ export const DialogDescription = React.forwardRef<HTMLParagraphElement, DialogDe
     const { descriptionId } = useDialogContext();
 
     const defaultProps = {
-      'data-cl-slot': 'dialog-description',
       id: descriptionId,
       ref,
     } satisfies DefaultProps<'p'>;

packages/headless/src/primitives/dialog/dialog-popup.tsx

@@ -26,7 +26,6 @@ export const DialogPopup = React.forwardRef<HTMLDivElement, DialogPopupProps>(fu
   }
 
   const ownProps = {
-    'data-cl-slot': 'dialog-popup',
     ref: combinedRef,
     'aria-labelledby': labelId,
     'aria-describedby': descriptionId,

packages/headless/src/primitives/dialog/dialog-title.tsx

@@ -14,7 +14,6 @@ export const DialogTitle = React.forwardRef<HTMLHeadingElement, DialogTitleProps
   const { labelId } = useDialogContext();
 
   const defaultProps = {
-    'data-cl-slot': 'dialog-title',
     id: labelId,
     ref,
   } satisfies DefaultProps<'h2'>;

packages/headless/src/primitives/dialog/dialog-trigger.tsx

@@ -25,7 +25,6 @@ export const DialogTrigger = React.forwardRef<HTMLButtonElement, DialogTriggerPr
 
     const ownProps = {
       type: 'button',
-      'data-cl-slot': 'dialog-trigger',
       ref: combinedRef,
     } satisfies DefaultProps<'button'>;
 

packages/headless/src/primitives/dialog/dialog-viewport.tsx

@@ -32,7 +32,6 @@ export const DialogViewport = React.forwardRef<HTMLDivElement, DialogViewportPro
     const state = { open };
 
     const defaultProps = {
-      'data-cl-slot': 'dialog-viewport',
       ref,
       ...transitionProps,
       style: modal ? undefined : { pointerEvents: 'auto' as const },

packages/headless/src/primitives/dialog/dialog.test.tsx

@@ -7,12 +7,15 @@ import { Dialog } from './index';
 
 afterEach(() => cleanup());
 
+// Headless parts no longer emit `data-cl-slot` — slot identity is applied by the styled
+// (mosaic) layer. Tests locate the surface-only parts (backdrop, viewport, trigger) via
+// `data-testid` and everything else via its accessible role or text.
 function renderDialog(props: Partial<React.ComponentProps<typeof Dialog.Root>> = {}) {
   return render(
     <Dialog.Root {...props}>
-      <Dialog.Trigger>Open dialog</Dialog.Trigger>
-      <Dialog.Backdrop />
-      <Dialog.Viewport>
+      <Dialog.Trigger data-testid='dialog-trigger'>Open dialog</Dialog.Trigger>
+      <Dialog.Backdrop data-testid='dialog-backdrop' />
+      <Dialog.Viewport data-testid='dialog-viewport'>
         <Dialog.Popup>
           <Dialog.Title>Dialog Title</Dialog.Title>
           <Dialog.Description>Some dialog description</Dialog.Description>
@@ -25,25 +28,6 @@ function renderDialog(props: Partial<React.ComponentProps<typeof Dialog.Root>> =
 }
 
 describe('Dialog', () => {
-  describe('slot attributes', () => {
-    it('renders trigger with data-cl-slot', () => {
-      renderDialog();
-      const trigger = screen.getByRole('button', { name: 'Open dialog' });
-      expect(trigger).toHaveAttribute('data-cl-slot', 'dialog-trigger');
-    });
-
-    it('renders all parts with correct slot attributes when open', () => {
-      renderDialog({ defaultOpen: true });
-
-      expect(document.querySelector('[data-cl-slot="dialog-backdrop"]')).toBeInTheDocument();
-      expect(document.querySelector('[data-cl-slot="dialog-viewport"]')).toBeInTheDocument();
-      expect(document.querySelector('[data-cl-slot="dialog-popup"]')).toBeInTheDocument();
-      expect(document.querySelector('[data-cl-slot="dialog-title"]')).toBeInTheDocument();
-      expect(document.querySelector('[data-cl-slot="dialog-description"]')).toBeInTheDocument();
-      expect(document.querySelector('[data-cl-slot="dialog-close"]')).toBeInTheDocument();
-    });
-  });
-
   describe('open/close', () => {
     it('opens on trigger click', async () => {
       const user = userEvent.setup();
@@ -53,7 +37,7 @@ describe('Dialog', () => {
       await user.click(trigger);
 
       expect(trigger).toHaveAttribute('data-cl-open', '');
-      expect(document.querySelector('[data-cl-slot="dialog-popup"]')).toBeInTheDocument();
+      expect(screen.getByRole('dialog')).toBeInTheDocument();
     });
 
     it('closes on Escape', async () => {
@@ -93,7 +77,7 @@ describe('Dialog', () => {
     it('respects controlled open prop', () => {
       renderDialog({ open: true });
 
-      expect(document.querySelector('[data-cl-slot="dialog-popup"]')).toBeInTheDocument();
+      expect(screen.getByRole('dialog')).toBeInTheDocument();
     });
 
     it('does not open when controlled open is false', async () => {
@@ -102,29 +86,29 @@ describe('Dialog', () => {
 
       await user.click(screen.getByRole('button', { name: 'Open dialog' }));
 
-      expect(document.querySelector('[data-cl-slot="dialog-popup"]')).not.toBeInTheDocument();
+      expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
     });
   });
 
   describe('ARIA attributes', () => {
     it('popup has aria-labelledby linked to title', () => {
       renderDialog({ defaultOpen: true });
 
-      const title = document.querySelector('[data-cl-slot="dialog-title"]');
-      const popup = document.querySelector('[data-cl-slot="dialog-popup"]');
+      const title = screen.getByText('Dialog Title');
+      const popup = screen.getByRole('dialog');
 
       expect(title).toHaveAttribute('id');
-      expect(popup).toHaveAttribute('aria-labelledby', title?.getAttribute('id'));
+      expect(popup).toHaveAttribute('aria-labelledby', title.getAttribute('id'));
     });
 
     it('popup has aria-describedby linked to description', () => {
       renderDialog({ defaultOpen: true });
 
-      const desc = document.querySelector('[data-cl-slot="dialog-description"]');
-      const popup = document.querySelector('[data-cl-slot="dialog-popup"]');
+      const desc = screen.getByText('Some dialog description');
+      const popup = screen.getByRole('dialog');
 
       expect(desc).toHaveAttribute('id');
-      expect(popup).toHaveAttribute('aria-describedby', desc?.getAttribute('id'));
+      expect(popup).toHaveAttribute('aria-describedby', desc.getAttribute('id'));
     });
 
     it('popup has role=dialog', () => {
@@ -137,7 +121,7 @@ describe('Dialog', () => {
   describe('animation lifecycle', () => {
     it('backdrop is not rendered when closed', () => {
       renderDialog();
-      expect(document.querySelector('[data-cl-slot="dialog-backdrop"]')).not.toBeInTheDocument();
+      expect(screen.queryByTestId('dialog-backdrop')).not.toBeInTheDocument();
     });
 
     it('applies data-cl-open on popup when open', async () => {
@@ -146,8 +130,7 @@ describe('Dialog', () => {
 
       await user.click(screen.getByRole('button', { name: 'Open dialog' }));
 
-      const popup = document.querySelector('[data-cl-slot="dialog-popup"]');
-      expect(popup).toHaveAttribute('data-cl-open', '');
+      expect(screen.getByRole('dialog')).toHaveAttribute('data-cl-open', '');
     });
 
     it('applies data-cl-open on backdrop when open', async () => {
@@ -156,8 +139,7 @@ describe('Dialog', () => {
 
       await user.click(screen.getByRole('button', { name: 'Open dialog' }));
 
-      const backdrop = document.querySelector('[data-cl-slot="dialog-backdrop"]');
-      expect(backdrop).toHaveAttribute('data-cl-open', '');
+      expect(screen.getByTestId('dialog-backdrop')).toHaveAttribute('data-cl-open', '');
     });
 
     it('applies data-cl-open on viewport when open', async () => {
@@ -166,13 +148,12 @@ describe('Dialog', () => {
 
       await user.click(screen.getByRole('button', { name: 'Open dialog' }));
 
-      const viewport = document.querySelector('[data-cl-slot="dialog-viewport"]');
-      expect(viewport).toHaveAttribute('data-cl-open', '');
+      expect(screen.getByTestId('dialog-viewport')).toHaveAttribute('data-cl-open', '');
     });
 
     it('viewport is not rendered when closed', () => {
       renderDialog();
-      expect(document.querySelector('[data-cl-slot="dialog-viewport"]')).not.toBeInTheDocument();
+      expect(screen.queryByTestId('dialog-viewport')).not.toBeInTheDocument();
     });
   });
 
@@ -204,12 +185,12 @@ describe('Dialog', () => {
         </Dialog.Root>,
       );
 
-      expect(document.querySelector('[data-cl-slot="dialog-popup"]')).not.toBeInTheDocument();
+      expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
       expect(screen.queryByText('Popup content')).not.toBeInTheDocument();
 
       await user.click(screen.getByRole('button', { name: 'Open' }));
 
-      expect(document.querySelector('[data-cl-slot="dialog-popup"]')).toBeInTheDocument();
+      expect(screen.getByRole('dialog')).toBeInTheDocument();
       expect(screen.getByText('Popup content')).toBeInTheDocument();
     });
   });
@@ -223,8 +204,8 @@ describe('Dialog', () => {
 
     it('trigger has data-cl-open when dialog is visible', () => {
       renderDialog({ defaultOpen: true });
-      // When modal is open, trigger's container gets aria-hidden, so use querySelector
-      const trigger = document.querySelector('[data-cl-slot="dialog-trigger"]');
+      // When modal is open, the trigger's container gets aria-hidden, so query by test id.
+      const trigger = screen.getByTestId('dialog-trigger');
       expect(trigger).toHaveAttribute('data-cl-open', '');
     });
   });
@@ -246,7 +227,7 @@ describe('Dialog', () => {
           <Dialog.Root modal={false}>
             <Dialog.Trigger>Open dialog</Dialog.Trigger>
             <Dialog.Backdrop />
-            <Dialog.Viewport>
+            <Dialog.Viewport data-testid='dialog-viewport'>
               <Dialog.Popup>
                 <Dialog.Title>Dialog Title</Dialog.Title>
                 <Dialog.Close>Close</Dialog.Close>
@@ -258,9 +239,9 @@ describe('Dialog', () => {
 
       await user.click(screen.getByRole('button', { name: 'Open dialog' }));
 
-      const viewport = document.querySelector('[data-cl-slot="dialog-viewport"]');
+      const viewport = screen.getByTestId('dialog-viewport');
       expect(viewport).toHaveStyle({ pointerEvents: 'auto' });
-      expect(viewport?.parentElement).toHaveStyle({ pointerEvents: 'none' });
+      expect(viewport.parentElement).toHaveStyle({ pointerEvents: 'none' });
 
       await user.click(screen.getByRole('button', { name: 'Background button' }));
       expect(onBackgroundClick).toHaveBeenCalledTimes(1);