import { type TemporalFormat } from "@trackunit/date-and-time-utils";
import { CommonProps, Refable, type Styleable } from "@trackunit/react-components";
import { ECElementEvent } from "echarts";
import { ReactElement } from "react";
export interface BarChartData<TProps extends object = object> {
    /**
     * The value to show for to the user
     */
    value?: number;
    /**
     * If selected, it'll be highlighted
     */
    selected?: boolean;
    /**
     * Per-bar color. Falls back to the series color / auto color when omitted.
     */
    color?: string;
    /**
     * Supply the original object that this chart data item was constructed from. It'll be available on callbacks
     */
    original?: TProps;
}
export interface BarChartGenericData<TProps extends object = object> extends BarChartData<TProps> {
    /**
     * The value to display on the x-axis
     */
    key: string;
}
export interface BarChartDateData<TProps extends object = object> extends BarChartData<TProps> {
    /**
     * The date value to display on the x-axis
     */
    date: string;
}
export interface SeriesData<TProps extends object> {
    name: string;
    color?: string;
    data: Array<BarChartGenericData<TProps>> | Array<BarChartDateData<TProps>>;
}
/**
 * A single entry in a tooltip payload. For `trigger: "item"` there is one entry;
 * for `trigger: "axis"` there is one entry per series at the hovered category.
 */
export interface BarChartTooltipEntry<TProps extends object = object> {
    /**
     * The name of the series this entry belongs to
     */
    seriesName: string;
    /**
     * The numeric value of the hovered bar
     */
    value: number | undefined;
    /**
     * The resolved color of the bar
     */
    color: string;
    /**
     * The colored-dot marker HTML that ECharts provides
     */
    marker: string;
    /**
     * The index of the data item within its series
     */
    dataIndex: number;
    /**
     * The original object the data item was constructed from
     */
    original?: TProps;
}
/**
 * Typed tooltip payload passed to `tooltip.formatter`.
 */
export interface BarChartTooltipParams<TProps extends object = object> {
    /**
     * The x-axis category/date value being hovered
     */
    axisValue: string;
    /**
     * One entry for `trigger: "item"`, one entry per series for `trigger: "axis"`
     */
    entries: Array<BarChartTooltipEntry<TProps>>;
}
export interface BarChartXAxisOptions {
    /**
     * Date granularity for date-based x-axis labels. Defaults to
     * `{ selectFormat: "dateOnly", dateFormat: "medium" }`.
     */
    dateFormat?: TemporalFormat;
    /**
     * Full control over the x-axis label string. Wins over `dateFormat`.
     */
    formatLabel?: (value: string, index: number) => string;
    /**
     * Rotation of the x-axis labels in degrees. Defaults to `45`; `0` renders horizontal labels.
     */
    rotateLabels?: number;
}
export interface BarChartYAxisOptions {
    /**
     * Locale-aware compact y-axis labels (e.g. `40,000 → 40K`). Defaults to `false`.
     */
    abbreviate?: boolean;
    /**
     * Full control over the y-axis label string. Wins over `abbreviate`.
     */
    formatLabel?: (value: number) => string;
}
export interface BarChartTooltipOptions<TProps extends object = object> {
    /**
     * Format a single tooltip value. Defaults to `` `${value} ${units}` ``.
     */
    formatValue?: (value: number) => string;
    /**
     * Build the entire tooltip from a typed payload. Wins over `formatValue`.
     */
    formatter?: (params: BarChartTooltipParams<TProps>) => string;
    /**
     * Tooltip trigger mode. Defaults to `"item"`.
     */
    trigger?: "item" | "axis";
}
export interface BarChartProps<TProps extends object> extends CommonProps, Refable<HTMLDivElement>, Styleable {
    /**
     * Array of series of data points to show
     */
    series: SeriesData<TProps> | Array<SeriesData<TProps>> | undefined;
    /**
     * onClick handler which includes the data object clicked on
     */
    onClick?: (event: ECElementEvent) => void;
    /**
     * Show chart as loading
     */
    loading?: boolean;
    /**
     * The units to show in the chart
     */
    units?: string;
    /**
     * Show data zoom
     */
    showDataZoom?: boolean;
    /**
     * Curated x-axis customization (label formatting and rotation).
     */
    xAxis?: BarChartXAxisOptions;
    /**
     * Curated y-axis customization (label formatting and abbreviation).
     */
    yAxis?: BarChartYAxisOptions;
    /**
     * Curated tooltip customization (value/payload formatting and trigger mode).
     */
    tooltip?: BarChartTooltipOptions<TProps>;
    /**
     * Toggle the custom legend row. Defaults to `true`.
     */
    showLegend?: boolean;
}
/**
 * Create a BarChart with automatic legends and formatting. Built on top of the Chart component
 * with sensible defaults for displaying categorical or time-series data.
 *
 * All customization props are optional and default to the component's original rendering, so
 * existing usages are unaffected.
 *
 * ### When to use
 * - To compare values across categories
 * - To show trends over time with discrete intervals
 * - When you need multiple series displayed side by side
 *
 * @example Bar chart with date-based data
 * ```tsx
 * import { BarChart } from "@trackunit/react-chart-components";
 *
 * const UtilizationChart = () => (
 *   <BarChart
 *     series={{
 *       name: "Utilization",
 *       data: [
 *         { date: "2024-01-01", value: 85 },
 *         { date: "2024-01-02", value: 72 },
 *         { date: "2024-01-03", value: 91 },
 *       ],
 *     }}
 *     units="%"
 *     onClick={(event) => console.log("Clicked bar:", event.data)}
 *   />
 * );
 * ```
 * @example Multi-series bar chart with data zoom
 * ```tsx
 * import { BarChart } from "@trackunit/react-chart-components";
 *
 * const ComparisonChart = () => (
 *   <BarChart
 *     series={[
 *       { name: "2023", color: "#3b82f6", data: [{ key: "Q1", value: 100 }, { key: "Q2", value: 120 }] },
 *       { name: "2024", color: "#10b981", data: [{ key: "Q1", value: 130 }, { key: "Q2", value: 145 }] },
 *     ]}
 *     units="units"
 *     showDataZoom={true}
 *   />
 * );
 * ```
 * @example Abbreviated y-axis, horizontal x-axis labels and a hidden legend
 * ```tsx
 * import { BarChart } from "@trackunit/react-chart-components";
 *
 * const EmissionsChart = () => (
 *   <BarChart
 *     series={{ name: "Emissions", data: [{ key: "Excavator", value: 40000, color: "#3b82f6" }] }}
 *     units="t"
 *     yAxis={{ abbreviate: true }}
 *     xAxis={{ rotateLabels: 0, formatLabel: (value) => value.slice(0, 10) }}
 *     showLegend={false}
 *   />
 * );
 * ```
 * @example Custom tooltip from the typed payload
 * ```tsx
 * import { BarChart } from "@trackunit/react-chart-components";
 *
 * const TrendChart = () => (
 *   <BarChart
 *     series={{ name: "Emissions", data: [{ date: "2024-01-01", value: 120 }] }}
 *     tooltip={{
 *       trigger: "axis",
 *       formatter: ({ axisValue, entries }) =>
 *         `${axisValue}<br/>${entries.map((e) => `${e.marker} ${e.seriesName}: ${e.value ?? 0}`).join("<br/>")}`,
 *     }}
 *   />
 * );
 * ```
 * @param {BarChartProps} props - The props for the Chart component
 * @returns {ReactElement} Chart component
 */
export declare const BarChart: <TProps extends object>({ series, loading, onClick, className, style, "data-testid": dataTestId, units, showDataZoom, xAxis, yAxis, tooltip, showLegend, ref, }: BarChartProps<TProps>) => ReactElement;