@pond-ts/charts 0.36.0 → 0.37.0

package/CHANGELOG.md

@@ -8,7 +8,8 @@ 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.37.0...HEAD
+[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 +33,38 @@ 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.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

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(() => {

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

@@ -17,7 +17,7 @@ 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>');
@@ -51,23 +51,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,7 +87,10 @@ 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 }))] }));
 }

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/context.d.ts

@@ -396,6 +396,10 @@ export interface AxisSpec {
     /** Explicit domain bounds, or `undefined` to auto-fit linked layers. */
     readonly min: number | undefined;
     readonly max: number | undefined;
+    /** Fractional headroom added to each side of the resolved domain (`0` = none). */
+    readonly pad: number;
+    /** Title placement; `'top'` makes the row reserve a header band above the plot. */
+    readonly labelPlacement: 'rotated' | 'top';
     /** Value formatting for the tick labels + the cursor readout ({@link AxisFormat}),
      *  or `undefined` for the scale's d3 default. */
     readonly format: AxisFormat | undefined;

package/dist/domain.d.ts

@@ -14,6 +14,11 @@
  * can otherwise invert it (e.g. `min=5` with no data would naively give
  * `[5, 1]`). Two explicit bounds are returned as-is (an inverted explicit domain
  * is a deliberate axis flip; we don't second-guess it).
+ *
+ * `pad` (fractional, default `0`) expands the resolved domain outward by
+ * `pad × span` on each side — headroom without hand-computing bounds, useful to
+ * lift a tight **explicit** domain off the plot edges. Applied last, to whatever
+ * domain was resolved (explicit or auto); `0` is a no-op.
  */
-export declare function resolveYDomain(min: number | undefined, max: number | undefined, extents: Iterable<readonly [number, number] | null>): [number, number];
+export declare function resolveYDomain(min: number | undefined, max: number | undefined, extents: Iterable<readonly [number, number] | null>, pad?: number): [number, number];
 //# sourceMappingURL=domain.d.ts.map

package/dist/domain.js

@@ -15,8 +15,22 @@ import { scaleLinear } from 'd3-scale';
  * can otherwise invert it (e.g. `min=5` with no data would naively give
  * `[5, 1]`). Two explicit bounds are returned as-is (an inverted explicit domain
  * is a deliberate axis flip; we don't second-guess it).
+ *
+ * `pad` (fractional, default `0`) expands the resolved domain outward by
+ * `pad × span` on each side — headroom without hand-computing bounds, useful to
+ * lift a tight **explicit** domain off the plot edges. Applied last, to whatever
+ * domain was resolved (explicit or auto); `0` is a no-op.
  */
-export function resolveYDomain(min, max, extents) {
+export function resolveYDomain(min, max, extents, pad = 0) {
+    const result = resolveBase(min, max, extents);
+    if (pad) {
+        const [lo, hi] = result;
+        const p = pad * (hi - lo);
+        return [lo - p, hi + p];
+    }
+    return result;
+}
+function resolveBase(min, max, extents) {
     // Both bounds explicit: trust them verbatim (allows an intentional flip).
     if (min !== undefined && max !== undefined)
         return [min, max];

package/dist/theme.d.ts

@@ -88,6 +88,17 @@ export interface ChartTheme {
         readonly grid: string;
         /** Gridline dash pattern (px on/off pairs); `[]` for solid. */
         readonly gridDash: readonly number[];
+        /**
+         * Typography for the axis **title** — the rotated y-axis unit strip and the
+         * x-axis label (distinct from the per-tick `label` colour above). Omit a
+         * field to fall back: `color` → `label`, `size` → `font.size + 1` (a touch
+         * larger than the ticks so the rotated strip reads), `opacity` → `0.85`.
+         */
+        readonly title?: {
+            readonly color?: string;
+            readonly size?: number;
+            readonly opacity?: number;
+        };
     };
     /** Label / tick typography. One source for axes + chrome. */
     readonly font: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pond-ts/charts",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "private": false,
   "description": "Canvas-rendered, streaming-first time-series charts for pond-ts",
   "license": "MIT",
@@ -38,8 +38,8 @@
     "perf": "PERF_BENCH=1 playwright test perf.spec.ts --workers=1"
   },
   "peerDependencies": {
-    "@pond-ts/react": "^0.36.0",
-    "pond-ts": "^0.36.0",
+    "@pond-ts/react": "^0.37.0",
+    "pond-ts": "^0.37.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {