react-iran-maps/dist/index.d.mts

Create powerful React SVG maps of Iran based on d3-geo and topojson.

import * as react_jsx_runtime from 'react/jsx-runtime';

/**
 * Data for a single county/city within a province.
 * @example { name: "تهران", value: 8500000 }
 */
interface CountyData {
    /** County name in Persian (e.g., "تهران", "کرج") */
    name: string;
    /** Value - number for quantitative data, string for categorical (e.g., "high") */
    value?: string | number;
}
/**
 * Map of county data indexed by county name. Used internally by the library.
 */
type CountyMapItem = Record<string, CountyData>;

/**
 * Data for a province and its counties. This is the main type for ChoroplethMap data.
 * @example
 * const data: ProvinceData = {
 *   name: "تهران",
 *   value: 15000000,
 *   counties: [
 *     { name: "تهران", value: 8500000 },
 *     { name: "کرج", value: 2000000 }
 *   ]
 * };
 */
interface ProvinceData {
    /** Province name in Persian (e.g., "تهران", "اصفهان") */
    name: string;
    /** Value - number for quantitative, string for categorical */
    value?: string | number;
    /** Array of counties for drilldown functionality */
    counties?: CountyData[];
}
/**
 * Internal representation of province data. Used by the library internally.
 * Counties are stored as Record instead of array.
 */
interface ProvinceMapItem {
    name: string;
    value?: string | number;
    counties?: Record<string, CountyData>;
}

/**
 * GeoJSON feature for a province. Used internally by the ChoroplethMap component.
 */
interface ProvinceFeature {
    type: "Feature";
    properties: {
        /** Province name in Persian (e.g., "تهران") */
        provincName: string;
        /** Province name in English (e.g., "Tehran") */
        NAME_1?: string;
        /** Number of counties (optional) */
        countyCount?: number;
    };
    geometry: any;
}

/**
 * GeoJSON feature for a county/city. Used internally and passed to custom tooltip renderers.
 * @example Used in renderTooltipContent prop to access county properties
 */
interface CountyFeature {
    type: "Feature";
    properties: {
        /** Province name in Persian (e.g., "تهران") */
        provincName?: string;
        /** County name in Persian (e.g., "شهریار") */
        cityName: string;
        /** Province name in English (e.g., "Tehran") */
        NAME_1: string;
        /** County name in English (optional) */
        NAME_2?: string;
        /** Geometric properties (optional) */
        area?: number;
        perimeter?: number;
        Shape_Leng?: number;
        Shape_Area?: number;
    };
    geometry: any;
}

/**
 * Single legend item for qualitative mode.
 */
interface LegendItem {
    /** Display label */
    label: string;
    /** Value to match against data */
    value: string;
    /** Hex color code */
    color: string;
}
/**
 * Legend for quantitative data (numeric values).
 * @example { mode: "quantitative", colors: ["#FFF", "#000"] }
 */
interface QuantitativeLegend {
    disable?: boolean;
    mode: "quantitative";
    /** Color gradient from low to high */
    colors: string[];
    items?: never;
}
/**
 * Legend for qualitative data (categorical values).
 * @example { mode: "qualitative", items: [{ label: "Low", value: "low", color: "#FFF" }] }
 */
interface QualitativeLegend {
    disable?: boolean;
    mode: "qualitative";
    items: LegendItem[];
    colors?: never;
}
type LegendConfig = QuantitativeLegend | QualitativeLegend;
/**
 * Props for the ChoroplethMap component.
 */
interface ChoroplethMapProps {
    /** Enable drilldown to counties on click */
    drilldown?: boolean;
    /** Disable tooltips */
    disableTooltip?: boolean;
    /** Province and county data */
    data?: ProvinceData[];
    /** Map width in pixels (default: 800) */
    width?: number;
    /** Map height in pixels (default: 600) */
    height?: number;
    /** Aspect ratio container (default: "1.23") */
    aspectRatio?: string;
    /** Legend configuration */
    legend?: LegendConfig;
    /** Map zoom scale */
    scale?: number;
    /** Custom tooltip HTML renderer */
    renderTooltipContent?: (provinceData?: ProvinceMapItem, geo?: CountyFeature) => string;
}

declare function ChoroplethMap({ drilldown, data, renderTooltipContent, width, height, aspectRatio, disableTooltip, scale: scaleProps, legend, }: ChoroplethMapProps): react_jsx_runtime.JSX.Element;

export { ChoroplethMap, type ChoroplethMapProps, type CountyData, type CountyFeature, type CountyMapItem, type ProvinceData, type ProvinceFeature, type ProvinceMapItem };