Re: [w3c/clipboard-apis] Add clipboard IDL description. (#158)

@snianu commented on this pull request.



> +    a user gesture event and the user must select the paste option from the native context menu that pops up
+    when read() is called from JS, otherwise, the promise will be rejected.
+
+    1. If |r| is not "granted", then [=a promise rejected with=] "NotAllowedError" DOMException in |realm|.
+
+    1. Let |itemList| and |cleanItemList| be an empty sequence<{{Blob}}>.
+
+    1. Let |clipboardItemList| be an empty [=ClipboardItems=].
+
+    1. For each |clipboardItem| in |data|:
+
+     1. For each |item| in |clipboardItem|:
+
+      1. Let |p1| be [=a new promise=] to {{Blob}} in |realm|.
+
+      1. If |p1| is [=reject=]d, then throw "Promises to Blobs were rejected." DOMException in |realm|.

Done.

>  
-    readonly attribute FrozenArray<DOMString> types;
+   dictionary ClipboardItemOptions {
+    PresentationStyle presentationStyle = "unspecified";
+   };
+  </pre>
+  <p><dfn>Clipboard Item</dfn></p>
+  A [=clipboard item=] is conceptually data that the user has expressed a desire to make shareable by invoking a "cut" or "copy" command.
+  For example, if a user copies a range of cells from a spreadsheet, it will result in one [=clipboard item=]. If a user copies a set of files from their desktop, that list of files will be a different single [=clipboard item=].

Done.

>  
-    readonly attribute FrozenArray&lt;DOMString> types;
+   dictionary ClipboardItemOptions {
+    PresentationStyle presentationStyle = "unspecified";
+   };
+  </pre>
+  <p><dfn>Clipboard Item</dfn></p>
+  A [=clipboard item=] is conceptually data that the user has expressed a desire to make shareable by invoking a "cut" or "copy" command.
+  For example, if a user copies a range of cells from a spreadsheet, it will result in one [=clipboard item=]. If a user copies a set of files from their desktop, that list of files will be a different single [=clipboard item=].
+  Some platforms may support having more than one [=clipboard item=] at a time on the [=Clipboard=], while other platforms replace the previous [=clipboard item=] with the new one. 
+
+  Each [=clipboard item=] can be represented as multiple mime-types. In the example where the user copies a range of cells from a spreadsheet, it may be represented as an image (image/png), an HTML table (text/html), or plain text (text/plain).

Done.

> +      {[format1]: promise_text_blob},
+      {options: "unspecified"});
+    </pre>
+
+   <dt><code><var>clipboardItem</var>.getType(<var>type</var>)</code>
+   <dd><p>Returns a [=Promise=] to the [=Blob=] corresponding to <var>type</var>.</p>
+
+   <dt><code><var>clipboardItem</var>.<var>types</var></code>
+   <dd><p>Returns the list of <var>types</var> contained in the <var>clipboardItem</var> object.
+
+  </dl>
+  <p>
+   A {{ClipboardItem}} object has an associated [=clipboard item=].
+  </p>
+  <p>
+   A {{ClipboardItem}} object's {{ClipboardItem/presentationStyle}} is its [=clipboard item=]'s [=presentation style=].

Done.

> +
+   <dt><code><var>clipboardItem</var>.getType(<var>type</var>)</code>
+   <dd><p>Returns a [=Promise=] to the [=Blob=] corresponding to <var>type</var>.</p>
+
+   <dt><code><var>clipboardItem</var>.<var>types</var></code>
+   <dd><p>Returns the list of <var>types</var> contained in the <var>clipboardItem</var> object.
+
+  </dl>
+  <p>
+   A {{ClipboardItem}} object has an associated [=clipboard item=].
+  </p>
+  <p>
+   A {{ClipboardItem}} object's {{ClipboardItem/presentationStyle}} is its [=clipboard item=]'s [=presentation style=].
+  </p>
+  <p>
+   A {{ClipboardItem}} object's {{ClipboardItem/types}} is its [=clipboard item=]'s [=types=].

Done.

> +  </p>
+
+  <p>A [=clipboard item=] has an associated <dfn>types</dfn> which contains the MIME types.</p>
+
+  <dl class=note>
+   <dt><code><var>clipboardItem</var> = new ClipboardItem([<var>items</var>, <var>options</var>])</code>
+   <dd>
+   Creates a new {{ClipboardItem}} object. <var>items</var> are used to fill its MIME types and [=Promise=]s to [=Blob=]s or {{DOMString}}s corresponding to the MIME types, <var>options</var> can be used to fill its {{ClipboardItemOptions}},
+   as per the example below.
+
+    <pre class="example javascript" highlight=js>
+     const format1 = 'text/plain';
+     const promise_text_blob = Promise.resolve(new Blob(['hello'], {type: format1}));
+     const clipboardItemInput = new ClipboardItem(
+      {[format1]: promise_text_blob},
+      {options: "unspecified"});

Done.

> +
+   <dt><code><var>clipboardItem</var>.<var>types</var></code>
+   <dd><p>Returns the list of <var>types</var> contained in the <var>clipboardItem</var> object.
+
+  </dl>
+  <p>
+   A {{ClipboardItem}} object has an associated [=clipboard item=].
+  </p>
+  <p>
+   A {{ClipboardItem}} object's {{ClipboardItem/presentationStyle}} is its [=clipboard item=]'s [=presentation style=].
+  </p>
+  <p>
+   A {{ClipboardItem}} object's {{ClipboardItem/types}} is its [=clipboard item=]'s [=types=].
+  </p>
+  <p>
+   The <a constructor lt="ClipboardItem()">constructor</a> steps for <code>new ClipboardItem(<var>items</var>, <var>options</var>)</code> are to set [=this=]'s items to <var>items</var> and options to <var>options</var>.

Added these details. Please let me know if this is going in the right direction. Thanks!

> +  <p>
+   A {{ClipboardItem}} object has an associated [=clipboard item=].
+  </p>
+  <p>
+   A {{ClipboardItem}} object's {{ClipboardItem/presentationStyle}} is its [=clipboard item=]'s [=presentation style=].
+  </p>
+  <p>
+   A {{ClipboardItem}} object's {{ClipboardItem/types}} is its [=clipboard item=]'s [=types=].
+  </p>
+  <p>
+   The <a constructor lt="ClipboardItem()">constructor</a> steps for <code>new ClipboardItem(<var>items</var>, <var>options</var>)</code> are to set [=this=]'s items to <var>items</var> and options to <var>options</var>.
+  </p>
+
+  <h4 attribute for=ClipboardItem lt=presentationStyle>presentationStyle</h4>
+  <p>
+   Each {{ClipboardItem}} has a {{ClipboardItem/presentationStyle}}, which is a {{PresentationStyle}}.

Done.

> +  Making the range of cells available as an image will allow the user to paste the cells into Photoshop, while the text/plain format can be used by applications like Windows Notepad.
+
+  Apps that support pasting only a single [=clipboard item=] should use the first [=clipboard item=].
+  Apps that support pasting more than one [=clipboard item=] could, for example, provide a user interface that previews the contents of each [=clipboard item=] and allow the user to choose which one to paste.
+  Further, apps are expected to enumerate the mime-types of the [=clipboard item=] they are pasting and select the one best-suited for the app according to some app-specific algorithm.
+  Alternatively, an app can present the user with options on how to paste a [=clipboard item=], e.g. “paste as image” or “paste formatted text”, etc.
+
+  A [=clipboard item=] contains multiple representations. Each representation consists of a MIME type and a corresponding {{DOMString}} or [=Blob=].
+
+  <p>A [=clipboard item=] has an associated <dfn>presentation style</dfn> which is <code>"unspecified"</code> or <code>"inline"</code> or <code>"attachment"</code>.
+  [=presentation style=] helps distinguish between "inline" data(e.g. selecting text on a web page and copying), vs. file-like data (e.g. copying a plain text file).
+  This difference is used to provide a hint when writing to the system pasteboard on iOS/iPadOS. This allows apps like Notes to insert a file attachment when copying a plain text file from the Files app, but insert text inline when
+  copying a selected piece of plain text from another app. In both cases, the MIME type in the pasteboard would be text/plain. This is used for both reading and writing.
+  </p>
+
+  <p>A [=clipboard item=] has an associated <dfn>types</dfn> which contains the MIME types.</p>

Removed.

> +  </p>
+  <p>
+   A {{ClipboardItem}} object's {{ClipboardItem/types}} is its [=clipboard item=]'s [=types=].
+  </p>
+  <p>
+   The <a constructor lt="ClipboardItem()">constructor</a> steps for <code>new ClipboardItem(<var>items</var>, <var>options</var>)</code> are to set [=this=]'s items to <var>items</var> and options to <var>options</var>.
+  </p>
+
+  <h4 attribute for=ClipboardItem lt=presentationStyle>presentationStyle</h4>
+  <p>
+   Each {{ClipboardItem}} has a {{ClipboardItem/presentationStyle}}, which is a {{PresentationStyle}}.
+   The {{ClipboardItem/presentationStyle}} getter steps are to return [=this=]'s [=clipboard item=]'s [=presentation style=].
+  </p>
+
+  <h4 attribute for=ClipboardItem lt=types>types</h4>
+  <p> Each {{ClipboardItem}} has a {{ClipboardItem/types}}, which contains the MIME types.

Added getter steps.

> +     const format1 = 'text/plain';
+     const promise_text_blob = Promise.resolve(new Blob(['hello'], {type: format1}));
+     const clipboardItemInput = new ClipboardItem(
+      {[format1]: promise_text_blob},
+      {options: "unspecified"});
+    </pre>
+
+   <dt><code><var>clipboardItem</var>.getType(<var>type</var>)</code>
+   <dd><p>Returns a [=Promise=] to the [=Blob=] corresponding to <var>type</var>.</p>
+
+   <dt><code><var>clipboardItem</var>.<var>types</var></code>
+   <dd><p>Returns the list of <var>types</var> contained in the <var>clipboardItem</var> object.
+
+  </dl>
+  <p>
+   A {{ClipboardItem}} object has an associated [=clipboard item=].

Bikeshed is throwing error due to multiple definitions of `clipboard item`, so I changed the `clipboard item` definition to `<dfn for="ClipboardItem">Clipboard Item</dfn>`

> +
+  <h4 attribute for=ClipboardItem lt=presentationStyle>presentationStyle</h4>
+  <p>
+   Each {{ClipboardItem}} has a {{ClipboardItem/presentationStyle}}, which is a {{PresentationStyle}}.
+   The {{ClipboardItem/presentationStyle}} getter steps are to return [=this=]'s [=clipboard item=]'s [=presentation style=].
+  </p>
+
+  <h4 attribute for=ClipboardItem lt=types>types</h4>
+  <p> Each {{ClipboardItem}} has a {{ClipboardItem/types}}, which contains the MIME types.
+      {{ClipboardItem/types}} getter steps are to return [=this=]'s [=clipboard item=]'s [=types=].</p>
+
+  <h4 method for=ClipboardItem lt=getType(type)>getType(type)</a> must run the below steps:</h4>
+
+   1. Let |realm| be [=this=]'s [=relevant realm=].
+
+   1. If |type| is not listed in the [=mandatory data types=] list, then [=a promise rejected with=] "The type was not found" DOMException in |realm|.

Done.

> +   The {{ClipboardItem/presentationStyle}} getter steps are to return [=this=]'s [=clipboard item=]'s [=presentation style=].
+  </p>
+
+  <h4 attribute for=ClipboardItem lt=types>types</h4>
+  <p> Each {{ClipboardItem}} has a {{ClipboardItem/types}}, which contains the MIME types.
+      {{ClipboardItem/types}} getter steps are to return [=this=]'s [=clipboard item=]'s [=types=].</p>
+
+  <h4 method for=ClipboardItem lt=getType(type)>getType(type)</a> must run the below steps:</h4>
+
+   1. Let |realm| be [=this=]'s [=relevant realm=].
+
+   1. If |type| is not listed in the [=mandatory data types=] list, then [=a promise rejected with=] "The type was not found" DOMException in |realm|.
+
+   1. Let |p| be [=a new promise=] in |realm|.
+
+   1. Let |blobData| be a [=Blob=] corresponding to the |type|.

Clarified some steps using some new concepts defined in the `clipboard item` object.

>  
-    Promise&lt;Blob> getType(DOMString type);
-  };
+   1. Return |p|.
+
+  <h4 typedef>ClipboardItemDataType</h4>

Done.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3c/clipboard-apis/pull/158#discussion_r747066211