import { HTMLAttributes } from 'react';
import { JSX } from 'react';
import { ReactElement } from 'react';
import { ReactNode } from 'react';

/**
 * Move a date by a number of working days.
 *
 * `n` days forward means `n` calls to {@link nextBusinessDay}; a negative `n`
 * walks backwards the same way. `n === 0` returns the day unchanged **even when it
 * is not a working day** — snapping silently would hide the case a caller most
 * needs to see.
 *
 * @param date - `YYYY-MM-DD` or a `Date`.
 * @param days - Working days to add. May be negative.
 * @param options - See {@link BusinessDayOptions}.
 * @returns Local midnight of the resulting day.
 * @throws {RangeError} On a malformed input, or on a calendar with no working days.
 *
 * @example
 * addBusinessDays("2026-04-01", 2); // 2026-04-06 — skips Good Friday and the weekend
 */
export declare function addBusinessDays(date: DateInput, days: number, options?: BusinessDayOptions): Date;

/**
 * Administrative regions of a federative unit.
 *
 * Only the Federal District has any — 35 of them, inside its single
 * municipality. Every other UF answers `[]`, which is a valid result and not an
 * error.
 *
 * @param uf - Federative unit acronym, case-insensitive.
 * @returns The regions, alphabetically. Empty outside the DF.
 */
export declare function administrativeRegionsByUf(uf: string): readonly BrazilAdministrativeRegion[];

/** What the two parsers return. Narrow on `kind`. */
export declare type Boleto = BoletoBanco | BoletoArrecadacao;

/** An arrecadação/convênio slip — utilities, taxes, traffic fines. */
export declare interface BoletoArrecadacao {
    kind: "arrecadacao";
    /** 44 digits, always starting with `8`. */
    codigoBarras: string;
    /** 48 digits, in four blocks of twelve. */
    linhaDigitavel: string;
    /** Position 2. See {@link segmentoLabel}. */
    segmento: number;
    /** Human label, or `null` for a value the layout does not define. */
    segmentoLabel: string | null;
    /** Position 3: `6`/`8` mean real money, `7`/`9` mean a reference quantity. */
    identificacaoValor: number;
    /** Which modulo position 3 selects for the general check digit. */
    dvModulo: 10 | 11;
    /** The general check digit, position 4. */
    dv: string;
    /** Reais, or `null` when position 3 says the field is a reference, not money. */
    valor: number | null;
    /** The raw 11-digit value field, useful when {@link valor} is `null`. */
    valorRaw: string;
    /**
     * Positions 16-19 — the 4-digit code FEBRABAN assigns the company — or, on
     * segmento 6, positions 16-23, which are the first eight CNPJ digits.
     */
    empresa: string;
    /** `true` when {@link empresa} is a CNPJ prefix rather than a FEBRABAN code. */
    empresaIsCnpj: boolean;
    /** 25 digits, or 21 when the CNPJ took four of them. Issuer-defined. */
    campoLivre: string;
    /**
     * Due date read from the first eight digits of the campo livre.
     *
     * The layout says a due date, **if present**, must sit there as `AAAAMMDD` —
     * but the field is optional and nothing marks its presence, so a campo livre
     * that merely looks like a date lands here too. Treat it as a hint for a UI,
     * never as the date a payment settles against.
     */
    vencimentoCampoLivre: Date | null;
}

/** A cobrança boleto — the kind a bank issues against an invoice. */
export declare interface BoletoBanco {
    kind: "banco";
    /** 44 digits. */
    codigoBarras: string;
    /** 47 digits. */
    linhaDigitavel: string;
    /** 3-digit bank code in the clearing house, e.g. `"341"`. */
    banco: string;
    /** 1 digit. `"9"` is BRL; nothing else is in use. */
    moeda: string;
    /** `"Real"` for `"9"`, `null` for anything else. */
    moedaLabel: string | null;
    /** The general check digit, position 5 of the barcode. */
    dv: string;
    /** Raw 4-digit field. `0` means the boleto carries no due date. */
    fatorVencimento: number;
    /** Due date, or `null` when the fator is `0`. */
    vencimento: Date | null;
    /** Which epoch {@link vencimento} was resolved under. `null` when there is none. */
    vencimentoEpoch: Exclude<BoletoEpoch, "auto"> | null;
    /** Reais. `0` when the issuer left the amount for the payer to fill in. */
    valor: number;
    /** 25 digits the issuing bank defines. Not interpretable without its manual. */
    campoLivre: string;
}

/**
 * Resolve a fator de vencimento to a calendar date.
 *
 * The field is four digits of days since a base date, and it has had **two** base
 * dates: 1997-10-07 until the counter saturated at 9999 on 2025-02-21, then
 * 2022-05-29 from 2025-02-22, when FEBRABAN restarted it at 1000.
 *
 * !!! danger "The two epochs are genuinely ambiguous"
 *     Every fator from 1000 to 9999 has a reading under each base — 1997-10-07
 *     gives a date in `2000-07-03 … 2025-02-21`, 2022-05-29 gives one in
 *     `2025-02-22 … 2049-10-14`. Nothing in the barcode says which. `"auto"`
 *     picks whichever lands nearer `reference`, which is right for the case that
 *     matters (a slip being paid now) and wrong for an archive sweep. Pass
 *     `"legacy"` or `"current"` when you know.
 *
 * @param fator - The raw 4-digit field as a number. `0` means "no due date".
 * @param options - Epoch selection. Default `"auto"` against `new Date()`.
 * @returns Local midnight of the due date, or `null` when `fator` is `0`.
 *
 * @example
 * boletoDueDate(1000, { epoch: "legacy" });  // 2000-07-03
 * boletoDueDate(1000, { epoch: "current" }); // 2025-02-22
 */
export declare function boletoDueDate(fator: number, options?: BoletoOptions): {
    date: Date;
    epoch: Exclude<BoletoEpoch, "auto">;
} | null;

/** Which base date the fator de vencimento counts from. See {@link boletoDueDate}. */
export declare type BoletoEpoch = "auto" | "legacy" | "current";

/**
 * @tempest-limits file-lines — the FEBRABAN spec in one file: the 47-digit linha
 * digitável, the 44-digit barcode, the two layouts (bank slips and arrecadação),
 * modulo-10 and modulo-11 check digits, the base date the due date counts from, and
 * the value scaling. Every piece cross-checks another — the conversion between the
 * two forms is what proves the check digits — so splitting it hides the one property
 * the file exists to guarantee.
 */
/**
 * A boleto string could not be read, or failed a check digit.
 *
 * Its own class so a scanner screen can tell "this is not a boleto" apart from a
 * bug, and so the message can be shown to the operator as-is.
 */
export declare class BoletoError extends Error {
    constructor(message: string);
}

/**
 * The two incompatible layouts that share the 44-digit barcode.
 *
 * `"banco"` is the cobrança boleto every bank issues; `"arrecadacao"` is the
 * concessionária/tributo slip, which starts with `8` and lays out its 44 digits
 * completely differently — same length, different meaning for every field.
 */
export declare type BoletoKind = "banco" | "arrecadacao";

/**
 * Which layout a string is in, without throwing.
 *
 * @param value - A barcode or typed line, masked or not.
 * @returns The layout, or `null` when the length is not 44, 47 or 48.
 */
export declare function boletoKind(value: string): BoletoKind | null;

/** Options shared by every parser here. */
export declare interface BoletoOptions {
    /** Fator de vencimento epoch. Default `"auto"`. */
    epoch?: BoletoEpoch;
    /** Date `"auto"` measures proximity against. Default `new Date()`. */
    reference?: Date;
}

/**
 * An administrative region of the Federal District.
 *
 * The DF has exactly one municipality — Brasília — and 35 administrative
 * regions inside it. Nobody in the DF writes "Brasília" in an address field,
 * so the regions are listed and resolvable; they are not municipalities, and
 * `municipalityId` is what they geocode through.
 */
export declare interface BrazilAdministrativeRegion {
    /** IBGE subdistrict code, e.g. `"53001080515"` for Ceilândia. */
    id: string;
    /** IBGE name, e.g. `"Sudoeste/Octogonal"`. */
    name: string;
    /** The municipality it belongs to — Brasília (`"5300108"`) for all 35. */
    municipalityId: string;
}

/**
 * Clickable choropleth map of Brazil's 27 federative units. Renders the bundled
 * simplified UF GeoJSON as SVG paths — **no external tiles or paid API**. Click
 * a state to fire `onSelect(uf)`; pass `selected` to highlight and `values` to
 * tint states by a metric.
 *
 * The GeoJSON (~36 KB gzip) is loaded lazily, so importing this component does
 * not pull the geometry until it actually mounts.
 *
 * @example
 * const [uf, setUf] = useState<UF | null>(null);
 * <BrazilMap selected={uf} onSelect={setUf} />
 *
 * @example
 * // Choropleth by a metric per state
 * <BrazilMap values={{ SP: 120, RJ: 90, MG: 60 }} />
 */
export declare function BrazilMap({ selected, onSelect, values, minColor, maxColor, colorScale, colorByRegion, height, padding, showLabels, label, loadingContent, showTooltip, renderTooltip, markers, onMarkerClick, zoomable, className, style, ...rest }: BrazilMapProps): JSX.Element;

export declare interface BrazilMapProps extends Omit<HTMLAttributes<HTMLDivElement>, "onSelect"> {
    /** Currently selected UF(s) — highlighted. Accepts one or many. */
    selected?: UF | readonly UF[] | null;
    /** Fired when a state is clicked. */
    onSelect?: (uf: UF) => void;
    /**
     * Optional choropleth values per UF. When set, each state is tinted between
     * `minColor` and `maxColor` by its value (linear). States without a value
     * use the base surface color.
     */
    values?: Partial<Record<UF, number>>;
    /** Choropleth low-end color (2-color linear ramp). Default: a light primary tint. */
    minColor?: string;
    /** Choropleth high-end color (2-color linear ramp). Default: the primary token. */
    maxColor?: string;
    /**
     * Custom value→color scale (e.g. from `sequentialScale`/`quantizeScale`).
     * Takes precedence over `minColor`/`maxColor`. Pair with a `<MapLegend>`.
     */
    colorScale?: ColorScale;
    /**
     * Tint each state by its macro-region (categorical). Overrides
     * `values`/`colorScale`. Pair with `<MapLegend items={regionLegendItems()} />`.
     */
    colorByRegion?: boolean;
    /** Viewport height in pixels. Default: `440`. */
    height?: number;
    /** Inner padding in pixels. Default: `12`. */
    padding?: number;
    /** Render the UF acronym at each state centroid. Default: `true`. */
    showLabels?: boolean;
    /** Accessible label for the map region. Default: `"Mapa do Brasil por estado"`. */
    label?: string;
    /** Custom content when the geometry is still loading. */
    loadingContent?: ReactNode;
    /** Show a floating tooltip (name + region + city count + value) on hover. Default: `true`. */
    showTooltip?: boolean;
    /** Override the default tooltip content. */
    renderTooltip?: (data: BrazilMapTooltipData) => ReactNode;
    /** Point markers to overlay on the map (e.g. capitals, stores). */
    markers?: readonly GeoMarker[];
    /** Fired when a marker is clicked. */
    onMarkerClick?: (marker: GeoMarker, index: number) => void;
    /** Enable wheel-zoom + drag-pan (double-click resets). Default: `false`. */
    zoomable?: boolean;
}

/** Data passed to a {@link BrazilMapProps.renderTooltip} callback. */
export declare interface BrazilMapTooltipData {
    uf: UF;
    name: string;
    /** Choropleth value for this UF, if `values` was provided. */
    value?: number;
}

/** A municipality, identified by the code that survives its renames. */
export declare interface BrazilMunicipality {
    /** 7-digit IBGE code, e.g. `"3550308"`. Stable across a rename. */
    id: string;
    /** Current IBGE name, e.g. `"São Paulo"`. */
    name: string;
}

/** A federative unit with its display name and city list. */
export declare interface BrazilState {
    /** Two-letter acronym, e.g. `"SP"`. */
    uf: UF;
    /** Full name, e.g. `"São Paulo"`. */
    name: string;
    /** Macro-region the state belongs to. */
    region: BrRegion;
    /** Municipality names within the state, alphabetically. */
    cities: string[];
    /** The same municipalities carrying their IBGE codes, same order. */
    municipalities: readonly BrazilMunicipality[];
    /** Administrative regions — 35 for `"DF"`, empty everywhere else. */
    administrativeRegions: readonly BrazilAdministrativeRegion[];
}

export declare function BrazilStateCitySelect({ defaultUf, defaultCity, onChange, stateLabel, cityLabel, statePlaceholder, cityPlaceholder, disabled, layout, }: BrazilStateCitySelectProps): ReactElement;

/** Current selection emitted by {@link BrazilStateCitySelect}. */
export declare interface BrazilStateCitySelection {
    /** Selected federative unit, or `null` when none. */
    uf: UF | null;
    /** Selected city, or `null` when none. */
    city: string | null;
    /**
     * IBGE code of the selected municipality, or `null` when none is selected.
     *
     * This is the value to store. It survives the renames `city` does not, and
     * it is what `geocodeMunicipality` and every other dataset here join on. A
     * DF administrative region carries Brasília's code, because that is the
     * municipality it is part of.
     */
    municipalityId: string | null;
}

export declare interface BrazilStateCitySelectProps {
    /** Pre-selected UF (uncontrolled initial value). */
    defaultUf?: UF;
    /** Pre-selected city (uncontrolled initial value). */
    defaultCity?: string;
    /** Fired whenever the state or city changes. */
    onChange?: (selection: BrazilStateCitySelection) => void;
    /** Label for the state select. Default: `"Estado"`. */
    stateLabel?: string;
    /** Label for the city select. Default: `"Cidade"`. */
    cityLabel?: string;
    /** Placeholder for the state select. Default: `"Selecione o estado"`. */
    statePlaceholder?: string;
    /** Placeholder for the city select. Default: `"Selecione a cidade"`. */
    cityPlaceholder?: string;
    /** Disable both selects. */
    disabled?: boolean;
    /** Layout of the two selects. Default: `"row"`. */
    layout?: "row" | "column";
}

/**
 * Clickable submap of a single Brazilian state showing **all its
 * municipalities** as SVG paths — no external tiles or paid API. The state's
 * geometry (~40-70 KB gzip) is loaded lazily per UF, so switching states fetches
 * only what is shown.
 *
 * @example
 * const [city, setCity] = useState<string | null>(null);
 * <BrazilStateMap uf="SP" selected={city} onSelect={(m) => setCity(m.name)} />
 *
 * @example
 * // Choropleth of a metric by municipality name
 * <BrazilStateMap uf="RJ" values={{ "Rio de Janeiro": 100, Niterói: 40 }} />
 */
export declare function BrazilStateMap({ uf, selected, onSelect, values, minColor, maxColor, colorScale, height, padding, showLabels, label, loadingContent, showTooltip, renderTooltip, markers, onMarkerClick, zoomable, className, style, ...rest }: BrazilStateMapProps): JSX.Element;

export declare interface BrazilStateMapProps extends Omit<HTMLAttributes<HTMLDivElement>, "onSelect"> {
    /** Federative unit to draw (required). */
    uf: UF;
    /** Selected municipality — matched by IBGE `id` or by `name`. Accepts many. */
    selected?: string | readonly string[] | null;
    /** Fired when a municipality is clicked. */
    onSelect?: (municipality: Municipality) => void;
    /**
     * Choropleth values keyed by municipality `id` **or** `name`. When set, each
     * municipality is tinted between `minColor` and `maxColor`.
     */
    values?: Record<string, number>;
    /** Choropleth low-end color (2-color linear ramp). Default: a light primary tint. */
    minColor?: string;
    /** Choropleth high-end color (2-color linear ramp). Default: the primary token. */
    maxColor?: string;
    /**
     * Custom value→color scale (from `sequentialScale`/`quantizeScale`). Takes
     * precedence over `minColor`/`maxColor`. Pair with a `<MapLegend>`.
     */
    colorScale?: ColorScale;
    /** Viewport height in pixels. Default: `440`. */
    height?: number;
    /** Inner padding in pixels. Default: `12`. */
    padding?: number;
    /**
     * Render each municipality name at its centroid. Off by default — a state
     * can have hundreds of municipalities and labels overlap badly.
     */
    showLabels?: boolean;
    /** Accessible label. Default: derived from the state name. */
    label?: string;
    /** Content while the state geometry is loading. */
    loadingContent?: ReactNode;
    /** Show a floating tooltip (name + IBGE code + value) on hover. Default: `true`. */
    showTooltip?: boolean;
    /** Override the default tooltip content. */
    renderTooltip?: (data: BrazilStateMapTooltipData) => ReactNode;
    /** Point markers to overlay on the state (e.g. addresses, POIs). */
    markers?: readonly GeoMarker[];
    /** Fired when a marker is clicked. */
    onMarkerClick?: (marker: GeoMarker, index: number) => void;
    /** Enable wheel-zoom + drag-pan (double-click resets). Default: `false`. */
    zoomable?: boolean;
}

/** Data passed to a {@link BrazilStateMapProps.renderTooltip} callback. */
export declare interface BrazilStateMapTooltipData extends Municipality {
    /** Choropleth value for this municipality, if `values` was provided. */
    value?: number;
}

/** The five Brazilian macro-regions (IBGE). */
export declare type BrRegion = "Norte" | "Nordeste" | "Centro-Oeste" | "Sudeste" | "Sul";

/** One federative unit feature. */
export declare interface BrUfFeature {
    type: "Feature";
    properties: {
        uf: UF;
        name: string;
        region: BrRegion;
        /** Representative point `[longitude, latitude]` (area-weighted centroid). */
        centroid: [number, number];
    };
    geometry: BrUfGeometry;
}

/** The bundled, simplified GeoJSON of all 27 UF boundaries. */
export declare interface BrUfFeatureCollection {
    type: "FeatureCollection";
    features: BrUfFeature[];
}

/** GeoJSON geometry for a federative unit — always a (multi)polygon. */
export declare interface BrUfGeometry {
    type: "Polygon" | "MultiPolygon";
    /** `Polygon` → `Ring[]`; `MultiPolygon` → `Ring[][]`. */
    coordinates: Ring[] | Ring[][];
}

/** Options shared by the calendar helpers. */
export declare interface BusinessDayOptions {
    /**
     * Which kinds count as non-working. Default `["national", "banking"]`, i.e.
     * the Bacen calendar — the right default for anything money moves through.
     * Pass `["national"]` for a labour-law calendar.
     */
    kinds?: readonly HolidayKind[];
    /**
     * Extra non-working days, as `YYYY-MM-DD` or `Date`. This is where state and
     * municipal holidays go: they are **not** in the built-in table and never will
     * be — there are 5 570 municipalities, each free to declare its own.
     */
    extra?: readonly DateInput[];
    /**
     * Days of the week that are not worked, `0` = Sunday. Default `[0, 6]`.
     */
    weekend?: readonly number[];
}

/** A fiscal access key taken apart. */
export declare interface ChaveNFe {
    /** Federative unit of the issuer, resolved from {@link cUF}. */
    uf: UF;
    /** The raw 2-digit IBGE code, positions 1-2. */
    cUF: string;
    /** Positions 3-6, `AAMM` — the two-digit year and the month of issue. */
    anoMes: string;
    /** Four-digit year derived from {@link anoMes}. */
    ano: number;
    /** Month of issue, 1-12. */
    mes: number;
    /** Positions 7-20, the issuer's CNPJ. */
    cnpj: string;
    /** Positions 21-22, `mod`. `"55"` is an NF-e, `"65"` an NFC-e. */
    modelo: string;
    /** Human label for {@link modelo}, or `null` for a model outside the table. */
    modeloLabel: string | null;
    /** Positions 23-25. */
    serie: string;
    /** Positions 26-34, `nNF`. */
    numero: string;
    /** Position 35, `tpEmis`. */
    tipoEmissao: string;
    /** Human label for {@link tipoEmissao}, or `null` for a value outside the table. */
    tipoEmissaoLabel: string | null;
    /** Positions 36-43, `cNF` — the issuer's random code. */
    codigoNumerico: string;
    /** Position 44, `cDV`. */
    dv: string;
}

/**
 * The check digit a 43-digit key body requires.
 *
 * Módulo 11: each digit is multiplied by weights cycling `2…9` from right to
 * left, the products are summed, and the digit is `11 - (sum mod 11)` — except
 * that a remainder of `0` or `1` yields `0`, since `11` and `10` do not fit one
 * position.
 *
 * Note this is the **fiscal** flavour of módulo 11. The cobrança boleto resolves
 * those same remainders to `1`; see `mod11DacCobranca` in `./boleto`.
 *
 * @param body - The first 43 digits of the key.
 * @returns The check digit, 0-9.
 * @throws {ChaveNFeError} When `body` is not exactly 43 digits.
 */
export declare function chaveNFeCheckDigit(body: string): number;

/**
 * A 44-digit fiscal access key could not be read.
 *
 * Its own class so a scanner screen can tell a bad key apart from a bug and show
 * the message to the operator unchanged.
 */
export declare class ChaveNFeError extends Error {
    constructor(message: string);
}

/** A `{ value, label }` option, handy for `<Select>` / `<Combobox>`. */
export declare interface Choice {
    value: string;
    label: string;
}

/**
 * City names for a federative unit (case-insensitive acronym). Returns an empty
 * array for an unknown UF — "no matches" is a valid result, not an error.
 */
export declare function citiesByUf(uf: string): string[];

/** `{ value, label }` options for every city in a UF (value === label). */
export declare function cityChoices(uf: string): Choice[];

/**
 * Convert a 44-digit barcode to its typed line — 47 digits, or 48 for `8…`.
 *
 * @param value - 44 digits.
 * @returns The typed line, check digits included.
 * @throws {BoletoError} On a bad length or a general check digit that does not
 * recompute.
 */
export declare function codigoBarrasToLinhaDigitavel(value: string): string;

/** Maps a numeric value to a CSS color string. */
export declare type ColorScale = (value: number) => string;

/**
 * WGS84 geographic coordinate. Mirrors the `Coordinate` schema from
 * `tempest-fastapi-sdk` (`geo/schemas.py`) — `latitude` in `[-90, 90]`,
 * `longitude` in `[-180, 180]`, serialized snake_case on the wire.
 */
declare interface Coordinate {
    /** WGS84 latitude in degrees, `[-90, 90]`. E.g. `-23.5505`. */
    latitude: number;
    /** WGS84 longitude in degrees, `[-180, 180]`. E.g. `-46.6333`. */
    longitude: number;
}

/**
 * The IBGE vintages the bundled datasets were built from.
 *
 * `roster` is the day the municipality list was read and `mesh` the boundary
 * release it was joined to. They differ on purpose: IBGE publishes new
 * municipalities before it publishes their boundaries, and the gap is what
 * {@link pendingGeometryIds} enumerates.
 *
 * @returns The two vintages, as they were written into the data file.
 */
export declare function datasetVintage(): {
    roster: string;
    mesh: string;
};

/** Anything these helpers accept as a day. */
export declare type DateInput = Date | string;

/** Diverging palette (red ↔ neutral ↔ blue), for signed metrics. */
export declare const DIVERGING_RDBU: readonly ["#b2182b", "#ef8a62", "#fddbc7", "#d1e5f0", "#67a9cf", "#2166ac"];

/**
 * Easter Sunday in the Gregorian calendar.
 *
 * The anonymous Gregorian computus (Meeus/Jones/Butcher): pure integer
 * arithmetic over the year, no tables and no dependency. It is exact for every
 * Gregorian year, which is why the four movable Brazilian holidays are derived
 * from it rather than listed.
 *
 * @param year - Gregorian year.
 * @returns Local midnight of Easter Sunday.
 *
 * @example
 * easterSunday(2026); // 2026-04-05
 */
export declare function easterSunday(year: number): Date;

/**
 * Invert {@link boletoDueDate}: the fator that encodes a due date.
 *
 * @param date - The due date. Only its local calendar day is used.
 * @param epoch - Base date to count from. Default `"current"`, the epoch in force
 * since 2025-02-22 and therefore the one a boleto issued today must use.
 * @returns The 4-digit fator.
 * @throws {BoletoError} When the date falls outside the 1000-9999 window of that
 * epoch, because no fator can represent it.
 *
 * @example
 * fatorVencimento(new Date(2025, 1, 22)); // 1000
 */
export declare function fatorVencimento(date: Date, epoch?: Exclude<BoletoEpoch, "auto">): number;

/** A ready-to-use mapping from coordinates to viewport pixels. */
declare interface FittedProjection {
    /** Project a coordinate to a pixel inside the viewport. */
    project: (coord: Coordinate) => PixelPoint;
    /** Uniform scale (unit-plane → pixels) actually used, after aspect fit. */
    scale: number;
    /** Viewport width in pixels. */
    width: number;
    /** Viewport height in pixels. */
    height: number;
}

/**
 * Group a key in blocks of four, the way a DANFE prints it.
 *
 * @param chave - The key, masked or not.
 * @returns Eleven groups of four digits separated by spaces, or the input
 * unchanged when it is not 44 digits — this is a display helper, not a validator.
 *
 * @example
 * formatChaveNFe("35260112345678000195550010000001231123456784");
 * // "3526 0112 3456 7800 0195 5500 1000 0001 2311 2345 6784"
 */
export declare function formatChaveNFe(chave: string): string;

/**
 * Group a typed line the way it is printed, so a human can read it back.
 *
 * 47 digits become `AAABC.CCCCD EEEEE.EEEEEF GGGGG.GGGGGH I JJJJKKKKKKKKKK`;
 * 48 digits become four blocks of twelve. Anything else is returned untouched —
 * this is a display helper, not a validator.
 *
 * @param value - A typed line, masked or not.
 * @returns The grouped string.
 *
 * @example
 * formatLinhaDigitavel("34191090086459218110900000463074184410000002000");
 * // "34191.09008 64592.181109 00000.463074 1 84410000002000"
 */
export declare function formatLinhaDigitavel(value: string): string;

/**
 * Forward-geocode a municipality by name (accent-insensitive), optionally scoped
 * to a UF. Returns every exact-name match — the same name can occur in several
 * states (e.g. "Bonito").
 *
 * @param name - Municipality name.
 * @param uf - Optional UF to restrict the search.
 * @returns Matching municipalities (empty array when none match).
 */
export declare function geocodeMunicipality(name: string, uf?: UF): Promise<MunicipalityCentroid[]>;

/**
 * A pin plotted on a map: a {@link Coordinate} plus optional presentation and
 * an identity used for click callbacks. Shared by `TrajectoryMap` and the
 * Brazil maps' `markers` prop.
 */
export declare interface GeoMarker extends Coordinate {
    /** Stable identity (returned by click handlers). Falls back to the index. */
    id?: string;
    /** Tooltip / accessible label for the pin. */
    label?: string;
    /** Fill color. Defaults to the primary token. */
    color?: string;
    /** Radius in pixels. Default: 6. */
    radius?: number;
}

/** Look up a single state by acronym (case-insensitive). Returns `null` if unknown. */
export declare function getState(uf: string): BrazilState | null;

/** One non-working day in a given year. */
export declare interface Holiday {
    /** `YYYY-MM-DD` in the local calendar. */
    date: string;
    /** Portuguese name, as the law or the Bacen calendar spells it. */
    name: string;
    kind: HolidayKind;
    /** `true` when the date is derived from Easter rather than fixed. */
    movable: boolean;
}

/**
 * How binding a non-working day is.
 *
 * - `"national"` — a feriado nacional in federal law. Nobody works, and a
 *   deadline that lands here moves.
 * - `"banking"` — not a statutory holiday, but a day the national financial
 *   system does not operate: Carnaval (Monday and Tuesday), Sexta-feira da
 *   Paixão and Corpus Christi. Bank branches are shut and compensation does not
 *   run, so a boleto or a TED dated here settles later — but an employer may
 *   legally require work, which is why the two kinds are separate.
 */
export declare type HolidayKind = "national" | "banking";

/**
 * Every national non-working day in a year, ordered by date.
 *
 * **What is here:** the nine feriados nacionais in federal law (Lei 662/1949 as
 * amended by Lei 10.607/2002, Lei 6.802/1980 for 12 October, and Lei 14.759/2023
 * for 20 November, which is why that one only appears from 2024), plus the four
 * movable days the national financial system observes.
 *
 * **What is deliberately not here**, and will not be:
 *
 * - **State and municipal holidays.** A data magna varies by state and each of the
 *   5 570 municipalities may declare its own, including up to four religious
 *   days. No table can be both complete and current; pass them through
 *   `options.extra`.
 * - **Ponto facultativo.** A federal decree that lets public servants off is not a
 *   holiday and binds nobody else, so it changes no deadline.
 * - **Pre-2002 history.** The table encodes the law as it stands today. Asking for
 *   1998 returns today's set shifted to 1998, not what was in force then.
 *
 * Carnaval, Sexta-feira da Paixão and Corpus Christi are the interesting case:
 * none of them is a feriado nacional in federal law, yet CMN Resolução 4.880/2020
 * closes the banks on all four days, so a payment cannot settle. They are returned
 * with `kind: "banking"` — counted by default, and excluded by passing
 * `kinds: ["national"]`.
 *
 * @param year - Gregorian year.
 * @returns The holidays of that year, ascending by date.
 *
 * @example
 * holidaysFor(2026).filter((holiday) => holiday.kind === "national").length; // 9
 */
export declare function holidaysFor(year: number): Holiday[];

/**
 * Whether a date is a working day: not a weekend, not a holiday.
 *
 * @param date - `YYYY-MM-DD` or a `Date`.
 * @param options - See {@link BusinessDayOptions}.
 * @returns `true` when work happens on that day.
 * @throws {RangeError} On a malformed string or an Invalid Date.
 *
 * @example
 * isBusinessDay("2026-04-03"); // false — Sexta-feira da Paixão
 */
export declare function isBusinessDay(date: DateInput, options?: BusinessDayOptions): boolean;

/**
 * Whether a date is a national holiday.
 *
 * @param date - `YYYY-MM-DD` or a `Date`. Only the local calendar day matters.
 * @param options - See {@link BusinessDayOptions}. `weekend` is ignored here — a
 * Sunday is not a holiday, it is a Sunday.
 * @returns `true` when the day is in the table (or in `extra`).
 * @throws {RangeError} On a malformed string or an Invalid Date.
 *
 * @example
 * isHoliday("2026-11-20"); // true
 * isHoliday("2026-02-17"); // true — Carnaval
 * isHoliday("2026-02-17", { kinds: ["national"] }); // false
 */
export declare function isHoliday(date: DateInput, options?: BusinessDayOptions): boolean;

/** True when `city` exists within `uf` (both case-insensitive). */
export declare function isValidCity(uf: string, city: string): boolean;

/** True when `value` is one of the 27 valid acronyms (case-insensitive). */
export declare function isValidUf(value: string): boolean;

/** A discrete legend entry. */
export declare interface LegendItem {
    color: string;
    label: ReactNode;
}

/**
 * Convert a typed line to its 44-digit barcode.
 *
 * @param value - 47 or 48 digits.
 * @returns The 44-digit barcode.
 * @throws {BoletoError} On a bad length or a check digit that does not recompute.
 */
export declare function linhaDigitavelToCodigoBarras(value: string): string;

/** All 27 federative units, sorted by name. */
export declare function listStates(): readonly BrazilState[];

/**
 * Lazily load the bundled simplified UF GeoJSON (~36 KB gzip). Kept out of the
 * synchronous barrel so a data-only import never pulls the geometry.
 */
export declare function loadBrUfGeoJson(): Promise<BrUfFeatureCollection>;

/**
 * Lazily load the simplified municipality GeoJSON for a federative unit. Each
 * state's geometry is a separate chunk (~40-70 KB gzip), fetched on demand —
 * the full ~2 MB municipal dataset never lands in one bundle.
 *
 * @param uf - Federative unit acronym (e.g. `"SP"`).
 * @returns The municipality collection, or `null` for an unknown UF.
 *
 * @example
 * const sp = await loadStateMunicipalities("SP");
 * sp?.features.length; // 644
 */
export declare function loadStateMunicipalities(uf: UF): Promise<StateMunicipalities | null>;

/**
 * Legend for a choropleth map. Renders a **continuous gradient** (with
 * min/mid/max ticks) from `min`/`max`/`palette`, or **discrete swatches** when
 * `items` is given. Pair it with a `BrazilMap`/`BrazilStateMap` `colorScale`.
 *
 * @example
 * // Continuous, matching a sequentialScale(0, 100)
 * <MapLegend title="Vendas" min={0} max={100} palette={SEQUENTIAL_BLUES} />
 *
 * @example
 * // Discrete buckets
 * <MapLegend
 *   title="Faixa"
 *   items={[
 *     { color: "#c6dbef", label: "< 10" },
 *     { color: "#6baed6", label: "10–50" },
 *     { color: "#08519c", label: "> 50" },
 *   ]}
 * />
 */
export declare function MapLegend({ title, items, min, max, palette, format, className, ...rest }: MapLegendProps): JSX.Element;

export declare interface MapLegendProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
    /** Legend heading. */
    title?: ReactNode;
    /**
     * Discrete entries (swatch + label). When provided the legend renders in
     * "steps" mode; otherwise it renders a continuous gradient from `min`/`max`.
     */
    items?: readonly LegendItem[];
    /** Continuous mode: low end of the domain. */
    min?: number;
    /** Continuous mode: high end of the domain. */
    max?: number;
    /** Continuous mode: palette (light → dark). Default: sequential blues. */
    palette?: readonly string[];
    /** Continuous mode: format the min/mid/max tick labels. */
    format?: (value: number) => string;
}

export declare interface MapMarkersProps {
    /** Projection used by the host map (markers must share it to line up). */
    projection: FittedProjection;
    /** Pins to plot. */
    markers: readonly GeoMarker[];
    /** Fired when a marker is clicked. */
    onMarkerClick?: (marker: GeoMarker, index: number) => void;
}

/**
 * DAC módulo 10, FEBRABAN flavour.
 *
 * Multipliers cycle `2, 1, 2, 1, …` from right to left; the **digits** of each
 * product are summed individually (so `6 × 2 = 12` contributes `1 + 2`); the DAC
 * is `10 - (sum mod 10)`, and `0` when that remainder is `0`.
 *
 * Ported from "Layout Padrão de Arrecadação/Recebimento com Utilização do Código
 * de Barras", FEBRABAN version 07 (effective 2023-03-01), section 07 — whose own
 * worked example gives `01230067896 → 3`.
 *
 * @param value - Digits only.
 * @returns The check digit, 0-9.
 * @throws {BoletoError} When `value` is empty or holds a non-digit.
 */
export declare function mod10Dac(value: string): number;

/**
 * DAC módulo 11 for an **arrecadação** barcode — position 4 of a `8…` slip.
 *
 * Same weights and same subtraction as {@link mod11DacCobranca}, but a remainder
 * of `0` or `1` resolves to **`0`**.
 *
 * Ported from the FEBRABAN version 07 layout, section 10, and pinned by that
 * document's own worked example: the 43-digit sequence
 * `8220000215048200974123220154098290108605940` sums to 705, `705 mod 11 = 1`,
 * and the barcode the spec prints carries `0` in position 4.
 *
 * @param value - The 43 digits of the barcode with position 4 removed.
 * @returns The check digit, 0 or 2-9.
 * @throws {BoletoError} When `value` is empty or holds a non-digit.
 */
export declare function mod11DacArrecadacao(value: string): number;

/**
 * DAC módulo 11 for a **cobrança** barcode — position 5 of a bank boleto.
 *
 * Weights cycle `2…9` from right to left, the products are summed whole, and the
 * DAC is `11 - (sum mod 11)`. A remainder of `0`, `1` or `10` would put `11`, `10`
 * or `1` in a one-digit field, and FEBRABAN resolves all three to **`1`**.
 *
 * That last rule is where cobrança and arrecadação disagree — see
 * {@link mod11DacArrecadacao}, which resolves the same remainders to `0`. Using
 * one flavour on the other layout produces a check digit that is wrong exactly
 * 3 times in 11, which is why they are separate functions here.
 *
 * @param value - The 43 digits of the barcode with position 5 removed.
 * @returns The check digit, 1-9.
 * @throws {BoletoError} When `value` is empty or holds a non-digit.
 */
export declare function mod11DacCobranca(value: string): number;

/**
 * Municipalities of a federative unit, each carrying its IBGE code.
 *
 * The code is what a backend wants stored: it survives the renames that keep
 * happening (`Presidente Juscelino` became `Serra Caiada` in 2013) and it is the
 * key every other dataset in this module joins on.
 *
 * @param uf - Federative unit acronym, case-insensitive.
 * @returns The municipalities, alphabetically. Empty for an unknown UF.
 */
export declare function municipalitiesByUf(uf: string): readonly BrazilMunicipality[];

/** A municipality identified for selection callbacks. */
export declare interface Municipality {
    /** 7-digit IBGE code. */
    id: string;
    /** Municipality name. */
    name: string;
}

/** A municipality with its representative coordinate (IBGE centroid). */
export declare interface MunicipalityCentroid {
    /** 7-digit IBGE code. */
    id: string;
    /** Municipality name. */
    name: string;
    /** Federative unit. */
    uf: UF;
    latitude: number;
    longitude: number;
}

/**
 * Centroid of a municipality by IBGE code.
 *
 * @param id - 7-digit IBGE code.
 * @returns The municipality centroid, or `null` if unknown.
 */
export declare function municipalityCentroid(id: string): Promise<MunicipalityCentroid | null>;

/** One municipality feature within a state. */
export declare interface MunicipalityFeature {
    type: "Feature";
    properties: {
        /** 7-digit IBGE municipality code. */
        id: string;
        /** Municipality name. */
        name: string;
        /** Representative point `[longitude, latitude]` (area-weighted centroid). */
        centroid: [number, number];
    };
    geometry: BrUfGeometry;
}

/**
 * Debounced municipality autocomplete backed by the offline
 * {@link searchMunicipalities} index — no network. Type a partial name, pick a
 * result, and `onSelect` fires with its `{ id, name, uf, latitude, longitude }`.
 * Wire `onSelect` to a `BrazilStateMap` `selected` to highlight it on the map.
 *
 * @example
 * const [uf, setUf] = useState<UF>("SP");
 * const [city, setCity] = useState<string | null>(null);
 * <MunicipalitySearch uf={uf} onSelect={(m) => setCity(m.name)} />
 * <BrazilStateMap uf={uf} selected={city} />
 */
export declare function MunicipalitySearch({ uf, onSelect, label, placeholder, limit, debounceMs, disabled, }: MunicipalitySearchProps): ReactElement;

export declare interface MunicipalitySearchProps {
    /** Restrict the search to a single UF. */
    uf?: UF;
    /** Fired when a municipality is picked from the results. */
    onSelect: (municipality: MunicipalityCentroid) => void;
    /** Field label. */
    label?: string;
    /** Input placeholder. Default: `"Buscar município…"`. */
    placeholder?: string;
    /** Max results shown. Default: `8`. */
    limit?: number;
    /** Debounce in ms before searching. Default: `250`. */
    debounceMs?: number;
    /** Disable the field. */
    disabled?: boolean;
}

/** {@link MunicipalityCentroid} plus the distance from the query point. */
export declare interface NearestMunicipality extends MunicipalityCentroid {
    /** Great-circle distance from the query coordinate, in kilometers. */
    distanceKm: number;
}

/**
 * Nearest Brazilian municipality to a coordinate by **centroid distance** —
 * fast and geometry-free (only the small centroid index loads). Approximate:
 * near borders or inside large municipalities a neighbor's centroid can be
 * closer. For an exact containing municipality use {@link reverseGeocode}.
 *
 * @param coord - Query coordinate.
 * @returns The nearest municipality with `distanceKm`, or `null` if the index
 *   is somehow empty.
 *
 * @example
 * const near = await nearestMunicipality({ latitude: -23.55, longitude: -46.63 });
 * // { id, name, uf: "SP", …, distanceKm }
 */
export declare function nearestMunicipality(coord: Coordinate): Promise<NearestMunicipality | null>;

/**
 * The first working day strictly after a date.
 *
 * Strictly after: calling it on a Wednesday returns Thursday, never the same
 * Wednesday. That is what a "prazo de D+1" means, and it makes the function safe
 * to call in a loop.
 *
 * @param date - `YYYY-MM-DD` or a `Date`.
 * @param options - See {@link BusinessDayOptions}.
 * @returns Local midnight of the next working day.
 * @throws {RangeError} On a malformed input, or when `options` marked so many days
 * off that no working day exists within {@link MAX_WALK_DAYS}.
 *
 * @example
 * nextBusinessDay("2026-12-24"); // 2026-12-28 — the 25th is Natal, then a weekend
 */
export declare function nextBusinessDay(date: DateInput, options?: BusinessDayOptions): Date;

/** A key after normalisation, ready to go into the payload. */
export declare interface NormalizedPixKey {
    type: PixKeyType;
    /** The exact string written into the BR Code. */
    value: string;
}

/**
 * Validate a Pix key and return the exact string to write into the payload.
 *
 * Normalisation per type: CPF and CNPJ lose their mask, a phone becomes E.164
 * with the `+55` country code, an EVP is lower-cased, and an e-mail is
 * lower-cased because DICT stores it that way — a key that differs only in case
 * would otherwise fail to resolve.
 *
 * All validation lives in {@link pixKeyType}; past that gate the normalisation is
 * total, which is why the phone branch strips a country code purely on length
 * rather than re-checking the shape.
 *
 * @param key - Raw key, masked or not.
 * @returns The type and the normalised value.
 * @throws {PixError} When the key matches no accepted format, or when a document
 * key fails its check digits.
 *
 * @example
 * normalizePixKey("123.456.789-09"); // { type: "cpf", value: "12345678909" }
 * normalizePixKey("(11) 98765-4321"); // { type: "phone", value: "+5511987654321" }
 */
export declare function normalizePixKey(key: string): NormalizedPixKey;

/**
 * Normalize an acronym to canonical uppercase form, or `null` if it is not a
 * valid UF. `"sp"` → `"SP"`, `"xx"` → `null`.
 */
export declare function normalizeUf(value: string): UF | null;

/**
 * Open the WhatsApp chat in a new tab.
 *
 * @example
 * <Button onClick={() => openWhatsApp(client.phone, greeting)}>
 *     Falar no WhatsApp
 * </Button>
 *
 * @param phone - Phone number in any shape; normalised by {@link toWhatsAppNumber}.
 * @param text - Message to pre-fill. Omitted or empty leaves the composer blank.
 * @returns `true` when a URL was built and the open was requested, `false` when
 *   the number is unusable or there is no `window` (test runner, service worker,
 *   build plugin). It reports the **request**, not the tab: opening with
 *   `noopener` makes `window.open` return `null` even on success, so its result
 *   cannot distinguish a blocked popup from an opened one.
 */
export declare function openWhatsApp(phone: string, text?: string): boolean;

/**
 * Read a 44-digit fiscal access key into its fields.
 *
 * The layout is fixed and shared by every document type that carries a key —
 * NF-e, NFC-e, CT-e, MDF-e — so `modelo` is what tells you which one you are
 * holding, not the length.
 *
 * ```text
 * 35 2601 12345678000195 55 001 000000123 1 12345678 4
 * cUF AAMM CNPJ           mod série nNF    tp cNF     cDV
 * ```
 *
 * @param chave - The key, with or without the spaces a DANFE prints.
 * @returns The parsed key.
 * @throws {ChaveNFeError} On a length other than 44, an unknown `cUF`, a month
 * outside 1-12, or a check digit that does not recompute.
 *
 * @example
 * const { uf, cnpj, numero, modeloLabel } = parseChaveNFe(scanned);
 */
export declare function parseChaveNFe(chave: string): ChaveNFe;

/**
 * Read a 44-digit barcode — either layout — into its fields.
 *
 * The first digit picks the layout: `8` is an arrecadação/convênio slip, anything
 * else is a cobrança boleto. They are **not** variants of one format; every field
 * moves. Narrow the result on `kind` before touching it.
 *
 * @param value - 44 digits. Spaces and punctuation are ignored.
 * @param options - Fator de vencimento epoch. See {@link boletoDueDate}.
 * @returns The parsed boleto, with the matching typed line filled in.
 * @throws {BoletoError} On a length other than 44, on a general check digit that
 * does not recompute, or on an arrecadação slip whose position 3 is out of spec.
 *
 * @example
 * const boleto = parseCodigoBarras(scanned);
 * if (boleto.kind === "banco") console.log(boleto.valor, boleto.vencimento);
 */
export declare function parseCodigoBarras(value: string, options?: BoletoOptions): Boleto;

/**
 * Read a typed line — 47 digits for a bank boleto, 48 for an arrecadação slip.
 *
 * Both layouts interleave check digits with the data, so the function rebuilds the
 * 44-digit barcode as it goes and every DV is verified: the three (bank) or four
 * (arrecadação) block digits, plus the general one.
 *
 * @param value - 47 or 48 digits. The usual `.`, ` ` and `-` are ignored.
 * @param options - Fator de vencimento epoch. See {@link boletoDueDate}.
 * @returns The parsed boleto, with the barcode filled in.
 * @throws {BoletoError} On a length other than 47 or 48, or on any check digit
 * that does not recompute.
 *
 * @example
 * const boleto = parseLinhaDigitavel("34191.09008 64592.181109 00000.463074 1 84410000002000");
 */
export declare function parseLinhaDigitavel(value: string, options?: BoletoOptions): Boleto;

/** Options for {@link parsePixPayload}. */
export declare interface ParsePixOptions {
    /**
     * Throw when the checksum does not match. Default `true`.
     *
     * Turn it off only to inspect a payload you already know is broken: a BR Code
     * whose CRC fails has been corrupted in transit, and the account it now points
     * at is not the account the payee published.
     */
    requireCrc?: boolean;
}

/**
 * Read a Pix "Copia e Cola" payload back into its parts.
 *
 * Tolerant by design: tags the SDK does not know about are kept verbatim in
 * {@link PixData.fields} instead of raising, because PSPs do add their own
 * templates and a reader that rejects them is useless in production. What is
 * *not* tolerated is a broken frame — a length prefix that runs off the end, a
 * missing tag 63 — or a checksum mismatch, which means the string was corrupted
 * and no longer names the account the payee published.
 *
 * @param payload - The copia-e-cola string. Surrounding whitespace is ignored.
 * @param options - See {@link ParsePixOptions}.
 * @returns The decoded payload.
 * @throws {PixError} On a malformed frame, a missing CRC tag, a tag 26 that is
 * not a Pix account, or — unless `requireCrc` is `false` — a CRC mismatch.
 *
 * @example
 * const data = parsePixPayload(copied);
 * console.log(data.key, data.amount, data.txid);
 */
export declare function parsePixPayload(payload: string, options?: ParsePixOptions): PixData;

/**
 * Municipalities that exist in the roster and have no boundary yet.
 *
 * One today: Boa Esperança do Norte (MT), installed in 2023, for which IBGE
 * serves no mesh at any endpoint. It is listed and selectable, and it is the one
 * municipality `geocodeMunicipality` cannot place — so a caller that must plot
 * every selection can check this list up front instead of discovering it as an
 * empty result.
 *
 * @returns The IBGE codes, in the order the data file declares them.
 */
export declare function pendingGeometryIds(): readonly string[];

/**
 * CRC-16/CCITT-FALSE of a string, as four upper-case hex characters.
 *
 * Bitwise rather than table-driven: 200-odd characters at 8 shifts each is
 * nothing, and a 256-entry table is 2 KB of payload every consumer of the `/br`
 * entry would carry.
 *
 * The input is taken as UTF-8 bytes. A Pix payload is ASCII by construction —
 * {@link pixPayload} rejects anything else — but the function is exported and a
 * caller may hand it arbitrary text, and hashing UTF-16 code units would then
 * disagree with every other implementation.
 *
 * @param input - Bytes to run through the register.
 * @returns Four upper-case hex characters, zero-padded.
 *
 * @example
 * pixCrc16("123456789"); // "29B1" — the catalogue check value
 */
export declare function pixCrc16(input: string): string;

/** A payload taken apart again. */
export declare interface PixData {
    /** `"dynamic"` when tag 26 carried a URL instead of a key. */
    kind: "static" | "dynamic";
    /** Present on a static payload. */
    key?: string;
    keyType?: PixKeyType;
    /** Present on a dynamic payload. */
    url?: string;
    merchantName: string;
    merchantCity: string;
    /** Reais. `undefined` when the payer chooses the amount. */
    amount?: number;
    /** ISO 4217 numeric. `"986"` for BRL. */
    currency: string;
    countryCode: string;
    merchantCategoryCode: string;
    /** `"***"` on a reusable static QR that identifies no single transaction. */
    txid?: string;
    description?: string;
    postalCode?: string;
    /** Tag 01 read as `"12"`. */
    oneTime: boolean;
    /** The four hex characters that closed the payload. */
    crc: string;
    /** Whether those four characters match a recomputed CRC. */
    crcValid: boolean;
    /** Every top-level TLV, in payload order, unknown tags included. */
    fields: PixField[];
}

/** A BR Code that carries a URL the wallet fetches to learn the amount. */
export declare interface PixDynamicInput {
    kind: "dynamic";
    /**
     * `payloadLocation` — the https URL the wallet GETs, **without** the scheme,
     * exactly as BACEN specifies (`pix.example.com/qr/v2/abc`).
     */
    url: string;
    merchantName: string;
    merchantCity: string;
    postalCode?: string;
    /** Single-use QR. Defaults to `true`, which is what a dynamic QR normally is. */
    oneTime?: boolean;
}

/** A pixel coordinate inside the plotting viewport. */
declare interface PixelPoint {
    x: number;
    y: number;
}

/**
 * A Pix payload could not be built or read.
 *
 * Its own class so a caller can tell "the operator typed a bad key" apart from a
 * bug, and so an `ErrorBoundary` can render a form error instead of a crash.
 */
export declare class PixError extends Error {
    constructor(message: string);
}

/** One TLV as it appeared in a payload, unknown tags included. */
export declare interface PixField {
    /** Two-character tag, e.g. `"59"`. */
    id: string;
    /** Raw value, still encoded when the tag is itself a template. */
    value: string;
}

/** Everything `pixPayload` accepts. */
export declare type PixInput = PixStaticInput | PixDynamicInput;

/** The five key formats DICT accepts. */
export declare type PixKeyType = "cpf" | "cnpj" | "email" | "phone" | "evp";

/**
 * Classify a Pix key, or `null` when it matches no accepted format.
 *
 * !!! warning "CPF and a national phone number are both eleven digits"
 *     `"11987654321"` is a valid mobile number and could be a CPF. The check
 *     digits break the tie: an 11-digit string is a CPF when its DV validates and
 *     a phone otherwise. Pass phone keys as `+5511987654321` to remove the guess
 *     entirely.
 *
 * @param key - Raw key, masked or not.
 * @returns The key type, or `null`.
 */
export declare function pixKeyType(key: string): PixKeyType | null;

/**
 * Build a Pix "Copia e Cola" payload — the string behind a Pix QR code.
 *
 * The format is EMVCo MPM: a flat list of `ID + 2-digit length + value` triples,
 * closed by tag 63 holding a CRC-16/CCITT-FALSE over **everything before it,
 * including the literal `6304` header of tag 63 itself**. That last detail is the
 * one implementations get wrong; see {@link pixCrc16}.
 *
 * Two shapes come out of here:
 *
 * - **static** — tag 26 carries the key, so the QR is self-contained and can be
 *   printed. Amount optional; a txid of `"***"` means "identifies no single
 *   transaction", which is what a reusable poster QR wants.
 * - **dynamic** — tag 26 carries a URL instead, and the wallet fetches the amount
 *   and payee from the PSP. Use it when the value is per-order. Defaults to
 *   single-use (tag 01 = `12`).
 *
 * The distinction matters and is not cosmetic: a static QR settles against
 * whatever the payer typed, a dynamic one against what the PSP served, so a
 * charge that must reconcile to a cent needs the dynamic form.
 *
 * @param input - Static or dynamic payload description.
 * @returns The full payload, CRC included, ready to render as a QR or to copy.
 * @throws {PixError} On an unrecognised key, a field over its length cap, a
 * non-positive amount, or text that is not representable in the BR Code.
 *
 * @example
 * pixPayload({
 *   key: "12345678909",
 *   merchantName: "Loja Tempest",
 *   merchantCity: "São Paulo",
 *   amount: 25.5,
 *   txid: "PEDIDO123",
 * });
 */
export declare function pixPayload(input: PixInput): string;

/**
 * A Pix QR code with the copia-e-cola string next to it.
 *
 * The two affordances belong together: a QR is unusable on the device that is
 * *showing* it, which is exactly where a mobile checkout puts it, so every real
 * Pix screen ends up needing the copyable string as well. Rendering only the
 * symbol is the single most common mistake in a Pix flow.
 *
 * Everything is computed locally — {@link pixPayload} builds the string and the
 * SDK's own encoder draws the symbol — so the key, the amount and the txid never
 * leave the page. A QR-image service would receive all three.
 *
 * @throws {PixError} When neither `pix` nor `payload` is given, when both are, or
 * when `pix` fails validation. A bad key is a programming or data error rather
 * than a state to render, so it surfaces; wrap the screen in `ErrorBoundary` when
 * the values come from user input.
 *
 * @example
 * <PixQRCode
 *   pix={{
 *     key: "loja@tempest.dev",
 *     merchantName: "Loja Tempest",
 *     merchantCity: "São Paulo",
 *     amount: 25.5,
 *     txid: "PEDIDO123",
 *   }}
 *   amountLabel="R$ 25,50"
 *   payeeLabel="Loja Tempest"
 * />
 *
 * @example
 * <PixQRCode payload={charge.brcode} level="Q" size={220} />
 */
export declare function PixQRCode({ pix, payload, size, level, showCopy, amountLabel, payeeLabel, labels, onCopied, className, ...rest }: PixQRCodeProps): JSX.Element;

/** Strings the component renders, so an app can translate them. */
export declare interface PixQRCodeLabels {
    /** Accessible name of the symbol. */
    qr: string;
    /** Copy button, idle. */
    copy: string;
    /** Copy button, just clicked. */
    copied: string;
}

export declare interface PixQRCodeProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
    /**
     * Build the payload from its parts. Mutually exclusive with {@link payload}.
     */
    pix?: PixInput;
    /**
     * A payload your PSP already produced, used verbatim.
     *
     * Prefer this for a dynamic charge: the PSP signed that string, and rebuilding
     * it here from parsed parts would only add a way to get it wrong.
     */
    payload?: string;
    /** Rendered side of the symbol in px, quiet zone included. Default `192`. */
    size?: number;
    /**
     * Error-correction level. Default `"M"`.
     *
     * A printed QR that will be photographed at an angle scans better at `"Q"` or
     * `"H"`; the cost is a denser symbol, so raise the size with it.
     */
    level?: QRErrorCorrection;
    /** Render the copia-e-cola line and its copy button. Default `true`. */
    showCopy?: boolean;
    /** Amount caption, e.g. `"R$ 25,50"`. Rendered above the symbol when set. */
    amountLabel?: string;
    /** Payee caption. Rendered under the amount when set. */
    payeeLabel?: string;
    labels?: Partial<PixQRCodeLabels>;
    /** Called after the payload reaches the clipboard. */
    onCopied?: () => void;
}

/** A BR Code that carries the key — the one you print on a poster. */
export declare interface PixStaticInput {
    kind?: "static";
    /** CPF, CNPJ, e-mail, phone or EVP. Validated and normalised. */
    key: string;
    /** Payee name. Truncated by the spec at 25 characters — longer throws. */
    merchantName: string;
    /** Payee city. Truncated by the spec at 15 characters — longer throws. */
    merchantCity: string;
    /** Amount in BRL. Omit for a payer-chooses-the-value QR. */
    amount?: number;
    /** Reference the PSP echoes back, `[A-Za-z0-9]{1,25}`. Defaults to `"***"`. */
    txid?: string;
    /** Free text shown by some wallets. Goes into tag 26, sub-tag 02. */
    description?: string;
    /** CEP, digits only. Optional tag 61. */
    postalCode?: string;
    /** Single-use QR: sets tag 01 to `"12"` instead of `"11"`. */
    oneTime?: boolean;
}

/**
 * The fixed tables of ISO/IEC 18004, transcribed.
 *
 * They are data, not logic: the standard specifies them and there is nothing to
 * derive. They live apart from {@link ./qr-encode} so the algorithm reads as
 * algorithm and a typo in a table stays findable.
 */
/** Error correction level, by how much of the symbol it can lose and survive. */
declare type QRErrorCorrection = "L" | "M" | "Q" | "H";

/**
 * Discrete scale: split `[min, max]` into `palette.length` equal buckets and
 * return the bucket's color (a classic choropleth "quantize" scale).
 */
export declare function quantizeScale(min: number, max: number, palette?: readonly string[]): ColorScale;

/**
 * Categorical, distinguishable colors for the five IBGE macro-regions
 * (Tableau-10 family). Swap for your brand palette if needed.
 */
export declare const REGION_COLORS: Record<BrRegion, string>;

/** Legend entries (swatch + region name) for a region-colored map. */
export declare function regionLegendItems(): LegendItem[];

/**
 * Find the municipality a name refers to, however it was written down.
 *
 * Four kinds of name resolve, which is the point — an address saved years ago
 * has to keep pointing at the same place:
 *
 * 1. The current IBGE name (`"Serra Caiada"`).
 * 2. A former name (`"Presidente Juscelino"`), from the alias table the
 *    generator builds by diffing vintages.
 * 3. A different spelling — accents, case and apostrophes are folded, so
 *    `"sant'ana do livramento"` finds `"Sant'Ana do Livramento"`.
 * 4. An administrative region of the DF (`"Ceilândia"`), which resolves to
 *    Brasília — the municipality it is part of.
 *
 * A live municipality always wins over a former name, so a name that is current
 * in one UF and historical in another resolves to the live one in each.
 *
 * @param uf - Federative unit acronym, case-insensitive.
 * @param name - The municipality, region or former name.
 * @returns The municipality, or `null` when nothing in that UF answers to it.
 */
export declare function resolveMunicipality(uf: string, name: string): BrazilMunicipality | null;

/**
 * Exact reverse-geocode: the municipality whose (simplified) boundary
 * **contains** the coordinate, via point-in-polygon. Loads one state's geometry
 * chunk — pass `uf` when you know it to skip the centroid lookup that picks the
 * candidate state. Boundaries are simplified (~2 km), so points within ~1-2 km
 * of a border may resolve to the neighbor; offshore points return `null`.
 *
 * @param coord - Query coordinate.
 * @param options - `uf` to force the state searched.
 * @returns The containing municipality, or `null` (falls back to the nearest
 *   centroid municipality when the point is inside no polygon of the state).
 *
 * @example
 * const here = await reverseGeocode({ latitude: -23.5505, longitude: -46.6333 });
 * // { id: "3550308", name: "São Paulo", uf: "SP" }
 */
export declare function reverseGeocode(coord: Coordinate, options?: {
    uf?: UF;
}): Promise<ReverseGeocodeResult | null>;

/** A municipality identified by point-in-polygon (see {@link reverseGeocode}). */
export declare interface ReverseGeocodeResult {
    id: string;
    name: string;
    uf: UF;
}

/** A ring of `[longitude, latitude]` pairs. */
export declare type Ring = [number, number][];

/**
 * Substring search over municipality names (accent-insensitive), for
 * autocomplete. Ranked prefix-first, then alphabetically.
 *
 * @param query - Partial name.
 * @param options - `uf` to scope, `limit` (default 20).
 * @returns Ranked matches.
 */
export declare function searchMunicipalities(query: string, options?: {
    uf?: UF;
    limit?: number;
}): Promise<MunicipalityCentroid[]>;

/**
 * Sequential, colorblind-safe palettes (ColorBrewer / Viridis families, public
 * domain). Ordered light → dark. Swap for your brand ramp if needed — any
 * ordered list of hex colors works with the scale builders below.
 */
export declare const SEQUENTIAL_BLUES: readonly ["#eff3ff", "#c6dbef", "#9ecae1", "#6baed6", "#3182bd", "#08519c"];

export declare const SEQUENTIAL_GREENS: readonly ["#edf8e9", "#c7e9c0", "#a1d99b", "#74c476", "#31a354", "#006d2c"];

export declare const SEQUENTIAL_VIRIDIS: readonly ["#440154", "#414487", "#2a788e", "#22a884", "#7ad151", "#fde725"];

/**
 * Continuous scale: linearly interpolate `palette` across `[min, max]`.
 *
 * @example
 * const color = sequentialScale(0, 100, SEQUENTIAL_BLUES);
 * <BrazilMap values={data} colorScale={color} />;
 */
export declare function sequentialScale(min: number, max: number, palette?: readonly string[]): ColorScale;

/**
 * Centroid of a federative unit.
 *
 * @param uf - Federative unit acronym.
 * @returns The state centroid, or `null` if unknown.
 */
export declare function stateCentroid(uf: UF): Promise<Coordinate | null>;

/** Municipality boundaries for a single federative unit. */
export declare interface StateMunicipalities {
    type: "FeatureCollection";
    /** The federative unit these municipalities belong to. */
    uf: UF;
    features: MunicipalityFeature[];
}

/** States belonging to a macro-region. */
export declare function statesByRegion(region: BrRegion): readonly BrazilState[];

/**
 * Threshold scale: `palette[i]` applies to values in
 * `[thresholds[i-1], thresholds[i])`. `palette` must have
 * `thresholds.length + 1` entries.
 *
 * @example
 * const color = thresholdScale([10, 50, 100], SEQUENTIAL_GREENS.slice(0, 4));
 */
export declare function thresholdScale(thresholds: readonly number[], palette: readonly string[]): ColorScale;

/**
 * Normalise a phone number to the digits-only form `wa.me` accepts.
 *
 * A Brazilian number is stored almost everywhere **without** the country code —
 * ten digits for a landline, eleven for a mobile — and `wa.me` refuses anything
 * that is not fully qualified. Those two shapes get `55` in front; a number that
 * already carries a country code (12 to 15 digits, the E.164 range that no
 * Brazilian national number can reach) is returned untouched, so a foreign
 * client's number still works.
 *
 * Everything else returns an empty string rather than a best guess. Handing back
 * the digits as typed is what the naive version does, and it builds a `wa.me`
 * URL that opens WhatsApp on a number nobody owns — a typo becomes a dead chat
 * window instead of a disabled button.
 *
 * Trunk and carrier-selection prefixes (`0`, `021`, …) are **not** stripped: a
 * leading zero is ambiguous between the two, so a number carrying one reads as
 * invalid instead of being silently reinterpreted. Pass the plain number. The
 * leading zero is what rules it out even at a plausible length — no E.164
 * country code starts with `0`, so `011999998888` is a national number wearing a
 * trunk prefix, never an international one.
 *
 * @example
 * toWhatsAppNumber("(11) 99999-8888"); // "5511999998888"
 * toWhatsAppNumber("+55 11 99999-8888"); // "5511999998888"
 * toWhatsAppNumber("99999-8888"); // "" — no area code, nothing to dial
 *
 * @param phone - Phone number in any shape: masked, spaced, `+`-prefixed.
 * @returns Digits ready for a `wa.me` link, or an empty string when the input
 *   cannot be resolved to a dialable number.
 */
export declare function toWhatsAppNumber(phone: string): string;

/** The 27 Brazilian federative units (26 states + Federal District). */
export declare type UF = "AC" | "AL" | "AP" | "AM" | "BA" | "CE" | "DF" | "ES" | "GO" | "MA" | "MT" | "MS" | "MG" | "PA" | "PB" | "PR" | "PE" | "PI" | "RJ" | "RN" | "RS" | "RO" | "RR" | "SC" | "SP" | "SE" | "TO";

/** `{ value: uf, label: name }` options for every state, for a `<Select>`. */
export declare function ufChoices(): Choice[];

/**
 * Whether a boleto string is internally consistent.
 *
 * Checks every digit the layout can check — the block DVs of a typed line and the
 * general DV in both representations. It says nothing about whether the boleto
 * exists, is registered, or is still payable: only a bank can answer that. What it
 * *does* catch is the common failure, a mistyped or truncated line.
 *
 * @param value - A barcode (44) or typed line (47/48), masked or not.
 * @returns `true` when everything recomputes.
 *
 * @example
 * if (!validateBoleto(input)) setError("Confira a linha digitável.");
 */
export declare function validateBoleto(value: string): boolean;

/**
 * Whether a fiscal access key is well formed.
 *
 * Three things have to hold: 44 digits, a `cUF` that is a real federative unit,
 * and a check digit that recomputes. It says nothing about whether the document
 * exists or was authorised — only SEFAZ can answer that — but it catches the
 * failure that actually happens, a key transcribed by hand or truncated by a
 * spreadsheet.
 *
 * @param chave - The key, with or without the spaces a DANFE prints.
 * @returns `true` when all three hold.
 *
 * @example
 * if (!validateChaveNFe(input)) setError("Chave inválida.");
 */
export declare function validateChaveNFe(chave: string): boolean;

/**
 * Build the `wa.me` deep link that opens a chat with an optional message
 * already typed.
 *
 * This is a **deep link, never a send**: the chat opens with the text ready and
 * the person presses send. That is the feature, not a limitation — it needs no
 * official Cloud API, no approved template and no business verification, and it
 * cannot let the UI claim a message was delivered when it was not.
 *
 * `api.whatsapp.com/send?phone=…` is deliberately not offered as an alternative
 * host: both resolve to the same chooser, and `wa.me` is the short form of it.
 *
 * @example
 * whatsAppUrl("(11) 99999-8888", "Seu horário é amanhã às 14h.");
 * // "https://wa.me/5511999998888?text=Seu%20hor%C3%A1rio%20%C3%A9%20amanh%C3%A3%20%C3%A0s%2014h."
 *
 * @param phone - Phone number in any shape; normalised by {@link toWhatsAppNumber}.
 * @param text - Message to pre-fill. Omitted or empty leaves the composer blank.
 * @returns The `https://wa.me/…` URL, or an empty string when the number cannot
 *   be normalised.
 */
export declare function whatsAppUrl(phone: string, text?: string): string;

export { }