import * as React from "react";
import { cn } from "@/lib/utils";

/**
 * PageHeader — WealthX Design System
 *
 * In-page heading block. Renders inside scrollable content — not part of
 * the layout shell. Use for sections that need a visible title and optional
 * description (e.g. "My Advisors", "How can we help?").
 *
 * For a sticky top-of-page bar with action buttons, use PageTopBar instead.
 */

// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------

export interface PageHeaderProps {
  /** Main page / section title */
  title: string;
  /** Optional subtitle shown below the title */
  description?: string;
  /** Optional action elements rendered to the right of the title block */
  actions?: React.ReactNode;
  className?: string;
}

// ---------------------------------------------------------------------------
// Component
// ---------------------------------------------------------------------------

export function PageHeader({
  title,
  description,
  actions,
  className,
}: PageHeaderProps) {
  return (
    <div
      data-slot="page-header"
      className={cn("flex items-start justify-between gap-4", className)}
    >
      {/* Title + description */}
      <div className="flex flex-col gap-0.5">
        <h1 className="text-xl font-bold leading-tight">{title}</h1>
        {description && (
          <p className="text-sm text-muted-foreground">{description}</p>
        )}
      </div>

      {/* Optional actions */}
      {actions && (
        <div className="flex shrink-0 items-center gap-2">{actions}</div>
      )}
    </div>
  );
}