@india-boundary-corrector/layer-configs 0.0.1

package/src/index.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Line style definition for drawing boundary lines
+ */
+export interface LineStyle {
+  /** Line color (CSS color string) */
+  color: string;
+  /** Width as fraction of base line width (default: 1.0) */
+  widthFraction?: number;
+  /** Dash pattern array (omit for solid line) */
+  dashArray?: number[];
+  /** Opacity/alpha value from 0 (transparent) to 1 (opaque) (default: 1.0) */
+  alpha?: number;
+  /** Minimum zoom level for this style (default: layerConfig.startZoom) */
+  startZoom?: number;
+  /** Maximum zoom level for this style (default: Infinity) */
+  endZoom?: number;
+}
+
+/**
+ * Configuration options for LayerConfig
+ */
+export interface LayerConfigOptions {
+  /** Unique identifier for this config */
+  id: string;
+  /** Minimum zoom to start rendering (default: 0) */
+  startZoom?: number;
+  /** Zoom level to switch from NE to OSM data (default: 5) */
+  zoomThreshold?: number;
+  /** Tile URL templates for matching (e.g., "https://{s}.tile.example.com/{z}/{x}/{y}.png") */
+  tileUrlTemplates?: string | string[];
+  /** Line width stops: map of zoom level to line width (at least 2 entries) */
+  lineWidthStops?: Record<number, number>;
+  /** Line styles array - lines are drawn in order */
+  lineStyles?: LineStyle[];
+  /** Factor to multiply line width for deletion blur (default: 1.5) */
+  delWidthFactor?: number;
+}
+
+/**
+ * Layer configuration class for boundary corrections
+ */
+export class LayerConfig {
+  readonly id: string;
+  readonly startZoom: number;
+  readonly zoomThreshold: number;
+  readonly tileUrlTemplates: string[];
+  readonly lineWidthStops: Record<number, number>;
+  readonly lineStyles: LineStyle[];
+  readonly delWidthFactor: number;
+
+  constructor(options: LayerConfigOptions);
+
+  /**
+   * Get line styles active at a given zoom level
+   * @param z - Zoom level
+   */
+  getLineStylesForZoom(z: number): LineStyle[];
+
+  /**
+   * Check if this config matches the given template URLs (with {z}/{x}/{y} placeholders)
+   * @param templates - Single template URL or array of template URLs
+   */
+  matchTemplate(templates: string | string[]): boolean;
+
+  /**
+   * Check if this config matches the given tile URLs (with actual coordinates)
+   * @param tiles - Single tile URL or array of tile URLs
+   */
+  matchTileUrl(tiles: string | string[]): boolean;
+
+  /**
+   * Extract tile coordinates (z, x, y) from a URL using this config's templates
+   * @param url - Tile URL to extract coordinates from
+   * @returns Tile coordinates or null if not found
+   */
+  extractCoords(url: string): TileCoords | null;
+
+  /**
+   * Serialize the config to a plain object for postMessage
+   */
+  toJSON(): LayerConfigOptions;
+
+  /**
+   * Create a LayerConfig from a plain object (e.g., from postMessage)
+   */
+  static fromJSON(obj: LayerConfigOptions): LayerConfig;
+}
+
+/**
+ * Registry for layer configurations
+ */
+export class LayerConfigRegistry {
+  constructor();
+
+  /**
+   * Get a layer config by id
+   */
+  get(id: string): LayerConfig | undefined;
+
+  /**
+   * Register a new layer config
+   */
+  register(config: LayerConfig): void;
+
+  /**
+   * Remove a layer config by id
+   */
+  remove(id: string): boolean;
+
+  /**
+   * Detect layer config from tile URL templates (with {z}/{x}/{y} placeholders)
+   * @param templates - Single template URL or array of template URLs
+   */
+  detectFromTemplates(templates: string | string[]): LayerConfig | undefined;
+
+  /**
+   * Detect layer config from actual tile URLs (with numeric coordinates)
+   * @param urls - Single tile URL or array of tile URLs
+   */
+  detectFromTileUrls(urls: string | string[]): LayerConfig | undefined;
+
+  /**
+   * Get all available layer config ids
+   */
+  getAvailableIds(): string[];
+
+  /**
+   * Create a new registry with all configs from this registry plus extra configs.
+   * @param extraLayerConfigs - Additional configs to add
+   */
+  createMergedRegistry(extraLayerConfigs?: LayerConfig[]): LayerConfigRegistry;
+
+  /**
+   * Parse a tile URL into its components: layer config and coordinates
+   * @param url - Tile URL to parse
+   * @returns Parsed tile URL result or null if not matched
+   */
+  parseTileUrl(url: string): ParsedTileUrl | null;
+}
+
+/** Default registry with built-in configs */
+export const layerConfigs: LayerConfigRegistry;
+
+/**
+ * Tile coordinates
+ */
+export interface TileCoords {
+  z: number;
+  x: number;
+  y: number;
+}
+
+/**
+ * Parsed tile URL result
+ */
+export interface ParsedTileUrl {
+  layerConfig: LayerConfig;
+  coords: TileCoords;
+}

package/src/index.js

@@ -0,0 +1,120 @@
+import configsJson from './configs.json' with { type: 'json' };
+import { LayerConfig } from './layerconfig.js';
+
+export { LayerConfig } from './layerconfig.js';
+
+/**
+ * Layer configuration registry
+ */
+export class LayerConfigRegistry {
+  constructor() {
+    this.registry = {};
+  }
+
+  /**
+   * Get a layer config by id
+   */
+  get(id) {
+    return this.registry[id];
+  }
+
+  /**
+   * Register a new layer config
+   */
+  register(config) {
+    this.registry[config.id] = config;
+  }
+
+  /**
+   * Remove a layer config by id
+   */
+  remove(id) {
+    if (!this.registry[id]) return false;
+    delete this.registry[id];
+    return true;
+  }
+
+  /**
+   * Detect layer config from tile URL templates (with {z}/{x}/{y} placeholders)
+   * @param {string | string[]} templates - Single template URL or array of template URLs
+   */
+  detectFromTemplates(templates) {
+    if (!templates || (Array.isArray(templates) && templates.length === 0)) return undefined;
+    
+    for (const config of Object.values(this.registry)) {
+      if (config.matchTemplate(templates)) {
+        return config;
+      }
+    }
+    
+    return undefined;
+  }
+
+  /**
+   * Detect layer config from actual tile URLs (with numeric coordinates)
+   * @param {string | string[]} urls - Single tile URL or array of tile URLs
+   */
+  detectFromTileUrls(urls) {
+    if (!urls || (Array.isArray(urls) && urls.length === 0)) return undefined;
+    
+    for (const config of Object.values(this.registry)) {
+      if (config.matchTileUrl(urls)) {
+        return config;
+      }
+    }
+    
+    return undefined;
+  }
+
+  /**
+   * Get all available layer config ids
+   */
+  getAvailableIds() {
+    return Object.keys(this.registry);
+  }
+
+  /**
+   * Create a new registry with all configs from this registry plus extra configs.
+   * @param {LayerConfig[]} extraLayerConfigs - Additional configs to add
+   * @returns {LayerConfigRegistry} A new registry with merged configs
+   */
+  createMergedRegistry(extraLayerConfigs) {
+    const registry = new LayerConfigRegistry();
+    
+    for (const id of this.getAvailableIds()) {
+      registry.register(this.get(id));
+    }
+    
+    if (extraLayerConfigs && extraLayerConfigs.length > 0) {
+      for (const config of extraLayerConfigs) {
+        registry.register(config);
+      }
+    }
+    
+    return registry;
+  }
+
+  /**
+   * Parse a tile URL into its components: layer config and coordinates
+   * @param {string} url - Tile URL to parse
+   * @returns {{ layerConfig: LayerConfig, coords: { z: number, x: number, y: number } } | null}
+   */
+  parseTileUrl(url) {
+    // Check if URL matches any layer config
+    const layerConfig = this.detectFromTileUrls([url]);
+    if (!layerConfig) return null;
+    
+    // Extract tile coordinates using the matched config
+    const coords = layerConfig.extractCoords(url);
+    if (!coords) return null;
+    
+    return { layerConfig, coords };
+  }
+}
+
+// Default registry with built-in configs loaded from JSON
+export const layerConfigs = new LayerConfigRegistry();
+for (const configData of configsJson) {
+  layerConfigs.register(new LayerConfig(configData));
+}
+

package/src/layerconfig.js

@@ -0,0 +1,269 @@
+/**
+ * Convert a tile URL template to a regex pattern and capture group names.
+ * Supports {z}, {x}, {y}, {s} (Leaflet subdomain), {a-c}/{1-4} (OpenLayers subdomain), and {r} (retina) placeholders.
+ * @param {string} template - URL template like "https://{s}.tile.example.com/{z}/{x}/{y}.png"
+ * @returns {{ pattern: RegExp, groups: string[] }}
+ */
+function templateToRegex(template) {
+  const groups = [];
+  // Escape regex special chars, then replace placeholders
+  let pattern = template
+    .replace(/[.*+?^${}()|[\]\\]/g, (char) => {
+      // Don't escape our placeholders
+      if (char === '{' || char === '}') return char;
+      return '\\' + char;
+    })
+    // Make protocol flexible (http/https)
+    .replace(/^https:\/\//, 'https?://')
+    .replace(/^http:\/\//, 'https?://')
+    // Handle {a-c} or {1-4} etc (OpenLayers style subdomain)
+    .replace(/\{[a-z0-9]-[a-z0-9]\}/gi, () => {
+      groups.push('s');
+      return '([a-z0-9]+)';
+    })
+    .replace(/\{(z|x|y|s|r)\}/gi, (_, name) => {
+      const lowerName = name.toLowerCase();
+      groups.push(lowerName);
+      if (lowerName === 's') {
+        // Subdomain: single letter or short string
+        return '([a-z0-9]+)';
+      }
+      if (lowerName === 'r') {
+        // Retina suffix: optional @2x or similar
+        return '(@\\d+x)?';
+      }
+      // z, x, y: numeric
+      return '(\\d+)';
+    });
+  
+  // Allow optional query string at end
+  return { pattern: new RegExp('^' + pattern + '(\\?.*)?$', 'i'), groups };
+}
+
+/**
+ * Convert a tile URL template to a regex that matches the template itself.
+ * @param {string} template - URL template like "https://{s}.tile.example.com/{z}/{x}/{y}.png"
+ * @returns {RegExp}
+ */
+function templateToTemplateRegex(template) {
+  // Escape regex special chars, then replace placeholders with literal match
+  let pattern = template
+    .replace(/[.*+?^${}()|[\]\\]/g, (char) => {
+      if (char === '{' || char === '}') return char;
+      return '\\' + char;
+    })
+    // Make protocol flexible (http/https)
+    .replace(/^https:\/\//, 'https?://')
+    .replace(/^http:\/\//, 'https?://')
+    // Handle {a-c} or {1-4} (OpenLayers style subdomain)
+    .replace(/\{([a-z0-9])-([a-z0-9])\}/gi, (_, start, end) => `(\\{${start}-${end}\\}|[a-z0-9]+)`)
+    .replace(/\{(z|x|y|s|r)\}/gi, (_, name) => {
+      const lowerName = name.toLowerCase();
+      if (lowerName === 's') {
+        // Match {s} placeholder or actual subdomain
+        return '(\\{s\\}|[a-z0-9]+)';
+      }
+      if (lowerName === 'r') {
+        // Match {r} placeholder or actual retina or empty
+        return '(\\{r\\}|@\\d+x)?';
+      }
+      // Match {z}, {x}, {y} placeholders
+      return `\\{${lowerName}\\}`;
+    });
+  
+  // Allow optional query string at end
+  return new RegExp('^' + pattern + '(\\?.*)?$', 'i');
+}
+
+/**
+ * Base class for layer configurations
+ * 
+ * Supports separate styling for NE (Natural Earth) data at low zoom levels
+ * and OSM data at higher zoom levels, split by zoomThreshold.
+ */
+export class LayerConfig {
+  constructor({
+    id,
+    startZoom = 0,
+    zoomThreshold = 5,
+    // Tile URL templates for matching (e.g., "https://{s}.tile.example.com/{z}/{x}/{y}.png")
+    tileUrlTemplates = [],
+    // Line width stops: map of zoom level to line width (at least 2 entries)
+    lineWidthStops = { 1: 0.5, 10: 2.5 },
+    // Line styles array - each element describes a line to draw
+    // { color: string, widthFraction?: number, dashArray?: number[], startZoom?: number, endZoom?: number }
+    // Lines are drawn in array order. startZoom defaults to layerConfig startZoom, endZoom defaults to Infinity
+    lineStyles = [{ color: 'green', widthFraction: 1.0 }],
+    // Factor to multiply line width for deletion blur (default 1.5)
+    // Higher values leave gaps where wiped lines meet existing lines
+    // Lower values mean wiped lines show through
+    delWidthFactor = 1.5,
+    // Factor to extend add lines by (multiplied by deletion line width)
+    // Helps cover gaps where deleted lines meet the new boundary
+    // Set to 0 to disable extension
+    lineExtensionFactor = 0.5,
+  }) {
+    if (!id || typeof id !== 'string') {
+      throw new Error('LayerConfig requires a non-empty string id');
+    }
+
+    this.id = id;
+    this.startZoom = startZoom;
+    this.zoomThreshold = zoomThreshold;
+
+    if (startZoom > zoomThreshold) {
+      throw new Error(`LayerConfig "${id}": startZoom (${startZoom}) must be <= zoomThreshold (${zoomThreshold})`);
+    }
+
+    // Normalize to array
+    const templates = Array.isArray(tileUrlTemplates) ? tileUrlTemplates : 
+                      (tileUrlTemplates ? [tileUrlTemplates] : []);
+    this.tileUrlTemplates = templates;
+    
+    // Pre-compile regex patterns for matching tile URLs (with actual coords)
+    this._compiledPatterns = templates.map(t => templateToRegex(t));
+    
+    // Pre-compile regex patterns for matching template URLs (with {z}/{x}/{y} placeholders)
+    this._templatePatterns = templates.map(t => templateToTemplateRegex(t));
+
+    // Validate lineWidthStops
+    if (!lineWidthStops || typeof lineWidthStops !== 'object' || Array.isArray(lineWidthStops)) {
+      throw new Error(`LayerConfig "${id}": lineWidthStops must be an object`);
+    }
+    const stopKeys = Object.keys(lineWidthStops);
+    if (stopKeys.length < 2) {
+      throw new Error(`LayerConfig "${id}": lineWidthStops must have at least 2 entries`);
+    }
+    for (const key of stopKeys) {
+      const zoom = Number(key);
+      if (!Number.isInteger(zoom) || zoom < 0) {
+        throw new Error(`LayerConfig "${id}": lineWidthStops keys must be non-negative integers, got "${key}"`);
+      }
+      if (typeof lineWidthStops[key] !== 'number' || lineWidthStops[key] <= 0) {
+        throw new Error(`LayerConfig "${id}": lineWidthStops values must be positive numbers`);
+      }
+    }
+    this.lineWidthStops = lineWidthStops;
+
+    // Validate lineStyles
+    if (!Array.isArray(lineStyles) || lineStyles.length === 0) {
+      throw new Error(`LayerConfig "${id}": lineStyles must be a non-empty array`);
+    }
+    for (let i = 0; i < lineStyles.length; i++) {
+      const style = lineStyles[i];
+      if (!style || typeof style !== 'object') {
+        throw new Error(`LayerConfig "${id}": lineStyles[${i}] must be an object`);
+      }
+      if (!style.color || typeof style.color !== 'string') {
+        throw new Error(`LayerConfig "${id}": lineStyles[${i}].color must be a non-empty string`);
+      }
+    }
+    
+    // Line styles - normalize startZoom/endZoom defaults
+    this.lineStyles = lineStyles.map(style => ({
+      ...style,
+      startZoom: style.startZoom ?? startZoom,
+      endZoom: style.endZoom ?? Infinity,
+    }));
+    
+    // Deletion width factor
+    this.delWidthFactor = delWidthFactor;
+    
+    // Line extension factor
+    this.lineExtensionFactor = lineExtensionFactor;
+  }
+
+  /**
+   * Get line styles active at a given zoom level
+   * @param {number} z - Zoom level
+   * @returns {Array<{color: string, widthFraction?: number, dashArray?: number[]}>}
+   */
+  getLineStylesForZoom(z) {
+    return this.lineStyles.filter(style => z >= style.startZoom && z <= style.endZoom);
+  }
+
+  /**
+   * Check if this config matches the given template URLs (with {z}/{x}/{y} placeholders)
+   * @param {string | string[]} templates - Single template URL or array of template URLs
+   * @returns {boolean}
+   */
+  matchTemplate(templates) {
+    if (this._templatePatterns.length === 0) return false;
+    
+    const urls = Array.isArray(templates) ? templates : [templates];
+    if (urls.length === 0) return false;
+    
+    return urls.some(url => 
+      this._templatePatterns.some(pattern => pattern.test(url))
+    );
+  }
+
+  /**
+   * Check if this config matches the given tile URLs (with actual coordinates)
+   * @param {string | string[]} tiles - Single tile URL or array of tile URLs
+   * @returns {boolean}
+   */
+  matchTileUrl(tiles) {
+    if (this._compiledPatterns.length === 0) return false;
+    
+    const urls = Array.isArray(tiles) ? tiles : [tiles];
+    if (urls.length === 0) return false;
+    
+    return urls.some(url => 
+      this._compiledPatterns.some(({ pattern }) => pattern.test(url))
+    );
+  }
+
+  /**
+   * Extract tile coordinates (z, x, y) from a URL using this config's templates
+   * @param {string} url - Tile URL to extract coordinates from
+   * @returns {{ z: number, x: number, y: number } | null}
+   */
+  extractCoords(url) {
+    for (const { pattern, groups } of this._compiledPatterns) {
+      const match = url.match(pattern);
+      if (match) {
+        const result = {};
+        for (let i = 0; i < groups.length; i++) {
+          const name = groups[i];
+          const value = match[i + 1];
+          if (name === 'z' || name === 'x' || name === 'y') {
+            result[name] = parseInt(value, 10);
+          }
+        }
+        if ('z' in result && 'x' in result && 'y' in result) {
+          return { z: result.z, x: result.x, y: result.y };
+        }
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Serialize the config to a plain object for postMessage
+   * @returns {Object}
+   */
+  toJSON() {
+    return {
+      id: this.id,
+      startZoom: this.startZoom,
+      zoomThreshold: this.zoomThreshold,
+      tileUrlTemplates: this.tileUrlTemplates,
+      lineWidthStops: this.lineWidthStops,
+      lineStyles: this.lineStyles,
+      delWidthFactor: this.delWidthFactor,
+      lineExtensionFactor: this.lineExtensionFactor,
+    };
+  }
+
+  /**
+   * Create a LayerConfig from a plain object (e.g., from postMessage)
+   * @param {Object} obj
+   * @returns {LayerConfig}
+   */
+  static fromJSON(obj) {
+    return new LayerConfig(obj);
+  }
+}
+
+export default LayerConfig;