From b77204f045d3757f89b1d0003e29f6e43f3f8d73 Mon Sep 17 00:00:00 2001
From: Joren Broekema <Joren.Broekema@ing.com>
Date: Mon, 1 Jul 2019 17:59:04 +0200
Subject: [PATCH] chore(overlays): add docs for popper positioning

---
 .../overlays/docs/LocalOverlayPositioning.md  | 80 ++++++++++++++++++-
 1 file changed, 79 insertions(+), 1 deletion(-)

diff --git a/packages/overlays/docs/LocalOverlayPositioning.md b/packages/overlays/docs/LocalOverlayPositioning.md
index 8152dad5a..c3fc1597d 100644
--- a/packages/overlays/docs/LocalOverlayPositioning.md
+++ b/packages/overlays/docs/LocalOverlayPositioning.md
@@ -1,2 +1,80 @@
 # LocalOverlayPositioning
-## Featuring - [Popper.js]()
+## Featuring - [Popper.js](https://popper.js.org/)
+
+Our local overlays use the open-source Popper.js library for positioning the content relative to the reference element, which we usually refer to as the invoker, in the context of local overlays.
+
+## Features
+- Everything Popper.js!
+- Currently eagerly loads popper in the constructor of LocalOverlayController. Loading during idle time / using prefetch would be better, this is still WIP.
+
+
+> Popper strictly is scoped on positioning. **It does not change the dimensions of the popper element nor the reference element**. This also means that if you use the arrow feature, you are in charge of styling it properly, use the x-placement attribute for this.
+
+## How to use
+For installation, see [LocalOverlayController](./LocalOverlayController.md)'s `How to use` section.
+
+The API for LocalOverlay without Popper looks like this (`overlays` being the OverlayManager singleton):
+```js
+const localOverlay = overlays.add(
+  new LocalOverlayController({
+    contentTemplate: () =>
+      html`
+        <div class="demo-popup">United Kingdom</div>
+      `,
+    invokerTemplate: () =>
+      html`
+        <button @click=${() => popupController.toggle()}>UK</button>
+      `,
+  });
+);
+```
+This will use the defaults we set for Popper configuration. To override the default options, you add a `popperConfig` object to the properties of the object you pass to `the LocalOverlayController` like so:
+```js
+const localOverlay = overlays.add(
+  new LocalOverlayController({
+    contentTemplate: () =>
+      html`
+        <div class="demo-popup">United Kingdom</div>
+      `,
+    invokerTemplate: () =>
+      html`
+        <button @click=${() => popupController.toggle()}>UK</button>
+      `,
+    popperConfig: {
+      /* Placement of popper element, relative to reference element */
+      placement: 'bottom-start',
+      positionFixed: true,
+      modifiers: {
+        /* Prevents detachment of content element from reference element */
+        keepTogether: {
+          enabled: true,
+        },
+        /* When enabled, adds shifting/sliding behavior on secondary axis */
+        preventOverflow: {
+          enabled: false,
+          boundariesElement: 'viewport',
+          /* When enabled, this is the <boundariesElement>-margin for the secondary axis */
+          padding: 32,
+        },
+        /* Use to adjust flipping behavior or constrain directions */
+        flip: {
+          boundariesElement: 'viewport',
+          /* <boundariesElement>-margin for flipping on primary axis */
+          padding: 16,
+        },
+        /* When enabled, adds an offset to either primary or secondary axis */
+        offset: {
+          enabled: true,
+          /* margin between popper and referenceElement */
+          offset: `0, 16px`,
+        },
+      },
+    },
+  });
+);
+```
+The popperConfig is 1 to 1 aligned with Popper.js' API. For more detailed information and more advanced options, visit the [Popper.js documentation](https://popper.js.org/popper-documentation.html) to learn about the usage.
+
+## Future additions
+- Coming soon: Webcomponent implementation of LocalOverlay with a default arrow, styled out of the box to at least have proper rotations and positions.
+- Default overflow and/or max-width behavior when content is too wide or high for the viewport.