diff --git a/tabbed-mode-explainer.md b/tabbed-mode-explainer.md index 7b54ea3..f74ab75 100644 --- a/tabbed-mode-explainer.md +++ b/tabbed-mode-explainer.md @@ -16,6 +16,8 @@ Add a new display override option `tabbed` which behaves similarly to `standalon "display_override": ["tabbed"] ``` +Per the design of `display_override`, sites cannot request the `tabbed` display mode in the `display` member. This is because it would be backwards-incompatible with user agents that do not support the tabbed display mode. By forcing it into the `display_override` member, the site can specify an explicit fallback chain, ending with the declared `display` mode. (This means sites can decide whether unsupported browsers should fall back to `standalone` or `browser`, depending on what is more important to the site: tabs, or a standalone window.) + Add a new manifest field `tab_strip` which allows apps to customize the tab strip. The `tab_strip` field will only be used when the display mode is `tabbed`. ``` @@ -29,11 +31,18 @@ Add a new manifest field `tab_strip` which allows apps to customize the tab stri }, ``` -The home tab is a pinned tab that, if enabled for an app, should be present in all app windows. Navigations outside of the home tab scope (as specified by `scope_patterns`) should open in a new tab instead of navigating the home tab. If the `home_tab` field is unset, then the app will not have a home tab. +The home tab is a pinned tab that, if enabled for an app, should be present in all app windows. If the `home_tab` field is unset, then the app will not have a home tab. + +The `home_tab.scope_patterns` field allows the app to set a list of [URLPatterns](https://wicg.github.io/urlpattern/#urlpattern) to define the scope of the home tab. This "home tab scope" carves the URL space of the application scope into two parts: "within home tab scope" and "outside of home tab scope". The home tab scope affects navigation in two important ways: + +1. From within the home tab, a navigation to a URL outside of the home tab scope will open a new tab and perform the navigation there. +2. From outside the home tab, a navigation to a URL within the home tab scope will focus the home tab and perform the navigation there. + +This "capturing" behaviour behaves a bit like `target=_blank` navigations, but applies to all navigations including regular `target=_self` links. Therefore, it explicitly breaks the normal HTML navigation flow, and is therefore something developers need to explicitly opt in to and be aware of. (As an example, a page may navigate itself to another URL, expecting its state to be destroyed, but due to the above home tab logic, the page may in fact stay open indefinitely.) -The `home_tab.scope_patterns` field allows the app to set a list of [URLPatterns](https://wicg.github.io/urlpattern/#urlpattern) to define the scope of the home tab. Navigation within the home tab going outside of this scope will be opened in a new tab, and navigation to a URL within the home tab scope will happen in the home tab. The [`URLPattern.baseURL`](https://wicg.github.io/urlpattern/#dom-urlpatterninit-baseurl) will be initialized to the parsed app scope, and apps will only be able to specify the pathname component of URLPattern. If the `scope_patterns` field is unset, then the home tab scope will only include the `start_url`. +The `scope_patterns` member will be resolved against the manifest URL, and patterns must be within the app scope. If there is a home tab, the app's `start_url` will automatically be included in the home tab scope (this is necessary to ensure when a window is created there is a URL to navigate the home tab to). If `home_tab` is present but `scope_patterns` is absent, then there will be a home tab, but it will only include the `start_url`. -The new tab button, should open a new tab at a URL that is within the scope of the app. The app may choose to set a custom URL to be opened. If this URL is not specified or is out of scope, it will default to the `start_url`. If the `new_tab_button` field is unset, it will default to an object with its subfields default values set. If the new tab URL is within the scope of the home tab, the new tab button will be hidden. +The new tab button should open a new tab at a URL that is within the scope of the app, but outside of the home tab scope. The app may choose to set a custom URL to be opened. If the new tab URL is within the scope of the home tab, the new tab button will be hidden. If this URL is not specified or is out of scope, it will default to the `start_url` (which means the button will, by definition, be hidden if there is a home tab). If the `tab_strip` field is unset, it will default to the following object: ``` @@ -82,9 +91,9 @@ The `new_tab_button` could have an `icons` field to customize the icon shown on Some apps may want to use a combination of display modes together. An example of this is using [window controls overlay](https://wicg.github.io/window-controls-overlay/) with tabbed mode. -These could be supported by adding more display override values, e.g., `window-controls-overlay-tabbed`, but this doesn’t scale well if many more display modes are added in the future. +There is a temptation to design a maximally flexible system where sites can request any combination of display mode (e.g. `"window-controls-overlay, tabbed"`). However, this would require every browser to explicitly design, support and test all permutations of all display modes, making the addition of each additional display mode prohibitively expensive. -Another solution is to allow apps to create custom display modes. See the [Display Mode Override Proposal](https://github.com/WICG/display-override/blob/main/explainer.md#custom-display-mode-names-with-display-modifiers-style-specification) for more detail. +Instead, it was decided that *if* certain combinations of display modes were wanted in the future, we would explicitly design and implement those combinations; e.g., we could add a `window-controls-overlay-tabbed` display mode if there was enough support for it. This is less flexible, but scales in a controllable way. This is discussed in detail in the [Display Mode Override Proposal](https://github.com/WICG/display-override/blob/main/explainer.md#custom-display-mode-names-with-display-modifiers-style-specification). ## Interaction with Launch Handler API