Editorial review: Document popover="hint" #37990
Conversation
chrisdavidmills
requested review from
estelle and
wbamberg
and removed request for
a team
github-actions
bot
added
Content:HTML
chrisdavidmills
changed the title
Preview URLs (14 pages)
Flaws (77)Note! 5 documents with no flaws that don't need to be listed. 🎉 URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
External URLs (1)URL:
(comment last updated: 2025-02-14 15:29:33) |
|
|
||
| - `"hint"` | ||
|
|
||
| - : [`hint`](/en-US/docs/Web/API/Popover_API/Using#using_hint_popover_state) popovers are similar to `auto` popovers, but with a significant difference. They can be light-dismissed, but they do not light-dismiss `auto` popovers when shown, only `hint` popovers. `hint` popovers tend to be shown and hidden in response to non-click JavaScript events such as [`mouseover`](/en-US/docs/Web/API/Element/mouseover_event)/[`mouseout`](/en-US/docs/Web/API/Element/mouseout_event) and [`focus`](/en-US/docs/Web/API/Element/focus_event)/[`blur`](/en-US/docs/Web/API/Element/blur_event). When clicking on a button, the click itself would cause an open `auto` popover to light-dismiss. |
There was a problem hiding this comment.
I'm glad you added the bit about the click causing a light dismiss.
There was a problem hiding this comment.
-
The spec says:
Closes other hint popovers when opened, but not other auto popovers; has light dismiss and responds to close requests."
We should mention that they respond to close events.
-
You're mixing the terminology here. Light dismiss means "close by clicking outside of popover or Esc key". This implies that light dismiss also causes "popover closing another popover".
-
Not sure the comparison to auto is useful
-
Heres here's a go at this (note slight reword on the "click", because I didn't get it.)
| - : [`hint`](/en-US/docs/Web/API/Popover_API/Using#using_hint_popover_state) popovers are similar to `auto` popovers, but with a significant difference. They can be light-dismissed, but they do not light-dismiss `auto` popovers when shown, only `hint` popovers. `hint` popovers tend to be shown and hidden in response to non-click JavaScript events such as [`mouseover`](/en-US/docs/Web/API/Element/mouseover_event)/[`mouseout`](/en-US/docs/Web/API/Element/mouseout_event) and [`focus`](/en-US/docs/Web/API/Element/focus_event)/[`blur`](/en-US/docs/Web/API/Element/blur_event). When clicking on a button, the click itself would cause an open `auto` popover to light-dismiss. | |
| - : [`hint`](/en-US/docs/Web/API/Popover_API/Using#using_hint_popover_state) popovers do not close `auto` popovers when they are displayed, but will close other hint popovers. | |
| They can be light dismissed and will respond to close requests. | |
| Usually they are shown and hidden in response to non-click JavaScript events such as [`mouseover`](/en-US/docs/Web/API/Element/mouseover_event)/[`mouseout`](/en-US/docs/Web/API/Element/mouseout_event) and [`focus`](/en-US/docs/Web/API/Element/focus_event)/[`blur`](/en-US/docs/Web/API/Element/blur_event). | |
| With this kind of implementation a click outside the button would cause an open `auto` popover to light-dismiss" |
There was a problem hiding this comment.
Sure, this sounds pretty good
There was a problem hiding this comment.
Update — I've tweaked this wording a bit; in particular, the last sentence wasn't quite right, so I've updated it to
Clicking a button to open a
hintpopover would cause an openautopopover to light-dismiss.
I've also updated this wording in the other places it is used (Popover API "using" guide, HTML popover global attribute).
chrisdavidmills
changed the title
|
|
||
| - : In [auto state](/en-US/docs/Web/API/Popover_API/Using#auto_state_and_light_dismiss): | ||
| - Popovers can be "light dismissed" — this means that you can hide the popover by clicking outside it or pressing the <kbd>Esc</kbd> key. | ||
| - Usually, only one popover can be shown at a time — showing a second popover when one is already shown will hide the first one. The exception to this rule is when you have nested auto popovers. See [Nested popovers](/en-US/docs/Web/API/Popover_API/Using#nested_popovers) for more details. |
There was a problem hiding this comment.
YOu mean "only one auto popover" - since manual popovers can be displayed in multiples. Right?
| - Usually, only one popover can be shown at a time — showing a second popover when one is already shown will hide the first one. The exception to this rule is when you have nested auto popovers. See [Nested popovers](/en-US/docs/Web/API/Popover_API/Using#nested_popovers) for more details. | |
| - Usually, only one `auto` popover can be shown at a time — showing a second popover when one is already shown will hide the first one. The exception to this rule is when you have nested auto popovers. See [Nested popovers](/en-US/docs/Web/API/Popover_API/Using#nested_popovers) for more details. |
There was a problem hiding this comment.
Yup, good catch.
There was a problem hiding this comment.
I found another instance of this, and fixed it.
| This makes it very convenient to position popovers relative to their controls using [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning). Explicit associations do not need to be made using the {{cssxref("anchor-name")}} and {{cssxref("position-anchor")}} properties. | ||
|
|
||
| For an example that uses this implicit association, see the [Using "hint" popover state](/en-US/docs/Web/API/Popover_API/Using#using_hint_popover_state) section above. |
There was a problem hiding this comment.
Just to be clear, you're saying that the implicit positioning is already in place, so you don't need to worry about it - a hint will appear in the right place above its associated element?
The first sentence doesn't quite say that "This makes it very convenient" - i.e. it sounds like something you have to do, and that you ware about to describe.
The second sentence says "for an example that uses this implicit association see ... you might say "You can see this implicit associate at work in the exmaple XXX: no special CSS had to be created to position the hints near their associated elements.
There was a problem hiding this comment.
Only the association is implicit, not the positioning. The implicit association means you don't need to create an explicit anchor reference, for example using the anchor-name and position-anchor properties.
You still need to do the anchor positioning explicitly, for example, using the anchor() function as values of inset properties, or the position-area property.
I've not made much of a change here, except that I've added a link to the relevant section of the main anchor positioning guide that explains this association, and how the actual positioning is a separate step.
I've also added this link to the other pages that mention the implicit association, as I thought it would be helpful to clear up confusion.
Let me know if you think this needs anything else.
|
|
||
| - `"manual"` | ||
|
|
||
| - : In [manual state](/en-US/docs/Web/API/Popover_API/Using#using_manual_popover_state): |
There was a problem hiding this comment.
FWIW "manual state" etc feels a bit odd. Easier to refer to a manual, auto or hint popover than to refer to a popover having a particular state - given that we don't change the state other than to set it.
There was a problem hiding this comment.
Yeah, I agree with this. On this page especially, it's a value, not a state. I'm not yet convinced that I need to change this terminology everywhere, but on this page, I've updated the auto and manual definitions so they follow the same structure and style as the hint definition.
| - Popovers cannot be "light dismissed", although declarative show/hide/toggle buttons will still work. | ||
| - Multiple independent popovers can be shown at a time. |
There was a problem hiding this comment.
I think the key here is that the display / close is entirely manual. Perhaps reverse these and spell it out. YOu might want to play with the words though.
| - Popovers cannot be "light dismissed", although declarative show/hide/toggle buttons will still work. | |
| - Multiple independent popovers can be shown at a time. | |
| - Multiple independent popovers can be shown at a time. | |
| - Popovers must explicitly be displayed and closed using declarative show/hide/toggle buttons or JavaScript | |
| - Popovers cannot be "light dismissed" (and are not automatically closed). | |
There was a problem hiding this comment.
I think the wording you've provided for the explicit display/close is good, so I've used that. I've not used quite the same structure as you did, to make sure it follows the same structure as the other definitions.
| @@ -12,6 +12,8 @@ The **`popoverTargetElement`** property of the {{domxref("HTMLButtonElement")}} | |||
|
|
|||
| It is the JavaScript equivalent of the [`popovertarget`](/en-US/docs/Web/HTML/Element/button#popovertarget) HTML attribute. | |||
|
|
|||
| Associating a popover with a control using the `popoverTargetElement` property creates an implicit anchor reference between the two. This makes it very convenient to position popovers relative to their controls using [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning). Explicit associations do not need to be made using the {{cssxref("anchor-name")}} and {{cssxref("position-anchor")}} properties. | |||
There was a problem hiding this comment.
This wording of "convenient" sounds like something you "do", but actually it is something you benefit from.
| Associating a popover with a control using the `popoverTargetElement` property creates an implicit anchor reference between the two. This makes it very convenient to position popovers relative to their controls using [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning). Explicit associations do not need to be made using the {{cssxref("anchor-name")}} and {{cssxref("position-anchor")}} properties. | |
| Associating a popover with a control using the `popoverTargetElement` property also automatically positions popovers relative to their controls. | |
| The association creates an implicit [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning) anchor reference between the two elements (there is no need to create an explicit association using the {{cssxref("anchor-name")}} and {{cssxref("position-anchor")}} properties). |
BUT, you might want to say how you can override this default layout?
There was a problem hiding this comment.
This suggestion is not right, for the reasons discussed in the earlier comment on the same subject.
To be clear, there is no default positioning between a positioned element and its anchor. You have to specify that yourself. There is an explicit positioning of a popover element, but the "using" guide explains how to override that if you want to.
No change here. Let me know if you still think it needs something, given the above explanation.
| - `source` {{optional_inline}} | ||
| - : An {{domxref("HTMLElement")}} reference; programmatically defines the invoker of the popover associated with the toggle action, that is, the control button or link associated with the popover. | ||
|
|
||
| Associating a popover with a control using the `source` option creates an implicit anchor reference between the two. This makes it very convenient to position popovers relative to their controls using [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning). Explicit associations do not need to be made using the {{cssxref("anchor-name")}} and {{cssxref("position-anchor")}} properties. |
There was a problem hiding this comment.
| - `source` {{optional_inline}} | ||
| - : An {{domxref("HTMLElement")}} reference; programmatically defines the invoker of the popover associated with the toggle action, that is, the control button or link associated with the popover. | ||
|
|
||
| Associating a popover with a control using the `source` option creates an implicit anchor reference between the two. This makes it very convenient to position popovers relative to their controls using [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning). Explicit associations do not need to be made using the {{cssxref("anchor-name")}} and {{cssxref("position-anchor")}} properties. |
There was a problem hiding this comment.
| @@ -12,6 +12,8 @@ The **`popoverTargetElement`** property of the {{domxref("HTMLInputElement")}} i | |||
|
|
|||
| It is the JavaScript equivalent of the [`popovertarget`](/en-US/docs/Web/HTML/Element/button#popovertarget) HTML attribute. | |||
|
|
|||
| Associating a popover with a control using the `popoverTargetElement` property creates an implicit anchor reference between the two. This makes it very convenient to position popovers relative to their controls using [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning). Explicit associations do not need to be made using the {{cssxref("anchor-name")}} and {{cssxref("position-anchor")}} properties. | |||
There was a problem hiding this comment.
| There is a third type of popover you can create — **hint popovers**, designated by setting `popover="hint"` on your popover element. `hint` popovers are similar to `auto` popovers, but with a significant difference. They can be light-dismissed, but they do not light-dismiss `auto` popovers when shown, only `hint` popovers. | ||
|
|
||
| This is useful for situations where, for example, you have toolbar buttons that can be pressed to show UI popovers, but you also want to reveal tooltips when the buttons are hovered, without dismissing the UI popovers. |
There was a problem hiding this comment.
A few thoughts
- The example cannot demonstrate that hint popovers can be light dismissed. The example seems to indicate that additionally when an auto popover is light dismissed popovers the hint is not.
- Can these be used with manual popovers - should they be? Nowhere in the doc do we say.
- I don't love this sentence, partially because of the use of light-dismiss when you mean close. Same comments/reasons as https://github.com/mdn/content/pull/37990/files#r1955356883
There is a third type of popover you can create — hint popovers, designated by setting
popover="hint"on your popover element.
These can be displayed overautopopovers without causing them to close, and enable use cases such as tooltips over nested menus. Note thathintpopovers will close other hint popovers when they are displayed, and can be light-dismissed.
There was a problem hiding this comment.
PS Very much like the rest of this example.
There was a problem hiding this comment.
The example cannot demonstrate that hint popovers can be light dismissed. The example seems to indicate that additionally when an auto popover is light dismissed popovers the hint is not.
I'm not really sure what to make of this comment. You can quite easily check that a hint popover can be light dismissed by hovering over a button and then pressing Esc. When you light dismiss, whatever popover is focussed at the time is the one that is dismissed. I'm not sure this needs any kind of change.
Can these be used with manual popovers - should they be? Nowhere in the doc do we say.
Yes, they can, but there is not much point. I've added a note to address this.
I don't love this sentence, partially because of the use of light-dismiss when you mean close.
OK; I've swapped "dismissed" for "closed" in that sentence.
| @@ -557,6 +557,8 @@ A few additional non-standard attributes are listed following the descriptions o | |||
|
|
|||
| - : Turns an `<input type="button">` element into a popover control button; takes the ID of the popover element to control as its value. See the {{domxref("Popover API", "Popover API", "", "nocode")}} landing page for more details. | |||
|
|
|||
| Associating a popover with a control using the `popovertarget` attribute creates an implicit anchor reference between the two. This makes it very convenient to position popovers relative to their controls using [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning). Explicit associations do not need to be made using the {{cssxref("anchor-name")}} and {{cssxref("position-anchor")}} properties. | |||
There was a problem hiding this comment.
| The `popover` attribute can take one of the following values: | ||
|
|
||
| - `auto` | ||
| - `hint` | ||
| - `manual` |
There was a problem hiding this comment.
FWIW I presume this is a standard way of documenting global properties - I much prefer the Web API way where you would actually document each of these values here. Jumping forward into the description is rubbish.
There was a problem hiding this comment.
Yeah, this is a bit crap. I've taken the definitions from the HTMLElement.popover property and repeated them here, although I've cut down the wording a bit so that it isn't too repetitious with the description section.
|
@chrisdavidmills Very nice. Most of the comments are duplicates
|
Co-authored-by: Hamish Willee <[email protected]>
Co-authored-by: Hamish Willee <[email protected]>
Co-authored-by: Hamish Willee <[email protected]>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Description
Chrome 133 supports the
popoverattributehintvalue, which creates popovers that do not light-dismissautopopovers when shown. This is useful for situations where, for example, you have toolbar buttons that can be pressed to show UI popovers, but you also want to reveal tooltips when the buttons are hovered, without dismissing the UI popovers.This PR adds the HTML
popoverattributehintvalue to thepopoverHTML global attribute page and theHTMLElement.popoverDOM API equivalent.It also adds a section explaining how to use
popover="hint"to the Popover API "Using..." guide.As a bonus, I've also added info about the implicit anchor references that are created between popovers (makes CSS anchor positioning easier to use with popovers).
See https://chromestatus.com/feature/5073251081912320 for the data source.
There is no reason why this can't be tech-reviewed now, but we can't merge it until the dom-examples example is reviewed and merged. I am therefore keeping this as a draft for now.
Motivation
Additional details
Related issues and pull requests
popover="hint"attribute value browser-compat-data#25864Fixes mdn/mdn#598