Skip to content
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.

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

Add CloseWatcher reference pages #33910

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Add CloseWatcher reference pages #33910

wants to merge 4 commits into from

Conversation

Elchi3
Copy link
Member

@Elchi3 Elchi3 commented Jun 4, 2024

Description

Adds references pages for CloseWatcher.

I reckon that my work here is quite minimal. Would be cool to write a bit more about this either in this PR or as a follow-up.

Motivation

This API is new and ships in Chromium based browsers in M126.
Fixes #34184

Additional details

Link to spec: https://html.spec.whatwg.org/multipage/interaction.html#the-closewatcher-interface

Related issues and pull requests

BCD: mdn/browser-compat-data#23207

@Elchi3 Elchi3 requested a review from a team as a code owner June 4, 2024 12:20
@Elchi3 Elchi3 requested review from sideshowbarker and removed request for a team June 4, 2024 12:20
@github-actions github-actions bot added Content:WebAPI Web API docs size/m [PR only] 51-500 LoC changed labels Jun 4, 2024
files/en-us/web/api/closewatcher/cancel_event/index.md Outdated Show resolved Hide resolved
files/en-us/web/api/closewatcher/close/index.md Outdated Show resolved Hide resolved
files/en-us/web/api/closewatcher/close_event/index.md Outdated Show resolved Hide resolved
files/en-us/web/api/closewatcher/index.md Outdated Show resolved Hide resolved
files/en-us/web/api/closewatcher/index.md Show resolved Hide resolved
files/en-us/web/api/closewatcher/index.md Outdated Show resolved Hide resolved
files/en-us/web/api/closewatcher/requestclose/index.md Outdated Show resolved Hide resolved
Elchi3 and others added 2 commits June 4, 2024 14:23
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
@wbamberg wbamberg requested review from wbamberg and removed request for sideshowbarker June 5, 2024 15:56

{{APIRef("HTML DOM")}} {{SeeCompatTable}}

The `CloseWatcher` API listens and responds to close requests. A close request can be for anything that the user wants to close, like a [popover](/en-US/docs/Web/API/Popover_API), a sidebar, a [dialog](/en-US/docs/Web/HTML/Element/dialog), or any UI that has an open/close interaction.
Copy link
Collaborator

@wbamberg wbamberg Jun 7, 2024

Choose a reason for hiding this comment

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

The main thing I am missing here is an explanation of why I should use this API - what problem it is solving.

I didn't really find that here but I did find some stuff here and especially in the linked demo, and in the spec.

AIUI it goes something like:

  • web developers sometimes want to add UI components to their sites that have "close behavior" that is, the component appears and the user can close it when they are done with it. For example, sidebars, popups, dialogs.
  • users generally expect to be able to use a particular method to close these components - for example, Escape on devices with keyboards. But this is dependent on the platform: for example, on Android, users expect to use the back button.
  • for built-in UI components, like <dialog> and popups, the browser takes care of closing the component when the user performs the appropriate action. This also makes web apps more integrated into the device, closer to native apps.
  • but for UI components that the user has built themselves (like a sidebar) it is difficult for the developer to respond to these device-specific close methods. You can't just listen to Esc keypress events, because that won't work on Android.
  • so the close watcher abstracts the device-specific close methods, and deliver a close event to the app when the user executes the appropriate one for the platform, so the web app can have this kind of device-integrated UI pattern.

If this is right, we should say something like it.

Copy link
Collaborator

Choose a reason for hiding this comment

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

A close request can be for anything that the user wants to close, like a popover, a sidebar, a dialog

Also if I'm right I'm not sure whether we would use this for built-in components like dialog and popup. Don't they automatically close when the user executes the close method?

Copy link
Contributor

Choose a reason for hiding this comment

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

Yes dialog (specifically when showModal is used) and popover (specifically when popover="auto") have an internal close watcher, so you don't need to use this API for those elements. However, for anything else you make yourself you would use this API.

files/en-us/web/api/closewatcher/index.md Outdated Show resolved Hide resolved
files/en-us/web/api/closewatcher/index.md Outdated Show resolved Hide resolved
files/en-us/web/api/closewatcher/index.md Outdated Show resolved Hide resolved
files/en-us/web/api/closewatcher/index.md Outdated Show resolved Hide resolved
files/en-us/web/api/closewatcher/closewatcher/index.md Outdated Show resolved Hide resolved
files/en-us/web/api/closewatcher/destroy/index.md Outdated Show resolved Hide resolved
files/en-us/web/api/closewatcher/destroy/index.md Outdated Show resolved Hide resolved
files/en-us/web/api/closewatcher/destroy/index.md Outdated Show resolved Hide resolved
files/en-us/web/api/closewatcher/close/index.md Outdated Show resolved Hide resolved
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Content:WebAPI Web API docs size/m [PR only] 51-500 LoC changed
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Document CloseWatcher API
3 participants