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

@domenic commented on this pull request.

We need to straighten out the relationship between the JS/IDL `ClipboardItem` and the "conceptual" clipboard item as a first step; it's making it hard to understand the intent of much of the rest of the text.

>    <pre class="idl" data-highlight="webidl">
-  typedef sequence&lt;ClipboardItem> ClipboardItems;
+   typedef (DOMString or Blob) ClipboardItemDataType;

In the output, the indentation for this IDL block is all messy; see https://pr-preview.s3.amazonaws.com/w3c/clipboard-apis/pull/158.html#clipboard-item-interface.


I'd expect:

- Indenting stuff inside braces
- Lining up parameter declarations when a definition is split over multiple lines.
- Newline after `[SecureContext, Exposed=Window]`

> +  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 [=ClipboardItem=] should use the first [=ClipboardItem=].
+  Apps that support pasting more than one [=ClipboardItem=] could, for example, provide a user interface that previews the contents of each [=ClipboardItem=] and allow the user to choose which one to paste.
+  Further, apps are expected to enumerate the mime-types of the [=ClipboardItem=] 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 [=ClipboardItem=], e.g. “paste as image” or “paste formatted text”, etc.
+
+  A [=ClipboardItem=] contains multiple representations. Each representation consists of a MIME type and a corresponding {{DOMString}} or [=Blob=].
+
+  <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 corresponding to the MIME types, <var>options</var> can be used to fill its {{ClipboardItemOptions}},
+   as per the example below.
+
+   <pre class="example javascript">

Syntax highlighting doesn't appear to be working in the output at https://pr-preview.s3.amazonaws.com/w3c/clipboard-apis/pull/158.html#clipboard-item-interface ; I'm not sure why though as I'm not familiar with ReSpec.

>  
-  dictionary ClipboardItemOptions {
-    PresentationStyle presentationStyle = "unspecified";
+  </dl>
+  <p>
+   The <a constructor lt="ClipboardItem()">ClipboardItem</a> 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>

```suggestion
   The constructor 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>.
```

Also I think you need to mark this up as defining the constructor but I'm not sure how to do that in ReSpec.

>  
-  dictionary ClipboardItemOptions {
-    PresentationStyle presentationStyle = "unspecified";
+  </dl>
+  <p>
+   The <a constructor lt="ClipboardItem()">ClipboardItem</a> 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>
+
+  <h4 attribute for=ClipboardItem lt=presentationStyle>presentationStyle</h4>
+  <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>.

enumerated attribute only applies to content attributes, i.e. attributes of HTML elements.

IDL attributes need to be defined with getter/setter steps. I think you can just delete this sentence.

> -  dictionary ClipboardItemOptions {
-    PresentationStyle presentationStyle = "unspecified";
+  </dl>
+  <p>
+   The <a constructor lt="ClipboardItem()">ClipboardItem</a> 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>
+
+  <h4 attribute for=ClipboardItem lt=presentationStyle>presentationStyle</h4>
+  <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>.
+  
+  Note: {{ClipboardItem/presentationStyle}} 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>{{ClipboardItem/presentationStyle}} getter steps are to return [=this=]'s {{ClipboardItem/presentationStyle}}</p>

This definition is circular; it is returning itself.

You need to instead define an associated concept, and have the getter return that. E.g.

```html
Each {{ClipboardItem}} has a <dfn for="ClipboardItem">presentation style</dfn>, which is a {{PresentationStyle}}.

The <dfn attribute for="ClipboardItem">presentationStyle</dfn> getter steps are to return [=this=]'s [=ClipboardItem/presentation style=].
```

Then, somewhere else in the spec, you need to set a given ClipboardItem's `[=ClipboardItem/presentation style=]`.

>  
-    readonly attribute FrozenArray&lt;DOMString> types;
+   dictionary ClipboardItemOptions {
+   PresentationStyle presentationStyle = "unspecified";
+   };
+  </pre>
+  <p><dfn export for=ClipboardItem id=concept-clipboard-item>ClipboardItem</dfn></p>
+  A [=ClipboardItem=] is conceptually data that the user has expressed a desire to make shareable by invoking a "cut" or "copy" command.

So you seem to have introduced a separate "conceptual" `[=ClipboardItem=]`, which is not the same as a `{{ClipboardItem}}` IDL/JavaScript object. (Note: normally we would give these "conceptual" items names like "clipboard item", not "ClipboardItem".)

That can work, but you need to be explicit about the relationship. E.g., does each `{{ClipboardItem}}` have a `[=ClipboardItem=]` (which you might call `the {{ClipboardItem}}'s [=ClipboardItem/clipboard item=]?). That is what is done for things like `Response`'s response in https://fetch.spec.whatwg.org/#concept-response-response . Then you have to be very clear about what acts on the conceptual clipboard item, and what acts on the `{{ClipboardItem}}` object. E.g. below I suggest associating a "presentation style" with a `{{ClipboardItem}}`. But maybe it should instead be associated with the conceptual clipboard item, if it's something the OS cares about? Then the getter steps would do something like `Return [=this=]'s [=ClipboardItem/clipboard item=]'s [=clipboard item/presentation style=]`.

Or, you could try to directly store information on the `{{ClipboardItem}}` object. That is probably the more common approach, but it might get confusing when talking about the OS integration, since I assume operating systems don't directly deal with IDL/JS objects.

-- 
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-797927619