Skip to content

Editorial review: Document popover="hint" #37990

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 14 commits into from
Feb 25, 2025
Merged

Editorial review: Document popover="hint" #37990

merged 14 commits into from
Feb 25, 2025

Conversation

chrisdavidmills
Copy link
Contributor

@chrisdavidmills chrisdavidmills commented Feb 6, 2025 •
edited
Loading

Description

Chrome 133 supports the popover attribute hint value, which creates popovers that do not light-dismiss auto popovers 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 popover attribute hint value to the popover HTML global attribute page and the HTMLElement.popover DOM 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

Fixes mdn/mdn#598
Fixes #38233

@chrisdavidmills chrisdavidmills requested review from a team as code owners February 6, 2025 16:59
@chrisdavidmills chrisdavidmills requested review from estelle and wbamberg and removed request for a team February 6, 2025 16:59
@chrisdavidmills chrisdavidmills marked this pull request as draft February 6, 2025 17:00
@github-actions github-actions bot added Content:HTML Hypertext Markup Language docs Content:WebAPI Web API docs labels Feb 6, 2025
@chrisdavidmills chrisdavidmills changed the title Document popover=hint Technical review: Document popover="hint" Feb 6, 2025
@github-actions github-actions bot added the size/m [PR only] 51-500 LoC changed label Feb 6, 2025
@github-actions GitHub Actions
Copy link
Contributor

github-actions bot commented Feb 6, 2025 •
edited
Loading

Preview URLs (17 pages)
Flaws (82)

Note! 8 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/API/Popover_API/Using
Title: Using the Popover API
Flaw count: 8

  • broken_links:
    • /en-US/docs/Glossary/top_layer is ill cased
    • /en-US/docs/Glossary/top_layer is ill cased
    • /en-US/docs/Glossary/inset_properties is ill cased
    • /en-US/docs/Glossary/top_layer is ill cased
  • macros:
    • Macro produces link /en-US/docs/Glossary/top_layer which is a redirect
    • Macro produces link /en-US/docs/Glossary/top_layer which is a redirect
    • Macro produces link /en-US/docs/Glossary/inset_properties which is a redirect
    • Macro produces link /en-US/docs/Glossary/top_layer which is a redirect

URL: /en-US/docs/Web/API/HTMLElement
Title: HTMLElement
Flaw count: 5

  • broken_links:
    • /en-US/docs/Glossary/top_layer is ill cased
    • /en-US/docs/Glossary/top_layer is ill cased
  • macros:
    • Macro produces link /en-US/docs/Glossary/top_layer which is a redirect
    • Macro produces link /en-US/docs/Glossary/top_layer which is a redirect
    • Can't resolve /en-US/docs/Web/API/HTMLElement/cancel_event

URL: /en-US/docs/Web/API/HTMLElement/showPopover
Title: HTMLElement: showPopover() method
Flaw count: 2

  • broken_links:
    • /en-US/docs/Glossary/top_layer is ill cased
  • macros:
    • Macro produces link /en-US/docs/Glossary/top_layer which is a redirect

URL: /en-US/docs/Web/HTML/Element/input
Title: <input>: The HTML Input element
Flaw count: 46

  • broken_links:
    • /en-US/docs/Glossary/user_agent is ill cased
    • /en-US/docs/Glossary/user_agent is ill cased
    • /en-US/docs/Glossary/user_agent is ill cased
    • /en-US/docs/Web/API/validityState/rangeOverflow is ill cased
    • /en-US/docs/Web/API/validityState/tooLong is ill cased
    • and 18 more flaws omitted
  • macros:
    • Macro produces link /en-US/docs/Glossary/user_agent which is a redirect
    • Macro produces link /en-US/docs/Glossary/user_agent which is a redirect
    • Macro produces link /en-US/docs/Glossary/user_agent which is a redirect
    • Macro produces link /en-US/docs/Web/API/validityState/rangeOverflow which is a redirect
    • Macro produces link /en-US/docs/Web/API/validityState/tooLong which is a redirect
    • and 18 more flaws omitted

URL: /en-US/docs/Web/HTML/Element/button
Title: <button>: The Button element
Flaw count: 4

  • broken_links:
    • /en-US/docs/Glossary/user_agent is ill cased
    • /en-US/docs/Glossary/accessible_name is ill cased
  • macros:
    • Macro produces link /en-US/docs/Glossary/user_agent which is a redirect
    • Macro produces link /en-US/docs/Glossary/accessible_name which is a redirect

URL: /en-US/docs/Web/HTML/Global_attributes/popover
Title: popover
Flaw count: 2

  • broken_links:
    • /en-US/docs/Glossary/top_layer is ill cased
  • macros:
    • Macro produces link /en-US/docs/Glossary/top_layer which is a redirect

URL: /en-US/docs/Web/CSS/anchor-name
Title: anchor-name
Flaw count: 7

  • broken_links:
    • /en-US/docs/Glossary/inset_properties is ill cased
    • /en-US/docs/Web/CSS/Value_definition_syntax#single_bar is a redirect
    • /en-US/docs/Web/CSS/Value_definition_syntax#hash_mark is a redirect
  • macros:
    • Macro produces link /en-US/docs/Glossary/inset_properties which is a redirect
    • Macro produces link /en-US/docs/Web/CSS/initial_value which is a redirect
    • Macro produces link /en-US/docs/Web/CSS/inheritance which is a redirect
    • Macro produces link /en-US/docs/Web/CSS/computed_value which is a redirect

URL: /en-US/docs/Web/CSS/CSS_anchor_positioning/Using
Title: Using CSS anchor positioning
Flaw count: 2

  • broken_links:
    • /en-US/docs/Glossary/inset_properties is ill cased
  • macros:
    • Macro produces link /en-US/docs/Glossary/inset_properties which is a redirect

URL: /en-US/docs/Web/CSS/position-anchor
Title: position-anchor
Flaw count: 6

  • broken_links:
    • /en-US/docs/Glossary/inset_properties is ill cased
    • /en-US/docs/Web/CSS/Value_definition_syntax#single_bar is a redirect
  • macros:
    • Macro produces link /en-US/docs/Glossary/inset_properties which is a redirect
    • Macro produces link /en-US/docs/Web/CSS/initial_value which is a redirect
    • Macro produces link /en-US/docs/Web/CSS/inheritance which is a redirect
    • Macro produces link /en-US/docs/Web/CSS/computed_value which is a redirect
External URLs (4)

URL: /en-US/docs/Web/API/Popover_API/Using
Title: Using the Popover API

URL: /en-US/docs/Web/API/HTMLElement/anchorElement
Title: HTMLElement: anchorElement property

URL: /en-US/docs/Web/HTML/Global_attributes/anchor
Title: anchor

(comment last updated: 2025-02-25 09:49:43)

mfreed7
mfreed7 reviewed Feb 11, 2025
View reviewed changes
Copy link

@mfreed7 mfreed7 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! Just a few small comments.

@github-actions github-actions bot added the Content:CSS Cascading Style Sheets docs label Feb 12, 2025
@chrisdavidmills chrisdavidmills marked this pull request as ready for review February 12, 2025 15:07
@chrisdavidmills chrisdavidmills requested a review from a team as a code owner February 12, 2025 15:07
@chrisdavidmills chrisdavidmills changed the title Technical review: Document popover="hint" Editorial review: Document popover="hint" Feb 12, 2025
@chrisdavidmills chrisdavidmills mentioned this pull request Feb 13, 2025
Merged
hamishwillee
hamishwillee reviewed Feb 13, 2025
View reviewed changes
hamishwillee
hamishwillee reviewed Feb 13, 2025
View reviewed changes
hamishwillee
hamishwillee reviewed Feb 13, 2025
View reviewed changes
hamishwillee
hamishwillee reviewed Feb 13, 2025
View reviewed changes
hamishwillee
hamishwillee reviewed Feb 14, 2025
View reviewed changes
hamishwillee
hamishwillee reviewed Feb 14, 2025
View reviewed changes
hamishwillee
hamishwillee reviewed Feb 14, 2025
View reviewed changes
lukewarlow
lukewarlow reviewed Feb 19, 2025
View reviewed changes
lukewarlow
lukewarlow reviewed Feb 19, 2025
View reviewed changes
lukewarlow
lukewarlow reviewed Feb 19, 2025
View reviewed changes
lukewarlow
lukewarlow reviewed Feb 19, 2025
View reviewed changes
lukewarlow
lukewarlow reviewed Feb 19, 2025
View reviewed changes
lukewarlow
lukewarlow reviewed Feb 19, 2025
View reviewed changes
Copy link
Contributor

@lukewarlow lukewarlow left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-authoritative LGTM

@lukewarlow lukewarlow mentioned this pull request Feb 19, 2025
Closed
hamishwillee
hamishwillee reviewed Feb 21, 2025
View reviewed changes
hamishwillee
hamishwillee reviewed Feb 21, 2025
View reviewed changes
@hamishwillee
Copy link
Collaborator

Close now. Last comment #37990 (comment)

hamishwillee
hamishwillee reviewed Feb 24, 2025
View reviewed changes
files/en-us/web/api/popover_api/using/index.md Outdated
## Styling popovers

The popover API has some related CSS features available that are worth looking at.
The Popover API has some related CSS techniques available that are worth looking at.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If these are part of the same spec, which I believe they are, this might be better as.

Suggested change
The Popover API has some related CSS techniques available that are worth looking at.
Popovers can be styled and positioned using CSS.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You are not wrong, but "Popovers can be styled and positioned using CSS." sounds a bit obvious — popovers are HTML elements, so of course they can be styled using CSS!

I thought about it a bit, and ended up going with:

This section covers some CSS selection and positioning techniques relevant to popovers.

hamishwillee
hamishwillee reviewed Feb 24, 2025
View reviewed changes
files/en-us/web/api/popover_api/using/index.md
}
```

You can select only popovers that are showing using the {{cssxref(":popover-open")}} pseudo-class:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps (i.e. I am not sure why "showing" doesn't work as well for me.)

Suggested change
You can select only popovers that are showing using the {{cssxref(":popover-open")}} pseudo-class:
You can select only popovers that are being displayed using the {{cssxref(":popover-open")}} pseudo-class:

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The thing about "showing" is that it is a specific semantic state for popovers, along with "hidden" for when they are not showing. These states differ from open/closed, for example.

I'd prefer to keep "showing", as it is the correct semantic spec language, and is consistent with how we talk about it across the rest of MDN.

hamishwillee
hamishwillee reviewed Feb 24, 2025
View reviewed changes
files/en-us/web/api/popover_api/using/index.md

### Styling the popover backdrop

The {{cssxref("::backdrop")}} pseudo-element is a full-screen element placed directly behind showing popover elements in the {{glossary("top layer")}}, allowing effects to be added to the page content behind the popover(s) if desired. You might for example want to blur out the content behind the popover to help focus the user's attention on it:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again, I don't like "showing" as an adjective. Consider

Suggested change
The {{cssxref("::backdrop")}} pseudo-element is a full-screen element placed directly behind showing popover elements in the {{glossary("top layer")}}, allowing effects to be added to the page content behind the popover(s) if desired. You might for example want to blur out the content behind the popover to help focus the user's attention on it:
The {{cssxref("::backdrop")}} pseudo-element is a full-screen element placed directly behind open popover elements in the {{glossary("top layer")}}, allowing effects to be added to the page content behind the popover(s) if desired. You might for example want to blur out the content behind the popover to help focus the user's attention on it:

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again, "showing" is the correct semantic term here. "Open" isn't correct.

hamishwillee
hamishwillee approved these changes Feb 24, 2025
View reviewed changes
Copy link
Collaborator

@hamishwillee hamishwillee left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@chrisdavidmills I have made a few very minor nit suggestions. But this is excellent. Approving so you can merge when you are ready.

@chrisdavidmills
Copy link
Contributor Author

@chrisdavidmills I have made a few very minor nit suggestions. But this is excellent. Approving so you can merge when you are ready.

Thanks @hamishwillee, for an awesome and thorough review!

@chrisdavidmills chrisdavidmills merged commit 7b35cff into mdn:main Feb 25, 2025
8 checks passed
@Josh-Cena Josh-Cena mentioned this pull request Feb 25, 2025
Closed
1 task
cssinate pushed a commit to cssinate/content that referenced this pull request Apr 11, 2025
@chrisdavidmills @hamishwillee
@github-actions @paul-grant-hs
Editorial review: Document popover="hint" (mdn#37990)
814bfe4 
* Document popover=hint

* Fixes for mfreed7 comments, added info about implicit anchor references

* Update files/en-us/web/api/htmlelement/popover/index.md

Co-authored-by: Hamish Willee <[email protected]>

* Update files/en-us/web/api/htmlelement/popover/index.md

Co-authored-by: Hamish Willee <[email protected]>

* Update files/en-us/web/html/global_attributes/popover/index.md

Co-authored-by: Hamish Willee <[email protected]>

* Update files/en-us/web/api/htmlelement/popover/index.md

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* Fixes for hamishwillee review comments

* Clean up in light of hamishwillee and lukewarlow review comments

* remove anchor attribute content from guide

* last few bits of cleanup

* Restructure popover anchor positioning information

* small wording adjustment

---------

Co-authored-by: Hamish Willee <[email protected]>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@keithamus keithamus keithamus left review comments

@mfreed7 mfreed7 mfreed7 left review comments

@lukewarlow lukewarlow lukewarlow left review comments

@github-actions github-actions[bot] github-actions[bot] left review comments

@hamishwillee hamishwillee hamishwillee approved these changes

@estelle estelle Awaiting requested review from estelle estelle is a code owner automatically assigned from mdn/yari-content-html

Assignees
No one assigned
Labels
Content:CSS Cascading Style Sheets docs Content:HTML Hypertext Markup Language docs Content:WebAPI Web API docs size/m [PR only] 51-500 LoC changed
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Anchor attribute is at risk, should it be prominently documented? Improvements to popover API and connection to anchor positioning
6 participants
@chrisdavidmills @hamishwillee @yisibl @mfreed7 @keithamus @lukewarlow