"use client";

import * as React from "react";

import type { ComponentDocSpec } from "@/lib/design-system/component-doc-types";
import {
  PageHeaderCollaborationPreview,
  PageHeaderCustomActionsPreview,
  PageHeaderDefaultPreview,
  PageHeaderResponsiveActionsPreview,
} from "@/components/design-system/page-header-previews";

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

export const pageHeaderComponentDoc: ComponentDocSpec = {
  slug: "page-header",
  summary:
    "Page identity row with one title, factual metadata, responsive labelled actions, overflow, and optional collaboration access.",
  sections: [
    ex(
      { id: "default", title: "Title and metadata" },
      <PageHeaderDefaultPreview />,
      "Use subtitle only for factual metadata such as count, ID, or freshness.",
    ),
    ex(
      { id: "responsive-actions", title: "Responsive action items" },
      <PageHeaderResponsiveActionsPreview />,
      "Switch the preview width to inspect the same header at each container tier. Labels compact to icons and long-tail actions move under More.",
    ),
    ex(
      { id: "collaboration", title: "Collaboration" },
      <PageHeaderCollaborationPreview />,
      "Access context and collaborator faces remain part of the page identity row.",
    ),
    ex(
      { id: "custom-actions", title: "Custom action composition" },
      <PageHeaderCustomActionsPreview />,
      "Use the actions slot only when a labelled scope control cannot be represented by actionItems.",
    ),
  ],
  anatomy: [
    {
      part: "Title",
      description: "The route h1. Catalog previews use headingLevel h2.",
    },
    {
      part: "Subtitle",
      description:
        "One line of factual metadata. Decorative descriptions are omitted.",
    },
    {
      part: "actionItems",
      description:
        "ResponsiveActionRow commands with icons, placement, and shortcuts.",
    },
    {
      part: "More",
      description: "Automatic overflow for tertiary and narrow-width actions.",
    },
    {
      part: "Collaboration access",
      description:
        "Access context, collaborator faces, and invite entry point.",
    },
  ],
  api: [
    {
      prop: "title",
      type: "ReactNode",
      description: "Page identity. String values render as the heading.",
    },
    {
      prop: "subtitle",
      type: "ReactNode",
      description: "Optional factual metadata.",
    },
    {
      prop: "actionItems",
      type: "PageHeaderActionItem[]",
      description: "Preferred labelled command model.",
    },
    {
      prop: "actions",
      type: "ReactNode",
      description: "Custom composite slot for scope controls and actions.",
    },
    {
      prop: "variant",
      type: "default | collaboration",
      defaultValue: "default",
      description: "Adds access and collaborator context.",
    },
    {
      prop: "headingLevel",
      type: "h1 | h2",
      defaultValue: "h1",
      description: "Use h2 only for embedded documentation previews.",
    },
  ],
  guidelines: {
    do: [
      "Prefer actionItems so actions inherit responsive labels, overflow, Tips, and shortcuts.",
      "Keep one filled primary action and at most three visible row actions.",
      "Keep Export, settings, and other long-tail commands under More.",
      "Use small action buttons. PageHeader owns the compact header rhythm.",
    ],
    dont: [
      "Do not add decorative copy under the title.",
      "Do not place a second primary action in the table toolbar.",
      "Do not hand-build a responsive action row beside PageHeader.",
    ],
  },
  accessibility: [
    "Routes keep headingLevel h1 so the page has one primary heading.",
    "Filled primary actions include a visible Kbd and a bound shortcut.",
    "Collapsed icon actions retain aria-label and Tip text.",
    "Collaborator controls expose the roster and each person name.",
  ],
  relatedSlugs: [
    "responsive-action-row",
    "button",
    "avatar",
    "utility-bar",
    "app-shell",
  ],
  extraImports: [
    {
      label: "PageHeader",
      path: "@exxatdesignux/ui/components/ui/page-header",
    },
    {
      label: "ResponsiveActionRow",
      path: "@exxatdesignux/ui/components/ui/responsive-action-row",
    },
  ],
};