@caoguo/maplibre 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,459 @@
+import { StyleSpecification, Map as Map$1 } from 'maplibre-gl';
+export { default as maplibregl } from 'maplibre-gl';
+export { WUHAN_CENTER, WUHAN_ZOOM, osmRasterStyle } from './styles.js';
+import { TiandituType, TiandituOptions } from './sources/index.js';
+export { AddTiandituOptions, MissingTokenError, TiandituLayer, TiandituSourceSpec, addTiandituBaseMap, buildTiandituSources, tiandituStyle, tiandituTileUrls } from './sources/index.js';
+import { TileStoreBackend, packGeoJSONToStore } from './offline/index.js';
+export { AirgapMessage, CACHEABLE_HOSTS, CACHE_NAME, IdbTileStore, MSG_AIRGAP, MemoryTileStore, OFFLINE_PROTOCOL, OfflineProtocolContext, PackGeoJSONOptions, ResolveResponseDeps, ResolvedResponse, SW_TEMPLATE_HINT, StoredTile, TileFormat, createDefaultStore, createFetchHandler, createOfflineLoader, installServiceWorker, offlineGeoJSONSource, offlineSourceTiles, offlineTileUrl, parseOfflineUrl, registerOfflineProtocol, registerOfflineServiceWorker, resolveCacheKey, resolveFromStore, resolveResponse, setAirgap, shouldCache, tileKey } from './offline/index.js';
+import { ThemeName } from '@caoguo/theme';
+
+/**
+ * 坐标系类型与变换接口（F-1.1）。
+ *
+ * 草果地图内部统一以 WGS84（EPSG:4326）为渲染基准。
+ * 业务数据可能为 GCJ-02（火星坐标）或 CGCS2000（国家2000），
+ * 通过 `createTransformer` 以 WGS84 为枢纽做相互转换。
+ */
+type CRS = 'WGS84' | 'GCJ02' | 'CGCS2000';
+type LngLat = [number, number];
+/** 一个坐标对（经/纬），与 MapLibre [lng, lat] 顺序一致 */
+type Point = LngLat;
+/** 地理范围 [west, south, east, north] */
+type Bounds = [number, number, number, number];
+interface Transformer {
+    /** 正向变换：from -> to */
+    forward(lng: number, lat: number): LngLat;
+    /** 逆向变换：to -> from（数学逆） */
+    inverse(lng: number, lat: number): LngLat;
+}
+/**
+ * CGCS2000 高精度偏移提供方（可选）。
+ * Phase 0 默认不接入官方格网，使用等价实现（误差 < 0.5m）。
+ * 测绘级场景可注入区域 7 参数 / 格网平移表。
+ */
+interface GridShiftProvider {
+    /** 返回相对 WGS84 的 [dLng, dLat] 偏移（单位：度） */
+    shift(lng: number, lat: number): LngLat;
+}
+
+/**
+ * WGS84 <-> GCJ-02（火星坐标系）转换。
+ *
+ * 算法：公开的解析偏移模型（Krasovsky 椭球），与 coordtransform 一致。
+ * 全国范围单点误差 < 50m（PRD 验收 F-1.1）。
+ * 注意：GCJ-02 -> WGS84 采用 3 次迭代反算，进一步收敛残差。
+ */
+/** WGS84 -> GCJ-02 */
+declare function wgs84ToGcj02(lng: number, lat: number): [number, number];
+/** GCJ-02 -> WGS84（3 次迭代反算） */
+declare function gcj02ToWgs84(lng: number, lat: number): [number, number];
+/** 是否在 GCJ-02 偏移覆盖区（中国境内外判定） */
+declare function isInChina(lng: number, lat: number): boolean;
+
+/**
+ * WGS84 <-> CGCS2000 转换。
+ *
+ * 说明：CGCS2000 与 WGS84 采用近似相同的参考椭球（扁率/长半轴差异极小，
+ * 历元差异仅导致 cm~dm 级点位偏移），在 Web Mercator 显示尺度下等价于一致。
+ * 因此 Phase 0 默认实现为恒等变换（残差 < 0.5m，满足 PRD 验收 F-1.1）。
+ *
+ * 测绘级高精度需求：可注入 `GridShiftProvider`（区域 7 参数 / 格网平移），
+ * 见 types.ts。本文件保留可扩展入口。
+ */
+
+/** 注册 CGCS2000 偏移提供方（可选，测绘级） */
+declare function setCgcs2000GridShift(provider: GridShiftProvider | null): void;
+/** WGS84 -> CGCS2000 */
+declare function wgs84ToCgcs2000(lng: number, lat: number): LngLat;
+/** CGCS2000 -> WGS84 */
+declare function cgcs2000ToWgs84(lng: number, lat: number): LngLat;
+
+/**
+ * 坐标系变换组合器（以 WGS84 为枢纽）。
+ *
+ * 用法：
+ *   const t = createTransformer('GCJ02', 'WGS84');
+ *   const [lng, lat] = t.forward(114.30, 30.59); // GCJ-02 业务数据 -> 渲染基准
+ */
+
+/** 把任意 CRS 的坐标转换到 WGS84 */
+declare function toWgs84(crs: CRS, lng: number, lat: number): LngLat;
+/** 把 WGS84 坐标转换到目标 CRS */
+declare function fromWgs84(crs: CRS, lng: number, lat: number): LngLat;
+declare function createTransformer(from: CRS, to: CRS): Transformer;
+/** 单点快捷转换 */
+declare function transformPoint(lng: number, lat: number, from: CRS, to: CRS): LngLat;
+/** 范围 [w, s, e, n] 转换（取四个角点极值） */
+declare function transformBounds(b: Bounds, from: CRS, to: CRS): Bounds;
+
+interface ScaleBar {
+    /** 比例尺条代表的真实距离（米） */
+    meters: number;
+    /** 比例尺条在屏幕上的像素宽度 */
+    pixels: number;
+    /** 展示文案，如 "500 m" / "2 km" */
+    label: string;
+}
+/**
+ * 计算比例尺。
+ * @param latitude 当前视图中心纬度（度）
+ * @param zoom     MapLibre zoom（Web Mercator）
+ * @param dpiScale 设备像素比（默认 1；Retina 设为 window.devicePixelRatio）
+ * @param maxWidth 比例尺条最大像素宽度（默认 100）
+ * @param tileSize 瓦片像素尺寸（默认 512，MapLibre v4 默认）
+ */
+declare function computeScaleBar(latitude: number, zoom: number, opts?: {
+    dpiScale?: number;
+    maxWidth?: number;
+    tileSize?: number;
+}): ScaleBar;
+interface ScaleControlOptions {
+    /** 挂载容器（可选；不传则在地图容器内自动创建） */
+    container?: HTMLElement;
+    /** 是否显示实时坐标（默认 true） */
+    showCoordinate?: boolean;
+    /** 最大比例尺像素宽度 */
+    maxWidth?: number;
+}
+/**
+ * 比例尺控件。需传入 maplibre Map 实例（直接用 maplibre-gl 的 Map）。
+ */
+declare class ScaleControl {
+    private el;
+    private barEl;
+    private labelEl;
+    private coordEl?;
+    private map;
+    private opts;
+    private onMove;
+    private onZoom;
+    constructor(map: ScaleControl['map'], options?: ScaleControlOptions);
+    /** 把控件挂到地图容器（无预设容器时调用） */
+    addTo(container: HTMLElement): this;
+    /** 计算并刷新显示 */
+    update(): void;
+    private handleMove;
+    /** 移除控件与事件监听 */
+    remove(): void;
+}
+
+/**
+ * 主题切换控件（T8 / F-1.9）。
+ *
+ * 在暗色（caoguo-dark）与亮色（caoguo-light）官方矢量主题间切换，
+ * 调用 `map.setStyle` 并保留当前视图（center/zoom）与现有 GeoJSON 源/图层。
+ *
+ * 设计为「纯函数 core + 薄 DOM 绑定」：
+ * - `toggleTheme` / `themeFromStyle` 为纯逻辑，可独立单测；
+ * - `ThemeSwitcher` 类负责渲染按钮并绑定点击事件。
+ */
+
+interface ThemeSwitcherOptions {
+    /** 挂载容器（可选） */
+    container?: HTMLElement;
+    /** 初始主题 */
+    initial?: ThemeName;
+}
+declare function oppositeTheme(theme: ThemeName): ThemeName;
+/**
+ * 从当前 style 对象推断主题名（依据其 JSON 标识）。
+ * 非草果主题时回退到传入的 fallback。
+ */
+declare function themeFromStyle(style: {
+    name?: string;
+} | string | null | undefined, fallback?: ThemeName): ThemeName;
+declare class ThemeSwitcher {
+    private el;
+    private btn;
+    private current;
+    private map;
+    constructor(map: ThemeSwitcher['map'], options?: ThemeSwitcherOptions);
+    private applyLabel;
+    /** 当前主题 */
+    getTheme(): ThemeName;
+    /** 切换到指定主题（保留视图，diff 模式避免闪烁） */
+    setTheme(theme: ThemeName): void;
+    /** 在明暗之间切换 */
+    toggle(): void;
+    /** 挂到容器 */
+    addTo(container: HTMLElement): this;
+    /** 移除 */
+    remove(): void;
+}
+
+/**
+ * 辉光线几何构建（T6 / F-1.3 纯逻辑部分）。
+ *
+ * 把 GeoJSON LineString 集合转换为「多遍辉光描边」所需的几何描述。
+ * 渲染层（CustomLineLayer）再据此在 WebGL 中绘制：每遍一个宽度档 + 透明度档，
+ * 叠加形成管线/路网/水系的辉光效果。
+ *
+ * 设计：本模块**不依赖 WebGL / maplibre**，纯函数可在 Node 单测。
+ * 坐标投影使用简化 Web Mercator（经度→x、纬度→y 的归一化世界坐标），
+ * 真实渲染时由 CustomLayer 的 matrix 变换到屏幕。
+ */
+interface GlowLine {
+    /** 线坐标 [lng, lat][] */
+    coordinates: [number, number][];
+    /** 该线所属分组（如 'pipe' | 'road' | 'water'），用于着色 */
+    group?: string;
+}
+interface GlowPass {
+    /** 相对基础宽度的倍数（核心线=1，外晕逐遍增大） */
+    widthScale: number;
+    /** 该遍不透明度（核心线高、外晕低） */
+    opacity: number;
+}
+interface GlowGeometry {
+    /** 所有线（含分组标记）的归一化坐标序列 */
+    lines: {
+        points: [number, number][];
+        group?: string;
+    }[];
+    /** 辉光多遍参数（从外晕到核心，或反之，由渲染层决定） */
+    passes: GlowPass[];
+    /** 总顶点数（用于缓冲分配） */
+    vertexCount: number;
+}
+/**
+ * 生成辉光多遍档位。
+ * @param passes 遍数（默认 4：3 层外晕 + 1 核心）
+ * @param coreOpacity 核心线不透明度
+ */
+declare function glowPasses(passes?: number, coreOpacity?: number): GlowPass[];
+/**
+ * 简化 Web Mercator 归一化（经度→x∈[-1,1]，纬度→y∈[-1,1]）。
+ * 仅用于几何构建与单测，真实投影在渲染层用 map 的 matrix。
+ */
+declare function projectSimple(lng: number, lat: number): [number, number];
+/**
+ * 构建辉光几何：投影每条线并统计顶点。
+ * 顶点数 = 各线（点数-1）*2（线段两端），用于 Line 绘制。
+ */
+declare function buildGlowGeometry(lines: GlowLine[], opts?: {
+    passes?: number;
+    coreOpacity?: number;
+}): GlowGeometry;
+
+/**
+ * 辉光管线 Custom Layer（T6 / F-1.3 WebGL 渲染层）。
+ *
+ * 实现 MapLibre v4 `CustomLayerInterface`：在地图之上叠加绘制 GeoJSON 线，
+ * 用多遍（glowPasses）描边形成管线/路网/水系的辉光效果。
+ *
+ * 设计：几何构建（投影/档位）在 `./glowGeometry` 纯函数中完成（可单测）；
+ * 本文件仅负责 WebGL 状态机与绘制，仅在浏览器执行。
+ * 通过 `Map.addGlowLayer` 注入，调用方无需感知 WebGL 细节。
+ *
+ * 依赖 MapLibre 注入的 `matrix`（map 的 projectionMatrix * modelViewMatrix），
+ * 与官方 CustomLayer 示例一致。
+ */
+
+/** MapLibre v4 CustomLayerInterface 最小子集（避免强类型耦合） */
+interface CustomLayerInterface {
+    id: string;
+    type: 'custom';
+    renderingMode?: '2d' | '3d';
+    onAdd?(map: unknown, gl: WebGLRenderingContext): void;
+    render(gl: WebGLRenderingContext, matrix: number[]): void;
+    onRemove?(map: unknown, gl: WebGLRenderingContext): void;
+    prerender?(gl: WebGLRenderingContext, matrix: number[]): void;
+}
+interface GlowLayerOptions {
+    /** 图层 id */
+    id?: string;
+    /** 线分组颜色映射（group -> [r,g,b] 0..1） */
+    colors?: Record<string, [number, number, number]>;
+    /** 基础线宽（像素，核心线） */
+    baseWidth?: number;
+    /** 辉光遍数 */
+    passes?: number;
+    /** 线集合 */
+    lines: GlowLine[];
+}
+declare class CustomLineLayer implements CustomLayerInterface {
+    id: string;
+    type: "custom";
+    renderingMode: '2d';
+    private lines;
+    private colors;
+    private baseWidth;
+    private passes;
+    private program?;
+    private buffer?;
+    private geometry;
+    private map?;
+    constructor(opts: GlowLayerOptions);
+    onAdd(map: unknown, gl: WebGLRenderingContext): void;
+    render(gl: WebGLRenderingContext, matrix: number[]): void;
+    onRemove(_map: unknown, gl: WebGLRenderingContext): void;
+}
+
+/**
+ * LOD 控制器（T7 / F-1.7，纯逻辑）。
+ *
+ * 按地图 zoom 自动切换数据密度（Level of Detail）：
+ * - 低 zoom（全国/省）显示聚合/简化数据，避免要素过密；
+ * - 高 zoom（市/区）显示全量/精细数据。
+ *
+ * 设计：本模块**不依赖 maplibre / WebGL / DOM**，纯函数可在 Node 单测。
+ * 控制器 `LodController` 监听 zoom 变化并回调当前应激活的 LOD 等级，
+ * 调用方据此 `setData` / 切换 source（具体渲染动作由调用方决定）。
+ */
+interface LodLevel<T = unknown> {
+    /** 该等级名称（如 'country' | 'province' | 'city' | 'detail'） */
+    id: string;
+    /** 进入该等级的最小 zoom（含） */
+    minZoom: number;
+    /** 进入该等级的最大 zoom（含）；省略表示 +∞ */
+    maxZoom?: number;
+    /** 该等级承载的数据/配置（任意类型，调用方解释） */
+    payload?: T;
+}
+interface LodChangeEvent<T> {
+    /** 当前激活等级 */
+    level: LodLevel<T>;
+    /** 是否相较上一次发生了等级切换 */
+    changed: boolean;
+    /** 当前 zoom */
+    zoom: number;
+}
+/**
+ * 根据 zoom 解析应激活的 LOD 等级。
+ * 规则：取满足 minZoom<=zoom<=(maxZoom??∞) 的等级；
+ * 若存在多个命中（区间重叠），取 minZoom 最大者（更精细优先）。
+ * 无命中返回 null（调用方可保留上一等级）。
+ */
+declare function resolveLod<T>(zoom: number, levels: LodLevel<T>[]): LodLevel<T> | null;
+/**
+ * 给定可视范围的"要素密度"建议（用于调试/UI 提示）。
+ * 返回每屏建议最大要素数（随 zoom 平方增长，模拟瓦片面积）。
+ */
+declare function suggestDensity(zoom: number, basePerTile?: number, tileCountFactor?: number): number;
+/**
+ * LOD 控制器（薄状态机）。监听 zoom，触发 onLod 回调。
+ */
+declare class LodController<T = unknown> {
+    private levels;
+    private current;
+    private onChange;
+    private map;
+    constructor(map: LodController['map'], levels: LodLevel<T>[], onChange: (e: LodChangeEvent<T>) => void);
+    private handler;
+    /** 立即评估当前 zoom 并（按需）触发回调 */
+    evaluate(force?: boolean): LodLevel<T> | null;
+    /** 当前等级 */
+    getLevel(): LodLevel<T> | null;
+    /** 更新分级配置（如权限/数据就绪后） */
+    setLevels(levels: LodLevel<T>[]): void;
+    /** 卸载监听 */
+    remove(): void;
+}
+
+type MapInstance = Map$1;
+
+interface MapOptions {
+    container: string | HTMLElement;
+    center?: [number, number];
+    zoom?: number;
+    style?: string | StyleSpecification;
+    pitch?: number;
+    bearing?: number;
+    /**
+     * 业务/叠加数据的坐标系（默认 WGS84）。
+     * 引擎内部以 WGS84 渲染；若数据为 GCJ-02 / CGCS2000，
+     * 设定后可通过 `transformToMap` 在入图前自动纠偏。
+     */
+    dataCRS?: CRS;
+}
+/**
+ * 草果地图引擎封装（展示层骨架）。
+ *
+ * 当前为轻量包装：直接复用 maplibre-gl 能力。
+ * 后续阶段将在此注入：GCJ-02/BD-09 坐标系插件、行业 Shader、离线瓦片加载，
+ * 业务调用方无需改动（通过本类统一入口）。
+ */
+declare class Map {
+    private _map;
+    private _dataCRS;
+    constructor(options: MapOptions);
+    /**
+     * 把业务坐标系坐标转换到地图渲染基准（WGS84）。
+     * 用于叠加 GCJ-02 / CGCS2000 数据前的纠偏。
+     */
+    transformToMap(lng: number, lat: number): LngLat;
+    /** 设定叠加数据坐标系 */
+    setDataCRS(crs: CRS): void;
+    /** 读取叠加数据坐标系 */
+    getDataCRS(): CRS;
+    /** 生成当前 dataCRS -> WGS84 的变换器（供批量转换使用） */
+    getTransformer(): Transformer;
+    /**
+     * 切换为底图为天地图（国内权威底图，CGCS2000 / Web Mercator）。
+     * token 必须由调用方注入，缺失时抛出 MissingTokenError。
+     */
+    useTianditu(type: TiandituType, opts: Omit<TiandituOptions, 'type'>): void;
+    /** 向当前地图注入天地图底图（叠加在现有 style 之上） */
+    addTianditu(opts: Omit<TiandituOptions, 'type'> & {
+        type?: TiandituType;
+    }): void;
+    /** 离线瓦片后端（默认浏览器 IndexedDB / Node 内存） */
+    private _store;
+    /** 注册离线协议并启用离线瓦片读取（F-1.4） */
+    enableOffline(store?: TileStoreBackend): void;
+    /** 当前离线存储实例 */
+    getOfflineStore(): TileStoreBackend;
+    /** 构造离线源 tiles（供 source.tiles 使用） */
+    offlineTiles(sourceId: string): string[];
+    /** 把 GeoJSON 打包进离线存储（分桶到瓦片网格） */
+    packGeoJSON(sourceId: string, geojson: Parameters<typeof packGeoJSONToStore>[1]['geojson'], opts?: {
+        maxZoom?: number;
+        expires?: number;
+    }): Promise<number>;
+    addLayer(layer: Record<string, unknown>): void;
+    removeLayer(id: string): void;
+    on(event: string, layerId?: string, cb?: (e: unknown) => void): void;
+    addSource(id: string, source: object): void;
+    getSource(id: string): unknown;
+    flyTo(opts: {
+        center?: [number, number];
+        zoom?: number;
+        pitch?: number;
+        bearing?: number;
+    }): void;
+    remove(): void;
+    /**
+     * 挂载比例尺 + 实时坐标控件（T8 / F-1.8）。
+     * 返回控件实例，可调用 .remove() 卸载。
+     */
+    addScaleControl(options?: {
+        showCoordinate?: boolean;
+        maxWidth?: number;
+    }): ScaleControl;
+    /**
+     * 挂载主题切换控件（T8 / F-1.9），在 caoguo-dark / caoguo-light 间切换。
+     * 返回控件实例，可调用 .toggle() / .setTheme() / .remove()。
+     */
+    addThemeSwitcher(initial?: ThemeName): ThemeSwitcher;
+    /**
+     * 挂载辉光管线 Custom Layer（T6 / F-1.3）。
+     * 传入 GeoJSON 线集合，叠加渲染管线/路网/水系辉光效果。
+     * @returns 图层 id（可用于 removeLayer）
+     */
+    addGlowLayer(opts: {
+        id?: string;
+        lines: GlowLine[];
+        colors?: Record<string, [number, number, number]>;
+        baseWidth?: number;
+        passes?: number;
+    }): string;
+    /**
+     * 挂载 LOD 控制器（T7 / F-1.7）。
+     * 随 zoom 切换数据密度等级，并在等级变化时回调（调用方据此 setData / 切源）。
+     * @returns LodController 实例（可 .getLevel() / .remove()）
+     */
+    addLodController<T = unknown>(levels: LodLevel<T>[], onLod: (e: LodChangeEvent<T>) => void): LodController<T>;
+    get instance(): Map$1;
+}
+
+export { type Bounds, type CRS, type CustomLayerInterface, CustomLineLayer, type GlowGeometry, type GlowLayerOptions, type GlowLine, type GlowPass, type GridShiftProvider, type LngLat, type LodChangeEvent, LodController, type LodLevel, Map, type MapInstance, type MapOptions, type Point, type ScaleBar, ScaleControl, type ScaleControlOptions, ThemeSwitcher, type ThemeSwitcherOptions, TiandituOptions, TiandituType, TileStoreBackend, type Transformer, buildGlowGeometry, cgcs2000ToWgs84, computeScaleBar, createTransformer, Map as default, fromWgs84, gcj02ToWgs84, glowPasses, isInChina, oppositeTheme, packGeoJSONToStore, projectSimple, resolveLod, setCgcs2000GridShift, suggestDensity, themeFromStyle, toWgs84, transformBounds, transformPoint, wgs84ToCgcs2000, wgs84ToGcj02 };