@wick-charts/react 0.3.4 → 0.3.6

package/dist/index.d.ts

@@ -412,7 +412,7 @@ export declare const catppuccin: ThemePreset;
  *   - Legend — flex sibling at the bottom (or right, when `position="right"`), so its height is
  *     reserved by browser layout.
  */
-export declare function ChartContainer({ children, theme, axis, padding, gradient, interactive, grid, headerLayout, perf, animations, style, className, }: ChartContainerProps): JSX_2.Element;
+export declare function ChartContainer({ children, theme, axis, padding, gradient, interactive, grid, headerLayout, perf, animations, onEdgeReached, style, className, }: ChartContainerProps): JSX_2.Element;
 
 /** Props for the {@link ChartContainer} component. */
 declare interface ChartContainerProps {
@@ -509,6 +509,18 @@ declare interface ChartContainerProps {
      * Only read at mount; changing this prop after the chart is created is ignored.
      */
     perf?: PerfOption;
+    /**
+     * Fired after the user releases a pan/zoom gesture that pulled the viewport
+     * past a data edge by more than ~10% of the visible range. Hosts typically
+     * respond by prefetching more history.
+     *
+     * For threshold-based prefetch (load *before* the user fully overshoots),
+     * use `<EdgeLoader>` instead — that component subscribes to `viewportChange`
+     * and arms when the visible range nears the data edge.
+     *
+     * Captured at mount only; changing the prop identity later is ignored.
+     */
+    onEdgeReached?: (info: EdgeReachedInfo) => void;
     /** Inline style for the chart's outer wrapper element. */
     style?: CSSProperties;
     /** Extra class for the chart's outer wrapper element. */
@@ -618,6 +630,36 @@ export declare class ChartInstance extends EventEmitter<ChartEvents> {
     setVisibleRange(range: VisibleRange | number): void;
     getYRange(): YRange;
     getCrosshairPosition(): CrosshairPosition | null;
+    /**
+     * Programmatically set or clear the crosshair. Same effect as the user
+     * hovering over `(timeToX(time), valueToY(y))` — emits `crosshairMove`,
+     * marks the overlay layer dirty, and lets `<Crosshair>` / `<Tooltip>`
+     * react via their normal store subscriptions.
+     *
+     * Pass `null` to clear (mirrors the pointer-leave path).
+     *
+     * `y` is optional. Resolution order when omitted:
+     *   1. **current crosshair's y** — preserves whatever the chart already
+     *      has (real cursor y, or a previously-synthesised value). This is
+     *      what makes the cross-chart broadcast pattern work: when an echo
+     *      arrives at the chart that originated the hover, the existing y
+     *      stays in place and the idempotency check below short-circuits the
+     *      loop. Without preservation, the echo would overwrite the source's
+     *      real cursor y with the midpoint default and the tooltip would
+     *      jitter between cursor and midpoint every mouse-move.
+     *   2. **midpoint of the current Y range** — fallback when there is no
+     *      current crosshair (first programmatic set on a chart that hasn't
+     *      been hovered yet).
+     *
+     * Idempotent: a call that produces the same `(time, y)` pair as the
+     * current crosshair is a no-op (no emit). Combined with the y-preservation
+     * above, this lets N charts broadcast their hover to each other without
+     * a feedback-loop guard.
+     */
+    setCrosshair(pos: {
+        time: number;
+        y?: number;
+    } | null): void;
     /** Get the last visible value and whether the absolute last point is on screen. */
     getLastValue(seriesId: string): {
         value: number;
@@ -1089,14 +1131,82 @@ export declare interface CrosshairPosition {
     y: number;
 }
 
+/**
+ * @deprecated Use a named preset instead — `catppuccin.theme` is the new
+ * default dark palette, and `dracula`, `nightOwl`, `oneDarkPro`, `gruvbox`,
+ * `monokaiPro`, `materialPalenight`, or `panda` cover the rest of the
+ * dark spectrum. `darkTheme` is kept as an alias for the previous default
+ * and will be removed in a future major release.
+ */
 export declare const darkTheme: ChartTheme;
 
 export declare function detectInterval(times: number[]): number;
 
 export declare const dracula: ThemePreset;
 
+/**
+ * Subscribes to the chart's viewport and triggers a fetch when the visible
+ * range nears the chosen data edge. Handles the boilerplate every load-on-scroll
+ * site otherwise has to re-implement: arming after first user pan, deduping
+ * via Promise tracking, and exposing the boundary's pixel coordinate so a
+ * loader can be anchored to "the wall of available history".
+ *
+ * Place as a child of `<ChartContainer>`.
+ */
+export declare function EdgeLoader({ side, threshold, onTrigger, indicator, children }: EdgeLoaderProps): JSX_2.Element | null;
+
+export declare interface EdgeLoaderProps {
+    /** Which edge to watch. */
+    side: EdgeSide;
+    /**
+     * Bars from the edge that arms the trigger. Multiplied by the chart's data
+     * interval. Default `5`.
+     */
+    threshold?: number;
+    /**
+     * Called when the visible range moves within {@link EdgeLoaderProps.threshold}
+     * bars of the data edge. Returning a Promise toggles `isLoading` for its
+     * lifetime. **Resolve with `false`** to signal "no more data" — the loader
+     * stops watching and switches the optional canvas indicator to its
+     * `'no-data'` state. Any other resolve value (including `undefined`) means
+     * "keep watching for the next near-edge event".
+     */
+    onTrigger: () => void | Promise<unknown>;
+    /**
+     * - `'canvas'` (default): drive the chart's built-in canvas spinner via
+     *   {@link ChartInstance.setEdgeState}. Renders inside the chart area at
+     *   the data boundary.
+     * - `'custom'`: skip the canvas indicator. Use the render-prop `children`
+     *   to draw your own DOM/SVG loader.
+     */
+    indicator?: 'canvas' | 'custom';
+    /**
+     * Optional render-prop. Receives the live edge state — render whatever
+     * positioned overlay you want, or return `null`.
+     */
+    children?: (args: EdgeLoaderRenderArgs) => ReactNode;
+}
+
+/** Argument shape passed to the {@link EdgeLoader} render-prop. */
+export declare interface EdgeLoaderRenderArgs {
+    /**
+     * CSS pixels in the chart's overlay coordinate space, anchored at the data
+     * edge (`data.from` for `side='left'`, `data.to` for `side='right'`).
+     * The overlay div is positioned with `inset: 0`, so this value can be used
+     * directly as `style={{ left: x }}` or `transform: translateX(...)`.
+     */
+    x: number;
+    side: EdgeSide;
+    /** True between {@link EdgeLoaderProps.onTrigger} firing and its Promise resolving. */
+    isLoading: boolean;
+    /** Time coordinate (ms) of the data edge — convenient for "fetch history before T" requests. */
+    boundaryTime: number;
+    /** Becomes `false` after `onTrigger` resolves with the literal value `false`. */
+    hasMore: boolean;
+}
+
 /** Payload for {@link ChartOptions.onEdgeReached}. */
-declare interface EdgeReachedInfo {
+export declare interface EdgeReachedInfo {
     side: EdgeSide;
     /** Time units the user pulled past the soft bound. */
     overshoot: number;
@@ -1105,7 +1215,7 @@ declare interface EdgeReachedInfo {
 }
 
 /** Which data side the user pulled past during a gesture. */
-declare type EdgeSide = 'left' | 'right';
+export declare type EdgeSide = 'left' | 'right';
 
 /**
  * Host-controlled visual state for a chart edge:
@@ -1114,7 +1224,7 @@ declare type EdgeSide = 'left' | 'right';
  * - `no-data`: a dashed boundary line + "No more data" label appears at the data edge.
  * - `has-more`: reserved — currently behaves like `idle`. Use when more data exists but is not being fetched.
  */
-declare type EdgeState = 'idle' | 'loading' | 'no-data' | 'has-more';
+export declare type EdgeState = 'idle' | 'loading' | 'no-data' | 'has-more';
 
 declare class EventEmitter<Events = Record<string, Listener>> {
     private listeners;
@@ -1208,6 +1318,19 @@ export declare interface InfoBarRenderContext {
     readonly isHover: boolean;
 }
 
+/**
+ * `true` when the given `#rrggbb` background reads as dark — Rec. 601 luma
+ * below the half-byte threshold (`< 128`). Used internally by
+ * {@link createTheme} to flip default palette/contrast picks, and exported
+ * for callers (docs UI chrome, host apps) that want to branch on theme
+ * polarity without carrying their own copy of the heuristic.
+ *
+ * Falls through (`false`) for non-hex inputs (e.g. `transparent`,
+ * `rgba(...)`, gradients) — the built-in presets all use plain hex on the
+ * top-level `background`, so this is fine for the vast majority of cases.
+ */
+export declare function isDarkBg(bg: string): boolean;
+
 export declare const lavenderMist: ThemePreset;
 
 export declare function Legend({ items, position, mode, children }: LegendProps): JSX_2.Element | null;
@@ -1290,6 +1413,13 @@ declare interface LegendRenderContext {
 
 export declare const lightPink: ThemePreset;
 
+/**
+ * @deprecated Use a named light preset instead — `quietLight`, `githubLight`,
+ * `solarizedLight`, `minimalLight`, `peachCream`, `sandDune`, `lightPink`,
+ * `lavenderMist`, `mintBreeze`, `rosePineDawn`, or `handwritten`. `lightTheme`
+ * is kept as an alias for the previous default and will be removed in a
+ * future major release.
+ */
 export declare const lightTheme: ChartTheme;
 
 /** @deprecated Use {@link TimePoint} instead. */