Repository navigation
docs(app-kit): show stable ChatEmbed file and artifact handlers (#20220) - #20662
Conversation
First Principles Review (Opus 5.5) — ⏭️ skippedRevision |
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing to check. [DESIGN-REVIEWED] 60f37d7 Description read[DESCRIPTION-READ] fea33a012faf2cb3748c010621729e16cfc7c4867c5ff686029dba408d79e553 That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
mbriones98
left a comment
There was a problem hiding this comment.
Checks green and readiness passed at 60f37d7; no behavior change.
Problem / Motivation
Goal: App authors who copy the Embedded Chat example get file and artifact handlers that do not re-render the transcript on every host render.
The Embedded Chat example in
docs/app-kit/api-reference.mdpassed inline arrows toonFileOpenandonArtifactOpen.ChatMessageListlists both callbacks in the dependency array of its memoizedrenderMessage(useCallback,website/src/app-sdk/ChatMessageList.tsx:305), andChatEmbedhands them straight through, so a new function identity on each host render throws that memo away and every message re-renders.Why it matters
The example is the template app authors copy. Copied as written, every embedded chat re-renders its whole transcript whenever the host component renders, which gets slower as the conversation grows.
Not a goal
ChatEmbed,ChatMessageListor any callback signature.What changed (motivation → approach → change)
Inline arrows in the documented example → new identities each render invalidate
renderMessage→ the example now shows both stable forms the issue allows:onFileOpenwrapped inuseCallbackwith its one dependency (viewer), using the documented(path, opts?: { line?, endLine? })shape.onArtifactOpenas a function defined outside the component.One short paragraph above the example says why: keep both handlers the same function between renders while their behaviour does not change, since the transcript re-renders whenever either changes identity. The paragraph describing the signatures and the omitted-prop behaviour is unchanged.
Backwards compatibility
Compatible: documentation only; no code, type or signature changes.
Removes nothing: the diff only rewrites a docs example and adds one paragraph.
Tests
N/A — documentation-only change.
python3 scripts/docs_lint.pyand./scripts/docs-lint.shpass locally, and neither reports a new identifier hit for the example's names.Manual verification
Checked the example's
onFileOpenparameter shape againstChatEmbedProps.onFileOpeninwebsite/src/app-sdk/ChatEmbed.tsx:125and the memo dependency list inChatMessageList.tsx:305on this branch's base.Related Issues
Closes #20220
Follow-up to the review on #19889. Open #19879 edits the same file but does not touch this example or these callbacks.
Decision for the owner
The decision is how the docs should show stable
onFileOpenandonArtifactOpenhandlers forChatEmbed. This draft showsuseCallbackfor the handler that reads component state and a module-level function for the one that does not, so readers see both forms the issue names without auseCallbackaround a function that never changes.Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.