Debian Codegraph @

packages/popper/src/modifiers/index.js

raw
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 */