Endpoint API.

<section class="ui-sample ui-service" data-api-endpoint="true"><header><code>GET</code><strong>/api/v1/components</strong><span class="badge badge--ok">200</span></header><pre><code>Accept: application/json
ETag: &quot;498f99c6&quot;</code></pre><p>184 componentes · 42 ms</p><a class="btn btn--quiet" href="#openapi">Abrir en OpenAPI</a></section>

<section class="ui-sample ui-service border border-slate-300 bg-white p-4 text-slate-950 grid gap-3" data-api-endpoint="true"><header class="flex flex-wrap items-center justify-between gap-3"><code>GET</code><strong>/api/v1/components</strong><span class="badge badge--ok">200</span></header><pre class="overflow-x-auto border border-slate-300 bg-slate-50 p-3"><code>Accept: application/json
ETag: &quot;498f99c6&quot;</code></pre><p>184 componentes · 42 ms</p><a class="btn btn--quiet underline underline-offset-4" href="#openapi">Abrir en OpenAPI</a></section>

export interface ApiEndpointProps {
  /** Método HTTP del endpoint. */
  method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
  /** Ruta del endpoint, sin dominio. */
  path?: string;
  /** Código HTTP de la última respuesta; se muestra como etiqueta y vacío la oculta. */
  httpStatus?: number | string;
  /** Tono de la etiqueta del código; por defecto se deduce del código (2xx: `ok`; 3xx: `warn`; 4xx y 5xx: `err`; otro: `neutral`). */
  statusTone?: "ok" | "warn" | "err" | "neutral";
  /** Ejemplo en texto plano (encabezados, cuerpo o comando); acepta varias líneas separadas por `\n`. Vacío oculta el bloque de código. */
  example?: string;
  /** Resultado de la última llamada: volumen, latencia o instrucción de reintento; vacío lo oculta. */
  detail?: string;
  /** URL de la documentación del endpoint. */
  href?: string;
  /** Texto del enlace a la documentación; vacío lo oculta. */
  linkLabel?: string;
  className?: string;
}

function claseEstado(httpStatus: number | string, tone?: "ok" | "warn" | "err" | "neutral") {
  const codigo = Number(httpStatus);
  const deducido = codigo >= 200 && codigo < 300 ? "ok" : codigo >= 300 && codigo < 400 ? "warn" : codigo >= 400 && codigo < 600 ? "err" : "neutral";
  const tono = tone ?? deducido;
  return tono === "neutral" ? "badge" : `badge badge--${tono}`;
}

/**
 * Ficha de un endpoint de API con método, ruta, código de la última respuesta, un ejemplo y enlace a su documentación; se usa en paneles de integración y catálogos de API.
 *
 * El código de la última respuesta va en texto dentro de una etiqueta con tono (`badge`), no sólo en color; el enlace a la documentación es una acción terciaria (`btn--quiet`).
 *
 * @example <ApiEndpoint method="GET" path="/api/v1/components" httpStatus={200} example={"Accept: application/json\nETag: \"498f99c6\""} detail="184 componentes · 42 ms" href="/openapi#components" />
 * @example <ApiEndpoint httpStatus={503} example={"Accept: application/json\nRetry-After: 60"} detail="Servicio no disponible · nuevo intento en 60 s" />
 */
export function ApiEndpoint({
  method = "GET",
  path = "/api/v1/components",
  httpStatus = 200,
  statusTone,
  example = "Accept: application/json\nETag: \"498f99c6\"",
  detail = "184 componentes · 42 ms",
  href = "#openapi",
  linkLabel = "Abrir en OpenAPI",
  className,
}: ApiEndpointProps) {
  return (
    <section className={["ui-service", className].filter(Boolean).join(" ")} data-api-endpoint>
      <header>
        <code>{method}</code>
        <strong>{path}</strong>
        {httpStatus !== "" ? <span className={claseEstado(httpStatus, statusTone)}>{httpStatus}</span> : null}
      </header>
      {example ? (
        <pre>
          <code>{example}</code>
        </pre>
      ) : null}
      {detail ? <p>{detail}</p> : null}
      {linkLabel ? <a className="btn btn--quiet" href={href}>{linkLabel}</a> : null}
    </section>
  );
}