From d2d63ffbcd4b2722f7be8915a38ff9b89216d9fa Mon Sep 17 00:00:00 2001 From: Marie Lucas Date: Tue, 17 Nov 2026 18:09:51 -0800 Subject: [PATCH 1/3] feat(charts): streamGL's handleRef accepts a callback ref architecture:public-component-api INV8 states that a public handleRef, on a component or a chart series definition, takes Ref, 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. 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. --- docs/architecture/public-component-api.md | 11 +++++- packages/charts/src/marks/marks.test.tsx | 47 ++++++++++++++++++++++- packages/charts/src/marks/streamGL.tsx | 38 +++++++++++++++--- 3 files changed, 87 insertions(+), 9 deletions(-) diff --git a/docs/architecture/public-component-api.md b/docs/architecture/public-component-api.md index 6d3ff5868cbeb..f2bb234fb9e93 100644 --- a/docs/architecture/public-component-api.md +++ b/docs/architecture/public-component-api.md @@ -25,6 +25,7 @@ verified_by: internal/eslint-plugin-astryx/require-baseprops-passthrough.js, packages/core/src/docPropLiterals.test.ts, packages/core/src/docPropReferences.test.ts, + packages/charts/src/marks/marks.test.tsx, ] deciding_specs: [ @@ -152,7 +153,13 @@ guidance owns the process used to propose and test APIs. moves a handler to another element keeps the order and cancellation it released for that handler and documents it (`family:input-fields` DEC-8). - **INV8 — Refs follow React 19.** A public DOM component accepts `ref` as a prop - and connects it to the element promised by its contract. + and connects it to the element promised by its contract. A public `handleRef` + through which a component or a chart series definition exposes its imperative + handle takes `Ref`, so it accepts an object ref or a callback ref. + React calls a callback ref with the handle when the handle attaches, so the + caller learns when the handle is ready. When the handle detaches, a cleanup + the callback ref returned runs; a callback ref without a cleanup is called + with `null`. - **INV9 — Released APIs change deliberately.** A released prop, type, export, default, or observable behavior is not removed, renamed, retyped, deprecated, or corrected incompatibly without the lifecycle, evidence, and migration required by @@ -460,7 +467,7 @@ Rejected: keeping a committed generated API report per package. | Invariant | Evidence | Failure signal | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| INV1, INV8 | Export, public-subpath, prop, and ref checks | A promised component/type cannot be imported or its ref cannot reach the contract element | +| INV1, INV8 | Export, public-subpath, prop, and ref checks | A promised component/type cannot be imported or its ref cannot reach the contract element; a `handleRef` that exposes a handle rejects a callback ref | | INV2 | Naming and logical-direction lint/tests | Equivalent concepts use conflicting names or physical direction leaks into public API | | INV2, DEC-1 | Public-API review against the system vocabulary | A public prop names a concept the system already names, such as a distance, depth, or press motion, with a new term, or uses `lift` for a layout distance | | INV3, INV4 | Historical API review benchmark and `spec:AST-002` evidence | A prop combines unrelated axes or exposes a derivable implementation choice; a new interaction-behavior prop that is not a `Behavior` closed union, carries an input word where its values can name the behavior, splits one behavior across per-input props, or, as a new prop, defaults to anything but the shipped behavior | diff --git a/packages/charts/src/marks/marks.test.tsx b/packages/charts/src/marks/marks.test.tsx index 2adc74b737a25..2905b6eb23f37 100644 --- a/packages/charts/src/marks/marks.test.tsx +++ b/packages/charts/src/marks/marks.test.tsx @@ -9,7 +9,16 @@ * @position Colocated test for the marks/ directory (issue #4295 viz coverage) */ -import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest'; +import {createRef} from 'react'; +import { + describe, + it, + expect, + expectTypeOf, + vi, + beforeEach, + afterEach, +} from 'vitest'; import {render, act, screen} from '@testing-library/react'; import {Chart} from '../Chart'; import {bar} from './bar'; @@ -429,6 +438,42 @@ describe('GL marks without WebGL', () => { unmount(); }); + it('streamGL takes an object ref or a callback ref as handleRef', () => { + const objectRef = createRef(); + const callbackRef = vi.fn<(handle: StreamGLHandle | null) => void>(); + expectTypeOf(streamGL).toBeCallableWith({ + color: '#10b981', + handleRef: objectRef, + }); + expectTypeOf(streamGL).toBeCallableWith({ + color: '#10b981', + handleRef: callbackRef, + }); + }); + + it('streamGL passes its handle to a callback ref when the series mounts, and null on unmount', () => { + const handleRef = vi.fn<(handle: StreamGLHandle | null) => void>(); + const {unmount} = renderMarks( + [streamGL({color: '#10b981', handleRef})], + [], + 'x', + {xDomain: [0, 10]}, + ); + expect(handleRef).toHaveBeenCalledTimes(1); + const handle = handleRef.mock.calls[0][0]; + expect(handle).toEqual({ + push: expect.any(Function), + clear: expect.any(Function), + }); + act(() => { + handle!.push(1, 2); + handle!.clear(); + }); + unmount(); + expect(handleRef).toHaveBeenCalledTimes(2); + expect(handleRef).toHaveBeenLastCalledWith(null); + }); + it('dotGLInteractive renders its two canvases and hover hit area without crashing', () => { const {plot, unmount} = renderMarks([ dotGLInteractive('v', {color: '#111111'}), diff --git a/packages/charts/src/marks/streamGL.tsx b/packages/charts/src/marks/streamGL.tsx index 29237d885d9ff..fb7cebb33df86 100644 --- a/packages/charts/src/marks/streamGL.tsx +++ b/packages/charts/src/marks/streamGL.tsx @@ -19,7 +19,7 @@ import { useImperativeHandle, useCallback, useState, - type MutableRefObject, + type Ref, } from 'react'; import type {SeriesDef} from '../types'; import {useChart} from '../ChartContext'; @@ -44,8 +44,12 @@ export interface StreamGLOptions { bufferSize?: number; lineWidth?: number; opacity?: number; - /** Ref to receive the push/clear handle */ - handleRef?: MutableRefObject; + /** + * Receives the push/clear handle. Takes an object ref or a callback ref. + * A callback ref runs with the handle on every attach. On every detach, + * React runs the cleanup it returned, or calls it with null. + */ + handleRef?: Ref; } const VERT = ` @@ -92,7 +96,7 @@ function StreamGLCanvas({ opacity: number; width: number; height: number; - handleRef?: MutableRefObject; + handleRef?: Ref; }) { const {xScale, yScale} = useChart(); const canvasRef = useRef(null); @@ -271,7 +275,7 @@ function StreamGLCanvas({ // Expose push/clear handle via ref. useImperativeHandle( - handleRef as MutableRefObject, + handleRef, () => ({ push(x: number, y: number) { if (!Number.isFinite(x) || !Number.isFinite(y)) { @@ -343,11 +347,33 @@ function StreamGLCanvas({ * * @example * ``` + * // Object ref: push data points in a rAF loop or event handler. * const streamRef = useRef(null); - * // Push data points in a rAF loop or event handler: * streamRef.current?.push(Date.now(), value); * * + * + * // 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. + * const handleRef = useRef(null); + * const samples = useRef([{x: 0, y: 50}]); + * const attach = useCallback((handle: StreamGLHandle | null) => { + * handleRef.current = handle; + * if (handle == null) { + * return; + * } + * handle.clear(); + * for (const sample of samples.current) { + * handle.push(sample.x, sample.y); + * } + * }, []); + * // Keep at most bufferSize (500 by default) samples, so a replay stays bounded. + * const pushPoint = (point: {x: number; y: number}) => { + * samples.current = [...samples.current, point].slice(-500); + * handleRef.current?.push(point.x, point.y); + * }; + * + * * ``` */ export function streamGL(options: StreamGLOptions): SeriesDef { From 0dab8f2289477dcad3f7fcd7e23d5d3416f4ad4f Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Thu, 19 Nov 2026 17:23:46 -0800 Subject: [PATCH 2/3] docs(public-component-api): callback refs for imperative handles are the rule in every package --- docs/architecture/public-component-api.md | 30 +++++++++++++++++------ 1 file changed, 22 insertions(+), 8 deletions(-) diff --git a/docs/architecture/public-component-api.md b/docs/architecture/public-component-api.md index f2bb234fb9e93..82cb0145cc7a3 100644 --- a/docs/architecture/public-component-api.md +++ b/docs/architecture/public-component-api.md @@ -16,6 +16,8 @@ applies_to: packages/core/src/BaseProps.ts, packages/lab/src/, packages/richtext/src/, + packages/charts/src/, + packages/vega/src/, packages/cli/authoring/doctypes/component/, internal/eslint-plugin-astryx/, ] @@ -152,14 +154,15 @@ guidance owns the process used to propose and test APIs. behavior only where that public API promises cancellation. A component that moves a handler to another element keeps the order and cancellation it released for that handler and documents it (`family:input-fields` DEC-8). -- **INV8 — Refs follow React 19.** A public DOM component accepts `ref` as a prop - and connects it to the element promised by its contract. A public `handleRef` - through which a component or a chart series definition exposes its imperative - handle takes `Ref`, so it accepts an object ref or a callback ref. - React calls a callback ref with the handle when the handle attaches, so the - caller learns when the handle is ready. When the handle detaches, a cleanup - the callback ref returned runs; a callback ref without a cleanup is called - with `null`. +- **INV8 — Refs follow React 19.** In every package, a public DOM component + accepts `ref` as a prop and connects it to the element promised by its + contract. A public ref through which a component or a definition exposes an + imperative handle takes `Ref`, so it accepts an object ref or a + callback ref (DEC-7). React calls a callback ref with the handle when the + handle attaches, so the caller learns when the handle is ready. When the + handle detaches, a cleanup the callback ref returned runs; a callback ref + without a cleanup is called with `null`. A chart series definition's + `handleRef`, such as streamGL's, is one application. - **INV9 — Released APIs change deliberately.** A released prop, type, export, default, or observable behavior is not removed, renamed, retyped, deprecated, or corrected incompatibly without the lifecycle, evidence, and migration required by @@ -463,6 +466,17 @@ The owner said: "okay let's get rid of this massive file. We don't need it, we s Rejected: keeping a committed generated API report per package. +### DEC-7 — Every package's handle refs accept callback refs + +**Reference:** `architecture:public-component-api/DEC-7` +**Decider:** `cixzhang`, `2026-11-19 17:20 PT` + +Callback refs are an API convention of the whole system, not of one package. A +public ref that exposes an imperative handle, in any package, takes +`Ref` and accepts an object ref or a callback ref (INV8). + +Rejected: accepting callback refs only in the packages that ask for them. + ## Verification | Invariant | Evidence | Failure signal | From 232e338218b99083e32ac0f5afbae695c059c413 Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Thu, 19 Nov 2026 17:52:46 -0800 Subject: [PATCH 3/3] docs(public-component-api): the every-package scope covers handle refs only; scope lines say so --- docs/architecture/public-component-api.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/architecture/public-component-api.md b/docs/architecture/public-component-api.md index 82cb0145cc7a3..b9dcf81980081 100644 --- a/docs/architecture/public-component-api.md +++ b/docs/architecture/public-component-api.md @@ -71,6 +71,7 @@ deciding_specs: ``` This record defines the shared public API contract for stable Astryx components. +Its handle-ref rule (INV8, DEC-7) applies in every package. ## Purpose @@ -154,9 +155,9 @@ guidance owns the process used to propose and test APIs. behavior only where that public API promises cancellation. A component that moves a handler to another element keeps the order and cancellation it released for that handler and documents it (`family:input-fields` DEC-8). -- **INV8 — Refs follow React 19.** In every package, a public DOM component - accepts `ref` as a prop and connects it to the element promised by its - contract. A public ref through which a component or a definition exposes an +- **INV8 — Refs follow React 19.** A public DOM component accepts `ref` as a + prop and connects it to the element promised by its contract. In every + package, a public ref through which a component or a definition exposes an imperative handle takes `Ref`, so it accepts an object ref or a callback ref (DEC-7). React calls a callback ref with the handle when the handle attaches, so the caller learns when the handle is ready. When the @@ -342,7 +343,9 @@ guidance owns the process used to propose and test APIs. change coupling step 6 describes. A removed or renamed row follows INV9. This record applies to stable public packages, and INV23 also applies to Lab -source. Lab components are not stable public promises until promotion. +source. INV8's handle-ref rule (DEC-7) applies in every package, Lab, Charts +and Vega included. Lab components are not stable public promises until +promotion. ## Change coupling