tempest-react-sdk 0.18.0 → 0.19.1

package/dist/br.d.ts

@@ -20,7 +20,7 @@ import { ReactNode } from 'react';
  * // Choropleth by a metric per state
  * <BrazilMap values={{ SP: 120, RJ: 90, MG: 60 }} />
  */
-export declare function BrazilMap({ selected, onSelect, values, minColor, maxColor, height, padding, showLabels, label, loadingContent, showTooltip, renderTooltip, className, style, ...rest }: BrazilMapProps): JSX.Element;
+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. */
@@ -33,10 +33,20 @@ export declare interface BrazilMapProps extends Omit<HTMLAttributes<HTMLDivEleme
      * use the base surface color.
      */
     values?: Partial<Record<UF, number>>;
-    /** Choropleth low-end color. Default: a light primary tint. */
+    /** Choropleth low-end color (2-color linear ramp). Default: a light primary tint. */
     minColor?: string;
-    /** Choropleth high-end color. Default: the primary token. */
+    /** 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`. */
@@ -51,6 +61,12 @@ export declare interface BrazilMapProps extends Omit<HTMLAttributes<HTMLDivEleme
     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. */
@@ -127,7 +143,7 @@ export declare interface BrazilStateCitySelectProps {
  * // 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, height, padding, showLabels, label, loadingContent, showTooltip, renderTooltip, className, style, ...rest }: BrazilStateMapProps): JSX.Element;
+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). */
@@ -141,10 +157,15 @@ export declare interface BrazilStateMapProps extends Omit<HTMLAttributes<HTMLDiv
      * municipality is tinted between `minColor` and `maxColor`.
      */
     values?: Record<string, number>;
-    /** Choropleth low-end color. Default: a light primary tint. */
+    /** Choropleth low-end color (2-color linear ramp). Default: a light primary tint. */
     minColor?: string;
-    /** Choropleth high-end color. Default: the primary token. */
+    /** 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`. */
@@ -162,6 +183,12 @@ export declare interface BrazilStateMapProps extends Omit<HTMLAttributes<HTMLDiv
     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. */
@@ -180,6 +207,8 @@ export declare interface BrUfFeature {
         uf: UF;
         name: string;
         region: BrRegion;
+        /** Representative point `[longitude, latitude]` (area-weighted centroid). */
+        centroid: [number, number];
     };
     geometry: BrUfGeometry;
 }
@@ -212,15 +241,84 @@ 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[];
 
+/** 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;
+}
+
+/** Diverging palette (red ↔ neutral ↔ blue), for signed metrics. */
+export declare const DIVERGING_RDBU: readonly ["#b2182b", "#ef8a62", "#fddbc7", "#d1e5f0", "#67a9cf", "#2166ac"];
+
+/** 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;
+}
+
+/**
+ * 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;
 
+/**
+ * Interpolate a palette at `t ∈ [0, 1]`, blending between the two nearest
+ * stops. `t <= 0` → first color, `t >= 1` → last.
+ */
+export declare function interpolatePalette(palette: readonly string[], t: number): string;
+
 /** 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;
+}
+
 /** All 27 federative units, sorted by name. */
 export declare function listStates(): readonly BrazilState[];
 
@@ -244,6 +342,62 @@ export declare function loadBrUfGeoJson(): Promise<BrUfFeatureCollection>;
  */
 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;
+}
+
+/**
+ * SVG overlay of point markers, projected with the host map's projection so
+ * they align with its shapes. Each marker carries a native `<title>` (its
+ * `label`) and is clickable when `onMarkerClick` is set.
+ */
+export declare function MapMarkers({ projection, markers, onMarkerClick }: MapMarkersProps): JSX.Element;
+
+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;
+}
+
 /** A municipality identified for selection callbacks. */
 export declare interface Municipality {
     /** 7-digit IBGE code. */
@@ -252,6 +406,26 @@ export declare interface Municipality {
     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";
@@ -260,19 +434,163 @@ export declare interface MunicipalityFeature {
         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>;
+
 /**
  * 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;
 
+/** A pixel coordinate inside the plotting viewport. */
+declare interface PixelPoint {
+    x: number;
+    y: number;
+}
+
+/**
+ * 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[];
+
+/**
+ * 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";
@@ -284,6 +602,16 @@ export declare interface StateMunicipalities {
 /** 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;
+
 /** 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";