"use client"

import * as React from "react"

import type { ComponentDocSpec } from "@/lib/design-system/component-doc-types"
import {
  AppShellPreview,
  SidebarCollapsedPreview,
  SidebarDrillInPreview,
  SidebarExpandedPreview,
  SidebarMobilePreview,
  SidebarSecondaryPanelPreview,
} from "@/components/design-system/shell-previews"

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

export const sidebarComponentDoc: ComponentDocSpec = {
  slug: "sidebar",
  summary:
    "Application navigation across expanded, collapsed, mobile, drill-in, and secondary-panel compositions.",
  sections: [
    ex(
      { id: "expanded", title: "Expanded primary sidebar" },
      <SidebarExpandedPreview />,
      "Full labels wrap, one route is active, and section labels use sidebar tokens.",
    ),
    ex(
      { id: "collapsed", title: "Collapsed icon rail" },
      <SidebarCollapsedPreview />,
      "Every icon-only route keeps an aria-label and Tip.",
    ),
    ex(
      { id: "drill-in", title: "Drill-in navigation" },
      <SidebarDrillInPreview />,
      "Flat route families such as Settings replace the primary list and provide one way back.",
    ),
    ex(
      { id: "secondary-panel", title: "Secondary scope panel" },
      <SidebarSecondaryPanelPreview />,
      "Persistent hierarchy scopes the current hub while the primary product navigation stays visible.",
    ),
    ex(
      { id: "mobile", title: "Mobile and reflow flyout" },
      <SidebarMobilePreview />,
      "The same navigation becomes a dismissible overlay at narrow width and 200 percent zoom.",
    ),
  ],
  anatomy: [
    { part: "AppSidebar", description: "Product-aware primary navigation shell." },
    { part: "SidebarMenuButton", description: "One active row with Font Awesome idle and active glyphs." },
    { part: "SidebarNavLabel", description: "Wraps expanded labels without truncation." },
    { part: "SidebarDrillInItems", description: "Flat nested route family with Back and Escape handling." },
    { part: "NestedSecondaryPanelShell", description: "Resizable persistent scope hierarchy beside a hub." },
    { part: "Nav flyout", description: "Overlay mode for mobile and WCAG reflow." },
  ],
  guidelines: {
    do: [
      "Register product navigation in NAV_BY_PRODUCT and use shared nav-active helpers.",
      "Use SidebarDrillIn for flat route families and SecondaryPanel for persistent hierarchy.",
      "Dismiss the nav flyout after a leaf route navigation.",
      "Keep one active row and let expanded labels wrap.",
    ],
    dont: [
      "Do not wire drill-in and secondaryPanel on the same nav item.",
      "Do not duplicate route matching with startsWith logic.",
      "Do not truncate navigation labels or use custom active pills.",
      "Do not copy sidebar chrome from a legacy screenshot.",
    ],
  },
  accessibility: [
    "Collapsed links expose an aria-label and visible Tip.",
    "Icon buttons meet the 24 pixel target floor.",
    "Escape closes drill-in and mobile flyout navigation.",
    "Resize handles use verticalResizeSeparatorAria with current, minimum, and maximum width.",
  ],
  relatedSlugs: ["app-shell", "utility-bar", "page-header", "breadcrumb"],
  extraImports: [
    { label: "Sidebar primitives", path: "@exxatdesignux/ui/components/ui/sidebar" },
    { label: "Navigation active helpers", path: "@exxatdesignux/ui/lib/nav-active" },
  ],
}

export const appShellComponentDoc: ComponentDocSpec = {
  slug: "app-shell",
  summary:
    "Canonical signed-in shell composition: UtilityBarSlot, product navigation, optional scope panel, SiteHeader bridge, and one page content column.",
  sections: [
    ex(
      { id: "canonical", title: "Canonical app shell" },
      <AppShellPreview />,
      "Global utilities and navigation stay outside the page content column.",
    ),
  ],
  anatomy: [
    { part: "UtilityBarSlot", description: "Global product context, breadcrumb, utilities, and identity." },
    { part: "AppSidebar", description: "Primary product navigation." },
    { part: "Secondary panel", description: "Optional persistent scope hierarchy for the active hub." },
    { part: "SiteHeader bridge", description: "Publishes breadcrumb or Back mode into the utility bar." },
    { part: "PageHeader", description: "Route identity and page-scoped actions." },
    { part: "Main content", description: "One scroll owner for page content." },
  ],
  guidelines: {
    do: [
      "Keep utility and navigation chrome stable while product routes change.",
      "Use product URL roots and product-namespaced persisted state.",
      "Allow the sidebar to become an overlay flyout during reflow.",
      "Mount SystemBannerSlot inside the app shell main region.",
    ],
    dont: [
      "Do not build a second product shell for one route.",
      "Do not place product-owned routes at the workspace root.",
      "Do not keep dual sidebars pinned at 320 pixels or 200 percent zoom.",
      "Do not add nested page scroll containers.",
    ],
  },
  accessibility: [
    "The shell exposes one main landmark and the route exposes one h1.",
    "Global utilities and each navigation landmark have distinct accessible names.",
    "Keyboard users can open, close, and traverse flyout and drill-in navigation.",
    "Page content reflows without document-level horizontal scrolling.",
  ],
  relatedSlugs: ["utility-bar", "sidebar", "page-header", "banner"],
}