[Overlay]: update and expand documentation

[najikahalsema]

Code of conduct

• I agree to follow this project's code of conduct.

Description of issue

Our overlay component is pretty complex, and our docs should cover those complexities. When we did a walkthrough of how to consume this component, there were a few things that weren't clear in the documentation. I think it would be great if we could write these docs in plain language and include examples for all the different usages we outline. Some specific things I noticed:

• The TriggerInteraction example is using 'click', but what we discussed pointed to 'modal' being the most accessible interaction to use. This isn't clear, and if I were a consumer, I would probably default to 'click' since that's the example the docs give me. Some further description of the different types of interactions would help our consumers decide which is best for their use case.
• Styling the component should be expounded upon to explain the 3 methods of inline styles, a <style> tag, and usage of css. Including examples for each.
• Documenting how to use theVirtualTrigger().
• Should we include documentation for managing focus and position?
• What about documenting how the overlay interacts with the shadowDOM/light DOM/DOM tree in general?

[Westbrook]

@najikahalsema does it make sense to split this issue up into the pieces of have yet to be addressed for easier consumption by contributors and the team?

I think 1, 2 and 5 might no longer be needed (post v2), but please use your judgement.

[najikahalsema]

I agree with you. I wonder if we would also still need to document the focus and positioning, though. Unfortunately, past Najika was not so verbose and I'm wondering what I meant, exactly. We have some documenting of the positioning and focus in the Imperative API docs. Do we feel this is sufficient?

[Westbrook]

• Focus may be included in the new docs, but I could take notes on more clear information that we could share. This may just need to wait until someone asks for something, but possibly @TarunAdobe @blunteshwar or @Rajdeepc might have insight here having come more recently to the project?
• Positioning could definitely be expanded. In specific we now have the PlacementController that could be leveraged in other contexts (like a single top-layer submenu system, right now we use a new top-layer for each level of submenu).

[Westbrook]

@TarunAdobe with your upcoming presentation on the inner working of the Overlay API, I'd really appreciate your thoughts on how best to expand our documentation coverage of this API.

[TarunAdobe]

YESSSS!!!. I'll keep that in mind.

[TarunAdobe]

wip - https://paper.dropbox.com/doc/Lets-improve-Overlay-API-Documentation--CH3fZ3rEDAS2A4v_onb4k0HkAg-YFdyDkzxjKk03xq9FtbzI

[Westbrook]

@TarunAdobe do you think your recent updates here complete the requests outlined herein, or is there further work to be done before this issue can be closed?

[najikahalsema]

completed via #3971