@wick-charts/react 0.2.2 → 0.3.0

package/dist/index.d.ts

@@ -69,6 +69,35 @@ declare interface AnimationsConfig {
  */
 declare type AnimationTime = number | false;
 
+/**
+ * Build a 2-stop candle-body gradient around a single hex color — a lightened
+ * top stop and a darkened bottom stop. Presets use this to get a subtle
+ * vertical lift without hand-picking both ends.
+ *
+ *     candlestick: { up: { body: autoGradient('#089981'), wick: '#089981' } }
+ *
+ * The input must be `#rrggbb`; other CSS color forms are returned as a flat
+ * `[color, color]` tuple because the lighten/darken math requires hex.
+ *
+ * The returned tuple carries the source color on a non-enumerable `source`
+ * property so {@link resolveCandlestickBodyColor} can recover it for scalar
+ * fallbacks (yLabel backgrounds, bands, volume tint) instead of picking the
+ * lightened top stop.
+ */
+export declare function autoGradient(color: string): AutoGradientTuple;
+
+/**
+ * Tuple returned by {@link autoGradient}. The non-enumerable `source` property
+ * carries the original canonical color so scalar-fallback consumers
+ * (yLabel backgrounds, bands, default wick, volume tint) can recover it via
+ * {@link resolveCandlestickBodyColor} instead of picking the lightened top
+ * stop. `JSON.stringify` drops the marker, which is fine because
+ * `themeToJson` serializes all dependent scalar fields explicitly.
+ */
+declare type AutoGradientTuple = [string, string] & {
+    readonly source?: string;
+};
+
 /**
  * Defines a bound for the Y axis.
  *
@@ -198,6 +227,16 @@ export declare interface BuildLastSnapshotsArgs {
     cacheKey: string;
 }
 
+/**
+ * `body` shape encodes the fill mode: a single color renders flat; a
+ * `[top, bottom]` tuple renders a 2-stop vertical gradient. Use
+ * `autoGradient(color)` for the subtle lightened/darkened look.
+ */
+declare interface CandlestickDirectionColors {
+    body: string | [string, string];
+    wick: string;
+}
+
 /**
  * Entrance animation styles for candlesticks (shown when a new candle appears via `appendData`).
  * - `'none'` — no animation.
@@ -215,16 +254,10 @@ export declare function CandlestickSeries({ data, options, id: idProp }: Candles
 export declare interface CandlestickSeriesOptions {
     /** Display label shown in the tooltip. */
     label?: string;
-    upColor: string;
-    downColor: string;
-    wickUpColor: string;
-    wickDownColor: string;
+    up: CandlestickDirectionColors;
+    down: CandlestickDirectionColors;
     /** Width of candle body as a fraction of the available bar slot (0-1). */
     bodyWidthRatio: number;
-    /** Apply a subtle vertical gradient to candle bodies. Default: true. */
-    bodyGradient?: boolean;
-    /** @deprecated Use {@link bodyGradient} instead. */
-    candleGradient?: boolean;
     /**
      * Entrance animation style for newly appended candles. Style is specific to
      * the candlestick; there is no chart-level override for style — only for
@@ -680,12 +713,23 @@ export declare interface ChartTheme {
         color: string;
         style: 'solid' | 'dashed' | 'dotted';
     };
-    /** OHLC candlestick body and wick colors. */
+    /**
+     * OHLC candlestick colors. `wick` defaults to `body` in {@link createTheme}
+     * when omitted, so most presets only need to set the body colors.
+     *
+     * `body` shape encodes the fill: a single color renders flat; a
+     * `[top, bottom]` tuple renders a 2-stop vertical gradient. Presets that
+     * want the subtle lightened/darkened look pass `autoGradient(color)`.
+     */
     candlestick: {
-        upColor: string;
-        downColor: string;
-        wickUpColor: string;
-        wickDownColor: string;
+        up: {
+            body: string | [string, string];
+            wick: string;
+        };
+        down: {
+            body: string | [string, string];
+            wick: string;
+        };
     };
     /** Default line series appearance including area gradient fill. */
     line: {
@@ -707,12 +751,27 @@ export declare interface ChartTheme {
         labelBackground: string;
         labelTextColor: string;
     };
-    /** Axis tick label styling. */
+    /**
+     * Axis tick styling. `fontSize` and `textColor` are the shared defaults used
+     * for both X and Y, as well as non-axis label surfaces (legend, crosshair
+     * labels, sparkline ticks). Set `x` / `y` only when a specific axis needs to
+     * diverge.
+     */
     axis: {
+        fontSize: number;
         textColor: string;
+        x?: {
+            fontSize?: number;
+            textColor?: string;
+        };
+        y?: {
+            fontSize?: number;
+            textColor?: string;
+        };
     };
     /** Floating label shown at the current value level on the Y axis. */
     yLabel: {
+        fontSize: number;
         upBackground: string;
         downBackground: string;
         neutralBackground: string;
@@ -720,6 +779,7 @@ export declare interface ChartTheme {
     };
     /** Hover tooltip styling. */
     tooltip: {
+        fontSize: number;
         background: string;
         textColor: string;
         borderColor: string;
@@ -1392,6 +1452,36 @@ declare interface Rect {
     height: number;
 }
 
+/**
+ * Resolve the effective font size for a given axis, falling back to the
+ * shared `axis.fontSize` default when no per-axis override is set.
+ *
+ * Pass `'x'` or `'y'` for axis-specific surfaces (TimeAxis, YAxis). Omit the
+ * argument for non-axis label surfaces that share the same size (Legend,
+ * Crosshair label, Sparkline ticks).
+ */
+export declare function resolveAxisFontSize(theme: ChartTheme, axis?: 'x' | 'y'): number;
+
+/**
+ * Resolve the effective text color for a given axis, falling back to the
+ * shared `axis.textColor` default when no per-axis override is set.
+ */
+export declare function resolveAxisTextColor(theme: ChartTheme, axis?: 'x' | 'y'): string;
+
+/**
+ * Pick a single flat color from a candlestick body that may be either a single
+ * color or a `[top, bottom]` gradient tuple. Use this wherever a solid color
+ * is needed — tooltip text, legend swatches, sparkline trend indicator,
+ * yLabel backgrounds, volume tinting, etc.
+ *
+ * For tuples produced by `autoGradient(c)` the canonical `c` is preserved on
+ * a non-enumerable `source` property and returned as-is — this prevents the
+ * lightened top stop from silently replacing the candle's perceived color
+ * across dependent UI. Plain user tuples without a source fall back to the
+ * top stop.
+ */
+export declare function resolveCandlestickBodyColor(body: string | [string, string]): string;
+
 export declare const rosePineDawn: ThemePreset;
 
 export declare const sandDune: ThemePreset;
@@ -1493,7 +1583,10 @@ export declare interface ThemeConfig {
     chartGradient?: [string, string];
     typography?: Partial<ChartTheme['typography']>;
     grid?: Partial<ChartTheme['grid']>;
-    candlestick?: Partial<ChartTheme['candlestick']>;
+    candlestick?: {
+        up?: Partial<ChartTheme['candlestick']['up']>;
+        down?: Partial<ChartTheme['candlestick']['down']>;
+    };
     line?: Partial<ChartTheme['line']>;
     seriesColors?: string[];
     bands?: Partial<ChartTheme['bands']>;
@@ -1713,13 +1806,11 @@ export declare interface TooltipRenderContext {
 /** Sort order for multi-series tooltip values. */
 export declare type TooltipSort = 'none' | 'asc' | 'desc';
 
-/** Font family and size tokens used across the chart. */
+/** Font family and base font size used across the chart. */
 export declare interface Typography {
     fontFamily: string;
+    /** Base body font size — titles, infobar, pie tooltip/legend default to this. */
     fontSize: number;
-    axisFontSize: number;
-    yFontSize: number;
-    tooltipFontSize: number;
 }
 
 export declare function useChartInstance(): ChartInstance;