Skip to Content
🎉 Now published as @nfsfu234/tour-guide project-wide config support — see what's new →
Changelog

Changelog

All notable changes to this project will be documented in this file. See standard-version  for commit guidelines.

1.1.0  — NFSFU234 Open Source Day (2026-08-25)

A major release focused on project-wide configuration, accessibility, positioning reliability, styling flexibility, test coverage, and package/build improvements.

This release is part of NFORSHIFU234 Dev’s open-source ecosystem and NFSFU234 Open Source Day, alongside NFSFU234 Form Validation  and the new NFSFU234 ShotSweep .

⚠️ BREAKING CHANGES

  • Package scope changed: the package is now published as @nfsfu234/tour-guide instead of nfsfu234-tour-guide. Existing consumers should update their dependency and imports. See MIGRATION.md.
  • Scoped package publishing: publishConfig.access is explicitly set to public, allowing the scoped package to be published publicly to npm.

Added

Project-wide configuration

  • Added defineConfig() for defining reusable Tour configuration.

  • Added <TourProvider> for providing shared configuration to multiple <Tour> instances.

  • Added the TourConfig type to the public API.

  • Shared configuration can now define defaults such as:

    • theme
    • accentColor
    • buttonLabels
    • showBranding
    • and other supported Tour options.

  • Per-tour props continue to take precedence over values supplied through TourProvider.

Example:

// tour.config.ts
import { defineConfig } from '@nfsfu234/tour-guide';
 
export default defineConfig({
  theme: 'dark',
  accentColor: '#10b981',
  showBranding: false,
});
// app/layout.tsx
import { TourProvider } from '@nfsfu234/tour-guide';
import tourConfig from '../tour.config';
 
export default function RootLayout({ children }) {
  return <TourProvider config={tourConfig}>{children}</TourProvider>;
}

This makes it possible to maintain a single source of truth for applications that use multiple tours, such as onboarding flows, feature announcements, and settings walkthroughs.

Accessibility

  • Added Escape keyboard handling to close both the welcome dialog and an active tour step.
  • Added Tab and Shift+Tab focus trapping within the open dialog.
  • Focus is automatically moved into the dialog when a welcome screen or tour step opens.
  • Added role="dialog" to interactive tour surfaces.
  • Added aria-modal to modal tour surfaces.
  • Added aria-live announcements for relevant tour content.
  • Added descriptive aria-label attributes to the tooltip and welcome screen.
  • Added role="progressbar" to the step progress indicator.
  • Added aria-valuenow, aria-valuemin, and aria-valuemax to the progress indicator.

Testing

  • Added the project’s first real automated test suite using Vitest.
  • Added coverage for shared configuration and Tour/provider prop precedence.
  • Added regression coverage for restoring highlighted element styles.
  • Added accessibility and styling tests covering class-name overrides, Escape handling, and focus trapping.
  • Added positioning tests covering viewport-edge flipping, clamping, and arrow direction.
  • Added regression coverage for tooltip re-measurement after mounting.
  • Added tests/ and vitest.config.ts.
  • Replaced the previous no-op test behavior ("No tests yet, skipping...") with an actual test command.

Fixed

Tooltip positioning

  • Fixed tooltips rendering on the wrong side of their target, particularly near viewport edges.
  • Fixed an issue where requesting position: 'right' could result in the tooltip appearing on the left, bottom-left, or another unexpected position.
  • Fixed the initial positioning calculation occurring before the tooltip had switched to position: fixed.
  • Tooltip positioning now performs an additional measurement after fixed positioning has been applied, ensuring the calculation uses the tooltip’s actual rendered dimensions.
  • Reworked viewport overflow handling so the requested side is calculated first and only changed when there is a genuine overflow that requires a flip.
  • Cross-axis clamping is now used as a safety measure without unnecessarily forcing the tooltip away from its requested side.
  • Fixed tooltip arrows pointing in the wrong direction after a positioning flip. The arrow now follows the tooltip’s actual resolved position rather than the originally requested step.position.

Highlight cleanup

  • Fixed highlighted target elements retaining tour-applied position and z-index styles after the tour ended.
  • Original inline position and z-index values are now saved and restored during cleanup instead of being cleared unconditionally.
  • This prevents tours from leaving behind layout or stacking changes after they close.

Styling

  • Fixed tooltipClassName and overlayClassName being unable to override theme colors.
  • Theme and custom-theme colors are now exposed through CSS custom properties instead of competing inline color declarations.
  • Base styling uses zero-specificity :where() selectors so consumer-provided classes can override the default colors without depending on stylesheet load order.
  • This makes the documented class-based customization behavior work as intended, including utility-class frameworks such as Tailwind CSS.

Build

  • Updated the tsup build configuration to enable --minify.
  • Enabled --treeshake for production builds.
  • Added/updated the npm run size workflow for checking package bundle size.
  • Because the production build is now minified and tree-shaken, previously documented bundle-size figures should be considered specific to this build configuration and should be re-verified after future build changes.

Package and project metadata

  • Updated package metadata for the @nfsfu234 scoped package.
  • Corrected the package description so it no longer references Tailwind CSS or Framer Motion as runtime dependencies/features of the zero-dependency implementation.
  • Updated the package’s public exports to include the new configuration and provider APIs.
  • Updated TypeScript types to expose the new configuration functionality.
  • Updated the package publishing configuration for public scoped-package releases.

Documentation

  • Updated the README to document project-wide configuration with defineConfig() and <TourProvider>.
  • Updated installation and import examples for the @nfsfu234/tour-guide package scope.
  • Documented shared configuration and per-instance prop precedence.
  • Updated documentation around styling and customization to reflect the corrected CSS override behavior.
  • Added migration guidance for consumers upgrading from the pre-1.1.0 package name.

Housekeeping

  • Updated the LICENSE copyright holder to NFORSHIFU LOGICFORGE LTD (operating as NFORSHIFU234 Dev), reflecting the legal entity backing the project.
  • Updated project metadata and release documentation to reflect the current NFORSHIFU234 Dev open-source ecosystem.

Release

Part of NFORSHIFU234 Dev’s open-source ecosystem and released for NFSFU234 Open Source Day alongside NFSFU234 Form Validation  and the new NFSFU234 ShotSweep .

1.0.10  (2026-03-06)

Bug Fixes

  • resolve Next.js 15 ESM module resolution by outputting .mjs extension (#100 ) (54543fe )

1.0.9  (2026-02-19)

Bug Fixes

  • only lock body scroll during welcome phase, not during active tour steps (#96 ) (2cd1b75 )

1.0.8  (2026-02-19)

Bug Fixes

  • only lock body scroll during welcome phase, not during active tour steps (#95 ) (6304287 )

1.0.7  (2026-02-19)

Bug Fixes

  • eliminate welcome+backdrop overlap by consolidating welcome phase into single full-screen div (#94 ) (8a0e83b )

1.0.6  (2026-02-19)

Bug Fixes

  • tour: ensure complete cleanup of backdrop & body scroll lock on tour end (#93 ) (23b19eb )

1.0.5  (2026-02-19)

Bug Fixes

  • prevent stale welcome screen DOM nodes & add safe cleanup (c8dbb88 )
  • tour: fix “node not a child of this node” error during welcome → active transition (#92 ) (f1c4d34 )

1.0.4  (2026-02-19)

Bug Fixes

1.0.3  (2026-02-19)

Bug Fixes

  • memoize welcomeConfig and filteredSteps to stabilize isActive phase reset (#90 ) (cc5901e )

1.0.2  (2026-02-19)

Bug Fixes

  • reset phase state when isActive toggles to prevent welcome+tooltip double render (#89 ) (483209f )

1.0.1  (2026-02-17)

Bug Fixes

  • update module paths in package.json for CommonJS and ES module compatibility (#88 ) (7fa1964 )

1.0.0  (2026-02-17)

⚠ BREAKING CHANGES

  • update module exports and types in package.json; add comment in index.tsx (#87)

Bug Fixes

  • update module exports and types in package.json; add comment in index.tsx (#87 ) (c1a0d1d )

0.3.1  (2026-02-17)

0.3.0  (2026-02-17)

⚠ BREAKING CHANGES

  • removed framer-motion and lucide-react dependencies, changed theme system, removed tourDots prop

Features

  • Add TypeScript definitions for nfsfu234-tour-guide module (#83 ) (ace5968 )
  • complete rewrite with zero dependencies (cf97b20 )

1.0.0  (2026-02-17)

⚠ BREAKING CHANGES

  • Complete rewrite of the Tour component architecture
  • Removed dependency on framer-motion and lucide-react
  • Changed tooltip rendering to use React portals and Intersection Observer
  • Simplified API - removed unused props and consolidated theme system
  • tourDots prop removed - use showProgress instead
  • Theme customization now uses customTheme prop instead of inline style overrides

Features

  • Zero Dependencies: Removed all external dependencies except React and ReactDOM (#83 )
  • Custom Theme System: Added customTheme prop with ThemeConfig interface for complete color customization (#84 )
  • Smart Tooltip Positioning: Tooltips now follow target elements using Intersection Observer and scroll listeners (#85 )
  • Body Scroll Lock: Welcome screen now properly locks body scroll to prevent backdrop movement (#86 )
  • Device Filtering: Steps are automatically filtered based on device prop (desktop/mobile/both) (#87 )
  • Mobile-Specific Content: Added contentMobile prop to show different text on mobile devices (#88 )
  • Improved TypeScript Support: Complete rewrite of type definitions with better inference (#89 )
  • Built-in Theme Presets: Added light and dark theme presets with beautiful defaults (#90 )

Bug Fixes

  • Tooltip Positioning: Fixed tooltips appearing off-screen or in wrong position (#91 )
  • Scroll Behavior: Target elements now properly scroll into view and stay visible (#92 )
  • Welcome Screen: Fixed backdrop scrolling issue on mobile devices (#93 )
  • TypeScript Errors: Resolved declaration file issues with tsup/rollup (#94 )
  • Z-Index Conflicts: Improved z-index management for overlay and tooltips (#95 )

Performance Improvements

  • Bundle Size: Reduced bundle size from ~45KB to ~10KB (gzipped) by removing dependencies
  • Render Optimization: Tooltips only re-render when position changes
  • Memory Management: Proper cleanup of event listeners and observers

Documentation

  • Complete README Rewrite: Added comprehensive API reference with examples (#96 )
  • Real-World Examples: Added SaaS onboarding, mobile-aware, and i18n examples
  • Theme Customization Guide: Detailed guide on creating custom themes
  • Migration Guide: Added migration guide from v0.x to v1.0 (see MIGRATION.md)
  • Contributing Guide: Updated CONTRIBUTING.md with current practices

Refactorings

  • Component Architecture: Split Tour into main component and Tooltip subcomponent
  • State Management: Simplified phase management (welcome → active → done)
  • Positioning Logic: Rewrote tooltip positioning with proper viewport handling
  • Type System: Reorganized interfaces for better maintainability

0.2.21  (2026-02-17)

Bug Fixes

0.2.20  (2026-02-17)

Features

0.2.19  (2026-02-17)

Features

Bug Fixes

0.2.18  (2026-02-17)

Bug Fixes

  • Refactor tooltip handling and step navigation (#78 ) (1520782 )
  • Refactor Tour component to manage phases and tooltip (#77 ) (3721cd6 )

0.2.17  (2026-02-17)

Bug Fixes

  • Refactor Tour component and enhance tooltip logic (#76 ) (52453e9 )

0.2.16  (2026-02-17)

Features

  • Enhance Tour component with tooltip positioning and improved navigation (#75 ) (ca7afd5 )

0.2.15  (2026-02-17)

Features

  • Update README and enhance Tour component with new features and styling options (#72 ) (bee54f2 )

Bug Fixes

  • Add missing type definitions for Node and React in devDependencies (#73 ) (76d8f8b )
  • Add standard-version for version management (#74 ) (8260397 )

0.2.14  (2026-02-17)

Bug Fixes

  • Refactor package.json for author and dependencies (#67 ) (7b10a79 )
  • Refactor Tour component interfaces and logic (#66 ) (3d8934f )
  • Update Dependabot assignees and reviewers to match current user (#68 ) (fbe947a )

0.2.13  (2026-02-16)

0.2.12  (2025-06-01)

Bug Fixes

0.2.11  (2025-06-01)

Bug Fixes

0.2.10  (2025-06-01)

Bug Fixes

0.2.9  (2025-06-01)

Bug Fixes

0.2.8  (2025-06-01)

Bug Fixes

0.2.7  (2025-06-01)

Bug Fixes

0.2.6  (2025-05-26)

Bug Fixes

0.2.5  (2025-05-17)

Bug Fixes

  • trying to fix the automation hauld for deploying after release is successful (#12 ) (805ef3d )

0.2.4  (2025-05-17)

Features

  • adding new files to the project (a3a16a6 )

Bug Fixes

0.2.3  (2025-05-17)

Features

  • adding new files to the project (a3a16a6 )

Bug Fixes

0.2.2  (2025-05-17)

0.2.1  (2025-05-17)

[0.1.0] - 2025-05-17

Added

  • Initial release of nfsfu234-tour-guide.
  • Support for customizable tour steps with target selectors, content, and positions.
  • Light and dark themes.
  • Welcome screen with customizable content.
  • Progress bar and optional progress dots.
  • Device-specific steps (desktop, mobile, both).
  • TypeScript support with full type definitions.
  • Keyboard navigation (Arrow keys, Enter, Escape).
  • Integration with framer-motion for animations and lucide-react for icons.

Fixed

  • N/A (initial release).

Changed

  • N/A (initial release).

Removed

  • N/A (initial release).
Last updated on
ContributingConfiguration