From 3ffdbba8580e0096aa7d492d49e1309001d25162 Mon Sep 17 00:00:00 2001 From: Gary Kacmarcik Date: Thu, 29 Dec 2016 18:58:04 -0800 Subject: [PATCH] Add initial draft of Async API read() and write(). --- index.bs | 120 +++++++++++++++++++++- index.html | 284 +++++++++++++++++++++++++++++++++++++++++++++-------- 2 files changed, 360 insertions(+), 44 deletions(-) diff --git a/index.bs b/index.bs index 2344395..52f1caf 100644 --- a/index.bs +++ b/index.bs @@ -29,6 +29,10 @@ urlPrefix: https://dom.spec.whatwg.org/#; type: dfn; text: constructing events urlPrefix: http://w3c.github.io/editing/contentEditable.html#dfn-; type: dfn; text: editing host +spec: ecma-262; urlPrefix: http://tc39.github.io/ecma262/ + type: dfn + text: Assert; url: sec-algorithm-conventions + text: promise; url: sec-promise-objects 
@@ -130,6 +134,7 @@ urlPrefix: http://w3c.github.io/editing/contentEditable.html#dfn-; type: dfn;
 		-->
 
 		

+
 		
 		dictionary ClipboardEventInit : EventInit {
 		  DataTransfer? clipboardData = null;
@@ -248,8 +253,121 @@ urlPrefix: http://w3c.github.io/editing/contentEditable.html#dfn-; type: dfn;
 			If the event listener modifies the selection or focus, the clipboard
 			action must be completed on the modified selection.
 
+
Asynchronous Clipboard API

+
+	
Model

+
+		The platform provides a system clipboard.
+
+		The [=system clipboard=] has a list of clipboard items that are collectively
+		called the system clipboard data. The [=system clipboard data=] is associated
+		with a {{DataTransfer}} object that contains the contents of the clipboard.
+
+	
+
+		
+		partial interface Navigator {
+		  [SecureContext] readonly attribute Clipboard clipboard;
+		};
+		

+
+		
+
+	
Clipboard Interface

+
+		
+		[SecureContext] interface Clipboard {
+		  Promise<DataTransfer> read();
+		  Promise<void> write(DataTransfer data);
+		};
+		

+
+		

+
+		

+		
read()

+		The [=read()=] method must run these steps:
+
+			1. Let |p| be a new [=Promise=].
+
+			1. TODO: Handle access permissions. Reject promise if not allowed.
+
+			1. Run the following steps [=in parallel=]:
+
+				1. Let |data| be a copy of the [=system clipboard data=].
+
+				1. Resolve |p| with |data|.
+
+			1. Return |p|.
+
+			

+
+			
+				navigator.clipboard.read().then(function(data) {
+					for (var i = 0; i < data.items.length; i++) {
+						if (data.items[i].type == "text/plain") {
+							console.log(“Your string:”, data.items[i].getAs(“text/plain”))
+						} else {
+							console.error(“No text/plain data on clipboard.”);
+						}
+					}
+				});
+			

+
+		

+
+		

+		
write(|data|)

+		The [=write(data)=] method must run these steps:
+
+			1. Let |p| be a new [=Promise=].
+
+			1. TODO: Handle access permissions. Reject promise if not allowed.
+
+			1. Run the following steps [=in parallel=]:
+
+				1. Let |cleanItemList| be an empty {{DataTransferItemList}}.
+
+				1. For each {{DataTransferItem}} |item| in |data|'s {{DataTransfer/items}} list:
+
+					1. Let |cleanItem| be a sanitized copy of |item|.
+
+					1. If unable to create a sanitized copy, then reject |p|.
+
+					1. Add |cleanItem| to |cleanItemList|.
+
+				1. Replace the [=system clipboard data=]'s {{DataTransfer/items}}
+					list with |cleanItemList|.
+
+				1. Resolve |p|.
+
+			2. Return |p|.
+
+			

+
+			
+				var data = new DataTransfer();
+				data.items.add("text/plain", "Howdy, partner!");
+				navigator.clipboard.write(data).then(function() {
+					console.log(“Copied to clipboard successfully!”);
+				}, function() {
+					console.error(“Unable to write to clipboard. :-(”);
+				});
+			

+
+		

+
+		

+
 
-
Synchronous Clipboard API

+
Synchronous Clipboard API

 
 	
Clipboard actions and events

 
diff --git a/index.html b/index.html
index a283bc4..f45a67a 100644
--- a/index.html
+++ b/index.html
@@ -1424,7 +1424,7 @@
   

    
 

    
Clipboard API and events

-   
Editor’s Draft, 

+   
Editor’s Draft, 

    

     

      
This version:
@@ -1497,35 +1497,51 @@ 
Table of Contents

        
      
     
  • 
-     5 Synchronous Clipboard API
+     5 Asynchronous Clipboard API
      
      
+      
    1. 5.1 Model
       
    2. 
-       5.1 Clipboard actions and events
+       5.2 Navigator Interface
+       
        
+        
      1. 5.2.1 clipboard
+       
      
+      
    3. 
+       5.3 Clipboard Interface
+       
        
+        
      1. 5.3.1 read()
+        
      2. 5.3.2 write(data)
+       
      
+     
    
+    
  • 
+     6 Synchronous Clipboard API
+     
      
+      
    1. 
+       6.1 Clipboard actions and events
        
        
         
      1. 
-         5.1.1 Actions
+         6.1.1 Actions
          
          
-          
        1. 5.1.1.1 The copy action
-          
        2. 5.1.1.2 The cut action
-          
        3. 5.1.1.3 The paste action
+          
        4. 6.1.1.1 The copy action
+          
        5. 6.1.1.2 The cut action
+          
        6. 6.1.1.3 The paste action
          
        
        
      
      
    
     
  • 
-     6 Mandatory data types
+     7 Mandatory data types
      
      
-      
    1. 6.1 Reading from the clipboard
-      
    2. 6.2 Writing to the clipboard
+      
    3. 7.1 Reading from the clipboard
+      
    4. 7.2 Writing to the clipboard
      
    
     
  • 
-     7 Security Considerations
+     8 Security Considerations
      
      
-      
    1. 7.1 Pasting HTML and multi-part data
-      
    2. 7.2 General security policies
-      
    3. 7.3 Nuisance considerations
+      
    4. 8.1 Pasting HTML and multi-part data
+      
    5. 8.2 General security policies
+      
    6. 8.3 Nuisance considerations
      
    
-    
  • 8 Privacy Considerations
-    
  • 9 Acknowledgements
+    
  • 9 Privacy Considerations
+    
  • 10 Acknowledgements
     
  • 
       Appendix A: Algorithms
      
      
@@ -1706,11 +1722,108 @@ 
      4.2.5. Event listeners that modify selection or focus
      
    
      If the event listener modifies the selection or focus, the clipboard
 			action must be completed on the modified selection.
      
-   
      5. Synchronous Clipboard API
      
-   
      5.1. Clipboard actions and events
      
+   
      5. Asynchronous Clipboard API
      
+   
      5.1. Model
      
+   
      The platform provides a system clipboard.
      
+   
      The system clipboard has a list of clipboard items that are collectively
+		called the system clipboard data. The system clipboard data is associated
+		with a DataTransfer object that contains the contents of the clipboard.
      
+   
+
      partial interface Navigator {
+  [SecureContext] readonly attribute Clipboard clipboard;
+};
+
      
+   
+   
      5.3. Clipboard Interface
      
+
      [SecureContext] interface Clipboard {
+  Promise<DataTransfer> read();
+  Promise<void> write(DataTransfer data);
+};
+
      
+   
      
+    
      
+     
      5.3.1. read()
      
+      The read() method must run these steps: 
+     
        
+      
      1. 
+       
        Let p be a new Promise.
        
+      
      2. 
+       
        TODO: Handle access permissions. Reject promise if not allowed.
        
+      
      3. 
+       
        Run the following steps in parallel:
        
+       
          
+        
        1. 
+         
          Let data be a copy of the system clipboard data.
          
+        
        2. 
+         
          Resolve p with data.
          
+       
        
+      
      4. 
+       
        Return p.
        
+     
      
+     
      
+
      navigator.clipboard.read().then(function(data) {
+  for (var i = 0; i < data.items.length; i++) {
+    if (data.items[i].type == "text/plain") {
+      console.log(“Your string:”, data.items[i].getAs(“text/plain”))
+    } else {
+      console.error(“No text/plain data on clipboard.”);
+    }
+  }
+});
+
      
+    
      
+    
      
+     
      5.3.2. write(data)
      
+      The write(data) method must run these steps: 
+     
        
+      
      1. 
+       
        Let p be a new Promise.
        
+      
      2. 
+       
        TODO: Handle access permissions. Reject promise if not allowed.
        
+      
      3. 
+       
        Run the following steps in parallel:
        
+       
          
+        
        1. 
+         
          Let cleanItemList be an empty DataTransferItemList.
          
+        
        2. 
+         
          For each DataTransferItem item in data’s items list:
          
+         
            
+          
          1. 
+           
            Let cleanItem be a sanitized copy of item.
            
+          
          2. 
+           
            If unable to create a sanitized copy, then reject p.
            
+          
          3. 
+           
            Add cleanItem to cleanItemList.
            
+         
          
+        
        3. 
+         
          Replace the system clipboard data's items list with cleanItemList.
          
+        
        4. 
+         
          Resolve p.
          
+       
        
+      
      4. 
+       
        Return p.
        
+     
      
+     
      
+
      var data = new DataTransfer();
+data.items.add("text/plain", "Howdy, partner!");
+navigator.clipboard.write(data).then(function() {
+  console.log(“Copied to clipboard successfully!”);
+}, function() {
+  console.error(“Unable to write to clipboard. :-(”);
+});
+
      
+    
      
+   
      
+   
      6. Synchronous Clipboard API
      
+   
      6.1. Clipboard actions and events
      
    
      This section defines clipboard actions and events and the processing model
 		for event dispatch.
      
-   
      5.1.1. Actions
      
+   
      6.1.1. Actions
      
    
      Each action has two flags called script-triggered and script-may-access-clipboard.
      
    
      The script-triggered flag is set if the action runs because
 			of a script, for example a document.execCommand() call.
@@ -1736,7 +1849,7 @@ 
      
       
    
     
    
    • 
-   
    5.1.1.1. The copy action
    
+   
    6.1.1.1. The copy action
    
    
    
      NOTE: 
     
    When the user initiates a copy action, the implementation fires a clipboard event named copy. If the event is not canceled, the selected data will be
@@ -1791,7 +1904,7 @@ 
    5.1.1.2. The cut action
    
+   
    6.1.1.2. The cut action
    
    
    
      NOTE: 
     
    When the user initiates a cut action, the implementation fires a clipboard event named cut. In an editable context, if the event is not
@@ -1862,7 +1975,7 @@ 
    5.1.1.3. The paste action
    
+   
    6.1.1.3. The paste action
    
    
    
      NOTE: 
     
    When a user initiates a paste action, the implementation fires a clipboard event named paste. The event fires before any clipboard data is inserted.
    
@@ -1935,12 +2048,12 @@ 
    6. Mandatory data types
    
+   
    7. Mandatory data types
    
    
    The implementation must recognise the native OS clipboard format description
 	for the following data types, to be able to populate the DataTransferItemList with the correct description for paste events, and
 	set the correct data format on the OS clipboard in response to copy and cut
 	events.
    
-   
    6.1. Reading from the clipboard
    
+   
    7.1. Reading from the clipboard
    
    
    These data types must be exposed by paste events if a
 		corresponding native type exists on the clipboard:
    
    
      
@@ -1973,7 +2086,7 @@ 
      
      
      application/octet-stream
      
    
    
-   
    6.2. Writing to the clipboard
    
+   
    7.2. Writing to the clipboard
    
    
    These data types must be placed on the clipboard with a corresponding
 		native type description if added to a DataTransfer object during copy and cut events.
    
    
   
    References
    
   
    Normative References
    
   
    
+   
    [ECMASCRIPT]
+   
    ECMAScript Language Specification. URL: https://tc39.github.io/ecma262/
    
    [HTML]
    
    Ian Hickson. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
    
    [HTMLLS]
@@ -2565,6 +2714,8 @@ 
    N
    
    S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
    
    [RFC2392]
    
    E. Levinson. Content-ID and Message-ID Uniform Resource Locators. August 1998. Internet RFC 2392.. URL: http://www.ietf.org/rfc/rfc2392.txt
+   
    [WebIDL]
+   
    Cameron McCormack; Boris Zbarsky; Tobie Langel. Web IDL. URL: https://heycam.github.io/webidl/
    
    [WHATWG-DOM]
    
    Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
   
    
@@ -2587,6 +2738,15 @@ 
    I
   readonly attribute DataTransfer? clipboardData;
 };
 
+partial interface Navigator {
+  [SecureContext] readonly attribute Clipboard clipboard;
+};
+
+[SecureContext] interface Clipboard {
+  Promise<DataTransfer> read();
+  Promise<void> write(DataTransfer data);
+};
+
 
    
   
    Issues Index
    
   
    
@@ -2606,8 +2766,8 @@ 
    
    #editable-contextReferenced in:
    
   
   
   
+  
+  
+  
+  
+  
+