From 0b6cc80f093995faadcc1f8b3961063975e9309e Mon Sep 17 00:00:00 2001 From: Pasquelin Alban Date: Thu, 10 Sep 2026 11:45:17 +0200 Subject: [PATCH] =?UTF-8?q?docs(repo):=20page=20GitHub=20pro=20=E2=80=94?= =?UTF-8?q?=20README=20enrichi=20+=20fichiers=20communautaires?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Le dépôt était public sans vitrine : README de 18 lignes, aucun fichier communautaire, profil GitHub à ~40 %. On donne au dépôt la même présentation que map3D. README : en-tête centré, badges (CI, npm geopf/windy, React 19, Three.js, TypeScript strict, MIT), tableau des trois voies du contrat, tableau des plugins avec leur rôle réel, installation, démarrage rapide, création d'un plugin, tableau des commandes, publication OIDC, résumé anglais repliable. Le lien vers map3D était un placeholder « github.com/… » — corrigé. .github/ : CONTRIBUTING (garde-fou `pnpm validater`, modèle develop/main, worktree obligatoire, Conventional Commits, ajout d'un plugin), CODE_OF_CONDUCT (Contributor Covenant 2.1), SECURITY (signalement privé, périmètre, rappel sur la clé Windy jamais committée, vérification de la provenance), trois gabarits d'issue (bug, évolution, nouveau plugin) + config sans issue vierge, gabarit de PR, et dependabot (npm groupé hebdomadaire, peer deps ignorées, actions mensuelles). Claude-Session: https://claude.ai/code/session_01LyrKrzZwquqPdLf5JYwycx --- .github/CODE_OF_CONDUCT.md | 61 ++++++++ .github/CONTRIBUTING.md | 96 +++++++++++++ .github/ISSUE_TEMPLATE/bug_report.yml | 73 ++++++++++ .github/ISSUE_TEMPLATE/config.yml | 11 ++ .github/ISSUE_TEMPLATE/feature_request.yml | 45 ++++++ .github/ISSUE_TEMPLATE/new_plugin.yml | 55 +++++++ .github/PULL_REQUEST_TEMPLATE.md | 36 +++++ .github/SECURITY.md | 60 ++++++++ .github/dependabot.yml | 38 +++++ README.md | 160 +++++++++++++++++++-- 10 files changed, 624 insertions(+), 11 deletions(-) create mode 100644 .github/CODE_OF_CONDUCT.md create mode 100644 .github/CONTRIBUTING.md create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/ISSUE_TEMPLATE/new_plugin.yml create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/SECURITY.md create mode 100644 .github/dependabot.yml 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`. +