BloomRouterController class

Client-side router controller using the HTML5 History API.

Coordinates browser-based URL synchronization, asynchronous route guard evaluation, reactive query strings and hash fragments, automatic scroll position restoration across session history entries, accessible screen-reader announcements via BloomAnnouncer, automatic keyboard focus management, and speculative link prefetching via IntersectionObserver.

Scroll Restoration & Fragments

When scrollRestoration is enabled (the default):

Sets window.history.scrollRestoration to 'manual' to override default browser scrolling.
Tags history entries with unique keys (bloomKey) stored in history.state.
Records (scrollX, scrollY) offsets before navigating away from an entry.
On forward navigation or fresh route pushes:
- If a hash fragment is present, scrolls the element with matching id (or name) into view.
- Otherwise, resets the window scroll position to (0, 0).
On back/forward popstate navigation, restores the previously saved (scrollX, scrollY) coordinates associated with the destination history entry key.

When enabled (the default):

announceNavigation politely broadcasts the new document title or pathname to screen readers via BloomAnnouncer after the new route renders.
autoFocus moves keyboard focus to the target element (preferring [data-bloom-focus], h1, main, or document.body), adding temporary tabindex="-1" if necessary.
Initial page load skips automatic announcements and focus resets.

Lifecycle and Cleanup

BloomRouterController attaches an active popstate listener to window and manages an IntersectionObserver. When unmounting or tearing down an application, dispose must be called to remove the event listener, disconnect the observer, and restore the previous browser window.history.scrollRestoration configuration.

final router = BloomRouter([
  BloomRoute('/', (params) => const Div(text: 'Home')),
  BloomRoute('/search', (params) => const Div(text: 'Search')),
]);

final controller = BloomRouterController(router);

BloomNode app() => Live(() => controller.resolve());

Constructors

BloomRouterController(BloomRouter _router, {bool scrollRestoration = true, bool announceNavigation = true, bool autoFocus = true, BloomAnnouncer? announcer}): Creates a client-side router controller managing browser navigation for _router.

Properties

announceNavigation → bool: Whether automatic route announcements via BloomAnnouncer are enabled.
final
announcer → BloomAnnouncer?: Optional custom announcer instance used for accessibility announcements.
final
autoFocus → bool: Whether automatic keyboard focus management is enabled on route transitions.
final
currentFragment ↔ Signal<String>: Reactive signal tracking the current URL hash fragment (without the leading #).
latefinal
currentPath ↔ Signal<String>: Reactive signal tracking the current URL pathname.
latefinal
currentQuery ↔ Signal<Map<String, String>>: Reactive signal tracking the current URL query parameters (single value per key, last wins).
latefinal
currentQueryAll ↔ Signal<Map<String, List<String>>>: Reactive signal tracking all current URL query parameters preserving repeated keys.
latefinal
hashCode → int: The hash code for this object.
no setterinherited
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
scrollRestoration → bool: Whether automatic scroll position restoration is enabled.
final

Methods

dispose() → void: Removes the popstate window event listener, disconnects the link prefetch observer, and restores browser history scroll restoration.
navigate(String path) → Future<void>: Navigates to path by pushing a new entry onto the browser history stack.
navigateFragment(String fragment) → Future<void>: Navigates to fragment on the current pathname by pushing a new history entry.
navigateQuery(Map<String, dynamic> query) → Future<void>: Navigates to an updated query string on the current pathname by pushing a new history entry.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
replace(String path) → Future<void>: Navigates to path by replacing the current browser history entry in place.
replaceFragment(String fragment) → Future<void>: Replaces the hash fragment on the current pathname in place without pushing a new history entry.
replaceQuery(Map<String, dynamic> query) → Future<void>: Replaces the query string on the current pathname in place without pushing a new history entry.
resolve() → BloomNode: Resolves the current URL path against the router and returns the matching BloomNode tree.
setFragment(String fragment, {bool replace = false}) → Future<void>: Updates the hash fragment on the current path, either pushing or replacing history.
setQuery(Map<String, dynamic> query, {bool replace = false}) → Future<void>: Updates the query parameters on the current path, either pushing or replacing history.
toString() → String: A string representation of this object.
inherited

Operators

operator ==(Object other) → bool: The equality operator.
inherited