@northlight/ui 2.40.0 → 2.41.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@northlight/ui",
-  "version": "2.40.0",
+  "version": "2.41.0",
   "description": "Northlight UI library, based on Chakra-ui",
   "license": "MIT",
   "author": "Camphouse",
@@ -11,17 +11,23 @@
       "types": "./dist/es/northlight.d.ts",
       "import": "./dist/es/northlight.js",
       "require": "./dist/umd/northlight.cjs"
-    }
+    },
+    "./sandbox": "./sandbox/lib/index.ts"
+  },
+  "bin": {
+    "sandbox": "./sandbox/bin/sandbox.sh"
   },
   "main": "./dist/es/northlight.js",
   "types": "./dist/es/northlight.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "sandbox"
   ],
   "scripts": {
     "clean": "rm -rf dist",
-    "lint": "eslint --ext ts,tsx lib/ test/",
+    "lint": "eslint --ext ts,tsx lib/ test/ sandbox/ northlight-sandbox/",
     "prepublishOnly": "yarn clean && yarn transpile",
+    "sandbox": "./sandbox/bin/sandbox.sh northlight-sandbox/scenarios.tsx",
     "test": "yarn mtft test",
     "transpile": "rollup -c",
     "watch": "yarn transpile -w"
@@ -51,7 +57,7 @@
     "@react-aria/calendar": "^3.5.0",
     "@react-aria/checkbox": "^3.11.0",
     "@react-aria/datepicker": "^3.7.0",
-    "@react-aria/focus": "^3.14.1",
+    "@react-aria/focus": "3.14.1",
     "@react-aria/i18n": "^3.8.2",
     "@react-aria/radio": "^3.8.0",
     "@react-aria/utils": "^3.20.0",
@@ -65,6 +71,7 @@
     "@types/react-router-dom": "^5.3.2",
     "@types/react-virtualized-auto-sizer": "^1.0.1",
     "@types/react-window": "^1.8.5",
+    "@vitejs/plugin-react": "^4.3.0",
     "chakra-react-select": "4.7.2",
     "framer-motion": "^4",
     "joi": "^17.11.0",
@@ -78,6 +85,8 @@
     "react-virtualized-auto-sizer": "^1.0.20",
     "react-window": "^1.8.9",
     "sinon": "^15.2.0",
+    "tsx": "^4.21.0",
+    "vite": "^6.0.0",
     "yafu": "^2.1.4"
   },
   "devDependencies": {
@@ -101,12 +110,13 @@
     "rollup-plugin-dts": "^5.2.0",
     "rollup-plugin-esbuild": "^5.0.0",
     "sinon": "^15.2.0",
-    "typescript": "^5.2.2"
+    "typescript": "^5.2.2",
+    "vitest": "^2.0.0"
   },
   "peerDependencies": {
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0",
     "react-router-dom": "^5.0.0"
   },
-  "gitHead": "be842f0a8e2c4e7f67a5120dc8af4500ecf90686"
+  "gitHead": "fd559db249b74856dcf44ba2615913607647637a"
 }

package/sandbox/bin/sandbox.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+DIR="$(dirname "$0")"
+exec pnpx tsx "$DIR/sandbox.ts" "$@"

package/sandbox/bin/sandbox.ts

@@ -0,0 +1,133 @@
+/* eslint-disable no-restricted-syntax */
+import { existsSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import react from '@vitejs/plugin-react'
+import { createServer } from 'vite'
+
+const DEFAULT_SCENARIOS_PATHS = [ 'sandbox/scenarios.ts', 'sandbox/scenarios.tsx' ]
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+function findScenariosFile (cwd: string, scenariosArg?: string): string | undefined {
+  if (scenariosArg) {
+    const absolutePath = resolve(cwd, scenariosArg)
+    return existsSync(absolutePath) ? absolutePath : undefined
+  }
+  for (const path of DEFAULT_SCENARIOS_PATHS) {
+    const absolutePath = resolve(cwd, path)
+    if (existsSync(absolutePath)) return absolutePath
+  }
+  return undefined
+}
+
+async function main () {
+  const cwd = process.cwd()
+  const scenariosArg = process.argv[2]
+  const absoluteScenariosPath = findScenariosFile(cwd, scenariosArg)
+
+  if (!absoluteScenariosPath) {
+    console.error('Scenarios file not found.')
+    console.error(
+      scenariosArg
+        ? `Please check the path: ${resolve(cwd, scenariosArg)}`
+        : `Create one of: ${DEFAULT_SCENARIOS_PATHS.join(', ')}`
+    )
+    process.exit(1)
+  }
+
+  const sandboxPackageDir = resolve(__dirname, '..')
+
+  const virtualEntryId = 'virtual:sandbox-entry.tsx'
+  const resolvedVirtualEntryId = `\0${virtualEntryId}`
+
+  const virtualHtmlId = 'virtual:sandbox-html'
+
+  const server = await createServer({
+    configFile: false,
+    root: cwd,
+    server: {
+      port: 5000,
+      strictPort: false,
+    },
+    plugins: [
+      react(),
+      {
+        name: 'sandbox-virtual-entry',
+        resolveId (id) {
+          if (id === virtualEntryId) return resolvedVirtualEntryId
+          if (id === '/' || id === '/index.html') return virtualHtmlId
+          return undefined
+        },
+        load (id) {
+          if (id === resolvedVirtualEntryId) {
+            return `
+              import { createElement } from 'react'
+              import { createRoot } from 'react-dom/client'
+              import { SandboxViewer } from '${sandboxPackageDir}/lib/viewer/sandbox-viewer.tsx'
+              import { scenarios } from '${absoluteScenariosPath}'
+
+              const root = document.getElementById('root')
+              createRoot(root).render(createElement(SandboxViewer, { scenarios }))
+            `
+          }
+          if (id === virtualHtmlId) {
+            return `
+              <!DOCTYPE html>
+              <html>
+                <head>
+                  <meta charset="UTF-8" />
+                  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+                  <title>Sandbox</title>
+                </head>
+                <body>
+                  <div id="root"></div>
+                  <script type="module" src="/@id/__x00__${virtualEntryId}"></script>
+                </body>
+              </html>
+            `
+          }
+          return undefined
+        },
+      },
+      {
+        name: 'sandbox-html-middleware',
+        configureServer (devServer) {
+          devServer.middlewares.use((req, res, next) => {
+            const url = req.url ?? ''
+            const isAsset =
+              url.startsWith('/@') || url.startsWith('/node_modules') || url.includes('.')
+
+            if (!isAsset) {
+              const html = `
+                <!DOCTYPE html>
+                <html>
+                  <head>
+                    <meta charset="UTF-8" />
+                    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+                    <title>Sandbox</title>
+                  </head>
+                  <body>
+                    <div id="root"></div>
+                    <script type="module" src="/@id/__x00__${virtualEntryId}"></script>
+                  </body>
+                </html>
+              `
+              devServer.transformIndexHtml(url, html).then((transformed) => {
+                res.setHeader('Content-Type', 'text/html')
+                res.end(transformed)
+              })
+              return
+            }
+            next()
+          })
+        },
+      },
+    ],
+  })
+
+  await server.listen()
+  server.printUrls()
+}
+
+main()

package/sandbox/lib/index.ts

@@ -0,0 +1,3 @@
+export { runScenarios } from './run-scenarios'
+export type { ComponentScenarios, PlayContext, Scenario } from './types.ts'
+export { SandboxViewer } from './viewer/sandbox-viewer'

package/sandbox/lib/run-scenarios.ts

@@ -0,0 +1,60 @@
+/* eslint-disable no-restricted-syntax */
+import { cleanup, render, screen, within } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { createElement } from 'react'
+import { MediatoolThemeProvider, theme } from '../../lib'
+import type { ComponentScenarios, PlayContext } from './types.ts'
+
+declare const describe: (name: string, fn: () => void) => void
+declare const it: (name: string, fn: () => void | Promise<void>) => void
+
+if (typeof window !== 'undefined' && !window.matchMedia) {
+  window.matchMedia = (query: string) => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addListener: () => {},
+    removeListener: () => {},
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    dispatchEvent: () => false,
+  })
+}
+
+function runScenarios (allScenarios: ComponentScenarios[]): void {
+  for (const componentScenarios of allScenarios) {
+    const { name: componentName, component: defaultComponent, scenarios } = componentScenarios
+
+    describe(componentName, () => {
+      for (const scenario of scenarios) {
+        const { name: scenarioName, props, component: scenarioComponent, play } = scenario
+        const component = scenarioComponent ?? defaultComponent
+
+        it(scenarioName, async () => {
+          const user = userEvent.setup()
+          const { container } = render(
+            createElement(
+              MediatoolThemeProvider,
+              { theme },
+              createElement(component, props as Record<string, unknown>)
+            )
+          )
+
+          if (play) {
+            const context: PlayContext = {
+              screen: within(container),
+              documentScreen: screen,
+              user,
+              container,
+            }
+            await play(context)
+          }
+
+          cleanup()
+        })
+      }
+    })
+  }
+}
+
+export { runScenarios }

package/sandbox/lib/types.ts

@@ -0,0 +1,35 @@
+import type { screen, within } from '@testing-library/react'
+import type userEvent from '@testing-library/user-event'
+import type { ComponentType } from 'react'
+
+type PlayContext = {
+  /** Queries scoped to the scenario container - use for non-portaled content */
+  screen: ReturnType<typeof within>
+  /** Queries scoped to document.body - use for portaled content (dropdowns, modals) */
+  documentScreen: typeof screen
+  user: ReturnType<typeof userEvent.setup>
+  container: HTMLElement
+}
+
+type Scenario<P> =
+  | {
+    name: string
+    props: P
+    component?: undefined
+    play?: (context: PlayContext) => Promise<void>
+  }
+  | {
+    name: string
+    props: Record<string, unknown>
+    component: ComponentType<any>
+    play?: (context: PlayContext) => Promise<void>
+  }
+
+type ComponentScenarios<P = any> = {
+  name: string
+  component: ComponentType<P>
+  scenarios: Scenario<P>[]
+  inline?: boolean
+}
+
+export type { PlayContext, Scenario, ComponentScenarios }

package/sandbox/lib/viewer/error-boundary.tsx

@@ -0,0 +1,34 @@
+import { Component, type ComponentType, type ReactNode, createElement } from 'react'
+
+type ErrorBoundaryProps = {
+  children: ReactNode
+  fallback: ComponentType<{ error: Error }>
+}
+
+type ErrorBoundaryState = {
+  error: Error | null
+}
+
+class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  constructor (props: ErrorBoundaryProps) {
+    super(props)
+    this.state = { error: null }
+  }
+
+  static getDerivedStateFromError (error: Error): ErrorBoundaryState {
+    return { error }
+  }
+
+  render () {
+    const { error } = this.state
+    const { children, fallback } = this.props
+
+    if (error) {
+      return createElement(fallback, { error })
+    }
+
+    return children
+  }
+}
+
+export { ErrorBoundary }

package/sandbox/lib/viewer/sandbox-viewer.css

@@ -0,0 +1,328 @@
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  background: #f8fafc;
+}
+
+.sandbox-viewer {
+  display: flex;
+  height: 100vh;
+  font-family:
+    -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+  color: #1e293b;
+}
+
+.sandbox-sidebar {
+  width: 220px;
+  background: #ffffff;
+  border-right: 1px solid #e2e8f0;
+  padding: 20px 0;
+  overflow-y: auto;
+  flex-shrink: 0;
+}
+
+.sandbox-search {
+  padding: 0 12px 16px;
+}
+
+.sandbox-search-input {
+  width: 100%;
+  padding: 8px 12px;
+  font-size: 13px;
+  border: 1px solid #e2e8f0;
+  border-radius: 6px;
+  background: #f8fafc;
+  color: #1e293b;
+  outline: none;
+  transition: all 0.15s ease;
+}
+
+.sandbox-search-input::placeholder {
+  color: #94a3b8;
+}
+
+.sandbox-search-input:focus {
+  border-color: #7c3aed;
+  background: #ffffff;
+  box-shadow: 0 0 0 3px rgba(124, 58, 237, 0.1);
+}
+
+.sandbox-title {
+  font-size: 11px;
+  font-weight: 600;
+  text-transform: uppercase;
+  color: #94a3b8;
+  padding: 0 20px 16px;
+  letter-spacing: 0.08em;
+}
+
+.sandbox-component {
+  display: block;
+  width: 100%;
+  padding: 10px 20px;
+  background: none;
+  border: none;
+  text-align: left;
+  cursor: pointer;
+  font-size: 14px;
+  color: #475569;
+  transition: all 0.15s ease;
+}
+
+.sandbox-component:hover {
+  background: #f1f5f9;
+  color: #1e293b;
+}
+
+.sandbox-component.selected {
+  background: linear-gradient(to right, #ede9fe, #f1f5f9);
+  color: #6d28d9;
+  font-weight: 500;
+  border-left: 3px solid #7c3aed;
+  padding-left: 17px;
+}
+
+.sandbox-main {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  background: #f8fafc;
+}
+
+.sandbox-tabs {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  padding: 0 24px;
+  background: #ffffff;
+  border-bottom: 1px solid #e2e8f0;
+  min-height: 52px;
+  overflow-x: auto;
+  flex-wrap: wrap;
+}
+
+.sandbox-tab {
+  padding: 14px 16px;
+  min-width: 100px;
+  text-align: center;
+  background: none;
+  border: none;
+  border-bottom: 2px solid transparent;
+  cursor: pointer;
+  font-size: 13px;
+  font-weight: 500;
+  color: #64748b;
+  margin-bottom: -1px;
+  transition: all 0.15s ease;
+  border-radius: 6px 6px 0 0;
+}
+
+.sandbox-tab:hover {
+  color: #475569;
+  background: #f8fafc;
+}
+
+.sandbox-tab.selected {
+  color: #7c3aed;
+  border-bottom-color: #7c3aed;
+  background: none;
+}
+
+.sandbox-play {
+  margin-left: auto;
+  padding: 8px 16px;
+  background: linear-gradient(135deg, #7c3aed 0%, #6d28d9 100%);
+  color: white;
+  border: none;
+  border-radius: 6px;
+  cursor: pointer;
+  font-size: 13px;
+  font-weight: 500;
+  transition: all 0.15s ease;
+  box-shadow: 0 1px 2px rgba(124, 58, 237, 0.2);
+}
+
+.sandbox-play:hover {
+  background: linear-gradient(135deg, #6d28d9 0%, #5b21b6 100%);
+  box-shadow: 0 2px 4px rgba(124, 58, 237, 0.3);
+  transform: translateY(-1px);
+}
+
+.sandbox-play:disabled {
+  background: #cbd5e1;
+  cursor: not-allowed;
+  box-shadow: none;
+  transform: none;
+}
+
+.sandbox-preview {
+  flex: 1;
+  padding: 32px;
+  overflow: auto;
+}
+
+.sandbox-error {
+  background: #fef2f2;
+  border: 1px solid #fecaca;
+  border-radius: 8px;
+  padding: 20px;
+  font-family: system-ui, -apple-system, sans-serif;
+}
+
+.sandbox-error-title {
+  color: #dc2626;
+  font-weight: 600;
+  font-size: 14px;
+  margin-bottom: 12px;
+}
+
+.sandbox-error-message {
+  color: #b91c1c;
+  font-family: ui-monospace, monospace;
+  font-size: 13px;
+  margin: 0 0 12px;
+  padding: 12px;
+  background: #fff;
+  border-radius: 4px;
+  border: 1px solid #fecaca;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+.sandbox-error-stack {
+  color: #6b7280;
+  font-family: ui-monospace, monospace;
+  font-size: 11px;
+  margin: 0;
+  padding: 12px;
+  background: #fff;
+  border-radius: 4px;
+  border: 1px solid #e5e7eb;
+  white-space: pre-wrap;
+  word-break: break-word;
+  max-height: 300px;
+  overflow: auto;
+}
+
+.sandbox-inline {
+  flex: 1;
+  padding: 24px;
+  overflow: auto;
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+}
+
+.sandbox-inline-scenario {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+}
+
+.sandbox-inline-label {
+  font-size: 12px;
+  font-weight: 500;
+  color: #64748b;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  width: 100px;
+  flex-shrink: 0;
+}
+
+.sandbox-inline-preview {
+  flex: 1;
+  background: #ffffff;
+  border-radius: 8px;
+  padding: 16px;
+  border: 1px solid #e2e8f0;
+}
+
+.sandbox-play-slot {
+  width: 32px;
+  flex-shrink: 0;
+}
+
+.sandbox-play-inline {
+  width: 32px;
+  height: 32px;
+  padding: 0;
+  background: linear-gradient(135deg, #7c3aed 0%, #6d28d9 100%);
+  color: white;
+  border: none;
+  border-radius: 6px;
+  cursor: pointer;
+  font-size: 12px;
+  transition: all 0.15s ease;
+}
+
+.sandbox-play-inline:hover {
+  background: linear-gradient(135deg, #6d28d9 0%, #5b21b6 100%);
+  transform: translateY(-1px);
+}
+
+.sandbox-play-inline:disabled {
+  background: #cbd5e1;
+  cursor: not-allowed;
+  transform: none;
+}
+
+.sandbox-play-inline.error {
+  background: linear-gradient(135deg, #dc2626 0%, #b91c1c 100%);
+}
+
+.sandbox-play.error {
+  background: linear-gradient(135deg, #dc2626 0%, #b91c1c 100%);
+}
+
+.sandbox-play.error:hover {
+  background: linear-gradient(135deg, #b91c1c 0%, #991b1b 100%);
+}
+
+.sandbox-play-error {
+  margin-top: 16px;
+  background: #fef2f2;
+  border: 1px solid #fecaca;
+  border-radius: 8px;
+  padding: 16px;
+}
+
+.sandbox-play-error-title {
+  color: #dc2626;
+  font-weight: 600;
+  font-size: 13px;
+  margin-bottom: 8px;
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+
+.sandbox-play-error-title::before {
+  content: "✕";
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 18px;
+  height: 18px;
+  background: #dc2626;
+  color: white;
+  border-radius: 50%;
+  font-size: 10px;
+  font-weight: bold;
+}
+
+.sandbox-play-error-message {
+  color: #b91c1c;
+  font-family: ui-monospace, monospace;
+  font-size: 12px;
+  margin: 0;
+  padding: 10px;
+  background: #fff;
+  border-radius: 4px;
+  border: 1px solid #fecaca;
+  white-space: pre-wrap;
+  word-break: break-word;
+}

package/sandbox/lib/viewer/sandbox-viewer.tsx

@@ -0,0 +1,308 @@
+import { screen, within } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { type ComponentType, createElement, useEffect, useRef, useState } from 'react'
+import { MediatoolThemeProvider, theme } from '../../../lib'
+import type { ComponentScenarios, PlayContext, Scenario } from '../types'
+import { ErrorBoundary } from './error-boundary'
+import './sandbox-viewer.css'
+
+function RenderErrorFallback ({ error }: { error: Error }) {
+  return (
+    <div className="sandbox-error">
+      <div className="sandbox-error-title">Render Error</div>
+      <pre className="sandbox-error-message">{ error.message }</pre>
+      <pre className="sandbox-error-stack">{ error.stack }</pre>
+    </div>
+  )
+}
+
+type PlayError = {
+  scenarioName: string
+  error: Error
+}
+
+type InlineScenarioProps = {
+  scenario: Scenario<unknown>
+  component: ComponentType<unknown>
+  playingScenario: string | null
+  playError: PlayError | null
+  playKey: number
+  onPlay: (
+    scenario: { name: string, play?: (context: PlayContext) => Promise<void> },
+    getContainer: () => HTMLElement | null,
+  ) => void
+}
+
+function InlineScenario (
+  { scenario, component, playingScenario, playError, playKey, onPlay }: InlineScenarioProps
+) {
+  const ref = useRef<HTMLDivElement>(null)
+  const isPlaying = playingScenario === scenario.name
+  const hasError = playError?.scenarioName === scenario.name
+
+  return (
+    <div className="sandbox-inline-scenario">
+      <div className="sandbox-inline-label">{ scenario.name }</div>
+      <div className="sandbox-inline-preview" ref={ ref }>
+        <ErrorBoundary fallback={ RenderErrorFallback }>
+          <div key={ `${scenario.name}-${playKey}` }>
+            { createElement(
+              scenario.component ?? component,
+              scenario.props as Record<string, unknown>
+            ) }
+          </div>
+        </ErrorBoundary>
+        { hasError && (
+          <div className="sandbox-play-error">
+            <div className="sandbox-play-error-title">Play Error</div>
+            <pre className="sandbox-play-error-message">{ playError.error.message }</pre>
+          </div>
+        ) }
+      </div>
+      <div className="sandbox-play-slot">
+        { scenario.play && (
+          <button
+            type="button"
+            className={ `sandbox-play-inline ${hasError ? 'error' : ''}` }
+            onClick={ () => onPlay(scenario, () => ref.current) }
+            disabled={ isPlaying }
+          >
+            { isPlaying ? '...' : hasError ? '!' : '▶' }
+          </button>
+        ) }
+      </div>
+    </div>
+  )
+}
+
+type Selection = {
+  componentSlug: string
+  scenarioSlug: string
+}
+
+type SandboxViewerProps = {
+  scenarios: ComponentScenarios[]
+}
+
+function toSlug (name: string): string {
+  return name.toLowerCase().replace(/\s+/g, '-')
+}
+
+function parsePath (): Selection | null {
+  const path = window.location.pathname
+  const parts = path.split('/').filter(Boolean)
+  if (parts.length === 0) return null
+  return {
+    componentSlug: parts[0],
+    scenarioSlug: parts[1] ?? '',
+  }
+}
+
+function toPath (componentSlug: string, scenarioSlug: string): string {
+  return `/${componentSlug}/${scenarioSlug}`
+}
+
+function SandboxViewerContent ({ scenarios }: SandboxViewerProps) {
+  const [ selection, setSelection ] = useState<Selection | null>(parsePath)
+  const [ playingScenario, setPlayingScenario ] = useState<string | null>(null)
+  const [ playError, setPlayError ] = useState<PlayError | null>(null)
+  const [ playKey, setPlayKey ] = useState(0)
+  const [ search, setSearch ] = useState('')
+  const containerRef = useRef<HTMLDivElement>(null)
+
+  const filteredScenarios = search
+    ? scenarios.filter((c) => {
+      const searchTerms = search.toLowerCase().split(/\s+/).filter(Boolean)
+      const nameWords = c.name.toLowerCase().split(/\s+/)
+      return searchTerms.every((term) =>
+        nameWords.some((word) => word.startsWith(term))
+      )
+    })
+    : scenarios
+
+  useEffect(() => {
+    const handlePopState = () => setSelection(parsePath())
+    window.addEventListener('popstate', handlePopState)
+    return () => window.removeEventListener('popstate', handlePopState)
+  }, [])
+
+  const navigate = (componentSlug: string, scenarioSlug: string) => {
+    const path = toPath(componentSlug, scenarioSlug)
+    window.history.pushState(null, '', path)
+    setSelection({ componentSlug, scenarioSlug })
+  }
+
+  const handleSelectComponent = (component: ComponentScenarios<unknown>) => {
+    const componentSlug = toSlug(component.name)
+    const firstScenario = component.scenarios[0]
+    const scenarioSlug = firstScenario ? toSlug(firstScenario.name) : ''
+    navigate(componentSlug, scenarioSlug)
+  }
+
+  const handleSelectScenario = (scenarioName: string) => {
+    if (!selection) return
+    navigate(selection.componentSlug, toSlug(scenarioName))
+  }
+
+  const selectedComponent = selection
+    ? scenarios.find((c) => toSlug(c.name) === selection.componentSlug)
+    : null
+
+  const selectedScenario =
+    selectedComponent && selection?.scenarioSlug
+      ? selectedComponent.scenarios.find((s) => toSlug(s.name) === selection.scenarioSlug)
+      : selectedComponent?.scenarios[0]
+
+  const selectionKey =
+    selectedComponent && selectedScenario
+      ? `${selectedComponent.name}/${selectedScenario.name}/${playKey}`
+      : ''
+
+  const handlePlay = async (
+    scenario: { name: string, play?: (context: PlayContext) => Promise<void> },
+    getContainer: () => HTMLElement | null
+  ) => {
+    if (!scenario.play) return
+
+    // Clear previous error and reset component
+    setPlayError(null)
+    setPlayKey((k) => k + 1)
+
+    // Wait for component to remount
+    await new Promise((resolve) => {
+      setTimeout(resolve, 50)
+    })
+
+    setPlayingScenario(scenario.name)
+
+    const container = getContainer()
+    if (!container) return
+
+    const user = userEvent.setup()
+    const context: PlayContext = {
+      screen: within(container),
+      documentScreen: screen,
+      user,
+      container,
+    }
+
+    try {
+      await scenario.play(context)
+    } catch (err) {
+      setPlayError({
+        scenarioName: scenario.name,
+        error: err instanceof Error ? err : new Error(String(err)),
+      })
+    }
+
+    setPlayingScenario(null)
+  }
+
+  return (
+    <div className="sandbox-viewer">
+      <nav className="sandbox-sidebar">
+        <div className="sandbox-search">
+          <input
+            type="text"
+            className="sandbox-search-input"
+            placeholder="Search..."
+            value={ search }
+            onChange={ (e) => setSearch(e.target.value) }
+          />
+        </div>
+        <div className="sandbox-title">Components</div>
+        { filteredScenarios.map((component) => (
+          <button
+            type="button"
+            key={ component.name }
+            className={
+              selection?.componentSlug === toSlug(component.name)
+                ? 'sandbox-component selected'
+                : 'sandbox-component'
+            }
+            onClick={ () => handleSelectComponent(component) }
+          >
+            { component.name }
+          </button>
+        )) }
+      </nav>
+      <main className="sandbox-main">
+        { selectedComponent &&
+          (selectedComponent.inline ? (
+            <div className="sandbox-inline">
+              { selectedComponent.scenarios.map((scenario) => (
+                <InlineScenario
+                  key={ scenario.name }
+                  scenario={ scenario }
+                  component={ selectedComponent.component }
+                  playingScenario={ playingScenario }
+                  playError={ playError }
+                  playKey={ playKey }
+                  onPlay={ handlePlay }
+                />
+              )) }
+            </div>
+          ) : (
+            <>
+              <div className="sandbox-tabs">
+                { selectedComponent.scenarios.map((scenario) => (
+                  <button
+                    type="button"
+                    key={ scenario.name }
+                    className={
+                      selectedScenario?.name === scenario.name
+                        ? 'sandbox-tab selected'
+                        : 'sandbox-tab'
+                    }
+                    onClick={ () => handleSelectScenario(scenario.name) }
+                  >
+                    { scenario.name }
+                  </button>
+                )) }
+                { selectedScenario?.play && (
+                  <button
+                    type="button"
+                    className={ `sandbox-play ${playError?.scenarioName === selectedScenario.name ? 'error' : ''}` }
+                    onClick={ () => handlePlay(selectedScenario, () => containerRef.current) }
+                    disabled={ playingScenario === selectedScenario.name }
+                  >
+                    { playingScenario === selectedScenario.name
+                      ? 'Playing...'
+                      : playError?.scenarioName === selectedScenario.name
+                        ? 'Failed'
+                        : 'Play' }
+                  </button>
+                ) }
+              </div>
+              <div className="sandbox-preview" ref={ containerRef } key={ selectionKey }>
+                { selectedScenario && (
+                  <ErrorBoundary fallback={ RenderErrorFallback }>
+                    { createElement(
+                      selectedScenario.component ?? selectedComponent.component,
+                      selectedScenario.props as Record<string, unknown>
+                    ) }
+                  </ErrorBoundary>
+                ) }
+                { playError?.scenarioName === selectedScenario?.name && playError && (
+                  <div className="sandbox-play-error">
+                    <div className="sandbox-play-error-title">Play Error</div>
+                    <pre className="sandbox-play-error-message">{ playError.error.message }</pre>
+                  </div>
+                ) }
+              </div>
+            </>
+          )) }
+      </main>
+    </div>
+  )
+}
+
+function SandboxViewer ({ scenarios }: SandboxViewerProps) {
+  return (
+    <MediatoolThemeProvider theme={ theme }>
+      <SandboxViewerContent scenarios={ scenarios } />
+    </MediatoolThemeProvider>
+  )
+}
+
+export { SandboxViewer, toSlug }