"use client";

import type { ComponentDocSpec } from "@/lib/design-system/component-doc-types";
import {
  WhatsNewSheetOpenPreview,
  WhatsNewSheetTriggerPreview,
} from "@/components/design-system/whats-new-sheet-previews";

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

export const whatsNewSheetComponentDoc: ComponentDocSpec = {
  slug: "whats-new-sheet",
  summary:
    "Compact left rail for one featured release note. Leo hero, highlight rows, pinned primary CTA, and a shared seen list with the utility bar megaphone.",
  sections: [
    ex(
      { id: "open", title: "Featured update" },
      <WhatsNewSheetOpenPreview />,
      "One update per open. Media uses WhatsNewLeoHero, not a screenshot. Primary action and Release history sit in the pinned footer.",
    ),
    ex(
      { id: "trigger", title: "Megaphone trigger" },
      <WhatsNewSheetTriggerPreview />,
      "Utility bar and profile menu share WhatsNewSheetTrigger and one provider-mounted sheet instance.",
    ),
  ],
  anatomy: [
    {
      part: "WhatsNewSheet",
      description:
        "Controlled sheet. Pass featured update, onPrimaryAction, and footerSecondary.",
    },
    {
      part: "WhatsNewAnnouncementCard",
      slug: "whats-new-announcement-card",
      description: "Scroll body: media, title, highlights, header dismiss.",
    },
    {
      part: "WhatsNewLeoHero",
      description:
        "Leo invited one-shot + DotPattern burst. Remount via playKey on each open.",
    },
    {
      part: "WhatsNewSheetTrigger",
      description:
        "Megaphone with unread count badge. aria-haspopup dialog.",
    },
    {
      part: "WhatsNewSheetProvider",
      description:
        "App wiring only. Catalog scope, routes, and seen list.",
    },
    {
      part: "FloatingSheetPanel",
      slug: "floating-sheet-panel",
      description: "Left rail shell. WHATS_NEW_SHEET_PANEL_PROPS preset.",
    },
  ],
  api: [
    {
      prop: "featured",
      type: "WhatsNewSheetFeaturedUpdate",
      description: "id, brandColor, and WhatsNewReleaseItem fields.",
    },
    {
      prop: "onPrimaryAction",
      type: "() => void",
      description: "Footer CTA. App opens product route or card href.",
    },
    {
      prop: "footerSecondary",
      type: "ReactNode",
      description: "Typically Release history link to /whats-new.",
    },
    {
      prop: "onDismiss",
      type: "(id: string) => void",
      description: "Card dismiss. Must write to the shared seen list in app wiring.",
    },
  ],
  ux: {
    job: "Understand one release in under ten seconds and try it or dismiss without losing hub context.",
    principles: ["P1", "P2", "P5", "P6", "P8"],
    modernReferences: ["Linear changelog drawer (M4, M7)", "Notion update modal (M1, M4)"],
    patternDoc: "apps/web/docs/whats-new-sheet-pattern.md",
    rulePath: ".cursor/rules/exxat-whats-new-sheet.mdc",
    whenToUse: [
      "Utility bar megaphone or profile What's new for one featured release",
      "Compact update UX where the hub must stay visible",
    ],
    whenNotToUse: [
      "Full release timeline (use /whats-new route)",
      "Blocking confirmation (use Dialog)",
    ],
  },
  extraImports: [
    { label: "App provider", path: "@/components/whats-new-sheet-context" },
    { label: "Handoff", path: "docs/exxat-ds/handoff/whats-new-sheet-small.md" },
  ],
  relatedSlugs: [
    "floating-sheet-panel",
    "utility-bar",
    "leo-icon",
    "products-home",
  ],
};