Encabezado documental.

<header class="ui-sample ui-document" data-document-header="true"><span>Contrato de prestación de servicios</span><h2>FYD-184</h2><dl><div><dt>Versión</dt><dd>3.0</dd></div><div><dt>Estado</dt><dd><span class="badge">Borrador</span></dd></div></dl></header>

<header class="ui-sample ui-document border border-slate-300 bg-white p-4 text-slate-950 flex flex-wrap items-center justify-between gap-3" data-document-header="true"><span>Contrato de prestación de servicios</span><h2>FYD-184</h2><dl class="grid gap-2"><div><dt>Versión</dt><dd>3.0</dd></div><div><dt>Estado</dt><dd><span class="badge">Borrador</span></dd></div></dl></header>

export interface DocumentHeaderProps {
  /** Tipo de documento, sobre el título («Contrato de prestación de servicios»); vacío lo oculta. */
  category?: string;
  /** Identificador o título del documento; vacío lo oculta. */
  title?: string;
  /** Versión vigente del documento; vacía oculta el dato. */
  version?: string;
  /** Estado del documento en su ciclo («Borrador», «En revisión», «Firmado»); se muestra como etiqueta y vacío oculta el dato. */
  status?: string;
  /** Tono de la etiqueta de estado; por defecto se deduce del texto (borrador: neutro; en revisión: `warn`; firmado o vigente: `ok`; anulado o vencido: `err`). */
  statusTone?: "ok" | "warn" | "err" | "neutral";
  /** Etiqueta del dato de versión (`<dt>`). */
  versionLabel?: string;
  /** Etiqueta del dato de estado (`<dt>`). */
  statusLabel?: string;
  className?: string;
}

const DOCUMENT_HEADER_TONOS: [string, "ok" | "warn" | "err" | "neutral"][] = [
  ["borrador", "neutral"],
  ["en revisión", "warn"],
  ["pendiente", "warn"],
  ["firmado", "ok"],
  ["vigente", "ok"],
  ["anulado", "err"],
  ["vencido", "err"],
];

function claseEstado(status: string, tone?: "ok" | "warn" | "err" | "neutral") {
  const texto = status.toLowerCase();
  const tono = tone ?? DOCUMENT_HEADER_TONOS.find(([clave]) => texto.startsWith(clave))?.[1] ?? "neutral";
  return tono === "neutral" ? "badge" : `badge badge--${tono}`;
}

/**
 * Encabezado de un documento con su tipo, identificador, versión y estado; va al inicio de la vista de un contrato, acta o informe.
 *
 * Versión y estado van en una lista de definiciones; cada dato vacío se omite. El estado va en texto dentro de una etiqueta con tono (`badge`).
 *
 * @example <DocumentHeader category="Contrato de prestación de servicios" title="FYD-184" version="3.0" status="Borrador" />
 * @example <DocumentHeader title="FYD-184" version="4.0" status="En revisión" />
 */
export function DocumentHeader({
  category = "Contrato de prestación de servicios",
  title = "FYD-184",
  version = "3.0",
  status = "Borrador",
  statusTone,
  versionLabel = "Versión",
  statusLabel = "Estado",
  className,
}: DocumentHeaderProps) {
  return (
    <header className={["ui-document", className].filter(Boolean).join(" ")} data-document-header>
      {category ? <span>{category}</span> : null}
      {title ? <h2>{title}</h2> : null}
      {version || status ? (
        <dl>
          {version ? (
            <div>
              <dt>{versionLabel}</dt>
              <dd>{version}</dd>
            </div>
          ) : null}
          {status ? (
            <div>
              <dt>{statusLabel}</dt>
              <dd>
                <span className={claseEstado(status, statusTone)}>{status}</span>
              </dd>
            </div>
          ) : null}
        </dl>
      ) : null}
    </header>
  );
}