@dnax/ui 0.0.54 → 0.0.56

package/components/QAutocomplete.vue

@@ -9,6 +9,7 @@ import { cn } from "../lib/utils"
 import { radiusStyle, useRadius } from "../lib/useComponentProps"
 import type { RadiusProp } from "../lib/useComponentProps"
 import { useOverlayBack } from "../lib/overlayBack"
+import { optionsOf } from "../lib/select"
 
 interface Props {
   /** Valeur sélectionnée */
@@ -230,18 +231,23 @@ const getLabel = (opt: any): string => {
   return v === undefined || v === null ? "" : String(v)
 }
 
+// `options` peut arriver `false` (v-if/&&, config non chargée) : sans cette coercition,
+// `.find` / `.filter` / `.some` jetteraient et le popup cesserait de se rendre
+// (même classe de bug que `q-select multiple` — cf. `.memory/knowledges.md`).
+const optionList = computed<any[]>(() => optionsOf(props.options))
+
 const selectedLabel = computed(() => {
   if (props.modelValue === undefined || props.modelValue === null) return ""
-  const opt = props.options.find((o) => getValue(o) === props.modelValue)
+  const opt = optionList.value.find((o) => getValue(o) === props.modelValue)
   return opt ? getLabel(opt) : String(props.modelValue)
 })
 
 // — Filtre client (sauté en mode serveur @filter) —
 const filtered = computed(() => {
-  if (hasFilter.value) return props.options
+  if (hasFilter.value) return optionList.value
   const q = query.value.trim().toLowerCase()
-  if (!q) return props.options
-  return props.options.filter((o) => getLabel(o).toLowerCase().includes(q))
+  if (!q) return optionList.value
+  return optionList.value.filter((o) => getLabel(o).toLowerCase().includes(q))
 })
 
 // — Affichage du champ —
@@ -323,7 +329,7 @@ const commit = () => {
   const q = query.value.trim()
   if (!q) return
   const label = q.toLowerCase()
-  const matches = props.options.some((o) => getLabel(o).toLowerCase() === label)
+  const matches = optionList.value.some((o) => getLabel(o).toLowerCase() === label)
   if (!matches) {
     query.value = ""
     emit("update:inputValue", "")

package/components/QSpreadsheet.vue

@@ -8,6 +8,24 @@
 // Suivi des modifications : `v-model:dirty` (état) + `v-model:changes` (delta lignes / feuilles
 // ajoutées, modifiées, supprimées), calculé en comparant le document à une **référence**
 // (`lib/spreadsheetChanges.ts`).
+import type {
+  QSpreadsheetCellOption,
+  QSpreadsheetOptionAccessor,
+} from "../lib/spreadsheetOptions"
+import type {
+  QSpreadsheetValidation,
+  QSpreadsheetValidationRule,
+} from "../lib/spreadsheetValidation"
+
+export type {
+  QSpreadsheetCellOption,
+  QSpreadsheetOptionAccessor,
+} from "../lib/spreadsheetOptions"
+export type {
+  QSpreadsheetValidation,
+  QSpreadsheetValidationRule,
+} from "../lib/spreadsheetValidation"
+
 export type QSpreadsheetCellType =
   | "string"
   | "text"
@@ -21,18 +39,9 @@ export type QSpreadsheetCellType =
   | "select"
   | "multiselect"
 
-export interface QSpreadsheetCellOption {
-  /** Valeur stockée dans la cellule */
-  value: any
-  /**
-   * Libellé affiché. Les nombres sont acceptés (`{ value: 1, label: 1 }` pour une
-   * note, un niveau…) : le composant les normalise en string partout où il fait des
-   * opérations de chaîne (recherche, filtre, tri, éditeur).
-   */
-  label: string | number
-  /** Couleur du badge (token ou hex, ex. "positive", "#22c55e") */
-  color?: string
-}
+// `QSpreadsheetCellOption` (option **normalisée**) et `QSpreadsheetOptionAccessor` vivent dans
+// `lib/spreadsheetOptions.ts` — source unique, testée hors navigateur — et sont ré-exportés en
+// tête de ce bloc.
 
 export interface QSpreadsheetColumn {
   /** Clé de la propriété dans la ligne */
@@ -48,12 +57,27 @@ export interface QSpreadsheetColumn {
   type?: QSpreadsheetCellType
   /** La cellule est éditable (Entrée / double-clic / frappe) */
   editable?: boolean
-  /** Pour type "select" / "multiselect" : options (badges colorés) */
-  options?: QSpreadsheetCellOption[]
+  /**
+   * Pour type `select` / `multiselect` : les options. Forme par défaut
+   * `{ value, label, color? }` — ou **n'importe quelle forme d'objet** (ex. `[{ _id, name }]`
+   * renvoyé par une API) dès que `optionLabel` / `optionValue` sont fournis.
+   */
+  options?: any[]
+  /**
+   * Pour type `select` / `multiselect` : clé (ou fonction) du **libellé** dans une option —
+   * défaut `"label"`. Ex. `option-label="name"`. Vocabulaire de `<q-select>`.
+   */
+  optionLabel?: QSpreadsheetOptionAccessor
+  /**
+   * Pour type `select` / `multiselect` : clé (ou fonction) de la **valeur stockée** dans la
+   * cellule — défaut `"value"`. Doit être **primitive** (string / number / bool) et unique.
+   * Ex. `option-value="_id"`.
+   */
+  optionValue?: QSpreadsheetOptionAccessor
   /** Pour type "select" / "multiselect" : rend les options actives en badge coloré (sinon texte) */
   chip?: boolean
-  /** Validation à la saisie : { min, max, integer?, pattern?, message? } */
-  validation?: QSpreadsheetValidation
+  /** Validation à la saisie : objet `{ min, max, … }` ou expression ArkType (`"number < 4"`) */
+  validation?: QSpreadsheetValidationRule
   /** Formatteur de la valeur affichée */
   format?: (val: any, row: Record<string, any>) => any
   /** Classe CSS de la cellule (défaut : ) */
@@ -64,24 +88,9 @@ export interface QSpreadsheetColumn {
   headerStyle?: string
 }
 
-export interface QSpreadsheetValidation {
-  /** Valeur minimale (types numériques / entiers) */
-  min?: number
-  /** Valeur maximale (types numériques / entiers) */
-  max?: number
-  /** Exige un entier (si présent, valide les entiers) */
-  integer?: boolean
-  /** Expression régulière validée contre le texte */
-  pattern?: string
-  /** Champ obligatoire (vide refusé) */
-  required?: boolean
-  /** Valeurs autorisées (liste) */
-  list?: any[]
-  /** Message d'erreur affiché (sinon message générique) */
-  message?: string
-  /** Schéma ArkType (string) — ex. "number.integer & >= 0 & <= 100" (optionnel) */
-  schema?: string
-}
+// `QSpreadsheetValidation` et `QSpreadsheetValidationRule` vivent dans
+// `lib/spreadsheetValidation.ts` (source unique, testée hors navigateur) et sont
+// ré-exportées en tête de ce bloc.
 
 /** Validation par plage de cellules (rows/cols 0-based) */
 export interface QSpreadsheetRangeValidator {
@@ -89,7 +98,7 @@ export interface QSpreadsheetRangeValidator {
   c0: number
   r1: number
   c1: number
-  validation: QSpreadsheetValidation
+  validation: QSpreadsheetValidationRule
 }
 
 export interface QSpreadsheetSelection {
@@ -161,6 +170,8 @@ import {
   deriveCols,
   parseCsv,
 } from "../lib/spreadsheet"
+import { checkValidation, type ArkCheck } from "../lib/spreadsheetValidation"
+import { normalizeCellOptions } from "../lib/spreadsheetOptions"
 import {
   DEFAULT_ROW_KEY,
   diffDocuments,
@@ -517,6 +528,38 @@ const colNameAt = (i: number) => cols.value[i]?.name ?? ""
 const colOf = (name: string) => cols.value.find((c) => c.name === name)
 
 // ─── Cellules à choix (select = une valeur, multiselect = un tableau de valeurs) ───
+/**
+ * Options d'une colonne, **normalisées une seule fois** vers `{ value, label, color? }` —
+ * `optionLabel` / `optionValue` y sont appliqués (défauts `"label"` / `"value"`). C'est ce qui
+ * garantit que badge, info-bulle, éditeur, tri, filtre et copie/CSV lisent tous la même forme :
+ * un accesseur oublié quelque part donnerait un badge `_id` et un tooltip « Ada ».
+ * Mémoïsé par nom de colonne (le cache vit dans l'instance du composant).
+ */
+const optionsCache = new Map<
+  string,
+  { opts: QSpreadsheetCellOption[]; options: unknown; label: unknown; value: unknown }
+>()
+const cellOptionsOf = (col: QSpreadsheetColumn | undefined): QSpreadsheetCellOption[] => {
+  if (!col) return []
+  const hit = optionsCache.get(col.name)
+  if (
+    hit &&
+    hit.options === col.options &&
+    hit.label === col.optionLabel &&
+    hit.value === col.optionValue
+  ) {
+    return hit.opts
+  }
+  const opts = normalizeCellOptions(col.options, col.optionLabel, col.optionValue)
+  optionsCache.set(col.name, {
+    opts,
+    options: col.options,
+    label: col.optionLabel,
+    value: col.optionValue,
+  })
+  return opts
+}
+
 /**
  * Valeurs d'une cellule à choix multiples, toujours sous forme de liste : un tableau est
  * repris tel quel, une valeur nue (`null`, `"it"`…) devient `[valeur]` (ou `[]` si vide).
@@ -530,7 +573,7 @@ const multiValues = (raw: any): any[] => {
 /** Libellés d'une cellule à choix multiples (le `value` brut si l'option est inconnue) */
 const multiLabels = (col: QSpreadsheetColumn | undefined, raw: any): string[] =>
   multiValues(raw).map((v) => {
-    const opt = col?.options?.find((o) => o.value === v)
+    const opt = cellOptionsOf(col).find((o) => o.value === v)
     return String(opt?.label ?? v)
   })
 
@@ -542,7 +585,7 @@ const choiceText = (col: QSpreadsheetColumn | undefined, raw: any): string => {
   if (col?.type === "multiselect") return multiLabels(col, raw).join(", ")
   if (isBlankValue(raw)) return ""
   if (col?.type === "select") {
-    const opt = col.options?.find((o) => o.value === raw)
+    const opt = cellOptionsOf(col).find((o) => o.value === raw)
     if (opt?.label !== undefined) return String(opt.label)
   }
   return String(raw)
@@ -842,7 +885,7 @@ const startEdit = (row: number, column: string, initial?: string) => {
   if (col?.editable === false || col?.type === "boolean") return
   const raw = state.value[row]?.[column]
   if (col?.type === "select") {
-    const opt = col.options?.find((o) => o.value === raw)
+    const opt = cellOptionsOf(col).find((o) => o.value === raw)
     // `label` peut être un nombre (options numériques) : `draft` alimente un
     // <input>/<textarea> et sert à `.trim()` / `.toLowerCase()` → toujours une string.
     draft.value = String(initial ?? opt?.label ?? "")
@@ -929,7 +972,9 @@ const coerceValue = (col: QSpreadsheetColumn | undefined, text: unknown, old: an
     return raw === "true" ? true : raw === "false" ? false : old
   }
   if (col?.type === "select") {
-    const opt = col.options?.find((o) => String(o.label ?? "") === raw || String(o.value) === raw)
+    const opt = cellOptionsOf(col).find(
+      (o) => String(o.label ?? "") === raw || String(o.value) === raw,
+    )
     return opt ? opt.value : old
   }
   // `multiselect` : collage / saisie « a, b » → tableau de valeurs d'option
@@ -940,7 +985,7 @@ const coerceValue = (col: QSpreadsheetColumn | undefined, text: unknown, old: an
       .filter((s) => s !== "")
     if (!parts.length) return null
     return parts.map((part) => {
-      const opt = col.options?.find(
+      const opt = cellOptionsOf(col).find(
         (o) => String(o.label ?? "") === part || String(o.value) === part,
       )
       return opt ? opt.value : part
@@ -1641,7 +1686,7 @@ const selectOptions = computed<QSpreadsheetCellOption[]>(() => {
   const col = colOf(editing.value.column)
   if (col?.type !== "select" && col?.type !== "multiselect") return []
   const q = String(draft.value ?? "").trim().toLowerCase()
-  return (col.options ?? []).filter(
+  return cellOptionsOf(col).filter(
     (o) => !q || String(o.label ?? o.value ?? "").toLowerCase().includes(q),
   )
 })
@@ -1676,7 +1721,7 @@ const toggleMultiOption = (opt: QSpreadsheetCellOption) => {
   const next = multiSelected(opt)
     ? current.filter((v) => v !== opt.value)
     : [...current, opt.value]
-  validateAndSet(row, column, old, next)
+  void validateAndSet(row, column, old, next)
 }
 
 // ─── Barre de formule (fx) ───
@@ -2499,7 +2544,7 @@ const badgeStyle = (opt: QSpreadsheetCellOption) => {
 
 const badgeOf = (col: QSpreadsheetColumn | undefined, val: any) => {
   if (col?.type !== "select" || !col.chip) return undefined
-  const opt = col.options?.find((o) => o.value === val)
+  const opt = cellOptionsOf(col).find((o) => o.value === val)
   if (!opt) return undefined
   return { label: opt.label, style: badgeStyle(opt) }
 }
@@ -2508,7 +2553,7 @@ const badgeOf = (col: QSpreadsheetColumn | undefined, val: any) => {
 const multiBadges = (col: QSpreadsheetColumn | undefined, val: any) => {
   if (col?.type !== "multiselect" || !col.chip) return []
   return multiValues(val).map((v) => {
-    const opt = col.options?.find((o) => o.value === v)
+    const opt = cellOptionsOf(col).find((o) => o.value === v)
     return {
       label: String(opt?.label ?? v),
       style: badgeStyle(opt ?? { value: v, label: String(v) }),
@@ -3854,60 +3899,50 @@ const condStyleOf = (r: number, c: number, name: string) => {
   return Object.keys(st).length ? st : undefined
 }
 
-// ════════ Validation de colonne (min / max / entier / pattern) ════════
+// ════════ Validation de colonne (min / max / entier / pattern / ArkType) ════════
 const valErrors = ref<Record<string, string>>({})
 const valKey = (r: number, name: string) => r + ":" + name
+
+// ArkType : import **dynamique** (jamais dans le graphe du barrel) mémoïsé au niveau
+// module — une seule promesse pour toute la session, et non une par édition de cellule.
+let arkModule: Promise<any | null> | null = null
+const loadArk = (): Promise<any | null> => {
+  arkModule ??= import("arktype")
+    .then((m) => m as any)
+    .catch(() => null)
+  return arkModule
+}
+
+/**
+ * Vérifie une expression ArkType. Une expression **invalide** (faute de syntaxe) ne doit
+ * JAMAIS jeter : l'exception remonterait en rejet non géré et la cellule ne serait ni
+ * validée ni commitée, sans aucun message (cf. `.memory/knowledges.md`).
+ */
+const arkCheck: ArkCheck = async (schema, value) => {
+  const m = await loadArk()
+  if (!m) return "ArkType unavailable"
+  try {
+    const problems = m.type(schema)(value)
+    const p = Array.isArray(problems) ? problems[0] : undefined
+    return p?.message ?? null
+  } catch (e) {
+    return `Invalid ArkType schema: ${(e as Error)?.message ?? String(e)}`
+  }
+}
+
+/** Validation d'une cellule : règles de la colonne, puis celles des plages qui la couvrent. */
 const guardValidation = async (
   row: number,
   col: QSpreadsheetColumn | undefined,
   value: any,
 ): Promise<string | null> => {
-  let ark: Promise<{ type: (s: string) => (v: unknown) => { message?: string }[] } | null> | null = null
-  const arkCheck = async (schema: string): Promise<string | null> => {
-    if (!ark)
-      ark = import("arktype")
-        .then((m) => m as any)
-        .catch(() => null)
-    const m = await ark
-    if (!m) return "ArkType unavailable"
-    const problems = m.type(schema)(value)
-    const p = Array.isArray(problems) ? problems[0] : undefined
-    return p?.message ?? null
-  }
-  const check = async (v: QSpreadsheetValidation | undefined): Promise<string | null> => {
-    if (!v) return null
-    const multi = Array.isArray(value)
-    const blank =
-      value === null || value === undefined || value === "" || (multi && value.length === 0)
-    if (v.required && blank) return v.message ?? "Required"
-    if (blank) return null // champ vide autorisé (sauf required)
-    if (v.list) {
-      // Choix multiples : chacune des valeurs doit être dans la liste
-      const values = multi ? value : [value]
-      if (values.some((x) => !v.list!.some((y) => String(y) === String(x))))
-        return v.message ?? "Not in the allowed list"
-    }
-    if (v.integer && typeof value === "number" && !Number.isInteger(value))
-      return v.message ?? "Integer required"
-    if (typeof value === "number") {
-      if (v.min !== undefined && value < v.min) return v.message ?? "Value below minimum (" + v.min + ")"
-      if (v.max !== undefined && value > v.max) return v.message ?? "Value above maximum (" + v.max + ")"
-    }
-    if (v.pattern && typeof value === "string" && !new RegExp(v.pattern).test(value))
-      return v.message ?? "Value does not match the required format"
-    if (v.schema) {
-      const e = await arkCheck(v.schema)
-      if (e) return v.message ?? e
-    }
-    return null
-  }
-  const colErr = await check(col?.validation)
+  const colErr = await checkValidation(col?.validation, value, arkCheck)
   if (colErr) return colErr
   if (props.validators?.length && col) {
     const ci = colIndex(col.name)
     for (const rv of props.validators) {
       if (row >= rv.r0 && row <= rv.r1 && ci >= rv.c0 && ci <= rv.c1) {
-        const e = await check(rv.validation)
+        const e = await checkValidation(rv.validation, value, arkCheck)
         if (e) return e
       }
     }

package/lib/select.ts

@@ -1,10 +1,11 @@
-// Coercitions défensives de QSelect (`lib/select.ts`).
+// Coercitions défensives des composants de sélection (QSelect, QAutocomplete) (`lib/select.ts`).
 //
 // Un `v-model` ou des `options` mal formés ne doivent **jamais** casser le rendu : un
 // `list.map is not a function` dans un `computed` du template tue tout le popup, sans
 // message utile. Cas réel : `<q-select multiple v-model="x">` avec `x` initialisé à
 // `false` (défaut d'un `ref` booléen, retour d'un `&&`, config non chargée) — le garde
-// `=== null`/`=== undefined` ne l'attrape pas, puis `false.map(...)` jette.
+// `=== null`/`=== undefined` ne l'attrape pas, puis `false.map(...)` jette. Idem
+// `:options` arrivant `false` (`props.options.map` / `.filter` / `.find`).
 //
 // Pur (aucun DOM) → testable hors navigateur, comme `lib/pagePadding.ts`.
 

package/lib/spreadsheetOptions.test.ts

@@ -0,0 +1,84 @@
+// Tests unitaires de la normalisation des options de colonne (`lib/spreadsheetOptions.ts`).
+// Cas visé : des données d'API `[{ _id, name }]` (ou `{ _id, name, value }`) utilisées
+// directement via `optionLabel` / `optionValue`, sans mapping manuel.
+import { describe, expect, it } from "bun:test"
+import { normalizeCellOptions } from "./spreadsheetOptions"
+
+const users = [
+  { _id: "u_8f3a", name: "Ada Lovelace", value: "ADA" },
+  { _id: "u_1b2c", name: "Alan Turing", value: "ALAN" },
+]
+
+describe("normalizeCellOptions — sans accesseurs (forme historique)", () => {
+  it("laisse passer `{ value, label, color? }`", () => {
+    const opts = [{ value: "tea", label: "Tea", color: "#ede9fe" }]
+    expect(normalizeCellOptions(opts)).toEqual([{ value: "tea", label: "Tea", color: "#ede9fe" }])
+  })
+
+  it("accepte un label numérique et l'absence de couleur", () => {
+    expect(normalizeCellOptions([{ value: 1, label: 1 }])).toEqual([{ value: 1, label: 1 }])
+  })
+
+  it("normalise une option primitive", () => {
+    expect(normalizeCellOptions(["a", 3])).toEqual([
+      { value: "a", label: "a" },
+      { value: 3, label: "3" },
+    ])
+  })
+
+  it("replie le label sur la valeur string si `label` manque", () => {
+    expect(normalizeCellOptions([{ value: "it" }])).toEqual([{ value: "it", label: "it" }])
+  })
+
+  it("tolère une entrée qui n'est pas un tableau", () => {
+    expect(normalizeCellOptions(false)).toEqual([])
+    expect(normalizeCellOptions(undefined)).toEqual([])
+  })
+})
+
+describe("normalizeCellOptions — `optionLabel` / `optionValue`", () => {
+  it("mappe `[{ _id, name }]` par nom de clé", () => {
+    expect(normalizeCellOptions(users, "name", "_id")).toEqual([
+      { value: "u_8f3a", label: "Ada Lovelace" },
+      { value: "u_1b2c", label: "Alan Turing" },
+    ])
+  })
+
+  it("mappe par fonction, comme `option-label` de QSelect", () => {
+    expect(normalizeCellOptions(users, (u) => u.name, (u) => u._id)).toEqual([
+      { value: "u_8f3a", label: "Ada Lovelace" },
+      { value: "u_1b2c", label: "Alan Turing" },
+    ])
+  })
+
+  it("permet de stocker le code métier (`value`) plutôt que l'`_id`", () => {
+    expect(normalizeCellOptions(users, "name", "value")[0]).toEqual({
+      value: "ADA",
+      label: "Ada Lovelace",
+    })
+  })
+
+  it("transmet `color` tel quel (décoré côté app)", () => {
+    const decorated = users.map((u) => ({ ...u, color: u.value === "ADA" ? "#ede9fe" : "#dcfce7" }))
+    const opts = normalizeCellOptions(decorated, "name", "_id")
+    expect(opts[0]).toEqual({ value: "u_8f3a", label: "Ada Lovelace", color: "#ede9fe" })
+    expect(opts[1]!.color).toBe("#dcfce7")
+  })
+
+  it("replie le label sur la valeur si la clé de label est absente de l'objet", () => {
+    expect(normalizeCellOptions([{ _id: "x" }], "name", "_id")).toEqual([{ value: "x", label: "x" }])
+  })
+
+  it("ne mute pas les objets source", () => {
+    const source = [{ _id: "u_1", name: "Ada" }]
+    normalizeCellOptions(source, "name", "_id")
+    expect(source).toEqual([{ _id: "u_1", name: "Ada" }])
+  })
+
+  it("produit une nouvelle liste à chaque appel (le cache est géré par le composant)", () => {
+    const a = normalizeCellOptions(users, "name", "_id")
+    const b = normalizeCellOptions(users, "name", "_id")
+    expect(a).not.toBe(b)
+    expect(a).toEqual(b)
+  })
+})

package/lib/spreadsheetOptions.ts

@@ -0,0 +1,70 @@
+// Options de cellule de QSpreadsheet (`<q-spreadsheet>`, colonnes `select` / `multiselect`).
+//
+// Une colonne reçoit `options` — par défaut sous la forme `{ value, label, color? }`. Avec
+// `optionLabel` / `optionValue`, **n'importe quelle forme d'objet** est acceptée (ex. le
+// `[{ _id, name }]` renvoyé par une API) : on la **normalise une seule fois** vers la forme
+// interne. C'est le point clé — badge, info-bulle, éditeur, tri, filtre et copie/CSV lisent
+// tous la même forme, donc aucun risque d'incohérence entre deux sites.
+//
+// Pur (aucun DOM) → testable hors navigateur, comme `spreadsheetValidation.ts`.
+
+import { optionsOf } from "./select"
+
+/** Option interne normalisée : la **seule** forme lue par le composant. */
+export interface QSpreadsheetCellOption {
+  /**
+   * Valeur stockée dans la cellule. Doit être **primitive** (string / number / boolean),
+   * unique dans la liste : le composant compare les valeurs par `===` et le document est
+   * sérialisé par `toJSON()`.
+   */
+  value: any
+  /**
+   * Libellé affiché. Les nombres sont acceptés (`{ value: 1, label: 1 }` pour une note, un
+   * niveau…) : le composant les normalise en string partout où il fait des opérations de
+   * chaîne (recherche, filtre, tri, éditeur).
+   */
+  label: string | number
+  /** Couleur du badge (token ou hex, ex. "positive", "#22c55e") */
+  color?: string
+}
+
+/**
+ * Accès à un champ d'une option : nom de clé (`"name"`, `"_id"`) **ou** fonction
+ * (`(o) => o.name`), comme l'`option-label` / `option-value` de `<q-select>`.
+ */
+export type QSpreadsheetOptionAccessor = string | ((opt: any) => any)
+
+const read = (opt: any, accessor: QSpreadsheetOptionAccessor | undefined): any =>
+  typeof accessor === "function" ? accessor(opt) : accessor === undefined ? undefined : opt?.[accessor]
+
+/**
+ * Normalise les options d'une colonne vers `{ value, label, color? }`.
+ *
+ * - `optionLabel` / `optionValue` : clé ou fonction — défauts `"label"` / `"value"` (donc une
+ *   colonne déjà écrite sous la forme `{ value, label }` n'est pas modifiée) ;
+ * - une option **primitive** (`"a"`, `3`) devient `{ value, label: String(value) }` ;
+ * - `label` absent → repli sur `String(value)` ;
+ * - `color` est **transmis tel quel** (la couleur est une décision de présentation) ;
+ * - `options` qui n'est pas un tableau → `[]` (jamais d'exception).
+ */
+export function normalizeCellOptions(
+  options: unknown,
+  optionLabel?: QSpreadsheetOptionAccessor,
+  optionValue?: QSpreadsheetOptionAccessor,
+): QSpreadsheetCellOption[] {
+  return optionsOf(options).map((opt): QSpreadsheetCellOption => {
+    if (opt === null || typeof opt !== "object") {
+      return { value: opt, label: String(opt ?? "") }
+    }
+
+    const value = read(opt, optionValue ?? "value")
+    const label = read(opt, optionLabel ?? "label")
+
+    const out: QSpreadsheetCellOption = {
+      value,
+      label: label === undefined || label === null ? String(value ?? "") : label,
+    }
+    if (opt.color !== undefined) out.color = opt.color
+    return out
+  })
+}

package/lib/spreadsheetValidation.test.ts

@@ -0,0 +1,106 @@
+// Tests unitaires de la validation de colonne de QSpreadsheet (`lib/spreadsheetValidation.ts`).
+// L'accès à ArkType est **injecté** : on teste l'ordonnancement des règles sans bundler
+// ni navigateur, et on vérifie qu'une expression est bien transmise telle quelle.
+import { describe, expect, it } from "bun:test"
+import { checkValidation, normalizeValidation, type ArkCheck } from "./spreadsheetValidation"
+
+/** Faux ArkType : échoue pour toute valeur >= 4 (comme une règle `"number < 4"`). */
+const fakeArk: ArkCheck = async (schema, value) =>
+  schema === "number < 4" && typeof value === "number" && value >= 4 ? "must be < 4" : null
+
+const noArk: ArkCheck = async () => {
+  throw new Error("arkCheck ne devait pas être appelé")
+}
+
+describe("normalizeValidation", () => {
+  it("une chaîne devient un schéma ArkType", () => {
+    expect(normalizeValidation("number < 4")).toEqual({ schema: "number < 4" })
+  })
+
+  it("un objet est laissé tel quel", () => {
+    const rule = { min: 0, max: 10 }
+    expect(normalizeValidation(rule)).toBe(rule)
+  })
+
+  it("undefined → undefined", () => {
+    expect(normalizeValidation(undefined)).toBeUndefined()
+  })
+})
+
+describe("checkValidation — expression directe (« number < 4 »)", () => {
+  it("transmet l'expression à ArkType et remonte son message", async () => {
+    expect(await checkValidation("number < 4", 3, fakeArk)).toBeNull()
+    expect(await checkValidation("number < 4", 4, fakeArk)).toBe("must be < 4")
+  })
+
+  it("`message` surcharge le message d'ArkType", async () => {
+    const rule = { schema: "number < 4", message: "Trop grand" }
+    expect(await checkValidation(rule, 9, fakeArk)).toBe("Trop grand")
+  })
+
+  it("une valeur vide passe (comme la forme objet)", async () => {
+    expect(await checkValidation("number < 4", null, noArk)).toBeNull()
+    expect(await checkValidation("number < 4", "", noArk)).toBeNull()
+  })
+
+  it("`required` refuse le vide **avant** d'appeler ArkType", async () => {
+    expect(await checkValidation({ required: true, schema: "number < 4" }, null, noArk)).toBe(
+      "Required",
+    )
+  })
+})
+
+describe("checkValidation — règle objet", () => {
+  it("sans règle → null", async () => {
+    expect(await checkValidation(undefined, 42, noArk)).toBeNull()
+  })
+
+  it("required + message", async () => {
+    expect(await checkValidation({ required: true }, "", noArk)).toBe("Required")
+    expect(await checkValidation({ required: true, message: "Obligatoire" }, [], noArk)).toBe(
+      "Obligatoire",
+    )
+  })
+
+  it("list : une valeur (mode simple)", async () => {
+    const rule = { list: ["a", "b"] }
+    expect(await checkValidation(rule, "a", noArk)).toBeNull()
+    expect(await checkValidation(rule, "z", noArk)).toBe("Not in the allowed list")
+  })
+
+  it("list : chaque valeur (multiselect)", async () => {
+    const rule = { list: [1, 2, 3] }
+    expect(await checkValidation(rule, [1, 3], noArk)).toBeNull()
+    expect(await checkValidation(rule, [1, 9], noArk)).toBe("Not in the allowed list")
+  })
+
+  it("list : compare en texte (1 ≡ « 1 »)", async () => {
+    expect(await checkValidation({ list: ["1", "2"] }, 1, noArk)).toBeNull()
+  })
+
+  it("integer / min / max", async () => {
+    expect(await checkValidation({ integer: true }, 2.5, noArk)).toBe("Integer required")
+    expect(await checkValidation({ min: 0 }, -1, noArk)).toBe("Value below minimum (0)")
+    expect(await checkValidation({ max: 100 }, 150, noArk)).toBe("Value above maximum (100)")
+    expect(await checkValidation({ min: 0, max: 100 }, 42, noArk)).toBeNull()
+  })
+
+  it("min/max ne s'appliquent qu'aux nombres", async () => {
+    expect(await checkValidation({ min: 0 }, "abc", noArk)).toBeNull()
+  })
+
+  it("pattern (texte seulement)", async () => {
+    const rule = { pattern: "^\\d{4}$" }
+    expect(await checkValidation(rule, "2026", noArk)).toBeNull()
+    expect(await checkValidation(rule, "26", noArk)).toBe(
+      "Value does not match the required format",
+    )
+    expect(await checkValidation(rule, 2026 as any, noArk)).toBeNull() // non-string : ignoré
+  })
+
+  it("le schéma est évalué en dernier (min échoue avant)", async () => {
+    const rule = { min: 0, schema: "number < 4" }
+    expect(await checkValidation(rule, -1, fakeArk)).toBe("Value below minimum (0)")
+    expect(await checkValidation(rule, 9, fakeArk)).toBe("must be < 4")
+  })
+})

package/lib/spreadsheetValidation.ts

@@ -0,0 +1,102 @@
+// Validation de colonne de QSpreadsheet (`<q-spreadsheet>`).
+//
+// Vit dans `lib/` — et non dans le SFC — pour être **testable sans navigateur** : c'est
+// exactement le code du composant, seul l'accès à ArkType est **injecté** (`ArkCheck`).
+//
+// Deux écritures possibles pour une colonne (ou une plage) :
+//
+//   { name: "score",    validation: { min: 0, max: 100, integer: true } }   // objet
+//   { name: "priority", validation: "number < 4" }                         // expression ArkType
+//
+// Une **chaîne** est une expression ArkType : c'est le raccourci de `{ schema: "…" }`.
+// Les deux formes se combinent (`{ required: true, schema: "number < 4" }`) et `message`
+// surcharge le message de la règle qui échoue.
+
+/** Règles de validation d'une colonne (ou d'une plage de cellules). */
+export interface QSpreadsheetValidation {
+  /** Valeur minimale (types numériques / entiers) */
+  min?: number
+  /** Valeur maximale (types numériques / entiers) */
+  max?: number
+  /** Exige un entier (si présent, valide les entiers) */
+  integer?: boolean
+  /** Expression régulière validée contre le texte */
+  pattern?: string
+  /** Champ obligatoire (vide refusé) */
+  required?: boolean
+  /** Valeurs autorisées (liste) */
+  list?: any[]
+  /** Message d'erreur affiché (sinon message générique) */
+  message?: string
+  /**
+   * Expression **ArkType** — ex. `"number < 4"`,
+   * `"number.integer & number >= 0 & number <= 100"`, `"string.email"`.
+   * Équivalent d'une règle écrite directement en chaîne.
+   */
+  schema?: string
+}
+
+/**
+ * Règle de validation : objet `{ min, max, … }` **ou** expression ArkType écrite
+ * directement (`validation: "number < 4"`).
+ */
+export type QSpreadsheetValidationRule = QSpreadsheetValidation | string
+
+/**
+ * Vérification d'un schéma ArkType, **injectée** par le composant (import dynamique +
+ * mémoïsation + `try/catch`) : renvoie un message d'erreur, ou `null` si la valeur passe.
+ */
+export type ArkCheck = (schema: string, value: unknown) => Promise<string | null>
+
+/** Normalise une règle : une chaîne devient un schéma ArkType (`{ schema }`). */
+export const normalizeValidation = (
+  rule: QSpreadsheetValidationRule | undefined,
+): QSpreadsheetValidation | undefined => (typeof rule === "string" ? { schema: rule } : rule)
+
+/**
+ * Valide une valeur contre une règle. Renvoie le message d'erreur, ou `null`.
+ *
+ * Ordre : `required` → vide toléré → `list` → `integer` → `min` / `max` → `pattern` →
+ * `schema` (ArkType). Une valeur **vide** passe toutes les règles sauf `required`.
+ * En `multiselect` (valeur = tableau), `list` s'applique **à chaque valeur** et un tableau
+ * vide compte comme vide, donc `required` le refuse.
+ */
+export async function checkValidation(
+  rule: QSpreadsheetValidationRule | undefined,
+  value: any,
+  arkCheck: ArkCheck,
+): Promise<string | null> {
+  const v = normalizeValidation(rule)
+  if (!v) return null
+
+  const multi = Array.isArray(value)
+  const blank =
+    value === null || value === undefined || value === "" || (multi && value.length === 0)
+  if (v.required && blank) return v.message ?? "Required"
+  if (blank) return null // champ vide autorisé (sauf required)
+
+  if (v.list) {
+    // Choix multiples : chacune des valeurs doit être dans la liste
+    const values = multi ? value : [value]
+    if (values.some((x) => !v.list!.some((y) => String(y) === String(x))))
+      return v.message ?? "Not in the allowed list"
+  }
+
+  if (v.integer && typeof value === "number" && !Number.isInteger(value))
+    return v.message ?? "Integer required"
+
+  if (typeof value === "number") {
+    if (v.min !== undefined && value < v.min) return v.message ?? `Value below minimum (${v.min})`
+    if (v.max !== undefined && value > v.max) return v.message ?? `Value above maximum (${v.max})`
+  }
+
+  if (v.pattern && typeof value === "string" && !new RegExp(v.pattern).test(value))
+    return v.message ?? "Value does not match the required format"
+
+  if (v.schema) {
+    const e = await arkCheck(v.schema, value)
+    if (e) return v.message ?? e
+  }
+
+  return null
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dnax/ui",
-  "version": "0.0.54",
+  "version": "0.0.56",
   "module": "index.ts",
   "description": "UI design System",
   "type": "module",