"use client";

import * as React from "react";

import { DetailsPageTemplatePreview } from "@/components/design-system/page-template-previews";
import type { ComponentDocSpec } from "@/lib/design-system/component-doc-types";

function ex(
  section: Omit<
    ComponentDocSpec["sections"][number],
    "children" | "description"
  >,
  children: React.ReactNode,
  description?: string,
) {
  return { ...section, children, description };
}

export const primaryPageTemplateComponentDoc: ComponentDocSpec = {
  slug: "primary-page-template",
  summary:
    "Canonical details-page shell with one breadcrumb carrier, one PageHeader, a constrained content column, and page-owned scrolling.",
  sections: [
    ex(
      { id: "details-page", title: "Details page template" },
      <DetailsPageTemplatePreview />,
      "Use for record details and standard product pages that need persistent shell chrome and one readable content column.",
    ),
  ],
  anatomy: [
    {
      part: "PrimaryPageTemplate",
      description:
        "Owns SidebarInset, the single main landmark, page scrolling, and content width.",
    },
    {
      part: "SiteHeader",
      description:
        "Carries the one breadcrumb trail. Do not add a second back control.",
    },
    {
      part: "PageHeader",
      description:
        "Carries the page title, factual metadata, and page actions.",
    },
    {
      part: "Content column",
      description: "Defaults to 1440px and may narrow for detail routes.",
    },
  ],
  api: [
    {
      prop: "siteHeader",
      type: "SiteHeaderProps",
      description: "Breadcrumb and route-level shell context.",
    },
    {
      prop: "maxWidthClassName",
      type: "string",
      defaultValue: "max-w-[1440px]",
      description: "Narrows details pages while preserving the shared shell.",
    },
    {
      prop: "contentClassName",
      type: "string",
      description: "Spacing and container classes for the content column.",
    },
    {
      prop: "containScroll",
      type: "boolean",
      defaultValue: "false",
      description: "Reserved for focused form and inspector layouts.",
    },
  ],
  ux: {
    job: "Read and act on one record without losing product, scope, or navigation context.",
    principles: ["P1", "P2", "P3", "P7", "P8", "P18"],
    modernReferences: [
      "Stripe record detail (M4, M7, M10)",
      "Linear issue detail (M1, M4, M7)",
    ],
    patternDoc: "apps/web/docs/record-detail-chrome-pattern.md",
    whenToUse: [
      "Record and entity detail routes",
      "Standard product pages that need a constrained content column",
    ],
    whenNotToUse: [
      "List hubs. Use ListPageTemplate",
      "Exam or compose workflows that remove shell chrome. Use a focus template",
    ],
  },
  guidelines: {
    do: [
      "Use SiteHeader for the one breadcrumb trail",
      "Use PageHeader for the one page title",
      "Narrow maxWidthClassName when detail content benefits from a shorter reading line",
    ],
    dont: [
      "Do not render a second main landmark inside the template",
      "Do not combine a breadcrumb with a separate Back button",
      "Do not give the body its own competing page title",
    ],
  },
  accessibility: [
    "PrimaryPageTemplate owns the single main landmark.",
    "Product routes keep PageHeader at heading level h1.",
    "The breadcrumb and page title remain keyboard and screen-reader discoverable.",
  ],
  relatedSlugs: [
    "page-header",
    "app-shell",
    "list-page-template",
    "utility-bar",
  ],
  extraImports: [
    {
      label: "PrimaryPageTemplate",
      path: "@/components/templates/primary-page-template",
    },
  ],
};