Popper 3: Pure, incrementally adoptable APIs?

[atomiks]

@FezVrasta made some comments about cutting a potential release just to refresh the build setup (mainly, just use .mjs for /lib & esm), and it got me thinking about a potential direction for the library which could improve it. This is entirely my own thoughts, and not @FezVrasta, and is here mainly for initial discussion.

The main concern people have with Popper is size. As we need to support more edge cases, the bundle size grows, even if 99% of consumers won't even notice nor care. Sometimes we have to assess whether it's worth even fixing an edge case because of this.

Edge cases

Popper supports a lot of edge cases. A browser extension author needs to support 100% of edge cases because of the fact that their extension works on 3rd party sites they have no control over; but a developer of a particular web app with particular conventions might not need half the code used to handle those edge cases. Perfect example: #1375

Extensibility

A lot of the size of Popper is the core used to handle ordering modifiers, phases, setting up the instance, etc. This is great for extensibility but based on the actual usage of this extensibility, it seems minimal on npm. Mostly it's used to hack something on, or fix some issue. People just use what's in core; there don't seem to be any community modifiers.

Modifiers

Modifiers could be more modular by forgoing an options object for functionality plugins that create the options, which can be tree-shaken away.

---

Proposal

I want to preface this by saying I think a stateful, works out-of-the-box createPopper should remain in the package. This is true for libs like Bootstrap that want to abstract Popper away and focus less on the low level parts of Popper for their consumers. But if Popper really wants to go super low level, I think this is the way to go. Maybe this could also enable React Native support better?! 👀

Largely I was inspired by the purity of Popmotion, compared to say anime.js. This makes Popper go more in the direction of the former.

import {position} from '@popperjs/core';

const {x, y} = position(button, tooltip, {
  placement: 'bottom',
});

// Already has `position: absolute`, etc
tooltip.style.transform = `translate3d(${x}px, ${y}px, 0)`;

There's no state, not even eventListeners or applyStyles, nor handling of scrolling parents, offsetParent, etc. It's 100% pure, and there are no modifiers — yet. Instead, everything is incrementally adoptable.

import {position, flip} from '@popperjs/core';

const {x, y} = position(button, tooltip, {
  placement: 'bottom',
  modifiers: [flip],
});

What about DOM handling? Splitting this out could better allow us to investigate supporting React Native.

import {position, scrollParent} from '@popperjs/core';

const {x, y} = position(button, tooltip, {
  placement: 'bottom',
  // Plugins that handle DOM scenarios and other edge cases
  dom: [scrollParent],
});

Some modifier options are unused/irrelevant for some situations. This means you create the modifier by passing it plugins to create the functionality (or options) — once again enabling tree-shaking.

import {createFlip, allowedAutoPlacements} from '@popperjs/core/flip';

const flip = createFlip([allowedAutoPlacements]);

Further, modifiers themselves are now extensible; you need to replace the whole modifier with the current architecture.

The biggest benefit here as mentioned is size. You only use what you need from Popper, and it's so low level that it acts more like "primitives" to build your positioning behavior.

What do you think about this type of API? Thankfully, Popper 2's codebase is in a good state and would allow this to be explored via refactoring without too much trouble. If people are interested in this direction, I can begin investigating. ✌️

[FezVrasta]

I like the idea but I don't think I understand what's the difference between position() and the existing createPopper with no modifiers applied?

[atomiks]

position would be pure, functional and much smaller in size than createPopper since it doesn't need to order modifiers or store state (like scrollParents, etc.), and is lower level by directly returning offsets. You need to hook up a bunch of modifiers to get the functionality in v2, like completely replacing the computeStyles modifier, etc.

[FezVrasta]

I see, it makes sense to me. We just need to find a way to reuse the same logic in the two different interfaces.

[FezVrasta]

I wonder if we could also extract the modifiers ordering logic into its own function so one could do:

import {position, flip, orderModifiers} from '@popperjs/core';

const {x, y} = position(button, tooltip, {
  placement: 'bottom',
  modifiers: orderModifiers([flip, preventOverflow]),
});

[FezVrasta]

I'm not sure about the dom: [] part though, I think this should be handled by dedicated React Native modifiers instead.

[atomiks]

The idea behind dom (the property name or way it's used entirely can be different) is that out of the box, position wouldn't look for scrollParents. This allows the most basic usage to work, like adding tooltips to a small landing page that has no scrollable containers, keeping things super lightweight. These wouldn't be modifiers, but rather "considerations" to fix positioning.

By importing dom "considerations", you make Popper start taking into account certain layout or CSS of the DOM. Once users get more complex with their layouts, and find the positioning does not work for a scenario, then they import the necessary functionality and add it to the array. Otherwise, it gets tree-shaken away, resulting in no bundle size cost.

I think it's hard to implement React Native logic as a modifier, because the DOM code would be more interlinked if it doesn't get split out and need to be imported separately. (Splitting it out would ensure the architecture stays more agnostic).

[atomiks]

More architectural ideas

Modifier mutations are entirely order-based and pure for the consumer

Currently, modifiers directly mutate modifiersData.popperOffsets and provide their own data to let other modifiers know what they did, so they can account for the mutation they performed. e.g. preventOverflow needing to know the mutations that offset did to work correctly.

This can be made pure and less prone to bugs in the following way (inside position function):

  let offsets = initialOffsetsFromPlacement;

  modifiers.forEach((modifier) => {
    offsets = modifier.getOffsets({
        ...options,
        // As long as the order is correct, the modifier
        // will start from the right place.
        offsets,
        rects: {
          popper: popperRect,
          reference: referenceRect,
        },
      });
  });

Now, preventOverflow uses the current offsets without needing to search for the data that offset and other modifiers provide:

// super basic example
const preventOverflow = (features) => {
  return {
    name: 'preventOverflow',
    getOffsets({placement, rects, offsets}) {
      const windowWidth = window.innerWidth;
      const windowHeight = window.innerHeight;
 
      // already takes into account the `offset` modifier because of the ordering
      let x = offsets.x;
      let y = offsets.y;

      x = Math.max(0, x);
      y = Math.max(0, y);

      if (x + rects.popper.width > windowWidth) {
        x = windowWidth - rects.popper.width;
      }
      if (y + rects.popper.height > windowHeight) {
        y = windowHeight - rects.popper.height;
      }

      return {x, y};
    },
  };
};

Modifiers are functions that take self-modifiers, aka options, as an array of features

This enables tree-shaking at a far more modular level than popper-lite configuration could:

import {position} from '@popperjs/core';
import {offset, skiddingDistanceTuple} from '@popperjs/core/offset';
import {preventOverflow, tether} from '@popperjs/core/preventOverflow';

const {x, y} = position(reference, popper, {
  placement: 'bottom',
  modifiers: [
    offset([skiddingDistanceTuple([0, 10])]),
    preventOverflow([
      tether({
        offset: {
          mainAxis: 10,
          altAxis: 0,
        },
      }),
    ]),
  ],
});

Example implementation of the features, where we use a tuple:

  const skiddingDistanceTuple = (tuple) => ({ placement, rects, options }) =>
    distanceAndSkiddingToXY(placement, rects, tuple);

  const offset = (features) => {
    return {
      name: 'offset',
      getOffsets({placement, rects, offsets}) {
        let modifiedOffsets = {x: 0, y: 0};

        features.forEach((feature) => {
          modifiedOffsets = feature({placement, rects, offsets: modifiedOffsets});
        });

        return {
          x: offsets.x + modifiedOffsets.x,
          y: offsets.y + modifiedOffsets.y,
        };
      },
    };
  };

Based on this type of architecture the new slogan could be Positioning primitives for tooltips and popovers (or floating elements, to be more generic but less SEO friendly).

As I work on more modifiers, I might need to change some ideas here, but I think this more pure/functional way to operate is more powerful, extensible and will be less buggy.

As far as the DOM splitting goes, I still need to explore this.

[FezVrasta]

Currently, modifiers directly mutate modifiersData.popperOffsets and provide their own data to let other modifiers know what they did, so they can account for the mutation they performed. e.g. preventOverflow needing to know the mutations that offset did to work correctly.

This approach would be a bit limiting IMHO, right now modifiers can store as many data as they want and share it across them.

[atomiks]

Yeah I implemented a couple more modifiers and had to provide a data object, which I've added in.

Currently the return is:

const {x, y, data} = position(...);

// data = modifiersData
arrow.style.transform = `translate3d(${data.arrow?.offset ?? 0}px, 0, 0)`;

[atomiks]

Right now every modifier returns a diff of what they did to the main x, y offsets, but they don't mutate anything, they just return it for purity. The diff represents a cumulative change to the x & y values compared to if there were no modifiers (aka the core placement offset logic).

Modifiers use the current offsets though which makes their logic way smaller to write. I just wrote the size modifier without needing to check for any data

[atomiks]

After further iteration, I realized the modifiers could be simplified even further. Now, every "feature" is really its own modifier. preventOverflow => shift:

import {position, dom, shiftMainAxis, shiftTether} from '@popperjs/core';

const button = document.querySelector('#button');
const tooltip = document.querySelector('#tooltip');

const {x, y} = position(button, tooltip, {
  platform: dom,
  modifiers: [shiftMainAxis(), shiftTether()],
});

Object.assign(tooltip.style, {
  position: "absolute",
  top: `${x}px`,
  left: `${y}px`,
});

This modularizes v2's options into their own modifiers so they can be tree-shaken away.

dom is an object containing methods that position uses to get the rects of the elements of the given platform, to make Popper agnostic. Currently, it's:

export default {
  getReferenceRect: getCompositeRect,
  getPopperRect: getLayoutRect
};

Inside position():

const referenceRect = platform.getReferenceRect({
  element: reference,
  context: popper,
  strategy: options.strategy,
});
const popperRect = platform.getPopperRect({
  element: popper 
});

I've never used React Native, so I have no idea if the object being passed as an argument is sufficient for it to get the "rects" in the native platform. This is something that needs to be tested. I've made it an object so it can be extended if necessary.

Edit: started reading RN docs. It looks like our rect objects match the shape of the object given by RN, which is provided by onLayout to <View />. But, to make it work with the position API is kinda weird:

import React, { useEffect, useState } from "react";
import { View, Text } from "react-native";

const platform = {
  getPopperRect: ({ element }) => element,
  getReferenceRect: ({ element }) => element,
};

const Test = () => {
  const [referenceRect, setReferenceRect] = useState(null);
  const [popperRect, setPopperRect] = useState(null);

  useEffect(() => {
    if (!referenceRect || !popperRect) {
      return;
    }

    const { x, y } = position(referenceRect, popperRect, { platform });

    // ...
  }, [referenceRect, popperRect]);

  return (
    <>
      <View
        onLayout={({ nativeEvent }) => setReferenceRect(nativeEvent.layout)}
      >
        <Text>Reference Box</Text>
      </View>
      <View onLayout={({ nativeEvent }) => setPopperRect(nativeEvent.layout)}>
        <Text>Popper Box</Text>
      </View>
    </>
  );
};

export default Test;

If we use refs instead (probably have to to consider the layout stuff like offsetParent equivalent in native, it looks like we need to make the methods async:

import React, { useEffect, useRef } from "react";
import { View, Text } from "react-native";

const platform = {
  getPopperRect: ({ element }) => new Promise((resolve) => element.measure(resolve)),
  getReferenceRect: ({ element }) => new Promise((resolve) => element.measure(resolve)),
};

const Test = () => {
  const referenceRef = useRef();
  const popperRef = useRef();

  useEffect(() => {
    async function getCoords() {
      const { x, y } = await position(referenceRef.current, popperRef.current, { platform });
      // ...
    }

    getCoords();
  }, [referenceRef, popperRef]);

  return (
    <>
      <View ref={referenceRef}>
        <Text>Reference Box</Text>
      </View>
      <View ref={popperRef}>
        <Text>Popper Box</Text>
      </View>
    </>
  );
};

export default Test;

[atomiks]

Btw, we could make @popperjs/dom and @popperjs/react-native packages which export the platform code. @popperjs/react should house react-popper?

[FezVrasta]

Are we losing the modifiers phases with this approach? That's quite important for performance reasons.

I think making popper work async would be a good thing, it allows more flexibility down the road and better reflects how it actually works (it always has to wait for elements to be visible, positioned, rendered, etc, before it can compute the offsets).

[atomiks]

Yes phases are gone. Actually, they were ineffective, because we were doing a lot of DOM reads inside non-read modifiers anyway. e.g. for the adaptive option in computeStyles. The problem is we need a cache instead. We do cache scrollParents, which is expensive, but we don't cache many DOM reads because all the functions are pure.

I haven't thought about the auto-ordering yet as I've been doing it manually inside modifiers for now, but I want something like dependencies which which is just requiresIfExists. I think that a modifier should never require another one, based on all the modifiers I've written, it should always use optional chaining on the data then fallback. But dependencies is more like "put this modifier before me", so it could have a better name. Like executedAfter or runsAfter.

[FezVrasta]

Sounds good to me, feel free to send a draft PR when you are ready so I can help with it.