Panel API - Panel Collision Management

[mweech]

This is a repost from #3288 (comment) originally written by @milesap

General Outline

The following is a general outline of how the new panel system will manage panel "collisions". A collision is when a panel (lets call it the overlaying panel) attempts to open either partically or fully over one or more other panels (which we'll call the underlay panels).

Goal

To provide a simple mechanism for panels to co-exist on a 2D plane without the need for individual panels to monitor and react to external changes in regards to new panels being created, moved, or opened/closed.

Panel underlay rules

A panel can prescribe to one of three underlay rules during its creation, depending on its needs and which are enforced by the RAMP panel API once the panel has successfully opened. The rule governs what happens to the panel when another panel is trying to open over it.

• default: this panel will be hidden from view - likely with the css property visibility:hidden. An observable named hiding will emit with the overlaying panel instance. This panels visibility will be restored once the overlay panel has closed.
• close: this panel will be closed using the panel API method close. It is not restored automatically.
• persistent: this panel refuses to hide or close. The call to open on the overlaying panel will fail and it will need to locate another spot or fail gracefully.

General comments

The open method will be altered to open(): {status: boolean | panels: Panel[] which now returns a boolean status indicating if the operation was successful and an array of panels that occupied its space.

A panel cannot change its underlay rule.

A panel should not change its relative position, or have its computed width/height altered once opened. Doing so triggers an underlay rule check which if failed causes the panel to be closed. Monitoring panels can be done with a MutationObserver scanning for changes to the styles property and changes to the viewport size.

When the viewport size changes the underlay rules are verified in the order the panels were opened.

[mweech]

Comment from @james-rae, originally here: #3288 (comment)

I'm not a UI guy, but I might be worried that in default mode, I'd think the panel had closed when it goes invisible.

Would making it something like 60% transparent work? I guess that is problematic as the user could still interact with it.

Arnold "I'll be back" gif?

[mweech]

Comment from @ShrutiVellanki, originally here: #3288 (comment)

On Underlay Rules:

---

I like the three types of "underlay rules" but I'm just worried something like this could happen:

• panel 1 subscribes to a default rule
• panel 2 subscribes to a close rule
• panel 3 subscribes to a persistent rule

Panel 4 is trying to open on top of all three of them.

• Panel 1 becomes invisible
• Panel 2 closes
• Panel 4 can't open in 3's spot so it relocates with 3 still open

You close Panel 4.

• Panel 1 is visible again, Panel 3 was always visible. Panel 2 is still closed.

Maybe this scenario is unlikely but it seems like somewhat of a weird possible experience.

---

Possible combined solution: Stubborn Panels + Accommodating Panels.

Stubborn Panels

A similar approach to what @james-rae said would work for panels like the side menu and "Link to Share":

They "grey out" + "freeze" ALL OTHER panels when open, and make it impossible for anyone to interact with them/open them until they are closed. If panels like these are on top, any other panel trying to open through the API fails until they are closed, period.

Accommodating Panels

An example of this panel would be enhancedTable/meta data/settings...to me, intuitively at least, it seems that if a user is trying to open metadata when enhancedTable was open, they want to interact with metadata ASAP (especially since they are tied to the same underlying feature), so enhancedTable should be accommodating enough to close (and vice versa).

Note that this use case would only make sense for panels that save their state on close...(enhancedTable does this and so does import wizard if you try and open up layers in the middle of it). This way the user knows that their progress won't be lost even if the panel disappears from view. If they don't save their state on close, they should be a stubborn panel.

[mweech]

Lots of great points above, but feels like it needs to be distilled into answering overarching questions before defining the modes we want to define.

So questions:

1. should a panel define how it wants to be handled? i.e. close, overlay (partial transparency?), protected (no overlay)

2. should a panel be able to invoke actions on other panels, or should that occur automatically based on declared intentions? i.e. should we make sure plugins can't mess with our panel states, only trigger automatic behavior

3. should a panel only be able to complete its action, if it is valid? i.e. prevent panel from opening if it would overlay a protected panel

4. are there default "panel stacks" that would help keep plugins from getting cluttered? i.e. "legend stack", "datagrid stack"

[dane-thomas]

A panel should not change its relative position, or have its computed width/height altered once opened.

Would this cause issues with the maximize/split feature of the table?

---

@ShrutiVellanki
As I understand it the problem is inconsistency between the panels?
If that's the case I believe the panels we use internally will have consistent interactions but the three options are viable ways for panels to interact. It should really be up to the map author to make sure there's consistency between their panels.

According to the panel docs, the side menu and link to share are not exactly the same types of panels and none of the panels listed in the doc would want to prevent the rest of the map from being interacted with.

[mweech]

Distilled this from a chat with Alex.. suggestion:

-Panel can be opened with three default behaviors:
- close on overlay (panel opens on top, it closes.. simple)
- transparent on overlay (panel opens on top, it becomes semi-transparent and interaction is disabled
- protected (no overlay allowed)

when a panel is protected, other panels cannot open over top of it. to avoid cases where a panel just randomly fails to open, we do either of the following:
- provide either a toast message with "Setting panel blocked Plugin panel from opening"
OR
- force panel to open underneath protected panel (drawback: if it is "close on overlay", it might disappear)

[milespetrov]

An alternate idea for the pile:

• Covering any part of a panel body hides that panel body so that only the panel header is shown.
• Covering any part of a panel header or within its margin space (~10px) closes it.
• There are no protected panels.

In the image above if Panel 3 opens last it would hide the "Some text" bodies of both Panel 1 & 2. Toggling the body of either Panel 1 or 2 (via a button in the respective header) would close Panel 3 since its header is being partially covered.

All panels would behave in the same way. No special rules. Likely half the complexity to implement. We can always hard code an area or two as "no fly zones" for panels if we need a viewer control to be always visible (such as the main bar).

[mweech]

its an interesting solution and would simplify things for a developer, but is adding a special button to the header going to be intuitive for the user? is there a middle ground that avoids complicated logic but has little learning curve??

[mweech]

Based on RAMP meeting on 2019/2/21

• A panel can do one of two things if it is covered by another panel:
  - close if covered
  - stays open if covered

• A panel is still interactive, even when covered by another panel.

• When a panel is opened it is placed on top by default and an X button to close is added to allow the user to close it. A panel can also be opened without an X to close, but it is placed at the bottom.

• Guidance will be provided to specify common areas to use for placing panels (i.e. grid area, legend area, etc), and suggested practices to avoid (do not make a fake legend).

• By comparison, dialogues are opened on top, and are the only interactive component until closed. Guidance should include notes on dialogue box usage as well.