From 99ae3446d56c476e9a7faede3aa2911f5b4f06c1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= Date: Mon, 27 Nov 2017 13:03:39 +1100 Subject: [PATCH 1/9] fix: ReSpec link warnings --- index.html | 126 ++++++++++++++++++++++++----------------------------- 1 file changed, 58 insertions(+), 68 deletions(-) diff --git a/index.html b/index.html index db57754..e1cd4be 100644 --- a/index.html +++ b/index.html @@ -65,28 +65,28 @@

.then(console.log('Share successful')); }); -

- Note that a url of '' - refers to the current page URL, just as it would in a link. Any other - absolute or relative URL can also be used. +

+ Note that a url of '' refers to the current page + URL, just as it would in a link. Any other absolute or relative URL can + also be used.

-

- In response to this call to navigator.share, the - user agent would display a picker or chooser dialog, allowing the user - to select a target to share this title and the page URL to. +

+ In response to this call to navigator.share(), the user agent + would display a picker or chooser dialog, allowing the user to select a + target to share this title and the page URL to.

API definition

-
+

Navigator interface

- The Navigator - interface is defined in [[!HTML]]. + The Navigator interface is + defined in [[!HTML]]. 

           partial interface Navigator {
@@ -95,8 +95,7 @@
The data argument is marked as "optional", but it is - effectively required; share will - throw a share() will throw a TypeError if called with no arguments. WebIDL mandates that it be optional because the @@ -104,39 +103,36 @@

"https://github.com/heycam/webidl/issues/130">Issue #130.

- User agents that do not support sharing SHOULD NOT expose share on the - Navigator interface. + User agents that do not support sharing SHOULD NOT expose + share() on the Navigator interface.

The above statement is designed to permit feature detection. If - share is present, there is a - reasonable expectation that it will work and present the user with at - least one share target. Clients can use the presence or - absence of this method to determine whether to show UI that triggers - its use. + share() is present, there is a reasonable expectation that it + will work and present the user with at least one share target. + Clients can use the presence or absence of this method to determine + whether to show UI that triggers its use.

- share method + share() method

- When the share method is called with argument + When the share() method is called with argument data, run the following steps:

  1. Let p be a new promise.
    2. -
  2. If none of data's members title, text, or url are present, reject p with - TypeError, and - abort these steps. +
  3. If none of data's members + title, text, or url are present, reject + p with TypeError, and + abort these steps.
    4. -
  4. If data's url member is - present: +
  5. If data's url + member is present:
    1. Let base be the this value's relevant @@ -145,8 +141,8 @@

    2. Let url be the result of running the URL parser on - data's url, with - base, and no encoding override. + data's url, with base, and no + encoding override.
    3. If url is failure, reject p with @@ -155,9 +151,9 @@

      and abort these steps.

    4. Set data to a copy of data, with its - url field set to the result of running - the URL - serializer on url. + url field set to the result of running the + URL serializer + on url.
    6. @@ -213,17 +209,16 @@

    targets are available, or the identity of the chosen target.

    - share always shows some form of - UI, to give the user a choice of application and get their approval - to invoke and send data to a potentially native application (which - carries a security risk). For this reason, user agents are - prohibited from showing any kind of "always use this target in the - future" option, or bypassing the UI if there is only a single share - target. + share() always shows some form of UI, to give the user a + choice of application and get their approval to invoke and send + data to a potentially native application (which carries a security + risk). For this reason, user agents are prohibited from showing any + kind of "always use this target in the future" option, or bypassing + the UI if there is only a single share target.

-
+

ShareData dictionary

@@ -236,7 +231,7 @@

The ShareData dictionary consists of several optional - fields: + members:

  • @@ -262,7 +257,7 @@

    UTF-8).
    - The url field can contain a url field can contain a relative URL. In this case, it will be automatically resolved relative to the current page location, just like a

-
+

Share targets

@@ -294,16 +289,15 @@

Each share target MAY be made conditionally available depending on the - ShareData payload delivered to the share - method. + ShareData payload delivered to the share() method.

Once a share target has been given the payload, the share is considered successful. If the target considers the data unacceptable or an error occurs, it can either recover gracefully, or show an error message to the end-user; it cannot rely on the sender to handle errors. In other - words, the share method is "fire and forget"; it - does not wait for the target to approve or reject the payload. + words, the share() method is "fire and forget"; it does not wait + for the target to approve or reject the payload.

@@ -337,14 +331,13 @@

can simply forward the share data to the operating system and not talk directly to native applications.

-

+

Mapping the ShareData to the share target (or operating system)'s native format can be tricky as some platforms will not have an equivalent set of fields. For example, if the target has a "text" field but not a "URL" field, one solution is to concatenate both the - text and url fields of - ShareData and pass the result in the "text" field of the - target. + text and url fields of ShareData and pass the + result in the "text" field of the target.

@@ -360,10 +353,9 @@

  • There is a requirement to not allow the website to learn which apps - are installed, or which app was chosen from - navigator.share, because this information could be - used for fingerprinting, as well as leaking details about the user's - device. + are installed, or which app was chosen from navigator.share(), + because this information could be used for fingerprinting, as well as + leaking details about the user's device.
  • Implementors will want to carefully consider what information is revealed in the error message when navigator.share @@ -413,12 +405,11 @@

    This doesn't mean user agents can add whatever members they like. It means that new members can be added to the standard in the future. -

    - The three members title, text, and url, are part of the - base feature set, and implementations that provide - navigator.share need to accept all three. Any new - members that are added in the future will be individually +

    + The three members title, text, and url, are part + of the base feature set, and implementations that provide + navigator.share() need to accept all three. Any new members that + are added in the future will be individually feature-detectable, to allow for backwards-compatibility with older implementations that don't recognise those members. These new members might also be added as optional "MAY" requirements. @@ -428,9 +419,8 @@

    discussion about how to provide feature-detection for dictionary members. Web Share will use the mechanism produced by that discussion. -

    - The share method throws a - + The share() method throws a TypeError if none of the specified members are present. The intention is that when a new member is added, it will also be added to this list of recognised From 067b8782e6d793d14349298c239f7c2573e11f0f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= Date: Mon, 27 Nov 2017 13:22:01 +1100 Subject: [PATCH 2/9] fix few additional things --- index.html | 91 +++++++++++++++++++++++++++++------------------------- 1 file changed, 49 insertions(+), 42 deletions(-) diff --git a/index.html b/index.html index e1cd4be..0fc1bfc 100644 --- a/index.html +++ b/index.html @@ -85,8 +85,8 @@

    Navigator interface

    - The Navigator interface is - defined in [[!HTML]]. + The Navigator + interface is defined in [[!HTML]]. 

               partial interface Navigator {
@@ -119,20 +119,19 @@ 
    
           
    
           
    
             When the share() method is called with argument
-            data, run the following steps:
+            ShareData data, run the following steps:
           
    
-          
      
+          
        
             
      1. Let p be a new promise.
             
        2. 
-            
      2. If none of data's members
-            title, text, or url are present, reject 
-              p with TypeError, and
-              abort these steps.
+            
      3. If none of data's members title, text,
+            or url are present, reject p with TypeError, and
+            abort these steps.
             
        4. 
-            
      4. If data's url
-            member is present:
+            
      5. If data's url member is present:
               
          
                 
        1. Let base be the this value's
                   relevant
@@ -224,8 +223,8 @@ 
          
         
          
         
                     dictionary ShareData {
-            USVString title;
             USVString text;
+            USVString title;
             USVString url;
           };
         
          
@@ -233,20 +232,28 @@ 
          
           The ShareData dictionary consists of several optional
           members:
         
          
-                  
+        
          
+          
          
+            title member
+          
          
+          
          
+            The title of the document being shared. May be ignored by the
+            target.
+          
          
+          
          
+            text member
+          
          
+          
          
+            Arbitrary text that forms the body of the message being shared.
+          
          
+          
          
+            url member
+          
          
+          
          
+            A valid URL string
+            referring to a resource being shared.
+          
          
+        
          
         
          
           These fields are USVString (as opposed to
@@ -358,23 +365,23 @@ 
          
         leaking details about the user's device.
         
          2. 
         
        2. Implementors will want to carefully consider what information is
-        revealed in the error message when navigator.share
-        is rejected. Even distinguishing between the case where no targets are
+        revealed in the error message when navigator.share() is
+        rejected. Even distinguishing between the case where no targets are
         available and user cancellation could reveal information about which
         apps are installed on the user's device.
         
          3. 
-        
        3. There is a requirement that navigator.share
-        presents the user with a dialog asking them to select a target
-        application (even if there is only one possible target). This surface
-        serves as a security confirmation, ensuring that websites cannot
-        silently send data to native applications.
+        
        4. There is a requirement that navigator.share() presents the
+        user with a dialog asking them to select a target application (even if
+        there is only one possible target). This surface serves as a security
+        confirmation, ensuring that websites cannot silently send data to
+        native applications.
         
          5. 
         
        5. Due to the capabilities of the API surface,
-        navigator.share is navigator.share() is available only in secure
         contexts (such as https:// schemes).
         
          6. 
-        
        6. Use of navigator.share from a Use of navigator.share() from a private browsing mode
         might leak private data to a third-party application that does not
         respect the user's privacy setting. User agents could present
@@ -382,11 +389,11 @@ 
          
         browsing mode, but this is not mandated as the chooser UI could be
         considered sufficient warning.
         
          7. 
-        
        7. The data passed to navigator.share might be
-        used to exploit buffer overflow or other remote code execution
-        vulnerabilities in native applications that receive shares. There is no
-        general way to guard against this, but implementors will want to be
-        aware that it is a possibility.
+        
        8. The data passed to navigator.share() might be used to
+        exploit buffer overflow or other remote code execution vulnerabilities
+        in native applications that receive shares. There is no general way to
+        guard against this, but implementors will want to be aware that it is a
+        possibility.
         
          9.

@@ -411,7 +418,7 @@

navigator.share() need to accept all three. Any new members that are added in the future will be individually feature-detectable, to allow for backwards-compatibility with - older implementations that don't recognise those members. These new + older implementations that don't recognize those members. These new members might also be added as optional "MAY" requirements.

@@ -423,7 +430,7 @@

The share() method throws a TypeError if none of the specified members are present. The intention is that when a new - member is added, it will also be added to this list of recognised + member is added, it will also be added to this list of recognized members (so as to not throw an error). This is for future-proofing implementations: if a web site written against a future version of this spec uses only new members (e.g., From 6f08f69929d932d0ab3ff9b8ca235236bcc7d0b9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= Date: Mon, 27 Nov 2017 13:31:55 +1100 Subject: [PATCH 3/9] Remove redundant data-link-for --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index 0fc1bfc..08dd92b 100644 --- a/index.html +++ b/index.html @@ -70,7 +70,7 @@

URL, just as it would in a link. Any other absolute or relative URL can also be used.

-

+

In response to this call to navigator.share(), the user agent would display a picker or chooser dialog, allowing the user to select a target to share this title and the page URL to. From ecd0108ce9ea5dd3b5e21ac05532d48fd5385816 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= Date: Mon, 27 Nov 2017 14:10:32 +1100 Subject: [PATCH 4/9] Address review feedback --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index 08dd92b..7fa545d 100644 --- a/index.html +++ b/index.html @@ -119,7 +119,7 @@

When the share() method is called with argument - ShareData data, run the following steps: + data, run the following steps:

  1. Let p be Date: Mon, 27 Nov 2017 14:44:34 +1100 Subject: [PATCH 5/9] Fixup exceptions --- index.html | 83 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 48 insertions(+), 35 deletions(-) diff --git a/index.html b/index.html index 7fa545d..8f3fd11 100644 --- a/index.html +++ b/index.html @@ -95,9 +95,8 @@

    The data argument is marked as "optional", but it is - effectively required; share() will throw a TypeError if called - with no arguments. WebIDL share() will throw a TypeError if + called with no arguments. WebIDL mandates that it be optional because the dictionary members are all optional. See WebIDL Issue #130. @@ -126,9 +125,8 @@

    "!promises-guide#a-new-promise">a new promise.

  2. If none of data's members title, text, - or url are present, reject p with TypeError, and - abort these steps. + or url are present, reject p with + TypeError, and abort these steps.
  3. If data's url member is present: @@ -145,9 +143,7 @@

  4. If url is failure, reject p with - TypeError, - and abort these steps. + TypeError, and abort these steps.
  5. Set data to a copy of data, with its url field set to the result of running the @@ -159,19 +155,16 @@

  6. If the method call was not triggered by user activation, reject p with - NotAllowedError, and - abort these steps. + "!promises-guide#reject-promise">reject p with a + "NotAllowedError" DOMException, and abort these steps.
  7. In parallel:
    1. If there are no share targets available, reject - p with AbortError, and abort - these steps. + p with "AbortError" DOMException, and + abort these steps.
    2. Present the user with a choice of one or more share targets, selected at the user agent's discretion. The user @@ -180,18 +173,16 @@

    3. If the user chose to cancel the share operation, reject - p with AbortError, and abort - these steps. + p with "AbortError" DOMException, and + abort these steps.
    4. Activate the chosen share target, convert data to a format suitable for ingestion into the target, and transmit the converted data to the target. If an error occurs starting the target or transmitting the data, reject - p with AbortError, and abort - these steps. + p with "AbortError" DOMException, and + abort these steps.
    5. Once the data has been successfully transmitted to the target,

+
+

+ Dependencies +

+

+ The following are defined in [[!WEBIDL]]: +

+
    +
  • + TypeError +
    • +
  • + DOMException +
    • +
  • + AbortError +
    • +
  • + NotAllowedError. +
    • +
+

Security and privacy considerations @@ -427,19 +443,16 @@

members. Web Share will use the mechanism produced by that discussion.

- The share() method throws a TypeError if none of - the specified members are present. The intention is that when a new - member is added, it will also be added to this list of recognized - members (so as to not throw an error). This is for future-proofing - implementations: if a web site written against a future version of this - spec uses only new members (e.g., - navigator.share({image: x})), it will be valid in future - user agents, but a TypeError on user - agents implementing an older version of the spec. Developers will be - asked to feature-detect any new fields they rely on, to avoid having - errors surface in their program. + The share() method throws a TypeError if none of the + specified members are present. The intention is that when a new member + is added, it will also be added to this list of recognized members (so + as to not throw an error). This is for future-proofing implementations: + if a web site written against a future version of this spec uses + only new members (e.g., navigator.share({image: + x})), it will be valid in future user agents, but a + TypeError on user agents implementing an older version of the + spec. Developers will be asked to feature-detect any new fields they + rely on, to avoid having errors surface in their program.

Editors of this spec will want to carefully consider the genericity of From 9fda45d9c505abc84143f48754dd314e234b5ede Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= Date: Mon, 27 Nov 2017 15:00:21 +1100 Subject: [PATCH 6/9] Fix more nits --- index.html | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/index.html b/index.html index 8f3fd11..9511e1e 100644 --- a/index.html +++ b/index.html @@ -156,14 +156,15 @@

"!HTML#triggered-by-user-activation">triggered by user activation, reject p with a - "NotAllowedError" DOMException, and abort these steps. + "NotAllowedError" DOMException, and abort these + steps.
  • In parallel:
    1. If there are no share targets available, reject - p with "AbortError" DOMException, and + p with an "AbortError" DOMException, and abort these steps.
    2. Present the user with a choice of one or more share @@ -173,7 +174,7 @@

    3. If the user chose to cancel the share operation, reject - p with "AbortError" DOMException, and + p with an "AbortError" DOMException, and abort these steps.
    4. Activate the chosen share target, convert @@ -181,7 +182,7 @@

      target, and transmit the converted data to the target. If an error occurs starting the target or transmitting the data, reject - p with "AbortError" DOMException, and + p with an "AbortError" DOMException, and abort these steps.

    5. Once the data has been successfully transmitted to the @@ -347,10 +348,6 @@

      The following are defined in [[!WEBIDL]]:

        -
      • - TypeError -
      • DOMException @@ -360,9 +357,14 @@

      • NotAllowedError. + "!WEBIDL#notallowederror">NotAllowedError
      +

      + TypeError + is defined by [[!ECMA-262]]. +

    • From 69353aea5fc923947ed3bd0847e02a21d5a256e1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= Date: Mon, 27 Nov 2017 15:02:41 +1100 Subject: [PATCH 7/9] fix typo --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index 9511e1e..6563f7f 100644 --- a/index.html +++ b/index.html @@ -224,7 +224,7 @@

    The ShareData dictionary consists of several optional members:

    -
    +
    title member
    From d6d7bb24c2cbaf5dab8b2cf084e1c87845e9f135 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= Date: Mon, 27 Nov 2017 15:07:18 +1100 Subject: [PATCH 8/9] fix ECMASCRIPT citation --- index.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.html b/index.html index 6563f7f..706cf8d 100644 --- a/index.html +++ b/index.html @@ -362,8 +362,8 @@

    TypeError - is defined by [[!ECMA-262]]. + "!ECMASCRIPT#sec-native-error-types-used-in-this-standard-typeerror">TypeError + is defined by [[!ECMASCRIPT]].

    From 9c2b429466d121d4e0ae88608f27f440666bb82c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= Date: Wed, 29 Nov 2017 14:11:10 +1100 Subject: [PATCH 9/9] Revert ordering of USVString title --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index 706cf8d..3b6227a 100644 --- a/index.html +++ b/index.html @@ -215,8 +215,8 @@ 

               dictionary ShareData {
-            USVString text;
             USVString title;
+            USVString text;
             USVString url;
           };