Add clipboard IDL description. #158

snianu · 2021-10-05T01:53:58Z

Closes #135

For normative changes, the following tasks have been completed:

Modified Web platform tests (link to pull request)

Implementation commitment:

WebKit Shipped
Chromium Shipped
Gecko (https://bugzilla.mozilla.org/show_bug.cgi?id=1619947)

Preview | Diff

annevk

I'm afraid this isn't really what is needed here.

I recommend looking at something like https://fetch.spec.whatwg.org/#headers-class to see what it takes to define a class.

index.bs

annevk · 2021-10-07T08:24:57Z

It's a bit hard to review and it seems some of the syntax might be incorrect as well as the items in the IDL are still not linked: https://pr-preview.s3.amazonaws.com/w3c/clipboard-apis/pull/158.html#clipboard-interface. E.g., you cannot click on constructor or the individual members.

For presentationStyle it's unclear what actually sets it.

types references the mandatory types, but is that accurate when someone created the ClipboardItem themselves? Seems unlikely?

I think you still need to flush out the data model better and then have various places that create these instances (either the system or the developer through the constructor).

index.bs

mbrodesser

Thanks for working on this.

index.bs

snianu · 2021-10-14T01:41:06Z

@mbrodesser Addressed all comments. PTAL. Thanks!

mbrodesser

Thanks for continuing working on this. It's going in the right direction.

index.bs

mbrodesser · 2021-10-14T08:51:46Z

index.bs

+		<p><dfn export for=ClipboardItem id=concept-clipboard-item>ClipboardItem</dfn></p>
+		The [=ClipboardItem=] object has MIME types that are in the {{ClipboardItem/types}} list, and [=Blob=]s corresponding to the {{ClipboardItem/types}}.
+		It has a mapping of the MIME types in {{DOMString}} format and a [=Blob=] corresponding to the MIME types that contains the actual payload.
+		There can be multiple [=ClipboardItem=]s as each [=ClipboardItem=] represents contents of a clipboard, and there can be multiple clipboards supported on a platform such as iOS/iPadOS.


Since this is about multiple ClipboardItems, that information seems to belong to the "Clipboard Interface" section (7.3, currently).

Moreover, the wording is not entirely accurate. On iOS, "multiple clipboards" (it seems "multiple clipboard items" is more accurate) seem to mean something different than multiple clipboards on Linux.
On the former, multiple clipboard items may belong to the same group of user-selected items, see #93 (comment).
On the latter, the multiple clipboards don't necessarily correspond to the same user selection. E.g., when pressing Ctrl+c, one clipboard is filled, and when selecting text with the mouse, another clipboard [readable by clicking the middle mouse button] is filled.
The intention of multiple clipboard items is to cover the iOS case, but exclude the Linux case.

I'm not very familiar with macOS, but from this article, it looks like we could create multiple pasteboards using the create methods defined in Creating and Releasing a Pasteboard section. For each pasteboard, we could add multiple pasteboard items using NSPasteboardType. In Chromium we only use the generalPasteboard to read/write a single Clipboarditem. So, I think multiple clipboards is applicable to both Linux and macOS.

it looks like we could create multiple pasteboards using the create methods defined in Creating and Releasing a Pasteboard section.

Yes, interface-wise, that seems possible. However, that seems to not match the use case described at #93 (comment).

For each pasteboard, we could add multiple pasteboard items using NSPasteboardType.

As mentioned above, that doesn't match the above mentioned use case. A NSPasteBoard may contain multiple pasteboard items, see https://developer.apple.com/documentation/appkit/nspasteboard/1529995-pasteboarditems?language=objc. That seems to match the use case. @rniwa

So, I think multiple clipboards is applicable to both Linux and macOS.

Apple's above mentioned use case wouldn't work on Linux, because there, a clipboard may contain only at most one item with multiple representations.

index.bs

snianu · 2021-11-03T01:43:49Z

@mbrodesser Addressed all comments. PTAL. Thanks!

domenic

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.

index.bs

domenic · 2021-11-04T15:57:36Z

index.bs

+			};
+		</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.

Added [=clipboard item=] and its relationship with {{ClipboardItem}}.

snianu · 2021-11-05T00:31:25Z

@domenic Addressed your comment. PTAL. Thanks!

mbrodesser · 2021-11-05T13:10:17Z

@domenic

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.

Out of interest, is there an alternative to defining a "conceptual" clipboard item and a corresponding JS object?

domenic · 2021-11-05T13:34:51Z

Yes, I mentioned the alternative in the next paragraph:

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.

mbrodesser · 2021-11-05T13:37:04Z

Yes, I mentioned the alternative in the next paragraph:

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.

Sorry, should've read the whole text. Thanks.

mbrodesser

Thanks for working on this.

I've only reviewed the first paragraphs, will try to find more time next week.

index.bs

mbrodesser · 2021-11-05T13:31:28Z

index.bs

+		</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=].


Since this is about multiple clipboard items, it seems to belong to section 7.3.1. ClipboardItems.

index.bs

domenic

I got further this time. Let's try to get ClipboardItem solid and then we can tackle Clipboard itself... I suspect the hardest part will be getType().

In general I'd encourage you to adopt the mindset: if I knew nothing about the current implementation of this in Chromium, could I read this spec from top to bottom and implement the result from scratch, in a way that behaves identical to the Chromium implementation? That's the bar we need to meet; see e.g. the specifications section of the Blink values in Practice document.

index.bs

domenic · 2021-11-05T20:52:02Z

index.bs

+			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>.


So, you have defined a ClipboardItem to have exactly one associated value: its "clipboard item". You have not defined that it has associated "items" or "options", so you cannot set those on it.

I believe you want to instead do something like the following:

Set this's clipboard item to a new clipboard item.

Set this's clipboard item's presentation style to options["presentationStyle"].

??? do something with items to store them somewhere ???

Step 3 is tricky because I don't know how to map a record<DOMString, ClipboardItemData> into any other concepts defined in this spec. A guess might be that each clipboard item has representations, which is a map from MIME types to ClipboardItemData values. (If so, that should be stated and defined in the section on "clipboard item".) Then you would do something like the following:

For each (key, value) of items:

Let mimeType be the result of parsing a MIME type given key.

If mimeType is failure, then throw a TypeError.

Set this's clipboard item's representations[mimeType] to value.

but there are variants, e.g.: maybe you don't want to parse the MIME types and will accept any random string; maybe you want to unwrap the promises instead of storing them internally so that later, when you get the data, you don't have to wait for the promise; etc.

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

index.bs

domenic · 2021-11-05T20:58:35Z

index.bs

+
+		</dl>
+		<p>
+			A {{ClipboardItem}} object has an associated [=clipboard item=].


This is on the right track, but you should have separate <dfn>s: one for the "clipboard item" type (what you have), and one for the "ClipboardItem's clipboard item" (which you don't have). Something like

A {{ClipboardItem}} object has an associated <dfn for="ClipboardItem">clipboard item</dfn>, which is a [=clipboard item=]

Then, you can reference this field elsewhere using the syntax like [=this=]'s [=ClipboardItem/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>

index.bs

mbrodesser · 2021-11-08T10:13:09Z

I got further this time. Let's try to get ClipboardItem solid and then we can tackle Clipboard itself... I suspect the hardest part will be getType().

In general I'd encourage you to adopt the mindset: if I knew nothing about the current implementation of this in Chromium, could I read this spec from top to bottom and implement the result from scratch, in a way that behaves identical to the Chromium implementation? That's the bar we need to meet; see e.g. the specifications section of the Blink values in Practice document.

Thanks for your review. I'll wait with another round of reviewing until your comments have been addressed.

snianu · 2021-11-11T02:30:56Z

@domenic Addressed all your comments. PTAL.

mbrodesser

@snianu thanks for the changes.

index.bs

mbrodesser · 2021-11-11T10:27:14Z

index.bs

+		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.


This information about multiple clipboard items seems to belong to the section "Clipboard Interface". This section explains one clipboard item.

So, this is just a statement about usage of ClipboardItem/ClipboardItems that is part of the processing model. I also mentioned this in the Clipboard Interface section, but added it here as well for completeness.

So, this is just a statement about usage of ClipboardItem/ClipboardItems that is part of the processing model.

It's an example, it doesn't define the processing model.

The core part of the sentence is that there could be more than one clipboard item which is relevant to the conceptual clipboard item object. The example is just a way to describe how one can use multiple clipboard items.

The core part of the sentence is that there could be more than one clipboard item which is relevant to the conceptual clipboard item object.

Why is that relevant? There can be multiple clipboard item instances, but that doesn't affect the definition of the conceptual clipboard item.
The example itself is helpful. I think it would just be better placed in a note of the Clipboard interface, as mentioned above. Maybe I'm completely misunderstanding something...

I don't think that particular sentence is related to definition of clipboard item. It just talks about how one can use multiple clipboard item objects. I don't really have a strong opinion so I can change it if others feel the same way.

index.bs

mbrodesser · 2021-11-11T11:11:43Z

index.bs

+		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 [=ClipboardItem/clipboard item=], which is a [=clipboard item=].


I still haven't grasped clearly how this part of a spec should ideally look like. Shouldn't it be:

JS/IDL interface.

Algorithms defining the JS/IDL methods.

Notes for the methods.

Notes for the other members (enums, typedefs, ...).

Documentation for the JS/IDL interface, including use cases for app- and web-devs.

Would be glad if someone could shed light on this.

CC @domenic

Suggested change

A {{ClipboardItem}} object has an associated [=ClipboardItem/clipboard item=], which is a [=clipboard item=].

A {{ClipboardItem}} object has an associated <dfn for="ClipboardItem">clipboard item</dfn>, which is a [=clipboard item=].

I still haven't grasped clearly how this part of a spec should ideally look like. Shouldn't it be:

I think we're on the right track. I would say:

IDL block

(Optional, but recommended:) A web-developer-facing note explaining the APIs. (You already have this, although I think you moved it down to the bottom now which is not what I would recommend.)

Definitions of concepts associated with the ClipboardItem interface, e.g. its clipboard item (this line that we're commenting on) or useful algorithms

Method steps for each operation, and getter/setter steps for each attribute

I don't think there's a need for notes on enums and typedefs, as web developers don't need to know about them (they're not first-class concepts) and for implementers they're pretty self-explanatory.

@domenic thanks for sharing your thoughts.

mbrodesser · 2021-11-11T13:17:20Z

index.bs

+
+		A {{ClipboardItem}} object has an associated [=ClipboardItem/clipboard item=], which is a [=clipboard item=].
+
+		To create a {{ClipboardItem}} object, given a [=clipboard item=] |clipboardItem|'s [=relevant realm=] |realm|, run these steps:


Can someone please explain why this requires a realm?

Any object creation requires a realm; e.g. creating an object in the realm of window is different from creating it in the realm of frames[0].

However I'm unsure what this algorithm is used for. It doesn't have a <dfn>, so nothing else in the spec can reference it. Are you planning to use it later?

Added a dfn. This is used in read().

mbrodesser · 2021-11-11T13:46:47Z

index.bs

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


This would've to be aligned with the remainder of the text, but it seems this belongs to an "Example" box, like there are some at https://url.spec.whatwg.org/#url-class.

In general, using such boxes and boxes for "Note"s would add more structure to the spec.

So, here I'm describing the conceptual clipboard item object's model. This is not relevant to web developers so not sure if this belongs to an Example section.

So, here I'm describing the conceptual clipboard item object's model. This is not relevant to web developers so not sure if this belongs to an Example section.

For the general understanding of web developers about the async clipboard API, it seems relevant, see also #158 (comment).

I suggest moving most of the prose of this section, including

"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 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 items. 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."

to a note (https://respec.org/docs/#note) of the Clipboard (not ClipboardItem) interface.

The text

"A clipboard item has a list of representations, each representation with an associated mime type and data. 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). Each of these mime types 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. 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.

A clipboard item can also optionally have a presentation style 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."

would be better placed as a note of the ClipboardIteminterface.

This section should then only contain the definition of the conceptual clipboard item and the definition of the constructor.

would be better placed as a note of the ClipboardIteminterface.

I disagree? That text is defining the structure of the conceptual clipboard item, which seems pretty important. It shouldn't be a note (since notes are non-normative), and it's only indirectly related to the ClipboardItem interface (since a ClipboardItem contains a conceptual clipboard item).

Similarly the first paragraph you mention,

to a note (https://respec.org/docs/#note) of the Clipboard (not ClipboardItem) interface.

should not be a note. I don't know why it would be more related to Clipboard than ClipboardItem, either...

would be better placed as a note of the ClipboardIteminterface.

I disagree? That text is defining the structure of the conceptual clipboard item, which seems pretty important. It shouldn't be a note (since notes are non-normative), and it's only indirectly related to the ClipboardItem interface (since a ClipboardItem contains a conceptual clipboard item).

Thanks for the comment. I didn't express myself clearly, sorry. I suggest separating the examples and the definition of the clipboard item concept. Wouldn't the examples be better located in a note of the ClipboardItem interface, intended for web-developers?

Similarly the first paragraph you mention,

to a note (https://respec.org/docs/#note) of the Clipboard (not ClipboardItem) interface.

should not be a note. I don't know why it would be more related to Clipboard than ClipboardItem, either...

It's about the level of abstraction of the examples: the examples for web-developers about multiple clipboard items should belong to the Clipboard interface, because only that exposes multiple items. The examples for one clipboard item should belong to the ClipboardItem interface.

WDYT? My understanding of the distinction between the conceptual clipboard item and ClipboardItem might still be wrong.

mbrodesser · 2021-11-11T13:53:42Z

index.bs

+		<a constructor lt="ClipboardItem()">constructor</a> steps for <code>new ClipboardItem(<var>items</var>, <var>options</var>)</code> are:
+			1. Set [=this=]'s [=ClipboardItem/clipboard item=] to a new [=clipboard item=].
+
+			1. If |options| is empty, then set [=this=]'s [=ClipboardItem/clipboard item=]'s [=presentation style=] to "unspecified", else, set [=this=]'s [=ClipboardItem/clipboard item=]'s [=presentation style=] to |options|["presentationStyle"].


Is the formatting of "|options|["presentationStyle"]" correct?

The formatting is correct, although at least in Bikeshed you can do |options|["{{ClipboardItemOptions/presentationStyle}}"] to get some extra nice cross-linking. It's worth trying to see if that works in ReSpec too.

Other issue: Options will never be empty, because it defaults to {}, and the presentationStyle member defaults to "unspecified", in the IDL. In other words, this is all taken care of in the IDL block. So you can just simplify this step to:

Set this's clipboard item's presentation style to options["presentationStyle"].

index.bs

domenic

Much better now, awesome!

I started to move on a bit to the Clipboard algorithms, just doing read() for now. Some of the things I commented on there are probably generalizable to readText() as well. (And maybe write() and writeText().)

domenic · 2021-11-11T20:54:41Z

index.bs

+		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 [=ClipboardItem/clipboard item=], which is a [=clipboard item=].


Suggested change

A {{ClipboardItem}} object has an associated [=ClipboardItem/clipboard item=], which is a [=clipboard item=].

A {{ClipboardItem}} object has an associated <dfn for="ClipboardItem">clipboard item</dfn>, which is a [=clipboard item=].

I still haven't grasped clearly how this part of a spec should ideally look like. Shouldn't it be:

I think we're on the right track. I would say:

IDL block

(Optional, but recommended:) A web-developer-facing note explaining the APIs. (You already have this, although I think you moved it down to the bottom now which is not what I would recommend.)

Definitions of concepts associated with the ClipboardItem interface, e.g. its clipboard item (this line that we're commenting on) or useful algorithms

Method steps for each operation, and getter/setter steps for each attribute

I don't think there's a need for notes on enums and typedefs, as web developers don't need to know about them (they're not first-class concepts) and for implementers they're pretty self-explanatory.

domenic · 2021-11-11T20:55:34Z

index.bs

+
+		A {{ClipboardItem}} object has an associated [=ClipboardItem/clipboard item=], which is a [=clipboard item=].
+
+		To create a {{ClipboardItem}} object, given a [=clipboard item=] |clipboardItem|'s [=relevant realm=] |realm|, run these steps:


Any object creation requires a realm; e.g. creating an object in the realm of window is different from creating it in the realm of frames[0].

However I'm unsure what this algorithm is used for. It doesn't have a <dfn>, so nothing else in the spec can reference it. Are you planning to use it later?

domenic · 2021-11-11T20:56:35Z

index.bs

+
+			1. Set |clipboardItemObject|'s [=clipboard item=] to |clipboardItem|.
+
+		<a constructor lt="ClipboardItem()">constructor</a> steps for <code>new ClipboardItem(<var>items</var>, <var>options</var>)</code> are:


I believe the correct markup here is something like

Suggested change

<a constructor lt="ClipboardItem()">constructor</a> steps for <code>new ClipboardItem(<var>items</var>, <var>options</var>)</code> are:

The <dfn lt="ClipboardItem()"><code>new ClipboardItem(<var>items</var>, <var>options</var>)</code></dfn> constructor steps are:

although I don't know very much about ReSpec so I might be off.

hm doesn't work for some reason.

domenic · 2021-11-11T20:58:48Z

index.bs

+		<a constructor lt="ClipboardItem()">constructor</a> steps for <code>new ClipboardItem(<var>items</var>, <var>options</var>)</code> are:
+			1. Set [=this=]'s [=ClipboardItem/clipboard item=] to a new [=clipboard item=].
+
+			1. If |options| is empty, then set [=this=]'s [=ClipboardItem/clipboard item=]'s [=presentation style=] to "unspecified", else, set [=this=]'s [=ClipboardItem/clipboard item=]'s [=presentation style=] to |options|["presentationStyle"].


The formatting is correct, although at least in Bikeshed you can do |options|["{{ClipboardItemOptions/presentationStyle}}"] to get some extra nice cross-linking. It's worth trying to see if that works in ReSpec too.

Other issue: Options will never be empty, because it defaults to {}, and the presentationStyle member defaults to "unspecified", in the IDL. In other words, this is all taken care of in the IDL block. So you can just simplify this step to:

Set this's clipboard item's presentation style to options["presentationStyle"].

index.bs

domenic · 2021-11-11T21:05:01Z

index.bs

+
+			1. Let |itemTypeList| be [=this=]'s [=ClipboardItem/clipboard item=]'s [=list of representations=].
+
+			1. If |mimeType| is not present in |itemTypeList|'s [=representation=]'s [=mime type=], then [=a promise rejected with=] {{"NotFoundError"}} DOMException in |realm|.


These steps need to be a bit more algorithmic. I suggest an explicit loop: something like

For each |representation| in |itemTypeList|:

If |representation|'s [=mime type=] is |mimeType|, then:

... do the stuff to return the promise, using |representation|'s [=data=].

Return a promise rejected with a "NotFoundError" DOMException.

Note the difference between my suggestion using a variable |representation|, introduced by the for loop, versus what you have here, which uses the spec type [=representation=]. You can't meaningfully get a specific value out of a type; you need an instance of the type.

index.bs

snianu · 2021-11-16T19:36:39Z

@domenic @mbrodesser Thanks for all the feedback! Addressed your comments. PTAL.

index.bs

domenic · 2021-11-18T18:02:37Z

index.bs


-				1. If |r| is not "granted", then reject |p| with a "NotAllowedError" DOMException
+				1. [=queue a global task=] on the [=permission task source=], given |realm|'s [=Realm/global object=], to perform the below steps:


It would be cleaner to only queue the task if r is not "granted".

Also, in this case you probably do not want to perform the following steps, so you need to abort these steps.

Here and elsewhere, don't forget to capitalize the first word in the sentence ("Queue").

index.bs

domenic · 2021-11-18T18:06:48Z

index.bs

+
+					1. For each |clipboardItem| in |data|:
+
+						1. For each |item| in |clipboardItem|:


Here |clipboardItem| is a {{ClipboardItem}}, not a list. So you cannot loop over it.

Maybe you want to loop over |clipboardItem|'s [=ClipboardItem/clipboard item=]'s [=list of representations=]? But that doesn't make much sense because there's no promises in the list of representations... I'm not sure what you're trying to do here.

|clipboardItem| here is {{ClipboardItem}}, but the |data| is a {{ClipboardItems}} defined in Clipboard Interface webidl.

So, during write() I want to access the Blob or DOMString data (depending on what the authors provided in ClipboardItemData) after all the promises to Blobs or DOMString are resolved. ClipboardItemData is the type that has promise to ClipboardItemDataType. I guess this will be part of the ClipboardItem constructor so I can maybe assume that the promises are resolved and the Blob data is already present? That way I can just access the |clipboardItem|'s [=ClipboardItem/clipboard item=]'s [=list of representations=]?

Oh, I see, I think I misread the spec. A representation's data will be a promise, after all; the constructor step 4.5 sets it to |value|, which is a promise.

So yes, you should access |clipboardItem|'s [=ClipboardItem/clipboard item=]'s [=list of representations=]. But then for each representation, you need to "unwrap" its data. To do that, probably the best thing to do is use https://webidl.spec.whatwg.org/#dfn-perform-steps-once-promise-is-settled

index.bs

mbrodesser · 2021-11-19T10:21:02Z

@domenic @mbrodesser Thanks for all the feedback! Addressed your comments. PTAL.

@snianu thanks for the update. Just had a brief look at it and it appears to be structured more clearly. Will have a closer look next week.

mbrodesser · 2021-11-29T09:52:13Z

@domenic @mbrodesser Thanks for all the feedback! Addressed your comments. PTAL.

@snianu thanks for the update. Just had a brief look at it and it appears to be structured more clearly. Will have a closer look next week.

@snianu just FYI I'm not working a fraction of perhaps the whole week, so feedback might be more delayed, sorry.

snianu · 2021-11-29T18:32:45Z

@domenic Addressed your comments. PTAL. Thanks!

mbrodesser · 2022-01-26T11:54:29Z

index.bs

+
+				On Windows, follow the convention described below:
+
+				1. Assign "PNG" to |wellKnownFormat|.


Is "PNG" the correct type? It's not included in https://docs.microsoft.com/en-us/windows/win32/dataxchg/standard-clipboard-formats#constants.

In Chromium we use either "PNG" or CF_DIBV5. Not sure about other browsers.

snianu · 2022-02-02T18:53:01Z

@mbrodesser I think I have addressed most of the issues in this PR. I know it has some "undefined behavior" in the algorithms, but without consensus from other implementers, I don't think I can add anything there. Moreover, it's not entirely related to async APIs since DataTransfer has similar issues as well related to sanitization. Can we at least merge these changes and open separate PR to address specific issues? I don't have much bandwidth to work on this PR since I'll be working on other projects and I don't want to put this PR on hold for long. This is a major improvement to the existing spec so let us merge these changes first. @BoCupp-Microsoft @whsieh FYI.

mbrodesser

@snianu

I agree that this PR clearly improves the state of the spec. Thanks for all the work so far.

Moreover, there's precedent that other, valuable, but significantly smaller PRs have been stuck (e.g. #127). Therefore, it seems reasonable to merge this PR if its content is without contradictions and all remaining open issues have been identified and clearly marked as such.

When the changes requested from this review iteration are incorporated, I'd approve this PR. The identified, remaining issues can then be dealt with separately.

@domenic: since you significantly contributed to this PR, your additional feedback would be appreciated.

index.bs

snianu · 2022-02-15T01:48:21Z

@mbrodesser Addressed all comments. PTAL.

mbrodesser

@snianu thanks for incorporating the previous feedback.

PTAL again. When the proposed changes are addressed, I'll approve the PR without reading the whole async clipboard spec again.

index.bs

snianu · 2022-03-01T22:10:38Z

@mbrodesser Sorry for the delay. I've been busy on other projects so couldn't address your comments in time. PTAL and let me know if you have any concerns. Thanks!

index.bs

mbrodesser

@snianu thanks for incorporating the feedback. Ready to approve when the two new comments are addressed.

mbrodesser · 2022-03-02T11:50:58Z

index.bs

+
+					1. For each [=/clipboard item=] |underlyingItem| of |data|:
+
+						1. Let |item| be the result of running the steps of [=create a ClipboardItem object=] given |underlyingItem|.


create a ClipboardItem object requires a Realm too.

CC @domenic

Yes, I think we can use the current |realm| here.

mbrodesser

Thanks for the work so far, @snianu.

snianu · 2022-03-03T17:05:05Z

@mbrodesser Thank you for your patience and thorough review! I can't merge this PR since it's blocked on approval from someone who has write access. Adding @BoCupp-Microsoft for additional +1.

snianu · 2022-03-03T17:13:52Z

@domenic Thank you for reviewing this PR and helping me understand some of the intricacies of the spec language :) I'm planning to create another PR where I'll add the custom format support and also define the sanitization step (which will probably be same as DataTransfer APIs, so basically no sanitization). I want to merge this PR first so the diff is small and its easier to review. Please let me know if you have any concerns.

domenic · 2022-03-03T17:26:56Z

No concerns; I agree the PR has gotten quite long and merging it so we have a more solid basis going forward is a good idea :)

martinthomson · 2023-03-20T21:56:04Z

index.bs

+				readonly attribute PresentationStyle presentationStyle;
+				readonly attribute FrozenArray&lt;DOMString> types;
+
+				Promise&lt;Blob&gt; getType(DOMString type);


This name isn't ideal. You aren't getting a type, you are getting the item... by type. get() might have been better.

Yeah, this method isn't returning a type -- It's returning a promise to the content (in the form of Blob) of that type. I can't change the IDL unfortunately since both WebKit and Chromium have already shipped this API. This PR was made to clarify the algorithms and interfaces that have been shipped already.

annevk reviewed Oct 5, 2021

View reviewed changes

index.bs Show resolved Hide resolved

index.bs Outdated Show resolved Hide resolved

snianu requested review from BoCupp-Microsoft and mkruisselbrink October 6, 2021 06:54

mbrodesser reviewed Oct 7, 2021

View reviewed changes

index.bs Outdated Show resolved Hide resolved

mbrodesser suggested changes Oct 7, 2021

View reviewed changes

snianu mentioned this pull request Oct 8, 2021

What is PresentationStyle? #159

Closed

mbrodesser suggested changes Oct 14, 2021

View reviewed changes

snianu mentioned this pull request Nov 1, 2021

Should we remove lastModified, ClipboardItemDelayedCallback, createDelayed and delayed? #160

Closed

domenic reviewed Nov 4, 2021

View reviewed changes

mbrodesser suggested changes Nov 5, 2021

View reviewed changes

domenic reviewed Nov 5, 2021

View reviewed changes

mbrodesser reviewed Nov 11, 2021

View reviewed changes

domenic reviewed Nov 11, 2021

View reviewed changes

css-meeting-bot mentioned this pull request Nov 12, 2021

Make async clipboard APIs (read/write) to sanitize interoperably with setData/getData for text/html #150

Closed

domenic reviewed Nov 18, 2021

View reviewed changes

index.bs Outdated Show resolved Hide resolved

annevk mentioned this pull request Nov 19, 2021

Add Custom Clipboard format support to async clipboard. #162

Closed

4 tasks

snianu mentioned this pull request Jan 24, 2022

Remove clipboard-write permission #164

Open

4 tasks

mbrodesser reviewed Jan 26, 2022

View reviewed changes

mbrodesser mentioned this pull request Jan 31, 2022

What should clipboard.readText() return when the clipboard contains multiple clipboard items? #166

Open

snianu added 2 commits February 1, 2022 15:26

Address comments.

5ab3eab

Address comments.

4f9b71c

snianu mentioned this pull request Feb 3, 2022

Should clipboard.writeText() replace \n characters with \r\n on Windows? #168

Closed

mbrodesser suggested changes Feb 4, 2022

View reviewed changes

Address comments.

9694d17

mbrodesser mentioned this pull request Feb 14, 2022

ClipboardItem constructor should throw when items are empty #169

Closed

Address comments.

fd317ba

snianu mentioned this pull request Feb 15, 2022

Arbitrary clipboard types #165

Closed

mbrodesser suggested changes Feb 21, 2022

View reviewed changes

index.bs Outdated Show resolved Hide resolved

index.bs Outdated Show resolved Hide resolved

index.bs Outdated Show resolved Hide resolved

index.bs Show resolved Hide resolved

index.bs Show resolved Hide resolved

Address PR comments.

02c7b2b

mbrodesser reviewed Mar 2, 2022

View reviewed changes

index.bs Outdated Show resolved Hide resolved

mbrodesser suggested changes Mar 2, 2022

View reviewed changes

Address comment.

0ab5153

mbrodesser approved these changes Mar 3, 2022

View reviewed changes

BoCupp-Microsoft approved these changes Mar 8, 2022

View reviewed changes

snianu merged commit acaa52d into main Mar 8, 2022

This was referenced Mar 8, 2022

Fix spec errors due to invalid markup. #172

Merged

What does ClipboardItem.getType do #119

Closed

EdgarChen mentioned this pull request Mar 9, 2023

Clipboard API mozilla/standards-positions#89

Closed

martinthomson reviewed Mar 20, 2023

View reviewed changes

saschanaz deleted the idl-desc branch August 1, 2024 15:07

		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.

	A {{ClipboardItem}} object has an associated [=ClipboardItem/clipboard item=], which is a [=clipboard item=].
	A {{ClipboardItem}} object has an associated <dfn for="ClipboardItem">clipboard item</dfn>, which is a [=clipboard item=].


		A {{ClipboardItem}} object has an associated [=ClipboardItem/clipboard item=], which is a [=clipboard item=].

		To create a {{ClipboardItem}} object, given a [=clipboard item=] \|clipboardItem\|'s [=relevant realm=] \|realm\|, run these steps:


		1. Set \|clipboardItemObject\|'s [=clipboard item=] to \|clipboardItem\|.

		<a constructor lt="ClipboardItem()">constructor</a> steps for <code>new ClipboardItem(<var>items</var>, <var>options</var>)</code> are:

	<a constructor lt="ClipboardItem()">constructor</a> steps for <code>new ClipboardItem(<var>items</var>, <var>options</var>)</code> are:
	The <dfn lt="ClipboardItem()"><code>new ClipboardItem(<var>items</var>, <var>options</var>)</code></dfn> constructor steps are:


		1. Let \|itemTypeList\| be [=this=]'s [=ClipboardItem/clipboard item=]'s [=list of representations=].

		1. If \|mimeType\| is not present in \|itemTypeList\|'s [=representation=]'s [=mime type=], then [=a promise rejected with=] {{"NotFoundError"}} DOMException in \|realm\|.


		1. If \|r\| is not "granted", then reject \|p\| with a "NotAllowedError" DOMException
		1. [=queue a global task=] on the [=permission task source=], given \|realm\|'s [=Realm/global object=], to perform the below steps:


		1. For each \|clipboardItem\| in \|data\|:

		1. For each \|item\| in \|clipboardItem\|:


		On Windows, follow the convention described below:

		1. Assign "PNG" to \|wellKnownFormat\|.


		1. For each [=/clipboard item=] \|underlyingItem\| of \|data\|:

		1. Let \|item\| be the result of running the steps of [=create a ClipboardItem object=] given \|underlyingItem\|.

Add clipboard IDL description. #158

Add clipboard IDL description. #158

Conversation

snianu commented Oct 5, 2021 • edited by pr-preview bot Loading

annevk left a comment

Choose a reason for hiding this comment

annevk commented Oct 7, 2021

mbrodesser left a comment

Choose a reason for hiding this comment

snianu commented Oct 14, 2021

mbrodesser left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

snianu commented Nov 3, 2021

domenic left a comment

Choose a reason for hiding this comment

domenic Nov 4, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

snianu commented Nov 5, 2021

mbrodesser commented Nov 5, 2021

domenic commented Nov 5, 2021

mbrodesser commented Nov 5, 2021

mbrodesser left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

domenic left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mbrodesser commented Nov 8, 2021

snianu commented Nov 11, 2021

mbrodesser left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mbrodesser Nov 15, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mbrodesser Nov 15, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

domenic left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

snianu commented Nov 16, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

snianu Nov 19, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mbrodesser commented Nov 19, 2021

mbrodesser commented Nov 29, 2021

snianu commented Nov 29, 2021

snianu commented Oct 5, 2021 •

edited by pr-preview bot

Loading

domenic Nov 4, 2021 •

edited

Loading

mbrodesser Nov 15, 2021 •

edited

Loading

mbrodesser Nov 15, 2021 •

edited

Loading

snianu Nov 19, 2021 •

edited

Loading

snianu commented Mar 1, 2022 •

edited

Loading