Skip to content
Draft
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 24 additions & 3 deletions docs/architecture/public-component-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@ applies_to:
packages/core/src/BaseProps.ts,
packages/lab/src/,
packages/richtext/src/,
packages/charts/src/,
packages/vega/src/,
Comment thread
astracat-bot[bot] marked this conversation as resolved.
Resolved
packages/cli/authoring/doctypes/component/,
internal/eslint-plugin-astryx/,
]
Expand All @@ -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:
[
Expand Down Expand Up @@ -151,8 +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.
- **INV8 — Refs follow React 19.** In every package, a public DOM component
Comment thread
astracat-bot[bot] marked this conversation as resolved.
Resolved
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<Handle>`, 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
Expand Down Expand Up @@ -456,11 +466,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<Handle>` 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 `<thing>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 |
Expand Down
47 changes: 46 additions & 1 deletion packages/charts/src/marks/marks.test.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down Expand Up @@ -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<StreamGLHandle>();
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'}),
Expand Down
38 changes: 32 additions & 6 deletions packages/charts/src/marks/streamGL.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ import {
useImperativeHandle,
useCallback,
useState,
type MutableRefObject,
type Ref,
} from 'react';
import type {SeriesDef} from '../types';
import {useChart} from '../ChartContext';
Expand All @@ -44,8 +44,12 @@ export interface StreamGLOptions {
bufferSize?: number;
lineWidth?: number;
opacity?: number;
/** Ref to receive the push/clear handle */
handleRef?: MutableRefObject<StreamGLHandle | null>;
/**
* 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<StreamGLHandle>;
}

const VERT = `
Expand Down Expand Up @@ -92,7 +96,7 @@ function StreamGLCanvas({
opacity: number;
width: number;
height: number;
handleRef?: MutableRefObject<StreamGLHandle | null>;
handleRef?: Ref<StreamGLHandle>;
}) {
const {xScale, yScale} = useChart();
const canvasRef = useRef<HTMLCanvasElement | null>(null);
Expand Down Expand Up @@ -271,7 +275,7 @@ function StreamGLCanvas({

// Expose push/clear handle via ref.
useImperativeHandle(
handleRef as MutableRefObject<StreamGLHandle | null>,
handleRef,
() => ({
push(x: number, y: number) {
if (!Number.isFinite(x) || !Number.isFinite(y)) {
Expand Down Expand Up @@ -343,11 +347,33 @@ function StreamGLCanvas({
*
* @example
* ```
* // Object ref: push data points in a rAF loop or event handler.
* const streamRef = useRef<StreamGLHandle>(null);
* // Push data points in a rAF loop or event handler:
* streamRef.current?.push(Date.now(), value);
*
* <Chart series={[streamGL({color: '#10b981', handleRef: streamRef})]} />
*
* // 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<StreamGLHandle | null>(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);
* };
*
* <Chart series={[streamGL({color: '#10b981', handleRef: attach})]} />
* ```
*/
export function streamGL(options: StreamGLOptions): SeriesDef {
Expand Down