@dnax/ui 0.0.55 → 0.0.56

package/components/QSpreadsheet.vue

@@ -8,11 +8,19 @@
 // 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,
@@ -31,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 */
@@ -58,8 +57,23 @@ 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 : objet `{ min, max, … }` ou expression ArkType (`"number < 4"`) */
@@ -157,6 +171,7 @@ import {
   parseCsv,
 } from "../lib/spreadsheet"
 import { checkValidation, type ArkCheck } from "../lib/spreadsheetValidation"
+import { normalizeCellOptions } from "../lib/spreadsheetOptions"
 import {
   DEFAULT_ROW_KEY,
   diffDocuments,
@@ -513,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).
@@ -526,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)
   })
 
@@ -538,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)
@@ -838,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 ?? "")
@@ -925,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
@@ -936,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
@@ -1637,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),
   )
 })
@@ -2495,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) }
 }
@@ -2504,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) }),

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/package.json

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