Adding display_override to incubations spec (#5)

Adding display_override, which uses the extension point in the display mode algorithm to support an advanced use case. Co-authored-by: Thomas Steiner <tomac@google.com>
WICG · Feb 18, 2021 · decad93 · decad93
1 parent 9c164ae
commit decad93
Show file tree

Hide file tree

Showing 3 changed files with 123 additions and 11 deletions.
diff --git a/.pr-preview.json b/.pr-preview.json
@@ -0,0 +1,4 @@
+{
+    "src_file": "index.html",
+    "type": "respec"
+}
diff --git a/index.html b/index.html
@@ -1,38 +1,140 @@
-<!doctype html>
+<!DOCTYPE html>
 <html lang="en">
   <head>
     <meta charset="utf-8">
-    <title>Spec proposal</title>
-    <script src="https://www.w3.org/Tools/respec/respec-w3c" class="remove"></script>
+    <title>
+      Spec proposal
+    </title>
+    <script src="https://www.w3.org/Tools/respec/respec-w3c" class=
+    "remove"></script>
     <script class='remove'>
       // See https://github.com/w3c/respec/wiki/ for how to configure ReSpec
       var respecConfig = {
         specStatus: "CG-DRAFT",
-        shortName: "beforeinstallprompt",
         editors: [{
-          name: "Marcos Cáceres"
-        }]
+          name: "Daniel Murphy"
+        }],
+        github: "WICG/manifest-incubations",
+        shortName: "manifest-incubations",
+        xref: {
+          specs: ["appmanifest"],
+          profile: "web-platform",
+        },
       };
     </script>
   </head>
   <body>
     <section id="abstract">
       <p>
-        This specification does neat stuff.
+        Feature specifications for manifest extensions & incubations which
+        Chromium has shipped but do not have committments / implementations
+        from other user agents. Instead of keeping these features as
+        explainers, they are documented more officially here.
       </p>
     </section>
     <section id="sotd">
       <p>
         This is an unofficial proposal.
       </p>
     </section>
-
     <section id="introduction">
-      <h2>Introduction</h2>
+      <h2>
+        Introduction
+      </h2>
       <p>
-        See <a href="https://github.com/w3c/respec/wiki/User's-Guide">ReSpec's user guide</a>
-        for how toget started!
+        See <a href="https://github.com/w3c/respec/wiki/User's-Guide">ReSpec's
+        user guide</a> for how toget started!
       </p>
     </section>
+    <section class="informative">
+      <h2>
+        Incubation Usage Examples
+      </h2>
+      <p>
+        The following shows a [=manifest=] that prefers the
+        <code>minimal-ui</code> <a data-cite=
+        "appmanifest#dfn-display-mode">display mode</a> over
+        <code>standalone</code>, but if <code>minimal-ui</code> isn't supported, falls back
+        to <code>standalone</code> as opposed to <code>browser</code>.
+      </p>
+      <pre class="example json" title="Advanced display usage manifest">
+        {
+          "name": "Recipe Zone",
+          "description": "All of the recipes!",
+          "icons": [{
+            "src": "icon/hd_hi",
+            "sizes": "128x128"
+          }],
+          "start_url": "/index.html",
+          "display_override": ["minimal-ui"],
+          "display": "standalone",
+          "theme_color": "yellow",
+          "background_color": "red"
+        }
+      </pre>
+    </section>
+    <section>
+      <h2 data-dft-for="">
+        Display_override extension
+      </h2>
+      <p>
+        For advanced usages, the display_override member can be used to specify
+        a custom fallback order of {DisplayModeType}}s for developers to choose
+        their prefered <a data-cite="appmanifest#dfn-display-mode">display
+        mode</a> .
+      </p>
+      <p>
+        The following steps are added to the <a data-cite=
+        "appmanifest#dfn-extension-point">extension point</a> in <a data-cite=
+        "appmanifest#dfn-steps-for-determing-the-web-app-s-chosen-display-mode">
+        determining the web app's chosen display mode</a>:
+      </p>
+      <ol>
+        <li>[=list/For each=] |candidate_display_mode:DisplayModeType| of
+        |manifest|.{{WebAppManifest/display_override}}:
+          <ol>
+            <li>If the user agent supports the |candidate_display_mode|, then
+            return |candidate_display_mode|.
+            </li>
+          </ol>
+        </li>
+      </ol>
+    </section>
+    <section data-dfn-for="WebAppManifestIncubations" data-link-for=
+    "WebAppManifestIncubations">
+      <h2>
+        <dfn data-dfn-for="">WebAppManifestIncubations</dfn> dictionary
+      </h2>
+      <pre class="idl">
+          partial dictionary WebAppManifest {
+            sequence&lt;DisplayModeType&gt; display_override;
+          };
+      </pre>
+      <p>
+        This is an extension of {{WebAppManifest}}.
+      </p>
+      <section>
+        <h3>
+          <code>display_override</code> member
+        </h3>
+        <p>
+          The <dfn>display_override</dfn> member is a <a>sequence</a> of {{
+          DisplayModeType}}. This item represents the developer's preferred
+          fallback chain for <a data-cite=
+          "appmanifest#dfn-display-mode">display modes</a>. This field
+          overrides the {{WebAppManifest/display}} property. If the user agent
+          does not support any of the display modes specified here, then it
+          falls back to considering the {{WebAppManifest/display}} field. See
+          <a data-cite="appmanifest#dfn-display-mode">display modes</a> for the
+          algorithm steps.
+        </p>
+        <p class="note">
+          This member is intended to be only used for advanced cases, where the
+          developer wants explicit control over the fallback order of their
+          display modes. Otherwise, the {{WebAppManifest/display}} should be
+          sufficient for most use cases.
+        </p>
+      </section>
+    </section>
   </body>
 </html>
diff --git a/tidyconfig.txt b/tidyconfig.txt
@@ -0,0 +1,6 @@
+char-encoding: utf8
+indent: yes
+indent-spaces: 2
+wrap: 80
+tidy-mark: no
+custom-tags: yes