Repository navigation
feat(charts): streamGL's handleRef accepts a callback ref - #12559
marie-lucas wants to merge 4 commits into
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
AI review status for this pull request.
|
PR Analysis Report
Generated by PR Enrichment workflow | View current CI run |
There was a problem hiding this comment.
Approval waits on an engineering owner's decision on the proposed architecture:public-component-api INV8 amendment, which the streamGL type change rests on, and two fixes are needed either way.
An engineering owner records that decision by commenting /approve-spec <full head SHA> on this pull request (the author may, as an engineering owner), and the decision includes whether this record, written for stable components, covers chart series definitions in the canary charts package.
Blocking findings:
- The new seed example in
streamGL.tsx(lines 355-361) pushes(0, 50)again each time the handle re-attaches, for example when an<Activity>shows the chart again or under StrictMode, so the chart draws a line from the newest sample back to the seed point; document that the callback runs on every attach and seed once behind a ref. - The new INV1/INV8 failure signal "a
handleRefrejects a callback ref" (public-component-api.mdline 468) also fires onSideNavCollapseButton's publichandleRef, which takes SideNav's handle as input; scope it to "ahandleRefthat exposes a handle rejects a callback ref".
CI did not run on this head because the CI queue was full, so it needs a re-run.
Claims and files checked
Review mode: full; reason: no-earlier-review
- Claim:
handleRefwidens toRef<StreamGLHandle>. Verified atstreamGL.tsx:51and:98. - Claim: the internal cast is removed and runtime behavior is unchanged. Verified:
streamGL.tsx:277, and the new runtime test also passes against the previousstreamGL.tsx. - Claim:
Chartmounts its series only after it measures its width. Verified atChart.tsx:359. - Claim: a callback ref gets the handle after mount and
nullon unmount. Verified bymarks.test.tsx:454-475. It is also called again on every re-attach (finding above). - Claim: every exported
handleRefin Core and Lab that exposes a handle already takesRef<Handle>. Verified for those props.SideNavCollapseButton'shandleReftakes a handle as input and is typedRefObject(finding above). - Claim: existing object refs still type-check and behave the same. Verified by the compile-time test and the object-ref cases in
glEffectReplay.test.tsx. - Claim: the canary-only charts package needs no Changeset. Verified: the package is private and canary-only, and the Changeset check refuses private packages.
- Claim: with the previous
streamGL.tsx, the new tests fail type-checking with TS2322 at the two callback-ref lines. Verified atmarks.test.tsx:450and:457. - Claim:
marks.test.tsxpasses 27/27 and the charts suite passes 126/126. Verified on this head. - Claim: the charts typecheck passes after Core and Charts are built. Verified on this head.
- Claim: the WebGL streaming story still type-checks with its object ref. Verified by reading: it passes a
MutableRefObject, whichRef<StreamGLHandle>accepts. - Claim: there is no visual change. Verified: the change is type, docs and tests only.
- Claim: the record text has no narration, status lines or references. Verified.
- File
docs/architecture/public-component-api.md: failure-signal finding; the INV8 amendment awaits an owner decision. - File
packages/charts/src/marks/streamGL.tsx: seed-example finding. - File
packages/charts/src/marks/marks.test.tsx: clear.
aab693b to
8e970bc
Compare
There was a problem hiding this comment.
Approval waits on an engineering owner's decision on the proposed architecture:public-component-api INV8 amendment, which the streamGL handleRef type change rests on; no blocking defect remains, and both earlier findings are fixed.
An engineering owner records that decision by commenting /approve-spec <full head SHA> on this pull request (the author may, as an engineering owner), and the decision includes whether this record, written for stable components, covers chart series definitions in the canary charts package. The CI workflow did not run its typecheck, tests or build on this head because CI was full, so it needs a re-run.
Optional suggestions:
- Miss: React 19 runs the cleanup a callback ref returns instead of calling it with
null, so INV8's new sentence and thehandleRefJSDoc could end with "unless it returned a cleanup function, which React runs instead". - The JSDoc example's
sampleslist is never trimmed, so a per-frame stream keeps every point and replays all of them on each attach; keeping only the lastbufferSizesamples avoids that.
Claims and files checked
Review mode: full; reason: history
- Claim:
handleRefwidens toRef<StreamGLHandle>. Verified atstreamGL.tsx:52and:99. - Claim: the internal cast is removed and no runtime code changes. Verified at
streamGL.tsx:277-278; the new runtime test also passes against the previousstreamGL.tsx. - Claim:
Chartmounts its series only after it measures its width. Verified atChart.tsx:359. - Claim: a callback ref gets the handle when it attaches and
nullwhen it detaches. Verified bymarks.test.tsx:454-475; a callback that returns a cleanup gets the cleanup instead (suggestion above). - Claim: every exported Core and Lab
handleRefthat exposes a handle already takesRef<Handle>, so the record needs no gap line. Verified;SideNavCollapseButton's takes a handle as input and the date scroller's is not exported. - Claim: existing object refs still type-check and behave the same. Verified by the charts typecheck and the object-ref StrictMode and Activity tests.
- Claim: an Activity that shows the chart again keeps the buffer, and a chart at width 0 unmounts the series and discards it. Verified by reading
streamGL.tsx:115-120,:311-336andChart.tsx:359. - Claim: the documented callback-ref pattern replays correctly on every attach. Verified on the head: each point is drawn once after StrictMode replay and after an Activity hide and show.
- Claim: the canary-only charts package needs no Changeset. Verified:
packages/charts/package.jsonis private and canary-only. - Claim: with the previous
streamGL.tsx, the new tests fail type-checking with TS2322 at the two callback-ref lines. Verified atmarks.test.tsx:450and:457. - Claim: the runtime test passes on the previous code too, and the two mutations would fail it. Verified 27/27 on the previous code; the mutation results follow from the assertions at
marks.test.tsx:462and:473-474. - Claim:
marks.test.tsxpasses 27/27 and the charts suite 12 files, 126/126. Verified on the head. - Claim: the charts typecheck passes after building Core and Charts. Verified on the head.
- Claim: the Streaming story is unchanged and still type-checks with its object ref. Verified by reading: it passes a
MutableRefObject, whichRef<StreamGLHandle>accepts. - Claim: knowledge, formatting and lint checks pass. Verified for the knowledge check, Prettier and ESLint on the changed files; the Lint workflow also passed.
- Claim: there is no visual change. Verified: type, docs and tests only.
- Claim: the record delta has no narration, research, status, or pull request references. Verified.
- File
docs/architecture/public-component-api.md: the INV8 amendment awaits an owner decision; optional cleanup wording. - File
packages/charts/src/marks/streamGL.tsx: clear apart from two optional wording suggestions. - File
packages/charts/src/marks/marks.test.tsx: clear.
architecture:public-component-api INV8 states that a public handleRef, on a component or a chart series definition, takes Ref<Handle>, so it accepts an object ref or a callback ref. React calls a callback ref with the handle when it attaches. On detach, React runs the cleanup it returned, or calls it with null. streamGL's handleRef now takes Ref<StreamGLHandle>. A caller can learn when the handle is ready, for example to seed data once the chart mounts the series. Object refs work as before. The internal cast is gone, and the JSDoc example shows both ref forms. Tests cover both ref forms at compile time and the callback ref's attach and detach at runtime. The record lists the test file under verified_by.
8e970bc to
d2d63ff
Compare
There was a problem hiding this comment.
Approval waits on an engineering owner's decision on the proposed architecture:public-component-api INV8 amendment, which the streamGL handleRef type change rests on; no defect remains at this head.
- Owner decision: an engineering owner approves the amended INV8 sentences and the scoped INV1/INV8 failure signal by commenting
/approve-spec <full head SHA>on this pull request, or says what INV8 should state instead; the author is an engineering owner and may do so, and approving also brings chart series definitions in the canary charts package under INV8.
The earlier notes are fixed: INV8 and the option JSDoc now describe React's cleanup-or-null detach, and the example keeps at most 500 samples. CI's typecheck, test and build legs were cancelled because CI was full, so they need a re-run at this head.
Claims and files checked
Review mode: full; reason: history
Claims:
- Chart mounts its series only after it measures its width, so a caller's mount effect sees a null handle: verified (
Chart.tsx:172,:359). - Before this change
handleReftook only a mutable object ref: verified (basestreamGL.tsx). - The type widens to
Ref<StreamGLHandle>, the cast goes away and no runtime code changes: verified (streamGL.tsx:52,:99,:277-278). - The public component API record owns ref admission, as the runtime record says: verified (runtime record, DOM and imperative API boundary).
- Every exported Core and Lab
handleRefthat exposes a handle already takesRef<Handle>: verified (inventory ofhandleRefdeclarations). - Existing object refs still type-check and behave the same: verified (charts typecheck with the object-ref test; the Streaming story passes a
useRef<StreamGLHandle | null>). - A callback ref should be stable because React calls a new function again: verified (React re-runs the imperative handle when the ref changes).
- The buffer is kept across an Activity show and discarded at width 0: verified (
Chart.tsx:359; probe replays into a new buffer after width 0). - No changeset because the charts package is canary-only: verified (
privatepackage; the changeset check refuses a private package). - Tests cover both ref forms at compile time and the callback ref at runtime: verified (
marks.test.tsx:441-475, 27/27). - With the previous
streamGL.tsx, the new tests fail type-checking at the two callback-ref lines: verified (TS2322 at:450and:457). - The runtime test also passes on the previous code, and the two described mutations would fail it: verified (27/27 with the base runtime; the call-count and
nullassertions). - The charts suite passes 126/126, including the object-ref replay cases: verified.
- Knowledge check, formatting, lint, typecheck and changeset check pass: verified; the full repository check, the pre-review checklist and the diff-routed spec lookup were not rerun.
- The amended INV8 matches React's detach behavior and the bottom-sheet switcher's FR9: verified (probe: handle then cleanup; handle and
nullwithout a cleanup). - The record delta meets the writing rubric (present tense, no references or project status): verified.
- No visual change: verified.
Files:
docs/architecture/public-component-api.md: text accurate; approval waits on an engineering owner's decision on the INV8 amendment.packages/charts/src/marks/streamGL.tsx: clear.packages/charts/src/marks/marks.test.tsx: clear.
|
/approve-spec d2d63ff |
|
/revoke-spec d2d63ff |
…the rule in every package
|
/approve-spec 0dab8f2 |
There was a problem hiding this comment.
Changes requested: the streamGL handleRef widening and the owner-approved callback-ref rule are sound, but the record's new every-package INV8 scope leaves gaps it does not name, and the description no longer matches the record.
- INV8 now says every package's public DOM components accept
ref(docs/architecture/public-component-api.md:157-159), but Charts'ChartAxis,ChartGrid,ChartLegend,ChartSwatchandChartTooltipand Lab components such asChatReasoningandTabBarMoreListtake norefand the record names noINV8 gap:line, so either put "In every package" on the handle-ref sentence only, which is what DEC-7 decides, or add that gap line. - The record still says it covers stable packages only (
:73, and:344: "applies to stable public packages, and INV23 also applies to Lab source"), which contradicts INV8's every-package scope and the new Charts and Vegaapplies_toentries, so amend:344and:73to say where INV8 applies. - The description's "Current specification" quotes an INV8 sentence this head no longer has and leaves out DEC-7 and the
applies_toadditions, so update it to match the record at this head.
Everything else checks out: the type change is compatible, the new tests fail against the base and pass here, and the earlier notes are fixed. The record edits will need a fresh /approve-spec from an engineering owner at the new head, and CI has not run on this draft yet.
Claims and files checked
Review mode: full; reason: spec-record
Claims:
- Chart mounts its series only after it measures its width, so a caller's mount effect sees no handle yet: verified (
Chart.tsx:172,:359). - Before this change
handleReftook only a mutable object ref: verified (basestreamGL.tsx). - The type widens to
Ref<StreamGLHandle>, the cast goes away and no runtime code changes: verified (streamGL.tsx:52,:99,:277-278). - The public component API record owns ref admission, as the runtime record says: verified (runtime record, DOM and imperative API boundary).
- The pull request amends INV8 to the quoted
handleRefsentence: false (INV8 atpublic-component-api.md:157-165now reads differently, and DEC-7 and the Charts and Vegaapplies_toentries are not mentioned). - The failure signal is added and the charts test is listed under
verified_by: verified (:484,:30). - Every exported Core and Lab
handleRefthat exposes a handle already takesRef<Handle>: verified (inventory ofhandleRefdeclarations). streamGLwas the only nonconforming site, so the record needs no gap line: false (INV8's every-package DOM-refsentence is unmet byChartLegend.tsx:31,ChartSwatch.tsx:27and others).- Existing object refs still type-check and behave the same: verified (charts typecheck; object-ref tests pass; the Streaming story passes a
useRef<StreamGLHandle | null>). - A callback ref should be stable because React calls a new function again: verified (React adds the ref to the handle's dependencies).
- The buffer is kept when the same series re-attaches and discarded when the chart's width drops to 0: verified (per-instance ring ref at
streamGL.tsx:115;Chart.tsx:359unmounts the series). - No changeset because the charts package is canary-only: verified (
privatepackage; the changeset check passes). - Tests cover both ref forms at compile time and the callback ref at runtime: verified (
marks.test.tsx:441-475). - With the previous
streamGL.tsx, the new tests fail type-checking at the two callback-ref lines: verified (TS2322 atmarks.test.tsx:450and:457). - The runtime test also passes on the previous code, and the call-count and
nullassertions catch the two described mutations: verified (27/27 on the base runtime;:462,:473-474). marks.test.tsxpasses 27/27 and the charts suite 126/126, object-ref replay cases included: verified.- Knowledge check, formatting, lint, typecheck and changeset check pass: verified; the diff-routed spec lookup, the pre-review checklist and the repository check were not rerun.
- No visual change: verified.
- The record delta meets the writing rubric: R1 and R5 verified; R7's claim that the rule's only nonconforming site changes with it is false (see above).
Files:
docs/architecture/public-component-api.md: two findings (INV8 gap for Charts and Lab DOM components; stable-only scope at:73and:344).packages/charts/src/marks/streamGL.tsx: clear.packages/charts/src/marks/marks.test.tsx: clear.
…s only; scope lines say so
|
/approve-spec 232e338 |
There was a problem hiding this comment.
Approved pending CI: CI has not run on this head yet. The pull request is a draft, so CI skipped every job; it runs once the pull request is marked ready for review.
The streamGL handleRef widening is compatible, the new type test fails against the previous streamGL.tsx and passes here, and the runtime test shows the callback ref receives the handle on attach and null on unmount. The owner-approved record change now applies "every package" to handle refs only, the scope lines say so, and the description matches the record, so the three earlier findings are fixed.
Claims and files checked
Review mode: full; reason: spec-record
Claims:
- Chart mounts its series only after it measures its width, so a caller's mount effect sees no handle yet: verified (
Chart.tsx:172,:359). - Before this change
handleReftook only a mutable object ref: verified (basestreamGL.tsx). - The type widens to
Ref<StreamGLHandle>, the cast goes away and no runtime code changes: verified (streamGL.tsx:52,:99,:277-278). - The public component API record owns ref admission, as the runtime record says: verified (runtime record, DOM and imperative API boundary).
- The pull request amends INV8 with the quoted handle-ref sentences: verified (
public-component-api.md:159-166). - INV8's DOM
refsentence is unchanged and keeps its scope: verified (:158-159,:345). - DEC-7 is added with its decider and rejected alternative: verified (
:472-481). - Charts and Vega join
applies_to, and the scope lines say the handle-ref rule applies in every package: verified (:19-20,:74,:345-347). - The failure signal is added and the charts test is listed under
verified_by: verified (:487,:30). - Every exported Core and Lab
handleRefthat exposes a handle already takesRef<Handle>, andstreamGLwas the only exception, so the record needs no gap line: verified (handle inventory; the oneRefObjecthandle,MonthScroller, is not exported). - The record change needs an engineering owner's approval at this head: verified (present).
- Existing object refs still type-check and behave the same: verified (charts typecheck; object-ref tests pass; the Streaming story has no type error).
- A callback ref should be stable, React calls it on every attach, and the buffer may be new or kept: verified (React adds the ref to the handle's dependencies; per-instance ring at
streamGL.tsx:115;Chart.tsx:359unmounts the series at width 0). - No changeset because the charts package is canary-only: verified (
privatepackage; the changeset check passes). - An
onReadyoption was rejected as a second API for the same job: consistent with INV21. - Tests cover both ref forms at compile time and the callback ref at runtime: verified (
marks.test.tsx:441-475). - With the previous
streamGL.tsx, the new tests fail type-checking at the two callback-ref lines: verified (TS2322atmarks.test.tsx:450and:457). - The runtime test also passes on the previous code, and its call-count and
nullassertions catch the two described mutations: verified (runtime code unchanged;:462,:473-474). marks.test.tsxpasses 27/27 and the charts suite 126/126, object-ref replay cases included: verified.- Knowledge check, formatting, lint, typecheck and changeset check pass: verified; the diff-routed spec lookup, the pre-review checklist and the repository check were not rerun.
- No visual change: verified.
- The record delta meets the writing rubric (present tense, no pull request references, no status or gap line needed): verified.
Files:
docs/architecture/public-component-api.md: clear.packages/charts/src/marks/streamGL.tsx: clear.packages/charts/src/marks/marks.test.tsx: clear.
|
/approve-spec 8f4c3a5 |
User need
A builder who streams data into
streamGL()needs to know when its push/clear handle exists, for example to seed initial points or replay buffered samples.Chartmounts its series only after it measures its width. So a caller's mount effect runs before the handle attaches, andhandleRef.currentis stillnullat that point. TodayhandleReftakes only a mutable object ref. The only way to observe the attach is to hand-write an object with acurrentgetter/setter, which is easy to get wrong and differs from every other Astryx handle. React already has a standard answer for this: a callback ref. The type rejects it.Problem and solution fit
StreamGLOptions.handleRefis widened fromMutableRefObject<StreamGLHandle | null>toRef<StreamGLHandle>. A callback ref then type-checks, and React calls it with the handle when it attaches and withnullwhen it detaches. The runtime already passes the ref touseImperativeHandle, which accepts callback refs, so the internal cast is removed and no runtime code changes.architecture:public-component-apiINV8 states the rule that decides this API. Core and Lab handles already follow it, and so does streamGL from this PR on.Current specification
architecture:public-component-apiowns public ref admission and naming,handleRefincluded, asarchitecture:react-component-runtime("DOM and imperative API boundary") states. This PR amends PCA INV8 (Refs follow React 19):The DOM-
refsentence of INV8 is unchanged and keeps its scope. The PR also:cixzhang, 2026-11-19 17:20 PT): callback refs for imperative handles are a convention of the whole system, not of one package. Rejected: accepting callback refs only in the packages that ask for them;packages/charts/src/andpackages/vega/src/toapplies_to, and says in the record's scope lines that the handle-ref rule applies in every package, Lab, Charts and Vega included;handleRefthat exposes a handle rejects a callback ref" to the INV1/INV8 failure signal and listspackages/charts/src/marks/marks.test.tsxunderverified_by.Every exported
handleRefthat exposes a handle in Core and Lab already usesRef<Handle>. streamGL was the only exception, and it conforms in this PR, so the record has no gap line.The record change needs the spec owner's
/approve-specat the exact head.Public delta and caller burden
StreamGLOptions.handleRefMutableRefObject<StreamGLHandle | null>Ref<StreamGLHandle>(object ref or callback ref)Before:
After (both work):
MutableRefObject<StreamGLHandle | null>is assignable toRef<StreamGLHandle>, and it still behaves the same. No default, behavior, theming or accessibility change.useCallback, because React calls a new function again on each render, as with any callback ref. React calls it on every attach, and the stream buffer can be new or kept, so replay the samples to show: clear, then push. For example, anActivitythat shows the chart again keeps the buffer, while a chart at width 0, such as in a hidden tab panel, unmounts the series and discards it. The JSDoc example shows the pattern.@astryxdesign/chartsis canary-only, so this PR has no Changeset.Design and alternatives
The handle stays a standard React ref, as on every other Astryx
handleRef. Rejected: anonReadycallback option, because it would be a second API for the job a callback ref already does (PCA INV21).Evidence
Tests in
packages/charts/src/marks/marks.test.tsx:expectTypeOf(streamGL).toBeCallableWith(...)acceptscreateRef<StreamGLHandle>()and a callback ref.{push, clear}after the series mounts. The handle works, and unmount calls the ref withnull.Red arms:
streamGL.tsxrestored with the new tests kept:tscfails withTS2322: Type 'Mock<(handle: StreamGLHandle | null) => void>' is not assignable to type 'MutableRefObject<StreamGLHandle | null> | undefined'at the two callback-ref lines.expected "vi.fn()" to be called 1 times, but got 0 times.null:expected "vi.fn()" to be called 2 times, but got 1 times.Green:
marks.test.tsx: 27/27.Unchanged legacy paths:
marks.test.tsxpasses, and so do the object-ref cases inglEffectReplay.test.tsx(StrictMode replay, Activity hide and show).Charts/WebGLStreaming story is unchanged and still type-checks with its object ref.Scope
Components: streamGL (charts mark)
Testing
pnpm check:knowledge: records alignedpnpm exec prettier --checkandpnpm exec eslint --max-warnings=0on the changed filespnpm -F @astryxdesign/charts typecheck(after building core and charts)pnpm exec vitest run packages/chartspnpm specs:for --diff origin/main: no concern-routed claims for the added linespnpm review:pre: 0 findingspnpm check:changesetsandpnpm check:repoNo visual change, so real-browser captures don't apply.
Writing rubric results
verified_bynames a test file.#plus digits,/pull/,/issues/).