@funnest/charts-react 0.0.0-stage → 0.1.0

package/dist/viz/annotations.d.ts

@@ -0,0 +1,34 @@
+import { formatNumber } from './context';
+export interface ReferenceLineProps {
+    /** Horizontal line at this value (target price, average entry, 0%). */
+    dataY?: number;
+    /** Vertical line at this x index (event, earnings date). */
+    dataX?: number;
+    label?: string;
+    /** Where the label sits along the line. Default 'right' (horizontal) / 'top' (vertical). */
+    labelPosition?: 'left' | 'right' | 'center' | 'top' | 'bottom';
+    color?: string;
+    /** Dash pattern; '' for a solid line. Default '4 4'. */
+    dash?: string;
+    strokeWidth?: number;
+}
+export declare function ReferenceLine({ dataY, dataX, label, labelPosition, color, dash, strokeWidth }: ReferenceLineProps): import("react").JSX.Element | null;
+export interface PointProps {
+    /** X index. */
+    dataX: number;
+    /** Value. Omit with `seriesId` to sit on that series. */
+    dataY?: number;
+    seriesId?: string;
+    color?: string;
+    radius?: number;
+    /** Text next to the point (e.g. "매수", "고점 12,400"). */
+    label?: string;
+    labelPosition?: 'top' | 'bottom' | 'left' | 'right';
+    /** Live-price beacon. */
+    pulse?: boolean;
+    onClick?: () => void;
+}
+/** A marker at a data position: trades on a price line, highs/lows, the latest value. */
+export declare function Point({ dataX, dataY, seriesId, color, radius, label, labelPosition, pulse, onClick }: PointProps): import("react").JSX.Element | null;
+/** Label for a value in the default number format (exported for custom annotations). */
+export declare const formatValue: typeof formatNumber;

package/dist/viz/axes.d.ts

@@ -0,0 +1,43 @@
+export interface XAxisProps {
+    position?: 'bottom' | 'top';
+    /** Space reserved for the axis. Default 24. */
+    height?: number;
+    /** Indices to label. Default: evenly spaced, about one label per 80px. */
+    ticks?: readonly number[];
+    /** Label for x position `index` (value is `xAxis.data[index]`, if any). */
+    tickLabelFormatter?: (value: string | number | undefined, index: number) => string;
+    showLine?: boolean;
+    showTickMarks?: boolean;
+    /** Vertical grid lines at each tick. */
+    showGrid?: boolean;
+    /** Minimum pixels per label when picking ticks automatically. Default 80. */
+    minTickSpacing?: number;
+}
+export declare function XAxis({ position, height, ticks, tickLabelFormatter, showLine, showTickMarks, showGrid, minTickSpacing, }: XAxisProps): import("react").JSX.Element | null;
+export declare namespace XAxis {
+    var axisSpace: (p: XAxisProps) => {
+        side: "bottom" | "top";
+        size: number;
+    };
+}
+export interface YAxisProps {
+    /** Right is the trading-chart convention. Default 'right'. */
+    position?: 'left' | 'right';
+    /** Space reserved for labels. Default 48. */
+    width?: number;
+    /** Explicit tick values. Default: nice numbers, about one per 40px. */
+    ticks?: readonly number[];
+    tickLabelFormatter?: (value: number) => string;
+    /** Horizontal grid lines across the plot. Default true. */
+    showGrid?: boolean;
+    showLine?: boolean;
+    /** Minimum pixels between ticks when picking automatically. Default 32. */
+    minTickSpacing?: number;
+}
+export declare function YAxis({ position, width, ticks, tickLabelFormatter, showGrid, showLine, minTickSpacing, }: YAxisProps): import("react").JSX.Element;
+export declare namespace YAxis {
+    var axisSpace: (p: YAxisProps) => {
+        side: "left" | "right";
+        size: number;
+    };
+}

package/dist/viz/bar.d.ts

@@ -0,0 +1,17 @@
+export interface BarPlotProps {
+    /** Only draw these series (default: all). */
+    seriesIds?: readonly string[];
+    /** Corner radius at the bar's far end. Default 3. */
+    radius?: number;
+    /** Gap between grouped bars in one slot, px. Default 2. */
+    groupGap?: number;
+    /** Per-bar color (e.g. up/down volume). Return undefined to use the series color. */
+    getBarColor?: (value: number, index: number, seriesId: string) => string | undefined;
+    /** Dim bars other than the scrubbed one. Default true. */
+    highlightScrubbed?: boolean;
+}
+/**
+ * Bars for every series: side by side (grouped) or on top of each other when the chart
+ * is `stacked`. Needs `xAxis.scaleType: 'band'` (BarChart sets it).
+ */
+export declare function BarPlot({ seriesIds, radius, groupGap, getBarColor, highlightScrubbed }: BarPlotProps): import("react").JSX.Element | null;

package/dist/viz/cartesian-chart.d.ts

@@ -0,0 +1,64 @@
+import { type CSSProperties, type ReactNode } from 'react';
+import { type ChartSeries } from './context';
+import { type LegendPosition } from './legend';
+export type Inset = number | Partial<Record<'top' | 'right' | 'bottom' | 'left', number>>;
+export interface XAxisConfig {
+    /** Labels or timestamps per x position (for axis labels, scrubber and legend). */
+    data?: readonly (string | number)[];
+    /** 'band' gives each x position a slot (bar charts); 'linear' spreads points edge to edge. */
+    scaleType?: 'linear' | 'band';
+    /** Band padding between bars, 0–0.95. Default 0.25. */
+    bandPadding?: number;
+}
+export interface YAxisConfig {
+    /** Fix either end of the value range; the other end follows the data. */
+    domain?: {
+        min?: number;
+        max?: number;
+    };
+    /** Always include 0 (default for bar charts). */
+    includeZero?: boolean;
+    /** Round the range outward to nice numbers. Default false (use the data range). */
+    nice?: boolean;
+}
+export interface CartesianChartProps {
+    series: readonly ChartSeries[];
+    /** Pixel width. Omit to fill the parent (measured with ResizeObserver). */
+    width?: number;
+    /** Pixel height of the drawing area. Default 240. */
+    height?: number;
+    /** Space between the SVG edge and the plot (axes add their own space). Default 8. */
+    inset?: Inset;
+    xAxis?: XAxisConfig;
+    yAxis?: YAxisConfig;
+    /** Stack the series (areas / bars). */
+    stacked?: boolean;
+    /** Track the pointer and expose the hovered index to <Scrubber>, legends and headers. */
+    enableScrubbing?: boolean;
+    onScrubberPositionChange?: (index: number | null) => void;
+    /** Draw-in animation on mount. Default true (off when the user prefers reduced motion). */
+    animate?: boolean;
+    /** Series legend outside the plot. */
+    legend?: boolean | LegendPosition;
+    /** Format legend values while scrubbing. */
+    legendValueFormatter?: (value: number, seriesId: string) => string;
+    /** Override the categorical palette. */
+    palette?: readonly string[];
+    className?: string;
+    style?: CSSProperties;
+    'aria-label'?: string;
+    children?: ReactNode;
+}
+/** Axis components declare the space they need so the plot can shrink before the first paint. */
+export interface AxisSpace {
+    side: 'top' | 'right' | 'bottom' | 'left';
+    size: number;
+}
+/**
+ * The base of every x/y chart. Computes scales from `series` and provides them to its
+ * children (Line, Area, BarPlot, XAxis, YAxis, ReferenceLine, Point, Scrubber), which draw
+ * themselves as SVG. Compose your own chart from those parts, or use LineChart / AreaChart /
+ * BarChart for the common layouts.
+ */
+export declare function CartesianChart({ series, width: fixedWidth, height, inset, xAxis, yAxis, stacked, enableScrubbing, onScrubberPositionChange, animate, legend, legendValueFormatter, palette, className, style, 'aria-label': ariaLabel, children, }: CartesianChartProps): import("react").JSX.Element;
+export declare const DEFAULT_CHART_HEIGHT = 240;

package/dist/viz/charts.d.ts

@@ -0,0 +1,68 @@
+import { type Curve } from '@funnest/charts-viz';
+import { type CSSProperties, type ReactNode } from 'react';
+import { type XAxisProps, type YAxisProps } from './axes';
+import { type BarPlotProps } from './bar';
+import { type CartesianChartProps } from './cartesian-chart';
+import { type AreaFill } from './line';
+import { type ScrubberProps } from './scrubber';
+type AxisToggle<P> = boolean | P;
+interface PresetProps extends Omit<CartesianChartProps, 'children'> {
+    showXAxis?: AxisToggle<XAxisProps>;
+    showYAxis?: AxisToggle<YAxisProps>;
+    /** Pointer-follow line + dots (turns on `enableScrubbing`). */
+    scrubber?: AxisToggle<ScrubberProps>;
+    /** Extra parts drawn on top: ReferenceLine, Point, … */
+    children?: ReactNode;
+}
+export interface LineChartProps extends PresetProps {
+    curve?: Curve;
+    strokeWidth?: number;
+    /** Fill under each line. Default 'none'. */
+    area?: AreaFill;
+    connectNulls?: boolean;
+}
+/**
+ * Lines for every series. With no axes it is a sparkline:
+ * `<LineChart series={[{ id: 'p', data }]} height={40} inset={2} />`.
+ */
+export declare function LineChart({ showXAxis, showYAxis, scrubber, curve, strokeWidth, area, connectNulls, children, ...chart }: LineChartProps): import("react").JSX.Element;
+export interface AreaChartProps extends PresetProps {
+    curve?: Curve;
+    fill?: Exclude<AreaFill, 'none'>;
+    /** Draw the top edge line. Default true. */
+    showLines?: boolean;
+    strokeWidth?: number;
+}
+/** Filled areas; set `stacked` for a composition over time (e.g. portfolio by asset). */
+export declare function AreaChart({ showXAxis, showYAxis, scrubber, curve, fill, showLines, strokeWidth, children, ...chart }: AreaChartProps): import("react").JSX.Element;
+export interface BarChartProps extends PresetProps, Pick<BarPlotProps, 'radius' | 'getBarColor' | 'groupGap'> {
+}
+/** Grouped (or `stacked`) bars on a categorical x axis. Hover highlights a bar when `scrubber`. */
+export declare function BarChart({ showXAxis, showYAxis, scrubber, radius, getBarColor, groupGap, xAxis, children, ...chart }: BarChartProps): import("react").JSX.Element;
+export interface PercentageBarItem {
+    id: string;
+    label: string;
+    value: number;
+    color?: string;
+}
+export interface PercentageBarChartProps {
+    data: readonly PercentageBarItem[];
+    /** Bar thickness. Default 10. */
+    barHeight?: number;
+    /** Gap between segments, px. Default 2. */
+    gap?: number;
+    /** Labels with percentages under the bar. Default true. */
+    showLabels?: boolean;
+    /** Format the label value. Default: "62.5%". */
+    formatLabel?: (item: PercentageBarItem, fraction: number) => string;
+    palette?: readonly string[];
+    className?: string;
+    style?: CSSProperties;
+    'aria-label'?: string;
+}
+/**
+ * One horizontal bar split into shares: portfolio weights, buy/sell pressure,
+ * long/short ratio.
+ */
+export declare function PercentageBarChart({ data, barHeight, gap, showLabels, formatLabel, palette, className, style, 'aria-label': ariaLabel, }: PercentageBarChartProps): import("react").JSX.Element;
+export {};

package/dist/viz/context.d.ts

@@ -0,0 +1,65 @@
+import type { BandScale, LinearScale, StackedSeries } from '@funnest/charts-viz';
+export interface ChartSeries {
+    id: string;
+    /** Values per x position; null = gap. */
+    data: readonly (number | null)[];
+    label?: string;
+    /** Any CSS color. Defaults to the palette. */
+    color?: string;
+}
+/** A series with its resolved color. */
+export interface ResolvedSeries extends ChartSeries {
+    color: string;
+    index: number;
+}
+export interface PlotRect {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+    width: number;
+    height: number;
+}
+export interface CartesianContextValue {
+    /** Unique per chart, for SVG ids (gradients, clip paths). */
+    id: string;
+    width: number;
+    height: number;
+    plot: PlotRect;
+    series: ResolvedSeries[];
+    getSeries(id: string): ResolvedSeries | undefined;
+    /** Number of x positions. */
+    length: number;
+    /** Pixel x of x position `i` (band center for bar charts). */
+    x(i: number): number;
+    /** Set when the x axis is categorical (bar charts). */
+    band: BandScale | null;
+    y: LinearScale;
+    /** Stacked edges per series id when `stacked`. */
+    stacked: Map<string, StackedSeries> | null;
+    /** Label for x position `i` (from `xAxis.data`, else the index). */
+    xLabel(i: number): string;
+    xData: readonly (string | number)[] | undefined;
+    /** Index under the pointer, or null. */
+    scrubIndex: number | null;
+    animate: boolean;
+}
+export declare const CartesianContext: import("react").Context<CartesianContextValue | null>;
+export declare function useCartesianChart(): CartesianContextValue;
+/**
+ * Visual tokens. Override with CSS variables on any ancestor. The fallbacks use the CSS
+ * system colors (Canvas / CanvasText), so charts follow the page's light/dark
+ * `color-scheme` with no setup.
+ */
+export declare const VAR: {
+    readonly text: 'var(--fnv-text-muted, color-mix(in srgb, CanvasText 50%, Canvas))';
+    readonly textStrong: 'var(--fnv-text, CanvasText)';
+    readonly grid: 'var(--fnv-grid, color-mix(in srgb, CanvasText 9%, transparent))';
+    readonly line: 'var(--fnv-line, color-mix(in srgb, CanvasText 32%, transparent))';
+    readonly bg: 'var(--fnv-bg, Canvas)';
+    readonly font: 'var(--fnv-font, inherit)';
+};
+/** Default number display: full digits up to 100k, compact (1.2M, 34만) beyond. */
+export declare const formatNumber: (v: number) => string;
+/** Pixel y of series `s` at index `i` (top edge when stacked), or null for a gap. */
+export declare function seriesY(ctx: CartesianContextValue, s: ResolvedSeries, i: number): number | null;

package/dist/viz/index.d.ts

@@ -0,0 +1,10 @@
+export { CartesianChart, type CartesianChartProps, type XAxisConfig, type YAxisConfig, type Inset } from './cartesian-chart';
+export { XAxis, YAxis, type XAxisProps, type YAxisProps } from './axes';
+export { Line, Area, type LineProps, type AreaProps, type AreaFill } from './line';
+export { BarPlot, type BarPlotProps } from './bar';
+export { Scrubber, type ScrubberProps } from './scrubber';
+export { ReferenceLine, Point, type ReferenceLineProps, type PointProps } from './annotations';
+export { Legend, type LegendProps, type LegendItem, type LegendPosition } from './legend';
+export { PeriodSelector, DEFAULT_PERIODS, type PeriodSelectorProps, type Period } from './period-selector';
+export { LineChart, AreaChart, BarChart, PercentageBarChart, type LineChartProps, type AreaChartProps, type BarChartProps, type PercentageBarChartProps, type PercentageBarItem, } from './charts';
+export { useCartesianChart, formatNumber, type ChartSeries, type CartesianContextValue, type PlotRect } from './context';

package/dist/viz/legend.d.ts

@@ -0,0 +1,24 @@
+import type { CSSProperties } from 'react';
+export type LegendPosition = 'top' | 'bottom';
+export interface LegendItem {
+    id: string;
+    label: string;
+    color: string;
+    /** Shown after the label (e.g. the scrubbed value). */
+    value?: string | undefined;
+    /** Rendered dimmed (series hidden). */
+    inactive?: boolean;
+}
+export interface LegendProps {
+    items: readonly LegendItem[];
+    /** Click to toggle a series; omit for a static legend. */
+    onItemClick?: (id: string) => void;
+    /** Pointer enters (id) or leaves (null) an item — e.g. to highlight that series. */
+    onItemHover?: (id: string | null) => void;
+    /** 'circle' (default), 'square' or 'line' swatches. */
+    shape?: 'circle' | 'square' | 'line';
+    className?: string;
+    style?: CSSProperties;
+}
+/** Series key, HTML (not SVG) so it wraps and stays readable at any width. */
+export declare function Legend({ items, onItemClick, onItemHover, shape, className, style }: LegendProps): import("react").JSX.Element;

package/dist/viz/line.d.ts

@@ -0,0 +1,35 @@
+import { type Curve, type XY } from '@funnest/charts-viz';
+import { type CartesianContextValue, type ResolvedSeries } from './context';
+export type AreaFill = 'gradient' | 'solid' | 'none';
+/** Pixel points of a series split at gaps (or joined across them with `connectNulls`). */
+export declare function seriesRuns(ctx: CartesianContextValue, s: ResolvedSeries, connectNulls?: boolean): {
+    upper: XY[];
+    lower: {
+        x: number;
+        y: number;
+    }[] | null;
+}[];
+export interface AreaProps {
+    seriesId: string;
+    curve?: Curve;
+    fill?: Exclude<AreaFill, 'none'>;
+    /** Fill opacity at the line (gradient fades to 0). Default 0.24 (solid 0.16). */
+    opacity?: number;
+    connectNulls?: boolean;
+}
+/** Filled area under a series (between stacked edges when the chart is stacked). */
+export declare function Area({ seriesId, curve, fill, opacity, connectNulls }: AreaProps): import("react").JSX.Element | null;
+export interface LineProps {
+    seriesId: string;
+    curve?: Curve;
+    strokeWidth?: number;
+    /** Dashed line, e.g. "4 4". */
+    dash?: string;
+    /** Draw across null gaps instead of breaking. */
+    connectNulls?: boolean;
+    /** Also fill underneath. Default 'none'. */
+    area?: AreaFill;
+    areaOpacity?: number;
+    opacity?: number;
+}
+export declare function Line({ seriesId, curve, strokeWidth, dash, connectNulls, area, areaOpacity, opacity, }: LineProps): import("react").JSX.Element | null;

package/dist/viz/period-selector.d.ts

@@ -0,0 +1,21 @@
+import { type CSSProperties } from 'react';
+export interface Period {
+    id: string;
+    label: string;
+}
+/** Common ranges for price charts. */
+export declare const DEFAULT_PERIODS: readonly Period[];
+export interface PeriodSelectorProps {
+    periods?: readonly Period[];
+    value: string;
+    onChange: (id: string) => void;
+    /** Active pill color. Default Funnest violet (set --fnv-accent to theme). */
+    activeColor?: string;
+    /** Stretch the tabs across the full width (mobile). */
+    fullWidth?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    'aria-label'?: string;
+}
+/** Range tabs (1D 1W 1M …) with a sliding pill; arrow keys move between tabs. */
+export declare function PeriodSelector({ periods, value, onChange, activeColor, fullWidth, className, style, 'aria-label': ariaLabel, }: PeriodSelectorProps): import("react").JSX.Element;

package/dist/viz/scrubber.d.ts

@@ -0,0 +1,18 @@
+export interface ScrubberProps {
+    /** Text above the scrub line. Default: the x label (`xAxis.data[index]`). Return '' to hide. */
+    label?: (index: number) => string;
+    /** Only mark these series (default: all). */
+    seriesIds?: readonly string[];
+    /** Dim the part of each line right of the scrubber. Default true. */
+    dimFuture?: boolean;
+    /** Tooltip with each series' value at the scrubbed index. Default false. */
+    showValues?: boolean;
+    /** Format tooltip values. */
+    valueFormatter?: (value: number, seriesId: string) => string;
+}
+/**
+ * Pointer-follow overlay: vertical line, a dot on each series and a label. Requires
+ * `enableScrubbing` on the chart. Read the index yourself with `onScrubberPositionChange`
+ * to drive a header (price / change at that point).
+ */
+export declare function Scrubber({ label, seriesIds, dimFuture, showValues, valueFormatter }: ScrubberProps): import("react").JSX.Element | null;

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@funnest/charts-react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "React bindings for Funnest Charts: the trading widget plus SVG line, area and bar charts",
+  "keywords": [
+    "react",
+    "chart",
+    "trading",
+    "candlestick",
+    "financial",
+    "line-chart",
+    "area-chart",
+    "bar-chart",
+    "sparkline",
+    "svg"
+  ],
+  "license": "Apache-2.0",
+  "author": "Funnest",
+  "homepage": "https://charts.funnest.xyz",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/funnest-xyz/funnest-charts.git",
+    "directory": "packages/react"
+  },
+  "bugs": {
+    "url": "https://github.com/funnest-xyz/funnest-charts/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "funnest-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "dependencies": {
+    "@funnest/charts": "0.1.0",
+    "@funnest/charts-viz": "0.1.0",
+    "@funnest/charts-ui": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "devDependencies": {
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --clean --external react --external react-dom --external @funnest/charts-ui --external @funnest/charts --external @funnest/charts-viz && tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json"
+  }
 }