@equinor/fusion-framework-module-navigation 6.0.1 → 7.0.0-next.2

package/src/lib/state/history.flows.ts

@@ -0,0 +1,279 @@
+import { Observable, of, merge } from 'rxjs';
+import { concatMap, map, withLatestFrom } from 'rxjs/operators';
+import type { Flow } from '@equinor/fusion-observable';
+import { filterAction } from '@equinor/fusion-observable/operators';
+import { actions, type Actions } from './history.actions';
+import { resolvePath } from '../utils';
+import { type Location, type LocationState, type HistoryStack, Action } from '../types';
+
+/**
+ * History flow for processing navigation actions.
+ */
+export type HistoryFlow = Flow<Actions, LocationState>;
+
+/**
+ * Factory function that creates a history flow from a stack.
+ */
+export type HistoryFlowCreator = (stack: HistoryStack) => HistoryFlow;
+
+const compareLocation = (a: Location, b: Location) => {
+  return (
+    a.hash === b.hash &&
+    a.search === b.search &&
+    a.pathname === b.pathname &&
+    JSON.stringify(a.state) === JSON.stringify(b.state)
+  );
+};
+
+/**
+ * Flow creator for handling navigate actions.
+ *
+ * Execution flow:
+ * 1. Filters for navigate actions
+ * 2. Resolves the target path from the action payload
+ * 3. Creates a location object with the resolved path, key (from action meta), and optional state
+ * 4. Checks if the new location is the same as current to prevent navigation loops
+ * 5. Updates the stack based on replace option (replace updates current, otherwise pushes new entry)
+ * 6. Returns success action with the new location and appropriate action type (PUSH/REPLACE)
+ */
+export const navigate: HistoryFlowCreator =
+  (stack: HistoryStack): HistoryFlow =>
+  (action$: Observable<Actions>) => {
+    const { navigate } = actions;
+    return action$.pipe(
+      filterAction(navigate.type),
+      map((action) => {
+        const { payload, meta } = action;
+        const path = resolvePath(payload.to);
+        const key = meta.key;
+        const { replace, state } = payload.options;
+        const nextLocation = { ...path, key, state } satisfies Location;
+        // prevent death loop navigation
+        if (compareLocation(nextLocation, stack.current)) {
+          return actions.abortNavigate('Location is the same as the current location');
+        }
+        if (replace) {
+          stack.replace(nextLocation);
+        } else {
+          stack.push(nextLocation);
+        }
+        return navigate.success({
+          delta: 0,
+          action: replace ? Action.Replace : Action.Push,
+          location: nextLocation,
+        });
+      }),
+    );
+  };
+
+/**
+ * Flow creator for handling go (back/forward) actions.
+ *
+ * Execution flow:
+ * 1. Filters for go actions
+ * 2. Combines with current state to get history entries
+ * 3. Moves the stack index by the specified delta (negative for back, positive for forward)
+ * 4. Returns success action with POP action type and the new current location
+ */
+export const go: HistoryFlowCreator =
+  (stack: HistoryStack): HistoryFlow =>
+  (action$: Observable<Actions>, state$: Observable<LocationState>) => {
+    const { go } = actions;
+    return action$.pipe(
+      filterAction(go.type),
+      withLatestFrom(state$),
+      map(([action, state]) => {
+        const { delta } = action.payload;
+        stack.go(delta, state);
+        return go.success({
+          delta: 0,
+          action: Action.Pop,
+          location: stack.current,
+        });
+      }),
+    );
+  };
+
+/**
+ * Flow creator for handling pop (browser back/forward) actions.
+ *
+ * Execution flow:
+ * 1. Filters for pop actions
+ * 2. Uses the location from the action payload or falls back to stack.current
+ * 3. Emits a success action with POP action type and the current location
+ * 4. Completes the observable immediately (synchronous operation)
+ */
+export const pop: HistoryFlowCreator =
+  (stack: HistoryStack): HistoryFlow =>
+  (action$: Observable<Actions>) => {
+    const { pop } = actions;
+    return action$.pipe(
+      filterAction(pop.type),
+      concatMap(
+        (action) =>
+          new Observable<Actions>((subscriber) => {
+            const currentLocation = action.payload.update?.location ?? stack.current;
+            // todo - we might need to check if the current location is in the history stack
+            // for now we will just use the current location
+            subscriber.next(
+              pop.success({
+                delta: 0,
+                action: Action.Pop,
+                location: currentLocation,
+              }),
+            );
+            subscriber.complete();
+          }),
+      ),
+    );
+  };
+
+/**
+ * Flow creator for checking navigation blockers before processing actions.
+ *
+ * Execution flow:
+ * 1. Filters for navigation actions (navigate, go, pop, validateLocation)
+ * 2. Determines the action type (PUSH/REPLACE for navigate, POP for others)
+ * 3. Combines with current state to check for active blockers
+ * 4. If no blockers exist, passes the action through immediately
+ * 5. If blockers exist:
+ *    - Creates a transition object with action, location, and retry callback
+ *    - Calls each blocker asynchronously (wrapped in Promise to prevent blocking)
+ *    - Blockers can call retry() to allow navigation or prevent it by not calling retry()
+ *    - Waits for all blockers to complete before continuing
+ * 6. Returns the original action if navigation is allowed, or completes without emitting if blocked
+ */
+export const checkBlockers: HistoryFlowCreator =
+  (stack: HistoryStack): HistoryFlow =>
+  (action$: Observable<Actions>, state$: Observable<LocationState>) => {
+    const { pop, navigate, go, validateLocation } = actions;
+    return action$.pipe(
+      filterAction(navigate.type, pop.type, go.type, validateLocation.type),
+      map((action) => {
+        switch (action.type) {
+          case navigate.type:
+            return {
+              replace: action.payload.options.replace,
+              action: action,
+            };
+          case go.type:
+          case pop.type:
+          case validateLocation.type:
+            return {
+              type: 'POP' as Action,
+              action: action,
+            };
+        }
+      }),
+      withLatestFrom(state$),
+      concatMap(([{ action, replace }, state]) => {
+        if (!state.blockers.length) {
+          return of(action);
+        }
+        return new Observable<Actions>((subscriber) => {
+          const location = stack.current;
+          const blockers = state.blockers.map((blocker) =>
+            Promise.resolve(
+              blocker({
+                delta: 0,
+                action: replace ? Action.Replace : Action.Push,
+                location,
+                retry: () => {
+                  subscriber.next(action);
+                },
+              }),
+            ),
+          );
+          Promise.allSettled(blockers).then(() => {
+            subscriber.complete();
+          });
+        });
+      }),
+    );
+  };
+
+/**
+ * Flow creator for validating the current location against history state.
+ *
+ * Execution flow:
+ * 1. Filters for validateLocation actions
+ * 2. Combines with current state to access history entries
+ * 3. Gets the current location from the stack
+ * 4. Searches history for an entry matching the current location's key
+ * 5. Validates that:
+ *    - The location key exists in history (returns failure if not found)
+ *    - The location state matches the history entry state (returns failure if mismatch)
+ * 6. Returns success action with current location if validation passes, failure otherwise
+ */
+export const validateCurrentLocation: HistoryFlowCreator =
+  (stack: HistoryStack): HistoryFlow =>
+  (action$: Observable<Actions>, state$: Observable<LocationState>) => {
+    const { validateLocation } = actions;
+    return action$.pipe(
+      filterAction(validateLocation.type),
+      withLatestFrom(state$),
+      map(([, state]) => {
+        const currentLocation = stack.current;
+        const record = state.history.find(({ location }) => location?.key === currentLocation?.key);
+        if (!record) {
+          return validateLocation.failure(new Error('Stack state not found'));
+        }
+        if (record?.location?.state !== currentLocation?.state) {
+          return validateLocation.failure(new Error('Stack state mismatch'));
+        }
+        return validateLocation.success({
+          delta: 0,
+          action: Action.Pop,
+          location: currentLocation,
+        });
+      }),
+    );
+  };
+
+/**
+ * Creates a combined history flow from multiple flow creators.
+ *
+ * Execution flow:
+ * 1. Creates a preprocessing step that applies blocker checking (unless skipped)
+ * 2. Initializes each flow creator with the stack to create individual flows
+ * 3. Merges all flows so they process actions in parallel
+ * 4. Returns a combined flow that:
+ *    - First applies preprocessing (blocker checking)
+ *    - Then processes actions through all merged flows
+ *    - Emits results from any flow that matches the action
+ *
+ * @param flowCreators - Array of flow creators to combine
+ * @param options - Optional configuration options
+ * @param options.skipBlockCheck - If true, skip blocker checking
+ * @returns A combined history flow creator
+ */
+export const createFlow = (
+  flowCreators: HistoryFlowCreator[],
+  options?: { skipBlockCheck?: boolean },
+): HistoryFlowCreator => {
+  return (stack: HistoryStack): HistoryFlow => {
+    const preProcessActions = options?.skipBlockCheck
+      ? (action$: Observable<Actions>) => action$
+      : checkBlockers(stack);
+
+    const flows: HistoryFlow = (
+      action$: Observable<Actions>,
+      state$: Observable<LocationState>,
+    ) => {
+      return merge(
+        ...flowCreators
+          .map((initializer) => initializer(stack))
+          .map((flow) => flow(action$, state$)),
+      );
+    };
+
+    return (action$: Observable<Actions>, state$: Observable<LocationState>) => {
+      return preProcessActions(action$, state$).pipe((source$) => flows(source$, state$));
+    };
+  };
+};
+
+/**
+ * Collection of flow creators for history state management.
+ */
+export const flowCreators = { navigate, go, pop, validateCurrentLocation };

package/src/lib/state/history.reducer.ts

@@ -0,0 +1,70 @@
+import { createReducer } from '@equinor/fusion-observable';
+import type { LocationState, NavigationUpdate } from '../types';
+import { actions, type Actions } from './history.actions';
+import { isSuccessAction } from '@equinor/fusion-observable/actions';
+
+/**
+ * Finds the index of the current location in the history array.
+ * Used to determine where to insert/replace entries for REPLACE actions.
+ */
+const findIndex = (state: LocationState) => {
+  return state.history.findIndex((update) => update.location.key === state.current.location.key);
+};
+
+/**
+ * Creates a reducer for history state management.
+ *
+ * @param initial - Initial navigation update or function that returns initial state
+ * @param options - Optional configuration options
+ * @param options.maxHistory - Maximum number of history entries to keep (default: 100)
+ * @returns A reducer for history state
+ */
+export const createHistoryReducer = (
+  initial: NavigationUpdate | (() => LocationState),
+  options?: { maxHistory?: number },
+) => {
+  const maxHistory = options?.maxHistory ?? 100;
+
+  const initialState: LocationState =
+    initial instanceof Function
+      ? initial()
+      : ({
+          current: initial,
+          history: [initial],
+          blockers: [],
+        } satisfies LocationState);
+
+  return createReducer<LocationState, Actions>(initialState, (builder) => {
+    // Handle navigate.success actions to update history array
+    builder.addCase(actions.navigate.success, (state, action) => {
+      const { update } = action.payload;
+      // For REPLACE actions, remove all entries after the current location (the tail)
+      // This ensures REPLACE doesn't add to history length when at the end,
+      // and removes any forward history when not at the end
+      if (update.action === 'REPLACE') {
+        const currentIndex = findIndex(state);
+        if (currentIndex !== -1) {
+          // Remove all entries from current position onwards
+          state.history.splice(currentIndex, state.history.length - currentIndex);
+        }
+      }
+      state.history.push(update);
+    });
+    // Update current location for all successful actions (navigate, go, pop, etc.)
+    builder.addMatcher(isSuccessAction, (state, action) => {
+      const { update } = action.payload;
+      state.current = update;
+    });
+    // Limit history size to prevent unbounded growth
+    // This matcher always runs (returns true) to check history length after every action
+    builder.addMatcher(
+      () => true,
+      (state) => {
+        if (state.history.length > maxHistory) {
+          // Keep only the most recent entries, removing oldest ones
+          state.history = state.history.slice(-maxHistory);
+        }
+      },
+    );
+  });
+};

package/src/lib/state/history.state.ts

@@ -0,0 +1,62 @@
+import {
+  createState,
+  type FlowState,
+  type ReducerWithInitialState,
+} from '@equinor/fusion-observable';
+import { actions, type Actions } from './history.actions';
+import { flowCreators, createFlow, type HistoryFlowCreator } from './history.flows';
+import type { HistoryStack, LocationState } from '../types';
+
+/**
+ * History state containing flow state and stack.
+ */
+export type HistoryState = FlowState<LocationState, typeof actions> & {
+  stack: HistoryStack;
+};
+
+/**
+ * Default flows for history state management.
+ */
+export const defaultFlows = [flowCreators.navigate, flowCreators.go, flowCreators.pop];
+
+/**
+ * Creates a history store with the specified stack and reducer.
+ *
+ * @param stack - The history stack implementation
+ * @param reducer - The reducer for history state
+ * @param options - Optional configuration options
+ * @returns A HistoryState instance
+ */
+export const createStore = (
+  stack: HistoryStack,
+  reducer: ReducerWithInitialState<LocationState, Actions>,
+  options?: {
+    flows?: HistoryFlowCreator[];
+    skipBlockCheck?: boolean;
+    validateCurrentLocation?: boolean;
+  },
+): HistoryState => {
+  // Create base state with actions and reducer, then add stack property
+  // The stack is stored alongside the flow state for use in flows
+  const state = Object.assign(createState(actions, reducer), { stack }) as HistoryState;
+
+  // Build set of flows to use (default flows or custom flows)
+  // Use Set to ensure no duplicates if validateCurrentLocation is added
+  const flows = new Set<HistoryFlowCreator>(options?.flows ?? defaultFlows);
+  // Optionally add validation flow to check location consistency
+  if (options?.validateCurrentLocation) {
+    flows.add(flowCreators.validateCurrentLocation);
+  }
+
+  // Create combined flow from all flow creators
+  // This merges all flows so they process actions in parallel
+  const flow = createFlow([...flows], {
+    skipBlockCheck: options?.skipBlockCheck,
+  });
+
+  // Initialize the flow with the stack and add it to the state subject
+  // The flow processes actions and updates state through the reducer
+  state.subject.addFlow(flow(stack));
+
+  return state;
+};

package/src/lib/state/index.ts

@@ -0,0 +1,3 @@
+export { createStore, type HistoryState } from './history.state';
+export { createHistoryReducer } from './history.reducer';
+export { actions, type Actions } from './history.actions';

package/src/lib/types.ts

@@ -0,0 +1,159 @@
+import type { Observable } from 'rxjs';
+import type { Actions } from './state/history.actions';
+
+/**
+ * Actions represent the type of change to a location value.
+ */
+export enum Action {
+  /**
+   * A POP indicates a change to an arbitrary index in the history stack, such
+   * as a back or forward navigation. It does not describe the direction of the
+   * navigation, only that the current index changed.
+   *
+   * Note: This is the default action for newly created history objects.
+   */
+  Pop = 'POP',
+  /**
+   * A PUSH indicates a new entry being added to the history stack, such as when
+   * a link is clicked and a new page loads.
+   */
+  Push = 'PUSH',
+  /**
+   * A REPLACE indicates the entry at the current index in the history stack
+   * being replaced by a new one.
+   */
+  Replace = 'REPLACE',
+}
+
+/**
+ * Target path for navigation operations.
+ * Can be a string path or a Path object.
+ */
+export type To = string | Partial<Path>;
+
+/**
+ * Path object containing pathname, optional search, and optional hash.
+ */
+export type Path = {
+  pathname: string;
+  search: string;
+  hash: string;
+};
+
+/**
+ * Location object representing a navigation entry.
+ * Extends Path with state and a unique key.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: necessary
+export type Location<T = any> = Path & {
+  state: T;
+  key: string;
+};
+
+/**
+ * Internal state for history management.
+ */
+export type LocationState = {
+  current: NavigationUpdate;
+  history: NavigationUpdate[];
+  blockers: NavigationBlocker[];
+};
+
+/**
+ * Callback function for listening to navigation changes.
+ */
+export type NavigationListener = (update: Readonly<NavigationUpdate>) => void;
+
+/**
+ * Navigation update event containing action and location.
+ */
+export type NavigationUpdate<A extends string = Action, T = unknown> = {
+  delta: number;
+  action: Readonly<A>;
+  location: Readonly<Location<T>>;
+};
+
+/**
+ * Navigation transition that was blocked.
+ * Provides a retry method to allow the navigation to proceed.
+ */
+export interface NavigationTransition extends NavigationUpdate {
+  /**
+   * Retries the navigation that was blocked.
+   */
+  retry(): void;
+}
+
+/**
+ * Callback function for blocking navigation attempts.
+ */
+export type NavigationBlocker = (transition: NavigationTransition) => void;
+
+/**
+ * Options for controlling navigation behavior.
+ *
+ * @interface NavigateOptions
+ *
+ * @property {boolean} [replace] - Determines the navigation action:
+ * - `false` (default): Pushes a new entry onto the history stack
+ * - `true`: Replaces the current entry in the history stack
+ *
+ * @property {unknown} [state] - Optional state object to associate with the navigation entry.
+ * This state can be accessed later when navigating back to this entry.
+ */
+export interface NavigateOptions {
+  replace?: boolean;
+  state?: unknown;
+}
+
+/**
+ * History interface for managing navigation state.
+ * Compatible with industry-standard routers (Remix/React Router) and provides observable state management.
+ */
+export interface History extends Disposable {
+  /** Observable stream of navigation state updates. */
+  readonly state$: Observable<NavigationUpdate>;
+  /** Observable stream of navigation actions. */
+  readonly action$: Observable<Actions>;
+  /** Current navigation action. */
+  readonly action: Action;
+  /** Current location in the history stack. */
+  readonly location: Location;
+
+  /** Creates a valid href string for a given path. */
+  createHref(to: To): string;
+  /** Creates a URL object for a given path. */
+  createURL(to: To): URL;
+  /** Encodes a location by properly URL-encoding the pathname. */
+  encodeLocation(to: To): Path;
+  /** Pushes a new navigation entry onto the history stack. */
+  push(to: To, state?: unknown): void;
+  /** Replaces the current history entry with a new one. */
+  replace(to: To, state?: unknown): void;
+  /** Navigate to a location with explicit options. */
+  navigate(to: To, options?: NavigateOptions): void;
+  /** Navigates backward or forward in the history stack. */
+  go(delta: number): void;
+  /** Sets up a listener for navigation changes. */
+  listen(listener: NavigationListener): () => void;
+  /** Registers a blocker to intercept navigation attempts. */
+  block(blocker: NavigationBlocker): VoidFunction;
+}
+
+/**
+ * History stack interface for managing navigation entries.
+ */
+export interface HistoryStack {
+  /** Origin URL for the history stack. */
+  readonly origin: string;
+  /** Current location in the stack. */
+  readonly current: Location;
+  /** Pushes a new entry onto the history stack. */
+  push(location: Location): void;
+  /** Replaces the current entry in the history stack. */
+  replace(location: Location): void;
+  /** Navigates backward or forward in the history stack. */
+  go(delta: number, state: Readonly<LocationState>): void;
+  /** Creates a URL object for a given path. */
+  createURL(to: To): URL;
+}

package/src/lib/utils/encode-trailing-whitespace.ts

@@ -0,0 +1,18 @@
+/**
+ * Encodes trailing whitespace in a string by replacing it with '%20'.
+ *
+ * @param input - The string to encode
+ * @returns The string with trailing whitespace encoded
+ *
+ * @example
+ * ```ts
+ * encodeTrailingWhitespace('hello ')
+ * // 'hello%20'
+ *
+ * encodeTrailingWhitespace('hello')
+ * // 'hello'
+ * ```
+ */
+export const encodeTrailingWhitespace = (input: string): string => {
+  return input.replace(/ $/, '%20');
+};

package/src/lib/utils/has-protocol.ts

@@ -0,0 +1,21 @@
+/**
+ * Checks if a string has a protocol prefix.
+ *
+ * @param input - The string to check
+ * @returns True if the string starts with a protocol (e.g., 'http:', 'https:', 'file:')
+ *
+ * @example
+ * ```ts
+ * hasProtocol('https://example.com')
+ * // true
+ *
+ * hasProtocol('/users')
+ * // false
+ *
+ * hasProtocol('file:///path/to/file')
+ * // true
+ * ```
+ */
+export const hasProtocol = (input: string): boolean => {
+  return /^[a-zA-Z][a-zA-Z\d+\-.]*:/.test(input);
+};

package/src/lib/utils/index.ts

@@ -0,0 +1,5 @@
+export { pathToString } from './path-to-string';
+export { pathToUrl } from './path-to-url';
+export { resolvePath } from './resolve-path';
+export { resolveWindowLocation } from './resolve-browser-location';
+export { resolveHashLocation } from './resolve-browser-location';

package/src/lib/utils/path-to-string.ts

@@ -0,0 +1,24 @@
+import type { Path } from '../types';
+import { encodeTrailingWhitespace } from './encode-trailing-whitespace';
+
+/**
+ * Converts a Partial<Path> object to a path string.
+ *
+ * @param to - The path object with optional pathname, search, and hash
+ * @returns A path string with properly formatted search and hash
+ *
+ * @example
+ * ```ts
+ * pathToString({ pathname: '/users', search: '?id=1', hash: '#section' })
+ * // '/users?id=1#section'
+ *
+ * pathToString({ pathname: '/users', search: 'id=1', hash: 'section' })
+ * // '/users?id=1#section'
+ * ```
+ */
+export const pathToString = (to: Partial<Path>): string => {
+  const pathname = encodeTrailingWhitespace(to.pathname ?? '/');
+  const search = encodeTrailingWhitespace(to.search?.replace(/^\?/, '') ?? '');
+  const hash = encodeTrailingWhitespace(to.hash?.replace(/^#/, '') ?? '');
+  return `${pathname}${search ? `?${search}` : ''}${hash ? `#${hash}` : ''}`;
+};