@equinor/fusion-framework-module-navigation 7.0.9 → 7.0.10

package/src/lib/state/check-blockers.ts

@@ -1,52 +0,0 @@
-import { Observable, of } from 'rxjs';
-import { concatMap, map, withLatestFrom } from 'rxjs/operators';
-import type { HistoryFlowCreator } from './navigate';
-import { actions, type Actions } from './actions';
-import { filterAction } from '@equinor/fusion-observable/operators';
-import { Action, type HistoryStack, type LocationState } from '../types';
-
-/** Flow creator that gates navigation actions through registered blockers. */
-export const checkBlockers: HistoryFlowCreator =
-  (stack: HistoryStack) => (action$: Observable<Actions>, state$: Observable<LocationState>) =>
-    // Normalize each navigation-related action into a common shape before gating on blockers.
-    action$.pipe(
-      filterAction(
-        actions.navigate.type,
-        actions.pop.type,
-        actions.go.type,
-        actions.validateLocation.type,
-      ),
-      map((action) => {
-        // Only `navigate` carries a replace flag; the rest are treated as POP transitions.
-        switch (action.type) {
-          case actions.navigate.type:
-            return { replace: action.payload.options.replace, action };
-          case actions.go.type:
-          case actions.pop.type:
-          case actions.validateLocation.type:
-            return { type: 'POP' as Action, action };
-        }
-      }),
-      withLatestFrom(state$),
-      concatMap(([{ action, replace }, state]) => {
-        // Allow actions through immediately when no blocker can veto the transition.
-        if (!state.blockers.length) {
-          return of(action);
-        }
-        return new Observable<Actions>((subscriber) => {
-          const location = stack.current;
-          // Invoke all blockers and complete once every asynchronous decision settles.
-          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());
-        });
-      }),
-    );

package/src/lib/state/create-flow.ts

@@ -1,36 +0,0 @@
-import { merge, type Observable } from 'rxjs';
-import type { HistoryFlow, HistoryFlowCreator } from './navigate';
-import { checkBlockers } from './check-blockers';
-import type { Actions } from './actions';
-import type { HistoryStack, LocationState } from '../types';
-
-/**
- * Creates a combined history flow from multiple flow creators.
- * @param flowCreators - Flow creators to combine.
- * @param options - Optional blocker configuration.
- * @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>,
-    ) => {
-      // Initialize each creator against the same stack before merging their action streams.
-      const initializedFlows = flowCreators
-        .map((initializer) => initializer(stack))
-        .map((flow) => flow(action$, state$));
-      return merge(...initializedFlows);
-    };
-    return (action$: Observable<Actions>, state$: Observable<LocationState>) => {
-      // Gate actions before dispatching them to the parallel history flows.
-      return preProcessActions(action$, state$).pipe((source$) => flows(source$, state$));
-    };
-  };
-};

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

@@ -1,77 +0,0 @@
-import { createReducer } from '@equinor/fusion-observable';
-import type { LocationState, NavigationUpdate } from '../types';
-import { actions, type Actions } from './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) => {
-  // Locate the current entry by key rather than reference, since updates are cloned.
-  return state.history.findIndex((update) => update.location.key === state.current.location.key);
-};
-
-/**
- * Creates a reducer for history state management.
- *
- * Handles navigate, go, and pop success actions by updating the
- * history array and current location. Enforces a maximum history
- * length to prevent unbounded memory growth.
- *
- * @param initial - Initial navigation update or factory returning initial state
- * @param options - Optional configuration
- * @param options.maxHistory - Maximum number of history entries to keep (default: `100`)
- * @returns A reducer with initial state for use with {@link createStore}
- */
-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);
-        // Only trim when the current entry is actually present in history.
-        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) => {
-        // Trim only once history has actually grown past the configured cap.
-        if (state.history.length > maxHistory) {
-          // Keep only the most recent entries, removing oldest ones
-          state.history = state.history.slice(-maxHistory);
-        }
-      },
-    );
-  });
-};

package/src/lib/state/create-store.ts

@@ -1,39 +0,0 @@
-import { createState, type ReducerWithInitialState } from '@equinor/fusion-observable';
-import { actions, type Actions } from './actions';
-import { flowCreators } from './flow-creators';
-import { createFlow } from './create-flow';
-import type { HistoryFlowCreator } from './navigate';
-import type { HistoryStack, LocationState } from '../types';
-import type { HistoryState } from './history.state';
-
-/**
- * Creates a history store with the specified stack and reducer.
- * @param stack - The history stack implementation.
- * @param reducer - The reducer that handles state transitions.
- * @param options - Optional flow configuration.
- * @returns A fully-initialized history state with flows attached.
- */
-export const createStore = (
-  stack: HistoryStack,
-  reducer: ReducerWithInitialState<LocationState, Actions>,
-  options?: {
-    flows?: HistoryFlowCreator[];
-    skipBlockCheck?: boolean;
-    validateCurrentLocation?: boolean;
-  },
-): HistoryState => {
-  // Attach the stack onto the created state so flows can reach it without prop-drilling.
-  const state = Object.assign(createState(actions, reducer), { stack }) as HistoryState;
-  const flows = new Set<HistoryFlowCreator>(
-    options?.flows ?? [flowCreators.navigate, flowCreators.go, flowCreators.pop],
-  );
-  // Validation is opt-in since it re-checks the current location on every relevant action.
-  if (options?.validateCurrentLocation) {
-    flows.add(flowCreators.validateCurrentLocation);
-  }
-  const flow = createFlow([...flows], {
-    skipBlockCheck: options?.skipBlockCheck,
-  });
-  state.subject.addFlow(flow(stack));
-  return state;
-};

package/src/lib/state/flow-creators.ts

@@ -1,7 +0,0 @@
-import { go } from './go';
-import { navigate } from './navigate';
-import { pop } from './pop';
-import { validateCurrentLocation } from './validate-current-location';
-
-/** Collection of flow creators for history state management. */
-export const flowCreators = { navigate, go, pop, validateCurrentLocation };

package/src/lib/state/go.ts

@@ -1,20 +0,0 @@
-import type { Observable } from 'rxjs';
-import { map, withLatestFrom } from 'rxjs/operators';
-import type { HistoryFlowCreator } from './navigate';
-import { actions, type Actions } from './actions';
-import { filterAction } from '@equinor/fusion-observable/operators';
-import type { LocationState } from '../types';
-import { Action } from '../types';
-
-/** Flow creator for handling go back and forward actions. */
-export const go: HistoryFlowCreator =
-  (stack) => (action$: Observable<Actions>, state$: Observable<LocationState>) =>
-    // Move the stack by the requested delta and emit the resulting location.
-    action$.pipe(
-      filterAction(actions.go.type),
-      withLatestFrom(state$),
-      map(([action, state]) => {
-        stack.go(action.payload.delta, state);
-        return actions.go.success({ delta: 0, action: Action.Pop, location: stack.current });
-      }),
-    );

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

@@ -1,14 +0,0 @@
-import type { FlowState } from '@equinor/fusion-observable';
-import type { actions } from './actions';
-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.
- */

package/src/lib/state/index.ts

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

package/src/lib/state/navigate.ts

@@ -1,58 +0,0 @@
-import type { Observable } from 'rxjs';
-import { map } from 'rxjs/operators';
-import type { Flow } from '@equinor/fusion-observable';
-import { filterAction } from '@equinor/fusion-observable/operators';
-import { actions, type Actions } from './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): boolean => {
-  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. */
-export const navigate: HistoryFlowCreator =
-  (stack: HistoryStack): HistoryFlow =>
-  (action$: Observable<Actions>) => {
-    const { navigate } = actions;
-    // Transform matching navigation actions into stack updates and success actions.
-    return action$.pipe(
-      filterAction(navigate.type),
-      map((action) => {
-        const { payload, meta } = action;
-        const path = resolvePath(payload.to);
-        const nextLocation = {
-          ...path,
-          key: meta.key,
-          state: payload.options.state,
-          unstable_mask: undefined,
-        } satisfies Location;
-        // Abort duplicate navigations to prevent a feedback loop in history state.
-        if (compareLocation(nextLocation, stack.current)) {
-          return actions.abortNavigate('Location is the same as the current location');
-        }
-        // Apply replacement or append semantics selected by the navigation request.
-        if (payload.options.replace) {
-          stack.replace(nextLocation);
-        } else {
-          stack.push(nextLocation);
-        }
-        return navigate.success({
-          delta: 0,
-          action: payload.options.replace ? Action.Replace : Action.Push,
-          location: nextLocation,
-        });
-      }),
-    );
-  };

package/src/lib/state/pop.ts

@@ -1,24 +0,0 @@
-import { Observable } from 'rxjs';
-import { concatMap } from 'rxjs/operators';
-import type { HistoryFlowCreator } from './navigate';
-import { actions, type Actions } from './actions';
-import { filterAction } from '@equinor/fusion-observable/operators';
-import type { HistoryStack } from '../types';
-import { Action } from '../types';
-
-/** Flow creator for handling POP actions from browser navigation. */
-export const pop: HistoryFlowCreator = (stack: HistoryStack) => (action$: Observable<Actions>) =>
-  // Translate a browser-driven POP into a success action carrying its location.
-  action$.pipe(
-    filterAction(actions.pop.type),
-    concatMap(
-      (action) =>
-        new Observable<Actions>((subscriber) => {
-          const currentLocation = action.payload.update?.location ?? stack.current;
-          subscriber.next(
-            actions.pop.success({ delta: 0, action: Action.Pop, location: currentLocation }),
-          );
-          subscriber.complete();
-        }),
-    ),
-  );

package/src/lib/state/validate-current-location.ts

@@ -1,33 +0,0 @@
-import type { Observable } from 'rxjs';
-import { map, withLatestFrom } from 'rxjs/operators';
-import type { HistoryFlowCreator } from './navigate';
-import { actions, type Actions } from './actions';
-import { filterAction } from '@equinor/fusion-observable/operators';
-import { Action, type LocationState, type HistoryStack } from '../types';
-
-/** Flow creator that validates the current stack location against reducer state. */
-export const validateCurrentLocation: HistoryFlowCreator =
-  (stack: HistoryStack) => (action$: Observable<Actions>, state$: Observable<LocationState>) =>
-    // Confirm the browser stack's current key still matches reducer state.
-    action$.pipe(
-      filterAction(actions.validateLocation.type),
-      withLatestFrom(state$),
-      map(([, state]) => {
-        const currentLocation = stack.current;
-        // Find the reducer entry matching the stack key before comparing location state.
-        const record = state.history.find(({ location }) => location?.key === currentLocation?.key);
-        // Reject validation when the browser stack key is absent from reducer state.
-        if (!record) {
-          return actions.validateLocation.failure(new Error('Stack state not found'));
-        }
-        // Reject validation when the stack and reducer carry different location state.
-        if (record.location?.state !== currentLocation?.state) {
-          return actions.validateLocation.failure(new Error('Stack state mismatch'));
-        }
-        return actions.validateLocation.success({
-          delta: 0,
-          action: Action.Pop,
-          location: currentLocation,
-        });
-      }),
-    );

package/src/lib/types.ts

@@ -1,190 +0,0 @@
-import type { Observable } from 'rxjs';
-import type { Actions } from './state/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 {@link Path} with arbitrary state data and a unique key.
- *
- * @template T - The type of the state payload stored in this location entry
- */
-// biome-ignore lint/suspicious/noExplicitAny: necessary
-export type Location<T = any> = Path & {
-  state: T;
-  key: string;
-  /** Masked path used by react-router 7.13+ for unstable view-transition masking. */
-  unstable_mask: Path | undefined;
-};
-
-/**
- * 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 the action, location, and stack delta.
- *
- * @template A - The type of navigation action (defaults to {@link Action})
- * @template T - The type of the state payload in the 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 Remix / React Router and provides observable
- * state management via RxJS.
- *
- * @example
- * ```ts
- * const history = createHistory('browser');
- * history.push('/dashboard');
- * history.state$.subscribe(update => console.log(update.location.pathname));
- * ```
- */
-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.
-   * @param to - Target path or partial path object
-   * @returns Fully-qualified href string
-   */
-  createHref(to: To): string;
-  /** Creates a {@link URL} object for a given path.
-   * @param to - Target path or partial path object
-   * @returns Resolved {@link URL} instance
-   */
-  createURL(to: To): URL;
-  /** Encodes a location by properly URL-encoding the pathname.
-   * @param to - Target path or partial path object
-   * @returns A {@link Path} with URL-encoded components
-   */
-  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.
-   * @param listener - Callback invoked on POP actions (browser back/forward)
-   * @returns A function that unsubscribes the listener when called
-   */
-  listen(listener: NavigationListener): () => void;
-  /** Registers a blocker to intercept navigation attempts.
-   * @param blocker - Callback invoked before each navigation to allow or prevent it
-   * @returns A function that removes the blocker when called
-   */
-  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

@@ -1,18 +0,0 @@
-/**
- * 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

@@ -1,21 +0,0 @@
-/**
- * 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

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

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

@@ -1,24 +0,0 @@
-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}` : ''}`;
-};