export type MetricTrendDirection = 'up' | 'down';
/**
 * How a change should read to the user. Deliberately separate from direction:
 * a metric can fall and read positive, or move and read neutral, so the arrow
 * and the sentiment are independent.
 */
export type MetricTrendTone = 'positive' | 'negative' | 'neutral';
/** Display-ready trend for an overview score or metric. */
export interface MetricTrend {
    direction: MetricTrendDirection;
    /** Formatted change, for example `9` or `32%`. */
    value: string;
    tone: MetricTrendTone;
}
export interface MetricChange {
    /** Signed difference, current minus previous. */
    delta: number;
    /** Magnitude of the difference. */
    absolute: number;
    /**
     * Magnitude as a share of the previous value, so `0.32` means 32 percent.
     * Zero when the previous value is zero, because the change has no base to
     * measure against and an infinite increase is not reportable.
     */
    ratio: number;
    /** `null` when the values match or either side is missing. */
    direction: MetricTrendDirection | null;
}
export interface ResolveMetricTrendOptions {
    /** Lower is better, so a decrease reads positive. Collisions, costs, defects. */
    inverted?: boolean;
    /** Report the change without a positive or negative reading. */
    neutral?: boolean;
    /** Report the change as a share of the previous value rather than a magnitude. */
    display?: 'absolute' | 'percentage';
    locale?: string;
}
/**
 * Compare a metric against its previous period.
 *
 * Reports magnitudes only — whether a rise is good news is a product decision,
 * so callers pair this with `resolveMetricTrend` or map `direction` themselves.
 */
export declare function computeMetricChange(current: number | null | undefined, previous: number | null | undefined): MetricChange;
/**
 * Build a display-ready trend, or `null` when there is nothing to report so the
 * caller can omit the trend entirely rather than render a zero.
 *
 * Percentages are formatted without decimals to match the product's overview
 * bar; `formatPercentage` is not used because it requires one or two decimals.
 */
export declare function resolveMetricTrend(current: number | null | undefined, previous: number | null | undefined, options?: ResolveMetricTrendOptions): MetricTrend | null;