@starterlib/ui 0.10.13 → 0.11.0

package/types/starterlib-ui-graphiques.d.ts

@@ -0,0 +1,421 @@
+import * as i0 from "@angular/core";
+import { InjectionToken, Provider, Signal } from "@angular/core";
+import { AnnonceLocale, CatalogueDuPointDEntree } from "@starterlib/ui";
+import { ColonneDeTableau } from "@starterlib/ui/listes";
+import { UniteDeTemps } from "@starterlib/util/graduations";
+/**
+ * Les donnees d'un graphique (P08-07), telles que l'API les donne : des instants ISO 8601 et des
+ * valeurs en CHAINE DECIMALE, jamais en flottant (regles-front §2). L'echelle se calcule sur des
+ * nombres derives ; l'affichage relit la chaine.
+ */
+/**
+ * Le trait d'une serie : la couleur ne porte jamais rien seule (WCAG 1.4.1), et sous contraste force
+ * le trait est tout ce qui distingue deux series. `mixte` (trait et point) sert la quatrieme.
+ */
+export type TraitDeSerie = 'plein' | 'tirets' | 'points' | 'mixte';
+/** Un point d'une serie. */
+export interface PointDeSerie {
+  /**
+   * ISO 8601 : un instant avec son decalage (`2026-10-07T08:00:00Z`), une heure de mur lue dans le
+   * fuseau du graphique (`2026-10-07T10:00`), ou un jour seul (`2026-10-07`), qui vaut minuit DANS
+   * ce fuseau : une courbe journaliere ne change pas de jour selon qui la regarde.
+   */
+  readonly instant: string;
+  /** La valeur en chaine decimale (`12450.30`, `-0.0825`) ; illisible, le point est ecarte. */
+  readonly valeur: string;
+}
+/** Une serie : son libelle (legende et colonne du tableau), ses points, son trait. */
+export interface SerieDeGraphique {
+  readonly libelle: string;
+  /** 500 points au plus, recommandes : au-dela, la reduction se fait cote SERVEUR. */
+  readonly points: readonly PointDeSerie[];
+  /** Par defaut, selon le rang : `plein`, `tirets`, `points`, `mixte`. */
+  readonly trait?: TraitDeSerie;
+}
+/**
+ * L'aire « perte depuis le sommet » : entre le PLAFOND fourni (le sommet atteint jusque-la, calcule
+ * par le serveur) et la premiere serie, hachuree. Le composant ne calcule aucun sommet.
+ */
+export interface ZoneDePerte {
+  /** Le nom de l'aire, dans la legende et en tete de sa colonne du tableau. */
+  readonly libelle: string;
+  /** Le plafond, aux instants de la premiere serie. */
+  readonly plafond: readonly PointDeSerie[];
+}
+/** Un evenement date : un trait vertical numerote, et sa ligne dans la liste des evenements. */
+export interface MarqueurDeGraphique {
+  /** Meme ecriture qu'un point (`PointDeSerie.instant`). */
+  readonly instant: string;
+  readonly libelle: string;
+}
+/**
+ * Les libelles de `@starterlib/ui/graphiques` (P08-07) : le catalogue par point d'entree (AD-10,
+ * D154), comme ceux des donnees et de la navigation. La langue suit celle du dictionnaire du tronc.
+ */
+export interface LibellesGraphiques {
+  /** Le bouton de `st-line-chart` qui montre le tableau equivalent. */
+  readonly voirLesDonnees: string;
+  /** Le meme bouton, le tableau montre : revenir a la courbe. */
+  readonly voirLeGraphique: string;
+  /** Annonce de la bascule vers le tableau. */
+  readonly tableauAffiche: string;
+  /** Annonce de la bascule vers la courbe. */
+  readonly graphiqueAffiche: string;
+  /** L'en-tete de la colonne des instants du tableau equivalent. */
+  readonly colonneDate: string;
+  /** Le nom de la legende (liste des series). */
+  readonly legende: string;
+  /** Le nom de la liste des evenements dates (marqueurs). */
+  readonly evenements: string;
+  /** Entre la date d'un evenement et son libelle (« 12 mars 2026 : changement de strategie »). */
+  readonly separateurDEvenement: string;
+  /** Une courbe ou une tendance sans aucun point lisible. */
+  readonly aucuneDonnee: string;
+  /**
+   * Ce que dit une tendance decorative (`st-sparkline` sans etiquette) : la derniere valeur et la
+   * variation depuis le premier point, deja formatees ; `null` : un seul point.
+   */
+  readonly tendance: (dernier: string, variation: string | null) => string;
+}
+export declare const LIBELLES_GRAPHIQUES_FR: LibellesGraphiques;
+export declare const LIBELLES_GRAPHIQUES_EN: LibellesGraphiques;
+/**
+ * Les catalogues des graphiques par langue (sous-etiquette primaire : `fr`, `en`). Une application qui
+ * ajoute une langue au dictionnaire du tronc ajoute la sienne ici, par
+ * `fournirLibellesGraphiques({ de: ... })`.
+ */
+export declare const ST_LIBELLES_GRAPHIQUES: InjectionToken<Readonly<Record<string, LibellesGraphiques>>>;
+/** Ajoute (ou remplace) des catalogues des graphiques, par langue. */
+export declare function fournirLibellesGraphiques(catalogues: Readonly<Record<string, LibellesGraphiques>>): Provider;
+/**
+ * Le catalogue de la langue du dictionnaire du tronc ; le francais quand la langue n'en a pas, un
+ * repli signale en developpement (D-29). A appeler dans un contexte d'injection.
+ */
+export declare function libellesDesGraphiques(): Signal<LibellesGraphiques>;
+/**
+ * Le catalogue des graphiques ET la langue de son repli (`catalogueDuPointDEntree`) : `lang` de ce
+ * qu'il ecrit seul (D-29). A appeler dans un contexte d'injection.
+ */
+export declare function catalogueDesGraphiques(): Signal<CatalogueDuPointDEntree<LibellesGraphiques>>;
+/** Le vrai signe moins (D30, EA-16), comme `st-number` et `st-money`. */
+declare const SIGNE_MOINS = "−";
+/** Un point lu : l'instant (millisecondes), la valeur derivee pour l'echelle, la chaine pour l'affichage. */
+interface PointLu {
+  readonly instant: number;
+  readonly valeur: number;
+  readonly texte: `${number}`;
+}
+/** Vrai si `texte` est une chaine decimale lisible. */
+declare function estDecimale(texte: string): texte is `${number}`;
+/**
+ * Le fuseau, s'il est connu d'Intl ; sinon UTC, signale en developpement. Un fuseau mal ecrit ne
+ * casse pas la page : il leverait a chaque format.
+ */
+declare function fuseauLisible(fuseau: string): string;
+/**
+ * L'instant d'un point ou d'un marqueur, en millisecondes : un jour seul vaut minuit dans `fuseau`,
+ * le reste se lit comme `st-date` (`lireInstant`) ; `null` si illisible.
+ */
+declare function instantDuPoint(texte: string, fuseau: string): number | null;
+/**
+ * Les points lisibles d'une serie, dans l'ordre du temps. Un point illisible (instant ou valeur) est
+ * ecarte, et signale en developpement : une courbe ne ment pas en le placant a zero.
+ */
+declare function lirePoints(points: readonly PointDeSerie[], fuseau: string, nom: string): PointLu[];
+/** Les evenements lisibles, dans l'ordre du temps ; un instant illisible est ecarte. */
+declare function lireMarqueurs(marqueurs: readonly MarqueurDeGraphique[], fuseau: string): {
+  readonly instant: number;
+  readonly libelle: string;
+}[];
+/**
+ * Des instants dans l'ordre du temps : les lignes du tableau equivalent. L'ordre d'une serie
+ * temporelle n'est pas un tri de tableau (V4-3) : aucune colonne n'y est triable, et la courbe
+ * montre deja ces instants dans cet ordre.
+ */
+declare function dansLOrdreDuTemps(instants: Iterable<number>): number[];
+/**
+ * La difference EXACTE `a - b` de deux chaines decimales, en entiers longs : « 12450.3 » moins
+ * « 11250.30 » donne « 1200.00 ». Une variation ne passe jamais par un flottant.
+ */
+declare function differenceDecimale(a: `${number}`, b: `${number}`): `${number}`;
+/** Ce que vaut une valeur : un montant dans sa devise, un pourcentage (3.25 : « 3,25 % »), un nombre. */
+interface FormeDeValeur {
+  readonly devise: string | null;
+  readonly pourcentage: boolean;
+}
+/**
+ * Le formateur des valeurs, depuis leur CHAINE exacte (Intl, ES2023) : un nombre garde les decimales
+ * de sa chaine (« 3.10 » : « 3,10 ») ; un montant, celles de sa devise. `signe` : la variation, son
+ * signe ecrit (« +1 200,00 € »), zero sans signe. Les formats se gardent par nombre de decimales :
+ * 500 points n'en creent qu'une poignee.
+ */
+declare function formateurDeValeurs(locale: string, forme: FormeDeValeur): (texte: `${number}`, signe?: boolean) => string;
+/**
+ * Le formateur des graduations d'un axe : les decimales du pas ; au-dela du million, la forme compacte
+ * (« 1,25 M€ »), pour qu'une etiquette tienne a 320 px. Une graduation n'est qu'un repere : elle ne
+ * relit aucune chaine.
+ */
+declare function formateurDeGraduations(locale: string, forme: FormeDeValeur, pas: number, plusGrande: number): (valeur: number) => string;
+/** Vrai si chaque instant tombe a minuit dans le fuseau : une serie de jours, sans heure a dire. */
+declare function tousAMinuit(instants: readonly number[], fuseau: string): boolean;
+/**
+ * Le formateur des reperes de l'axe du temps, selon l'unite du pas : l'heure, le jour et le mois, le
+ * mois (l'annee au premier repere et en janvier), l'annee. Dans le fuseau du graphique.
+ */
+declare function formateurDeReperes(locale: string, fuseau: string): (instant: number, unite: UniteDeTemps, premier: boolean) => string;
+/** Le formateur des dates du tableau equivalent : le jour, et l'heure si la serie en porte une. */
+declare function formateurDeDates(locale: string, fuseau: string, avecHeure: boolean): (instant: number) => string;
+/** Une serie lue : son rang (1 a 4, sa couleur), son trait, son libelle, ses points dans l'ordre. */
+interface SerieLue {
+  readonly rang: number;
+  readonly trait: TraitDeSerie;
+  readonly libelle: string;
+  readonly points: readonly PointLu[];
+}
+/** Un evenement lu, numerote dans l'ordre du temps. */
+interface MarqueurLu {
+  readonly numero: number;
+  readonly instant: number;
+  readonly iso: string;
+  readonly date: string;
+  readonly libelle: string;
+}
+/** Ce que le gabarit dessine : calcule une fois par changement des donnees ou de la largeur. */
+interface Dessin {
+  readonly largeur: number;
+  readonly hauteur: number;
+  /** Le cadre du trace : de `gauche` a `droite`, de `haut` a `bas`. */
+  readonly gauche: number;
+  readonly droite: number;
+  readonly haut: number;
+  readonly bas: number;
+  readonly graduations: readonly {
+    readonly y: number;
+    readonly texte: string;
+    readonly zero: boolean;
+  }[];
+  readonly reperes: readonly {
+    readonly x: number;
+    readonly texte: string;
+    readonly ancre: 'start' | 'middle' | 'end';
+  }[];
+  readonly traces: readonly {
+    readonly rang: number;
+    readonly trait: TraitDeSerie;
+    /** Le chemin de la serie ; `null` pour un point seul, dessine en disque (`point`). */
+    readonly d: string | null;
+    readonly point: {
+      readonly x: number;
+      readonly y: number;
+    } | null;
+  }[];
+  readonly perte: string | null;
+  readonly marqueurs: readonly {
+    readonly x: number;
+    readonly numero: number;
+  }[];
+}
+/**
+ * Une courbe dans le temps (P08-07, DEC-103) : une a quatre series, l'aire « perte depuis le
+ * sommet » sous un plafond fourni, des evenements dates ; en SVG ecrit a la main, sans bibliotheque.
+ *
+ * ```html
+ * <st-line-chart etiquette="Capital du compte" [resume]="resume()" devise="EUR"
+ *   [series]="[{ libelle: 'Capital', points: capital() }]"
+ *   [zonePerte]="{ libelle: 'Perte depuis le sommet', plafond: sommets() }" />
+ * ```
+ *
+ * - **Accessible** : un `svg` `role="img"` nomme (`etiquette`) et decrit (`resume`, texte fourni et
+ *   visible) ; la legende et les evenements sont du TEXTE ; « Voir les donnees » bascule vers un
+ *   `st-data-table` equivalent, au clavier, et la bascule s'annonce.
+ * - **La couleur ne dit rien seule** : chaque serie a son trait (plein, tirets, points, mixte), que le
+ *   contraste force garde quand les couleurs s'effacent ; l'aire de perte est hachuree.
+ * - **Des chaines decimales** : l'echelle se calcule sur des nombres derives, toute valeur affichee
+ *   relit sa chaine (regles-front §2). Les graduations viennent de `@starterlib/util/graduations`.
+ * - **Sobre** : aucune animation ; un calcul par changement des donnees ou de la largeur, jamais a
+ *   la seconde. 500 points par serie au plus, recommandes : au-dela, la reduction se fait cote
+ *   serveur (signale en developpement), le composant ne reechantillonne pas.
+ * - `pariteEchelle` : des graduations symetriques autour de zero, un gain et une perte de meme
+ *   ampleur a la meme taille (parite d'echelle).
+ */
+export declare class StLineChart {
+  private readonly locale;
+  private readonly fuseauParDefaut;
+  protected readonly catalogue: import("@angular/core").Signal<import("@starterlib/ui").CatalogueDuPointDEntree<import("@starterlib/ui/graphiques").LibellesGraphiques>>;
+  protected readonly annonce: AnnonceLocale;
+  /** Une a quatre series ; au-dela, les suivantes ne sont pas dessinees (signale en developpement). */
+  readonly series: import("@angular/core").InputSignal<readonly SerieDeGraphique[]>;
+  /** L'aire « perte depuis le sommet » sous le plafond fourni, sur la premiere serie. */
+  readonly zonePerte: import("@angular/core").InputSignal<ZoneDePerte | null>;
+  readonly marqueurs: import("@angular/core").InputSignal<readonly MarqueurDeGraphique[]>;
+  /** Code ISO 4217 : les valeurs sont des montants dans cette devise. */
+  readonly devise: import("@angular/core").InputSignal<string | null>;
+  /** Sans devise : les valeurs sont EN POUR CENT, telles que l'API les donne (3.25 : « 3,25 % »). */
+  readonly pourcentage: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
+  /** Le fuseau des reperes et des dates ; par defaut, celui de l'application. */
+  readonly fuseau: import("@angular/core").InputSignal<string | null>;
+  /** Le nom du graphique, deja traduit. */
+  readonly etiquette: import("@angular/core").InputSignal<string>;
+  /** Ce que la courbe montre, en une ou deux phrases, deja traduites : lu et affiche. */
+  readonly resume: import("@angular/core").InputSignal<string>;
+  /** Graduations symetriques autour de zero : un gain et une perte a la meme taille. */
+  readonly pariteEchelle: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
+  /** La hauteur du trace, en pixels CSS. */
+  readonly hauteur: import("@angular/core").InputSignal<number>;
+  protected readonly vueDonnees: import("@angular/core").WritableSignal<boolean>;
+  private readonly largeur;
+  protected readonly identifiants: {
+    readonly motif: `${string}-motif`;
+    readonly resume: `${string}-resume`;
+  };
+  private readonly fuseauDeRendu;
+  private readonly forme;
+  protected readonly seriesLues: import("@angular/core").Signal<readonly SerieLue[]>;
+  protected readonly plafond: import("@angular/core").Signal<{
+    libelle: string;
+    points: PointLu[];
+  } | null>;
+  protected readonly marqueursLus: import("@angular/core").Signal<readonly MarqueurLu[]>;
+  /** Aucun point lisible, ni dans les series ni dans le plafond. */
+  protected readonly vide: import("@angular/core").Signal<boolean>;
+  protected readonly dessin: import("@angular/core").Signal<Dessin | null>;
+  /** Les colonnes du tableau equivalent : l'instant, chaque serie, le plafond. */
+  protected readonly colonnes: import("@angular/core").Signal<readonly ColonneDeTableau[]>;
+  /** Une ligne par instant, dans l'ordre du temps ; chaque valeur relue depuis sa chaine. */
+  protected readonly lignes: import("@angular/core").Signal<readonly Readonly<Record<string, string>>[]>;
+  constructor();
+  /** La courbe ou le tableau ; le bouton garde le focus, et la bascule s'annonce. */
+  protected basculer(): void;
+  static ɵfac: i0.ɵɵFactoryDeclaration<StLineChart, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<StLineChart, "st-line-chart", never, {
+    "series": {
+      "alias": "series";
+      "required": true;
+      "isSignal": true;
+    };
+    "zonePerte": {
+      "alias": "zonePerte";
+      "required": false;
+      "isSignal": true;
+    };
+    "marqueurs": {
+      "alias": "marqueurs";
+      "required": false;
+      "isSignal": true;
+    };
+    "devise": {
+      "alias": "devise";
+      "required": false;
+      "isSignal": true;
+    };
+    "pourcentage": {
+      "alias": "pourcentage";
+      "required": false;
+      "isSignal": true;
+    };
+    "fuseau": {
+      "alias": "fuseau";
+      "required": false;
+      "isSignal": true;
+    };
+    "etiquette": {
+      "alias": "etiquette";
+      "required": true;
+      "isSignal": true;
+    };
+    "resume": {
+      "alias": "resume";
+      "required": true;
+      "isSignal": true;
+    };
+    "pariteEchelle": {
+      "alias": "pariteEchelle";
+      "required": false;
+      "isSignal": true;
+    };
+    "hauteur": {
+      "alias": "hauteur";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}
+/**
+ * Une tendance (P08-07) : une serie, sans axe, a cote d'un chiffre ou dans une cellule ; meme moteur
+ * d'echelle que `st-line-chart` (`@starterlib/util/graduations`).
+ *
+ * ```html
+ * <st-sparkline [points]="soldes()" devise="EUR" />
+ * <st-sparkline [points]="cours()" etiquette="Cours sur trente jours, en hausse de 4 %" />
+ * ```
+ *
+ * - Sans `etiquette` : DECORATIVE (`aria-hidden`), et toujours accompagnee de son texte, la derniere
+ *   valeur et la variation depuis le premier point, relues depuis leurs chaines (variation calculee
+ *   exactement, jamais en flottant). Ce texte se lit en phrase (« Derniere valeur : ..., variation :
+ *   ... »), le signe moins en toutes lettres.
+ * - Avec `etiquette` : une image NOMMEE, sans texte ; l'etiquette dit la tendance.
+ * - Le trait garde son epaisseur quelle que soit la taille de la boite (`non-scaling-stroke`) ;
+ *   aucune animation.
+ */
+export declare class StSparkline {
+  private readonly locale;
+  private readonly libellesDuTronc;
+  private readonly fuseauParDefaut;
+  protected readonly catalogue: import("@angular/core").Signal<import("@starterlib/ui").CatalogueDuPointDEntree<import("@starterlib/ui/graphiques").LibellesGraphiques>>;
+  readonly points: import("@angular/core").InputSignal<readonly PointDeSerie[]>;
+  /** `null` : decorative, avec son texte. Donnee : le nom de l'image, deja traduit, sans texte. */
+  readonly etiquette: import("@angular/core").InputSignal<string | null>;
+  /** Code ISO 4217 : les valeurs sont des montants dans cette devise. */
+  readonly devise: import("@angular/core").InputSignal<string | null>;
+  /** Sans devise : les valeurs sont EN POUR CENT (3.25 : « 3,25 % »). */
+  readonly pourcentage: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
+  readonly trait: import("@angular/core").InputSignal<TraitDeSerie>;
+  /** Le fuseau de lecture des instants sans decalage ; par defaut, celui de l'application. */
+  readonly fuseau: import("@angular/core").InputSignal<string | null>;
+  private readonly lus;
+  protected readonly trace: import("@angular/core").Signal<{
+    ligne: string | null;
+    dernier: string;
+  } | null>;
+  /** La derniere valeur et la variation, vues et lues ; `null` sans aucun point. */
+  protected readonly texte: import("@angular/core").Signal<{
+    dernier: string;
+    variation: string | null;
+    lu: string;
+  } | null>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<StSparkline, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<StSparkline, "st-sparkline", never, {
+    "points": {
+      "alias": "points";
+      "required": true;
+      "isSignal": true;
+    };
+    "etiquette": {
+      "alias": "etiquette";
+      "required": false;
+      "isSignal": true;
+    };
+    "devise": {
+      "alias": "devise";
+      "required": false;
+      "isSignal": true;
+    };
+    "pourcentage": {
+      "alias": "pourcentage";
+      "required": false;
+      "isSignal": true;
+    };
+    "trait": {
+      "alias": "trait";
+      "required": false;
+      "isSignal": true;
+    };
+    "fuseau": {
+      "alias": "fuseau";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}
+
+export {};

package/types/starterlib-ui-indicateurs.d.ts

@@ -6,8 +6,11 @@ import { InjectionToken } from "@angular/core";
  * ⚠️ `primaire` et non « info » : les deux designaient deja la meme couleur
  * d'accent, et rien ne distinguait un statut « info » d'un statut « primaire »
  * ailleurs dans le socle.
+ *
+ * `essai` (P08-04) : un environnement fictif (« Donnees fictives », « Bac a sable »), avec sa
+ * fiole ; le mot est le libelle, fourni par l'application.
  */
-export type TonDeStatut = TonSemantique;
+export type TonDeStatut = TonSemantique | Extract<Ton, 'essai'>;
 /**
  * `md` (defaut) : 24 px, libelle de 11 px, icone de 16 px au trait (planche 2 de Claude Design).
  * `sm` : 18 px, icone de 14 px PLEINE, pour les tableaux denses (a cette taille, un trait ne
@@ -49,11 +52,12 @@ export declare class StStatusPill {
   readonly libelle: import("@angular/core").InputSignal<string>;
   /**
    * `null` : la forme du ton (neutre `cercle`, information et primaire `cercle-info`, succes
-   * `cercle-coche`, avertissement `triangle-alerte`, danger `cercle-croix`). Fournie, une forme
+   * `cercle-coche`, avertissement `triangle-alerte`, erreur et danger `cercle-croix`, essai `essai`).
+   * Fournie, une forme
    * plus precise : `horloge` (en attente), `octogone-alerte` (bloque), `interdit` (opposition).
    */
   readonly icone: import("@angular/core").InputSignal<Icone | null>;
-  readonly ton: import("@angular/core").InputSignal<TonSemantique>;
+  readonly ton: import("@angular/core").InputSignal<TonDeStatut>;
   readonly taille: import("@angular/core").InputSignal<TailleDePastille>;
   readonly variante: import("@angular/core").InputSignal<VarianteDePastille>;
   readonly casse: import("@angular/core").InputSignal<CasseDePastille>;
@@ -200,7 +204,10 @@ export declare class StBadge {
     };
   }, {}, never, never, true, never>;
 }
-/** Le ton de l'etiquette : papier teinte du ton (`discrete`) ou aplat (`pleine`). */
+/**
+ * Le ton de l'etiquette : papier teinte du ton (`discrete`) ou aplat (`pleine`). `essai` (P08-04) :
+ * un environnement fictif, dont le mot est le libelle (« Donnees fictives »).
+ */
 export type TonDEtiquette = Exclude<Ton, 'discret' | 'inverse'>;
 /**
  * `md` (defaut) : 22 px, 4 x 10 de marge (planches 10 a 12) ; `sm` : 18 px, 2 x 8 (planches 2,