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

@mbrodesser requested changes on this pull request.

@snianu thanks for incorporating the previous feedback. I'll continue reviewing tomorrow.

> +
+  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.
+
+  A [=/clipboard item=] has a <dfn>list of representations</dfn>, each <dfn>representation</dfn> with an associated <dfn for=representation>mime type</dfn> (a [=/MIME type=]) and <dfn for=representation>data</dfn> (a {{ClipboardItemData}}).
+
+  <p class=note>
+   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).
+  </p>
+
+  Each of these [=/MIME type=]s describe a different [=representation=] of the same [=/clipboard item=] at different levels of fidelity and make the [=/clipboard item=] more consumable by target applications during paste.
+
+  <p class=note>
+   Making the range of cells available as an image will allow the user to paste the cells into a photo editing app, while the text/plain format can be used by text editor apps.
+  </p>
+
+  A [=/clipboard item=] can also optionally have a <dfn>presentation style</dfn> that helps distinguish whether apps "pasting" a [=/clipboard item=] should insert the contents of an appropriate [=representation=] inline at the point of paste or if it should be treated as an attachment.

A clipboard item always has a presentation style, it may just be `unspecified`. So this could be rephrased to something like:
```
A [=/clipboard item] has a <dfn>presentation style</dfn> (a {{PresentationStyle}}). It helps distinguish [...]
```

>  
-    readonly attribute FrozenArray&lt;DOMString> types;
+  <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}},

Something like
```<var>items</var> denote multiple representations, each given by their [=/MIME type=] and a [=Promise] to a {{Blob}} or {{DOMString}}```
seems more accurate, including the link to MIME type.

>  
-    Promise&lt;Blob> getType(DOMString type);
-  };
+    <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},
+      {presentationStyle: "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>

Perhaps instead
[...] ```corresponding to the [=/MIME type=] <var>type</var>``` [...]
..

>  
-    Promise&lt;Blob> getType(DOMString type);
-  };
+    <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},
+      {presentationStyle: "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.

```Returns the list of [=/MIME type=]s contained in``` [...]
would be clearer.

> +     const clipboardItemInput = new ClipboardItem(
+      {[format1]: promise_text_blob},
+      {presentationStyle: "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>
+
+  <h4 id="clipboard-item">Clipboard Item</h4>
+
+  A <dfn>clipboard item</dfn> is conceptually data that the user has expressed a desire to make shareable by invoking a "cut" or "copy" command.

As mentioned some weeks ago, that text doesn't cover the case of a website creating a `ClipboardItem` and propagating it to the system clipboard via `write()` or `writeText()`. There's also a subtle difference: a user expressing his desire to share data and a website reading data (and asking for permission to do that). So something like the following could be clearer:

```
A clipboard item serves two purposes. First, it allows a website to read data copied by a user to the system clipboard. Second, it allows a website to write data to the system clipboard.
```

Moreover, as proposed previously a more formal definition of `clipboard item` would be clearer:
```A <dfn>clipboard item</dfn> is a struct``` [...].

> +   <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>
+
+  <h4 id="clipboard-item">Clipboard Item</h4>
+
+  A <dfn>clipboard item</dfn> is conceptually data that the user has expressed a desire to make shareable by invoking a "cut" or "copy" command.
+
+  <p class=note>
+   For example, if a user copies a range of cells from a spreadsheet of a native application, it will result in one [=/clipboard item=]. If a user copies a set of files from their desktop, that list of files will be represented by multiple [=/clipboard item=]s.
+  </p>
+
+  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.

This is vaguely formulated, because it's unclear which "previous clipboard item" is meant.

How about moving this as a note to the `read()` section? After step 3.3. ("Let data be a copy of the system clipboard data represented as clipboard items.[...]). Ideally, that platform-specific part would have to be specified in detail for each platform, however in order to limit the scope of this review, I suggest adding it as a note. CC @domenic 
For `write()` a note about the platform-dependency would have to be added too, after step 3.3.3. Something like
"As the ClipboardItems are written in order, this implies for platforms supporting only exactly one ClipboardItem, the last item replaces the previously written ones."


> +
+  A [=/clipboard item=] has a <dfn>list of representations</dfn>, each <dfn>representation</dfn> with an associated <dfn for=representation>mime type</dfn> (a [=/MIME type=]) and <dfn for=representation>data</dfn> (a {{ClipboardItemData}}).
+
+  <p class=note>
+   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).
+  </p>
+
+  Each of these [=/MIME type=]s describe a different [=representation=] of the same [=/clipboard item=] at different levels of fidelity and make the [=/clipboard item=] more consumable by target applications during paste.
+
+  <p class=note>
+   Making the range of cells available as an image will allow the user to paste the cells into a photo editing app, while the text/plain format can be used by text editor apps.
+  </p>
+
+  A [=/clipboard item=] can also optionally have a <dfn>presentation style</dfn> that helps distinguish whether apps "pasting" a [=/clipboard item=] should insert the contents of an appropriate [=representation=] inline at the point of paste or if it should be treated as an attachment.
+
+  Apps that support pasting only a single [=/clipboard item=] should use the first [=/clipboard item=].

This is the opposite of what happens in `write()`: there, the last item replaces the previous ones.

This seems to be about web-apps, so it would be clearer to explicitly mention "Webapps supporting only a single ... should use the first ..." with a note that `write()` chooses the last item.

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

Message ID: <w3c/clipboard-apis/pull/158/review/854175588@github.com>