Tonos y palette

El SDK admite dos formas de suministrar tonos a vto.start(): una lista plana (colors) y un selector de dos niveles (palette). Ambas pueden coexistir: palette monta el selector acordeón dentro del visor mientras que colors provee el tono que se aplica al arrancar.

---

colors — lista plana

colors: Color[] es la forma básica de definir la paleta. El primer elemento se aplica al iniciar el visor.

Campos de Color

Campo	Tipo	Obligatorio	Descripción
id	string	Sí	Identificador único del tono. Los ids con prefijo neon- activan un preset de color vívido en el motor.
name	string	Sí	Nombre visible del tono (p.ej. 'Cobrizo Rubí').
h	number	Sí	Matiz HSL, rango 0–360.
s	number	Sí	Saturación HSL, rango 0–100.
l	number	Sí	Luminosidad HSL, rango 0–100.
sku	string	No	SKU del producto (clave de favorito).
product	Product	No	Producto asociado (card del visor + favoritos). Prioridad más baja que products[id] y resolveProduct.
swatchImageUrl	string	No	URL de la imagen del swatch. Si se omite, el SDK renderiza un círculo HSL.

Ejemplo

const TONOS: Color[] = [
  { id: 'cobrizo',    name: 'Cobrizo Rubí', h: 358, s: 82, l: 46 },
  { id: 'cobre',      name: 'Cobre',         h: 18,  s: 90, l: 48 },
  { id: 'neon-verde', name: 'Neón Verde',    h: 110, s: 100, l: 50 },
]

await vto.start({ module: 'hair-color', colors: TONOS })

El id neon-verde activa el preset vívido del motor de renderizado.

---

palette — selector de 2 niveles

palette: ShadeGroup[] (campo de StartOptions) activa el selector de tonos tipo acordeón dentro del visor:

• Nivel 1 — familias: cada ShadeGroup aparece como un swatch con su nombre. Al pulsar, se despliega el nivel 2 y se aplica el último sub-tono elegido en esa familia (o el primero disponible la primera vez).
• Nivel 2 — sub-tonos: los Color[] de la familia. Al elegir uno se aplica el efecto de inmediato.

Si una familia no tiene sub-tonos (shades vacío o ausente y sin resolveShades), el SDK aplica su color principal directamente al pulsar.

Campos de ShadeGroup

Campo	Tipo	Obligatorio	Descripción
id	string	Sí	Identificador único de la familia.
name	string	Sí	Nombre visible de la familia (p.ej. 'AURA Color Gloss').
swatch	{ h, s, l }	No	Color raíz del swatch de nivel 1 (h 0–360, s/l 0–100). Si se omite, se usa el color del primer shade.
swatchImageUrl	string	No	Imagen raíz del swatch de nivel 1. Tiene prioridad visual sobre swatch cuando ambos están presentes.
shades	Color[]	No	Sub-tonos (nivel 2). Puede omitirse si se cargan por API con resolveShades.
product	Product	No	Producto del color principal (aplica cuando la familia no tiene sub-tonos).
sku	string	No	SKU del color principal (clave de favorito cuando la familia no tiene sub-tonos).

Ejemplo

await vto.start({
  module: 'hair-color',
  colors: TONOS,               // tono inicial
  palette: [
    {
      id: 'gloss',
      name: 'AURA Color Gloss',
      swatch: { h: 358, s: 82, l: 46 },
      shades: [
        { id: 'cobrizo', name: 'Cobrizo Rubí', h: 358, s: 82, l: 46 },
        { id: 'cobre',   name: 'Cobre',         h: 18,  s: 90, l: 48 },
      ],
    },
    {
      id: 'neon',
      name: 'AURA Neon',
      swatch: { h: 110, s: 100, l: 50 },
      shades: [
        { id: 'neon-verde',  name: 'Neón Verde',  h: 110, s: 100, l: 50 },
        { id: 'neon-fucsia', name: 'Neón Fucsia', h: 320, s: 100, l: 55 },
      ],
    },
  ],
  ui: { branding: { name: 'AURA' } },
})

---

resolveShades — carga de sub-tonos por API

Cuando shades no viene en el JSON (p.ej. un catálogo grande), se puede cargar por API de forma diferida:

resolveShades?: (group: ShadeGroup) => Color[] | Promise<Color[]>

El SDK llama resolveShades(group) la primera vez que el usuario expande una familia sin shades. El resultado se cachea para evitar llamadas repetidas.

Ejemplo

await vto.start({
  module: 'hair-color',
  colors: TONOS,
  palette: [
    { id: 'gloss',  name: 'AURA Color Gloss',  swatch: { h: 358, s: 82, l: 46 } },
    { id: 'matte',  name: 'AURA Color Matte',  swatch: { h: 25,  s: 70, l: 40 } },
  ],
  resolveShades: async (group) => {
    const res = await fetch(`/api/palette/${group.id}/shades`)
    return res.json()
  },
  ui: { branding: { name: 'AURA' } },
})

resolveShades se define en StartOptions junto a palette. Los campos colors y palette pueden coexistir: colors provee la lista plana que el SDK aplica al arrancar; palette monta el selector de 2 niveles para que el usuario navegue familias y sub-tonos.

Tabla exhaustiva de tipos en 10-referencia-de-tipos.md.