A more granular control over handling of prefers-reduced-motion

[mourner]

Motivation

There's quite a bit of confusion over GL JS handling of prefers-reduced-motion OS option (see #8288 and #8494 for background). Examples: #8716, #8648

Design

From #8494 (comment) by @andrewharvey:

could be we expose some kind of option so the app developer can say if this transition is considered essential or not?

We could add {essential: true} to animation options (false by default) that makes it animate regardless of prefers-reduced-motion. That would allow developers to fully control the experience, marking animations as essential where necessary. cc @arindam1993

[aMoniker]

You should also include an option to disable prefers-reduced-motion entirely.

Upgrading to the latest version, map panning feels broken in chrome with prefers-reduced-motion enabled - pan quickly then let go, and it snaps to what seems like the wrong location.

Personally, I have "Reduce motion" enabled in my OSX settings because I don't like the OS window transitions. That this would affect the way I can pan an embedded map on a website is unexpected and undesired.

[mourner]

@aMoniker the panning thing seems like a separate issue — I think we should disable panning inertia when disabling animation. cc @arindam1993

[aMoniker]

@mourner That sounds like it might be the solution. For now I've written an ugly hack to override the output of window.matchMedia and return false whenever (prefers-reduced-motion: reduce) is passed as a query.

[dnspnjrs]

@aMoniker are you willing to share a snippet of your ugly hack? I'm struggling with this issue in a project.

I am using the mapbox gl js in a project and I would like to ignore the prefers-reduced-motion: reduce for the flyTo.

flyTo accepts the offset: option but jumpTo does not accept this.

[aMoniker]

@dnspnjrs It's in typescript, but should work fine in plain javascript if you remove the types:

/**
 * The prefers-reduced-motion hacks below are to circumvent broken map panning
 * that was introduced when mapbox started paying attention to this:
 * https://github.com/mapbox/mapbox-gl-js/blob/master/src/util/browser.js#L60
 *
 * They may fix this issue, which might mean we can delete this hack:
 * https://github.com/mapbox/mapbox-gl-js/issues/8743
 */

let origMatchMedia: (query: string) => MediaQueryList;
const reducedMotionQuery = '(prefers-reduced-motion: reduce)';
function reducedMotionHack() {
  if (!window.matchMedia) return;
  origMatchMedia = window.matchMedia;
  window.matchMedia = matchMediaHack;
}
function matchMediaHack(query: string): MediaQueryList {
  if (query !== reducedMotionQuery) return origMatchMedia(query);
  const mql: MediaQueryList = {
    matches: false,
    media: reducedMotionQuery,
    onchange: null,
    addListener: () => null,
    removeListener: () => null,
    addEventListener: () => null,
    removeEventListener: () => null,
    dispatchEvent: () => true,
  };
  return mql;
}

Then call reducedMotionHack() once sometime during your app's initialization.

[andrewharvey]

Proposal to change the API to support an essential AnimationOption at #8883, we could then update the example at https://docs.mapbox.com/mapbox-gl-js/example/flyto-options/ to include this essential option, since to demonstrate "slowly fly to a location" it's essential that the animation occurs, to address https://github.com/mapbox/mapbox-gl-js-docs/issues/117.