@hypoth-ui/docs-renderer-next 0.1.0

package/app/components/[id]/page.tsx

@@ -0,0 +1,316 @@
+import { readFile } from "node:fs/promises";
+import {
+  type ComponentAccessibility,
+  type ComponentStatus,
+  type ContractManifest,
+  type Edition,
+  getMinimumEdition,
+  isComponentAvailable,
+} from "@hypoth-ui/docs-core";
+import {
+  getEditionConfig,
+  loadManifestByIdFromPacks,
+  loadManifestsFromPacks,
+  resolveContentFile,
+} from "../../../lib/content-resolver";
+
+/**
+ * Display manifest shape used for rendering component pages
+ * Normalizes both ContractManifest and legacy ComponentManifest formats
+ */
+interface DisplayManifest {
+  name: string;
+  description: string;
+  status: ComponentStatus;
+  props: Array<{ name: string; type: string; default?: string; description: string }>;
+  events: Array<{ name: string; description: string }>;
+  examples: Array<{ title: string; code: string }>;
+  tokensUsed: string[];
+  accessibility?: ComponentAccessibility;
+}
+import { notFound, redirect } from "next/navigation";
+import { MdxRenderer } from "../../../components/mdx-renderer";
+import { EditionProvider } from "../../../components/mdx/edition";
+import { TokensUsed } from "../../../components/tokens-used";
+
+interface ComponentPageProps {
+  params: Promise<{
+    id: string;
+  }>;
+}
+
+/**
+ * Get the current edition from environment or config
+ */
+async function getCurrentEdition(): Promise<Edition> {
+  // Check environment variable first
+  const envEdition = process.env.DS_EDITION;
+  if (envEdition && ["core", "pro", "enterprise"].includes(envEdition)) {
+    return envEdition as Edition;
+  }
+
+  // Fall back to edition config from content resolver
+  try {
+    const config = await getEditionConfig();
+    return config.edition;
+  } catch {
+    return "enterprise"; // Default to enterprise (shows all)
+  }
+}
+
+/**
+ * Load contract manifests from content packs with overlay resolution
+ */
+async function loadContractManifests(): Promise<ContractManifest[]> {
+  return loadManifestsFromPacks();
+}
+
+/**
+ * Generate static params for all components available in the current edition
+ */
+export async function generateStaticParams() {
+  const edition = await getCurrentEdition();
+  const manifests = await loadContractManifests();
+
+  // Filter by edition
+  const availableComponents = manifests.filter((manifest) =>
+    isComponentAvailable(manifest.editions, edition)
+  );
+
+  return availableComponents.map((manifest) => ({
+    id: manifest.id,
+  }));
+}
+
+export async function generateMetadata({ params }: ComponentPageProps) {
+  const { id } = await params;
+
+  // Load manifest with overlay resolution
+  const manifest = await loadManifestByIdFromPacks(id);
+
+  if (!manifest) {
+    return { title: "Component Not Found" };
+  }
+
+  return {
+    title: manifest.name,
+    description: manifest.description,
+  };
+}
+
+export default async function ComponentPage({ params }: ComponentPageProps) {
+  const { id } = await params;
+  const edition = await getCurrentEdition();
+
+  // Try to load from contract manifests
+  const manifests = await loadContractManifests();
+  const contractManifest = manifests.find((m) => m.id === id);
+
+  // Check edition access
+  if (contractManifest) {
+    const isAvailable = isComponentAvailable(contractManifest.editions, edition);
+
+    if (!isAvailable) {
+      // Redirect to upgrade page
+      const requiredEdition = getMinimumEdition(contractManifest.editions);
+      redirect(`/edition-upgrade?component=${id}&from=${edition}&to=${requiredEdition}`);
+    }
+  }
+
+  // Use overlay-resolved manifest or fall back to direct lookup
+  const manifest = contractManifest ?? (await loadManifestByIdFromPacks(id));
+
+  if (!manifest) {
+    notFound();
+  }
+
+  // Load MDX content with overlay resolution
+  let mdxContent: string | null = null;
+  try {
+    const resolved = await resolveContentFile(`components/${id}.mdx`);
+    if (resolved) {
+      mdxContent = await readFile(resolved.resolvedPath, "utf-8");
+    }
+  } catch {
+    // No MDX file, use auto-generated content from manifest
+  }
+
+  // Normalize to DisplayManifest format for rendering
+  // Contract manifests don't have props/events/examples (those come from MDX)
+  const displayManifest: DisplayManifest = {
+    name: manifest.name,
+    description: manifest.description,
+    status: manifest.status,
+    props: [],
+    events: [],
+    examples: [],
+    tokensUsed: manifest.tokensUsed ?? [],
+    accessibility: manifest.accessibility,
+  };
+
+  return (
+    <EditionProvider edition={edition}>
+      <article className="component-page">
+        <header className="component-header">
+          <div className="component-status" data-status={displayManifest.status}>
+            {displayManifest.status}
+          </div>
+          <h1>{displayManifest.name}</h1>
+          {displayManifest.description && (
+            <p className="component-description">{displayManifest.description}</p>
+          )}
+        </header>
+
+        {displayManifest.tokensUsed.length > 0 && (
+          <TokensUsed tokens={displayManifest.tokensUsed} />
+        )}
+
+        {displayManifest.accessibility && (
+          <section className="component-accessibility">
+            <h2>Accessibility</h2>
+            <dl className="accessibility-details">
+              <div className="accessibility-item">
+                <dt>APG Pattern</dt>
+                <dd>
+                  <a
+                    href={`https://www.w3.org/WAI/ARIA/apg/patterns/${displayManifest.accessibility.apgPattern.toLowerCase().replace(/\s+/g, "-")}/`}
+                    target="_blank"
+                    rel="noopener noreferrer"
+                  >
+                    {displayManifest.accessibility.apgPattern}
+                  </a>
+                </dd>
+              </div>
+              {displayManifest.accessibility.keyboard.length > 0 && (
+                <div className="accessibility-item">
+                  <dt>Keyboard Interactions</dt>
+                  <dd>
+                    <ul className="keyboard-list">
+                      {displayManifest.accessibility.keyboard.map((interaction) => (
+                        <li key={interaction}>{interaction}</li>
+                      ))}
+                    </ul>
+                  </dd>
+                </div>
+              )}
+              <div className="accessibility-item">
+                <dt>Screen Reader</dt>
+                <dd>{displayManifest.accessibility.screenReader}</dd>
+              </div>
+              {displayManifest.accessibility.ariaPatterns &&
+                displayManifest.accessibility.ariaPatterns.length > 0 && (
+                  <div className="accessibility-item">
+                    <dt>ARIA Patterns</dt>
+                    <dd>
+                      <ul className="aria-list">
+                        {displayManifest.accessibility.ariaPatterns.map((pattern) => (
+                          <li key={pattern}>
+                            <code>{pattern}</code>
+                          </li>
+                        ))}
+                      </ul>
+                    </dd>
+                  </div>
+                )}
+              {displayManifest.accessibility.knownLimitations &&
+                displayManifest.accessibility.knownLimitations.length > 0 && (
+                  <div className="accessibility-item accessibility-item--warning">
+                    <dt>Known Limitations</dt>
+                    <dd>
+                      <ul className="limitations-list">
+                        {displayManifest.accessibility.knownLimitations.map((limitation) => (
+                          <li key={limitation}>{limitation}</li>
+                        ))}
+                      </ul>
+                    </dd>
+                  </div>
+                )}
+            </dl>
+          </section>
+        )}
+
+        {mdxContent ? (
+          <MdxRenderer source={mdxContent} />
+        ) : (
+          <div className="component-auto-docs">
+            {/* Auto-generated documentation from manifest */}
+            <section>
+              <h2>Usage</h2>
+              <pre>
+                <code>{`<ds-${id}></ds-${id}>`}</code>
+              </pre>
+            </section>
+
+            {displayManifest.props && displayManifest.props.length > 0 && (
+              <section>
+                <h2>Properties</h2>
+                <table className="props-table">
+                  <thead>
+                    <tr>
+                      <th>Name</th>
+                      <th>Type</th>
+                      <th>Default</th>
+                      <th>Description</th>
+                    </tr>
+                  </thead>
+                  <tbody>
+                    {displayManifest.props.map((prop) => (
+                      <tr key={prop.name}>
+                        <td>
+                          <code>{prop.name}</code>
+                        </td>
+                        <td>
+                          <code>{prop.type}</code>
+                        </td>
+                        <td>{prop.default ? <code>{prop.default}</code> : "—"}</td>
+                        <td>{prop.description}</td>
+                      </tr>
+                    ))}
+                  </tbody>
+                </table>
+              </section>
+            )}
+
+            {displayManifest.events && displayManifest.events.length > 0 && (
+              <section>
+                <h2>Events</h2>
+                <table className="events-table">
+                  <thead>
+                    <tr>
+                      <th>Name</th>
+                      <th>Description</th>
+                    </tr>
+                  </thead>
+                  <tbody>
+                    {displayManifest.events.map((event) => (
+                      <tr key={event.name}>
+                        <td>
+                          <code>{event.name}</code>
+                        </td>
+                        <td>{event.description}</td>
+                      </tr>
+                    ))}
+                  </tbody>
+                </table>
+              </section>
+            )}
+
+            {displayManifest.examples && displayManifest.examples.length > 0 && (
+              <section>
+                <h2>Examples</h2>
+                {displayManifest.examples.map((example) => (
+                  <div key={example.title} className="example">
+                    <h3>{example.title}</h3>
+                    <pre>
+                      <code>{example.code}</code>
+                    </pre>
+                  </div>
+                ))}
+              </section>
+            )}
+          </div>
+        )}
+      </article>
+    </EditionProvider>
+  );
+}

package/app/edition-upgrade/page.tsx

@@ -0,0 +1,76 @@
+import type { Edition } from "@hypoth-ui/docs-core";
+import Link from "next/link";
+import { UpgradePrompt } from "../../components/upgrade/upgrade-prompt";
+import { getEditionConfig } from "../../lib/content-resolver";
+
+interface UpgradePageProps {
+  searchParams: Promise<{
+    component?: string;
+    from?: string;
+    to?: string;
+  }>;
+}
+
+export default async function EditionUpgradePage({ searchParams }: UpgradePageProps) {
+  const params = await searchParams;
+  const componentId = params.component;
+  const fromEdition = (params.from ?? "core") as Edition;
+  const toEdition = (params.to ?? "enterprise") as Edition;
+
+  // Load upgrade config from edition config
+  const config = await getEditionConfig();
+
+  return (
+    <div className="upgrade-page">
+      <UpgradePrompt
+        currentEdition={fromEdition}
+        requiredEdition={toEdition}
+        upgradeConfig={config.upgrade}
+        itemName={componentId}
+        componentId={componentId}
+        variant="full-page"
+      />
+
+      <div className="upgrade-actions">
+        <Link href="/" className="btn btn-secondary">
+          Back to Documentation
+        </Link>
+      </div>
+
+      <style jsx>{`
+        .upgrade-page {
+          display: flex;
+          flex-direction: column;
+          justify-content: center;
+          align-items: center;
+          min-height: 80vh;
+          padding: 2rem;
+          gap: 2rem;
+        }
+
+        .upgrade-actions {
+          display: flex;
+          gap: 1rem;
+          justify-content: center;
+        }
+
+        .btn {
+          padding: 0.75rem 1.5rem;
+          border-radius: 8px;
+          font-weight: 600;
+          text-decoration: none;
+          transition: all 0.2s;
+        }
+
+        .btn-secondary {
+          background: var(--ds-surface-tertiary, #e9ecef);
+          color: var(--ds-text-primary, #333);
+        }
+
+        .btn-secondary:hover {
+          background: var(--ds-surface-hover, #dee2e6);
+        }
+      `}</style>
+    </div>
+  );
+}

package/app/guides/[id]/page.tsx

@@ -0,0 +1,67 @@
+import { readFile } from "node:fs/promises";
+import { parseFrontmatter } from "@hypoth-ui/docs-core";
+import { notFound } from "next/navigation";
+import { MdxRenderer } from "../../../components/mdx-renderer";
+import { discoverGuides, resolveContentFile } from "../../../lib/content-resolver";
+
+interface GuidePageProps {
+  params: Promise<{
+    id: string;
+  }>;
+}
+
+// Generate static params for all guides from content packs
+export async function generateStaticParams() {
+  try {
+    const guides = await discoverGuides();
+    return guides.map(({ id }) => ({ id }));
+  } catch {
+    return [{ id: "getting-started" }, { id: "theming" }];
+  }
+}
+
+export async function generateMetadata({ params }: GuidePageProps) {
+  const { id } = await params;
+
+  try {
+    const resolved = await resolveContentFile(`guides/${id}.mdx`);
+    if (!resolved) {
+      return { title: "Guide Not Found" };
+    }
+
+    const content = await readFile(resolved.resolvedPath, "utf-8");
+    const { frontmatter } = parseFrontmatter(content);
+
+    return {
+      title: frontmatter.title,
+      description: frontmatter.description,
+    };
+  } catch {
+    return { title: "Guide Not Found" };
+  }
+}
+
+export default async function GuidePage({ params }: GuidePageProps) {
+  const { id } = await params;
+
+  // Resolve guide content through overlay chain
+  const resolved = await resolveContentFile(`guides/${id}.mdx`);
+
+  if (!resolved) {
+    notFound();
+  }
+
+  let mdxContent: string;
+
+  try {
+    mdxContent = await readFile(resolved.resolvedPath, "utf-8");
+  } catch {
+    notFound();
+  }
+
+  return (
+    <article className="guide-page">
+      <MdxRenderer source={mdxContent} />
+    </article>
+  );
+}

package/app/layout.tsx

@@ -0,0 +1,93 @@
+import { applyDefaultFeatures } from "@hypoth-ui/docs-core";
+import type { Metadata } from "next";
+import type { ReactNode } from "react";
+import { BrandedHeader } from "../components/branding/header";
+import { FeedbackWidget } from "../components/feedback/feedback-widget";
+import { NavSidebar } from "../components/nav-sidebar";
+import { SearchInput } from "../components/search/search-input";
+import { ThemeInitScript } from "../components/theme-init-script";
+import { ThemeSwitcher } from "../components/theme-switcher";
+import { BrandingProvider } from "../lib/branding-context";
+import { getEditionConfig } from "../lib/content-resolver";
+import "../styles/globals.css";
+
+/**
+ * Generate metadata dynamically based on branding config
+ */
+export async function generateMetadata(): Promise<Metadata> {
+  const config = await getEditionConfig();
+  const siteName = config.branding?.name ?? "Design System";
+
+  return {
+    title: {
+      template: `%s | ${siteName}`,
+      default: siteName,
+    },
+    description: `Documentation for ${siteName}`,
+  };
+}
+
+interface RootLayoutProps {
+  children: ReactNode;
+}
+
+export default async function RootLayout({ children }: RootLayoutProps) {
+  // Load edition config for branding
+  const config = await getEditionConfig();
+
+  // Apply default features to ensure all flags are present
+  const features = applyDefaultFeatures(config.features);
+
+  // Generate CSS custom properties for branding
+  const brandingStyles = `
+    :root {
+      --ds-brand-primary: ${config.branding?.primaryColor ?? "#0066cc"};
+    }
+  `;
+
+  return (
+    <html lang="en" data-mode="light">
+      <head>
+        <ThemeInitScript />
+        {/* Inject branding CSS custom properties - safe as brandingStyles is server-generated */}
+        {/* biome-ignore lint/security/noDangerouslySetInnerHtml: CSS is server-generated from config */}
+        <style dangerouslySetInnerHTML={{ __html: brandingStyles }} />
+        {config.branding?.favicon && <link rel="icon" href={config.branding.favicon} />}
+      </head>
+      <body>
+        {/* T064: Skip link for keyboard accessibility */}
+        <a href="#main-content" className="skip-link">
+          Skip to main content
+        </a>
+        <BrandingProvider
+          branding={config.branding}
+          features={config.features}
+          upgrade={config.upgrade}
+          edition={config.edition}
+          editionId={config.id}
+          editionName={config.name}
+        >
+          <div className="docs-layout">
+            {/* T065: Proper landmark roles - header contains navigation */}
+            <BrandedHeader editionName={config.name}>
+              {/* T056: Conditionally render SearchInput based on features.search */}
+              {features.search && <SearchInput />}
+              {/* T055: Conditionally render ThemeSwitcher based on features.darkMode */}
+              {features.darkMode && <ThemeSwitcher />}
+            </BrandedHeader>
+            {/* T065: Proper landmark roles - nav element for navigation */}
+            <nav className="docs-sidebar" aria-label="Documentation navigation">
+              <NavSidebar edition={config.edition} />
+            </nav>
+            {/* T065: Proper landmark roles - main content area */}
+            <main id="main-content" className="docs-main">
+              <div className="docs-content">{children}</div>
+            </main>
+            {/* T057: Conditionally render FeedbackWidget based on features.feedback */}
+            {features.feedback && <FeedbackWidget />}
+          </div>
+        </BrandingProvider>
+      </body>
+    </html>
+  );
+}

package/app/page.tsx

@@ -0,0 +1,29 @@
+import Link from "next/link";
+
+export default function HomePage() {
+  return (
+    <div className="docs-home">
+      <h1>Design System Documentation</h1>
+      <p>Welcome to the design system documentation.</p>
+
+      <nav className="docs-home-nav">
+        <h2>Get Started</h2>
+        <ul>
+          <li>
+            <Link href="/guides/getting-started">Getting Started</Link>
+          </li>
+          <li>
+            <Link href="/guides/theming">Theming</Link>
+          </li>
+        </ul>
+
+        <h2>Components</h2>
+        <ul>
+          <li>
+            <Link href="/components/button">Button</Link>
+          </li>
+        </ul>
+      </nav>
+    </div>
+  );
+}

package/components/branding/header.tsx

@@ -0,0 +1,82 @@
+"use client";
+
+/**
+ * Branded Header Component
+ *
+ * Site header with branding, navigation, and optional features.
+ */
+
+import Link from "next/link";
+import type { ReactNode } from "react";
+import { useBranding } from "../../lib/branding-context";
+import { Logo } from "./logo";
+
+export interface BrandedHeaderProps {
+  /** Additional content in the header (e.g., search, theme toggle) */
+  children?: ReactNode;
+  /** Custom class name */
+  className?: string;
+  /** Edition name to display (passed from server) */
+  editionName?: string;
+}
+
+export function BrandedHeader({ children, className = "", editionName }: BrandedHeaderProps) {
+  const { primaryColor } = useBranding();
+
+  return (
+    <header className={`branded-header ${className}`}>
+      <div className="branded-header__left">
+        <Link href="/" className="branded-header__logo-link">
+          <Logo size="medium" />
+        </Link>
+        {editionName && editionName !== "Default" && (
+          <span className="branded-header__edition">{editionName}</span>
+        )}
+      </div>
+
+      <div className="branded-header__right">{children}</div>
+
+      <style jsx>{`
+        .branded-header {
+          display: flex;
+          align-items: center;
+          justify-content: space-between;
+          padding: 0.75rem 1.5rem;
+          background: var(--ds-surface-primary, #fff);
+          border-bottom: 1px solid var(--ds-border, #e5e7eb);
+          position: sticky;
+          top: 0;
+          z-index: 100;
+        }
+
+        .branded-header__left {
+          display: flex;
+          align-items: center;
+          gap: 0.75rem;
+        }
+
+        .branded-header__logo-link {
+          display: flex;
+          align-items: center;
+          text-decoration: none;
+          color: inherit;
+        }
+
+        .branded-header__edition {
+          font-size: 0.75rem;
+          padding: 0.125rem 0.5rem;
+          border-radius: 9999px;
+          font-weight: 600;
+          background-color: var(--ds-brand-primary, ${primaryColor});
+          color: white;
+        }
+
+        .branded-header__right {
+          display: flex;
+          align-items: center;
+          gap: 1rem;
+        }
+      `}</style>
+    </header>
+  );
+}