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

@mbrodesser requested changes on this pull request.

Thanks for working on this.

> @@ -621,8 +622,84 @@ urlPrefix: https://w3c.github.io/FileAPI/#dfn-; type: dfn;
   };
   </pre>
 
-  <div id="clipboard-idl" dfn-for="Clipboard">
+  <div class="algorithm" data-algorithm="clipboard-item">
+  <h4 id="h-clipboard-item"><dfn>ClipboardItem</dfn></h4>
+  The [=ClipboardItem=] object represents the content of the MIME types that are in the [=mandatory data types=] list, and are currently on the [=system clipboard=].

This suggests one `ClipboardItem` would suffice to include all data from the system clipboard. For some OSs, that's not true. E.g., macOS may include multiple items where each has multiple representations. See https://github.com/w3c/clipboard-apis/issues/93#issuecomment-853727779.

> @@ -621,8 +622,84 @@ urlPrefix: https://w3c.github.io/FileAPI/#dfn-; type: dfn;
   };
   </pre>
 
-  <div id="clipboard-idl" dfn-for="Clipboard">
+  <div class="algorithm" data-algorithm="clipboard-item">
+  <h4 id="h-clipboard-item"><dfn>ClipboardItem</dfn></h4>
+  The [=ClipboardItem=] object represents the content of the MIME types that are in the [=mandatory data types=] list, and are currently on the [=system clipboard=].
+  It has a mapping of the MIME types in {{DOMString}} format and a [=Blob=] corresponding to the MIME types that contains the actual payload. A web author needs to
+  create a [=ClipboardItem=] object in order to write content to the clipboard using the {{Clipboard/write()}} method. {{Clipboard/read()}} returns a [=ClipboardItem=] object

No, `read()` returns a promise to multiple `ClipboardItem`s.

> @@ -621,8 +622,84 @@ urlPrefix: https://w3c.github.io/FileAPI/#dfn-; type: dfn;
   };
   </pre>
 
-  <div id="clipboard-idl" dfn-for="Clipboard">
+  <div class="algorithm" data-algorithm="clipboard-item">
+  <h4 id="h-clipboard-item"><dfn>ClipboardItem</dfn></h4>
+  The [=ClipboardItem=] object represents the content of the MIME types that are in the [=mandatory data types=] list, and are currently on the [=system clipboard=].
+  It has a mapping of the MIME types in {{DOMString}} format and a [=Blob=] corresponding to the MIME types that contains the actual payload. A web author needs to
+  create a [=ClipboardItem=] object in order to write content to the clipboard using the {{Clipboard/write()}} method. {{Clipboard/read()}} returns a [=ClipboardItem=] object
+  that can be used to read a specific |type| using {{ClipboardItem/getType()}}.
+  </div>
+  <dl class=note>
+   <dt><code><var>clipboardItem</var> = new <a constructor lt="ClipboardItem()">ClipboardItem</a>([<var>items</var>, <var>options</var>])</code>

It would be really nice to incorporate the changes proposed in https://github.com/w3c/clipboard-apis/pull/127 too. Here, `items` would be renamed to `entries`. Can be done in a separate PR, though.

> -  <div id="clipboard-idl" dfn-for="Clipboard">
+  <div class="algorithm" data-algorithm="clipboard-item">
+  <h4 id="h-clipboard-item"><dfn>ClipboardItem</dfn></h4>
+  The [=ClipboardItem=] object represents the content of the MIME types that are in the [=mandatory data types=] list, and are currently on the [=system clipboard=].
+  It has a mapping of the MIME types in {{DOMString}} format and a [=Blob=] corresponding to the MIME types that contains the actual payload. A web author needs to
+  create a [=ClipboardItem=] object in order to write content to the clipboard using the {{Clipboard/write()}} method. {{Clipboard/read()}} returns a [=ClipboardItem=] object
+  that can be used to read a specific |type| using {{ClipboardItem/getType()}}.
+  </div>
+  <dl class=note>
+   <dt><code><var>clipboardItem</var> = new <a constructor lt="ClipboardItem()">ClipboardItem</a>([<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 corresponding to the MIME types, <var>options</var> can be used to fill its {{ClipboardItemOptions}},
+   as per the example below.
+
+   <div class=example id=example-clipboard-item-class>
+   <pre><code class=lang-javascript>

The line breaks are not respected, making the example harder to read. `<pre class="example javascript">` could work.

> +    {options: "unspecified"});
+   </code></pre>
+   </div>
+
+   <dt><code><var>clipboardItem</var> . <a method for=ClipboardItem lt=getType()>getType</a>(<var>type</var>)</code>
+   <dd><p>Returns a  [=Promise=] to the [=Blob=] corresponding to the <var>type</var>.</p>
+
+   <dt><code><var>types</var> of <var>clipboardItem</var></code>
+   <dd><p>Returns the list of <var>types</var> contained in the <var>clipboardItem</var> object.
+
+  </dl>
+  <p>
+   The {{ClipboardItem/constructor()}} step for <code>new ClipboardItem(<var>items</var>, <var>options</var>)</code> is to set [=this=]'s items to <var>items</var> and options to <var>options</var>
+  </p>
+
+  <dfn>ClipboardItemDataType</dfn>

The change proposed in https://github.com/w3c/clipboard-apis/pull/127 would add clarity. Can be done in a separate PR.

> +   <dd><p>Returns a  [=Promise=] to the [=Blob=] corresponding to the <var>type</var>.</p>
+
+   <dt><code><var>types</var> of <var>clipboardItem</var></code>
+   <dd><p>Returns the list of <var>types</var> contained in the <var>clipboardItem</var> object.
+
+  </dl>
+  <p>
+   The {{ClipboardItem/constructor()}} step for <code>new ClipboardItem(<var>items</var>, <var>options</var>)</code> is to set [=this=]'s items to <var>items</var> and options to <var>options</var>
+  </p>
+
+  <dfn>ClipboardItemDataType</dfn>
+  <p>
+   A {{DOMString}} or [=Blob=] type. This contains the payload corresponding to the MIME type while creating a {{ClipboardItem}} object.
+  </p>
+
+  <dfn>ClipboardItemData</dfn>

Same here. The change proposed in https://github.com/w3c/clipboard-apis/pull/127 would add clarity.

> +  <p>
+   A [=Promise=] to the [=ClipboardItemDataType=].
+  </p>
+
+  {{ClipboardItem}}
+  <p> A {{ClipboardItem}} object contains the {{ClipboardItem/types}} listed in the [=mandatory data types=] list that are present on the [=system clipboard=].
+  <p> The {{ClipboardItem/constructor()}} step for <code>new ClipboardItem(<var>items</var>, <var>options</var>)</code>
+  is to set [=this=]'s items to <var>items</var> and options to <var>options</var>
+  </p>
+
+  Issue: Add definition to clarify what {{ClipboardItem/createDelayed()}} method does. From the discussions it looks like a Windows/Mac only feature where the
+  platform supports writing of the data to the system clipboard in a delayed fashion so the system clipboard can request data on-demand.
+  See https://docs.microsoft.com/en-us/windows/win32/dataxchg/clipboard-operations#delayed-rendering
+
+  <dfn>presentationStyle</dfn>
+  <p>It is an <a href=https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#enumerated-attribute>enumerated attribute</a> whose keywords are the <code>string</code>, <code>unspecified</code>, <code>inline</code> and <code>attachment</code>.</p>

I don't understand the purpose of `presentationStyle`. Perhaps it's just me, or an example could help.

> @@ -701,11 +784,20 @@ urlPrefix: https://w3c.github.io/FileAPI/#dfn-; type: dfn;
 
     1. If |r| is not "granted", then reject |p| with a "NotAllowedError" DOMException
 
-    1. Let |cleanItemList| be an empty sequence&lt;{{Blob}}>.
+    1. Let |itemList| and |cleanItemList| be an empty sequence&lt;{{Blob}}>.
+
+    1. For each |item| in |data|:

`data` is of type `ClipboardItems` (plural). So `item` is of type `ClipboardItem`. It seems the data-algorithm defined here would need to iterate over the types.

-- 
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#pullrequestreview-773711332