spec.adoc

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

1. The popover MUST reference a target.

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

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

   2. body bounds MUSNT exceed window bounds.

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

   4. 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.

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

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

   1. 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.

4. 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.

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

   2. 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.

   3. 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.

   4. 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.

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

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

Limitations of this specification

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

2. 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.

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

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