@pond-ts/charts 0.36.0 → 0.38.0

package/CHANGELOG.md

@@ -8,7 +8,9 @@ The `@pond-ts` packages — `pond-ts`, `@pond-ts/react`, `@pond-ts/charts`, and
 them all. Pre-1.0: minor bumps may include new features and type-level changes;
 patch bumps are strictly additive.
 
-[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.36.0...HEAD
+[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.38.0...HEAD
+[0.38.0]: https://github.com/pjm17971/pond-ts/compare/v0.37.0...v0.38.0
+[0.37.0]: https://github.com/pjm17971/pond-ts/compare/v0.36.0...v0.37.0
 [0.36.0]: https://github.com/pjm17971/pond-ts/compare/v0.35.0...v0.36.0
 [0.35.0]: https://github.com/pjm17971/pond-ts/compare/v0.34.1...v0.35.0
 [0.34.1]: https://github.com/pjm17971/pond-ts/compare/v0.34.0...v0.34.1
@@ -32,6 +34,81 @@ patch bumps are strictly additive.
 [0.19.0]: https://github.com/pjm17971/pond-ts/compare/v0.18.0...v0.19.0
 [0.18.0]: https://github.com/pjm17971/pond-ts/compare/v0.17.1...v0.18.0
 
+## [0.38.0] — 2026-07-03
+
+A `@pond-ts/charts` release: **axis-edge value indicators + the crosshair
+cursor** — the ChartIQ / Yahoo-Finance price-tag family, driven by the Tidal
+terminal. `pond-ts`, `@pond-ts/react`, and `@pond-ts/fit` carry no code changes —
+republished in lock-step (peer ranges widen to `^0.38.0`).
+
+### Added
+
+- `@pond-ts/charts`: **`<YAxisIndicator>` + `createLiveValue`** — a value pill
+  pinned to a y-axis edge, decoupled from the series' last point. A `LiveValue`
+  `source` updates it at high frequency **without re-rendering the chart** (only
+  the subscribed pill repaints). Props: `value` / `source`, `axis`, `side`,
+  `color`, `format`, `line` (dashed guide), `pointer` (callout triangle).
+- `@pond-ts/charts`: **`cursor="crosshair"`** `CursorMode` — a synced vertical
+  line + per-series dots, each series' value pinned to its y-axis and the hovered
+  time pinned to the x-axis.
+- `@pond-ts/charts`: **`indicator`** opt-in on `<Baseline>` (a y-axis value pill)
+  and `<Marker>` (an x-axis time pill, with a connector down to the mark).
+- `@pond-ts/charts`: `<Baseline labelSide>` (`left` / `right`) + `labelPosition`
+  (`center` on the line / `above` it) for the near-line label chip.
+- `@pond-ts/charts`: `<Region edges>` (default `true`; `false` = shaded fill with
+  no side outlines).
+- `@pond-ts/charts`: `axisPillStyle`, `contrastText`, `pointerStyle` chip helpers
+  are exported.
+
+### Changed
+
+- `@pond-ts/charts`: axis indicator pills are **solid** (colour fill +
+  auto-contrast text), aligned to the tick-label row, and **always show the axis
+  coordinate** — never a custom label (a label stays the in-plot chip).
+- `@pond-ts/charts`: cursor flag / inline chips now have **square corners**; the
+  cursor **time** atop a flag stack renders as plain text (no chip background).
+- `@pond-ts/charts`: Storybook reorganized into a feature-axis reference tree with
+  systematic per-prop coverage (dev-only; stories are excluded from the package).
+
+### Fixed
+
+- `@pond-ts/charts`: the crosshair x-axis pill used the container's time formatter
+  (showing a raw number on a value axis) — it now uses the axis's own resolved
+  formatter, matching the ticks. The crosshair also no longer double-renders the
+  time (a stray per-row chip alongside the x-axis pill).
+
+## [0.37.0] — 2026-07-02
+
+A `@pond-ts/charts` release: the axis wave — label, tick, and domain controls
+driven by the Tidal terminal's friction. `pond-ts`, `@pond-ts/react`, and
+`@pond-ts/fit` carry no code changes — republished in lock-step (peer ranges
+widen to `^0.37.0`).
+
+### Added
+
+- **Charts — axis title typography (`theme.axis.title`).** The rotated y-axis
+  title now renders a touch larger than the ticks by default and is fully
+  themeable (`{ color, size, opacity }`, shared with the x-axis label). (#318)
+- **Charts — `YAxis labelPlacement`.** `'rotated'` (default) or `'top'` — a
+  horizontal title above the axis, aligned to the axis line, in a reserved
+  header band that clears the top tick. (#318, #320)
+- **Charts — `XAxis align`.** `'center'` (**new default**), `'auto'` (previous
+  behaviour: centred but first/last end-anchored), or `'right'` (label beside an
+  extended tick). (#318)
+- **Charts — `YAxis pad`.** Fractional headroom added to each side of the
+  resolved domain (`0` default) — lifts a tight domain off the plot edges
+  without hand-computing bounds. (#319)
+- **Charts — `YAxis boundaryLabels`.** `false` drops the top & bottom tick
+  numbers (gridlines stay) for stacked layouts where the edge labels crowd. (#319)
+- **Charts — new `Charts/Axes` Storybook gallery** covering the above. (#318)
+
+### Changed
+
+- **Charts — domain-extreme y-tick labels now clamp inside the row** instead of
+  half-overflowing the top/bottom edge (resolves Tidal friction F-charts-6). (#319)
+- **Charts — `XAxis` tick-label default is now `'center'`** (was the
+  end-anchored `'auto'`). Pass `align="auto"` for the old behaviour. (#318)
+
 ## [0.36.0] — 2026-07-02
 
 A `@pond-ts/charts` release: a CSS-custom-property → theme bridge so a canvas
@@ -77,7 +154,7 @@ lock-step (their `pond-ts` / `@pond-ts/react` peer ranges widen to `^0.35.0`).
   (`[6, 4]` dashed, `[2, 3]` ≈ dotted; omit or `[]` = solid) applied to the
   series stroke. Lets a theme set a **modeled / forecast** line (e.g. GARCH
   vol) apart from an observed one at a glance. Distinct from a `GapMode`'s
-  inferred gap-bridge dashing (which marks *missing data*, not the whole
+  inferred gap-bridge dashing (which marks _missing data_, not the whole
   line). Additive: existing themes are unaffected; a solid line never touches
   `setLineDash`. New `Charts/LineChart → LineStyles` story. (#313)
 
@@ -116,7 +193,7 @@ Tidal wire-format spike. `@pond-ts/react`, `@pond-ts/charts`, and
 - **`TimeSeries.fromColumns`** — the columnar (struct-of-arrays) ingress,
   the counterpart to `fromJSON`'s row-tuple shape. Accepts either a plain
   `number[]` or a `Float64Array` per column — one polymorphic door, so a
-  wire format only changes the *decoder*, not the ingest. `Float64Array`
+  wire format only changes the _decoder_, not the ingest. `Float64Array`
   columns are adopted directly (zero-copy); `number[]` columns are copied.
   A `null`/`undefined` cell or a non-finite value (`NaN`/`Infinity`) is a
   gap, identically across both input shapes. Enforces the same

package/dist/ChartRow.js

@@ -12,6 +12,10 @@ const IMPLICIT_AXIS_ID = '__default__';
 /** Axis tick count for the per-axis formatter — matches `<YAxis>`'s tick count
  *  so the readout formatter is calibrated exactly as the labels are. */
 const AXIS_TICK_COUNT = 5;
+/** Vertical band (px) reserved above the plot for a `labelPlacement="top"` axis
+ *  title, so it clears the top tick + plotted data. Sized for the default title
+ *  (~`font.size + 1`); a much larger themed title may want more room. */
+const TOP_LABEL_HEADER = 16;
 /**
  * A horizontal band sharing the container's time axis. `ChartRow` owns the
  * **horizontal layout** (axes left/right around a `<Layers>` plot area) and
@@ -91,6 +95,8 @@ export function ChartRow({ height, cursor, children }) {
                 width: 0,
                 min: undefined,
                 max: undefined,
+                pad: 0,
+                labelPlacement: 'rotated',
                 format: undefined,
                 tickValues: undefined,
                 index: 0,
@@ -126,6 +132,11 @@ export function ChartRow({ height, cursor, children }) {
     const containerLeftSlots = container.leftSlots;
     const containerRightSlots = container.rightSlots;
     const { axisSlots, leftPad, rightPad } = useMemo(() => placeAxisSlots(leftAxes, rightAxes, containerLeftSlots, containerRightSlots), [leftAxes, rightAxes, containerLeftSlots, containerRightSlots]);
+    // Header band reserved at the top of the plot when any axis draws a `'top'`
+    // title — the scale range then starts below it (see below).
+    const topHeader = effectiveAxes.some((ax) => ax.labelPlacement === 'top')
+        ? TOP_LABEL_HEADER
+        : 0;
     // One y-scale per axis. A layer counts toward an axis when its (late-resolved)
     // axis id matches; `resolveYDomain` handles the auto-fit + empty/flat/inverted
     // edges. yExtent() is O(points), so only walk the layers when a bound auto-fits.
@@ -137,11 +148,15 @@ export function ChartRow({ height, cursor, children }) {
                     .filter((entry) => (entry.axisId ?? defaultAxisId) === ax.id)
                     .map((entry) => entry.layer.yExtent())
                 : [];
-            const [lo, hi] = resolveYDomain(ax.min, ax.max, extents);
-            map.set(ax.id, scaleLinear().domain([lo, hi]).range([height, 0]));
+            const [lo, hi] = resolveYDomain(ax.min, ax.max, extents, ax.pad);
+            // Reserve a header band at the top when any axis draws a `'top'` title,
+            // so the title clears the top tick + plot (the whole row shifts down
+            // uniformly, keeping stacked axes aligned). No top titles ⇒ range top 0,
+            // so nothing changes for existing charts.
+            map.set(ax.id, scaleLinear().domain([lo, hi]).range([height, topHeader]));
         }
         return map;
-    }, [effectiveAxes, layerList, height, defaultAxisId]);
+    }, [effectiveAxes, layerList, height, defaultAxisId, topHeader]);
     // A value formatter per axis (its `format` resolved against its scale) — shared
     // by the axis tick labels and the cursor readout so a value reads the same.
     const formats = useMemo(() => {
@@ -164,6 +179,14 @@ export function ChartRow({ height, cursor, children }) {
         }
         return map;
     }, [effectiveAxes]);
+    // Which side each axis sits on — so an axis-edge overlay (the crosshair's
+    // value pills) hugs the correct gutter without re-deriving from the specs.
+    const axisSides = useMemo(() => {
+        const map = new Map();
+        for (const ax of effectiveAxes)
+            map.set(ax.id, ax.side);
+        return map;
+    }, [effectiveAxes]);
     const frame = useMemo(() => ({
         height,
         cursor,
@@ -172,6 +195,7 @@ export function ChartRow({ height, cursor, children }) {
         yScales,
         formats,
         tickValues,
+        axisSides,
         defaultAxisId,
         axisSlots,
         registerAxis,
@@ -187,6 +211,7 @@ export function ChartRow({ height, cursor, children }) {
         yScales,
         formats,
         tickValues,
+        axisSides,
         defaultAxisId,
         axisSlots,
         registerAxis,

package/dist/Layers.js

@@ -5,7 +5,7 @@ import { drawGrid } from './grid.js';
 import { cursorParts } from './tracker.js';
 import { resolveSelection } from './select.js';
 import { panRange, zoomRange } from './viewport.js';
-import { flagChipStyle, flagChipX } from './chip.js';
+import { flagChipStyle, flagChipX, axisPillX, axisPillStyle } from './chip.js';
 import { ContainerContext, LayersContext, RowContext, } from './context.js';
 /** Gridline tick count — matches the axes (`YAxis`/`TimeAxis`) so they align. */
 const GRID_TICKS = 5;
@@ -49,7 +49,7 @@ export function Layers({ children }) {
     }), [row.registerLayer, row.unregisterLayer]);
     const background = container.theme.background;
     const { grid: gridColor, gridDash } = container.theme.axis;
-    const { layers, yScales, formats, defaultAxisId, tickValues } = row;
+    const { layers, yScales, formats, defaultAxisId, tickValues, axisSides } = row;
     // x geometry is shared and lives on the container (uniform across rows).
     const { xScale, plotWidth } = container;
     const draw = useCallback((ctx, w, h) => {
@@ -132,6 +132,8 @@ export function Layers({ children }) {
             // The chip uses this layer's axis formatter, so a readout value reads
             // exactly as the axis labels it.
             const fmt = formats.get(axisId) ?? String;
+            // Which gutter the crosshair value pill hugs (the axis's own side).
+            const side = axisSides.get(axisId) ?? 'left';
             for (const s of entry.layer.sampleAt(cursorTime)) {
                 out.push({
                     px: xScale(s.x),
@@ -139,6 +141,7 @@ export function Layers({ children }) {
                     value: s.value,
                     color: s.color,
                     format: fmt,
+                    side,
                 });
             }
         }
@@ -148,6 +151,7 @@ export function Layers({ children }) {
         layers,
         yScales,
         formats,
+        axisSides,
         xScale,
         defaultAxisId,
         parts.dots,
@@ -403,9 +407,13 @@ export function Layers({ children }) {
     // The time is shared across rows (one cursor, one time), so it shows **once**,
     // atop the first row — not repeated per row. (Gating it here also drops the
     // top-of-stack space reservation on the other rows, see `flagBase`.)
+    // Crosshair (`chip: 'axis'`) is excluded: it pins the time to the shared x-axis
+    // pill (`<XAxis>`), so a per-row chip here would double it (and land wrong on a
+    // stacked row).
     const showTime = showCursorTime &&
         cursorTime !== null &&
         (parts.line || parts.dots) &&
+        parts.chip !== 'axis' &&
         row.isFirstRow;
     // Flag geometry: each value flies as a flag from the top of its own staff — the
     // chip's top sits at `flagBase` (just below the time chip when shown) and the
@@ -491,9 +499,12 @@ export function Layers({ children }) {
                             cursorX >= 0 &&
                             cursorX <= plotWidth && (_jsx("line", { x1: Math.round(cursorX), y1: 0, x2: Math.round(cursorX), y2: row.height, stroke: cursorColor, strokeWidth: 1, shapeRendering: "crispEdges" })), parts.chip === 'flag' &&
                             trackerSamples.map((s, i) => s.py > flagBase ? (_jsx("line", { x1: s.px, y1: flagBase, x2: s.px, y2: s.py, stroke: cursorColor, strokeWidth: 1, opacity: 0.5 }, `staff-${i}`)) : null), parts.chip === 'flag' &&
-                            trackerFlags.map((f, i) => f.topPy > flagBase ? (_jsx("line", { x1: f.px, y1: flagBase, x2: f.px, y2: f.topPy, stroke: cursorColor, strokeWidth: 1, opacity: 0.5 }, `boxstaff-${i}`)) : null), parts.dots &&
+                            trackerFlags.map((f, i) => f.topPy > flagBase ? (_jsx("line", { x1: f.px, y1: flagBase, x2: f.px, y2: f.topPy, stroke: cursorColor, strokeWidth: 1, opacity: 0.5 }, `boxstaff-${i}`)) : null), parts.chip === 'axis' &&
+                            trackerSamples.map((s, i) => (_jsx("line", { x1: s.side === 'right' ? Math.round(s.px) : 0, y1: Math.round(s.py), x2: s.side === 'right' ? plotWidth : Math.round(s.px), y2: Math.round(s.py), stroke: s.color, strokeWidth: 1, opacity: 0.4, strokeDasharray: "3 3", shapeRendering: "crispEdges" }, `hconn-${i}`))), parts.dots &&
                             trackerSamples.map((s, i) => (_jsx("circle", { cx: s.px, cy: s.py, r: 3, fill: s.color, stroke: background, strokeWidth: background ? 1 : 0 }, `dot-${i}`)))] }), showTime && timeX !== null && cursorTime !== null && (_jsx("div", { style: {
                         ...chipStyle,
+                        background: 'transparent',
+                        padding: 0,
                         top: `${flagTop}px`,
                         left: timeX > plotWidth * LABEL_FLIP_FRACTION
                             ? undefined
@@ -518,6 +529,15 @@ export function Layers({ children }) {
                                 right: flip ? `${plotWidth - s.px + 8}px` : undefined,
                                 color: s.color,
                             }, children: s.format(s.value) }, i));
+                    }), parts.chip === 'axis' &&
+                    trackerSamples.map((s, i) => {
+                        const top = Math.max(flagLineHeight / 2, Math.min(row.height - flagLineHeight / 2, s.py));
+                        return (_jsx("div", { style: {
+                                ...axisPillStyle(container.theme, s.color),
+                                top: `${top}px`,
+                                transform: 'translateY(-50%)',
+                                ...axisPillX(s.side, plotWidth),
+                            }, children: s.format(s.value) }, `ytag-${i}`));
                     }), parts.chip === 'flag' &&
                     cursorX !== null &&
                     trackerSamples.map((s, i) => (

package/dist/XAxis.d.ts

@@ -24,6 +24,19 @@ export interface XAxisProps {
         readonly at: number;
         readonly label: string;
     }>;
+    /**
+     * Horizontal placement of each tick label relative to its tick.
+     * - **`'center'` (default)** — every label centred on its tick. Note the
+     *   first/last labels can then extend past the plot edges (the strip doesn't
+     *   clip), so a wide first label may reach into the left y-axis gutter; use
+     *   `'auto'` if that crowds.
+     * - `'auto'` — centred, but the first label left-anchors and the last
+     *   right-anchors so the edge labels stay inside the plot (the old default).
+     * - `'right'` — the label sits to the **right** of an extended tick that
+     *   drops from the axis line (label beside the tick, not under it) — useful
+     *   for dense or wide labels that would collide when centred.
+     */
+    align?: 'auto' | 'center' | 'right';
 }
 /**
  * The shared **x axis**, a sibling of {@link YAxis} for the horizontal axis. A
@@ -35,5 +48,5 @@ export interface XAxisProps {
  *
  * `<TimeAxis>` is the time-flavoured preset (`<XAxis />`).
  */
-export declare function XAxis({ format, label, side, height, ticks: customTicks, }?: XAxisProps): import("react/jsx-runtime").JSX.Element;
+export declare function XAxis({ format, label, side, height, ticks: customTicks, align, }?: XAxisProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=XAxis.d.ts.map

package/dist/XAxis.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Fragment, useContext } from 'react';
 import { ContainerContext } from './context.js';
+import { axisPillStyle } from './chip.js';
 import { resolveAxisFormat, resolveTimeFormat, } from './format.js';
 /** Tick strip height (mark + value label) in CSS px. */
 const TICK_STRIP = 22;
@@ -17,12 +18,23 @@ const TICK_COUNT = 5;
  *
  * `<TimeAxis>` is the time-flavoured preset (`<XAxis />`).
  */
-export function XAxis({ format, label, side = 'bottom', height, ticks: customTicks, } = {}) {
+export function XAxis({ format, label, side = 'bottom', height, ticks: customTicks, align = 'center', } = {}) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<XAxis> must be rendered inside a <ChartContainer>');
     }
     const { xScale, plotWidth, leftGutter, theme, formatTime, xKind } = container;
+    // The crosshair's x-time pill: when the container cursor is `'crosshair'` and a
+    // cursor is live in-bounds, pin the hovered time to this axis (covering the
+    // tick behind it), matching the on-axis y value pills the rows draw. Gated on
+    // the container default, so a per-row `cursor` override doesn't reach here.
+    const cursorX = container.cursorX;
+    const showCursorTag = container.cursor === 'crosshair' &&
+        cursorX !== null &&
+        cursorX >= 0 &&
+        cursorX <= plotWidth;
+    const cursorColor = theme.cursor ?? theme.axis.label;
+    const annotationColor = theme.annotation?.color ?? '#0d9488';
     // Tick formatter: an explicit `format` is resolved against the axis kind
     // (a time specifier through the time scale, a number specifier through the
     // value scale); otherwise the container's shared formatter — the one the
@@ -32,6 +44,18 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
         : xKind === 'time'
             ? resolveTimeFormat(xScale, TICK_COUNT, format)
             : resolveAxisFormat(xScale, TICK_COUNT, format);
+    // Marker annotations that opted into an axis indicator (`<Marker indicator>`)
+    // pin their **time** to this shared x-axis — a pill at `at`, in the annotation
+    // colour, reading like a tick. An indicator always shows the axis coordinate
+    // (the formatted `at`), never the marker's custom label (that stays the in-plot
+    // chip). Skipped when off-plot.
+    const markerTags = container.annotations
+        .filter((a) => a.indicator && a.kind === 'marker' && a.xs[0] !== undefined)
+        .map((a) => {
+        const at = a.xs[0];
+        return { id: a.id ?? `marker-at-${at}`, x: xScale(at), text: fmt(at) };
+    })
+        .filter((t) => t.x >= 0 && t.x <= plotWidth);
     const placed = customTicks
         ? customTicks.map((t) => ({ x: xScale(t.at), label: t.label }))
         : xScale.ticks(TICK_COUNT).map((d) => ({
@@ -40,6 +64,9 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
         }));
     const stripHeight = height ?? TICK_STRIP + (label ? LABEL_STRIP : 0);
     const onTop = side === 'top';
+    // Axis pills (marker / crosshair) sit at the same offset as the tick labels so
+    // they line up with their tick-label neighbours (matches `labelOffset` below).
+    const pillOffset = align === 'right' ? 2 : 6;
     return (_jsxs("div", { style: {
             position: 'relative',
             marginLeft: `${leftGutter}px`,
@@ -51,23 +78,33 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
             fontSize: `${theme.font.size}px`,
             color: theme.axis.label,
         }, children: [placed.map((t, i) => {
-                // End-align the edge labels so they stay within [0, plotWidth].
-                const labelTransform = i === 0
+                const isFirst = i === 0;
+                const isLast = i === placed.length - 1;
+                // `center`: every label centred on its tick. `auto`: centred, but the
+                // edge labels end-align so they stay within [0, plotWidth]. `right`:
+                // label left-anchored just past an extended tick (beside, not under).
+                const labelTransform = align === 'right'
                     ? 'none'
-                    : i === placed.length - 1
-                        ? 'translateX(-100%)'
-                        : 'translateX(-50%)';
+                    : align === 'auto' && isFirst
+                        ? 'none'
+                        : align === 'auto' && isLast
+                            ? 'translateX(-100%)'
+                            : 'translateX(-50%)';
+                // `right` drops a longer tick alongside the label; others keep the 4px stub.
+                const tickHeight = align === 'right' ? theme.font.size + 4 : 4;
+                const labelLeft = align === 'right' ? t.x + 4 : t.x;
+                const labelOffset = align === 'right' ? 2 : 6;
                 return (_jsxs(Fragment, { children: [_jsx("div", { style: {
                                 position: 'absolute',
                                 left: `${t.x}px`,
                                 [onTop ? 'bottom' : 'top']: 0,
                                 width: '1px',
-                                height: '4px',
+                                height: `${tickHeight}px`,
                                 background: theme.axis.grid,
                             } }), _jsx("div", { style: {
                                 position: 'absolute',
-                                left: `${t.x}px`,
-                                [onTop ? 'bottom' : 'top']: '6px',
+                                left: `${labelLeft}px`,
+                                [onTop ? 'bottom' : 'top']: `${labelOffset}px`,
                                 transform: labelTransform,
                                 whiteSpace: 'nowrap',
                             }, children: t.label })] }, `${t.x}-${i}`));
@@ -77,8 +114,31 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
                     width: '100%',
                     textAlign: 'center',
                     [onTop ? 'top' : 'bottom']: 0,
-                    opacity: 0.7,
+                    // Themeable axis-title text (shared with the rotated y-axis title).
+                    fontSize: `${theme.axis.title?.size ?? theme.font.size + 1}px`,
+                    color: theme.axis.title?.color ?? theme.axis.label,
+                    opacity: theme.axis.title?.opacity ?? 0.85,
                     whiteSpace: 'nowrap',
-                }, children: label }))] }));
+                }, children: label })), markerTags.map((t) => (_jsxs(Fragment, { children: [_jsx("div", { style: {
+                            position: 'absolute',
+                            left: `${t.x}px`,
+                            [onTop ? 'bottom' : 'top']: 0,
+                            width: '1px',
+                            height: `${pillOffset}px`,
+                            background: annotationColor,
+                            zIndex: 2,
+                        } }), _jsx("div", { style: {
+                            ...axisPillStyle(theme, annotationColor),
+                            left: `${t.x}px`,
+                            transform: 'translateX(-50%)',
+                            [onTop ? 'bottom' : 'top']: `${pillOffset}px`,
+                            zIndex: 2,
+                        }, children: t.text })] }, t.id))), showCursorTag && (_jsx("div", { style: {
+                    ...axisPillStyle(theme, cursorColor),
+                    left: `${cursorX}px`,
+                    transform: 'translateX(-50%)',
+                    [onTop ? 'bottom' : 'top']: `${pillOffset}px`,
+                    zIndex: 3,
+                }, children: fmt(+xScale.invert(cursorX)) }))] }));
 }
 //# sourceMappingURL=XAxis.js.map

package/dist/YAxis.d.ts

@@ -11,9 +11,25 @@ export interface YAxisProps {
     side?: 'left' | 'right';
     /** Display label / unit (e.g. `bpm`); defaults to `id`. */
     label?: string;
+    /**
+     * How the axis title (`label`) is drawn:
+     * - **`'rotated'` (default)** — a thin vertical strip down the outer edge
+     *   (the standard y-axis convention; fits long labels in a narrow gutter).
+     * - `'top'` — horizontal, at the top of the axis, aligned to its side. Reads
+     *   better for short unit labels; keep it terse and pair it with a domain
+     *   that has headroom (auto-fit / padded) so it doesn't crowd the top tick.
+     */
+    labelPlacement?: 'rotated' | 'top';
     /** Explicit domain bounds; omit to auto-fit the charts linked to this axis. */
     min?: number;
     max?: number;
+    /**
+     * Fractional headroom added to each side of the resolved domain — `0` (the
+     * default) means none. Lifts a tight domain off the plot edges without
+     * hand-computing bounds (e.g. `pad={0.05}` adds 5% of the span top & bottom).
+     * Applies to an explicit `[min, max]` or an auto-fit domain.
+     */
+    pad?: number;
     /**
      * Value formatting for the tick labels (and the cursor readout, which matches):
      * a d3 format specifier string (e.g. `'.0%'`, `',.2f'`) or a `(value) => string`
@@ -37,6 +53,14 @@ export interface YAxisProps {
         readonly at: number;
         readonly label: string;
     }>;
+    /**
+     * Render the tick labels at the domain extremes (the top & bottom ticks)?
+     * **Default `true`.** `false` drops just those two numbers — the gridlines
+     * stay — for when the min/max labels crowd a stacked row's edges and you'd
+     * rather omit them than keep them. (Extreme labels are otherwise clamped to
+     * stay inside the row, never overflowing the edge.)
+     */
+    boundaryLabels?: boolean;
     /** Gutter width in CSS pixels (default 50). */
     width?: number;
     /**
@@ -53,5 +77,5 @@ export interface YAxisProps {
  * tick marks + labels from that scale. Charts attach via `<LineChart axis="id">`
  * (default: the first axis).
  */
-export declare function YAxis({ id, side, label, min, max, format, ticks, width, index, }: YAxisProps): import("react/jsx-runtime").JSX.Element;
+export declare function YAxis({ id, side, label, min, max, format, ticks, pad, boundaryLabels, width, labelPlacement, index, }: YAxisProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=YAxis.d.ts.map

package/dist/YAxis.js

@@ -13,7 +13,7 @@ const TICK_COUNT = 5;
  * tick marks + labels from that scale. Charts attach via `<LineChart axis="id">`
  * (default: the first axis).
  */
-export function YAxis({ id, side = 'left', label, min, max, format, ticks, width = DEFAULT_WIDTH, index = 0, }) {
+export function YAxis({ id, side = 'left', label, min, max, format, ticks, pad = 0, boundaryLabels = true, width = DEFAULT_WIDTH, labelPlacement = 'rotated', index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<YAxis> must be rendered inside a <ChartContainer>');
@@ -28,10 +28,12 @@ export function YAxis({ id, side = 'left', label, min, max, format, ticks, width
         width,
         min,
         max,
+        pad,
+        labelPlacement,
         format,
         tickValues: ticks?.map((t) => t.at),
         index,
-    }), [id, side, width, min, max, format, ticks, index]);
+    }), [id, side, width, min, max, pad, labelPlacement, format, ticks, index]);
     // A stable per-instance slot (see useSlotKey) keeps this axis in a fixed
     // registry position, so a min/max/side change updates in place rather than
     // re-appending (which would move the first axis behind a later one and
@@ -76,27 +78,50 @@ export function YAxis({ id, side = 'left', label, min, max, format, ticks, width
                 fontSize: `${theme.font.size}px`,
                 color: theme.axis.label,
             }, children: [yScale &&
-                    tickList.map(({ value, label }) => (_jsx("div", { style: {
-                            position: 'absolute',
-                            top: `${yScale(value)}px`,
-                            [side === 'left' ? 'right' : 'left']: '4px',
-                            transform: 'translateY(-50%)',
-                            whiteSpace: 'nowrap',
-                        }, children: label }, value))), _jsx("div", { style: {
+                    tickList.map(({ value, label }, i) => {
+                        // Drop just the top & bottom labels when boundary labels are off
+                        // (gridlines are drawn separately, so they stay).
+                        if (!boundaryLabels && (i === 0 || i === tickList.length - 1))
+                            return null;
+                        // Clamp the label's centre so a domain-extreme label stays inside
+                        // the row instead of half-overflowing the top/bottom edge (and
+                        // colliding across a splitter in a stacked layout) — F-charts-6.
+                        const half = theme.font.size / 2 + 1;
+                        const top = Math.max(half, Math.min(row.height - half, yScale(value)));
+                        return (_jsx("div", { style: {
+                                position: 'absolute',
+                                top: `${top}px`,
+                                [side === 'left' ? 'right' : 'left']: '4px',
+                                transform: 'translateY(-50%)',
+                                whiteSpace: 'nowrap',
+                            }, children: label }, value));
+                    }), labelPlacement === 'top' ? (_jsx("div", { style: {
+                        position: 'absolute',
+                        top: 0,
+                        // Align to the axis line (the plot-facing edge), matching the tick
+                        // labels' alignment, rather than floating at the outer gutter edge.
+                        [side === 'left' ? 'right' : 'left']: '4px',
+                        fontSize: `${theme.axis.title?.size ?? theme.font.size + 1}px`,
+                        color: theme.axis.title?.color ?? theme.axis.label,
+                        opacity: theme.axis.title?.opacity ?? 0.85,
+                        whiteSpace: 'nowrap',
+                        pointerEvents: 'none',
+                    }, children: label ?? id })) : (_jsx("div", { style: {
                         position: 'absolute',
                         [side === 'left' ? 'left' : 'right']: '1px',
                         top: 0,
                         bottom: 0,
-                        width: `${theme.font.size + 2}px`,
+                        width: `${(theme.axis.title?.size ?? theme.font.size + 1) + 3}px`,
                         display: 'flex',
                         alignItems: 'center',
                         justifyContent: 'center',
-                        fontSize: `${theme.font.size - 1}px`,
-                        opacity: 0.7,
+                        fontSize: `${theme.axis.title?.size ?? theme.font.size + 1}px`,
+                        color: theme.axis.title?.color ?? theme.axis.label,
+                        opacity: theme.axis.title?.opacity ?? 0.85,
                         pointerEvents: 'none',
                     }, children: _jsx("span", { style: {
                             whiteSpace: 'nowrap',
                             transform: `rotate(${side === 'left' ? -90 : 90}deg)`,
-                        }, children: label ?? id }) })] }) }));
+                        }, children: label ?? id }) }))] }) }));
 }
 //# sourceMappingURL=YAxis.js.map

package/dist/annotations.d.ts

@@ -51,9 +51,16 @@ export interface MarkerProps {
     /** Make the marker **editable** (in edit mode): dragging its line reports the
      *  new `at` (controlled — wire it back to `at`). The whole line moves. */
     onChange?: (at: number) => void;
+    /** Also pin this marker's **time** to the **x-axis** as an on-axis pill (drawn
+     *  by `<XAxis>` at `at`, in the annotation colour) — the axis-edge counterpart
+     *  of the near-line chip. Default `false`. The pill always shows the formatted
+     *  `at` (the axis coordinate), never the custom `label` (which stays the
+     *  near-line chip) — an indicator reads like a tick. A connector links the
+     *  marker line to its pill. */
+    indicator?: boolean;
 }
 /** A vertical line at an x position (a time, a distance, a lap boundary). */
-export declare function Marker({ at, label, id, selected, selectable, hovered, editing, onChange, }: MarkerProps): import("react/jsx-runtime").JSX.Element;
+export declare function Marker({ at, label, id, selected, selectable, hovered, editing, onChange, indicator, }: MarkerProps): import("react/jsx-runtime").JSX.Element;
 export interface BaselineProps {
     /** y value in the linked axis's units. */
     value: number;
@@ -62,6 +69,11 @@ export interface BaselineProps {
     /** Chip label. Omit to format `value` with that axis's formatter; pass `false`
      *  (or `''`) to render **no label chip**. */
     label?: string | false;
+    /** Which side of the chart the near-line label chip sits. **Default `left`.** */
+    labelSide?: 'left' | 'right';
+    /** Where the label chip sits relative to the line: **`center`** (default) rides
+     *  on the line, vertically centred; `above` sits just on top of it. */
+    labelPosition?: 'center' | 'above';
     /** Stable consumer id — a click reports it via `onSelectAnnotation`. */
     id?: string;
     /** Controlled selection — brightens to the front (level 1). Handles are an
@@ -82,10 +94,16 @@ export interface BaselineProps {
     /** Make the baseline **editable** (in edit mode): dragging it vertically reports
      *  the new `value` (controlled — wire it back to `value`). */
     onChange?: (value: number) => void;
+    /** Also pin this baseline's **value** to its **y-axis** as an on-axis pill (in
+     *  the annotation colour) — the axis-edge counterpart of the near-line chip.
+     *  Default `false`. The pill always shows the formatted `value` (the axis
+     *  coordinate), never the custom `label` (which stays the near-line chip) — an
+     *  indicator reads like a tick. */
+    indicator?: boolean;
 }
 /** A horizontal line at a y value, scaled against one row axis (RTC's `Baseline`).
  *  Its label anchors at the left, at the line's height. */
-export declare function Baseline({ value, axis, label, id, selected, selectable, hovered, editing, onChange, }: BaselineProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function Baseline({ value, axis, label, labelSide, labelPosition, id, selected, selectable, hovered, editing, onChange, indicator, }: BaselineProps): import("react/jsx-runtime").JSX.Element | null;
 export interface RegionProps {
     /** Start x in axis units (time or value). */
     from: number;
@@ -122,8 +140,12 @@ export interface RegionProps {
         from: number;
         to: number;
     }) => void;
+    /** Draw the vertical **side outlines** at `from`/`to`. **Default `true`.**
+     *  `false` shades the span with no edge lines (fill only) — a soft highlight
+     *  band. Edit-mode resizing still works (the grab areas are invisible). */
+    edges?: boolean;
 }
 /** A shaded span over an x range — a lap, a zone, a selected interval. Its label
  *  flies as a flag off the left edge. */
-export declare function Region({ from, to, label, id, selected, selectable, hovered, editing, onChange, }: RegionProps): import("react/jsx-runtime").JSX.Element;
+export declare function Region({ from, to, label, id, selected, selectable, hovered, editing, onChange, edges, }: RegionProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=annotations.d.ts.map