@dnax/ui 0.0.46 → 0.0.49

package/lib/mapLeaflet.ts

@@ -0,0 +1,142 @@
+// mapLeaflet — moteur **Leaflet** de `<q-map>` : raster sans clé, importé dynamiquement.
+//
+// Trois différences à garder en tête :
+//  - Leaflet travaille en **`[lat, lng]`** (l'inverse de dnax.ui, qui expose `[lng, lat]`)
+//    → toute position passe par `toLeaflet()` ;
+//  - il n'a ni styles vectoriels, ni relief, ni projection : `setStyle` / `setTerrain` /
+//    `setProjection` n'y font rien, c'est `setRaster` qui change la couche de tuiles ;
+//  - ses épingles par défaut sont des **images** (impossible de les recolorer par option)
+//    → les marqueurs sont dessinés en `divIcon` SVG, ce qui permet la prop `color`.
+import {
+  safeCssColor,
+  toLeaflet,
+  type QMapLeafletOptions,
+  type QMapMarkSpec,
+} from "./map"
+import type { MapEngine, MapEngineInput } from "./mapEngine"
+
+/** Épingle SVG (couleur du thème) : Leaflet place le `div`, l'ancre est au pied du pin. */
+const pinIcon = (L: any, color: string) =>
+  L.divIcon({
+    className: "q-map__pin",
+    html:
+      '<svg viewBox="0 0 24 24" width="26" height="26" aria-hidden="true">' +
+      `<path d="M12 2c-3.9 0-7 3.1-7 7 0 5.2 7 13 7 13s7-7.8 7-13c0-3.9-3.1-7-7-7z" fill="${color}" stroke="#fff" stroke-width="1.6"/>` +
+      '<circle cx="12" cy="9" r="2.6" fill="#fff"/>' +
+      "</svg>",
+    iconSize: [26, 26],
+    iconAnchor: [13, 25],
+    popupAnchor: [0, -22],
+  })
+
+export async function createLeafletEngine(input: MapEngineInput): Promise<MapEngine> {
+  // Le paquet n'a pas d'export ESM explicite : on prend le défaut, sinon le module.
+  const leaflet: any = await import("leaflet")
+  const L: any = leaflet.default ?? leaflet
+  const options = input.options as QMapLeafletOptions
+
+  const map = L.map(input.el, {
+    center: options.center,
+    zoom: options.zoom,
+    ...options.mapOptions,
+  })
+
+  let layer = L.tileLayer(options.tiles, {
+    attribution: options.attribution,
+    ...options.layerOptions,
+  }).addTo(map)
+
+  let created: Array<() => void> = []
+  let readyCallbacks: Array<(engine: MapEngine) => void> = []
+  let ready = false
+
+  const clearMarks = () => {
+    for (const dispose of created) dispose()
+    created = []
+  }
+
+  /** Bulle thématée : la classe est posée sur le conteneur `.leaflet-popup`. */
+  const popupOptions = (offset?: number) => ({
+    className: "q-map__popup",
+    offset: L.point(0, -(typeof offset === "number" ? offset : 18)),
+  })
+
+  const engine: MapEngine = {
+    native: map,
+
+    setView: (center, zoom) => map.setView(toLeaflet(center), zoom),
+
+    // Leaflet n'a pas de notion de style : la couche de tuiles est la carte.
+    setStyle: () => {},
+
+    setRaster: (tiles, attribution) => {
+      const next = L.tileLayer(tiles, {
+        attribution: attribution ?? options.attribution,
+        ...options.layerOptions,
+      })
+      map.removeLayer(layer)
+      layer = next.addTo(map)
+    },
+
+    setMarks: (marks: QMapMarkSpec[]) => {
+      clearMarks()
+
+      for (const { mark, index, position, html } of marks) {
+        const latlng = toLeaflet(position)
+        const onPick = () => input.pick({ mark, index, position, lng: position[0], lat: position[1] })
+
+        if (mark.type === "popup") {
+          if (!html) continue
+          const popup = L.popup(popupOptions(mark.offset)).setLatLng(latlng).setContent(html)
+          if (mark.open !== false) popup.openOn(map)
+
+          const node = popup.getElement() as HTMLElement | null
+          node?.addEventListener("click", onPick)
+          created.push(() => {
+            node?.removeEventListener("click", onPick)
+            popup.remove()
+          })
+          continue
+        }
+
+        const marker = L.marker(latlng, {
+          icon: pinIcon(L, safeCssColor(input.color(mark.color)) ?? "#1976d2"),
+          draggable: !!mark.draggable,
+        })
+        if (html) marker.bindPopup(html, popupOptions(mark.offset))
+        marker.addTo(map)
+        if (mark.open && html) marker.openPopup()
+
+        marker.on("click", onPick)
+        created.push(() => marker.remove())
+      }
+    },
+
+    setTerrain: () => {},
+    setProjection: () => {},
+
+    resize: () => map.invalidateSize(),
+
+    destroy: () => {
+      clearMarks()
+      map.remove()
+    },
+
+    onReady: (callback) => {
+      if (ready) callback(engine)
+      else readyCallbacks.push(callback)
+    },
+  }
+
+  map.whenReady(() => {
+    if (ready) return
+    ready = true
+    const callbacks = readyCallbacks
+    readyCallbacks = []
+    for (const callback of callbacks) callback(engine)
+  })
+
+  engine.setMarks(input.marks)
+
+  return engine
+}

package/lib/mapMaplibre.ts

@@ -0,0 +1,106 @@
+// mapMaplibre — moteur **MapLibre GL JS** seul (sans le SDK MapTiler) : le fork
+// open-source de mapbox-gl, importé dynamiquement (aucun WebGL ni DOM au prerender SSR).
+//
+// Différences avec le moteur MapTiler, qui partage pourtant la même base :
+//  - **aucun catalogue de styles** ni clé d'API : le style (`map-style`) est résolu par
+//    `maplibreStyle()` — style de démonstration MapLibre, raster OSM, URL ou objet ;
+//  - **aucun contrôle par défaut** : le SDK MapTiler ajoute zoom/géolocalisation tout
+//    seul, ici ils sont montés explicitement depuis les props ;
+//  - **pas de source de relief** : `terrain` n'a pas d'effet (on passe `options.terrain`
+//    au constructeur, avec une source DEM déclarée par le style).
+import { maplibreStyle, type QMapMaplibreOptions } from "./map"
+import {
+  buildMapLibreMarks,
+  controlPosition,
+  type MapEngine,
+  type MapEngineInput,
+} from "./mapEngine"
+
+export async function createMaplibreEngine(input: MapEngineInput): Promise<MapEngine> {
+  // Le paquet est un bundle UMD : on prend le défaut, sinon le module.
+  const mod: any = await import("maplibre-gl")
+  const maplibregl: any = mod.default ?? mod
+
+  const options = input.options as QMapMaplibreOptions
+  const map = new maplibregl.Map({ ...options.map, container: input.el })
+
+  if (!options.styleKnown) {
+    console.warn(
+      '[q-map] `map-style` inconnu avec provider="maplibre" : repli sur le style de ' +
+        'démonstration MapLibre (valeurs : "demotiles", "openstreetmap", une URL de style)',
+    )
+  }
+
+  // Contrôles : MapLibre n'en monte aucun de lui-même (le SDK MapTiler, si).
+  const controls = input.controls ?? {}
+  if (controls.navigation !== false) {
+    map.addControl(
+      new maplibregl.NavigationControl(),
+      controlPosition(controls.navigation, "top-right"),
+    )
+  }
+  if (controls.geolocate !== false) {
+    map.addControl(
+      new maplibregl.GeolocateControl({ trackUserLocation: false }),
+      controlPosition(controls.geolocate, "top-right"),
+    )
+  }
+  if (controls.scale) {
+    map.addControl(new maplibregl.ScaleControl(), controlPosition(controls.scale, "bottom-right"))
+  }
+  if (controls.fullscreen) {
+    map.addControl(
+      new maplibregl.FullscreenControl(),
+      controlPosition(controls.fullscreen, "top-right"),
+    )
+  }
+
+  let clear = () => {}
+  let readyCallbacks: Array<(engine: MapEngine) => void> = []
+  let ready = false
+
+  const engine: MapEngine = {
+    native: map,
+
+    setView: (center, zoom) => map.jumpTo({ center, zoom }),
+
+    setStyle: (style) => map.setStyle(maplibreStyle({ style }).style),
+
+    setMarks: (marks) => {
+      clear()
+      clear = buildMapLibreMarks(maplibregl, map, marks, input)
+    },
+
+    // Pas de relief sans source DEM : `options.terrain` (constructeur) porte le cas.
+    setTerrain: () => {},
+
+    setProjection: (projection) => map.setProjection({ type: projection }),
+
+    resize: () => map.resize(),
+
+    destroy: () => {
+      clear()
+      map.remove()
+    },
+
+    onReady: (callback) => {
+      if (ready) callback(engine)
+      else readyCallbacks.push(callback)
+    },
+  }
+
+  const markReady = () => {
+    if (ready) return
+    ready = true
+    const callbacks = readyCallbacks
+    readyCallbacks = []
+    for (const callback of callbacks) callback(engine)
+  }
+
+  map.on("load", markReady)
+  map.on("error", (event: unknown) => input.error((event as any)?.error ?? event))
+
+  engine.setMarks(input.marks)
+
+  return engine
+}

package/lib/mapMaptiler.ts

@@ -0,0 +1,93 @@
+// mapMaptiler — moteur **MapTiler / OpenStreetMap** de `<q-map>` : le SDK JS MapTiler v4
+// (MapLibre GL JS + catalogue de styles + APIs), importé dynamiquement (aucun WebGL ni DOM
+// au prerender SSR).
+//
+// Le même moteur sert les deux fournisseurs : `maptiler` (styles vectoriels + clé) et
+// `openstreetmap` (style raster construit par `mapOptionsOf`, sans clé). Les méthodes qui
+// n'ont de sens que sur les styles MapTiler (`enableTerrain`, `setProjection`) sont
+// ignorées pour `openstreetmap`.
+//
+// C'est aussi lui qui résout les **noms courts de style** (`streets`, `dataviz`…) en
+// `MapStyle` du SDK — variante `.DARK` comprise — puisque c'est lui qui détient le SDK.
+import { mapStyleKey } from "./map"
+import { buildMapLibreMarks, type MapEngine, type MapEngineInput } from "./mapEngine"
+
+export async function createMaptilerEngine(input: MapEngineInput): Promise<MapEngine> {
+  const sdk: any = await import("@maptiler/sdk")
+
+  /** Nom court → `MapStyle` du SDK (+ variante sombre si elle existe) ; un objet de
+   *  style, un ID ou une URL sont rendus tels quels. */
+  const resolveStyle = (value: unknown, dark?: boolean): unknown => {
+    const key = mapStyleKey(value)
+    if (!key) return value
+
+    const reference = sdk.MapStyle?.[key.toUpperCase()]
+    if (!reference) return value
+
+    return dark && reference.DARK ? reference.DARK : reference
+  }
+
+  const options = { ...input.options, style: resolveStyle(input.options.style, input.dark) }
+  const map = new sdk.Map({ ...options, container: input.el })
+
+  let clear = () => {}
+  let readyCallbacks: Array<(engine: MapEngine) => void> = []
+  let ready = false
+
+  /** Relief et projection n'ont de sens qu'avec les styles du catalogue MapTiler. */
+  const terrainSupported = input.provider === "maptiler"
+
+  const engine: MapEngine = {
+    native: map,
+
+    setView: (center, zoom) => map.jumpTo({ center, zoom }),
+
+    setStyle: (style, dark) => map.setStyle(resolveStyle(style, dark)),
+
+    setMarks: (marks) => {
+      clear()
+      clear = buildMapLibreMarks(sdk, map, marks, input)
+    },
+
+    setTerrain: (on) => {
+      if (!terrainSupported) return
+      if (on) map.enableTerrain?.()
+      else map.disableTerrain?.()
+    },
+
+    setProjection: (projection) => {
+      if (!terrainSupported) return
+      map.setProjection?.(projection, { persist: true })
+    },
+
+    resize: () => map.resize?.(),
+
+    destroy: () => {
+      clear()
+      map.remove?.()
+    },
+
+    onReady: (callback) => {
+      if (ready) callback(engine)
+      else readyCallbacks.push(callback)
+    },
+  }
+
+  // Premier `load` **ou** `ready` : le second attend la fin de l'installation des
+  // contrôles du SDK, il peut donc être retardé.
+  const markReady = () => {
+    if (ready) return
+    ready = true
+    const callbacks = readyCallbacks
+    readyCallbacks = []
+    for (const callback of callbacks) callback(engine)
+  }
+
+  map.on("load", markReady)
+  map.on("ready", markReady)
+  map.on("error", (event: unknown) => input.error((event as any)?.error ?? event))
+
+  engine.setMarks(input.marks)
+
+  return engine
+}

package/lib/numericKeyboard.test.ts

@@ -0,0 +1,179 @@
+// Tests unitaires du clavier numérique : disposition des touches et règles de saisie.
+import { describe, expect, it } from "bun:test"
+import {
+  applyDigitOrder,
+  decimalCount,
+  digitCount,
+  keypadDigits,
+  keypadLayout,
+  pressKey,
+  pressKeys,
+  shuffledDigits,
+} from "./numericKeyboard"
+
+describe("keypadLayout", () => {
+  it("rend 12 touches, 1-9 puis 0 et l'effacement", () => {
+    const keys = keypadLayout()
+    expect(keys).toHaveLength(12)
+    expect(keys.slice(0, 9).map((k) => k.key)).toEqual([
+      "1",
+      "2",
+      "3",
+      "4",
+      "5",
+      "6",
+      "7",
+      "8",
+      "9",
+    ])
+    expect(keys[9]!.kind).toBe("empty")
+    expect(keys[10]!.key).toBe("0")
+    expect(keys[11]).toMatchObject({ key: "backspace", kind: "backspace", label: "⌫" })
+  })
+
+  it("met « C » dans la case libre en mode numeric + clearable", () => {
+    const keys = keypadLayout({ clearable: true })
+    expect(keys[9]).toMatchObject({ key: "clear", label: "C", kind: "clear" })
+  })
+
+  it("met le séparateur décimal en mode decimal (et jamais de C)", () => {
+    const keys = keypadLayout({ mode: "decimal", clearable: true })
+    expect(keys[9]).toMatchObject({ key: "separator", label: ",", kind: "separator" })
+    expect(keys.some((k) => k.kind === "clear")).toBe(false)
+  })
+
+  it("affiche le séparateur demandé", () => {
+    expect(keypadLayout({ mode: "decimal", decimalSeparator: "." })[9]!.label).toBe(".")
+    expect(keypadLayout({ mode: "decimal", decimalSeparator: "." })[9]!.ariaLabel).toContain(".")
+  })
+})
+
+describe("compteurs", () => {
+  it("compte les chiffres, séparateur exclu", () => {
+    expect(digitCount("12,50")).toBe(4)
+    expect(digitCount("")).toBe(0)
+  })
+
+  it("compte les décimales saisies", () => {
+    expect(decimalCount("12,5")).toBe(1)
+    expect(decimalCount("12,")).toBe(0)
+    expect(decimalCount("12")).toBe(-1)
+  })
+})
+
+describe("pressKey — chiffres", () => {
+  it("ajoute les chiffres bout à bout", () => {
+    expect(pressKeys("", ["1", "2", "3"])).toBe("123")
+  })
+
+  it("conserve les zéros de tête en mode numeric (code, téléphone)", () => {
+    expect(pressKeys("", ["0", "4", "0", "6"])).toBe("0406")
+  })
+
+  it("remplace le « 0 » seul en mode decimal (montant)", () => {
+    expect(pressKeys("", ["0", "5"], { mode: "decimal" })).toBe("5")
+    expect(pressKeys("", ["0", "5"], { mode: "numeric" })).toBe("05")
+    // … mais pas derrière le séparateur : « 0,5 » reste « 0,5 »
+    expect(pressKeys("0,", ["5"], { mode: "decimal" })).toBe("0,5")
+  })
+
+  it("respecte maxLength (en chiffres), quel que soit le séparateur", () => {
+    expect(pressKeys("", ["1", "2", "3", "4"], { maxLength: 3 })).toBe("123")
+    expect(pressKeys("12", ["3"], { maxLength: 3, mode: "decimal" })).toBe("123")
+    // Le séparateur ne compte pas : « 12,5 » = 3 chiffres, le 4e est refusé si maxLength = 3
+    expect(pressKeys("12,5", ["9"], { maxLength: 3, mode: "decimal" })).toBe("12,5")
+    expect(pressKeys("12,5", ["9"], { maxLength: 4, mode: "decimal" })).toBe("12,59")
+  })
+
+  it("ignore les touches inconnues", () => {
+    expect(pressKey("12", "abc")).toBe("12")
+  })
+})
+
+describe("pressKey — séparateur, décimales", () => {
+  it("n'accepte le séparateur qu'une fois, jamais en mode numeric", () => {
+    expect(pressKeys("", ["separator", "separator"], { mode: "decimal" })).toBe("0,")
+    expect(pressKeys("12", ["separator"], { mode: "decimal" })).toBe("12,")
+    expect(pressKeys("12", ["separator"], { mode: "numeric" })).toBe("12")
+  })
+
+  it("pose « 0, » quand le champ est vide", () => {
+    expect(pressKey("", "separator", { mode: "decimal" })).toBe("0,")
+  })
+
+  it("borne les décimales avec maxDecimals", () => {
+    expect(pressKeys("12,", ["5", "0", "9"], { mode: "decimal", maxDecimals: 2 })).toBe("12,50")
+    expect(pressKey("12,5", "separator", { mode: "decimal", maxDecimals: 0 })).toBe("12,5")
+  })
+
+  it("suit le séparateur demandé", () => {
+    expect(pressKeys("", ["1", "separator", "5"], { mode: "decimal", decimalSeparator: "." })).toBe(
+      "1.5",
+    )
+  })
+})
+
+describe("pressKey — effacement", () => {
+  it("retire le dernier caractère, puis vide", () => {
+    expect(pressKeys("123", ["backspace", "backspace"])).toBe("1")
+    expect(pressKey("1", "backspace")).toBe("")
+    expect(pressKey("", "backspace")).toBe("")
+  })
+
+  it("efface tout avec clear", () => {
+    expect(pressKey("12,50", "clear")).toBe("")
+  })
+
+  it("permet de repartir après un effacement complet", () => {
+    expect(pressKeys("123", ["clear", "7"])).toBe("7")
+  })
+})
+
+describe("disposition aléatoire", () => {
+  /** Générateur congruentiel linéaire : une suite reproductible pour les tests */
+  const seeded = (seed: number) => {
+    let state = seed
+    return () => {
+      state = (state * 1664525 + 1013904223) % 4294967296
+      return state / 4294967296
+    }
+  }
+
+  it("mélange les dix chiffres, sans perte ni doublon", () => {
+    const order = shuffledDigits()
+    expect([...order].sort()).toEqual([...keypadDigits].sort())
+    expect(new Set(order).size).toBe(10)
+  })
+
+  it("est reproductible pour une graine donnée", () => {
+    expect(shuffledDigits(seeded(7))).toEqual(shuffledDigits(seeded(7)))
+  })
+
+  it("ne retombe pas sur l'ordre canonique avec un vrai aléa", () => {
+    const canonical = keypadDigits.join("")
+    const identical = Array.from({ length: 100 }, () => shuffledDigits().join("")).filter(
+      (order) => order === canonical,
+    )
+    expect(identical).toHaveLength(0)
+  })
+
+  it("répartit les chiffres dans les cellules et laisse les touches d'édition", () => {
+    const base = keypadLayout({ mode: "decimal" })
+    const order = ["9", "8", "7", "6", "5", "4", "3", "2", "1", "0"]
+    const shuffled = applyDigitOrder(base, order)
+
+    expect(shuffled[0]).toMatchObject({ key: "9", kind: "digit" })
+    expect(shuffled[8]).toMatchObject({ key: "1", kind: "digit" })
+    expect(shuffled[10]).toMatchObject({ key: "0", kind: "digit" })
+    // Le séparateur (case 9) et l'effacement (case 11) ne bougent pas
+    expect(shuffled[9]).toMatchObject({ key: "separator", kind: "separator" })
+    expect(shuffled[11]).toMatchObject({ key: "backspace", kind: "backspace" })
+  })
+
+  it("garde dix touches chiffre et les touches spéciales en place (clearable)", () => {
+    const shuffled = applyDigitOrder(keypadLayout({ clearable: true }), shuffledDigits(seeded(3)))
+    expect(shuffled.filter((k) => k.kind === "digit")).toHaveLength(10)
+    expect(shuffled[9]!.kind).toBe("clear")
+    expect(shuffled[11]!.kind).toBe("backspace")
+  })
+})

package/lib/numericKeyboard.ts

@@ -0,0 +1,166 @@
+// numericKeyboard — clavier numérique (pavé à l'écran) : disposition des touches et règles de
+// saisie (chiffres, séparateur décimal, effacement, longueur maximale, zéros de tête).
+//
+// Pur (aucun DOM) → testable hors navigateur, comme `lib/pagePadding.ts`. La valeur manipulée
+// est une **chaîne** : c'est ce qui conserve les zéros de tête d'un code (0406) et évite les
+// arrondis flottants d'un montant.
+
+/** Nature d'une touche — sert au style et à l'action */
+export type KeypadKeyKind = "digit" | "separator" | "backspace" | "clear" | "empty"
+
+export interface KeypadKey {
+  /** Identifiant de la touche : `"0"`–`"9"`, `"separator"`, `"backspace"`, `"clear"`, `""` */
+  key: string
+  kind: KeypadKeyKind
+  /** Texte affiché (le séparateur affiche celui de la locale) */
+  label: string
+  /** Libellé accessible quand la touche n'est pas un chiffre */
+  ariaLabel?: string
+}
+
+export type KeypadMode = "numeric" | "decimal"
+
+export interface KeypadOptions {
+  /** `numeric` (défaut : code, téléphone) ou `decimal` (montants : touche séparateur) */
+  mode?: KeypadMode
+  /** Ajoute une touche « tout effacer » si une case est libre (`numeric`) */
+  clearable?: boolean
+  /** Séparateur décimal affiché — `,` par défaut (français), `.` en anglais */
+  decimalSeparator?: string
+}
+
+/**
+ * Les 12 touches du pavé (3 × 4). En mode `numeric` la case en bas à gauche est libre —
+ * elle accueille la touche « C » quand `clearable` est demandé ; en mode `decimal` elle
+ * porte le séparateur, il n'y a donc pas de place pour « C » (voir `clear()`).
+ */
+export function keypadLayout(options: KeypadOptions = {}): KeypadKey[] {
+  const separator = (options.decimalSeparator ?? ",").slice(0, 1) || ","
+  const mode = options.mode === "decimal" ? "decimal" : "numeric"
+
+  const digit = (value: string): KeypadKey => ({ key: value, kind: "digit", label: value })
+
+  return [
+    digit("1"),
+    digit("2"),
+    digit("3"),
+    digit("4"),
+    digit("5"),
+    digit("6"),
+    digit("7"),
+    digit("8"),
+    digit("9"),
+    mode === "decimal"
+      ? { key: "separator", kind: "separator", label: separator, ariaLabel: `Séparateur décimal (${separator})` }
+      : options.clearable
+        ? { key: "clear", kind: "clear", label: "C", ariaLabel: "Tout effacer" }
+        : { key: "", kind: "empty", label: "" },
+    digit("0"),
+    { key: "backspace", kind: "backspace", label: "⌫", ariaLabel: "Effacer le dernier chiffre" },
+  ]
+}
+
+/** Les dix chiffres d'une disposition de pavé, dans l'ordre canonique */
+export const keypadDigits = ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9"] as const
+
+/**
+ * Une permutation aléatoire de `0`-`9` (Fisher–Yates), pour un pavé à **disposition
+ * aléatoire** (anti-observation : un code tapé sous les yeux d'un tiers).
+ *
+ * `rng` est injectable (tests, graine) ; par défaut `Math.random`. Le mélange porte sur les
+ * chiffres **entre eux** : c'est `applyDigitOrder` qui les répartit ensuite dans les cellules,
+ * en laissant les touches d'édition (séparateur, `C`, `⌫`) à leur place.
+ */
+export function shuffledDigits(rng: () => number = Math.random): string[] {
+  const digits = [...keypadDigits]
+  for (let i = digits.length - 1; i > 0; i--) {
+    const j = Math.floor(rng() * (i + 1))
+    const swap = digits[i]!
+    digits[i] = digits[j]!
+    digits[j] = swap
+  }
+  return digits
+}
+
+/**
+ * Répartit des chiffres (`order`, une permutation de `0`-`9`) dans les cellules « chiffre »
+ * d'une disposition, les autres touches restant à leur place. Si `order` est plus courte que le
+ * nombre de cellules, les cellules surnuméraires gardent leur chiffre d'origine.
+ */
+export function applyDigitOrder(keys: KeypadKey[], order: readonly string[]): KeypadKey[] {
+  let index = 0
+  return keys.map((key) => {
+    if (key.kind !== "digit") return key
+    const value = order[index++]
+    return value ? { ...key, key: value, label: value } : key
+  })
+}
+
+export interface KeypadPressOptions extends KeypadOptions {
+  /** Longueur maximale, en **chiffres** (le séparateur ne compte pas) — 0 = illimité */
+  maxLength?: number
+  /** Nombre maximal de décimales après le séparateur — 0 = illimité */
+  maxDecimals?: number
+  /** Interdit un second séparateur (défaut) — `false` pour l'autoriser ? Jamais utile. */
+  allowMultipleSeparators?: boolean
+}
+
+/** Nombre de chiffres d'une valeur de pavé (séparateur exclu) */
+export const digitCount = (value: string): number => (value.match(/[0-9]/g) ?? []).length
+
+/** Nombre de décimales saisies après le séparateur (`-1` s'il n'y en a pas) */
+export const decimalCount = (value: string, separator = ","): number => {
+  const index = value.indexOf(separator)
+  return index === -1 ? -1 : digitCount(value.slice(index + 1))
+}
+
+/**
+ * Applique une touche à une valeur et renvoie la nouvelle valeur.
+ *
+ * - `backspace` retire le dernier caractère, `clear` vide la valeur ;
+ * - un chiffre au-delà de `maxLength` (en chiffres) est ignoré ;
+ * - le séparateur s'insère au plus une fois, et « 0, » est posé si le champ est vide ;
+ * - `maxDecimals` borne les décimales (les chiffres surnuméraires sont ignorés) ;
+ * - en mode `decimal` (montants), un « 0 » seul est **remplacé** par le chiffre suivant
+ *   (saisie façon calculatrice) ; en mode `numeric` (code, téléphone) il est **conservé**,
+ *   pour ne pas perdre les zéros de tête.
+ */
+export function pressKey(
+  value: string,
+  key: string,
+  options: KeypadPressOptions = {},
+): string {
+  const current = typeof value === "string" ? value : ""
+  const separator = (options.decimalSeparator ?? ",").slice(0, 1) || ","
+  const mode = options.mode === "decimal" ? "decimal" : "numeric"
+  const maxDigits = typeof options.maxLength === "number" && options.maxLength > 0 ? options.maxLength : Infinity
+  const maxDecimals =
+    typeof options.maxDecimals === "number" && options.maxDecimals >= 0 ? options.maxDecimals : Infinity
+
+  if (key === "backspace") return current.slice(0, -1)
+  if (key === "clear") return ""
+
+  if (key === "separator") {
+    if (mode !== "decimal" || maxDecimals === 0) return current
+    if (current.includes(separator)) return current
+    if (!current) return `0${separator}`
+    return current.endsWith(separator) ? current : `${current}${separator}`
+  }
+
+  if (!/^[0-9]$/.test(key)) return current
+
+  // Décimales déjà complètes → le chiffre est ignoré
+  const decimals = decimalCount(current, separator)
+  if (decimals >= 0 && decimals >= maxDecimals) return current
+  if (digitCount(current) >= maxDigits) return current
+
+  // Calculatrice : « 0 » seul est remplacé (montants), sauf derrière le séparateur (« 0,5 »)
+  if (mode === "decimal" && current === "0") return key
+
+  return `${current}${key}`
+}
+
+/** Applique une suite de touches (utile aux tests et à une saisie programmée) */
+export function pressKeys(value: string, keys: string[], options: KeypadPressOptions = {}): string {
+  return keys.reduce((acc, key) => pressKey(acc, key, options), value)
+}