feat(Popup): add 'offset' prop (#606)

* introduce offset prop

* correct description of supported values

* update changelog

Author: kuzhelov

CHANGELOG.md

@@ -49,6 +49,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - Export `call-recording` SVG icon @Bugaa92 ([#585](https://github.com/stardust-ui/react/pull/585))
 - Export `canvas-add-page` SVG icon @priyankar205 ([#601](https://github.com/stardust-ui/react/pull/601))
 - Add `sizeModifier` variable (with `x` and `xx` values) to `Icon`'s Teams theme styles @priyankar205 ([#601](https://github.com/stardust-ui/react/pull/601))
+- Add `offset` prop to `Popup` to extend set of popup positioning options @kuzhelov ([#606](https://github.com/stardust-ui/react/pull/606))
 
 ### Documentation
 - Add `prettier` support throughout the docs @levithomason  ([#568](https://github.com/stardust-ui/react/pull/568))

docs/src/examples/components/Popup/Variations/PopupExampleOffset.shorthand.tsx

@@ -0,0 +1,44 @@
+import React from 'react'
+import { Button, Grid, Popup, Alignment, Position } from '@stardust-ui/react'
+
+const renderButton = rotateArrowUp => (
+  <Button
+    icon={{
+      name: 'arrow circle up',
+      styles: { transform: `rotate(${rotateArrowUp})` },
+    }}
+    styles={{ height: '80px', minWidth: '80px', padding: 0 }}
+  />
+)
+
+const triggers = [
+  { position: 'above', align: 'start', offset: '-100%p', rotateArrowUp: '-45deg' },
+  { position: 'above', align: 'end', offset: '100%p', rotateArrowUp: '45deg' },
+  { position: 'below', align: 'start', offset: '-100%p', rotateArrowUp: '-135deg' },
+  { position: 'below', align: 'end', offset: '100%p', rotateArrowUp: '135deg' },
+]
+
+const PopupExamplePosition = () => (
+  <Grid columns="repeat(2, 80px)" variables={{ padding: '30px', gridGap: '30px' }}>
+    {triggers.map(({ position, align, offset, rotateArrowUp }) => (
+      <Popup
+        align={align as Alignment}
+        position={position as Position}
+        offset={offset}
+        trigger={renderButton(rotateArrowUp)}
+        content={{
+          content: (
+            <p>
+              The popup is rendered at {position}-{align}
+              <br />
+              corner of the trigger.
+            </p>
+          ),
+        }}
+        key={`${position}-${align}`}
+      />
+    ))}
+  </Grid>
+)
+
+export default PopupExamplePosition

docs/src/examples/components/Popup/Variations/index.tsx

@@ -10,6 +10,11 @@ const Variations = () => (
       description="A popup can be positioned around its trigger and aligned relative to the trigger's margins. Click on a button to open a popup on a specific position and alignment."
       examplePath="components/Popup/Variations/PopupExamplePosition"
     />
+    <ComponentExample
+      title="Offset"
+      description="Popup position could be further customized by providing offset value. Note that percentage values of both trigger and popup elements' lengths are supported."
+      examplePath="components/Popup/Variations/PopupExampleOffset"
+    />
   </ExampleSection>
 )
 

src/components/Popup/Popup.tsx

@@ -54,6 +54,15 @@ export interface PopupProps
   /** Initial value for 'open'. */
   defaultOpen?: boolean
 
+  /** Offset value to apply to rendered popup. Accepts the following units:
+   * - px or unit-less, interpreted as pixels
+   * - %, percentage relative to the length of the trigger element
+   * - %p, percentage relative to the length of the popup element
+   * - vw, CSS viewport width unit
+   * - vh, CSS viewport height unit
+   */
+  offset?: string
+
   /** Defines whether popup is displayed. */
   open?: boolean
 
@@ -245,17 +254,23 @@ export default class Popup extends AutoControlledComponent<Extendable<PopupProps
     rtl: boolean,
     accessibility: AccessibilityBehavior,
   ): JSX.Element {
-    const { align, position } = this.props
+    const { align, position, offset } = this.props
     const { target } = this.state
 
     const placement = computePopupPlacement({ align, position, rtl })
 
+    const popperModifiers = {
+      // https://popper.js.org/popper-documentation.html#modifiers..offset
+      ...(offset && { offset: { offset: this.applyRtlToOffset(offset, rtl, position) } }),
+    }
+
     return (
       target && (
         <Popper
           placement={placement}
           referenceElement={target}
           children={this.renderPopperChildren.bind(this, popupPositionClasses, rtl, accessibility)}
+          modifiers={popperModifiers}
         />
       )
     )
@@ -316,4 +331,14 @@ export default class Popup extends AutoControlledComponent<Extendable<PopupProps
       _.invoke(this.props, 'onOpenChange', eventArgs, { ...this.props, ...{ open: newValue } })
     }
   }
+
+  private applyRtlToOffset(offset: string, rtl: boolean, position: Position): string {
+    if (rtl && (position === 'above' || position === 'below')) {
+      return offset.trimLeft().startsWith('-')
+        ? offset.trimLeft().replace(/^-\s*/, '')
+        : `-${offset}`
+    }
+
+    return offset
+  }
 }