From f1879cee73cc001a9987d0d2116cf1a1c389389d Mon Sep 17 00:00:00 2001 From: Maaz Syed Adeeb Date: Tue, 3 Apr 2018 20:10:36 +0530 Subject: [PATCH 1/2] Fixing typos and generating docs --- docs/_includes/popper-documentation.md | 232 ++++-------------- packages/popper/src/index.js | 8 +- packages/popper/src/methods/defaults.js | 18 +- packages/popper/src/methods/destroy.js | 2 +- .../src/methods/disableEventListeners.js | 2 +- packages/popper/src/modifiers/arrow.js | 2 +- packages/popper/src/modifiers/index.js | 52 ++-- 7 files changed, 84 insertions(+), 232 deletions(-) diff --git a/docs/_includes/popper-documentation.md b/docs/_includes/popper-documentation.md index 2a993e5f53..8af42f9588 100644 --- a/docs/_includes/popper-documentation.md +++ b/docs/_includes/popper-documentation.md @@ -9,8 +9,8 @@
dataObject
-

The dataObject is an object containing all the informations used by Popper.js -this object get passed to modifiers and to the onCreate and onUpdate callbacks.

+

The dataObject is an object containing all the information used by Popper.js. +This object is passed to modifiers and to the onCreate and onUpdate callbacks.

referenceObject

The referenceObject is an object that provides an interface compatible with Popper.js @@ -18,7 +18,7 @@ and lets you use it as replacement of a real DOM node.
You can use this method to position a popper relatively to a set of coordinates in case you don't have a DOM node to use as reference.

new Popper(referenceObject, popperNode);
-

NB: This feature isn't supported in Internet Explorer 10

+

NB: This feature isn't supported in Internet Explorer 10.

@@ -82,30 +82,20 @@ make sure they are performant enough to avoid performance bottlenecks.

### new Popper(reference, popper, options) -Create a new Popper.js instance +Creates a new Popper.js instance. **Returns**: Object - instance - The generated Popper.js instance | Param | Type | Description | | --- | --- | --- | | reference | HTMLElement \| [referenceObject](#referenceObject) | The reference element used to position the popper | -| popper | HTMLElement | The HTML element used as popper. | +| popper | HTMLElement | The HTML element used as the popper | | options | Object | Your custom options to override the ones defined in [Defaults](#defaults) | ### Popper.Defaults : Object -Default options provided to Popper.js constructor.
-These can be overriden using the `options` argument of Popper.js.
-To override an option, simply pass as 3rd argument an object with the same -structure of this object, example: -``` -new Popper(ref, pop, { - modifiers: { - preventOverflow: { enabled: false } - } -}) -``` +Default options provided to Popper.js constructor.
These can be overridden using the `options` argument of Popper.js.
To override an option, simply pass an object with the same structure of the `options` object, as the 3rd argument. For example: ``` new Popper(ref, pop, { modifiers: { preventOverflow: { enabled: false } } }) ``` **Kind**: static property of [Popper](#Popper) @@ -121,7 +111,7 @@ new Popper(ref, pop, { #### Defaults.placement -Popper's placement +Popper's placement. **Kind**: static property of [Defaults](#Popper.Defaults) **Properties** @@ -145,7 +135,7 @@ Set this to true if you want popper to position it self in 'fixed' mode #### Defaults.eventsEnabled -Whether events (resize, scroll) are initially enabled +Whether events (resize, scroll) are initially enabled. **Kind**: static property of [Defaults](#Popper.Defaults) **Properties** @@ -157,8 +147,7 @@ Whether events (resize, scroll) are initially enabled #### Defaults.removeOnDestroy -Set to true if you want to automatically remove the popper when -you call the `destroy` method. +Set to true if you want to automatically remove the popper when you call the `destroy` method. **Kind**: static property of [Defaults](#Popper.Defaults) **Properties** @@ -170,8 +159,7 @@ you call the `destroy` method. #### Defaults.modifiers -List of modifiers used to modify the offsets before they are applied to the popper. -They provide most of the functionalities of Popper.js +List of modifiers used to modify the offsets before they are applied to the popper. They provide most of the functionalities of Popper.js. **Kind**: static property of [Defaults](#Popper.Defaults) **Properties** @@ -183,9 +171,7 @@ They provide most of the functionalities of Popper.js #### Defaults.onCreate() -Callback called when the popper is created.
-By default, is set to no-op.
-Access Popper.js instance with `data.instance`. +Callback called when the popper is created.
By default, it is set to no-op.
Access Popper.js instance with `data.instance`. **Kind**: static method of [Defaults](#Popper.Defaults) **Properties** @@ -197,11 +183,7 @@ Access Popper.js instance with `data.instance`. #### Defaults.onUpdate() -Callback called when the popper is updated, this callback is not called -on the initialization/creation of the popper, but only on subsequent -updates.
-By default, is set to no-op.
-Access Popper.js instance with `data.instance`. +Callback called when the popper is updated. This callback is not called on the initialization/creation of the popper, but only on subsequent updates.
By default, it is set to no-op.
Access Popper.js instance with `data.instance`. **Kind**: static method of [Defaults](#Popper.Defaults) **Properties** @@ -213,71 +195,44 @@ Access Popper.js instance with `data.instance`. ### Popper.placements : enum -List of accepted placements to use as values of the `placement` option.
-Valid placements are: -- `auto` -- `top` -- `right` -- `bottom` -- `left` - -Each placement can have a variation from this list: -- `-start` -- `-end` - -Variations are interpreted easily if you think of them as the left to right -written languages. Horizontally (`top` and `bottom`), `start` is left and `end` -is right.
-Vertically (`left` and `right`), `start` is top and `end` is bottom. - -Some valid examples are: -- `top-end` (on top of reference, right aligned) -- `right-start` (on right of reference, top aligned) -- `bottom` (on bottom, centered) -- `auto-right` (on the side with more space available, alignment depends by placement) +List of accepted placements to use as values of the `placement` option.
Valid placements are: - `auto` - `top` - `right` - `bottom` - `left` Each placement can have a variation from this list: - `-start` - `-end` Variations are interpreted easily if you think of them as the left to right written languages. Horizontally (`top` and `bottom`), `start` is left and `end` is right.
Vertically (`left` and `right`), `start` is top and `end` is bottom. Some valid examples are: - `top-end` (on top of reference, right aligned) - `right-start` (on right of reference, top aligned) - `bottom` (on bottom, centered) - `auto-right` (on the side with more space available, alignment depends by placement) **Kind**: static enum of [Popper](#Popper) **Read only**: true ### Popper.update() -Updates the position of the popper, computing the new offsets and applying -the new style.
-Prefer `scheduleUpdate` over `update` because of performance reasons. +Updates the position of the popper, computing the new offsets and applying the new style.
Prefer `scheduleUpdate` over `update` because of performance reasons. **Kind**: static method of [Popper](#Popper) ### Popper.destroy() -Destroy the popper +Destroys the popper. **Kind**: static method of [Popper](#Popper) ### Popper.enableEventListeners() -It will add resize/scroll events and start recalculating -position of the popper element when they are triggered. +It will add resize/scroll events and start recalculating position of the popper element when they are triggered. **Kind**: static method of [Popper](#Popper) ### Popper.disableEventListeners() -It will remove resize/scroll events and won't recalculate popper position -when they are triggered. It also won't trigger onUpdate callback anymore, -unless you call `update` method manually. +It will remove resize/scroll events and won't recalculate popper position when they are triggered. It also won't trigger `onUpdate` callback anymore, unless you call `update` method manually. **Kind**: static method of [Popper](#Popper) ### Popper.scheduleUpdate() -Schedule an update, it will run on the next UI update available +Schedules an update. It will run on the next UI update available. **Kind**: static method of [Popper](#Popper) ## dataObject -The `dataObject` is an object containing all the informations used by Popper.js -this object get passed to modifiers and to the `onCreate` and `onUpdate` callbacks. +The `dataObject` is an object containing all the information used by Popper.js. This object is passed to modifiers and to the `onCreate` and `onUpdate` callbacks. **Kind**: global variable **Properties** @@ -288,12 +243,12 @@ this object get passed to modifiers and to the `onCreate` and `onUpdate` callbac | data.placement | String | Placement applied to popper | | data.originalPlacement | String | Placement originally defined on init | | data.flipped | Boolean | True if popper has been flipped by flip modifier | -| data.hide | Boolean | True if the reference element is out of boundaries, useful to know when to hide the popper. | +| data.hide | Boolean | True if the reference element is out of boundaries, useful to know when to hide the popper | | data.arrowElement | HTMLElement | Node used as arrow by arrow modifier | -| data.styles | Object | Any CSS property defined here will be applied to the popper, it expects the JavaScript nomenclature (eg. `marginBottom`) | -| data.arrowStyles | Object | Any CSS property defined here will be applied to the popper arrow, it expects the JavaScript nomenclature (eg. `marginBottom`) | +| data.styles | Object | Any CSS property defined here will be applied to the popper. It expects the JavaScript nomenclature (eg. `marginBottom`) | +| data.arrowStyles | Object | Any CSS property defined here will be applied to the popper arrow. It expects the JavaScript nomenclature (eg. `marginBottom`) | | data.boundaries | Object | Offsets of the popper boundaries | -| data.offsets | Object | The measurements of popper, reference and arrow elements. | +| data.offsets | Object | The measurements of popper, reference and arrow elements | | data.offsets.popper | Object | `top`, `left`, `width`, `height` values | | data.offsets.reference | Object | `top`, `left`, `width`, `height` values | | data.offsets.arrow | Object | `top` and `left` offsets, only one of them will be different from 0 | @@ -301,16 +256,7 @@ this object get passed to modifiers and to the `onCreate` and `onUpdate` callbac ## referenceObject -The `referenceObject` is an object that provides an interface compatible with Popper.js -and lets you use it as replacement of a real DOM node.
-You can use this method to position a popper relatively to a set of coordinates -in case you don't have a DOM node to use as reference. - -``` -new Popper(referenceObject, popperNode); -``` - -NB: This feature isn't supported in Internet Explorer 10 +The `referenceObject` is an object that provides an interface compatible with Popper.js and lets you use it as replacement of a real DOM node.
You can use this method to position a popper relatively to a set of coordinates in case you don't have a DOM node to use as reference. ``` new Popper(referenceObject, popperNode); ``` NB: This feature isn't supported in Internet Explorer 10. **Kind**: global variable **Properties** @@ -324,12 +270,7 @@ NB: This feature isn't supported in Internet Explorer 10 ## modifiers : object -Modifiers are plugins used to alter the behavior of your poppers.
-Popper.js uses a set of 9 modifiers to provide all the basic functionalities -needed by the library. - -Usually you don't want to override the `order`, `fn` and `onLoad` props. -All the other properties are configurations that could be tweaked. +Modifiers are plugins used to alter the behavior of your poppers.
Popper.js uses a set of 9 modifiers to provide all the basic functionalities needed by the library. Usually you don't want to override the `order`, `fn` and `onLoad` props. All the other properties are configurations that could be tweaked. **Kind**: global namespace @@ -391,10 +332,7 @@ All the other properties are configurations that could be tweaked. ### modifiers~shift -Modifier used to shift the popper on the start or end of its reference -element.
-It will read the variation of the `placement` property.
-It can be one either `-end` or `-start`. +Modifier used to shift the popper on the start or end of its reference element.
It will read the variation of the `placement` property.
It can be one either `-end` or `-start`. **Kind**: inner property of [modifiers](#modifiers) @@ -436,39 +374,7 @@ It can be one either `-end` or `-start`. ### modifiers~offset -The `offset` modifier can shift your popper on both its axis. - -It accepts the following units: -- `px` or unitless, interpreted as pixels -- `%` or `%r`, percentage relative to the length of the reference element -- `%p`, percentage relative to the length of the popper element -- `vw`, CSS viewport width unit -- `vh`, CSS viewport height unit - -For length is intended the main axis relative to the placement of the popper.
-This means that if the placement is `top` or `bottom`, the length will be the -`width`. In case of `left` or `right`, it will be the height. - -You can provide a single value (as `Number` or `String`), or a pair of values -as `String` divided by a comma or one (or more) white spaces.
-The latter is a deprecated method because it leads to confusion and will be -removed in v2.
-Additionally, it accepts additions and subtractions between different units. -Note that multiplications and divisions aren't supported. - -Valid examples are: -``` -10 -'10%' -'10, 10' -'10%, 10' -'10 + 10%' -'10 - 5vh + 3%' -'-10px + 5vh, 5px - 6%' -``` -> **NB**: If you desire to apply offsets to your poppers in a way that may make them overlap -> with their reference element, unfortunately, you will have to disable the `flip` modifier. -> More on this [reading this issue](https://github.com/FezVrasta/popper.js/issues/373) +The `offset` modifier can shift your popper on both its axis. It accepts the following units: - `px` or unit-less, interpreted as pixels - `%` or `%r`, percentage relative to the length of the reference element - `%p`, percentage relative to the length of the popper element - `vw`, CSS viewport width unit - `vh`, CSS viewport height unit For length is intended the main axis relative to the placement of the popper.
This means that if the placement is `top` or `bottom`, the length will be the `width`. In case of `left` or `right`, it will be the `height`. You can provide a single value (as `Number` or `String`), or a pair of values as `String` divided by a comma or one (or more) white spaces.
The latter is a deprecated method because it leads to confusion and will be removed in v2.
Additionally, it accepts additions and subtractions between different units. Note that multiplications and divisions aren't supported. Valid examples are: ``` 10 '10%' '10, 10' '10%, 10' '10 + 10%' '10 - 5vh + 3%' '-10px + 5vh, 5px - 6%' ``` > **NB**: If you desire to apply offsets to your poppers in a way that may make them overlap > with their reference element, unfortunately, you will have to disable the `flip` modifier. > You can read more on this at this [issue](https://github.com/FezVrasta/popper.js/issues/373). **Kind**: inner property of [modifiers](#modifiers) @@ -521,18 +427,7 @@ Valid examples are: ### modifiers~preventOverflow -Modifier used to prevent the popper from being positioned outside the boundary. - -An scenario exists where the reference itself is not within the boundaries.
-We can say it has "escaped the boundaries" — or just "escaped".
-In this case we need to decide whether the popper should either: - -- detach from the reference and remain "trapped" in the boundaries, or -- if it should ignore the boundary and "escape with its reference" - -When `escapeWithReference` is set to`true` and reference is completely -outside its boundaries, the popper will overflow (or completely leave) -the boundaries in order to remain attached to the edge of the reference. +Modifier used to prevent the popper from being positioned outside the boundary. A scenario exists where the reference itself is not within the boundaries.
We can say it has "escaped the boundaries" — or just "escaped".
In this case we need to decide whether the popper should either: - detach from the reference and remain "trapped" in the boundaries, or - if it should ignore the boundary and "escape with its reference" When `escapeWithReference` is set to`true` and reference is completely outside its boundaries, the popper will overflow (or completely leave) the boundaries in order to remain attached to the edge of the reference. **Kind**: inner property of [modifiers](#modifiers) @@ -592,7 +487,7 @@ the boundaries in order to remain attached to the edge of the reference. | Name | Type | Default | Description | | --- | --- | --- | --- | -| padding | number | 5 | Amount of pixel used to define a minimum distance between the boundaries and the popper this makes sure the popper has always a little padding between the edges of its container | +| padding | number | 5 | Amount of pixel used to define a minimum distance between the boundaries and the popper. This makes sure the popper always has a little padding between the edges of its container | @@ -602,16 +497,12 @@ the boundaries in order to remain attached to the edge of the reference. | Name | Type | Default | Description | | --- | --- | --- | --- | -| boundariesElement | String \| HTMLElement | 'scrollParent' | Boundaries used by the modifier, can be `scrollParent`, `window`, `viewport` or any DOM element. | +| boundariesElement | String \| HTMLElement | 'scrollParent' | Boundaries used by the modifier. Can be `scrollParent`, `window`, `viewport` or any DOM element. | ### modifiers~keepTogether -Modifier used to make sure the reference and its popper stay near eachothers -without leaving any gap between the two. Expecially useful when the arrow is -enabled and you want to assure it to point to its reference element. -It cares only about the first axis, you can still have poppers with margin -between the popper and its reference element. +Modifier used to make sure the reference and its popper stay near each other without leaving any gap between the two. Especially useful when the arrow is enabled and you want to ensure that it points to its reference element. It cares only about the first axis. You can still have poppers with margin between the popper and its reference element. **Kind**: inner property of [modifiers](#modifiers) @@ -653,12 +544,7 @@ between the popper and its reference element. ### modifiers~arrow -This modifier is used to move the `arrowElement` of the popper to make -sure it is positioned between the reference element and its popper element. -It will read the outer size of the `arrowElement` node to detect how many -pixels of conjuction are needed. - -It has no effect if no `arrowElement` is provided. +This modifier is used to move the `arrowElement` of the popper to make sure it is positioned between the reference element and its popper element. It will read the outer size of the `arrowElement` node to detect how many pixels of conjunction are needed. It has no effect if no `arrowElement` is provided. **Kind**: inner property of [modifiers](#modifiers) @@ -711,13 +597,7 @@ It has no effect if no `arrowElement` is provided. ### modifiers~flip -Modifier used to flip the popper's placement when it starts to overlap its -reference element. - -Requires the `preventOverflow` modifier before it in order to work. - -**NOTE:** this modifier will interrupt the current update cycle and will -restart it if it detects the need to flip the placement. +Modifier used to flip the popper's placement when it starts to overlap its reference element. Requires the `preventOverflow` modifier before it in order to work. **NOTE:** this modifier will interrupt the current update cycle and will restart it if it detects the need to flip the placement. **Kind**: inner property of [modifiers](#modifiers) @@ -767,7 +647,7 @@ restart it if it detects the need to flip the placement. | Name | Type | Default | Description | | --- | --- | --- | --- | -| behavior | String \| Array | 'flip' | The behavior used to change the popper's placement. It can be one of `flip`, `clockwise`, `counterclockwise` or an array with a list of valid placements (with optional variations). | +| behavior | String \| Array | 'flip' | The behavior used to change the popper's placement. It can be one of `flip`, `clockwise`, `counterclockwise` or an array with a list of valid placements (with optional variations) | @@ -787,14 +667,12 @@ restart it if it detects the need to flip the placement. | Name | Type | Default | Description | | --- | --- | --- | --- | -| boundariesElement | String \| HTMLElement | 'viewport' | The element which will define the boundaries of the popper position, the popper will never be placed outside of the defined boundaries (except if keepTogether is enabled) | +| boundariesElement | String \| HTMLElement | 'viewport' | The element which will define the boundaries of the popper position. The popper will never be placed outside of the defined boundaries (except if `keepTogether` is enabled) | ### modifiers~inner -Modifier used to make the popper flow toward the inner of the reference element. -By default, when this modifier is disabled, the popper will be placed outside -the reference element. +Modifier used to make the popper flow toward the inner of the reference element. By default, when this modifier is disabled, the popper will be placed outside the reference element. **Kind**: inner property of [modifiers](#modifiers) @@ -836,12 +714,7 @@ the reference element. ### modifiers~hide -Modifier used to hide the popper when its reference element is outside of the -popper boundaries. It will set a `x-out-of-boundaries` attribute which can -be used to hide with a CSS selector the popper when its reference is -out of boundaries. - -Requires the `preventOverflow` modifier before it in order to work. +Modifier used to hide the popper when its reference element is outside of the popper boundaries. It will set a `x-out-of-boundaries` attribute which can be used to hide with a CSS selector the popper when its reference is out of boundaries. Requires the `preventOverflow` modifier before it in order to work. **Kind**: inner property of [modifiers](#modifiers) @@ -883,16 +756,7 @@ Requires the `preventOverflow` modifier before it in order to work. ### modifiers~computeStyle -Computes the style that will be applied to the popper element to gets -properly positioned. - -Note that this modifier will not touch the DOM, it just prepares the styles -so that `applyStyle` modifier can apply it. This separation is useful -in case you need to replace `applyStyle` with a custom implementation. - -This modifier has `850` as `order` value to maintain backward compatibility -with previous versions of Popper.js. Expect the modifiers ordering method -to change in future major versions of the library. +Computes the style that will be applied to the popper element to gets properly positioned. Note that this modifier will not touch the DOM, it just prepares the styles so that `applyStyle` modifier can apply it. This separation is useful in case you need to replace `applyStyle` with a custom implementation. This modifier has `850` as `order` value to maintain backward compatibility with previous versions of Popper.js. Expect the modifiers ordering method to change in future major versions of the library. **Kind**: inner property of [modifiers](#modifiers) @@ -942,7 +806,7 @@ to change in future major versions of the library. | Name | Type | Default | Description | | --- | --- | --- | --- | -| gpuAcceleration | Boolean | true | If true, it uses the CSS 3d transformation to position the popper. Otherwise, it will use the `top` and `left` properties. | +| gpuAcceleration | Boolean | true | If true, it uses the CSS 3D transformation to position the popper. Otherwise, it will use the `top` and `left` properties | @@ -967,16 +831,7 @@ to change in future major versions of the library. ### modifiers~applyStyle -Applies the computed styles to the popper element. - -All the DOM manipulations are limited to this modifier. This is useful in case -you want to integrate Popper.js inside a framework or view library and you -want to delegate all the DOM manipulations to it. - -Note that if you disable this modifier, you must make sure the popper element -has its position set to `absolute` before Popper.js can do its work! - -Just disable this modifier and define you own to achieve the desired effect. +Applies the computed styles to the popper element. All the DOM manipulations are limited to this modifier. This is useful in case you want to integrate Popper.js inside a framework or view library and you want to delegate all the DOM manipulations to it. Note that if you disable this modifier, you must make sure the popper element has its position set to `absolute` before Popper.js can do its work! Just disable this modifier and define your own to achieve the desired effect. **Kind**: inner property of [modifiers](#modifiers) @@ -1037,7 +892,7 @@ Just disable this modifier and define you own to achieve the desired effect. | Name | Type | Default | Description | | --- | --- | --- | --- | -| gpuAcceleration | Boolean | true | If true, it uses the CSS 3d transformation to position the popper. Otherwise, it will use the `top` and `left` properties. | +| gpuAcceleration | Boolean | true | If true, it uses the CSS 3D transformation to position the popper. Otherwise, it will use the `top` and `left` properties | @@ -1053,10 +908,7 @@ Get the window associated with the element ## ModifierFn(data, options) ⇒ [dataObject](#dataObject) -Modifier function, each modifier can have a function of this type assigned -to its `fn` property.
-These functions will be called on each update, this means that you must -make sure they are performant enough to avoid performance bottlenecks. +Modifier function, each modifier can have a function of this type assigned to its `fn` property.
These functions will be called on each update, this means that you must make sure they are performant enough to avoid performance bottlenecks. **Kind**: global function **Returns**: [dataObject](#dataObject) - The data object, properly modified diff --git a/packages/popper/src/index.js b/packages/popper/src/index.js index 50d90c8e0a..8f054e28de 100644 --- a/packages/popper/src/index.js +++ b/packages/popper/src/index.js @@ -12,10 +12,10 @@ import placements from './methods/placements'; export default class Popper { /** - * Create a new Popper.js instance + * Creates a new Popper.js instance. * @class Popper * @param {HTMLElement|referenceObject} reference - The reference element used to position the popper - * @param {HTMLElement} popper - The HTML element used as popper. + * @param {HTMLElement} popper - The HTML element used as the popper * @param {Object} options - Your custom options to override the ones defined in [Defaults](#defaults) * @return {Object} instance - The generated Popper.js instance */ @@ -104,7 +104,7 @@ export default class Popper { } /** - * Schedule an update, it will run on the next UI update available + * Schedules an update. It will run on the next UI update available. * @method scheduleUpdate * @memberof Popper */ @@ -143,7 +143,7 @@ export default class Popper { * new Popper(referenceObject, popperNode); * ``` * - * NB: This feature isn't supported in Internet Explorer 10 + * NB: This feature isn't supported in Internet Explorer 10. * @name referenceObject * @property {Function} data.getBoundingClientRect * A function that returns a set of coordinates compatible with the native `getBoundingClientRect` method. diff --git a/packages/popper/src/methods/defaults.js b/packages/popper/src/methods/defaults.js index 8ab4e9bab9..461f98106e 100644 --- a/packages/popper/src/methods/defaults.js +++ b/packages/popper/src/methods/defaults.js @@ -2,9 +2,9 @@ import modifiers from '../modifiers/index'; /** * Default options provided to Popper.js constructor.
- * These can be overriden using the `options` argument of Popper.js.
- * To override an option, simply pass as 3rd argument an object with the same - * structure of this object, example: + * These can be overridden using the `options` argument of Popper.js.
+ * To override an option, simply pass an object with the same + * structure of the `options` object, as the 3rd argument. For example: * ``` * new Popper(ref, pop, { * modifiers: { @@ -18,7 +18,7 @@ import modifiers from '../modifiers/index'; */ export default { /** - * Popper's placement + * Popper's placement. * @prop {Popper.placements} placement='bottom' */ placement: 'bottom', @@ -30,7 +30,7 @@ export default { positionFixed: false, /** - * Whether events (resize, scroll) are initially enabled + * Whether events (resize, scroll) are initially enabled. * @prop {Boolean} eventsEnabled=true */ eventsEnabled: true, @@ -44,17 +44,17 @@ export default { /** * Callback called when the popper is created.
- * By default, is set to no-op.
+ * By default, it is set to no-op.
* Access Popper.js instance with `data.instance`. * @prop {onCreate} */ onCreate: () => {}, /** - * Callback called when the popper is updated, this callback is not called + * Callback called when the popper is updated. This callback is not called * on the initialization/creation of the popper, but only on subsequent * updates.
- * By default, is set to no-op.
+ * By default, it is set to no-op.
* Access Popper.js instance with `data.instance`. * @prop {onUpdate} */ @@ -62,7 +62,7 @@ export default { /** * List of modifiers used to modify the offsets before they are applied to the popper. - * They provide most of the functionalities of Popper.js + * They provide most of the functionalities of Popper.js. * @prop {modifiers} */ modifiers, diff --git a/packages/popper/src/methods/destroy.js b/packages/popper/src/methods/destroy.js index f427481cc1..df585e0bfb 100644 --- a/packages/popper/src/methods/destroy.js +++ b/packages/popper/src/methods/destroy.js @@ -2,7 +2,7 @@ import isModifierEnabled from '../utils/isModifierEnabled'; import getSupportedPropertyName from '../utils/getSupportedPropertyName'; /** - * Destroy the popper + * Destroys the popper. * @method * @memberof Popper */ diff --git a/packages/popper/src/methods/disableEventListeners.js b/packages/popper/src/methods/disableEventListeners.js index 87a8c0d995..4d2e0322b7 100644 --- a/packages/popper/src/methods/disableEventListeners.js +++ b/packages/popper/src/methods/disableEventListeners.js @@ -2,7 +2,7 @@ import removeEventListeners from '../utils/removeEventListeners'; /** * It will remove resize/scroll events and won't recalculate popper position - * when they are triggered. It also won't trigger onUpdate callback anymore, + * when they are triggered. It also won't trigger `onUpdate` callback anymore, * unless you call `update` method manually. * @method * @memberof Popper diff --git a/packages/popper/src/modifiers/arrow.js b/packages/popper/src/modifiers/arrow.js index c14e9f16c1..94bab5ac42 100644 --- a/packages/popper/src/modifiers/arrow.js +++ b/packages/popper/src/modifiers/arrow.js @@ -50,7 +50,7 @@ export default function arrow(data, options) { // // extends keepTogether behavior making sure the popper and its - // reference have enough pixels in conjuction + // reference have enough pixels in conjunction // // top/left side diff --git a/packages/popper/src/modifiers/index.js b/packages/popper/src/modifiers/index.js index a8ad57e91b..db8fd7d797 100644 --- a/packages/popper/src/modifiers/index.js +++ b/packages/popper/src/modifiers/index.js @@ -52,7 +52,7 @@ export default { * The `offset` modifier can shift your popper on both its axis. * * It accepts the following units: - * - `px` or unitless, interpreted as pixels + * - `px` or unit-less, interpreted as pixels * - `%` or `%r`, percentage relative to the length of the reference element * - `%p`, percentage relative to the length of the popper element * - `vw`, CSS viewport width unit @@ -60,7 +60,7 @@ export default { * * For length is intended the main axis relative to the placement of the popper.
* This means that if the placement is `top` or `bottom`, the length will be the - * `width`. In case of `left` or `right`, it will be the height. + * `width`. In case of `left` or `right`, it will be the `height`. * * You can provide a single value (as `Number` or `String`), or a pair of values * as `String` divided by a comma or one (or more) white spaces.
@@ -81,7 +81,7 @@ export default { * ``` * > **NB**: If you desire to apply offsets to your poppers in a way that may make them overlap * > with their reference element, unfortunately, you will have to disable the `flip` modifier. - * > More on this [reading this issue](https://github.com/FezVrasta/popper.js/issues/373) + * > You can read more on this at this [issue](https://github.com/FezVrasta/popper.js/issues/373). * * @memberof modifiers * @inner @@ -102,7 +102,7 @@ export default { /** * Modifier used to prevent the popper from being positioned outside the boundary. * - * An scenario exists where the reference itself is not within the boundaries.
+ * A scenario exists where the reference itself is not within the boundaries.
* We can say it has "escaped the boundaries" — or just "escaped".
* In this case we need to decide whether the popper should either: * @@ -132,23 +132,23 @@ export default { /** * @prop {number} padding=5 * Amount of pixel used to define a minimum distance between the boundaries - * and the popper this makes sure the popper has always a little padding + * and the popper. This makes sure the popper always has a little padding * between the edges of its container */ padding: 5, /** * @prop {String|HTMLElement} boundariesElement='scrollParent' - * Boundaries used by the modifier, can be `scrollParent`, `window`, + * Boundaries used by the modifier. Can be `scrollParent`, `window`, * `viewport` or any DOM element. */ boundariesElement: 'scrollParent', }, /** - * Modifier used to make sure the reference and its popper stay near eachothers - * without leaving any gap between the two. Expecially useful when the arrow is - * enabled and you want to assure it to point to its reference element. - * It cares only about the first axis, you can still have poppers with margin + * Modifier used to make sure the reference and its popper stay near each other + * without leaving any gap between the two. Especially useful when the arrow is + * enabled and you want to ensure that it points to its reference element. + * It cares only about the first axis. You can still have poppers with margin * between the popper and its reference element. * @memberof modifiers * @inner @@ -166,7 +166,7 @@ export default { * This modifier is used to move the `arrowElement` of the popper to make * sure it is positioned between the reference element and its popper element. * It will read the outer size of the `arrowElement` node to detect how many - * pixels of conjuction are needed. + * pixels of conjunction are needed. * * It has no effect if no `arrowElement` is provided. * @memberof modifiers @@ -205,7 +205,7 @@ export default { * @prop {String|Array} behavior='flip' * The behavior used to change the popper's placement. It can be one of * `flip`, `clockwise`, `counterclockwise` or an array with a list of valid - * placements (with optional variations). + * placements (with optional variations) */ behavior: 'flip', /** @@ -215,9 +215,9 @@ export default { padding: 5, /** * @prop {String|HTMLElement} boundariesElement='viewport' - * The element which will define the boundaries of the popper position, - * the popper will never be placed outside of the defined boundaries - * (except if keepTogether is enabled) + * The element which will define the boundaries of the popper position. + * The popper will never be placed outside of the defined boundaries + * (except if `keepTogether` is enabled) */ boundariesElement: 'viewport', }, @@ -281,8 +281,8 @@ export default { fn: computeStyle, /** * @prop {Boolean} gpuAcceleration=true - * If true, it uses the CSS 3d transformation to position the popper. - * Otherwise, it will use the `top` and `left` properties. + * If true, it uses the CSS 3D transformation to position the popper. + * Otherwise, it will use the `top` and `left` properties */ gpuAcceleration: true, /** @@ -309,7 +309,7 @@ export default { * Note that if you disable this modifier, you must make sure the popper element * has its position set to `absolute` before Popper.js can do its work! * - * Just disable this modifier and define you own to achieve the desired effect. + * Just disable this modifier and define your own to achieve the desired effect. * * @memberof modifiers * @inner @@ -326,27 +326,27 @@ export default { /** * @deprecated since version 1.10.0, the property moved to `computeStyle` modifier * @prop {Boolean} gpuAcceleration=true - * If true, it uses the CSS 3d transformation to position the popper. - * Otherwise, it will use the `top` and `left` properties. + * If true, it uses the CSS 3D transformation to position the popper. + * Otherwise, it will use the `top` and `left` properties */ gpuAcceleration: undefined, }, }; /** - * The `dataObject` is an object containing all the informations used by Popper.js - * this object get passed to modifiers and to the `onCreate` and `onUpdate` callbacks. + * The `dataObject` is an object containing all the information used by Popper.js. + * This object is passed to modifiers and to the `onCreate` and `onUpdate` callbacks. * @name dataObject * @property {Object} data.instance The Popper.js instance * @property {String} data.placement Placement applied to popper * @property {String} data.originalPlacement Placement originally defined on init * @property {Boolean} data.flipped True if popper has been flipped by flip modifier - * @property {Boolean} data.hide True if the reference element is out of boundaries, useful to know when to hide the popper. + * @property {Boolean} data.hide True if the reference element is out of boundaries, useful to know when to hide the popper * @property {HTMLElement} data.arrowElement Node used as arrow by arrow modifier - * @property {Object} data.styles Any CSS property defined here will be applied to the popper, it expects the JavaScript nomenclature (eg. `marginBottom`) - * @property {Object} data.arrowStyles Any CSS property defined here will be applied to the popper arrow, it expects the JavaScript nomenclature (eg. `marginBottom`) + * @property {Object} data.styles Any CSS property defined here will be applied to the popper. It expects the JavaScript nomenclature (eg. `marginBottom`) + * @property {Object} data.arrowStyles Any CSS property defined here will be applied to the popper arrow. It expects the JavaScript nomenclature (eg. `marginBottom`) * @property {Object} data.boundaries Offsets of the popper boundaries - * @property {Object} data.offsets The measurements of popper, reference and arrow elements. + * @property {Object} data.offsets The measurements of popper, reference and arrow elements * @property {Object} data.offsets.popper `top`, `left`, `width`, `height` values * @property {Object} data.offsets.reference `top`, `left`, `width`, `height` values * @property {Object} data.offsets.arrow] `top` and `left` offsets, only one of them will be different from 0 From 6d21cd259a5b8df96514bbf06cc73da38f47b047 Mon Sep 17 00:00:00 2001 From: Maaz Syed Adeeb Date: Sun, 8 Apr 2018 15:36:25 +0530 Subject: [PATCH 2/2] Reset generated docs --- docs/_includes/popper-documentation.md | 232 ++++++++++++++++++++----- 1 file changed, 190 insertions(+), 42 deletions(-) diff --git a/docs/_includes/popper-documentation.md b/docs/_includes/popper-documentation.md index 8af42f9588..2a993e5f53 100644 --- a/docs/_includes/popper-documentation.md +++ b/docs/_includes/popper-documentation.md @@ -9,8 +9,8 @@
dataObject
-

The dataObject is an object containing all the information used by Popper.js. -This object is passed to modifiers and to the onCreate and onUpdate callbacks.

+

The dataObject is an object containing all the informations used by Popper.js +this object get passed to modifiers and to the onCreate and onUpdate callbacks.

referenceObject

The referenceObject is an object that provides an interface compatible with Popper.js @@ -18,7 +18,7 @@ and lets you use it as replacement of a real DOM node.
You can use this method to position a popper relatively to a set of coordinates in case you don't have a DOM node to use as reference.

new Popper(referenceObject, popperNode);
-

NB: This feature isn't supported in Internet Explorer 10.

+

NB: This feature isn't supported in Internet Explorer 10

@@ -82,20 +82,30 @@ make sure they are performant enough to avoid performance bottlenecks.

### new Popper(reference, popper, options) -Creates a new Popper.js instance. +Create a new Popper.js instance **Returns**: Object - instance - The generated Popper.js instance | Param | Type | Description | | --- | --- | --- | | reference | HTMLElement \| [referenceObject](#referenceObject) | The reference element used to position the popper | -| popper | HTMLElement | The HTML element used as the popper | +| popper | HTMLElement | The HTML element used as popper. | | options | Object | Your custom options to override the ones defined in [Defaults](#defaults) | ### Popper.Defaults : Object -Default options provided to Popper.js constructor.
These can be overridden using the `options` argument of Popper.js.
To override an option, simply pass an object with the same structure of the `options` object, as the 3rd argument. For example: ``` new Popper(ref, pop, { modifiers: { preventOverflow: { enabled: false } } }) ``` +Default options provided to Popper.js constructor.
+These can be overriden using the `options` argument of Popper.js.
+To override an option, simply pass as 3rd argument an object with the same +structure of this object, example: +``` +new Popper(ref, pop, { + modifiers: { + preventOverflow: { enabled: false } + } +}) +``` **Kind**: static property of [Popper](#Popper) @@ -111,7 +121,7 @@ Default options provided to Popper.js constructor.
These can be overridden #### Defaults.placement -Popper's placement. +Popper's placement **Kind**: static property of [Defaults](#Popper.Defaults) **Properties** @@ -135,7 +145,7 @@ Set this to true if you want popper to position it self in 'fixed' mode #### Defaults.eventsEnabled -Whether events (resize, scroll) are initially enabled. +Whether events (resize, scroll) are initially enabled **Kind**: static property of [Defaults](#Popper.Defaults) **Properties** @@ -147,7 +157,8 @@ Whether events (resize, scroll) are initially enabled. #### Defaults.removeOnDestroy -Set to true if you want to automatically remove the popper when you call the `destroy` method. +Set to true if you want to automatically remove the popper when +you call the `destroy` method. **Kind**: static property of [Defaults](#Popper.Defaults) **Properties** @@ -159,7 +170,8 @@ Set to true if you want to automatically remove the popper when you call the `de #### Defaults.modifiers -List of modifiers used to modify the offsets before they are applied to the popper. They provide most of the functionalities of Popper.js. +List of modifiers used to modify the offsets before they are applied to the popper. +They provide most of the functionalities of Popper.js **Kind**: static property of [Defaults](#Popper.Defaults) **Properties** @@ -171,7 +183,9 @@ List of modifiers used to modify the offsets before they are applied to the popp #### Defaults.onCreate() -Callback called when the popper is created.
By default, it is set to no-op.
Access Popper.js instance with `data.instance`. +Callback called when the popper is created.
+By default, is set to no-op.
+Access Popper.js instance with `data.instance`. **Kind**: static method of [Defaults](#Popper.Defaults) **Properties** @@ -183,7 +197,11 @@ Callback called when the popper is created.
By default, it is set to no-op #### Defaults.onUpdate() -Callback called when the popper is updated. This callback is not called on the initialization/creation of the popper, but only on subsequent updates.
By default, it is set to no-op.
Access Popper.js instance with `data.instance`. +Callback called when the popper is updated, this callback is not called +on the initialization/creation of the popper, but only on subsequent +updates.
+By default, is set to no-op.
+Access Popper.js instance with `data.instance`. **Kind**: static method of [Defaults](#Popper.Defaults) **Properties** @@ -195,44 +213,71 @@ Callback called when the popper is updated. This callback is not called on the i ### Popper.placements : enum -List of accepted placements to use as values of the `placement` option.
Valid placements are: - `auto` - `top` - `right` - `bottom` - `left` Each placement can have a variation from this list: - `-start` - `-end` Variations are interpreted easily if you think of them as the left to right written languages. Horizontally (`top` and `bottom`), `start` is left and `end` is right.
Vertically (`left` and `right`), `start` is top and `end` is bottom. Some valid examples are: - `top-end` (on top of reference, right aligned) - `right-start` (on right of reference, top aligned) - `bottom` (on bottom, centered) - `auto-right` (on the side with more space available, alignment depends by placement) +List of accepted placements to use as values of the `placement` option.
+Valid placements are: +- `auto` +- `top` +- `right` +- `bottom` +- `left` + +Each placement can have a variation from this list: +- `-start` +- `-end` + +Variations are interpreted easily if you think of them as the left to right +written languages. Horizontally (`top` and `bottom`), `start` is left and `end` +is right.
+Vertically (`left` and `right`), `start` is top and `end` is bottom. + +Some valid examples are: +- `top-end` (on top of reference, right aligned) +- `right-start` (on right of reference, top aligned) +- `bottom` (on bottom, centered) +- `auto-right` (on the side with more space available, alignment depends by placement) **Kind**: static enum of [Popper](#Popper) **Read only**: true ### Popper.update() -Updates the position of the popper, computing the new offsets and applying the new style.
Prefer `scheduleUpdate` over `update` because of performance reasons. +Updates the position of the popper, computing the new offsets and applying +the new style.
+Prefer `scheduleUpdate` over `update` because of performance reasons. **Kind**: static method of [Popper](#Popper) ### Popper.destroy() -Destroys the popper. +Destroy the popper **Kind**: static method of [Popper](#Popper) ### Popper.enableEventListeners() -It will add resize/scroll events and start recalculating position of the popper element when they are triggered. +It will add resize/scroll events and start recalculating +position of the popper element when they are triggered. **Kind**: static method of [Popper](#Popper) ### Popper.disableEventListeners() -It will remove resize/scroll events and won't recalculate popper position when they are triggered. It also won't trigger `onUpdate` callback anymore, unless you call `update` method manually. +It will remove resize/scroll events and won't recalculate popper position +when they are triggered. It also won't trigger onUpdate callback anymore, +unless you call `update` method manually. **Kind**: static method of [Popper](#Popper) ### Popper.scheduleUpdate() -Schedules an update. It will run on the next UI update available. +Schedule an update, it will run on the next UI update available **Kind**: static method of [Popper](#Popper) ## dataObject -The `dataObject` is an object containing all the information used by Popper.js. This object is passed to modifiers and to the `onCreate` and `onUpdate` callbacks. +The `dataObject` is an object containing all the informations used by Popper.js +this object get passed to modifiers and to the `onCreate` and `onUpdate` callbacks. **Kind**: global variable **Properties** @@ -243,12 +288,12 @@ The `dataObject` is an object containing all the information used by Popper.js. | data.placement | String | Placement applied to popper | | data.originalPlacement | String | Placement originally defined on init | | data.flipped | Boolean | True if popper has been flipped by flip modifier | -| data.hide | Boolean | True if the reference element is out of boundaries, useful to know when to hide the popper | +| data.hide | Boolean | True if the reference element is out of boundaries, useful to know when to hide the popper. | | data.arrowElement | HTMLElement | Node used as arrow by arrow modifier | -| data.styles | Object | Any CSS property defined here will be applied to the popper. It expects the JavaScript nomenclature (eg. `marginBottom`) | -| data.arrowStyles | Object | Any CSS property defined here will be applied to the popper arrow. It expects the JavaScript nomenclature (eg. `marginBottom`) | +| data.styles | Object | Any CSS property defined here will be applied to the popper, it expects the JavaScript nomenclature (eg. `marginBottom`) | +| data.arrowStyles | Object | Any CSS property defined here will be applied to the popper arrow, it expects the JavaScript nomenclature (eg. `marginBottom`) | | data.boundaries | Object | Offsets of the popper boundaries | -| data.offsets | Object | The measurements of popper, reference and arrow elements | +| data.offsets | Object | The measurements of popper, reference and arrow elements. | | data.offsets.popper | Object | `top`, `left`, `width`, `height` values | | data.offsets.reference | Object | `top`, `left`, `width`, `height` values | | data.offsets.arrow | Object | `top` and `left` offsets, only one of them will be different from 0 | @@ -256,7 +301,16 @@ The `dataObject` is an object containing all the information used by Popper.js. ## referenceObject -The `referenceObject` is an object that provides an interface compatible with Popper.js and lets you use it as replacement of a real DOM node.
You can use this method to position a popper relatively to a set of coordinates in case you don't have a DOM node to use as reference. ``` new Popper(referenceObject, popperNode); ``` NB: This feature isn't supported in Internet Explorer 10. +The `referenceObject` is an object that provides an interface compatible with Popper.js +and lets you use it as replacement of a real DOM node.
+You can use this method to position a popper relatively to a set of coordinates +in case you don't have a DOM node to use as reference. + +``` +new Popper(referenceObject, popperNode); +``` + +NB: This feature isn't supported in Internet Explorer 10 **Kind**: global variable **Properties** @@ -270,7 +324,12 @@ The `referenceObject` is an object that provides an interface compatible with Po ## modifiers : object -Modifiers are plugins used to alter the behavior of your poppers.
Popper.js uses a set of 9 modifiers to provide all the basic functionalities needed by the library. Usually you don't want to override the `order`, `fn` and `onLoad` props. All the other properties are configurations that could be tweaked. +Modifiers are plugins used to alter the behavior of your poppers.
+Popper.js uses a set of 9 modifiers to provide all the basic functionalities +needed by the library. + +Usually you don't want to override the `order`, `fn` and `onLoad` props. +All the other properties are configurations that could be tweaked. **Kind**: global namespace @@ -332,7 +391,10 @@ Modifiers are plugins used to alter the behavior of your poppers.
Popper.j ### modifiers~shift -Modifier used to shift the popper on the start or end of its reference element.
It will read the variation of the `placement` property.
It can be one either `-end` or `-start`. +Modifier used to shift the popper on the start or end of its reference +element.
+It will read the variation of the `placement` property.
+It can be one either `-end` or `-start`. **Kind**: inner property of [modifiers](#modifiers) @@ -374,7 +436,39 @@ Modifier used to shift the popper on the start or end of its reference element.< ### modifiers~offset -The `offset` modifier can shift your popper on both its axis. It accepts the following units: - `px` or unit-less, interpreted as pixels - `%` or `%r`, percentage relative to the length of the reference element - `%p`, percentage relative to the length of the popper element - `vw`, CSS viewport width unit - `vh`, CSS viewport height unit For length is intended the main axis relative to the placement of the popper.
This means that if the placement is `top` or `bottom`, the length will be the `width`. In case of `left` or `right`, it will be the `height`. You can provide a single value (as `Number` or `String`), or a pair of values as `String` divided by a comma or one (or more) white spaces.
The latter is a deprecated method because it leads to confusion and will be removed in v2.
Additionally, it accepts additions and subtractions between different units. Note that multiplications and divisions aren't supported. Valid examples are: ``` 10 '10%' '10, 10' '10%, 10' '10 + 10%' '10 - 5vh + 3%' '-10px + 5vh, 5px - 6%' ``` > **NB**: If you desire to apply offsets to your poppers in a way that may make them overlap > with their reference element, unfortunately, you will have to disable the `flip` modifier. > You can read more on this at this [issue](https://github.com/FezVrasta/popper.js/issues/373). +The `offset` modifier can shift your popper on both its axis. + +It accepts the following units: +- `px` or unitless, interpreted as pixels +- `%` or `%r`, percentage relative to the length of the reference element +- `%p`, percentage relative to the length of the popper element +- `vw`, CSS viewport width unit +- `vh`, CSS viewport height unit + +For length is intended the main axis relative to the placement of the popper.
+This means that if the placement is `top` or `bottom`, the length will be the +`width`. In case of `left` or `right`, it will be the height. + +You can provide a single value (as `Number` or `String`), or a pair of values +as `String` divided by a comma or one (or more) white spaces.
+The latter is a deprecated method because it leads to confusion and will be +removed in v2.
+Additionally, it accepts additions and subtractions between different units. +Note that multiplications and divisions aren't supported. + +Valid examples are: +``` +10 +'10%' +'10, 10' +'10%, 10' +'10 + 10%' +'10 - 5vh + 3%' +'-10px + 5vh, 5px - 6%' +``` +> **NB**: If you desire to apply offsets to your poppers in a way that may make them overlap +> with their reference element, unfortunately, you will have to disable the `flip` modifier. +> More on this [reading this issue](https://github.com/FezVrasta/popper.js/issues/373) **Kind**: inner property of [modifiers](#modifiers) @@ -427,7 +521,18 @@ The `offset` modifier can shift your popper on both its axis. It accepts the fo ### modifiers~preventOverflow -Modifier used to prevent the popper from being positioned outside the boundary. A scenario exists where the reference itself is not within the boundaries.
We can say it has "escaped the boundaries" — or just "escaped".
In this case we need to decide whether the popper should either: - detach from the reference and remain "trapped" in the boundaries, or - if it should ignore the boundary and "escape with its reference" When `escapeWithReference` is set to`true` and reference is completely outside its boundaries, the popper will overflow (or completely leave) the boundaries in order to remain attached to the edge of the reference. +Modifier used to prevent the popper from being positioned outside the boundary. + +An scenario exists where the reference itself is not within the boundaries.
+We can say it has "escaped the boundaries" — or just "escaped".
+In this case we need to decide whether the popper should either: + +- detach from the reference and remain "trapped" in the boundaries, or +- if it should ignore the boundary and "escape with its reference" + +When `escapeWithReference` is set to`true` and reference is completely +outside its boundaries, the popper will overflow (or completely leave) +the boundaries in order to remain attached to the edge of the reference. **Kind**: inner property of [modifiers](#modifiers) @@ -487,7 +592,7 @@ Modifier used to prevent the popper from being positioned outside the boundary. | Name | Type | Default | Description | | --- | --- | --- | --- | -| padding | number | 5 | Amount of pixel used to define a minimum distance between the boundaries and the popper. This makes sure the popper always has a little padding between the edges of its container | +| padding | number | 5 | Amount of pixel used to define a minimum distance between the boundaries and the popper this makes sure the popper has always a little padding between the edges of its container | @@ -497,12 +602,16 @@ Modifier used to prevent the popper from being positioned outside the boundary. | Name | Type | Default | Description | | --- | --- | --- | --- | -| boundariesElement | String \| HTMLElement | 'scrollParent' | Boundaries used by the modifier. Can be `scrollParent`, `window`, `viewport` or any DOM element. | +| boundariesElement | String \| HTMLElement | 'scrollParent' | Boundaries used by the modifier, can be `scrollParent`, `window`, `viewport` or any DOM element. | ### modifiers~keepTogether -Modifier used to make sure the reference and its popper stay near each other without leaving any gap between the two. Especially useful when the arrow is enabled and you want to ensure that it points to its reference element. It cares only about the first axis. You can still have poppers with margin between the popper and its reference element. +Modifier used to make sure the reference and its popper stay near eachothers +without leaving any gap between the two. Expecially useful when the arrow is +enabled and you want to assure it to point to its reference element. +It cares only about the first axis, you can still have poppers with margin +between the popper and its reference element. **Kind**: inner property of [modifiers](#modifiers) @@ -544,7 +653,12 @@ Modifier used to make sure the reference and its popper stay near each other wit ### modifiers~arrow -This modifier is used to move the `arrowElement` of the popper to make sure it is positioned between the reference element and its popper element. It will read the outer size of the `arrowElement` node to detect how many pixels of conjunction are needed. It has no effect if no `arrowElement` is provided. +This modifier is used to move the `arrowElement` of the popper to make +sure it is positioned between the reference element and its popper element. +It will read the outer size of the `arrowElement` node to detect how many +pixels of conjuction are needed. + +It has no effect if no `arrowElement` is provided. **Kind**: inner property of [modifiers](#modifiers) @@ -597,7 +711,13 @@ This modifier is used to move the `arrowElement` of the popper to make sure it i ### modifiers~flip -Modifier used to flip the popper's placement when it starts to overlap its reference element. Requires the `preventOverflow` modifier before it in order to work. **NOTE:** this modifier will interrupt the current update cycle and will restart it if it detects the need to flip the placement. +Modifier used to flip the popper's placement when it starts to overlap its +reference element. + +Requires the `preventOverflow` modifier before it in order to work. + +**NOTE:** this modifier will interrupt the current update cycle and will +restart it if it detects the need to flip the placement. **Kind**: inner property of [modifiers](#modifiers) @@ -647,7 +767,7 @@ Modifier used to flip the popper's placement when it starts to overlap its refer | Name | Type | Default | Description | | --- | --- | --- | --- | -| behavior | String \| Array | 'flip' | The behavior used to change the popper's placement. It can be one of `flip`, `clockwise`, `counterclockwise` or an array with a list of valid placements (with optional variations) | +| behavior | String \| Array | 'flip' | The behavior used to change the popper's placement. It can be one of `flip`, `clockwise`, `counterclockwise` or an array with a list of valid placements (with optional variations). | @@ -667,12 +787,14 @@ Modifier used to flip the popper's placement when it starts to overlap its refer | Name | Type | Default | Description | | --- | --- | --- | --- | -| boundariesElement | String \| HTMLElement | 'viewport' | The element which will define the boundaries of the popper position. The popper will never be placed outside of the defined boundaries (except if `keepTogether` is enabled) | +| boundariesElement | String \| HTMLElement | 'viewport' | The element which will define the boundaries of the popper position, the popper will never be placed outside of the defined boundaries (except if keepTogether is enabled) | ### modifiers~inner -Modifier used to make the popper flow toward the inner of the reference element. By default, when this modifier is disabled, the popper will be placed outside the reference element. +Modifier used to make the popper flow toward the inner of the reference element. +By default, when this modifier is disabled, the popper will be placed outside +the reference element. **Kind**: inner property of [modifiers](#modifiers) @@ -714,7 +836,12 @@ Modifier used to make the popper flow toward the inner of the reference element. ### modifiers~hide -Modifier used to hide the popper when its reference element is outside of the popper boundaries. It will set a `x-out-of-boundaries` attribute which can be used to hide with a CSS selector the popper when its reference is out of boundaries. Requires the `preventOverflow` modifier before it in order to work. +Modifier used to hide the popper when its reference element is outside of the +popper boundaries. It will set a `x-out-of-boundaries` attribute which can +be used to hide with a CSS selector the popper when its reference is +out of boundaries. + +Requires the `preventOverflow` modifier before it in order to work. **Kind**: inner property of [modifiers](#modifiers) @@ -756,7 +883,16 @@ Modifier used to hide the popper when its reference element is outside of the po ### modifiers~computeStyle -Computes the style that will be applied to the popper element to gets properly positioned. Note that this modifier will not touch the DOM, it just prepares the styles so that `applyStyle` modifier can apply it. This separation is useful in case you need to replace `applyStyle` with a custom implementation. This modifier has `850` as `order` value to maintain backward compatibility with previous versions of Popper.js. Expect the modifiers ordering method to change in future major versions of the library. +Computes the style that will be applied to the popper element to gets +properly positioned. + +Note that this modifier will not touch the DOM, it just prepares the styles +so that `applyStyle` modifier can apply it. This separation is useful +in case you need to replace `applyStyle` with a custom implementation. + +This modifier has `850` as `order` value to maintain backward compatibility +with previous versions of Popper.js. Expect the modifiers ordering method +to change in future major versions of the library. **Kind**: inner property of [modifiers](#modifiers) @@ -806,7 +942,7 @@ Computes the style that will be applied to the popper element to gets properly p | Name | Type | Default | Description | | --- | --- | --- | --- | -| gpuAcceleration | Boolean | true | If true, it uses the CSS 3D transformation to position the popper. Otherwise, it will use the `top` and `left` properties | +| gpuAcceleration | Boolean | true | If true, it uses the CSS 3d transformation to position the popper. Otherwise, it will use the `top` and `left` properties. | @@ -831,7 +967,16 @@ Computes the style that will be applied to the popper element to gets properly p ### modifiers~applyStyle -Applies the computed styles to the popper element. All the DOM manipulations are limited to this modifier. This is useful in case you want to integrate Popper.js inside a framework or view library and you want to delegate all the DOM manipulations to it. Note that if you disable this modifier, you must make sure the popper element has its position set to `absolute` before Popper.js can do its work! Just disable this modifier and define your own to achieve the desired effect. +Applies the computed styles to the popper element. + +All the DOM manipulations are limited to this modifier. This is useful in case +you want to integrate Popper.js inside a framework or view library and you +want to delegate all the DOM manipulations to it. + +Note that if you disable this modifier, you must make sure the popper element +has its position set to `absolute` before Popper.js can do its work! + +Just disable this modifier and define you own to achieve the desired effect. **Kind**: inner property of [modifiers](#modifiers) @@ -892,7 +1037,7 @@ Applies the computed styles to the popper element. All the DOM manipulations ar | Name | Type | Default | Description | | --- | --- | --- | --- | -| gpuAcceleration | Boolean | true | If true, it uses the CSS 3D transformation to position the popper. Otherwise, it will use the `top` and `left` properties | +| gpuAcceleration | Boolean | true | If true, it uses the CSS 3d transformation to position the popper. Otherwise, it will use the `top` and `left` properties. | @@ -908,7 +1053,10 @@ Get the window associated with the element ## ModifierFn(data, options) ⇒ [dataObject](#dataObject) -Modifier function, each modifier can have a function of this type assigned to its `fn` property.
These functions will be called on each update, this means that you must make sure they are performant enough to avoid performance bottlenecks. +Modifier function, each modifier can have a function of this type assigned +to its `fn` property.
+These functions will be called on each update, this means that you must +make sure they are performant enough to avoid performance bottlenecks. **Kind**: global function **Returns**: [dataObject](#dataObject) - The data object, properly modified