kaizen-lib 0.2.11 → 0.2.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaizen-lib",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "description": "Tokens y componentes compartidos entre los fronts de Kaizen.",
   "license": "MIT",
   "author": "Nicolás Sandobal",

package/src/ui/DiscoHaxball.tsx

@@ -1,81 +1,101 @@
-'use client';
-
-import { useId } from 'react';
-import styled from 'styled-components';
-import { CAMISETAS_HAXBALL, type CamisetaHaxball, type NombreCamiseta } from './camisetasHaxball';
-
-export { CAMISETAS_HAXBALL } from './camisetasHaxball';
-export type { CamisetaHaxball, NombreCamiseta } from './camisetasHaxball';
-
-type Props = {
-  /** Una clave de `CAMISETAS_HAXBALL`, o una camiseta suelta para previsualizar valores que todavía no están en el catálogo. */
-  camiseta: NombreCamiseta | CamisetaHaxball;
-  /** Lado del cuadrado, en px. */
-  size?: number;
-  className?: string;
-};
-
-/** Ancho de cada franja, en unidades del `viewBox` (0 a 100). No sale de ningún dato de Haxball: es la aproximación que arma un patrón legible sobre un disco de ese tamaño. */
-const GROSOR_FRANJA = 16;
-
-/** Alto de sobra del patrón para que, rotado a cualquier ángulo, siga cubriendo el círculo entero (diagonal de un cuadrado de 100 ≈ 141). */
-const ALTO_PATRON = 200;
-
-function resolverCamiseta(camiseta: Props['camiseta']): CamisetaHaxball {
-  return typeof camiseta === 'string' ? CAMISETAS_HAXBALL[camiseta] : camiseta;
-}
-
-const Svg = styled.svg`
-  display: block;
-  flex-shrink: 0;
-`;
-
-/**
- * El disco de Haxball: la ficha con la que un jugador aparece en la cancha,
- * pintada con las franjas que arma `room.setTeamColors(equipo, angulo,
- * colorTexto, colores)` — la única personalización visual que da la API del
- * juego, y la fuente de `CAMISETAS_HAXBALL` (copiada de
- * `kaizen-bot/structure/base.js`).
- *
- * **Es una aproximación, no un renderer pixel-perfect.** No hay documentación
- * pública del algoritmo exacto de Haxball (grosor real de franja, radio real
- * del disco): esto reproduce el modelo general —franjas paralelas rotadas por
- * `angulo`, cicladas por `colores`— calibrado a ojo. Si en algún momento hace
- * falta fidelidad exacta, hay que calibrarlo contra capturas del juego real,
- * no contra esta implementación.
- *
- * No dibuja `colorTexto`: en el juego es el color del número de jugador sobre
- * el disco, y acá no hay ningún número que mostrar (esto es un selector fuera
- * de partida, no una ficha en cancha). El dato queda en `CamisetaHaxball` por
- * si el día de mañana hace falta superponer una inicial o un número.
- */
-export function DiscoHaxball({ camiseta, size = 64, className }: Props) {
-  const { angulo, colores, nombre } = resolverCamiseta(camiseta);
-  const patternId = `disco-haxball-${useId()}`;
-
-  return (
-    <Svg
-      viewBox="0 0 100 100"
-      width={size}
-      height={size}
-      role="img"
-      aria-label={`Camiseta de ${nombre}`}
-      className={className}
-    >
-      <defs>
-        <pattern
-          id={patternId}
-          patternUnits="userSpaceOnUse"
-          width={GROSOR_FRANJA * colores.length}
-          height={ALTO_PATRON}
-          patternTransform={`rotate(${angulo} 50 50)`}
-        >
-          {colores.map((color, indice) => (
-            <rect key={indice} x={indice * GROSOR_FRANJA} y={0} width={GROSOR_FRANJA} height={ALTO_PATRON} fill={color} />
-          ))}
-        </pattern>
-      </defs>
-      <circle cx={50} cy={50} r={48} fill={`url(#${patternId})`} />
-    </Svg>
-  );
-}
+'use client';
+
+import { useId } from 'react';
+import styled from 'styled-components';
+import { CAMISETAS_HAXBALL, type CamisetaHaxball, type NombreCamiseta } from './camisetasHaxball';
+import { recortarAvatarHaxball } from './avatarHaxball';
+
+export { CAMISETAS_HAXBALL } from './camisetasHaxball';
+export type { CamisetaHaxball, NombreCamiseta } from './camisetasHaxball';
+export { recortarAvatarHaxball, LUGARES_AVATAR_HAXBALL } from './avatarHaxball';
+
+type Props = {
+  /** Una clave de `CAMISETAS_HAXBALL`, o una camiseta suelta para previsualizar valores que todavía no están en el catálogo. */
+  camiseta: NombreCamiseta | CamisetaHaxball;
+  /** El avatar del jugador sobre el disco, en `colorTexto`: lo que no entra se corta con `recortarAvatarHaxball`. */
+  texto?: string;
+  /** Lado del cuadrado, en px. */
+  size?: number;
+  className?: string;
+};
+
+/** Ancho del `viewBox`: un solo ciclo de colores cubre el disco de punta a punta, como en Haxball — 3 colores son 3 franjas, nunca un patrón que se repite. */
+const ANCHO_DISCO = 100;
+
+/** Alto de sobra del patrón para que, rotado a cualquier ángulo, siga cubriendo el círculo entero (diagonal de un cuadrado de 100 ≈ 141). */
+const ALTO_PATRON = 200;
+
+
+function resolverCamiseta(camiseta: Props['camiseta']): CamisetaHaxball {
+  return typeof camiseta === 'string' ? CAMISETAS_HAXBALL[camiseta] : camiseta;
+}
+
+const Svg = styled.svg`
+  display: block;
+  flex-shrink: 0;
+`;
+
+/**
+ * El disco de Haxball: la ficha con la que un jugador aparece en la cancha,
+ * pintada con las franjas que arma `room.setTeamColors(equipo, angulo,
+ * colorTexto, colores)` — la única personalización visual que da la API del
+ * juego, y la fuente de `CAMISETAS_HAXBALL` (copiada de
+ * `kaizen-bot/structure/base.js`).
+ *
+ * **Es una aproximación, no un renderer pixel-perfect.** No hay documentación
+ * pública del algoritmo exacto de Haxball (grosor real de franja, radio real
+ * del disco): esto reproduce el modelo general —franjas paralelas rotadas por
+ * `angulo`, una por color y de igual ancho, repartidas sobre el disco—
+ * calibrado a ojo. Si en algún momento hace falta fidelidad exacta, hay que
+ * calibrarlo contra capturas del juego real, no contra esta implementación.
+ *
+ * `texto` se dibuja en `colorTexto`, el mismo color que usa el juego para el
+ * avatar del jugador sobre el disco.
+ */
+export function DiscoHaxball({ camiseta, texto, size = 64, className }: Props) {
+  const { angulo, colorTexto, colores, nombre } = resolverCamiseta(camiseta);
+  const caracteres = texto ? recortarAvatarHaxball(texto) : '';
+  const patternId = `disco-haxball-${useId()}`;
+  const grosorFranja = ANCHO_DISCO / colores.length;
+
+  return (
+    <Svg
+      viewBox={`0 0 ${ANCHO_DISCO} ${ANCHO_DISCO}`}
+      width={size}
+      height={size}
+      role="img"
+      aria-label={`Camiseta de ${nombre}`}
+      className={className}
+    >
+      <defs>
+        <pattern
+          id={patternId}
+          patternUnits="userSpaceOnUse"
+          width={ANCHO_DISCO}
+          height={ALTO_PATRON}
+          patternTransform={`rotate(${angulo} 50 50)`}
+        >
+          {colores.map((color, indice) => (
+            <rect key={indice} x={indice * grosorFranja} y={0} width={grosorFranja} height={ALTO_PATRON} fill={color} />
+          ))}
+        </pattern>
+      </defs>
+      <circle cx={50} cy={50} r={48} fill={`url(#${patternId})`} />
+      {caracteres && (
+        <text
+          x={50}
+          y={50}
+          textAnchor="middle"
+          dominantBaseline="central"
+          fontFamily="Arial, Helvetica, sans-serif"
+          fontWeight={700}
+          fontSize={44}
+          fill={colorTexto}
+          aria-hidden="true"
+        >
+          {caracteres}
+        </text>
+      )}
+    </Svg>
+  );
+}

package/src/ui/PanelExpandible.tsx

@@ -0,0 +1,299 @@
+'use client';
+
+import { useEffect, useId, useState, type ReactNode } from 'react';
+import styled from 'styled-components';
+import { fg, font, hairline, motion, radius, ring, shadow, space, surface } from '../tokens';
+
+/**
+ * Un **panel** de una pantalla: una elevación partida en dos. Elicitado de
+ * valle-verde (v1.3.13), donde ya lo usaban siete pantallas.
+ *
+ * - **Cabecera**: el título y, bien a la vista, el **indicador** que resume lo
+ *   que hay adentro, con una leyenda chica debajo que dice qué es ese número.
+ *   En el extremo, el chevron.
+ * - **Cuerpo**: el contenido. Se pliega y se despliega.
+ *
+ * El indicador es lo que justifica plegar: con el panel cerrado la cabecera
+ * sigue diciendo lo que importa, y la pantalla entra entera sin scrollear.
+ *
+ * ## Decisiones
+ *
+ * - **Plegado no desmonta.** El cuerpo queda en el DOM con `hidden`: una tabla
+ *   con filas seleccionadas o filtros cargados los conserva al reabrir, y no
+ *   vuelve a pedir sus datos.
+ * - **El control accesible es el chevron**, un botón con `aria-expanded` y
+ *   `aria-controls`. Toda la cabecera responde al click por comodidad de mouse
+ *   y de dedo, pero no es un botón: adentro lleva un encabezado y un número, y
+ *   un botón no puede contener un encabezado.
+ * - **Controlado o no**: `abierto` + `onCambiar`, o `abiertoInicial`.
+ * - **Se compacta, no desborda.** El plegable es un grid con la columna en
+ *   `minmax(0, 1fr)`: sin columna declarada, la implícita medía el ancho
+ *   máximo del contenido y una tabla ancha empujaba el panel fuera de la
+ *   pantalla (valle-verde 1.4.3).
+ *
+ * ```tsx
+ * <PanelExpandible titulo="Comprometido" indicador={12} leyenda="pacientes sin entrega">
+ *   <Tabla />
+ * </PanelExpandible>
+ * ```
+ */
+
+const Raiz = styled.section`
+  border-radius: ${radius.lg};
+  background: ${surface[1]};
+  box-shadow: ${shadow.sm};
+  min-width: 0;
+`;
+
+const Cabecera = styled.div<{ $abierto: boolean; $plegable: boolean }>`
+  display: flex;
+  align-items: center;
+  gap: ${space[4]};
+  padding: ${space[4]} ${space[5]};
+  border-radius: ${({ $abierto }) => ($abierto ? `${radius.lg} ${radius.lg} 0 0` : radius.lg)};
+  cursor: ${({ $plegable }) => ($plegable ? 'pointer' : 'default')};
+  user-select: none;
+  transition: background ${motion.fast} ${motion.ease};
+
+  &:hover {
+    background: ${({ $plegable }) => ($plegable ? surface.hover : 'transparent')};
+  }
+`;
+
+const Titulo = styled.h2`
+  flex: 1 1 auto;
+  min-width: 0;
+  margin: 0;
+  font-size: ${font.xl};
+  font-weight: 600;
+  line-height: 1.2;
+  color: ${fg.DEFAULT};
+  overflow-wrap: anywhere;
+`;
+
+const Indicador = styled.div`
+  flex: 0 1 auto;
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+  text-align: right;
+`;
+
+const Valor = styled.strong`
+  font-size: ${font['2xl']};
+  font-weight: 600;
+  line-height: 1.1;
+  font-variant-numeric: tabular-nums;
+  color: ${fg.DEFAULT};
+  white-space: nowrap;
+`;
+
+const Leyenda = styled.span`
+  font-size: ${font.xs};
+  color: ${fg.subtle};
+`;
+
+const Indicadores = styled.div`
+  flex: 0 1 auto;
+  min-width: 0;
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: flex-end;
+  gap: ${space[2]} ${space[5]};
+`;
+
+const Chevron = styled.button<{ $abierto: boolean; $duracion: number }>`
+  flex: 0 0 auto;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 36px;
+  height: 36px;
+  padding: 0;
+  border: none;
+  border-radius: ${radius.md};
+  background: transparent;
+  color: ${fg.muted};
+  cursor: pointer;
+  outline: 2px solid transparent;
+  outline-offset: 2px;
+
+  &:focus-visible { outline-color: ${ring}; }
+
+  svg {
+    transform: rotate(${({ $abierto }) => ($abierto ? '180deg' : '0deg')});
+    transition: transform ${({ $duracion }) => Math.min($duracion, 300)}ms ${motion.ease};
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    svg { transition: none; }
+  }
+`;
+
+const Cuerpo = styled.div`
+  padding: ${space[5]};
+  border-top: 1px solid ${hairline.DEFAULT};
+  min-width: 0;
+`;
+
+/*
+ * El alto se anima con `grid-template-rows` de 0fr a 1fr: anima hasta el alto
+ * real del contenido sin medirlo, que con `height` no se puede (no anima a
+ * `auto`). El hijo directo recorta lo que no entra mientras tanto.
+ */
+const Plegable = styled.div<{ $expandido: boolean; $duracion: number }>`
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+  grid-template-rows: ${({ $expandido }) => ($expandido ? '1fr' : '0fr')};
+  transition: grid-template-rows ${({ $duracion }) => $duracion}ms ${motion.ease};
+
+  > div {
+    min-height: 0;
+    overflow: hidden;
+  }
+
+  &[hidden] { display: none; }
+
+  @media (prefers-reduced-motion: reduce) {
+    transition: none;
+  }
+`;
+
+/**
+ * ¿Se anima? Con `prefers-reduced-motion`, y donde el navegador no sabe
+ * preguntarlo, el panel se abre y se cierra de una (el estado seguro).
+ */
+const puedeAnimar = (): boolean =>
+  typeof window !== 'undefined'
+  && typeof window.matchMedia === 'function'
+  && typeof window.requestAnimationFrame === 'function'
+  && !window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+export type PanelExpandibleProps = {
+  /** El nombre del panel. Se escribe como se lee: "Comprometido", no "COMPROMETIDO". */
+  titulo: string;
+  /** El número (o dato) que resume el contenido. Va grande, a la derecha de la cabecera. */
+  indicador?: ReactNode;
+  /** Qué es el indicador, en una línea corta. */
+  leyenda?: ReactNode;
+  /** Más de un indicador, cada uno con su leyenda. Con esto, `indicador` y `leyenda` no se miran. */
+  indicadores?: { valor: ReactNode; leyenda?: ReactNode }[];
+  /**
+   * Si el panel se pliega (por defecto, sí). Con `false` conserva el formato pero no
+   * tiene chevron ni responde al click: para la pantalla que tiene **un solo** panel.
+   */
+  plegable?: boolean;
+  /** Arranca abierto (por defecto) o plegado, cuando el panel maneja su propio estado. */
+  abiertoInicial?: boolean;
+  /** Controlado desde afuera. Con esto, `abiertoInicial` no se mira. */
+  abierto?: boolean;
+  onCambiar?: (abierto: boolean) => void;
+  /** Cuánto tarda en plegarse o desplegarse, en ms. Default 300. */
+  duracionMs?: number;
+  /**
+   * Nombre accesible del chevron, sin el título (que se agrega solo). Defaults
+   * `'Plegar'` y `'Desplegar'`: un consumidor con más de un idioma los pisa.
+   */
+  etiquetaPlegar?: string;
+  etiquetaDesplegar?: string;
+  className?: string;
+  children: ReactNode;
+};
+
+export function PanelExpandible({
+  titulo,
+  indicador,
+  leyenda,
+  indicadores,
+  plegable = true,
+  abiertoInicial = true,
+  abierto: abiertoControlado,
+  onCambiar,
+  duracionMs = 300,
+  etiquetaPlegar = 'Plegar',
+  etiquetaDesplegar = 'Desplegar',
+  className,
+  children,
+}: PanelExpandibleProps) {
+  const [abiertoPropio, setAbiertoPropio] = useState(abiertoInicial);
+  const abierto = !plegable || (abiertoControlado ?? abiertoPropio);
+
+  /*
+   * Dos estados además de `abierto`: si el cuerpo está en el árbol visible
+   * (`montado`) y si está desplegado (`expandido`). Al abrir, primero se
+   * muestra plegado y en el cuadro siguiente se despliega, para que haya algo
+   * que animar. Al cerrar, se pliega y recién al terminar se oculta: así lo
+   * plegado no queda enfocable ni lo lee un lector de pantalla. Por eso la
+   * duración es una prop y no sólo CSS: el temporizador tiene que coincidir.
+   */
+  const [montado, setMontado] = useState(abierto);
+  const [expandido, setExpandido] = useState(abierto);
+  useEffect(() => {
+    if (!puedeAnimar()) {
+      setMontado(abierto);
+      setExpandido(abierto);
+      return undefined;
+    }
+    if (abierto) {
+      setMontado(true);
+      const cuadro = window.requestAnimationFrame(() => setExpandido(true));
+      return () => window.cancelAnimationFrame(cuadro);
+    }
+    setExpandido(false);
+    const espera = window.setTimeout(() => setMontado(false), duracionMs);
+    return () => window.clearTimeout(espera);
+  }, [abierto, duracionMs]);
+  const idCuerpo = useId();
+
+  const alternar = () => {
+    if (!plegable) return;
+    if (abiertoControlado === undefined) setAbiertoPropio(!abierto);
+    onCambiar?.(!abierto);
+  };
+
+  const hayIndicador = indicador !== undefined && indicador !== null;
+
+  return (
+    <Raiz className={className}>
+      <Cabecera $abierto={abierto} $plegable={plegable} onClick={alternar}>
+        <Titulo>{titulo}</Titulo>
+        {indicadores ? (
+          <Indicadores>
+            {indicadores.map((it, i) => (
+              <Indicador key={i}>
+                <Valor>{it.valor}</Valor>
+                {it.leyenda && <Leyenda>{it.leyenda}</Leyenda>}
+              </Indicador>
+            ))}
+          </Indicadores>
+        ) : (hayIndicador || leyenda) && (
+          <Indicador>
+            {hayIndicador && <Valor>{indicador}</Valor>}
+            {leyenda && <Leyenda>{leyenda}</Leyenda>}
+          </Indicador>
+        )}
+        {plegable && (
+          <Chevron
+            type="button"
+            $abierto={abierto}
+            $duracion={duracionMs}
+            aria-expanded={abierto}
+            aria-controls={idCuerpo}
+            aria-label={`${abierto ? etiquetaPlegar : etiquetaDesplegar} ${titulo}`}
+            // El click sube a la cabecera, que es la que alterna: acá no se repite.
+          >
+            <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+              <polyline points="6 9 12 15 18 9" />
+            </svg>
+          </Chevron>
+        )}
+      </Cabecera>
+      <Plegable id={idCuerpo} $expandido={expandido} $duracion={duracionMs} hidden={!montado}>
+        <div>
+          <Cuerpo>{children}</Cuerpo>
+        </div>
+      </Plegable>
+    </Raiz>
+  );
+}

package/src/ui/avatarHaxball.ts

@@ -0,0 +1,23 @@
+/** Lugares del avatar de Haxball sobre el disco: dos caracteres, o un emoji que ocupa los dos. */
+export const LUGARES_AVATAR_HAXBALL = 2;
+
+const EMOJI = /\p{Extended_Pictographic}|\p{Regional_Indicator}/u;
+
+/**
+ * Recorta un texto a lo que entra en el avatar: cuenta por grafemas (una
+ * bandera o una familia es uno solo), un emoji ocupa los 2 lugares y lo que
+ * no entra entero se descarta, en orden. Es la regla que valida quien guarda
+ * el avatar y la que aplica `DiscoHaxball` al dibujarlo.
+ */
+export function recortarAvatarHaxball(texto: string): string {
+  const grafemas = new Intl.Segmenter(undefined, { granularity: 'grapheme' }).segment(texto.trim());
+  let resultado = '';
+  let ocupados = 0;
+  for (const { segment } of grafemas) {
+    const lugares = EMOJI.test(segment) ? LUGARES_AVATAR_HAXBALL : 1;
+    if (ocupados + lugares > LUGARES_AVATAR_HAXBALL) break;
+    resultado += segment;
+    ocupados += lugares;
+  }
+  return resultado;
+}