1863404 - [Docs] Add a more detailed explanation of feature callout panel/arrow positions, with diagrams

Status: NEW

(Firefox :: Messaging System, task, P3)

Description

[Shane Hughes [:aminomancer]]

The most confusing part about Feature Callout is the confusing part about XUL popups in general - the popup positioning system. Feature Callouts (and popups generally) accept 2 main positional values: the anchor attachment point and the popup attachment point. The anchor attachment point defines where on the anchor element the callout should be attached. And the popup attachment point defines which point on the callout should be attached to the anchor attachment point.

So you can think about it like you're pinning a poster on a wall. You have to choose the intersection points between the pin, the poster, and the wall. That means you're choosing two things: where on the wall the pin will go through, and where on the poster the pin will go through. Which part of the poster is attached to which part of the wall.

With the feature callout panel changes, popups now support attachment points in all 8 cardinal and semi-cardinal directions. Think of it like North, Northeast, East, Southeast, and so on. But instead they are called topcenter, topright, rightcenter, bottomright, and so on. So the callout and the anchor both get one of those values and that determines where the arrow is on the callout (provided the arrow is not hidden) and where the callout attaches to the anchor.

That means there are lots of possible configurations, and there's also the option to hide the arrow. Also, if the callout cannot fit in its desired position (e.g. because it would bleed off the edge of the screen), it will flip or slide.

For example, if we use an anchor attachment of bottomcenter and a callout attachment of topcenter, the desired position is that the callout appears under the anchor, pointing up to it. But if the callout would bleed off the bottom of the screen, it will flip to the reverse instead: the callout will appear above the anchor, pointing down to it.

If, instead, the callout is too close to the right or left side of the screen, such that it would bleed off one of the horizontal edges, then it can't flip, because the arrow is not horizontal. So instead the callout will hide its arrow and slide, appearing as close to the anchor element as possible.

These are a lot of possibilities to consider, and I've done my best to convey it in words, but it's really the kind of thing you have to see to understand. For the preliminary documentation, I think screenshots will do the best job. Adding text to the screenshots to label them will help, like diagrams. In the long run, this is the kind of thing our CMS should be able to preview, so it should all be pretty intuitive eventually. But for now, just add a brief explanation with labeled screenshots of a handful of the more popular configurations (bottomcenter topcenter, bottomcenter topright, etc.) and what happens when they flip or slide.

Comment 1

[Shane Hughes [:aminomancer]]

There are also supposed to be offset properties that can nudge the callout away from its computed position by a certain fixed pixel value, but these have yet to be implemented. So, for whoever takes this, check on bug 1863384 before you start. If it's not complete then skip over it, and whoever does bug 1863384 can handle the documentation for it. But if it's complete, then you should also include those offset properties in the panel position explanation.

Comment 2

[Shane Hughes [:aminomancer]]

Jason, I'm compiling a list of easy first bugs for other team members to get into feature callout. Are you working on this or can we add it to the list?

Comment 3

[Jason Prickett]

We can add this to the list!