# gilbarbara/react-joyride architecture

> Architecture diagram of the GitHub repository gilbarbara/react-joyride, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gilbarbara/react-joyride
- Repository: https://github.com/gilbarbara/react-joyride

## Overview

##### Project type and purpose
- React Joyride is an open-source React UI library for building guided tours and product onboarding flows.
- It provides reusable components (beacons, tooltips, overlays, spotlights) and core logic (step management, state store, DOM targeting).

##### File structure
- Top-level directories:
- src/ – all library source code: components, modules, types, styles, defaults
- docs/ – markdown docs for end users
- e2e/ – end-to-end tests (Playwright CT)
- test/ – unit tests and fixtures (Vitest)
- scripts/ – build & maintenance scripts (e.g., fix-cjs)
- .github/, husky/, CI config – continuous integration & quality gating
- Configuration files: package.json, tsconfig.json, Playwright and Vitest configs, Sonar & lint settings.

##### README for additional insights
- Usage example showing how an application imports Joyride, passes a steps array, and renders the component.
- References to react-floater for positioning and optional polyfills for legacy browser support.
- Development flow: npm link, watch builds, demo app integration.

##### Main components
a. Consumer application (the host app)
b. Joyride entry point (src/index.tsx → Joyride component)
c. Internal modules / logic layer (src/modules: store, dom, step, helpers, scope)
d. UI components (src/components: Beacon, Overlay, Spotlight, Tooltip, Portal)
e. Styling & defaults (src/styles.ts, src/defaults.ts)
f. External dependencies: React, react-floater, scrollingelement polyfill
g. Build & packaging pipeline (scripts/fix-cjs, bundler, watch, output to dist/)
h. Test suites: unit tests (Vitest), e2e tests (Playwright CT)
i. Documentation site (docs/, book.json, docs build)

##### Relationships and interactions
- Consumer App → imports Joyride → passes steps & config props
- Joyride component → initializes module layer (store, scope, step controller)
- Module layer → computes current step, listens for events, reads DOM targets via dom module
- Joyride → renders UI components via React Portal into document.body
- UI components → Beacon & Spotlight highlight target elements, Overlay dims background, Tooltip renders content (using react-floater)
- Styling definitions & default props feed into components
- Build pipeline transforms src/ → distributed package; CI runs tests & publishes docs.

##### Architectural patterns & design principles
- Unidirectional data flow: props → store → modules → render
- Component composition: Joyride wraps modular pieces (Beacon, Overlay, Tooltip)
- Separation of concerns: logic (modules/) vs. presentation (components/) vs. types vs. styles
- Extensibility: custom components via props, external polyfills support legacy browsers

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Runtime Components
  subgraph "Runtime Components"
    App["Consumer App"]:::runtime
    Joyride["Joyride"]:::runtime
    subgraph "Logic Modules"
      DOM["DOM Targeting Module"]:::runtime
      Helpers["Helpers Module"]:::runtime
      Scope["Scope Management Module"]:::runtime
      StepCtrl["Step Controller Module"]:::runtime
      Store["State Store Module"]:::runtime
    end
    subgraph "UI Components"
      Beacon["Beacon Component"]:::runtime
      Overlay["Overlay Component"]:::runtime
      Spotlight["Spotlight Component"]:::runtime
      Tooltip["Tooltip Component"]:::runtime
      TooltipCont["Tooltip Container"]:::runtime
      TooltipClose["Tooltip Close Button"]:::runtime
      Portal["Portal Wrapper"]:::runtime
      StepWrap["Step Wrapper"]:::runtime
      CompBarrel["Components Barrel"]:::runtime
    end
    subgraph "Styles & Defaults"
      Styles["Default Styles"]:::runtime
      Defaults["Default Props & Options"]:::runtime
    end
  end

  %% External Dependencies
  subgraph "External Dependencies"
    React["React"]:::external
    Floater["react-floater"]:::external
    Polyfill["scrollingelement polyfill"]:::external
  end

  %% Build & CI Pipeline
  subgraph "Build & CI Pipeline"
    FixCJS["CommonJS Fix Script"]:::pipeline
    Bundler["Bundler & Watch"]:::pipeline
    Dist["Dist Output"]:::pipeline
    CI["CI & Quality"]:::pipeline
  end

  %% Testing
  subgraph "Testing"
    Unit["Unit Tests (Vitest)"]:::pipeline
    E2E["E2E Tests (Playwright CT)"]:::pipeline
  end

  %% Documentation
  subgraph "Documentation"
    DocsContent["Docs Content"]:::docs
    DocsConfig["Documentation Config"]:::docs
  end

  %% Connections
  App -->|"imports & steps props"| Joyride
  Joyride -->|"init modules"| DOM
  Joyride -->|"init modules"| Helpers
  Joyride -->|"init modules"| Scope
  Joyride -->|"init modules"| StepCtrl
  Joyride -->|"init modules"| Store

  Joyride -->|"render"| Beacon
  Joyride -->|"render"| Overlay
  Joyride -->|"render"| Spotlight
  Joyride -->|"render"| Tooltip
  Joyride -->|"render"| StepWrap

  Store -->|"state updates"| Beacon
  Store -->|"state updates"| Overlay
  Store -->|"state updates"| Spotlight
  Store -->|"state updates"| Tooltip

  StepCtrl -->|"current step"| Beacon
  StepCtrl -->|"current step"| Overlay
  StepCtrl -->|"current step"| Spotlight
  StepCtrl -->|"current step"| Tooltip

  Beacon -->|"highlight target"| Portal
  Spotlight -->|"spotlight target"| Portal
  Overlay -->|"dim background"| Portal
  Tooltip -->|"position via Floater"| Portal

  Tooltip -->|"contains"| TooltipCont
  Tooltip -->|"contains"| TooltipClose

  React --> Joyride
  Floater --> Tooltip
  Polyfill --> Joyride

  FixCJS --> Bundler
  Bundler --> Dist
  CI --> Unit
  CI --> E2E
  CI --> DocsContent

  %% Click Events
  click Joyride "https://github.com/gilbarbara/react-joyride/blob/main/src/index.tsx"
  click DOM "https://github.com/gilbarbara/react-joyride/blob/main/src/modules/dom.ts"
  click Helpers "https://github.com/gilbarbara/react-joyride/blob/main/src/modules/helpers.tsx"
  click Scope "https://github.com/gilbarbara/react-joyride/blob/main/src/modules/scope.ts"
  click StepCtrl "https://github.com/gilbarbara/react-joyride/blob/main/src/modules/step.ts"
  click Store "https://github.com/gilbarbara/react-joyride/blob/main/src/modules/store.ts"
  click Beacon "https://github.com/gilbarbara/react-joyride/blob/main/src/components/Beacon.tsx"
  click Overlay "https://github.com/gilbarbara/react-joyride/blob/main/src/components/Overlay.tsx"
  click Spotlight "https://github.com/gilbarbara/react-joyride/blob/main/src/components/Spotlight.tsx"
  click Tooltip "https://github.com/gilbarbara/react-joyride/blob/main/src/components/Tooltip/index.tsx"
  click TooltipCont "https://github.com/gilbarbara/react-joyride/blob/main/src/components/Tooltip/Container.tsx"
  click TooltipClose "https://github.com/gilbarbara/react-joyride/blob/main/src/components/Tooltip/CloseButton.tsx"
  click Portal "https://github.com/gilbarbara/react-joyride/blob/main/src/components/Portal.tsx"
  click StepWrap "https://github.com/gilbarbara/react-joyride/blob/main/src/components/Step.tsx"
  click CompBarrel "https://github.com/gilbarbara/react-joyride/blob/main/src/components/index.tsx"
  click Styles "https://github.com/gilbarbara/react-joyride/blob/main/src/styles.ts"
  click Defaults "https://github.com/gilbarbara/react-joyride/blob/main/src/defaults.ts"
  click FixCJS "https://github.com/gilbarbara/react-joyride/blob/main/scripts/fix-cjs.ts"
  click Unit "https://github.com/gilbarbara/react-joyride/tree/main/test/modules/"
  click Unit "https://github.com/gilbarbara/react-joyride/blob/main/test/styles.spec.ts"
  click Unit "https://github.com/gilbarbara/react-joyride/tree/main/test/tours/"
  click Unit "https://github.com/gilbarbara/react-joyride/tree/main/test/__fixtures__/"
  click E2E "https://github.com/gilbarbara/react-joyride/blob/main/e2e/standard.spec.tsx"
  click E2E "https://github.com/gilbarbara/react-joyride/blob/main/e2e/controlled.spec.tsx"
  click E2E "https://github.com/gilbarbara/react-joyride/blob/main/e2e/scroll.spec.tsx"
  click E2E "https://github.com/gilbarbara/react-joyride/tree/main/e2e/__fixtures__/"
  click E2E "https://github.com/gilbarbara/react-joyride/tree/main/e2e/__snapshots__/"
  click DocsContent "https://github.com/gilbarbara/react-joyride/blob/main/docs/*.md"
  click DocsConfig "https://github.com/gilbarbara/react-joyride/blob/main/book.json"
  click DocsConfig "https://github.com/gilbarbara/react-joyride/blob/main/docs/SUMMARY.md"
  click CI "https://github.com/gilbarbara/react-joyride/blob/main/.github/workflows/main.yml"
  click CI "https://github.com/gilbarbara/react-joyride/tree/main/.husky/pre-commit"
  click CI "https://github.com/gilbarbara/react-joyride/tree/main/.husky/post-merge"
  click CI "https://github.com/gilbarbara/react-joyride/blob/main/sonar-project.properties"
  click CI "https://github.com/gilbarbara/react-joyride/blob/main/.editorconfig"
  click CI "https://github.com/gilbarbara/react-joyride/blob/main/.prettierignore"

  %% Styles
  classDef runtime fill:#D0E8FF,stroke:#333,stroke-width:1px
  classDef external fill:#D0FFD0,stroke:#333,stroke-width:1px
  classDef pipeline fill:#FFE5B4,stroke:#333,stroke-width:1px
  classDef docs fill:#E0E0E0,stroke:#333,stroke-width:1px
```
