feat(ui): Introduce mosaic recipes and conditions

.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);

packages/swingset/src/app/[group]/[component]/page.tsx

@@ -0,0 +1,15 @@
+import { DocsViewer } from '@/components/DocsViewer';
+
+interface Props {
+  params: Promise<{ group: string; component: string }>;
+}
+
+export default async function ComponentPage({ params }: Props) {
+  const { group, component } = await params;
+  return (
+    <DocsViewer
+      group={group}
+      slug={component}
+    />
+  );
+}

packages/swingset/src/components/ClientRoot.tsx

@@ -19,12 +19,10 @@ import { ThemeToggle } from './ThemeToggle';
 
 function useBreadcrumb() {
   const pathname = usePathname();
-  // /components/button        → ["Button"]
-  // /components/button/primary → ["Button", "Primary"]
-  const parts = pathname
-    .replace(/^\/components\//, '')
-    .split('/')
-    .filter(Boolean);
+  // /components/button → ["Button"]
+  // /primitives/dialog → ["Dialog"]
+  // The first segment is the group; drop it and surface the component (plus any sub-path).
+  const parts = pathname.split('/').filter(Boolean).slice(1);
   return parts.map(p => p.charAt(0).toUpperCase() + p.slice(1).replace(/-/g, ' '));
 }
 

packages/swingset/src/components/DocsViewer.tsx

@@ -2,40 +2,52 @@
 
 import dynamic from 'next/dynamic';
 
-import { getModuleBySlug } from '@/lib/registry';
+import { getModule } from '@/lib/registry';
 
 import { PlaygroundProvider } from './PlaygroundContext';
 import { ViewSource } from './ViewSource';
 
-const docModules: Record<string, React.ComponentType> = {
-  button: dynamic(() => import('../stories/button.mdx')),
-  input: dynamic(() => import('../stories/input.mdx')),
-  // Headless primitives — alphabetical.
-  accordion: dynamic(() => import('../stories/accordion.mdx')),
-  autocomplete: dynamic(() => import('../stories/autocomplete.mdx')),
-  collapsible: dynamic(() => import('../stories/collapsible.mdx')),
-  dialog: dynamic(() => import('../stories/dialog.mdx')),
-  menu: dynamic(() => import('../stories/menu.mdx')),
-  popover: dynamic(() => import('../stories/popover.mdx')),
-  select: dynamic(() => import('../stories/select.mdx')),
-  tabs: dynamic(() => import('../stories/tabs.mdx')),
-  tooltip: dynamic(() => import('../stories/tooltip.mdx')),
+// MDX docs keyed by `group` slug → `component` slug. Group-aware so identically-named
+// entries (the headless `Dialog` primitive vs. the styled `Dialog` component) stay distinct.
+const docModules: Record<string, Record<string, React.ComponentType>> = {
+  components: {
+    button: dynamic(() => import('../stories/button.mdx')),
+    input: dynamic(() => import('../stories/input.mdx')),
+    dialog: dynamic(() => import('../stories/dialog.component.mdx')),
+  },
+  primitives: {
+    // Headless primitives — alphabetical.
+    accordion: dynamic(() => import('../stories/accordion.mdx')),
+    autocomplete: dynamic(() => import('../stories/autocomplete.mdx')),
+    collapsible: dynamic(() => import('../stories/collapsible.mdx')),
+    dialog: dynamic(() => import('../stories/dialog.mdx')),
+    menu: dynamic(() => import('../stories/menu.mdx')),
+    popover: dynamic(() => import('../stories/popover.mdx')),
+    select: dynamic(() => import('../stories/select.mdx')),
+    tabs: dynamic(() => import('../stories/tabs.mdx')),
+    tooltip: dynamic(() => import('../stories/tooltip.mdx')),
+  },
 };
 
 interface DocsViewerProps {
+  group: string;
   slug: string;
 }
 
-export function DocsViewer({ slug }: DocsViewerProps) {
-  const DocContent = docModules[slug];
+export function DocsViewer({ group, slug }: DocsViewerProps) {
+  const DocContent = docModules[group]?.[slug];
   if (!DocContent) {
-    return <div className='text-muted-foreground p-8 text-sm'>No docs found for &quot;{slug}&quot;.</div>;
+    return (
+      <div className='text-muted-foreground p-8 text-sm'>
+        No docs found for &quot;{group}/{slug}&quot;.
+      </div>
+    );
   }
-  const meta = getModuleBySlug(slug)?.meta;
+  const meta = getModule(group, slug)?.meta;
   return (
-    // Keyed by slug so navigating between components resets the playground state.
+    // Keyed by group/slug so navigating between components resets the playground state.
     <PlaygroundProvider
-      key={slug}
+      key={`${group}/${slug}`}
       meta={meta}
     >
       <article className='prose relative mx-auto w-full min-w-0 max-w-3xl p-8'>