@micheeeeel/yinyangapp 2.0.4 → 2.1.0

package/dist/types/adapters/yasuniCauseAdapter.d.ts

@@ -0,0 +1,12 @@
+import type { Composante } from "../data/yasuni_cause";
+import type { Cause } from "../interfaces/ICauseModel";
+/**
+ * Adapte le catalogue Composante[] (format yasuni_cause.ts) vers le format
+ * Cause attendu par validateCauseGraph et mapCauseToInternalModel.
+ * Les scores initiaux sont neutres (0.5 = 50 % de tension), les poids valent 1
+ * par satellite tant qu'aucune valeur n'est renseignée dans les données.
+ */
+export declare function composantesToCause(composantes: Composante[], id?: string, name?: string): Cause;
+/** La `Cause` du Yasuní, fraîchement construite à chaque appel (l'hôte peut
+ *  la muter sans effet de bord). `id` par défaut : "yasuni". */
+export declare function getYasuniCause(id?: string): Cause;

package/dist/types/animations/AnimationsMngr.d.ts

@@ -5,9 +5,56 @@ export declare class AnimationsMngr {
     startAll(): void;
     setRotationDuration(durationMs: number): void;
     revertRotation(component: IYinYangController): void;
-    stopRotation(component: IYinYangController): void;
+    /**
+     * Arrête la rotation. Avec `rampMs > 0` et une rotation en cours, le
+     * yin-yang continue sa course et décélère à taux constant pour s'arrêter
+     * exactement sur sa position de base (angle multiple de 360°) — voir
+     * `beginHomingStop`. `rampMs` omis (0) ou aucune rotation active → arrêt
+     * immédiat, comportement historique (utilisé tel quel par le benchmark et
+     * les changements de composant).
+     */
+    stopRotation(component: IYinYangController, rampMs?: number): void;
+    /**
+     * Arrête la rotation en rejoignant la position de base dans une durée
+     * FIXE `durationMs`, quelle que soit la distance restante — troisième mode
+     * d'arrêt, entre l'instantané (`rampMs=0`) et le freinage "confort"
+     * (`stopRotation` avec `rampMs>0`, qui peut faire durer l'arrêt jusqu'à
+     * near un tour complet). Voir `beginFastHomingStop`.
+     */
+    stopRotationFast(component: IYinYangController, durationMs: number): void;
+    /**
+     * Calibre un freinage à décélération constante qui ramène la rotation
+     * exactement sur un multiple de 360° (donc visuellement sur la position de
+     * base) au moment précis où la vitesse atteint 0 — pas de saut final.
+     *
+     * On vise en priorité le prochain passage par la position de base dans le
+     * sens courant (distance `remainingToZero`, 0 à 360°). Si cette distance
+     * est trop courte pour freiner en douceur à la vitesse actuelle (durée
+     * naturelle < `rampMs`, ce qui donnerait un freinage brutal), on fait
+     * plutôt un tour de plus (`+360°`) pour laisser le temps de décélérer
+     * confortablement — `rampMs` sert donc de plancher de confort, pas d'une
+     * durée cible stricte : la distance à parcourir pour retomber pile sur la
+     * position de base prime.
+     */
+    private beginHomingStop;
+    /**
+     * Calibre un freinage qui rejoint TOUJOURS le prochain passage par la
+     * position de base dans le sens courant (jamais de tour supplémentaire —
+     * contrairement à `beginHomingStop`), dans la durée fixe `durationMs`
+     * choisie par l'utilisateur — voir `computeFastStopProfile`.
+     */
+    private beginFastHomingStop;
+    private finalizeStop;
     private resetRotationFrame;
-    animate(component: IYinYangController, clockWise: boolean, time?: number): void;
+    /**
+     * Démarre (ou modifie en vol) la rotation. Avec `rampMs > 0`, la vitesse
+     * angulaire part de sa valeur courante (0 si à l'arrêt) et chasse
+     * progressivement la vitesse cible déduite de `time`/`clockWise` — un appel
+     * pendant qu'un arrêt progressif est en cours ré-accélère en douceur depuis
+     * la vitesse déjà atteinte, sans à-coup. `rampMs` omis (0) → vitesse cible
+     * appliquée instantanément, comportement historique.
+     */
+    animate(component: IYinYangController, clockWise: boolean, time?: number, rampMs?: number): void;
     private startRotationLoop;
     private applyRotationFrame;
     private applyRotationToYinYangGroup;

package/dist/types/animations/fastHomingStop.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Calcule un profil de vitesse qui ramène une rotation (spin ou orbite) pile
+ * sur sa position de base — distance `distance` (>0, dans le sens courant) —
+ * dans une durée totale FIXE `targetDurationMs` choisie par l'utilisateur,
+ * quelle que soit cette distance. C'est le troisième mode d'arrêt ("Accéléré")
+ * : contrairement au freinage "confort" (décélération à taux constant depuis
+ * la vitesse courante, qui peut prendre jusqu'à near un tour complet si la
+ * distance restante est grande), celui-ci respecte toujours le budget de
+ * temps demandé, quitte à accélérer au-delà de la vitesse de croisière.
+ *
+ * Utilisé identiquement par AnimationsMngr (spin, en degrés) et
+ * ChildrenOrbitManager (orbite, en radians) — les unités n'ont pas
+ * d'importance ici tant que `v0Mag`, `distance` et `targetDurationMs` sont
+ * exprimés de façon cohérente entre eux (deg/ms + deg, ou rad/ms + rad).
+ *
+ * Deux formes possibles :
+ * - "decel" : la décélération constante "naturelle" (celle qui ramènerait à
+ *   vitesse nulle exactement à la distance `distance`) prend déjà moins de
+ *   temps que `targetDurationMs` — on l'utilise telle quelle, ce qui termine
+ *   AVANT l'échéance plutôt que d'artificiellement étirer l'arrêt.
+ * - "triangle" : cette décélération naturelle prendrait plus de temps que le
+ *   budget imposé — on accélère d'abord jusqu'à une vitesse de pointe `vp`
+ *   (calculée pour que la distance totale tombe pile juste), puis on
+ *   décélère jusqu'à 0, les deux phases se partageant exactement
+ *   `targetDurationMs` avec la même magnitude d'accélération. Cette
+ *   contrainte (vitesse toujours ≥ vitesse de départ ou ≥ 0) garantit que la
+ *   vitesse ne redevient jamais négative en cours de route — un simple
+ *   polynôme cubique satisfaisant les 4 contraintes aux bords (position et
+ *   vitesse de départ/arrivée) peut sinon, dans certains cas, brièvement
+ *   repartir en arrière avant de revenir pile sur la cible.
+ */
+export type FastStopProfile = {
+    kind: "decel";
+    v0Mag: number;
+    accel: number;
+    durationMs: number;
+} | {
+    kind: "triangle";
+    v0Mag: number;
+    /** Vitesse de pointe atteinte en fin de phase d'accélération. */
+    vp: number;
+    /** Durée de la phase d'accélération (0 à vp). */
+    t1: number;
+    /** Accélération de la phase 1 (peut être ~0 si t1 ~ 0). */
+    a1: number;
+    /** Décélération (magnitude) de la phase 2 (vp → 0). */
+    a2: number;
+    /** Distance déjà parcourue à la fin de la phase 1 — sert de base à la
+     *  phase 2 (voir evaluateFastStopProfile). */
+    distPhase1: number;
+    durationMs: number;
+};
+export declare function computeFastStopProfile(v0Mag: number, distance: number, targetDurationMs: number): FastStopProfile;
+export declare function evaluateFastStopProfile(profile: FastStopProfile, elapsedMs: number): {
+    speedMag: number;
+    distanceTraveled: number;
+};

package/dist/types/animations/fastHomingStop.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/api-film.d.ts

@@ -21,6 +21,13 @@ export interface YinYangFilmConfig {
      *  clic sur la facette). Défaut : true. `false` = bordure neutre unique,
      *  sans calque de bordure par composante (film plus léger). */
     highlightActiveSegment?: boolean;
+    /** Rend l'image figée du statut Idle (aucune facette active, illustration
+     *  neutre — Homme de Vitruve — à la place du yin/yang, anneau de bordure
+     *  non survolé, aucune étincelle) au lieu du film animé habituel. Mêmes
+     *  calques que YinYangDrawer.refreshIdleSphereOverlay, capturés une seule
+     *  fois : ni <style>, ni keyframes, ni étincelle — coût runtime nul, pour
+     *  les marqueurs de carte qui n'ont pas besoin d'animation. Défaut : false. */
+    idle?: boolean;
 }
 /** Cuit un tour complet et renvoie un <svg> autonome (keyframes inlinées). */
 export declare function createYinYangFilmSvg(config: YinYangFilmConfig): SVGSVGElement;

package/dist/types/api-random.d.ts

@@ -0,0 +1,32 @@
+import type { Cause } from "./interfaces/ICauseModel";
+/** Intervalle inclusif [min, max]. */
+export type RandomRange = [min: number, max: number];
+export interface RandomCauseOptions {
+    /** Identifiant de la Cause produite (ex. id de la mission). Défaut : dérivé
+     *  de la graine, sinon "random-<n>". */
+    id?: string;
+    name?: string;
+    /** Graine : même graine ⇒ même Cause. Sans graine, tirage Math.random. */
+    seed?: string | number;
+    /** Nombre de composantes (arcs de facette). Défaut : [2, 7]. */
+    components?: RandomRange;
+    /** ODD par composante, tirés sans remise parmi les 17 (jamais deux fois le
+     *  même ODD dans une Cause, donc jamais deux fois la même couleur).
+     *  Défaut : [1, 3] — plafonné par les ODD restants. */
+    oddsPerComponent?: RandomRange;
+    /** Facettes (satellites) par ODD. Défaut : [1, 4]. */
+    cuttingsPerOdd?: RandomRange;
+    /** Score de chaque facette. Défaut : [0.15, 0.85]. */
+    score?: RandomRange;
+    /** Poids entier de chaque facette. Défaut : [1, 3]. */
+    weight?: RandomRange;
+}
+/**
+ * Construit une `Cause` aléatoire : 2 à 7 composantes (orientations yin/yang
+ * alternées), chacune avec des ODD distincts tirés parmi les 17 — la couleur
+ * de chaque arc est donc celle de l'ODD officiel — et un nombre aléatoire de
+ * facettes par ODD (scores et poids aléatoires).
+ *
+ * À passer telle quelle à `createYinYangFilmSvg`, `mountYinYang`, etc.
+ */
+export declare function createRandomCause(options?: RandomCauseOptions): Cause;

package/dist/types/api-random.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/api.d.ts

@@ -46,3 +46,6 @@ export declare function createYinYangSvg(config: YinYangSvgConfig): SVGSVGElemen
 export declare function createYinYangSvgs(configs: YinYangSvgConfig[]): (SVGSVGElement | null)[];
 export { createYinYangFilmSvg, createYinYangFilmSvgAsync } from "./api-film";
 export type { YinYangFilmConfig, YinYangFilmAsyncOptions } from "./api-film";
+export { createRandomCause } from "./api-random";
+export type { RandomCauseOptions, RandomRange } from "./api-random";
+export { getYasuniCause } from "./adapters/yasuniCauseAdapter";

package/dist/types/components/controller/YinYangController.d.ts

@@ -96,6 +96,11 @@ export declare class YinYangController implements IYinYangController {
     factory: IYinYangAppFactory;
     animator: IAnimator;
     private childControllers;
+    /** État de la rotation spin (voir startRotation/stopRotationAll) — non nul
+     *  tant que la rotation est active, pour que les enfants recréés en cours
+     *  de route (createYinYangChildren) démarrent immédiatement avec les mêmes
+     *  réglages plutôt que de rester immobiles jusqu'à un prochain toggle. */
+    private rotationState;
     private childrenOrbitManager;
     private childOddMap;
     /**
@@ -380,7 +385,11 @@ export declare class YinYangController implements IYinYangController {
     private clearActiveChild;
     private animateChildren;
     private clearChildren;
-    setChildrenOrbitEnabled(isEnabled: boolean): void;
+    setChildrenOrbitEnabled(isEnabled: boolean, rampMs?: number): void;
+    /** Arrête l'orbite des satellites en rejoignant leur position de base dans
+     *  une durée fixe `durationMs` (troisième mode d'arrêt — voir
+     *  ChildrenOrbitManager.stopFast). */
+    stopChildrenOrbitFast(durationMs: number): void;
     setChildrenOrbitDuration(_durationMs: number): void;
     setChildrenOrbitSpeed(speed: number): void;
     setChildrenOrbitRadiusScale(scale: number): void;
@@ -946,6 +955,20 @@ export declare class YinYangController implements IYinYangController {
      * Rotations are reverted on click events.
      */
     InitializeAnimations(): void;
+    /**
+     * Démarre la rotation spin de manière centralisée : ce composant ET tous
+     * ses satellites actuellement déployés. L'état est mémorisé pour que les
+     * satellites recréés ensuite (createYinYangChildren, ex. changement de
+     * facette) démarrent aussitôt avec les mêmes réglages plutôt que de rester
+     * immobiles jusqu'au prochain toggle.
+     */
+    startRotation(clockWise: boolean, durationMs: number, rampMs?: number): void;
+    /** Arrête la rotation de ce composant ET de tous ses satellites actuels. */
+    stopRotationAll(rampMs?: number): void;
+    /** Arrête la rotation de ce composant ET de tous ses satellites en
+     *  rejoignant leur position de base dans une durée fixe `durationMs`
+     *  (troisième mode d'arrêt — voir AnimationsMngr.stopRotationFast). */
+    stopRotationAllFast(durationMs: number): void;
     highlightOddInChildren(oddId: string | null): void;
     highlightOddByStackItemId(stackItemId: string | null): void;
     /**

package/dist/types/components/controller/odd/ChildrenOrbitManager.d.ts

@@ -12,14 +12,62 @@ export declare class ChildrenOrbitManager {
     private deps;
     private readonly orbitService;
     private cachedOrbitData;
+    /** Temps de rampe (ms) courant pour l'accélération/décélération de la
+     *  boucle active — mémorisé pour que setSpeed() (vitesse changée en vol)
+     *  et la boucle elle-même s'y réfèrent sans avoir à le repasser partout. */
+    private rampMs;
+    /** Vitesse angulaire instantanée (rad/ms, signée) — chasse la vitesse
+     *  cible (state.children.orbitSpeed, en rad/s) au rythme imposé par
+     *  rampMs. */
+    private currentOmega;
+    private lastTimestamp;
+    /** Présent tant qu'un arrêt "retour à la position de base" est en cours :
+     *  l'orbite continue sa course pour s'arrêter exactement sur un multiple
+     *  de 2π (donc visuellement sur la position de base), plutôt que de couper
+     *  la vitesse puis sauter à angle 0. Même principe que AnimationsMngr :
+     *  `beginHomingStop` (mode "normal") décélère à taux constant, avec un tour
+     *  de plus si besoin de confort ; `beginFastHomingStop` (mode "Accéléré")
+     *  rejoint TOUJOURS le prochain passage par la position de base dans une
+     *  durée fixe choisie par l'utilisateur — voir `fastHomingStop.ts`. */
+    private homeBrake?;
     constructor(deps: ChildrenOrbitManagerDeps);
     invalidateCache(): void;
     buildOrbitData(): ChildrenOrbitEntry[];
     applyTransforms(angleOffset: number, orbitData?: ChildrenOrbitEntry[]): void;
-    setEnabled(isEnabled: boolean): void;
+    setEnabled(isEnabled: boolean, rampMs?: number): void;
+    /** Change la vitesse cible. Si une boucle est déjà active, elle relit
+     *  orbitSpeed à chaque frame et y converge au rythme de sa rampe en cours
+     *  (pas besoin de la redémarrer) — un changement de vitesse en vol est
+     *  donc lui aussi progressif plutôt que d'un coup. */
     setSpeed(speed: number): void;
     setRadiusScale(scale: number): void;
-    start(_durationMs: number): void;
-    stop(): void;
+    /**
+     * Démarre (ou modifie en vol) l'orbite. Avec `rampMs > 0`, la vitesse
+     * angulaire part de sa valeur courante (0 si à l'arrêt) et chasse
+     * progressivement `state.children.orbitSpeed` (relu à chaque frame — un
+     * arrêt en cours de freinage repris ici ré-accélère en douceur depuis la
+     * vitesse déjà atteinte). `rampMs` omis (0) → vitesse cible appliquée
+     * instantanément, comportement historique.
+     */
+    start(_targetSpeed: number, rampMs?: number): void;
+    /**
+     * Arrête l'orbite. Avec `rampMs > 0` et une orbite en cours, les satellites
+     * continuent leur course et décélèrent à taux constant pour s'arrêter
+     * exactement sur leur position de base (angle multiple de 2π) — voir
+     * `beginHomingStop`. `rampMs` omis (0) ou aucune orbite active → arrêt
+     * immédiat, comportement historique.
+     */
+    stop(rampMs?: number): void;
+    /**
+     * Arrête l'orbite en rejoignant la position de base dans une durée FIXE
+     * `durationMs`, quelle que soit la distance restante (jamais de tour
+     * supplémentaire) — voir AnimationsMngr.stopRotationFast pour le même
+     * mécanisme côté rotation spin.
+     */
+    stopFast(durationMs: number): void;
+    private computeRemainingToZero;
+    private beginHomingStop;
+    private beginFastHomingStop;
+    private finalizeStop;
 }
 export {};

package/dist/types/components/controls/VizControlsPanel.d.ts

@@ -9,6 +9,8 @@ export interface VizControlsDeps {
     renderColumnLayouts: () => void;
     animationConfig: {
         rotationDurationMs: number;
+        rotationRampMs: number;
+        orbitRampMs: number;
     };
 }
 export declare function mountVizControls(deps: VizControlsDeps): void;

package/dist/types/components/view/YinYangDrawer.d.ts

@@ -104,6 +104,23 @@ export declare class YinYangDrawer {
     private startOuterSparkAnimation;
     private clearOuterSpark;
     private normalizeAngle;
+    /**
+     * Peuple `filterEl` (un <filter> déjà créé, vide) avec un halo en deux
+     * couches derrière une copie nette de la source — pas juste un simple
+     * feGaussianBlur, qui ne fait qu'adoucir/affaiblir le trait lui-même sans
+     * rien ajouter autour : un flou seul redistribue l'énergie d'un trait fin
+     * sur une zone plus large, ce qui l'assombrit au lieu de "rayonner".
+     * Chaque couche est floutée puis son alpha est ré-amplifié (feColorMatrix,
+     * dernière ligne = multiplicateur d'alpha) pour qu'elle reste lumineuse
+     * malgré la dilution du flou, puis les deux couches sont fusionnées
+     * SOUS la source nette (feMerge, ordre = dessous → dessus).
+     *
+     * Les rayons de flou sont proportionnels à `scaleRadius` (le rayon du
+     * diagramme, pas une constante absolue en px) : un halo de quelques px ne
+     * se voit pas sur un grand diagramme mais engloutit tout sur un petit
+     * marqueur de carte — proportionnel, il reste visible dans les deux cas.
+     */
+    private buildSparkGlowFilter;
     private getOrCreateSparkLayer;
     /**
      * Triggers the "étincelle d'équilibre": two one-shot sparks running at
@@ -387,6 +404,22 @@ export declare class YinYangDrawer {
     private isArcVisibleForLabel;
     private renderOddArcLabels;
     private applyOddArcLabelCounterRotation;
+    /**
+     * Contre-tourne le score et le poids affichés en permanence dans le noyau
+     * du lobe dominant — sur le cercle central (renderFacetteStateLabel/
+     * renderFacetteWeightLabel) comme sur un satellite (renderChildStateLabel/
+     * renderChildWeightLabel, un seul des deux paires existe selon isChild) —
+     * même principe que applyOddArcLabelCounterRotation, mais appliqué
+     * directement sur l'élément (pivot = sa propre position x/y) plutôt que
+     * via un groupe wrapper : contrairement aux labels d'arc ODD, ces montants
+     * sont déjà positionnés par des attributs x/y directs, donc une rotation
+     * autour de ce même point annule l'orientation héritée du spin du lobe
+     * sans déplacer le montant. Chaque satellite ayant son propre YinYangDrawer,
+     * cette méthode tourne indépendamment pour chacun (voir AnimationsMngr, qui
+     * l'appelle via component.view.yinYangDrawer pour le composant en train de
+     * tourner, parent ou enfant).
+     */
+    private applyFacetteAmountLabelsCounterRotation;
     private getRotationAngleFromTransform;
     private getDisplayedArcAngles;
     /**

package/dist/types/config/animationConfig.d.ts

@@ -2,6 +2,13 @@ export declare const animationConfig: {
     componentSwitchDurationMs: number;
     borderColorCycleDurationMs: number;
     rotationDurationMs: number;
+    /** Temps de rampe (ms) par défaut pour l'accélération/décélération
+     *  progressive de la rotation Yin/Yang (voir AnimationsMngr.animate /
+     *  stopRotation) — 0 donnerait le comportement historique (à-coup). */
+    rotationRampMs: number;
+    /** Idem, pour l'orbite des satellites autour du cercle central (voir
+     *  ChildrenOrbitManager.start / stop) — même rôle, mécanisme séparé. */
+    orbitRampMs: number;
     forceFieldRevealDurationMs: number;
     forceFieldRevealChainStepMs: number;
     /** Fondu de sortie du champ de force d'action ET du champ d'événement quand

package/dist/types/interfaces/IYinYangController.d.ts

@@ -13,7 +13,10 @@ export interface IYinYangController {
     clearForceFieldDetails(): void;
     applyChildrenFitScale(): void;
     setChildrenEnabled(isEnabled: boolean): void;
-    setChildrenOrbitEnabled(isEnabled: boolean): void;
+    setChildrenOrbitEnabled(isEnabled: boolean, rampMs?: number): void;
+    /** Arrête l'orbite des satellites en rejoignant leur position de base dans
+     *  une durée fixe (troisième mode d'arrêt). */
+    stopChildrenOrbitFast(durationMs: number): void;
     setChildrenOrbitDuration(durationMs: number): void;
     setChildrenOrbitSpeed(speed: number): void;
     setChildrenOrbitRadiusScale(scale: number): void;
@@ -35,6 +38,15 @@ export interface IYinYangController {
     getParentKey(): string | null;
     generateChildKey(): string;
     InitializeAnimations(): void;
+    /** Démarre la rotation spin de ce composant ET de tous ses satellites
+     *  actuellement déployés — voir AnimationsMngr.animate pour la sémantique
+     *  de rampMs. */
+    startRotation(clockWise: boolean, durationMs: number, rampMs?: number): void;
+    /** Arrête la rotation spin de ce composant ET de tous ses satellites. */
+    stopRotationAll(rampMs?: number): void;
+    /** Arrête la rotation spin en rejoignant la position de base dans une
+     *  durée fixe (troisième mode d'arrêt). */
+    stopRotationAllFast(durationMs: number): void;
     highlightOddInChildren(oddId: string | null): void;
     refreshWeightPreviewPulse(): void;
     enterOddView(oddId: string): void;

package/dist/types/utils/InactivityTracker.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Suivi partagé de l'inactivité utilisateur (aucune interaction — souris,
+ * clavier, tactile — sur le document) : un seul jeu d'écouteurs global,
+ * plusieurs "watchers" indépendants peuvent s'y abonner avec leur propre
+ * délai (relu en direct, donc réglable via un slider sans se réabonner) et
+ * reçoivent onIdle() une fois ce délai écoulé sans activité, puis onActive()
+ * dès que l'activité reprend — jusqu'au prochain cycle idle → actif.
+ */
+declare class InactivityTracker {
+    private lastActivityAt;
+    private watchers;
+    private intervalId;
+    private readonly handleActivity;
+    /** S'abonne au suivi d'inactivité. `getThresholdMs` est relu à chaque
+     *  vérification (pas figé à l'abonnement), pour suivre un slider réglé en
+     *  direct. Retourne une fonction de désabonnement. */
+    register(getThresholdMs: () => number, onIdle: () => void, onActive: () => void): () => void;
+    private ensureListening;
+    private teardown;
+    private tick;
+}
+/** Instance unique partagée par tous les contrôles qui déclenchent un
+ *  comportement automatique après inactivité (voir VizControlsPanel). */
+export declare const inactivityTracker: InactivityTracker;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@micheeeeel/yinyangapp",
-  "version": "2.0.4",
+  "version": "2.1.0",
   "description": "A program to visualize human activity balance to reach Sustainable Development Objectives",
   "main": "dist/bundle.js",
   "types": "dist/types/main.d.ts",