#1847084: Measure/track displacing elements better + provide change events for them (fix overlay + toolbar) introduces a method to the JavaScript Drupal object -- displace.
The displace method finds elements in the DOM marked with one of four attributes: data-offset-top, data-offset-right, data-offset-bottom or data-offset-left.
Modules that apply one of these four attributes to their markup indicate that their DOM components can potentially shift (hence displace) other DOM elements from their initial positions. This happens in the case of the Toolbar, that marks its horizontal bars with data-offset-top and its trays with data-offset-left or data-offset-right, depending on text direction. The displace method, on screen resize, or when the method is invoked, calculates the height or width of these elements and then triggers a drupalViewportOffsetChange event on the document. The updated offset values are passed as an argument. The argument is an object with four keys -- one for each edge.
Much of this code was inspired by the Overlay module, which had performed similar calculations just for its own components. Now this placement strategy has been externalized and made available to any module.
At the moment, the Overlay module and the tableheader.js utility listen to the drupalViewportOffsetChange event.
When many displacing elements exist on an edge, the biggest or most offset one produces the offset value for that edge. In this way, offsetting elements are not additive, they are superlative. Here is a demonstrative illustration that depicts in wireframe form a mocked up left-offsetting pair of elements and a window similar to the Overlay.
The displace method should be used for overlay and modal like components that mustn't overlap with ever-present administrative elements like the Toolbar.
Tests, utilizing the Testswarm project, can be found in the FAT module: http://drupal.org/project/fat
