diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..8e143ae --- /dev/null +++ b/.github/CODE_OF_CONDUCT.md @@ -0,0 +1,61 @@ +# Code de conduite — Contributor Covenant + +## Notre engagement + +En tant que membres, contributrices, contributeurs et responsables de ce projet, nous nous +engageons à faire de la participation à notre communauté une expérience exempte de harcèlement, +quels que soient l'âge, la taille, le handicap visible ou invisible, l'origine ethnique, les +caractéristiques sexuelles, l'identité et l'expression de genre, le niveau d'expérience, +l'éducation, le statut socio-économique, la nationalité, l'apparence personnelle, la race, la +religion ou l'identité et l'orientation sexuelle. + +Nous nous engageons à agir et interagir de manière à contribuer à une communauté ouverte, +accueillante, diverse, inclusive et saine. + +## Nos critères + +Exemples de comportements qui contribuent à un environnement positif : + +- faire preuve d'empathie et de bienveillance envers les autres ; +- respecter les opinions, points de vue et expériences divergents ; +- donner et accepter avec grâce les critiques constructives ; +- assumer ses erreurs, s'en excuser auprès des personnes affectées et en tirer les leçons ; +- se concentrer sur ce qui est le mieux pour la communauté, pas seulement pour soi. + +Exemples de comportements inacceptables : + +- langage ou imagerie sexualisés, et avances sexuelles de quelque nature que ce soit ; +- trolling, commentaires insultants ou désobligeants, attaques personnelles ou politiques ; +- harcèlement public ou privé ; +- publication d'informations privées de tiers (adresse physique ou électronique) sans autorisation + explicite ; +- toute conduite qui pourrait raisonnablement être considérée comme inappropriée dans un cadre + professionnel. + +## Responsabilités d'application + +Les responsables du projet doivent clarifier et faire respecter ces critères, et prendront des +mesures correctives appropriées et équitables en réponse à tout comportement jugé inapproprié, +menaçant, offensant ou nuisible. + +Ils ont le droit et la responsabilité de supprimer, modifier ou rejeter les commentaires, commits, +code, modifications du wiki, issues et autres contributions non alignés sur ce code de conduite, +et communiqueront les raisons de leurs décisions de modération le cas échéant. + +## Portée + +Ce code de conduite s'applique à tous les espaces du projet — issues, pull requests, discussions, +code et documentation — ainsi qu'aux espaces publics où une personne représente le projet. + +## Application + +Les comportements abusifs, harcelants ou autrement inacceptables peuvent être signalés aux +responsables du projet à l'adresse **alban.pasquelin@gmail.com**. Toutes les plaintes seront +examinées et instruites rapidement et équitablement. Les responsables sont tenus au respect de la +vie privée et de la sécurité de la personne ayant signalé un incident. + +## Attribution + +Ce code de conduite est adapté du [Contributor Covenant](https://www.contributor-covenant.org), +version 2.1, disponible à l'adresse +. diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..1b9ee76 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,96 @@ +# Contribuer à plugingsMap3D + +Merci de l'intérêt porté aux plugins officiels de [map3D](https://github.com/pasquelin/map3D) ! +Ce document décrit le strict nécessaire pour qu'une contribution soit fusionnable. + +Le projet est **francophone** : code, commentaires, JSDoc, docs et messages de commit sont +rédigés **en français**. Les identifiants restent en anglais (`enrichBuilding`, `apiKey`…). + +## Prérequis + +- **Node 22** et **pnpm** (la version est épinglée par `packageManager` dans le `package.json` racine) +- `pnpm install` à la racine — le monorepo couvre `packages/*` et `packages/*/example` + +## Le garde-fou : `pnpm validater` + +```bash +pnpm validater # typecheck + lint + format:check + test +``` + +C'est **exactement** ce que rejoue la CI sur chaque PR. Une PR dont `validater` échoue ne peut pas +être fusionnée — lance-le en local avant de pousser. + +| Commande | Effet | +|---|---| +| `pnpm build` | build lib de chaque package (`dist/` : ESM + CJS + `.d.ts`) | +| `pnpm typecheck` | `tsc --noEmit` par package | +| `pnpm test` | Vitest (tests colocalisés `*.test.ts`) | +| `pnpm lint` / `pnpm format` | ESLint / Prettier | +| `pnpm --filter @pasquelin/map3d-plugin--example dev` | lance l'exemple d'un plugin | + +## Modèle de branches + +- **`develop`** est la base d'intégration : une feature part de `develop` et y retourne **par PR**. +- **`main`** est la branche de release : elle ne reçoit que les fusions de release et les tags `vX.Y.Z`. + +Une feature = une branche = un **`git worktree` isolé**. Jamais deux sessions dans le même +working tree : les index se marchent dessus. + +```bash +git worktree add ../plugingsMap3D-feat-x -b feat/x develop +# … commits sur feat/x … → PR vers develop +git worktree remove ../plugingsMap3D-feat-x +``` + +Ajoute les fichiers **par chemin explicite** (`git add packages/windy/src/index.ts`), pas `git add -A`. + +## Messages de commit + +Convention [Conventional Commits](https://www.conventionalcommits.org/fr/), en français : + +``` +feat(windy): filtre les webcams hors service +fix(geopf): gère la réponse WFS vide +docs(readme): tableau des plugins +chore(release): 0.2.0 +``` + +Portées usuelles : `geopf`, `windy`, `plan-3d`, `template`, `ci`, `docs`, `build`, `release`. + +## Conventions de code + +- **Point d'entrée public** de chaque package : `src/index.ts`. +- **Style Prettier** : pas de `;`, guillemets simples, `printWidth: 120`, `trailingComma: all`. +- **`any` interdit** (`@typescript-eslint/no-explicit-any: error`), **`type` jamais `interface`**, + `strict` + `noUncheckedIndexedAccess`. Paramètre volontairement ignoré : préfixe `_`. +- Les peerDependencies (`react`, `react-dom`, `three`, `@pasquelin/map3d`) sont **externalisées** — + ne rien en embarquer dans un `dist/`. +- Tests **colocalisés** `*.test.ts`. Commentaires courts, qui expliquent le *pourquoi*. +- **Aucun secret committé** : une clé d'API vit dans l'`example/.env` (gitignoré), documentée sans + valeur réelle dans `example/.env.example`. + +## Ajouter un plugin + +1. `cp -r packages/plugin-template packages/mon-plugin`, puis renommer `name` et `meta.id`. +2. Choisir **une** voie du contrat (`enrich`, `markers` ou `layer`) — voir le + [contrat de plugin](https://github.com/pasquelin/map3D/blob/main/docs/fr/PLUGINS.md). +3. Écrire son `README.md`, son exemple exécutable dans `example/` et ses tests. +4. Le laisser **`private: true`** par défaut. Pour le rendre publiable : retirer `private`, + compléter le packaging (`exports`, `files` slim, `publishConfig.provenance`, `LICENSE` MIT), + l'intégrer à la version unifiée et aux étapes `publish` de `.github/workflows/release.yml`. + +> Le tout premier publish d'un paquet neuf ne peut pas passer par l'OIDC seul (le trusted publisher +> s'attache à un paquet **existant**) : il faut un `NPM_TOKEN` temporaire, puis configurer le +> trusted publisher et retirer le token. + +## Ouvrir une PR + +- Cible **`develop`**, titre au format Conventional Commits. +- Décris le *pourquoi*, pas seulement le *quoi* ; capture d'écran ou GIF si l'effet est visuel. +- `pnpm validater` vert, CHANGELOG mis à jour sous `## [Non publié]` si le changement est visible. +- Une PR = un sujet. Les refactos opportunistes vont dans leur propre PR. + +## Signaler un bug ou proposer une idée + +Passe par les [issues](https://github.com/pasquelin/plugingsMap3D/issues) et leurs gabarits. +Pour une **faille de sécurité**, ne pas ouvrir d'issue publique : voir [SECURITY.md](SECURITY.md). diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..de45e57 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,73 @@ +name: 🐛 Bug +description: Signaler un comportement incorrect d'un plugin +labels: ["bug", "à trier"] +body: + - type: markdown + attributes: + value: | + Merci pour le signalement ! Pour une **faille de sécurité**, n'ouvrez pas d'issue publique : + voir [SECURITY.md](https://github.com/pasquelin/plugingsMap3D/blob/main/.github/SECURITY.md). + + - type: dropdown + id: package + attributes: + label: Plugin concerné + options: + - "@pasquelin/map3d-plugin-geopf" + - "@pasquelin/map3d-plugin-windy" + - "@pasquelin/map3d-plugin-plan-3d" + - "@pasquelin/map3d-plugin-template" + - Monorepo (build, CI, outillage) + validations: + required: true + + - type: textarea + id: description + attributes: + label: Ce qui se passe + description: Décrivez le comportement observé, et ce que vous attendiez à la place. + validations: + required: true + + - type: textarea + id: reproduction + attributes: + label: Étapes de reproduction + description: | + Idéalement à partir de l'exemple du plugin : + `pnpm --filter @pasquelin/map3d-plugin--example dev` + placeholder: | + 1. Lancer l'exemple … + 2. Activer le plugin depuis le hub … + 3. Cliquer sur … + 4. Observer … + validations: + required: true + + - type: textarea + id: versions + attributes: + label: Versions + description: Sortie de `npm ls @pasquelin/map3d @pasquelin/map3d-plugin- react three`, plus Node et le navigateur. + render: text + validations: + required: true + + - type: textarea + id: logs + attributes: + label: Console / réseau + description: Erreurs de la console, et la réponse du service tiers (WFS Géoplateforme, API Windy) si l'appel est en cause. + render: text + + - type: checkboxes + id: checks + attributes: + label: Vérifications + options: + - label: J'ai cherché une issue existante sur le même sujet. + required: true + - label: Je suis sur la dernière version publiée du plugin. + required: true + - label: Mon rapport ne contient aucune clé d'API ni secret. + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..d515191 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: false +contact_links: + - name: 📖 Contrat de plugin map3D + url: https://github.com/pasquelin/map3D/blob/main/docs/fr/PLUGINS.md + about: Comment écrire un plugin — voies enrich / markers / layer, definePlugin. + - name: 🗺️ Question sur la lib map3D + url: https://github.com/pasquelin/map3D/issues + about: Le bug concerne la carte elle-même (caméra, tuiles, markers, thème) et non un plugin. + - name: 🔒 Faille de sécurité + url: https://github.com/pasquelin/plugingsMap3D/security/advisories/new + about: Signalement privé — n'ouvrez jamais d'issue publique pour une vulnérabilité. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..7985906 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,45 @@ +name: 💡 Évolution +description: Proposer une amélioration d'un plugin existant +labels: ["enhancement", "à trier"] +body: + - type: dropdown + id: package + attributes: + label: Plugin concerné + options: + - "@pasquelin/map3d-plugin-geopf" + - "@pasquelin/map3d-plugin-windy" + - "@pasquelin/map3d-plugin-plan-3d" + - "@pasquelin/map3d-plugin-template" + - Monorepo (build, CI, outillage) + validations: + required: true + + - type: textarea + id: probleme + attributes: + label: Le problème + description: Quel besoin réel n'est pas couvert aujourd'hui ? Décrivez l'usage, pas la solution. + validations: + required: true + + - type: textarea + id: solution + attributes: + label: La solution envisagée + description: API souhaitée, option de configuration, exemple de code. + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives et contournements + description: Ce que vous faites en attendant, et pourquoi ça ne suffit pas. + + - type: checkboxes + id: rupture + attributes: + label: Compatibilité + options: + - label: Cette évolution casserait l'API publique existante. diff --git a/.github/ISSUE_TEMPLATE/new_plugin.yml b/.github/ISSUE_TEMPLATE/new_plugin.yml new file mode 100644 index 0000000..b02ec86 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/new_plugin.yml @@ -0,0 +1,55 @@ +name: 🧩 Nouveau plugin +description: Proposer un nouveau plugin officiel map3D +labels: ["nouveau plugin", "à trier"] +body: + - type: markdown + attributes: + value: | + Avant de proposer, lire le + [contrat de plugin](https://github.com/pasquelin/map3D/blob/main/docs/fr/PLUGINS.md) et + [CONTRIBUTING.md](https://github.com/pasquelin/plugingsMap3D/blob/main/.github/CONTRIBUTING.md). + Un plugin **tiers** n'a pas besoin de vivre ici : ce gabarit sert aux plugins **officiels**. + + - type: input + id: nom + attributes: + label: Nom proposé + placeholder: "@pasquelin/map3d-plugin-…" + validations: + required: true + + - type: dropdown + id: voie + attributes: + label: Voie du contrat + options: + - "enrich — complète un objet après une interaction" + - "markers — pose des markers depuis une source distante" + - "layer — pose sa propre 3D dans engine.scene" + validations: + required: true + + - type: textarea + id: valeur + attributes: + label: Ce qu'il apporte + description: Quelle donnée, pour quel usage, pour qui ? + validations: + required: true + + - type: textarea + id: source + attributes: + label: Source de données + description: Service interrogé, licence des données, conditions d'utilisation, quotas, et si une clé d'API est nécessaire. + validations: + required: true + + - type: checkboxes + id: checks + attributes: + label: Faisabilité + options: + - label: La licence de la source autorise cet usage. + - label: Le plugin tient dans une seule voie du contrat. + - label: Je suis prêt·e à en assurer la maintenance. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..fce010c --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,36 @@ +## Ce que fait cette PR + + + +Closes # + +## Plugin(s) concerné(s) + +- [ ] `@pasquelin/map3d-plugin-geopf` +- [ ] `@pasquelin/map3d-plugin-windy` +- [ ] `@pasquelin/map3d-plugin-plan-3d` +- [ ] `@pasquelin/map3d-plugin-template` +- [ ] Monorepo (build, CI, docs, outillage) + +## Type + +- [ ] `feat` — nouvelle fonctionnalité +- [ ] `fix` — correction de bug +- [ ] `docs` — documentation seule +- [ ] `refactor` / `perf` / `test` / `chore` / `ci` +- [ ] ⚠️ **Rupture d'API** (documentée dans le CHANGELOG) + +## Vérifications + +- [ ] La PR cible **`develop`** (et non `main`). +- [ ] Le titre suit les [Conventional Commits](https://www.conventionalcommits.org/fr/). +- [ ] `pnpm validater` passe en local (typecheck + lint + format:check + test). +- [ ] Des tests couvrent le changement (`*.test.ts` colocalisés). +- [ ] L'exemple du plugin tourne toujours : `pnpm --filter @pasquelin/map3d-plugin--example dev`. +- [ ] `CHANGELOG.md` mis à jour sous `## [Non publié]` si le changement est visible pour l'utilisateur. +- [ ] Aucune clé d'API ni secret committé ; aucun `any` introduit. +- [ ] Aucune peerDependency (`react`, `react-dom`, `three`, `@pasquelin/map3d`) ajoutée aux `dependencies`. + +## Comment tester + + diff --git a/.github/SECURITY.md b/.github/SECURITY.md new file mode 100644 index 0000000..a4c5fbd --- /dev/null +++ b/.github/SECURITY.md @@ -0,0 +1,60 @@ +# Politique de sécurité + +## Versions supportées + +Les plugins publiables (`@pasquelin/map3d-plugin-geopf`, `@pasquelin/map3d-plugin-windy`) partagent +une **version unifiée**. Le projet est en `0.x` : seule la **dernière version publiée** reçoit des +correctifs de sécurité. + +| Version | Supportée | +|---|---| +| dernière `0.x` publiée | ✅ | +| versions antérieures | ❌ | + +Vérifier la version courante : `npm view @pasquelin/map3d-plugin-geopf version`. + +## Signaler une faille + +**N'ouvrez pas d'issue publique** pour une vulnérabilité. + +1. De préférence, utilisez le + [signalement privé de GitHub](https://github.com/pasquelin/plugingsMap3D/security/advisories/new) + (onglet *Security* → *Report a vulnerability*). +2. À défaut, écrivez à **alban.pasquelin@gmail.com** avec `[SECURITY]` en objet. + +Merci d'inclure : la version concernée, les étapes de reproduction, l'impact estimé et, si possible, +un correctif ou une piste. Réponse sous **72 h**, correctif publié dès que possible sous forme d'une +nouvelle version (une version publiée n'est jamais republiée). + +## Périmètre + +Sont dans le périmètre de ce dépôt : + +- le code des packages `packages/*/src` publié sur npm ; +- la chaîne de publication (`.github/workflows/release.yml`, provenance OIDC) ; +- l'exposition involontaire d'un secret dans un paquet publié ou dans le dépôt. + +Sont **hors** périmètre : les vulnérabilités de la lib hôte +[map3D](https://github.com/pasquelin/map3D) (à signaler sur son propre dépôt), celles des services +tiers interrogés (Géoplateforme IGN, Windy) et celles des dépendances amont — à signaler à leurs +mainteneurs, même si elles remontent ici via `pnpm audit`. + +## Clés d'API — le rappel qui compte + +`@pasquelin/map3d-plugin-windy` requiert une clé d'API Windy. Elle n'est **jamais** committée : +elle vit dans `packages/windy/example/.env` (gitignoré), documentée sans valeur réelle dans +`.env.example`, et le hub des plugins la traite comme un champ `secret` (jamais affichée en clair). + +⚠️ Dans une application **web**, toute clé embarquée dans le bundle est lisible par le client : +pour un déploiement public, faites transiter les appels par un proxy côté serveur et restreignez la +clé chez le fournisseur. + +## Intégrité des paquets + +Les paquets sont publiés par GitHub Actions via **npm Trusted Publishing (OIDC)** — aucun token de +publication — avec **provenance signée**. Vérifier : + +```bash +npm audit signatures +npm view @pasquelin/map3d-plugin-geopf --json | grep -i provenance +``` diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..bc4914a --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,38 @@ +# Veille de dépendances : un lot par semaine, groupé pour éviter le bruit de PR. +version: 2 +updates: + # Dépendances npm du monorepo (racine + packages + exemples). + - package-ecosystem: npm + directories: + - "/" + - "/packages/*" + - "/packages/*/example" + schedule: + interval: weekly + day: monday + open-pull-requests-limit: 5 + commit-message: + prefix: "chore(deps)" + prefix-development: "chore(deps-dev)" + groups: + outillage: + patterns: ["typescript", "eslint*", "typescript-eslint", "prettier", "vite*", "vitest", "@vitejs/*"] + types: + patterns: ["@types/*"] + ignore: + # Peer deps : la contrainte est volontairement large, on ne la bump pas automatiquement. + - dependency-name: "react" + - dependency-name: "react-dom" + - dependency-name: "three" + - dependency-name: "@pasquelin/map3d" + + # Actions du workflow CI/release. + - package-ecosystem: github-actions + directory: "/" + schedule: + interval: monthly + commit-message: + prefix: "ci(deps)" + groups: + actions: + patterns: ["*"] diff --git a/README.md b/README.md index 3b1b823..0c3cfe2 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,156 @@ -# plugingsMap3D +
-Monorepo des plugins officiels de [map3D](https://github.com/…) — `@pasquelin/map3d-plugin-*`. -**1 plugin = 1 package** (`packages//`) + son exemple (`packages//example/`). +### plugingsMap3D — les plugins officiels de [map3D](https://github.com/pasquelin/map3D) -## Dev -- Dépend de `@pasquelin/map3d` (npm, peerDep `^0.2.0`) — plus besoin du sibling `map3D` buildé. -- `pnpm install` · `pnpm validater` · `pnpm build` · exemple d'un plugin : `pnpm --filter @pasquelin/map3d-plugin--example dev`. -- Publication : cf. `CLAUDE.md` (version unifiée + tag `vX.Y.Z` → release OIDC). +*Official plugins for map3D — real data poured into a React 3D map: French BDTOPO buildings on pick, live public webcams around the view.* -Registre des plugins officiels : `map3D/docs/{fr,en}/PLUGINS.md`. +[![CI](https://github.com/pasquelin/plugingsMap3D/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/pasquelin/plugingsMap3D/actions/workflows/ci.yml) +[![npm geopf](https://img.shields.io/npm/v/@pasquelin/map3d-plugin-geopf?label=geopf&logo=npm&color=cb3837)](https://www.npmjs.com/package/@pasquelin/map3d-plugin-geopf) +[![npm windy](https://img.shields.io/npm/v/@pasquelin/map3d-plugin-windy?label=windy&logo=npm&color=cb3837)](https://www.npmjs.com/package/@pasquelin/map3d-plugin-windy) +[![React 19](https://img.shields.io/badge/React-19-61DAFB?logo=react&logoColor=white)](https://react.dev) +[![Three.js ≥0.169](https://img.shields.io/badge/Three.js-%E2%89%A50.169-000000?logo=three.js&logoColor=white)](https://threejs.org) +[![TypeScript strict](https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org) +[![License: MIT](https://img.shields.io/badge/license-MIT-1e6fbf)](LICENSE) + +**[Démo live map3D ↗](https://pasquelin.github.io/map3D/)** · **[Lib map3D ↗](https://github.com/pasquelin/map3D)** · **[Contrat plugin 🇫🇷](https://github.com/pasquelin/map3D/blob/main/docs/fr/PLUGINS.md)** · **[Plugin API 🇬🇧](https://github.com/pasquelin/map3D/blob/main/docs/en/PLUGINS.md)** · **[Changelog](CHANGELOG.md)** + +
+ +--- + +## Pourquoi ce dépôt + +[map3D](https://github.com/pasquelin/map3D) est une lib de cartographie 3D temps réel pour React. +Elle ne connaît **aucune** source de données métier : c'est le rôle des plugins. Ce monorepo +héberge les plugins **officiels**, publiés sous le scope `@pasquelin` — **1 plugin = 1 package** +(`packages//`) **+ son exemple exécutable** (`packages//example/`). + +Un plugin se branche sur l'une des trois **voies** du contrat `definePlugin` : + +| Voie | Ce qu'elle fait | Exemple ici | +|---|---|---| +| `enrich` | complète un objet de la carte après une interaction (pick de bâtiment) | `geopf` | +| `markers` | fournit des markers DOM à partir d'une source distante, rafraîchis sur la vue | `windy` | +| `layer` | accède directement à `engine.scene` / `engine.projection` pour poser sa 3D | `plan-3d` | + +## Les plugins + +| Package | Voie | Rôle | npm | +|---|---|---|---| +| [`@pasquelin/map3d-plugin-geopf`](packages/geopf) | `enrich` | Bâtiments France : au clic sur un bâtiment 3D, remonte les attributs officiels **BDTOPO** de la **Géoplateforme IGN** (nature, usage, hauteur, étages, matériaux…) via `useBuildingEnrichment()`. Le pick reste instantané, l'enrichissement se fait en tâche de fond. | [![npm](https://img.shields.io/npm/v/@pasquelin/map3d-plugin-geopf?color=cb3837&label=)](https://www.npmjs.com/package/@pasquelin/map3d-plugin-geopf) | +| [`@pasquelin/map3d-plugin-windy`](packages/windy) | `markers` | Webcams publiques réelles autour de la vue courante ([Windy Webcams API v3](https://api.windy.com/webcams)) : un marker par webcam, vignette en avatar, infobulle d'aperçu et menu (ouvrir / copier le lien). | [![npm](https://img.shields.io/npm/v/@pasquelin/map3d-plugin-windy?color=cb3837&label=)](https://www.npmjs.com/package/@pasquelin/map3d-plugin-windy) | +| [`@pasquelin/map3d-plugin-plan-3d`](packages/plan-3d) | `layer` | **Placeholder** de la voie `layer` : dépose un volume repère reprojeté chaque frame. Démontre le contrat, pas un produit. | privé | +| [`@pasquelin/map3d-plugin-template`](packages/plugin-template) | — | **Gabarit** à copier pour créer son propre plugin. | privé | + +Les deux paquets publiables partagent une **version unifiée** : un tag `vX.Y.Z` les publie ensemble. + +## Installation + +```bash +npm i @pasquelin/map3d @pasquelin/map3d-plugin-geopf +# ou : pnpm add … / yarn add … +``` + +`react`, `react-dom` (19), `three` (≥ 0.169) et `@pasquelin/map3d` (^0.2.0) sont des +**peerDependencies** — jamais bundlées par les plugins. + +## Démarrage rapide + +Un plugin se passe à `` ; il est **désactivé par défaut** et s'active depuis le hub des +plugins (menu Réglages) de map3D. + +```tsx +import { Map } from '@pasquelin/map3d' +import { geopfBatiments } from '@pasquelin/map3d-plugin-geopf' +import { windyWebcams } from '@pasquelin/map3d-plugin-windy' + + +``` + +Lire l'enrichissement `geopf` depuis un enfant de `` : + +```tsx +import { useBuildingEnrichment } from '@pasquelin/map3d' + +function BuildingInfo() { + const enrichment = useBuildingEnrichment() + return 
{JSON.stringify(enrichment, null, 2)}
+} +``` + +Chaque package a son README détaillé (options, sécurité de la clé API, limites) et son exemple : + +```bash +pnpm --filter @pasquelin/map3d-plugin-geopf-example dev +pnpm --filter @pasquelin/map3d-plugin-windy-example dev +``` + +## Créer son plugin + +```bash +cp -r packages/plugin-template packages/mon-plugin +# renommer `name` et `meta.id`, ajuster `config` et la voie utilisée +pnpm install && pnpm validater +``` + +Le [contrat de plugin](https://github.com/pasquelin/map3D/blob/main/docs/fr/PLUGINS.md) (`definePlugin`, +voies `enrich` / `markers` / `layer`) est documenté côté map3D. Pour proposer un plugin officiel +ici, voir [CONTRIBUTING.md](.github/CONTRIBUTING.md). + +## Développement + +Monorepo **pnpm** (Node 22). Prérequis : `pnpm install`. + +| Commande | Effet | +|---|---| +| `pnpm build` | build lib de chaque package (`dist/` : ESM + CJS + `.d.ts`) | +| `pnpm typecheck` | `tsc --noEmit` par package | +| `pnpm test` | Vitest (tests colocalisés `*.test.ts`) | +| `pnpm lint` / `pnpm format` | ESLint / Prettier | +| **`pnpm validater`** | typecheck + lint + format:check + test — **le garde-fou complet**, rejoué en CI | +| `pnpm version:plugins X.Y.Z` | bump unifié (racine + `geopf` + `windy`) | + +Le code, les commentaires et la documentation sont **en français**. `any` est interdit +(`strict` + `noUncheckedIndexedAccess`), `type` plutôt que `interface`. + +## Publication + +Publication **automatique** par GitHub Actions : pousser un tag `vX.Y.Z` publie les paquets +publiables sur npm, avec **provenance signée** via OIDC (npm Trusted Publishing — aucun token). +Détail du flux dans [CLAUDE.md](CLAUDE.md#mise-en-production-release-npm). + +## Contribuer + +Les features partent de **`develop`** et y retournent par PR (`main` est la branche de release). +Une feature = une branche = un **worktree** isolé. Lire +[CONTRIBUTING.md](.github/CONTRIBUTING.md), le [code de conduite](.github/CODE_OF_CONDUCT.md) et +la [politique de sécurité](.github/SECURITY.md). + +## Licence + +**MIT** © [Alban Pasquelin](https://github.com/pasquelin) — voir [LICENSE](LICENSE). +À noter : la lib map3D elle-même est sous licence **PolyForm Noncommercial**. --- -# plugingsMap3D (EN) +
+English summary + +Monorepo of the **official plugins for [map3D](https://github.com/pasquelin/map3D)**, a real-time +3D mapping library for React. **1 plugin = 1 package** (`packages//`) + its runnable example. + +- **[`@pasquelin/map3d-plugin-geopf`](packages/geopf)** — French building attributes (IGN BDTOPO, + WFS) resolved on 3D building pick, through the `enrich` lane. +- **[`@pasquelin/map3d-plugin-windy`](packages/windy)** — real public webcams around the current + view (Windy Webcams API v3), through the `markers` lane. +- `plan-3d` (layer-lane placeholder) and `plugin-template` (starter) stay private. + +`react`/`react-dom` 19, `three` ≥ 0.169 and `@pasquelin/map3d` ^0.2.0 are peer dependencies. +Builds ship ESM + CJS + types, published to npm with signed provenance. Source, comments and docs +are written in French. MIT licensed. + +```bash +npm i @pasquelin/map3d @pasquelin/map3d-plugin-geopf +``` -Monorepo for map3D's official plugins — `@pasquelin/map3d-plugin-*`. **1 plugin = 1 package** + its own example. -Depends on `@pasquelin/map3d` (npm peerDep `^0.2.0`). `pnpm install`, `pnpm validater`, `pnpm build`. +