basalt-ui 1.27.0 → 1.28.0

package/src/charts/primitives/ChartFrame.tsx

@@ -1,10 +1,24 @@
 import type { CSSProperties, ReactNode } from 'react'
 import { useCallback, useState } from 'react'
+import type { BasaltProps } from '../../common/props'
+import { VX } from '../../tokens'
 import { useChartSize } from '../hooks/useChartSize'
 import { deriveLegend } from '../series'
 import type { ChartLegendConfig, LegendPlacement, SeriesStyle } from '../series'
+import {
+  chartTierMetrics,
+  legendEntryCap,
+  resolveChartTier,
+  resolvePlotRect,
+} from './chart-frame-layout'
+import { ChartTierProvider } from './chart-tier'
 import { ChartLegend } from './ChartLegend'
-import { ChartPending } from './ChartPending'
+import { ChartEmpty, ChartError, ChartPending, resolveChartState } from './ChartPending'
+import type { ChartState } from './ChartPending'
+
+/** Re-exported for `ChartFrame.test.tsx` and any other consumer that previously reached these
+ * through `ChartFrame` — the layout math itself lives in `./chart-frame-layout` (pure, DOM-free). */
+export { legendEntryCap, resolvePlotRect, resolveChartTier } from './chart-frame-layout'
 
 const DEFAULT_HEIGHT = 240
 const DEFAULT_MIN_WIDTH = 200
@@ -30,7 +44,7 @@ export type ChartFrameLegend = {
   toggle?: boolean
 }
 
-export type ChartFrameProps = {
+export type ChartFrameProps = BasaltProps & {
   /** Series identity — drives the derived legend. Pass the SAME array the kind draws + tooltips from. */
   series: readonly SeriesStyle[]
   /** Fixed height in pixels. Used when neither `aspectRatio` nor `fill` is set. Default 240. */
@@ -50,8 +64,19 @@ export type ChartFrameProps = {
    * three-state "nothing to draw" rationale) over the full plot rect in place of `children`,
    * suppresses the legend entirely (a legend naming a series with nothing yet to point at is its
    * own small lie), and marks the outer container `aria-busy="true"`.
+   *
+   * An alias for `state={{ pending: true }}` and staying that way — it predates {@link ChartState}
+   * and every kind forwards it.
    */
   isPending?: boolean
+  /**
+   * The three "nothing to draw" states in one prop — the shape a query result already has. Wins
+   * over `isPending`, which stays a supported alias for `state={{ pending: true }}`. Precedence is
+   * pending → error → empty ({@link resolveChartState}); each renders its own placeholder over the
+   * full plot rect in place of `children` and suppresses the legend, and only `pending` marks the
+   * container `aria-busy`.
+   */
+  state?: ChartState
   /**
    * Accessible text alternative for the chart, applied as `aria-label` (+ `role="group"`) on the
    * outer container so screen readers announce something other than an unlabeled graphic. Every
@@ -102,12 +127,22 @@ export type ChartFrameLegendHover = {
  * is the one merge every kind performs: consumer `placement`/`groups`/`maxRows` (or the defaults)
  * plus the kind's `highlighted`/`onHighlight`, which a consumer may not set directly.
  * `config === false` disables the legend regardless of `hover` (the sparkline escape).
+ *
+ * A single-entry legend is pure noise — it only ever restates the chart's own title ("— BTC
+ * price" under a chart already titled "BTC price"), costs a legend row of vertical space, and its
+ * one toggle can blank the whole plot. So when `seriesCount` is passed, is `<= 1`, AND the caller
+ * passed no explicit config (`undefined` — NOT `{}`, which is a deliberate opt-in), the legend is
+ * suppressed automatically. `config === undefined` is the load-bearing check: a kind that composes
+ * `ChartFrame` directly without threading `seriesCount` through (e.g. `DualPanel`) simply omits
+ * the third argument and keeps today's behaviour.
  */
 export function resolveLegend(
   config: ChartLegendConfig | false | undefined,
   hover?: ChartFrameLegendHover,
+  seriesCount?: number,
 ): ChartFrameLegend | false {
   if (config === false) return false
+  if (config === undefined && seriesCount !== undefined && seriesCount <= 1) return false
   return {
     placement: config?.placement ?? 'bottom',
     ...(config?.groups !== undefined && { groups: config.groups }),
@@ -124,7 +159,9 @@ export function resolveLegend(
  * rect via a second, independent `useChartSize` on the legend's own wrapper div. The legend
  * `<div>` wraps (`ChartLegend`'s `flexWrap`), so its measured band grows as entries wrap and the
  * plot shrinks accordingly — the plot can never overlap the legend because the legend's measured
- * band is always subtracted first.
+ * band is always subtracted first. It also can never shrink to nothing: {@link resolvePlotRect}
+ * floors it at `VX.minPlotHeight` and the frame grows, or under `fill` the legend rolls up
+ * ({@link legendEntryCap}).
  *
  * Layout-only: it does not know lines from bars (that stays in the kind), so it is not a
  * Recharts god-component. Render the child only when the resolved plot rect is non-empty.
@@ -139,6 +176,9 @@ export function ChartFrame({
   legend = {},
   ariaLabel,
   isPending = false,
+  state,
+  className,
+  style,
   children,
 }: ChartFrameProps): ReactNode {
   const { ref: containerRef, width: containerW, height: containerH } = useChartSize()
@@ -156,7 +196,11 @@ export function ChartFrame({
 
   const placement = legend === false ? 'bottom' : (legend.placement ?? 'bottom')
   const vertical = placement === 'left' || placement === 'right'
-  const legendVisible = legend !== false && !isPending
+  // Every non-null state replaces the plot, and all three suppress the legend for one reason: a
+  // legend naming a series with nothing to point at is its own small lie.
+  const resolvedState = resolveChartState({ ...(state !== undefined && { state }), isPending })
+  const legendVisible = legend !== false && resolvedState === null
+  const tier = resolveChartTier(containerW)
 
   const resolvedHeight = fill
     ? containerH
@@ -167,16 +211,46 @@ export function ChartFrame({
   const sideLegendWidth = legendVisible && vertical ? legendW : 0
   const topBottomLegendHeight = legendVisible && !vertical ? legendH : 0
 
-  const plot = {
-    width: Math.max(containerW - sideLegendWidth, minWidth),
-    height: resolvedHeight - topBottomLegendHeight,
-  }
+  const plot = resolvePlotRect({
+    containerW,
+    resolvedHeight,
+    minWidth,
+    sideLegendWidth,
+    topBottomLegendHeight,
+  })
 
   const legendItems = legend === false ? [] : deriveLegend(series)
   const togglable = legend !== false && (legend.toggle ?? legendItems.length > 1)
 
+  // A fixed-height frame grows around its legend; a `fill` one cannot, so its legend rolls up
+  // instead of eating the plot (see `legendEntryCap`). Top/bottom only — a side legend costs
+  // width, not height.
+  // The tier's own cap folds in as an upper bound BEFORE the fill measurement, so a phone-width
+  // `fill` frame can only ever roll up further, never less (`chartTierMetrics`).
+  const tierMaxRows = chartTierMetrics(tier).legendMaxRows
+  const callerMaxRows =
+    legend === false
+      ? undefined
+      : legend.maxRows === undefined
+        ? tierMaxRows
+        : tierMaxRows === undefined
+          ? legend.maxRows
+          : Math.min(legend.maxRows, tierMaxRows)
+
+  const maxRows =
+    legend === false
+      ? undefined
+      : fill && !vertical
+        ? legendEntryCap({
+            items: legendItems,
+            containerW,
+            available: resolvedHeight - VX.minPlotHeight,
+            ...(callerMaxRows !== undefined && { callerMaxRows }),
+          })
+        : callerMaxRows
+
   const legendNode =
-    legend === false || isPending ? null : (
+    legend === false || resolvedState !== null ? null : (
       <div ref={legendRef} style={legendWrapperStyle(vertical)}>
         <ChartLegend
           items={legendItems}
@@ -185,7 +259,7 @@ export function ChartFrame({
           {...(togglable && { onToggle: toggleKey })}
           {...(chartId !== undefined && { chartId })}
           {...(legend.groups !== undefined && { groups: legend.groups })}
-          {...(legend.maxRows !== undefined && { maxRows: legend.maxRows })}
+          {...(maxRows !== undefined && { maxRows })}
           {...(legend.highlighted !== undefined && { highlighted: legend.highlighted })}
           {...(legend.onHighlight !== undefined && { onHighlight: legend.onHighlight })}
         />
@@ -193,21 +267,28 @@ export function ChartFrame({
     )
 
   return (
-    <div
-      ref={containerRef}
-      style={outerStyle(fill, vertical)}
-      {...(ariaLabel !== undefined && { role: 'group', 'aria-label': ariaLabel })}
-      {...(isPending && { 'aria-busy': 'true' })}
-    >
-      {legendNode !== null && (placement === 'top' || placement === 'left') && legendNode}
-      {plot.width > 0 &&
-        plot.height > 0 &&
-        (isPending ? (
-          <ChartPending width={plot.width} height={plot.height} />
-        ) : (
-          children({ ...plot, hidden })
-        ))}
-      {legendNode !== null && (placement === 'bottom' || placement === 'right') && legendNode}
-    </div>
+    <ChartTierProvider tier={tier}>
+      <div
+        ref={containerRef}
+        {...(className !== undefined && { className })}
+        style={{ ...outerStyle(fill, vertical), ...style }}
+        {...(ariaLabel !== undefined && { role: 'group', 'aria-label': ariaLabel })}
+        {...(resolvedState === 'pending' && { 'aria-busy': 'true' })}
+      >
+        {legendNode !== null && (placement === 'top' || placement === 'left') && legendNode}
+        {plot.width > 0 &&
+          plot.height > 0 &&
+          (resolvedState === 'pending' ? (
+            <ChartPending width={plot.width} height={plot.height} />
+          ) : resolvedState === 'error' ? (
+            <ChartError width={plot.width} height={plot.height} error={state?.error} />
+          ) : resolvedState === 'empty' ? (
+            <ChartEmpty width={plot.width} height={plot.height} />
+          ) : (
+            children({ ...plot, hidden })
+          ))}
+        {legendNode !== null && (placement === 'bottom' || placement === 'right') && legendNode}
+      </div>
+    </ChartTierProvider>
   )
 }

package/src/charts/primitives/ChartLegend.tsx

@@ -1,6 +1,9 @@
 import type { CSSProperties, FocusEvent, MouseEvent, ReactNode } from 'react'
-import { VX, alpha } from '../../tokens'
+import { useState } from 'react'
+import type { BasaltProps } from '../../common/props'
+import { alpha, VX } from '../../tokens'
 import type { SeriesRole, LegendPlacement } from '../series'
+import { useChartTierMetrics } from './chart-tier'
 
 export type LegendEntry = {
   key: string
@@ -74,7 +77,7 @@ function orderEntries(
   return { entries, dividerAfter }
 }
 
-function wrapperStyle(placement: LegendPlacement): CSSProperties {
+function wrapperStyle(placement: LegendPlacement, fontSize: number): CSSProperties {
   const vertical = placement === 'left' || placement === 'right'
   return {
     display: 'flex',
@@ -85,7 +88,7 @@ function wrapperStyle(placement: LegendPlacement): CSSProperties {
     columnGap: VX.legendGap,
     rowGap: VX.legendGap,
     padding: '8px 0 2px',
-    fontSize: VX.legendFontSize,
+    fontSize,
     color: VX.muted,
   }
 }
@@ -258,7 +261,17 @@ function LegendChild({ item }: { item: LegendEntry }) {
  *
  * `onToggle` makes an entry a real toggle: clicking it hides the series in the plot, the tooltip,
  * and the auto y-domain together (`ChartFrame` owns the `hidden` set — see `docs/CHARTS-SPEC.md`
- * §5). Omit it for a static legend; a hidden entry is announced via `aria-pressed`.
+ * §5).
+ *
+ * The label font and the DEFAULT entry cap both track the ambient chart tier (§8): inside a
+ * phone-width `ChartFrame` the legend drops one type step and rolls up past two entries. An
+ * explicit `maxRows` always wins. Omit it for a static legend; a hidden entry is announced via `aria-pressed`.
+ *
+ * **The rollup is a disclosure, not a label.** A cap of two leaves six of eight plotted colours
+ * unnamed, and a `+6 more` that is a `<span>` gives a phone reader no way to learn them — a
+ * categorical encoding the chart draws and refuses to decode. The chip is a `<button>` carrying
+ * `aria-expanded`: expanded, every entry renders, the legend band grows, and `ChartFrame`'s
+ * observer re-flows the frame around it (the plot keeps `VX.minPlotHeight`).
  */
 export function ChartLegend({
   items,
@@ -270,7 +283,9 @@ export function ChartLegend({
   placement = 'bottom',
   groups = false,
   maxRows,
-}: {
+  className,
+  style,
+}: BasaltProps & {
   items: LegendEntry[]
   highlighted?: string | null
   onHighlight?: (key: string | null) => void
@@ -283,6 +298,8 @@ export function ChartLegend({
   groups?: boolean
   maxRows?: number
 }) {
+  const tier = useChartTierMetrics()
+  const [expanded, setExpanded] = useState(false)
   const handleEnter = (e: MouseEvent<HTMLButtonElement> | FocusEvent<HTMLButtonElement>) => {
     const key = e.currentTarget.dataset['legendKey']
     if (key !== undefined) onHighlight?.(key)
@@ -296,9 +313,9 @@ export function ChartLegend({
   const idPrefix = chartId ? `${chartId}-` : ''
   const vertical = placement === 'left' || placement === 'right'
   const { entries, dividerAfter } = orderEntries(items, groups)
-  const visible =
-    maxRows !== undefined && maxRows < entries.length ? entries.slice(0, maxRows) : entries
-  const hiddenCount = entries.length - visible.length
+  const cap = maxRows ?? tier.legendMaxRows
+  const rolledUp = cap === undefined ? 0 : Math.max(entries.length - cap, 0)
+  const visible = rolledUp > 0 && !expanded ? entries.slice(0, cap) : entries
 
   const nodes: ReactNode[] = []
   visible.forEach((item, i) => {
@@ -340,13 +357,26 @@ export function ChartLegend({
     if (dividerAfter.has(i))
       nodes.push(<LegendDivider key={`divider-${item.key}`} columnLayout={vertical} />)
   })
-  if (hiddenCount > 0) {
+  if (rolledUp > 0) {
     nodes.push(
-      <span key="legend-more" style={LEGEND_ITEM_BASE}>
-        +{hiddenCount} more
-      </span>,
+      <button
+        key="legend-more"
+        type="button"
+        aria-expanded={expanded}
+        onClick={() => setExpanded((prev) => !prev)}
+        style={{ ...LEGEND_ITEM_BUTTON, cursor: 'pointer', textDecoration: 'underline' }}
+      >
+        {expanded ? 'Show less' : `+${rolledUp} more`}
+      </button>,
     )
   }
 
-  return <div style={wrapperStyle(placement)}>{nodes}</div>
+  return (
+    <div
+      {...(className !== undefined && { className })}
+      style={{ ...wrapperStyle(placement, tier.legendFontSize), ...style }}
+    >
+      {nodes}
+    </div>
+  )
 }

package/src/charts/primitives/ChartPending.tsx

@@ -1,7 +1,8 @@
 import type { CSSProperties, ReactNode } from 'react'
+import type { BasaltProps } from '../../common/props'
 import { VX } from '../../tokens'
 
-export type ChartCenterProps = {
+export type ChartCenterProps = BasaltProps & {
   width: number
   height: number
   children: ReactNode
@@ -21,11 +22,24 @@ const centerStyle = (width: number, height: number): CSSProperties => ({
  * there was previously nothing to reach for when a chart file needed to center something. Not a
  * general layout system — width, height, children, nothing else.
  */
-export function ChartCenter({ width, height, children }: ChartCenterProps): ReactNode {
-  return <div style={centerStyle(width, height)}>{children}</div>
+export function ChartCenter({
+  width,
+  height,
+  className,
+  style,
+  children,
+}: ChartCenterProps): ReactNode {
+  return (
+    <div
+      {...(className !== undefined && { className })}
+      style={{ ...centerStyle(width, height), ...style }}
+    >
+      {children}
+    </div>
+  )
 }
 
-export type ChartPendingProps = {
+export type ChartPendingProps = BasaltProps & {
   width: number
   height: number
   /** Default `'Loading…'`. */
@@ -49,11 +63,175 @@ const labelStyle: CSSProperties = {
  * measurement — no axes, no gridlines, no hatching, no data marks — just a faint, static, centered
  * label. No animation: the package's motion doctrine bans looping/pulsing idle motion, so a static
  * reserved box is the correct answer here, not a compromise.
+ *
+ * The label is `role="status"` (polite), so a screen reader hears the chart resolve through all
+ * three states rather than only its failure: `ChartError` was `role="alert"` and its two siblings
+ * were silent, which announced the one outcome and swallowed the other two. Polite, not assertive —
+ * a loading placeholder must not interrupt what the reader is already being told.
  */
-export function ChartPending({ width, height, label = 'Loading…' }: ChartPendingProps): ReactNode {
+export function ChartPending({
+  width,
+  height,
+  label = 'Loading…',
+  className,
+  style,
+}: ChartPendingProps): ReactNode {
+  return (
+    <ChartCenter
+      width={width}
+      height={height}
+      {...(className !== undefined && { className })}
+      {...(style !== undefined && { style })}
+    >
+      {/* `<output>` is the tag oxlint suggests, and it is the wrong one: it means "the result of
+          a calculation", owns form semantics (`form`/`name`/`for`), and this box is precisely the
+          state in which there IS no result yet. A polite live region on a plain span is the
+          standard pattern. */}
+      {/* oxlint-disable-next-line jsx-a11y/prefer-tag-over-role */}
+      <span style={labelStyle} role="status">
+        {label}
+      </span>
+    </ChartCenter>
+  )
+}
+
+/**
+ * The three "nothing to draw" states a chart can be in, in ONE prop — the shape a
+ * `@tanstack/react-query` result (or anything derived from one) already has.
+ *
+ * It exists because the answer that already existed, `dashboard/QueryState`, renders Mantine and
+ * therefore cannot be reached from `./charts` at all (the Mantine-free boundary). A chart consumer
+ * without that import was left writing the four-way branch by hand, which is the exact bug
+ * `QueryState` was built for: the shape suggests `empty` and a 500 renders "No data".
+ *
+ * Precedence is fixed and is the whole product: **pending → error → empty**. A refetch that is
+ * both in flight and carrying a stale error is pending, not failed; a query that errored has no
+ * standing to claim its result was empty.
+ */
+export type ChartState = {
+  /** The query has not resolved yet. Wins over every other flag. */
+  pending?: boolean
+  /** Truthy = the query failed. Any thrown value; an `Error`'s `message` is used as the label. */
+  error?: unknown
+  /** The query resolved and there is genuinely nothing to plot. */
+  empty?: boolean
+}
+
+/** Which placeholder {@link ChartState} resolves to, or `null` to draw the chart. */
+export type ResolvedChartState = 'pending' | 'error' | 'empty' | null
+
+/**
+ * Resolve {@link ChartState} (plus the older standalone `isPending` flag, which stays a supported
+ * alias) into the ONE placeholder to render. Pure and exported so a hand-composed plot applies the
+ * same precedence rather than re-deriving it.
+ */
+export function resolveChartState(input: {
+  state?: ChartState
+  isPending?: boolean
+}): ResolvedChartState {
+  const { state, isPending } = input
+  if (isPending === true || state?.pending === true) return 'pending'
+  if (state?.error !== undefined && state.error !== null && state.error !== false) return 'error'
+  if (state?.empty === true) return 'empty'
+  return null
+}
+
+export type ChartEmptyProps = BasaltProps & {
+  width: number
+  height: number
+  /** Default `'No data'`. */
+  label?: string
+  /** Optional affordance under the label — a "clear filters" button, a range reset. Rendered as
+   * given: this layer is Mantine-free, so the caller owns whatever it puts here. */
+  action?: ReactNode
+}
+
+const stackStyle: CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  alignItems: 'center',
+  gap: 8,
+}
+
+/**
+ * Measured and EMPTY — the query resolved and there is nothing to plot. Distinct from
+ * {@link ChartPending} ("not asked yet") and from a hatched absence ("watched, measured nothing"):
+ * collapsing any of the three into another is the honesty bug this trio exists to prevent.
+ *
+ * Same footprint discipline as `ChartPending`: it reserves the plot rect and draws nothing that
+ * could be read as a measurement — no axes, no gridlines, no marks. Announced `role="status"`
+ * (polite) like `ChartPending`, so the resolution is heard; only `ChartError` is an `alert`.
+ */
+export function ChartEmpty({
+  width,
+  height,
+  label = 'No data',
+  action,
+  className,
+  style,
+}: ChartEmptyProps): ReactNode {
+  return (
+    <ChartCenter
+      width={width}
+      height={height}
+      {...(className !== undefined && { className })}
+      {...(style !== undefined && { style })}
+    >
+      {/* Same waiver, same reason, as `ChartPending` — see the comment there. */}
+      {/* oxlint-disable-next-line jsx-a11y/prefer-tag-over-role */}
+      <span style={stackStyle} role="status">
+        <span style={labelStyle}>{label}</span>
+        {action}
+      </span>
+    </ChartCenter>
+  )
+}
+
+export type ChartErrorProps = BasaltProps & {
+  width: number
+  height: number
+  /** Overrides the text outright. Omitted, an `Error`'s own `message` is used, else
+   * `'Could not load chart'` — a failure never borrows the empty state's copy. */
+  label?: string
+  /** The thrown value, used for the default label. */
+  error?: unknown
+  /** Optional affordance under the label — typically a retry. */
+  action?: ReactNode
+}
+
+/** The message an unknown thrown value gets to state for itself. Kept local rather than importing
+ * `./query`'s `toErrorMessage`: `./charts` resolves with no other basalt subpath installed, and a
+ * chart placeholder needs one line, not the HTTP-status vocabulary that helper carries. */
+function errorLabel(error: unknown): string {
+  if (error instanceof Error && error.message !== '') return error.message
+  if (typeof error === 'string' && error !== '') return error
+  return 'Could not load chart'
+}
+
+/**
+ * Measured and FAILED. The branch a hand-written chart switch reliably gets wrong — a 500 rendered
+ * as "No data" is a positive claim that the server answered and had nothing, which it did not.
+ */
+export function ChartError({
+  width,
+  height,
+  label,
+  error,
+  action,
+  className,
+  style,
+}: ChartErrorProps): ReactNode {
   return (
-    <ChartCenter width={width} height={height}>
-      <span style={labelStyle}>{label}</span>
+    <ChartCenter
+      width={width}
+      height={height}
+      {...(className !== undefined && { className })}
+      {...(style !== undefined && { style })}
+    >
+      <span style={stackStyle} role="alert">
+        <span style={labelStyle}>{label ?? errorLabel(error)}</span>
+        {action}
+      </span>
     </ChartCenter>
   )
 }

package/src/charts/primitives/ChartTooltip.tsx

@@ -1,8 +1,9 @@
 import type { CSSProperties, ReactNode } from 'react'
-import { useLayoutEffect, useRef, useState } from 'react'
+import { useLayoutEffect, useRef, useState, useSyncExternalStore } from 'react'
 import { createPortal } from 'react-dom'
 import { VX } from '../../tokens'
 import { fmtTooltipDate } from '../utils/format'
+import { useChartTierMetrics } from './chart-tier'
 
 // Panel bg + shadow-card, radius 8 (docs/DESIGN-SPEC.md §5's "Tooltip/popover/menu" idiom) — the
 // same depth-via-shadow treatment as ChartCard, never a `border` property. Surfaces resolve per
@@ -18,7 +19,6 @@ const TOOLTIP_STYLES: CSSProperties = {
   lineHeight: '18px',
   color: VX.ink,
   boxShadow: VX.shadowCard,
-  minWidth: 140,
 }
 
 /** Tooltip header — shows formatted date + optional right-aligned label with color. */
@@ -140,6 +140,21 @@ export function TooltipBody({ children }: { children: ReactNode }) {
   return <div style={{ padding: '5px 0' }}>{children}</div>
 }
 
+/**
+ * "Am I on the client?", answered SYNCHRONOUSLY and hydration-safely.
+ *
+ * `useSyncExternalStore` is the one hook whose server snapshot React honours during BOTH
+ * `renderToString` and the hydration pass, so the server sees `false` and the client's very first
+ * render already sees `true` — no effect, no extra frame, and therefore no one-frame flash of a
+ * missing tooltip on a hover that has already happened. An `useEffect`-set flag would be correct
+ * on the server and a render late on the client. The store never emits, so nothing ever
+ * re-subscribes.
+ */
+const neverSubscribe = () => () => {}
+const onClient = () => true
+const onServer = () => false
+const useIsClient = (): boolean => useSyncExternalStore(neverSubscribe, onClient, onServer)
+
 /** Gap between the anchor point and the tooltip box, and the minimum distance kept from the
  * viewport edge. */
 const TOOLTIP_GAP = 12
@@ -152,6 +167,13 @@ const VIEWPORT_MARGIN = 8
  *
  * The box is measured after mount via `useLayoutEffect`, so the first paint of a given tooltip is
  * hidden rather than misplaced — a tooltip that flashes at the wrong corner reads as a bug.
+ *
+ * **It renders NOTHING on the server.** `createPortal` throws outright in `react-dom/server`
+ * ("Portals are not currently supported by the server renderer"), and an unconditional portal made
+ * this the single component in the package that could not be server-rendered. The guard is
+ * {@link useIsClient}, not a `typeof document` check: under a DOM-preloaded test runner `document`
+ * exists while `renderToString` still refuses portals. A tooltip is a hover artifact with nothing
+ * to emit server-side, so rendering nothing is the whole fix, not a degradation.
  */
 export function ChartTooltipFloat({
   anchor,
@@ -168,6 +190,8 @@ export function ChartTooltipFloat({
 }) {
   const ref = useRef<HTMLDivElement>(null)
   const [box, setBox] = useState<{ width: number; height: number } | null>(null)
+  const isClient = useIsClient()
+  const { tooltipMinWidth } = useChartTierMetrics()
 
   useLayoutEffect(() => {
     const el = ref.current
@@ -181,8 +205,10 @@ export function ChartTooltipFloat({
   }, [children, anchor])
 
   if (anchor === null) return null
-  // SSR guard: react-dom/server has no jsdom and does not support portals.
-  if (typeof document === 'undefined') return null
+  // The SSR guard — see the component doc. A `typeof document` check does NOT cover this: under a
+  // jsdom/happy-dom-preloaded test runner `document` exists while `renderToString` still refuses
+  // portals, which is exactly how this shipped.
+  if (!isClient) return null
 
   const width = box?.width ?? 0
   const height = box?.height ?? 0
@@ -203,7 +229,13 @@ export function ChartTooltipFloat({
       ref={ref}
       role="tooltip"
       {...(ariaLive && { 'aria-live': 'polite' as const })}
-      style={{ ...TOOLTIP_STYLES, left, top, visibility: box === null ? 'hidden' : 'visible' }}
+      style={{
+        ...TOOLTIP_STYLES,
+        minWidth: tooltipMinWidth,
+        left,
+        top,
+        visibility: box === null ? 'hidden' : 'visible',
+      }}
     >
       {children}
     </div>,

package/src/charts/primitives/Crosshair.tsx

@@ -1,5 +1,6 @@
 import type { ReactNode } from 'react'
 import { VX } from '../../tokens'
+import { useChartTierMetrics } from './chart-tier'
 
 /**
  * The shared vertical hover crosshair — one implementation for what used to be five hand-rolled
@@ -22,6 +23,9 @@ export function Crosshair({
 /**
  * The punched-out hover marker: a filled circle whose stroke is the chart background color, so it
  * reads as a "hole" cut into the line on both themes. Centralizes the `dotStroke = chart-bg` trick.
+ *
+ * The default radius tracks the ambient chart tier (`docs/CHARTS-SPEC.md` §8) — an explicit `r`
+ * (a `getMarker`'s own radius) still wins.
  */
 export function SeriesDot({
   cx,
@@ -34,7 +38,6 @@ export function SeriesDot({
   color: string
   r?: number
 }): ReactNode {
-  return (
-    <circle cx={cx} cy={cy} r={r ?? VX.dotR} fill={color} stroke={VX.dotStroke} strokeWidth={2} />
-  )
+  const { dotR } = useChartTierMetrics()
+  return <circle cx={cx} cy={cy} r={r ?? dotR} fill={color} stroke={VX.dotStroke} strokeWidth={2} />
 }