diff --git a/proposals/sidepanel-close-api.md b/proposals/sidepanel-close-api.md new file mode 100644 index 00000000..f1a1cd27 --- /dev/null +++ b/proposals/sidepanel-close-api.md @@ -0,0 +1,142 @@ +# New close() Method for the sidePanel API + +**Summary** + +Proposal to introduce a programmatic close method for the side panel API. + +**Document Metadata** + +**Author:** [hharshas](https://github.com/hharshas) + +**Sponsoring Browser:** Chromium + +**Contributors:** [hharshas](https://github.com/hharshas) ([Summer Of +Code](https://summerofcode.withgoogle.com/)), mentor: oliverdunk, solomonkinard + +**Created:** 2025-05-27 + +**Related Issues:** [#521](https://github.com/w3c/webextensions/issues/521), +[#chromium](https://issues.chromium.org/issues/403765214) + +## Motivation + +### Objective + +What does this API enable? +- `sidePanel.close()` method will allow the sidebar to close programmatically. + +Why do we need it? +- Currently, extensions cannot directly close their own side panel from the + background script, developers have to: + 1. Send a message from a background script to the side panel. + 2. Call `window.close()` from the side panel window on message delivery. + +This event aims to give developers an easier control. + +#### Use Cases + +Programmatic Control: +- An extension could automatically close the panel after completing an action or + when certain conditions are met. For example, an extension that helps users fill + out a form could close the side panel automatically once the form is submitted. + This ensures the side panel only stays open while it’s needed, + streamlining the user experience. + +### Known Consumers + +[The Chromium bug](https://issues.chromium.org/issues/403765214) has a significant +amount of developer interest and the discussions on the issue shows the same. + +## Specification + +### Schema + +```typescript +namespace sidePanel { + dictionary CloseOptions { + // The window in which to close the side panel. + long? windowId; + + // The tab for which to close the side panel. If specified, + // only closes tab-specific side panels. + long? tabId; + + // At least one of these must be provided, otherwise rejects with an error. + }; + + interface Functions { + // Closes the extension's side panel. + // `options`: Specifies the context in which to close the side panel. + // `callback`: Called when the side panel has been closed. + static void close( + CloseOptions options, + optional VoidCallback callback); + }; +}; +``` + +### Return value + +- Type: Promise + +- Resolves when the panel has been closed. If the panel is + already closed, still resolves successfully. + +### Behavior + +- The operation will only close side panels that belong to the + calling extension. +- If the panel is already closed or does not exist in the given + context, the method does nothing. +- If neither `windowId` nor `tabId` is provided, rejects with an error. +- If `windowId` or `tabId` is invalid, rejects with an error. +- If both `windowId` and `tabId` are provided, the method will verify + that the tab belongs to the specified window. If not, it rejects with an error. +- If both `windowId` and `tabId` are provided: + 1. If a contextual side panel is visible on the specified `tabId`, it will be closed. + 2. If a global side panel is visible on the given `tabId`, + it will be closed for all tabs in that window, not just the specified tab. + +### New Permissions + +N/A + +### Manifest File Changes + +N/A + +## Security and Privacy + +### Exposed Sensitive Data + +This API does not expose any sensitive data. + +### Abuse Mitigations + +The API is limited to closing only the extension's own side panel. + +### Additional Security Considerations + +N/A + +## Alternatives + +### Existing Workarounds + +* Message passing between background and panel contexts. +* Calling `window.close()` from the panel context. + +### Open Web API + +Not applicable to the open web as it only complements the existing `open()` +functionality. + +## Implementation Notes + +N/A + +## Future Work + +This implementation will align with +[#779](https://github.com/w3c/webextensions/pull/779), to ensure proper event +handling on panel closure (Open for discussion).