@antadesign/anta 0.3.33 → 0.3.34

package/docs/install-config.md

@@ -9,55 +9,127 @@ npm install @antadesign/anta   # or pnpm / bun
 Pin an exact version in `package.json` (`"@antadesign/anta": "0.3.16"`) instead
 of a floating tag such as `"latest"`.
 
-### Usage
+### Full bundle
+
+Use the full bundle as the default setup. Import the JavaScript entry and its
+stylesheet in your browser app entry:
 
 ```tsx
-import '@antadesign/anta/tokens.css'  // CSS custom properties
-import '@antadesign/anta/reset.css'   // reset and typography defaults
-import '@antadesign/anta/elements'    // registers <a-*> elements
-import '@antadesign/anta/theme-antune.css' // optional Antune theme
-import { Progress } from '@antadesign/anta'
+import '@antadesign/anta/bundle.css'
+import { Progress } from '@antadesign/anta/bundle'
 
 <Progress value={42} label="Uploaded" hint="3 of 7" />
 ```
 
-### Full bundle
+`bundle` registers every custom element and exports the JSX wrappers.
+`bundle.css` contains global tokens, the reset, element styles, and composed
+wrapper styles. The JavaScript bundle does not import this stylesheet, so keep
+both imports. Its React peer dependency and Preact configuration are the same
+as the regular JSX entry.
+
+Use this pair together. Adding granular element imports also loads their CSS,
+duplicating rules already in `bundle.css`.
 
-For a single minified Anta runtime and stylesheet, use the bundle pair instead
-of the separate tokens, reset, elements, and JSX imports:
+### Granular usage (advanced)
+
+Use granular imports to choose which browser elements and styles your app loads,
+or to render JSX on a server or in a worker. Load shared tokens once, optionally
+include the reset, and import the element entries you use:
 
 ```tsx
-import '@antadesign/anta/bundle.css'
-import { Progress } from '@antadesign/anta/bundle'
+import '@antadesign/anta/tokens.css'
+import '@antadesign/anta/reset.css'
+import '@antadesign/anta/elements/a-progress'
+import '@antadesign/anta/elements/a-title'
+import '@antadesign/anta/elements/a-tag'
+import { Progress, Title, Tag } from '@antadesign/anta'
+
+<>
+  <Title>Uploads</Title>
+  <Progress value={42} label="Uploaded" hint="3 of 7" />
+  <Tag>In progress</Tag>
+</>
+```
 
-<Progress value={42} label="Uploaded" hint="3 of 7" />
+Each element entry imports its own CSS for your bundler to include and registers
+its browser class when needed. Title and Tag load only CSS; they have no custom
+element class to register. Element entries do not import global tokens or the reset.
+
+JSX wrappers produce `<a-*>` tags and attributes. They do not register browser
+elements or import CSS. Load element entries in the browser's UI thread;
+see [Registering elements](#registering-elements) for server and worker rendering.
+
+Composed components have CSS-only entries for their layout styles:
+
+| JSX wrapper | UI-side style entry |
+|---|---|
+| `Breadcrumbs` | `@antadesign/anta/elements/a-breadcrumbs` |
+| `Steps` | `@antadesign/anta/elements/a-steps` |
+| `InputDate` | `@antadesign/anta/elements/a-input-date` |
+| `Select` | `@antadesign/anta/elements/a-select` |
+| `SelectFaceted` | `@antadesign/anta/elements/a-select-faceted` |
+
+These entries load layout CSS without registering a class or loading nested
+elements. Import the browser elements used by the composition too. For example,
+`Steps` uses Tabs and Tooltip, and may render icons, loaders, or panels depending
+on its props:
+
+```ts
+// Browser UI entry, alongside shared tokens and the optional reset.
+import '@antadesign/anta/elements/a-steps'
+import '@antadesign/anta/elements/a-tabs'
+import '@antadesign/anta/elements/a-tab'
+import '@antadesign/anta/elements/a-tabpanel'
+import '@antadesign/anta/elements/a-tooltip'
+import '@antadesign/anta/elements/a-icon'
+import '@antadesign/anta/elements/a-loader'
 ```
 
-`bundle` registers every custom element and re-exports the JSX API. Its React
-peer dependency and Preact configuration are the same as the regular JSX entry.
+Import `Steps` from `@antadesign/anta` where you render JSX, including in a worker
+or on the server. Select and SelectFaceted share one stylesheet, which bundlers
+include once when both style entries are imported.
 
-### What you import (and why)
+To load all elements through the separate entries, replace the per-element imports
+with `import '@antadesign/anta/elements'`. Keep the tokens and optional reset.
 
-Tokens, elements, and the JSX layer render a styled component. The reset is
-recommended; the reference theme is optional.
+Individual stylesheets are also exported for direct CSS imports. With a bundler
+that supports `?raw`, you can read a stylesheet as text:
 
-| Import | Provides | Skip if… |
-|---|---|---|
-| `@antadesign/anta/tokens.css` | Six seed tokens, derived role scales (`--bg-1…5`, `--text-1…5`, `--border-1…5`), `.dark` and its `color-scheme`, the 15px root size, and layer order. Override a seed to reskin its tone. | You provide those variables. |
-| `@antadesign/anta/reset.css` | A small reset plus Anta's focus, heading, list, and link typography in `@layer anta.reset`. | You use another reset and typography. |
-| `@antadesign/anta/elements` | Registers every `<a-*>` element and its CSS. Per-element entries register one; see [Registering elements](#registering-elements). | You render only on the server or register elements individually. |
-| `@antadesign/anta` | Typed React/Preact wrappers such as `Progress`, `Text`, and `Icon`. | You write `<a-*>` elements directly. |
-| `@antadesign/anta/bundle.css` | One minified stylesheet containing tokens, reset, element, and JSX-wrapper styles. | You want granular CSS imports. |
-| `@antadesign/anta/bundle` | One minified ESM runtime that registers every `<a-*>` element and re-exports the JSX API. | You want granular JS imports. |
-| `@antadesign/anta/theme-antune.css` *(optional)* | Antune, the hand-tuned reference palette. Import last to replace the seed-derived default. | You want the seed-derived or your own palette. |
-| `@antadesign/anta/theme-antithesis.css` *(optional)* | Antithesis: warm color seeds, pill buttons, square text fields, and `1px` tag corners. Import as the only theme. | You want Antune, the seed-derived palette, or your own theme. |
+```ts
+import titleCss from '@antadesign/anta/elements/a-title.css?raw'
+```
 
-Load `tokens.css` before element CSS. Elements read its variables; without it,
-they render unstyled.
+This returns CSS text; it does not apply styles or register an element.
 
-To use the optional reference palette, import `theme-antune.css` after the element
-registration import. It ships in `@antadesign/anta`; omit it to keep the
-seed-derived default palette or provide your own theme.
+### Optional theme
+
+Add one optional theme after either the full bundle CSS or the granular styles:
+
+```ts
+import '@antadesign/anta/theme-antune.css'
+```
+
+Use `theme-antithesis.css` for Antithesis, or omit both themes to keep the
+seed-derived default palette. These theme files do not load fonts. Choose fonts
+separately; see [Fonts](#fonts).
+
+### What you import (and why)
+
+| Import | Provides |
+|---|---|
+| `@antadesign/anta/bundle` | All browser element definitions and the JSX API in one minified ESM runtime. |
+| `@antadesign/anta/bundle.css` | Global tokens, reset, element, and composed wrapper styles in one minified stylesheet. |
+| `@antadesign/anta/tokens.css` | Shared color roles, fonts, dark-mode support, and layer order for granular usage. |
+| `@antadesign/anta/reset.css` | Optional reset and typography defaults in `@layer anta.reset`. |
+| `@antadesign/anta/elements/a-*` | One element's behavior and CSS, or CSS alone for structural tags and composed layouts. |
+| `@antadesign/anta/elements` | All browser element definitions, element styles, and composed layout styles through separate modules. |
+| `@antadesign/anta` | Typed JSX wrappers for React, Preact, and configured runtimes, without CSS or element registration. |
+| `@antadesign/anta/elements/*.css` | Individual stylesheets without element registration. |
+| `@antadesign/anta/theme-antune.css` | Optional Antune theme. |
+| `@antadesign/anta/theme-antithesis.css` | Optional Antithesis theme. |
+
+With granular usage, include `tokens.css` before element styles unless your app
+provides those variables. Elements depend on them for their default appearance.
 
 ### Cascade layers
 
@@ -121,71 +193,176 @@ and your installed Anta version. Web documentation may describe a newer release.
 
 ## Registering elements
 
-JSX wrappers render `<a-*>` tags. Register their classes before those tags reach
-the DOM. Registration needs `HTMLElement`, so the import is a no-op in Node.js
-and Worker threads.
+JSX wrappers render `<a-*>` tags. Load their browser definitions and styles in
+the UI thread before rendering or hydrating those tags. For full bundle usage,
+and hooks:
 
 ```ts
-import '@antadesign/anta/elements'  // auto-registers all elements
+// src/main.tsx (or wherever your root render lives)
+import '@antadesign/anta/bundle.css'
+import '@antadesign/anta/bundle'
+import { createRoot } from 'react-dom/client'
+import App from './App'
+createRoot(document.getElementById('root')!).render(<App />)
 ```
 
-`/elements` registers everything. Per-element entries register one element and
-load only its CSS:
+The JavaScript bundle registers all browser elements. With granular usage, load
+shared tokens, the optional reset, and the entries your app uses:
 
 ```ts
-import '@antadesign/anta/elements/a-tooltip'  // only <a-tooltip> + its CSS
-import '@antadesign/anta/elements/a-button'   // only <a-button> + its CSS
+import '@antadesign/anta/tokens.css'
+import '@antadesign/anta/reset.css'
+import '@antadesign/anta/elements/a-tooltip'  // <a-tooltip> behavior and CSS
+import '@antadesign/anta/elements/a-button'   // <a-button> behavior and CSS
+import '@antadesign/anta/elements/a-title'    // Title CSS only
+import '@antadesign/anta/elements/a-tag'      // Tag CSS only
 ```
 
-Both are idempotent, side-effect imports and safe during SSR.
+To load all browser elements and layout styles, replace the individual element
+imports with `import '@antadesign/anta/elements'`. Keep the shared tokens and
+optional reset. Registration is idempotent and guarded when `customElements`
+is unavailable. CSS imports need a bundler that handles stylesheets.
 
-Use a static import in your app entry, outside components and hooks:
+Static imports register classes before the app's first client render or
+hydration. Server-rendered HTML can paint before the browser loads JavaScript;
+load its CSS with the initial document, as in the Next.js setup below.
 
-```ts
-// src/main.tsx (or wherever your root render lives)
-import '@antadesign/anta/elements'
-import { createRoot } from 'react-dom/client'
-import App from './App'
-createRoot(document.getElementById('root')!).render(<App />)
-```
-
-Module initialisation registers the classes before the first render, avoiding a
-flash of un-upgraded elements.
-
-> **Why not `useEffect(() => import('@antadesign/anta/elements'), [])`?**
-> `useEffect` runs after paint and the import resolves later. The browser can
-> paint unregistered elements first. `useLayoutEffect` is still asynchronous and
-> warns during SSR hydration.
+> Loading elements in `useEffect` can delay registration until after paint. The
+> dynamic import resolves later, so unregistered elements can appear first.
+> Moving the dynamic import into `useLayoutEffect` still leaves the import
+> asynchronous. Use a static import at the top of the UI entry.
 
 Choose the entry point for your runtime:
 
-- **Plain HTML or static sites:** a `<script type="module">` in the document head.
-- **Astro or Next.js:** a client-only script. In Astro, use
-  `<script>import '@antadesign/anta/elements'</script>`; in Next.js, import it
-  from a `'use client'` file.
+- **Plain HTML or static sites:** a module entry processed by a bundler that
+  handles CSS imports; see [Raw web components](#raw-web-components-no-jsx).
+- **Astro:** import the runtime in an Astro-processed `<script>` and the CSS in
+  your layout. For full bundle usage, use `bundle` and `bundle.css`.
+- **Next.js:** import the runtime from a `'use client'` file and the CSS from
+  your root layout; see [Next.js](#nextjs).
 - **Worker-rendered UI:** code that runs on the UI thread and initializes the
   DOM. A Worker has no `HTMLElement`.
 
+### Server and worker rendering
+
+Import JSX wrappers in the code that renders your UI:
+
+```tsx
+// Server or worker
+import { Button, Title } from '@antadesign/anta'
+```
+
+Load the matching browser definitions and styles in a separate UI entry:
+
+```ts
+// Browser UI thread
+import '@antadesign/anta/tokens.css'
+import '@antadesign/anta/reset.css'
+import '@antadesign/anta/elements/a-button'
+import '@antadesign/anta/elements/a-title'
+```
+
+Rendering a JSX wrapper does not register its browser element. Raw `<a-*>`
+markup uses the same browser entries and can omit the JSX wrappers.
+For a custom JSX runtime, call `configure()` in the process or thread that
+renders the wrappers; see [Framework setup](#framework-setup).
+
 ## Framework setup
 
 ### React
 
-Works out of the box.
+React needs no `configure()` call. Load the JavaScript and CSS entries for your
+chosen import strategy before rendering.
+
+### Next.js
+
+For the full bundle setup, import its stylesheet in the App Router root layout:
+
+```tsx
+// app/layout.tsx
+import '@antadesign/anta/bundle.css'
+import type { ReactNode } from 'react'
+
+export default function Layout({ children }: { children: ReactNode }) {
+  return <html lang="en"><body>{children}</body></html>
+}
+```
+
+Import the runtime and JSX wrappers in a Client Component:
+
+```tsx
+// app/page.tsx
+'use client'
+
+import { useState } from 'react'
+import { Button, Title } from '@antadesign/anta/bundle'
+
+export default function Page() {
+  const [count, setCount] = useState(0)
+  return <>
+    <Title>Anta in Next.js</Title>
+    <Button label={`Count: ${count}`} onClick={() => setCount(value => value + 1)} />
+  </>
+}
+```
+
+Next.js prerenders Client Components on the server for the initial page load.
+`'use client'` marks the client/server module boundary; it does not disable
+server rendering. Anta guards element registration when browser APIs are absent
+and registers the elements when the client module runs before hydration.
+
+For granular usage, replace the layout's bundle stylesheet with shared tokens
+and the optional reset:
+
+```ts
+// app/layout.tsx imports
+import '@antadesign/anta/tokens.css'
+import '@antadesign/anta/reset.css'
+```
+
+Keep the same page component and replace its imports with:
+
+```ts
+// app/page.tsx
+'use client'
+
+import { useState } from 'react'
+import '@antadesign/anta/elements/a-button'
+import '@antadesign/anta/elements/a-title'
+import { Button, Title } from '@antadesign/anta'
+```
+
+Both setups work with Next.js's default Turbopack bundler.
 
 ### Preact with compat
 
-If your bundler aliases `react` to `preact/compat`, Anta works without setup.
+If your bundler aliases `react` to `preact/compat`, Anta needs no `configure()`
+call. Load the entries for your chosen import strategy. The Vite Preact preset
+provides these runtime aliases.
 
 ### Preact without compat
 
-Call `configure()` before rendering any anta components:
+If `react` is not aliased to `preact/compat`, pass Preact's JSX factory and hooks
+to `configure()` before rendering Anta components. For full bundle usage:
 
 ```ts
-import { configure } from '@antadesign/anta'
+import '@antadesign/anta/bundle.css'
+import { configure } from '@antadesign/anta/bundle'
 import { h, Fragment } from 'preact'
-configure(h, Fragment)
+import { useState, useId, useMemo, useRef, useLayoutEffect } from 'preact/hooks'
+import { useSyncExternalStore } from 'preact/compat'
+
+configure(h, Fragment, {
+  useState, useId, useMemo, useRef, useLayoutEffect, useSyncExternalStore,
+})
 ```
 
+Import JSX wrappers from `@antadesign/anta/bundle` with this setup. For granular
+usage, import both `configure` and the wrappers from `@antadesign/anta` and load
+the UI entries separately. The root package and the prebuilt bundle each have
+their own renderer configuration, so use `configure` from the same entry as
+your wrappers. The explicit `preact/compat` hook import does not require an alias.
+
 ### TypeScript: typing raw `<a-*>` tags in JSX
 
 JSX wrappers such as `<Button>` and `<Progress>` need no extra typing. Configure
@@ -233,43 +410,69 @@ upgrades; there is no per-tag list to maintain.
 
 ### Raw web components (no JSX)
 
-Elements also work in plain HTML. Registration loads their CSS; resolve the bare
-specifier with a bundler or import map.
+Elements also work in plain HTML without JSX wrappers. This example requires a
+bundler that processes module scripts and CSS imports:
 
 ```html
 <script type="module">
-  import '@antadesign/anta/elements'
+  import '@antadesign/anta/tokens.css'
+  import '@antadesign/anta/reset.css'
+  import '@antadesign/anta/elements/a-progress'
 </script>
 
 <a-progress value="42" max="100" tone="info"></a-progress>
 ```
 
+An import map resolves module names but does not process the plain CSS imports
+in Anta's element entries. When serving native modules without a bundler, use
+a separately prepared JavaScript entry and linked stylesheets.
+
 ## Dark mode
 
-For a page-wide dark mode, add `dark` to `html`. The `body` `--bg-2` background
-then paints the browser canvas, and the root controls scrollbar colors:
+For a page-wide dark mode, add `dark` to `html`. Shared tokens switch the palette
+and root color scheme, including scrollbar colors. The reset, included in
+`bundle.css` or loaded separately as `reset.css`, paints `body` with `--bg-2`:
 
 ```html
 <html class="dark">
   <body>
-    <Progress value={50} />
+    <a-progress value="50"></a-progress>
   </body>
 </html>
 ```
 
 Use `dark` or `light` on another ancestor to scope its color scheme and palette.
+If you omit the reset, set your app's background and text color in your own CSS,
+for example with `--bg-2` and `--text-2`.
 
 ## Fonts
 
-Without an optional theme, `tokens.css` defines system stacks in `--sans-serif`,
-`--serif`, and `--monospace`. Reference themes register hosted fonts and replace
-some of those same variables. Components and theme rules decide which stack to
-use. Theme-free components do not force font-specific stylistic sets or
-variable-font axes. `tokens.css` also sets `1rem` to 15px.
+Anta works with system fonts without any font downloads. `tokens.css`, also
+included in `bundle.css`, defines system stacks in `--sans-serif`, `--serif`,
+and `--monospace`, and sets `1rem` to 15px. The optional themes keep those stacks
+and do not register font faces or request font files. Components and theme rules
+choose which stack to use.
+
+Use fonts from Google Fonts or host font files in your application. Manage font
+loading in a separate application stylesheet such as `fonts.css`, and import it
+after the Anta styles and optional theme:
+
+```ts
+import '@antadesign/anta/bundle.css'
+import '@antadesign/anta/theme-antune.css' // Optional
+import './fonts.css'
+```
 
-Register application-owned fonts and redefine the variables in CSS loaded after
-the Anta styles and optional theme. This example uses separate Roman and Italic
-variable files:
+With granular usage, load `fonts.css` after `tokens.css`, your element styles,
+and the optional theme. Anta.design also loads its reference fonts through a
+separate stylesheet. That setup is an example, and is not imported by the
+package. See [Font examples](./theming.md#fonts-in-a-theme) for that setup and
+Google Fonts examples.
+
+Register your fonts and override only the stacks you want to change. Keep
+fallback families after each custom font name. This `fonts.css` example uses
+separate Roman and Italic variable files and keeps the default serif and
+monospace stacks:
 
 ```css
 @font-face {
@@ -277,6 +480,7 @@ variable files:
   src: url("/fonts/app-sans-roman.woff2") format("woff2");
   font-style: normal;
   font-weight: 100 900;
+  font-display: swap;
 }
 
 @font-face {
@@ -284,19 +488,22 @@ variable files:
   src: url("/fonts/app-sans-italic.woff2") format("woff2");
   font-style: italic;
   font-weight: 100 900;
+  font-display: swap;
 }
 
 :root {
-  --sans-serif: "App Sans", sans-serif;
-  --serif: Georgia, serif;
-  --monospace: ui-monospace, monospace;
+  --sans-serif: "App Sans", system-ui, -apple-system, "Segoe UI", sans-serif;
 }
 ```
 
-Place this application stylesheet after `theme-antune.css` or
-`theme-antithesis.css`, not before it. When all stylesheets are in the document
-head, the override applies before the first paint. Anta's semantic italics
-(`em`, `i`, `var`, and `dt`) select the Italic face.
+[Font display](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/font-display)
+with `swap` shows fallback text while the custom font loads, then switches to
+that font when it is ready. If the font fails to load, the browser keeps using a
+fallback family. The variables remain valid in either case.
+
+Anta's reset styles semantic italics (`em`, `i`, `var`, and `dt`) to select the
+Italic face. If you omit the reset, your application or the browser's default
+rules provide those styles.
 
 ### Variable slant
 
@@ -310,6 +517,7 @@ through `font-style: oblique` instead of setting `slnt` on italic elements:
   font-style: oblique 0deg 12deg;
   font-weight: 100 900;
   font-stretch: 75% 100%;
+  font-display: swap;
 }
 
 :root {

package/docs/packages/plot.md

@@ -680,7 +680,7 @@ Scatter arguments
 | `x?` | [`FieldArg`](#data-fields) | `'x'` | Horizontal field name or accessor. |
 | `y?` | [`FieldArg`](#data-fields) | `'y'` | Vertical field name or accessor. |
 | `color?` | [`ColorArg`](#series-colors) | Black | Series color; theme pairs provide separate light and dark colors. |
-| `size?` | `number \| ((row, index) => number)` | `5` | Mark diameter in pixels, or a per-row accessor. A row’s `size` takes precedence. |
+| `size?` | `number \| ((row, index, viewport) => number)` | `5` | [Mark diameter](#size) in pixels, or a per-row accessor. A row’s `size` takes precedence. |
 | [`mark?`](#mark-shapes) | `MarkShape` | `'circle'` | Mark shape: circle, square, diamond, or triangle. |
 | [`stroke?`](#strokes) | `StrokeArg` | None | Outline color and optional width. |
 | [`tooltip?`](#tooltips) | `TooltipArg` | None | Use `true` for the default tooltip, or a callback for custom content. |
@@ -3086,6 +3086,7 @@ to continuous axes.
 |---|---|---|
 | `x` | `AxisViewport \| null` | Current horizontal viewport, or `null` for a categorical axis. |
 | `y` | `AxisViewport \| null` | Current vertical viewport, or `null` for a categorical axis. |
+| `zoom_factor` | `{ x: number; y: number }` | Per-axis gesture magnification, initially 1; preserved during pan, resize, and data-domain changes. |
 
 Each `AxisViewport` contains:
 
@@ -3096,6 +3097,68 @@ Each `AxisViewport` contains:
 
 ## Configuration details
 
+### Size
+
+Scatter `size` accepts a fixed pixel diameter or a pure accessor returning a number.
+The accessor receives `(row, index, viewport)`, so you can combine data and viewport
+without storing zoom in application state.
+
+Hold **Ctrl** and scroll near **50**. The first series stays at 4px. The other series
+alternate between 2px and 4px based on their data, then grow with horizontal zoom,
+at different rates, up to 16px. Hold **Ctrl** and drag to pan; **Reset zoom** restores
+the starting sizes.
+
+```ts
+import { scatter, type PlotArgs } from '@antadesign/plot'
+import '@antadesign/plot/elements/a-plot'
+import type { APlotElement } from '@antadesign/plot/browser'
+
+export function viewportSizes(): PlotArgs<Node> {
+  const labels = ['Fixed 4px', 'Data + gradual zoom', 'Data + faster zoom']
+  const positions = [0, 10, 25, 40, 45, 48, 49, 49.5, 49.75, 50, 50.25, 50.5, 51, 52, 55, 60, 75, 90, 100]
+  const rows = (label: string) => positions.map((x, i) => ({ x, y: label, weight: i % 2 ? 4 : 2 }))
+  return {
+    height: 260,
+    margin: { top: 24, right: 20, bottom: 48, left: 160 },
+    axis: { x: { min: 0, max: 100, label: 'Zoom near 50' }, y: { categories: labels, label: '' } },
+    background: { light: '#ffffff', dark: '#202124' },
+    chrome_color: { light: '#64748b', dark: '#cbd5e1' },
+    grid: false,
+    zoom_pan: { x: true, y: false, modifier: true },
+    series: [
+      scatter<Node>({ data: rows(labels[0]), size: 4,
+        color: { light: '#64748b', dark: '#cbd5e1' }, tooltip: true }),
+      scatter<Node>({ data: rows(labels[1]),
+        size: (row, index, viewport) => Math.min(16, Number(row.weight) * viewport.zoom_factor.x ** 0.25),
+        color: { light: '#7c3aed', dark: '#c4b5fd' }, tooltip: true }),
+      scatter<Node>({ data: rows(labels[2]),
+        size: (row, index, viewport) => Math.min(16, Number(row.weight) * viewport.zoom_factor.x ** 0.5),
+        color: { light: '#c2410c', dark: '#fdba74' }, tooltip: true }),
+    ],
+  }
+}
+
+const plot = document.createElement('a-plot') as APlotElement
+plot.plotArgs = viewportSizes()
+document.body.append(plot)
+```
+
+`viewport` has the same shape as [Viewport changes](#viewport-changes): `x` and `y`
+contain visible and full domains (`null` for a categorical axis), and `zoom_factor.x` and
+`zoom_factor.y` contain gesture magnification. Each starts at 1. Panning, resizing, and
+data-domain changes preserve magnification. Reset and new keyed viewport requests
+establish factor 1 on their affected axes. Zooming out beyond a requested initial
+window can yield factors below 1. Use `Math.max(viewport.zoom_factor.x, viewport.zoom_factor.y)`
+to follow the more magnified axis.
+
+Size accessors run during composition, including zoom and pan, rather than when
+the series is constructed. Keep them pure and inexpensive. Existing accessors
+that only read the row or index remain valid. Returned sizes must be finite and
+non-negative; invalid results report a composition error and retain the previous
+plot. Numeric row `size` fields take precedence, and the index stays tied to the
+original input row after category filtering. Drawing, hit testing, and highlights
+reuse the composed sizes. Other series' size options and font sizes remain numeric.
+
 ### Font
 
 `font` on the plot supplies shared text settings. `title.font`,

package/docs/theming.md

@@ -14,7 +14,8 @@ import '@antadesign/anta/theme-antune.css' // Choose one theme included in the p
 
 ## Fonts in a theme
 
-Without a reference theme, `tokens.css` defines three system font stacks:
+Anta's themes do not load fonts. `tokens.css` defines three system font stacks,
+which the optional themes preserve:
 
 ```css
 :root, .light {
@@ -27,14 +28,14 @@ Without a reference theme, `tokens.css` defines three system font stacks:
 ```
 
 Components and theme rules choose which variable to use. For example, body text
-can use `--sans-serif` while a particular title style uses `--serif`. Without a
-theme, Anta does not force font-specific stylistic sets or variable-font axes.
+can use `--sans-serif` while a particular title style uses `--serif`. Package
+styles do not force font-specific stylistic sets or variable-font axes.
 
-You can register your fonts and redefine the stacks in a custom theme stylesheet
-such as `theme.css`:
+Host your font files in your application and register them in a separate
+stylesheet such as `fonts.css`. Load it after Anta's styles and optional theme:
 
 ```css
-/* theme.css */
+/* fonts.css */
 @font-face {
   font-family: "App Sans";
   src: url("/fonts/app-sans.woff2") format("woff2");
@@ -50,13 +51,12 @@ such as `theme.css`:
 }
 ```
 
-The **Antune** and **Antithesis** themes included with Anta use custom fonts that
-require separate licenses. If your application does not have those licenses,
-redefine all three font variables as shown above.
+Alternatively, use the [Google Fonts CSS API](https://developers.google.com/fonts/docs/css2)
+to load your chosen families. This example includes regular and italic styles:
 
 ```css
-/* theme.css */
-@import url("https://fonts.googleapis.com/css2?family=Inter:wght@400;600&family=JetBrains+Mono:wght@400;600&family=Source+Serif+4:wght@400;600&display=swap");
+/* fonts.css: place @import before other rules. */
+@import url("https://fonts.googleapis.com/css2?family=Inter:ital,wght@0,400;0,600;1,400;1,600&family=JetBrains+Mono:ital,wght@0,400;0,600;1,400;1,600&family=Source+Serif+4:ital,wght@0,400;0,600;1,400;1,600&display=swap");
 
 :root {
   --sans-serif: "Inter", sans-serif;
@@ -65,8 +65,17 @@ redefine all three font variables as shown above.
 }
 ```
 
-After you redefine these three variables, the theme fonts are not used or
-downloaded (exactly what we want in this case).
+Choose the styles and weights your app uses. Loading Google Fonts makes requests
+to Google's servers; self-host font files when you need all assets on your own
+origin.
+
+The anta.design website loads its reference fonts through separate
+[Antune font CSS](https://anta.design/themes/fonts-antune.css) and
+[Antithesis font CSS](https://anta.design/themes/fonts-antithesis.css). These
+site stylesheets show the website's font-face declarations, font stacks, and
+font-specific axis settings. They are examples of application font setup and
+are not imported by the published themes. Use your own font stylesheet and
+font sources in your application.
 
 <a id="color-seeds"></a>