feature-tour

Componente de tour/onboarding para React Native.

Instalación

Requiere react-native-svg:

npx expo install react-native-svg

Uso básico

import { useRef } from 'react';
import { View, Text, Button } from 'react-native';
import { Tour, TourProvider, TourHandle, TourStepConfig } from './feature-tour';

export default function MyScreen() {
  // tourRef expone start() y stop() para controlar el tour de forma imperativa
  const tourRef = useRef<TourHandle>(null);

  // Cada ref se asigna al elemento de UI que el tour resaltará
  const headerRef = useRef<View>(null);
  const buttonRef = useRef<View>(null);

  // Define la lista ordenada de pasos; cada paso apunta a un ref y contiene los datos del tooltip
  const steps: TourStepConfig[] = [
    {
      id: 'header',       
      ref: headerRef,     // El elemento a resaltar
      title: 'Cabecera',
      content: 'Aquí está el título principal.',
      tooltipPosition: 'bottom', // El tooltip aparece debajo del elemento resaltado
    },
    {
      id: 'button',
      ref: buttonRef,
      title: 'Acción',
      content: 'Pulsa aquí para continuar.',
      tooltipPosition: 'top',  // El tooltip aparece encima del elemento resaltado
      tooltipSize: 'lg',       // Usa la variante de tooltip más ancha (320px en lugar de 260px)
    },
  ];

  return (
    // TourProvider provee el tema y el contexto compartido a todos los componentes del tour
    <TourProvider>
      {/* <Tour> renderiza el overlay y el tooltip; es invisible hasta que se llama a start() */}
      <Tour ref={tourRef} steps={steps} />

      {/* Asigna los refs a los elementos que quieres resaltar en cada paso */}
      <Text ref={headerRef}>Mi app</Text>

      {/* Llamar a tourRef.current.start() inicia el tour en el paso 0 */}
      <Button title="Iniciar tour" onPress={() => tourRef.current?.start()} />
    </TourProvider>
  );
}

Props de <Tour>

| Prop | Tipo | Default | Descripción | |---|---|---|---| | steps | TourStepConfig[] | — | Pasos del tour | | skipLabel | string | 'Saltar' | Texto del botón "Saltar" | | nextLabel | string | 'Siguiente' | Texto del botón "Siguiente" | | finishLabel | string | 'Finalizar' | Texto del botón del último paso | | showSkipButton | boolean | true | Muestra u oculta el botón de omitir |

Ejemplo con etiquetas en inglés:

// Sobreescribe las etiquetas predeterminadas
<Tour ref={tourRef} steps={steps} skipLabel="Skip" nextLabel="Next" finishLabel="Done" />

Contenido personalizado en un paso

content acepta tanto un string (texto simple) como cualquier ReactNode:

// --- Opción 1: string simple ---
// El tooltip renderiza el texto directamente dentro de un componente <Text>.
{ id: 'step1', ref, title: 'Título', content: 'Descripción sencilla.' }

// --- Opción 2: ReactNode personalizado ---
// Cuando content es un ReactNode, se envuelve en un <View> simple;
// tienes control total sobre el layout y los estilos.
{
  id: 'stats',
  ref: statsRef,
  title: 'Estadísticas',
  content: (
    <View style={{ gap: 4 }}>
      {/* Fila de texto descriptivo */}
      <Text style={{ fontSize: 13, color: '#475569' }}>Aquí ves un resumen de tu actividad.</Text>

      {/* Fila de badges — cada badge es una píldora pequeña con fondo de color */}
      <View style={{ flexDirection: 'row', gap: 8, marginTop: 4 }}>
        <Text style={{ fontSize: 12, backgroundColor: '#e0f2fe', paddingHorizontal: 8,
        paddingVertical: 2, borderRadius: 10 }}>12 proyectos</Text>
        <Text style={{ fontSize: 12, backgroundColor: '#dcfce7', paddingHorizontal: 8,
        paddingVertical: 2, borderRadius: 10 }}>48 tareas</Text>
      </View>
    </View>
  ),
  tooltipPosition: 'bottom', // Coloca el tooltip debajo del elemento de estadísticas
}

Props de TourStepConfig

| Prop | Tipo | Default | Descripción | |---|---|---|---| | id | string | — | Identificador único del paso | | ref | RefObject<View> | — | Referencia al elemento a destacar | | title | string | — | Título del tooltip | | content | string \| ReactNode | — | Texto simple o componente React personalizado | | tooltipPosition | 'top' \| 'bottom' \| 'auto' | 'auto' | Posición del tooltip | | tooltipSize | 'sm' \| 'lg' | 'sm' | Tamaño del tooltip | | highlightPadding | number | 8 | Espacio extra alrededor del elemento |

Tema

Personaliza el aspecto visual pasando un objeto theme parcial a <TourProvider>:

import { Tour, TourProvider, TourTheme } from './feature-tour';

// Define el tema fuera del componente para evitar recrearlo en cada render
// Partial<TourTheme> permite sobreescribir solo los tokens deseados
const miTema: Partial<TourTheme> = {
  primaryColor: '#7c3aed',        // Botón "Siguiente" en morado
  tooltipBackgroundColor: '#1e1e2e', // Fondo oscuro para el tooltip
  tooltipTitleColor: '#ffffff',
  tooltipDescriptionColor: '#a0a0b0',
  overlayColor: 'rgba(0,0,0,0.75)',
};

// Pasa el tema al provider; solo los tokens definidos sobreescriben el DEFAULT_TOUR_THEME
export default function App() {
  return (
    <TourProvider theme={miTema}>
      {/* resto de la app */}
    </TourProvider>
  );
}

También puedes pasar los tokens directamente como objeto literal:

// Proporciona solo los tokens que quieras sobreescribir; 
// el resto tomará los valores de DEFAULT_TOUR_THEME.
// Aquí cambiamos el color de acción principal y suavizamos las esquinas del highlight.
<TourProvider theme={{ primaryColor: '#2563eb', highlightBorderRadius: 12 }}>

| Token | Default | Descripción | |---|---|---| | primaryColor | '#2563eb' | Color de fondo del botón "Siguiente" | | primaryTextColor | '#ffffff' | Color del texto del botón "Siguiente" | | skipButtonTextColor | '#888888' | Color del texto del botón "Saltar" | | skipButtonBackgroundColor | 'transparent' | Color de fondo del botón "Saltar" | | tooltipBackgroundColor | '#ffffff' | Fondo del tooltip | | tooltipTitleColor | '#111111' | Color del título | | tooltipDescriptionColor | '#444444' | Color de la descripción | | tooltipProgressColor | '#888888' | Color del contador de pasos | | tooltipBorderRadius | 10 | Radio del tooltip | | overlayColor | 'rgba(0,0,0,0.6)' | Color del fondo oscuro | | highlightBorderColor | '#ffffff' | Color del borde del elemento destacado | | highlightBorderRadius | 10 | Radio del recuadro de highlight |