leaflet-india-boundary 0.1.0

package/src/leaflet.ts

@@ -0,0 +1,252 @@
+import {
+  geoJSON,
+  type GeoJSON as LeafletGeoJSON,
+  type Map as LeafletMap,
+  type Path,
+  type PathOptions,
+} from "leaflet";
+import { INDIA_BOUNDARY_ATTRIBUTION } from "./attribution.js";
+import { INDIA_BOUNDARY, type IndiaBoundaryProperties } from "./data.js";
+import {
+  isOsmAdminBoundaryVisible,
+  OSM_ADMIN_BOUNDARY_MIN_ZOOM,
+  OSM_ADMIN_BOUNDARY_OPACITY,
+  osmAdminBoundaryColor,
+  osmAdminBoundaryWidth,
+  OSM_ADMIN_BOUNDARY_WIDE_ZOOM,
+  type OsmAdminBoundaryStyleOptions,
+} from "./style.js";
+
+/** Base class Leaflet writes onto the SVG paths, for CSS overrides. */
+export const INDIA_BOUNDARY_CLASS = "leaflet-india-boundary";
+
+/** Added alongside the base class from `wideZoom` up, mirroring carto's colour swap. */
+export const INDIA_BOUNDARY_WIDE_CLASS = "leaflet-india-boundary--wide";
+
+/** Pane the layer creates and filters when `tileFilter` is set. */
+export const INDIA_BOUNDARY_PANE = "indiaBoundary";
+
+export interface IndiaBoundaryLayerOptions extends OsmAdminBoundaryStyleOptions {
+  /**
+   * A CSS filter to put the boundary stroke through — pass exactly the same value
+   * your app applies to `.leaflet-tile-pane`.
+   *
+   * **This is the option most likely to be needed and least likely to be
+   * guessed, so it is worth the paragraph.** If your basemap is stock OSM raster
+   * tiles, leave this unset and everything below is irrelevant.
+   *
+   * If instead you filter your tile pane — inverting OSM's light tiles to build a
+   * dark basemap is the common case — then the tiles on screen are no longer the
+   * colours OSM rendered. carto's border colours are still correct *inside the
+   * tile*, but your overlay is drawn into a pane that is not filtered, so a
+   * colour lifted from carto's stylesheet lands nowhere near the purple actually
+   * visible. Passing the same filter here puts the overlay through the same
+   * transform, and it comes out matching.
+   *
+   * Setting this also raises the default `opacity` from carto's 0.5 to 1 — see
+   * {@link IndiaBoundaryLayerOptions.opacity}.
+   *
+   * Implemented by creating a dedicated map pane and filtering that, so it works
+   * under both the SVG and Canvas renderers. If you also pass `pane`, the filter
+   * goes on *your* pane and therefore on everything else in it, so pass a pane you
+   * own.
+   */
+  tileFilter?: string;
+
+  /**
+   * Stroke opacity. Defaults to carto's own 0.5, or to 1 when `tileFilter` is set.
+   *
+   * The default is conditional because carto's 0.5 is not a free-standing value —
+   * it is composited against carto's light land fill (`#f2efe9`) *inside the tile*,
+   * before any filter of yours runs. Honouring 0.5 on the unfiltered side of an
+   * inverting filter, over a near-black map, lands about three times too dark. The
+   * exact match was tried in the app this came from and resolves to `#5b5157`,
+   * which is genuinely indistinguishable from OSM's own borders and therefore
+   * genuinely invisible: a dark basemap crushes every border, OSM's included.
+   *
+   * So: unfiltered basemap, 0.5 is right. Filtered basemap, 1 keeps carto's hue
+   * while staying legible, which is the entire point of drawing the line.
+   */
+  opacity?: number;
+
+  /** Extra class(es) on each path, alongside {@link INDIA_BOUNDARY_CLASS}. */
+  className?: string;
+
+  /**
+   * Map pane to draw into. Defaults to Leaflet's `overlayPane`, or to a pane this
+   * layer creates ({@link INDIA_BOUNDARY_PANE}) when `tileFilter` is set.
+   */
+  pane?: string;
+
+  /**
+   * Attribution shown in Leaflet's attribution control. Defaults to
+   * {@link INDIA_BOUNDARY_ATTRIBUTION}, because the OSM-derived portion of this
+   * data is ODbL and asks for it. Pass `false` only if you credit it elsewhere.
+   */
+  attribution?: string | false;
+
+  /**
+   * Whether the boundary responds to the pointer. Off by default: it is a border,
+   * not a feature, and a national boundary swallowing clicks meant for the markers
+   * underneath it is a bug in every app I can imagine.
+   */
+  interactive?: boolean;
+}
+
+interface Resolved {
+  style: OsmAdminBoundaryStyleOptions;
+  opacity: number;
+  wideZoom: number;
+  className?: string;
+  tileFilter?: string;
+  pane?: string;
+  interactive: boolean;
+}
+
+function resolve(options: IndiaBoundaryLayerOptions): Resolved {
+  return {
+    style: options,
+    // The one line in this package that encodes the filter interaction.
+    opacity: options.opacity ?? (options.tileFilter ? 1 : OSM_ADMIN_BOUNDARY_OPACITY),
+    wideZoom: options.wideZoom ?? OSM_ADMIN_BOUNDARY_WIDE_ZOOM,
+    className: options.className,
+    tileFilter: options.tileFilter,
+    pane: options.pane ?? (options.tileFilter ? INDIA_BOUNDARY_PANE : undefined),
+    interactive: options.interactive ?? false,
+  };
+}
+
+function pathStyle(zoom: number, r: Resolved): PathOptions {
+  const wide = zoom >= r.wideZoom;
+  const classes = [INDIA_BOUNDARY_CLASS];
+  if (wide) classes.push(INDIA_BOUNDARY_WIDE_CLASS);
+  if (r.className) classes.push(r.className);
+
+  return {
+    className: classes.join(" "),
+    color: osmAdminBoundaryColor(zoom, r.style),
+    weight: osmAdminBoundaryWidth(zoom),
+    opacity: r.opacity,
+    // Below carto's z4 the basemap draws no national borders, so this draws
+    // nothing either. `stroke: false` rather than removing the layer from the
+    // map: same result on screen, but `map.hasLayer()` keeps telling the truth
+    // and layer-control checkboxes do not flicker.
+    stroke: isOsmAdminBoundaryVisible(zoom, r.style),
+    fill: false,
+    interactive: r.interactive,
+    // carto joins its border segments with a bevel. Note that nothing in CSS may
+    // set `stroke-linejoin` — a CSS property would beat the SVG attribute
+    // Leaflet writes here.
+    lineJoin: "bevel",
+  };
+}
+
+/**
+ * India's boundary through Jammu & Kashmir, Ladakh and Aksai Chin — as depicted
+ * by the Survey of India — drawn over your basemap in the basemap's own border
+ * style.
+ *
+ * ```js
+ * import { indiaBoundaryLayer } from "leaflet-india-boundary/leaflet";
+ *
+ * indiaBoundaryLayer().addTo(map);
+ * ```
+ *
+ * The returned layer restyles itself on zoom, so carto's per-zoom widths and its
+ * colour swap at z10 keep matching the tiles underneath, and it draws nothing
+ * below z4 where the basemap has no national borders to match.
+ *
+ * ## The ceiling, stated plainly
+ *
+ * This *adds* India's claimed border. It cannot *remove* the Line of Control /
+ * Line of Actual Control that raster tiles have already drawn, because by the time
+ * a tile reaches the browser it is a picture. Where the two run apart, both are
+ * visible. Suppressing the basemap's own line needs either vector tiles, where the
+ * boundary layer can be filtered out, or a provider political view — HERE's
+ * `pview=IN`, MapTiler's worldview setting.
+ */
+export function indiaBoundaryLayer(
+  options: IndiaBoundaryLayerOptions = {},
+): LeafletGeoJSON<IndiaBoundaryProperties> {
+  const r = resolve(options);
+  const attribution = options.attribution ?? INDIA_BOUNDARY_ATTRIBUTION;
+
+  // Declared before `geoJSON()` on purpose. Leaflet builds the child paths
+  // synchronously inside the constructor, which calls `style` right there — so a
+  // `style` closure reading a `let` declared afterwards would hit it in its
+  // temporal dead zone and throw on construction.
+  let map: LeafletMap | null = null;
+  const zoomNow = () => map?.getZoom() ?? r.style.minZoom ?? OSM_ADMIN_BOUNDARY_MIN_ZOOM;
+
+  const layer = geoJSON<IndiaBoundaryProperties>(INDIA_BOUNDARY, {
+    style: () => pathStyle(zoomNow(), r),
+    pane: r.pane,
+    interactive: r.interactive,
+    ...(attribution === false ? {} : { attribution }),
+  });
+
+  const restyle = () => {
+    const zoom = zoomNow();
+    layer.setStyle(() => pathStyle(zoom, r));
+
+    // `setStyle` does not reapply `className`. Leaflet writes the class once, when
+    // it creates the path element, and its `_updateStyle` only touches the paint
+    // attributes — so the wide-zoom modifier has to be toggled by hand or it stays
+    // frozen at whatever it was when the layer was built. Harmless for the default
+    // rendering, where the colour arrives as the `stroke` attribute; not harmless
+    // for anyone driving the colours from style.css, where the class *is* the
+    // mechanism.
+    const wide = zoom >= r.wideZoom;
+    for (const el of indiaBoundaryElements(layer)) {
+      el.classList.toggle(INDIA_BOUNDARY_WIDE_CLASS, wide);
+    }
+  };
+
+  // Instance-level overrides of two documented `Layer` methods. Leaflet's own
+  // class system (`L.GeoJSON.extend`) would work too, but it types poorly and
+  // subclassing it from an ES class fights its `initialize` convention for no
+  // gain — there is no second implementation to share.
+  const baseOnAdd = layer.onAdd.bind(layer);
+  const baseOnRemove = layer.onRemove.bind(layer);
+
+  layer.onAdd = (m: LeafletMap) => {
+    map = m;
+    // Must happen before the base `onAdd`, which is when each path resolves the
+    // renderer that will live in this pane.
+    if (r.tileFilter && r.pane) {
+      const pane = m.getPane(r.pane) ?? m.createPane(r.pane);
+      if (!pane.style.zIndex) pane.style.zIndex = "400"; // beside overlayPane, under markers
+      pane.style.filter = r.tileFilter;
+      if (!r.interactive) pane.style.pointerEvents = "none";
+    }
+    const result = baseOnAdd(m);
+    m.on("zoomend", restyle);
+    restyle();
+    return result;
+  };
+
+  layer.onRemove = (m: LeafletMap) => {
+    m.off("zoomend", restyle);
+    map = null;
+    return baseOnRemove(m);
+  };
+
+  return layer;
+}
+
+/**
+ * Escape hatch for anyone doing something this factory does not cover — reading
+ * the live SVG elements, say, to hand them to an animation library.
+ *
+ * Returns undefined for canvas-rendered paths, which have no element of their own.
+ */
+export function indiaBoundaryElements(
+  layer: LeafletGeoJSON<IndiaBoundaryProperties>,
+): Element[] {
+  const out: Element[] = [];
+  layer.eachLayer((child) => {
+    const el = (child as Path).getElement?.();
+    if (el) out.push(el);
+  });
+  return out;
+}

package/src/react.ts

@@ -0,0 +1,92 @@
+import { useEffect } from "react";
+import { useMap } from "react-leaflet";
+import { indiaBoundaryLayer, type IndiaBoundaryLayerOptions } from "./leaflet.js";
+
+export type IndiaBoundaryProps = IndiaBoundaryLayerOptions;
+
+/**
+ * react-leaflet wrapper. Drop it inside a `<MapContainer>`, anywhere below the
+ * `<TileLayer>`:
+ *
+ * ```tsx
+ * import { IndiaBoundary } from "leaflet-india-boundary/react";
+ *
+ * <MapContainer center={[22, 79]} zoom={5}>
+ *   <TileLayer url="https://tile.openstreetmap.org/{z}/{x}/{y}.png" />
+ *   <IndiaBoundary />
+ * </MapContainer>
+ * ```
+ *
+ * If your app filters its tile pane to build a dark basemap, pass the same filter
+ * so the overlay is transformed with it — see `tileFilter` on
+ * {@link IndiaBoundaryLayerOptions}, which is the one option worth reading about
+ * before you need it:
+ *
+ * ```tsx
+ * <IndiaBoundary tileFilter="invert(1) hue-rotate(192deg) saturate(0.45)" />
+ * ```
+ *
+ * Renders no DOM of its own — the layer is Leaflet's, so React only owns its
+ * lifetime. Note this file is deliberately `.ts`, not `.tsx`: the component
+ * returns `null`, so the package needs no JSX transform to build.
+ */
+export function IndiaBoundary(props: IndiaBoundaryProps = {}): null {
+  const map = useMap();
+
+  // Every option is a primitive, so they can be listed individually instead of
+  // reaching for a deep-equality hook or re-creating the layer whenever the
+  // caller passes a fresh object literal (which, in JSX, is every render).
+  const {
+    attribution,
+    className,
+    color,
+    colorWide,
+    interactive,
+    minZoom,
+    opacity,
+    pane,
+    tileFilter,
+    wideZoom,
+  } = props;
+
+  useEffect(() => {
+    const layer = indiaBoundaryLayer({
+      attribution,
+      className,
+      color,
+      colorWide,
+      interactive,
+      minZoom,
+      opacity,
+      pane,
+      tileFilter,
+      wideZoom,
+    });
+    layer.addTo(map);
+    return () => {
+      layer.remove();
+    };
+  }, [
+    map,
+    attribution,
+    className,
+    color,
+    colorWide,
+    interactive,
+    minZoom,
+    opacity,
+    pane,
+    tileFilter,
+    wideZoom,
+  ]);
+
+  return null;
+}
+
+export {
+  INDIA_BOUNDARY_CLASS,
+  INDIA_BOUNDARY_PANE,
+  INDIA_BOUNDARY_WIDE_CLASS,
+  indiaBoundaryLayer,
+  type IndiaBoundaryLayerOptions,
+} from "./leaflet.js";

package/src/style.css

@@ -0,0 +1,66 @@
+/*
+ * leaflet-india-boundary — OPTIONAL stylesheet.
+ *
+ * You do not need this file. The layer sets colour, width, opacity and join as
+ * SVG attributes, so `indiaBoundaryLayer().addTo(map)` already draws a border
+ * that matches the basemap. Import this only if you would rather drive the
+ * styling from CSS than from JavaScript options.
+ *
+ *   import "leaflet-india-boundary/style.css";
+ *
+ * Be aware of the precedence if you do: a CSS `stroke` beats the SVG `stroke`
+ * attribute Leaflet writes, so any colour rule here silently wins over the
+ * `color` / `colorWide` options. That is the point of the file, but it is worth
+ * knowing before you spend an afternoon wondering why `color` does nothing.
+ *
+ * One rule you must not add: `stroke-linejoin`. The layer sets `lineJoin: bevel`
+ * as an SVG attribute to match carto, and a CSS property would override it.
+ */
+
+.leaflet-india-boundary {
+  /* Belt and braces. The layer also passes `interactive: false`, which keeps
+     Leaflet from marking the paths as pointer targets, so clicks reach the
+     markers underneath. */
+  pointer-events: none;
+
+  /* CSS route to the tile-filter fix, for apps that would rather set a variable
+     than pass `tileFilter` in JS. Set it on your map container:
+
+       .leaflet-container {
+         --india-boundary-filter: invert(1) hue-rotate(192deg) saturate(0.45);
+       }
+
+     Use one route or the other, not both — `tileFilter` filters a dedicated pane,
+     and combining the two filters the stroke twice.
+
+     Why this exists at all: if you filter `.leaflet-tile-pane` to turn OSM's light
+     tiles into a dark basemap, the tiles on screen are no longer the colours OSM
+     rendered, while this overlay sits in an unfiltered pane. carto's purple applied
+     raw here lands nowhere near the purple actually visible. Putting the overlay
+     through the same filter is what makes them match. See the README. */
+  filter: var(--india-boundary-filter, none);
+}
+
+/*
+ * carto's own values, for reference and for overriding. Uncomment to take control
+ * of the colours from CSS.
+ *
+ * These are openstreetmap-carto's `@admin-boundaries` and `@admin-boundaries-wide`
+ * verbatim from `style/admin.mss`, which is the whole trick: the border reads as
+ * part of the map because it is the exact colour the map draws every other national
+ * border in.
+ *
+ * Do not add a white line underneath. carto has one, but it is a `comp-op: darken`
+ * device for hiding the seam where two countries' borders overlap — not a visible
+ * casing. On a single overlay there is no seam to hide and it just looks wrong.
+ */
+
+/*
+.leaflet-india-boundary {
+  stroke: #8d618b;
+}
+
+.leaflet-india-boundary--wide {
+  stroke: #a37da1;
+}
+*/

package/src/style.ts

@@ -0,0 +1,168 @@
+/**
+ * openstreetmap-carto's own `admin_level=2` border style, transcribed from its
+ * `style/admin.mss` (the `::wideline` attachment) rather than picked by eye.
+ *
+ * Matching these exactly is most of what stops the overlay reading as something
+ * drawn *on top of* the basemap instead of part of it. A border that is a
+ * slightly different purple, or a pixel too heavy, looks like an annotation. The
+ * same border in the basemap's own colour and weight looks like the map.
+ *
+ * Nothing in this module imports Leaflet, or anything else. It is here so that a
+ * MapLibre, OpenLayers or deck.gl user gets the same values without taking a
+ * mapping dependency they do not use.
+ */
+
+/** carto's `@admin-boundaries`. Applies below {@link OSM_ADMIN_BOUNDARY_WIDE_ZOOM}. */
+export const OSM_ADMIN_BOUNDARY_COLOR = "#8d618b";
+
+/** carto's `@admin-boundaries-wide`, which it swaps in from zoom 10. */
+export const OSM_ADMIN_BOUNDARY_COLOR_WIDE = "#a37da1";
+
+/** The zoom at which carto swaps `@admin-boundaries` for the lighter wide colour. */
+export const OSM_ADMIN_BOUNDARY_WIDE_ZOOM = 10;
+
+/**
+ * carto's country-border rule starts at `[zoom >= 4]`, so below that the basemap
+ * draws no national boundaries at all — and neither should this overlay. On a
+ * borderless world map it is a lone squiggle floating over central Asia, attached
+ * to nothing. See `isOsmAdminBoundaryVisible`.
+ */
+export const OSM_ADMIN_BOUNDARY_MIN_ZOOM = 4;
+
+/**
+ * carto's width table ends here. Above it the z14 width carries on, which is what
+ * carto does too.
+ */
+export const OSM_ADMIN_BOUNDARY_MAX_TABLE_ZOOM = 14;
+
+/**
+ * carto's own stroke opacity for national borders.
+ *
+ * Read the note on `tileFilter` in the README before overriding this. Short
+ * version: carto composites this 0.5 against its light land fill (`#f2efe9`)
+ * *inside the tile*. If your app puts a CSS filter over its tile pane, an overlay
+ * drawn at 0.5 on the unfiltered side of that filter lands roughly three times
+ * too dark and disappears.
+ */
+export const OSM_ADMIN_BOUNDARY_OPACITY = 0.5;
+
+/**
+ * Stroke width by zoom, from carto's `::wideline` attachment.
+ *
+ * carto pairs this with a white "background" line, which is *not* a visible
+ * casing — it is a `comp-op: darken` trick for hiding the seams where two
+ * countries' borders overlap. Do not draw one. On a single overlay there is
+ * nothing to hide, and a white line under a purple one just looks like a mistake.
+ */
+export const OSM_ADMIN_BOUNDARY_WIDTH: Readonly<Record<number, number>> =
+  Object.freeze({
+    4: 1.2,
+    5: 1.5,
+    6: 1.8,
+    7: 2.2,
+    8: 3,
+    9: 3.5,
+    10: 4.5,
+    11: 5,
+    12: 6,
+    13: 7,
+    14: 8,
+  });
+
+/** Every carto-derived value in one object, for destructuring or spreading. */
+export const OSM_ADMIN_STYLE = Object.freeze({
+  color: OSM_ADMIN_BOUNDARY_COLOR,
+  colorWide: OSM_ADMIN_BOUNDARY_COLOR_WIDE,
+  wideZoom: OSM_ADMIN_BOUNDARY_WIDE_ZOOM,
+  minZoom: OSM_ADMIN_BOUNDARY_MIN_ZOOM,
+  maxTableZoom: OSM_ADMIN_BOUNDARY_MAX_TABLE_ZOOM,
+  opacity: OSM_ADMIN_BOUNDARY_OPACITY,
+  width: OSM_ADMIN_BOUNDARY_WIDTH,
+});
+
+/** Overrides accepted by the resolvers below and by every layer factory. */
+export interface OsmAdminBoundaryStyleOptions {
+  /** Stroke colour below `wideZoom`. Defaults to carto's `@admin-boundaries`. */
+  color?: string;
+  /** Stroke colour from `wideZoom` up. Defaults to carto's `@admin-boundaries-wide`. */
+  colorWide?: string;
+  /** Zoom at which `colorWide` takes over. Defaults to 10, as carto does. */
+  wideZoom?: number;
+  /** Below this zoom the boundary is not drawn. Defaults to 4, as carto does. */
+  minZoom?: number;
+  /** Stroke opacity. Defaults to carto's 0.5 — but see `tileFilter`. */
+  opacity?: number;
+}
+
+/** carto's width for a zoom, clamped to the ends of its table. */
+export function osmAdminBoundaryWidth(zoom: number): number {
+  const z = Math.min(
+    OSM_ADMIN_BOUNDARY_MAX_TABLE_ZOOM,
+    Math.max(OSM_ADMIN_BOUNDARY_MIN_ZOOM, Math.round(zoom)),
+  );
+  return OSM_ADMIN_BOUNDARY_WIDTH[z] ?? OSM_ADMIN_BOUNDARY_WIDTH[OSM_ADMIN_BOUNDARY_MIN_ZOOM];
+}
+
+/** carto's border colour for a zoom. */
+export function osmAdminBoundaryColor(
+  zoom: number,
+  options: OsmAdminBoundaryStyleOptions = {},
+): string {
+  const wideZoom = options.wideZoom ?? OSM_ADMIN_BOUNDARY_WIDE_ZOOM;
+  return zoom >= wideZoom
+    ? (options.colorWide ?? OSM_ADMIN_BOUNDARY_COLOR_WIDE)
+    : (options.color ?? OSM_ADMIN_BOUNDARY_COLOR);
+}
+
+/** Whether the basemap draws national borders at this zoom, and so whether we should. */
+export function isOsmAdminBoundaryVisible(
+  zoom: number,
+  options: OsmAdminBoundaryStyleOptions = {},
+): boolean {
+  return zoom >= (options.minZoom ?? OSM_ADMIN_BOUNDARY_MIN_ZOOM);
+}
+
+/** A resolved stroke, ready to hand to whatever renderer you are using. */
+export interface ResolvedBoundaryStyle {
+  color: string;
+  width: number;
+  opacity: number;
+  visible: boolean;
+}
+
+/**
+ * The whole style for one zoom level, in renderer-neutral terms.
+ *
+ * ```js
+ * const { color, width, visible } = osmAdminBoundaryStyle(map.getZoom());
+ * ```
+ */
+export function osmAdminBoundaryStyle(
+  zoom: number,
+  options: OsmAdminBoundaryStyleOptions = {},
+): ResolvedBoundaryStyle {
+  return {
+    color: osmAdminBoundaryColor(zoom, options),
+    width: osmAdminBoundaryWidth(zoom),
+    opacity: options.opacity ?? OSM_ADMIN_BOUNDARY_OPACITY,
+    visible: isOsmAdminBoundaryVisible(zoom, options),
+  };
+}
+
+/**
+ * carto's width table as a MapLibre / Mapbox style expression, for
+ * `paint: { "line-width": … }`.
+ *
+ * `interpolate` rather than `step` on purpose: carto's table is per-integer-zoom
+ * because raster tiles only exist at integer zooms, but a vector map renders the
+ * fractional zooms in between, and stepping through them makes the line visibly
+ * jump. Interpolating hits carto's exact widths at every integer zoom and behaves
+ * sanely between them.
+ */
+export function osmAdminBoundaryWidthExpression(): unknown[] {
+  const stops = Object.keys(OSM_ADMIN_BOUNDARY_WIDTH)
+    .map(Number)
+    .sort((a, b) => a - b)
+    .flatMap((z) => [z, OSM_ADMIN_BOUNDARY_WIDTH[z]]);
+  return ["interpolate", ["linear"], ["zoom"], ...stops];
+}