navigation-stack 0.3.1 → 0.4.0

package/test/testUtil.js

@@ -0,0 +1,3 @@
+export function shouldWarn(about) {
+  console.warn.expected.push(about); // eslint-disable-line no-console
+}

package/types/data-storage/index.d.ts

@@ -0,0 +1,35 @@
+// TypeScript Version: 3.0
+
+import { Session } from '../index.d.js';
+
+export {};
+
+export type GenericValue =
+  | string
+  | number
+  | boolean
+  | Record<string, unknown>
+  | null
+  | undefined;
+
+export class DataStorage<
+  Key extends string = string,
+  Value extends GenericValue = GenericValue,
+> {
+  constructor(session: Session, options: { namespace: string });
+
+  get(key: Key): Value;
+
+  set(key: Key, value: Value): void;
+}
+
+export class LocationDataStorage<
+  Key extends string = string,
+  Value extends GenericValue = GenericValue,
+> {
+  constructor(session: Session, options: { namespace: string });
+
+  get(location: Location, key: Key): Value;
+
+  set(location: Location, key: Key, value: Value): void;
+}

package/types/index.d.ts

@@ -11,11 +11,7 @@ export type InputLocationQuery = Record<
   string | number | boolean | null | undefined
 >;
 
-export interface Location<TState = any> {
-  /**
-   * See the README on the `action` property of `location`.
-   */
-  action: 'PUSH' | 'REPLACE' | 'SHIFT' | 'INIT';
+export interface LocationBase {
   /**
    * the path name; as on window.location e.g. '/foo'
    */
@@ -32,61 +28,52 @@ export interface Location<TState = any> {
    * the location hash; as on window.location e.g. '#qux'
    */
   hash: string;
+}
+
+export interface Location extends LocationBase {
   /**
    * a unique key identifying the current history entry
    */
   key: string;
+}
+
+type PushOrReplaceOperation = 'PUSH' | 'REPLACE';
+
+export interface LocationInternal extends Location {
+  /**
+   * `navigation-stack` operation.
+   */
+  operation: PushOrReplaceOperation | 'SHIFT' | 'INIT';
   /**
    * the current index of the history entry, starting at 0 for the initial
-   * entry; this increments on FarceActions.push but not on
-   * FarceActions.replace
+   * entry; this increments on `.push()` but not on `.replace()`
    */
   index: number;
   /**
    * the difference between the current index and the index of the previous location
    */
   delta: number;
-  /**
-   * any additional location state that the application might explicitly define and store
-   */
-  state: TState;
 }
 
 /**
  * Location descriptor object used in #push and #replace.
  */
 export interface InputLocationObject {
-  pathname: Location['pathname'];
-  search?: Location['search'];
+  pathname: LocationBase['pathname'];
+  search?: LocationBase['search'];
   query?: InputLocationQuery;
-  hash?: Location['hash'];
-  state?: Location['state'];
-}
-
-export interface LocationBase {
-  pathname: Location['pathname'];
-  search: Location['search'];
-  query: Query;
-  hash: Location['hash'];
-  state?: Location['state'];
-}
-
-export interface NavigationLocation extends LocationBase {
-  action: 'PUSH' | 'REPLACE';
+  hash?: LocationBase['hash'];
 }
 
 /**
- * Location descriptor string:
- *  store.dispatch(FarceActions.push('/foo?bar=baz#qux'));
+ * Location input string: "/foo?bar=baz#qux"
  *
- * Equivalent location descriptor object:
- *    store.dispatch(FarceActions.push({
- *     pathname: '/foo',
- *     search: '?bar=baz',
- *     hash: '#qux',
- *   }));
- *
- * https://github.com/4Catalyzer/farce#locations-and-location-descriptors
+ * Equivalent location input object:
+ * {
+ *   pathname: '/foo',
+ *   search: '?bar=baz',
+ *   hash: '#qux'
+ * }
  */
 export type InputLocationString = string;
 
@@ -99,10 +86,6 @@ export interface InputLocationTypes {
 
 export type InputLocation = InputLocationTypes[keyof InputLocationTypes];
 
-export interface CreateMiddlewaresOptions {
-  basePath?: string;
-}
-
 export type NavigationBlockerSyncResult = boolean | undefined;
 export type NavigationBlockerResult =
   | NavigationBlockerSyncResult
@@ -112,13 +95,13 @@ export type NavigationBlockerResult =
  * Navigation blocker function receives a `location` to which the application (or the user) is attempting to navigate.
  *
  * * The `location` argument is `null` when the web browser tab is about to be closed.
- * * The `location` argument is of type `NavigationLocation` when a `.push()` or `.replace()` action is blocked.
+ * * The `location` argument is of type `LocationBase` when a `.push()` or `.replace()` navigation is blocked.
  * * The `location` argument is of type `Location` when blocking a navigation that was initiated outside of the application code.
  *   For example, when the user clicks "Back" or "Forward" button in a web browser.
  */
-export interface NavigationBlocker {
-  (location: Location | NavigationLocation | null): NavigationBlockerResult;
-}
+export type NavigationBlocker = (
+  location: Location | LocationBase | null,
+) => NavigationBlockerResult;
 
 // I dunno why did they use an `interface` here.
 export interface BeforeLocationChangeListener {
@@ -137,166 +120,204 @@ export function removeBasePath<L extends InputLocation>(
 export function getLocationUrl(location: InputLocationObject): string;
 export function parseLocationUrl(locationUrl: string): LocationBase;
 
-export function createMiddlewares(
-  session: SessionBase,
-  options?: CreateMiddlewaresOptions,
-): Middleware[];
+export function parseInputLocation(location: InputLocation): LocationBase;
 
 export function addNavigationBlocker(
-  session: SessionBase,
+  session: Session,
   blocker: NavigationBlocker,
 ): () => void;
 
-export function addBeforeLocationChangeListener(
-  session: SessionBase,
-  listener: BeforeLocationChangeListener,
-): () => void;
-
-export const ActionTypes: {
-  INIT: '@@navigation-stack/INIT';
-  PUSH: '@@navigation-stack/PUSH';
-  REPLACE: '@@navigation-stack/REPLACE';
-  NAVIGATE: '@@navigation-stack/NAVIGATE';
-  SHIFT: '@@navigation-stack/SHIFT';
-  UPDATE: '@@navigation-stack/UPDATE';
-  DISPOSE: '@@navigation-stack/DISPOSE';
-};
-
-export interface InitAction {
-  type: (typeof ActionTypes)['INIT'];
+export interface NavigationStackOptions {
+  basePath?: string;
+  maintainScrollPosition?: boolean;
 }
 
-export interface PushAction {
-  type: (typeof ActionTypes)['PUSH'];
-  payload: InputLocation;
-}
+export class NavigationStack<ScrollableContainer = any, Anchor = any> {
+  constructor(
+    session: Session<ScrollableContainer, Anchor>,
+    options?: NavigationStackOptions,
+  );
 
-export interface ReplaceAction {
-  type: (typeof ActionTypes)['REPLACE'];
-  payload: InputLocation;
-}
+  addScrollableContainer(
+    scrollableContainerKey: string,
+    scrollableContainer: ScrollableContainer,
+  ): () => void;
+
+  subscribe(listener: (location: Location) => void): () => void;
+
+  current(): Location;
 
-export interface RewindAction {
-  type: (typeof ActionTypes)['SHIFT'];
-  payload: number;
+  init(initialLocation?: InputLocation): void;
+
+  push(location: InputLocation): void;
+
+  replace(location: InputLocation): void;
+
+  shift(delta: number): void;
+
+  locationRendered(): void;
+
+  stop(): void;
 }
 
-export interface DisposeAction {
-  type: (typeof ActionTypes)['DISPOSE'];
+export type SessionTerminationBlocker = () => boolean | undefined;
+
+interface SessionExecutionStatusListenerParameters {
+  running: boolean;
 }
 
-export type Action =
-  | InitAction
-  | PushAction
-  | ReplaceAction
-  | RewindAction
-  | DisposeAction;
+export type SessionExecutionStatusListener = (
+  parameters: SessionExecutionStatusListenerParameters,
+) => void;
 
-export const Actions: {
-  init(): InitAction;
-  push(location: InputLocation): PushAction;
-  replace(location: InputLocation): ReplaceAction;
-  shift(delta: number): RewindAction;
-  dispose(): DisposeAction;
-};
+export type ScrollListener = () => void;
 
-type BeforeDestroyListener = () => boolean | undefined;
+export class ServerSideNavigationError extends Error {
+  constructor(location: LocationBase);
 
-interface SessionNavigation {
-  init(): void;
+  location: LocationBase;
+}
 
-  // Subscribes to changes in location,
-  // excluding ones that happened as a result of calling `.navigate()`.
-  subscribe(listener: (location: Location) => void): () => void;
+export class NavigationOutOfBoundsError extends Error {
+  constructor(index: number);
 
-  navigate(location: NavigationLocation): Location;
+  index: number;
+}
 
-  shift(delta: number): void;
+export class Navigation {
+  // Subscribes to "location change" events.
+  subscribe(listener: (location: LocationInternal) => void): () => void;
+
+  init(
+    initialLocation: LocationBase,
+    parameters: Pick<
+      LocationInternal,
+      'operation' | 'key' | 'index' | 'delta'
+    >,
+  ): LocationInternal | undefined;
+
+  navigate(
+    location: LocationBase,
+    parameters: Pick<
+      LocationInternal,
+      'operation' | 'key' | 'index' | 'delta'
+    >,
+  ): LocationInternal | undefined;
+
+  shift(
+    parameters: Pick<LocationInternal, 'operation' | 'index' | 'delta'>,
+  ): LocationInternal | undefined;
+
+  getInitialLocation(): InputLocation | undefined;
 }
 
-interface SessionDataStorage {
+export interface EnvironmentDataStorage {
   get(key: string): string | null;
   remove(key: string): void;
   set(key: string, value: string): void;
 }
 
-export interface Session {
-  navigation: SessionNavigation;
-  dataStorage: SessionDataStorage;
-  addBeforeDestroyListener(listener: BeforeDestroyListener): void;
+export interface SessionLifecycle {
+  addTerminationBlocker(blocker: SessionTerminationBlocker): () => void;
+  addExecutionStatusListener(
+    listener: SessionExecutionStatusListener,
+  ): () => void;
+}
+
+// Manages scroll position in an environment such as a web browser.
+export interface EnvironmentScrollPosition<ScrollableContainer, Anchor> {
+  // Gets numeric scroll position of a page.
+  getPageScrollPosition(): [number, number];
+  // Sets numeric scroll position of a page.
+  setPageScrollPosition(scrollPosition: [number, number]): void;
+  // Sets scroll position of a page to be at an "anchor".
+  setPageScrollPositionAtAnchor(anchor: Anchor): void;
+  // Gets numeric scroll position of a scrollable element.
+  getScrollableContainerScrollPosition(
+    scrollableContainer: ScrollableContainer,
+  ): [number, number];
+  // Sets numeric scroll position of a scrollable element.
+  setScrollableContainerScrollPosition(
+    scrollableContainer: ScrollableContainer,
+    scrollPosition: [number, number],
+  ): void;
+  // Adds "on scroll" listeners.
+  addPageScrollListener(listener: ScrollListener): () => void;
+  addScrollableContainerScrollListener(listener: ScrollListener): () => void;
+  // These methods could be used to disable environment's automatic scroll position restoration feature,
+  // such as the one present in web browsers, so that the code could control it manually.
+  enableAutomaticScrollRestoration(): void;
+  disableAutomaticScrollRestoration(): void;
+  // `init()` is called every time when a new page is rendered.
+  init(): void;
+}
 
-  // These're internal variables that're manually set under the hood.
-  // _beforeLocationChangeListenersList?: Array<BeforeLocationChangeListener>;
-  // _navigationBlockersList?: Array<NavigationBlocker>;
-  // _removeBeforeDestroyListener?: () => void;
-  // _navigationBlockersEvaluationStatus?: { cancelled?: boolean };
+export interface Environment<ScrollableContainer, Anchor> {
+  dataStorage: EnvironmentDataStorage;
+  scrollPosition: EnvironmentScrollPosition<ScrollableContainer, Anchor>;
 }
 
-// This is just a copy-paste of the `session` interface above.
-declare abstract class SessionBase implements Session {
-  navigation: SessionNavigation;
+export interface Session<ScrollableContainer = any, Anchor = any> {
+  // `key` should be unique within `environment.dataStorage`.
+  // For example, `BrowserEnvironment` uses `window.sessionStorage`
+  // that is shared across different sessions within a given web browser tab,
+  // hence the uniqueness requirement.
+  key: string;
 
-  dataStorage: SessionDataStorage;
+  // Private varibles. Not public API.
+  environment: Environment<ScrollableContainer, Anchor>;
 
-  addBeforeDestroyListener(listener: BeforeDestroyListener): void;
+  lifecycle: SessionLifecycle;
 
-  // These're internal variables that're manually set under the hood.
-  // _beforeLocationChangeListenersList?: Array<BeforeLocationChangeListener>;
-  // _navigationBlockersList?: Array<NavigationBlocker>;
-  // _removeBeforeDestroyListener?: () => void;
-  // _navigationBlockersEvaluationStatus?: { cancelled?: boolean };
-}
+  subscribe(listener: (location: LocationInternal) => void): () => void;
 
-export class BrowserSession extends SessionBase {}
+  start(initialLocation?: LocationBase): void;
 
-export interface MemorySessionOptions {
-  save?: (data: string) => void;
-  load?: () => string | undefined | null;
-}
+  stop(): void;
 
-export class ServerSession extends SessionBase {
-  constructor(initialLocation: InputLocation);
-}
+  navigate(operation: PushOrReplaceOperation, location: LocationBase): void;
 
-export class MemorySession extends SessionBase {
-  constructor(initialLocation: InputLocation, options?: MemorySessionOptions);
+  shift(delta: number): void;
 }
 
-export const locationReducer: Reducer<Location, Action>;
+// This is just a copy-paste of the `session` interface above.
+declare abstract class SessionBaseClass<
+  ScrollableContainer = any,
+  Anchor = any,
+> implements Session<ScrollableContainer, Anchor>
+{
+  constructor(parameters: { navigation: Navigation });
+
+  // `key` should be unique within `environment.dataStorage`.
+  // For example, `BrowserEnvironment` uses `window.sessionStorage`
+  // that is shared across different sessions within a given web browser tab,
+  // hence the uniqueness requirement.
+  key: string;
 
-export class LocationDataStorage {
-  constructor(session: Session, options: { namespace: string });
+  // Private varibles. Not public API.
+  environment: Environment<ScrollableContainer, Anchor>;
 
-  get(location: Location, key: string): any;
+  lifecycle: SessionLifecycle;
 
-  set(location: Location, key: string, value: any): void;
-}
+  subscribe(listener: (location: LocationInternal) => void): () => void;
 
-// The following types are copy-pasted from `redux`.
+  start(initialLocation?: LocationBase): void;
 
-interface ReduxAction<T = any> {
-  type: T;
-}
+  stop(): void;
 
-interface AnyAction extends ReduxAction {
-  // Allows any extra properties to be defined in an action.
-  [extraProps: string]: any;
-}
+  navigate(operation: PushOrReplaceOperation, location: LocationBase): void;
 
-interface Dispatch<A extends Action = AnyAction> {
-  <T extends A>(action: T): T;
+  shift(delta: number): void;
 }
 
-interface MiddlewareAPI<D extends Dispatch = Dispatch, S = any> {
-  dispatch: D;
-  getState(): S;
+export class WebBrowserSession extends SessionBaseClass<HTMLElement, string> {
+  constructor();
 }
 
-interface Middleware<S = any, D extends Dispatch = Dispatch> {
-  (api: MiddlewareAPI<D, S>): (next: Dispatch) => (action: any) => any;
+export class ServerSideRenderSession extends SessionBaseClass<string, string> {
+  constructor();
 }
 
-type Reducer<S = any, A extends Action = AnyAction> = (
-  state: S | undefined,
-  action: A,
-) => S;
+export class InMemorySession extends SessionBaseClass<string, string> {
+  constructor();
+}

package/types/redux/index.d.ts

@@ -0,0 +1,90 @@
+import { InputLocation, Session } from '../index.d.js';
+
+export interface CreateMiddlewaresOptions {
+  basePath?: string;
+}
+
+export function createMiddlewares(
+  session: Session,
+  options?: CreateMiddlewaresOptions,
+): Middleware[];
+
+export const ActionTypes: {
+  INIT: '@@navigation-stack/INIT';
+  PUSH: '@@navigation-stack/PUSH';
+  REPLACE: '@@navigation-stack/REPLACE';
+  NAVIGATE: '@@navigation-stack/NAVIGATE';
+  SHIFT: '@@navigation-stack/SHIFT';
+  UPDATE: '@@navigation-stack/UPDATE';
+  STOP: '@@navigation-stack/STOP';
+};
+
+export interface InitAction {
+  type: (typeof ActionTypes)['INIT'];
+  payload?: InputLocation;
+}
+
+export interface PushAction {
+  type: (typeof ActionTypes)['PUSH'];
+  payload: InputLocation;
+}
+
+export interface ReplaceAction {
+  type: (typeof ActionTypes)['REPLACE'];
+  payload: InputLocation;
+}
+
+export interface ShiftAction {
+  type: (typeof ActionTypes)['SHIFT'];
+  payload: number;
+}
+
+export interface DisposeAction {
+  type: (typeof ActionTypes)['STOP'];
+}
+
+export type Action =
+  | InitAction
+  | PushAction
+  | ReplaceAction
+  | ShiftAction
+  | DisposeAction;
+
+export const Actions: {
+  init(initialLocation?: InputLocation): InitAction;
+  push(location: InputLocation): PushAction;
+  replace(location: InputLocation): ReplaceAction;
+  shift(delta: number): ShiftAction;
+  stop(): DisposeAction;
+};
+
+export const locationReducer: Reducer<Location, Action>;
+
+// The following types are copy-pasted from `redux`.
+
+interface ReduxAction<T = any> {
+  type: T;
+}
+
+interface AnyAction extends ReduxAction {
+  // Allows any extra properties to be defined in an action.
+  [extraProps: string]: any;
+}
+
+interface Dispatch<A extends Action = AnyAction> {
+  <T extends A>(action: T): T;
+}
+
+interface MiddlewareAPI<D extends Dispatch = Dispatch, S = any> {
+  dispatch: D;
+  getState(): S;
+}
+
+interface Middleware<S = any, D extends Dispatch = Dispatch> {
+  (api: MiddlewareAPI<D, S>): (next: Dispatch) => (action: any) => any;
+}
+
+type Reducer<S = any, A extends Action = AnyAction> = (
+  state: S | undefined,
+  action: A,
+) => S;

package/types/scroll-position/index.d.ts

@@ -0,0 +1,107 @@
+// TypeScript Version: 3.0
+
+import { EnvironmentScrollPosition, Location, Session } from '../index.d.js';
+
+export { EnvironmentScrollPosition, Location, Session } from '../index.d.js';
+
+export {};
+
+export class ScrollPositionRestoration<
+  ScrollableContainer = any,
+  Anchor = any,
+> {
+  constructor(
+    session: Session<ScrollableContainer, Anchor>,
+
+    // `_options` are currently only used in tests.
+    _options?: {
+      // `_options._shouldUpdatePageScrollPositionForLocation`
+      // isn't used in real life and is not part of the public API.
+      // It's only used in tests.
+      _shouldUpdatePageScrollPositionForLocation?: (
+        location: Location,
+        prevLocation: Location | undefined,
+      ) => boolean;
+
+      // `_options._getPageScrollPositionForLocation`
+      // isn't used in real life and is not part of the public API.
+      // It's only used in tests.
+      _getPageScrollPositionForLocation?: (
+        location: Location,
+        prevLocation: Location | undefined,
+      ) => boolean;
+
+      // Using this option, a developer could theoretically provide their own implementation
+      // of setting a scroll position. For example, it could use "smooth" (animated) scrolling, etc.
+      // This could be part of the public API if anyone provided a sensible real-world use case for it.
+      _pageScrollPositionSetter: ScrollPositionSetter<
+        ScrollableContainer,
+        Anchor
+      >;
+    },
+  );
+
+  addScrollableContainer(
+    scrollableContainerKey: string,
+    scrollableContainer: ScrollableContainer,
+
+    // `_options` are currently only used in tests.
+    _options?: {
+      // `_options._shouldUpdateScrollPositionForLocation`
+      // isn't used in real life and is not part of the public API.
+      // It's only used in tests.
+      _shouldUpdateScrollPositionForLocation?: (
+        location: Location,
+        prevLocation: Location | undefined,
+      ) => boolean;
+
+      // `_options._getScrollPositionForLocation`
+      // isn't used in real life and is not part of the public API.
+      // It's only used in tests.
+      _getScrollPositionForLocation?: (
+        location: Location,
+        prevLocation: Location | undefined,
+      ) => boolean;
+
+      // Using this option, a developer could theoretically provide their own implementation
+      // of setting a scroll position. For example, it could use "smooth" (animated) scrolling, etc.
+      // This could be part of the public API if anyone provided a sensible real-world use case for it.
+      _scrollPositionSetter: ScrollPositionSetter<ScrollableContainer, Anchor>;
+    },
+  ): () => void;
+
+  locationRendered: (location: Location) => void;
+
+  stop(): void;
+
+  // `_enableSavingScrollPosition()` and `_disableSavingScrollPosition()`
+  // aren't used in real life and are not part of the public API.
+  // They're only used in tests.
+  _enableSavingScrollPosition(): void;
+
+  // `_enableSavingScrollPosition()` and `_disableSavingScrollPosition()`
+  // aren't used in real life and are not part of the public API.
+  // They're only used in tests.
+  _disableSavingScrollPosition(): void;
+}
+
+// Theoretically, a developer could pass their own `ScrollPositionSetter` implementation
+// when calling `.addScrollableContainer()` or
+export interface ScrollPositionSetter<ScrollableContainer, Anchor> {
+  // Sets scroll position of a page or a scrollable element.
+  // Returns a `Promise` that resolves when it has finished setting the scroll position.
+  set(
+    // When setting page scroll position, `scrollableContainer` is `undefined`.
+    // When setting scrollable element scroll position, `scrollableContainer` is the scrollable element.
+    scrollableContainer: ScrollableContainer,
+    // When setting page scroll position, it could be either an anchor or numeric coordinates.
+    // When setting scrollable element scroll position, it could only be numeric coordinates.
+    scrollPositionOrAnchor: Anchor | [number, number],
+    // `scrollPosition` provides the API for setting scroll position according to the environment.
+    // For example, `WebBrowserScrollPosition` provides the methods for setting scroll position in a web browser.
+    scrollPosition: EnvironmentScrollPosition<ScrollableContainer, Anchor>,
+  ): Promise<void>;
+
+  // Cancels any pending (or in-progress) setting of scroll position.
+  cancel(): void;
+}