@micheeeeel/yinyangapp 1.0.6 → 2.0.0

package/README.md

@@ -0,0 +1,105 @@
+# @micheeeeel/yinyangapp
+
+Visualisation « Sphères » (diagramme yin/yang + satellites) de l'équilibre des
+activités humaines vis-à-vis des Objectifs de Développement Durable.
+
+Deux usages :
+
+- **Page standalone** (`npm start`, déployée sur GitHub Pages) : l'application
+  complète (panneaux, pile d'actions, recherche…) bootstrapée par `src/main.ts`.
+- **Librairie npm** : une app hôte (ex. React) importe les fonctions de
+  `src/api.ts` pour obtenir un diagramme.
+
+## Installation dans une app hôte
+
+```bash
+npm install @micheeeeel/yinyangapp d3
+```
+
+`d3` (v7) est un **peer dependency** : il n'est pas embarqué dans le bundle, c'est
+l'app hôte qui le fournit — soit via son propre bundler (`import "d3"`, résolu
+automatiquement), soit en global `window.d3` si le bundle est chargé en `<script>`
+(voir `webpack.config.js` → `externals`).
+
+Importer le CSS une fois :
+
+```ts
+import "@micheeeeel/yinyangapp/dist/bundle.css";
+```
+
+## API
+
+```ts
+import {
+  createYinYangSvg,   // rendu hors écran → SVGSVGElement détaché (ou null)
+  createYinYangSvgs,  // idem, en lot
+  mountYinYang,       // diagramme vivant dans un conteneur de l'hôte → { controller, destroy }
+  mapCauseToInternalModel,
+  type Cause, type YinYangSvgConfig, type YinYangMountConfig,
+} from "@micheeeeel/yinyangapp";
+```
+
+`data` accepte une `Cause` (format métier : composantes → ODD → facettes avec
+`score`/`weight`) ou un `YinYangInternalModel` déjà adapté.
+
+Toutes ces fonctions touchent le DOM : à appeler côté client uniquement
+(`useEffect` en React, pas de SSR).
+
+### Exemple React
+
+```tsx
+import { useEffect, useRef } from "react";
+import { createYinYangSvg, type Cause } from "@micheeeeel/yinyangapp";
+
+export function YinYang({ data, size = 400 }: { data: Cause; size?: number }) {
+  const ref = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    const host = ref.current;
+    if (!host) return;
+    const svg = createYinYangSvg({ data, viewData: { minEdge: size } });
+    if (svg) host.appendChild(svg);
+    return () => { host.innerHTML = ""; };
+  }, [data, size]);
+  return <div ref={ref} />;
+}
+```
+
+Pour un diagramme interactif, préférer `mountYinYang({ data, container: ref.current })`
+et appeler `destroy()` dans le cleanup du `useEffect`.
+
+### Film léger pour markers de carte
+
+`createYinYangFilmSvg` « cuit » un tour complet de l'étincelle périmètre (sans
+satellites, sans glow) en un **SVG autonome sans JavaScript** : rotation CSS de
+l'étincelle + flip-book de calques pré-rendus pour les bascules de composante.
+Coût runtime par instance ≈ un GIF ; prévu pour des dizaines de markers Mapbox.
+
+```ts
+import { createYinYangFilmSvg } from "@micheeeeel/yinyangapp";
+
+const film = createYinYangFilmSvg({
+  data,                    // Cause ou YinYangInternalModel
+  size: 120,               // px
+  rotationDurationMs: 6000,
+  transitionFrames: 4,     // images par bascule (0 = switch immédiat)
+});
+new mapboxgl.Marker({ element: film }).setLngLat([lng, lat]).addTo(map);
+```
+
+- Cuire **une fois par lieu** (~300 ms) et cloner : `film.cloneNode(true)`.
+- Vitesse par instance sans recuire : `clone.style.setProperty("--yy-rotation", "5200ms")`.
+- Ordres de grandeur (4 composantes, 120 px) : `transitionFrames: 4` → ~170 Ko brut /
+  16 Ko gzip / 1 700 nœuds ; `transitionFrames: 0` → ~40 Ko / 350 nœuds.
+- Survol / sélection : remplacer le film par `mountYinYang` (diagramme vivant),
+  puis revenir au film.
+
+Guide d'intégration détaillé (React + Mapbox, cache, survol) : [docs/integration-yvy-frontend.md](docs/integration-yvy-frontend.md).
+
+## Développement
+
+```bash
+npm start        # dev server
+npm test         # vitest
+npm run build    # dist/bundle.js + dist/bundle.css + dist/types/
+npm publish --access public
+```