@sntlr/registry-shell 1.0.0

package/src/define-config.ts

@@ -0,0 +1,206 @@
+/**
+ * `defineConfig` — the single entry point registry builders use.
+ *
+ * ```ts
+ * // registry-shell.config.ts
+ * import { defineConfig } from "@sntlr/registry-shell"
+ *
+ * export default defineConfig({
+ *   branding: { siteName: "My UI", shortName: "UI", ... },
+ *   // paths/homePage/adapter are optional
+ * })
+ * ```
+ */
+
+export interface GithubConfig {
+  /** GitHub org or user that owns the repo. */
+  owner: string
+  /** Repo name. */
+  repo: string
+  /** Button label in the header. Default: `"Github"`. */
+  label?: string
+  /**
+   * Show the public star count (fetched server-side, revalidated hourly).
+   * Default: `true`.
+   */
+  showStars?: boolean
+}
+
+export interface BrandingConfig {
+  /** Full product name, e.g. "My UI". Used in HTML title. */
+  siteName: string
+  /** Short breadcrumb label, e.g. "UI". */
+  shortName: string
+  /** Canonical URL of the deployed registry, e.g. "https://ui.example.com". */
+  siteUrl?: string
+  /** SEO meta description. Shown in search results + social cards. */
+  description?: string
+  /** Path/URL to a 1200×630 Open Graph image. Relative to `siteUrl` if no scheme. */
+  ogImage?: string
+  /** Twitter handle (without `@`) for Twitter card attribution. */
+  twitterHandle?: string
+  /**
+   * Optional. Adds a GitHub link button to the header. Omit to hide the
+   * button entirely (default).
+   */
+  github?: GithubConfig
+  /** Accessible alt text for the logo image. Default: siteName. */
+  logoAlt?: string
+  /** Public path to the dark-theme SVG favicon. */
+  faviconDark?: string
+  /** Public path to the light-theme SVG favicon. */
+  faviconLight?: string
+  /** Public path to a fallback `.ico` favicon. */
+  faviconIco?: string
+}
+
+/**
+ * Filesystem locations the default adapter scans. All paths are relative to
+ * the config file's directory. Any path can be omitted to use the default.
+ */
+export interface ShellPaths {
+  /** Component source files. Default: "components/ui". */
+  components?: string
+  /** Block directories (each block is a folder). Default: "registry/new-york/blocks". */
+  blocks?: string
+  /** Preview index file. Default: "components/previews/index.ts" (or .tsx). */
+  previews?: string
+  /** Doc MDX files. Default: "content/docs". */
+  docs?: string
+  /** Built registry JSON files (served at /r/[name].json). Default: "public/r". */
+  registryJson?: string
+  /** A11y JSON files (served at /a11y/[name].json). Default: "public/a11y". */
+  a11y?: string
+  /** Test JSON files (served at /tests/[name].json). Default: "public/tests". */
+  tests?: string
+  /** Props JSON files (served at /props/[name].json). Default: "public/props". */
+  props?: string
+  /** Block names to omit from navigation (e.g. example blocks). */
+  skipBlocks?: string[]
+  /**
+   * Optional. Path to a `.css` file the shell imports AFTER its own
+   * globals. Use this for brand fonts (`@font-face`), token overrides
+   * (redefine `--primary` etc. on `:root` / `.dark`), extra `@source`
+   * directives, or any custom utilities.
+   *
+   * Imported at the very end of the shell's `globals.css` so your `:root`
+   * declarations win the cascade against the shell's defaults.
+   *
+   * Example: `globalCss: "./styles/theme.css"`.
+   */
+  globalCss?: string
+  /**
+   * Optional. Directory (relative to the config file) where
+   * `registry-shell build` writes Next's build output, and where
+   * `registry-shell start` reads it back from. Default: `.next`.
+   *
+   * Override only if `.next` collides with something else in your
+   * project. Most Next.js hosts (Vercel, Netlify, self-hosted)
+   * auto-detect `.next` — if you change this, update your host's
+   * "Output Directory" setting to match.
+   */
+  buildOutput?: string
+}
+
+/**
+ * Advanced: point at a custom adapter module. The module must default-export
+ * a factory `(resolved: ResolvedShellConfig) => RegistryAdapter`. When unset,
+ * the shell uses its built-in convention-based adapter.
+ */
+export type CustomAdapterSpec = string
+
+export interface ShellConfig {
+  /**
+   * Required. Displayed in shell chrome.
+   */
+  branding: BrandingConfig
+
+  /**
+   * When `true`, docs are organized under per-locale subfolders
+   * (e.g. `content/docs/en/foo.mdx`, `content/docs/fr/foo.mdx`) and each
+   * subfolder name is treated as a locale code. Requires `defaultLocale`.
+   *
+   * When `false` (default), docs live directly under `paths.docs` and
+   * locale variants use the file-extension convention `{slug}.{locale}.mdx`
+   * alongside the canonical `{slug}.mdx`.
+   */
+  multilocale?: boolean
+
+  /**
+   * Required when `multilocale` is `true`. Locale code (e.g. `"en"`) of the
+   * subfolder containing the canonical doc set. Other locales are optional
+   * translations and fall back to this one when a slug is missing.
+   */
+  defaultLocale?: string
+
+  /**
+   * Optional in multilocale mode. Explicit list of locale codes the shell
+   * should offer in its locale toggle (e.g. `["en", "fr", "ja"]`). When
+   * unset, the shell auto-discovers locales by scanning subfolders under
+   * `paths.docs`.
+   *
+   * Ignored in single-locale mode (the toggle is hidden).
+   */
+  locales?: string[]
+
+  /**
+   * Optional. Override filesystem layout. Defaults match the sntlr-registry
+   * convention.
+   */
+  paths?: ShellPaths
+
+  /**
+   * Optional. Path to a custom homepage module, relative to config dir.
+   * The module must default-export a React component accepting
+   * `{ firstDocSlug?: string }` props.
+   */
+  homePage?: string
+
+  /**
+   * Optional. Locale → key → value dictionaries merged into the shell's
+   * built-in i18n table. Use for marketing copy referenced by a custom
+   * homepage.
+   */
+  extraTranslations?: Record<string, Record<string, string>>
+
+  /**
+   * Optional. Path to a custom adapter module. See `CustomAdapterSpec`.
+   */
+  adapter?: CustomAdapterSpec
+
+  /**
+   * Optional. Pin the dev/start server to a specific port. Falls through to
+   * Next.js's default (3000, auto-incrementing if in use) when unset.
+   */
+  port?: number
+
+  /**
+   * Optional. Extra npm package names the shell's Next.js build should
+   * transpile. Use this when your registry depends on another workspace
+   * package (e.g. a shared components library) whose TSX files should be
+   * compiled the same way as your own.
+   *
+   * Forwarded to Next's `transpilePackages`. The shell itself
+   * (`@sntlr/registry-shell`) is always transpiled regardless.
+   */
+  transpilePackages?: string[]
+
+  /**
+   * Optional. Template the shell uses to render the install command in the
+   * component "Install" tab. Supported placeholders:
+   *   - `{name}`    — the component/block slug (e.g. `"button"`)
+   *   - `{siteUrl}` — `branding.siteUrl` (trailing slash stripped)
+   *
+   * Default: `"npx shadcn@latest add {siteUrl}/r/{name}.json"`. Set to an
+   * empty string to hide the install line entirely.
+   */
+  installCommandTemplate?: string
+}
+
+/**
+ * Identity function with type inference — users call this purely for editor
+ * support. No runtime validation here; the shell validates at boot time.
+ */
+export function defineConfig(config: ShellConfig): ShellConfig {
+  return config
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+/**
+ * @sntlr/registry-shell — public API.
+ *
+ * Registry builders import `defineConfig` from here into their
+ * `registry-shell.config.ts`. Custom-adapter authors also import
+ * `ResolvedShellConfig` to type their factory's argument.
+ */
+export { defineConfig } from "./define-config.js"
+export type {
+  ShellConfig,
+  BrandingConfig,
+  GithubConfig,
+  ShellPaths,
+  CustomAdapterSpec,
+} from "./define-config.js"
+export type { ResolvedShellConfig } from "./config-loader.js"
+export type { AdapterOverrides } from "./adapter/custom.js"

package/src/next-app/app/[...asset]/route.ts

@@ -0,0 +1,81 @@
+/**
+ * Catch-all route that serves arbitrary files from the user registry's
+ * `public/` directory. Fires only when no other app route matches, so it
+ * doesn't interfere with static routes like `/`, `/docs/...`, `/r/...`,
+ * etc. The shell's own `public/` assets are served first by Next.js's
+ * built-in static handler; this route handles the user's project's assets
+ * since Next only serves the bundled package's `public/`.
+ *
+ * Examples of what this enables:
+ *   - `![foo](./my-image.png)` inside user MDX resolving to
+ *     `{userRoot}/public/my-image.png`
+ *   - Custom favicons referenced in `branding.faviconDark` that live under
+ *     `{userRoot}/public/`
+ */
+import "server-only"
+import fs from "node:fs"
+import path from "node:path"
+import { NextRequest } from "next/server"
+
+const MIME: Record<string, string> = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".avif": "image/avif",
+  ".svg": "image/svg+xml",
+  ".ico": "image/x-icon",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".otf": "font/otf",
+  ".json": "application/json",
+  ".txt": "text/plain; charset=utf-8",
+  ".xml": "application/xml",
+  ".pdf": "application/pdf",
+  ".mp4": "video/mp4",
+  ".webm": "video/webm",
+}
+
+export async function GET(
+  _request: NextRequest,
+  { params }: { params: Promise<{ asset: string[] }> },
+) {
+  const { asset } = await params
+  const userRoot = process.env.USER_REGISTRY_ROOT
+  if (!userRoot || asset.length === 0) {
+    return new Response("Not found", { status: 404 })
+  }
+
+  // Reject traversal.
+  if (asset.some((seg) => seg.includes("..") || seg.includes("\0"))) {
+    return new Response("Forbidden", { status: 403 })
+  }
+
+  const publicDir = path.join(userRoot, "public")
+  const filePath = path.join(publicDir, ...asset)
+
+  // Defense-in-depth: make sure the resolved path is still under public/.
+  const resolved = path.resolve(filePath)
+  if (!resolved.startsWith(path.resolve(publicDir) + path.sep)) {
+    return new Response("Forbidden", { status: 403 })
+  }
+
+  try {
+    const stat = await fs.promises.stat(resolved)
+    if (!stat.isFile()) return new Response("Not found", { status: 404 })
+    const body = await fs.promises.readFile(resolved)
+    const type = MIME[path.extname(resolved).toLowerCase()] ?? "application/octet-stream"
+    return new Response(new Uint8Array(body), {
+      status: 200,
+      headers: {
+        "Content-Type": type,
+        "Content-Length": String(stat.size),
+        "Cache-Control": "public, max-age=0, must-revalidate",
+      },
+    })
+  } catch {
+    return new Response("Not found", { status: 404 })
+  }
+}

package/src/next-app/app/_user-global.css

@@ -0,0 +1,6 @@
+/* Auto-generated by @sntlr/registry-shell. Do not edit.
+ *
+ * This file is rewritten by the CLI on every `registry-shell dev/build` boot.
+ * When a registry sets `paths.globalCss` in its config, the generated file
+ * `@import`s that user CSS. Without a config (shell-only mode), it stays a
+ * no-op so the `@import "./_user-global.css"` in globals.css never 404s. */

package/src/next-app/app/_user-sources.css

@@ -0,0 +1,9 @@
+/* Auto-generated by @sntlr/registry-shell. Do not edit. */
+@source "./";
+@source "../components";
+@source "../lib";
+@source "../hooks";
+@source "../fallback";
+@source "../../../../sntlr-registry/components/ui";
+@source "../../../../sntlr-registry/registry/new-york/blocks";
+@source "../../../../sntlr-registry/components/previews";

package/src/next-app/app/a11y/[name]/route.ts

@@ -0,0 +1,19 @@
+import { NextRequest, NextResponse } from "next/server"
+import { registry } from "@shell/registry.config"
+
+/**
+ * Serves the user registry's `public/a11y/{name}.json` files. The shell's
+ * own `public/` doesn't hold these (they live in the user's project), so a
+ * route handler proxies the read through the adapter.
+ */
+export async function GET(
+  _request: NextRequest,
+  { params }: { params: Promise<{ name: string }> },
+) {
+  const { name } = await params
+  const data = registry?.getA11yData ? await registry.getA11yData(name) : null
+  if (!data) {
+    return NextResponse.json({ error: "A11y data not found" }, { status: 404 })
+  }
+  return NextResponse.json(data)
+}

package/src/next-app/app/api/search-index/route.ts

@@ -0,0 +1,19 @@
+import { NextResponse } from "next/server"
+import { getAllDocs } from "@shell/lib/docs"
+import { getAllComponents } from "@shell/lib/components-nav"
+
+export function GET() {
+  const docs = getAllDocs().map((doc) => ({
+    label: doc.title,
+    href: `/docs/${doc.slug}`,
+    group: "Documentation",
+  }))
+
+  const components = getAllComponents().map((comp) => ({
+    label: comp.label,
+    href: `/components/${comp.name}`,
+    group: "Components",
+  }))
+
+  return NextResponse.json([...docs, ...components])
+}

package/src/next-app/app/components/[name]/page.tsx

@@ -0,0 +1,61 @@
+import { notFound } from "next/navigation"
+import { getAllComponents } from "@shell/lib/components-nav"
+import { registry } from "@shell/registry.config"
+import { ComponentPreview } from "@shell/components/component-preview"
+import { ComponentTabs } from "@shell/components/component-tabs"
+import { TranslatedText } from "@shell/components/translated-text"
+import { ResizablePreview } from "@shell/components/resizable-preview"
+import { ComponentBreadcrumb } from "@shell/components/component-breadcrumb"
+
+export function generateStaticParams() {
+  return getAllComponents().map((comp) => ({ name: comp.name }))
+}
+
+export function generateMetadata({ params }: { params: Promise<{ name: string }> }) {
+  return params.then(({ name }) => {
+    const comp = getAllComponents().find((c) => c.name === name)
+    if (!comp) return {}
+    return {
+      title: `${comp.label} - UI Registry`,
+    }
+  })
+}
+
+export default async function ComponentPage({
+  params,
+}: {
+  params: Promise<{ name: string }>
+}) {
+  const { name } = await params
+  const comp = getAllComponents().find((c) => c.name === name)
+
+  if (!comp) notFound()
+
+  const source = registry?.getComponentSource(name) ?? null
+
+  return (
+    <div>
+      {/* Component header — sticky on desktop, breadcrumb on mobile when scrolled */}
+      <ComponentBreadcrumb name={comp.label}>
+        <div className="sticky top-14 z-20 bg-background border-b border-border max-md:static max-md:border-b-0">
+          <div className="mx-auto px-4 md:px-8 py-4 max-md:py-3">
+            <h1 className="text-2xl max-md:text-xl font-bold">{comp.label}</h1>
+            <p className="text-sm text-muted-foreground max-md:hidden">
+              <TranslatedText k="component.subtitle" />
+            </p>
+          </div>
+        </div>
+      </ComponentBreadcrumb>
+
+      {/* Resizable preview area */}
+      <ResizablePreview>
+        <ComponentPreview name={name} />
+      </ResizablePreview>
+
+      {/* Tabs with reserved TOC column on the right. Content clamps to 900px on xl. */}
+      <div className="mx-auto px-4 md:px-8 pb-8 w-full">
+        <ComponentTabs name={name} source={source} />
+      </div>
+    </div>
+  )
+}

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

@@ -0,0 +1,18 @@
+import { SidebarLayout } from "@shell/components/sidebar-layout"
+import { getAllDocs } from "@shell/lib/docs"
+import { getAllComponents } from "@shell/lib/components-nav"
+
+export default function ComponentsLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  const docs = getAllDocs()
+  const components = getAllComponents()
+
+  return (
+    <SidebarLayout docs={docs} components={components}>
+      {children}
+    </SidebarLayout>
+  )
+}

package/src/next-app/app/docs/[slug]/page.tsx

@@ -0,0 +1,53 @@
+import { notFound } from "next/navigation"
+import { getAllDocs, getDocBySlug, getDocAllLocales } from "@shell/lib/docs"
+import { DocsToc } from "@shell/components/docs-toc"
+import { LocalizedMdx } from "@shell/components/localized-mdx"
+
+export function generateStaticParams() {
+  return getAllDocs().map((doc) => ({ slug: doc.slug }))
+}
+
+export function generateMetadata({ params }: { params: Promise<{ slug: string }> }) {
+  return params.then(({ slug }) => {
+    const doc = getDocBySlug(slug)
+    if (!doc) return {}
+    return {
+      title: `${doc.meta.title} - UI Registry`,
+      description: doc.meta.description,
+    }
+  })
+}
+
+export default async function DocPage({
+  params,
+}: {
+  params: Promise<{ slug: string }>
+}) {
+  const { slug } = await params
+  const doc = getDocBySlug(slug)
+
+  if (!doc) notFound()
+
+  const locales = getDocAllLocales(slug)
+
+  return (
+    <div className="mx-auto py-10 px-4 md:px-8 w-full max-w-300 flex justify-center gap-8">
+      {/* Left spacer mirrors the TOC width to keep the article column
+          horizontally centered under the topbar at xl+. */}
+      <div className="hidden xl:block w-44 shrink-0" aria-hidden="true" />
+      <article
+        data-docs-content
+        className="prose prose-zinc dark:prose-invert flex-1 min-w-0 xl:max-w-225"
+      >
+        <LocalizedMdx locales={locales} />
+      </article>
+      {/* TOC column — space always reserved at xl+ to avoid layout shift when
+          headings change; inner element hidden below xl since there's no room. */}
+      <div className="hidden xl:block w-44 shrink-0">
+        <div className="sticky top-20">
+          <DocsToc />
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/next-app/app/docs/layout.tsx

@@ -0,0 +1,18 @@
+import { SidebarLayout } from "@shell/components/sidebar-layout"
+import { getAllDocs } from "@shell/lib/docs"
+import { getAllComponents } from "@shell/lib/components-nav"
+
+export default function DocsLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  const docs = getAllDocs()
+  const components = getAllComponents()
+
+  return (
+    <SidebarLayout docs={docs} components={components}>
+      {children}
+    </SidebarLayout>
+  )
+}