@dnax/ui 0.0.67 → 0.0.70

package/lib/chartFormat.ts

@@ -0,0 +1,222 @@
+// Formatage des valeurs de `<q-chart>` (axes, info-bulles, étiquettes, tableaux).
+//
+// Le traducteur (`chartToECharts`) reste **pur** : ce module ne lit ni le DOM ni la locale
+// du navigateur. La locale vient de la prop `locale` (défaut : `fr-FR`, cohérent avec le
+// reste du design system), éventuellement surchargée par un format.
+//
+// Rien n'est formaté tant que l'appelant ne demande rien : sans `format`, une valeur sort
+// telle quelle (`String(value)`), donc aucun changement de comportement rétroactif.
+
+/** Format « court » : une chaîne suffit (`format: "compact"`) */
+export type QChartFormatKind =
+  | "number"
+  | "decimal"
+  | "percent"
+  | "compact"
+  | "currency"
+  | "date"
+  | "time"
+  | "datetime"
+
+/** Contexte passé aux formateurs (fonction ou objet) */
+export interface QChartFormatContext {
+  /** Locale de repli (celle du graphique) */
+  locale?: string
+  /** Index de la donnée dans sa marque */
+  index?: number
+  /** Ligne d'origine */
+  row?: any
+  /** Nom de la série / de la catégorie, si connu */
+  name?: string
+}
+
+/** Format complet (objet) */
+export interface QChartFormatOptions {
+  /** Famille de formatage */
+  style?: QChartFormatKind
+  /** Locale BCP 47 (`fr-FR`, `en-US`…) — prioritaire sur celle du graphique */
+  locale?: string
+  /** Devise ISO 4217 pour `currency` (`XOF` par défaut → « F CFA ») */
+  currency?: string
+  /** Fuseau horaire IANA (`Africa/Dakar`…) pour les formats de date */
+  timeZone?: string
+  minimumFractionDigits?: number
+  maximumFractionDigits?: number
+  /** `date` / `datetime` : style de la partie date */
+  dateStyle?: "full" | "long" | "medium" | "short"
+  /** `time` / `datetime` : style de la partie heure */
+  timeStyle?: "full" | "long" | "medium" | "short"
+  /** Texte ajouté avant / après la valeur formatée */
+  prefix?: string
+  suffix?: string
+}
+
+/** Un format : chaîne courte, objet d'options, ou fonction `(value, ctx) => string` */
+export type QChartFormat =
+  | QChartFormatKind
+  | QChartFormatOptions
+  | ((value: any, ctx?: QChartFormatContext) => string)
+
+/** Locale par défaut de tous les formats (l'application peut la changer par prop) */
+export const DEFAULT_LOCALE = "fr-FR"
+
+/** Devise par défaut : franc CFA (lisible en `fr-FR` : « 1 234 F CFA ») */
+export const DEFAULT_CURRENCY = "XOF"
+
+const isObject = (v: any): v is QChartFormatOptions => v !== null && typeof v === "object"
+
+/** Normalise un format en options exploitables (`undefined` si aucun format demandé) */
+export function normalizeFormat(
+  format: QChartFormat | undefined,
+): QChartFormatOptions | undefined {
+  if (format === undefined || format === null) return undefined
+  if (typeof format === "string") return { style: format }
+  if (typeof format === "function") return undefined
+  if (isObject(format)) return format
+  return undefined
+}
+
+/** Nombre fini ? (`null`, `""`, `NaN` sont écartés) */
+const finite = (v: any): v is number => typeof v === "number" && Number.isFinite(v)
+
+/** `value` → `Date` (nombre = timestamp, chaîne = ISO / date lisible) */
+function toDate(value: any): Date | undefined {
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? undefined : value
+  if (finite(value)) {
+    // Un timestamp en **secondes** (API usuelles) est ramené en millisecondes.
+    const ms = Math.abs(value) < 1e11 ? value * 1000 : value
+    const d = new Date(ms)
+    return Number.isNaN(d.getTime()) ? undefined : d
+  }
+  if (typeof value === "string" && value.trim() !== "") {
+    const d = new Date(value)
+    return Number.isNaN(d.getTime()) ? undefined : d
+  }
+  return undefined
+}
+
+const dateFormatted = (value: any, options: QChartFormatOptions, locale: string): string | undefined => {
+  const date = toDate(value)
+  if (!date) return undefined
+  const style = options.style
+  const opts: Intl.DateTimeFormatOptions = { timeZone: options.timeZone }
+  if (style === "date" || style === "datetime") {
+    opts.dateStyle = options.dateStyle ?? (style === "datetime" ? "short" : "medium")
+  }
+  if (style === "time" || style === "datetime") {
+    opts.timeStyle = options.timeStyle ?? "short"
+  }
+  return new Intl.DateTimeFormat(locale, opts).format(date)
+}
+
+const numberFormatted = (value: any, options: QChartFormatOptions, locale: string): string | undefined => {
+  const style = options.style ?? "number"
+  if (typeof value === "boolean") return String(value)
+  if (!finite(value)) return undefined
+  const digits: Intl.NumberFormatOptions = {}
+  if (options.minimumFractionDigits !== undefined) digits.minimumFractionDigits = options.minimumFractionDigits
+  if (options.maximumFractionDigits !== undefined) digits.maximumFractionDigits = options.maximumFractionDigits
+  if (style === "compact") {
+    return new Intl.NumberFormat(locale, {
+      notation: "compact",
+      compactDisplay: "short",
+      maximumFractionDigits: options.maximumFractionDigits ?? 1,
+    }).format(value)
+  }
+  if (style === "currency") {
+    return new Intl.NumberFormat(locale, {
+      style: "currency",
+      currency: options.currency ?? DEFAULT_CURRENCY,
+      ...digits,
+    }).format(value)
+  }
+  if (style === "percent") {
+    // La valeur est **déjà en pourcentage** (42 → « 42 % ») : `Intl` multiplie par 100,
+    // on divise donc avant (et non l'inverse, qui donnerait 4200 %).
+    return new Intl.NumberFormat(locale, {
+      style: "percent",
+      maximumFractionDigits: options.maximumFractionDigits ?? 1,
+      ...digits,
+    }).format(value / 100)
+  }
+  // `number` / `decimal` / style absent : nombre localisé
+  return new Intl.NumberFormat(locale, {
+    maximumFractionDigits: options.maximumFractionDigits ?? 2,
+    ...digits,
+  }).format(value)
+}
+
+/** Formate une valeur selon `format`.
+ *
+ *  - `undefined` / `null` → chaîne vide ;
+ *  - sans `format` → `String(value)` (aucun formatage implicite) ;
+ *  - `percent` attend une valeur **en pourcentage** (`42` → « 42 % ») ;
+ *  - `currency` utilise `XOF` (F CFA) par défaut ;
+ *  - une date peut être un `Date`, un timestamp (s/ms) ou une chaîne ISO. */
+export function formatValue(
+  value: any,
+  format?: QChartFormat,
+  ctx: QChartFormatContext = {},
+): string {
+  if (typeof format === "function") {
+    const out = format(value, ctx)
+    return out === undefined || out === null ? "" : String(out)
+  }
+  if (value === undefined || value === null || value === "") return ""
+  const options = normalizeFormat(format)
+  if (!options) return String(value)
+  const locale = options.locale ?? ctx.locale ?? DEFAULT_LOCALE
+  const temporal =
+    options.style === "date" || options.style === "time" || options.style === "datetime"
+  const text = temporal
+    ? (dateFormatted(value, options, locale) ?? String(value))
+    : (numberFormatted(value, options, locale) ?? String(value))
+  return `${options.prefix ?? ""}${text}${options.suffix ?? ""}`
+}
+
+/** Un format de pourcentage sans `%` (pour composer soi-même un libellé) */
+export function formatPercent(value: any, format?: QChartFormat, ctx?: QChartFormatContext): string {
+  const options = normalizeFormat(format)
+  const merged: QChartFormat = { ...(options ?? {}), style: "percent" }
+  return formatValue(value, merged, ctx)
+}
+
+
+/** Formateur ECharts pour un axe (`axisLabel.formatter`), ou `undefined` si rien n'est demandé. */
+export function axisFormatter(
+  format: QChartFormat | undefined,
+  ctx: QChartFormatContext = {},
+): ((value: any) => string) | undefined {
+  if (format === undefined || format === null) return undefined
+  return (value: any) => formatValue(value, format, ctx)
+}
+
+/** Graduation d'un axe **temporel** selon sa granularité.
+ *  `auto` (défaut) laisse le moteur choisir : aucune fonction n'est renvoyée. */
+export function timeTickFormatter(
+  unit: "auto" | "day" | "week" | "month" | "quarter" | "year" | undefined,
+  locale = DEFAULT_LOCALE,
+  timeZone?: string,
+): ((value: any) => string) | undefined {
+  if (!unit || unit === "auto") return undefined
+  return (value: any) => {
+    const date = toDate(value)
+    if (!date) return String(value ?? "")
+    if (unit === "quarter") {
+      const quarter = Math.floor(date.getUTCMonth() / 3) + 1
+      const year = String(date.getUTCFullYear()).slice(2)
+      return `T${quarter} ${year}`
+    }
+    const opts: Intl.DateTimeFormatOptions = { timeZone }
+    if (unit === "day" || unit === "week") {
+      opts.day = "numeric"
+      opts.month = "short"
+    } else if (unit === "month") {
+      opts.month = "short"
+      opts.year = "2-digit"
+    } else {
+      opts.year = "numeric"
+    }
+    return new Intl.DateTimeFormat(locale, opts).format(date)
+  }
+}

package/lib/chartStats.ts

@@ -0,0 +1,178 @@
+// Calculs statistiques du traducteur de graphiques — **purs**, testables sans DOM.
+//
+// Utilisés par les marques `histogram`, `boxplot` et `waterfall` (P1 de `QChart`).
+// Aucune notion de couleur ni de rendu : uniquement des nombres, pour que les tests
+// portent sur la sémantique (tranches, quartiles, cumul) et non sur ECharts.
+
+/** Une tranche d'histogramme */
+export interface QChartBin {
+  /** Borne basse (incluse) */
+  x0: number
+  /** Borne haute (exclue, sauf la dernière tranche) */
+  x1: number
+  /** Nombre de valeurs dans la tranche */
+  count: number
+  /** Libellé par défaut (`x0 – x1`) — l'appelant peut le reformater */
+  label: string
+}
+
+/** Arrondit un nombre de borne pour les libellés (évite `0.30000000000000004`) */
+const clean = (v: number) => Number(v.toPrecision(12))
+
+/** Histogramme : répartit des valeurs numériques en `bins` tranches.
+ *
+ *  - `bins` par défaut : `ceil(sqrt(n))` (règle de la racine), borné à `[1, 40]` ;
+ *  - `domain` force les bornes ; sinon `[min, max]` des valeurs ;
+ *  - une valeur `null` / non finie est ignorée ;
+ *  - la borne haute de la **dernière** tranche est inclusive (la valeur maximale compte). */
+export function histogram(
+  values: readonly any[],
+  options: { bins?: number; domain?: [number, number] } = {},
+): QChartBin[] {
+  const nums = values.filter((v): v is number => typeof v === "number" && Number.isFinite(v))
+  if (nums.length === 0) return []
+  let lo = options.domain?.[0] ?? Math.min(...nums)
+  let hi = options.domain?.[1] ?? Math.max(...nums)
+  if (!Number.isFinite(lo) || !Number.isFinite(hi)) return []
+  if (hi < lo) [lo, hi] = [hi, lo]
+  const requested = Math.max(1, Math.min(40, Math.round(options.bins ?? Math.ceil(Math.sqrt(nums.length)))))
+  // Domaine dégénéré (une seule valeur) : une tranche autour de la valeur
+  if (hi === lo) {
+    return [{ x0: lo, x1: hi, count: nums.length, label: `${clean(lo)}` }]
+  }
+  // Le nombre de tranches demandé est **respecté** : pas d'arrondi « joli » qui le changerait.
+  const step = (hi - lo) / requested
+  const bins: QChartBin[] = Array.from({ length: requested }, (_, i) => ({
+    x0: clean(lo + i * step),
+    x1: clean(lo + (i + 1) * step),
+    count: 0,
+    label: "",
+  }))
+  for (const v of nums) {
+    // La valeur maximale tombe dans la dernière tranche (borne haute inclusive)
+    let i = Math.floor((v - lo) / step)
+    if (i < 0) i = 0
+    if (i >= requested) i = requested - 1
+    const bin = bins[i]
+    if (bin) bin.count++
+  }
+  for (const bin of bins) bin.label = `${clean(bin.x0)} – ${clean(bin.x1)}`
+  return bins
+}
+
+/** Quantile (interpolation linéaire, méthode R-7 — celle d'Excel `QUARTILE.INC`) */
+export function quantile(sorted: readonly number[], p: number): number {
+  if (sorted.length === 0) return Number.NaN
+  const pos = (sorted.length - 1) * Math.max(0, Math.min(1, p))
+  const lower = Math.floor(pos)
+  const upper = Math.ceil(pos)
+  if (lower === upper) return sorted[lower]!
+  return sorted[lower]! + (sorted[upper]! - sorted[lower]!) * (pos - lower)
+}
+
+/** Boîte à moustaches (cinq nombres) */
+export interface QChartBox {
+  min: number
+  q1: number
+  median: number
+  q3: number
+  max: number
+}
+
+/** Statistiques d'une série de valeurs (`undefined` si aucune valeur numérique) */
+export function boxStats(values: readonly any[]): QChartBox | undefined {
+  const nums = values
+    .filter((v): v is number => typeof v === "number" && Number.isFinite(v))
+    .slice()
+    .sort((a, b) => a - b)
+  if (nums.length === 0) return undefined
+  return {
+    min: nums[0]!,
+    q1: quantile(nums, 0.25),
+    median: quantile(nums, 0.5),
+    q3: quantile(nums, 0.75),
+    max: nums[nums.length - 1]!,
+  }
+}
+
+/** Ajustement affine par moindres carrés — `undefined` si les abscisses sont toutes égales */
+export function linearFit(
+  points: readonly (readonly [number, number])[],
+): { slope: number; intercept: number } | undefined {
+  const pts = points.filter(
+    ([x, y]) => typeof x === "number" && typeof y === "number" && Number.isFinite(x) && Number.isFinite(y),
+  )
+  if (pts.length < 2) return undefined
+  const n = pts.length
+  const sumX = pts.reduce((s, [x]) => s + x, 0)
+  const sumY = pts.reduce((s, [, y]) => s + y, 0)
+  const meanX = sumX / n
+  const meanY = sumY / n
+  let num = 0
+  let den = 0
+  for (const [x, y] of pts) {
+    num += (x - meanX) * (y - meanY)
+    den += (x - meanX) ** 2
+  }
+  if (den === 0) return undefined
+  const slope = num / den
+  return { slope, intercept: meanY - slope * meanX }
+}
+
+/** Étape d'un graphique en cascade (waterfall) */
+export interface QChartWaterfallStep {
+  /** Valeur de départ de la barre (le cumul précédent) */
+  base: number
+  /** Hauteur signée de la barre (le delta) */
+  delta: number
+  /** Cumul après l'étape */
+  total: number
+  /** Ligne de **total** (barre posée depuis zéro) ? */
+  totalRow: boolean
+}
+
+/** Décompose des deltas en barres flottantes cumulées.
+ *
+ *  `flags[i] === true` marque une ligne de **total** : la barre part de zéro et sa hauteur
+ *  est le cumul courant (elle ne s'ajoute pas une seconde fois au cumul). */
+export function waterfallSteps(
+  values: readonly any[],
+  flags: readonly any[] = [],
+): QChartWaterfallStep[] {
+  const steps: QChartWaterfallStep[] = []
+  let running = 0
+  for (let i = 0; i < values.length; i++) {
+    const raw = values[i]
+    const value = typeof raw === "number" && Number.isFinite(raw) ? raw : 0
+    const totalRow = flags[i] === true || flags[i] === "total"
+    if (totalRow) {
+      steps.push({ base: 0, delta: running, total: running, totalRow: true })
+      continue
+    }
+    steps.push({ base: running, delta: value, total: running + value, totalRow: false })
+    running += value
+  }
+  return steps
+}
+
+/** Répartition en pourcentage (somme des valeurs absolues, `0` évité).
+ *  Une valeur nulle ou non finie vaut `0` : la part reste calculable. */
+export function percentShares(values: readonly any[]): number[] {
+  const nums = values.map((v) => (typeof v === "number" && Number.isFinite(v) ? v : 0))
+  const total = nums.reduce((s, v) => s + Math.abs(v), 0)
+  return total === 0 ? nums.map(() => 0) : nums.map((v) => (Math.abs(v) / total) * 100)
+}
+
+/** Somme par catégorie — sert au calcul des **empilements 100 %**. */
+export function categoryTotals(
+  entries: readonly { category: any; value: any }[],
+): Map<string, number> {
+  const totals = new Map<string, number>()
+  for (const { category, value } of entries) {
+    if (category === undefined || category === null) continue
+    if (typeof value !== "number" || !Number.isFinite(value)) continue
+    const key = String(category)
+    totals.set(key, (totals.get(key) ?? 0) + value)
+  }
+  return totals
+}

package/lib/chartTable.test.ts

@@ -0,0 +1,140 @@
+// Tests des **micro-visualisations de cellule** de la marque `table` (barres de données,
+// barres divergentes, heat, sparklines) — purs, sans DOM.
+import { describe, expect, it } from "bun:test"
+import { cellBarGeometry, cellScale, cellVisualOf, sparklineGeometry } from "./chartTable"
+import { tableModel } from "./chart"
+
+describe("cellVisualOf", () => {
+  it("`true` = barre de données, objet rendu tel quel, absent = rien", () => {
+    expect(cellVisualOf(true)).toEqual({ type: "bar" })
+    expect(cellVisualOf(undefined)).toBeUndefined()
+    expect(cellVisualOf(false)).toBeUndefined()
+    expect(cellVisualOf({ type: "delta" })).toEqual({ type: "delta" })
+  })
+})
+
+describe("cellScale", () => {
+  it("bornes observées, ramenées à zéro", () => {
+    expect(cellScale([10, 50, 100], { type: "bar" })).toEqual({ min: 0, max: 100, maxAbs: 100 })
+    expect(cellScale([-10, 20], { type: "delta" })).toEqual({ min: -10, max: 20, maxAbs: 20 })
+  })
+
+  it("bornes explicites (`min` / `max`) et valeurs non numériques ignorées", () => {
+    expect(cellScale([10, null, "x", 30], { type: "bar", min: 0, max: 200 })).toEqual({
+      min: 0,
+      max: 200,
+      maxAbs: 200,
+    })
+    expect(cellScale([], { type: "bar" })).toEqual({ min: 0, max: 0, maxAbs: Number.EPSILON })
+  })
+})
+
+describe("cellBarGeometry", () => {
+  const scale = { min: 0, max: 100, maxAbs: 100 }
+
+  it("`bar` : barre à gauche proportionnelle à la valeur", () => {
+    expect(cellBarGeometry(50, { type: "bar" }, scale)).toEqual({
+      width: 50,
+      left: 0,
+      ratio: 0.5,
+      diverging: false,
+      sign: 1,
+    })
+    expect(cellBarGeometry(-25, { type: "bar" }, scale)?.width).toBe(25)
+    expect(cellBarGeometry(0, { type: "bar" }, scale)?.width).toBe(0)
+  })
+
+  it("`delta` : divergente depuis 50 %, positives à droite", () => {
+    expect(cellBarGeometry(25, { type: "delta" }, scale)).toMatchObject({
+      left: 50,
+      width: 12.5,
+      diverging: true,
+      sign: 1,
+    })
+    expect(cellBarGeometry(-25, { type: "delta" }, scale)).toMatchObject({
+      left: 37.5,
+      width: 12.5,
+      diverging: true,
+      sign: -1,
+    })
+  })
+
+  it("`heat` : barre pleine largeur, l'intensité porte la valeur", () => {
+    expect(cellBarGeometry(25, { type: "heat" }, scale)).toMatchObject({ left: 0, width: 100, ratio: 0.25 })
+  })
+
+  it("aucune barre pour une sparkline ou une valeur manquante", () => {
+    expect(cellBarGeometry(10, { type: "sparkline" }, scale)).toBeUndefined()
+    expect(cellBarGeometry(undefined, { type: "bar" }, scale)).toBeUndefined()
+    expect(cellBarGeometry("x", { type: "bar" }, scale)).toBeUndefined()
+  })
+})
+
+describe("sparklineGeometry", () => {
+  it("trace la ligne, la surface et le point final", () => {
+    const spark = sparklineGeometry([1, 2, 3], { point: "last" })!
+    expect(spark.points.length).toBe(3)
+    expect(spark.path.startsWith("M2,")).toBe(true)
+    expect(spark.path).toContain("L98,2")
+    expect(spark.areaPath).toContain("Z")
+    expect(spark.marker).toEqual(spark.points[2]!)
+  })
+
+  it("met en évidence `first`, `high`, `low` ou rien", () => {
+    const first = sparklineGeometry([3, 1, 7], { point: "first" })!
+    expect(first.marker).toEqual(first.points[0]!)
+    const high = sparklineGeometry([3, 1, 7], { point: "high" })!
+    expect(high.marker).toEqual(high.points[2]!)
+    const low = sparklineGeometry([3, 1, 7], { point: "low" })!
+    expect(low.marker).toEqual(low.points[1]!)
+    expect(sparklineGeometry([3, 1, 7], { point: false })!.marker).toBeUndefined()
+  })
+
+  it("valeurs constantes : ligne au milieu ; aucune valeur : rien", () => {
+    const flat = sparklineGeometry([5, 5, 5])!
+    expect(flat.points.every((p) => p.y === flat.points[0]!.y)).toBe(true)
+    expect(flat.points[0]!.y).toBe(12)
+    expect(sparklineGeometry([])).toBeUndefined()
+    expect(sparklineGeometry(undefined)).toBeUndefined()
+  })
+})
+
+describe("tableModel — échelles et totaux des micro-visualisations", () => {
+  const rows = [
+    { type: "A", orders: 100, target: 10, trend: [1, 2, 3] },
+    { type: "B", orders: 50, target: -5, trend: [3, 2, 1] },
+  ]
+  const mark = {
+    type: "table" as const,
+    data: rows,
+    totals: { label: "Total" },
+    columns: [
+      { field: "type", label: "Type" },
+      { field: "orders", label: "Orders", cell: { type: "bar" as const } },
+      { field: "target", label: "vs Target", cell: { type: "delta" as const } },
+      { field: "trend", label: "Trend", cell: { type: "sparkline" as const } },
+    ],
+  }
+
+  it("calcule une échelle par colonne visualisée (jamais pour une sparkline)", () => {
+    const model = tableModel(mark)
+    expect(model.cellScales).toEqual({
+      orders: { min: 0, max: 100, maxAbs: 100 },
+      target: { min: -5, max: 10, maxAbs: 10 },
+    })
+    expect(model.cellScales?.trend).toBeUndefined()
+  })
+
+  it("expose les valeurs **brutes** des totaux pour les barres du pied de table", () => {
+    const model = tableModel(mark)
+    expect(model.totalValues).toEqual({ orders: 150, target: 5 })
+    expect(model.totals).toEqual({ type: "Total", orders: "150", target: "5" })
+  })
+
+  it("sans `cell`, pas d'échelle (modèle inchangé)", () => {
+    const model = tableModel({ type: "table", data: rows, columns: ["type", "orders"] })
+    expect(model.cellScales).toBeUndefined()
+    expect(model.totalValues).toBeUndefined()
+    expect(model.totals).toBeUndefined()
+  })
+})