@trapar-waves/react-three-maplibre 1.1.23 → 2.0.0

package/readme/README-RU.md

@@ -9,105 +9,76 @@
 
 ---
 
-[English](../README.md) | [中文](/readme/README-CN.md) | [日本語](/readme/README-JP.md)
+[English](../README.md) | [中文](./README-CN.md) | [日本語](./README-JP.md)
 
 > Библиотека на базе React, интегрирующая Three.js, MapLibre и AntV для расширенной геопространственной 3D-визуализации.
 
-## ✨ Особенности
+![react-three-maplibre hero](../assets/readme/hero.svg)
+
+![Features](../assets/readme/headers/features.svg)
 
 - **Геопространственная визуализация:** Комбинирует `@antv/l7` и `maplibre-gl` для мощного рендеринга геопространственных данных с пользовательскими слоями карт.
 - **3D-рендеринг с React:** Использует `@react-three/fiber` и `@react-three/drei` для интеграции Three.js в рабочий процесс на базе React для декларативного управления 3D-сценами.
 - **Интеграция настраиваемого UI:** Обеспечивает бесперебойную интеграцию с React (`react`, `react-dom`) для создания интерактивных геопространственных приложений.
 - **Стилизация с упором на утилиты:** Применяет `tailwindcss` для гибкой и быстрой стилизации компонентов и макетов.
-- **Типовая безопасность:** Использует TypeScript для обеспечения типовой безопасности и улучшения опыта разработчика во время разработки.
+- **Типобезопасность:** Использует TypeScript для обеспечения типобезопасности и улучшения опыта разработчика во время разработки.
 - **Быстрый рабочий процесс разработки:** Использует `rsbuild` для оптимизированных сборок и эффективной производительности сервера разработки.
 - **Богатая библиотека компонентов:** Интегрируется с `three-stdlib` и `@react-three/drei` для переиспользуемых утилит и компонентов Three.js.
 - **Интерактивность карт:** Реализует `react-map-gl` для интерактивных элементов управления картами и навигации на клиентской стороне в геопространственных контекстах.
 - **Дополнения AntV:** Включает `@antv/l7-maps` для дополнительных возможностей слоев карт и инструментов визуализации.
 
-## 💻 Технологический стек
-
-- **Фреймворк/Библиотека:** React
-- **UI-тулкит/Стилизация:** Tailwind CSS
-- **3D-рендеринг:** Three.js (`@react-three/fiber`, `@react-three/drei`)
-- **Геопространственные библиотеки:** MapLibre GL, AntV L7
-- **Инструмент сборки:** Rsbuild
-- **Язык:** TypeScript
-
-Полный список зависимостей см. в [package.json](package.json).
+![Tech Stack](../assets/readme/headers/tech-stack.svg)
 
-## 🚀 Начало работы
+- **Фреймворк/библиотека:** `React`
+- **UI-тулкит/стилизация:** `Tailwind CSS`
+- **3D-рендеринг:** `Three.js` (`@react-three/fiber`, `@react-three/drei`)
+- **Геопространственные библиотеки:** `MapLibre GL`, `AntV L7`
+- **Инструмент сборки:** `Rsbuild`
+- **Язык:** `TypeScript`
 
-Следуйте этим инструкциям, чтобы запустить проект локально.
+Полный список зависимостей смотрите в [package.json](../package.json).
 
-### Предварительные требования
+![Getting Started](../assets/readme/headers/getting-started.svg)
 
-Убедитесь, что у вас установлены следующие компоненты:
+## Предварительные требования
 
-- Node.js (рекомендуется версия >= 18.x)
-- Пакетный менеджер (npm, yarn или pnpm)
-
-```bash
-node -v
-npm -v
-```
+- Node.js (рекомендуется >= 18.x)
+- Менеджер пакетов (npm, yarn или pnpm)
 
 ### Установка
 
 1. Создайте новый проект с помощью шаблона:
 
-```bash
-pnpm create trapar-waves
-```
-
-2. Перейдите в каталог вашего проекта и установите зависимости:
+   ```bash
+   pnpm create trapar-waves
+   ```
 
-```bash
-cd your-project-name
-pnpm install
-# or
-npm install
-# or
-yarn install
-```
+2. Перейдите в директорию проекта и установите зависимости:
 
-### Разработка
+   ```bash
+   pnpm install
+   ```
 
-Запустите сервер разработки с горячей перезагрузкой:
-
-```bash
-pnpm dev
-# or
-npm run dev
-# or
-yarn dev
-```
+3. Запустите сервер разработки:
 
-Приложение будет доступно по адресу `http://localhost:3000` по умолчанию.
+   ```bash
+   pnpm dev
+   ```
 
-### Сборка для продакшена
+![Project Structure](../assets/readme/headers/project-structure.svg)
 
-Чтобы создать сборку для продакшена:
-
-```bash
-pnpm build
-# or
-npm run build
-# or
-yarn build
 ```
-
-Предварительный просмотр сборки продакшена локально:
-
-```bash
-pnpm preview
-# or
-npm run preview
-# or
-yarn preview
+├── public/             # Статические ресурсы
+├── src/                # Исходный код
+│   ├── App.tsx         # Основной компонент приложения
+│   └── index.tsx       # Точка входа
+├── rsbuild.config.ts   # Конфигурация Rsbuild
+├── tsconfig.json       # Конфигурация TypeScript
+├── eslint.config.js    # Конфигурация ESLint
+└── package.json        # Зависимости и скрипты проекта
 ```
 
-## 📦 Использование
+![Usage](../assets/readme/headers/usage.svg)
 
 Эта библиотека предназначена для использования в качестве шаблона для создания приложений геопространственной 3D-визуализации. Она предоставляет фундаментальную настройку с React, Three.js, MapLibre GL и AntV L7.
 
@@ -142,7 +113,8 @@ const latLon = {
   latitude: 31.215175,
   longitude: 121.417463,
 };
-const MAPTILER_KEY = import.meta.env.PUBLIC_MAPTILER_KEY;
+const MAP_STYLE_URL
+  = "https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json";
 
 function App() {
   const ref = useRef<HTMLDivElement>(null!);
@@ -187,7 +159,7 @@ function App() {
           zoom: 11,
           pitch: 64.88,
         }}
-        mapStyle={`https://api.maptiler.com/maps/streets/style.json?key=${MAPTILER_KEY}`}
+        mapStyle={MAP_STYLE_URL}
         onLoad={initL7}
       >
         <Stats className="stats" parent={ref} />
@@ -211,22 +183,17 @@ export default App;
 ```
 
 Этот пример демонстрирует:
+
 - Создание карты MapLibre GL с помощью `react-map-gl`
 - Интеграция AntV L7 для визуализации геопространственных данных
 - Использование React Three Fiber и Drei для 3D-рендеринга
 - Позиционирование 3D-объектов относительно карты с помощью `react-three-map`
 
-### Переменные окружения
+### Подложка карты
 
-Для использования сервисов карт, таких как MapTiler, вам нужно настроить переменные окружения. Создайте файл `.env` в корне вашего проекта:
+В шаблоне по умолчанию используется стиль Carto GL без API-ключа (`MAP_STYLE_URL` в `src/App.tsx`). Для другого провайдера (например, MapTiler) задайте `mapStyle` и храните ключи в `.env` / CI.
 
-```
-PUBLIC_MAPTILER_KEY=your_maptiler_api_key_here
-```
-
-Обязательно добавьте `.env` в ваш `.gitignore`, чтобы ваши ключи оставались в безопасности.
-
-## 🤝 Участие в разработке
+![Contributing](../assets/readme/headers/contributing.svg)
 
 Вклад в проект приветствуется и очень ценится! Чтобы внести вклад, следуйте этим шагам:
 
@@ -236,15 +203,16 @@ PUBLIC_MAPTILER_KEY=your_maptiler_api_key_here
 4. Отправьте изменения в ветку (`git push origin feature/amazing-feature`)
 5. Откройте Pull Request
 
-Пожалуйста, убедитесь, что ваш код соответствует существующему стилю и проходит все тесты.
+![License](../assets/readme/headers/license.svg)
+
+MIT License © 2025 Trapar Waves
 
-## 👤 Author
+## 👤 Автор
 
-- **Rikka:** (admin@rikka.cc)
-- **GitHub Profile:** [Muromi-Rikka](https://github.com/Muromi-Rikka)
+- **Rikka:** [admin@rikka.cc](mailto:admin@rikka.cc)
+- **Профиль GitHub:** [Muromi-Rikka](https://github.com/Muromi-Rikka)
 
-## 🔗 Links
+## 🔗 Ссылки
 
 - **Репозиторий:** [https://github.com/Trapar-waves/react-three-maplibre](https://github.com/Trapar-waves/react-three-maplibre)
-- **Домашняя страница:** [https://github.com/Trapar-waves/react-three-maplibre](https://github.com/Trapar-waves/react-three-maplibre)
-- **Проблемы:** [https://github.com/Trapar-waves/react-three-maplibre/issues](https://github.com/Trapar-waves/react-three-maplibre/issues)
+- **Issues:** [https://github.com/Trapar-waves/react-three-maplibre/issues](https://github.com/Trapar-waves/react-three-maplibre/issues)

package/rsbuild.config.ts

@@ -1,11 +1,37 @@
 import { defineConfig, loadEnv } from "@rsbuild/core";
+import { pluginLess } from "@rsbuild/plugin-less";
 import { pluginReact } from "@rsbuild/plugin-react";
+import { RsdoctorRspackPlugin } from "@rsdoctor/rspack-plugin";
 import tailwind from "@tailwindcss/postcss";
+import process from "node:process";
+import TurboConsole from "unplugin-turbo-console/rspack";
 
 const { publicVars } = loadEnv({ cwd: "./environments" });
 
+function normalizeBasePath(): string {
+  const raw = process.env.BASE_PATH?.trim();
+  if (!raw || raw === "/") {
+    return "/";
+  }
+  const prefixed = raw.startsWith("/") ? raw : `/${raw}`;
+  return prefixed.endsWith("/") ? prefixed : `${prefixed}/`;
+}
+
+const basePath = normalizeBasePath();
+const isUseSubpath = basePath !== "/";
+
+const isEnableRsdoctor = Boolean(process.env.RSDOCTOR);
+const isEnableTurboConsole = process.env.NODE_ENV === "development";
+
 export default defineConfig({
-  plugins: [pluginReact()],
+  ...(isUseSubpath && {
+    output: { assetPrefix: basePath },
+    server: { base: basePath },
+  }),
+  performance: {
+    ...(isEnableRsdoctor && { buildCache: false }),
+  },
+  plugins: [pluginReact(), pluginLess()],
   source: {
     define: publicVars,
   },
@@ -15,5 +41,24 @@ export default defineConfig({
         plugins: [tailwind],
       },
     },
+    rspack: [
+      (config) => {
+        if (isEnableTurboConsole) {
+          config.plugins.push(TurboConsole());
+        }
+        if (isEnableRsdoctor) {
+          config.plugins.push(
+            new RsdoctorRspackPlugin({
+              output: {
+                mode: "brief",
+                options: {
+                  type: ["json"],
+                },
+              },
+            }),
+          );
+        }
+      },
+    ],
   },
 });

package/src/app.tsx

@@ -0,0 +1,217 @@
+import type { ReactNode } from "react";
+import type { MapRef } from "react-map-gl/maplibre";
+import { PointLayer, Scene } from "@antv/l7";
+import { MapLibre } from "@antv/l7-maps";
+import { Box, Stats } from "@react-three/drei";
+import { extend } from "@react-three/fiber";
+import { useRef } from "react";
+import Map from "react-map-gl/maplibre";
+import { Canvas } from "react-three-map/maplibre";
+import { LineMaterial, LineSegments2, LineSegmentsGeometry } from "three-stdlib";
+
+// eslint-disable-next-line unicorn/no-top-level-side-effects -- R3F extend must run before render
+extend({ LineMaterial, LineSegments2, LineSegmentsGeometry });
+
+declare module "@react-three/fiber" {
+  interface ThreeElements {
+    lineMaterial: Partial<LineMaterial> & ThreeElements["material"];
+    lineSegments2: ThreeElements["object3D"] & { children?: ReactNode };
+    lineSegmentsGeometry: ThreeElements["bufferGeometry"];
+  }
+}
+
+const latLon = {
+  latitude: 31.215175,
+  longitude: 121.417463,
+};
+
+/**
+ * Carto 托管的 MapLibre GL 矢量底图，无需 API Key（使用请遵守 https://carto.com/basemaps/ 条款）。
+*/
+const MAP_STYLE_URL = "https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json";
+
+function publicAssetUrl(filename: string): string {
+  const base = (import.meta.env.BASE_URL ?? "/").replace(/\/$/, "");
+  const path = filename.startsWith("/") ? filename : `/${filename}`;
+  return `${base || ""}${path}`.replaceAll("//", "/");
+}
+
+const HOMEPAGE = "https://github.com/Trapar-waves/react-three-maplibre";
+const LOGOS_SET_URL = "https://icon-sets.iconify.design/logos/";
+
+interface TechPill {
+  iconClass: string;
+  id: string;
+  label: string;
+}
+
+const techStack: TechPill[] = [
+  { iconClass: "icon-[logos--react]", id: "react", label: "React 19" },
+  { iconClass: "icon-[logos--typescript-icon]", id: "ts", label: "TypeScript" },
+  { iconClass: "icon-[logos--tailwindcss-icon]", id: "tailwind", label: "Tailwind 4" },
+  { iconClass: "icon-[material-icon-theme--rstack]", id: "rsbuild", label: "Rsbuild" },
+  { iconClass: "icon-[simple-icons--maplibre]", id: "maplibre", label: "MapLibre · react-map-gl" },
+  { iconClass: "icon-[logos--markdown]", id: "l7", label: "AntV L7" },
+  { iconClass: "icon-[logos--threejs]", id: "r3f", label: "R3F · drei · three-stdlib" },
+  { iconClass: "icon-[logos--markdown]", id: "rtmap", label: "react-three-map" },
+  { iconClass: "icon-[logos--eslint]", id: "eslint", label: "ESLint" },
+  { iconClass: "icon-[logos--pnpm]", id: "pnpm", label: "pnpm" },
+  { iconClass: "icon-[logos--github-icon]", id: "github", label: "GitHub Actions" },
+];
+
+const readmeFeatures: string[] = [
+  "MapLibre 与 AntV L7 组合，自定义地图与点层渲染。",
+  "@react-three/fiber、drei 将 Three.js 以声明式接入 React。",
+  "react-three-map 与 MapLibre 视口同步；Canvas 使用 overlay 模式使 Three 叠在 L7 点层之上。",
+  "Tailwind CSS 快速布局与面板样式。",
+  "TypeScript 覆盖地图与场景相关类型。",
+  "Rsbuild 开发与生产构建。",
+  "react-map-gl 提供交互与导航体验。",
+  "three-stdlib 与 drei 复用常用几何与调试组件。",
+  "GitHub Pages 支持 BASE_PATH 与 404.html SPA 部署。",
+  "默认 Carto Basemaps GL 样式，本地与 CI 均无需地图 API Key。",
+];
+
+const readmeTechNote = "演示使用 @react-three/drei 的 Stats；生产可按需移除。若需其他底图，可在 App.tsx 中替换 MAP_STYLE_URL 并自行处理鉴权。";
+
+function App() {
+  const divReference = useRef<HTMLDivElement>(null!);
+  const mapReference = useRef<MapRef>(null!);
+  function initL7() {
+    if (!mapReference.current) {
+      return;
+    }
+
+    const scene = new Scene({
+      id: "map",
+      map: new MapLibre({
+        mapInstance: mapReference.current.getMap(),
+      }),
+    });
+    scene.on("loaded", async () => {
+      try {
+        const response = await fetch(publicAssetUrl("BElVQFEFvpAKzddxFZxJ.txt"));
+        if (!response.ok) {
+          return;
+        }
+        const data = await response.text();
+        const pointLayer = new PointLayer({
+          blend: "additive",
+        })
+          .source(data, {
+            parser: {
+              type: "csv",
+              x: "lng",
+              y: "lat",
+            },
+          })
+          .size(0.5)
+          .color("#080298");
+
+        scene.addLayer(pointLayer);
+      }
+      catch {}
+    });
+  }
+  return (
+    <div className="h-screen w-screen relative overflow-hidden" ref={divReference}>
+      <aside
+        aria-label="模板说明"
+        className="pointer-events-none absolute left-4 top-4 z-10 max-w-sm motion-safe:transition motion-safe:duration-200"
+      >
+        <div
+          className="pointer-events-auto max-h-[min(70vh,560px)] overflow-y-auto overscroll-contain rounded-xl border border-white/15 bg-slate-950/80 p-4 text-sm text-slate-100 shadow-xl backdrop-blur-md"
+        >
+          <p className="font-semibold text-white">react-three-maplibre</p>
+          <p className="mt-2 leading-relaxed text-slate-300">
+            MapLibre 与 react-three-map 同屏；L7 点层叠加 CSV，Three 方体经
+            {" "}
+            <code className="rounded bg-slate-800 px-1">overlay</code>
+            {" "}
+            画布叠在 L7 之上。底图为 Carto 公开 GL 样式，无需地图服务 API Key。技术图标见
+            {" "}
+            <a
+              className="font-medium text-sky-300 underline decoration-sky-700 underline-offset-2 hover:text-sky-200"
+              href={LOGOS_SET_URL}
+              rel="noreferrer"
+              target="_blank"
+            >
+              Iconify logos
+            </a>
+            。
+          </p>
+          <p className="mt-3 text-xs font-medium uppercase tracking-wide text-slate-500">
+            技术栈
+          </p>
+          <div className="mt-2 flex flex-wrap gap-2">
+            {techStack.map(item => (
+              <span
+                className="inline-flex items-center gap-1.5 rounded-lg border border-white/10 bg-slate-900/80 px-2 py-1 text-xs text-slate-200"
+                key={item.id}
+              >
+                <span aria-hidden className={`${item.iconClass} text-base text-sky-300`} />
+                {item.label}
+              </span>
+            ))}
+          </div>
+          <p className="mt-4 text-xs font-medium uppercase tracking-wide text-slate-500">
+            README 摘要
+          </p>
+          <ul className="mt-2 list-disc space-y-1 pl-4 text-slate-400">
+            {readmeFeatures.map(line => (
+              <li key={line}>{line}</li>
+            ))}
+          </ul>
+          <p className="mt-3 text-xs italic leading-relaxed text-slate-500">
+            {readmeTechNote}
+          </p>
+          <p className="mt-3 text-xs leading-relaxed text-slate-500">
+            品牌图标来自
+            {" "}
+            <a className="text-sky-400 underline hover:text-sky-300" href={LOGOS_SET_URL} rel="noreferrer" target="_blank">SVG Logos</a>
+            {" "}
+            （CC0）。
+          </p>
+          <a
+            className="mt-3 inline-flex min-h-11 w-full items-center justify-center rounded-lg bg-sky-500 px-4 py-2 text-sm font-semibold text-slate-950 hover:bg-sky-400 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-white"
+            href={HOMEPAGE}
+            rel="noreferrer"
+            target="_blank"
+          >
+            查看仓库
+          </a>
+        </div>
+      </aside>
+      <Map
+        id="map"
+        initialViewState={{
+          ...latLon,
+          pitch: 64.88,
+          zoom: 11,
+        }}
+        mapStyle={MAP_STYLE_URL}
+        onLoad={initL7}
+        ref={mapReference}
+      >
+        <Stats className="stats" parent={divReference} />
+
+        <Canvas
+          id="trapar-r3f-overlay"
+          overlay
+          {...latLon}
+        >
+          <hemisphereLight
+            args={["#ffffff", "#60666C"]}
+            position={[1, 4.5, 3]}
+          />
+          <object3D scale={500}>
+            <Box position={[-1.2, 1, 0]} />
+            <Box position={[1.2, 1, 0]} />
+          </object3D>
+        </Canvas>
+      </Map>
+    </div>
+  );
+}
+
+export default App;

package/src/index.tsx

@@ -1,10 +1,10 @@
 import ReactDOM from "react-dom/client";
-import App from "./App";
+import App from "./app";
 import "./global.css";
 
-const rootEl = document.getElementById("root");
-if (rootEl) {
-  const root = ReactDOM.createRoot(rootEl);
+const rootElement = document.querySelector("#root");
+if (rootElement) {
+  const root = ReactDOM.createRoot(rootElement);
   root.render(
     <App />,
   );

package/tsconfig.json

@@ -2,7 +2,7 @@
   "compilerOptions": {
     "target": "ES2020",
     "jsx": "react-jsx",
-    "lib": ["DOM", "ES2020"],
+    "lib": ["DOM", "ESNext"],
     "useDefineForClassFields": true,
 
     /* modules */

package/src/App.tsx

@@ -1,91 +0,0 @@
-import type { ReactNode } from "react";
-import type { MapRef } from "react-map-gl/maplibre";
-import { PointLayer, Scene } from "@antv/l7";
-import { MapLibre } from "@antv/l7-maps";
-import { Box, Stats } from "@react-three/drei";
-import { extend } from "@react-three/fiber";
-import { useRef } from "react";
-import Map from "react-map-gl/maplibre";
-import { Canvas } from "react-three-map/maplibre";
-import { LineMaterial, LineSegments2, LineSegmentsGeometry } from "three-stdlib";
-
-extend({ LineSegmentsGeometry, LineMaterial, LineSegments2 });
-
-declare module "@react-three/fiber" {
-  interface ThreeElements {
-    lineSegmentsGeometry: ThreeElements["bufferGeometry"];
-    lineMaterial: ThreeElements["material"] & Partial<LineMaterial>;
-    lineSegments2: ThreeElements["object3D"] & { children?: ReactNode };
-  }
-}
-
-const latLon = {
-  latitude: 31.215175,
-  longitude: 121.417463,
-};
-const MAPTILER_KEY = import.meta.env.PUBLIC_MAPTILER_KEY;
-
-function App() {
-  const ref = useRef<HTMLDivElement>(null!);
-  const mapRef = useRef<MapRef>(null!);
-  function initL7() {
-    if (mapRef.current) {
-      const scene = new Scene({
-        id: "map",
-        map: new MapLibre({
-          mapInstance: mapRef.current.getMap(),
-        }),
-      });
-      scene.on("loaded", () => {
-        fetch("/BElVQFEFvpAKzddxFZxJ.txt")
-          .then(res => res.text())
-          .then((data) => {
-            const pointLayer = new PointLayer({
-              blend: "additive",
-            })
-              .source(data, {
-                parser: {
-                  type: "csv",
-                  y: "lat",
-                  x: "lng",
-                },
-              })
-              .size(0.5)
-              .color("#080298");
-
-            scene.addLayer(pointLayer);
-          });
-      });
-    }
-  }
-  return (
-    <div className="h-screen w-screen relative overflow-hidden" ref={ref}>
-      <Map
-        id="map"
-        ref={mapRef}
-        initialViewState={{
-          ...latLon,
-          zoom: 11,
-          pitch: 64.88,
-        }}
-        mapStyle={`https://api.maptiler.com/maps/streets/style.json?key=${MAPTILER_KEY}`}
-        onLoad={initL7}
-      >
-        <Stats className="stats" parent={ref} />
-
-        <Canvas {...latLon}>
-          <hemisphereLight
-            args={["#ffffff", "#60666C"]}
-            position={[1, 4.5, 3]}
-          />
-          <object3D scale={500}>
-            <Box position={[-1.2, 1, 0]} />
-            <Box position={[1.2, 1, 0]} />
-          </object3D>
-        </Canvas>
-      </Map>
-    </div>
-  );
-}
-
-export default App;