// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

/**
 * @file TopNavMegaMenuFeaturedCard.tsx
 * @input Uses React, StyleX, theme tokens
 * @output Exports TopNavMegaMenuFeaturedCard component
 * @position Standard featured card for the TopNavMegaMenu featured slot.
 *
 * Provides a consistent appearance for promotional/featured content in mega menus.
 * The `featured` slot on TopNavMegaMenu is still open ReactNode — this component
 * is the standard card, but consumers can pass anything.
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/core/src/TopNav/TopNav.doc.mjs
 * - /packages/core/src/TopNav/index.ts
 * - /packages/cli/assets/templates/blocks/components/TopNav/ (showcase blocks)
 */
import React, { type ReactNode } from 'react';
import * as stylex from "../style-runtime.js";
import "../theme/tokens.stylex.js";
import { colorVars, spacingVars, typeScaleVars, fontWeightVars } from "../theme/tokens.stylex.js";
import { mergeProps } from "../utils/index.js";
import type { BaseProps } from "../BaseProps.js";
import { useLinkComponent } from "../Link/useLinkComponent.js";
import { themeProps } from "../utils/themeProps.js";

// =============================================================================
// Styles
// =============================================================================

const styles = {
  root: {
    k1xSpc: "x78zum5",
    kXwgrk: "xdt5ytf",
    $$css: true as const
  }
};

// =============================================================================
// Types
// =============================================================================

export interface TopNavMegaMenuFeaturedCardProps extends BaseProps<HTMLDivElement> {
  ref?: React.Ref<HTMLDivElement>;
  /** Card title. */
  title: string;
  /** Description text below the title. */
  description?: string;
  /** Optional image URL displayed above the body. */
  image?: string;
  /**
   * Alt text for the image.
   *
   * When omitted, the image is explicitly decorative (`alt=""` +
   * `role="presentation"` + `aria-hidden`, matching Avatar) and hidden from
   * assistive technology. Since the card already has a visible `title`, a
   * decorative image is usually correct; pass `imageAlt` only when the image
   * conveys information beyond the title and description.
   */
  imageAlt?: string;
  /** CTA link text. */
  linkLabel?: string;
  /** CTA link URL. */
  linkHref?: string;
  /** Custom content rendered below the standard body. */
  children?: ReactNode;
}

// =============================================================================
// Component
// =============================================================================

/**
 * Standard featured card for the TopNavMegaMenu `featured` slot.
 *
 * Provides a consistent card with optional image, title, description,
 * and CTA link. For fully custom content, pass any ReactNode directly
 * to the `featured` slot instead.
 *
 * @example
 * ```
 * <TopNavMegaMenu
 *   label="Products"
 *   items={...}
 *   featured={
 *     <TopNavMegaMenuFeaturedCard
 *       title="What's new in v4.0"
 *       description="AI-powered analytics and real-time collaboration."
 *       image="https://example.com/promo.jpg"
 *       imageAlt="Team collaboration"
 *       linkLabel="Read the announcement"
 *       linkHref="/blog/v4"
 *     />
 *   }
 * />
 * ```
 */
export function TopNavMegaMenuFeaturedCard({
  ref,
  title,
  description,
  image,
  imageAlt,
  linkLabel,
  linkHref,
  children,
  xstyle,
  className,
  style,
  ...rest
}: TopNavMegaMenuFeaturedCardProps) {
  const LinkComponent = useLinkComponent();
  return <div ref={ref} {...mergeProps(themeProps('top-nav-mega-menu-featured-card'), stylex.props(styles.root, xstyle), className, style)} {...rest}>
      {image &&
    // Without `imageAlt`, the image is explicitly decorative rather than
    // silently empty-alt, matching Avatar's handling of unnamed images.
    // Usually correct here: the card already has a visible title.
    <img src={image} alt={imageAlt ?? ''} role={imageAlt ? undefined : 'presentation'} aria-hidden={imageAlt ? undefined : true} className="xh8yej3 xhjk10j xl1xv1r x1lliihq" />}
      <div className="x78zum5 xdt5ytf x1txdalj x1shk3sm">
        <span className="xcr08ib x2mo6ok x1kq96og x1tgivj0">{title}</span>
        {description && <span className="x141an7d x1ltkj2j xv1l7n4">{description}</span>}
        {linkLabel && linkHref && <LinkComponent href={linkHref} className="x141an7d x2mo6ok x1ltkj2j xjse4m1 x1hl2dhg">
            {linkLabel} →
          </LinkComponent>}
        {children}
      </div>
    </div>;
}
TopNavMegaMenuFeaturedCard.displayName = 'TopNavMegaMenuFeaturedCard';