new components

libs/ui/README.md

@@ -72,6 +72,14 @@ hecho **no se pueden enlazar a mano** esas entradas en un elemento que ya use
 
 Se puede ver funcionando en la app `playground` (`nx serve playground`).
 
+## Theming: tokens CSS
+
+El aspecto visual (color, forma, sombra, tipografía de controles) se resuelve
+en custom properties (`--pi-color-*`, `--pi-theme-*`) aplicadas vía `ShellClass`
+(`pi-shell pi-shell__<tema>`). Documentación completa, tabla de valores por
+tema (Default/Alternative/Minimal/Gradient) y guía para añadir tokens o temas
+nuevos: [`TOKENS.md`](./TOKENS.md).
+
 | Componente                                           | Contrato              | Tipo del valor                        |
 | ---------------------------------------------------- | --------------------- | ------------------------------------- |
 | text, email, password, phone, icon, search, textarea | `FormValueControl`    | `string`                              |
@@ -106,6 +114,63 @@ Detalles a tener en cuenta:
 Los selects (`ui/select`) siguen con `ControlValueAccessor`; quedaron fuera del
 alcance de esta migración.
 
+## Charts
+
+`pi-chart` (un componente, un input `type`) se dividió en **4 componentes
+independientes** — `pi-line-chart`, `pi-bar-chart`, `pi-pie-chart`,
+`pi-doughnut-chart` —, cada uno en su propia carpeta, con su propio selector y
+su propio registro de Chart.js. Ningún consumidor arrastra código de un tipo
+de gráfico que no usa: `pi-pie-chart` no registra `LineController`/`BarController`.
+
+Comparten dos bases abstractas (no un único componente con `@switch`):
+
+- `PiBaseChartComponent` — el `<canvas>`, `device`, y el ciclo de vida que
+  llama a `buildChart()`.
+- `PiBaseCartesianChartComponent extends PiBaseChartComponent` — de
+  `pi-line-chart`/`pi-bar-chart`: reciben `datasets` (una serie por
+  elemento, comparadas a lo largo de `xAxisMarks`), usan `pi-chart-legend`
+  (leyenda propia, no la de Chart.js) y comparten el tooltip/hover.
+- `PiBaseArcChartComponent extends PiBaseChartComponent` — de
+  `pi-pie-chart`/`pi-doughnut-chart`: reciben `slices`
+  (`{ label, value, color }[]`, tipo `ChartSlice`), no `datasets` — la forma
+  de los datos es otra (una magnitud repartida en porciones, cada una con su
+  propio color, no varias series en el tiempo) — y usan la leyenda **nativa**
+  de Chart.js en vez de `pi-chart-legend`.
+
+```html
+<pi-line-chart [device]="device" [xAxisMarks]="meses" [datasets]="datasets" />
+<pi-line-chart [device]="device" [xAxisMarks]="meses" [datasets]="datasets" [filled]="true" /> <!-- área -->
+<pi-bar-chart [device]="device" [xAxisMarks]="meses" [datasets]="datasets" />
+<pi-pie-chart [device]="device" [slices]="slices" />
+<pi-doughnut-chart [device]="device" [slices]="slices" />
+```
+
+Detalles a tener en cuenta:
+
+- **`[filled]="true"` en `pi-line-chart` exige el plugin `Filler` de
+  Chart.js.** Sin registrarlo, `fill: true` en el dataset no falla — se
+  ignora en silencio y el gráfico sale sin rellenar. Ya está registrado en
+  `line-chart.component.ts`; si se añade otro tipo relleno, hay que
+  registrarlo ahí también.
+- **El área usa un color traducido a `rgba(…, 0.15)`, no el `backgroundColor`
+  del dataset tal cual.** Ese campo también pinta el relleno de los puntos;
+  si se reutilizase el color opaco para el área saldría un bloque sólido en
+  vez de una zona translúcida, así que `pointBackgroundColor` conserva el
+  color original y `backgroundColor` pasa a translúcido solo cuando `filled`
+  está activo (ver `hexToRgba` en `chart.configs.ts`).
+- **`DatasetColor` no tenía `success`/`warn`** (solo `primary`/`accent`/
+  `highlighted`/`grey`), así que un `pie`/`doughnut` no podía representar
+  estados (pagado/pendiente/rechazado, etc.) con los mismos colores que
+  `pi-chip-status`. Se añadieron con los mismos hex que `--pi-color-success`/
+  `--pi-color-warn`.
+- **`Dataset.cubicInterpolationMode` pasa a opcional.** Solo tiene sentido en
+  `line`; forzarlo en `bar`/`pie`/`doughnut` no aportaba nada y esos tipos ni
+  siquiera usan `Dataset` (los dos últimos usan `ChartSlice`).
+- **El `type="bar"` del `pi-chart` original nunca funcionó**: el input
+  existía pero `getLineChartConfigs()` construía siempre un chart `line`
+  ignorando su valor. Se descubrió al dividir los componentes; `pi-bar-chart`
+  es la primera versión que realmente renderiza barras.
+
 **El loader de servidor de traducciones ya no está en el barrel.**
 `util/translate/loaders/translate-server.loader` usa `fs`, `path` y `process`;
 exportarlo desde `@pi/ui` rompía el bundle de navegador de cualquier app que