@neural-charts/native 0.0.0-stage → 0.1.0-beta.1

package/docs/guide.md

@@ -0,0 +1,783 @@
+# Primer alcance
+
+Neural Charts Native se dedica a teléfonos y tablets iOS y Android con Angular Native. El catálogo incluye gráficas cartesianas y radiales, distribuciones, jerarquías, intervalos, relaciones ponderadas y siluetas. El renderizador dibuja geometría propia mediante vistas SVG nativas y texto del sistema. Los ejemplos utilizan datos reproducibles y el componente real de la librería; la entrada data también acepta las medidas originales de una aplicación.
+
+# Explorar y seleccionar
+
+interactionChange notifica cambios de estado: comenzar/terminar exploración, cambiar dato/grupo, fijar o limpiar. Moverse dentro del mismo dato, insistir en un extremo o volver a limpiar una selección vacía no repite notificaciones. Las burbujas de tamaño cero conservan su observación para Anterior/Siguiente sin crear una zona táctil invisible. Los intervalos radiales rotados mantienen selección coherente al cruzar el inicio del círculo; los huecos siguen sin dato. Alcance y criterios de hardening en docs/seven-refinement.md.
+
+options.tooltip.content='shared' activa el tooltip compartido en líneas, columnas y barras. Cero y ausencia se distinguen. La leyenda interactiva actualiza la visibilidad y recalcula con el Core; hiddenSeriesIds permite enlazar ese estado a la aplicación. Las series ocultas siguen disponibles para restaurarlas. Un gauge no tiene leyenda de series.
+
+Arrastra dentro de la gráfica para explorar observaciones. En líneas y columnas se busca la posición horizontal más cercana; en barras, la vertical. Con varias series en la misma posición se usa la otra coordenada para desambiguar. Al soltar se fija la selección. Una cancelación restaura la selección anterior. El tooltip flotante se coloca junto al dato, evitando el dedo y los bordes. Repetir el toque sobre el mismo dato lo cierra; tocar otro cambia el detalle. El panel inferior es opcional.
+
+Detalles permite leer el texto completo en un panel nativo desplazable; Contraer vuelve a la posición automática. El detalle compacto reserva su altura antes de mostrarse; los nombres largos o listas extensas pasan al panel. Las listas compartidas mantienen el orden de las series y distinguen cero de ausencia. La expansión se conserva al navegar y se restablece al limpiar o reproducir la animación. Nombres largos en el showcase reutiliza los mismos datos. options.tooltip.pinnable=true añade Fijar/Desfijar: mantiene el dato visible, pausa exploración y háptica, y permite leer el panel. Una revisión de datos libera la fijación; limpiar y reproducir la cierran. Arrastrar, acciones y animación de tamaño siguen pendientes.
+
+En cajas, rangos de columnas, barras de error y columnas triangulares, el arrastre continuo sigue el grupo más cercano al cruzar espacios vacíos; no cierra y vuelve a abrir el tooltip entre figuras. El toque individual conserva la selección sobre la figura.
+
+El tooltip flotante cambia de posición con una transición breve, independiente del cálculo de datos. Su cierre utiliza la posición visible durante el movimiento. La colocación compara zonas de ocupación aproximada con un presupuesto fijo de muestras y prefiere cubrir menos datos sin tapar el punto seleccionado. Si no cabe, utiliza el panel de detalle; el contenido compartido de cajas permanece en ese panel.
+
+La estimación de ocupación se calcula cuando hace falta mostrar un tooltip flotante y se reutiliza al cambiar de dato dentro de la misma escena y vista. Desplazar la gráfica sin selección, desactivar el tooltip o usar el modo acoplado no ejecuta ese cálculo. Una transición hacia la misma posición conserva su animación en curso; desactivar las animaciones o solicitar un cambio inmediato sigue deteniéndola.
+
+# Límites de geometría nativa
+
+El adaptador limita los trazados serializados a 1.000.000 de caracteres por serie y 2.000.000 por escena. Si se supera uno de estos presupuestos, `planningError` devuelve el motivo `NATIVE_PATH_LIMIT` y la ruta de la serie o de la escena afectada. No se omiten observaciones ni se sustituyen los datos originales de forma silenciosa. Reduce la densidad del origen antes de volver a planificar.
+
+El coste depende de la forma de los datos y del número de series, además de su recuento. Las áreas spline apiladas necesitan muestras intermedias para mantener las fronteras comunes; una señal que alterna bruscamente puede alcanzar el presupuesto antes que otra suave con el mismo número de puntos. Estos límites protegen la conversión de geometría; no garantizan una tasa de fotogramas ni un consumo de memoria determinados en un dispositivo.
+
+# Arranque para desarrolladores
+
+El showcase web y la aplicación nativa son destinos independientes de este repositorio. Para trabajar aquí usa Node 22.22.3 o superior. Para instalar la beta en tu aplicación, usa `npm install @neural-charts/native@beta`. La guía que estás leyendo se genera desde docs/guide.md en cada build.
+
+```sh
+npm ci
+npm run showcase        # Documentación y ejemplos web
+npm run build:showcase  # Build del sitio
+npm run build:showcase:review # Build equivalente del showcase
+npm start               # Desarrollo nativo con Expo
+npm run verify          # Contratos, tipos y pruebas
+```
+
+# API de la beta
+
+Importa NativeDataChart en un componente Angular Native. data es obligatorio y options es opcional. interactionChange emite la observación explorada, la selección y el estado del arrastre. planningError informa de datos u opciones inválidas. El contenedor de la app necesita GestureRoot y la configuración de Metro de Angular Native. El ejemplo recibe los datos tipados desde su consumidor.
+
+options.axes configura ejes y rejilla; options.legend configura la leyenda. Su contenido conserva los nombres completos y ocupa como máximo 144 píxeles lógicos: si necesita más espacio se desplaza y muestra una indicación. Esto evita que muchas series desplacen toda la gráfica fuera de la pantalla. Una leyenda de solo lectura sigue señalando las series ocultas; el mensaje de estado solo indica cómo restaurarlas cuando esa acción está disponible. Ocultar la rejilla no elimina las etiquetas ni los datos. Las opciones del showcase utilizan estas mismas entradas.
+
+```ts
+import {Component, input} from '@angular/core';
+import {NativeDataChart, type NativeLineData, type NativeChartOptions}
+  from '@neural-charts/native';
+
+@Component({
+  selector: 'app-example-chart',
+  imports: [NativeDataChart],
+  template: `<neu-c-chart [data]="data()" [options]="options" />`,
+})
+export class ExampleChart {
+  readonly data = input.required<NativeLineData>();
+  readonly options = {
+    axes: {grid: true, x: {title: 'Día'}, y: {title: 'Visitas'}},
+    format: {unit: 'visitas'},
+    legend: {visible: true, position: 'bottom'},
+    tooltip: {content: 'shared', pinnable: true},
+    interaction: {haptics: true},
+  } as const satisfies NativeChartOptions<'line'>;
+}
+```
+
+# Showcase web y límites de la vista
+
+El sitio web es mobile first y utiliza el host oficial @ng-native/web para representar los mismos componentes. Su adaptador de Pointer Events permite explorar con ratón o dedo y usar el teclado. Las acciones y los detalles pasan por el mismo modelo de selección. La háptica está desactivada y señalizada en esta vista: un navegador no demuestra el comportamiento de los reconocedores nativos, VoiceOver/TalkBack ni la fluidez en hardware. Las capturas web son evidencia del sitio web, no del binario iOS o Android.
+
+Cada ejemplo puede verse en formato iOS o Android. La librería también admite tablets; el selector de la web no añade un tercer marco. El gráfico vive en un documento embebido con su propio ancho, de modo que la vista de teléfono no hereda el ancho de escritorio. Son previsualizaciones web, no simuladores del sistema operativo. El botón Reproducir animación reinicia la entrada del mismo componente, conservando su instancia. Movimiento reducido muestra directamente el estado final y cancela una animación en curso.
+
+# Orientación y espacio disponible
+
+En ventanas horizontales de hasta 500 puntos lógicos de alto se reducen los márgenes y separaciones del componente. Los datos, los objetivos táctiles y las acciones de selección no cambian. La altura del área de dibujo sigue controlada por `options.appearance.plotHeight`, acotada entre 180 y 600 puntos lógicos. Si la configuración completa no cabe, la app debe proporcionar desplazamiento; no se deben recortar los ejes para encajar el contenido.
+
+El tooltip flotante utiliza el espacio disponible alrededor del dato, también en áreas de dibujo bajas. Solo pasa al panel de detalles cuando su contenido no cabe sin recortar ni cubrir el punto seleccionado, o cuando la configuración de lectura lo requiere. Los textos ampliados y los detalles extensos conservan su presentación accesible en el panel.
+
+# Animación del componente nativo
+
+La entrada pertenece a NativeChart y comparte política y parámetros entre plataformas. En iOS y Android utiliza WorkletStyle y valores compartidos oficiales de Angular Native con Reanimated en el hilo de interfaz. La web utiliza BrowserChartMotion con AnimatedStyle en el navegador. Las líneas se revelan de izquierda a derecha; las columnas y barras crecen desde su origen proyectado. Circular y donut conservan su barrido; el gauge revela únicamente la lectura, con fondo, bandas y objetivo fijos. Polar, radar y sectores concéntricos como sunburst, variablepie, rueda y cuerdas crecen desde su centro real proyectado. Embudo, pirámide, treemap y organización se revelan verticalmente. Las comparativas, intervalos y diagramas de arcos se revelan horizontalmente sin escalar sus posiciones. Las nubes de burbujas, dispersión y burbujas empaquetadas crecen desde el centro de cada círculo hasta un máximo de 32; por encima utilizan un fundido agrupado. Las etiquetas esperan a la fase final cuando lo necesita cada familia. Los ejes y la rejilla permanecen fijos. Un único progreso controla las capas, sin recalcular datos ni ejecutar detección de cambios por cada frame en el controlador. El movimiento reducido termina la entrada inmediatamente.
+
+options.animation.enabled vale true por defecto. durationMs empieza en 1100 milisegundos y se limita al intervalo 0–2000. Incrementa revision para limpiar selección y tooltip y reproducir la entrada sin desmontar el componente. También se limpia con la animación desactivada o movimiento reducido. Los cambios de título, tema y color no la repiten. Una corrección de tamaño durante el arranque espera al layout estable; un cambio de tamaño durante la animación la termina. El ajuste de movimiento reducido del sistema siempre tiene prioridad.
+
+```html
+<neu-c-chart [data]="data()"
+  [options]="{animation: {enabled: true, durationMs: 1100, revision: animationRevision()}}" />
+```
+
+Al tocar o navegar por datos, la entrada termina antes de seleccionar para que el tooltip coincida con la posición definitiva. Un cambio de tamaño termina la transformación anterior. Al cambiar de geometría se sustituye la animación; al desmontar se cancela cualquier arranque pendiente y la ejecución de animación de la plataforma. Compartir componente, parámetros y política no demuestra fluidez ni comportamiento táctil en un dispositivo: las pruebas nativas y sus límites se registran por separado.
+
+Al ocultar o restaurar una serie desde la leyenda, o actualizar valores dentro del mismo tipo, la geometría anterior y la nueva se funden con una transición breve de hasta 220 ms. Los refrescos frecuentes no vuelven a iniciar la entrada de 1100 ms; cambiar de tipo o incrementar revision sí la reproduce. La selección válida se conserva; no se reinicia la animación de entrada por tener o no un tooltip activo. Se mantiene una sola geometría anterior y se libera al finalizar. animation.enabled: false, duración cero y movimiento reducido muestran el estado final directamente. No se recalculan datos por fotograma.
+
+# Identidad de los datos
+
+Cada observación tiene una identidad estable formada por seriesId y pointId. Las etiquetas, la posición visual y la referencia del objeto no sustituyen esa identidad. El dato explorado y el seleccionado son estados distintos: mover el dedo muestra una vista previa, soltar la confirma y cancelar recupera la anterior. Un cambio de datos conserva la selección si su identidad sigue existiendo en la misma familia; shared conserva su grupo semántico cuando sea posible. updateScenePresentation cambia metadatos y colores reutilizando geometría e índices. La preview no recalcula el Core por título, descripción o color.
+
+Cada coordenada compartida identifica un único grupo semántico; varias series pueden pertenecer al mismo grupo. Dos claves de grupo distintas en esa coordenada se rechazan para evitar que el tacto seleccione un grupo diferente del que muestra la navegación.
+
+# Configuración reutilizable
+
+NativeDataChart recibe data y options. NativeChartOptions agrupa axes, legend, tooltip, animation, interaction y appearance con interfaces readonly. Usa as const satisfies NativeChartOptions<'line'> para conservar literales y detectar incompatibilidades. Las familias sin ejes los rechazan; el tooltip compartido pertenece a líneas y columnas/barras. El gauge usa data.unit y no admite leyenda. Cada referencia documenta tipos, valores iniciales, restricciones y ejemplos.
+
+La entrada hiddenSeriesIds es un modelo opcional: la leyenda funciona por sí misma y también permite [(hiddenSeriesIds)] para guardar la visibilidad en la aplicación. Al cambiar los datos se eliminan identificadores que ya no existen. Ocultar la serie seleccionada limpia el detalle y notifica interactionChange; al cambiar las filas de un grupo compartido se notifica su contenido actualizado. Cambiar solo tooltip o leyenda no vuelve a planificar los datos. NativeChart y NativeScene quedan disponibles como API avanzada de escenas proyectadas.
+
+Los paths de escenas externas se validan una vez al adquirirlos: comandos completos, números finitos y flags de arcos. La geometría puede salir del plot para recortar dominios explícitos; parámetros y extremos se limitan en magnitud a 1024 veces la mayor dimensión de escena. El contenedor nativo recorta el dibujo. Esta validación no calcula el contorno completo de curvas o arcos. Los límites son de seguridad, no presupuestos de rendimiento de dispositivos.
+
+# Háptica
+
+El interruptor permite desactivar la respuesta. Se pide feedback solo cuando cambia la identidad del dato, nunca por cada evento del dedo, con al menos 45 ms entre peticiones. Se omite en simuladores, sin módulo, con ahorro de batería, fuera de primer plano o con movimiento reducido. Android utiliza el feedback de la vista que respeta los ajustes del sistema; iOS conserva las restricciones del sistema. Un módulo presente no demuestra que exista un actuador físico. Las respuestas requieren revisión en hardware real.
+
+# Accesibilidad
+
+La gráfica es un control nativo ajustable con etiqueta, valor y acciones anterior/siguiente. También ofrece botones de 48 puntos y texto nativo escalable. Con un lector de pantalla activo se evita competir con sus gestos. La navegación por datos usa las mismas identidades que el tacto. VoiceOver, TalkBack, contraste, tamaños de texto y lectura completa de datos necesitan revisión en dispositivos antes de certificar accesibilidad.
+
+# Datos y recursos
+
+Cada dato se identifica por serie y punto, nunca por etiqueta o índice visual. Las escenas se copian y congelan al entrar. Se valida finitud, identidad y límites: 10.000 observaciones, 16 series y límites de geometría. El índice se prepara una vez. Los movimientos se agrupan por frame, con búsqueda binaria por posición y resolución de coincidencias. Al desmontar se cancelan frames y se eliminan listeners y referencias. Este límite es defensivo, no una promesa de rendimiento para 10.000 puntos.
+
+Burbujas utiliza el tamaño medido del área de datos para planificar posiciones y radios en el Core. Mantiene círculos, ejes y selección alineados sin reservar las franjas vacías de un marco panorámico fijo. Solo un cambio real de dimensiones actualiza esa planificación; los movimientos del dedo y las mediciones repetidas no la vuelven a ejecutar. En la API avanzada de escenas, viewportChange comunica las dimensiones del área de datos; la fachada data/options lo gestiona automáticamente.
+
+# Cálculo compartido
+
+NativeDataChart convierte la definición de datos mediante la entrada pública @neural-charts/core/plan, sin DOM. planNativeChart está disponible en @neural-charts/native/plan para integraciones avanzadas. El cálculo permanece en el Core compartido; el adaptador se ocupa de presentación, selección y ejecución nativa.
+
+# Datos reales
+
+El paquete instala una versión fijada de @neural-charts/core desde npm. El Core público, con licencia MIT, valida los datos y calcula dominios, ticks y geometría sin APIs de navegador ni de Angular Native. La aplicación y el showcase usan la misma fachada NativeDataChart. Los contratos y la documentación del motor están en https://github.com/PedroMorenoTrujillo/neural-charts-core.
+
+Admite categorías, líneas con intervalos numéricos irregulares o fechas UTC, varias series, huecos null, ceros y negativos. Conserva identidades y transporta claves de grupo. La visibilidad recalcula dominios/sectores en el Core y conserva la leyenda al ocultarlo todo. Rechaza duplicados, valores no finitos y excesos de límites. Estas validaciones no certifican rendimiento en dispositivos.
+
+Los ejemplos copiados importan únicamente entradas públicas. data contiene valores e identidades; options contiene títulos, colores y presentación. Los cambios de presentación reutilizan la geometría y los índices de interacción.
+
+Mantén los objetos de negocio fuera de la entrada de la gráfica y recupéralos mediante los IDs de serie y punto del evento. Los campos datum, markers y dash por serie se rechazan; los marcadores se configuran mediante options.appearance.markers y el trazo discontinuo aún no está disponible. Títulos y rejilla de ejes pertenecen a options.axes; no se admiten ajustes de ancho de etiqueta en data. Las incompatibilidades producen un diagnóstico en lugar de aceptar opciones sin efecto.
+
+El buscador encuentra propiedades concretas como options.tooltip.pinnable e interfaces como NativeTooltipOptions. El resultado abre directamente la propiedad o el tipo, también al recargar o compartir su URL, sin fragmentos en la dirección.
+
+# Configurador y filtros
+
+Cada familia tiene un único conjunto de datos ilustrativos. Líneas y columnas comparan dos series de ese mismo conjunto; barras utiliza sus canales. No se alternan conjuntos de datos preparados para simular opciones. El configurador modifica título, subtítulo, colores, visibilidad y posición de la leyenda, ejes, títulos de ejes y rejilla. El filtro conserva una parte del origen: los últimos cuatro días o los dos primeros canales. Los identificadores de serie y punto se mantienen.
+
+En escritorio puedes ver las opciones junto al teléfono; en móvil aparecen debajo. La gráfica embebida, la tabla y el código se actualizan con el mismo estado de signals. Restablecer recupera las opciones y visibilidad iniciales. Replay limpia selección/tooltip y respeta movimiento reducido. Texto y color no repiten la entrada ni recalculan datos. Una actualización conserva una identidad seleccionada que siga existiendo; todavía no hay una entrada de selección controlada.
+
+# Pruebas y límites
+
+Las pruebas Node usan un Fabric simulado y comprueban contratos e interacción. La compilación y los bundles comprueban integración, no fluidez. Las capturas de simulador prueban representación en ese simulador. La háptica, latencia y calidad percibida se miden en dispositivos reales. Android necesita un SDK y runtime Java disponibles para validar el binario. El ledger registra evidencias y pendientes sin equipararlos a certificación.
+
+# Estado de las pruebas nativas
+
+La revisión actual ha probado la fachada data/options en Android API 36 y en un iPhone iOS 27: Siguiente, selección táctil, cambio de dato, cierre al repetir toque, replay y seis leyendas con ocultación total/restauración. Gauge no tiene leyenda. Líneas, columnas y barras tienen comprobación de tooltip compartido con dos series y fijación/cierre. Android añade un escenario de doce series con nombres largos, árabe, un nombre sin espacios, cero y ausencia: permite leer la última fila, desplazar el panel, fijar y cerrar. La matriz Android incluye tamaño de tablet mediante resolución y densidad ajustadas en el emulador propio, no hardware físico. Quedan la matriz avanzada de contenido en iOS/tablets, cancelación, texto grande, rotación, iPad, lectores, háptica física y rendimiento medido. Las capturas y los resultados se registran con su alcance; los formatos embebidos de la web son previsualizaciones de navegador.
+
+La campaña del 1 de noviembre verifica Árbol, Organización, Dependency Wheel, Arc Diagram y Chord en Android e iOS sobre la revisión 57e8142: cinco casos aprobados por plataforma. Comprueba dibujo nativo, selección táctil con identidad original, contenido y cierre del tooltip, replay y ocultación total/restauración de la leyenda sin errores de configuración. Esta comprobación focal no supone una nueva validación de los 48 tipos ni de sus 195 ejemplos. Los 41 tipos básicos, los intervalos y los comparativos tienen campañas anteriores separadas. Siguen pendientes la matriz completa de variantes, estrés, tablets, lectores y háptica física. El informe reproducible está en docs/native-verification.md.
+
+# Pruebas y limpieza de recursos
+
+npm test ejecuta pruebas finitas con un máximo de dos trabajadores. Cada caso desmonta sus aplicaciones. Cada ejecución elimina su carpeta temporal al terminar, fallar o interrumpirse normalmente; no guarda un archivo de capturas por ejecución. Los servidores y simuladores propios se cierran cuando terminan sus comprobaciones. Las pruebas Node y las regresiones de compilación de Metro para iOS y Android no sustituyen la aceptación nativa. Los resultados por revisión se registran en el ledger. Detalles y límites en docs/test-resources.md.
+
+# Catálogo y opciones actuales
+
+Los tipos disponibles se renderizan con NativeChart en la aplicación nativa y en el host web oficial. Pie y Donut usan sectores táctiles; Gauge conserva el valor exacto; Burbujas conserva X, Y y tamaño. Las etiquetas porcentuales utilizan contraste de texto automático y se limitan a sectores legibles. Las barras agrupadas reciben las posiciones de categoría del Core. Las líneas densas omiten marcadores decorativos sin descartar datos; las burbujas densas agrupan geometría por serie para limitar vistas nativas.
+
+El showcase utiliza Neural UI v2, inglés/español y temas claro/oscuro. Cada familia tiene demo, configurador y documentación propia. Solo ofrece marcos iOS/Android; la librería también admite tablets. El cambio de marco conserva la instancia y la selección. Una gráfica ancha permite desplazamiento horizontal y selección por toque.
+
+La preview utiliza NativeDataChart y la misma política de animación, con ejecución propia del navegador y respeto al movimiento reducido. El navegador no certifica el comportamiento de los reconocedores, el rendimiento ni la háptica de iOS/Android. La nueva fachada y los ajustes de detalle requieren una nueva aceptación nativa.
+
+# Zoom y exploración
+
+Activa `options.viewport` en líneas, columnas, barras o burbujas. Al omitirlo no aparecen controles ni reconocedores de zoom. Dentro del grupo, `axes` vale `'x'` por defecto y `pinch`, `pan` y `controls` valen `true`. Las opciones explícitas del ejemplo facilitan decidir qué interacción necesita tu aplicación.
+
+```ts
+import type {NativeChartOptions} from '@neural-charts/native';
+
+const options = {
+  viewport: {axes: 'x', pinch: true, pan: true, controls: true},
+} satisfies NativeChartOptions<'line'>;
+```
+
+El pellizco amplía la ventana de datos; el arrastre con dos dedos la desplaza. Un dedo sigue disponible para explorar puntos. Los controles permiten ampliar, reducir, desplazar y restablecer sin depender de un gesto. `(viewportChange)` entrega `{value, source}` cuando cambia la ventana aceptada, no en cada movimiento. La vista previa del gesto transforma la presentación y el Core calcula el resultado al terminar. Cancelar, cambiar los datos o desmontar no debe dejar una transformación pendiente.
+
+`x` e `y` identifican los ejes de los datos. En barras horizontales, el eje de categorías `x` se dibuja verticalmente. Las categorías se delimitan mediante IDs existentes; los ejes numéricos o temporales utilizan intervalos numéricos. Circular, donut y gauge no admiten `viewport`. Un tooltip fijado pausa la exploración hasta cerrarlo o desfijarlo.
+
+El desplazamiento de una gráfica ancha es independiente del zoom: `options.appearance.minPlotWidth` reserva anchura para el área de datos y las etiquetas X. Solo esa región se desplaza; título, eje Y, leyenda y controles conservan su posición. Usa `0` para adaptarla al ancho disponible.
+
+En árbol y organización, el viewport utiliza coordenadas de distribución normalizadas 0–1. Una zona ampliada puede no contener nodos aunque el origen sí los tenga. El mensaje distingue esa región vacía de una fuente sin datos o de todos los grupos ocultos. Ofrece alejar/restablecer o desplazar únicamente cuando esas acciones están activadas; restablecer conserva los nodos e IDs originales.
+
+# Variantes, referencias y estilos
+
+Columnas y barras admiten una serie, series agrupadas y `options.layout.stacking: 'sum' | 'percent'`. En porcentaje, cada categoría visible necesita valores conocidos y no negativos en todas las series visibles. Un valor ausente produce `INCOMPLETE_PERCENT_CATEGORY`; un cero real conserva su significado. El tooltip compartido muestra el valor original y su porcentaje cuando existe. Las líneas, circular, donut, gauge y burbujas no admiten apilado.
+
+`options.axes.x.referenceLines` y `options.axes.y.referenceLines` marcan valores sin ampliar el dominio. Cada referencia tiene `id`, `value` y, opcionalmente, `label`, `color`, `width` y `dash`. Se admiten hasta 16 IDs únicos entre ambos ejes. Columnas y barras utilizan el eje de valores `y`; sus referencias cambian de orientación junto a la gráfica. En un eje X categórico, `value` es el ID de una categoría. Una referencia fuera de la ventana no se dibuja.
+
+`options.appearance.points` configura hasta 256 colores mediante `{seriesId, pointId, color}` en los tipos cartesianos. Los IDs deben existir en los datos. El cambio afecta al punto y su detalle, sin cambiar el valor, el color de la línea ni su leyenda. Circular y donut utilizan `appearance.series` para sus sectores; gauge utiliza la serie `reading`.
+
+Configura títulos con `appearance.title`, `appearance.subtitle` y `axes.x.titleStyle` o `axes.y.titleStyle`. Estos grupos ofrecen alineación, color, tamaño y peso. Las líneas admiten marcadores circulares, cuadrados, rombos y triángulos, con relleno y borde propios, dentro de `appearance.markers`. Los cambios de presentación reutilizan el cálculo de datos. Las interfaces y la referencia de propiedades muestran los límites de cada opción.
+
+La leyenda admite `top`, `bottom`, `left` y `right`. Las posiciones laterales requieren al menos 640 píxeles lógicos de ancho del componente; por debajo, izquierda pasa arriba y derecha pasa abajo, conservando visibilidad y selección de series.
+
+# Áreas, líneas suaves y dispersión
+
+`NativeAreaData`, `NativeSplineData` y `NativeScatterData` utilizan `type: 'area'`, `'spline'` y `'scatter'`. Cada tipo tiene su demo, configurador y referencia individual.
+
+Áreas rellena hasta cero con transparencia y dibuja el contorno aparte. Las series se superponen sin apilarse. Por defecto el eje Y incluye cero; un dominio explícito puede recortar el relleno. `includeZero: false` es incompatible. Los huecos se conservan por defecto; `series.gaps: 'connect'` permite unirlos de forma explícita.
+
+Spline utiliza interpolación monótona del Core entre observaciones ordenadas. Las muestras de la curva no son datos ni objetivos táctiles: el tooltip y la tabla conservan los valores originales. No admite configurar otra curva mediante `series.curve`. Comparte marcadores, tooltip compartido, referencias, leyendas y ventana de datos con líneas.
+
+Dispersión representa pares X/Y independientes, sin conectarlos ni asignarles tamaño Z. Admite pares ausentes con null, ceros, negativos, ejes numéricos, referencias, colores por punto, leyendas y ventana en ambos ejes. Sus marcadores son circulares del mismo tamaño. El tooltip es individual; las opciones de línea, los marcadores de línea y el detalle compartido se rechazan.
+
+Los nuevos tipos continúan en estado experimental hasta completar su aceptación nativa. Las pruebas del navegador o de compilación no certifican los gestos de iOS/Android ni el rendimiento en dispositivos.
+
+# Ejemplos con datos y enlaces propios
+
+La galería reúne los casos de uso de los tipos implementados. Cada tarjeta abre una URL como `/charts/line/time` o `/charts/areaspline/percent`; el código de datos y opciones corresponde al caso seleccionado. No modifica otra gráfica fuera de la vista. Los ejemplos de una misma familia reutilizan una única instancia del componente nativo y sus controles de presentación mantienen el mismo origen de datos. Los filtros conservan IDs y valores de las observaciones supervivientes.
+
+Los casos incluyen huecos, UTC, intervalos irregulares, signos, series coincidentes, nombres largos, datos densos, dominios recortados, apilados, ceros/ausentes, bandas y lecturas fuera del rango. La señal densa es sintética y su código usa un generador tipado; no es una medición de rendimiento del dispositivo. Las etiquetas largas se acotan visualmente y conservan el texto accesible completo.
+
+Waterfall, radar, área polar y Pareto utilizan cálculo propio en la entrada pública del Core. Pareto deriva el acumulado sobre el origen completo y utiliza un eje porcentual independiente; las combinaciones genéricas con múltiples ejes siguen pendientes. La baseline distingue implementación, verificación web y aceptación nativa.
+
+# Áreas apiladas
+
+Utiliza `NativeAreaData` o `NativeAreaSplineData` y configura `options.layout.stacking` como `sum` o `percent`. La suma separa aportaciones positivas y negativas; el porcentaje rechaza valores negativos. Una fila incompleta interrumpe todas las bandas y no se rellena con ceros. Los porcentajes utilizan solo las series visibles. Un total cero no tiene porcentaje definido.
+
+```typescript
+import type {NativeChartOptions} from '@neural-charts/native';
+
+const options = {
+  layout: {stacking: 'sum', stackLabels: true},
+  tooltip: {content: 'shared'},
+} as const satisfies NativeChartOptions<'area'>;
+```
+
+El apilado es incompatible con `series.curve`, `gaps: 'connect'` y `axes.y.includeZero: false`. El tooltip mantiene el valor original de cada aportación. Ocultar una serie recalcula la pila mediante el Core.
+
+# Series mixtas
+
+`NativeMixedData` combina series `type: 'column'`, `'line'` y `'area'` sobre un único marco de categorías y una escala Y compartida. Cada serie mantiene ID, nombre y puntos propios. No superpone componentes ni calcula una escala diferente para cada capa. Los rellenos se pintan bajo las columnas y las líneas quedan encima.
+
+```typescript
+import type {NativeMixedData, NativeChartOptions} from '@neural-charts/native';
+
+const data = {
+  type: 'mixed',
+  axes: {
+    x: {type: 'category', values: [{id: 'mon'}, {id: 'tue'}]},
+    y: {type: 'linear'},
+  },
+  series: [
+    {id: 'actual', name: 'Actual', type: 'column', data: [
+      {id: 'mon', x: 'mon', y: 29}, {id: 'tue', x: 'tue', y: 35},
+    ]},
+    {id: 'target', name: 'Target', type: 'line', data: [
+      {id: 'mon', x: 'mon', y: 30}, {id: 'tue', x: 'tue', y: 30},
+    ]},
+  ],
+} as const satisfies NativeMixedData;
+const options = {tooltip: {content: 'shared'}} as const satisfies NativeChartOptions<'mixed'>;
+```
+
+El tooltip compartido y la selección se agrupan por ID de categoría, conservando los centros de las columnas agrupadas. Leyenda, referencias y zoom utilizan el mismo marco. Esta versión admite X categórico y una Y numérica; no admite unidades incompatibles sobre esa misma escala, apilado mixto, eje secundario ni Pareto. Las series `column` rechazan `curve` y `gaps`.
+
+# Treemap
+
+`NativeTreemapData` contiene `root`. Cada nodo tiene un ID globalmente único y una etiqueta opcional. Una hoja contiene `value: number | null`; una rama contiene `children`, nunca ambos. El Core calcula la distribución y los subtotales conocidos. Un descendiente ausente marca su subtotal como incompleto. Los ceros conservan navegación sin inventar área.
+
+```typescript
+import type {NativeTreemapData} from '@neural-charts/native';
+
+const data = {
+  type: 'treemap',
+  root: {id: 'portfolio', label: 'Portfolio', children: [
+    {id: 'software', label: 'Software', children: [
+      {id: 'apps', label: 'Applications', value: 42},
+      {id: 'cloud', label: 'Cloud', value: 28},
+    ]},
+    {id: 'services', label: 'Services', value: 22},
+  ]},
+} as const satisfies NativeTreemapData;
+```
+
+El toque selecciona el bloque pintado más profundo y repetirlo cierra el tooltip. Anterior/Siguiente permite consultar ceros y nodos sin espacio. Las etiquetas se acotan dentro de cada bloque; el detalle conserva el nombre completo. Los colores de grupo se configuran mediante IDs en `options.appearance.series`. No se exponen ejes, zoom cartesiano, tooltip compartido, leyenda de visibilidad, navegación a subárboles ni escala de color cuantitativa en esta versión.
+
+Límites de seguridad: 512 nodos, profundidad 16, raíz y hasta 15 grupos, etiquetas de 200 caracteres y hasta 64 etiquetas visuales. Se rechazan negativos, sumas desbordadas, ciclos, nodos repetidos y propiedades incompatibles. Estos límites no certifican rendimiento físico.
+
+# Etiquetas de valores y totales
+
+`options.appearance.dataLabels` activa etiquetas de valores originales en gráficas cartesianas. En líneas y curvas solo etiqueta observaciones reales: un cruce geométrico o una muestra interpolada no añade datos. En burbujas utiliza el tamaño original. Está desactivada por defecto en cartesianas; las etiquetas de sectores y jerarquía están activadas por defecto.
+
+`options.layout.stackLabels` requiere `stacking`. En suma muestra por separado totales positivos y negativos; en porcentaje muestra 100 % solo cuando el total está definido. Los valores proceden del cálculo del Core, sin volver a sumar en el componente. Se omiten filas incompletas y extremos fuera del dominio. Ambas opciones son independientes del tooltip.
+
+La presentación limita las etiquetas a 64, evita solapamientos y omite las que no caben o quedan fuera de la ventana. Los valores de puntos se colocan por encima del marcador, dejando espacio libre; si no hay sitio, se omite la etiqueta en vez de cubrir el punto. En burbujas se respeta el radio dibujado. Las etiquetas interiores de celdas, sectores y jerarquías conservan su colocación propia. Por encima de 64 observaciones no se crean etiquetas por punto. Los valores exactos continúan disponibles mediante tooltip y navegación accesible. El escalado de texto del sistema sigue habilitado.
+
+# Nuevas familias de datos
+
+Waterfall utiliza un flujo ordenado de incrementos, subtotales de tramo y total acumulado. Admite valores con signo y conserva el prefijo al ampliar una ventana; no admite cambios desconocidos ni apilado. Radar compara perfiles no negativos en 3–32 ejes radiales; los valores ausentes interrumpen el contorno y eliminan el relleno. Área polar mantiene iguales los ángulos y permite radio lineal o superficie proporcional.
+
+Pareto admite hasta 64 categorías completas no negativas, ordena de forma estable y calcula el porcentaje acumulado en una escala Y independiente. La leyenda y el zoom X no modifican el denominador. El origen todo a cero conserva los ceros seleccionables y omite la curva porcentual.
+
+Los cuatro incluyen ejemplos independientes y contratos data/options. Las comprobaciones locales de cálculo, componente y navegador se distinguen de la aceptación física en iOS y Android, todavía pendiente para estas familias.
+
+# Embudo y pirámide
+
+`NativeFunnelData` y `NativePyramidData` reciben `type: 'funnel'` o `type: 'pyramid'` y un array `data` de 1–16 etapas `{id, label, value}`. Los IDs son únicos y estables; los valores son finitos y no negativos. Se rechaza `null`: todas las etapas deben tener un valor conocido. El orden original nunca se ordena por magnitud.
+
+La **altura de cada fila** es proporcional a su valor dentro del total visible; el área del polígono no es proporcional. Los porcentajes son participaciones en la suma de etapas visibles. No representan conversión, retención ni porcentaje respecto a la primera etapa. Ocultar una etapa mediante la leyenda redistribuye las alturas y el denominador de las restantes. Cero conserva identidad, tabla y navegación Anterior/Siguiente sin dibujar un polígono ni crear una zona táctil invisible. Si todo es cero, no se inventan porcentajes ni volumen.
+
+La forma pertenece a `options.layout`, nunca a los datos:
+
+```ts
+import type {NativeFunnelData, NativeChartOptions} from '@neural-charts/native';
+
+const data = {
+  type: 'funnel',
+  data: [
+    {id: 'awareness', label: 'Conocimiento', value: 480},
+    {id: 'interest', label: 'Interés', value: 300},
+    {id: 'evaluation', label: 'Evaluación', value: 160},
+    {id: 'purchase', label: 'Compra', value: 60},
+  ],
+} as const satisfies NativeFunnelData;
+
+const options = {
+  layout: {neckWidth: 0.3, neckHeight: 0.25, reversed: false},
+  legend: {position: 'bottom', interactive: true},
+  tooltip: {content: 'point', pinnable: true},
+  appearance: {dataLabels: true, series: [{id: 'awareness', color: '#2C6DCD'}]},
+} as const satisfies NativeChartOptions<'funnel'>;
+```
+
+Embudo admite `neckWidth` y `neckHeight` entre 0 y 1, con valores iniciales 0.3 y 0.25; `reversed` empieza en `false`. Pirámide solo admite `reversed`, inicialmente `true`: el vértice aparece arriba y la silueta se ensancha hacia abajo. Cambiar la dirección no reordena las etapas. Cambiar la forma recalcula geometría; colores y nombres mediante `appearance.series` conservan geometría e identidades. Las etiquetas que no caben en una etapa estrecha se omiten para conservar legibilidad: el valor no se descarta y continúa disponible mediante toque, tooltip, Anterior/Siguiente y tabla.
+
+Ambas familias admiten títulos, tema, locale, colores por ID de etapa, leyenda, etiquetas, detalle individual, fijación y una entrada por opacidad acotada. Se rechazan ejes, viewport, apilado y totales apilados, tooltip compartido, marcadores, crosshair y cambios de apariencia por punto. La pirámide rechaza las opciones de cuello. La web muestra cuatro ejemplos de embudo y tres de pirámide, con datos y opciones copiables sobre el mismo componente nativo. La aceptación física en iOS y Android sigue pendiente; la previsualización web no la sustituye.
+
+# Área suave, bandas y columnas de intervalo
+
+`NativeAreaSplineData` utiliza `type: 'areaspline'` y el mismo origen ordenado id/x/y de una línea. Sin apilado, la interpolación monótona es fija y el relleno termina en cero. Null interrumpe el trazado y el área. Admite marcadores, detalle compartido, leyenda, referencias y viewport; rechaza `series.curve`. Las muestras geométricas de la curva no se convierten en observaciones nuevas.
+
+Para área spline apilada utiliza `options.layout.stacking: 'sum'`; para apilado al 100 %, utiliza `'percent'`. Opcionalmente, `stackLabels: true` muestra los totales visibles. Las capas utilizan curvas suaves compartidas, con tangentes horizontales en los puntos originales, para mantener bordes coincidentes y evitar que una capa invada otra. Esta interpolación conservadora es distinta de la curva monótona sin apilar. Los huecos rompen todas las capas y el porcentaje rechaza valores negativos. El tooltip compartido conserva los valores originales y añade el porcentaje cuando está definido.
+
+```typescript
+import type {NativeChartOptions} from '@neural-charts/native';
+
+const options = {
+  layout: {stacking: 'percent', stackLabels: true},
+  tooltip: {content: 'shared'},
+  legend: {interactive: true},
+} as const satisfies NativeChartOptions<'areaspline'>;
+```
+
+`NativeAreaRangeData`, `NativeAreaSplineRangeData` y `NativeColumnRangeData` utilizan `arearange`, `areasplinerange` y `columnrange`. Cada serie requiere `id`, `name` y puntos `{id, x, low, high}`. X puede ser categoría, número o tiempo UTC. Los extremos deben ser finitos y cumplir `low <= high`; una ausencia requiere `low: null` y `high: null`. Se rechaza una pareja incompleta. Las bandas y columnas flotan entre extremos originales; no se infiere un punto medio ni un margen de incertidumbre.
+
+```ts
+import type {NativeAreaRangeData, NativeChartOptions} from '@neural-charts/native';
+
+const data = {
+  type: 'arearange',
+  axes: {x: {type: 'linear'}, y: {type: 'linear'}},
+  series: [{id: 'temperature', name: 'Temperatura', data: [
+    {id: 'morning', x: 8, low: 12, high: 22},
+    {id: 'midday', x: 12, low: 18, high: 29},
+    {id: 'evening', x: 18, low: 15, high: 24},
+  ]}],
+} as const satisfies NativeAreaRangeData;
+const options = {tooltip: {content: 'shared'}} as const satisfies NativeChartOptions<'arearange'>;
+```
+
+El detalle individual y compartido, la tabla y la navegación conservan ambos extremos. Las curvas de `areasplinerange` son fijas; no crean puntos semánticos intermedios. Las tres familias admiten ejes, referencias, colores, etiquetas, leyenda y viewport. No admiten apilado, marcadores, curve/gaps por serie ni colores por punto.
+
+# Histogramas y densidad normal
+
+`NativeHistogramData` recibe `type: 'histogram'`, `samples: readonly number[]` y `binCount` opcional. Admite hasta 10.000 medidas finitas, con negativos y sin null. El Core calcula las frecuencias: no se entregan columnas preparadas. `binCount` es entero entre 1 y 64; omitido utiliza `ceil(log2(n)) + 1`, limitado a 64. Cada intervalo incluye su extremo izquierdo; solo el último incluye el derecho. Las muestras constantes producen un único intervalo. La altura es el recuento y el tooltip conserva los límites numéricos. Una partición explícita que no se pueda representar por precisión numérica genera diagnóstico.
+
+`NativeBellcurveData` recibe `type: 'bellcurve'` y las muestras originales. Calcula media y desviación típica **muestral**, con denominador `n−1`, y genera densidad normal en torno a la media. `intervals` es entero entre 16 y 256, inicialmente 64, y produce `intervals + 1` puntos derivados. `standardDeviations` está entre 1 y 6, inicialmente 3, a cada lado de la media. La curva representa densidad, no frecuencias ni observaciones originales; un ajuste no demuestra que el origen sea normal.
+
+Con menos de dos muestras o varianza cero conserva el recuento y la media reales, sin inventar una curva ajustada. El origen vacío conserva un resumen de cero muestras. Los cálculos no representables generan diagnóstico explícito. La leyenda oculta la serie derivada `distribution` sin cambiar el resumen del origen completo.
+
+```ts
+import type {NativeHistogramData, NativeBellcurveData} from '@neural-charts/native';
+
+const samples = [12, 15, 18, 20, 21, 22, 24, 25, 25, 26, 28, 30, 32, 35];
+const histogram = {type: 'histogram', samples, binCount: 6} as const satisfies NativeHistogramData;
+const density = {type: 'bellcurve', samples, intervals: 64, standardDeviations: 3} as const satisfies NativeBellcurveData;
+```
+
+Ambas familias admiten títulos, ejes, cuadrícula, colores por ID `distribution`, etiquetas, leyenda y detalle individual con fijación. No admiten viewport, referencias, tooltip compartido, marcadores, colores por punto ni apilado. El resumen de la web y su tabla distinguen recuentos y densidad derivados de las muestras originales.
+
+# Áreas centradas
+
+`NativeStreamgraphData` utiliza `type: 'streamgraph'`, ejes ordenados y series con `id`, `name` y puntos id/x/y. Y debe ser no negativo o null. La distribución centrada es fija: los desplazamientos se utilizan exclusivamente para geometría; tooltip, etiquetas, tabla y navegación conservan los valores originales. Una aportación ausente interrumpe toda la fila, sin convertirla en cero.
+
+Admite detalle individual o compartido, leyenda, colores, etiquetas, referencias y viewport. Rechaza layout stacking, curve/gaps por serie, grosor de línea, marcadores y colores por punto. Los tres ejemplos muestran composición básica, fila incompleta y totales desiguales. La aceptación física de estas siete familias en iOS y Android continúa pendiente y se registra por separado de las verificaciones de cálculo y navegador.
+
+# Cajas, bigotes y barras de error
+
+`NativeBoxplotData` recibe `type: 'boxplot'`, ejes y series con `id`, `name` y puntos `{id, x, minimum, q1, median, q3, maximum}`. Los cinco números son resúmenes suministrados por la aplicación, no muestras originales: la gráfica no calcula cuartiles ni infiere valores atípicos. Deben ser finitos y cumplir `minimum <= q1 <= median <= q3 <= maximum`, o ser todos null para un hueco completo. El tooltip, la navegación accesible y la tabla conservan los cinco valores. El detalle compartido utiliza espacio separado cuando necesita presentar varias series.
+
+`NativeErrorbarData` recibe `type: 'errorbar'` y puntos `{id, x, low, high}`. Entrega los límites que ya define tu origen; no se calculan error estándar, confianza ni incertidumbre desde muestras. Ambos extremos deben ser finitos con `low <= high`, o ambos null. Los extremos coincidentes siguen siendo datos semánticos, aunque la altura sea cero.
+
+```ts
+import type {NativeBoxplotData, NativeChartOptions} from '@neural-charts/native';
+
+const data = {
+  type: 'boxplot',
+  axes: {x: {type: 'category', values: [{id: 'a', label: 'Grupo A'}, {id: 'b', label: 'Grupo B'}]}, y: {type: 'linear'}},
+  series: [{id: 'summary', name: 'Resumen de medidas', data: [
+    {id: 'a', x: 'a', minimum: 8, q1: 12, median: 17, q3: 22, maximum: 28},
+    {id: 'b', x: 'b', minimum: 10, q1: 14, median: 19, q3: 24, maximum: 30},
+  ]}],
+} as const satisfies NativeBoxplotData;
+const options = {layout: {whiskerWidth: 0.5}, tooltip: {content: 'shared'}} as const satisfies NativeChartOptions<'boxplot'>;
+```
+
+Las dimensiones del glifo pertenecen a `options.layout`: `whiskerWidth` en cajas está entre 0 y 1, inicialmente 0.5; `capWidth` en barras de error está entre 0 y 1, inicialmente 1. Son fracciones del ancho de su cuerpo, no valores de los datos. Los datos nativos rechazan esos campos. `groupGap`, `barGap` y `maxBarWidth` siguen siendo geometría del origen, como en columnas.
+
+# Tallos, parejas y columnas triangulares
+
+`NativeLollipopData` utiliza `type: 'lollipop'` y puntos id/x/y. Un tallo desde cero y un extremo representan el valor original, con signo. Cero conserva el extremo y navegación; null es ausencia. `NativeDumbbellData` utiliza `type: 'dumbbell'` y parejas id/x/low/high, finitas y ordenadas o ambas null. La línea une los extremos originales; no añade un punto medio. Una pareja coincidente conserva ambos valores.
+
+El radio de los círculos de extremo se configura mediante `options.layout.markerRadius`, entre 1 y 16 puntos lógicos, inicialmente 4. Es una dimensión del glifo; no utiliza `appearance.markers`. Cambiarla recalcula la forma y conserva métricas e identidades.
+
+`NativeColumnPyramidData` utiliza `type: 'columnpyramid'` y puntos id/x/y. La altura triangular desde cero representa el valor; el área del triángulo no es proporcional. Los negativos apuntan bajo cero. El cero conserva semántica sin inventar un área pintada. No dispone de grupo `layout`.
+
+Las cinco familias utilizan series con nombre e IDs estables y admiten X categórico, numérico o temporal UTC. Incluyen ejes, leyenda, colores, etiquetas acotadas, detalle individual o compartido, referencias y viewport. Los dominios de tallos y columnas triangulares deben conservar el origen cero. Se rechazan apilado, curve/gaps por serie, controles de marcadores de línea y colores por punto. Cada familia tiene tres ejemplos reales y código data/options copiable; la aceptación física en iOS y Android sigue pendiente.
+
+En histogramas, el eje X presenta límites numéricos de intervalos sobre los bordes reales de las columnas, con un máximo de ocho marcas y menos en vistas estrechas. El tooltip conserva el intervalo exacto completo. El nombre de la serie calculada se configura con `options.appearance.series: [{id: 'distribution', name: 'Frecuencia'}]`; así coinciden la leyenda y el tooltip sin modificar las muestras. Las marcas usan cuatro cifras significativas y recuperan el texto completo si el redondeo produjera etiquetas ambiguas.
+
+# Sectores de radio variable
+
+`NativeVariablePieData` utiliza `type: 'variablepie'` y filas `{id, label, value, z}`. Son dos medidas independientes, finitas y no negativas: `value` determina el ángulo y `z` el radio. Admite hasta 16 filas completas, sin null. El dominio opcional `zDomain` es una pareja no negativa creciente que debe contener todas las Z; omitido se calcula con las filas visibles. Una leyenda puede cambiar esa normalización si no se fija el dominio.
+
+`options.layout.minRadiusRatio` está entre 0 y 1, inicialmente 0.25. `options.layout.radiusScale` es `'area'` o `'radius'`, inicialmente `'area'`. Con `'area'` se interpola **el radio al cuadrado**: `r² = rMin² + Znormalizada × (rMax² − rMin²)`. El área del sector también depende del ángulo independiente; por tanto **no representa Z por sí sola**. `'radius'` interpola directamente el radio entre esos límites. Son opciones de distribución y se rechazan en los datos nativos.
+
+```ts
+import type {NativeVariablePieData, NativeChartOptions} from '@neural-charts/native';
+
+const data = {
+  type: 'variablepie', zDomain: [0, 100],
+  data: [
+    {id: 'organic', label: 'Orgánico', value: 44, z: 25},
+    {id: 'direct', label: 'Directo', value: 28, z: 70},
+    {id: 'referral', label: 'Referidos', value: 18, z: 45},
+  ],
+} as const satisfies NativeVariablePieData;
+const options = {layout: {minRadiusRatio: 0.25, radiusScale: 'area'}} as const satisfies NativeChartOptions<'variablepie'>;
+```
+
+El tooltip conserva value, porcentaje angular y Z originales. Un valor angular cero conserva navegación y Z sin dibujar ni crear un sector táctil invisible. Colores y leyenda utilizan IDs de categoría. Admite etiquetas, detalle individual y fijación; no expone ejes cartesianos, viewport, tooltip compartido, colores por punto ni controles de marcadores.
+
+# Gráficas por unidades
+
+`NativeItemData` utiliza `type: 'item'` y categorías `{id, label, value}`. Los valores son enteros seguros no negativos, con máximo 16 categorías y suma máxima **256 en el origen completo**, incluidas categorías ocultas. Cada círculo pintado representa exactamente una unidad: no se escalan ni redondean los valores para decidir el número de círculos.
+
+```ts
+import type {NativeItemData, NativeChartOptions} from '@neural-charts/native';
+
+const data = {type: 'item', data: [
+  {id: 'completed', label: 'Completadas', value: 12},
+  {id: 'pending', label: 'Pendientes', value: 8},
+  {id: 'blocked', label: 'Bloqueadas', value: 0},
+]} as const satisfies NativeItemData;
+const options = {layout: {columns: 4}} as const satisfies NativeChartOptions<'item'>;
+```
+
+`options.layout.columns` es entero entre 1 y 32; omítelo para distribución automática según el área disponible. Cambiar columnas redistribuye las mismas unidades, sin cambiar su recuento. La interacción utiliza los círculos exactos; los huecos entre ellos no seleccionan una categoría. Hay una observación semántica por categoría, no una por círculo. Cero conserva Anterior/Siguiente sin dibujar unidades ficticias.
+
+Colores y leyenda utilizan IDs de categoría. Admite etiquetas, detalle individual por categoría y fijación. No admite ejes cartesianos, viewport, tooltip compartido, cambios por punto ni controles de marcadores.
+
+# Polígonos de vértices originales
+
+`NativePolygonData` utiliza `type: 'polygon'`, X numérico o temporal UTC, Y numérico y series con `id`, `name` y vértices `{id, x, y}`. Cada serie no vacía requiere al menos tres vértices únicos y completos. Se conserva el orden original y el cierre se genera automáticamente: no ordenes por X ni repitas el primer vértice al final. Admite contornos cóncavos simples. Rechaza null, coordenadas repetidas, área cero y autointersecciones.
+
+```ts
+import type {NativePolygonData} from '@neural-charts/native';
+
+const data = {
+  type: 'polygon',
+  axes: {x: {type: 'linear'}, y: {type: 'linear'}},
+  series: [{id: 'region', name: 'Región factible', data: [
+    {id: 'v0', x: 0, y: 0}, {id: 'v1', x: 6, y: 0},
+    {id: 'v2', x: 6, y: 4}, {id: 'v3', x: 3, y: 2},
+    {id: 'v4', x: 0, y: 4},
+  ]}],
+} as const satisfies NativePolygonData;
+```
+
+Los puntos de vértice son fijos y conservan X/Y originales; los cruces geométricos y el interior pintado no crean observaciones nuevas. Admite colores por serie, ejes, leyenda, etiquetas, detalle individual, fijación, crosshair, referencias y viewport. No admite tooltip compartido, controles de marcadores de línea, colores por punto, apilado ni opciones curve/gaps.
+
+Las tres familias tienen tres ejemplos independientes con datos completos y opciones copiables. Sus valores ilustrativos se entregan al mismo planificador y componente nativo de la biblioteca; no utilizan geometría de demostración superpuesta. Las comprobaciones de cálculo y navegador se registran por separado de la aceptación física en iOS y Android, todavía pendiente.
+
+# Jerarquías en anillos
+
+`NativeSunburstData` recibe `type: 'sunburst'` y `root`, con la misma unión estricta `NativeTreemapNode`: una hoja tiene `value: number | null`; una rama tiene `children`, nunca ambos. Los IDs son globalmente únicos. El límite es 512 nodos, profundidad 8 y 15 ramas de raíz más un centro neutro. Las etiquetas solo se dibujan si su caja completa cabe dentro del anillo y de su sector angular; en caso contrario se omiten y el tooltip conserva el nombre completo.
+
+```ts
+import type {NativeSunburstData} from '@neural-charts/native';
+
+const data = {type: 'sunburst', root: {
+  id: 'portfolio', label: 'Cartera', children: [
+    {id: 'software', label: 'Software', children: [
+      {id: 'apps', label: 'Aplicaciones', value: 20},
+      {id: 'cloud', label: 'Nube', value: 12},
+    ]},
+    {id: 'services', label: 'Servicios', children: [
+      {id: 'support', label: 'Soporte', value: 8},
+      {id: 'consulting', label: 'Consultoría', value: null},
+    ]},
+  ],
+}} as const satisfies NativeSunburstData;
+```
+
+El Core calcula los subtotales **conocidos** de padres y raíz a partir de hojas originales. Null conserva el estado incompleto; no se transforma en una contribución conocida ni en un total completo. Cero y ausencia mantienen significados distintos. Los anillos y sus objetivos táctiles corresponden a la jerarquía exacta; no se inventa un porcentaje arbitrario para presentar el total desconocido.
+
+Colores y leyenda utilizan IDs de ramas de raíz, por ejemplo `software` o `services`, mediante `options.appearance.series`. Ocultar una rama elimina su contribución visible y recalcula los valores de padres/raíz y la distribución. El centro conserva un color neutro. Admite nombres, detalle individual, fijación y una tabla que distingue hojas, subtotales calculados e incompletos. No expone ejes, viewport, referencias, crosshair, tooltip compartido, controles de marcadores ni colores por punto.
+
+# Árboles y organizaciones dirigidas
+
+`NativeTreegraphData` y `NativeOrganizationData` reciben nodos `{id, label, groupId?}`, enlaces `{id, from, to}` y grupos opcionales `{id, label}`. No contienen campos numéricos `value`, X o Y: las relaciones son los datos originales. Admite hasta 128 nodos, 512 enlaces y 15 grupos en total, incluyendo el grupo implícito `nodes` cuando falta `groupId`.
+
+```ts
+import type {NativeTreegraphData, NativeOrganizationData, NativeChartOptions} from '@neural-charts/native';
+
+const tree = {
+  type: 'treegraph',
+  groups: [{id: 'planning', label: 'Planificación'}, {id: 'delivery', label: 'Entrega'}],
+  nodes: [
+    {id: 'product', label: 'Producto', groupId: 'planning'},
+    {id: 'design', label: 'Diseño', groupId: 'planning'},
+    {id: 'engineering', label: 'Ingeniería', groupId: 'delivery'},
+  ],
+  links: [
+    {id: 'product-design', from: 'product', to: 'design'},
+    {id: 'product-engineering', from: 'product', to: 'engineering'},
+  ],
+} as const satisfies NativeTreegraphData;
+
+const organization = {...tree, type: 'organization', links: [
+  ...tree.links,
+  {id: 'design-engineering', from: 'design', to: 'engineering'},
+]} as const satisfies NativeOrganizationData;
+
+const options = {
+  appearance: {dataLabels: true, series: [
+    {id: 'planning', color: '#2C6DCD'},
+    {id: 'delivery', color: '#638A35'},
+    {id: 'links', color: '#8392A6'},
+  ]},
+  viewport: {axes: 'xy', initial: {x: [0.1, 0.9], y: [0, 1]}, controls: true},
+} as const satisfies NativeChartOptions<'organization'>;
+```
+
+Ambos grafos deben ser acíclicos, con IDs estables únicos y extremos existentes. Se rechazan autoenlaces, enlaces duplicados y referencias inexistentes. Treegraph admite como máximo un padre por nodo y puede representar un bosque de varias raíces. Organization admite varios padres sin introducir ciclos.
+
+Los colores y la leyenda utilizan grupos de nodos. `links` está reservado al estilo de conectores; no es un grupo de nodos, una entrada independiente de leyenda ni un ID válido para ocultar por separado. Su estilo sigue siendo válido si no hay enlaces visibles o están ocultos todos los grupos; la leyenda permanece disponible para restaurarlos con los IDs y colores originales. Ocultar un grupo elimina sus nodos y enlaces incidentes y redistribuye el grafo. El detalle calcula conexiones entrantes/salientes, su grado y profundidad después de aplicar visibilidad. Esas métricas se presentan como **calculadas**, nunca como valores numéricos originales.
+
+La web muestra tablas de nodos, enlaces y grupos originales, separadas de las métricas calculadas. `options.appearance.dataLabels` controla los nombres dibujados y empieza activada; ocultar nombres no elimina etiquetas originales del tooltip ni de las tablas. Admite detalle individual y fijación.
+
+El viewport es opcional y utiliza dimensiones de distribución normalizadas entre **0 y 1**, con `axes: 'x' | 'y' | 'xy'`; el valor inicial de axes es `xy`. No son ejes ni métricas numéricas del origen. Las ventanas son parejas numéricas finitas crecientes; se rechazan ventanas por categoría. No se exponen ejes, referencias, crosshair, tooltip compartido, controles de marcadores ni colores por punto.
+
+Los tres ejemplos de cada familia utilizan datos originales completos y el componente nativo real. Estas verificaciones de implementación, cálculo y navegador no sustituyen la aceptación física pendiente en iOS y Android.
+
+# Redes sin dirección
+
+NativeNetworkgraphData recibe type: 'networkgraph', nodes con id, label y groupId opcional, links con id, from y to y groups opcional con id y label. No contiene valores numéricos de nodos ni pesos inventados. Admite ciclos y componentes desconectados; rechaza autoenlaces, extremos inexistentes y parejas duplicadas sin dirección. Hasta 128 nodos, 512 enlaces y 15 grupos contando el implícito nodes. links es un ID reservado al estilo del conector, no un grupo de leyenda.
+
+La distribución estática es determinista y limita el trabajo por pares; no ejecuta simulaciones continuas ni temporizadores. Ocultar un grupo elimina sus nodos y enlaces incidentes antes de recalcular el grado visible. El tooltip muestra ese recuento y el nombre original, sin atribuir dirección ni profundidad. Las tablas separan los nodos y enlaces originales de los recuentos calculados. Los nombres dibujados se limitan a 64 y se omiten si no caben.
+
+Configura colores con options.appearance.series por ID de grupo y el conector mediante el ID links. El zoom utiliza options.viewport sobre coordenadas de distribución normalizadas entre 0 y 1; estas posiciones no son datos originales. Sin ejes numéricos, tooltip compartido ni apilado.
+
+# Burbujas empaquetadas
+
+NativePackedBubbleData recibe type: 'packedbubble' y series con id, name y data. Cada punto utiliza id, label opcional y value: number | null. Admite hasta 16 series y 256 puntos en total. Los valores deben ser finitos y no negativos. null se omite; cero sigue accesible con Anterior/Siguiente sin crear un círculo ficticio.
+
+El área es proporcional al valor original con una escala común para todas las series. options.layout.splitSeries separa las series en grupos mediante una única escala final: una misma área representa el mismo valor aunque cambie de grupo. No se renormaliza cada serie por separado. La distribución evita solapamientos y tiene un presupuesto acotado; no garantiza la solución de área mínima. La posición y la distancia no codifican medidas originales.
+
+options.appearance.dataLabels muestra nombres originales cuando caben, hasta 64 etiquetas. Colores, nombres de serie, leyenda interactiva y tooltip individual fijable conservan IDs originales. No admite radio arbitrario, ejes de datos, cruceta, tooltip compartido ni apilado.
+
+options.viewport admite únicamente axes: 'xy', con escala uniforme para conservar círculos y proporciones. Las ventanas iniciales deben proporcionar x e y como parejas finitas crecientes entre 0 y 1, con la misma amplitud y al menos 0,125. El zoom máximo es 8×. El Core limita los gestos y controles al mínimo permitido; el recorte y la selección utilizan la misma área visible. splitSeries pertenece a options.layout y se rechaza en data.
+
+# Vectores
+
+NativeVectorData utiliza type: 'vector', ejes numéricos X/Y y series de puntos con id, x, y, dx y dy. X/Y localizan la observación; dx/dy son componentes vectoriales independientes, con una unidad común opcional en data.unit. El tooltip distingue posición, componentes y magnitud calculada con Math.hypot. El límite es 16 series y 2.048 puntos en total.
+
+Las dos componentes deben ser finitas o ambas null. Una coordenada nula o una pareja de componentes nulas omite el símbolo; un vector cero sigue siendo seleccionable como un anillo pequeño. El origen copiable y la tabla conservan los datos ausentes. No se interpolan observaciones ni se crean medidas sintéticas.
+
+La longitud usa una escala de magnitud común entre las series visibles. Las flechas respetan la orientación cartesiana y la inversión de ejes, pero sus ángulos no se deforman por diferencias entre las amplitudes X/Y. No representan extremos de desplazamiento proyectados. El cálculo reutiliza la validación, dominios, proyección y ventanas numéricas existentes.
+
+Admite zoom y desplazamiento X/Y, referencias, títulos de ejes, colores de serie, leyenda interactiva, selección y tooltip fijable. Sin ejes categóricos/temporales, apilado, tooltip compartido, colores por punto ni options.format; la unidad pertenece a data.unit. Los símbolos mantienen un tamaño lógico acotado al ampliar la ventana.
+
+# Barbas de viento
+
+NativeWindbarbData utiliza type: 'windbarb', ejes numéricos y series de puntos {id, x, value, direction}. value es la velocidad original en m/s entre 0 y 150; direction indica de dónde viene el viento, en grados horarios desde el norte y en [0, 360). 0° es norte y 90° este. La brújula no gira al invertir los ejes de datos. El límite total es 2.048 puntos entre 16 series.
+
+La posición Y conserva la velocidad en m/s. El símbolo redondea a cinco nudos: media barba representa 5, una completa 10 y una bandera rellena 50. Un anillo indica una velocidad que redondea a cero nudos. El tooltip siempre conserva la velocidad y dirección originales, sin sustituirlas por la velocidad redondeada del símbolo.
+
+value: null omite la observación; direction: null mantiene una velocidad conocida con un rombo de dirección desconocida. Un cero sigue siendo un dato. La tabla del origen incluye valores ausentes y no desaparece al ocultar una serie. El render no dibuja líneas que conecten observaciones independientes.
+
+Admite zoom y desplazamiento numéricos, referencias, colores de serie, títulos, etiquetas, leyenda interactiva y tooltip fijable. Sin apilado, tooltip compartido, colores por punto, ejes categóricos/temporales ni options.format. La unidad m/s es fija y no se puede cambiar sin convertir los datos antes de entregarlos.
+
+
+## Sankey: cantidades entre etapas
+
+NativeSankeyData describe nodos con id, label y groupId opcional, y enlaces con id, from, to y value no negativo o null. Los IDs de nodos y enlaces son únicos en el diagrama. Admite hasta 128 nodos, 512 enlaces y un grafo acíclico. Los enlaces paralelos utilizan IDs diferentes. El grosor conserva una escala común y los nodos muestran el mayor total conocido de entradas o salidas. Cero sigue siendo cero; los enlaces null no inventan flujos y sus nodos permanecen marcados como incompletos.
+
+La orientación, el grosor y la separación pertenecen a options.layout. La leyenda por grupos retira enlaces incidentes y recalcula la escala visible. Los tooltips distinguen cantidades de entradas/salidas y flujos originales. La exploración XY utiliza coordenadas normalizadas de distribución, sin presentarlas como medidas X/Y.
+
+```typescript
+import type {NativeSankeyData, NativeChartOptions} from '@neural-charts/native';
+
+const data = {
+  type: 'sankey',
+  nodes: [{id: 'source', label: 'Origen'}, {id: 'target', label: 'Destino'}],
+  links: [{id: 'transfer', from: 'source', to: 'target', value: 48}],
+} satisfies NativeSankeyData;
+
+const options = {
+  title: 'Flujos entre etapas',
+  layout: {orientation: 'horizontal', nodeWidth: 14, nodePadding: 12},
+  tooltip: {mode: 'floating', pinnable: true},
+  viewport: {axes: 'xy'},
+} satisfies NativeChartOptions<'sankey'>;
+```
+
+Sankey no admite ejes cartesianos, tooltip compartido, apilado, referencias ni colores por enlace; utiliza appearance.series para los grupos. Los polígonos por debajo de la precisión de dibujo pueden omitirse sin ensancharlos ni convertir el valor en cero: la identidad y el valor siguen disponibles en las observaciones con sankey.geometryOmitted y en los datos originales. La navegación accesible permite inspeccionarlos aunque no exista una banda táctil representable. La compilación y las pruebas de navegador no sustituyen las pruebas en dispositivos iOS y Android.
+
+
+# Objetivos y anchos proporcionales
+
+Bullet compara medidas con objetivos opcionales en una misma escala. Cada punto contiene id, x e y; target es independiente: omitirlo significa que no se ha configurado, null significa desconocido y 0 sigue siendo un objetivo conocido. Si falta la medida pero existe un objetivo conocido, el detalle anuncia Objetivo y explica que la medida es desconocida. Las bandas cualitativas pertenecen a options.layout.bands: no son series, no aparecen en la leyenda y no amplían el dominio numérico.
+
+Bullet admite disposición horizontal o vertical, varias series, detalle individual o compartido, fijación y referencias. pointPadding controla la separación entre categorías. No admite viewport ni apilado. Mantén pocas categorías visibles en un teléfono; los límites de entrada no garantizan legibilidad en una única vista.
+
+Variwide utiliza una serie con puntos {id, x, y, z}. La altura representa y y el ancho representa la proporción original de z. Un z conocido reserva su ancho aunque y sea null. Un z de cero no recibe ancho inventado; los valores positivos inferiores a la precisión geométrica mantienen su identidad y un marcador independiente para selección. Si todos los anchos son cero o desconocidos, el reparto queda vacío de forma explícita.
+
+Variwide admite zoom y desplazamiento sobre Y numérico, con controles y gestos opcionales. Se rechazan zoom X ponderado, varias series y apilado. Los valores originales, incluidos null y cero, siguen en la tabla de datos; no se reconstruyen desde la geometría visible.
+
+# Ejes semánticos en columnas, barras y Bullet
+
+En NativeDataChart, options.axes.x e y describen los mismos ejes de datos que data.axes. X conserva las categorías e Y las medidas. En orientación horizontal, X se representa a la izquierda e Y debajo de la gráfica. El adaptador intercambia la posición física de títulos, visibilidad y estilos, sin cambiar los datos.
+
+Por ejemplo, options.axes.x.title configura el título de categorías también en una barra horizontal. options.axes.y.visible controla el eje de medidas, situado abajo en esa orientación. Las referencias numéricas de columnas y barras utilizan Y; sus referencias X categóricas todavía no están disponibles y se rechazan. Bullet admite referencias X categóricas e Y numéricas.
+
+El adaptador avanzado NativeChart conserva sus propiedades físicas para escenas ya proyectadas. Los ejemplos públicos utilizan data y options con los contratos semánticos anteriores.
+
+# Relaciones ponderadas: rueda, arcos y cuerdas
+
+DependencyWheel, ArcDiagram y Chord utilizan nodos originales {id, label, groupId?}, enlaces {id, from, to, value} y grupos opcionales. value es un número finito no negativo o null. Los IDs de nodo y enlace son únicos entre sí y no cambian con el idioma, la visibilidad o la distribución. Se rechazan autorrelaciones y extremos inexistentes.
+
+DependencyWheel representa relaciones dirigidas, incluidos ciclos. Chord y ArcDiagram representan relaciones no dirigidas: el orden de extremos no inventa una dirección. ArcDiagram conserva el orden original de los nodos; el radio de sus círculos es una opción visual. Los pesos de enlaces determinan el grosor de los arcos o bandas.
+
+Los totales de nodo son cantidades incidentes conocidas, no valores originales ni recuentos de conexiones. Un enlace null permanece en la tabla original y marca sus extremos como incompletos; nunca fabrica una observación cero. El cero conocido y los valores positivos bajo la precisión del dibujo conservan su identidad y detalle accesible, aunque no tengan área visible.
+
+Las bandas se dibujan primero y los sectores o círculos opacos después. Seleccionar un nodo tiene prioridad sobre una banda; un toque dentro del anillo puede seleccionar la banda real. Tocar otra vez cierra el tooltip. El detalle fijado conserva nombres completos de nodo, ambos extremos del enlace y el estado de datos incompletos.
+
+Utiliza NativeDependencyWheelData, NativeArcDiagramData o NativeChordData junto con NativeChartOptions del mismo tipo. En las dos familias radiales, options.layout ofrece startAngle de −360 a 360 grados, nodePadding de 0 a 20 grados y nodeWidth de 2 a 64 píxeles lógicos. ArcDiagram ofrece reversed, nodeRadius de 2 a 24 y linkWidth de 1 a 48. Sus valores se limitan al espacio disponible sin modificar las cantidades originales.
+
+Los tres tipos admiten hasta 64 nodos,256 enlaces y15 grupos explícitos más el grupo implícito nodes. Los nombres de nodo y grupo conservan hasta 256 caracteres; la etiqueta completa de un enlace conserva ambos extremos. La interfaz puede abreviar la etiqueta visual y el tooltip fijado permite leerla completa. Estos límites no garantizan legibilidad con todos los elementos en una pantalla pequeña.
+
+No admiten ejes, referencias, apilado, zoom de viewport ni tooltip compartido. ArcDiagram puede configurar appearance.minPlotWidth para desplazar solo la gráfica; títulos, leyenda y navegación mantienen el ancho del dispositivo. Ocultar/restaurar grupos recalcula la geometría y los totales conocidos visibles, manteniendo las identidades originales.
+
+# Pictorial: capacidad y siluetas
+
+Pictorial utiliza NativeDataChart con NativePictorialData y NativeChartOptions<'pictorial'>. Cada punto conserva su ID, categoría x y medida y no negativa. null significa desconocido; cero permanece conocido sin generar tinta ni una zona táctil inventada. La altura rellena representa el valor: el área y el volumen físico de la silueta no son medidas equivalentes.
+
+data.axes.x contiene hasta 32 categorías con IDs y nombres. Las series conservan IDs, nombres y hasta 64 puntos originales en total, con un máximo de ocho series. Una capacidad original puede definirse con data.axes.y.domain: [0, máximo], cuyo máximo debe ser finito y positivo. Los títulos y colores pertenecen a options. NativePictorialPoint, NativePictorialSeries, NativePictorialAxesData, NativePictorialShape, NativePictorialMesh y NativePictorialVertex describen los contratos públicos de forma explícita.
+
+options.layout.shape acepta los presets person, bottle y heart o una malla normalizada. NativePictorialMesh contiene id, aspectRatio, vertices y triangles. La relación de aspecto va de 0,1 a 10; la malla utiliza de 3 a 192 vértices en [0,1] y hasta 64 triángulos conformes. Los huecos de la malla permanecen vacíos. No se acepta SVG/XML arbitrario. La separación options.layout.gap va de 0 a 64 unidades lógicas y se limita a la mitad del espacio de cada silueta cuando sea necesario. options.layout.background controla el fondo neutro completo.
+
+Sin stacking, cada serie dispone de una silueta. sum divide una silueta compartida en bandas de valores originales. percent utiliza la parte conocida de cada categoría; el tooltip indica los totales incompletos, sin presentarlos como una población completa. percent es incompatible con data.axes.y.domain. La capacidad se conserva al ocultar o restaurar series, sin cambiar las identidades originales.
+
+Se admiten etiquetas y título del eje X categórico, colores por serie, leyenda, tooltip individual/fijable y appearance.minPlotWidth para desplazar únicamente la gráfica. No se admiten eje Y visible, cuadrícula numérica, referencias, zoom/pellizco, tooltip compartido, etiquetas de valor o total sobre la silueta ni colores por punto. Los controles y la API rechazan estas combinaciones en vez de ignorarlas.
+
+El fondo permanece estático y el relleno se revela desde su base proyectada sin deformar la silueta. El índice táctil solo selecciona los polígonos realmente rellenos: huecos y zonas vacías no interceptan toques. Anterior y Siguiente permiten consultar también ceros y valores positivos sin tinta visible. Cambiar solo títulos, colores o contenido del tooltip reutiliza la geometría; cambiar forma, separación, fondo o apilado vuelve a planificarla.
+
+La tabla del origen utiliza Neural Table y conserva los puntos originales aunque sean null, cero, estén ocultos o no tengan relleno visible. Muestra la medida original separada del total visible conocido que devuelve el Core y marca los totales incompletos. Ocultar toda la leyenda no elimina esas filas de consulta. Su desplazamiento queda contenido en la tabla.
+
+Los ejemplos son agrupado, capacidad fija, suma, porcentaje, valores incompletos, corazón, malla con hueco y cero, en español e inglés. Cada propiedad de malla muestra un ejemplo tipado completo para evitar configuraciones parciales incompatibles. Se aplican límites nativos de trazados y escenas; una malla válida que excede el presupuesto de dibujo se rechaza, sin simplificar datos ni retirar elementos silenciosamente. Estos límites no son mediciones de FPS ni garantías de legibilidad móvil.
+
+Las comprobaciones de Node/Fabric, de compilación y del navegador se registran por separado de la aceptación de Pictorial en iOS y Android, todavía pendiente. Los resultados de relaciones ponderadas de la revisión 57e8142 no certifican esta nueva familia, tablets, lectores, háptica física ni rendimiento medido.
+
+## Tilemap
+
+Tilemap representa medidas en posiciones enteras de una cuadrícula: `x` e `y` identifican la celda y `value` es la medida. No representa un mapa geográfico. Admite hexágonos, círculos, rombos y cuadrados mediante `options.layout.tileShape`, sin cambiar los datos originales. La única serie conserva IDs estables y permite ocultar/restaurar el conjunto desde su leyenda.
+
+La escala se configura en `options.colorAxis.scale`: continua con entre dos y ocho paradas, o por clases con hasta dieciséis intervalos. Los valores fuera de un dominio continuo explícito conservan su medida y muestran el extremo de color; el tooltip indica ese ajuste. Los huecos entre clases conservan su color y estado independientes. `null` se pinta con el color de ausencia y no genera una observación numérica; cero sigue siendo un valor seleccionable. `options.colorAxis.visible` controla solamente la leyenda de color, sin recalcular la escena.
+
+La selección utiliza el contorno exacto de cada celda: tocar un hueco o una medida ausente no elige una celda vecina. Las teclas de navegación y el tooltip fijable conservan el ID y las coordenadas originales. El adaptador renderiza las geometrías y colores devueltos por el Core; no calcula polígonos, distribuciones ni colores en la vista.
+
+El límite es de 2.048 celdas y los lotes de pintura agrupan únicamente colores y opacidades exactamente iguales, sin reducir precisión. En el peor caso hay 2.048 lotes y el serializador rechaza escenas que superan dos millones de caracteres de rutas. Son límites de seguridad, no garantías de fluidez. Los ocho ejemplos incluyen formas, escalas por clases, ausencia completa, ceros y dominio explícito. No hay ejes, viewport, apilado, colores por serie ni tooltip compartido en Tilemap. Consulta [el contrato completo](./tilemap.md).
+
+# Curvas de nivel de un campo medido
+
+NativeContourData recibe una rejilla rectangular de coordenadas X/Y numéricas crecientes y medidas originales por filas. grid.ids conserva un ID único por muestra; grid.values mantiene null como desconocido y cero como conocido. Una rejilla admite de 2 a 64 coordenadas por eje, hasta 4.096 muestras originales.
+
+NativeChartOptions<'contour'> exige options.layout.levels: de uno a ocho niveles finitos estrictamente crecientes, cada uno con un ID estable. Los nombres y colores pertenecen a appearance.series y utilizan esos IDs. Cambiar la presentación conserva la geometría y el índice de interacción. Las curvas utilizan marching squares con decisión bilineal en puntos de silla; no se suavizan ni se sustituyen por bandas rellenas.
+
+El tooltip señala que una isolínea es interpolada y distingue su nivel de las cuatro medidas originales de la celda. Se puede fijar para leer IDs largos; la tabla paginada del showcase conserva todas las muestras, aunque no exista ningún cruce o una muestra sea desconocida. Anterior/Siguiente recorre segmentos derivados. Una celda afectada por null no genera líneas ficticias.
+
+El presupuesto de cálculo completo es de 4.096 segmentos, ampliable hasta 8.192. Se aplica antes del recorte: si se supera, se devuelve un diagnóstico sin geometría parcial. El zoom, pellizco, desplazamiento y las referencias utilizan las coordenadas numéricas X/Y; no representan intensidad ni una proyección geográfica. No se admiten apilado, marcadores, cursor cruzado ni tooltip compartido.
+
+Las demos incluyen un campo medido, muestras ausentes, una rejilla no uniforme, un punto de silla, zoom XY y un campo uniforme sin cruces. La animación revela líneas y respeta la reducción de movimiento. Las pruebas de componentes y de procesamiento son independientes de la validación registrada en iOS y Android.
+
+# Intervalos de ejecución y distribuciones
+
+Flame recibe `NativeFlameData`: un eje `axes.x` lineal o `time` y una lista de intervalos originales con `id`, `label`, `start`, `end` y `parentId` opcional. Representa una traza síncrona de un hilo en tiempo original. Los hijos deben estar contenidos en su padre; los hermanos con duración positiva no pueden solaparse. Se rechazan ciclos y padres inexistentes. Los eventos de duración cero siguen disponibles por toque y navegación. El límite es de 2.048 intervalos y 32 niveles de profundidad.
+
+`NativeChartOptions<'flame'>` configura la separación mediante `layout.rowPadding`, el zoom y pellizco X mediante `viewport.axes:'x'`, y referencias temporales mediante `axes.x.referenceLines`. Los nombres de funciones se muestran solo cuando caben. El tooltip distingue duración inclusiva y exclusiva, profundidad y llamadas hijas. Sin leyenda de visibilidad, apilado, tooltip compartido ni zoom Y. No sustituye una traza concurrente o un flamegraph agregado.
+
+Violín recibe `NativeViolinData` con grupos de muestras originales: cada grupo tiene `id`, `label` y `samples`; cada muestra conserva `id` y `value:number|null`. Cero y valores negativos son conocidos; `null` es desconocido. Se admiten hasta 16 grupos y 4.096 muestras en total. Un grupo sin medidas conocidas conserva su lugar y leyenda sin inventar un resumen. Las muestras constantes se dibujan como una línea sin dispersión, salvo suavizado explícito.
+
+`NativeChartOptions<'violin'>` separa la estimación de la medida. `layout.bandwidth` es un ancho positivo en unidades originales; omitirlo utiliza una estimación robusta. `layout.resolution` admite enteros de 32 a 128. `layout.normalization` permite `width` para igual ancho máximo, `area` para igual área de probabilidad y `count` para ponderar el área por el número de muestras conocidas. La leyenda oculta grupos sin alterar escalas ni normalización de los demás. Un dominio Y explícito debe contener todo el soporte del kernel. No se admiten viewport numérico, referencias, apilado ni tooltip compartido.
+
+La silueta y sus cuartiles son cálculos derivados. El tooltip identifica la mediana, el rango, la media, los recuentos conocidos y desconocidos y el ancho de banda. La tabla del showcase conserva las muestras originales y muestra hasta 64 filas por página. Las pruebas de cálculo, componentes y navegador no certifican todavía rendimiento, accesibilidad ni respuesta háptica en dispositivos; la app de pruebas y la campaña nativa se realizan después del cierre del catálogo.
+
+# Conjuntos, intersecciones y Euler
+
+Los ejemplos de Euler utilizan `NativeVennData`: el caso de inclusión contiene un conjunto completo dentro de otro y el caso separado conserva una intersección cero sin dibujar un solapamiento ficticio. Comparten geometría e interacción con Venn. No necesitas cambiar de componente ni convertir tus medidas en posiciones de círculos.
+
+El contrato admite entre uno y tres conjuntos con IDs estables y exige cada combinación no vacía en `data`, incluidos ceros y valores `null` explícitos. Las medidas son inclusivas: una intersección de dos conjuntos contiene también la intersección triple. Los valores desconocidos no se convierten en ceros ni en áreas inventadas. La tabla y Anterior/Siguiente conservan las medidas que no generan una región visible.
+
+Los dos conjuntos tienen una disposición circular medida, incluida la inclusión y la separación. Con tres conjuntos, ciertas combinaciones solo admiten una aproximación circular: se informa del error de área sin modificar las medidas originales. Esta capacidad no equivale a un solucionador general para cualquier número de conjuntos o cualquier topología. Consulta el caso de dos conjuntos, los casos de Euler y la distribución de tres conjuntos para elegir una representación adecuada.
+
+# Estimaciones e intervalos de incertidumbre
+
+`NativeFanData` recibe la estimación central y los intervalos proporcionados por tu aplicación. La gráfica no calcula pronósticos ni infiere probabilidades. `bands` declara de una a seis bandas, con IDs estables de hasta 64 caracteres, nombre y `coverage` estrictamente creciente entre cero y uno. El ID `center` está reservado para la estimación.
+
+Cada punto conserva `id`, `x`, `value` e `intervals`. Sus extremos `low` y `high` son conocidos o ambos `null`. Un intervalo conocido contiene la estimación y está dentro de cada banda más amplia conocida. Un intervalo omitido no está configurado; `null` es desconocido; cero sigue siendo un valor real. Se rechazan duplicados, intervalos invertidos y bandas que se cruzan. Hasta 1.024 puntos utilizan IDs categóricos, números finitos o marcas UTC en milisegundos, según `axes.x.type`. La unión de tipos impide mezclar categorías con coordenadas numéricas.
+
+```typescript
+import type {NativeFanData, NativeChartOptions} from '@neural-charts/native';
+
+const data = {
+  type: 'fan',
+  axes: {x: {type: 'linear'}, y: {type: 'linear'}},
+  bands: [{id: 'interval', label: 'Intervalo 80%', coverage: 0.8}],
+  data: [
+    {id: 'a', x: 0, value: 0, intervals: [{bandId: 'interval', low: -1, high: 1}]},
+    {id: 'b', x: 1, value: 2, intervals: [{bandId: 'interval', low: 0, high: 4}]},
+  ],
+} as const satisfies NativeFanData;
+
+const options = {
+  title: 'Estimaciones originales',
+  legend: {position: 'bottom'},
+  tooltip: {content: 'shared', pinnable: true},
+  appearance: {series: [{id: 'center', color: '#2C6DCD'}, {id: 'interval', color: '#638A35'}]},
+  viewport: {axes: 'x'},
+} as const satisfies NativeChartOptions<'fan'>;
+```
+
+El detalle compartido agrupa solo la misma X original y presenta los extremos de cada intervalo, junto con la estimación central. La leyenda oculta bandas sin modificar el origen. Los marcadores pertenecen a la estimación central; sus formas, relleno, borde y diámetro son presentación. El zoom y las referencias conservan las medidas originales. No se admiten apilado, bandas ajustadas por separado ni escala logarítmica. Los títulos y colores pertenecen exclusivamente a `options`.
+
+# Regresión desde muestras originales
+
+`NativeRegressionData` recibe hasta ocho series y 4.096 filas XY en total. Cada muestra mantiene IDs estables de hasta 96 caracteres. `null` en cualquiera de las coordenadas hace que ese par no participe en el cálculo; cero es conocido. El prefijo `ols:` está reservado para los ajustes derivados. Se calcula una regresión de mínimos cuadrados independiente por serie, sin extrapolar fuera de sus X conocidas.
+
+```typescript
+import type {NativeRegressionData, NativeChartOptions} from '@neural-charts/native';
+
+const data = {
+  type: 'regression',
+  axes: {x: {type: 'linear'}, y: {type: 'linear'}},
+  series: [{id: 'samples', name: 'Muestras', data: [
+    {id: 'a', x: 0, y: 1},
+    {id: 'b', x: 1, y: 3},
+    {id: 'unknown', x: null, y: 8},
+  ]}],
+} as const satisfies NativeRegressionData;
+
+const options = {
+  title: 'Muestras y ajuste',
+  appearance: {series: [
+    {id: 'samples', color: '#2C6DCD'},
+    {id: 'ols:samples', name: 'Ajuste calculado', color: '#638A35'},
+  ]},
+  tooltip: {pinnable: true},
+  viewport: {axes: 'xy'},
+} as const satisfies NativeChartOptions<'regression'>;
+```
+
+Muestras y recta comparten un único marco de ejes y mantienen colores y visibilidad independientes. Ocultar una serie no cambia los datos utilizados para ajustar su modelo. El zoom recorta la recta original, incluso si la ventana no contiene ninguna muestra; no vuelve a entrenarla. El detalle diferencia la estimación de un dato original e incluye pendiente, ordenada, R² y recuentos de pares conocidos y desconocidos.
+
+Con menos de dos pares completos o sin variación en X no se dibuja una recta ficticia: se explica por qué no hay ajuste. Una Y constante produce pendiente cero, con R² indefinido. Los cálculos compensados y centrados conservan precisión con X grandes y pequeñas diferencias, y rechazan coeficientes que no pueden representarse. La asociación lineal no implica causalidad ni convierte el ajuste en una previsión. No hay intervalos de confianza calculados, apilado ni tooltip compartido.
+
+Ambas páginas incluyen seis ejemplos, configurador, referencia de propiedades con tipos e incompatibilidades y tabla de datos originales paginada. Las pruebas de cálculo, componentes y navegador siguen separadas de la campaña pendiente en las apps de iOS y Android.