@pond-ts/charts 0.56.2 → 0.58.0

package/dist/ChartContainer.d.ts

@@ -2,7 +2,7 @@ import { type ReactNode } from 'react';
 import { type DiscontinuityProvider, type TradingCalendarLike } from './tradingTimeScale.js';
 import { Sequence, BoundedSequence } from 'pond-ts';
 import type { TimeRange } from 'pond-ts';
-import { type AnnotationKind, type CreateSpec, type CursorMode, type SelectInfo, type TrackerInfo, type DrawStatsFrame } from './context.js';
+import { type AnnotationKind, type CreateSpec, type CursorMode, type TrackerInfo, type DrawStatsFrame } from './context.js';
 import { type AxisFormat, type CursorFormat } from './format.js';
 import { type ChartTheme } from './theme.js';
 export interface ChartContainerProps {
@@ -14,6 +14,49 @@ export interface ChartContainerProps {
      * the data — so a tuple stays a time domain on a time chart.
      */
     range?: readonly [number, number] | TimeRange;
+    /**
+     * **Cap the slot pitch** on a **category** x axis, in CSS pixels
+     * ([PND-BANDPACK]). A band scale otherwise spreads its categories across the
+     * full plot width, so three categories in a 900px panel become three 300px
+     * bars and thirty become thirty 30px ones — the same chart in the same panel
+     * reading as two different charts depending on how many categories the data
+     * happened to return.
+     *
+     * That is fine for a static chart with a known domain and wrong for a **live**
+     * one: when the category count moves over a session, bar width becomes a
+     * meaningless variable that moves on its own, and a reader can't compare the
+     * chart to what it looked like a minute ago or to the same chart on another
+     * screen. Capping the pitch keeps bar width constant and comparable, and the
+     * empty space left over is itself information — it shows the set is small.
+     *
+     * Omitted ⇒ slots fill the plot (unchanged). When `n × maxBandWidth` exceeds
+     * the plot, the cap can't bind and the slots fill as before, so this degrades
+     * correctly as categories accumulate. Use {@link bandAlign} to say where the
+     * capped block sits.
+     *
+     * **This caps the slot, not the bar.** `<BarChart gap>` still insets the bar
+     * within its slot, and the two compose — one knob for pitch, one for ink,
+     * neither doing the other's job. (Inverting `gap` against a measured plot
+     * width was the workaround this replaces for the width half; the packing half
+     * had no workaround at all.)
+     *
+     * **Vertical / x-axis categories only.** A `orientation="horizontal"`
+     * categorical chart puts its categories on the **y** axis as unit slots,
+     * which is a different mechanism and is not capped by this.
+     */
+    maxBandWidth?: number;
+    /**
+     * Where the capped category block sits in the plot when {@link maxBandWidth}
+     * binds. **Default `'start'`** — pack from the left, leaving the far side
+     * empty. `'center'` and `'end'` place it otherwise.
+     *
+     * A no-op without `maxBandWidth`, or when the cap doesn't bind: the block
+     * fills the plot and there is no slack to place. (There is deliberately no
+     * `'fill'` member — "fill" is what *omitting* `maxBandWidth` means, and a
+     * `fill` value alongside a pitch cap would be a contradiction rather than a
+     * choice.)
+     */
+    bandAlign?: 'start' | 'center' | 'end';
     /**
      * A **trading-calendar** discontinuity provider — closed-market time
      * (weekends, holidays, overnight, lunch breaks) collapsed. Supply it to turn
@@ -122,6 +165,13 @@ export interface ChartContainerProps {
      * `'point'` / `'inline'` / `'flag'` add per-series marks; `'none'` hides it.
      * `'region'` shades the bucket under the pointer (needs {@link cursorSequence}).
      * See {@link CursorMode}.
+     *
+     * @deprecated Mount a **cursor component** instead — `<LineCursor>` /
+     * `<PointCursor>` / `<InlineCursor>` / `<FlagCursor>` / `<CrosshairCursor>` /
+     * `<RangeCursor>` as a child of the container (or inside a `<ChartRow>` for
+     * the per-row override); mount nothing for `'none'`. This prop keeps working
+     * for one more minor by synthesizing the equivalent preset internally; a
+     * mounted cursor component overrides it. See `docs/rfcs/interaction.md` §9.
      */
     cursor?: CursorMode;
     /**
@@ -144,6 +194,10 @@ export interface ChartContainerProps {
      * re-realizes the buckets on each pointer move (harmless for a coarse
      * day/session sequence, wasteful for a fine one over a wide view) — hoist it or
      * `useMemo` it.
+     *
+     * @deprecated Use `<RangeCursor sequence={…}>` — the prop moved onto the
+     * component that uses it, where it is no longer mode-conditional. Works for
+     * one more minor; a mounted `<RangeCursor>`'s sequence wins over this.
      */
     cursorSequence?: Sequence | BoundedSequence;
     /**
@@ -166,6 +220,12 @@ export interface ChartContainerProps {
      * domain is meaningless), so a **value** axis is always freeform. No-op unless
      * `cursor="region"` on a **time** or **value** x-axis (a **category** axis is
      * excluded — an ordinal-slot select is a different gesture).
+     *
+     * @deprecated Use `<RangeCursor onDragRelease>` — the drag moved onto the
+     * component, and the payload becomes `{ x: [lo, hi] }` (a {@link RangeSpan},
+     * forward-compatible with the 2-D drag's optional `y`) instead of the bare
+     * pair. Works for one more minor; a mounted `<RangeCursor onDragRelease>`
+     * takes over the gesture.
      */
     onRegionSelect?: (range: readonly [number, number]) => void;
     /**
@@ -176,6 +236,9 @@ export interface ChartContainerProps {
      * selects). **Omitted** ⇒ a region-drag
      * **preempts** pan (drag always selects; document that precedence for users).
      * Wheel-zoom is unaffected in every case.
+     *
+     * @deprecated Use `<RangeCursor dragModifier>` — the prop moved onto the
+     * component alongside `onDragRelease`. Works for one more minor.
      */
     regionSelectModifier?: 'shift';
     /**
@@ -194,51 +257,6 @@ export interface ChartContainerProps {
      * frame); route it to a ref/store rather than doing React state work per frame.
      */
     onDrawStats?: (frame: DrawStatsFrame) => void;
-    /**
-     * Controlled selection — the selected mark (echo the `onSelect` arg back), or
-     * `null`. **Omitted ⇒ uncontrolled** (a click on a selectable layer manages it
-     * internally; pass `null` to force nothing selected). A layer is **selectable
-     * only when it carries an `id`** (the stable series identity) — `BarChart` /
-     * `ScatterChart` highlight the mark matching the selection's `id` (the series)
-     * and its `key` (the sample), so two series sharing a timestamp don't both
-     * light up, and the selection survives a data update (it keys on the stable
-     * `id`, not the sample `key`). A layer with no `id` renders + reads out but
-     * can't be selected.
-     */
-    selected?: SelectInfo | null;
-    /**
-     * Fires when a selectable layer's mark is clicked, with the hit mark, or `null`
-     * when a click misses every mark (or hits a layer with no `id` — display-only,
-     * so it reads as empty space). Notification only — works in both controlled and
-     * uncontrolled mode. If this or `selected` is set but no layer has an `id`, a
-     * dev-warning notes that nothing is selectable.
-     */
-    onSelect?: (hit: SelectInfo | null) => void;
-    /**
-     * Controlled hover-highlight — the transiently lit mark (echo the `onHover` arg
-     * back), or `null`. **Omitted ⇒ uncontrolled** (the pointer over a selectable
-     * layer manages it internally). The hover analog of {@link selected}: pass it to
-     * **pin** a lit mark from outside the chart (e.g. hovering a legend / list row
-     * lights the matching {@link BarChart} bar). Only layers with a hover-highlight
-     * (currently `BarChart`) render it; keyed by the same {@link SelectInfo} identity
-     * as selection.
-     */
-    hovered?: SelectInfo | null;
-    /**
-     * Fires when the pointer enters a selectable layer's mark (the hit mark) or
-     * leaves every mark (`null`) — the hover analog of {@link onSelect}. Notification
-     * only (works controlled or uncontrolled), and **deduped**: it fires on a mark
-     * transition, not on every pointer move. Wire it to mirror hover out-of-band
-     * (e.g. a list row ↔ the bar), pairing with {@link hovered} to sync both ways.
-     * (The annotation counterpart is {@link onHoverAnnotation}.)
-     *
-     * **Dedup key:** by the mark's `key` + `label` only (not `value`/`color`). So on
-     * a live chart where a bar's value changes while the cursor stays on it, this
-     * won't re-fire — read the current value from your series, not the last
-     * `onHover` payload. (Matches the internal hover-highlight, which repaints on
-     * key transitions.)
-     */
-    onHover?: (hit: SelectInfo | null) => void;
     /**
      * Which pan/zoom gestures the plot captures:
      *
@@ -253,7 +271,7 @@ export interface ChartContainerProps {
      * `false` ⇒ `'none'`). Bound the reachable range with {@link bounds}
      * (zoom-out / pan extent) and {@link minDuration} (zoom-in floor).
      */
-    panZoom?: boolean | 'none' | 'pan' | 'panZoom';
+    panZoom?: boolean | 'none' | 'pan' | 'panZoom' | 'panZoomX' | 'panZoomY' | 'panZoomXY';
     /**
      * **Outer pan/zoom extent** — `[min, max]` (same units as {@link range}) the
      * view can never move outside. Panning into an edge stops there (the window
@@ -284,6 +302,10 @@ export interface ChartContainerProps {
      * Show the cursor's time atop the in-chart readout (when a row's `cursor` draws
      * one). **Default `false`.** Formatted by {@link timeFormat} to match the time
      * axis.
+     *
+     * @deprecated Use `showTime` on the mounted cursor component
+     * (`<LineCursor showTime>` / `<FlagCursor showTime>` / …). Works for one
+     * more minor via the shim.
      */
     cursorTime?: boolean;
     /**
@@ -294,6 +316,10 @@ export interface ChartContainerProps {
      * the vertical line snaps its **x** to the data grid (so the time readout is
      * clean), and both draw a full-height dashed vertical + full-width dashed
      * horizontal line.
+     *
+     * @deprecated Use `<CrosshairCursor snap={…}>` — the prop moved onto the
+     * component, where it is no longer mode-conditional. Works for one more
+     * minor via the shim.
      */
     crosshairSnap?: boolean;
     /**
@@ -375,6 +401,11 @@ export interface ChartContainerProps {
      * {@link timeFormat} owns the labels. (A category axis reads names, and a
      * `transform`ed axis's pill speaks its derived unit — neither consults
      * `cursorFormat`.)
+     *
+     * @deprecated Use `format` on the mounted cursor (`<CrosshairCursor
+     * format={…}>`) — it feeds the same shared readout channel (marker
+     * indicators and annotation auto-labels included). Works for one more
+     * minor; a mounted cursor's `format` wins over this.
      */
     cursorFormat?: CursorFormat;
     /**
@@ -419,5 +450,5 @@ export interface ChartContainerProps {
  * {@link TimeAxis} at the bottom, aligned under the plots. Y axes are per-row
  * (`<YAxis>`).
  */
-export declare function ChartContainer({ range, width, rowGap, showAxis, trackerPosition, onTrackerChanged, onDrawStats, selected, onSelect, hovered, onHover, panZoom, bounds, onTimeRangeChange, minDuration, cursor, cursorSequence, onRegionSelect, regionSelectModifier, cursorTime, crosshairSnap, editAnnotations, creating, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap, timeFormat, cursorFormat, origin, theme, discontinuities, calendar, spacing, grid, sessionDividers, children, }: ChartContainerProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChartContainer({ range, maxBandWidth, bandAlign, width, rowGap, showAxis, trackerPosition, onTrackerChanged, onDrawStats, panZoom, bounds, onTimeRangeChange, minDuration, cursor: cursorProp, cursorSequence: cursorSequenceProp, onRegionSelect, regionSelectModifier, cursorTime: cursorTimeProp, crosshairSnap: crosshairSnapProp, editAnnotations, creating, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap, timeFormat, cursorFormat: cursorFormatProp, origin, theme, discontinuities, calendar, spacing, grid, sessionDividers, children, }: ChartContainerProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=ChartContainer.d.ts.map