Repository navigation
Add a proposal for a unified Sidebar API - #1206
kiaraarose wants to merge 1 commit into
Conversation
This proposal takes the implementations of sidePanel (in Chrome and Safari) and sidebar_action (Firefox and Safari) to work towards a unified API that can be implemented across all browser vendors. Note: the Safari implementation is behind a feature flag in WebKit and has not shipped.
| A window has an *open state* for the extension. `open()`, `toggle()` and the | ||
| user opening the sidebar turn it on, and `close()`, `toggle()`, the user closing | ||
| the sidebar and closing the window turn it off. While it is on, the window shows | ||
| one sidebar pane for the extension, and the pane shows the panel that applies to | ||
| the window's **selected tab**: the tab's own panel if it has a tab-level panel, | ||
| otherwise the window panel, as long as the effective options are usable. | ||
|
|
||
| The pane stays open when the user switches tabs, and follows the selected tab. | ||
| When the user selects another tab, the pane shows the panel that applies to that | ||
| tab, and does not reload if that is the panel it was already showing. Whenever | ||
| no panel applies to the selected tab because the options are not usable, the | ||
| pane hides and the open state stays on, so the pane returns when a panel applies | ||
| again. A `close()`, or the user closing the sidebar in between, turns the open | ||
| state off, and the pane does not return. When the user opens the sidebar of an |
There was a problem hiding this comment.
The open state belongs to the window, which is simple, but it behaves oddly when an extension has both a tab-level panel and a window panel. If the user opens tab A's own panel and then selects tab C, the pane shows the window panel on C even though the user never opened it. Closing from any tab turns the state off for all of them. The Alternatives section notes that Chrome keeps the state per panel. Is the window-wide behavior intended for the mixed case, or should the state be tracked separately for tab-level panels and the window panel?
The state also stays on while the pane is hidden, so any later setOptions that makes a panel usable brings the pane back, however long ago the user opened it and without a gesture. Abuse Mitigations says only a gesture opens UI. I'd either limit the return, for example to selecting a tab, or say here why it is acceptable.
| `onClosed` fires when the window stops showing a panel for which `onOpened` | ||
| fired: | ||
|
|
||
| * the pane is closed; | ||
| * another panel replaces it, including the pane swapping to another panel of the | ||
| extension on a tab switch (the pane stays open, but the panel it showed is | ||
| closed); | ||
| * the pane hides because no panel applies to the selected tab; | ||
| * its tab or window closes. |
There was a problem hiding this comment.
Two gaps. The sidebar is a slot the browser shares between extensions, so the proposal should say whether another extension's panel, or the browser's own, replacing this one turns the open state off and fires onClosed. "Another panel replaces it" can be read either way.
The order on a tab switch between two panels also isn't stated. I'd have onClosed for the old panel fire before onOpened for the new one.
| * `setTitle` / `getTitle` set and read the title at the global, window, or tab | ||
| level. `title: null` removes the value at that level. |
There was a problem hiding this comment.
I'd fold the title into setOptions and getOptions, as the icon already is, so it can change together with path and enabled. That drops setTitle, getTitle and their details types, and the null and resolution rules stay the same. It also fits the direction we have been taking for other namespaces, where state is set through an options bag instead of one setter per property.
| * `setBehavior` / `getBehavior`: with `openPanelOnActionClick: true`, activating | ||
| the extension's action toggles the sidebar as `toggle()` does for the | ||
| `windowId` of the tab where the action was activated, instead of showing the | ||
| popup or dispatching the click event. The default is `false`. If the extension | ||
| has no `action` key, the setting applies to the browser's own button for the | ||
| extension, and is ignored in a browser that has none. The setting is persisted | ||
| across restarts, as it is in Chrome. |
There was a problem hiding this comment.
| atomically together with `path` and `enabled`; there is no separate `setIcon`. | ||
| `iconVariants` is as defined in this [proposal](dark_mode_extension_icons.md) | ||
| and in [PR 1134](https://github.com/w3c/webextensions/pull/1134). Unknown | ||
| properties in an icon group are ignored (issue 1119), and a relative path |
There was a problem hiding this comment.
issue 1119, issue 1122 and issue 1142 are plain text while the other issues are linked. The Failures paragraph is also long enough to split into two.
|
Thanks for writing this up! Two questions from reading the proposal against what 1. Does a bad argument throw or resolve?Scenario A typo:
The call matches both. With "resolves", the panel stays enabled and the developer sees no error. Sentence 2 also implies that an unknown member ( Suggestion For the method argument objects ( 2. Is the legacy namespace exposed when the manifest has both keys?Scenario For a migration, a manifest lists
Suggestion I suggest a general rule: "When the |
Summary
Adds a proposal for a unified
sidebarnamespace andsidebarmanifest key, unifyingchrome.sidePanelandbrowser.sidebarAction. Sponsoring browser: Safari.Related TPAC discussions
sidebarnamespace instead of an alias;close({ tabId })andopen({ tabId })fail for a tab without a tab-specific panel instead of falling back.sidebarmanifest key, no developer-facing permission,SIDEBARas the context type when the key is used, and icons through manifesticon_variantsandsetOptions().{}#254 (optional and required arguments), Inconsistency: Behavior ofaction.setIcon({})#1101 (empty objects), Inconsistency: insertion of default values into dictionaries, null vs undefined vs false #1124 (nullandundefined), Makeaction.setIcon({path: "invalid.png"})reject and have no side-effect #1115, Ignoreicon_variantswith unknown properties #1119 and Inconsistency:action.setIcon({path: "relative.png"})relative path handling #1122 (icon paths and groups).Related issues
sidebarAPI for mv3 #128 (unified sidebar API)sidePanelAPI: support "one instance per tab" inopenPanelOnActionClick#515sidePanelAPI: lifecycle events #517sidePanelAPI:sidePanel.close()andsidePanel.toggle()#521