§Gravity UI ChartKit ·

Componente React basado en plugins que proporciona una interfaz de renderizado unificada para múltiples bibliotecas de gráficos. Registras uno o más plugins y renderizas gráficos a través de <ChartKit type="..." data={...} /> — ChartKit se encarga de enviarlo al renderizador correcto automáticamente.

Cada renderizador de plugin se carga de forma diferida (lazy-loaded), por lo que el código de la biblioteca subyacente solo se descarga cuando ChartKit se renderiza realmente en la interfaz de usuario. ChartKit también maneja la visualización de tooltips amigables para móviles de forma nativa. Puedes usar los plugins integrados o implementar los tuyos propios.

Cuándo usarlo:

• Necesitas gráficos declarativos modernos (gravity-charts) o gráficos de series temporales / monitorización (yagr).
• Necesitas múltiples tipos de gráficos bajo una única API consistente.
• Estás desarrollando dentro del ecosistema de Gravity UI.

Cuándo no usarlo:

• Solo necesitas una biblioteca de gráficos específica; prefiere usar @gravity-ui/charts directamente.

§Tabla de contenidos

• Primeros pasos
• Actualización de paquetes de gráficos
• Desarrollo

§Primeros pasos

§Requisitos

• React 16, 17 o 18.
• [@gravity-ui/uikit](https://github.com/gravity-ui/uikit) — dependencia peer requerida (proporciona theming y primitivas de UI).

§Instalación

npm install @gravity-ui/chartkit @gravity-ui/uikit

§Estilos

Importa los estilos de @gravity-ui/uikit en tu punto de entrada:

import '@gravity-ui/uikit/styles/fonts.css';
import '@gravity-ui/uikit/styles/styles.css';

Para detalles completos de configuración, consulta la guía de estilos de uikit.

§Uso básico

ChartKit utiliza un registro global de plugins. Llama a settings.set una vez en el punto de entrada de tu aplicación para registrar los plugins que necesitas. Cuando se renderiza <ChartKit type="..." />, busca el plugin coincidente; si no se encuentra ninguno, se lanza un error. El renderizador de cada plugin es un componente React.lazy, por lo que su código se descarga solo cuando ChartKit aparece por primera vez en la interfaz de usuario.

Puedes registrar múltiples plugins a la vez:

settings.set({plugins: [GravityChartsPlugin, YagrPlugin]});

O llama a settings.set varias veces; fusiona la lista de plugins en lugar de reemplazarla.

Ejemplo básico:

import {ThemeProvider} from '@gravity-ui/uikit';
import ChartKit, {settings} from '@gravity-ui/chartkit';
import {GravityChartsPlugin} from '@gravity-ui/chartkit/gravity-charts';

import '@gravity-ui/uikit/styles/fonts.css';
import '@gravity-ui/uikit/styles/styles.css';

settings.set({plugins: [GravityChartsPlugin]});

const data = {
  series: {
    data: [
      {
        type: 'line',
        name: 'Series',
        data: [
          {x: 0, y: 10},
          {x: 1, y: 25},
          {x: 2, y: 18},
          {x: 3, y: 30},
        ],
      },
    ],
  },
};

export default function App() {
  return (
    <ThemeProvider theme="light">
      <div style={{height: 300}}>
        <ChartKit type="gravity-charts" data={data} />
      </div>
    </ThemeProvider>
  );
}

ChartKit se adapta al tamaño de su contenedor padre; asegúrate de que el contenedor tenga una altura explícita.

§Actualización de paquetes de gráficos

ChartKit incluye dos bibliotecas de gráficos de Gravity UI como dependencias:

• @gravity-ui/charts — potencia el plugin gravity-charts.
• @gravity-ui/yagr — potencia el plugin yagr.

Si necesitas una versión más reciente de uno de estos paquetes, abre una solicitud de actualización de paquete Package update request y selecciona el(los) paquete(s) que necesitas. Los mantenedores actualizarán los paquetes seleccionados y publicarán la actualización.

§Desarrollo

§Prerrequisitos

• Node.js 22 (ver .nvmrc).
• npm 10 o posterior.

§Configuración

Clona el repositorio e instala las dependencias:

git clone https://github.com/gravity-ui/ChartKit.git
cd ChartKit
npm ci

§Ejecutar Storybook

npm run start

Storybook estará disponible en http://localhost:7007.

§Desarrollar con una dependencia local

Para trabajar en una dependencia (por ejemplo, @gravity-ui/charts) y ver tus cambios en vivo en Storybook sin publicarlos en npm:

1. Enlaza el paquete local

# En tu clon local de @gravity-ui/charts:
git clone https://github.com/gravity-ui/charts.git
cd charts
npm ci
# haz tus cambios
npm run build
npm link

# En ChartKit:
npm link @gravity-ui/charts

2. Configura la observación del paquete local

Crea un archivo .env.local en la raíz de ChartKit (está ignorado por git):

LOCAL_PKG=@gravity-ui/charts

Esto le indica a Vite que observe ese paquete en node_modules y omita su pre-empaquetado. Después de reconstruir @gravity-ui/charts, Storybook se recargará en caliente automáticamente.

Para múltiples paquetes, usa una lista separada por comas:

LOCAL_PKG=@gravity-ui/charts,@gravity-ui/uikit

3. Inicia Storybook

npm run start

4. Restaura el paquete original

Cuando hayas terminado:

1. Comenta LOCAL_PKG en .env.local.
2. Ejecuta npm install en ChartKit; esto reemplaza el enlace simbólico con la versión del registro.

# En ChartKit:
npm ci

§Ejecutar pruebas

npm test

Las pruebas de regresión visual se ejecutan en Docker para garantizar capturas de pantalla consistentes entre entornos:

npm run test:docker

Para actualizar las capturas de pantalla de referencia después de cambios intencionados en la UI:

npm run test:docker:update

§Contribuir

Por favor, consulta la guía de contribución antes de enviar una pull request.

§Licencia

Distribuido bajo la Licencia MIT. Consulta LICENSE para más detalles.

§Para agentes de IA

Un componente de React que distribuye plugins y renderiza gráficos de múltiples bibliotecas de gráficos de Gravity UI a través de una única API <ChartKit type="..." data={...} />. Úsalo cuando necesites un punto de entrada único de carga diferida para tipos de gráficos mixtos, en lugar de importar cada biblioteca de gráficos directamente.

§Cuándo usarlo

• Renderizar más de un motor de gráficos (por ejemplo, gravity-charts + yagr) bajo un componente consistente.
• Carga diferida de paquetes de gráficos: el renderizador de cada plugin es React.lazy, por lo que el código de una biblioteca solo se descarga cuando su tipo de gráfico se muestra realmente.
• Agrupar gráficos en una aplicación Gravity UI que desee tooltips amigables para móviles y temas unificados de inmediato.

§Cuándo no usarlo

• Para un solo tipo de gráfico, importa @gravity-ui/charts (general) o @gravity-ui/yagr (series temporales de alto rendimiento) directamente; el registro de plugins es una sobrecarga para un solo motor.
• Para componer una cuadrícula de panel de control con widgets, usa @gravity-ui/dashkit; ChartKit renderiza un gráfico; DashKit organiza varios widgets.

§Errores comunes

• Renderizar <ChartKit> antes de settings.set({plugins: [...]}): el registro global de plugins debe estar poblado en el punto de entrada de la aplicación; un type no registrado lanzará un error en tiempo de renderizado.
• Prop chartType / library alucinada: la prop de distribución es type (por ejemplo, type="gravity-charts"), y los datos son data.
• Olvidar la altura del contenedor: ChartKit llena su padre; sin una altura explícita en el contenedor, el gráfico colapsa a cero.
• Esperar que los plugins estén incluidos en el paquete: los renderizadores de plugins (@gravity-ui/chartkit/gravity-charts, .../yagr) son diferidos; la primera renderización de un tipo descarga su paquete.
• Falta la importación de estilos de uikit: la tematización depende de @gravity-ui/uikit/styles/styles.css; sin ella, los gráficos se renderizan sin estilo.

§Documentación para agentes de IA

La documentación legible por agentes para la versión instalada se encuentra en node_modules/@gravity-ui/chartkit/build/docs/INDEX.md.