feat(swingset): add mosaic Dialog story with group-aware routing

Adds a styled mosaic Dialog story (Components) that uses a Button as the
trigger via the render prop. Routes are now group-aware (/components/<c>
and /primitives/<c>) so the styled Dialog and the headless Dialog primitive
no longer collide on a title-only slug.

Author: alexcarpenter

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/app/components/[component]/page.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/ClientRoot.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'>

packages/swingset/src/components/DocsViewer.tsx

@@ -58,7 +58,7 @@ export function AppSidebar({ ...props }: React.ComponentProps<typeof Sidebar>) {
         <span className='text-sidebar-foreground/70 text-[10px] font-medium'>Mosaic - Swingset</span>
       </SidebarHeader>
       <SidebarContent className='gap-0'>
-        {groups.map(({ group, components }) => (
+        {groups.map(({ group, groupSlug, components }) => (
           <SidebarGroup
             key={group}
             className='py-1'
@@ -70,7 +70,7 @@ export function AppSidebar({ ...props }: React.ComponentProps<typeof Sidebar>) {
             <SidebarGroupContent>
               <SidebarMenu>
                 {components.map(({ mod, componentSlug }) => {
-                  const href = `/components/${componentSlug}`;
+                  const href = `/${groupSlug}/${componentSlug}`;
                   return (
                     <SidebarMenuItem key={mod.meta.title}>
                       <SidebarMenuButton

packages/swingset/src/components/app-sidebar.tsx

@@ -124,7 +124,10 @@ function SidebarProvider({
             ...style,
           } as React.CSSProperties
         }
-        className={cn('group/sidebar-wrapper has-data-[variant=inset]:bg-sidebar flex min-h-svh w-full', className)}
+        className={cn(
+          'group/sidebar-wrapper has-data-[variant=inset]:bg-sidebar isolate flex min-h-svh w-full',
+          className,
+        )}
         {...props}
       >
         {children}

packages/swingset/src/components/ui/sidebar.tsx

@@ -3,6 +3,7 @@ import { meta as accordionMeta } from '../stories/accordion.stories';
 import { meta as autocompleteMeta } from '../stories/autocomplete.stories';
 import { Disabled, meta as buttonMeta, Primary, Sizes } from '../stories/button.stories';
 import { meta as collapsibleMeta } from '../stories/collapsible.stories';
+import { Default as DialogDefault, meta as dialogComponentMeta } from '../stories/dialog.component.stories';
 import { meta as dialogMeta } from '../stories/dialog.stories';
 import {
   Default,
@@ -23,6 +24,8 @@ const buttonModule: StoryModule = { meta: buttonMeta, Primary, Sizes, Disabled }
 
 const inputModule: StoryModule = { meta: inputMeta, Default, Sizes: InputSizes, Disabled: InputDisabled, Invalid };
 
+const dialogComponentModule: StoryModule = { meta: dialogComponentMeta, Default: DialogDefault };
+
 // Headless primitives carry just `meta` (no story functions). Like every component
 // they're documented as a single overview page; their live demos come from `<Story>` /
 // `<Preview>` embeds in the MDX, which import the stories module directly.
@@ -39,6 +42,7 @@ const tooltipModule: StoryModule = { meta: tooltipMeta };
 export const registry: StoryModule[] = [
   buttonModule,
   inputModule,
+  dialogComponentModule,
   // Primitives — alphabetical within the group.
   accordionModule,
   autocompleteModule,
@@ -51,13 +55,18 @@ export const registry: StoryModule[] = [
   tooltipModule,
 ];
 
-/** Look up a component's story module from its slug (derived from `meta.title`). */
-export function getModuleBySlug(slug: string): StoryModule | undefined {
-  return registry.find(mod => toSlug(mod.meta.title) === slug);
+/**
+ * Look up a component's story module by its group + component slug (both derived from `meta`).
+ * Group-aware so identically-titled entries in different groups (e.g. the headless `Dialog`
+ * primitive and the styled `Dialog` component) resolve to distinct pages.
+ */
+export function getModule(groupSlug: string, componentSlug: string): StoryModule | undefined {
+  return registry.find(mod => toSlug(mod.meta.group) === groupSlug && toSlug(mod.meta.title) === componentSlug);
 }
 
 export function getSidebarGroups(): Array<{
   group: string;
+  groupSlug: string;
   components: Array<{ mod: StoryModule; componentSlug: string }>;
 }> {
   const groupMap = new Map<string, Array<{ mod: StoryModule; componentSlug: string }>>();
@@ -70,5 +79,9 @@ export function getSidebarGroups(): Array<{
     groupMap.get(group)?.push({ mod, componentSlug: toSlug(title) });
   }
 
-  return Array.from(groupMap.entries()).map(([group, components]) => ({ group, components }));
+  return Array.from(groupMap.entries()).map(([group, components]) => ({
+    group,
+    groupSlug: toSlug(group),
+    components,
+  }));
 }

packages/swingset/src/lib/registry.ts

@@ -0,0 +1,63 @@
+import * as DialogStories from './dialog.component.stories';
+
+# Dialog
+
+The styled Mosaic `Dialog` — the headless `@clerk/headless` dialog primitives composed with
+Mosaic slot recipes. It inherits open state, portalling, focus management, dismissal (outside
+press / Escape), and ARIA wiring from the primitive, and adds Mosaic's themed styling for each
+part. Slot identity (`data-cl-slot`) is applied by this styled layer, not by the headless parts.
+
+## Example
+
+The trigger below is a Mosaic `Button`, wired in through the trigger's `render` prop. Open it,
+then press Escape or click the backdrop to dismiss.
+
+<Story
+  name='Default'
+  storyModule={DialogStories}
+/>
+
+## Usage
+
+```tsx
+import { Button } from '@clerk/ui/mosaic/components/button';
+import { Dialog } from '@clerk/ui/mosaic/components/dialog';
+
+<Dialog.Root>
+  <Dialog.Trigger render={props => <Button {...props}>Open dialog</Button>} />
+  <Dialog.Portal>
+    <Dialog.Backdrop />
+    <Dialog.Viewport>
+      <Dialog.Popup>
+        <Dialog.Title>Confirm action</Dialog.Title>
+        <Dialog.Description>Are you sure you want to proceed?</Dialog.Description>
+        <Dialog.Close>Cancel</Dialog.Close>
+      </Dialog.Popup>
+    </Dialog.Viewport>
+  </Dialog.Portal>
+</Dialog.Root>;
+```
+
+Any part accepts a `render` prop for polymorphic rendering — pass a function that receives the
+part's computed props and spreads them onto your element, as the trigger does with `Button`.
+
+## Parts
+
+| Part                 | Slot                 | Description                                             |
+| -------------------- | -------------------- | ------------------------------------------------------- |
+| `Dialog.Root`        | none (context)       | Owns open state, ARIA ids, and the transition lifecycle |
+| `Dialog.Trigger`     | `dialog-trigger`     | Toggles the dialog open on click                        |
+| `Dialog.Portal`      | none (portal)        | Portals its children; renders nothing until mounted     |
+| `Dialog.Backdrop`    | `dialog-backdrop`    | Themed overlay behind the dialog                        |
+| `Dialog.Viewport`    | `dialog-viewport`    | Fixed centering container; owns scroll lock             |
+| `Dialog.Popup`       | `dialog-popup`       | The dialog surface (`role="dialog"`, focus-trapped)     |
+| `Dialog.Title`       | `dialog-title`       | Heading; wired to the popup's `aria-labelledby`         |
+| `Dialog.Description` | `dialog-description` | Description; wired to the popup's `aria-describedby`    |
+| `Dialog.Close`       | `dialog-close`       | Closes the dialog on click                              |
+
+## Styling
+
+Each styled part is themed by the Mosaic dialog recipe and stays targetable through its
+`data-cl-slot` plus the state attributes the primitive emits (`data-cl-open`,
+`data-cl-starting-style`, `data-cl-ending-style`). Override per slot through
+`appearance.elements` — e.g. `{ 'dialog-popup': { borderRadius: 24 } }`.

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

@@ -0,0 +1,32 @@
+/** @jsxImportSource @emotion/react */
+import { Button } from '@clerk/ui/mosaic/components/button';
+import { Dialog } from '@clerk/ui/mosaic/components/dialog';
+import type { HTMLAttributes } from 'react';
+
+import type { StoryMeta } from '@/lib/types';
+
+export const meta: StoryMeta = {
+  group: 'Components',
+  title: 'Dialog',
+  source: 'packages/ui/src/mosaic/components/dialog.tsx',
+};
+
+export function Default() {
+  return (
+    <Dialog.Root>
+      <Dialog.Trigger
+        render={(props: Omit<HTMLAttributes<HTMLElement>, 'color'>) => <Button {...props}>Open dialog</Button>}
+      />
+      <Dialog.Portal>
+        <Dialog.Backdrop />
+        <Dialog.Viewport>
+          <Dialog.Popup>
+            <Dialog.Title>Confirm action</Dialog.Title>
+            <Dialog.Description>Are you sure you want to proceed? This action cannot be undone.</Dialog.Description>
+            <Dialog.Close>Cancel</Dialog.Close>
+          </Dialog.Popup>
+        </Dialog.Viewport>
+      </Dialog.Portal>
+    </Dialog.Root>
+  );
+}