@okyrychenko-dev/react-action-guard-router 0.2.4 → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,228 @@
+# Changelog
+
+## 1.0.0
+
+[Release history](https://github.com/okyrychenko-dev/react-action-guard/releases/tag/@okyrychenko-dev/react-action-guard-router@1.0.0)
+
+### Minor Changes
+
+- b4945b0: Restore TanStack navigation blocking using native useBlocker. Confirmed transitions keep protection armed, failed confirmations deny navigation, and superseded or unmounted attempts cannot allow navigation. Require TanStack Router >=1.170.41 within v1, the verified compatibility floor, and use native unload protection with a one-shot bypass after accepted document navigation, avoiding a duplicate browser prompt.
+
+  Invalidate pending confirmations when when or scope changes, including replacements that leave the computed blocking state active.
+
+  Preserve pending confirmations when observer callbacks onBlock or onAllow change during a rerender.
+
+  Compare scopes by normalized contents so equivalent arrays, including reordered or duplicated entries, preserve pending confirmations while effective scope changes invalidate them.
+
+  Document and test the native not-found limitation at TanStack Router 1.170.41: unmatched-to-matched navigation skips adapter callbacks even with an active condition or scope; subsequent matched-route navigation remains guarded.
+
+- bd1dc3b: Publish format-specific ESM and CommonJS declarations so NodeNext CommonJS consumers can use the supported public imports. Correct Core's legacy main/module paths and resolve Next's router.js entry so native Node ESM can load the Next adapter. Require React Router DOM >=6.19.0 within v6 or v7 because earlier v6 releases do not export the stable useBlocker API. This excludes previously declared unsupported versions and releases the pre-1.0 router package as a minor change. Consumers on older v6 must upgrade before adopting this release; no new runtime dependency is added. Publish evidence-labelled capabilities and packed peer/provider checks, and clarify App Router and application-owned payment cancellation limits.
+
+### Patch Changes
+
+- 06df6f3: Use shared confirmation ownership in React Router so only the latest attached navigation attempt can proceed or notify permission. Invalidate pending answers when the evaluated protection state, scope, or message changes, while preserving them across callback rerenders and equivalent scopes.
+
+  Reset the current blocked transition and clear its pending confirmation when protection configuration changes, without resuming stale approvals or resetting superseding attempts.
+
+  Retain ownership of synchronous denials and silent blocking when they replace an async prompt, so later protection changes reset the current blocked transition rather than consulting the obsolete prompt.
+
+- 0d3c1f7: Complete the Blocking lifecycle architecture migration. Remove mutable blocker and middleware maps,
+  named middleware registration, direct event dispatch, and compatibility restore contracts. Observe
+  lifecycle transitions through ownership-safe anonymous leases and read readonly BlockerInfo snapshots.
+  Devtools sessions release only their observations; manual observation is now additive on every store.
+  Centralize guarded-control state and accessible reasons while retaining public hooks, state mappers,
+  state utilities, and distinct link behavior. Consolidate shared TanStack coverage at its coordination
+  interface and document migration from removed interfaces. Retain react-zustand-toolkit as the state
+  management base.
+- dd13e1b: Evaluate pure navigation predicates on every React render, including stable functions reading refs or external state. Remove misleading useCallback guidance: changing a ref alone still requires a React rerender to refresh protection. Preserve scope OR semantics and router-specific navigation and unload capabilities.
+- 369b2c0: Prevent stale Pages Router confirmations from resuming navigation and notify permission once across async acceptance and route replay.
+- 6d59289: Skip scheduled windows that have already elapsed when a delayed start timer runs, and retain long windows without overflowing their end timers. Share router protection scope keys, remove unused internal confirmation handling, and correct the documented public router types.
+- 26cc31e: Align packaged README requirements with the Core ^2.0.0 release cohort and use durable repository URLs for migration, observability and Next runtime evidence. Declare the Query adapter's existing Node.js >=20 requirement inherited from type-utils. Reconcile superseded intermediate compatibility descriptions in pending release notes.
+
+  Include CHANGELOG.md in every package so the packaged README changelog links resolve. Generate versioned API references and advance changelog links as part of the Changesets version command.
+
+- 691ea3e: Settle pending custom confirmation dialogs as false on effect teardown, including unmount and hiding a preserved React Activity subtree. Clear preserved dialog state so it cannot reappear after effects reconnect. Dialog-specific resolvers now close their own dialog exactly once and cannot affect a replacement dialog. Stable hook-level controls continue to act on the current dialog.
+- 6230733: Adopt `@okyrychenko-dev/type-utils` 0.1.2 for internal type guards, assertions, and utility types, replacing equivalent hand-rolled checks, a duplicated `assertNever` helper, and inline nullable/optional unions. Runtime behavior is unchanged; some public function signatures now show the package's equivalent utility types. Adds `@okyrychenko-dev/type-utils` as a new dependency and explicitly requires Node.js 20 or newer; Node.js 18 is EOL and unsupported.
+- Updated dependencies [6a08414]
+- Updated dependencies [39fb3de]
+- Updated dependencies [32264e4]
+- Updated dependencies [5d403d8]
+- Updated dependencies [3db526a]
+- Updated dependencies [64145c9]
+- Updated dependencies [0d3c1f7]
+- Updated dependencies [083a5b7]
+- Updated dependencies [690a3a9]
+- Updated dependencies [a1b83db]
+- Updated dependencies [d07b65a]
+- Updated dependencies [bd1dc3b]
+- Updated dependencies [6513e1e]
+- Updated dependencies [6d59289]
+- Updated dependencies [26cc31e]
+- Updated dependencies [b987ed1]
+- Updated dependencies [743c6f4]
+- Updated dependencies [303abc3]
+- Updated dependencies [eefba30]
+- Updated dependencies [4363609]
+- Updated dependencies [40e8420]
+- Updated dependencies [6230733]
+  - @okyrychenko-dev/react-action-guard@2.0.0
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.4] - 2026-05-27
+
+### Changed
+
+- Raised `@okyrychenko-dev/react-action-guard` compatibility to the `1.0.4` line.
+- Updated the transitive toolkit override to `react-zustand-toolkit@^0.4.1`.
+
+## [0.2.3] - 2026-05-09
+
+### Changed
+
+- Raised `@okyrychenko-dev/react-action-guard` compatibility to the `1.0.3` line.
+- Prepared package metadata for the coordinated `react-action-guard` stability release.
+
+## [0.2.2] - 2026-04-18
+
+### Changed
+
+- Raised `@okyrychenko-dev/react-action-guard` compatibility to the `1.0.2` line
+- Updated the transitive toolkit override to `react-zustand-toolkit@^0.4.0`
+
+## [0.2.1] - 2026-03-08
+
+### Fixed
+
+- Restored Storybook production build by switching internal Storybook component imports back to local relative paths
+
+## [0.2.0] - 2026-03-08
+
+### Changed
+
+- Normalized `useNavigationBlocker` semantics across adapters so `isBlocking` consistently means the blocking condition is armed
+- Added optional `isIntercepting` for adapters that can expose an active interception state directly
+- Tightened the public confirmation API to the parts that are actually supported end-to-end
+- Clarified README guidance around adapter capabilities, async confirmation behavior, and Next.js App Router limitations
+- Aligned package scripts and Storybook component exports with the current package structure
+
+### Fixed
+
+- Async `onConfirm` handlers are now evaluated once per blocked navigation attempt across adapters
+- Storybook barrel exports and imports now match the reusable components and utilities shipped with the package
+
+## [0.1.0] - 2026-01-25
+
+### Added
+
+- 🚀 Initial release of `@okyrychenko-dev/react-action-guard-router`
+- **React Router v6+ Integration**
+  - `useNavigationBlocker` hook for blocking navigation
+  - `usePrompt` hook for simple confirmation dialogs
+  - Full support for React Router's `useBlocker` API
+  - Scope-based and condition-based blocking
+- **TanStack Router Integration**
+  - `useNavigationBlocker` hook using TanStack Router's history blocking
+  - Support for modern TanStack Router applications
+  - Scope-based and condition-based blocking
+- **Next.js Integration**
+  - Pages Router support with full navigation blocking (Next.js 9+)
+  - App Router support with documented limitations (Next.js 13.4+ for stable support)
+  - Separate exports for each router type
+- **Core Utilities**
+  - `useBeforeUnload` hook for browser unload protection
+  - Utility functions for condition resolution and scope handling
+  - Shared types and interfaces
+- **Features**
+  - Automatic integration with `react-action-guard` scope system
+  - **Custom Dialog Support** via `onConfirm` callback
+    - Support for both synchronous and asynchronous dialog handlers
+    - Race condition prevention in React Router adapter with sequence tracking
+    - Error logging for debugging Promise rejections
+  - **useDialogState Helper Hook**
+    - Simplifies custom dialog state management
+    - Generic type support for custom message data
+    - Promise-based confirmation flow
+  - Browser `beforeunload` event protection
+  - Customizable confirmation dialogs
+  - TypeScript-friendly API surface
+  - Tree-shakeable with subpath exports
+  - Callbacks for block/allow events
+  - Automatic cleanup on unmount
+
+- 📚 **Comprehensive Storybook Documentation** (12 interactive stories):
+  - **React Router stories** (7 examples):
+    - `AsyncConfirm` - Asynchronous confirmation dialogs
+    - `CombinedSources` - Combining multiple blocking sources
+    - `CustomDialog` - Custom dialog implementations
+    - `PrioritizedBlockers` - Priority-based blocking scenarios
+    - `ScopeSync` - Multi-component scope synchronization
+    - `UsePrompt` - Simple prompt hook usage
+    - `WindowConfirm` - Browser native confirmation dialogs
+  - **Next.js stories** (2 examples):
+    - `NextAppRouterDemo` - App Router navigation blocking
+    - `NextPagesRouterDemo` - Pages Router navigation blocking
+  - **TanStack Router stories** (1 example):
+    - `TanStackRouterDemo` - TanStack Router navigation blocking
+  - **Core utilities story**:
+    - `BrowserUnload` - Browser unload protection demo
+  - **Introduction story** with package overview
+
+- 🧩 **Storybook Components Library** (14 reusable components):
+  - `ActionButtons` - Standardized action button layouts
+  - `BlockerItem` - Blocker information display with utilities
+  - `CodeBlock` - Syntax-highlighted code examples
+  - `ConfirmDialog` - Customizable confirmation dialog with CSS
+  - `DebugPanel` - Real-time blocker state visualization with CSS
+  - `FormField` - Form input components
+  - `InfoBox` - Information callouts
+  - `MockRouterProvider` - React Router test provider
+  - `MockTanStackRouterProvider` - TanStack Router test provider
+  - `NavigationSimulator` - Navigation interaction simulator with CSS
+  - `StatusDisplay` - Blocking status indicator
+  - `StoryContainer` - Story wrapper layout
+  - `ScopeSync` - Scope coordination styles (CSS)
+  - Shared CSS styles for consistent presentation
+
+### Documentation
+
+- 📖 Comprehensive README with examples for all router types
+- 💻 JSDoc comments for all public APIs
+- 📚 Usage examples for common scenarios
+- 🎨 Custom dialog integration examples (Material-UI, Radix UI)
+- 🗺️ Migration guide for different routers
+- 📘 Interactive Storybook documentation with live examples
+
+### Testing
+
+- ✅ Full test coverage with vitest
+- 🧪 Added `handleConfirmation` utility tests
+- 🔬 Enhanced core utility function tests
+- 🛠️ Test helpers for all router types
+
+### Development
+
+- 📦 Storybook integration with development scripts (`storybook`, `build-storybook`)
+- 🔧 ESLint configuration with `curly: ["error", "all"]` rule
+- 🧰 Dev dependencies: Storybook packages, `clsx`, `remark-gfm`
+
+### Requirements
+
+- **Peer Dependencies**:
+  - `@okyrychenko-dev/react-action-guard` ^1.0.4
+  - `react` ^18.0.0 || ^19.0.0
+  - One of: `react-router-dom` ^6.0.0, `@tanstack/react-router` ^1.0.0, or `next` ^13.4.0
+
+[Unreleased]: https://github.com/okyrychenko-dev/react-action-guard/compare/@okyrychenko-dev/react-action-guard-router@1.0.0...HEAD
+[0.2.4]: https://github.com/okyrychenko-dev/react-action-guard-router/compare/v0.2.3...v0.2.4
+[0.2.3]: https://github.com/okyrychenko-dev/react-action-guard-router/compare/v0.2.2...v0.2.3
+[0.2.2]: https://github.com/okyrychenko-dev/react-action-guard-router/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/okyrychenko-dev/react-action-guard-router/releases/tag/v0.2.1
+[0.2.0]: https://github.com/okyrychenko-dev/react-action-guard-router/releases/tag/v0.2.0
+[0.1.0]: https://github.com/okyrychenko-dev/react-action-guard-router/releases/tag/v0.1.0
+[1.0.0]: https://github.com/okyrychenko-dev/react-action-guard/releases/tag/@okyrychenko-dev/react-action-guard-router@1.0.0