# Specification



## Terminology

`main-axis`:: The axis which is parallel with the side of the `target` that the `popover` is laid out upon. If the `popover` is left _or_ right of the `target` then the `main-axis` is horizontal. If the `popover` is above _or_ below the `target` then the `main-axis` is vertical.

`cross-axis`:: The axis which is counter to the `main-axis`.

`zone`:: The maximum-sized rectangle in a particular direction between one side of the `target` and the `window bounds`. There are four possible `zones` therefore: `top` `right` `bottom` `left`.

`target`:: The element that the `popover` calculates its position relative to.

`docking edge`:: The edge of `body` that is closest to `target` or vice-versa.



## Requirements

. The `popover` MUST reference a **target**.

. The `popover` MUST have a **body** whose contents may be any view.

.. The `body` should autosize to the dimensions of its contents.

.. `body bounds` MUSNT exceed `window bounds`.

.. There SHOULD be a small visual gap between the respective boundaries of `body` and `window`.

.. The `body` MUST bias toward **cross-axis** centre-alignment with the `target`'s centre `registration point` up until such movement would break requirement `2.ii`.

.. The `docking edge` of the `body` must be sufficiently spaced from `target` to fit `tip`.

. The `popover` MUST automatically choose to layout in one of the four **zones**. The selected `zone` MUST be the one with the largest area.

.. A `zone` preference MAY be given so that if multiple `zone` areas can wholly fit the `popover` one can be chosen over others even if it is of a lesser area.

. The `popover` MUST have a **tip** that is connected to the `body` and points to the centre **registration point** of the `target`'s `docking edge`.

.. The `tip` should automatically position itself on the `body`'s `docking edge`.

.. The `tip` should bias toward centre-alignment of itself on the `cross-axis` up to such a point that it does not exceed the `body bounds`.

.. If the `body bounds` have reached `window bounds` then the `tip` should slide along its own `cross-axis` until it reaches either centre-alignment with `target` or `body` bounds first.

.. The `tip` SHOULD be an equilateral triangle shape until doing so would no longer allow it to fit within `body bounds`. At that point it MUST be a right-angle triangle with the hypotenuse oriented toward the opposite `cross-axis` end of `body`.

. When the `target position` or `target bounds` or `window bounds` change the `popover` should recalculate its `body` and `tip` layout.

. When the `window bounds` change the `popover` should recalculate its `body` and `tip` position.



## Limitations of this specification

. Behaviour of what to do when `target` exits `window bounds` is undefined.

. A `zone` preference is only eligible when multiple `zones` wholly fit the `body`. A more sophisticated algorithm could account for percentage-fit such that a `zone` would be used even if it did not wholly fit `body` and even while other `zones` do.

. Layout thrashing of `body` changing zones can be mitigated by hysteresis and/or throttling techniques but is not specified here.

. Only behaviour for rectangular `target` and `popovers` are specified.