page-param.ts

import { BootstrapContext } from '@wesib/wesib';
import { Page } from './page';

/**
 * A key of {@link PageParam.Ref page parameter request} property containing requested page parameter.
 */
export const PageParam__symbol = /*#__PURE__*/ Symbol('PageParam');

/**
 * Page navigation parameter.
 *
 * Can applied before navigation happened (i.e. to {@link LeavePageEvent}). Then it will be available to the target page
 * both before and after navigation.
 *
 * @typeParam T - Parameter value type.
 * @typeParam TInput - Parameter input type.
 */
export abstract class PageParam<T, TInput> implements PageParam.Ref<T, TInput> {

  get [PageParam__symbol](): this {
    return this;
  }

  /**
   * Creates page parameter handle.
   *
   * This method is called when {@link Page.put assigning new page parameter}. It is called at most once per request,
   * unless this parameter is assigned already. A {@link PageParam.Handle.put} method will be called instead
   * in the latter case.
   *
   * @param page - A page to assign navigation parameter to.
   * @param input - Parameter input used to construct its initial value.
   * @param bsContext - Bootstrap context.
   *
   * @returns New page parameter value handle.
   */
  abstract create(
    page: Page,
    input: TInput,
    bsContext: BootstrapContext,
  ): PageParam.Handle<T, TInput>;

  /**
   * Creates default page parameter handle.
   *
   * This method is called when {@link Page.get requesting page parameter} which value is not present in the page.
   * The value handle returned is assigned to the page.
   *
   * Returns nothing by default.
   *
   * @param _page - A page to assign navigation parameter to.
   * @param _bsContext - Bootstrap context.
   *
   * @returns New page parameter value handle or nothing if there is no default value.
   */
  byDefault(_page: Page, _bsContext: BootstrapContext): PageParam.Handle<T, TInput> | undefined {
    return;
  }

}

export namespace PageParam {
  /**
   * Page navigation parameter reference.
   *
   * @typeParam T - Parameter value type.
   * @typeParam TInput - Parameter input type.
   */
  export interface Ref<T, TInput> {
    /**
     * Referred page navigation parameter instance.
     */
    readonly [PageParam__symbol]: PageParam<T, TInput>;
  }

  /**
   * Page navigation parameter that has default value.
   *
   * @typeParam T - Parameter value type.
   * @typeParam TInput - Parameter input type.
   */
  export interface WithDefaults<T, TInput> extends PageParam<T, TInput> {
    byDefault(page: Page, bsContext: BootstrapContext): PageParam.Handle<T, TInput>;
  }

  export namespace WithDefaults {
    /**
     * A reference to page navigation parameter that has default value.
     *
     * @typeParam T - Parameter value type.
     * @typeParam TInput - Parameter input type.
     */
    export interface Ref<T, TInput> {
      /**
       * Referred page navigation parameter instance.
       */
      readonly [PageParam__symbol]: WithDefaults<T, TInput>;
    }
  }

  /**
   * Page navigation parameter value handle.
   *
   * Holds and maintains parameter value.
   *
   * Created by {@link PageParam.create} method.
   *
   * @typeParam T - Parameter value type.
   * @typeParam TInput - Parameter input type.
   */
  export interface Handle<T, TInput> {
    /**
     * Returns current parameter value.
     *
     * @returns Parameter value.
     */
    get(): T;

    /**
     * Puts page parameter value.
     *
     * This method is called when {@link Page.put re-assigning page parameter}. It is called when page parameter
     * is assigned already and can be used to update it. The update logic is up to the implementation.
     *
     * @param input - Parameter input to use when updating its value.
     */
    put(input: TInput): void;

    /**
     * Transfers parameter to target page.
     *
     * This is called right before {@link LeavePageEvent} is fired for each parameter handle of current page.
     *
     * @param to - A page to transfer parameter to.
     * @param when - When the transfer happens. Either `pretend`, `pre-open`, `pre-replace`, `open`, or `return`.
     * `return` is used when return to page generated by another app version. E.g. from the page that has been
     * reloaded.
     *
     * @returns New parameter handle instance for target page, or `undefined` if nothing to transfer.
     */
    transfer?(
      to: Page,
      when: 'pretend' | 'pre-open' | 'pre-replace' | 'enter' | 'return',
    ): Handle<T, TInput> | undefined;

    /**
     * This method is called when the page this parameter created for is entered.
     *
     * @param page - Entered page.
     * @param when - When the page is entered. Either `init`, `open`, `replace`, `enter`, or `return`.
     */
    enter?(page: Page, when: 'init' | 'open' | 'replace' | 'enter' | 'return'): void;

    /**
     * This method is called when the page this parameter created for is left.
     */
    leave?(): void;

    /**
     * This method is called when page navigation aborted and target page won't be reached.
     *
     * The handle won't be accessed after this method call.
     *
     * @param at - The page the browser remains at.
     */
    stay?(at: Page): void;

    /**
     * This method is called when the page this parameter is created for is removed from navigation history.
     *
     * The handle won't be accessed after this method call.
     */
    forget?(): void;
  }
}