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

@mbrodesser requested changes on this pull request.

Will continue reviewing tomorrow.

> +     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.
+
+  </dl>
+
+  <h4 id="clipboard-item">Clipboard Item</h4>

This heading seems superfluous and "Clipboard Item" isn't a defined term. All information here would then belong to the current parent section "ClipboardItem interface".

> +  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=].
+  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 type=]s 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 {{ClipboardItem}} object has an associated <dfn for="ClipboardItem">clipboard item</dfn>, which is a [=/clipboard item=].
+
+  A {{ClipboardItem}} object has an associated <dfn for="ClipboardItem">types array</dfn>, which is a {{FrozenArray}}.

Why is this not part of `clipboard item`? `presentation style` is. Both should belong to the same, or is there something I'm overlooking?

Shouldn't it be a `FrozenArray<DOMString>`?

> +
+       1. If |v| is a {{DOMString}}, then follow the below steps:
+
+        1. Let |dataAsBytes| be the result of [=UTF-8 encoding=] |v|.
+
+        1. Let |blobData| be a {{Blob}} created using |dataAsBytes| with its {{Blob/type}} set to |mimeType|, [=serialize a MIME type|serialized=].
+
+        1. Resolve |p| with |blobData|.
+
+       1. If |v| is a {{Blob}}, then follow the below steps:
+
+        1. Resolve |p| with |v|.
+
+      1. If |representationDataPromise| was rejected, then:
+
+       1. [=Reject=] |p| with {{"NotFoundError"}} {{DOMException}} in |realm|.

In response to https://github.com/w3c/clipboard-apis/pull/158/#discussion_r777750170: it seems reasonable to add something like
```
Issue: web-developers might be interested in the underlying rejection reason.
```
Not more, to limit the scope of this review.

>    };
   </pre>
 
-  <div id="clipboard-idl" dfn-for="Clipboard">
+  The methods of the {{Clipboard}} interface take or return multiple {{ClipboardItem}} objects, and their specification is written to deal with the generic case. However, not all platforms support more than one [=/clipboard item=]; on such platforms, the algorithms below will ignore any {{ClipboardItem}} objects beyond the first one that are passed to {{Clipboard/write()}}, and {{Clipboard/read()}} and {{Clipboard/readText()}} will only ever return a single-item array.

`Some methods` is more accurate.
```, and their specification is written to deal with the generic case.``` could be dropped, it's redundant.

```
on such platforms, the algorithms below will ignore any {{ClipboardItem}} objects beyond the first one that are passed to {{Clipboard/write()}}, and {{Clipboard/read()}} and {{Clipboard/readText()}} will only ever return a single-item array.
```
isn't entirely true, please see https://github.com/w3c/clipboard-apis/pull/158#discussion_r786017821. The simplest fix would be to change the above cited text to a note with text like:
```
Some methods of the {{Clipboard}} interface take or return multiple {{ClipboardItem}} objects. However, not all platforms support more than one [=/clipboard item=]; on such platforms: `write()` writes all items in sequence, hence the last one replaces the previous ones.
```
The methods `read()` and `readText()` automatically behave correct, since there's only one ClipboardItem.

However, the algorithm of `readText()` needs to be corrected for the case when there are **multiple** clipboard items on the system clipboard, each containing a "text/plain" representation.



>    };
   </pre>
 
-  <div id="clipboard-idl" dfn-for="Clipboard">
+  The methods of the {{Clipboard}} interface take or return multiple {{ClipboardItem}} objects, and their specification is written to deal with the generic case. However, not all platforms support more than one [=/clipboard item=]; on such platforms, the algorithms below will ignore any {{ClipboardItem}} objects beyond the first one that are passed to {{Clipboard/write()}}, and {{Clipboard/read()}} and {{Clipboard/readText()}} will only ever return a single-item array.
+
+  A {{Clipboard}} object has an associated <dfn>clipboard</dfn>, which is a [=clipboard=].

This doesn't make sense the last "clipboard" again links to the `Clipboard` defined in the IDL. As that `clipboard` seems never used, presumably this sentence can be deleted.

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

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