File: widget-position-constrain/js/Widget-PositionConstrain.js

            /**
             * Provides constrained xy positioning support for Widgets, through an extension.
             *
             * It builds on top of the widget-position module, to provide constrained positioning support.
             *
             * @module widget-position-constrain
             */
            var CONSTRAIN = "constrain",
                CONSTRAIN_XYCHANGE = "constrain|xyChange",
                CONSTRAIN_CHANGE = "constrainChange",
            
                PREVENT_OVERLAP = "preventOverlap",
                ALIGN = "align",
            
                EMPTY_STR = "",
            
                BINDUI = "bindUI",
            
                XY = "xy",
                X_COORD = "x",
                Y_COORD = "y",
            
                Node = Y.Node,
            
                VIEWPORT_REGION = "viewportRegion",
                REGION = "region",
            
                PREVENT_OVERLAP_MAP;
            
            /**
             * A widget extension, which can be used to add constrained xy positioning support to the base Widget class,
             * through the <a href="Base.html#method_build">Base.build</a> method. This extension requires that
             * the WidgetPosition extension be added to the Widget (before WidgetPositionConstrain, if part of the same
             * extension list passed to Base.build).
             *
             * @class WidgetPositionConstrain
             * @param {Object} User configuration object
             */
            function PositionConstrain(config) {}
            
            /**
             * Static property used to define the default attribute
             * configuration introduced by WidgetPositionConstrain.
             *
             * @property ATTRS
             * @type Object
             * @static
             */
            PositionConstrain.ATTRS = {
            
                /**
                 * @attribute constrain
                 * @type boolean | Node
                 * @default null
                 * @description The node to constrain the widget's bounding box to, when setting xy. Can also be
                 * set to true, to constrain to the viewport.
                 */
                constrain : {
                    value: null,
                    setter: "_setConstrain"
                },
            
                /**
                 * @attribute preventOverlap
                 * @type boolean
                 * @description If set to true, and WidgetPositionAlign is also added to the Widget,
                 * constrained positioning will attempt to prevent the widget's bounding box from overlapping
                 * the element to which it has been aligned, by flipping the orientation of the alignment
                 * for corner based alignments
                 */
                preventOverlap : {
                    value:false
                }
            };
            
            /**
             * @property _PREVENT_OVERLAP
             * @static
             * @protected
             * @type Object
             * @description The set of positions for which to prevent
             * overlap.
             */
            PREVENT_OVERLAP_MAP = PositionConstrain._PREVENT_OVERLAP = {
                x: {
                    "tltr": 1,
                    "blbr": 1,
                    "brbl": 1,
                    "trtl": 1
                },
                y : {
                    "trbr": 1,
                    "tlbl": 1,
                    "bltl": 1,
                    "brtr": 1
                }
            };
            
            PositionConstrain.prototype = {
            
                initializer : function() {
                    if (!this._posNode) {
                        Y.error("WidgetPosition needs to be added to the Widget, before WidgetPositionConstrain is added");
                    }
                    Y.after(this._bindUIPosConstrained, this, BINDUI);
                },
            
                /**
                 * Calculates the constrained positions for the XY positions provided, using
                 * the provided node argument is passed in. If no node value is passed in, the value of
                 * the "constrain" attribute is used.
                 *
                 * @method getConstrainedXY
                 * @param {Array} xy The xy values to constrain
                 * @param {Node | boolean} node Optional. The node to constrain to, or true for the viewport
                 * @return {Array} The constrained xy values
                 */
                getConstrainedXY : function(xy, node) {
                    node = node || this.get(CONSTRAIN);
            
                    var constrainingRegion = this._getRegion((node === true) ? null : node),
                        nodeRegion = this._posNode.get(REGION);
            
                    return [
                        this._constrain(xy[0], X_COORD, nodeRegion, constrainingRegion),
                        this._constrain(xy[1], Y_COORD, nodeRegion, constrainingRegion)
                    ];
                },
            
                /**
                 * Constrains the widget's bounding box to a node (or the viewport). If xy or node are not
                 * passed in, the current position and the value of "constrain" will be used respectively.
                 *
                 * The widget's position will be changed to the constrained position.
                 *
                 * @method constrain
                 * @param {Array} xy Optional. The xy values to constrain
                 * @param {Node | boolean} node Optional. The node to constrain to, or true for the viewport
                 */
                constrain : function(xy, node) {
                    var currentXY,
                        constrainedXY,
                        constraint = node || this.get(CONSTRAIN);
            
                    if (constraint) {
                        currentXY = xy || this.get(XY);
                        constrainedXY = this.getConstrainedXY(currentXY, constraint);
            
                        if (constrainedXY[0] !== currentXY[0] || constrainedXY[1] !== currentXY[1]) {
                            this.set(XY, constrainedXY, { constrained:true });
                        }
                    }
                },
            
                /**
                 * The setter implementation for the "constrain" attribute.
                 *
                 * @method _setConstrain
                 * @protected
                 * @param {Node | boolean} val The attribute value
                 */
                _setConstrain : function(val) {
                    return (val === true) ? val : Node.one(val);
                },
            
                /**
                 * The method which performs the actual constrain calculations for a given axis ("x" or "y") based
                 * on the regions provided.
                 *
                 * @method _constrain
                 * @protected
                 *
                 * @param {Number} val The value to constrain
                 * @param {String} axis The axis to use for constrainment
                 * @param {Region} nodeRegion The region of the node to constrain
                 * @param {Region} constrainingRegion The region of the node (or viewport) to constrain to
                 *
                 * @return {Number} The constrained value
                 */
                _constrain: function(val, axis, nodeRegion, constrainingRegion) {
                    if (constrainingRegion) {
            
                        if (this.get(PREVENT_OVERLAP)) {
                            val = this._preventOverlap(val, axis, nodeRegion, constrainingRegion);
                        }
            
                        var x = (axis == X_COORD),
            
                            regionSize    = (x) ? constrainingRegion.width : constrainingRegion.height,
                            nodeSize      = (x) ? nodeRegion.width : nodeRegion.height,
                            minConstraint = (x) ? constrainingRegion.left : constrainingRegion.top,
                            maxConstraint = (x) ? constrainingRegion.right - nodeSize : constrainingRegion.bottom - nodeSize;
            
                        if (val < minConstraint || val > maxConstraint) {
                            if (nodeSize < regionSize) {
                                if (val < minConstraint) {
                                    val = minConstraint;
                                } else if (val > maxConstraint) {
                                    val = maxConstraint;
                                }
                            } else {
                                val = minConstraint;
                            }
                        }
                    }
            
                    return val;
                },
            
                /**
                 * The method which performs the preventOverlap calculations for a given axis ("x" or "y") based
                 * on the value and regions provided.
                 *
                 * @method _preventOverlap
                 * @protected
                 *
                 * @param {Number} val The value being constrain
                 * @param {String} axis The axis to being constrained
                 * @param {Region} nodeRegion The region of the node being constrained
                 * @param {Region} constrainingRegion The region of the node (or viewport) we need to constrain to
                 *
                 * @return {Number} The constrained value
                 */
                _preventOverlap : function(val, axis, nodeRegion, constrainingRegion) {
            
                    var align = this.get(ALIGN),
                        x = (axis === X_COORD),
                        nodeSize,
                        alignRegion,
                        nearEdge,
                        farEdge,
                        spaceOnNearSide,
                        spaceOnFarSide;
            
                    if (align && align.points && PREVENT_OVERLAP_MAP[axis][align.points.join(EMPTY_STR)]) {
            
                        alignRegion = this._getRegion(align.node);
            
                        if (alignRegion) {
                            nodeSize        = (x) ? nodeRegion.width : nodeRegion.height;
                            nearEdge        = (x) ? alignRegion.left : alignRegion.top;
                            farEdge         = (x) ? alignRegion.right : alignRegion.bottom;
                            spaceOnNearSide = (x) ? alignRegion.left - constrainingRegion.left : alignRegion.top - constrainingRegion.top;
                            spaceOnFarSide  = (x) ? constrainingRegion.right - alignRegion.right : constrainingRegion.bottom - alignRegion.bottom;
                        }
            
                        if (val > nearEdge) {
                            if (spaceOnFarSide < nodeSize && spaceOnNearSide > nodeSize) {
                                val = nearEdge - nodeSize;
                            }
                        } else {
                            if (spaceOnNearSide < nodeSize && spaceOnFarSide > nodeSize) {
                                val = farEdge;
                            }
                        }
                    }
            
                    return val;
                },
            
                /**
                 * Binds event listeners responsible for updating the UI state in response to
                 * Widget constrained positioning related state changes.
                 * <p>
                 * This method is invoked after bindUI is invoked for the Widget class
                 * using YUI's aop infrastructure.
                 * </p>
                 *
                 * @method _bindUIPosConstrained
                 * @protected
                 */
                _bindUIPosConstrained : function() {
                    this.after(CONSTRAIN_CHANGE, this._afterConstrainChange);
                    this._enableConstraints(this.get(CONSTRAIN));
                },
            
                /**
                 * After change listener for the "constrain" attribute, responsible
                 * for updating the UI, in response to attribute changes.
                 *
                 * @method _afterConstrainChange
                 * @protected
                 * @param {EventFacade} e The event facade
                 */
                _afterConstrainChange : function(e) {
                    this._enableConstraints(e.newVal);
                },
            
                /**
                 * Updates the UI if enabling constraints, and sets up the xyChange event listeners
                 * to constrain whenever the widget is moved. Disabling constraints removes the listeners.
                 *
                 * @method _enableConstraints
                 * @private
                 * @param {boolean} enable Enable or disable constraints
                 */
                _enableConstraints : function(enable) {
                    if (enable) {
                        this.constrain();
                        this._cxyHandle = this._cxyHandle || this.on(CONSTRAIN_XYCHANGE, this._constrainOnXYChange);
                    } else if (this._cxyHandle) {
                        this._cxyHandle.detach();
                        this._cxyHandle = null;
                    }
                },
            
                /**
                 * The on change listener for the "xy" attribute. Modifies the event facade's
                 * newVal property with the constrained XY value.
                 *
                 * @method _constrainOnXYChange
                 * @protected
                 * @param {EventFacade} e The event facade for the attribute change
                 */
                _constrainOnXYChange : function(e) {
                    if (!e.constrained) {
                        e.newVal = this.getConstrainedXY(e.newVal);
                    }
                },
            
                /**
                 * Utility method to normalize region retrieval from a node instance,
                 * or the viewport, if no node is provided.
                 *
                 * @method _getRegion
                 * @private
                 * @param {Node} node Optional.
                 */
                _getRegion : function(node) {
                    var region;
                    if (!node) {
                        region = this._posNode.get(VIEWPORT_REGION);
                    } else {
                        node = Node.one(node);
                        if (node) {
                            region = node.get(REGION);
                        }
                    }
                    return region;
                }
            };
            
            Y.WidgetPositionConstrain = PositionConstrain;