|
|
@@ -17,7 +17,61 @@ import getPositionedAncestor from './getpositionedancestor.js';
|
|
|
* target in the visually most efficient way, taking various restrictions like viewport or limiter geometry
|
|
|
* into consideration.
|
|
|
*
|
|
|
- * TODO: more docs and example.
|
|
|
+ * // The element which is to be positioned.
|
|
|
+ * const element = document.body.querySelector( '#toolbar' );
|
|
|
+ *
|
|
|
+ * // A target to which the element is positioned relatively.
|
|
|
+ * const target = document.body.querySelector( '#container' );
|
|
|
+ *
|
|
|
+ * // Finding the optimal coordinates for the positioning.
|
|
|
+ * const { left, top, name } = getOptimalPosition( {
|
|
|
+ * element: element,
|
|
|
+ * target: target,
|
|
|
+ *
|
|
|
+ * // The algorithm will chose among these positions to meet the requirements such
|
|
|
+ * // as "limiter" element or "fitInViewport", set below. The positions are considered
|
|
|
+ * // in the order of the array.
|
|
|
+ * positions: [
|
|
|
+ * //
|
|
|
+ * // [ Target ]
|
|
|
+ * // +-----------------+
|
|
|
+ * // | Element |
|
|
|
+ * // +-----------------+
|
|
|
+ * //
|
|
|
+ * targetRect => ( {
|
|
|
+ * top: targetRect.bottom,
|
|
|
+ * left: targetRect.left,
|
|
|
+ * name: 'mySouthEastPosition'
|
|
|
+ * } ),
|
|
|
+ *
|
|
|
+ * //
|
|
|
+ * // +-----------------+
|
|
|
+ * // | Element |
|
|
|
+ * // +-----------------+
|
|
|
+ * // [ Target ]
|
|
|
+ * //
|
|
|
+ * ( targetRect, elementRect ) => ( {
|
|
|
+ * top: targetRect.top - elementRect.height,
|
|
|
+ * left: targetRect.left,
|
|
|
+ * name: 'myNorthEastPosition'
|
|
|
+ * } )
|
|
|
+ * ],
|
|
|
+ *
|
|
|
+ * // Find a position such guarantees the element remains within visible boundaries of <body>.
|
|
|
+ * limiter: document.body,
|
|
|
+ *
|
|
|
+ * // Find a position such guarantees the element remains within visible boundaries of the browser viewport.
|
|
|
+ * fitInViewport: true
|
|
|
+ * } );
|
|
|
+ *
|
|
|
+ * // The best position which fits into document.body and the viewport. May be useful
|
|
|
+ * // to set proper class on the `element`.
|
|
|
+ * console.log( name ); -> "myNorthEastPosition"
|
|
|
+ *
|
|
|
+ * // Using the absolute coordinates which has been found to position the element
|
|
|
+ * // as in the diagram depicting the "myNorthEastPosition" position.
|
|
|
+ * element.style.top = top;
|
|
|
+ * element.style.left = left;
|
|
|
*
|
|
|
* @param {module:utils/dom/position~Options} options Positioning options object.
|
|
|
* @returns {module:utils/dom/position~Position}
|