Leyenda cartográfica.

<section class="ui-sample ui-map" data-map-legend="true"><strong>Pobreza por ingresos por comuna, 2022</strong><ol><li><span class="map-swatch map-swatch--low" aria-hidden="true"></span> Menos de 5%</li><li><span class="map-swatch map-swatch--mid" aria-hidden="true"></span> 5 a 10%</li><li><span class="map-swatch map-swatch--high" aria-hidden="true"></span> Más de 10%</li><li><span class="map-swatch map-swatch--sin-datos" aria-hidden="true"></span> Sin datos</li></ol><small>Fuente: Ministerio de Desarrollo Social y Familia, estimación comunal</small></section>

<section class="ui-sample ui-map border border-slate-300 bg-white p-4 text-slate-950 grid gap-3" data-map-legend="true"><strong>Pobreza por ingresos por comuna, 2022</strong><ol class="grid gap-2"><li><span class="map-swatch map-swatch--low" aria-hidden="true"></span> Menos de 5%</li><li><span class="map-swatch map-swatch--mid" aria-hidden="true"></span> 5 a 10%</li><li><span class="map-swatch map-swatch--high" aria-hidden="true"></span> Más de 10%</li><li><span class="map-swatch map-swatch--sin-datos" aria-hidden="true"></span> Sin datos</li></ol><small class="text-sm text-slate-600">Fuente: Ministerio de Desarrollo Social y Familia, estimación comunal</small></section>

export interface MapLegendItem {
  /** Rango o categoría que representa la muestra («Menos de 5%»). */
  label: string;
  /** Categoría sin datos: la muestra va hueca (sólo el borde) para no confundirla con cero. */
  noData?: boolean;
  /** Tono de la muestra de color: bajo (`map-swatch--low`, el de `map-zone--1`), medio (`--mid`, `map-zone--3`) o alto (`--high`, `map-zone--4`). Sin `level` ni `color`, la muestra es un cuadro del color del texto. */
  level?: "low" | "mid" | "high";
  /** Color de la muestra, para un tramo que no calza con `level`, como el de `map-zone--2`; tiene prioridad sobre el de `level`. Va como `fill` de un SVG dentro de la muestra (no como estilo en línea): acepta un color literal (`#79c8ae`, `rgb(…)`), no `var()`; para un color del kit usa `level`. */
  color?: string;
}

export interface MapLegendProps {
  /** Qué mide el mapa y a qué unidad territorial corresponde. */
  title?: string;
  /** Categorías en orden, de menor a mayor, con la de sin datos al final; sin categorías no se muestra la leyenda. */
  items?: MapLegendItem[];
  /** Origen de los datos, con su prefijo («Fuente: …»); vacío lo oculta. */
  source?: string;
  className?: string;
}

const CATEGORIAS: MapLegendItem[] = [
  { label: "Menos de 5%", level: "low" },
  { label: "5 a 10%", level: "mid" },
  { label: "Más de 10%", level: "high" },
  { label: "Sin datos", noData: true },
];

// Hueca sin datos (map-swatch--sin-datos); `color` gana a `level` y se pinta con un SVG
// (un atributo fill no es un estilo en línea), sin la clase del tono debajo para que un
// color translúcido no deje ver el de `level`; sin ninguno de los dos, del color del
// texto (map-swatch--texto).
function claseMuestra(item: MapLegendItem): string {
  if (item.noData) return "map-swatch map-swatch--sin-datos";
  if (item.color) return "map-swatch";
  return item.level ? `map-swatch map-swatch--${item.level}` : "map-swatch map-swatch--texto";
}

/**
 * Leyenda que acompaña a un mapa temático para leer qué representa cada muestra: título de la medida, categorías ordenadas y fuente de los datos.
 *
 * Cada categoría con `level` toma el color del tramo correspondiente de `MapChoropleth`. La categoría sin datos lleva `noData: true` y una muestra hueca, distinta de la de cero. Las muestras son decorativas (`aria-hidden`): el rango se lee en el texto.
 *
 * @example <MapLegend title="Desocupación por región" items={[{ label: "Menos de 6%", level: "low" }, { label: "6 a 9%", level: "mid" }, { label: "Más de 9%", level: "high" }, { label: "Sin datos", noData: true }]} source="Fuente: INE, Encuesta Nacional de Empleo" />
 */
export function MapLegend({
  title = "Pobreza por ingresos por comuna, 2022",
  items = CATEGORIAS,
  source = "Fuente: Ministerio de Desarrollo Social y Familia, estimación comunal",
  className,
}: MapLegendProps) {
  if (!items.length) return null;
  return (
    <section className={["ui-map", className].filter(Boolean).join(" ")} data-map-legend>
      {title ? <strong>{title}</strong> : null}
      <ol>
        {items.map((item, i) => (
          <li key={`${item.label}-${i}`}>
            <span className={claseMuestra(item)} aria-hidden="true">
              {item.color && !item.noData ? (
                <svg className="map-swatch__color" viewBox="0 0 1 1" preserveAspectRatio="none" aria-hidden="true" focusable="false">
                  <rect width="1" height="1" fill={item.color} />
                </svg>
              ) : null}
            </span>
            {` ${item.label}`}
          </li>
        ))}
      </ol>
      {source ? <small>{source}</small> : null}
    </section>
  );
}