@sntlr/registry-shell 1.0.0

package/src/next-app/components/component-tabs.tsx

@@ -0,0 +1,209 @@
+"use client"
+
+import { useCallback, useEffect, useRef, useState } from "react"
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "@shell/components/shell-ui/tabs"
+import { PropsTable } from "@shell/components/props-table"
+import { A11yInfo } from "@shell/components/a11y-info"
+import { EmptyState, EmptyStateIcon, EmptyStateTitle, EmptyStateDescription } from "@shell/components/shell-ui/empty-state"
+import { TestInfo } from "@shell/components/test-info"
+import { useTranslations } from "@shell/lib/i18n"
+import { branding } from "@shell/lib/branding"
+import { FileText, Link as LinkIcon } from "lucide-react"
+
+const DEFAULT_INSTALL_TEMPLATE = "npx shadcn@latest add {siteUrl}/r/{name}.json"
+
+function renderInstallCommand(name: string): string {
+  const template = process.env.NEXT_PUBLIC_SHELL_INSTALL_CMD ?? DEFAULT_INSTALL_TEMPLATE
+  return template
+    .replace(/\{name\}/g, name)
+    .replace(/\{siteUrl\}/g, branding.siteUrl.replace(/\/$/, ""))
+}
+
+interface ComponentTabsProps {
+  name: string
+  source: string | null
+}
+
+interface TocEntry {
+  id: string
+  text: string
+  level: number
+}
+
+function useTocFromContent(containerRef: React.RefObject<HTMLDivElement | null>, activeTab: string) {
+  const [entries, setEntries] = useState<TocEntry[]>([])
+
+  const scan = useCallback(() => {
+    const el = containerRef.current
+    if (!el) return
+    const headings = el.querySelectorAll<HTMLHeadingElement>("h3[id], h4[id]")
+    const items: TocEntry[] = []
+    headings.forEach((h) => {
+      items.push({
+        id: h.id,
+        text: h.textContent ?? "",
+        level: h.tagName === "H3" ? 3 : 4,
+      })
+    })
+    setEntries(items)
+  }, [containerRef])
+
+  useEffect(() => {
+    // Small delay to let tab content render
+    const t = setTimeout(scan, 50)
+    return () => clearTimeout(t)
+  }, [activeTab, scan])
+
+  return entries
+}
+
+function SectionHeading({ id, children }: { id: string; children: React.ReactNode }) {
+  return (
+    <h3 id={id} className="text-lg font-semibold group relative scroll-mt-20">
+      {children}
+      <a
+        href={`#${id}`}
+        onClick={(e) => {
+          e.preventDefault()
+          history.replaceState(null, "", `#${id}`)
+          document.getElementById(id)?.scrollIntoView({ behavior: "smooth", block: "start" })
+        }}
+        className="inline-flex items-center ml-2 opacity-0 group-hover:opacity-100 transition-opacity text-muted-foreground hover:text-foreground"
+        aria-label={`Link to ${typeof children === "string" ? children : "section"}`}
+      >
+        <LinkIcon className="size-3.5" />
+      </a>
+    </h3>
+  )
+}
+
+const tabs = [
+  { value: "install", labelKey: "tabs.install" as const },
+  { value: "docs", labelKey: "tabs.documentation" as const },
+  { value: "guidelines", labelKey: "tabs.guidelines" as const },
+  { value: "a11y", labelKey: "tabs.accessibility" as const },
+  { value: "tests", labelKey: "tabs.tests" as const },
+]
+
+export function ComponentTabs({ name, source }: ComponentTabsProps) {
+  const [activeTab, setActiveTab] = useState("install")
+  const contentRef = useRef<HTMLDivElement>(null)
+  const tocEntries = useTocFromContent(contentRef, activeTab)
+  const t = useTranslations()
+
+  return (
+    <div className="flex justify-center gap-8">
+      <div ref={contentRef} className="flex-1 min-w-0 xl:max-w-225">
+        <Tabs value={activeTab} onValueChange={setActiveTab}>
+          <div className="sticky top-14 md:top-14 z-10 bg-background border-b border-border pt-4 md:pt-8 -mx-1 px-1">
+            <TabsList variant="line" className="w-full justify-start *:shrink-0">
+              {tabs.map((tab) => (
+                <TabsTrigger key={tab.value} value={tab.value}>
+                  {t(tab.labelKey)}
+                </TabsTrigger>
+              ))}
+            </TabsList>
+          </div>
+
+          <TabsContent value="install" className="px-2 mt-6">
+            <div className="space-y-6">
+              <div>
+                <SectionHeading id="installation">
+                  {t("component.installation")}
+                </SectionHeading>
+                <pre className="bg-muted rounded-lg p-4 overflow-x-auto text-sm">
+                  <code>{renderInstallCommand(name)}</code>
+                </pre>
+              </div>
+
+              {source && (
+                <div>
+                  <SectionHeading id="source">
+                    {t("component.source")}
+                  </SectionHeading>
+                  <pre className="bg-muted rounded-lg p-4 overflow-x-auto text-sm">
+                    <code>{source}</code>
+                  </pre>
+                </div>
+              )}
+            </div>
+          </TabsContent>
+
+          <TabsContent value="docs" className="px-2 mt-6">
+            <div className="space-y-6">
+              <SectionHeading id="props-behavior">
+                {t("component.propsBehavior")}
+              </SectionHeading>
+              <PropsTable name={name} />
+            </div>
+          </TabsContent>
+
+          <TabsContent value="guidelines" className="px-2 mt-6">
+            <div className="space-y-4">
+              <SectionHeading id="guidelines">
+                {t("tabs.guidelines")}
+              </SectionHeading>
+              <EmptyState>
+                <EmptyStateIcon><FileText /></EmptyStateIcon>
+                <EmptyStateTitle>{t("tabs.guidelines")}</EmptyStateTitle>
+                <EmptyStateDescription>{t("component.guidelinesPlaceholder")}</EmptyStateDescription>
+              </EmptyState>
+            </div>
+          </TabsContent>
+
+          <TabsContent value="a11y" className="px-2 mt-6">
+            <div className="space-y-4">
+              <SectionHeading id="accessibility">
+                {t("tabs.accessibility")}
+              </SectionHeading>
+              <A11yInfo name={name} />
+            </div>
+          </TabsContent>
+
+          <TabsContent value="tests" className="px-2 mt-6">
+            <div className="space-y-4">
+              <SectionHeading id="tests">
+                {t("tabs.tests")}
+              </SectionHeading>
+              <TestInfo name={name} />
+            </div>
+          </TabsContent>
+        </Tabs>
+      </div>
+
+      {/* TOC column — space always reserved at xl+ to avoid layout shift when
+          switching tabs; inner nav only renders when there are headings. */}
+      <div className="hidden xl:block w-44 shrink-0">
+        {tocEntries.length > 0 && (
+          <nav aria-label={t("toc.title")} className="sticky top-16 pt-20">
+            <p className="text-xs font-semibold text-foreground mb-2" aria-hidden="true">
+              {t("toc.title")}
+            </p>
+            <ul role="list" className="space-y-0.5">
+              {tocEntries.map((entry) => (
+                <li key={entry.id}>
+                  <a
+                    href={`#${entry.id}`}
+                    onClick={(e) => {
+                      e.preventDefault()
+                      const el = document.getElementById(entry.id)
+                      if (el) {
+                        el.scrollIntoView({ behavior: "smooth", block: "start" })
+                        history.replaceState(null, "", `#${entry.id}`)
+                      }
+                    }}
+                    className={`block text-xs px-2 py-1 rounded-md transition-colors text-muted-foreground hover:text-foreground hover:bg-accent/50 ${
+                      entry.level === 4 ? "pl-4" : ""
+                    }`}
+                  >
+                    {entry.text}
+                  </a>
+                </li>
+              ))}
+            </ul>
+          </nav>
+        )}
+      </div>
+    </div>
+  )
+}

package/src/next-app/components/docs-toc.tsx

@@ -0,0 +1,86 @@
+"use client"
+
+import { useEffect, useState } from "react"
+import { useTranslations } from "@shell/lib/i18n"
+
+interface TocEntry {
+  id: string
+  text: string
+  level: number
+}
+
+export function DocsToc() {
+  const [entries, setEntries] = useState<TocEntry[]>([])
+  const [activeId, setActiveId] = useState<string>("")
+  const t = useTranslations()
+
+  useEffect(() => {
+    const article = document.querySelector("[data-docs-content]")
+    if (!article) return
+
+    const headings = article.querySelectorAll<HTMLHeadingElement>("h1, h2, h3")
+    const items: TocEntry[] = []
+    headings.forEach((h) => {
+      if (!h.id) {
+        h.id = h.textContent
+          ?.toLowerCase()
+          .replace(/[^\w\s-]/g, "")
+          .replace(/\s+/g, "-") ?? ""
+      }
+      if (!h.id) return
+      const level = parseInt(h.tagName[1])
+      items.push({ id: h.id, text: h.textContent ?? "", level })
+    })
+    // eslint-disable-next-line react-hooks/set-state-in-effect -- syncing with external DOM headings
+    setEntries(items)
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting) {
+            setActiveId(entry.target.id)
+          }
+        }
+      },
+      { rootMargin: "0px 0px -80% 0px", threshold: 0.1 }
+    )
+    headings.forEach((h) => { if (h.id) observer.observe(h) })
+    return () => observer.disconnect()
+  }, [])
+
+  if (entries.length === 0) return null
+
+  return (
+    <nav aria-label={t("toc.title")} className="w-44 hidden xl:block">
+      <p className="text-xs font-semibold text-foreground mb-2" aria-hidden="true">
+        {t("toc.title")}
+      </p>
+      <ul role="list" className="space-y-0.5">
+        {entries.map((entry) => (
+          <li key={entry.id}>
+            <a
+              href={`#${entry.id}`}
+              aria-current={activeId === entry.id ? "true" : undefined}
+              onClick={(e) => {
+                e.preventDefault()
+                const el = document.getElementById(entry.id)
+                if (el) {
+                  el.scrollIntoView({ behavior: "smooth", block: "start" })
+                  // Update URL hash without scroll jump
+                  history.replaceState(null, "", `#${entry.id}`)
+                }
+              }}
+              className={`block text-xs px-2 py-1 rounded-md transition-colors ${
+                activeId === entry.id
+                  ? "text-foreground font-medium bg-accent"
+                  : "text-muted-foreground hover:text-foreground hover:bg-accent/50"
+              } ${entry.level === 3 ? "pl-4" : ""}`}
+            >
+              {entry.text}
+            </a>
+          </li>
+        ))}
+      </ul>
+    </nav>
+  )
+}

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

@@ -0,0 +1,35 @@
+"use client"
+
+import { Sidebar } from "@shell/components/sidebar"
+import { useMobileSidebar } from "@shell/components/sidebar-provider"
+import type { DocMeta } from "@shell/lib/docs"
+import type { ComponentMeta } from "@shell/lib/components-nav"
+
+/**
+ * Client-side wrapper that mounts the mobile-only variant of the Sidebar from
+ * the root layout. This ensures the hamburger menu in the header works on
+ * **every** page (including the homepage), even though the desktop inline
+ * sidebar is still scoped to per-section layouts via `SidebarLayout`.
+ *
+ * The full Sidebar component reads its `open` / `onClose` from the
+ * `useMobileSidebar` hook, which is a client-side context — so this wrapper
+ * exists purely to bridge the server `RootLayout` to those hooks.
+ */
+export function GlobalMobileSidebar({
+  docs,
+  components,
+}: {
+  docs: DocMeta[]
+  components: ComponentMeta[]
+}) {
+  const { open, close } = useMobileSidebar()
+  return (
+    <Sidebar
+      docs={docs}
+      components={components}
+      open={open}
+      onClose={close}
+      display="mobile"
+    />
+  )
+}

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

@@ -0,0 +1,188 @@
+"use client"
+
+import Image from "next/image"
+import Link from "next/link"
+import {
+  Breadcrumb,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbSeparator,
+} from "@shell/components/shell-ui/breadcrumb"
+import { Badge } from "@shell/components/shell-ui/badge"
+import { useTheme } from "next-themes"
+import { useEffect, useState } from "react"
+import { Github, Menu, Star } from "lucide-react"
+import { Button } from "@shell/components/shell-ui/button"
+import { LocaleToggle } from "@shell/components/locale-toggle"
+import { ThemeToggle } from "@shell/components/theme-toggle"
+import { SearchTrigger } from "@shell/components/search"
+import { useMobileSidebar } from "@shell/components/sidebar-provider"
+import { useNavData } from "@shell/components/nav-data-provider"
+import { useActiveSection, type ActiveSection } from "@shell/hooks/use-active-section"
+import { TranslatedText } from "@shell/components/translated-text"
+import { GITHUB_URL, formatStarCount } from "@shell/lib/github"
+import { branding } from "@shell/lib/branding"
+
+function HeaderTab({
+  href,
+  active,
+  children,
+}: {
+  href: string
+  active: boolean
+  children: React.ReactNode
+}) {
+  return (
+    <Link
+      href={href}
+      className={`relative px-3 py-1.5 text-sm font-medium transition-colors ${
+        active
+          ? "text-foreground"
+          : "text-muted-foreground hover:text-foreground"
+      }`}
+    >
+      {children}
+      {active && (
+        <span className="absolute -bottom-3.25 left-0 right-0 h-0.5 bg-primary" />
+      )}
+    </Link>
+  )
+}
+
+export function Header({ githubStars }: { githubStars?: number | null } = {}) {
+  const { resolvedTheme } = useTheme()
+  const [mounted, setMounted] = useState(false)
+  const { open: sidebarOpen, toggle, collapsed } = useMobileSidebar()
+
+  const navData = useNavData()
+  const activeSection: ActiveSection = useActiveSection(navData?.components ?? [])
+  const firstDocSlug = navData?.docs[0]?.slug
+  const firstComponentName = navData?.components.find((c) => c.kind === "component")?.name
+  const firstBlockName = navData?.components.find((c) => c.kind === "block")?.name
+  const hasBlocks = Boolean(firstBlockName)
+
+  // eslint-disable-next-line react-hooks/set-state-in-effect -- standard hydration mount detection
+  useEffect(() => setMounted(true), [])
+
+  const faviconSrc = mounted
+    ? resolvedTheme === "dark"
+      ? branding.faviconLight
+      : branding.faviconDark
+    : branding.faviconDark
+
+  return (
+    <header className="h-14 border-b border-border sticky top-0 z-30 bg-background">
+      <div className="relative flex items-center justify-between h-full px-4 md:px-6">
+        {/* Left: hamburger + breadcrumb (fixed-width container so absolute-centered tabs don't shift) */}
+        <div className="flex items-center gap-2 md:w-80 md:shrink-0 min-w-0">
+          {/* Hamburger — always takes space on mobile for consistent brand position */}
+          <div
+            className={`md:overflow-hidden md:transition-all md:duration-300 md:ease-in-out motion-reduce:transition-none ${
+              collapsed ? "md:w-9 md:opacity-100" : "md:w-0 md:opacity-0"
+            }`}
+          >
+            <Button
+              variant={sidebarOpen ? "default" : "ghost"}
+              size="icon"
+              onClick={toggle}
+              aria-label="Toggle menu"
+              aria-expanded={sidebarOpen}
+            >
+              <Menu className="size-4" />
+            </Button>
+          </div>
+
+          <Breadcrumb className="min-w-0">
+            <BreadcrumbList className="flex-nowrap gap-1.5 sm:gap-2 text-sm">
+              <BreadcrumbItem>
+                <BreadcrumbLink href="/" className="flex items-center gap-2 hover:no-underline">
+                  <Image
+                    src={faviconSrc}
+                    alt={`${branding.logoAlt} logo`}
+                    width={22}
+                    height={22}
+                  />
+                </BreadcrumbLink>
+              </BreadcrumbItem>
+              <BreadcrumbSeparator />
+              <BreadcrumbItem>
+                <BreadcrumbLink href="/" className="font-medium hover:no-underline">
+                  {branding.shortName}
+                </BreadcrumbLink>
+              </BreadcrumbItem>
+              <span id="header-breadcrumb" className="contents" />
+            </BreadcrumbList>
+          </Breadcrumb>
+        </div>
+
+        {/* Center: section tabs — absolutely centered, independent of breadcrumb width */}
+        {navData && (
+          <nav
+            aria-label="Sections"
+            className="hidden md:flex items-center gap-1 absolute left-1/2 -translate-x-1/2 h-full"
+          >
+            {firstDocSlug && (
+              <HeaderTab href={`/docs/${firstDocSlug}`} active={activeSection === "docs"}>
+                <TranslatedText k="sidebar.documentation" />
+              </HeaderTab>
+            )}
+            {firstComponentName && (
+              <HeaderTab href={`/components/${firstComponentName}`} active={activeSection === "components"}>
+                <TranslatedText k="sidebar.components" />
+              </HeaderTab>
+            )}
+            {hasBlocks && firstBlockName && (
+              <HeaderTab href={`/components/${firstBlockName}`} active={activeSection === "blocks"}>
+                <TranslatedText k="sidebar.blocks" />
+              </HeaderTab>
+            )}
+          </nav>
+        )}
+
+        <div className="flex items-center gap-1">
+          {/* GitHub button — rendered only when the registry config provides
+              a `github` object. Label defaults to "Github" but is overridable
+              (e.g. "Sponsor"). Star count fetches server-side with hourly
+              revalidation, unless the registry opted out via showStars=false. */}
+          {branding.github && (
+            <Button
+              asChild
+              variant="outline"
+              size="sm"
+              className="hidden md:inline-flex h-8 px-2.5 gap-1.5 text-xs font-medium"
+            >
+              <a
+                href={GITHUB_URL}
+                target="_blank"
+                rel="noopener noreferrer"
+                aria-label={
+                  typeof githubStars === "number"
+                    ? `${branding.github.label ?? "GitHub"}, ${githubStars} stars`
+                    : branding.github.label ?? "GitHub repository"
+                }
+              >
+                <Github className="size-3.5" />
+                <span>{branding.github.label ?? "Github"}</span>
+                {typeof githubStars === "number" && (
+                  <Badge
+                    variant="secondary"
+                    className="gap-0.5 px-1.5 py-0 h-4 text-[10px] font-mono tabular-nums"
+                  >
+                    {formatStarCount(githubStars)}
+                    <Star className="size-2.5 fill-current" />
+                  </Badge>
+                )}
+              </a>
+            </Button>
+          )}
+          <SearchTrigger />
+          {/* Locale + theme switches always visible — small icons fit even on
+              mobile and avoid the indirection of a Settings modal. */}
+          <LocaleToggle />
+          <ThemeToggle />
+        </div>
+      </div>
+    </header>
+  )
+}

package/src/next-app/components/heading-anchor.tsx

@@ -0,0 +1,52 @@
+"use client"
+
+import { Link as LinkIcon } from "lucide-react"
+
+function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^\w\s-]/g, "")
+    .replace(/\s+/g, "-")
+}
+
+interface HeadingProps extends React.HTMLAttributes<HTMLHeadingElement> {
+  children?: React.ReactNode
+}
+
+function createHeading(level: 1 | 2 | 3 | 4 | 5 | 6) {
+  const Tag = `h${level}` as const
+
+  return function Heading({ children, id, ...props }: HeadingProps) {
+    const headingId = id || slugify(typeof children === "string" ? children : "")
+    if (!headingId) return <Tag {...props}>{children}</Tag>
+
+    return (
+      <Tag id={headingId} className="group relative scroll-mt-20" {...props}>
+        {children}
+        <a
+          href={`#${headingId}`}
+          onClick={(e) => {
+            e.preventDefault()
+            history.replaceState(null, "", `#${headingId}`)
+            document.getElementById(headingId)?.scrollIntoView({ behavior: "smooth", block: "start" })
+            // Copy link to clipboard
+            navigator.clipboard?.writeText(window.location.href)
+          }}
+          className="inline-flex items-center ml-2 opacity-0 group-hover:opacity-100 transition-opacity text-muted-foreground hover:text-foreground"
+          aria-label={`Link to ${typeof children === "string" ? children : "section"}`}
+        >
+          <LinkIcon className="size-4" />
+        </a>
+      </Tag>
+    )
+  }
+}
+
+export const mdxHeadings = {
+  h1: createHeading(1),
+  h2: createHeading(2),
+  h3: createHeading(3),
+  h4: createHeading(4),
+  h5: createHeading(5),
+  h6: createHeading(6),
+}