message: docs: document history
diff: @@ -46,7 +46,9 @@ export interface NavigationCallback {
  ): void
  }
  -// starting point for abstract history
  +/**
  + * Starting location for Histories
  + */
  const START_PATH = ''
  export const START: HistoryLocationNormalized = {
  fullPath: START_PATH,
  @@ -54,19 +56,81 @@ export const START: HistoryLocationNormalized = {
  export type ValueContainer<T> = { value: T }
  +/**
  + * Interface implemented by History implementations that can be passed to the
  + * router as {@link Router.history}
  + *
  + * @alpha
  + */
  export interface RouterHistory {
  + /**
  + * Base path that is prepended to every url. This allows hosting an SPA at a
  + * subfolder of a domain like `example.com/subfolder` by having a `base` of
  + * `/subfolder`
  + */
  readonly base: string
  + /**
  + * Current History location
  + */
  readonly location: HistoryLocationNormalized
  + /**
  + * Current History state
  + */
  readonly state: HistoryState
  // readonly location: ValueContainer<HistoryLocationNormalized>
  + /**
  + * Navigates to a location. In the case of an HTML5 History implementation,
  + * this will call `history.pushState` to effectively change the URL.
  + *
  + * @param to - location to push
  + * @param data - optional {@link HistoryState} to be associated with the
  + * navigation entry
  + */
  push(to: RawHistoryLocation, data?: HistoryState): void
  + /**
  + * Same as {@link RouterHistory.push} but performs a `history.replaceState`
  + * instead of `history.pushState`
  + *
  + * @param to - location to set
  + * @param data - optional {@link HistoryState} to be associated with the
  + * navigation entry
  + */
  replace(to: RawHistoryLocation, data?: HistoryState): void
  + /**
  + * Goes back in history
  + *
  + * @param triggerListeners - whether this should trigger listeners attached to
  + * the history
  + */
  back(triggerListeners?: boolean): void
  + /**
  + * Goes forward in history
  + *
  + * @param triggerListeners - whether this should trigger listeners attached to
  + * the history
  + */
  forward(triggerListeners?: boolean): void
  + /**
  + * Traverses history in a given direction
  + *
  + * @param distance - distance to travel. If distance is \< 0, it will go back,
  + * if it's \> 0, it will go forward
  + * @param triggerListeners - whether this should trigger listeners attached to
  + * the history
  + */
  go(distance: number, triggerListeners?: boolean): void
  + /**
  + * Attach a listener to the History implementation that is triggered when the
  + * navigation is triggered from outside (like the Browser back and forward
  + * buttons) or when passing `true` to {@link RouterHistory.back} and
  + * {@link RouterHistory.forward}
  + *
  + * @param callback - listener to attach
  + * @returns a callback to remove the listener
  + */
  listen(callback: NavigationCallback): () => void
  destroy(): void
  }
  