Skip to content

Add environment-safe chart barrels #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
tannerlinsley wants to merge 1 commit into
base: main
Choose a base branch
from
+585 −213
Open

Add environment-safe chart barrels #8

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
26 changes: 26 additions & 0 deletions API-FRICTION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -176,6 +176,7 @@ Each entry records:
| F-138 | Publisher pin predated explicit trust permissions | Tooling/Release | resolved |
| F-139 | Top-level entries bypassed tarball validation | Tooling/Release | resolved |
| F-140 | Behavior config could erase responsive datum inference | API | monitoring |
| F-141 | Root barrels crossed the browser host boundary | API/Tooling | resolved |

## Findings

Expand Down Expand Up @@ -3394,3 +3395,28 @@ Each entry records:
- Follow-up: add a focused type regression for the single-call form and decide
whether its overload can retain builder datum inference without making
behavior ownership ambiguous.

### F-141 — Root barrels crossed the browser host boundary

- Status: resolved
- Severity: high
- Owner: API/Tooling
- Observed in: isolating the React Native host proof from the core package
- Friction: shared chart definitions and scene compilation are
platform-neutral, but the root value barrel made bundlers traverse DOM hosts,
adapters, reconciliation, and SVG surfaces. Its type graph also declared
`Element`, `HTMLElement`, and `SVGSVGElement`, so a non-DOM consumer could
not select the portable contracts as one supported entry.
- Decision: preserve the existing browser-oriented root API and add
`@tanstack/charts/portable` for common authoring/runtime values plus
`@tanstack/charts/types` for portable contracts. DOM surface, renderer, host,
and render-context types now live behind an internal module while retaining
their existing root re-exports. Do not conditionally change the root until a
native host can test one coherent platform contract.
- Verification: root typechecking and 61 focused core tests pass. The packed
package gate resolves both new entries from `dist`, compiles their
declarations with Web Worker rather than DOM globals, and proves the
portable bundle excludes the root, adapters, Canvas, DOM host/text, browser
export, reconciliation, renderer, and SVG surface modules. That full
portable barrel measures 55.26 kB minified and 17.04 kB gzip; granular
subpaths remain the bundle-sensitive option.
15 changes: 14 additions & 1 deletion docs/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,7 +135,20 @@ import { mountChart } from '@tanstack/charts/dom'
import { renderChartSvg } from '@tanstack/charts/svg'
```

Subpaths are not a second API. They expose the same functions without making unrelated marks, the DOM host, exporters, or framework code reachable from that entry.
Use the portable barrel when definitions and scene compilation must not make
the browser host reachable:

```ts
import {
createChartRuntime,
defineChart,
lineY,
} from '@tanstack/charts/portable'
import type { ChartDefinition } from '@tanstack/charts/types'
```

The root remains the browser-oriented compatibility entry. Subpaths expose the
same contracts behind explicit capability boundaries.

Optional capabilities have explicit entries:

Expand Down
5 changes: 4 additions & 1 deletion docs/reference/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,8 @@ select the optional Canvas renderer; their `/core` entries require an explicit
## Import map

The root `@tanstack/charts` entry point exports the common grammar, runtime,
scene, SVG renderer, and their public types. Granular subpaths keep optional
scene, SVG renderer, browser host, and their public types. The portable entry
excludes browser hosts and adapters. Granular subpaths keep optional
capabilities and individual marks independently tree-shakeable.

| Import | Public values |
Expand Down Expand Up @@ -86,6 +87,7 @@ capabilities and individual marks independently tree-shakeable.
| `@tanstack/charts/link` | `link` |
| `@tanstack/charts/mark/scale-values` | `createMarkWithScaleValues` |
| `@tanstack/charts/polar` | `polar`, radial arc/line/area/dot marks, and radial/angle guides |
| `@tanstack/charts/portable` | Common root authoring, runtime, scene, and static SVG values without browser hosts or adapters |
| `@tanstack/charts/reconcile` | `reconcileChartSvg` |
| `@tanstack/charts/rect` | `rect`, `cell` |
| `@tanstack/charts/renderer` | `mountChartRenderer` |
Expand All @@ -97,6 +99,7 @@ capabilities and individual marks independently tree-shakeable.
| `@tanstack/charts/svg/resources` | `renderChartSvgWithResources` |
| `@tanstack/charts/text` | `text` |
| `@tanstack/charts/tick` | `tickX`, `tickY` |
| `@tanstack/charts/types` | Portable definition, mark, scene, runtime, focus, and tooltip-model types |
| `@tanstack/charts/vector` | `vector` |

Import from the narrowest stable entry point when bundle isolation matters.
Expand Down
5 changes: 5 additions & 0 deletions docs/reference/types.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,11 @@ flow through its definition into scales, axis formatters, host and adapter
callbacks, focus callbacks, and selection callbacks. Normal application code
should not cast chart definitions or supply adapter generics.

Browser applications can import types from the package root. Platform-neutral
libraries can import the same definition, mark, scene, runtime, focus, and
tooltip-model contracts from `@tanstack/charts/types`; DOM host and renderer
types remain available from the root.

## Values and channels

```ts
Expand Down
15 changes: 14 additions & 1 deletion packages/charts-core/docs/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,7 +135,20 @@ import { mountChart } from '@tanstack/charts/dom'
import { renderChartSvg } from '@tanstack/charts/svg'
```

Subpaths are not a second API. They expose the same functions without making unrelated marks, the DOM host, exporters, or framework code reachable from that entry.
Use the portable barrel when definitions and scene compilation must not make
the browser host reachable:

```ts
import {
createChartRuntime,
defineChart,
lineY,
} from '@tanstack/charts/portable'
import type { ChartDefinition } from '@tanstack/charts/types'
```

The root remains the browser-oriented compatibility entry. Subpaths expose the
same contracts behind explicit capability boundaries.

Optional capabilities have explicit entries:

Expand Down
5 changes: 4 additions & 1 deletion packages/charts-core/docs/reference/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,8 @@ select the optional Canvas renderer; their `/core` entries require an explicit
## Import map

The root `@tanstack/charts` entry point exports the common grammar, runtime,
scene, SVG renderer, and their public types. Granular subpaths keep optional
scene, SVG renderer, browser host, and their public types. The portable entry
excludes browser hosts and adapters. Granular subpaths keep optional
capabilities and individual marks independently tree-shakeable.

| Import | Public values |
Expand Down Expand Up @@ -86,6 +87,7 @@ capabilities and individual marks independently tree-shakeable.
| `@tanstack/charts/link` | `link` |
| `@tanstack/charts/mark/scale-values` | `createMarkWithScaleValues` |
| `@tanstack/charts/polar` | `polar`, radial arc/line/area/dot marks, and radial/angle guides |
| `@tanstack/charts/portable` | Common root authoring, runtime, scene, and static SVG values without browser hosts or adapters |
| `@tanstack/charts/reconcile` | `reconcileChartSvg` |
| `@tanstack/charts/rect` | `rect`, `cell` |
| `@tanstack/charts/renderer` | `mountChartRenderer` |
Expand All @@ -97,6 +99,7 @@ capabilities and individual marks independently tree-shakeable.
| `@tanstack/charts/svg/resources` | `renderChartSvgWithResources` |
| `@tanstack/charts/text` | `text` |
| `@tanstack/charts/tick` | `tickX`, `tickY` |
| `@tanstack/charts/types` | Portable definition, mark, scene, runtime, focus, and tooltip-model types |
| `@tanstack/charts/vector` | `vector` |

Import from the narrowest stable entry point when bundle isolation matters.
Expand Down
5 changes: 5 additions & 0 deletions packages/charts-core/docs/reference/types.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,11 @@ flow through its definition into scales, axis formatters, host and adapter
callbacks, focus callbacks, and selection callbacks. Normal application code
should not cast chart definitions or supply adapter generics.

Browser applications can import types from the package root. Platform-neutral
libraries can import the same definition, mark, scene, runtime, focus, and
tooltip-model contracts from `@tanstack/charts/types`; DOM host and renderer
types remain available from the root.

## Values and channels

```ts
Expand Down
10 changes: 10 additions & 0 deletions packages/charts-core/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,7 @@
"./link": "./src/link.ts",
"./mark/scale-values": "./src/mark-with-scale-values.ts",
"./polar": "./src/polar.ts",
"./portable": "./src/portable.ts",
"./reconcile": "./src/reconcile.ts",
"./rect": "./src/rect.ts",
"./renderer": "./src/renderer.ts",
Expand All @@ -65,6 +66,7 @@
"./svg/resources": "./src/svg-resources.ts",
"./text": "./src/text.ts",
"./tick": "./src/tick.ts",
"./types": "./src/portable-types.ts",
"./vector": "./src/vector.ts"
},
"publishConfig": {
Expand Down Expand Up @@ -167,6 +169,10 @@
"types": "./dist/polar.d.ts",
"import": "./dist/polar.js"
},
"./portable": {
"types": "./dist/portable.d.ts",
"import": "./dist/portable.js"
},
"./reconcile": {
"types": "./dist/reconcile.d.ts",
"import": "./dist/reconcile.js"
Expand Down Expand Up @@ -211,6 +217,10 @@
"types": "./dist/tick.d.ts",
"import": "./dist/tick.js"
},
"./types": {
"types": "./dist/portable-types.d.ts",
"import": "./dist/portable-types.js"
},
"./vector": {
"types": "./dist/vector.d.ts",
"import": "./dist/vector.js"
Expand Down
8 changes: 2 additions & 6 deletions packages/charts-core/src/adapter-renderer.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,8 @@ import { mountChartRenderer } from './renderer'
import { createChartRuntime } from './runtime'
import { resolveChartAdapterLayout } from './adapter-shared'
import type { ChartAdapter } from './adapter-shared'
import type {
ChartRendererHost,
ChartRendererHostOptions,
ChartRuntime,
ChartValue,
} from './types'
import type { ChartRendererHost, ChartRendererHostOptions } from './dom-types'
import type { ChartRuntime, ChartValue } from './types'

export function createChartRendererAdapter<
TDatum,
Expand Down
8 changes: 2 additions & 6 deletions packages/charts-core/src/adapter.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,8 @@ import { renderChartSvg } from './svg'
import { createSvgChartRenderer } from './svg-surface'
import { resolveChartAdapterLayout } from './adapter-shared'
import type { ChartAdapter } from './adapter-shared'
import type {
ChartHost,
ChartHostOptions,
ChartRuntime,
ChartValue,
} from './types'
import type { ChartHost, ChartHostOptions } from './dom-types'
import type { ChartRuntime, ChartValue } from './types'

export {
resolveChartAdapterLayout,
Expand Down
3 changes: 2 additions & 1 deletion packages/charts-core/src/canvas.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,8 @@ import {
} from './canvas'
import { lineY } from './line'
import { defineChart } from './scene'
import type { ChartScene, ChartSurfaceRenderOptions, SceneNode } from './types'
import type { ChartSurfaceRenderOptions } from './dom-types'
import type { ChartScene, SceneNode } from './types'

interface FakeCanvasContext {
operations: string[]
Expand Down
12 changes: 7 additions & 5 deletions packages/charts-core/src/canvas.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,18 @@
import { mountChartRenderer } from './renderer'
import { createChartRuntime } from './runtime'
import type {
ChartAnimationOptions,
ChartBounds,
ChartPoint,
ChartRenderer,
ChartRendererHost,
ChartRendererHostOptions,
ChartRuntime,
ChartScene,
ChartSurface,
ChartSurfaceRenderOptions,
} from './dom-types'
import type {
ChartAnimationOptions,
ChartBounds,
ChartPoint,
ChartRuntime,
ChartScene,
ChartValue,
SceneNode,
SceneStyle,
Expand Down
Loading
Loading