@dnax/ui 0.0.48 → 0.0.50

package/components/QTimeline.vue

@@ -0,0 +1,111 @@
+<script lang="ts">
+// QTimeline — conteneur d'une frise chronologique verticale (API Quasar).
+//   <q-timeline color="primary" layout="comfortable">
+//     <q-timeline-entry heading title="2024" />
+//     <q-timeline-entry title="Shipped" icon="lucide:check" />
+//   </q-timeline>
+//
+// Le conteneur dessine le rail (ligne de 1px) et transmet la couleur et
+// l'espacement aux entrées, à la fois par `provide`/`inject` (ci-dessous) et par
+// des variables CSS héritées (`--q-timeline-color`, `--q-timeline-gap`…).
+import type { ComputedRef, InjectionKey } from "vue"
+
+/** Espacement vertical de la frise */
+export type TimelineLayout = "dense" | "comfortable" | "loose"
+
+/** Contexte hérité par les entrées (voir `qTimelineKey`). */
+export interface TimelineContext {
+  /** Couleur du rail et des pastilles (token ou hex) */
+  color: string
+  /** Espacement vertical des entrées */
+  layout: TimelineLayout
+}
+
+/** Clé locale d'injection : couleur + layout du conteneur vers les entrées. */
+export const qTimelineKey: InjectionKey<ComputedRef<TimelineContext>> = Symbol("q-timeline")
+</script>
+
+<script setup lang="ts">
+import { computed, provide } from "vue"
+import { cn } from "../lib/utils"
+import { colorValue, foregroundFor } from "../lib/colors"
+
+interface Props {
+  /** Couleur du rail et des pastilles par défaut (token ou hex) */
+  color?: string
+  /** Thème sombre */
+  dark?: boolean
+  /** Élément rendu (`ul` par défaut) */
+  tag?: string
+  /** Espacement vertical : dense | comfortable (défaut) | loose */
+  layout?: TimelineLayout
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  color: "primary",
+  dark: false,
+  tag: "ul",
+  layout: "comfortable",
+})
+
+const timelineClasses = computed(() =>
+  cn("q-timeline", `q-timeline--${props.layout}`, props.dark && "q-timeline--dark"),
+)
+
+// Variables CSS posées sur la racine : le rail les lit, les entrées les héritent.
+const timelineStyle = computed<Record<string, string>>(() => ({
+  "--q-timeline-color": colorValue(props.color),
+  "--q-timeline-color-foreground": foregroundFor(props.color),
+  ...(props.dark
+    ? {
+        "--q-timeline-fg": "#e6edf3",
+        "--q-timeline-muted": "rgb(255 255 255 / 0.6)",
+        "--q-timeline-surface": "#0f1115",
+      }
+    : {}),
+}))
+
+provide(qTimelineKey, computed<TimelineContext>(() => ({ color: props.color, layout: props.layout })))
+</script>
+
+<template>
+  <component
+    :is="tag"
+    class="q-timeline"
+    :class="timelineClasses"
+    :style="timelineStyle"
+    role="list"
+    v-bind="$attrs"
+  >
+    <slot />
+  </component>
+</template>
+
+<style scoped>
+.q-timeline {
+  position: relative;
+  width: 100%;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  color: var(--q-timeline-fg, var(--foreground, #1d1d1d));
+}
+
+/* Rail vertical : une ligne de 1px centrée qui traverse toute la frise.
+   La couleur est héritée du conteneur, surchargeable par entrée. */
+.q-timeline::before {
+  content: "";
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  left: 50%;
+  width: 1px;
+  transform: translateX(-50%);
+  background-color: var(--q-timeline-color, var(--primary));
+}
+
+/* Thème sombre forcé par la prop `dark` (les variables sont posées inline). */
+.q-timeline--dark {
+  color: var(--q-timeline-fg, #e6edf3);
+}
+</style>

package/components/QTimelineEntry.vue

@@ -0,0 +1,271 @@
+<script setup lang="ts">
+// QTimelineEntry — une entrée de <q-timeline> (API Quasar).
+//   <q-timeline-entry heading title="2024" />
+//   <q-timeline-entry title="Shipped" subtitle="2 days ago" icon="lucide:check" color="positive" />
+//
+// `side` place l'entrée à gauche ou à droite du rail. **Sans `side`, l'alternance
+// est automatique** : la classe `q-timeline__entry--auto` s'appuie sur
+// `:nth-child(odd|even)` de la racine du parent (impair → gauche, pair → droite) —
+// un `heading` compte donc dans l'alternance, comme dans Quasar.
+import { computed, inject } from "vue"
+import { Icon } from "@iconify/vue"
+import { cn } from "../lib/utils"
+import { colorValue, foregroundFor } from "../lib/colors"
+import { qTimelineKey, type TimelineLayout } from "./QTimeline.vue"
+
+interface Props {
+  /** Entrée « titre de période » : centrée, sans pastille ni côté */
+  heading?: boolean
+  /** Élément rendu (`li` par défaut) */
+  tag?: string
+  /** Côté de l'entrée : left | right (défaut : alternance automatique) */
+  side?: "left" | "right"
+  /** Icône Iconify dans la pastille (ex. "lucide:check") */
+  icon?: string
+  /** URL d'image dans la pastille (prioritaire sur l'icône) */
+  avatar?: string
+  /** Titre de l'entrée */
+  title?: string
+  /** Sous-titre (date, lieu…) */
+  subtitle?: string
+  /** Couleur de la pastille (token ou hex) — héritée du conteneur sinon */
+  color?: string
+  /** Thème sombre */
+  dark?: boolean
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  heading: false,
+  tag: "li",
+  icon: "",
+  avatar: "",
+  title: "",
+  subtitle: "",
+  color: "",
+  dark: false,
+})
+
+// Contexte du conteneur, avec repli si l'entrée est utilisée hors <q-timeline>.
+const timeline = inject(qTimelineKey, undefined)
+const parentColor = computed(() => timeline?.value.color ?? "primary")
+const layout = computed<TimelineLayout>(() => timeline?.value.layout ?? "comfortable")
+
+/** Espacement vertical selon le layout hérité du conteneur. */
+const LAYOUT_GAP: Record<TimelineLayout, string> = {
+  dense: "12px",
+  comfortable: "26px",
+  loose: "42px",
+}
+
+const entryClasses = computed(() =>
+  cn(
+    "q-timeline__entry",
+    // côté explicite, sinon alternance automatique (nth-child) portée par `--auto`
+    props.side ? `q-timeline__entry--${props.side}` : "q-timeline__entry--auto",
+    props.dark && "q-timeline__entry--dark",
+  ),
+)
+
+const entryStyle = computed<Record<string, string>>(() => {
+  const style: Record<string, string> = { "--q-timeline-gap": LAYOUT_GAP[layout.value] }
+
+  // Couleur propre à l'entrée → surcharge la couleur héritée du conteneur ;
+  // sinon on déduit seulement la couleur de texte de la pastille.
+  if (props.color) {
+    style["--q-timeline-color"] = colorValue(props.color)
+    style["--q-timeline-color-foreground"] = foregroundFor(props.color)
+  }
+  else {
+    style["--q-timeline-color-foreground"] = foregroundFor(parentColor.value)
+  }
+
+  if (props.dark) {
+    style["--q-timeline-fg"] = "#e6edf3"
+    style["--q-timeline-muted"] = "rgb(255 255 255 / 0.6)"
+    style["--q-timeline-surface"] = "#0f1115"
+  }
+
+  return style
+})
+</script>
+
+<template>
+  <!-- Titre de période : centré, sans pastille -->
+  <component
+    v-if="heading"
+    :is="tag"
+    class="q-timeline__heading"
+    :style="entryStyle"
+    role="listitem"
+    v-bind="$attrs"
+  >
+    <span class="q-timeline__heading-title">
+      <slot name="title">
+        <slot>{{ title }}</slot>
+      </slot>
+    </span>
+  </component>
+
+  <!-- Entrée standard : pastille posée sur le rail + contenu -->
+  <component
+    v-else
+    :is="tag"
+    class="q-timeline__entry"
+    :class="entryClasses"
+    :style="entryStyle"
+    role="listitem"
+    v-bind="$attrs"
+  >
+    <span class="q-timeline__dot">
+      <slot name="icon">
+        <img v-if="avatar" class="q-timeline__avatar" :src="avatar" alt="" />
+        <Icon v-else-if="icon" :icon="icon" class="q-timeline__icon" aria-hidden="true" />
+      </slot>
+    </span>
+
+    <div class="q-timeline__content">
+      <div v-if="$slots.title || title" class="q-timeline__title">
+        <slot name="title">{{ title }}</slot>
+      </div>
+      <div v-if="$slots.subtitle || subtitle" class="q-timeline__subtitle">
+        <slot name="subtitle">{{ subtitle }}</slot>
+      </div>
+      <div v-if="$slots.default" class="q-timeline__body">
+        <slot />
+      </div>
+    </div>
+  </component>
+</template>
+
+<style scoped>
+/* ─── Tronc commun : entrée et titre de période ─────────────────────────── */
+.q-timeline__entry,
+.q-timeline__heading {
+  position: relative;
+  padding-bottom: var(--q-timeline-gap, 26px);
+  list-style: none;
+}
+
+/* ─── Entrée standard : une demi-colonne autour du rail centré ──────────── */
+.q-timeline__entry {
+  box-sizing: border-box;
+  width: 50%;
+}
+
+/* Côté gauche (impair par défaut) : contenu poussé vers le rail, à droite */
+.q-timeline__entry--left,
+.q-timeline__entry--auto:nth-child(odd) {
+  margin-right: auto;
+  padding-right: 30px;
+  text-align: right;
+}
+
+/* Côté droit (pair par défaut) : contenu poussé vers le rail, à gauche */
+.q-timeline__entry--right,
+.q-timeline__entry--auto:nth-child(even) {
+  margin-left: auto;
+  padding-left: 30px;
+  text-align: left;
+}
+
+/* ─── Pastille posée sur le rail ────────────────────────────────────────── */
+.q-timeline__dot {
+  position: absolute;
+  top: 0;
+  z-index: 1;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 20px;
+  height: 20px;
+  overflow: hidden;
+  border-radius: 50%;
+  background-color: var(--q-timeline-color, var(--primary));
+  color: var(--q-timeline-color-foreground, var(--primary-foreground, #fff));
+  /* anneau qui détache la pastille du rail */
+  box-shadow: 0 0 0 3px var(--q-timeline-surface, var(--background, #fff));
+}
+
+.q-timeline__entry--left .q-timeline__dot,
+.q-timeline__entry--auto:nth-child(odd) .q-timeline__dot {
+  right: 0;
+  transform: translateX(50%);
+}
+
+.q-timeline__entry--right .q-timeline__dot,
+.q-timeline__entry--auto:nth-child(even) .q-timeline__dot {
+  left: 0;
+  transform: translateX(-50%);
+}
+
+.q-timeline__icon {
+  width: 12px;
+  height: 12px;
+}
+
+.q-timeline__avatar {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+/* ─── Contenu de l'entrée ───────────────────────────────────────────────── */
+.q-timeline__content {
+  display: inline-block;
+  max-width: 100%;
+  text-align: left;
+}
+
+.q-timeline__title {
+  font-size: 15px;
+  font-weight: 600;
+  line-height: 1.35;
+  color: var(--q-timeline-fg, var(--foreground, #1d1d1d));
+}
+
+.q-timeline__subtitle {
+  margin-top: 2px;
+  font-size: 12.5px;
+  color: var(--q-timeline-muted, var(--muted-foreground, rgb(0 0 0 / 0.55)));
+}
+
+.q-timeline__body {
+  margin-top: 6px;
+  font-size: 14px;
+  line-height: 1.55;
+  color: var(--q-timeline-muted, var(--muted-foreground, rgb(0 0 0 / 0.68)));
+}
+
+/* ─── Titre de période : centré, sans pastille ──────────────────────────── */
+.q-timeline__heading {
+  z-index: 1;
+  text-align: center;
+}
+
+.q-timeline__heading-title {
+  display: inline-block;
+  padding: 3px 14px;
+  font-size: 12px;
+  font-weight: 700;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: var(--q-timeline-fg, var(--foreground, #1d1d1d));
+  background-color: var(--q-timeline-surface, var(--background, #fff));
+  border-radius: 999px;
+}
+
+/* ─── Thème sombre ──────────────────────────────────────────────────────── */
+/* La prop `dark` est traitée par les variables inline (cf. entryStyle).
+   Mode sombre ambiant : repli quand les jetons du design system sont absents. */
+.dark .q-timeline__title,
+.dark .q-timeline__heading-title {
+  color: var(--q-timeline-fg, #e6edf3);
+}
+.dark .q-timeline__subtitle,
+.dark .q-timeline__body {
+  color: var(--q-timeline-muted, rgb(255 255 255 / 0.6));
+}
+.dark .q-timeline__heading-title {
+  background-color: var(--q-timeline-surface, #0f1115);
+}
+</style>

package/index.ts

@@ -67,18 +67,22 @@ export { default as QImg } from "./components/QImg.vue"
 export { default as QInfiniteScroll } from "./components/QInfiniteScroll.vue"
 export { default as QInnerLoading } from "./components/QInnerLoading.vue"
 export { default as QInput } from "./components/QInput.vue"
+export { default as QInputChat } from "./components/QInputChat.vue"
+export { default as QInputCurrency } from "./components/QInputCurrency.vue"
 export { default as QInputOtp } from "./components/QInputOtp.vue"
 export { default as QInputPassword } from "./components/QInputPassword.vue"
 export { default as QInputTag } from "./components/QInputTag.vue"
 export { default as QInteract } from "./components/QInteract.vue"
 export { default as QIntersection } from "./components/QIntersection.vue"
 export { default as QItem } from "./components/QItem.vue"
+export { default as QItemLabel } from "./components/QItemLabel.vue"
 export { default as QItemSection } from "./components/QItemSection.vue"
 export { default as QLayout } from "./components/QLayout.vue"
 export { default as QLinearProgress } from "./components/QLinearProgress.vue"
 export { default as QList } from "./components/QList.vue"
 export { default as QLoading } from "./components/QLoading.vue"
 export { default as QLoadingProvider } from "./components/QLoadingProvider.vue"
+export { default as QMap } from "./components/QMap.vue"
 export { default as QMarquee } from "./components/QMarquee.vue"
 export { default as QMessageScroller } from "./components/QMessageScroller.vue"
 export { default as QMessageScrollerButton } from "./components/QMessageScrollerButton.vue"
@@ -92,10 +96,14 @@ export { default as QNavMenuItem } from "./components/QNavMenuItem.vue"
 export { default as QNavMenuTrigger } from "./components/QNavMenuTrigger.vue"
 export { default as QNotifyProvider } from "./components/QNotifyProvider.vue"
 export { default as QNotifyToast } from "./components/QNotifyToast.vue"
+export { default as QNumericKeyboard } from "./components/QNumericKeyboard.vue"
 export { default as QPage } from "./components/QPage.vue"
+export { default as QPageContainer } from "./components/QPageContainer.vue"
 export { default as QPagination } from "./components/QPagination.vue"
 export { default as QParallax } from "./components/QParallax.vue"
+export { default as QPopupProxy } from "./components/QPopupProxy.vue"
 export { default as QPullToRefresh } from "./components/QPullToRefresh.vue"
+export { default as QQrcode } from "./components/QQrcode.vue"
 export { default as QRadio } from "./components/QRadio.vue"
 export { default as QRating } from "./components/QRating.vue"
 export { default as QReorder } from "./components/QReorder.vue"
@@ -132,7 +140,9 @@ export { default as QTable } from "./components/QTable.vue"
 export { default as QTabs } from "./components/QTabs.vue"
 export { default as QText } from "./components/QText.vue"
 export { default as QTextCaption } from "./components/QTextCaption.vue"
-export { default as QTiptap } from "./components/QTiptap.vue"
+export { default as QTime } from "./components/QTime.vue"
+export { default as QTimeline } from "./components/QTimeline.vue"
+export { default as QTimelineEntry } from "./components/QTimelineEntry.vue"
 export { default as QToolbar } from "./components/QToolbar.vue"
 export { default as QTooltip } from "./components/QTooltip.vue"
 export { default as QUploader } from "./components/QUploader.vue"

package/lib/bottomSheet.test.ts

@@ -0,0 +1,121 @@
+// Tests unitaires des points d'ancrage (`breakpoints`) du bottom sheet.
+import { describe, expect, it } from "bun:test"
+import {
+  clampRatio,
+  nearestBreakpoint,
+  normalizeBreakpoints,
+  ratioFromDrag,
+  releaseBreakpoint,
+  stepBreakpoint,
+} from "./bottomSheet"
+
+describe("normalizeBreakpoints", () => {
+  it("trie et dédoublonne les fractions de ]0, 1]", () => {
+    expect(normalizeBreakpoints([0.5, 0.25, 0.75, 0.25])).toEqual([0.25, 0.5, 0.75])
+    expect(normalizeBreakpoints([1, 0.5])).toEqual([0.5, 1])
+  })
+
+  it("écarte 0 (état « fermé »), les hors-bornes et le non numérique", () => {
+    expect(normalizeBreakpoints([0, 0.25, 1.5, -0.5])).toEqual([0.25])
+    expect(normalizeBreakpoints([Number.NaN, Number.POSITIVE_INFINITY])).toEqual([])
+    expect(normalizeBreakpoints(["0.25", "0.5"])).toEqual([0.25, 0.5])
+  })
+
+  it("accepte une chaîne (usage en attribut)", () => {
+    expect(normalizeBreakpoints("0.25, 0.5")).toEqual([0.25, 0.5])
+    expect(normalizeBreakpoints("[0.25, 0.5, 0.75]")).toEqual([0.25, 0.5, 0.75])
+    expect(normalizeBreakpoints("")).toEqual([])
+  })
+
+  it("rend une liste vide pour une valeur absente ou illisible", () => {
+    expect(normalizeBreakpoints()).toEqual([])
+    expect(normalizeBreakpoints(null)).toEqual([])
+    expect(normalizeBreakpoints(0.5)).toEqual([])
+    expect(normalizeBreakpoints({})).toEqual([])
+  })
+})
+
+describe("nearestBreakpoint", () => {
+  const anchors = [0.25, 0.5, 0.75]
+
+  it("choisit le point d'ancrage le plus proche (le plus bas à égalité)", () => {
+    expect(nearestBreakpoint(0.3, anchors)).toBe(0.25)
+    expect(nearestBreakpoint(0.4, anchors)).toBe(0.5)
+    expect(nearestBreakpoint(0.375, anchors)).toBe(0.25)
+    expect(nearestBreakpoint(0.9, anchors)).toBe(0.75)
+  })
+
+  it("borne la valeur quand la liste est vide", () => {
+    expect(nearestBreakpoint(1.4, [])).toBe(1)
+    expect(nearestBreakpoint(-2, [])).toBe(0)
+  })
+})
+
+describe("stepBreakpoint", () => {
+  const anchors = [0.25, 0.5, 0.75]
+
+  it("monte et descend d'un cran depuis le point d'ancrage courant", () => {
+    expect(stepBreakpoint(0.25, anchors, 1)).toBe(0.5)
+    expect(stepBreakpoint(0.5, anchors, 1)).toBe(0.75)
+    expect(stepBreakpoint(0.75, anchors, -1)).toBe(0.5)
+  })
+
+  it("reste sur place aux extrémités", () => {
+    expect(stepBreakpoint(0.75, anchors, 1)).toBe(0.75)
+    expect(stepBreakpoint(0.25, anchors, -1)).toBe(0.25)
+  })
+
+  it("accepte une liste non triée et une valeur intermédiaire", () => {
+    expect(stepBreakpoint(0.6, [0.25, 0.75, 0.5], 1)).toBe(0.75)
+  })
+})
+
+describe("clampRatio / ratioFromDrag", () => {
+  it("borne une fraction et protège le non numérique", () => {
+    expect(clampRatio(1.4)).toBe(1)
+    expect(clampRatio(-0.2)).toBe(0)
+    expect(clampRatio(Number.NaN)).toBe(0)
+    expect(clampRatio(0.4, 0.25, 0.75)).toBe(0.4)
+  })
+
+  it("convertit un drag vertical en fraction (vers le haut = agrandir)", () => {
+    // 100 px vers le haut dans une vue de 800 px → +0.125
+    expect(ratioFromDrag(0.5, -100, 800)).toBeCloseTo(0.625, 5)
+    expect(ratioFromDrag(0.5, 200, 800)).toBeCloseTo(0.25, 5)
+    expect(ratioFromDrag(0.5, 9999, 800)).toBe(0)
+  })
+
+  it("rend la fraction de départ si la hauteur de vue est inutilisable", () => {
+    expect(ratioFromDrag(0.5, 100, 0)).toBe(0.5)
+    expect(ratioFromDrag(0.5, Number.NaN, 800)).toBe(0.5)
+  })
+})
+
+describe("releaseBreakpoint", () => {
+  const anchors = [0.25, 0.5, 0.75]
+
+  it("se pose sur le point d'ancrage le plus proche", () => {
+    expect(releaseBreakpoint(0.28, anchors)).toEqual({ close: false, breakpoint: 0.25 })
+    expect(releaseBreakpoint(0.7, anchors)).toEqual({ close: false, breakpoint: 0.75 })
+    expect(releaseBreakpoint(1, anchors)).toEqual({ close: false, breakpoint: 0.75 })
+  })
+
+  it("ferme le panneau relâché à 0 ou sous le plus bas point d'ancrage", () => {
+    expect(releaseBreakpoint(0, anchors)).toEqual({ close: true })
+    expect(releaseBreakpoint(-0.1, anchors)).toEqual({ close: true })
+    // 0.05 est à plus de 0.15 sous 0.25 → fermeture
+    expect(releaseBreakpoint(0.05, anchors)).toEqual({ close: true })
+    // 0.15 reste dans la tolérance → on remonte sur 0.25
+    expect(releaseBreakpoint(0.15, anchors)).toEqual({ close: false, breakpoint: 0.25 })
+  })
+
+  it("respecte un seuil de fermeture explicite", () => {
+    expect(releaseBreakpoint(0.2, anchors, 0)).toEqual({ close: true })
+    expect(releaseBreakpoint(0.2, anchors, 0.5)).toEqual({ close: false, breakpoint: 0.25 })
+  })
+
+  it("ferme toujours sans point d'ancrage exploitable", () => {
+    expect(releaseBreakpoint(0.5, [])).toEqual({ close: true })
+    expect(releaseBreakpoint(Number.NaN, anchors)).toEqual({ close: true })
+  })
+})

package/lib/bottomSheet.ts

@@ -0,0 +1,115 @@
+// bottomSheet — points d'ancrage (`breakpoints`) d'un bottom sheet : les hauteurs
+// relatives où le panneau peut se poser, et les calculs de drag / snap associés.
+// Pur (aucun DOM) → testable hors navigateur, comme `lib/layout.ts`.
+//
+// Convention : un point d'ancrage est une **fraction de la hauteur de vue** (0 → 1),
+// comme chez Ionic (`:breakpoints="[0.25, 0.5, 0.75]"`). `0` est accepté dans la liste
+// mais retiré à la normalisation : il signifie « fermé », un état porté par `v-model`.
+
+const toNumber = (value: unknown): number | undefined => {
+  if (typeof value === "number") return Number.isFinite(value) ? value : undefined
+  if (typeof value !== "string" || value.trim() === "") return undefined
+  const n = Number(value)
+  return Number.isFinite(n) ? n : undefined
+}
+
+/**
+ * Points d'ancrage exploitables : nombres finis de ]0, 1], dédoublonnés et **croissants**.
+ * Accepte aussi une chaîne (`"0.25,0.5"` ou `"[0.25, 0.5]"`) pour l'usage en attribut.
+ */
+export function normalizeBreakpoints(breakpoints?: unknown): number[] {
+  let raw: unknown = breakpoints
+
+  if (typeof raw === "string") {
+    raw = raw
+      .replace(/[[\]()]/g, "")
+      .split(/[,;\s]+/)
+      .filter(Boolean)
+  }
+
+  if (!Array.isArray(raw)) return []
+
+  const values = raw
+    .map((value) => toNumber(value))
+    .filter((value): value is number => value !== undefined && value > 0 && value <= 1)
+
+  return [...new Set(values)].sort((a, b) => a - b)
+}
+
+/** Fraction bornée à [min, max] (défaut `0 → 1`) — valeur illisible → `min`. */
+export function clampRatio(value: number, min = 0, max = 1): number {
+  if (!Number.isFinite(value)) return min
+  return Math.min(max, Math.max(min, value))
+}
+
+/**
+ * Point d'ancrage le plus proche de `value` — à égalité, le plus bas.
+ * `breakpoints` vide → la valeur bornée à [0, 1].
+ */
+export function nearestBreakpoint(value: number, breakpoints: readonly number[]): number {
+  if (breakpoints.length === 0) return clampRatio(value)
+
+  let best = breakpoints[0]!
+  for (const candidate of breakpoints) {
+    if (Math.abs(candidate - value) < Math.abs(best - value)) best = candidate
+  }
+  return best
+}
+
+/**
+ * Point d'ancrage voisin dans une direction (`1` = plus haut, `-1` = plus bas), borné :
+ * aux extrémités, la valeur courante est rendue telle quelle. Sert au cycle clavier
+ * (touche Entrée sur la poignée) et à l'API exposée.
+ */
+export function stepBreakpoint(
+  value: number,
+  breakpoints: readonly number[],
+  direction: 1 | -1,
+): number {
+  if (breakpoints.length === 0) return clampRatio(value)
+
+  const ordered = [...breakpoints].sort((a, b) => a - b)
+  const current = nearestBreakpoint(value, ordered)
+  const index = ordered.indexOf(current)
+  const next = index + direction
+  if (next < 0 || next >= ordered.length) return current
+  return ordered[next]!
+}
+
+/** Fraction atteinte après un drag vertical : un geste vers le haut (`dy < 0`) agrandit. */
+export function ratioFromDrag(startRatio: number, dy: number, viewportHeight: number): number {
+  if (!Number.isFinite(dy) || !Number.isFinite(viewportHeight) || viewportHeight <= 0) {
+    return clampRatio(startRatio)
+  }
+  return clampRatio(startRatio - dy / viewportHeight)
+}
+
+/** Décision prise au relâchement du drag : se poser sur un point d'ancrage, ou fermer. */
+export interface BreakpointRelease {
+  /** Le panneau doit se fermer */
+  close: boolean
+  /** Point d'ancrage retenu (absent quand `close`) */
+  breakpoint?: number
+}
+
+/**
+ * Où se poser au relâchement : sous le plus bas point d'ancrage de plus de
+ * `closeThreshold` (fraction), ou à 0 → **fermeture** ; sinon le point d'ancrage le plus
+ * proche. Garde la règle historique du composant — un drag vers le bas ferme le panneau,
+ * même quand `0` n'est pas dans la liste (Ionic, lui, ne ferme plus dans ce cas).
+ */
+export function releaseBreakpoint(
+  ratio: number,
+  breakpoints: readonly number[],
+  closeThreshold = 0.15,
+): BreakpointRelease {
+  if (!Number.isFinite(ratio) || ratio <= 0) return { close: true }
+
+  const ordered = [...breakpoints].sort((a, b) => a - b)
+  if (ordered.length === 0) return { close: true }
+
+  const lowest = ordered[0]!
+  if (ratio < lowest - Math.max(0, closeThreshold)) return { close: true }
+
+  return { breakpoint: nearestBreakpoint(ratio, ordered), close: false }
+}