Consistent container update / removal

[etpinard]

fixes #1069

Currently, relayout is allowed to be called with 💠 special 💠 'add' and 'remove' values for annotations and shapes. For example,

Plotly.relayout(gd, 'annotations', 'add');
// => adds a blank annotations

Plotly.relayout(gd, 'annotations[2]', 'remove');
// => remove the 3rd annotation

which gets the job done, but is a little sloppy. We can do better and luckily 'add' and 'remove' we're never implemented for the new (e.g. images, updatemenus, sliders, mapbox layers) layout array containers.

This PR enforces,

Plotly.relayout(gd, `${containerName}[${itemIndex}]`, null);

as a way to delete items in containers found in layout. Similarly,

Plotly.restyle(gd, `transforms[${itemIndex}]`, null, [`${traceIndex}`]);

will delete transform item in the relevant trace(s).

Moreover,

Plotly.relayout(gd, `${containerName}[${newItemIndex}]`, {
  // container item opts 
});

will consistently add items to the array container if newItemIndex is beyond the current container length.

[etpinard]

I made a PR right now even this is a WIP as this was the last remaning item in the v1.19.0 without a corresponding PR. I'll wrap this is up tomorrow.

TODO:

• add mucho tests
• add restyle logic for transforms

[rreusser]

Love it. Nice refactor.

[etpinard]

Yep. I thought exposing plots.layoutArrayContainers was a nice compromise.

Next step would be to auto-generate that list using the plot-schema. (later ...)

[rreusser]

Outstanding! What happens to the surrounding indices when you do that? Presumably it's up to the user/front-end to manage references to non-existent array elements. Like if you have [annotation1, annotation2] and you remove the first annotation. Do you then have [null, annotation2] or [annotation2]?

[etpinard]

Do you then have [null, annotation2] or [annotation2]?

you have [annotation2]

That is, null clears items in the array containers.

[bpostlethwaite]

Is there a place we can add a deprecation notice about the 'add' and 'remove' API? Do any docs need updating? Should we add an issue in the Plotlyjs 2.0 to remove 'add' and 'remove' as part of that Milestone?

[bpostlethwaite]

💃 for the PR. Just a few questions

[etpinard]

Is there a place we can add a deprecation notice about the 'add' and 'remove' API? Do any docs need updating?

I don't any reference of 'add' or 'remove' under https://plot.ly/javascript/#chart-events maybe @cldougl would know more?

Should we add an issue in the Plotlyjs 2.0 to remove 'add' and 'remove' as part of that Milestone?

Good call. I'll add it to #420

[rreusser]

@etpinard That makes sense. I'll only point out the obvious possibility of writing code that references other items by array index.