| 1 |
import applyStyle, { applyStyleOnLoad } from './applyStyle'; |
| 2 |
import computeStyle from './computeStyle'; |
| 3 |
import arrow from './arrow'; |
| 4 |
import flip from './flip'; |
| 5 |
import keepTogether from './keepTogether'; |
| 6 |
import offset from './offset'; |
| 7 |
import preventOverflow from './preventOverflow'; |
| 8 |
import shift from './shift'; |
| 9 |
import hide from './hide'; |
| 10 |
import inner from './inner'; |
| 11 |
|
| 12 |
/** |
| 13 |
* Modifier function, each modifier can have a function of this type assigned |
| 14 |
* to its `fn` property.<br /> |
| 15 |
* These functions will be called on each update, this means that you must |
| 16 |
* make sure they are performant enough to avoid performance bottlenecks. |
| 17 |
* |
| 18 |
* @function ModifierFn |
| 19 |
* @argument {dataObject} data - The data object generated by `update` method |
| 20 |
* @argument {Object} options - Modifiers configuration and options |
| 21 |
* @returns {dataObject} The data object, properly modified |
| 22 |
*/ |
| 23 |
|
| 24 |
/** |
| 25 |
* Modifiers are plugins used to alter the behavior of your poppers.<br /> |
| 26 |
* Popper.js uses a set of 9 modifiers to provide all the basic functionalities |
| 27 |
* needed by the library. |
| 28 |
* |
| 29 |
* Usually you don't want to override the `order`, `fn` and `onLoad` props. |
| 30 |
* All the other properties are configurations that could be tweaked. |
| 31 |
* @namespace modifiers |
| 32 |
*/ |
| 33 |
export default { |
| 34 |
/** |
| 35 |
* Modifier used to shift the popper on the start or end of its reference |
| 36 |
* element.<br /> |
| 37 |
* It will read the variation of the `placement` property.<br /> |
| 38 |
* It can be one either `-end` or `-start`. |
| 39 |
* @memberof modifiers |
| 40 |
* @inner |
| 41 |
*/ |
| 42 |
shift: { |
| 43 |
/** @prop {number} order=100 - Index used to define the order of execution */ |
| 44 |
order: 100, |
| 45 |
/** @prop {Boolean} enabled=true - Whether the modifier is enabled or not */ |
| 46 |
enabled: true, |
| 47 |
/** @prop {ModifierFn} */ |
| 48 |
fn: shift, |
| 49 |
}, |
| 50 |
|
| 51 |
/** |
| 52 |
* The `offset` modifier can shift your popper on both its axis. |
| 53 |
* |
| 54 |
* It accepts the following units: |
| 55 |
* - `px` or unit-less, interpreted as pixels |
| 56 |
* - `%` or `%r`, percentage relative to the length of the reference element |
| 57 |
* - `%p`, percentage relative to the length of the popper element |
| 58 |
* - `vw`, CSS viewport width unit |
| 59 |
* - `vh`, CSS viewport height unit |
| 60 |
* |
| 61 |
* For length is intended the main axis relative to the placement of the popper.<br /> |
| 62 |
* This means that if the placement is `top` or `bottom`, the length will be the |
| 63 |
* `width`. In case of `left` or `right`, it will be the `height`. |
| 64 |
* |
| 65 |
* You can provide a single value (as `Number` or `String`), or a pair of values |
| 66 |
* as `String` divided by a comma or one (or more) white spaces.<br /> |
| 67 |
* The latter is a deprecated method because it leads to confusion and will be |
| 68 |
* removed in v2.<br /> |
| 69 |
* Additionally, it accepts additions and subtractions between different units. |
| 70 |
* Note that multiplications and divisions aren't supported. |
| 71 |
* |
| 72 |
* Valid examples are: |
| 73 |
* ``` |
| 74 |
* 10 |
| 75 |
* '10%' |
| 76 |
* '10, 10' |
| 77 |
* '10%, 10' |
| 78 |
* '10 + 10%' |
| 79 |
* '10 - 5vh + 3%' |
| 80 |
* '-10px + 5vh, 5px - 6%' |
| 81 |
* ``` |
| 82 |
* > **NB**: If you desire to apply offsets to your poppers in a way that may make them overlap |
| 83 |
* > with their reference element, unfortunately, you will have to disable the `flip` modifier. |
| 84 |
* > You can read more on this at this [issue](https://github.com/FezVrasta/popper.js/issues/373). |
| 85 |
* |
| 86 |
* @memberof modifiers |
| 87 |
* @inner |
| 88 |
*/ |
| 89 |
offset: { |
| 90 |
/** @prop {number} order=200 - Index used to define the order of execution */ |
| 91 |
order: 200, |
| 92 |
/** @prop {Boolean} enabled=true - Whether the modifier is enabled or not */ |
| 93 |
enabled: true, |
| 94 |
/** @prop {ModifierFn} */ |
| 95 |
fn: offset, |
| 96 |
/** @prop {Number|String} offset=0 |
| 97 |
* The offset value as described in the modifier description |
| 98 |
*/ |
| 99 |
offset: 0, |
| 100 |
}, |
| 101 |
|
| 102 |
/** |
| 103 |
* Modifier used to prevent the popper from being positioned outside the boundary. |
| 104 |
* |
| 105 |
* A scenario exists where the reference itself is not within the boundaries.<br /> |
| 106 |
* We can say it has "escaped the boundaries" — or just "escaped".<br /> |
| 107 |
* In this case we need to decide whether the popper should either: |
| 108 |
* |
| 109 |
* - detach from the reference and remain "trapped" in the boundaries, or |
| 110 |
* - if it should ignore the boundary and "escape with its reference" |
| 111 |
* |
| 112 |
* When `escapeWithReference` is set to`true` and reference is completely |
| 113 |
* outside its boundaries, the popper will overflow (or completely leave) |
| 114 |
* the boundaries in order to remain attached to the edge of the reference. |
| 115 |
* |
| 116 |
* @memberof modifiers |
| 117 |
* @inner |
| 118 |
*/ |
| 119 |
preventOverflow: { |
| 120 |
/** @prop {number} order=300 - Index used to define the order of execution */ |
| 121 |
order: 300, |
| 122 |
/** @prop {Boolean} enabled=true - Whether the modifier is enabled or not */ |
| 123 |
enabled: true, |
| 124 |
/** @prop {ModifierFn} */ |
| 125 |
fn: preventOverflow, |
| 126 |
/** |
| 127 |
* @prop {Array} [priority=['left','right','top','bottom']] |
| 128 |
* Popper will try to prevent overflow following these priorities by default, |
| 129 |
* then, it could overflow on the left and on top of the `boundariesElement` |
| 130 |
*/ |
| 131 |
priority: ['left', 'right', 'top', 'bottom'], |
| 132 |
/** |
| 133 |
* @prop {number} padding=5 |
| 134 |
* Amount of pixel used to define a minimum distance between the boundaries |
| 135 |
* and the popper. This makes sure the popper always has a little padding |
| 136 |
* between the edges of its container |
| 137 |
*/ |
| 138 |
padding: 5, |
| 139 |
/** |
| 140 |
* @prop {String|HTMLElement} boundariesElement='scrollParent' |
| 141 |
* Boundaries used by the modifier. Can be `scrollParent`, `window`, |
| 142 |
* `viewport` or any DOM element. |
| 143 |
*/ |
| 144 |
boundariesElement: 'scrollParent', |
| 145 |
}, |
| 146 |
|
| 147 |
/** |
| 148 |
* Modifier used to make sure the reference and its popper stay near each other |
| 149 |
* without leaving any gap between the two. Especially useful when the arrow is |
| 150 |
* enabled and you want to ensure that it points to its reference element. |
| 151 |
* It cares only about the first axis. You can still have poppers with margin |
| 152 |
* between the popper and its reference element. |
| 153 |
* @memberof modifiers |
| 154 |
* @inner |
| 155 |
*/ |
| 156 |
keepTogether: { |
| 157 |
/** @prop {number} order=400 - Index used to define the order of execution */ |
| 158 |
order: 400, |
| 159 |
/** @prop {Boolean} enabled=true - Whether the modifier is enabled or not */ |
| 160 |
enabled: true, |
| 161 |
/** @prop {ModifierFn} */ |
| 162 |
fn: keepTogether, |
| 163 |
}, |
| 164 |
|
| 165 |
/** |
| 166 |
* This modifier is used to move the `arrowElement` of the popper to make |
| 167 |
* sure it is positioned between the reference element and its popper element. |
| 168 |
* It will read the outer size of the `arrowElement` node to detect how many |
| 169 |
* pixels of conjunction are needed. |
| 170 |
* |
| 171 |
* It has no effect if no `arrowElement` is provided. |
| 172 |
* @memberof modifiers |
| 173 |
* @inner |
| 174 |
*/ |
| 175 |
arrow: { |
| 176 |
/** @prop {number} order=500 - Index used to define the order of execution */ |
| 177 |
order: 500, |
| 178 |
/** @prop {Boolean} enabled=true - Whether the modifier is enabled or not */ |
| 179 |
enabled: true, |
| 180 |
/** @prop {ModifierFn} */ |
| 181 |
fn: arrow, |
| 182 |
/** @prop {String|HTMLElement} element='[x-arrow]' - Selector or node used as arrow */ |
| 183 |
element: '[x-arrow]', |
| 184 |
}, |
| 185 |
|
| 186 |
/** |
| 187 |
* Modifier used to flip the popper's placement when it starts to overlap its |
| 188 |
* reference element. |
| 189 |
* |
| 190 |
* Requires the `preventOverflow` modifier before it in order to work. |
| 191 |
* |
| 192 |
* **NOTE:** this modifier will interrupt the current update cycle and will |
| 193 |
* restart it if it detects the need to flip the placement. |
| 194 |
* @memberof modifiers |
| 195 |
* @inner |
| 196 |
*/ |
| 197 |
flip: { |
| 198 |
/** @prop {number} order=600 - Index used to define the order of execution */ |
| 199 |
order: 600, |
| 200 |
/** @prop {Boolean} enabled=true - Whether the modifier is enabled or not */ |
| 201 |
enabled: true, |
| 202 |
/** @prop {ModifierFn} */ |
| 203 |
fn: flip, |
| 204 |
/** |
| 205 |
* @prop {String|Array} behavior='flip' |
| 206 |
* The behavior used to change the popper's placement. It can be one of |
| 207 |
* `flip`, `clockwise`, `counterclockwise` or an array with a list of valid |
| 208 |
* placements (with optional variations) |
| 209 |
*/ |
| 210 |
behavior: 'flip', |
| 211 |
/** |
| 212 |
* @prop {number} padding=5 |
| 213 |
* The popper will flip if it hits the edges of the `boundariesElement` |
| 214 |
*/ |
| 215 |
padding: 5, |
| 216 |
/** |
| 217 |
* @prop {String|HTMLElement} boundariesElement='viewport' |
| 218 |
* The element which will define the boundaries of the popper position. |
| 219 |
* The popper will never be placed outside of the defined boundaries |
| 220 |
* (except if `keepTogether` is enabled) |
| 221 |
*/ |
| 222 |
boundariesElement: 'viewport', |
| 223 |
/** |
| 224 |
* @prop {Boolean} flipVariations=false |
| 225 |
* The popper will switch placement variation between `-start` and `-end` when |
| 226 |
* the reference element overlaps its boundaries. |
| 227 |
* |
| 228 |
* The original placement should have a set variation. |
| 229 |
*/ |
| 230 |
flipVariations: false, |
| 231 |
/** |
| 232 |
* @prop {Boolean} flipVariationsByContent=false |
| 233 |
* The popper will switch placement variation between `-start` and `-end` when |
| 234 |
* the popper element overlaps its reference boundaries. |
| 235 |
* |
| 236 |
* The original placement should have a set variation. |
| 237 |
*/ |
| 238 |
flipVariationsByContent: false, |
| 239 |
}, |
| 240 |
|
| 241 |
/** |
| 242 |
* Modifier used to make the popper flow toward the inner of the reference element. |
| 243 |
* By default, when this modifier is disabled, the popper will be placed outside |
| 244 |
* the reference element. |
| 245 |
* @memberof modifiers |
| 246 |
* @inner |
| 247 |
*/ |
| 248 |
inner: { |
| 249 |
/** @prop {number} order=700 - Index used to define the order of execution */ |
| 250 |
order: 700, |
| 251 |
/** @prop {Boolean} enabled=false - Whether the modifier is enabled or not */ |
| 252 |
enabled: false, |
| 253 |
/** @prop {ModifierFn} */ |
| 254 |
fn: inner, |
| 255 |
}, |
| 256 |
|
| 257 |
/** |
| 258 |
* Modifier used to hide the popper when its reference element is outside of the |
| 259 |
* popper boundaries. It will set a `x-out-of-boundaries` attribute which can |
| 260 |
* be used to hide with a CSS selector the popper when its reference is |
| 261 |
* out of boundaries. |
| 262 |
* |
| 263 |
* Requires the `preventOverflow` modifier before it in order to work. |
| 264 |
* @memberof modifiers |
| 265 |
* @inner |
| 266 |
*/ |
| 267 |
hide: { |
| 268 |
/** @prop {number} order=800 - Index used to define the order of execution */ |
| 269 |
order: 800, |
| 270 |
/** @prop {Boolean} enabled=true - Whether the modifier is enabled or not */ |
| 271 |
enabled: true, |
| 272 |
/** @prop {ModifierFn} */ |
| 273 |
fn: hide, |
| 274 |
}, |
| 275 |
|
| 276 |
/** |
| 277 |
* Computes the style that will be applied to the popper element to gets |
| 278 |
* properly positioned. |
| 279 |
* |
| 280 |
* Note that this modifier will not touch the DOM, it just prepares the styles |
| 281 |
* so that `applyStyle` modifier can apply it. This separation is useful |
| 282 |
* in case you need to replace `applyStyle` with a custom implementation. |
| 283 |
* |
| 284 |
* This modifier has `850` as `order` value to maintain backward compatibility |
| 285 |
* with previous versions of Popper.js. Expect the modifiers ordering method |
| 286 |
* to change in future major versions of the library. |
| 287 |
* |
| 288 |
* @memberof modifiers |
| 289 |
* @inner |
| 290 |
*/ |
| 291 |
computeStyle: { |
| 292 |
/** @prop {number} order=850 - Index used to define the order of execution */ |
| 293 |
order: 850, |
| 294 |
/** @prop {Boolean} enabled=true - Whether the modifier is enabled or not */ |
| 295 |
enabled: true, |
| 296 |
/** @prop {ModifierFn} */ |
| 297 |
fn: computeStyle, |
| 298 |
/** |
| 299 |
* @prop {Boolean} gpuAcceleration=true |
| 300 |
* If true, it uses the CSS 3D transformation to position the popper. |
| 301 |
* Otherwise, it will use the `top` and `left` properties |
| 302 |
*/ |
| 303 |
gpuAcceleration: true, |
| 304 |
/** |
| 305 |
* @prop {string} [x='bottom'] |
| 306 |
* Where to anchor the X axis (`bottom` or `top`). AKA X offset origin. |
| 307 |
* Change this if your popper should grow in a direction different from `bottom` |
| 308 |
*/ |
| 309 |
x: 'bottom', |
| 310 |
/** |
| 311 |
* @prop {string} [x='left'] |
| 312 |
* Where to anchor the Y axis (`left` or `right`). AKA Y offset origin. |
| 313 |
* Change this if your popper should grow in a direction different from `right` |
| 314 |
*/ |
| 315 |
y: 'right', |
| 316 |
}, |
| 317 |
|
| 318 |
/** |
| 319 |
* Applies the computed styles to the popper element. |
| 320 |
* |
| 321 |
* All the DOM manipulations are limited to this modifier. This is useful in case |
| 322 |
* you want to integrate Popper.js inside a framework or view library and you |
| 323 |
* want to delegate all the DOM manipulations to it. |
| 324 |
* |
| 325 |
* Note that if you disable this modifier, you must make sure the popper element |
| 326 |
* has its position set to `absolute` before Popper.js can do its work! |
| 327 |
* |
| 328 |
* Just disable this modifier and define your own to achieve the desired effect. |
| 329 |
* |
| 330 |
* @memberof modifiers |
| 331 |
* @inner |
| 332 |
*/ |
| 333 |
applyStyle: { |
| 334 |
/** @prop {number} order=900 - Index used to define the order of execution */ |
| 335 |
order: 900, |
| 336 |
/** @prop {Boolean} enabled=true - Whether the modifier is enabled or not */ |
| 337 |
enabled: true, |
| 338 |
/** @prop {ModifierFn} */ |
| 339 |
fn: applyStyle, |
| 340 |
/** @prop {Function} */ |
| 341 |
onLoad: applyStyleOnLoad, |
| 342 |
/** |
| 343 |
* @deprecated since version 1.10.0, the property moved to `computeStyle` modifier |
| 344 |
* @prop {Boolean} gpuAcceleration=true |
| 345 |
* If true, it uses the CSS 3D transformation to position the popper. |
| 346 |
* Otherwise, it will use the `top` and `left` properties |
| 347 |
*/ |
| 348 |
gpuAcceleration: undefined, |
| 349 |
}, |
| 350 |
}; |
| 351 |
|
| 352 |
/** |
| 353 |
* The `dataObject` is an object containing all the information used by Popper.js. |
| 354 |
* This object is passed to modifiers and to the `onCreate` and `onUpdate` callbacks. |
| 355 |
* @name dataObject |
| 356 |
* @property {Object} data.instance The Popper.js instance |
| 357 |
* @property {String} data.placement Placement applied to popper |
| 358 |
* @property {String} data.originalPlacement Placement originally defined on init |
| 359 |
* @property {Boolean} data.flipped True if popper has been flipped by flip modifier |
| 360 |
* @property {Boolean} data.hide True if the reference element is out of boundaries, useful to know when to hide the popper |
| 361 |
* @property {HTMLElement} data.arrowElement Node used as arrow by arrow modifier |
| 362 |
* @property {Object} data.styles Any CSS property defined here will be applied to the popper. It expects the JavaScript nomenclature (eg. `marginBottom`) |
| 363 |
* @property {Object} data.arrowStyles Any CSS property defined here will be applied to the popper arrow. It expects the JavaScript nomenclature (eg. `marginBottom`) |
| 364 |
* @property {Object} data.boundaries Offsets of the popper boundaries |
| 365 |
* @property {Object} data.offsets The measurements of popper, reference and arrow elements |
| 366 |
* @property {Object} data.offsets.popper `top`, `left`, `width`, `height` values |
| 367 |
* @property {Object} data.offsets.reference `top`, `left`, `width`, `height` values |
| 368 |
* @property {Object} data.offsets.arrow] `top` and `left` offsets, only one of them will be different from 0 |
| 369 |
*/ |