@gentleduck/docs 0.0.13 → 0.0.16

package/src/components/layouts/site-header.tsx

@@ -0,0 +1,178 @@
+'use client'
+
+import { MainNav } from '@duck-docs/components/main-nav'
+import { ModeSwitcher } from '@duck-docs/components/mode-toggle'
+import { useSiteConfig } from '@duck-docs/context'
+import { cn } from '@gentleduck/libs/cn'
+import { buttonVariants } from '@gentleduck/registry-ui/button'
+import { useAtom } from 'jotai'
+import { atomWithStorage } from 'jotai/utils'
+import { CaseUpper, Github, Twitter, Type } from 'lucide-react'
+import Link from 'next/link'
+import React from 'react'
+import { HeaderContainer, HeaderRoot } from './header-shell'
+
+const CommandMenu = React.lazy(() =>
+  import('@duck-docs/components/layouts/command-menu').then((m) => ({ default: m.CommandMenu })),
+)
+const MobileNav = React.lazy(() => import('@duck-docs/components/mobile-nav').then((m) => ({ default: m.MobileNav })))
+
+export function SiteHeader() {
+  const siteConfig = useSiteConfig()
+
+  return (
+    <HeaderRoot className="border-border/50 border-b bg-background/95 backdrop-blur-sm supports-[backdrop-filter]:bg-background/70">
+      <HeaderContainer>
+        <MainNav />
+        <React.Suspense fallback={null}>
+          <MobileNav />
+        </React.Suspense>
+        <div className="flex flex-1 items-center justify-between space-x-2 md:justify-end">
+          <div className="w-full flex-1 md:w-auto md:flex-none">
+            <React.Suspense
+              fallback={
+                <div
+                  className={cn(
+                    buttonVariants({ size: 'sm', variant: 'outline' }),
+                    'relative h-8 w-full bg-muted/50 text-muted-foreground text-sm shadow-none md:w-40 lg:w-64',
+                  )}>
+                  <span className="hidden lg:inline-flex">Search documentation...</span>
+                  <span className="inline-flex lg:hidden">Search...</span>
+                </div>
+              }>
+              <CommandMenu />
+            </React.Suspense>
+          </div>
+          <nav aria-label="Social and settings" className="flex items-center">
+            <GitHubStarsButton />
+            <FontStyleButton />
+            {siteConfig.links?.discord ? (
+              <Link
+                aria-label="Discord (opens in a new tab)"
+                href={siteConfig.links.discord}
+                rel="noreferrer"
+                target="_blank">
+                <div
+                  className={cn(
+                    buttonVariants({
+                      size: 'icon',
+                      variant: 'ghost',
+                    }),
+                  )}>
+                  <svg
+                    aria-hidden="true"
+                    className="size-4"
+                    fill="currentColor"
+                    viewBox="0 0 24 24"
+                    xmlns="http://www.w3.org/2000/svg">
+                    <path d="M20.317 4.37a19.791 19.791 0 0 0-4.885-1.515.074.074 0 0 0-.079.037c-.21.375-.444.864-.608 1.25a18.27 18.27 0 0 0-5.487 0 12.64 12.64 0 0 0-.617-1.25.077.077 0 0 0-.079-.037A19.736 19.736 0 0 0 3.677 4.37a.07.07 0 0 0-.032.027C.533 9.046-.32 13.58.099 18.057a.082.082 0 0 0 .031.057 19.9 19.9 0 0 0 5.993 3.03.078.078 0 0 0 .084-.028 14.09 14.09 0 0 0 1.226-1.994.076.076 0 0 0-.041-.106 13.107 13.107 0 0 1-1.872-.892.077.077 0 0 1-.008-.128 10.2 10.2 0 0 0 .372-.292.074.074 0 0 1 .077-.01c3.928 1.793 8.18 1.793 12.062 0a.074.074 0 0 1 .078.01c.12.098.246.198.373.292a.077.077 0 0 1-.006.127 12.299 12.299 0 0 1-1.873.892.077.077 0 0 0-.041.107c.36.698.772 1.362 1.225 1.993a.076.076 0 0 0 .084.028 19.839 19.839 0 0 0 6.002-3.03.077.077 0 0 0 .032-.054c.5-5.177-.838-9.674-3.549-13.66a.061.061 0 0 0-.031-.03zM8.02 15.33c-1.183 0-2.157-1.085-2.157-2.419 0-1.333.956-2.419 2.157-2.419 1.21 0 2.176 1.095 2.157 2.42 0 1.333-.956 2.418-2.157 2.418zm7.975 0c-1.183 0-2.157-1.085-2.157-2.419 0-1.333.955-2.419 2.157-2.419 1.21 0 2.176 1.095 2.157 2.42 0 1.333-.946 2.418-2.157 2.418z" />
+                  </svg>
+                </div>
+              </Link>
+            ) : null}
+            {siteConfig.links?.twitter ? (
+              <Link
+                aria-label="Twitter (opens in a new tab)"
+                href={siteConfig.links.twitter}
+                rel="noreferrer"
+                target="_blank">
+                <div
+                  className={cn(
+                    buttonVariants({
+                      size: 'icon',
+                      variant: 'ghost',
+                    }),
+                  )}>
+                  <Twitter aria-hidden="true" />
+                </div>
+              </Link>
+            ) : null}
+            <ModeSwitcher />
+          </nav>
+        </div>
+      </HeaderContainer>
+    </HeaderRoot>
+  )
+}
+
+function GitHubStarsButton() {
+  const [stars, setStars] = React.useState<number | null>(null)
+  const siteConfig = useSiteConfig()
+  const repoFromUrl = siteConfig.links?.github?.replace('https://github.com/', '').replace(/\/$/, '')
+  const repo = siteConfig.githubRepo ?? repoFromUrl
+
+  React.useEffect(() => {
+    async function fetchStars() {
+      try {
+        if (!repo) {
+          return
+        }
+        const res = await fetch(`https://api.github.com/repos/${repo}`)
+        if (!res.ok) return
+        const data = await res.json()
+        if (typeof data.stargazers_count === 'number') {
+          setStars(data.stargazers_count)
+        }
+      } catch (err) {
+        console.error('Failed to fetch stars:', err)
+      }
+    }
+    fetchStars()
+  }, [])
+
+  if (!siteConfig.links?.github) {
+    return null
+  }
+
+  return (
+    <Link
+      aria-label="GitHub (opens in a new tab)"
+      href={siteConfig.links.github}
+      rel="noopener noreferrer"
+      target="_blank">
+      <div
+        className={cn(
+          buttonVariants({
+            className: 'size-auto h-8 w-16 font-medium text-sm',
+            size: 'icon',
+            variant: 'ghost',
+          }),
+        )}>
+        <Github aria-hidden="true" />
+        {stars !== null ? stars.toLocaleString() : '...'}
+      </div>
+    </Link>
+  )
+}
+const fontAtom = atomWithStorage('fontType', 'mono')
+
+export function FontStyleButton() {
+  const [fontType, setFontType] = useAtom(fontAtom)
+  const firstRender = React.useRef(true)
+
+  React.useEffect(() => {
+    if (firstRender.current) {
+      firstRender.current = false
+      return
+    }
+
+    const family =
+      fontType === 'sans'
+        ? 'var(--font-geist-sans, "Montserrat"), sans-serif'
+        : 'var(--font-geist-mono, "Geist Mono"), monospace'
+
+    document.documentElement.style.setProperty('font-family', family, 'important')
+  }, [fontType])
+
+  return (
+    <button
+      aria-label={fontType === 'mono' ? 'Switch to sans-serif font' : 'Switch to monospace font'}
+      className={cn(buttonVariants({ size: 'icon', variant: 'ghost' }))}
+      onClick={() => setFontType(fontType === 'mono' ? 'sans' : 'mono')}
+      type="button">
+      {fontType === 'mono' ? <Type aria-hidden="true" /> : <CaseUpper aria-hidden="true" />}
+    </button>
+  )
+}
+
+export { HeaderBrand, HeaderContainer, HeaderRoot, HeaderSection } from './header-shell'

package/src/components/main-nav.tsx

@@ -4,7 +4,7 @@ import { useDocsConfig } from '@duck-docs/context'
 import { cn } from '@gentleduck/libs/cn'
 import Link from 'next/link'
 import { usePathname } from 'next/navigation'
-import { HeaderBrand } from './layouts/site-header/header-shell'
+import { HeaderBrand } from './layouts/site-header'
 
 export function MainNav() {
   const pathname = usePathname()
@@ -14,9 +14,10 @@ export function MainNav() {
     <div className="mr-4 hidden md:flex">
       <HeaderBrand className="mr-4 lg:mr-6" />
       {mainNav?.length ? (
-        <nav className="flex items-center gap-4 text-sm xl:gap-6">
+        <nav aria-label="Main" className="flex items-center gap-4 text-sm xl:gap-6">
           {mainNav.map((item) => (
             <Link
+              aria-current={pathname === item.href ? 'page' : undefined}
               className={cn(
                 'font-medium transition-colors hover:text-foreground/80',
                 pathname === item.href ? 'text-foreground' : 'text-foreground/80',

package/src/components/mdx/ARCHITECTURE.md

@@ -0,0 +1,61 @@
+# MDX Architecture
+
+This directory contains the runtime rendering layer for docs MDX content.
+
+## Key Modules
+
+1. `mdx.tsx`
+- Thin public entrypoint.
+- Compiles MDX runtime code and renders it with the composed component registry.
+
+2. `mdx-runtime.ts`
+- Runtime loader helper (`useMDXComponent`).
+- Keeps `new Function(...)` handling isolated from UI component composition.
+
+3. `mdx-components-registry.ts`
+- Final composed MDX component map.
+- Merges base content components and UI-facing primitives.
+
+4. `mdx-components-base.tsx`
+- Core markdown/mdx renderers (typography, code/pre, table, tabs, callouts, media).
+- Includes MDX-specific wrappers (`pre`, `Steps`, `Step`, etc.).
+
+5. `mdx-components-ui.tsx`
+- Optional UI primitives exposed directly in MDX content.
+- Keeps registry-ui dependencies isolated from base markdown semantics.
+
+6. `mdx-components/`
+- Leaf render components used by the base registry.
+- `code/pre-block/` is organized for maintainable command/code block behavior.
+
+7. `src/styles/mdx*.css`
+- `mdx.css` is a compatibility barrel file.
+- Style layers are split into:
+  - `mdx-base.css`
+  - `mdx-typography.css`
+  - `mdx-code.css`
+  - `mdx-extensions.css`
+
+## Velite/Rehype Metadata Flow
+
+Plugin metadata is typed in `src/types/mdx-runtime.ts` and applied by:
+- `src/velite/plugins/metadata-plugin.ts`
+- `src/velite/plugins/rehype-pre-block-source.ts`
+- `src/velite/plugins/rehype-npm-command.ts`
+
+Use `hast-properties.ts` helpers when adding new plugin metadata to avoid ad hoc object shape mutations.
+
+## Extension Rules
+
+1. Add new MDX-level visual behavior in `mdx-components-base.tsx` unless it is a generic UI primitive.
+2. Add UI primitives in `mdx-components-ui.tsx`, then compose via registry.
+3. Keep `mdx.tsx` thin; avoid adding renderer internals there.
+4. Any new plugin metadata must be represented in `src/types/mdx-runtime.ts` first.
+
+## Testing Conventions
+
+1. Keep plugin/AST tests in `tests/velite/plugins/**`.
+2. Keep runtime component composition tests in `tests/components/mdx/**`.
+3. Validate package sources with `bun run check-types`.
+4. Validate tests with `bun run check-types:test`.
+5. Execute runtime regressions with `bun run test`.

package/src/components/mdx/mdx-component-registry.types.ts

@@ -0,0 +1,5 @@
+import type * as React from 'react'
+
+export type MdxComponent = React.ComponentType<any> | ((props: any) => React.ReactNode)
+
+export type MdxComponentMap = Record<string, MdxComponent>

package/src/components/mdx/mdx-components/callout.tsx

@@ -1,17 +1,37 @@
 import { cn } from '@gentleduck/libs/cn'
-import { Alert, AlertDescription, AlertTitle } from '@gentleduck/registry-ui-duckui/alert'
+import { Alert, AlertDescription, AlertTitle } from '@gentleduck/registry-ui/alert'
 
-interface CalloutProps {
-  icon?: React.ReactNode
-  title?: string
-  children?: React.ReactNode
-  className?: string
-  [key: string]: unknown
+type CalloutTone = 'default' | 'info' | 'warning' | 'deprecated'
+
+const CALLOUT_TONE_CLASSES: Record<CalloutTone, string> = {
+  default: '',
+  info: 'border-sky-300/80 bg-gradient-to-br from-cyan-50 to-sky-50 text-sky-950 dark:border-sky-900 dark:from-cyan-950/35 dark:to-sky-950/30 dark:text-sky-100 [&_svg]:text-sky-600 dark:[&_svg]:text-sky-300',
+  warning:
+    'border-yellow-300/80 bg-gradient-to-br from-yellow-50 to-amber-50 text-yellow-950 dark:border-yellow-900 dark:from-yellow-950/35 dark:to-amber-950/30 dark:text-yellow-100 [&_svg]:text-yellow-600 dark:[&_svg]:text-yellow-300',
+  deprecated:
+    'border-rose-300/85 bg-gradient-to-br from-rose-50 to-pink-50 text-rose-950 dark:border-rose-900 dark:from-rose-950/40 dark:to-pink-950/30 dark:text-rose-100 [&_svg]:text-rose-600 dark:[&_svg]:text-rose-300',
 }
 
-export function Callout({ title, children, icon, className, ...props }: CalloutProps) {
+export function Callout({
+  title,
+  children,
+  icon,
+  tone,
+  className,
+  ...props
+}: React.ComponentPropsWithoutRef<typeof Alert> & {
+  icon?: React.ReactNode
+  tone?: CalloutTone
+}) {
   return (
-    <Alert className={cn('my-6', icon && 'grid-cols-[calc(var(--spacing)*4)_1fr] gap-x-3', className)}>
+    <Alert
+      className={cn(
+        'my-6',
+        icon && 'grid-cols-[calc(var(--spacing)*4)_1fr] gap-x-3',
+        CALLOUT_TONE_CLASSES[tone ?? 'default'],
+        className,
+      )}
+      {...props}>
       {icon && (
         <span className="row-span-2 [&_svg]:size-4 [&_svg]:shrink-0 [&_svg]:translate-y-0.5 [&_svg]:text-current">
           {icon}

package/src/components/mdx/mdx-components/code/code-preview.tsx

@@ -3,10 +3,10 @@
 import { Icons } from '@duck-docs/components/icons'
 import { useLiftMode } from '@duck-docs/hooks/use-lift-mode'
 import { cn } from '@gentleduck/libs/cn'
-import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from '@gentleduck/registry-ui-duckui/resizable'
-import { Tabs, TabsContent } from '@gentleduck/registry-ui-duckui/tabs'
+import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from '@gentleduck/registry-ui/resizable'
+import { Tabs, TabsContent } from '@gentleduck/registry-ui/tabs'
 import React from 'react'
-import type { ImperativePanelHandle } from 'react-resizable-panels'
+import type { PanelImperativeHandle } from 'react-resizable-panels'
 
 type Block = {
   name: string
@@ -19,7 +19,7 @@ type Block = {
 export function CodePreview({ block }: { block: Block & { hasLiftMode: boolean } }) {
   const { isLiftMode } = useLiftMode(block.name)
   const [isLoading, setIsLoading] = React.useState(true)
-  const ref = React.useRef<ImperativePanelHandle>(null)
+  const ref = React.useRef<PanelImperativeHandle>(null)
 
   return (
     <Tabs
@@ -34,7 +34,7 @@ export function CodePreview({ block }: { block: Block & { hasLiftMode: boolean }
       <TabsContent
         className="relative after:absolute after:inset-0 after:right-3 after:z-0 after:rounded-lg after:bg-muted"
         value="preview">
-        <ResizablePanelGroup className="relative z-10" direction="horizontal">
+        <ResizablePanelGroup className="relative z-10" orientation="horizontal">
           <ResizablePanel
             className={cn(
               'relative rounded-lg border bg-background',
@@ -42,10 +42,12 @@ export function CodePreview({ block }: { block: Block & { hasLiftMode: boolean }
             )}
             defaultSize={100}
             minSize={30}
-            ref={ref}>
+            panelRef={ref}>
             {isLoading ? (
-              <div className="absolute inset-0 z-10 flex h-[--container-height] w-full items-center justify-center gap-2 bg-background text-muted-foreground text-sm">
-                <Icons.spinner className="h-4 w-4 animate-spin" />
+              <div
+                className="absolute inset-0 z-10 flex h-[--container-height] w-full items-center justify-center gap-2 bg-background text-muted-foreground text-sm"
+                role="status">
+                <Icons.spinner aria-hidden="true" className="h-4 w-4 animate-spin" />
                 Loading...
               </div>
             ) : null}
@@ -57,6 +59,7 @@ export function CodePreview({ block }: { block: Block & { hasLiftMode: boolean }
                 setIsLoading(false)
               }}
               src={`/blocks/${block.name}`}
+              title={`Preview of ${block.name}`}
             />
           </ResizablePanel>
           <ResizableHandle

package/src/components/mdx/mdx-components/code/component-preview.tsx

@@ -1,10 +1,11 @@
 'use client'
 
 import { CopyButton } from '@duck-docs/components/copy-button'
+import { Icons } from '@duck-docs/components/icons'
 import { useRegistryIndex } from '@duck-docs/context'
 import { cn } from '@gentleduck/libs/cn'
-import { Button } from '@gentleduck/registry-ui-duckui/button'
-import { Tabs, TabsContent, TabsList, TabsTrigger } from '@gentleduck/registry-ui-duckui/tabs'
+import { Button } from '@gentleduck/registry-ui/button'
+import { Tabs, TabsContent, TabsList, TabsTrigger } from '@gentleduck/registry-ui/tabs'
 import { Crown } from 'lucide-react'
 import * as React from 'react'
 
@@ -18,6 +19,35 @@ interface ComponentPreviewProps extends React.HTMLAttributes<HTMLDivElement> {
   showSettings?: boolean
 }
 
+type CodeFragmentProps = {
+  'data-rehype-pretty-code-fragment'?: unknown
+  children?: React.ReactNode
+}
+
+type CopyValueProps = {
+  __rawString__?: string
+  value?: string
+}
+
+function getCodeStringFromFragment(codeNode: React.ReactElement | undefined): string | null {
+  if (!codeNode || !React.isValidElement<CodeFragmentProps>(codeNode)) {
+    return null
+  }
+
+  if (typeof codeNode.props['data-rehype-pretty-code-fragment'] === 'undefined') {
+    return null
+  }
+
+  const fragmentChildren = React.Children.toArray(codeNode.props.children)
+  const copyNode = fragmentChildren[1]
+
+  if (!copyNode || !React.isValidElement<CopyValueProps>(copyNode)) {
+    return null
+  }
+
+  return copyNode.props.value ?? copyNode.props.__rawString__ ?? null
+}
+
 export function ComponentPreview({
   name,
   children,
@@ -36,17 +66,22 @@ export function ComponentPreview({
 
   const Preview = React.useMemo(() => {
     if (!registryIndex) {
-      return <p className="text-muted-foreground text-sm">Registry index is not configured for this docs app.</p>
+      return (
+        <div className="flex h-full w-full items-center justify-center text-muted-foreground text-sm">
+          Registry index is not configured for this docs app.
+        </div>
+      )
     }
 
     const Component = registryIndex[name]?.component
 
     if (!Component) {
       return (
-        <p className="text-muted-foreground text-sm">
-          Component <code className="relative rounded bg-muted px-[0.3rem] py-[0.2rem] font-mono text-sm">{name}</code>{' '}
-          not found in registry.
-        </p>
+        <div className="flex h-full w-full items-center justify-center text-muted-foreground text-sm">
+          Component{' '}
+          <code className="relative mx-1 rounded bg-muted px-[0.3rem] py-[0.2rem] font-mono text-sm">{name}</code> not
+          found in registry.
+        </div>
       )
     }
 
@@ -54,20 +89,7 @@ export function ComponentPreview({
   }, [name, registryIndex])
 
   const codeString = React.useMemo(() => {
-    if (
-      // ! FIX:
-      //  @ts-ignore 'Code.props' is of type 'unknown'.ts(18046)
-      typeof Code?.props['data-rehype-pretty-code-fragment'] !== 'undefined'
-    ) {
-      const Button = React.Children.toArray(
-        // ! FIX:
-        //  @ts-expect-error Property 'children' does not exist on type '{}'.ts(2339)
-        Code.props.children,
-      ) as React.ReactElement[]
-      // ! FIX:
-      //  @ts-expect-error Property '__rawString__' does not exist on type '{}'.ts(2339)
-      return Button[1]?.props?.value || Button[1]?.props?.__rawString__ || null
-    }
+    return getCodeStringFromFragment(Code)
   }, [Code])
 
   return (
@@ -80,7 +102,7 @@ export function ComponentPreview({
             <TabsList className="w-full justify-start overflow-x-auto rounded-none border-b bg-transparent p-0 [&_button]:shadow-none">
               {TABS.map((tab, idx) => (
                 <TabsTrigger
-                  className="cursor-pointer rounded-none border-b-[2px] border-b-transparent px-12 py-2 [&[aria-selected='true']]:border-b-primary [&[aria-selected='true']]:shadow-none [&_input]:focus-visible:shadow-none [&_input]:focus-visible:ring-transparent [&_input]:focus-visible:ring-offset-0"
+                  className="cursor-pointer rounded-none border-b-[2px] border-b-transparent px-12 py-2 [&[aria-selected='true']]:border-b-primary [&[aria-selected='true']]:shadow-none"
                   key={idx}
                   value={tab.value}>
                   {tab.name}
@@ -90,20 +112,30 @@ export function ComponentPreview({
           )}
         </div>
         <TabsContent className="relative min-w-2/5 rounded-md border" value="preview">
-          <div className="absolute flex w-full items-center justify-between p-4">
+          <div className="absolute flex w-full items-center justify-between p-3">
             <span className="text-muted-foreground text-sm">{}</span>
             <div className="flex items-center gap-2">
-              <CopyButton value={codeString} variant="outline" />
+              <CopyButton value={codeString ?? ''} variant="outline" />
             </div>
           </div>
           <div
-            className={cn('preview flex h-[500px] w-full justify-center overflow-auto p-10', {
+            className={cn('preview flex h-[502px] w-full justify-center overflow-auto p-10', {
               'items-center': align === 'center',
               'items-end': align === 'end',
               'items-start': align === 'start',
             })}
             duck-preview="">
-            {Preview}
+            <React.Suspense
+              fallback={
+                <div
+                  className="flex h-full w-full items-center justify-center gap-2 text-muted-foreground text-sm"
+                  role="status">
+                  <Icons.spinner aria-hidden="true" className="h-4 w-4 animate-spin" />
+                  Loading...
+                </div>
+              }>
+              {Preview}
+            </React.Suspense>
           </div>
         </TabsContent>
         <TabsContent
@@ -127,7 +159,7 @@ export const BuildTab = () => {
       <div className="absolute inset-0 top-0 left-0 flex h-[500px] flex-col items-center justify-center gap-4 rounded-md bg-zinc-700/10 px-4 py-2 backdrop-blur-sm dark:bg-zinc-700/50">
         <div className="flex items-center gap-4">
           <Button className="rounded-sm font-bold" size={'sm'}>
-            <Crown />
+            <Crown aria-hidden="true" />
             <span>Coming soon</span>
           </Button>
         </div>

package/src/components/mdx/mdx-components/code/component-source.tsx

@@ -1,32 +1,62 @@
 'use client'
 
-import { Separator } from '@gentleduck/registry-ui-duckui/separator'
-import { Tabs, TabsContent, TabsList, TabsTrigger } from '@gentleduck/registry-ui-duckui/tabs'
-import type React from 'react'
+import { Icons } from '@duck-docs/components/icons'
+import { cn } from '@gentleduck/libs/cn'
+import { Separator } from '@gentleduck/registry-ui/separator'
+import { Tabs, TabsContent, TabsList, TabsTrigger } from '@gentleduck/registry-ui/tabs'
+import * as React from 'react'
 import { FigcaptionBlock } from './figcaption-block'
 
 interface ComponentSourceProps extends React.HTMLAttributes<HTMLDivElement> {
-  children: React.ReactNode[]
-  src: string
+  children?: React.ReactNode
+  path?: string
+}
+
+function getChildLabel(child: React.ReactNode): string {
+  return (
+    String((child as any).props?.children?.[0]?.props?.__rawString__ ?? '')
+      .split('\n')[0]
+      ?.replace('//', '')
+      .trim() || 'source'
+  )
 }
 
-/** NOTE: the props are not used */
 export function ComponentSource({ children, className, ...props }: ComponentSourceProps) {
-  if (!children.length) {
-    return children
+  const items = React.Children.toArray(children)
+
+  if (items.length === 0) {
+    return (
+      <div
+        className="flex h-24 w-full items-center justify-center gap-2 rounded-md border border-border bg-muted/40 text-muted-foreground text-sm"
+        role="status">
+        <Icons.spinner aria-hidden="true" className="h-4 w-4 animate-spin" />
+        Loading...
+      </div>
+    )
+  }
+
+  // Single file -- render just the code block, no wrapper
+  if (items.length === 1) {
+    const value = getChildLabel(items[0])
+    return (
+      <div className="relative m-0 mt-2 shrink-0 list-none rounded-lg border bg-muted/40 ring-offset-background focus-visible:shadow-none focus-visible:outline-none focus-visible:outline-hidden focus-visible:ring-0 focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 [&>div>div>button]:top-2 [&>div>div>button]:right-2 [&>div>div]:m-0 [&>div]:static [&>div]:my-0 [&>div]:border-none [&>div]:bg-transparent">
+        <FigcaptionBlock>{value}</FigcaptionBlock>
+        {items[0]}
+      </div>
+    )
   }
 
-  const defaultValue = String((children[0] as any).props.children[0].props.__rawString__)
-    .split('\n')[0]
-    ?.replace('//', '') as string
+  // Multiple files -- render with tabs
+  const defaultValue = getChildLabel(items[0])
 
   return (
-    <Tabs className="rounded-md border border-border bg-muted/40" defaultValue={defaultValue}>
+    <Tabs
+      className={cn('rounded-md border border-border bg-muted/40', className)}
+      {...props}
+      defaultValue={defaultValue}>
       <TabsList className="w-[622px] justify-start overflow-x-auto bg-transparent px-2 py-2">
-        {children.map((item, idx) => {
-          const value = String((item as any).props.children[0].props.__rawString__)
-            .split('\n')[0]
-            ?.replace('//', '') as string
+        {items.map((item, idx) => {
+          const value = getChildLabel(item)
           return (
             <TabsTrigger className="aria-[selected='true']:bg-muted" key={idx} value={value}>
               {value}
@@ -35,13 +65,11 @@ export function ComponentSource({ children, className, ...props }: ComponentSour
         })}
       </TabsList>
       <Separator />
-      {children.map((item, idx) => {
-        const value = String((item as any).props.children[0].props.__rawString__)
-          .split('\n')[0]
-          ?.replace('//', '') as string
+      {items.map((item, idx) => {
+        const value = getChildLabel(item)
         return (
           <TabsContent
-            className="relative m-0 bg-transparent focus-visible:shadow-none focus-visible:outline-none focus-visible:ring-0 [&>div>div>button]:top-1 [&>div>div>button]:right-1 [&>div>div]:m-0"
+            className="relative m-0 bg-transparent focus-visible:shadow-none focus-visible:outline-none focus-visible:ring-0 [&>div>div>button]:top-2 [&>div>div>button]:right-2 [&>div>div]:m-0"
             key={idx}
             value={value}>
             <FigcaptionBlock>{value}</FigcaptionBlock>

package/src/components/mdx/mdx-components/code/figcaption-block.tsx

@@ -1,6 +1,5 @@
 import { getIconForLanguageExtension } from '@duck-docs/components/icons'
 import { cn } from '@gentleduck/libs/cn'
-import { Separator } from '@gentleduck/registry-ui-duckui/separator'
 
 export function FigcaptionBlock({ children, className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
   const language = children?.toString().split('.').pop() ?? 'terminal'
@@ -9,17 +8,12 @@ export function FigcaptionBlock({ children, className, ...props }: React.HTMLAtt
 
   return (
     <>
-      <figcaption {...props} className="rounded-lg p-2">
-        <div
-          className={cn(
-            className,
-            'flex items-center gap-2 font-mono text-muted-foreground text-sm ltr:pl-1.5 rtl:pr-1.5 [&_svg]:h-4 [&_svg]:w-4',
-          )}>
+      <figcaption className={cn('border-border border-b p-3', className)} {...props}>
+        <div className="flex items-center gap-2 font-mono text-muted-foreground text-sm ltr:pl-1.5 rtl:pr-1.5 [&_svg]:h-4 [&_svg]:w-4">
           {Icon}
           {children}
         </div>
       </figcaption>
-      <Separator />
     </>
   )
 }