From 37cdf6370917ec5447caa4fff2c3d9c632e50c75 Mon Sep 17 00:00:00 2001 From: Aaron Gustafson Date: Mon, 13 Jun 2022 15:25:50 -0700 Subject: [PATCH 1/9] Initial pass: Manifest Override --- index.html | 133 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 133 insertions(+) diff --git a/index.html b/index.html index ae2ad06..29cf775 100644 --- a/index.html +++ b/index.html @@ -495,6 +495,139 @@

+
+

+ Manifest override objects +

+

+ Each manifest override object is a generic object value + that allows for certain manifest properties to be overridden within + a particular context. +

+

The structure of a [=manifest override object=] is as follows:

+ 
+        {
+          "context_key": {
+            "property": "new value"
+          }
+        }
+
+

+ Each manifest property that accepts a [=manifest override object=] + as its value will define the contexts it supports and which + properties it supports overriding. User agents MUST ignore any contexts + that are not supported by the property as well as any override + properties not explicitly allowed within it. +

+

+ When the manifest property’s context is applicable, the value of each + allowable override will be used in place of the original value defined + in the Manifest. +

+

+ Redefined array items will be overridden in the order they are authored. + When redefining objects (e.g., [=manifest/shortcuts=], [=manifest/icons=]), + authors will only be able to redefine specific properties of that object. + In order to ensure all overrides are applied correctly, the order must + match the original array (i.e., each [=manifest/shortcut=] must be redefined + in order, as must their icons, if they also require re-definition). +

+ Redefined array items must also be equal in number to the array being + overridden. If there is a mismatch in the number of items in either array, + any excess items will be ignored. This is only an issue if the original + array has more items than the override array, because any excess items + within the original array will not be re-defined. +

+

+ When there is a conflict because two different properties are attempting + to override the same value in their respective active contexts, the one + defined last will win. By way of example, consider the following: +

+ 
+        {
+          "lang": "en-US",
+          "icons": [
+            {
+              "src": "icon.png",
+              "sizes": "128x128",
+              "type": "image/png"
+            }
+          ],
+          "translations": {
+            "es": {
+              "icons": [
+                {
+                  "src": "icon-es.png"
+                }
+              ]
+            }
+          },
+          "user_preferences": {
+            "color_scheme_dark": {
+              "icons": [
+                {
+                  "src": "icon-dark.png"
+                }
+              ]
+            }
+          }
+        }
+
+

+ In this example, if the user’s primary language is Español, but + their preferred color scheme was set to "dark", the icon supploed + would be the dark version and not the localized one. For this reason, + it is imperative that properties taking a [=manifest override object=] + as their value consider whether any other properties that also enable + overrides should be able to be redefined within them. In the above + example, the author’s intent would likely have been better realized + if `user_preference` was put before `translations` and the localized + context block redefined the `user_preferences` value for that language: +

+ 
+        {
+          "lang": "en-US",
+          "icons": [
+            {
+              "src": "icon.png",
+              "sizes": "128x128",
+              "type": "image/png"
+            }
+          ],
+          "user_preferences": {
+            "color_scheme_dark": {
+              "icons": [
+                {
+                  "src": "icon-dark.png"
+                }
+              ]
+            }
+          },
+          "translations": {
+            "es": {
+              "icons": [
+                {
+                  "src": "icon-es.png"
+                }
+              ],
+              "user_preferences": {
+                "color_scheme_dark": {
+                  "icons": [
+                    {
+                      "src": "icon-es-dark.png"
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          
+        }
+
+

+ User agents MAY ignore any override properties they do not support. +

+

Installation prompts From 6b4b38969c601001593acae1fa85bde777a2e4b2 Mon Sep 17 00:00:00 2001 From: Aaron Gustafson Date: Mon, 13 Jun 2022 16:09:25 -0700 Subject: [PATCH 2/9] Update index.html Co-authored-by: Thomas Steiner --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index 29cf775..62fca9c 100644 --- a/index.html +++ b/index.html @@ -575,7 +575,7 @@

In this example, if the user’s primary language is Español, but - their preferred color scheme was set to "dark", the icon supploed + their preferred color scheme was set to "dark", the icon supplied would be the dark version and not the localized one. For this reason, it is imperative that properties taking a [=manifest override object=] as their value consider whether any other properties that also enable From facdebecab0c784a087b299ffd4e24e0f99612d6 Mon Sep 17 00:00:00 2001 From: Louise Brett <80441278+loubrett@users.noreply.github.com> Date: Tue, 14 Jun 2022 17:13:55 +1000 Subject: [PATCH 3/9] Add user_preferences member --- index.html | 104 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 104 insertions(+) diff --git a/index.html b/index.html index 62fca9c..a23228e 100644 --- a/index.html +++ b/index.html @@ -495,6 +495,110 @@

+
+

+ user_preferences member +

+

+ The `user_preferences` member of the [=application manifest=] is an + object that can be used to override values of manfiest members depending + on which user preferences are set. It has the following members: +

+
    +
  • [=user_preferences/color_scheme=] +
    • +
+

+ The user agent SHOULD use the override values instead of the value of + the corresponding member defined at the top level on the manifest. +

+

+ To process the `user_preferences` member, given + [=ordered map=] |json:ordered_map|, [=ordered map=] |manifest:ordered map|, + run the following during the [=application manifest/processing + extension-point=] in [=processing a manifest=]: +

+
    +
  1. If |json|["user_preferences"] does not [=map/exist=], return. +
    2. +
  2. If the type of |json|["user_preferences"] is not [=ordered map=], + return. +
    3. +
  3. Set |manifest|["user_preferences"] to a new [=ordered map=]. +
    4. +
  4. [=Process the `color_scheme` member=] passing + |json|["user_preferences"] and |manifest|["user_preferences"]. +
    5. +
+
+

+ color_scheme + member +

+

+ The [=user_prefences=] `color_scheme` member is an object that + contains the overrides for color scheme preferences. It has the + following members: +

+

+ The dark member + specifies the manifest overrides to use when the user prefers a + dark theme. +

+

+ The light member + specifies the manifest overrides to use when the user prefers a + light theme. +

+

+ To process the `color_scheme` member, given [=ordered map=] + |json_user_preferences:ordered_map|, [=ordered map=] + |manifest_user_preferences:ordered map|, run the following: +

+
    +
  1. If |json_user_preferences|["color_scheme"] does not [=map/exist=], + return. +
    2. +
  2. If the type of |json_user_preferences|["color_scheme"] is not + [=ordered map=], return. +
    3. +
  3. Set |manifest_user_preferences|["color_scheme"] to a new + [=ordered map=]. +
    4. +
  4. [=list/For each=] |member:string| of [=list=] « "dark", "light" »: +
      +
    1. Let |overrides:ordered map| be the result of processing a + manifest override object. +
      2. +
    2. Set |manifest_user_preferences|["color_scheme"][member] to + |overrides|. +
      3. +
    +
    5. +
+
+
+

+ Overridable properties +

+

+ The proterties that user_preferences can override in the + [=manfiest override obeject=] are: +

+
    +
  • [=manifest/theme_color=] member. +
    • +
  • [=manifest/background_color=] member. +
    • +
  • [=Shortcut item's=] [=shortcut item/icons=] member. +
    • +
  • [=Icons=] [=icons/src=] member. +
    • +
  • [=Icons=] [=icons/type=] member. +
    • +
+
+

Manifest override objects From e94d18d0baef776ad49eb787b988f294909d507a Mon Sep 17 00:00:00 2001 From: Aaron Gustafson Date: Tue, 14 Jun 2022 11:25:53 -0700 Subject: [PATCH 4/9] Update index.html Co-authored-by: Louise Brett <80441278+loubrett@users.noreply.github.com> --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index a23228e..aee0c8a 100644 --- a/index.html +++ b/index.html @@ -685,7 +685,7 @@

as their value consider whether any other properties that also enable overrides should be able to be redefined within them. In the above example, the author’s intent would likely have been better realized - if `user_preference` was put before `translations` and the localized + if `user_preferences` was put before `translations` and the localized context block redefined the `user_preferences` value for that language: 


From 0e1237901ad9f0ce123b8049fe8252f39630c215 Mon Sep 17 00:00:00 2001
From: Louise Brett <80441278+loubrett@users.noreply.github.com>
Date: Wed, 15 Jun 2022 16:58:30 +1000
Subject: [PATCH 5/9] Update index.html

---
 index.html | 32 ++++++++++++++++++++++----------
 1 file changed, 22 insertions(+), 10 deletions(-)

diff --git a/index.html b/index.html
index aee0c8a..850eb41 100644
--- a/index.html
+++ b/index.html
@@ -508,9 +508,17 @@ 

         
  • [=user_preferences/color_scheme=]
         
    • 
       
+      
    
+        This list of members is expected to expand in the future to include
+        other user 
+        preference media features such as contrast and 
+        forced-colors,
+        as defined in [=CSS=].
+      
    
       
    
         The user agent SHOULD use the override values instead of the value of
-        the corresponding member defined at the top level on the manifest.
+        the corresponding member defined at the top level of the manifest.
       
    
       
    
         To process the `user_preferences` member, given
@@ -532,11 +540,11 @@ 
    
       
       
    
         
    
-          color_scheme
+          color_scheme
           member
         
    
         
    
-          The [=user_prefences=] `color_scheme` member is an object that 
+          The [=user_preferences=] `color_scheme` member is an object that 
           contains the overrides for color scheme preferences. It has the
           following members:
         
    
@@ -570,8 +578,8 @@ 
    
               
  • Let |overrides:ordered map| be the result of processing a 
                 manifest override object.
               
    • 
-              
  • Set |manifest_user_preferences|["color_scheme"][member] to 
-                |overrides|.
+              
  • Set |manifest_user_preferences|["color_scheme"][|member:string|]
+                to |overrides|.
               
    • 
             
           
@@ -582,19 +590,23 @@ 
    
           Overridable properties
         
    
         
    
-          The proterties that user_preferences can override in the 
-          [=manfiest override obeject=] are:
+          The proterties that [=user_preferences=] can override in the 
+          [=manifest override object=] are:
         
    
         
      
           
    • [=manifest/theme_color=] member.
           
      • 
           
    • [=manifest/background_color=] member.
           
      • 
-          
    • [=Shortcut item's=] [=shortcut item/icons=] member.
+          
    • [=manifest/Shortcut item's=] icons [=image resource/src=] member.
+          
      • 
+          
    • [=manifest/Shortcut item's=] icons [=image resource/type=] member.
           
      • 
-          
    • [=Icons=] [=icons/src=] member.
+          
    • [=manifest/icons=] [=image resource/src=] member.
           
      • 
-          
    • [=Icons=] [=icons/type=] member.
+          
    • [=manifest/icons=] [=image resource/type=] member.
           
      • 
         
    
       
    

From 4cbfa14fe5085a0e18857abf60a2d8bfad809d04 Mon Sep 17 00:00:00 2001
From: Louise Brett <80441278+loubrett@users.noreply.github.com>
Date: Wed, 15 Jun 2022 17:08:11 +1000
Subject: [PATCH 6/9] Update index.html

---
 index.html | 18 +++++++++++-------
 1 file changed, 11 insertions(+), 7 deletions(-)

diff --git a/index.html b/index.html
index 850eb41..277d01e 100644
--- a/index.html
+++ b/index.html
@@ -514,7 +514,7 @@ 
    
         preference media features such as contrast and 
         forced-colors,
-        as defined in [=CSS=].
+        as defined in CSS.
       
    
       
    
         The user agent SHOULD use the override values instead of the value of
@@ -598,15 +598,19 @@ 
    
           
           
  • [=manifest/background_color=] member.
           
    • 
-          
  • [=manifest/Shortcut item's=] icons [=image resource/src=] member.
+          
  • Shortcut item's 
+            icons 
+            src member.
           
    • 
-          
  • [=manifest/Shortcut item's=] icons [=image resource/type=] member.
+          
  • Shortcut item's 
+            icons 
+            type member.
           
    • 
-          
  • [=manifest/icons=] [=image resource/src=] member.
+          
  • [=manifest/icons=] src member.
           
    • 
-          
  • [=manifest/icons=] [=image resource/type=] member.
+          
  • [=manifest/icons=] type member.
           
    •

    From 87125c30f78b22c7d1fcd7e278fbcb04b02dfbaa Mon Sep 17 00:00:00 2001 From: Louise Brett <80441278+loubrett@users.noreply.github.com> Date: Thu, 16 Jun 2022 11:05:30 +1000 Subject: [PATCH 7/9] Add extra nesting to user_preferences --- index.html | 42 ++++++++++++++++++++++++------------------ 1 file changed, 24 insertions(+), 18 deletions(-) diff --git a/index.html b/index.html index 277d01e..b771b86 100644 --- a/index.html +++ b/index.html @@ -683,12 +683,14 @@

    } }, "user_preferences": { - "color_scheme_dark": { - "icons": [ - { - "src": "icon-dark.png" - } - ] + "color_scheme": + "dark": { + "icons": [ + { + "src": "icon-dark.png" + } + ] + } } } } @@ -715,12 +717,14 @@

    } ], "user_preferences": { - "color_scheme_dark": { - "icons": [ - { - "src": "icon-dark.png" - } - ] + "color_scheme": { + "dark": { + "icons": [ + { + "src": "icon-dark.png" + } + ] + } } }, "translations": { @@ -731,12 +735,14 @@

    } ], "user_preferences": { - "color_scheme_dark": { - "icons": [ - { - "src": "icon-es-dark.png" - } - ] + "color_scheme": { + "dark": { + "icons": [ + { + "src": "icon-es-dark.png" + } + ] + } } } } From 449b6d394ab51f196f16cd10682fa03b9237f1b1 Mon Sep 17 00:00:00 2001 From: Louise Brett <80441278+loubrett@users.noreply.github.com> Date: Thu, 16 Jun 2022 11:11:21 +1000 Subject: [PATCH 8/9] Update index.html --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index b771b86..cb140c3 100644 --- a/index.html +++ b/index.html @@ -683,7 +683,7 @@

    } }, "user_preferences": { - "color_scheme": + "color_scheme": { "dark": { "icons": [ { From 1cc9d120ab6126fed1587bd3ab0f1d632c90ef0b Mon Sep 17 00:00:00 2001 From: Aaron Gustafson Date: Fri, 24 Jun 2022 16:37:51 -0700 Subject: [PATCH 9/9] Adding an algorithm for processing an override object --- index.html | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/index.html b/index.html index cb140c3..67c5af3 100644 --- a/index.html +++ b/index.html @@ -753,6 +753,29 @@

    User agents MAY ignore any override properties they do not support.

    +

    + To apply a manifest override object, given [=ordered_map=] + |overrides:json|, [=ordered map=] + |manifest:ordered map|, and [=array=] |allowed_properties:array| run the following: +

    +
      +
    1. Let |allowed_overrides| be a new [=ordered map=]. +
      2. +
    2. [=list/For each=] |member:string| of |overrides|: +
        +
      1. If |member| is not in |allowed_properties|, continue. +
        2. +
      2. Set |allowed_overrides|[|member|] to |overrides[|member|]|. +
        3. +
      +
      3. +
    3. Let |overriden_manifest| be the result of creating a new [=ordered map=] + by merging |manifest| with |allowed_overrides|. +
      4. +
    4. + Set |manifest| to |overriden_manifest|. +
      5. +