@sntlr/registry-shell 1.0.0

package/src/next-app/components/sidebar.tsx

@@ -0,0 +1,222 @@
+"use client"
+
+import Link from "next/link"
+import { usePathname } from "next/navigation"
+import { useEffect, useRef } from "react"
+import { useIsMobile } from "@shell/hooks/use-mobile"
+import { BookOpen, Component, Blocks } from "lucide-react"
+import type { DocMeta } from "@shell/lib/docs"
+import type { ComponentMeta } from "@shell/lib/components-nav"
+import { useTranslations, useLocale } from "@shell/lib/i18n"
+import { Backdrop } from "@shell/components/shell-ui/backdrop"
+
+import type { ActiveSection } from "@shell/hooks/use-active-section"
+
+interface SidebarProps {
+  docs: DocMeta[]
+  components: ComponentMeta[]
+  open?: boolean
+  onClose?: () => void
+  collapsed?: boolean
+  /** When set, desktop views show only this section. Mobile always shows all three. */
+  activeSection?: ActiveSection
+  /**
+   * Which viewport variants of the sidebar to render.
+   * - `"all"` (default): mobile floating card + desktop inline + desktop floating (current behavior).
+   * - `"mobile"`: only the mobile floating card + backdrop. Used by the root layout so the
+   *   hamburger menu works on every page (including the homepage), without injecting a
+   *   desktop sidebar on pages that don't have one.
+   * - `"desktop"`: only the desktop inline + desktop floating card. Used by `SidebarLayout`
+   *   so the per-section docs/components pages still get their desktop nav, while the
+   *   root layout owns the mobile variant.
+   */
+  display?: "all" | "mobile" | "desktop"
+}
+
+export function Sidebar({ docs, components, open, onClose, collapsed, activeSection, display = "all" }: SidebarProps) {
+  const pathname = usePathname()
+  const t = useTranslations()
+  const { locale } = useLocale()
+
+  const isMobile = useIsMobile()
+  const uiComponents = components.filter((c) => c.kind === "component")
+  const blocks = components.filter((c) => c.kind === "block")
+
+  // Close floating nav on mobile navigation only
+  const isMobileRef = useRef(isMobile)
+  isMobileRef.current = isMobile
+  const mountedRef = useRef(false)
+  useEffect(() => {
+    if (!mountedRef.current) { mountedRef.current = true; return }
+    if (isMobileRef.current) onClose?.()
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- only trigger on pathname change
+  }, [pathname])
+
+  const docsSection = (
+    <SidebarSection icon={BookOpen} title={t("sidebar.documentation")}>
+      {docs.map((doc) => (
+        <SidebarLink
+          key={doc.slug}
+          href={`/docs/${doc.slug}`}
+          active={pathname === `/docs/${doc.slug}`}
+        >
+          {doc.titles?.[locale] ?? doc.title}
+        </SidebarLink>
+      ))}
+    </SidebarSection>
+  )
+
+  const componentsSection = (
+    <SidebarSection icon={Component} title={t("sidebar.components")}>
+      {uiComponents.map((comp) => (
+        <SidebarLink
+          key={comp.name}
+          href={`/components/${comp.name}`}
+          active={pathname === `/components/${comp.name}`}
+        >
+          {comp.label}
+        </SidebarLink>
+      ))}
+    </SidebarSection>
+  )
+
+  const blocksSection = blocks.length > 0 ? (
+    <SidebarSection icon={Blocks} title={t("sidebar.blocks")}>
+      {blocks.map((comp) => (
+        <SidebarLink
+          key={comp.name}
+          href={`/components/${comp.name}`}
+          active={pathname === `/components/${comp.name}`}
+        >
+          {comp.label}
+        </SidebarLink>
+      ))}
+    </SidebarSection>
+  ) : null
+
+  // Mobile: always show all three sections (no topbar tabs on mobile)
+  const mobileNavContent = (
+    <nav aria-label="Main navigation" className="p-4 space-y-4">
+      {docsSection}
+      {componentsSection}
+      {blocksSection}
+    </nav>
+  )
+
+  // Desktop: show only the active section (topbar tabs handle section switching)
+  const desktopNavContent = (
+    <nav aria-label="Main navigation" className="p-4 space-y-4">
+      {activeSection === "docs" && docsSection}
+      {activeSection === "components" && componentsSection}
+      {activeSection === "blocks" && blocksSection}
+      {/* Fallback: when we can't determine a section, show all */}
+      {activeSection === null && (
+        <>
+          {docsSection}
+          {componentsSection}
+          {blocksSection}
+        </>
+      )}
+    </nav>
+  )
+
+  const showMobile = display === "all" || display === "mobile"
+  const showDesktop = display === "all" || display === "desktop"
+
+  return (
+    <>
+      {/* Backdrop — mobile nav only (no backdrop in desktop fullscreen) */}
+      {showMobile && open && !collapsed && (
+        <Backdrop
+          belowHeader
+          className="md:hidden"
+          onClick={onClose}
+        />
+      )}
+
+      {/* Mobile floating card — mobile only */}
+      {showMobile && (
+        <aside
+          className={`
+            md:hidden fixed top-18 left-4 z-50 w-64 rounded-lg border border-border bg-background shadow-xl overflow-y-auto overflow-x-hidden transition-all duration-300 ease-in-out motion-reduce:transition-none
+            ${open ? "opacity-100 translate-y-0" : "opacity-0 -translate-y-2 pointer-events-none"}
+          `}
+          style={{ maxHeight: "calc(100vh - 6rem)" }}
+        >
+          {mobileNavContent}
+        </aside>
+      )}
+
+      {/* Desktop floating card — only meaningful on component pages where the
+          user can enter fullscreen preview mode. On other sections the
+          fullscreen state is moot and the floating card just looks out of
+          place; skip rendering it entirely. */}
+      {showDesktop &&
+        (activeSection === "components" || activeSection === "blocks") && (
+          <aside
+            className={`
+            hidden md:block fixed top-18 left-4 z-50 w-64 rounded-lg border border-border bg-background shadow-xl overflow-y-auto overflow-x-hidden transition-all duration-300 ease-in-out motion-reduce:transition-none
+            ${open && collapsed ? "opacity-100 translate-y-0" : "opacity-0 -translate-y-2 pointer-events-none"}
+          `}
+            style={{ maxHeight: "calc(100vh - 6rem)" }}
+          >
+            {desktopNavContent}
+          </aside>
+        )}
+
+      {/* Desktop inline sidebar — only when not collapsed */}
+      {showDesktop && !collapsed && (
+        <aside
+          className="hidden md:block w-64 border-r border-border bg-background h-[calc(100vh-3.5rem)] overflow-y-auto overflow-x-hidden sticky top-14 shrink-0"
+        >
+          {desktopNavContent}
+        </aside>
+      )}
+    </>
+  )
+}
+
+function SidebarSection({
+  icon: Icon,
+  title,
+  children,
+}: {
+  icon: React.ComponentType<{ className?: string }>
+  title: string
+  children: React.ReactNode
+}) {
+  return (
+    <div>
+      <div className="flex items-center gap-2 text-sm font-semibold text-foreground mb-2">
+        <Icon className="size-4" />
+        <span className="flex-1 text-left">{title}</span>
+      </div>
+      <ul className="space-y-1">{children}</ul>
+    </div>
+  )
+}
+
+function SidebarLink({
+  href,
+  active,
+  children,
+}: {
+  href: string
+  active: boolean
+  children: React.ReactNode
+}) {
+  return (
+    <li>
+      <Link
+        href={href}
+        className={`block text-sm px-2 py-1.5 rounded-md transition-colors ${
+          active
+            ? "bg-accent text-accent-foreground font-medium"
+            : "text-muted-foreground hover:text-foreground hover:bg-accent/50"
+        }`}
+      >
+        {children}
+      </Link>
+    </li>
+  )
+}

package/src/next-app/components/snapshot-preview.tsx

@@ -0,0 +1,28 @@
+"use client"
+
+import { SnapshotModeProvider } from "@shell/components/preview-layout"
+import { previewLoader } from "@shell/lib/preview-loader"
+
+const { Preview } = previewLoader
+
+/**
+ * Renders a component preview without the PreviewCanvas chrome.
+ * The preview components still use PreviewLayout internally, but this page
+ * provides a clean, minimal container for Playwright screenshots.
+ *
+ * Usage: /preview-snapshot/{component-name}
+ */
+export function SnapshotPreview({ name }: { name: string }) {
+  return (
+    <SnapshotModeProvider>
+      <div data-snapshot-target className="inline-block">
+        <Preview
+          name={name}
+          fallback={
+            <p className="text-sm text-muted-foreground">No preview for {name}</p>
+          }
+        />
+      </div>
+    </SnapshotModeProvider>
+  )
+}

package/src/next-app/components/test-info.tsx

@@ -0,0 +1,155 @@
+"use client"
+
+import { useEffect, useState } from "react"
+import { CheckCircle2, XCircle, FlaskConical, Eye, Keyboard, Gauge, Shield } from "lucide-react"
+import { Badge } from "@shell/components/shell-ui/badge"
+import {
+  Accordion,
+  AccordionContent,
+  AccordionItem,
+  AccordionTrigger,
+} from "@shell/components/shell-ui/accordion"
+import {
+  EmptyState,
+  EmptyStateIcon,
+  EmptyStateDescription,
+} from "@shell/components/shell-ui/empty-state"
+import { useTranslations } from "@shell/lib/i18n"
+
+interface TestFile {
+  file: string
+  type: string
+  tests: string[]
+}
+
+interface TestReport {
+  component: string
+  hasUnitTests: boolean
+  hasInteractionTests: boolean
+  hasVisualTests: boolean
+  hasA11yTests: boolean
+  hasPerformanceTests: boolean
+  hasProps: boolean
+  hasA11yDocs: boolean
+  hasPreview: boolean
+  testFiles: TestFile[]
+  totalTests: number
+}
+
+const typeIcons: Record<string, React.ComponentType<{ className?: string }>> = {
+  unit: FlaskConical,
+  interaction: Keyboard,
+  visual: Eye,
+  a11y: Shield,
+  performance: Gauge,
+}
+
+function CheckItem({ passed, label }: { passed: boolean; label: string }) {
+  return (
+    <div className="flex items-center gap-2 text-sm">
+      {passed ? (
+        <CheckCircle2 className="size-4 text-green-500 shrink-0" />
+      ) : (
+        <XCircle className="size-4 text-muted-foreground/40 shrink-0" />
+      )}
+      <span className={passed ? "text-foreground" : "text-muted-foreground"}>
+        {label}
+      </span>
+    </div>
+  )
+}
+
+export function TestInfo({ name }: { name: string }) {
+  const [report, setReport] = useState<TestReport | null>(null)
+  const [error, setError] = useState(false)
+  const t = useTranslations()
+
+  useEffect(() => {
+    fetch(`/tests/${name}.json`)
+      .then((r) => {
+        if (!r.ok) throw new Error()
+        return r.json()
+      })
+      .then(setReport)
+      .catch(() => setError(true))
+  }, [name])
+
+  if (error) {
+    return (
+      <EmptyState>
+        <EmptyStateIcon><FlaskConical /></EmptyStateIcon>
+        <EmptyStateDescription>{t("component.testsPlaceholder")}</EmptyStateDescription>
+      </EmptyState>
+    )
+  }
+
+  if (!report) {
+    return <p className="text-sm text-muted-foreground" role="status">{t("a11y.loading")}</p>
+  }
+
+  const hasAnyTests = report.totalTests > 0
+
+  return (
+    <div className="space-y-6">
+      {/* Health overview */}
+      <div className="space-y-3">
+        <h4 id="test-health" className="text-base font-semibold">{t("tests.health")}</h4>
+        <div className="grid grid-cols-2 gap-2">
+          <CheckItem passed={report.hasProps} label={t("tests.propsDocs")} />
+          <CheckItem passed={report.hasA11yDocs} label={t("tests.a11yDocs")} />
+          <CheckItem passed={report.hasPreview} label={t("tests.preview")} />
+          <CheckItem passed={report.hasUnitTests} label={t("tests.unit")} />
+          <CheckItem passed={report.hasInteractionTests} label={t("tests.interaction")} />
+          <CheckItem passed={report.hasVisualTests} label={t("tests.visual")} />
+          <CheckItem passed={report.hasA11yTests} label={t("tests.accessibility")} />
+          <CheckItem passed={report.hasPerformanceTests} label={t("tests.performance")} />
+        </div>
+      </div>
+
+      {hasAnyTests && (
+        <div className="space-y-3">
+          <h4 id="test-coverage" className="text-base font-semibold">
+            {t("tests.tests")}
+            <Badge variant="secondary" className="ml-2">{report.totalTests}</Badge>
+          </h4>
+
+          <Accordion type="multiple" defaultValue={report.testFiles.map((f) => f.type)}>
+            {report.testFiles.map((tf) => {
+              const Icon = typeIcons[tf.type] ?? FlaskConical
+
+              return (
+                <AccordionItem key={tf.file} value={tf.type}>
+                  <AccordionTrigger>
+                    <div className="flex items-center gap-2">
+                      <Icon className="size-4 text-muted-foreground" />
+                      <span>{t(`tests.${tf.type}` as string)}</span>
+                      <Badge variant="outline" className="text-[10px]">{tf.tests.length}</Badge>
+                    </div>
+                  </AccordionTrigger>
+                  <AccordionContent>
+                    <p className="text-xs text-muted-foreground font-mono mb-2">{tf.file}</p>
+                    <ul className="space-y-1">
+                      {tf.tests.map((test, i) => (
+                        <li key={i} className="text-sm text-muted-foreground flex items-center gap-2">
+                          <CheckCircle2 className="size-3 text-green-500 shrink-0" />
+                          {test}
+                        </li>
+                      ))}
+                    </ul>
+                  </AccordionContent>
+                </AccordionItem>
+              )
+            })}
+          </Accordion>
+        </div>
+      )}
+
+      {!hasAnyTests && (
+        <EmptyState>
+          <EmptyStateIcon><FlaskConical /></EmptyStateIcon>
+          <EmptyStateDescription>{t("component.testsPlaceholder")}</EmptyStateDescription>
+        </EmptyState>
+      )}
+    </div>
+  )
+}

package/src/next-app/components/theme-provider.tsx

@@ -0,0 +1,16 @@
+"use client"
+
+import { ThemeProvider as NextThemesProvider } from "next-themes"
+
+export function ThemeProvider({ children }: { children: React.ReactNode }) {
+  return (
+    <NextThemesProvider
+      attribute="class"
+      defaultTheme="system"
+      enableSystem
+      disableTransitionOnChange
+    >
+      {children}
+    </NextThemesProvider>
+  )
+}

package/src/next-app/components/theme-toggle.tsx

@@ -0,0 +1,21 @@
+"use client"
+
+import { useTheme } from "next-themes"
+import { Moon, Sun } from "lucide-react"
+import { Button } from "@shell/components/shell-ui/button"
+
+export function ThemeToggle() {
+  const { setTheme, resolvedTheme } = useTheme()
+
+  return (
+    <Button
+      variant="ghost"
+      size="icon"
+      onClick={() => setTheme(resolvedTheme === "dark" ? "light" : "dark")}
+      aria-label="Toggle theme"
+    >
+      <Sun className="size-4 scale-100 rotate-0 transition-all dark:scale-0 dark:-rotate-90" />
+      <Moon className="absolute size-4 scale-0 rotate-90 transition-all dark:scale-100 dark:rotate-0" />
+    </Button>
+  )
+}

package/src/next-app/components/translated-text.tsx

@@ -0,0 +1,8 @@
+"use client"
+
+import { useTranslations } from "@shell/lib/i18n"
+
+export function TranslatedText({ k }: { k: Parameters<ReturnType<typeof useTranslations>>[0] }) {
+  const t = useTranslations()
+  return <>{t(k)}</>
+}

package/src/next-app/fallback/homepage.tsx

@@ -0,0 +1,112 @@
+/**
+ * Fallback homepage rendered at `/` when the user's config has no custom
+ * `homePage`. Two states:
+ *   - Registry has content → generic index listing components/blocks/docs.
+ *   - Registry empty / absent → terse "no registry wired" placeholder
+ *     pointing at the shell's documentation site.
+ */
+import Link from "next/link"
+import { getAllComponents } from "@shell/lib/components-nav"
+import { getAllDocs } from "@shell/lib/docs"
+import type { HomePageProps } from "@shell/lib/registry-adapter"
+
+export default function FallbackHomePage({ firstDocSlug }: HomePageProps) {
+  const items = getAllComponents()
+  const docs = getAllDocs()
+
+  if (items.length === 0 && docs.length === 0) return <NoRegistryPlaceholder />
+
+  const components = items.filter((c) => c.kind === "component")
+  const blocks = items.filter((c) => c.kind === "block")
+
+  return (
+    <main
+      id="main-content"
+      tabIndex={-1}
+      className="outline-none max-w-5xl mx-auto px-4 md:px-8 py-12"
+    >
+      <section className="mb-12">
+        <h1 className="text-3xl font-bold">Registry</h1>
+        <p className="mt-2 text-muted-foreground">
+          {components.length} component{components.length === 1 ? "" : "s"},{" "}
+          {blocks.length} block{blocks.length === 1 ? "" : "s"}, {docs.length} doc
+          {docs.length === 1 ? "" : "s"}
+        </p>
+        {firstDocSlug && (
+          <Link
+            href={`/docs/${firstDocSlug}`}
+            className="mt-4 inline-block text-sm underline underline-offset-4"
+          >
+            Browse documentation →
+          </Link>
+        )}
+      </section>
+
+      {components.length > 0 && (
+        <section className="mb-12">
+          <h2 className="text-xl font-semibold mb-4">Components</h2>
+          <ul className="grid grid-cols-2 md:grid-cols-3 gap-2 text-sm">
+            {components.map((c) => (
+              <li key={c.name}>
+                <Link className="hover:underline" href={`/components/${c.name}`}>
+                  {c.label}
+                </Link>
+              </li>
+            ))}
+          </ul>
+        </section>
+      )}
+
+      {blocks.length > 0 && (
+        <section>
+          <h2 className="text-xl font-semibold mb-4">Blocks</h2>
+          <ul className="grid grid-cols-2 md:grid-cols-3 gap-2 text-sm">
+            {blocks.map((b) => (
+              <li key={b.name}>
+                <Link className="hover:underline" href={`/components/${b.name}`}>
+                  {b.label}
+                </Link>
+              </li>
+            ))}
+          </ul>
+        </section>
+      )}
+    </main>
+  )
+}
+
+/**
+ * Shown when the shell boots with no config AND no content. Zero external
+ * dependencies (no fetches, no dynamic content) — if a consumer ever sees
+ * this, they're either running `registry-shell dev` in a blank directory
+ * or they're mid-setup.
+ */
+function NoRegistryPlaceholder() {
+  return (
+    <main
+      id="main-content"
+      tabIndex={-1}
+      className="outline-none max-w-xl mx-auto px-6 py-24 text-center"
+    >
+      <h1 className="text-2xl font-semibold">No registry wired</h1>
+      <p className="mt-3 text-sm text-muted-foreground">
+        Add a{" "}
+        <code className="bg-muted rounded px-1.5 py-0.5 text-xs">
+          registry-shell.config.ts
+        </code>{" "}
+        to this project and restart the dev server.
+      </p>
+      <p className="mt-8 text-xs text-muted-foreground">
+        Setup guide:{" "}
+        <a
+          href="https://github.com/scintillar-com/registry-shell"
+          className="underline underline-offset-4 hover:text-foreground"
+          target="_blank"
+          rel="noopener noreferrer"
+        >
+          scintillar-com/registry-shell
+        </a>
+      </p>
+    </main>
+  )
+}

package/src/next-app/fallback/previews.ts

@@ -0,0 +1,17 @@
+/**
+ * Fallback previewLoader used when the user's registry has no
+ * `components/previews/index.ts`. Renders the caller's `fallback` prop (or
+ * nothing) for every name.
+ */
+import { createElement, Fragment, type ReactNode } from "react"
+import type { PreviewLoader } from "@shell/lib/registry-adapter"
+
+function EmptyPreview({ fallback = null }: { name: string; fallback?: ReactNode }) {
+  return createElement(Fragment, null, fallback)
+}
+
+export const previewLoader: PreviewLoader = {
+  Preview: EmptyPreview,
+  load: () => null,
+  names: () => [],
+}

package/src/next-app/hooks/use-active-section.ts

@@ -0,0 +1,23 @@
+"use client"
+
+import { usePathname } from "next/navigation"
+import type { ComponentMeta } from "@shell/lib/components-nav"
+
+export type ActiveSection = "docs" | "components" | "blocks" | null
+
+/**
+ * Returns the current navigation section based on the URL and component list.
+ * - `/docs/*` → "docs"
+ * - `/components/{name}` → "components" or "blocks" depending on the item's kind
+ * - anything else → null
+ */
+export function useActiveSection(components: ComponentMeta[]): ActiveSection {
+  const pathname = usePathname()
+  if (pathname.startsWith("/docs/")) return "docs"
+  if (pathname.startsWith("/components/")) {
+    const name = pathname.split("/")[2]
+    const item = components.find((c) => c.name === name)
+    return item?.kind === "block" ? "blocks" : "components"
+  }
+  return null
+}

package/src/next-app/hooks/use-controls.ts

@@ -0,0 +1,72 @@
+"use client"
+
+import { useState } from "react"
+
+interface SelectControl {
+  type: "select"
+  options: string[]
+  default: string
+}
+
+interface BooleanControl {
+  type: "boolean"
+  default: boolean
+}
+
+interface TextControl {
+  type: "text"
+  default: string
+}
+
+interface NumberControl {
+  type: "number"
+  default: number
+  min?: number
+  max?: number
+}
+
+type ControlDef = SelectControl | BooleanControl | TextControl | NumberControl
+
+export type ControlDefs = Record<string, ControlDef>
+
+type ControlValues<T extends ControlDefs> = {
+  [K in keyof T]: T[K] extends SelectControl
+    ? string
+    : T[K] extends BooleanControl
+      ? boolean
+      : T[K] extends TextControl
+        ? string
+        : T[K] extends NumberControl
+          ? number
+          : never
+}
+
+export interface ControlEntry {
+  name: string
+  def: ControlDef
+  value: unknown
+  onChange: (value: unknown) => void
+}
+
+export function useControls<T extends ControlDefs>(defs: T) {
+  const [values, setValues] = useState<Record<string, unknown>>(() => {
+    const initial: Record<string, unknown> = {}
+    for (const [key, def] of Object.entries(defs)) {
+      initial[key] = def.default
+    }
+    return initial
+  })
+
+  const entries: ControlEntry[] = Object.entries(defs).map(([name, def]) => ({
+    name,
+    def,
+    value: values[name],
+    onChange: (value: unknown) =>
+      setValues((prev) => ({ ...prev, [name]: value })),
+  }))
+
+  return {
+    values: values as ControlValues<T>,
+    entries,
+  }
+}