How enszrlu/nextstep works
Main Components
• Core library components:
• NextStep: The central component that manages the tour process and rendering.
• NextStepProvider/NextStepContext: Provides context/state management for the tour.
• useNextStep: A hook to start, close, or control the tour from within the application.
• Tour configuration:
• Customization components:
• Custom Card components to render tour tooltips.
• NextStepViewport: Wrapping scrollable content to ensure steps target the right viewport.
Navigation Adapters
• The project includes an adapters directory both under src and in the built dist folder.
• Adapters for:
• Next.js (default behavior).
• React Router.
• Remix.
• Window adapter (fallback for non-framework specific navigation).
• These adapters abstract navigation actions such as push, getCurrentPath, and allow custom implementations.
Relationships and Data Flow
• The application that uses NextStep will wrap its components in a NextStepProvider so that the core NextStep component can access the tour configuration and manage global state.
• During a tour, events like onStepChange, onComplete, and onSkip are triggered and can be hooked by developers.
• The NextStep component interacts with the navigation adapter (provided either as default in Next.js or via a custom adapter) to perform route navigation when a step specifies nextRoute or prevRoute.
• The useNextStep hook allows UI triggers (buttons, events) to initiate or manipulate a tour.
Architectural Patterns and Design Principles
• Modularity: Different directories for source code (src) and build output (dist) demonstrate clear separation between development and production artifacts.
• Adapter Pattern: The use of navigation adapters for various frameworks indicates dynamic binding of routing logic.
• Component-Based UI: By exposing customizable components (like CustomCard) and viewports, it follows common React component patterns.
• Event-Driven Communication: Hooks and callback props (onStepChange, onComplete, onSkip) create an event-driven system for managing tours.
Relevant Technologies and Tools
• TypeScript is used throughout the code (as indicated by .ts and .tsx files).
• Motion (from the motion.dev library) is used for animations.
• React as the main UI framework.
• The provided configuration for Vite and the specific export settings for Next.js (ES Modules) must also be captured since they impact deployment/integration.
Instructing the Principal Software Engineer
1. Application Integration Layer: Show where in the user’s app the NextStepProvider is applied and where the NextStep component is rendered.
4. Tour Configuration & Customization: Include a “Tour Steps” component block detailing the structure of a tour (steps, selectors, routing), along with configurable Custom Card and NextStepViewport.
– Data flow (for example, “tour config”, “navigation actions”, “state/event callbacks”).
– Dependencies (e.g., “uses”, “calls”, “implements”).
• Using annotations to explain the function of each component, choices of routing adapters, and how customization points (like custom cards and viewports) are injected.
This detailed, component-by-component breakdown ensures clarity about which elements belong to the core library, which provide integration points (adapters), and which allow user customization. This comprehensive map helps in both debugging the flow and understanding how to extend or modify the onboarding experience.