idicon 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,331 @@
-# Temporary Holding Version
+# IDicon
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Avatares SVG únicos y deterministas a partir de un id. Dado el identificador de un cliente o usuario, `idicon` devuelve siempre el mismo avatar: una persona, un personaje, un objeto o una forma geométrica, con cara, sobre un fondo con patrón y una paleta de hasta 6 colores. No necesita base de datos ni servidor: el avatar se calcula, no se almacena.
+
+El repositorio contiene dos cosas:
+
+- **El paquete npm** `idicon`: la librería que genera los avatares (sin dependencias) y un componente opcional para React.
+- **Una web de demostración** para probar ids, opciones y paletas, y copiar o descargar el resultado.
+
+Índice:
+
+1. [Guía de implementación en otro proyecto](#1-guía-de-implementación-en-otro-proyecto)
+2. [Referencia de la API](#2-referencia-de-la-api)
+3. [Garantías del generador](#3-garantías-del-generador)
+4. [Estabilidad del diseño y versionado](#4-estabilidad-del-diseño-y-versionado)
+5. [Web de demostración](#5-web-de-demostración)
+6. [Mantenimiento del paquete](#6-mantenimiento-del-paquete)
+
+---
+
+
+
+## 1. Guía de implementación en otro proyecto
+
+Pasos para usar IDicon en una aplicación real, con clientes. Síguelos en orden.
+
+### Paso 0: decisiones previas (5 minutos)
+
+Antes de escribir código, acuerda con el equipo:
+
+- **Qué versión se instala.** Siempre una versión concreta (etiqueta `vX.Y.Z` o número en el registro), nunca "lo último de `main`". Ver [sección 4](#4-estabilidad-del-diseño-y-versionado).
+- **Si los avatares llevan la paleta de la empresa.** Si sí, elige los 5 colores (`#rrggbb`) una sola vez. Si no, el generador asigna una paleta distinta a cada id.
+- **Qué id se usa.** Debe ser el identificador **estable** del cliente (el id de la base de datos, el email, un UUID). No uses el nombre si puede cambiar: cambiar el id cambia el avatar.
+
+
+
+### Paso 1: instalar el paquete
+
+Requisitos: Node.js 18 o superior (o cualquier navegador moderno). El paquete es solo módulos ES (`import`). React es opcional y solo hace falta para `idicon/react`.
+
+El paquete está publicado en npm ([npmjs.com/package/idicon](https://www.npmjs.com/package/idicon)). Instala una versión concreta:
+
+```bash
+npm install idicon@0.1.0
+```
+
+Alternativas, por si en algún entorno no hay acceso al registro de npm:
+
+```bash
+# Desde el repositorio Git, fijando una etiqueta de versión
+npm install git+https://github.com/AI-Digital-Solutions-Blue/IDicon-generator.git#v0.1.0
+
+# Desde un fichero generado con npm pack
+npm install ./idicon-0.1.0.tgz
+```
+
+Comprueba en tu `package.json` que la versión queda **fijada sin `^` ni `~`**, por ejemplo `"idicon": "0.1.0"`. Así una actualización del paquete nunca cambia tus avatares sin que tú lo decidas.
+
+### Paso 2: centralizar la configuración
+
+Crea un único módulo en tu aplicación que envuelva al paquete. Todas las pantallas lo usan a él, no a `idicon` directamente, para que las opciones (paleta, contenido) sean las mismas en toda la app y vivan en un solo sitio.
+
+```ts
+// src/lib/avatares.ts
+import { generateAvatarSvg, avatarDataUri, type AvatarOptions } from "idicon";
+
+// Opciones comunes a toda la aplicación. Cambiarlas cambia TODOS los avatares.
+const OPCIONES: AvatarOptions = {
+  // Paleta de marca (5 colores #rrggbb). Quita esta línea para paletas automáticas.
+  palette: ["#12263F", "#2E5E8C", "#7FB2E5", "#F2C14E", "#F7F4EA"],
+  // subject: "person",   // si solo quieres personas
+  // pattern: "plain",    // si prefieres fondos lisos
+};
+
+/** Id estable del cliente → SVG. */
+export function avatarSvg(clienteId: string, size = 96): string {
+  return generateAvatarSvg(clienteId, { ...OPCIONES, size });
+}
+
+/** Igual, como URL para <img src>. */
+export function avatarUrl(clienteId: string, size = 96): string {
+  return avatarDataUri(clienteId, { ...OPCIONES, size });
+}
+```
+
+
+
+### Paso 3: usarlo en la interfaz
+
+**React** (con el componente del paquete y las opciones centralizadas):
+
+```tsx
+// src/components/AvatarCliente.tsx
+import { Avatar } from "idicon/react";
+
+const OPCIONES = { palette: ["#12263F", "#2E5E8C", "#7FB2E5", "#F2C14E", "#F7F4EA"] } as const;
+
+export function AvatarCliente({ id, size = 40 }: { id: string; size?: number }) {
+  return <Avatar id={id} size={size} {...OPCIONES} title={id} />;
+}
+```
+
+```tsx
+<AvatarCliente id={cliente.id} />
+<AvatarCliente id={cliente.id} size={96} />
+```
+
+**HTML o cualquier otro framework** (Vue, Angular, plantillas de servidor):
+
+```ts
+import { avatarUrl } from "./lib/avatares";
+
+img.src = avatarUrl(cliente.id, 48);
+// o en una plantilla: <img src="${avatarUrl(id)}" width="48" height="48" alt="">
+```
+
+**Como fondo CSS**:
+
+```ts
+el.style.backgroundImage = `url("${avatarUrl(cliente.id)}")`;
+```
+
+
+
+### Paso 4: (opcional) servirlo desde el backend
+
+Si varias aplicaciones, o apps que no son JavaScript, deben mostrar el mismo avatar, expón una URL en tu servidor. Ejemplo con Express:
+
+```ts
+import express from "express";
+import { avatarSvg } from "./lib/avatares";
+
+const app = express();
+
+app.get("/avatar/:id.svg", (req, res) => {
+  res.type("image/svg+xml");
+  res.set("Cache-Control", "public, max-age=31536000, immutable"); // el avatar no cambia
+  res.send(avatarSvg(req.params.id, 256));
+});
+```
+
+Entonces cualquier cliente usa `<img src="https://tu-servidor/avatar/cliente-1042.svg">`. La cabecera de caché es segura porque el mismo id siempre devuelve el mismo SVG (mientras no cambie la versión del paquete; ver sección 4).
+
+### Paso 5: comprobar la integración
+
+- [ ] El mismo cliente muestra el mismo avatar en todas las pantallas y tras recargar.
+- [ ] Dos clientes distintos muestran avatares distintos.
+- [ ] Con paleta de marca: todos los avatares usan solo esos colores (más tinta oscura o blanca en la cara).
+- [ ] En TypeScript, `subject="cualquiercosa"` da error de compilación (los tipos llegan bien).
+- [ ] El `package.json` fija la versión exacta.
+- [ ] Si usas un endpoint: la respuesta tiene `Content-Type: image/svg+xml`.
+
+
+
+### Paso 6: política de actualización
+
+- Lee el [CHANGELOG](CHANGELOG.md) antes de subir de versión. Si la entrada dice que **altera avatares existentes**, tus clientes verán avatares nuevos. Decide si lo aceptas y, si procede, avísales.
+- Las versiones **menores y de parche** (`0.1.0` → `0.1.1`, `0.2.0`) no cambian ningún avatar existente; son seguras.
+- Las versiones **mayores** (`0.x` → `1.0`, `1.x` → `2.0`) pueden cambiar el dibujo.
+- Cada SVG lleva el atributo `data-idicon-design="N"` con la versión de diseño que lo generó. Sirve para comprobar, en un test o en soporte, con qué versión se dibujó un avatar.
+- Si necesitas que convivan dos diseños (por ejemplo, clientes antiguos conservan el suyo y los nuevos usan el nuevo), incluye la versión en el id: `generateAvatarSvg("v1:" + cliente.id)` con el paquete antiguo y `"v2:" + cliente.id` con el nuevo. Como el id forma parte de la semilla, cada prefijo da su propio avatar estable.
+
+---
+
+
+
+## 2. Referencia de la API
+
+```ts
+import { generateAvatarSvg, avatarDataUri, SUBJECTS, PATTERNS, PATTERN_CHOICES, PALETTES, DESIGN_VERSION } from "idicon";
+import type { AvatarOptions, Subject, Pattern, PatternChoice } from "idicon";
+import { Avatar, type AvatarProps } from "idicon/react";
+```
+
+
+
+### `generateAvatarSvg(id, options?) → string`
+
+Devuelve el avatar de `id` como documento SVG completo (texto). El id se recorta (espacios al principio y al final) y se normaliza (`NFC`), así que `"ana"` y `" ana "` dan el mismo avatar. Cualquier texto vale como id: nunca se escribe dentro del SVG.
+
+### `avatarDataUri(id, options?) → string`
+
+El mismo avatar como URL `data:image/svg+xml;charset=utf-8,...`, lista para `src` de una imagen o `background-image` en CSS.
+
+### Opciones (`AvatarOptions`)
+
+
+| Opción    | Valores                                                                         | Por defecto | Qué hace                                                                                                       |
+| --------- | ------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------- |
+| `subject` | `"random"`, `"person"`, `"character"`, `"object"`, `"shape"`, `"none"`          | `"random"`  | Qué se dibuja. `random` deja que el id elija entre todos; `none` dibuja solo el fondo.                         |
+| `pattern` | `"random"`, `"plain"`, `"rings"`, `"stripes"`, `"blobs"`, `"dots"`, `"horizon"` | `"random"`  | Patrón del fondo. `plain` es un color liso.                                                                    |
+| `palette` | 5 colores `#rrggbb`                                                             | automática  | Paleta manual. Si no se indica, o no es válida, el id elige una de las 12 paletas incluidas.                   |
+| `size`    | número                                                                          | `256`       | Ancho y alto en píxeles escritos en el `<svg>`. El dibujo escala por su `viewBox`, así que no cambia nada más. |
+
+
+- `"character"`: robot, gato, búho, fantasma o monstruo.
+- `"object"`: caja, nube, bombilla, cohete, maceta o taza.
+- `"shape"`: hexágono, triángulo, rombo, cuadrado, estrella, corazón, gota o píldora.
+
+
+
+### Constantes
+
+- `SUBJECTS`: valores válidos de `subject`. `PATTERN_CHOICES`: valores válidos de `pattern`. `PATTERNS`: solo los patrones dibujables. Útiles para construir selectores.
+- `PALETTES`: las 12 paletas incluidas (5 colores cada una), como punto de partida para una paleta manual.
+- `DESIGN_VERSION`: versión del dibujo. Es el valor que aparece en `data-idicon-design` de cada SVG.
+
+
+
+### `Avatar` (`idicon/react`)
+
+Props: `id` (obligatorio), `subject`, `pattern`, `palette`, `size`, `className`, `title`. Dibuja el SVG en línea dentro de un `<span>`. Requiere React 18 o superior.
+
+---
+
+
+
+## 3. Garantías del generador
+
+- **Determinista.** El mismo id con las mismas opciones produce siempre el mismo SVG, en cualquier máquina, navegador o versión de Node. No usa `Math.random()`.
+- **Las opciones no se mezclan.** Paleta, patrón, personaje y pose se deciden con secuencias independientes derivadas del id. Cambiar el patrón o los colores nunca cambia el personaje, la pose ni la cara, y viceversa.
+- **Máximo 6 colores.** Los 5 de la paleta más la tinta de la cara, que se elige oscura o blanca según el contraste con el color sobre el que se dibuja.
+- **Contraste.** Los colores de la paleta se reparten entre fondo, cuerpo, cara y acento comprobando que se distingan entre sí. Con una paleta manual, cada id reparte esos colores de forma distinta; si los 5 colores son muy parecidos, la cara puede perder contraste.
+- **Formato.** Cuadrado de esquinas rectas, `viewBox="0 0 120 120"`, unos 3-4 KB por avatar. El personaje queda recortado dentro del cuadrado aunque esté inclinado.
+- **Seguro.** El id nunca aparece en el SVG generado. Hay un test que lo comprueba.
+- **Rápido.** Generar un avatar cuesta microsegundos; se puede hacer en cada render sin cachear.
+
+---
+
+
+
+## 4. Estabilidad del diseño y versionado
+
+El avatar de un id es el resultado de un dibujo concreto. **Cualquier cambio en el dibujo (añadir un personaje, una paleta o un patrón, o reordenar decisiones aleatorias dentro de una capa) cambia los avatares de ids ya existentes.** Para un cliente que ya conoce su avatar, eso parece un error. El proyecto tiene tres mecanismos para que nunca ocurra por accidente:
+
+### Candado de diseño (test automático)
+
+`src/lib/design-lock.test.ts` genera 494 avatares (38 ids × 13 combinaciones de opciones), calcula una huella de cada uno y la compara con `src/lib/__snapshots__/design-lock.json`. **Si cualquier avatar cambia en lo más mínimo,** `npm test` **falla** y muestra qué ids y opciones se vieron afectados.
+
+Un cambio de dibujo solo puede entrar si alguien lo acepta a propósito:
+
+```bash
+# 1. Subir DESIGN_VERSION en src/lib/avatar.ts (1 → 2)
+# 2. Regenerar el candado
+npm run design:accept
+# 3. Anotarlo en CHANGELOG.md como cambio que altera avatares existentes
+# 4. Publicar como versión MAYOR
+```
+
+Si el test falla y **no** querías cambiar el dibujo, el cambio tiene un efecto secundario: revísalo antes de aceptarlo.
+
+### Versión de diseño
+
+`DESIGN_VERSION` (exportada y escrita en cada SVG como `data-idicon-design`) identifica el dibujo. Sube con cada cambio visual aceptado; las apps pueden usarla para saber con qué diseño se generó un avatar.
+
+### Integración continua
+
+`.github/workflows/ci.yml` ejecuta lint, tests (con el candado) y ambos builds en cada push y pull request. Un check rojo en GitHub significa que el cambio no es seguro para publicar.
+
+### Reglas de versión (semver)
+
+
+| Cambio                                            | Versión   | Ejemplo           |
+| ------------------------------------------------- | --------- | ----------------- |
+| Altera algún avatar existente                     | **Mayor** | `1.4.2` → `2.0.0` |
+| Opción nueva que por defecto no cambia nada       | Menor     | `1.4.2` → `1.5.0` |
+| Corrección sin efecto visual, documentación, demo | Parche    | `1.4.2` → `1.4.3` |
+
+
+Mientras la versión sea `0.x`, el dibujo todavía puede cambiar; **antes de usarlo con clientes reales, publica** `1.0.0` como compromiso de estabilidad.
+
+---
+
+
+
+## 5. Web de demostración
+
+```bash
+npm install
+npm run dev        # http://localhost:5173
+npm run build:demo # versión estática en dist-demo/
+```
+
+La demo permite escribir un id o generar uno aleatorio, elegir contenido, patrón y paleta (automática, predefinida, manual con selector de color y cuentagotas, o guardada con nombre), copiar la imagen al portapapeles como PNG, copiar el SVG, descargar en SVG o PNG, y guardar avatares en el navegador para volver a ellos.
+
+---
+
+
+
+## 6. Mantenimiento del paquete
+
+```bash
+npm run build          # compila la librería a dist/ (JS + .d.ts)
+npm test               # tests del generador y candado de diseño
+npm run lint           # oxlint
+npm run design:accept  # acepta un cambio de dibujo (ver sección 4)
+```
+
+Estructura:
+
+```
+src/
+  index.ts                 Entrada pública del paquete
+  react.tsx                Entrada idicon/react
+  lib/
+    avatar.ts              Composición del avatar: fondo, personajes, cara, pose
+    palettes.ts            Paletas, contraste y reparto de colores
+    random.ts              Generador aleatorio con semilla (sfc32 + xmur3)
+    avatar.test.ts         Tests de reglas (determinismo, colores, opciones...)
+    design-lock.test.ts    Candado de diseño
+    __snapshots__/         Huellas del candado
+  App.tsx, components/, lib/*.ts restantes   Solo para la demo
+scripts/fix-dts.mjs        Ajusta las rutas de import en los .d.ts tras compilar
+.github/workflows/ci.yml   Integración continua
+CHANGELOG.md               Historial de versiones
+```
+
+Solo lo exportado desde `src/index.ts` y `src/react.tsx` forma parte de la API pública. El resto es interno y puede cambiar.
+
+### Publicar una versión
+
+1. `npm test`, `npm run lint` y `npm run build` pasan (y el CI está en verde).
+2. Añade la entrada al `CHANGELOG.md`, indicando si altera avatares existentes.
+3. Sube la versión según la tabla de la sección 4. Esto actualiza `package.json` y crea la etiqueta Git `vX.Y.Z`:
+  ```bash
+   npm version patch   # o minor, o major
+   git push --follow-tags
+  ```
+4. Si se publica en un registro: `npm pack --dry-run` para revisar el contenido (solo `dist/`, `README.md` y `package.json`) y después `npm publish`. Para un registro privado con ámbito (por ejemplo `@empresa/idicon` en GitHub Packages), cambia `name` en `package.json` y configura `publishConfig.registry` antes.
+
+`npm publish` ejecuta `npm run build` automáticamente (`prepack`), así que `dist/` siempre se genera a partir del código actual. Las apps que instalan desde Git con `#vX.Y.Z` también compilan `dist/` al instalar.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { generateAvatarSvg, avatarDataUri, SUBJECTS, PATTERNS, PATTERN_CHOICES, DESIGN_VERSION, type AvatarOptions, type Subject, type Pattern, type PatternChoice, } from "./lib/avatar.js";
+export { PALETTES } from "./lib/palettes.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,QAAQ,EACR,QAAQ,EACR,eAAe,EACf,cAAc,EACd,KAAK,aAAa,EAClB,KAAK,OAAO,EACZ,KAAK,OAAO,EACZ,KAAK,aAAa,GACnB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+// Public entry of the npm package. Anything not re-exported here is internal
+// and may change without notice.
+export { generateAvatarSvg, avatarDataUri, SUBJECTS, PATTERNS, PATTERN_CHOICES, DESIGN_VERSION, } from "./lib/avatar.js";
+export { PALETTES } from "./lib/palettes.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,iCAAiC;AACjC,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,QAAQ,EACR,QAAQ,EACR,eAAe,EACf,cAAc,GAKf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/lib/avatar.d.ts

@@ -0,0 +1,35 @@
+export type Pattern = "rings" | "stripes" | "blobs" | "dots" | "horizon";
+export declare const PATTERNS: readonly Pattern[];
+/** "random" lets the id decide, "plain" is a flat color with no pattern. */
+export type PatternChoice = "random" | "plain" | Pattern;
+/** What the avatar shows: "random" lets the id decide, "none" is background only. */
+export type Subject = "random" | "person" | "character" | "object" | "shape" | "none";
+export declare const SUBJECTS: readonly Subject[];
+export declare const PATTERN_CHOICES: readonly PatternChoice[];
+export interface AvatarOptions {
+    subject?: Subject;
+    pattern?: PatternChoice;
+    /** Exactly 5 #rrggbb colors; anything else falls back to the automatic palette. */
+    palette?: readonly string[];
+    /**
+     * Pixel width and height written on the <svg> element (default 256). The
+     * drawing scales through its viewBox, so this never changes what is drawn.
+     */
+    size?: number;
+}
+/**
+ * Version of the drawing itself. Bump it (together with the package's major
+ * version) whenever any change makes an existing id render differently:
+ * a new character, palette or pattern, or a reordered rng call. The design
+ * lock test (design-lock.test.ts) fails on such a change until it is
+ * accepted on purpose.
+ */
+export declare const DESIGN_VERSION = 1;
+/** The avatar for `id`, as a standalone SVG document string. */
+export declare function generateAvatarSvg(id: string, options?: AvatarOptions): string;
+/**
+ * The same avatar as a `data:` URL, ready for an <img src> or a CSS
+ * background-image, for pages that cannot inline SVG markup.
+ */
+export declare function avatarDataUri(id: string, options?: AvatarOptions): string;
+//# sourceMappingURL=avatar.d.ts.map

package/dist/lib/avatar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"avatar.d.ts","sourceRoot":"","sources":["../../src/lib/avatar.ts"],"names":[],"mappings":"AA0MA,MAAM,MAAM,OAAO,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;AACzE,eAAO,MAAM,QAAQ,EAAE,SAAS,OAAO,EAAqD,CAAC;AAC7F,4EAA4E;AAC5E,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;AAiWzD,qFAAqF;AACrF,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;AACtF,eAAO,MAAM,QAAQ,EAAE,SAAS,OAAO,EAAiE,CAAC;AACzG,eAAO,MAAM,eAAe,EAAE,SAAS,aAAa,EAAqC,CAAC;AAS1F,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,mFAAmF;IACnF,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAID;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC,gEAAgE;AAChE,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM,CAoCjF;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM,CAE7E"}