@maptec/cli 1.0.0

package/skills/jsapi-skills/references/controls.md

@@ -0,0 +1,195 @@
+# Maptec Controls Reference
+
+Use this reference when adding built-in map controls such as navigation, scale, fullscreen, compass, or hawkeye.
+
+## 中文能力入口
+
+本文件对应功能 **地图控件**：支持缩放导航、比例尺、全屏、指南针、鹰眼控件的位置配置、添加、移除与清理。
+
+当前公开控件类：
+
+- `Maptec.NavigationControl`
+- `Maptec.ScaleControl`
+- `Maptec.FullscreenControl`
+- `Maptec.CompassControl`
+- `Maptec.HawkeyeControl`
+
+| 用户需求 | 优先实现 |
+|---|---|
+| “添加缩放控件” | `new Maptec.NavigationControl()` + `map.addControl(nav, position)` |
+| “在地图右下角添加比例尺控件” | `new Maptec.ScaleControl()` + `map.addControl(scale, "bottom-right")` |
+| “添加全屏按钮” | `new Maptec.FullscreenControl()` |
+| “添加指南针控件” | `new Maptec.CompassControl()` 或使用 `NavigationControl` 内置指南针 |
+| “添加鹰眼地图” | `new Maptec.HawkeyeControl(options)` |
+| “隐藏/显示某个控件” | 保存 control 实例，使用 `map.addControl` / `map.removeControl` 切换 |
+
+## Common Pattern
+
+Controls are created with `new Maptec.XControl(...)` and added with `map.addControl(control, position?)`.
+
+```js
+map.on("load", () => {
+  const scale = new Maptec.ScaleControl();
+  map.addControl(scale, "bottom-left");
+});
+```
+
+Supported positions:
+
+- `"top-left"`
+- `"top-right"`
+- `"bottom-left"`
+- `"bottom-right"`
+
+Use `map.removeControl(control)` for cleanup when needed.
+
+```js
+const controls = [];
+
+function addControl(control, position) {
+  map.addControl(control, position);
+  controls.push(control);
+}
+
+function cleanup() {
+  controls.forEach((control) => map.removeControl(control));
+}
+```
+
+## NavigationControl
+
+Contains zoom buttons and compass.
+
+```js
+const nav = new Maptec.NavigationControl();
+map.addControl(nav, "top-left");
+```
+
+Use this when users need standard zoom and orientation controls.
+
+## ScaleControl
+
+Displays a distance scale.
+
+```js
+const scale = new Maptec.ScaleControl({
+  maxWidth: 100,
+  unit: "metric"
+});
+
+map.addControl(scale, "bottom-left");
+```
+
+Supported units:
+
+- `"metric"`
+- `"imperial"`
+- `"nautical"`
+
+## FullscreenControl
+
+Adds a fullscreen toggle button.
+
+```js
+const fullscreen = new Maptec.FullscreenControl();
+map.addControl(fullscreen, "top-right");
+```
+
+It follows the evented pattern where supported:
+
+- `on(type, listener)`
+- `once(type, listener?)`
+- `off(type, listener)`
+
+## CompassControl
+
+Shows a compass with rotation controls.
+
+- Left/right arrows rotate the map.
+- Center compass resets north when not facing north.
+- When already north, center toggles 2D/3D pitch.
+
+```js
+const compass = new Maptec.CompassControl();
+map.addControl(compass, "top-right");
+```
+
+## HawkeyeControl
+
+Shows an overview map and viewport box.
+
+```js
+const hawkeye = new Maptec.HawkeyeControl({
+  zoomDiff: 4,
+  overviewBoxColor: "blue",
+  width: "150px",
+  height: "100px"
+});
+
+map.addControl(hawkeye, "bottom-right");
+```
+
+Options:
+
+- `zoomDiff`: zoom difference between main map and overview map; default `4`.
+- `overviewBoxColor`: CSS color for viewport box.
+- `width`: overview width; default `"150px"`.
+- `height`: overview height; default `"100px"`.
+
+## Business Locate Button
+
+`maptec-js/src/index.ts` 未公开导出 `GeolocateControl`。如果产品需要定位按钮，用浏览器定位能力实现业务按钮，再移动地图并添加或更新 Marker。
+
+```js
+const locateButton = document.createElement("button");
+locateButton.type = "button";
+locateButton.textContent = "定位";
+locateButton.className = "map-locate-button";
+
+let userMarker = null;
+
+locateButton.addEventListener("click", () => {
+  if (!navigator.geolocation) {
+    console.warn("当前浏览器不支持定位");
+    return;
+  }
+
+  navigator.geolocation.getCurrentPosition(
+    (position) => {
+      const lngLat = [
+        position.coords.longitude,
+        position.coords.latitude
+      ];
+
+      if (!userMarker) {
+        userMarker = new Maptec.Marker({
+          position: lngLat,
+          color: "#2563eb"
+        });
+        map.addOverlay(userMarker);
+      } else {
+        userMarker.position = lngLat;
+      }
+
+      map.flyTo({ center: lngLat, zoom: 16 });
+    },
+    (error) => {
+      console.error("定位失败", error);
+    },
+    { enableHighAccuracy: true, timeout: 10000 }
+  );
+});
+```
+
+## Pitfalls
+
+- Do not write `new Maptec.PerformanceMonitorControl()`, `new Maptec.GeolocateControl()`, `new Maptec.LogoControl()`, or `new Maptec.AttributionControl()` in user-facing examples unless those classes are explicitly exported by the current SDK.
+- Do not add both `NavigationControl` and separate `CompassControl` unless the UI intentionally needs both.
+- Keep control instances so they can be removed during component cleanup.
+
+## Agent 规则
+
+- 添加控件必须使用 `map.addControl(control, position?)`，清理时使用 `map.removeControl(control)`。
+- 内置控件只能使用当前公开导出的 `NavigationControl`、`ScaleControl`、`FullscreenControl`、`CompassControl`、`HawkeyeControl`。
+- 定位按钮使用浏览器 `navigator.geolocation` 加自定义业务按钮方案，不要编造 `Maptec.GeolocateControl`。
+- 控件位置只能使用 SDK 支持的位置值：`top-left`、`top-right`、`bottom-left`、`bottom-right`。

package/skills/jsapi-skills/references/events.md

@@ -0,0 +1,222 @@
+# Maptec Events Reference
+
+Use this reference when handling map events, mouse/wheel events, subscriptions, custom events, overlay events, or cleanup.
+
+## 中文能力入口
+
+本文件对应功能 **事件监听**：支持地图点击、缩放变化、中心点变化、Marker 点击、矢量覆盖物点击、信息窗口打开/关闭等事件监听代码。
+
+| 用户需求 | 事件 |
+|---|---|
+| “点击地图获取当前位置的经纬度” | `map.on("click", handler)`，读取 `event.lngLat` |
+| “监听地图缩放级别变化” | `map.on("zoomend", handler)`，读取 `map.zoom` |
+| “监听中心点变化” | `map.on("moveend", handler)`，读取 `map.center` |
+| “监听Marker点击” | `marker.on("click", handler)` |
+| “监听矢量覆盖物点击” | `circleOverlay.on("click", handler)`、`polylineOverlay.on("click", handler)`、`polygonOverlay.on("click", handler)`、`geojsonOverlay.on("click", handler)` |
+| “监听信息窗口打开/关闭” | `popup.on("open", handler)`、`popup.on("close", handler)` |
+
+## Evented Pattern
+
+Maptec map, overlays, and some controls support:
+
+- `on(type, listener)`: subscribe.
+- `once(type, listener?)`: subscribe once, or return a promise when no listener is provided.
+- `off(type, listener)`: remove listener.
+
+Some `on` calls return a `Subscription` with `unsubscribe()`.
+
+```js
+const subscription = map.on("click", (event) => {
+  console.log("clicked", event.lngLat);
+});
+
+subscription.unsubscribe();
+```
+
+If the runtime does not return a subscription, keep the listener reference and call `off`.
+
+```js
+const onMoveEnd = () => {
+  console.log(map.center, map.zoom);
+};
+
+map.on("moveend", onMoveEnd);
+map.off("moveend", onMoveEnd);
+```
+
+## Map Event Types
+
+Common `MapEventType` entries:
+
+- Lifecycle: `load`, `destroy`, `resize`
+- Mouse: `click`, `dblclick`, `contextmenu`, `mousedown`, `mouseup`, `mousemove`, `mouseover`, `mouseout`, `mouseenter`, `mouseleave`
+- Wheel: `wheel`
+- Touch: `touchstart`, `touchmove`, `touchend`, `touchcancel`
+- Move: `movestart`, `move`, `moveend`
+- Drag: `dragstart`, `drag`, `dragend`
+- Zoom: `zoomstart`, `zoom`, `zoomend`
+- Rotate: `rotatestart`, `rotate`, `rotateend`
+- Pitch: `pitchstart`, `pitch`, `pitchend`
+- Box zoom: `boxzoomstart`, `boxzoomend`, `boxzoomcancel`
+
+```js
+map.on("load", () => {
+  console.log("map loaded");
+});
+
+map.on("moveend", () => {
+  console.log("view", map.center, map.zoom);
+});
+```
+
+## MapMouseEvent
+
+Mouse events such as `click` provide a `MapMouseEvent`.
+
+Important fields:
+
+- `type`
+- `target`: map instance
+- `originalEvent`: original DOM mouse event
+- `point`: screen pixel point
+- `lngLat`: geographic coordinate
+- `defaultPrevented`
+
+Method:
+
+- `preventDefault()`
+
+```js
+map.on("click", (event) => {
+  console.log("screen point", event.point);
+  console.log("lngLat", event.lngLat);
+});
+```
+
+Click map and get `[lng, lat]`:
+
+```js
+const onMapClick = (event) => {
+  const lngLat = Maptec.LngLat.convert(event.lngLat).toArray();
+  console.log("点击坐标", lngLat);
+};
+
+map.on("click", onMapClick);
+
+// cleanup
+map.off("click", onMapClick);
+```
+
+Use `event.lngLat` for map coordinates and `event.point` for UI pixel calculations.
+
+## MapWheelEvent
+
+`wheel` events provide `MapWheelEvent`.
+
+Fields:
+
+- `type`: `"wheel"`
+- `target`: map instance
+- `originalEvent`: original `WheelEvent`
+- `defaultPrevented`
+
+Method:
+
+- `preventDefault()`: prevents the map's default zoom behavior for that wheel event.
+
+```js
+map.on("wheel", (event) => {
+  if (shouldBlockWheelZoom(event.originalEvent)) {
+    event.preventDefault();
+  }
+});
+```
+
+## MaptecEvent
+
+`Maptec.Event` can be created and fired.
+
+```js
+const event = new Maptec.Event("custom:ready", {
+  message: "地图初始化完成"
+});
+
+map.fire(event);
+```
+
+Use custom events sparingly. Prefer normal application state events unless the event should be part of the Maptec map event pipeline.
+
+## Overlay Events
+
+Overlays such as `Marker`, `Popup`, `CircleOverlay`, `PolylineOverlay`, `PolygonOverlay`, and `GeoJSONOverlay` expose event methods where supported.
+
+```js
+const marker = new Maptec.Marker({
+  position: [103.8198, 1.3521]
+});
+
+marker.on("click", () => {
+  marker.togglePopup();
+});
+
+map.addOverlay(marker);
+```
+
+```js
+const polyline = new Maptec.PolylineOverlay({
+  positions: [
+    [103.8318, 1.3048],
+    [103.8198, 1.3521]
+  ],
+  strokeColor: "#7c3aed",
+  strokeWeight: 5
+});
+
+const onLineClick = (event) => {
+  console.log("点击折线", event.features);
+};
+
+polyline.on("click", onLineClick);
+map.addOverlay(polyline);
+```
+
+## Cleanup Pattern
+
+```js
+const cleanups = [];
+
+function listen(target, type, listener) {
+  const subscription = target.on(type, listener);
+  cleanups.push(() => {
+    if (subscription?.unsubscribe) {
+      subscription.unsubscribe();
+      return;
+    }
+    target.off?.(type, listener);
+  });
+}
+
+listen(map, "moveend", () => {
+  console.log(map.center);
+});
+
+function cleanup() {
+  cleanups.splice(0).forEach((fn) => fn());
+}
+```
+
+## Pitfalls
+
+- Do not attach listeners repeatedly inside render loops without cleanup.
+- Use `once` for one-time initialization reactions.
+- Use `preventDefault()` only when intentionally overriding SDK behavior.
+- Use `lngLat` for geographic work and `point` for pixel/UI work.
+- 覆盖物事件示例必须使用真实公开类名，不要写 `Circle`、`Polyline`、`Polygon`。
+
+## Agent 规则
+
+- 监听事件时必须保存 listener 引用或订阅对象，清理阶段使用 `off` 或 `unsubscribe()`。
+- 地图点击获取经纬度时使用 `event.lngLat`，需要数组时再转换为 `[lng, lat]`。
+- 缩放、中心点、旋转、倾斜等状态应从地图实例读取，不要自行缓存后当作真实状态。
+- 覆盖物事件使用 `Marker`、`Popup`、`CircleOverlay`、`PolylineOverlay`、`PolygonOverlay`、`GeoJSONOverlay` 的事件能力。
+- 不要编造未确认事件名；未确认事件必须标记为 `需确认 Maptec 是否支持`。

package/skills/jsapi-skills/references/geocoding.md

@@ -0,0 +1,184 @@
+# 地理编码能力参考
+
+当用户要求把地址、地名、地标、道路或 POI 名称转换为经纬度坐标时，使用本参考。本文件只覆盖功能 **地理编码**。
+
+逆地理编码，即坐标反查地址，请读取 `re-geocoding.md`。
+
+## 能力入口
+
+| 用户需求 | 优先实现 |
+|---|---|
+| “将新加坡摩天观景轮标注在地图上” | `Geocode.getLocation` 获取坐标，再添加 `Marker` |
+| “将地址转换为经纬度坐标” | `Geocode.getLocation(address, options, callback)` |
+| “把地名作为路线起终点” | 先 `Geocode.getLocation`，再把 `[lng, lat]` 传给路线规划 |
+
+## Geocode 服务
+
+```js
+const geocode = new Maptec.Geocode({
+  language: "en",
+  region: "SG",
+  timeout: 10000
+});
+```
+
+`GeocodeOptions`:
+
+- `language?: string`：IETF language tag，默认 `"en"`。
+- `region?: string`：ccTLD region code，例如 `"SG"` 或 `"BR"`。
+- `timeout?: number`：请求超时时间，默认 `10000` 毫秒。
+
+## getLocation
+
+当用户输入地址、地名、地标或道路名，代码需要坐标时使用 `getLocation`。
+
+调用模式：
+
+```js
+geocode.getLocation(address, callback);
+geocode.getLocation(address, options, callback);
+```
+
+示例：
+
+```js
+geocode.getLocation("Singapore Flyer", {
+  language: "en",
+  region: "SG"
+}, (error, result) => {
+  if (error) {
+    console.error("地理编码失败", error);
+    return;
+  }
+
+  const first = result?.results?.[0];
+  const location = first?.geometry?.location;
+  if (!location) {
+    console.warn("没有地理编码结果", result?.status);
+    return;
+  }
+
+  const position = [location.longitude, location.latitude];
+  map.flyTo({ center: position, zoom: 15 });
+
+  const marker = new Maptec.Marker({ position });
+  map.addOverlay(marker);
+});
+```
+
+`GeocodeLocationOptions`:
+
+- `language?: string`
+- `region?: string`
+- `components?: string`：过滤格式为 `component:value|component:value`。
+- `locationBias?: { southwest: LngLatLike; northeast: LngLatLike }`：偏向某个矩形范围，但不保证结果一定在范围内。
+
+```js
+geocode.getLocation("coffee", {
+  locationBias: {
+    southwest: [103.6, 1.20],
+    northeast: [104.1, 1.48]
+  }
+}, callback);
+```
+
+## 结果类型
+
+`GeocodeCallback = (error, result?) => void`。
+
+`GeocodeError`:
+
+- `code: string`
+- `message: string`
+
+`GeocodeStatus`:
+
+- `"OK"`
+- `"ZERO_RESULTS"`
+- `"ERROR"`
+
+`GeocodeResult`:
+
+- `status: GeocodeStatus`
+- `results: GeoResult[]`
+- `error?: GeocodeError`
+
+`GeoResult`:
+
+- `formattedAddress: string`
+- `placeId: string`
+- `types: string[]`
+- `languageCode: string`
+- `geometry: GeocodeGeometry`
+- `addressComponents: GeocodeAddressComponent[]`
+- `matchDetails: GeocodeMatchDetails`
+- `supplementaryInfo: GeocodeSupplementaryInfo`
+
+`GeocodeGeometry`:
+
+- `location: LngLatObject`
+- `locationType: GeocodeLocationType`
+- `viewport: GeocodeViewport`
+- `distance: number`
+
+`GeocodeLocationType`:
+
+- `"ROOFTOP"`
+- `"INTERPOLATED"`
+- `"CENTER"`
+
+`GeocodeViewport`:
+
+- `southwest: LngLatObject`
+- `northeast: LngLatObject`
+
+## 坐标转换
+
+地理编码结果中的 `location` 是对象形式，需要转换为 `[lng, lat]`。
+
+```js
+function toLngLatFromGeocode(location) {
+  if (!location) return null;
+  return [location.longitude, location.latitude];
+}
+```
+
+转换后可传给 `Marker`、`Popup`、`Driving.search`、`fitBounds`、`flyTo` 或 `GeoJSON`。
+
+## 路线规划集成
+
+```js
+async function geocodeOne(query, region = "SG") {
+  return new Promise((resolve, reject) => {
+    geocode.getLocation(query, { region }, (error, result) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+
+      const location = result?.results?.[0]?.geometry?.location;
+      if (!location) {
+        reject(new Error(`No geocode result: ${query}`));
+        return;
+      }
+
+      resolve([location.longitude, location.latitude]);
+    });
+  });
+}
+```
+
+## 注意事项
+
+- 不要使用 `[location.latitude, location.longitude]`；必须转换成 `[longitude, latitude]`。
+- `locationBias` 只是偏向，不是硬边界过滤。
+- 必须处理 `ZERO_RESULTS` 和空 `results`。
+- 地址或地名作为路线起终点时，先地理编码，再调用路线规划。
+- 对关键业务可使用 `matchDetails` 判断低置信度结果，不要直接绘制高风险结果。
+
+## Agent 规则
+
+- 地址、地名、地标或道路名称转坐标必须使用 `Maptec.Geocode.getLocation`。
+- 地理编码结果必须从 `geometry.location` 转换为 `[longitude, latitude]`，不能写成 `[latitude, longitude]`。
+- 必须处理错误、`ZERO_RESULTS` 和空 `results`。
+- 地理编码结果用于 Marker 或路线规划前，应确认存在有效坐标。