@sntlr/registry-shell 1.0.0

package/src/next-app/lib/registry-adapter.ts

@@ -0,0 +1,199 @@
+import type { ComponentType, ReactNode } from "react"
+
+/** One entry in the registry's navigation — a UI component or a block. */
+export interface ComponentMeta {
+  /** URL-safe slug, e.g. `"button"` or `"auth-login"`. */
+  name: string
+  /** Human-readable title, e.g. `"Button"` or `"Auth Login"`. */
+  label: string
+  /**
+   * `"component"` for low-level UI primitives (Button, Dialog), `"block"` for
+   * composed screens/patterns (Auth Login, Data Table). Shell groups these
+   * into separate sidebar sections.
+   */
+  kind: "component" | "block"
+}
+
+/** Doc page metadata (frontmatter + slug). Drives the docs sidebar. */
+export interface DocMeta {
+  /** URL-safe slug, matches the `.mdx` filename without extension. */
+  slug: string
+  /** Default-locale title (typically English). */
+  title: string
+  description: string
+  /** Sidebar sort order. Lower = higher up. Default 999. */
+  order: number
+  /** Per-locale titles, e.g. `{ en: "Getting Started", fr: "Démarrage" }`. */
+  titles: Record<string, string>
+}
+
+/** Full MDX body of a doc for one locale, plus its metadata. */
+export interface DocContent {
+  meta: Omit<DocMeta, "titles">
+  /** Raw MDX string — the shell renders it via `next-mdx-remote`. */
+  content: string
+}
+
+/**
+ * Renders interactive component previews on the detail pages. The registry
+ * owns the dynamic-import map (see `sntlr-registry/components/previews/index.ts`
+ * for a reference implementation) because Next.js `dynamic()` needs string
+ * literal paths at compile time.
+ */
+export interface PreviewLoader {
+  /**
+   * Stable wrapper component. Use this in shell code:
+   * `<Preview name={compName} fallback={<EmptyState/>} />`. Avoids the
+   * `react-hooks/static-components` lint that fires when a component type is
+   * looked up inside render.
+   */
+  Preview: ComponentType<{ name: string; fallback?: ReactNode }>
+  /** All names for which `load()` returns a component. */
+  names(): string[]
+  /** Low-level lookup. Prefer `Preview`; exposed for edge cases. */
+  load(name: string): ComponentType | null
+}
+
+/** Props the shell passes to an optional custom `HomePage` component. */
+export interface HomePageProps {
+  /** Slug of the first doc (lowest `order`), so the homepage can link to it. */
+  firstDocSlug?: string
+}
+
+/**
+ * Branding displayed in the shell chrome (header, favicon, HTML title) and on
+ * the built-in Getting Started landing. Pure data — safe to import from client
+ * components.
+ */
+export interface GithubConfig {
+  owner: string
+  repo: string
+  label?: string
+  showStars?: boolean
+}
+
+export interface BrandingConfig {
+  /** Full product name, e.g. `"Scintillar UI"`. Used in HTML title. */
+  siteName: string
+  /** Short breadcrumb label, e.g. `"UI"`. Shown next to the logo. */
+  shortName: string
+  /** Canonical URL of the deployed registry, e.g. `"https://ui.sntlr.app"`. */
+  siteUrl?: string
+  /** SEO description. Used in `<meta name="description">`, OG, Twitter. */
+  description?: string
+  /** OG image URL (1200×630 recommended). */
+  ogImage?: string
+  /** Twitter handle without the `@`. */
+  twitterHandle?: string
+  /** Optional GitHub link button in the header. */
+  github?: GithubConfig
+  /** Accessible alt text for the logo image. */
+  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
+}
+
+/**
+ * Client-safe slice of a registry — bundles everything the shell renders in
+ * the browser (without pulling in the server-only adapter that uses `fs`).
+ * Wire this in `ui-registry/registry.client.ts`.
+ *
+ * A registry package typically exposes this via a `client.ts` module that
+ * re-exports `branding`, `previewLoader`, a default `HomePage`, and optional
+ * `extraTranslations`. See `sntlr-registry/client.ts` for a reference.
+ */
+export interface RegistryClient {
+  branding: BrandingConfig
+  previewLoader: PreviewLoader
+  /**
+   * Optional custom homepage component. When set, the shell's `/` route
+   * renders this instead of the built-in Getting Started / generic index.
+   * When `undefined`/`null`, the shell uses `GenericIndexPage` (a plain
+   * component/block listing).
+   */
+  HomePage?: ComponentType<HomePageProps> | null
+  /**
+   * Locale → key → value dictionaries merged into the shell's i18n table.
+   * Use this to ship marketing/homepage copy; the shell owns the generic UI
+   * keys (sidebar, header, search, a11y, etc.). Invariant: if `HomePage` is
+   * set, this must include every key the homepage references.
+   */
+  extraTranslations?: Record<string, Record<string, string>>
+}
+
+/**
+ * The complete server-side contract the shell consumes. A registry package
+ * implements this (typically in `adapter.ts`) and the shell imports the
+ * default export via `ui-registry/registry.config.ts`.
+ *
+ * All filesystem reads, registry-JSON serving, and MDX parsing live here —
+ * the shell never touches the registry's files directly. This is what makes
+ * the shell swappable across arbitrary registries.
+ */
+export interface RegistryAdapter {
+  /**
+   * Full list of navigable items (components + blocks). Typically scans the
+   * registry's `components/ui` and `registry/STYLE/blocks` folders at build
+   * time, where STYLE is e.g. "new-york" or "default".
+   */
+  getAllComponents(): ComponentMeta[]
+
+  /** Full list of MDX docs with their frontmatter. */
+  getAllDocs(): DocMeta[]
+
+  /**
+   * Return doc content for one slug, preferring the requested locale. Fall
+   * back to the default locale when the localized file doesn't exist. Return
+   * `null` when the slug is unknown so the shell can `notFound()`.
+   */
+  getDocBySlug(slug: string, locale?: string): DocContent | null
+
+  /** Return `{ [locale]: rawMdx }` for all locales a doc is translated into. */
+  getDocAllLocales(slug: string): Record<string, string>
+
+  /**
+   * Raw source of a component/block file for the "Code" tab. Should check
+   * both the component directory and the primitives/blocks directories.
+   * Return `null` if unknown.
+   */
+  getComponentSource(name: string): string | null
+
+  /**
+   * Return the shadcn-format JSON for a registry item. Usually reads the
+   * pre-built `public/r/{name}.json` produced by `shadcn build`. Accepts the
+   * slug with or without a trailing `.json`.
+   */
+  getRegistryItem(name: string): Promise<unknown | null>
+
+  /**
+   * Return the a11y metadata JSON for a component. Powers the Accessibility
+   * tab. Convention: `public/a11y/{name}.json` generated from
+   * `content/a11y/{name}.yaml` by the registry's `generate:a11y` script.
+   */
+  getA11yData?(name: string): Promise<unknown | null>
+
+  /**
+   * Return the test summary JSON for a component. Powers the Tests tab.
+   * Convention: `public/tests/{name}.json` generated by `generate:tests`.
+   */
+  getTestData?(name: string): Promise<unknown | null>
+
+  /**
+   * Return the prop-documentation JSON for a component. Powers the props
+   * table inside the Docs tab. Convention: `public/props/{name}.json`
+   * generated by `generate:props`.
+   */
+  getPropsData?(name: string): Promise<unknown | null>
+
+  previewLoader: PreviewLoader
+  branding: BrandingConfig
+
+  /** See `RegistryClient.HomePage`. */
+  homePage?: ComponentType<HomePageProps> | null
+  /** See `RegistryClient.extraTranslations`. */
+  extraTranslations?: Record<string, Record<string, string>>
+}

package/src/next-app/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}

package/src/next-app/next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+/// <reference path="./.next/types/routes.d.ts" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/src/next-app/next.config.ts

@@ -0,0 +1,101 @@
+import type { NextConfig } from "next"
+import fs from "node:fs"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+const USER_ROOT = process.env.USER_REGISTRY_ROOT
+
+/**
+ * Resolve a virtual `@user/*` alias to the user's file when it exists, else
+ * to a shell-bundled fallback under `fallback/`. Called once at Next boot.
+ */
+function toPosix(p: string): string {
+  // Turbopack on Windows rejects backslash absolute paths.
+  return p.replace(/\\/g, "/")
+}
+
+/** Common ancestor directory of two absolute paths. */
+function findCommonRoot(a: string, b: string): string {
+  const pa = path.resolve(a).split(path.sep)
+  const pb = path.resolve(b).split(path.sep)
+  const common: string[] = []
+  for (let i = 0; i < Math.min(pa.length, pb.length); i++) {
+    if (pa[i] !== pb[i]) break
+    common.push(pa[i])
+  }
+  return common.join(path.sep) || path.sep
+}
+
+function resolveUserModule(relativePath: string, fallback: string): string {
+  if (USER_ROOT) {
+    // Try a few extensions since users may write .ts or .tsx.
+    const candidates = [relativePath, `${relativePath}.ts`, `${relativePath}.tsx`]
+    for (const c of candidates) {
+      const abs = path.isAbsolute(c) ? c : path.join(USER_ROOT, c)
+      if (fs.existsSync(abs) && fs.statSync(abs).isFile()) return toPosix(abs)
+      const indexTs = path.join(abs, "index.ts")
+      if (fs.existsSync(indexTs)) return toPosix(indexTs)
+      const indexTsx = path.join(abs, "index.tsx")
+      if (fs.existsSync(indexTsx)) return toPosix(indexTsx)
+    }
+  }
+  return toPosix(path.join(HERE, fallback))
+}
+
+const USER_PREVIEWS = resolveUserModule("components/previews", "fallback/previews.ts")
+const USER_HOMEPAGE = process.env.USER_HOMEPAGE_PATH
+  ? resolveUserModule(process.env.USER_HOMEPAGE_PATH, "fallback/homepage.tsx")
+  : toPosix(path.join(HERE, "fallback/homepage.tsx"))
+
+// The CLI's `build` / `start` commands set USER_DIST_DIR to
+// `<user-project>/.next` so Next writes its output (and reads it back on
+// start) at the user's project root, not inside node_modules. Absolute
+// path — Next accepts that for `distDir`.
+const USER_DIST_DIR = process.env.USER_DIST_DIR
+
+const nextConfig: NextConfig = {
+  output: process.env.BUILD_STANDALONE === "true" ? "standalone" : undefined,
+  ...(USER_DIST_DIR ? { distDir: toPosix(USER_DIST_DIR) } : {}),
+
+  // When installed as an external package (link:../registry-shell, npm, etc.),
+  // the shell's TSX lives under the user's node_modules and Next won't
+  // transpile it by default. The registry can list additional packages via
+  // `transpilePackages` in its config (CLI forwards as USER_TRANSPILE_PACKAGES).
+  transpilePackages: [
+    "@sntlr/registry-shell",
+    ...(process.env.USER_TRANSPILE_PACKAGES
+      ? process.env.USER_TRANSPILE_PACKAGES.split(",").filter(Boolean)
+      : []),
+  ],
+
+  // Turbopack root: walk up until we find a dir that contains both the shell
+  // package and the user's project. For a pnpm workspace setup that's the
+  // workspace root. Falls back to process.cwd() (which is the user's project
+  // when run via `registry-shell dev`).
+  turbopack: {
+    root: process.env.TURBOPACK_ROOT
+      ? toPosix(process.env.TURBOPACK_ROOT)
+      : toPosix(findCommonRoot(HERE, USER_ROOT ?? process.cwd())),
+    resolveAlias: {
+      "@user/previews": USER_PREVIEWS,
+      "@user/homepage": USER_HOMEPAGE,
+    },
+  },
+
+  webpack: (config) => {
+    config.resolve = config.resolve ?? {}
+    config.resolve.alias = {
+      ...(config.resolve.alias ?? {}),
+      "@user/previews": USER_PREVIEWS,
+      "@user/homepage": USER_HOMEPAGE,
+      // Shell's internal alias — its own files.
+      "@shell": toPosix(HERE),
+      // shadcn convention: user files use `@/` for their own project root.
+      ...(USER_ROOT ? { "@": toPosix(USER_ROOT) } : {}),
+    }
+    return config
+  },
+}
+
+export default nextConfig

package/src/next-app/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+}
+
+export default config

package/src/next-app/public/favicon_dark.svg

@@ -0,0 +1,3 @@
+<svg width="128" height="82" viewBox="0 0 128 82" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M95.7812 3.18066C97.3554 1.60657 99.9073 1.60659 101.481 3.18066C103.056 4.7548 103.056 7.30671 101.481 8.88086L79.3223 31.04C73.7739 36.5884 73.774 45.5844 79.3223 51.1328L100.905 72.7158C102.508 74.3181 102.508 76.9163 100.905 78.5186C99.3031 80.1203 96.7057 80.1204 95.1035 78.5186L73.5205 56.9346C67.9722 51.3864 58.9761 51.3864 53.4277 56.9346L32.3223 78.041C30.7481 79.6152 28.1952 79.6152 26.6211 78.041C25.047 76.4669 25.047 73.914 26.6211 72.3398L47.7275 51.2344C53.2757 45.686 53.2759 36.6899 47.7275 31.1416L26.041 9.45605C24.4388 7.85382 24.4388 5.25556 26.041 3.65332C27.6433 2.0512 30.2415 2.05112 31.8438 3.65332L53.5293 25.3398C59.0777 30.8882 68.0737 30.8882 73.6221 25.3398L95.7812 3.18066ZM61.0986 69.4502C62.7013 67.8476 65.2988 67.8476 66.9014 69.4502C68.504 71.0528 68.504 73.6513 66.9014 75.2539C65.2989 76.856 62.7012 76.856 61.0986 75.2539C59.496 73.6513 59.496 71.0528 61.0986 69.4502ZM4.98926 33.3418C8.97557 29.3555 15.4395 29.3555 19.4258 33.3418C23.4117 37.3281 23.4119 43.7911 19.4258 47.7773C15.4395 51.7637 8.97557 51.7637 4.98926 47.7773C1.00321 43.7912 1.00342 37.3281 4.98926 33.3418ZM108.574 33.3418C112.561 29.3555 119.024 29.3555 123.011 33.3418C126.997 37.3281 126.997 43.7912 123.011 47.7773C119.024 51.7637 112.561 51.7637 108.574 47.7773C104.588 43.7911 104.588 37.3281 108.574 33.3418Z" stroke="#005E3E" stroke-width="4"/>
+</svg>

package/src/next-app/public/favicon_light.svg

@@ -0,0 +1,3 @@
+<svg width="128" height="82" viewBox="0 0 128 82" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M95.7812 3.18066C97.3554 1.60657 99.9073 1.60659 101.481 3.18066C103.056 4.7548 103.056 7.30671 101.481 8.88086L79.3223 31.04C73.7739 36.5884 73.774 45.5844 79.3223 51.1328L100.905 72.7158C102.508 74.3181 102.508 76.9163 100.905 78.5186C99.3031 80.1203 96.7057 80.1204 95.1035 78.5186L73.5205 56.9346C67.9722 51.3864 58.9761 51.3864 53.4277 56.9346L32.3223 78.041C30.7481 79.6152 28.1952 79.6152 26.6211 78.041C25.047 76.4669 25.047 73.914 26.6211 72.3398L47.7275 51.2344C53.2757 45.686 53.2759 36.6899 47.7275 31.1416L26.041 9.45605C24.4388 7.85382 24.4388 5.25556 26.041 3.65332C27.6433 2.0512 30.2415 2.05112 31.8438 3.65332L53.5293 25.3398C59.0777 30.8882 68.0737 30.8882 73.6221 25.3398L95.7812 3.18066ZM61.0986 69.4502C62.7013 67.8476 65.2988 67.8476 66.9014 69.4502C68.504 71.0528 68.504 73.6513 66.9014 75.2539C65.2989 76.856 62.7012 76.856 61.0986 75.2539C59.496 73.6513 59.496 71.0528 61.0986 69.4502ZM4.98926 33.3418C8.97557 29.3555 15.4395 29.3555 19.4258 33.3418C23.4117 37.3281 23.4119 43.7911 19.4258 47.7773C15.4395 51.7637 8.97557 51.7637 4.98926 47.7773C1.00321 43.7912 1.00342 37.3281 4.98926 33.3418ZM108.574 33.3418C112.561 29.3555 119.024 29.3555 123.011 33.3418C126.997 37.3281 126.997 43.7912 123.011 47.7773C119.024 51.7637 112.561 51.7637 108.574 47.7773C104.588 43.7911 104.588 37.3281 108.574 33.3418Z" stroke="#5CD6AD" stroke-width="4"/>
+</svg>

package/src/next-app/registry.config.ts

@@ -0,0 +1,50 @@
+/**
+ * Server-side registry adapter. Not user-editable anymore — the shell reads
+ * the user's `registry-shell.config.ts` via env vars set by the CLI and
+ * instantiates the default convention-based adapter (or a user-supplied
+ * custom one).
+ *
+ * Loaded once at Next.js module init.
+ */
+import "server-only"
+import type { RegistryAdapter } from "@shell/lib/registry-adapter"
+import { loadResolvedConfig } from "../config-loader"
+import { createDefaultAdapter } from "../adapter/default"
+import { loadCustomAdapterOverrides } from "../adapter/custom"
+
+function buildAdapter(): RegistryAdapter | null {
+  const resolved = loadResolvedConfig()
+  if (!resolved) return null
+
+  const base = createDefaultAdapter(resolved)
+  // Shallow-merged on top of `base` so a custom adapter can override one
+  // method (e.g. getAllComponents from a DB) and keep the defaults for the
+  // rest. Loaded via jiti — the adapter file can be plain TS.
+  const overrides = loadCustomAdapterOverrides(resolved) as Partial<RegistryAdapter>
+
+  return {
+    getAllComponents: overrides.getAllComponents ?? base.getAllComponents,
+    getAllDocs: overrides.getAllDocs ?? base.getAllDocs,
+    getDocBySlug: overrides.getDocBySlug ?? base.getDocBySlug,
+    getDocAllLocales: overrides.getDocAllLocales ?? base.getDocAllLocales,
+    getComponentSource: overrides.getComponentSource ?? base.getComponentSource,
+    getRegistryItem: overrides.getRegistryItem ?? base.getRegistryItem,
+    getA11yData: overrides.getA11yData ?? base.getA11yData,
+    getTestData: overrides.getTestData ?? base.getTestData,
+    getPropsData: overrides.getPropsData ?? base.getPropsData,
+    previewLoader: UNUSED_SERVER_SIDE_PREVIEW_LOADER,
+    branding: base.branding,
+    extraTranslations: overrides.extraTranslations ?? base.extraTranslations,
+  }
+}
+
+// The adapter's `previewLoader` field is never read on the server — previews
+// are imported directly from the `@user/previews` alias in client code (see
+// lib/preview-loader.ts). This placeholder satisfies the interface.
+const UNUSED_SERVER_SIDE_PREVIEW_LOADER: RegistryAdapter["previewLoader"] = {
+  Preview: () => null,
+  load: () => null,
+  names: () => [],
+}
+
+export const registry: RegistryAdapter | null = buildAdapter()

package/src/next-app/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "incremental": true,
+    "module": "esnext",
+    "esModuleInterop": true,
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "plugins": [{ "name": "next" }],
+    "paths": {
+      "@shell/*": ["./*"]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "user-aliases.d.ts",
+    ".next/types/**/*.ts",
+    "**/*.ts",
+    "**/*.tsx"
+  ],
+  "exclude": ["node_modules"]
+}

package/src/next-app/user-aliases.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Virtual modules resolved by next.config.ts based on `USER_REGISTRY_ROOT`.
+ * At build time they point at the user's files; if the user has none, they
+ * fall back to shell-bundled stubs under `fallback/`.
+ */
+
+declare module "@user/previews" {
+  import type { PreviewLoader } from "@shell/lib/registry-adapter"
+  export const previewLoader: PreviewLoader
+}
+
+declare module "@user/homepage" {
+  import type { ComponentType } from "react"
+  import type { HomePageProps } from "@shell/lib/registry-adapter"
+  const HomePage: ComponentType<HomePageProps>
+  export default HomePage
+}