@swrve/offscreen

Offscreen Utilities v1

offscreen utilties has been upgraded to use popper.js position engine.

It is made up of three main parts.

Manager

This uses context to manage the relationship between the Reference point and the Frame.

Reference - ( formily Hook )

This wraps around the button or element you wish to attach a popup, tooltip or floating menu too. It uses a child render prop to pass a ref to the wrapped compoennt. The component must accept a ref via either being a standard element, using ForwardRef or by using the innerRef approach. The following components already follow the innerRef pattern, Button, Chip, IconButton. You may need to upgrade the component you wish to wrap to follow the correct ref pattern.

Frame

This decorates react-poppers Popper component and custom Swrve specific functionality and styling. It has the following props, that can be used to configure Frame. It also inplements some of Poppers more advanced features such as modifiers, which are used to control the behaviour of the Popper component.

Arrow

css in js arrow component.

How to use Modifiers

Modifier are pretty poorly explained on the ReactPopper and Popper.js docs. But they are essentially pretty simple. Modifiers let you control the way popper.js calculates the styles for the Popper component and create custom modifiers that can be inserted into a chain of functions, each mutating the style in a specific way. This is controlled with the order key a modifier. The apply style modifier has a order of 900 and the computeStyle modifiier has a order of 860, so to intercept the styles object between them you set the order of a custom modifier to be 890 or similar.

    const modifiers = {
      setMinWidth: {
        enabled: true,
        order: 891,
        fn: (data, options) => {
          data.styles.minWidth = data.offsets.reference.width
          return data
        }
      }
    }

---

Future Improvements

• Extend the modifer system to allow for more control of how the Popper is positioned on the screen. https://popper.js.org/popper-documentation.html#modifiers
• Re-implement the theming approach.
• Improve testing and code coverage.
• Update arrow padding to use a modifier rather than the className based approach.

---

FAQ

Q. Why did we upgrade.

A. Offscreen management is very complicated and while the custom approach was working well it made more sense to use a industry standard approach such as Popper.js

Q. Can I still use Downshift / Framer

A. yes, offscreen utils and popper.js is only interested in the positioning of the elements, it is up to you to add your own system to manage the user interactions.

Q. Can I use Portals

A. Yes, but you'll need to ensure your user interaction system is build to recognise the portal.

Q. Why is Arrow using css in js

A. React popper is written to use css in js, all the examples are using styled components. When used with css arrows such as the ones creted by something like http://www.cssarrowplease.com/ positioning of the arrow becomes buggy - so its best to avoid this appoach.

Reference

https://github.com/FezVrasta/react-popper

https://popper.js.org/popper-documentation.html