'use client';

/**
 * Documentation Page Layout Component
 *
 * Provides consistent structure for all documentation pages:
 * - Breadcrumb navigation at top
 * - Article content area (passed as children)
 * - Next Steps section at bottom
 * - Table of Contents sidebar on the right
 *
 * Uses ThreeColumnLayout for consistent column structure:
 * - Center: Article content (max-w-3xl)
 * - Right: Table of Contents (w-56, hidden xl:block)
 *
 * This component extracts common layout patterns from all doc pages,
 * reducing duplication and ensuring consistency.
 *
 * Usage:
 * ```tsx
 * <DocPage
 *   breadcrumbItems={[...]}
 *   tocItems={[...]}
 *   nextSteps={{ description: "...", links: [...] }}
 * >
 *   <Hero ... />
 *   <section>...</section>
 * </DocPage>
 * ```
 */

import { Breadcrumb } from '@/components/docs/shared/Breadcrumb';
import { DocsTOC } from '@/components/docs/layout/DocsTOC';
import { SectionHeader, LinkCard, LinkCardGrid } from '@/components/docs/blocks';
import { ThreeColumnLayout } from '@/components/layout/ThreeColumnLayout';

/**
 * Next step link card configuration
 */
export interface NextStepLink {
  href: string;
  title: string;
  description: string;
  accent: 'primary' | 'secondary' | 'success' | 'warning';
}

/**
 * Table of Contents item
 */
export interface TocItem {
  id: string;
  text: string;
  level: number;
}

/**
 * Breadcrumb navigation item
 */
export interface BreadcrumbItem {
  label: string;
  href?: string;
}

/**
 * DocPage component props
 */
export interface DocPageProps {
  /** Breadcrumb navigation items (top of page) */
  breadcrumbItems: BreadcrumbItem[];

  /** Table of contents items (right sidebar) */
  tocItems: TocItem[];

  /** Next steps section configuration */
  nextSteps: {
    /** Optional description text before link cards */
    description?: string;
    /** Link cards to display (typically 2) */
    links: NextStepLink[];
  };

  /** Page content (Hero, sections, etc.) */
  children: React.ReactNode;
}

/**
 * Documentation Page Layout Component
 *
 * Wraps documentation content with consistent structure including
 * breadcrumbs, TOC sidebar, and next steps section.
 */
export const DocPage = ({
  breadcrumbItems,
  tocItems,
  nextSteps,
  children,
}: DocPageProps) => {
  return (
    <ThreeColumnLayout
      center={
        <article className="max-w-3xl mx-auto px-6 lg:px-12 py-12">
          {/* Breadcrumb Navigation */}
          <Breadcrumb items={breadcrumbItems} />

          {/* Page Content (Hero + Sections) */}
          {children}

          {/* Next Steps Section */}
          <section id="next-steps" className="mb-12">
            <SectionHeader level={2} id="next-steps" className="mb-6">
              Next Steps
            </SectionHeader>

            {nextSteps.description && (
              <p className="text-gray-300 leading-relaxed mb-6">
                {nextSteps.description}
              </p>
            )}

            <LinkCardGrid columns={2}>
              {nextSteps.links.map((link, index) => (
                <LinkCard
                  key={index}
                  href={link.href}
                  title={link.title}
                  description={link.description}
                  accent={link.accent}
                />
              ))}
            </LinkCardGrid>
          </section>
        </article>
      }
      right={
        <div className="border-l border-white/10 bg-slate-950/30 backdrop-blur-sm sticky top-12 h-[calc(100vh-3rem)] overflow-y-auto">
          <DocsTOC items={tocItems} />
        </div>
      }
    />
  );
};
