A public API change require running ./gradlew :mpp:jbApiDump and commiting the change.

cc @igordmn, Igor adding you as a reviewer as here we have an API change for desktop. (Also there was a discussion in a slack thread - https://jetbrains.slack.com/archives/C076VK0LGH1/p1746625562243429)

Done, API dump updated!

For context, this is necessary for users to be able to use the Transferable#isDataFlavorSupported(DataFlavor) and Transferable#getTransferData(DataFlavor) APIs. Otherwise, they'd have to guess what the flavour to use is...

I gave it another thought.

IMO, It would be better to move a new public property to ui module, in PlatformClipboard.desktop.kt, so the new property won't expose an extra public class ClipboardUtils_desktopKt (we can see it now in foundation.api dump).

And adding @ExperimentalComposeUiApi to it would be safer for now.

It is easy to break Jewel and any other users when there is no actual API that you're changing/breaking

It will be a definite breakage after CMP-7558, as the main purpose of it is to not expose implementation details to the external users.

So, is the main use case is to retrieve the annotated string from ClipEntry? If so, then my suggestion of removing won't help your case if you still need creating DataFlavor("AnnotatedString").

Considering the AWT coupling issue, the best way to solve this case is to have public functions that provide AnnotatedString. Similar to the internal ones:

It is a big task, which should be done in AOSP first as common API. There are probably alternatives, but before suggesting one, I would like to understand the main issue more.

After this PR we don't lose information in the standard copy/paste actions anymore. Why we still need a custom clipboard and retrieve the annotated string from the default one? Suppose, we copied a text from Text/BasicTextField, and Compose created an AnnotatedString and stored it in the default clipboard. Where we need to retrieve it?

It will be a definite breakage after CMP-7558, as the main purpose of it is to not expose implementation details to the external users.

We can change the Jewel implementation (we'll keep it internal) when CMP-7558 ships and we get it in Jewel, that is not a huge problem.

So, is the main use case is to retrieve the annotated string from ClipEntry? If so, then my suggestion of removing won't help your case if you still need creating DataFlavor("AnnotatedString").

Yes it is, but the main issue this PR fixes is that right now the AnnotatedString that gets passed to Clipboard is stripped of all annotations. I can live with having to have my own copy of the DataFlavor until CMP-7558 is done, and we can use whatever better API there will be.

Considering the AWT coupling issue, the best way to solve this case is to have public functions that provide AnnotatedString. Similar to the internal ones:
[...]
It is a big task, which should be done in AOSP first as common API. There are probably alternatives, but before suggesting one, I would like to understand the main issue more.

Agreed, that would be the ideal scenario, but I was told we could not add any new public API, especially in commonMain. In the meantime though this is a way (undocumented, unofficial) that still allows Jewel to fix a pretty bad UX when copying rich text.

After this PR we don't lose information in the standard copy/paste actions anymore. Why we still need a custom clipboard and retrieve the annotated string from the default one? Suppose, we copied a text from Text/BasicTextField, and Compose created an AnnotatedString and stored it in the default clipboard. Where we need to retrieve it?

Jewel will implement its own Clipboard (see this PR for example) where it will take the AnnotatedString and convert it to raw Markdown, which is a format that can be then put in the AWT clipboard. This is necessary, because we can't put non-serializable content in the system clipboard. It is also what IJ does in general when you copy some highlighted code to the clipboard — it has a mechanism to "convert" said rich text to HTML and RTF, so it can preserve its formatting when pasted elsewhere.

If it is okay that it will definitely break, we can merge it as is, though, let's add a comment for private val annotatedStringFlavor: DataFlavor:

This implementation detail is used by Jewel. When removing it, please provide an alternative of retrieving an annotated string, and notify a Jewel developer that they need to change the implementation.

After https://youtrack.jetbrains.com/issue/CMP-7558/New-Clipboard-Adoption.-Review-API or https://youtrack.jetbrains.com/issue/CMP-7624/Design-ClipEntry-common-API there should be a way to retrieve the annotated string: defaultClipEntryFactory.asAnnotatedString(clipEntry), clipEntry.asAnnotatedString().

Something like awtAnnotatedStringFlavor: DataFlavor probably won't be exposed as API for desktop, as it is only one of the many ways to provide it. Instead of putting the annotated string to transferable, we could put our own class with metadata, or even don't create Transferable until it is needed for passing to the clipboard.

If it is okay that it will definitely break, we can merge it as is, though, let's add a comment for private val annotatedStringFlavor: DataFlavor

Done

After https://youtrack.jetbrains.com/issue/CMP-7558/New-Clipboard-Adoption.-Review-API or https://youtrack.jetbrains.com/issue/CMP-7624/Design-ClipEntry-common-API there should be a way to retrieve the annotated string: defaultClipEntryFactory.asAnnotatedString(clipEntry), clipEntry.asAnnotatedString().

Something like awtAnnotatedStringFlavor: DataFlavor probably won't be exposed as API for desktop, as it is only one of the many ways to provide it. Instead of putting the annotated string to transferable, we could put our own class with metadata, or even don't create Transferable until it is needed for passing to the clipboard.

That's fine. As long as we still have access to the full AnnotatedString in Clipboard via whatever API ends up being there, we are ok with that.

Done, API dump updated!

For context, this is necessary for users to be able to use the Transferable#isDataFlavorSupported(DataFlavor) and Transferable#getTransferData(DataFlavor) APIs. Otherwise, they'd have to guess what the flavour to use is...

This check is done to retain the existing behaviour in androidx.compose.foundation.text.selection.TextFieldSelectionManager#paste, which only tries to get an AnnotatedString:

val text = clipboard?.getClipEntry()?.readAnnotatedString() ?: return@launch

I will propose to Jetpack Compose to alter this slightly as:

val text = clipboard?.getClipEntry()?.readAnnotatedString()
  ?: clipboard?.getClipEntry()?.readText()?.let { AnnotatedString(it) }
  ?: return@launch

To make it more explicit at the usage site, but for now this covers that case.

I don't know why StringSelection implements ClipboardOwner only to have its only function do nothing; I however am going to retain the same behaviour, just in case it covers some unintuitive edge cases. It shouldn't cause any issues, judging by the JavaDoc of ClipboardOwner.

Note: when AWT puts this transferable in the clipboard, it drops the AnnotatedString flavour, since it's not serializable. The net result is having just the plain text put in the system clipboard, which is consistent with the current behaviour.

it drops the AnnotatedString flavour, since it's not serializable.

What if I have this code in the same app (ignoring the fact I use internal functions here):

val annotatedString = AnnotatedString(...)
val clipEntry = annotatedString.toClipEntry()!!
clipboard.setClipEntry(clipEntry)
...

val result = clipboard.getClipEntry().readAnnotatedString()

is result expected to be equal to annotatedString ?

Yes, it's what one of the tests is checking, too.

In prod code however the clip entry is handed immediately to the Clipboard, which in turns sets it immediately in the AWT clipboard, which drops the annotated string as described above. So, the only time the annotated string really "exists" in the transferable is while in transit via the Compose clipboard. As soon as it's handed over to AWT it is discarded.

I removed this TODO I left here a couple years ago as it seems it was addressed in the line below. Someone just forgot to remove the TODO :)

I think this was technically wrong before, as we are supposed to provide the owner to the AWT clipboard if there is one. Given the Transferable itself is the only way we could have an owner, if it implements ClipboardOwner we pass it as owner.

ClipboardOwner is a simple interface that only provides a callback to know "you're not the owner of the clipboard any longer", meaning something else was put in the clipboard. I think this can be needed to do some cleanup in some Transferables which may be holding on to resources internally.

If the transferable is plain text, we should probably return true here as well.

This is not done on purpose, because if you do, you have no way to distinguish the case where there is plain text, and there is no AnnotatedString. It doesn't happen when we put things in the clipboard, but nothing prevents users from putting whatever they want in the clipboard, including a situation like this.

I'm not sure you need to distinguish that. If you're expecting to receive an annotated string, you call has/readAnnotatedString and that's it.

As-is, what we have is inconsistent: hasAnnotatedString can return false and then readAnnotatedString returns a non-null value.

Also to note, we're assuming that the plain text and annotated string contents are interchangeable as at most the plain text is annotatedString.text. Compose does, in general. In normal cases, they are. But here again, absolutely nothing says they must be. You might have a different semantic representation of the same content between plain text and AnnotatedString.

An example; an app puts this text as AnnotatedString: "Hello world". But, for some reason that makes sense to them, the plain text content is Hello *world* — the app is expressing the bold part in the plain text as asterisks, to maintain the intent, even though the representations now have diverged. This is a perfectly valid use case.

I'm not sure you need to distinguish that. If you're expecting to receive an annotated string, you call has/readAnnotatedString and that's it.

These are internal APIs. hasAnnotatedString isn't even an expect/actual, it's literally only used in the desktop target. Users can't access these.

As-is, what we have is inconsistent: hasAnnotatedString can return false and then readAnnotatedString returns a non-null value.

This is only needed because @eymar said that we shouldn't change the commonMain code that uses these APIs (it only uses read* APIs), but this works around an issue in the implementation that only ever calls readAnnotatedString and never falls back to readText. I think you can find that conversation in some other comments to this PR.

Said problematic code in commonMain:

For context, this is necessary for users to be able to use the Transferable#isDataFlavorSupported(DataFlavor) and Transferable#getTransferData(DataFlavor) APIs.

Could you elaborate more, and provide code how it should be used in outside code?

If it is not for the outside code, I would suggest to remove it as public API. The AWT implementation should be only one of many possible implementations.

Detailed explanation

There is an architectural issue in the current API in jb-main that the Clipboard API is tightly coupled with AWT.

It is tightly coupled because it creates AWT-based classes in one place (in toClipEntry), and uses casting to AWT classes in another place (in readAnnotatedString/readText). Instead of that we had to keep ClipEntry platform-independent, and store raw data in it, not the AWT based objects. Convert to AWT based class only:

• in places where it is needed - in the copy/paste actions itself, with supporting different implementations via CompositionLocal or a global factory.
• as interop functions for external users, when they know that the current implementation is the AWT one.

In other words, we shouldn't use nativeClipEntry and derivatives (awtTransferable) in Compose itself, we should provide them for external interop.

The overall review and necessary changes to the current API will be done in https://youtrack.jetbrains.com/issue/CMP-7558/New-Clipboard-Adoption.-Review-API. For this PR, we should try to not make things more coupled.

Having readAnnotatedString isn't fine because of the issue I described, but because we already have it coupled in readText, it is fine for this PR, and it will be fixed together with the other functions later