BbCopyText: async ValueFuncAsync needs ClipboardItem to survive the transient user activation

[mathewtaylor]

Split out of #453 (@DCarlson12), by agreement on that issue. The synchronous Func<string> half stays there and can land on its own; this covers the asynchronous variant, which is a materially different piece of work.

Why this is not just another parameter

clipboard.js currently does:

export async function copyToClipboard(text) {
  try {
    await navigator.clipboard.writeText(text);
    return true;
  } catch {
    // textarea + document.execCommand fallback
  }
}

Clipboard writes require transient user activation. Today Value is a string already in hand, so the click handler runs essentially straight into writeText and the activation is still live.

If we await a consumer-supplied Func<Task<string>> first — a fetch, a database read, anything genuinely async — several browsers, Safari most strictly, treat the activation as spent by the time writeText is called and reject the write.

The failure is quiet, which is the dangerous part. The rejection is caught by the existing catch, which falls through to the document.execCommand('copy') fallback — and that is also gesture-gated (and deprecated), so it fails too. The user clicks copy, sees the success state, and gets nothing on the clipboard.

The actual fix is in the JS layer

Hand the promise to ClipboardItem so the browser keeps the activation alive across the await, rather than awaiting first and writing second:

navigator.clipboard.write([
  new ClipboardItem({ 'text/plain': textPromise })
]);

Work involved:

• Restructure copyToClipboard to accept a promise-producing callback rather than a resolved string, so the .NET side can be invoked inside the ClipboardItem rather than before the write.
• Feature-detect: ClipboardItem support for promise values differs across browsers, and navigator.clipboard.write is not universally available where writeText is. Needs a path for browsers that only support the resolved-string form — accepting that those will fail on a genuinely slow func, and deciding whether that surfaces as an error rather than a silent no-op.
• Revisit the execCommand fallback. It cannot rescue an expired activation, so treating it as the catch-all for every failure hides this class of bug. It should probably only run for the insecure-context case it was written for.
• Decide what a failed copy reports. Today failure is invisible; with an async source, failure becomes much more likely and the component should probably surface it.

Testing

This cannot be verified by unit test or by building — activation semantics only exist in a real browser, and they differ per engine. Needs manual verification in Safari specifically, plus Chrome and Firefox, with a deliberately slow func (a second or more) rather than an immediately-resolved task, which will pass everywhere and prove nothing.

Depends on

#453 — the sync ValueFunc should land first. It settles the parameter naming and the precedence rules (see below), which this variant then follows.

Shared API decisions, settled on #453

Both halves need these, so recording them here too:

1. Value is currently [Parameter, EditorRequired]. Adding func-based parameters means dropping EditorRequired, or the analyzer nags anyone who sets only a func. That is an API-surface snapshot change.
2. "First non-null" precedence needs tightening — Value is a string, so a non-null empty string would win a literal reading and silently copy nothing. Precedence should key on !string.IsNullOrEmpty(Value), and the docs should state plainly what happens when both a value and a func are set.

[mathewtaylor]

Fixed in #525, merged to develop.

ValueFuncAsync is in. Value still wins when non-empty, then ValueFunc, then this. OnCopyFailed reports a CopyTextFailure of Refused or NoValue, so a failed copy is no longer invisible — which is what let this go unnoticed in the first place.

Three attempts, and the first two are worth recording because they look right.

1. Resolve then write — spends the activation on the await, refused. The original bug.
2. Hand the promise to ClipboardItem — the documented answer, and it fixed Chrome. Safari still refused.
3. Add a resolve-then-write fallback for Safari — also refused.

What both missed is that Safari objects to when the write is made, not what is in it. A Blazor click travels C# → SignalR → JS, so by the time the write happens the gesture window has closed. A literal Value copies fine in Safari only because that hop is fast enough to slip through.

So JavaScript now owns the copy gesture: a listener on the element calls clipboard.write() immediately, inside the real gesture, and calls back into .NET for the text from inside the ClipboardItem. The Blazor handlers stand down while JS is in charge and take over if the module fails to load or during prerendering.

Also addressed from this issue's list: the execCommand fallback ran on every failure, including an expired activation it cannot rescue, and reported success regardless. It now runs only for the insecure-context case it was written for.

Verified in Chrome and Safari with a deliberately slow 1.5-second function. The plain literal-value copy was re-checked in both too, since the click path changed for every usage rather than just the async one.