import type { ReactNode } from "react";

interface Props {
  /** El título de la pantalla. El único `<h1>` de la página. */
  title: string;
  /** Metadato breve que completa el título, como el rol de la cuenta. */
  titleAccessory?: ReactNode;
  /** Qué contesta esta pantalla, en una o dos líneas. */
  description?: ReactNode;
  /** Los controles de la pantalla. Como mucho uno primario. */
  actions?: ReactNode;
  /** Un slot para contenido adicional al final de la página. */
  footerSlot?: ReactNode;
}

/**
 * El encabezado de la página: título, sus acciones y su bajada.
 *
 * Existe porque **el contenido no tenía encabezado**. La franja de arriba es
 * navegación —dice dónde estás, no qué es esta pantalla— y sin embargo era el
 * único lugar del producto donde aparecía el nombre de la vista y donde
 * terminaban colgados los botones. El resultado era una columna de contenido que
 * empezaba en cualquier cosa: una tabla, un aviso, un párrafo suelto.
 *
 * Los tres slots son los mismos para las trece pantallas, y ése es el punto: la
 * vista pasa contenido y no decide tamaños. Antes cada una elegía el suyo, que
 * es de dónde salían siete formas distintas de dibujar el mismo nivel.
 *
 * **El `<h1>` vive acá y no en la barra.** Un localizador de navegación no es el
 * titular de la pantalla, y tenerlo como `h1` dejaba a las trece vistas sin
 * ningún encabezado propio en el contenido.
 *
 * Las acciones envuelven y no se recortan: un título largo empuja para abajo y
 * nunca deja el botón afuera del borde.
 */
export function PageHeading({
  title,
  titleAccessory,
  description,
  actions,
  footerSlot = null,
}: Props) {
  return (
    <div className="flex flex-col gap-x-1.5">
      <div className="flex flex-wrap items-start justify-between gap-x-4 gap-y-2">
        <div className="flex min-w-0 flex-wrap items-center gap-2">
          <h1 className="min-w-0 text-2xl font-bold tracking-tight text-balance">
            {title}
          </h1>
          {titleAccessory}
        </div>

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

      {description && (
        <p className="text-muted-foreground text-sm text-pretty">
          {description}
        </p>
      )}

      {footerSlot && (
        <div className="flex flex-wrap items-center gap-2 mt-3">{footerSlot}</div>
      )}
    </div>
  );
}