@sil/data 0.1.5 → 0.1.6

package/dist/types/__tests__/countryMaps.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/data/countryMaps.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Individual country SVG map utilities.
+ *
+ * Provides functions to render a standalone SVG for a single country, using
+ * the bundled world-map path data for the country outline and the bundled
+ * cities dataset for optional city markers.  The viewBox is automatically
+ * derived from the country's geographic bounding box stored in the geography
+ * dataset.
+ *
+ * For maps that also show administrative subdivision (province / state)
+ * boundaries, use {@link getCountrySubdivisionMapUrl} to obtain a reference
+ * URL pointing to an external source – those boundaries are not bundled in
+ * this package.
+ *
+ * @example
+ * ```ts
+ * import { getCountrySvg } from "@sil/data";
+ *
+ * // Render Germany with city markers
+ * document.getElementById("map").innerHTML = getCountrySvg("DE", {
+ *   fill: "#4a90e2",
+ *   stroke: "#ffffff",
+ * });
+ *
+ * // Render France without city markers
+ * document.getElementById("map").innerHTML = getCountrySvg("FR", {
+ *   showCities: false,
+ * });
+ * ```
+ */
+import type { CountryMapOptions } from "../types/index.js";
+/**
+ * Default styling and display options for single-country SVG maps.
+ */
+export declare const COUNTRY_MAP_DEFAULTS: Required<CountryMapOptions>;
+/**
+ * Convert geographic coordinates (latitude / longitude) to the SVG coordinate
+ * system used by the bundled world-map path data.
+ *
+ * The world map uses a simple equirectangular projection scaled to a
+ * 2000 × 857 canvas (matching `WORLD_MAP_VIEWBOX`).
+ *
+ * @param lat Latitude in decimal degrees (−90 … +90)
+ * @param lon Longitude in decimal degrees (−180 … +180)
+ * @returns `{ x, y }` in world-map SVG units.
+ *
+ * @example
+ * const { x, y } = latLonToMapPoint(52.52, 13.41); // Berlin, Germany
+ */
+export declare function latLonToMapPoint(lat: number, lon: number): {
+    x: number;
+    y: number;
+};
+/**
+ * Return an external URL for a country's administrative-subdivision map.
+ *
+ * The URL points to a Wikimedia Commons PNG rendering (800 px wide) of the
+ * corresponding SVG map file.  These maps typically include province, state,
+ * or region boundaries.  The image is **not bundled** in this package – it is
+ * fetched at runtime from Wikimedia servers.
+ *
+ * **Note:** Wikimedia Commons SVG thumbnails require a hash-based path for
+ * most files.  This helper uses the same simplified URL convention that is
+ * already in use in the `flags` module (`getCountryMapSvgUrl`).  If a
+ * particular country's map file is not served at this path, the URL may
+ * return a 404; in that case, use the Wikimedia Commons search page for
+ * `"administrative divisions map of {country name}"` to find the correct file.
+ *
+ * @param alpha3 ISO 3166-1 alpha-3 code (case-insensitive, e.g. `"DEU"`, `"usa"`)
+ * @returns A reference URL string – not guaranteed to resolve for every country.
+ *
+ * @example
+ * getCountrySubdivisionMapUrl("DEU");
+ * // → "https://upload.wikimedia.org/wikipedia/commons/thumb/maps/DEU.svg/800px-DEU.svg.png"
+ */
+export declare function getCountrySubdivisionMapUrl(alpha3: string): string;
+/**
+ * Render a standalone SVG string for a single country.
+ *
+ * The SVG shows:
+ * - The country's outline, drawn from the bundled world-map vector paths.
+ * - Optional city markers (dots) for every city in the bundled cities dataset
+ *   that belongs to this country.  Capital cities use a distinct colour and a
+ *   slightly larger dot.
+ *
+ * Each country `<path>` element receives:
+ * - `id` — ISO alpha-2 code, e.g. `id="DE"`
+ * - `data-code` — same code
+ * - `data-name` — human-readable country name
+ *
+ * Each city `<circle>` element receives:
+ * - `data-city` — city name
+ * - `data-capital="true"` — only present for the capital city
+ *
+ * @param alpha2  ISO 3166-1 alpha-2 code (case-insensitive, e.g. `"DE"`, `"us"`)
+ * @param options Optional styling / display overrides.
+ * @returns A complete `<svg>…</svg>` string, or `null` if the country code is
+ *   unknown or has no drawable path data.
+ *
+ * @example
+ * const svg = getCountrySvg("JP", { fill: "#e8f4f8", capitalColor: "#e24a4a" });
+ * document.getElementById("map")!.innerHTML = svg ?? "";
+ */
+export declare function getCountrySvg(alpha2: string, options?: CountryMapOptions): string | null;

package/dist/types/index.d.ts

@@ -15,7 +15,7 @@
  * }));
  * ```
  */
-export type { Country, PhoneCountryCode, City, State, StateType, Continent, ContinentName, Currency, CountryGeography, CountryBounds, ClimateZone, FlagInfo, FlagColor, CardinalDirection, WorldMapCountry, WorldMapOptions, WorldMapHighlight, } from "./types/index.js";
+export type { Country, PhoneCountryCode, City, State, StateType, Continent, ContinentName, Currency, CountryGeography, CountryBounds, ClimateZone, FlagInfo, FlagColor, CardinalDirection, WorldMapCountry, WorldMapOptions, WorldMapHighlight, CountryMapOptions, } from "./types/index.js";
 export { countries, getCountryByCode, getCountriesByContinent, getCountryFlag, } from "./data/countries.js";
 export { phoneCountryCodes, getPhoneCodeByCountry, getCountriesByPhoneCode, } from "./data/phoneCodes.js";
 export { cities, getCitiesByCountry, getCapitalCity, getCitiesByPopulation, searchCities, } from "./data/cities.js";
@@ -27,3 +27,4 @@ export { flagData, getFlagData, getFlagsByColor, getSimilarFlags, getFlagSvgUrl,
 export { haversineDistance, bearing, bearingToCardinal, getDistanceBetweenCountries, getDirectionBetweenCountries, compareTemperature, compareSize, getHemisphere, getGeoHints, } from "./utils/geo.js";
 export type { GeoHint, Hemisphere } from "./utils/geo.js";
 export { WORLD_MAP_VIEWBOX, WORLD_MAP_DEFAULTS, worldMapCountries, getCountryMapData, searchWorldMapCountries, getWorldMapSvg, highlightCountries, colorizeWorldMap, } from "./data/worldMap.js";
+export { COUNTRY_MAP_DEFAULTS, latLonToMapPoint, getCountrySvg, getCountrySubdivisionMapUrl, } from "./data/countryMaps.js";

package/dist/types/types/index.d.ts

@@ -218,3 +218,32 @@ export interface WorldMapHighlight {
     /** Optional accessible label (written as a `<title>` element). */
     label?: string;
 }
+/**
+ * Styling and display options for rendering a single-country SVG map.
+ */
+export interface CountryMapOptions {
+    /** Fill color for the country shape. Default: "#d0d0d0" */
+    fill?: string;
+    /** Stroke (border) color for the country outline. Default: "#ffffff" */
+    stroke?: string;
+    /** Stroke width in SVG units. Default: 0.5 */
+    strokeWidth?: number;
+    /** SVG element width attribute (e.g. "100%", 800). Default: "100%" */
+    width?: string | number;
+    /** SVG element height attribute (e.g. "auto", 400). Default: "auto" */
+    height?: string | number;
+    /** Optional CSS class added to the `<svg>` element. */
+    className?: string;
+    /** Whether to show city marker dots. Default: true */
+    showCities?: boolean;
+    /** Fill color for regular city markers. Default: "#555555" */
+    cityColor?: string;
+    /** Fill color for the capital city marker. Default: "#cc2222" */
+    capitalColor?: string;
+    /** Radius of regular city markers in SVG units. Default: 3 */
+    cityRadius?: number;
+    /** Radius of the capital city marker in SVG units. Default: 5 */
+    capitalRadius?: number;
+    /** Extra space (in SVG units) added around the country outline. Default: 5 */
+    padding?: number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sil/data",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "A comprehensive collection of reusable world data: countries, phone codes, flags, cities, states, provinces and more",
   "type": "module",
   "main": "./dist/sil-data.cjs",