ngx-orbit-tour 🛰️

ngx-orbit-tour es una librería de guided tours, onboarding y ayuda contextual para Angular 17+. Pensada para dashboards, SaaS y apps enterprise: API standalone, Signals, overlay con máscara SVG (spotlight) y motor desacoplado del DOM de tu producto.

Autor: Diego Osorio · Repositorio: github.com/diegoso4/ngx-orbit

Características ✨

• Tours guiados con registro declarativo (OrbitTourDefinition) y pasos anclados por ID.
• Spotlight SVG — resalta elementos sin hacks de querySelector global.
• Signals — estado reactivo del tour (paso actual, visibilidad, progreso).
• Standalone-first — provideOrbitTour(), directivas y componentes importables por piezas.
• Anclas — directiva [orbitAnchor] + registro automático en runtime.
• Ayuda contextual — orbitTourHelp y botón orbit-tour-help-button.
• Persistencia opcional — startIfNotCompleted() con clave en localStorage.
• SSR-safe — el motor no arranca overlay fuera del navegador.
• Angular CDK — scroll y posicionamiento integrados (^20).
• Sin UI framework extra — no depende de Bootstrap ni Tailwind.

Requisitos 📋

| Requisito | Versión | | --------- | ------- | | Node.js | >=20.19 o >=22.12 | | Angular | 17+ (peers ^20) | | @angular/cdk | ^20.2 |

Instalación 🚀

Usa el gestor de tu proyecto (orden recomendado: pnpm → yarn → npm).

pnpm (recomendado)

pnpm add @diegoso4/ngx-orbit-tour

Yarn

yarn add @diegoso4/ngx-orbit-tour

npm

npm install @diegoso4/ngx-orbit-tour

Peer dependencies

Si tu app aún no las tiene:

pnpm add @angular/core @angular/common @angular/cdk

{
  "dependencies": {
    "@diegoso4/ngx-orbit-tour": "^0.1.0"
  }
}

npm, pnpm y yarn avisan si faltan peer dependencies de Angular/CDK.

Uso 🔥

1. Registrar el motor

En app.config.ts (o bootstrapApplication):

import { ApplicationConfig } from '@angular/core';
import { provideOrbitTour } from '@diegoso4/ngx-orbit-tour';

export const appConfig: ApplicationConfig = {
  providers: [
    provideOrbitTour(),
    // provideOrbitTour({ engine: { storagePrefix: 'my-app' } }),
  ],
};

2. Marcar anclas en la plantilla

import { OrbitAnchorDirective } from '@diegoso4/ngx-orbit-tour';

@Component({
  standalone: true,
  imports: [OrbitAnchorDirective],
  template: `
    <header orbitAnchor="dashboard-header">...</header>
    <main orbitAnchor="dashboard-main">...</main>
  `,
})
export class DashboardComponent {}

3. Registrar tours y arrancarlos

import { Component, inject, OnInit } from '@angular/core';
import {
  OrbitTourService,
  type OrbitTourDefinition,
} from '@diegoso4/ngx-orbit-tour';

@Component({ /* ... */ })
export class AppComponent implements OnInit {
  private readonly tour = inject(OrbitTourService);

  ngOnInit(): void {
    const dashboardTour: OrbitTourDefinition = {
      id: 'dashboard-tour',
      skippable: true,
      showStepCounter: true,
      steps: [
        {
          id: 'welcome',
          anchor: 'dashboard-header',
          title: 'Bienvenido',
          description: 'Este es el encabezado principal.',
          placement: 'bottom',
        },
        {
          id: 'content',
          anchor: 'dashboard-main',
          title: 'Contenido',
          description: 'Aquí vive el área de trabajo.',
          placement: 'right',
        },
      ],
    };

    this.tour.register(dashboardTour);
    void this.tour.startIfNotCompleted('dashboard-tour');
  }
}

4. Ayuda contextual (opcional)

import {
  OrbitTourHelpDirective,
  OrbitTourHelpButtonComponent,
} from '@diegoso4/ngx-orbit-tour';

@Component({
  imports: [OrbitTourHelpDirective, OrbitTourHelpButtonComponent],
  template: `
    <section orbitTourHelp="dashboard-tour">...</section>
    <orbit-tour-help-button />
  `,
})
export class ShellComponent {}

API principal

| Método | Descripción | | ------ | ----------- | | register(definition) | Añade un tour al catálogo | | registerMany(definitions) | Registro en lote | | start(tourId) | Inicia el tour | | startIfNotCompleted(tourId) | Inicia solo si no está marcado como completado | | next() / previous() | Navegación entre pasos | | skip() / end() | Salir o finalizar |

Soporte 📚

• Issues y código: github.com/diegoso4/ngx-orbit
• Documentación extendida: ngx-orbit-tour — docs

Licencia 📄

MIT · © Diego Osorio