Transition API

[ryanflorence]

After registering a transition hook, there are two cases when transitioning away from a location:

1. the user does something to cause onbeforeunload (like closing the window)
2. the user does something to transition somewhere else in the app

In the case of (1), the only thing we can do is provide a string to onbeforeunload to get a confirmation from the user (https://developer.mozilla.org/en-US/docs/Web/API/WindowEventHandlers/onbeforeunload).

In the case of (2) we could allow the developer to do anything they want.

Currently history only handles case (1) with a bit of indirection between creating the history and registering hooks.

A strawman API to allow for both, and remove the indirection could look something like:

// callback with a string and both cases get a confirmation dialog
history.registerTransitionHook((isUnload, cb) => {
  cb("you sure you want to leave?");
});

// if you want to do something fancy for case (2)
history.registerTransitionHook((isUnload, cb) => {
  // if its an unload event you must do things synchronously
  if (isUnload) {
    cb("you sure?")
  }
  else {
    // do something fancier than window.confirm
    cb(true) // allow the transition
    cb(false) // cancel the transition
  }
});

With this API there would be no need for getUserConfirmation and we could allow devs more freedom when transitioning inside the app instead of restricting them to the constraints of onbeforeunload in all cases.

[mjackson]

Currently history only handles case (1)

We actually support both (1) and (2) with the current API.

The getUserConfirmation API was prompted by the fact that, on most platforms, there's usually one standard way to prompt a user for confirmation:

• window.confirm in browsers
• UIAlertView on iOS < 8
• UIAlertController on iOS 8
• AlertDialog on Android

On all of these platforms, we can provide a sane default and the vast majority of users never actually have to know about getUserConfirmation. All they have to know is "I need to return a string from one of my transition hooks if I don't want the transition to take place". We could easily support return false as well. Users don't need to know anything about callbacks or other args in their transition hooks.

Advanced users can still display their own custom dialog inside getUserConfirmation. The only case where this API is a little tricky is when they need to show different custom confirmation dialogs based on context. This requires a bit more work because they need to keep track of where they currently are in the app and show the corresponding dialog.

My questions are:

1. Is it worth making the simple top-level API more complex for the needs of (what I believe is) a small percentage of users? We're talking about a subset (those who want to display different dialogs based on context) of a subset (those who want to use custom dialogs) of our users.
2. Should we be encouraging users to show different confirmation dialogs based on context? Feels like a poor design decision, and one that most apps don't actually make.

[ryanflorence]

Is it worth making the simple top-level API more complex

Probably not.

Lets wait for people to complain.

[fkrauthan]

Well there are a bunch of good examples where you want custom dialog's. Think about a react application that has a sign up and a chat (e.g. Slack). Now on signup you might wanna warn the user that he looses all his data if he leaves. On the chat you want him to make a decision between do you wanna throw your message away or send it before leaving or cancel leaving at all. For that you need to have the capabilities to show context based custom dialog's. And I am sure there are tons of other use-cases too where you need that.