tempest-react-sdk 0.15.0 → 0.17.0

package/dist/br.d.ts

@@ -0,0 +1,271 @@
+import { HTMLAttributes } from 'react';
+import { JSX } from 'react/jsx-runtime';
+import { ReactElement } from 'react';
+import { ReactNode } from 'react';
+
+/**
+ * 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, height, padding, showLabels, label, loadingContent, 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. Default: a light primary tint. */
+    minColor?: string;
+    /** Choropleth high-end color. Default: the primary token. */
+    maxColor?: string;
+    /** 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;
+}
+
+/** 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;
+    /** City names within the state, alphabetically. */
+    cities: string[];
+}
+
+/**
+ * Cascading Estado → Cidade selector backed by the bundled BR locations data —
+ * pick a state and the city list narrows to that UF's municipalities. No
+ * network, no external API. Complements {@link BrazilMap} (wire the map's
+ * `onSelect` to drive the same UF).
+ *
+ * @example
+ * <BrazilStateCitySelect onChange={({ uf, city }) => console.log(uf, city)} />
+ */
+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;
+}
+
+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, height, padding, showLabels, label, loadingContent, 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. Default: a light primary tint. */
+    minColor?: string;
+    /** Choropleth high-end color. Default: the primary token. */
+    maxColor?: string;
+    /** 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;
+}
+
+/** 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;
+    };
+    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[][];
+}
+
+/** 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[];
+
+/** Look up a single state by acronym (case-insensitive). Returns `null` if unknown. */
+export declare function getState(uf: string): BrazilState | null;
+
+/** 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;
+
+/** 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>;
+
+/** A municipality identified for selection callbacks. */
+export declare interface Municipality {
+    /** 7-digit IBGE code. */
+    id: string;
+    /** Municipality name. */
+    name: string;
+}
+
+/** One municipality feature within a state. */
+export declare interface MunicipalityFeature {
+    type: "Feature";
+    properties: {
+        /** 7-digit IBGE municipality code. */
+        id: string;
+        /** Municipality name. */
+        name: string;
+    };
+    geometry: BrUfGeometry;
+}
+
+/**
+ * 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 ring of `[longitude, latitude]` pairs. */
+export declare type Ring = [number, number][];
+
+/** 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[];
+
+/** 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[];
+
+export { }