@antv/l7-mapkit 0.1.0

package/README.md

@@ -0,0 +1,165 @@
+# @antv/l7-mapkit
+
+> React components for AntV L7 geospatial visualization library. Built on React 18+ and @antv/l7 2.25+.
+
+## Features
+
+- **🎯 Flat Props API** - Direct props like `colorField`, `sizeValues`, `shape` instead of nested objects
+- **⚡ Event Handling** - Events directly attached to components (`onClick`, `onMouseEnter`) without separate event components
+- **🧩 Composable** - Component composition pattern inspired by mapcn design philosophy
+- **📦 TypeScript First** - Complete type definitions with JSDoc documentation
+- **🤖 LLM Friendly** - Includes `llms.txt` and comprehensive API docs for AI assistants
+- **🗺️ Multiple Maps** - Supports GaodeMap (高德) and built-in Map (no third-party dependency)
+
+## Installation
+
+```bash
+npm install @antv/l7-mapkit @antv/l7 @antv/l7-maps
+```
+
+## Quick Start
+
+```tsx
+import { GaodeMapScene, PointLayer } from '@antv/l7-mapkit';
+
+const data = {
+  type: 'FeatureCollection',
+  features: [
+    { type: 'Feature', geometry: { type: 'Point', coordinates: [120.19, 30.26] }, properties: { value: 80 } },
+    { type: 'Feature', geometry: { type: 'Point', coordinates: [121.47, 31.23] }, properties: { value: 120 } },
+  ],
+};
+
+function App() {
+  return (
+    <GaodeMapScene
+      style={{ width: '100%', height: '400px' }}
+      mapConfig={{ zoom: 7, center: [120.5, 30.8] }}
+    >
+      <PointLayer
+        source={data}
+        colorField="value"
+        colorValues={['#fee5d9', '#fc4e2a', '#800026']}
+        size={8}
+        shape="circle"
+        onClick={(e) => console.log(e.feature.properties)}
+      />
+    </GaodeMapScene>
+  );
+}
+```
+
+## Components
+
+### Scene Components
+
+- **`<GaodeMapScene>`** - Gaode Map container component
+- **`<MapScene>`** - Built-in map container (no third-party dependency)
+
+### Layer Components
+
+All layer components share the same flat props interface:
+
+- **`<PointLayer>`** - Point/scatter layer
+- **`<LineLayer>`** - Line/path layer (supports arc, greatcircle shapes)
+- **`<PolygonLayer>`** - Polygon/area layer
+- **`<HeatmapLayer>`** - Heatmap layer (2D/3D/hexagon/grid)
+- **`<RasterLayer>`** - Raster/tile layer
+- **`<ImageLayer>`** - Image overlay layer
+- **`<CityBuildingLayer>`** - 3D building layer
+
+### Interactive Components
+
+- **`<Marker>`** - Map marker with custom React content
+- **`<MarkerLayer>`** - Batch markers with clustering support
+- **`<Popup>`** - Map popup with custom React content
+- **`<Control>`** - Built-in controls (zoom/scale/logo/layerSwitch/etc.)
+- **`<CustomControl>`** - Custom control with any React content
+- **`<LoadImage>` / `<LoadImages>`** - Load image resources
+
+### Hooks
+
+- **`useScene()`** - Get current Scene instance (must be used inside Scene components)
+- **`useLayer()`** - Get current Layer instance (must be used inside layer children)
+
+## Layer Props Reference
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `source` | any | Data source (GeoJSON/array/URL) **required** |
+| `sourceConfig` | object | Data parser config `{ parser: { type: 'json', x: 'lng', y: 'lat' } }` |
+| `color` | string | Fixed color value |
+| `colorField` | string | Color mapping field name |
+| `colorValues` | string[] \| fn | Color mapping values or callback |
+| `size` | number | Fixed size in pixels |
+| `sizeField` | string | Size mapping field name |
+| `sizeValues` | number[] \| fn | Size mapping range `[min, max]` |
+| `shape` | string | Shape type (circle/triangle/arc/etc.) |
+| `style` | object | Layer style `{ opacity, stroke, strokeWidth }` |
+| `filterField` | string | Filter field name |
+| `filterValues` | any[] \| fn | Filter values or callback |
+| `animate` | object | Animation config `{ enable, speed, trailLength }` |
+| `active` | boolean \| object | Hover highlight |
+| `select` | boolean \| object | Click selection |
+| `onClick` | fn | Click event handler |
+| `onMouseEnter` | fn | Mouse enter handler |
+| `onMouseLeave` | fn | Mouse leave handler |
+| `onLoaded` | fn(layer, scene) | Layer loaded callback |
+
+## Migration from 2.x
+
+L7-MapKit 3.0 is a complete rewrite with breaking changes:
+
+### Before (2.x)
+```tsx
+<PointLayer
+  source={{ data }}
+  color={{ field: 'value', values: ['red', 'blue'] }}
+  size={{ field: 'count', values: [5, 20] }}
+/>
+<LayerEvent type="click" handler={handleClick} />
+```
+
+### After (3.0)
+```tsx
+<PointLayer
+  source={data}
+  colorField="value"
+  colorValues={['red', 'blue']}
+  sizeField="count"
+  sizeValues={[5, 20]}
+  onClick={handleClick}
+/>
+```
+
+Key changes:
+- ✅ Flat props instead of nested objects
+- ✅ Events directly on components (no `LayerEvent`/`SceneEvent`)
+- ✅ All class components converted to function components with hooks
+- ✅ Only GaodeMap and built-in Map supported (Mapbox removed)
+- ✅ React 18+ only (uses `useId`, strict mode safe)
+
+## Documentation
+
+- [Full API Reference](docs/llms-full.md)
+- [LLM-friendly docs](llms.txt)
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Type check
+npm run type-check
+
+# Build
+npm run build
+
+# Watch mode
+npm run dev
+```
+
+## License
+
+MIT

package/dist/component/Control/CustomControl.d.ts

@@ -0,0 +1,22 @@
+import React from 'react';
+import type { ControlPosition } from './types';
+/**
+ * 自定义控件属性
+ */
+export interface CustomControlProps {
+    /** 控件位置 */
+    position?: ControlPosition;
+    /** 控件名称 */
+    name?: string;
+    /** 自定义类名 */
+    className?: string;
+    /** 自定义样式 */
+    style?: React.CSSProperties;
+    /** 子组件 */
+    children?: React.ReactNode;
+}
+/**
+ * 自定义控件组件
+ * 支持 PC 和移动端响应式布局，使用 Tailwind CSS 样式
+ */
+export declare const CustomControl: React.FC<CustomControlProps>;

package/dist/component/Control/ExportImageControl.d.ts

@@ -0,0 +1,36 @@
+import React from 'react';
+import type { ControlPosition } from './types';
+/**
+ * 导出图片控件属性
+ */
+export interface ExportImageControlProps {
+    /** 控件位置 */
+    position?: ControlPosition;
+    /** 图片类型 */
+    imageType?: 'png' | 'jpeg';
+    /** 按钮文本 */
+    btnText?: string;
+    /** 按钮标题 */
+    title?: string;
+    /** 是否垂直布局 */
+    vertical?: boolean;
+    /** 自定义类名 */
+    className?: string;
+    /** 自定义样式 */
+    style?: React.CSSProperties;
+    /** 控件添加回调 */
+    onAdd?: () => void;
+    /** 控件移除回调 */
+    onRemove?: () => void;
+    /** 控件显示回调 */
+    onShow?: () => void;
+    /** 控件隐藏回调 */
+    onHide?: () => void;
+    /** 导出回调 */
+    onExport?: (dataUrl: string) => void;
+}
+/**
+ * 导出图片控件组件
+ * 支持 PC 和移动端响应式布局，使用 Tailwind CSS 样式
+ */
+export declare const ExportImageControl: React.FC<ExportImageControlProps>;

package/dist/component/Control/FullscreenControl.d.ts

@@ -0,0 +1,38 @@
+import React from 'react';
+import type { ControlPosition } from './types';
+/**
+ * 全屏控件属性
+ */
+export interface FullscreenControlProps {
+    /** 控件位置 */
+    position?: ControlPosition;
+    /** 按钮文本 */
+    btnText?: string;
+    /** 按钮标题 */
+    title?: string;
+    /** 是否垂直布局 */
+    vertical?: boolean;
+    /** 退出按钮文本 */
+    exitBtnText?: string;
+    /** 退出按钮标题 */
+    exitTitle?: string;
+    /** 自定义类名 */
+    className?: string;
+    /** 自定义样式 */
+    style?: React.CSSProperties;
+    /** 控件添加回调 */
+    onAdd?: () => void;
+    /** 控件移除回调 */
+    onRemove?: () => void;
+    /** 控件显示回调 */
+    onShow?: () => void;
+    /** 控件隐藏回调 */
+    onHide?: () => void;
+    /** 全屏状态变化回调 */
+    onFullscreenChange?: (isFullscreen: boolean) => void;
+}
+/**
+ * 全屏控件组件
+ * 支持 PC 和移动端响应式布局，使用 Tailwind CSS 样式
+ */
+export declare const FullscreenControl: React.FC<FullscreenControlProps>;

package/dist/component/Control/GeoLocateControl.d.ts

@@ -0,0 +1,34 @@
+import React from 'react';
+import type { ControlPosition } from './types';
+/**
+ * 定位控件属性
+ */
+export interface GeoLocateControlProps {
+    /** 控件位置 */
+    position?: ControlPosition;
+    /** 按钮文本 */
+    btnText?: string;
+    /** 按钮标题 */
+    title?: string;
+    /** 是否垂直布局 */
+    vertical?: boolean;
+    /** 坐标转换函数 */
+    transform?: (lnglat: [number, number]) => [number, number];
+    /** 自定义类名 */
+    className?: string;
+    /** 自定义样式 */
+    style?: React.CSSProperties;
+    /** 控件添加回调 */
+    onAdd?: () => void;
+    /** 控件移除回调 */
+    onRemove?: () => void;
+    /** 控件显示回调 */
+    onShow?: () => void;
+    /** 控件隐藏回调 */
+    onHide?: () => void;
+}
+/**
+ * 定位控件组件
+ * 支持 PC 和移动端响应式布局，使用 Tailwind CSS 样式
+ */
+export declare const GeoLocateControl: React.FC<GeoLocateControlProps>;

package/dist/component/Control/MapThemeControl.d.ts

@@ -0,0 +1,56 @@
+import React from 'react';
+import type { ControlPosition } from './types';
+/**
+ * 地图主题选项
+ */
+export interface MapThemeOption {
+    /** 主题值 */
+    value: string;
+    /** 显示文本 */
+    text: string;
+    [key: string]: any;
+}
+/**
+ * 地图主题控件属性
+ */
+export interface MapThemeControlProps {
+    /** 控件位置 */
+    position?: ControlPosition;
+    /** 主题选项列表 */
+    options?: MapThemeOption[];
+    /** 按钮文本 */
+    btnText?: string;
+    /** 按钮标题 */
+    title?: string;
+    /** 是否垂直布局 */
+    vertical?: boolean;
+    /** Popper 放置位置 */
+    popperPlacement?: 'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end' | 'right-start' | 'right-end';
+    /** Popper 触发方式 */
+    popperTrigger?: 'click' | 'hover';
+    /** Popper 类名 */
+    popperClassName?: string;
+    /** 自定义类名 */
+    className?: string;
+    /** 自定义样式 */
+    style?: React.CSSProperties;
+    /** 控件添加回调 */
+    onAdd?: () => void;
+    /** 控件移除回调 */
+    onRemove?: () => void;
+    /** 控件显示回调 */
+    onShow?: () => void;
+    /** 控件隐藏回调 */
+    onHide?: () => void;
+    /** Popper 显示回调 */
+    onPopperShow?: () => void;
+    /** Popper 隐藏回调 */
+    onPopperHide?: () => void;
+    /** 选择变化回调 */
+    onSelectChange?: (value: string) => void;
+}
+/**
+ * 地图主题控件组件
+ * 支持 PC 和移动端响应式布局，使用 Tailwind CSS 样式
+ */
+export declare const MapThemeControl: React.FC<MapThemeControlProps>;

package/dist/component/Control/MouseLocationControl.d.ts

@@ -0,0 +1,30 @@
+import React from 'react';
+import type { ControlPosition } from './types';
+/**
+ * 鼠标位置控件属性
+ */
+export interface MouseLocationControlProps {
+    /** 控件位置 */
+    position?: ControlPosition;
+    /** 自定义类名 */
+    className?: string;
+    /** 自定义样式 */
+    style?: React.CSSProperties;
+    /** 坐标转换函数 */
+    transform?: (position: any) => any;
+    /** 控件添加回调 */
+    onAdd?: () => void;
+    /** 控件移除回调 */
+    onRemove?: () => void;
+    /** 控件显示回调 */
+    onShow?: () => void;
+    /** 控件隐藏回调 */
+    onHide?: () => void;
+    /** 位置变化回调 */
+    onLocationChange?: (lnglat: [number, number]) => void;
+}
+/**
+ * 鼠标位置控件组件
+ * 支持 PC 和移动端响应式布局，使用 Tailwind CSS 样式
+ */
+export declare const MouseLocationControl: React.FC<MouseLocationControlProps>;

package/dist/component/Control/ScaleControl.d.ts

@@ -0,0 +1,36 @@
+import React from 'react';
+import type { ControlPosition } from './types';
+/**
+ * 比例尺控件属性
+ */
+export interface ScaleControlProps {
+    /** 控件位置 */
+    position?: ControlPosition;
+    /** 自定义类名 */
+    className?: string;
+    /** 自定义样式 */
+    style?: React.CSSProperties;
+    /** 是否锁定宽度 */
+    lockWidth?: boolean;
+    /** 最大宽度 */
+    maxWidth?: number;
+    /** 是否显示公制单位 */
+    metric?: boolean;
+    /** 是否显示英制单位 */
+    imperial?: boolean;
+    /** 是否在地图静止时更新 */
+    updateWhenIdle?: boolean;
+    /** 控件添加回调 */
+    onAdd?: () => void;
+    /** 控件移除回调 */
+    onRemove?: () => void;
+    /** 控件显示回调 */
+    onShow?: () => void;
+    /** 控件隐藏回调 */
+    onHide?: () => void;
+}
+/**
+ * 比例尺控件组件
+ * 支持 PC 和移动端响应式布局，使用 Tailwind CSS 样式
+ */
+export declare const ScaleControl: React.FC<ScaleControlProps>;

package/dist/component/Control/ZoomControl.d.ts

@@ -0,0 +1,34 @@
+import React from 'react';
+import type { ControlPosition } from './types';
+/**
+ * 缩放控件属性
+ */
+export interface ZoomControlProps {
+    /** 控件位置 */
+    position?: ControlPosition;
+    /** 缩放按钮文本 */
+    zoomInText?: React.ReactNode;
+    zoomOutText?: React.ReactNode;
+    /** 缩放按钮标题 */
+    zoomInTitle?: string;
+    zoomOutTitle?: string;
+    /** 是否显示缩放级别 */
+    showZoom?: boolean;
+    /** 自定义类名 */
+    className?: string;
+    /** 自定义样式 */
+    style?: React.CSSProperties;
+    /** 控件添加回调 */
+    onAdd?: () => void;
+    /** 控件移除回调 */
+    onRemove?: () => void;
+    /** 控件显示回调 */
+    onShow?: () => void;
+    /** 控件隐藏回调 */
+    onHide?: () => void;
+}
+/**
+ * 缩放控件组件
+ * 支持 PC 和移动端响应式布局，使用 Tailwind CSS 样式
+ */
+export declare const ZoomControl: React.FC<ZoomControlProps>;

package/dist/component/Control/types.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 控件位置类型
+ */
+export type ControlPosition = 'topleft' | 'topright' | 'bottomleft' | 'bottomright';
+/**
+ * 控件回调接口
+ */
+export interface IControlCallback<T> {
+    /** 控件添加回调 */
+    onAdd?: () => void;
+    /** 控件移除回调 */
+    onRemove?: () => void;
+    /** 控件显示回调 */
+    onShow?: () => void;
+    /** 控件隐藏回调 */
+    onHide?: () => void;
+}

package/dist/component/Control.d.ts

@@ -0,0 +1,44 @@
+import type { PositionName } from '@antv/l7';
+import React from 'react';
+/**
+ * 内置控件类型
+ * - zoom: 缩放控件
+ * - scale: 比例尺控件
+ * - logo: Logo 控件
+ * - layerSwitch: 图层切换控件
+ * - mouseLocation: 鼠标坐标控件
+ * - mapTheme: 地图主题控件
+ * - geoLocate: 定位控件
+ * - exportImage: 导出图片控件
+ * - fullscreen: 全屏控件
+ * - swipe: 卷帘对比控件
+ */
+export type ControlType = 'zoom' | 'scale' | 'logo' | 'layerSwitch' | 'mouseLocation' | 'mapTheme' | 'geoLocate' | 'exportImage' | 'fullscreen' | 'swipe';
+export interface IControlProps {
+    /**
+     * 控件类型
+     * @see ControlType
+     */
+    type: ControlType;
+    /**
+     * 控件位置
+     * @default 'bottomright'
+     */
+    position?: PositionName;
+    /** 透传给控件构造器的其他配置项 */
+    [key: string]: any;
+}
+/**
+ * 内置地图控件组件，必须在 GaodeMapScene 或 MapScene 内部使用。
+ *
+ * @example
+ * ```tsx
+ * <GaodeMapScene ...>
+ *   <Control type="zoom" position="topleft" />
+ *   <Control type="scale" position="bottomleft" />
+ *   <Control type="layerSwitch" position="topright" />
+ * </GaodeMapScene>
+ * ```
+ */
+declare const _default: React.NamedExoticComponent<IControlProps>;
+export default _default;

package/dist/component/CustomControl.d.ts

@@ -0,0 +1,32 @@
+import type { PositionName } from '@antv/l7';
+import React from 'react';
+export interface ICustomControlProps {
+    /**
+     * 控件位置
+     * @default 'topright'
+     */
+    position?: PositionName;
+    /** 控件容器 className */
+    className?: string;
+    /** 控件容器内联样式 */
+    style?: React.CSSProperties;
+    /** 自定义控件内容 */
+    children?: React.ReactNode;
+}
+/**
+ * 自定义地图控件组件，支持将任意 React 内容渲染到地图控件区域。
+ * 必须在 GaodeMapScene 或 MapScene 内部使用。
+ *
+ * @example
+ * ```tsx
+ * <GaodeMapScene ...>
+ *   <CustomControl position="topright" className="my-legend">
+ *     <div style={{ background: 'white', padding: 8 }}>
+ *       <h4>图例</h4>
+ *       <span style={{ color: '#f00' }}>● 高值</span>
+ *     </div>
+ *   </CustomControl>
+ * </GaodeMapScene>
+ * ```
+ */
+export default function CustomControl(props: ICustomControlProps): React.ReactPortal | null;

package/dist/component/Layer.d.ts

@@ -0,0 +1,79 @@
+import React from 'react';
+import type { ILayerProps } from './LayerAttribute/index';
+/**
+ * 点图层，适合渲染散点、气泡、热力等点数据。
+ *
+ * @example
+ * ```tsx
+ * <PointLayer
+ *   source={data}
+ *   sourceConfig={{ parser: { type: 'json', x: 'lng', y: 'lat' } }}
+ *   colorField="value"
+ *   colorValues={['#f0f9e8', '#08589e']}
+ *   size={6}
+ *   shape="circle"
+ *   onClick={(e) => console.log(e)}
+ * />
+ * ```
+ */
+export declare const PointLayer: React.NamedExoticComponent<ILayerProps>;
+/**
+ * 线图层，适合渲染路径、边界、轨迹等线数据。
+ * shape 支持：'line' | 'arc' | 'arc3d' | 'greatcircle'
+ *
+ * @example
+ * ```tsx
+ * <LineLayer
+ *   source={geojson}
+ *   color="#1890ff"
+ *   size={2}
+ *   style={{ opacity: 0.8 }}
+ * />
+ * ```
+ */
+export declare const LineLayer: React.NamedExoticComponent<ILayerProps>;
+/**
+ * 面图层，适合渲染行政区划、围栏、区域填充等面数据。
+ *
+ * @example
+ * ```tsx
+ * <PolygonLayer
+ *   source={geoData}
+ *   colorField="value"
+ *   colorValues={['#edf8e9', '#006d2c']}
+ *   style={{ opacity: 0.6 }}
+ *   active
+ * />
+ * ```
+ */
+export declare const PolygonLayer: React.NamedExoticComponent<ILayerProps>;
+/**
+ * 热力图层，适合渲染密度分布、强度分布等热力数据。
+ * shape 支持：'heatmap' | 'heatmap3d' | 'hexagon' | 'grid'
+ *
+ * @example
+ * ```tsx
+ * <HeatmapLayer
+ *   source={points}
+ *   sourceConfig={{ parser: { type: 'json', x: 'lng', y: 'lat' } }}
+ *   colorValues={['#f7fbff', '#08306b']}
+ *   shape="heatmap"
+ * />
+ * ```
+ */
+export declare const HeatmapLayer: React.NamedExoticComponent<ILayerProps>;
+/**
+ * 栅格图层，适合渲染影像、遥感等栅格数据。
+ */
+export declare const RasterLayer: React.NamedExoticComponent<ILayerProps>;
+/**
+ * 图片图层，将一张图片叠加到地图指定范围。
+ *
+ * @example
+ * ```tsx
+ * <ImageLayer
+ *   source={{ data: 'https://example.com/image.png', bounds: [73, 3, 135, 53] }}
+ * />
+ * ```
+ */
+export declare const ImageLayer: React.NamedExoticComponent<ILayerProps>;

package/dist/component/LayerAttribute/BaseLayer.d.ts

@@ -0,0 +1,14 @@
+import type { ILayerProps } from './index';
+interface IBaseLayerProps extends ILayerProps {
+    layerType: string;
+}
+/**
+ * 所有图层组件的基础实现，负责：
+ * 1. 创建 L7 图层实例
+ * 2. 将扁平 props 映射到图层 API 调用
+ * 3. 响应 props 变化并更新图层
+ * 4. 注册/注销事件监听
+ * 5. 提供 LayerContext 供子组件使用
+ */
+export declare function BaseLayer(props: IBaseLayerProps): import("react/jsx-runtime").JSX.Element;
+export {};