Encabezado de página.

<header class="ui-sample ui-content" data-page-header="true"><h2>Componentes</h2><p>Patrones canónicos con ejemplos y código copiable.</p><nav aria-label="Acciones de página"><a class="btn btn--primary" href="#accion">Abrir inventario</a></nav></header>

<header class="ui-sample ui-content border border-slate-300 bg-white p-4 text-slate-950 flex flex-wrap items-center justify-between gap-3" data-page-header="true"><h2>Componentes</h2><p>Patrones canónicos con ejemplos y código copiable.</p><nav class="flex flex-wrap items-center gap-3" aria-label="Acciones de página"><a class="btn btn--primary underline underline-offset-4" href="#accion">Abrir inventario</a></nav></header>

import type { MouseEventHandler } from "react";

/** Peso visual de una acción: `primary` para la principal (una por página), `secondary` para alternativas y `quiet` para terciarias con aspecto de enlace. */
export type PageHeaderActionVariant = "primary" | "secondary" | "quiet";

export interface PageHeaderAction {
  /** Texto del enlace; vacío omite la acción. */
  label: string;
  href: string;
  /** Se llama al activar el enlace, antes de navegar. */
  onClick?: MouseEventHandler<HTMLAnchorElement>;
  /** Peso visual; por defecto la primera acción visible es `primary` y las demás `secondary`. */
  variant?: PageHeaderActionVariant;
}

const ACTIONS: PageHeaderAction[] = [{ label: "Abrir inventario", href: "#accion" }];

export interface PageHeaderProps {
  /** Título de la página. */
  title?: string;
  /** Una oración que dice qué contiene la página; vacía no se muestra. */
  description?: string;
  /** Enlaces de acción de la página; una lista vacía no emite la navegación y una acción sin texto se omite. */
  actions?: PageHeaderAction[];
  /** Nombre accesible de la navegación de acciones (`aria-label`). */
  actionsLabel?: string;
  className?: string;
}

/**
 * Encabezado de página con título, descripción breve y enlaces de acción; va al inicio de una página de índice, catálogo o sección.
 *
 * Las acciones son enlaces con forma de botón: la primera es la principal y las demás, alternativas, salvo que `variant` diga otra cosa. Las partes vacías no se emiten: sin descripción no hay párrafo y sin acciones no hay navegación.
 *
 * @example <PageHeader title="Catálogo de datos" description="Series, mapas y documentos publicados por COCHID." actions={[{ label: "Descargar catálogo", href: "/catalogo.csv" }, { label: "Ver metodología", href: "/metodologia" }]} />
 * @example <PageHeader title="Componentes" actions={[]} />
 */
export function PageHeader({
  title = "Componentes",
  description = "Patrones canónicos con ejemplos y código copiable.",
  actions = ACTIONS,
  actionsLabel = "Acciones de página",
  className,
}: PageHeaderProps) {
  const visibles = actions.filter((action) => action.label);
  if (!title && !description && !visibles.length) return null;
  return (
    <header className={["ui-content", className].filter(Boolean).join(" ")} data-page-header>
      {title ? <h2>{title}</h2> : null}
      {description ? <p>{description}</p> : null}
      {visibles.length ? (
        <nav aria-label={actionsLabel}>
          {visibles.flatMap((action, i) => {
            const variante = action.variant ?? (i === 0 ? "primary" : "secondary");
            const enlace = <a className={`btn btn--${variante}`} href={action.href} onClick={action.onClick} key={`${action.href}-${i}`}>{action.label}</a>;
            return i ? [" ", enlace] : [enlace];
          })}
        </nav>
      ) : null}
    </header>
  );
}