@micheeeeel/yinyangapp 1.0.6 → 2.0.0

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

@@ -5,6 +5,7 @@ import { ICategory } from "../../interfaces/ICategory";
 import { IYinYangView } from "../../interfaces/IYinYangView";
 import { IYinOrYangPattern } from "../../interfaces/IYinOrYangPattern";
 import { IViewData } from "../../interfaces/IViewData";
+import { IYinYangGeometry, YinYangCategoryArcGeometry, YinYangSpikeGeometry } from "../../interfaces/IYinYangGeometry";
 export declare class ViewInitializer {
     graphicContainer: IGraphicElement;
     graphicStrategy: IGraphicsStrategy;
@@ -13,13 +14,66 @@ export declare class ViewInitializer {
         yin: IYinOrYangPattern;
         yang: IYinOrYangPattern;
     };
+    yinOrYangGroupGhost: {
+        yin: IYinOrYangPattern;
+        yang: IYinOrYangPattern;
+    };
     yinYangGroup: IGraphicElement;
+    childrenGroup: IGraphicElement;
+    facetteImageBackgroundGroup: IGraphicElement;
+    borderArcsGroup: IGraphicElement;
     smallCircleRadius: number;
     distanceFromChild: number;
     controller: IYinYangController;
     viewData: IViewData;
-    averageScore: number;
+    averageTension: number;
+    averageTensionGhost: number;
+    /** Somme des deltas de poids projetés sur CETTE facette (0 s'il n'y a
+     *  aucun aperçu en cours) — le pendant "poids" d'averageTensionGhost, que
+     *  le badge du ghost affiche à côté du delta de score. Écrit par
+     *  YinYangController.applyWeightPreview, qui est seul à connaître la pile
+     *  d'actions ; reste à 0 sur un satellite, dont les deltas sont déjà
+     *  affichés à côté de lui (ChildScoresDeltaRenderer). */
+    weightDeltaGhostTotal: number;
+    ghostVisible: boolean;
+    yinOpacity: number;
+    yangOpacity: number;
+    perimeterWaveOpacity: number;
+    numberOfWaves: number;
+    waveSpacing: number;
+    waveStrokeWidth: number;
+    ghostPerimeterStrokeWidth: number;
+    ghostPerimeterColor: string;
+    waveColorIncrease: string;
+    waveColorDecrease: string;
+    ghostPerimeterSolid: boolean;
+    basePulseEnabled: boolean;
+    ghostPulseDurationSec: number;
+    pulseMorphRatio: number;
+    waveTravelDurationSec: number;
+    /** Multiplicateur de taille du badge de deltas posé dans le noyau du lobe
+     *  dominant (score/poids projetés) — voir
+     *  YinYangDrawer.updateGhostDeltaBadge. Au-delà de 1, le texte déborde
+     *  volontairement du disque du noyau : il n'y a plus de plaque de fond à
+     *  respecter depuis que le noyau lui-même en tient lieu. */
+    ghostDeltaBadgeSizeBoost: number;
     categories: ICategory[];
+    /** Projection ghost des arcs de bordure (une par facette) — recalculée par
+     *  updateBorderSegmentGhost à partir des weightDelta actifs sur toute la
+     *  pile ; null quand aucun weightDelta n'est prévisualisé. */
+    borderSegmentsGhost: YinYangCategoryArcGeometry[] | null;
+    /** Projection ghost des arcs ODD (categories) de la facette actuellement
+     *  affichée — recalculée par updateCategoryGhost à partir des weightDelta
+     *  actifs sur les satellites de cette facette ; null quand aucun n'est
+     *  prévisualisé. Se recalcule naturellement pour la nouvelle facette après
+     *  un changement de composante (voir YinYangController.applyWeightPreview). */
+    categoriesGhost: ICategory[] | null;
+    /** Projection ghost des spikes (satellites de la facette/ODD affichée)
+     *  ayant un weightDelta actif — recalculée par updateSpikeGhost ; null
+     *  quand aucun n'est prévisualisé. Contrairement aux arcs, chaque spike
+     *  est indépendant (pas de renormalisation entre siblings), donc seuls
+     *  les spikes ciblés par un delta sont présents dans ce tableau. */
+    spikesGhost: YinYangSpikeGeometry[] | null;
     containerId: string;
     key: string;
     isChild: boolean;
@@ -29,9 +83,157 @@ export declare class ViewInitializer {
     borderThickness: number;
     borderInnerRadius: number;
     borderOuterRadius: number;
+    /** Poids de ce satellite relatif à la moyenne de sa fratrie (1 = moyenne),
+     *  voir IViewData.weightRatio. */
+    weightRatio: number;
+    /** Poids brut (échelle absolue), voir IViewData.weight. */
+    weight: number;
     offsetfromBorder: number;
-    isEnemy: boolean;
+    childrenScale: number;
+    oddGradientSpread: number;
+    oddGradientIntensity: number;
+    borderGlowIntensity: number;
+    borderSegmentWidthExpansion: number;
+    /** Arrondi des extrémités des arcs de bordure, exprimé en fraction de la
+     *  demi-épaisseur de la couronne : 0 = angles vifs (portion de camembert),
+     *  1 = capsule parfaite. Voir BorderDrawer.getSegmentCornerRadius. */
+    borderSegmentCornerRadius: number;
+    /** Intensité du biseau posé sur chaque arc (ombre au bord interne, crête
+     *  lumineuse au bord externe) qui remplace le relief que donnaient
+     *  autrefois les cercles concentriques tracés. 0 = arc plat. */
+    borderSegmentBevelIntensity: number;
+    /** Amplitude du soulèvement radial d'un arc survolé, en fraction de
+     *  l'épaisseur totale de la couronne. 0 = pas de soulèvement. */
+    borderSegmentHoverLift: number;
+    outerSparkIntensity: number;
+    outerSparkEnabled: boolean;
+    outerSparkLength: number;
+    outerSparkStrokeWidth: number;
+    outerSparkAngleRad: number;
+    outerSparkRotationDurationMs: number;
+    outerSparkGlowColor: string;
+    balanceSparkIntensity: number;
+    /** Tail length reached at the end of the primary spark's own path — it
+     *  starts at 0.1 and grows linearly with distance traveled (see
+     *  YinYangDrawer.startBalanceSparkAnimation). */
+    balanceSparkMaxLength: number;
+    balanceSparkStrokeWidth: number;
+    balanceSparkDurationMs: number;
+    /** Balance spark colors, keyed by the POLE each spark belongs to, not by
+     *  its primary/inverse role: the primary spark is always the dominant
+     *  lobe (see triggerBalanceSpark), so keying by role meant the dominant
+     *  pole kept the same color whether it was yin or yang. */
+    balanceSparkYangColor: string;
+    balanceSparkYinColor: string;
+    /** How far (px) the ember particles fly from the contact point during
+     *  the consume phase — see YinYangDrawer's ember shower. */
+    balanceSparkEmberDistance: number;
+    /** Multiplier applied to the embers' base radius. */
+    balanceSparkEmberSize: number;
+    /** Duration (ms) of one ember's pop-out-and-fade cycle — smaller is a
+     *  faster crackle. */
+    balanceSparkEmberSpeedMs: number;
+    balanceSparkEmberColor: string;
+    /** How concentrated the tadpole's swelling is toward the head: the
+     *  width at a point t (0=tail tip, 1=head) is maxWidth·t^power. Higher
+     *  = a longer thin tail with the bulk of the width packed near the
+     *  head; lower (near 1) = a more even, cone-like taper. */
+    balanceSparkTaperPower: number;
+    /** Fraction of the final max width the spark already has the instant
+     *  it's born (0 = a true point, growing entirely from nothing). */
+    balanceSparkBirthWidthRatio: number;
+    /** How many swimming tadpole fragments the lone survivor shatters into
+     *  — see the fragment block in YinYangDrawer.startBalanceSparkAnimation.
+     *  Clamped there to the fragment pool size (10). They split the remnant
+     *  (see balanceSparkDriftRemnantScale) evenly, so raising the count
+     *  shortens each of them. */
+    balanceSparkDriftFragmentCount: number;
+    /** Total length the lone survivor sheds when it shatters, as a fraction
+     *  of the disc radius at a FULL imbalance (score 1) — the actual remnant
+     *  is this scaled by the current facette's imbalance, then split evenly
+     *  between the fragments. A perfectly balanced facette sheds nothing. */
+    balanceSparkDriftRemnantScale: number;
+    /** Outward ("centrifugal") push, in px/ms, blended with the spark's own
+     *  tangential speed to set the shattered fragments' shared launch
+     *  direction — see the launch-vector block in
+     *  YinYangDrawer.startBalanceSparkAnimation. 0 launches them straight
+     *  along the tangent; higher values bend the launch further outward. */
+    balanceSparkDriftCentrifugalForce: number;
+    /** Gap (pre-scale px) between the border ring and the facette image ring,
+     *  and between that ring and the container edge. */
+    facetteImageMargin: number;
+    /** Percent of the thumbnail radius that stays fully opaque before the
+     *  vaporous fade to the edge begins. */
+    facetteImageFadeStart: number;
+    /** Opacity remaining at the very edge of the thumbnail (0 = fully invisible). */
+    facetteImageFadeEndOpacity: number;
+    /** Fraction (0.1-2) of the max available diameter actually used by the
+     *  heaviest facette's thumbnail. The thumbnail's inner edge stays fixed at
+     *  a constant distance from the border arc regardless of this value, so it
+     *  shrinks/grows toward the container edge only — values above 1
+     *  deliberately overshoot the reserved gap. */
+    facetteImageDiameterScale: number;
+    /** Exponent (0-1) applied to each facette's weight ratio (its weight over
+     *  the heaviest facette's weight) before it scales the thumbnail radius:
+     *  radius = baseRadius * weightRatio^curve. 1 = linear (proportional to
+     *  weight, the default, and the strongest shrinkage). Below 1 attenuates
+     *  the falloff — lighter facettes stay closer to full size — down to 0,
+     *  where every facette renders at the same full size regardless of weight. */
+    facetteImageWeightCurve: number;
+    /** Extra pre-scale px added to the thumbnail's distance from the diagram
+     *  center, on top of the fixed mid-gap position — moves it closer to
+     *  (negative) or further from (positive) the sphere, independent of margin
+     *  and diameter. */
+    facetteImageOffset: number;
+    oddContextLabelsVisible: boolean;
+    oddContextLabelsSuppressed: boolean;
+    oddLabelsCompact: boolean;
+    legendLabelsBgEnabled: boolean;
+    labelsFontAutoScale: number;
+    labelsFontScale: number;
+    componentLabelFontScale: number;
+    childStateDeltaFontScale: number;
+    oddLabelFontScale: number;
+    /** Score/poids de la facette affichés au centre du cercle principal (voir
+     *  YinYangDrawer.renderFacetteStateLabel/WeightLabel). */
+    facetteLabelFontScale: number;
+    /** Suffixe "/max" du score et du poids — mutualisé entre le libellé de
+     *  facette (renderFacetteStateLabel/WeightLabel) et celui de l'ODD
+     *  sélectionné (buildOddArcLabelLines) : un seul réglage pour les deux,
+     *  puisqu'ils occupent le même cercle et ne s'affichent jamais ensemble. */
+    facetteLabelSuffixVisible: boolean;
+    labelsTextShadowEnabled: boolean;
+    childLabelMaxLines: number;
+    oddLabelMaxLines: number;
+    oddLabelShortMaxChars: number;
+    geometry: IYinYangGeometry;
+    yinOrYangGroupCache?: {
+        yin: IYinOrYangPattern;
+        yang: IYinOrYangPattern;
+    };
     private areChildren;
+    private currentComponentIndex;
+    private animationSequence;
+    private isAnimationRunning;
+    private isDisplayingOddMode;
+    /**
+     * Returns whether the view is currently in ODD display mode.
+     */
+    isInOddMode(): boolean;
+    private displayingOddId;
+    /**
+     * Returns the currently displayed ODD id in ODD view mode, or null otherwise.
+     */
+    getDisplayingOddId(): string | null;
+    private animationRadii?;
+    private currentAnimation?;
+    private lastGhostDisplayKey;
+    private lastGhostOrderKey;
+    private lastGhostOrderParent;
+    private sliderElement;
+    private sliderValueElement;
+    private categoryFadeOpacities;
+    private readonly borderSegmentGapAngle;
     constructor(graphicStrategy: IGraphicsStrategy);
     /**
      * Initializes the graphical elements for the YinYang visualization.
@@ -43,7 +245,208 @@ export declare class ViewInitializer {
      * @param parent - The parent controller (optional), used to calculate child positions.
      */
     initializeGraphicElements(controller: IYinYangController, viewData: IViewData, parent?: IYinYangController): void;
+    /** Current absolute scale applied to globalGroup by the last resizeWholePattern()
+     *  call (e.g. the shrink reserving room for satellites). Lets code positioning
+     *  elements in the pre-scale coordinate space (like the facette image ring)
+     *  compute how much of that space maps to the container's actual edge. */
+    patternScale: number;
     resizeWholePattern(shrinkRatio: number): void;
+    setChildrenScale(scale: number): void;
+    private applyChildrenScale;
+    /**
+     * Updates the average tension and redraws the visualization.
+     *
+     * @param newTension - The new tension value (0 to 1).
+     */
+    updateTension(newTension: number): void;
+    /**
+     * Updates the ghost tension and redraws the ghost geometry only.
+     *
+     * @param newTension - The new ghost tension value (0 to 1).
+     */
+    updateGhostTension(newTension: number): void;
+    setGhostVisible(isVisible: boolean): void;
+    refreshGhostDisplay(): void;
+    /**
+     * Single source of truth for whether the ghost yin/yang should be visible:
+     * only on the central diagram (never on satellite children), only while the
+     * STACK tab is active, only when the user hasn't manually hidden it, and
+     * never while a blocking animation (rotation, facette/ODD switch, ...) is
+     * running on this controller — see YinYangController.beginBlockingAnimation.
+     */
+    isGhostDisplayAllowed(): boolean;
+    /**
+     * Redraws the YinYang geometry based on the current average tension.
+     * Keeps yinYangGroup intact while refreshing symbol groups and spikes.
+     */
+    private redrawYinYangGeometry;
+    /**
+     * Redraws the ghost Yin/Yang geometry without touching borders or spikes.
+     */
+    private redrawGhostGeometry;
+    /**
+     * Redraws the borders with the current relief intensity setting
+     */
+    redrawBorders(): void;
+    /**
+     * Refreshes the spikes visualization based on current visibility settings.
+     * This includes clearing old spikes and redrawing them.
+     */
+    refreshSpikes(): void;
+    /**
+     * Gets the current average tension.
+     *
+     * @returns The current average tension value.
+     */
+    getAverageTension(): number;
+    getAverageState(): number;
+    /** Poids agrégé de la facette courante : somme des poids de tous ses ODD
+     *  (même formule que getOddWeight, celle qui fixe la taille de chaque
+     *  arc — le chiffre affiché au centre du cercle explique donc la somme
+     *  des arcs qui l'entourent). */
+    getFacetteWeight(): number;
+    /** Plafond du poids agrégé : WEIGHT_MAX par satellite, tous ODD confondus
+     *  (même règle que le plafond par-ODD affiché sur les arcs, voir
+     *  buildOddArcLabelLines dans YinYangDrawer). */
+    getFacetteWeightMax(): number;
+    getCurrentComponentIndex(): number;
+    getCurrentComponentName(): string;
+    getCurrentComponentOrientation(): "yin" | "yang";
+    /**
+     * Centre courant (écran, repère de `globalGroup`) du sous-cercle yin ou
+     * yang, en tenant compte d'une éventuelle rotation Yin/Yang en cours
+     * (AnimationsMngr écrit un `transform` orbite+spin directement sur
+     * `yinOrYangGroup[orientation].graphElementGroup` à chaque frame, sans
+     * jamais toucher `geometry`). Résolu via le CTM plutôt qu'en rejouant la
+     * formule d'orbite d'AnimationsMngr : le point transformé est le centre
+     * CANONIQUE du lobe, qui est aussi le pivot de sa rotation locale — une
+     * rotation autour de son propre point fixe n'a par construction aucun
+     * effet sur lui, donc seule la translation d'orbite se répercute ici,
+     * jamais le spin. Même principe que
+     * YinYangController.getLiveLobeCoreCenter (dupliqué plutôt que partagé
+     * pour ne rien risquer sur ce chemin déjà en prod), utilisé ici pour que
+     * l'étincelle d'équilibre trace le bon cercle — orbitant mais non
+     * spinnant — pendant la rotation.
+     */
+    getLiveOrbitCenter(orientation: "yin" | "yang"): {
+        x: number;
+        y: number;
+    };
+    private getComponentOrientation;
+    private getRadiiForScore;
+    categoryBlendOpacity: number;
+    getOddColor(oddId: string): string;
+    /**
+     * Converts a string to a safe identifier for SVG/CSS (removes special characters, replaces with underscores)
+     * @param id - The original identifier
+     * @returns A sanitized identifier safe for SVG/CSS usage
+     */
+    getSafeIdPart(id: string): string;
+    /**
+     * Gets the category blend opacity (transparency level for category layering).
+     * During animation, fading-out categories have their blend opacity
+     * progressively reduced in sync with the arc's own disappearance.
+     * @param category - The category identifier
+     * @returns The opacity value (0-1)
+     */
+    getCategoryBlendOpacity(category: string): number;
+    /**
+     * Computes per-category blend mask opacities during animation.
+     * Categories fading out (present in start but not in target) get
+     * their opacity progressively reduced from 1.0 to the configured minimum.
+     * Categories fading in (present in target but not in start) get
+     * their opacity progressively increased from the configured minimum to 1.0.
+     * Categories present in both maintain full opacity.
+     *
+     * @param startCategories - The categories at animation start.
+     * @param targetCategories - The categories at animation end.
+     * @param easeProgress - The eased animation progress (0 to 1).
+     */
+    private updateCategoryFadeOpacities;
+    /** Returns true while a "real" (user/search-driven) component-switch
+     *  animation is in progress. Pseudo-activations (notifyChildren = false,
+     *  e.g. the perimeter spark sweeping across a border arc) are decorative
+     *  and must never block a genuine click/search/nav switch from firing. */
+    isComponentSwitching(): boolean;
+    /**
+     * Animates a smooth transition to a different component.
+     * Smoothly interpolates the score and animates category/color changes.
+     *
+     * @param componentIndex - The index of the component to animate to.
+     * @param duration - Animation duration in milliseconds (default: 800ms).
+     */
+    animateToComponent(componentIndex: number, duration?: number, notifyChildren?: boolean): void;
+    /**
+     * Rend synchroniquement une image de la bascule fromIndex → toIndex au
+     * progrès donné (0..1), sans boucle rAF : même interpolation que
+     * startComponentAnimationLoop (easing cubique, rayons, catégories, fondu),
+     * suivie d'un redraw complet. Sert à la cuisson des "films" (voir api-film.ts).
+     * Laisse l'instance dans l'état stable de toIndex quand progress >= 1.
+     */
+    renderSwitchFrame(fromIndex: number, toIndex: number, progress: number): void;
+    animateToComponentView(duration?: number): void;
+    animateToOdd(oddId: string, oddScore: number, duration?: number): void;
+    /**
+     * Converts categories hex colors to RGB for efficient interpolation.
+     * This is done once before animation starts, not per frame.
+     */
+    private convertCategoriesToRGB;
+    /**
+     * Interpolates between two sets of categories using pre-computed RGB colors.
+     * No hex conversion happens during animation - only arithmetic operations.
+     *
+     * Critical: Angles are RECALCULATED from percentages after interpolation,
+     * not interpolated directly. This ensures valid geometry when slice counts differ.
+     */
+    private interpolateCategoriesRGB;
+    private startCategoryAnimation;
+    private startComponentAnimationLoop;
+    private getAnimationCurrentState;
+    private getComponentAnimationState;
+    private buildOddCategories;
+    private getOddWeight;
+    private buildCategoriesFromComponent;
+    /**
+     * Recomputes the ghost (projected) ODD categories from a per-(oddId,
+     * cuttingIndex) weightDelta map, then asks YinYangDrawer to redraw just
+     * the ghost overlay — the ODD-arc equivalent of updateBorderSegmentGhost.
+     * Scoped to the currently displayed facette only (getCurrentComponent):
+     * unlike the border ring, the ODD arcs belong to a single facette, so
+     * switching facette naturally makes this recompute against the new one's
+     * odds the next time a weightDelta is previewed there.
+     */
+    updateCategoryGhost(weightDeltaByOddCutting: Map<string, number> | null): void;
+    private buildGhostCategories;
+    /**
+     * Recomputes the ghost (projected) spikes from the same per-(oddId,
+     * cuttingIndex) weightDelta map used for the ODD-arc ghost, then asks
+     * SpikeDrawer to redraw just the ghost overlay. Unlike arcs/border
+     * segments, a spike's length depends only on its own weight (no
+     * renormalization against siblings), so only the targeted spikes need a
+     * ghost entry — same "only what's targeted" scope as
+     * WeightPreviewRingRenderer's satellite ghosts.
+     */
+    updateSpikeGhost(weightDeltaByOddCutting: Map<string, number> | null): void;
+    private buildGhostSpikes;
+    private projectSpikeWeight;
+    private buildGhostOddSpikes;
+    private buildGhostComponentSpikes;
+    private areCategoriesEqual;
+    private clearGroupChildren;
+    /**
+     * Converts hex color to RGB object.
+     * @param hex Hex color (e.g., "#FF0000")
+     * @returns {r, g, b} object or null if invalid
+     */
+    private hexToRgb;
+    /**
+     * Converts RGB values to hex color.
+     * @param r Red value (0-255)
+     * @param g Green value (0-255)
+     * @param b Blue value (0-255)
+     * @returns Hex color string (e.g., "#FF0000")
+     */
+    private rgbToHex;
     /**
      * Creates the main graphic container where the YinYang visualization will be rendered .
      *
@@ -59,6 +462,37 @@ export declare class ViewInitializer {
      * @returns Object containing the Yin and Yang group elements and properties.
      */
     private createYinOrYangGroups;
+    private updateYinOrYangGroup;
+    private applyGhostOverlapRules;
+    private buildGeometry;
+    private buildSpikes;
+    /**
+     * Builds spikes for the ODD view (single ODD displayed).
+     * Each spike represents one oddCutting, distributed evenly across 360°.
+     */
+    private buildOddSpikes;
+    private buildComponentSpikes;
+    private buildSpike;
+    private calculateAverageTension;
+    private getCurrentComponent;
+    handleSparkAngleUpdate(currentAngle: number, previousAngle: number | null): void;
+    private normalizeAngle;
+    private hasCrossedAngle;
+    private getTotalBorderColors;
+    private getCategoryColor;
+    private getComponentColor;
+    private buildBorderSegments;
+    /**
+     * Recomputes the ghost (projected) border segments from a per-facette
+     * weightDelta map, then asks BorderDrawer to redraw just the ghost overlay
+     * — the border-ring equivalent of updateGhostTension. Segment angles are
+     * normalized against the projected total weight of every facette (see
+     * buildBorderSegments), so a single facette's weightDelta shifts every
+     * segment's boundary, not just its own — the full ring is recomputed.
+     */
+    updateBorderSegmentGhost(weightDeltaByComponentOddCutting: Map<string, number> | null): void;
+    private buildGhostBorderSegments;
+    private setupCategories;
     /**
      * Determines the position of the pattern.
      * If the view is a child, its position is calculated relative to the parent;
@@ -79,6 +513,8 @@ export declare class ViewInitializer {
         positionX: number;
         positionY: number;
     };
+    private getParentChildCount;
+    private getChildCount;
     /**
      * Centers the current motif in the graphic container.
      *