@overdoser/react-toolkit 0.0.6 → 0.0.8

package/components/Chart/Sparkline.d.ts

@@ -0,0 +1,31 @@
+import { CSSProperties } from 'react';
+export interface SparklineProps {
+    /** Numeric series, in left-to-right order. */
+    data: number[];
+    /** Pixel width. @default 80 */
+    width?: number;
+    /** Pixel height. @default 24 */
+    height?: number;
+    /** Stroke color (CSS). @default 'var(--crk-chart-1)' */
+    color?: string;
+    /** Stroke width in pixels. @default 1.5 */
+    strokeWidth?: number;
+    /** Interpolation between points. @default 'monotone' */
+    curve?: 'linear' | 'monotone';
+    /** Fill the area under the line. @default false */
+    fill?: boolean;
+    /** Draw a dot at the last point. @default false */
+    showLastPoint?: boolean;
+    /** Accessible label for the chart (`aria-label`). */
+    'aria-label'?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Tiny inline trend line with no axes, legend, or tooltip — sized in pixels
+ * so it can sit inside a table cell, KPI tile, or anywhere a glyph fits.
+ *
+ * @example
+ * <Sparkline data={[1, 3, 2, 4, 3, 5, 4]} />
+ */
+export declare const Sparkline: import('react').ForwardRefExoticComponent<SparklineProps & import('react').RefAttributes<SVGSVGElement>>;

package/components/Chart/TradingChart.d.ts

@@ -0,0 +1,89 @@
+import { CSSProperties } from 'react';
+import { Bar, CrosshairInfo, Datafeed, IndicatorConfig, Period, Resolution, SeriesType, Timezone, VisibleRange } from './trading/types';
+export interface TradingChartProps {
+    datafeed: Datafeed;
+    symbol: string;
+    resolution: Resolution;
+    /**
+     * Visible time-range window (e.g. `'1D'`, `'5D'`, `'1M'`, `'1Y'`, `'5Y'`).
+     * When set, the chart fetches bars for the last `period` of time and the
+     * initial visible range covers the whole window. Overrides `initialLookback`.
+     *
+     * The chart does not auto-adjust `resolution` when `period` changes — use
+     * `suggestResolutionForPeriod()` / `suggestPeriodForResolution()` if you
+     * want them coupled in your UI.
+     */
+    period?: Period;
+    /** Main-pane series style. @default 'candle' */
+    seriesType?: SeriesType;
+    /** Indicators to render. Overlays go on the main pane; volume/rsi get their own sub-pane below. */
+    indicators?: IndicatorConfig[];
+    /** Decimal places for price labels and tooltip. @default 2 */
+    precision?: number;
+    /** Initial historical bars to request when `period` is not set. @default 500 */
+    initialLookback?: number;
+    /** Pixel height of the chart. @default 420 */
+    height?: number;
+    /** Up-candle / line color. @default 'var(--crk-color-success)' */
+    upColor?: string;
+    /** Down-candle color. @default 'var(--crk-color-danger)' */
+    downColor?: string;
+    /** Stroke color for `seriesType="line"` and the area outline. @default 'var(--crk-chart-1)' */
+    lineColor?: string;
+    /**
+     * Controlled timezone — pair with `onTimezoneChange` if the consumer wants
+     * to own the value. If omitted, the chart uses `defaultTimezone` and the
+     * built-in config panel manages it internally.
+     */
+    timezone?: Timezone;
+    /** Initial timezone when uncontrolled. @default 'local' */
+    defaultTimezone?: Timezone;
+    /** Fires when the timezone changes — either via the config panel or
+     *  externally. */
+    onTimezoneChange?: (tz: Timezone) => void;
+    /**
+     * Show the gear button + configuration popover in the chart header.
+     * The panel lets the user pick a timezone today; more settings will live
+     * here in the future. @default true
+     */
+    showConfigPanel?: boolean;
+    /** Fired when the crosshair moves (`null` when leaving the chart). */
+    onCrosshair?: (info: CrosshairInfo | null) => void;
+    /** Fired after pan / zoom / data updates. */
+    onVisibleRangeChange?: (range: VisibleRange, bars: Bar[]) => void;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Canvas-rendered candlestick / line / area chart with a TradingView-style
+ * datafeed adapter, pan + zoom + crosshair, and a small library of built-in
+ * indicators (SMA, EMA, Bollinger Bands as overlays; RSI and Volume in
+ * sub-panes).
+ *
+ * Drop a `Datafeed` in and the chart calls `getBars` on mount, then
+ * `subscribeBars` for realtime ticks. Pan-left past the loaded window
+ * triggers another `getBars` for older history automatically.
+ *
+ * @example
+ * <TradingChart
+ *   datafeed={myDatafeed}
+ *   symbol="AAPL"
+ *   resolution="60"
+ *   seriesType="candle"
+ *   indicators={[
+ *     { type: 'ema', period: 12, color: 'var(--crk-chart-2)' },
+ *     { type: 'ema', period: 26, color: 'var(--crk-chart-3)' },
+ *     { type: 'volume' },
+ *     { type: 'rsi' },
+ *   ]}
+ * />
+ */
+export declare function TradingChart({ datafeed, symbol, resolution, period, seriesType, indicators, precision, initialLookback, height, upColor, downColor, lineColor, timezone, defaultTimezone, onTimezoneChange, showConfigPanel, onCrosshair, onVisibleRangeChange, className, style, }: TradingChartProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Full crosshair date/time label with a timezone tag.
+ * Format: `YYYY-MM-DD HH:MM:SS <tz>` — `<tz>` is `+HH:MM` for local,
+ * `UTC`, or the short timezone name (`EST`, `BST`, …) for IANA zones.
+ */
+export declare function formatCrosshairTime(unixSec: number, timezone: Timezone): string;
+/** Convert a TV-style resolution to an approximate seconds-per-bar count. */
+export declare function approxIntervalSeconds(resolution: Resolution): number;

package/components/Chart/index.d.ts

@@ -0,0 +1,18 @@
+export { LineChart } from './LineChart';
+export type { LineChartProps, LineLabelArgs, LineDotArgs, LinePointClickArgs, } from './LineChart';
+export { AreaChart } from './AreaChart';
+export type { AreaChartProps } from './AreaChart';
+export { BarChart } from './BarChart';
+export type { BarChartProps, BarClickArgs, BarLabelArgs } from './BarChart';
+export { PieChart } from './PieChart';
+export type { PieChartProps, PieLabelArgs, PieSliceClickArgs } from './PieChart';
+export { RadarChart } from './RadarChart';
+export type { RadarChartProps, RadarAxisLabelArgs } from './RadarChart';
+export { TradingChart, formatCrosshairTime } from './TradingChart';
+export type { TradingChartProps } from './TradingChart';
+export type { Bar, Resolution, Period, Timezone, Datafeed, GetBarsArgs, SubscribeBarsArgs, SubscriptionHandle, SeriesType, IndicatorConfig, CrosshairInfo, VisibleRange, } from './trading/types';
+export { sma, ema, bollinger, rsi, volume as volumeSeries } from './trading/indicators';
+export { periodToSeconds, suggestResolutionForPeriod, suggestPeriodForResolution, } from './trading/period';
+export { Sparkline } from './Sparkline';
+export type { SparklineProps } from './Sparkline';
+export type { ChartConfig, SeriesConfig, ChartClasses, ChartMargin } from './types';

package/components/Chart/scales.d.ts

@@ -0,0 +1,21 @@
+/** Returns the [min, max] of a numeric series. */
+export declare function extent(values: number[]): [number, number];
+/** Maps a numeric domain `[d0, d1]` to a pixel range `[r0, r1]`. */
+export declare function linearScale(domain: [number, number], range: [number, number]): {
+    (v: number): number;
+    invert(px: number): number;
+};
+/**
+ * Categorical scale — maps each domain entry to the center of an equal-width band.
+ * `padding` is the inner gap as a fraction of band width.
+ */
+export declare function bandScale<T extends string | number>(domain: T[], range: [number, number], padding?: number): {
+    (v: T): number;
+    bandWidth(): number;
+    step(): number;
+};
+/**
+ * Returns approximately `count` "nice" tick values that span `[min, max]`.
+ * Uses a 1/2/5 × 10ⁿ progression so labels round cleanly.
+ */
+export declare function niceTicks(min: number, max: number, count?: number): number[];

package/components/Chart/trading/indicators.d.ts

@@ -0,0 +1,28 @@
+import { Bar } from './types';
+/**
+ * Simple Moving Average over `period` bars. The first `period - 1` entries
+ * are `null` (warm-up) so the resulting array is aligned to `bars`.
+ */
+export declare function sma(bars: Bar[], period: number): (number | null)[];
+/**
+ * Exponential Moving Average with the standard `α = 2 / (period + 1)`
+ * smoothing constant, seeded with the first `period` bars' SMA.
+ */
+export declare function ema(bars: Bar[], period: number): (number | null)[];
+export interface BollingerBands {
+    middle: (number | null)[];
+    upper: (number | null)[];
+    lower: (number | null)[];
+}
+/**
+ * Bollinger Bands. `middle` is an SMA of `period` closes; `upper`/`lower`
+ * are `middle ± stdDev * σ` where σ is the population standard deviation.
+ */
+export declare function bollinger(bars: Bar[], period: number, stdDev?: number): BollingerBands;
+/**
+ * Relative Strength Index using Wilder's smoothing (the original definition).
+ * Output ranges 0–100; first `period` entries are `null`.
+ */
+export declare function rsi(bars: Bar[], period?: number): (number | null)[];
+/** Pass-through of the volume series for convenience and downstream typing. */
+export declare function volume(bars: Bar[]): (number | null)[];

package/components/Chart/trading/period.d.ts

@@ -0,0 +1,19 @@
+import { Period, Resolution } from './types';
+/**
+ * Convert a `Period` string to seconds. Accepts the typed presets as well as
+ * any `<n><unit>` string where unit is `h` / `d` / `w` / `m` / `y`
+ * (case-insensitive). Falls back to 30 days on unparseable input.
+ */
+export declare function periodToSeconds(period: Period): number;
+/**
+ * Recommend a `Resolution` for a given `Period`, targeting roughly 200–500
+ * visible bars — the sweet spot where candles stay legible and the price axis
+ * has enough headroom. Consumers can override; the coupling is opinionated,
+ * not enforced.
+ */
+export declare function suggestResolutionForPeriod(period: Period): Resolution;
+/**
+ * Recommend a `Period` for a given `Resolution` — the inverse of
+ * `suggestResolutionForPeriod`. Same 200–500-bar target.
+ */
+export declare function suggestPeriodForResolution(resolution: Resolution): Period;

package/components/Chart/trading/types.d.ts

@@ -0,0 +1,122 @@
+/**
+ * A single OHLCV bar. `time` is a unix timestamp **in seconds** (TradingView
+ * convention). `volume` is optional — when absent, the volume sub-pane shows
+ * nothing meaningful.
+ */
+export interface Bar {
+    time: number;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    volume?: number;
+}
+/**
+ * TradingView-style resolution string — the size of one bar. Minutes are bare
+ * numbers (`'1'`, `'5'`, `'60'`), and longer periods use letter suffixes:
+ * - `'D'`  — daily
+ * - `'W'`  — weekly
+ * - `'M'`  — monthly
+ *
+ * Any other string is accepted (passed through to the datafeed) — useful for
+ * exchange-specific intervals (`'1H'`, `'4H'`, `'12H'`, etc.).
+ */
+export type Resolution = '1' | '3' | '5' | '15' | '30' | '60' | '120' | '240' | 'D' | 'W' | 'M' | (string & {});
+/**
+ * Visible time-range window. Drives the initial X-axis span of the chart.
+ * Common presets are typed; any other `<n><unit>` string (`'30d'`, `'2y'`,
+ * `'48h'`, …) is accepted and parsed.
+ */
+export type Period = '1D' | '5D' | '1M' | '3M' | '6M' | '1Y' | '5Y' | (string & {});
+/**
+ * Timezone used to render the crosshair date/time label.
+ * - `'local'` — the user's local timezone (offset shown as `+HH:MM`).
+ * - `'utc'`   — UTC.
+ * - Any other string is treated as an IANA timezone name
+ *   (e.g. `'America/New_York'`, `'Europe/London'`).
+ */
+export type Timezone = 'local' | 'utc' | (string & {});
+/** Returned by `subscribeBars` so the chart can later unsubscribe. */
+export type SubscriptionHandle = string | number | symbol | object;
+export interface GetBarsArgs {
+    symbol: string;
+    resolution: Resolution;
+    /** Inclusive lower bound, unix seconds. */
+    from: number;
+    /** Inclusive upper bound, unix seconds. */
+    to: number;
+    /** Hint about how many bars to return; the datafeed may return more or fewer. */
+    countBack?: number;
+}
+export interface SubscribeBarsArgs {
+    symbol: string;
+    resolution: Resolution;
+    /**
+     * Called when a new tick arrives. If the bar's `time` equals the previous
+     * bar's `time`, the chart treats it as an update to the in-progress bar;
+     * otherwise it's appended as a new bar.
+     */
+    onTick: (bar: Bar) => void;
+}
+/**
+ * Plug-in interface for streaming or batched OHLCV data — modelled on the
+ * TradingView Charting Library so adapters port over with minimal churn.
+ */
+export interface Datafeed {
+    /** Resolve a historical window. Must return bars sorted by `time` ascending. */
+    getBars(args: GetBarsArgs): Promise<Bar[]>;
+    /** Start streaming live ticks for `symbol` at `resolution`. */
+    subscribeBars(args: SubscribeBarsArgs): SubscriptionHandle;
+    /** Stop the corresponding subscription. */
+    unsubscribeBars(handle: SubscriptionHandle): void;
+}
+/**
+ * Visual series mode for the main pane.
+ * - `'candle'` — filled candlesticks (open/close body + high/low wick).
+ * - `'bar'`    — OHLC bars (high/low vertical line + open tick left + close tick right).
+ * - `'line'`   — close-price line.
+ * - `'area'`   — close-price line with a translucent fill below.
+ */
+export type SeriesType = 'candle' | 'bar' | 'line' | 'area';
+/** Configuration for one indicator. Concrete shape depends on `type`. */
+export type IndicatorConfig = {
+    type: 'sma';
+    period: number;
+    color?: string;
+} | {
+    type: 'ema';
+    period: number;
+    color?: string;
+} | {
+    type: 'bollinger';
+    period: number;
+    stdDev?: number;
+    color?: string;
+    fillOpacity?: number;
+} | {
+    type: 'rsi';
+    period?: number;
+    color?: string;
+    overbought?: number;
+    oversold?: number;
+} | {
+    type: 'volume';
+    upColor?: string;
+    downColor?: string;
+};
+/** Reported to consumers when the user moves the crosshair. */
+export interface CrosshairInfo {
+    /** Index of the bar under the crosshair, or `null` if off-chart. */
+    barIndex: number | null;
+    /** Bar at `barIndex`, or `null` if off-chart. */
+    bar: Bar | null;
+    /** Y-axis value the crosshair sits at, in price units (main pane). */
+    priceAtCursor: number | null;
+}
+/** Returned by useful internal helpers; not part of the public API. */
+export interface VisibleRange {
+    /** First bar index (fractional during smooth pan). */
+    from: number;
+    /** Last bar index. */
+    to: number;
+}

package/components/Chart/types.d.ts

@@ -0,0 +1,60 @@
+import { ReactNode } from 'react';
+/** Configuration for a single data series in a chart. */
+export interface SeriesConfig {
+    /** Visible label in the legend and tooltip. */
+    label: string;
+    /** CSS color value, e.g. `'var(--crk-chart-1)'` or `'#ff0'`. */
+    color: string;
+    /**
+     * Optional icon to render in the legend instead of the default color
+     * swatch. Use an inline SVG for best results; it inherits `color` from
+     * the series, so `stroke="currentColor"` / `fill="currentColor"` are
+     * recommended.
+     */
+    icon?: ReactNode;
+}
+/**
+ * Keyed by data-field name. Each entry configures one rendered series.
+ * The keys here must match keys present on the rows in `data`.
+ *
+ * @example
+ * const config: ChartConfig = {
+ *   revenue: { label: 'Revenue', color: 'var(--crk-chart-1)' },
+ *   costs:   { label: 'Costs',   color: 'var(--crk-chart-2)' },
+ * };
+ */
+export type ChartConfig = Record<string, SeriesConfig>;
+/** Override class names on internal elements of any chart. */
+export interface ChartClasses {
+    root: string;
+    svg: string;
+    grid: string;
+    axis: string;
+    axisLabel: string;
+    series: string;
+    point: string;
+    legend: string;
+    legendItem: string;
+    tooltip: string;
+}
+/** Inner padding (in CSS pixels) between the SVG edge and the plot area. */
+export interface ChartMargin {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/** Active hover state shared by all axis-based charts. */
+export interface ActivePoint {
+    /** Index into the chart's `data` array. */
+    index: number;
+    /** Pixel coordinates (SVG-space) of the focal point. */
+    x: number;
+    y: number;
+}
+/** Render-prop signature for a custom tooltip body. */
+export type TooltipRenderer<T> = (args: {
+    row: T;
+    index: number;
+    config: ChartConfig;
+}) => ReactNode;

package/components/Chart/useChartDimensions.d.ts

@@ -0,0 +1,12 @@
+import { RefObject } from 'react';
+export interface ChartDimensions {
+    width: number;
+    height: number;
+}
+/**
+ * Tracks the rendered size of `ref` using `ResizeObserver`.
+ *
+ * `initial` is used until the observer reports the real size; pick something
+ * non-zero so SSR / first paint has plausible scales.
+ */
+export declare function useChartDimensions(ref: RefObject<HTMLElement | null>, initial?: ChartDimensions): ChartDimensions;

package/components/Popover/Popover.d.ts

@@ -5,8 +5,23 @@ export interface PopoverClasses {
     popover: string;
 }
 export interface PopoverProps {
-    /** Trigger content. Wrapped in an internal `<button>`. */
+    /**
+     * Trigger content. By default, wrapped in an internal `<button>` — pass any
+     * `ReactNode` (string, icon, fragment). If you need to pass your own
+     * interactive element (e.g. a `<Button>`) without the extra wrapping that
+     * would nest `<button>` inside `<button>`, set `asChild` and pass a single
+     * React element instead.
+     */
     trigger: React.ReactNode;
+    /**
+     * Render the trigger as-is (no internal `<button>` wrapper) and merge the
+     * onClick / `aria-*` handlers + ref into it. The trigger MUST be a single
+     * React element whose root is interactive (e.g. a `<button>`, `<a>`, or a
+     * `role="button"` element). Use this when nesting `<button>` inside
+     * `<button>` would otherwise produce a hydration warning.
+     * @default false
+     */
+    asChild?: boolean;
     /** Panel content. Rendered inside a `[role="dialog"]` when open. */
     content: React.ReactNode;
     /** Side of the trigger to anchor the panel to. @default 'bottom' */