@launch77-shared/app-template-webapp 1.2.0 → 1.2.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @launch77-shared/app-template-webapp
 
+## 1.2.1
+
+### Patch Changes
+
+- 95a40e7: Upgraded default next version from 14 to 15
+
 ## 1.2.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@launch77-shared/app-template-webapp",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Launch77 webapp app template",
   "type": "module",
   "main": "index.js",

package/package.json.hbs

@@ -12,9 +12,11 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "next": "^14.2.0",
+    "dotenv": "^16.4.5",
+    "next": "^15.0.0",
     "react": "^18.3.1",
-    "react-dom": "^18.3.1"
+    "react-dom": "^18.3.1",
+    "@launch77/plugin-runtime": "^0.3.2"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
@@ -22,7 +24,7 @@
     "@types/react-dom": "^18.2.25",
     "autoprefixer": "^10.4.21",
     "eslint": "^8.56.0",
-    "eslint-config-next": "^14.2.0",
+    "eslint-config-next": "^15.0.0",
     "postcss": "^8.5.6",
     "tailwindcss": "^3.4.17",
     "typescript": "^5.3.0"

package/src/app/page.tsx.hbs

@@ -17,6 +17,12 @@ export default function HomePage() {
           >
             Go to Dashboard
           </Link>
+          <Link
+            href="/plugins"
+            className="inline-flex items-center justify-center px-6 py-3 text-base font-medium text-gray-700 bg-white hover:bg-gray-50 border border-gray-300 rounded-lg transition-colors"
+          >
+            View Plugins
+          </Link>
           <Link
             href="/about"
             className="inline-flex items-center justify-center px-6 py-3 text-base font-medium text-gray-700 bg-white hover:bg-gray-50 border border-gray-300 rounded-lg transition-colors"

package/src/app/plugins/page.tsx

@@ -0,0 +1,78 @@
+import Link from 'next/link'
+import { getInstalledPlugins } from '@/modules/plugins/utils'
+
+export default async function PluginsPage() {
+  const plugins = await getInstalledPlugins()
+
+  return (
+    <div className="container mx-auto py-8 px-4">
+      <div>
+        <h1 className="text-3xl font-bold mb-2">Installed Plugins</h1>
+        <p className="text-muted-foreground mb-8">Manage and explore your Launch77 plugins</p>
+
+        {plugins.length === 0 ? (
+          <div className="rounded-lg border border-border bg-card p-8 text-center">
+            <p className="text-muted-foreground mb-4">No plugins installed yet.</p>
+            <p className="text-sm text-muted-foreground">Install plugins using the Launch77 CLI:</p>
+            <code className="mt-2 inline-block rounded bg-muted px-3 py-1 text-sm">launch77 plugin:install [plugin-name]</code>
+          </div>
+        ) : (
+          <div className="overflow-x-auto">
+            <table className="w-full border-collapse">
+              <thead>
+                <tr className="border-b">
+                  <th className="text-left p-3 font-semibold">Plugin</th>
+                  <th className="text-left p-3 font-semibold">Version</th>
+                  <th className="text-left p-3 font-semibold">Description</th>
+                  <th className="text-left p-3 font-semibold">Installed</th>
+                  <th className="text-left p-3 font-semibold">Showcase</th>
+                </tr>
+              </thead>
+              <tbody>
+                {plugins.map((plugin) => (
+                  <tr key={plugin.name} className="border-b hover:bg-muted/50 transition-colors">
+                    <td className="p-3">
+                      <span className="font-mono text-sm">{plugin.name}</span>
+                    </td>
+                    <td className="p-3">
+                      <span className="text-sm text-muted-foreground">{plugin.version}</span>
+                    </td>
+                    <td className="p-3">
+                      <span className="text-sm">{plugin.description || '—'}</span>
+                    </td>
+                    <td className="p-3">
+                      <span className="text-sm text-muted-foreground">
+                        {new Date(plugin.installedAt).toLocaleDateString('en-US', {
+                          year: 'numeric',
+                          month: 'short',
+                          day: 'numeric',
+                          hour: '2-digit',
+                          minute: '2-digit',
+                          second: '2-digit',
+                        })}
+                      </span>
+                    </td>
+                    <td className="p-3">
+                      {plugin.showcaseUrl ? (
+                        <Link href={plugin.showcaseUrl} className="text-sm text-primary hover:underline inline-flex items-center gap-1">
+                          View
+                          <svg className="w-3 h-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 5l7 7-7 7" />
+                          </svg>
+                        </Link>
+                      ) : (
+                        <span className="text-sm text-muted-foreground">—</span>
+                      )}
+                    </td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+        )}
+
+        {plugins.length > 0 && <div className="mt-8 text-sm text-muted-foreground">Total plugins installed: {plugins.length}</div>}
+      </div>
+    </div>
+  )
+}

package/src/modules/plugins/utils.test.ts

@@ -0,0 +1,335 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import fs from 'fs'
+import path from 'path'
+import { getInstalledPlugins } from './utils'
+
+// Mock fs and path modules
+vi.mock('fs')
+vi.mock('path', async () => {
+  const actual = await vi.importActual('path')
+  return {
+    ...actual,
+    join: vi.fn((...args) => args.join('/')),
+  }
+})
+
+describe('getInstalledPlugins', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    // Mock process.cwd()
+    vi.spyOn(process, 'cwd').mockReturnValue('/test/project')
+  })
+
+  it('should return empty array when no plugins are installed', async () => {
+    const mockPackageJson = {
+      dependencies: {
+        react: '^18.0.0',
+        next: '^14.0.0',
+      },
+      launch77: {
+        // No installedPlugins
+      },
+    }
+
+    vi.mocked(fs.readFileSync).mockImplementation((filePath) => {
+      if (filePath === '/test/project/package.json') {
+        return JSON.stringify(mockPackageJson)
+      }
+      throw new Error('File not found')
+    })
+
+    const plugins = await getInstalledPlugins()
+    expect(plugins).toEqual([])
+  })
+
+  it('should extract plugin metadata from launch77.installedPlugins', async () => {
+    const mockPackageJson = {
+      dependencies: {
+        react: '^18.0.0',
+      },
+      launch77: {
+        installedPlugins: {
+          ui: {
+            package: '@launch77-shared/plugin-ui',
+            version: '0.3.1',
+            installedAt: '2024-01-01T00:00:00.000Z',
+            source: 'npm',
+          },
+        },
+      },
+    }
+
+    const mockPluginPackageJson = {
+      name: '@launch77-shared/plugin-ui',
+      version: '0.3.1',
+      description: 'UI components library',
+      author: 'Launch77 Team',
+      repository: { url: 'https://github.com/launch77/ui' },
+      keywords: ['launch77', 'ui', 'components'],
+    }
+
+    const mockPluginJson = {
+      targets: ['app'],
+      showcaseUrl: '/ui-examples',
+    }
+
+    vi.mocked(fs.readFileSync).mockImplementation((filePath) => {
+      if (filePath === '/test/project/package.json') {
+        return JSON.stringify(mockPackageJson)
+      }
+      if (filePath === '/test/project/node_modules/@launch77-shared/plugin-ui/package.json') {
+        return JSON.stringify(mockPluginPackageJson)
+      }
+      if (filePath === '/test/project/node_modules/@launch77-shared/plugin-ui/plugin.json') {
+        return JSON.stringify(mockPluginJson)
+      }
+      throw new Error('File not found')
+    })
+
+    vi.mocked(fs.existsSync).mockImplementation((filePath) => {
+      return filePath.includes('plugin-ui')
+    })
+
+    const plugins = await getInstalledPlugins()
+    expect(plugins).toHaveLength(1)
+    expect(plugins[0]).toEqual({
+      name: '@launch77-shared/plugin-ui',
+      version: '0.3.1',
+      description: 'UI components library',
+      author: 'Launch77 Team',
+      repository: 'https://github.com/launch77/ui',
+      keywords: ['launch77', 'ui', 'components'],
+      showcaseUrl: '/ui-examples',
+    })
+  })
+
+  it('should handle plugins without showcaseUrl', async () => {
+    const mockPackageJson = {
+      launch77: {
+        installedPlugins: {
+          release: {
+            package: '@launch77-shared/plugin-release',
+            version: '1.0.0',
+            installedAt: '2024-01-01T00:00:00.000Z',
+            source: 'npm',
+          },
+        },
+      },
+    }
+
+    const mockPluginPackageJson = {
+      name: '@launch77-shared/plugin-release',
+      version: '1.0.0',
+      description: 'Release automation',
+    }
+
+    const mockPluginJson = {
+      targets: ['app', 'library'],
+      // No showcaseUrl
+    }
+
+    vi.mocked(fs.readFileSync).mockImplementation((filePath) => {
+      if (filePath === '/test/project/package.json') {
+        return JSON.stringify(mockPackageJson)
+      }
+      if (filePath === '/test/project/node_modules/@launch77-shared/plugin-release/package.json') {
+        return JSON.stringify(mockPluginPackageJson)
+      }
+      if (filePath === '/test/project/node_modules/@launch77-shared/plugin-release/plugin.json') {
+        return JSON.stringify(mockPluginJson)
+      }
+      throw new Error('File not found')
+    })
+
+    vi.mocked(fs.existsSync).mockImplementation((filePath) => {
+      return filePath.includes('plugin-release')
+    })
+
+    const plugins = await getInstalledPlugins()
+    expect(plugins).toHaveLength(1)
+    expect(plugins[0].showcaseUrl).toBeNull()
+  })
+
+  it('should sort plugins alphabetically by name', async () => {
+    const mockPackageJson = {
+      launch77: {
+        installedPlugins: {
+          ui: {
+            package: '@launch77-shared/plugin-ui',
+            version: '0.3.1',
+            installedAt: '2024-01-01T00:00:00.000Z',
+            source: 'npm',
+          },
+          'analytics-web': {
+            package: '@launch77-shared/plugin-analytics-web',
+            version: '1.0.0',
+            installedAt: '2024-01-01T00:00:00.000Z',
+            source: 'npm',
+          },
+          marketing: {
+            package: '@launch77-shared/plugin-marketing',
+            version: '0.5.0',
+            installedAt: '2024-01-01T00:00:00.000Z',
+            source: 'npm',
+          },
+        },
+      },
+    }
+
+    vi.mocked(fs.readFileSync).mockImplementation((filePath) => {
+      if (filePath === '/test/project/package.json') {
+        return JSON.stringify(mockPackageJson)
+      }
+      // Return minimal package.json for each plugin
+      if (filePath.includes('/package.json') && filePath.includes('node_modules')) {
+        const name = filePath.match(/plugin-[^/]+/)?.[0] || 'unknown'
+        return JSON.stringify({
+          name: `@launch77-shared/${name}`,
+          version: '1.0.0',
+        })
+      }
+      return '{}'
+    })
+
+    vi.mocked(fs.existsSync).mockReturnValue(true)
+
+    const plugins = await getInstalledPlugins()
+    expect(plugins).toHaveLength(3)
+    expect(plugins[0].name).toBe('@launch77-shared/plugin-analytics-web')
+    expect(plugins[1].name).toBe('@launch77-shared/plugin-marketing')
+    expect(plugins[2].name).toBe('@launch77-shared/plugin-ui')
+  })
+
+  it('should handle malformed plugin.json gracefully', async () => {
+    const mockPackageJson = {
+      launch77: {
+        installedPlugins: {
+          broken: {
+            package: '@launch77-shared/plugin-broken',
+            version: '1.0.0',
+            installedAt: '2024-01-01T00:00:00.000Z',
+            source: 'npm',
+          },
+        },
+      },
+    }
+
+    const mockPluginPackageJson = {
+      name: '@launch77-shared/plugin-broken',
+      version: '1.0.0',
+      description: 'Plugin with broken config',
+    }
+
+    vi.mocked(fs.readFileSync).mockImplementation((filePath) => {
+      if (filePath === '/test/project/package.json') {
+        return JSON.stringify(mockPackageJson)
+      }
+      if (filePath === '/test/project/node_modules/@launch77-shared/plugin-broken/package.json') {
+        return JSON.stringify(mockPluginPackageJson)
+      }
+      if (filePath === '/test/project/node_modules/@launch77-shared/plugin-broken/plugin.json') {
+        return 'invalid json {' // Malformed JSON
+      }
+      throw new Error('File not found')
+    })
+
+    vi.mocked(fs.existsSync).mockImplementation((filePath) => {
+      return filePath.includes('plugin-broken')
+    })
+
+    const plugins = await getInstalledPlugins()
+    expect(plugins).toHaveLength(1)
+    expect(plugins[0].showcaseUrl).toBeNull() // Should handle error and continue
+  })
+
+  it('should return empty array when package.json cannot be read', async () => {
+    vi.mocked(fs.readFileSync).mockImplementation(() => {
+      throw new Error('Cannot read file')
+    })
+
+    const plugins = await getInstalledPlugins()
+    expect(plugins).toEqual([])
+  })
+
+  it('should handle multiple installed plugins', async () => {
+    const mockPackageJson = {
+      launch77: {
+        installedPlugins: {
+          ui: {
+            package: '@launch77-shared/plugin-ui',
+            version: '0.3.1',
+            installedAt: '2024-01-01T00:00:00.000Z',
+            source: 'npm',
+          },
+          test: {
+            package: '@launch77-shared/plugin-test',
+            version: '1.0.0',
+            installedAt: '2024-01-01T00:00:00.000Z',
+            source: 'npm',
+          },
+        },
+      },
+    }
+
+    vi.mocked(fs.readFileSync).mockImplementation((filePath) => {
+      if (filePath === '/test/project/package.json') {
+        return JSON.stringify(mockPackageJson)
+      }
+      if (filePath.includes('/package.json') && filePath.includes('node_modules')) {
+        const name = filePath.match(/plugin-[^/]+/)?.[0] || 'unknown'
+        return JSON.stringify({
+          name: `@launch77-shared/${name}`,
+          version: '1.0.0',
+        })
+      }
+      return '{}'
+    })
+
+    vi.mocked(fs.existsSync).mockReturnValue(true)
+
+    const plugins = await getInstalledPlugins()
+    expect(plugins).toHaveLength(2)
+    expect(plugins.some((p) => p.name === '@launch77-shared/plugin-ui')).toBe(true)
+    expect(plugins.some((p) => p.name === '@launch77-shared/plugin-test')).toBe(true)
+  })
+
+  it('should handle author as object', async () => {
+    const mockPackageJson = {
+      launch77: {
+        installedPlugins: {
+          ui: {
+            package: '@launch77-shared/plugin-ui',
+            version: '0.3.1',
+            installedAt: '2024-01-01T00:00:00.000Z',
+            source: 'npm',
+          },
+        },
+      },
+    }
+
+    const mockPluginPackageJson = {
+      name: '@launch77-shared/plugin-ui',
+      version: '0.3.1',
+      author: {
+        name: 'John Doe',
+        email: 'john@example.com',
+      },
+    }
+
+    vi.mocked(fs.readFileSync).mockImplementation((filePath) => {
+      if (filePath === '/test/project/package.json') {
+        return JSON.stringify(mockPackageJson)
+      }
+      if (filePath === '/test/project/node_modules/@launch77-shared/plugin-ui/package.json') {
+        return JSON.stringify(mockPluginPackageJson)
+      }
+      return '{}'
+    })
+
+    vi.mocked(fs.existsSync).mockReturnValue(true)
+
+    const plugins = await getInstalledPlugins()
+    expect(plugins).toHaveLength(1)
+    expect(plugins[0].author).toBe('John Doe')
+  })
+})

package/src/modules/plugins/utils.ts

@@ -0,0 +1,124 @@
+import path from 'path'
+import fs from 'fs'
+import { PackageManifestService } from '@launch77/plugin-runtime'
+import { MetadataService } from '@launch77/plugin-runtime'
+import type { InstalledPluginMetadata } from '@launch77/plugin-runtime'
+
+export interface InstalledPlugin {
+  name: string
+  version: string
+  description: string
+  author: string
+  repository: string
+  keywords: string[]
+  showcaseUrl: string | null
+  installedAt: string
+}
+
+/**
+ * Resolve the actual npm package name for a plugin
+ */
+function resolvePluginPackageName(pluginKey: string, metadata: InstalledPluginMetadata): string {
+  // For local plugins, we need to construct the proper package name
+  // The metadata.package field might just be the plugin name without the scope
+  if (metadata.source === 'local') {
+    // Check if it already has a scope
+    if (metadata.package.startsWith('@')) {
+      return metadata.package
+    }
+    // Add the workspace scope for local plugins
+    return `@launch77-shared/plugin-${metadata.package}`
+  }
+  // For npm plugins, use the package as-is
+  return metadata.package
+}
+
+/**
+ * Try to find a module by checking multiple locations
+ * This handles workspace hoisting and different module resolution scenarios
+ */
+function findModulePath(moduleName: string, startPath: string): string | null {
+  const attempts = [
+    // Direct path in current directory's node_modules
+    path.join(startPath, 'node_modules', moduleName),
+    // Check parent directories (for workspace hoisting)
+    path.join(startPath, '..', 'node_modules', moduleName),
+    path.join(startPath, '..', '..', 'node_modules', moduleName),
+    path.join(startPath, '..', '..', '..', 'node_modules', moduleName),
+    // Check workspace root directly for launch77-shared workspace
+    path.join(startPath, '..', '..', '..', 'launch77-shared', 'node_modules', moduleName),
+  ]
+
+  for (const attemptPath of attempts) {
+    if (fs.existsSync(attemptPath)) {
+      return attemptPath
+    }
+  }
+
+  return null
+}
+
+/**
+ * Get all installed Launch77 plugins using the official PackageManifestService
+ */
+export async function getInstalledPlugins(): Promise<InstalledPlugin[]> {
+  const manifestService = new PackageManifestService()
+  const metadataService = new MetadataService()
+  const currentPath = process.cwd()
+
+  try {
+    // Get installed plugins from the manifest service
+    const installedPlugins: Record<string, InstalledPluginMetadata> = await manifestService.getInstalledPlugins(currentPath)
+    const plugins: InstalledPlugin[] = []
+
+    for (const [pluginKey, pluginMeta] of Object.entries(installedPlugins)) {
+      try {
+        // Resolve the actual package name
+        const packageName = resolvePluginPackageName(pluginKey, pluginMeta)
+
+        // Find the plugin module path
+        const pluginPath = findModulePath(packageName, currentPath)
+
+        if (!pluginPath) {
+          // Plugin not found in node_modules - skip silently
+          continue
+        }
+
+        // Read plugin.json for showcaseUrl
+        let showcaseUrl: string | null = null
+        try {
+          const pluginMetadata = await metadataService.readPluginMetadata(pluginPath)
+          showcaseUrl = pluginMetadata.showcaseUrl || null
+        } catch {
+          // Plugin.json might not exist or be invalid - that's ok
+        }
+
+        // Read package.json for additional metadata
+        const pluginPackageJsonPath = path.join(pluginPath, 'package.json')
+        if (fs.existsSync(pluginPackageJsonPath)) {
+          const pluginPackageJson = JSON.parse(fs.readFileSync(pluginPackageJsonPath, 'utf-8'))
+
+          plugins.push({
+            name: pluginPackageJson.name || packageName,
+            version: pluginMeta.version,
+            description: pluginPackageJson.description || '',
+            author: typeof pluginPackageJson.author === 'string' ? pluginPackageJson.author : pluginPackageJson.author?.name || '',
+            repository: pluginPackageJson.repository?.url || pluginPackageJson.repository || '',
+            keywords: pluginPackageJson.keywords || [],
+            showcaseUrl,
+            installedAt: pluginMeta.installedAt,
+          })
+        }
+      } catch {
+        // Error processing this plugin - skip silently
+        continue
+      }
+    }
+
+    // Sort by installation date descending (newest first)
+    return plugins.sort((a, b) => new Date(b.installedAt).getTime() - new Date(a.installedAt).getTime())
+  } catch {
+    // Error reading manifest
+    return []
+  }
+}

package/src/modules/showcase/components/BackToTop.tsx

@@ -0,0 +1,47 @@
+'use client'
+
+import React, { useState, useEffect } from 'react'
+
+export function BackToTop() {
+  const [isVisible, setIsVisible] = useState(false)
+
+  // Show button when page is scrolled down
+  useEffect(() => {
+    const toggleVisibility = () => {
+      if (window.pageYOffset > 300) {
+        setIsVisible(true)
+      } else {
+        setIsVisible(false)
+      }
+    }
+
+    window.addEventListener('scroll', toggleVisibility)
+    return () => window.removeEventListener('scroll', toggleVisibility)
+  }, [])
+
+  const scrollToTop = () => {
+    window.scrollTo({
+      top: 0,
+      behavior: 'smooth',
+    })
+  }
+
+  return (
+    <button
+      onClick={scrollToTop}
+      className={`
+        fixed bottom-6 right-6 z-40
+        p-3 bg-white text-gray-700 border border-gray-200
+        rounded-lg shadow-lg
+        hover:bg-gray-50 hover:shadow-xl
+        transition-all duration-300 ease-in-out
+        ${isVisible ? 'opacity-100 translate-y-0' : 'opacity-0 translate-y-10 pointer-events-none'}
+      `}
+      aria-label="Back to top"
+    >
+      <svg className="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M5 10l7-7m0 0l7 7m-7-7v18" />
+      </svg>
+    </button>
+  )
+}

package/src/modules/showcase/components/CodeBlock.tsx

@@ -0,0 +1,76 @@
+'use client'
+
+import React, { useState } from 'react'
+
+interface CodeBlockProps {
+  code: string
+  language?: string
+  title?: string
+  className?: string
+}
+
+export function CodeBlock({ code, language = 'typescript', title, className = '' }: CodeBlockProps) {
+  const [copied, setCopied] = useState(false)
+
+  const handleCopy = async () => {
+    try {
+      await navigator.clipboard.writeText(code)
+      setCopied(true)
+      setTimeout(() => setCopied(false), 2000)
+    } catch (err) {
+      console.error('Failed to copy code:', err)
+    }
+  }
+
+  return (
+    <div className={`relative group ${className}`}>
+      {title && (
+        <div className="flex items-center justify-between px-4 py-2 bg-gray-100 border border-gray-200 border-b-0 rounded-t-lg">
+          <span className="text-sm font-medium text-gray-700">{title}</span>
+          <span className="text-xs text-gray-500">{language}</span>
+        </div>
+      )}
+
+      <div className={`relative bg-gray-900 ${title ? 'rounded-b-lg' : 'rounded-lg'} overflow-hidden`}>
+        {/* Copy button */}
+        <button
+          onClick={handleCopy}
+          className={`
+            absolute top-2 right-2 px-3 py-1.5 text-xs font-medium
+            bg-gray-800 hover:bg-gray-700 text-gray-300 hover:text-white
+            rounded-md transition-all duration-200
+            opacity-0 group-hover:opacity-100 focus:opacity-100
+            ${copied ? 'bg-green-600 hover:bg-green-600 text-white' : ''}
+          `}
+          aria-label={copied ? 'Copied!' : 'Copy code'}
+        >
+          {copied ? (
+            <span className="flex items-center gap-1">
+              <svg className="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M5 13l4 4L19 7" />
+              </svg>
+              Copied
+            </span>
+          ) : (
+            <span className="flex items-center gap-1">
+              <svg className="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M8 16H6a2 2 0 01-2-2V6a2 2 0 012-2h8a2 2 0 012 2v2m-6 12h8a2 2 0 002-2v-8a2 2 0 00-2-2h-8a2 2 0 00-2 2v8a2 2 0 002 2z" />
+              </svg>
+              Copy
+            </span>
+          )}
+        </button>
+
+        {/* Code content */}
+        <pre className="p-4 overflow-x-auto">
+          <code className="text-sm text-gray-100 font-mono">{code}</code>
+        </pre>
+      </div>
+    </div>
+  )
+}
+
+// Export a simple inline code component too
+export function InlineCode({ children }: { children: React.ReactNode }) {
+  return <code className="px-1.5 py-0.5 text-sm bg-gray-100 text-gray-900 rounded font-mono">{children}</code>
+}

package/src/modules/showcase/components/MobileMenu.tsx

@@ -0,0 +1,154 @@
+'use client'
+
+import React, { useState, useEffect } from 'react'
+import type { ShowcaseSection } from './ShowcaseLayout'
+
+interface MobileMenuProps {
+  isOpen: boolean
+  onClose: () => void
+  sections: ShowcaseSection[]
+  activeSection: string
+  title: string
+}
+
+export function MobileMenu({ isOpen, onClose, sections, activeSection, title }: MobileMenuProps) {
+  const [expandedSections, setExpandedSections] = useState<string[]>(sections.map((s) => s.id))
+
+  // Handle escape key
+  useEffect(() => {
+    const handleEscape = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        onClose()
+      }
+    }
+
+    if (isOpen) {
+      document.addEventListener('keydown', handleEscape)
+      return () => document.removeEventListener('keydown', handleEscape)
+    }
+  }, [isOpen, onClose])
+
+  const toggleSection = (sectionId: string) => {
+    setExpandedSections((prev) => (prev.includes(sectionId) ? prev.filter((id) => id !== sectionId) : [...prev, sectionId]))
+  }
+
+  const scrollToSection = (id: string) => {
+    const element = document.getElementById(id)
+    if (element) {
+      const offset = 80
+      const elementPosition = element.getBoundingClientRect().top
+      const offsetPosition = elementPosition + window.pageYOffset - offset
+
+      window.scrollTo({
+        top: offsetPosition,
+        behavior: 'smooth',
+      })
+
+      onClose() // Close menu after navigation
+    }
+  }
+
+  return (
+    <>
+      {/* Backdrop */}
+      {isOpen && <div className="fixed inset-0 bg-black/50 z-40 md:hidden transition-opacity" onClick={onClose} aria-hidden="true" />}
+
+      {/* Drawer */}
+      <aside
+        className={`
+          fixed inset-y-0 left-0 z-50 w-72 bg-white
+          transform transition-transform duration-300 ease-in-out
+          ${isOpen ? 'translate-x-0' : '-translate-x-full'}
+          md:hidden
+          shadow-xl
+        `}
+        aria-label="Mobile navigation"
+      >
+        <div className="flex flex-col h-full">
+          {/* Header */}
+          <div className="flex items-center justify-between px-4 py-4 border-b border-gray-200">
+            <h2 className="text-sm font-semibold text-gray-900 uppercase tracking-wider">{title}</h2>
+            <button onClick={onClose} className="p-1 rounded-md text-gray-500 hover:text-gray-700 hover:bg-gray-100 transition-colors" aria-label="Close navigation menu">
+              <svg className="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
+              </svg>
+            </button>
+          </div>
+
+          {/* Navigation */}
+          <nav className="flex-1 overflow-y-auto px-4 py-4">
+            <div className="space-y-1">
+              {sections.map((section) => {
+                const hasItems = section.items && section.items.length > 0
+                const isExpanded = expandedSections.includes(section.id)
+                const isSectionActive = activeSection === section.id
+                const hasActiveChild = section.items?.some((item) => item.id === activeSection)
+
+                return (
+                  <div key={section.id}>
+                    {/* Section header */}
+                    <button
+                      onClick={() => {
+                        if (hasItems) {
+                          toggleSection(section.id)
+                        }
+                        scrollToSection(section.id)
+                      }}
+                      className={`
+                        w-full flex items-center justify-between px-3 py-2 text-sm font-medium rounded-md transition-colors
+                        ${isSectionActive || hasActiveChild ? 'bg-blue-50 text-blue-700' : 'text-gray-700 hover:bg-gray-100'}
+                      `}
+                    >
+                      <span>{section.title}</span>
+                      {hasItems && (
+                        <svg
+                          className={`
+                            w-4 h-4 transition-transform duration-200
+                            ${isExpanded ? 'rotate-90' : ''}
+                          `}
+                          fill="currentColor"
+                          viewBox="0 0 20 20"
+                        >
+                          <path fillRule="evenodd" d="M7.293 14.707a1 1 0 010-1.414L10.586 10 7.293 6.707a1 1 0 011.414-1.414l4 4a1 1 0 010 1.414l-4 4a1 1 0 01-1.414 0z" clipRule="evenodd" />
+                        </svg>
+                      )}
+                    </button>
+
+                    {/* Section items */}
+                    {hasItems && (
+                      <div
+                        className={`
+                          overflow-hidden transition-all duration-200
+                          ${isExpanded ? 'max-h-96' : 'max-h-0'}
+                        `}
+                      >
+                        <div className="ml-4 mt-1 space-y-1">
+                          {section.items.map((item) => {
+                            const isItemActive = activeSection === item.id
+
+                            return (
+                              <button
+                                key={item.id}
+                                onClick={() => scrollToSection(item.id)}
+                                className={`
+                                  w-full text-left px-3 py-1.5 text-sm rounded-md transition-colors
+                                  ${isItemActive ? 'bg-blue-100 text-blue-700 font-medium' : 'text-gray-600 hover:bg-gray-100 hover:text-gray-900'}
+                                `}
+                              >
+                                {item.title}
+                              </button>
+                            )
+                          })}
+                        </div>
+                      </div>
+                    )}
+                  </div>
+                )
+              })}
+            </div>
+          </nav>
+        </div>
+      </aside>
+    </>
+  )
+}

package/src/modules/showcase/components/NavigationSidebar.tsx

@@ -0,0 +1,120 @@
+'use client'
+
+import React, { useState } from 'react'
+import type { ShowcaseSection } from './ShowcaseLayout'
+
+interface NavigationSidebarProps {
+  sections: ShowcaseSection[]
+  activeSection: string
+  title: string
+}
+
+export function NavigationSidebar({ sections, activeSection, title }: NavigationSidebarProps) {
+  const [expandedSections, setExpandedSections] = useState<string[]>(
+    // Start with all sections expanded
+    sections.map((s) => s.id)
+  )
+
+  const toggleSection = (sectionId: string) => {
+    setExpandedSections((prev) => (prev.includes(sectionId) ? prev.filter((id) => id !== sectionId) : [...prev, sectionId]))
+  }
+
+  const scrollToSection = (id: string) => {
+    const element = document.getElementById(id)
+    if (element) {
+      const offset = 80 // Account for any fixed headers
+      const elementPosition = element.getBoundingClientRect().top
+      const offsetPosition = elementPosition + window.pageYOffset - offset
+
+      window.scrollTo({
+        top: offsetPosition,
+        behavior: 'smooth',
+      })
+    }
+  }
+
+  return (
+    <aside className="sticky top-0 h-screen w-64 overflow-y-auto border-r border-gray-200 bg-gray-50">
+      <div className="px-4 py-6">
+        {/* Sidebar header */}
+        <div className="mb-6 pb-6 border-b border-gray-200">
+          <h2 className="text-sm font-semibold text-gray-900 uppercase tracking-wider">{title}</h2>
+        </div>
+
+        {/* Navigation sections */}
+        <nav className="space-y-1" aria-label="Showcase navigation">
+          {sections.map((section) => {
+            const hasItems = section.items && section.items.length > 0
+            const isExpanded = expandedSections.includes(section.id)
+            const isSectionActive = activeSection === section.id
+            const hasActiveChild = section.items?.some((item) => item.id === activeSection)
+
+            return (
+              <div key={section.id}>
+                {/* Section header */}
+                <button
+                  onClick={() => {
+                    if (hasItems) {
+                      toggleSection(section.id)
+                    }
+                    scrollToSection(section.id)
+                  }}
+                  className={`
+                    w-full flex items-center justify-between px-3 py-2 text-sm font-medium rounded-md transition-colors
+                    ${isSectionActive || hasActiveChild ? 'bg-blue-50 text-blue-700' : 'text-gray-700 hover:bg-gray-100'}
+                  `}
+                  aria-expanded={hasItems ? isExpanded : undefined}
+                  aria-controls={hasItems ? `section-${section.id}` : undefined}
+                >
+                  <span>{section.title}</span>
+                  {hasItems && (
+                    <svg
+                      className={`
+                        w-4 h-4 transition-transform duration-200
+                        ${isExpanded ? 'rotate-90' : ''}
+                      `}
+                      fill="currentColor"
+                      viewBox="0 0 20 20"
+                    >
+                      <path fillRule="evenodd" d="M7.293 14.707a1 1 0 010-1.414L10.586 10 7.293 6.707a1 1 0 011.414-1.414l4 4a1 1 0 010 1.414l-4 4a1 1 0 01-1.414 0z" clipRule="evenodd" />
+                    </svg>
+                  )}
+                </button>
+
+                {/* Section items (collapsible) */}
+                {hasItems && (
+                  <div
+                    id={`section-${section.id}`}
+                    className={`
+                      overflow-hidden transition-all duration-200
+                      ${isExpanded ? 'max-h-96' : 'max-h-0'}
+                    `}
+                  >
+                    <div className="ml-4 mt-1 space-y-1">
+                      {section.items.map((item) => {
+                        const isItemActive = activeSection === item.id
+
+                        return (
+                          <button
+                            key={item.id}
+                            onClick={() => scrollToSection(item.id)}
+                            className={`
+                              w-full text-left px-3 py-1.5 text-sm rounded-md transition-colors
+                              ${isItemActive ? 'bg-blue-100 text-blue-700 font-medium' : 'text-gray-600 hover:bg-gray-100 hover:text-gray-900'}
+                            `}
+                          >
+                            {item.title}
+                          </button>
+                        )
+                      })}
+                    </div>
+                  </div>
+                )}
+              </div>
+            )
+          })}
+        </nav>
+      </div>
+    </aside>
+  )
+}

package/src/modules/showcase/components/ShowcaseLayout.tsx

@@ -0,0 +1,118 @@
+'use client'
+
+import React, { useState, useEffect } from 'react'
+import { NavigationSidebar } from './NavigationSidebar'
+import { MobileMenu } from './MobileMenu'
+import { BackToTop } from './BackToTop'
+import { useScrollSpy } from '../hooks/useScrollSpy'
+
+export interface ShowcaseSection {
+  id: string
+  title: string
+  items?: Array<{
+    id: string
+    title: string
+  }>
+}
+
+export interface ShowcaseLayoutProps {
+  title: string
+  description?: string
+  sections: ShowcaseSection[]
+  children: React.ReactNode
+}
+
+export function ShowcaseLayout({ title, description, sections, children }: ShowcaseLayoutProps) {
+  const [mobileMenuOpen, setMobileMenuOpen] = useState(false)
+  const [mounted, setMounted] = useState(false)
+
+  // Get all section IDs for scroll spy
+  const sectionIds = sections.flatMap((section) => [section.id, ...(section.items?.map((item) => item.id) || [])])
+
+  const activeSection = useScrollSpy(sectionIds)
+
+  // Handle mounting to avoid hydration issues
+  useEffect(() => {
+    setMounted(true)
+  }, [])
+
+  // Close mobile menu on window resize
+  useEffect(() => {
+    const handleResize = () => {
+      if (window.innerWidth >= 768) {
+        setMobileMenuOpen(false)
+      }
+    }
+
+    window.addEventListener('resize', handleResize)
+    return () => window.removeEventListener('resize', handleResize)
+  }, [])
+
+  // Prevent body scroll when mobile menu is open
+  useEffect(() => {
+    if (mobileMenuOpen) {
+      document.body.style.overflow = 'hidden'
+    } else {
+      document.body.style.overflow = ''
+    }
+
+    return () => {
+      document.body.style.overflow = ''
+    }
+  }, [mobileMenuOpen])
+
+  if (!mounted) {
+    // Return a simplified version during SSR to avoid hydration mismatch
+    return (
+      <div className="min-h-screen bg-white">
+        <div className="mx-auto max-w-7xl">
+          <main className="px-4 py-12 sm:px-6 lg:px-8">
+            <header className="mb-12">
+              <h1 className="text-4xl font-bold tracking-tight text-gray-900">{title}</h1>
+              {description && <p className="mt-4 text-lg text-gray-600">{description}</p>}
+            </header>
+            {children}
+          </main>
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div className="min-h-screen bg-white">
+      {/* Mobile menu button */}
+      <button onClick={() => setMobileMenuOpen(true)} className="fixed top-4 left-4 z-50 flex items-center justify-center w-10 h-10 bg-white border border-gray-200 rounded-lg shadow-sm md:hidden hover:bg-gray-50 transition-colors" aria-label="Open navigation menu">
+        <svg className="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M4 6h16M4 12h16M4 18h16" />
+        </svg>
+      </button>
+
+      {/* Mobile menu */}
+      <MobileMenu isOpen={mobileMenuOpen} onClose={() => setMobileMenuOpen(false)} sections={sections} activeSection={activeSection} title={title} />
+
+      {/* Desktop layout */}
+      <div className="flex">
+        {/* Desktop sidebar */}
+        <div className="hidden md:block">
+          <NavigationSidebar sections={sections} activeSection={activeSection} title={title} />
+        </div>
+
+        {/* Main content */}
+        <main className="flex-1 px-4 py-12 sm:px-6 lg:px-8">
+          <div className="mx-auto max-w-4xl">
+            <header className="mb-12">
+              <h1 className="text-4xl font-bold tracking-tight text-gray-900">{title}</h1>
+              {description && <p className="mt-4 text-lg text-gray-600">{description}</p>}
+            </header>
+
+            {/* Content with proper spacing */}
+            <div className="space-y-16">{children}</div>
+          </div>
+        </main>
+      </div>
+
+      {/* Back to top button */}
+      <BackToTop />
+    </div>
+  )
+}

package/src/modules/showcase/hooks/useScrollSpy.ts

@@ -0,0 +1,98 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+
+/**
+ * Hook that tracks which section is currently visible in the viewport
+ * Used to highlight the active section in the navigation
+ */
+export function useScrollSpy(sectionIds: string[]): string {
+  const [activeSection, setActiveSection] = useState<string>('')
+
+  useEffect(() => {
+    if (typeof window === 'undefined' || sectionIds.length === 0) {
+      return
+    }
+
+    // Options for the Intersection Observer
+    // rootMargin adjusts the observation area:
+    // - negative top margin accounts for any fixed headers
+    // - negative bottom margin ensures we switch sections before the bottom is reached
+    const observerOptions: IntersectionObserverInit = {
+      root: null,
+      rootMargin: '-80px 0px -80% 0px',
+      threshold: 0,
+    }
+
+    // Callback for when sections enter/leave the viewport
+    const observerCallback: IntersectionObserverCallback = (entries) => {
+      entries.forEach((entry) => {
+        if (entry.isIntersecting) {
+          setActiveSection(entry.target.id)
+        }
+      })
+    }
+
+    // Create the observer
+    const observer = new IntersectionObserver(observerCallback, observerOptions)
+
+    // Observe all sections
+    const elements: Element[] = []
+    sectionIds.forEach((id) => {
+      const element = document.getElementById(id)
+      if (element) {
+        observer.observe(element)
+        elements.push(element)
+      }
+    })
+
+    // Cleanup function
+    return () => {
+      elements.forEach((element) => {
+        observer.unobserve(element)
+      })
+      observer.disconnect()
+    }
+  }, [sectionIds])
+
+  return activeSection
+}
+
+/**
+ * Hook for managing mobile menu state
+ */
+export function useMobileMenu() {
+  const [isOpen, setIsOpen] = useState(false)
+
+  // Close menu when window is resized to desktop size
+  useEffect(() => {
+    const handleResize = () => {
+      if (window.innerWidth >= 768) {
+        setIsOpen(false)
+      }
+    }
+
+    window.addEventListener('resize', handleResize)
+    return () => window.removeEventListener('resize', handleResize)
+  }, [])
+
+  // Prevent body scroll when menu is open
+  useEffect(() => {
+    if (isOpen) {
+      document.body.style.overflow = 'hidden'
+    } else {
+      document.body.style.overflow = ''
+    }
+
+    return () => {
+      document.body.style.overflow = ''
+    }
+  }, [isOpen])
+
+  return {
+    isOpen,
+    open: () => setIsOpen(true),
+    close: () => setIsOpen(false),
+    toggle: () => setIsOpen((prev) => !prev),
+  }
+}

package/src/modules/showcase/index.ts

@@ -0,0 +1,12 @@
+// Main showcase layout component
+export { ShowcaseLayout } from './components/ShowcaseLayout'
+export type { ShowcaseLayoutProps, ShowcaseSection } from './components/ShowcaseLayout'
+
+// Additional components
+export { CodeBlock, InlineCode } from './components/CodeBlock'
+export { NavigationSidebar } from './components/NavigationSidebar'
+export { MobileMenu } from './components/MobileMenu'
+export { BackToTop } from './components/BackToTop'
+
+// Hooks
+export { useScrollSpy, useMobileMenu } from './hooks/useScrollSpy'