feat (rsc): add streamUI onFinish callback

[gclark-eightfold]

Summary

Adds an onFinish callback to streamUI.

Resolves #1845

Tasks

• implementation
• test
• example
• docs
  • reference
  • example
• changeset

[gclark-eightfold]

For the "test", "example", and "docs:example" tasks, I couldn't find the right places to extend for the streamUI api. Please let me know if any of these are blocking for merge.

[gclark-eightfold]

@lgrammel If you get a chance, can you review these changes?

[lgrammel]

@gclark-eightfold general direction looks good. tests would be important, since i'm thinking about refactoring the inner loop of streamUI to a stream similar to streamText at some point

[gclark-eightfold]

@lgrammel I'll see about adding some tests then soon. I did see there were some already made for the precursor render function, so I may adapt / take some pointers from those unless there's any better examples to model off of.

Edit: I actually see now the E2E tests already made for streamUI. Let me know if these are sufficient.

[lgrammel]

@gclark-eightfold I have concerns going all in on e2e, bc of the nature of e2e tests. I'd love to have tests similar to streamText, but that requires a refactoring on my end

[Godrules500]

Thanks for working on this! I'm looking forward to this one since it's preventing me from using streamUI!

[gclark-eightfold]

@lgrammel I re-added some of the tests I found for the render function that were removed in this PR in favor of E2E tests
https://github.com/vercel/ai/pull/1825/files#diff-ba5d05e418f64a2fa3c1e20b39bc9378e4d29218f46156f7ac95fac0b1559e56

I can remove the snapshot tests that aren't related to the onFinish callback if preferred since I believe those should be covered in the E2E tests, but just LMK what your preference is there.

[lgrammel]

For the "test", "example", and "docs:example" tasks, I couldn't find the right places to extend for the streamUI api. Please let me know if any of these are blocking for merge.

The example could go under examples/next-openai/app (new api route / chat frontend)
The docs example could be a new page under content/examples/01-next-app/01-basics

[lgrammel]

@lgrammel I'll see about adding some tests then soon. I did see there were some already made for the precursor render function, so I may adapt / take some pointers from those unless there's any better examples to model off of.

Edit: I actually see now the E2E tests already made for streamUI. Let me know if these are sufficient.

It's fine as is for now.

[gclark-eightfold]

@lgrammel Should be all added now.
I opted to add the onFinish documentation under content/examples/05-interface/03-token-usage.mdx to match that of content/examples/03-node/02-streaming-structured-data/10-token-usage.mdx

Let me know if this should be changed in any way. Also wasn't able to figure out how to run a server for the MDX content to verify it all works, but I tried to keep it as close to what exists already.

[lgrammel]

@gclark-eightfold looks very good. I'll do some testing, also one the docs.

[lgrammel]

Looks great! Awesome work!

[Godrules500]

I've been playing with this, but I was curious, since onFinish cannot have a return like the text callback, how can I display that a finish reason violated the safety settings?

[lgrammel]

I've been playing with this, but I was curious, since onFinish cannot have a return like the text callback, how can I display that a finish reason violated the safety settings?

if you use streamable value or streamable ui, you can update them from within the onFinish callback