diff --git a/docs/architecture/public-component-api.md b/docs/architecture/public-component-api.md index 55d356a707629..cef8d636538ce 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/, ] @@ -25,6 +27,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: [ @@ -68,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 @@ -151,8 +155,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. +- **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 + 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 @@ -335,7 +346,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 @@ -459,11 +472,22 @@ 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 | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 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 037c73eddd3f1..2e18749a827f1 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'; @@ -481,6 +490,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 {