Add inline help to Custom HTML widget

[westonruter]

There is no inline help in the Custom HTML widget for how to interact with the code editor. While the widget will add this to the help text on the widgets admin screen, this is not easily discoverable. Additionally, this help tab text is not displayed in the Customizer at all. Just like the Additional CSS section description in the Customizer, there could be a (?) icon in the widget, and once expanded it could reveal the same help text to guide usage of the widget. I suggest the icon could be placed in the top-right corner of the widget with the help text then appearing at the top when expanded, similar to the Customizer section description.

See also:

• #41872
• ​https://github.com/WordPress/better-code-editing/issues/36
• ​https://github.com/WordPress/better-code-editing/issues/64
• ​https://wordpress.slack.com/archives/C02RP4X03/p1503940071000037
• ​https://wordpress.slack.com/archives/C0381N237/p1505323129000204

Builds off of [41376] for #12423.

[westonruter]

As suggested by @afercia, this can be generalized so that when you construct WP_Widget there can be an optional help parameter for control_options which, when supplied, would automatically be inserted into the widget control. In that way it wouldn't be something ad hoc for the Custom HTML widget alone but could be re-used by other widgets. I am not aware of other widgets that need help text, however.

[afercia]

Custom widgets :)

[westonruter]

Bumping priority to high for visibility and alignment with 4.9 goals, and given proximity to beta 1 deadline.

[melchoyce]

Changing to a defect since it's needed for accessibility.

[melchoyce]

Tried out a couple different positioning options in Widget with help.png.

(Note: I tried out a footer option, but I assuming that won't be viable because you'd get stuck in the editor before making it down there. Let me know if this assumption is correct.)

[jameskockelbergh]

My opinion is that the help icon contained within the widget header is the best proposal.

Linking to the help under the widget title pushes the widget functionality to far down.

[boemedia]

Is there a convention for the help icon in other places in WordPress? If not, I guess I prefer the help icon in the widget header, as it makes it visible too when the widget is collapsed. If this option is implemented, maybe add this to 10ups SketchPress document for future reference?

[afercia]

The 5.1 release beta 1 is today and this ticket still needs a direction and patch. Punting to Future Release. Pinging the Widgets component maintainers: @westonruter @welcher

[karmatosed]

Just going through this as part of design triage. @melchoyce do you have a preference for direction here? I ask as you were working on this.

[melchoyce]

I'd love to see a patch writing up the header version, just to figure out if it'll work or feel janky (since the rest of the header open/closes the accordion).