@dnax/ui 0.0.55 → 0.0.58

package/components/QSpreadsheet.vue

@@ -8,11 +8,27 @@
 // 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 { QSpreadsheetFill, QSpreadsheetLock } from "../lib/spreadsheetZones"
+import type {
+  QSpreadsheetCellOption,
+  QSpreadsheetOptionAccessor,
+} from "../lib/spreadsheetOptions"
 import type {
   QSpreadsheetValidation,
   QSpreadsheetValidationRule,
 } from "../lib/spreadsheetValidation"
 
+export type {
+  QSpreadsheetFill,
+  QSpreadsheetFillContext,
+  QSpreadsheetFillFormula,
+  QSpreadsheetLock,
+  QSpreadsheetLockPoint,
+} from "../lib/spreadsheetZones"
+export type {
+  QSpreadsheetCellOption,
+  QSpreadsheetOptionAccessor,
+} from "../lib/spreadsheetOptions"
 export type {
   QSpreadsheetValidation,
   QSpreadsheetValidationRule,
@@ -31,18 +47,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 +65,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"`) */
@@ -70,6 +92,14 @@ export interface QSpreadsheetColumn {
   cellClass?: (val: any, row: Record<string, any>) => string | undefined
   /** Couleur de fond de la cellule (plan) */
   cellBackground?: (val: any, row: Record<string, any>) => string | undefined
+  /**
+   * Cellule **non modifiable** : édition, effacement, bascule booléenne, collage, remplissage et
+   * barre de formule sont refusés pour les lignes où le prédicat est vrai. Reçoit la valeur
+   * courante, la ligne et son **index** — donc verrouille aussi une cellule **vide**
+   * (`(v) => v !== null`, `(_, row) => row.locked`, `(_, __, i) => i === 0`…).
+   * Pour désigner un bloc par ses coordonnées, préférer `lockedRanges`.
+   */
+  cellReadonly?: (val: any, row: Record<string, any>, rowIndex: number) => boolean
   headerClass?: string
   headerStyle?: string
 }
@@ -78,6 +108,10 @@ export interface QSpreadsheetColumn {
 // `lib/spreadsheetValidation.ts` (source unique, testée hors navigateur) et sont
 // ré-exportées en tête de ce bloc.
 
+// Les verrous (`QSpreadsheetLock`) et le préremplissage (`QSpreadsheetFill`) vivent dans
+// `lib/spreadsheetZones.ts` — forme **lisible** (noms de colonnes) traduite en rectangles
+// d'index par des fonctions pures, testées hors navigateur.
+
 /** Validation par plage de cellules (rows/cols 0-based) */
 export interface QSpreadsheetRangeValidator {
   r0: number
@@ -157,6 +191,8 @@ import {
   parseCsv,
 } from "../lib/spreadsheet"
 import { checkValidation, type ArkCheck } from "../lib/spreadsheetValidation"
+import { normalizeCellOptions } from "../lib/spreadsheetOptions"
+import { inLockRect, lockRects, prefillForRow } from "../lib/spreadsheetZones"
 import {
   DEFAULT_ROW_KEY,
   diffDocuments,
@@ -192,6 +228,42 @@ interface Props {
   lang?: "en" | "fr"
   /** Validations par plage : [{ r0,c0,r1,c1, validation }] — s'ajoutent aux colonnes */
   validators?: QSpreadsheetRangeValidator[]
+  /**
+   * Cellules **verrouillées**, écrites avec des **noms** (jamais d'index) :
+   * - `{ row: 2, column: "total" }` → la cellule « total » de la ligne 2 ;
+   * - `{ row: 0 }` → toute la ligne 0 ;
+   * - `{ column: "total" }` → toute la colonne « total » ;
+   * - `{ from: { row, column }, to: { row, column } }` → le bloc entre les deux coins.
+   *
+   * S'applique **même à une cellule vide**. S'ajoute à `columns[].cellReadonly` et aux props
+   * globales `readonly` / `disable`.
+   */
+  lockedRanges?: QSpreadsheetLock[]
+  /**
+   * **Préremplit** des zones, écrites avec des **noms** de colonnes (jamais d'index) —
+   * même vocabulaire que `lockedRanges`, plus une `value` :
+   * - `[{ column: "status", value: "todo" }]` → toute la colonne « status » ;
+   * - `[{ row: 0, value: "—" }]` → toute la ligne 0 ;
+   * - `[{ row: 2, column: "total", value: 0 }]` → la cellule (ligne 2, colonne « total ») ;
+   * - `[{ from: { row: 0, column: "total" }, to: { row: 2, column: "status" }, value: false }]`
+   *   → le bloc entre les deux coins (bornes **incluses**).
+   *
+   * `value` est une **constante** *ou* une **fonction** `(ctx) => any` (ctx : `rowIndex`,
+   * `row`, `column`, `letter`, `rowCount`, `letterOf`) — pour une valeur **dynamique**.
+   *
+   * `fx` porte une **formule**, **prioritaire sur `value`** : une chaîne (`"SUM(B1:B2)"` — le `=`
+   * initial est ajouté s'il manque) ou une fonction `(ctx) => string`. C'est la façon explicite
+   * d'écrire une formule, p. ex. la somme d'une colonne :
+   * `{ row: 3, column: "net", fx: (c) => `SUM(${c.letterOf("effectif")}1:${c.letterOf("effectif")}${c.rowCount})` }`.
+   * (Une chaîne de `value` commençant par `"="` reste stockée comme formule, mais `fx` est
+   * préféré : il documente l'intention et n'exige pas le préfixe.)
+   *
+   * Une ligne **neuve** (bouton « + », insertion) naît déjà préremplie. Les données **déjà
+   * chargées** ne sont **jamais** modifiées automatiquement : appeler `applyPrefill()`
+   * (méthode exposée) pour combler les cellules **vides** — le dernier `prefill` gagne,
+   * les noms de colonnes inconnus sont ignorés.
+   */
+  prefill?: QSpreadsheetFill[]
   /** Affiche le numéro de ligne (colonne de gauche) */
   showRowNumbers?: boolean
   /** Affiche l'en-tête de colonne (lettre + label) */
@@ -513,6 +585,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 +630,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 +642,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)
@@ -744,6 +848,27 @@ const cellTitle = (row: number, column: string): string | undefined => {
   return undefined
 }
 
+/** Verrous de `lockedRanges`, traduits en rectangles d'index (noms de colonnes résolus). */
+const lockRectsResolved = computed(() => lockRects(props.lockedRanges, colIndex))
+
+/**
+ * La cellule est-elle **verrouillée** ? Une seule porte pour toutes les mutations : props
+ * globales (`readonly` / `disable`), colonne `editable: false`, prédicat `cellReadonly(val, row)`
+ * et verrous `lockedRanges`. S'applique **même à une cellule vide** (il n'y a rien à effacer,
+ * mais on ne peut pas y écrire) — verrouiller n'est pas effacer.
+ */
+const isCellLocked = (row: number, column: string): boolean => {
+  if (props.readonly || props.disable) return true
+  const col = colOf(column)
+  if (!col) return false
+  if (col.editable === false) return true
+  const rowData = state.value[row] ?? {}
+  if (col.cellReadonly?.(rowData[column], rowData, row)) return true
+  const ci = colIndex(column)
+  if (ci === -1) return false
+  return lockRectsResolved.value.some((z) => inLockRect(z, row, ci))
+}
+
 const cellClasses = (row: number, column: string) => {
   const col = colOf(column)
   const v = state.value[row]?.[column]
@@ -759,6 +884,9 @@ const cellClasses = (row: number, column: string) => {
     isActive(row, column) && "q-spreadsheet__cell--active",
     editing.value?.row === row && editing.value?.column === column && "q-spreadsheet__cell--editing",
     props.readonly && "q-spreadsheet__cell--readonly",
+    // Verrou **ciblé** (colonne, prédicat, plage) : affordance visuelle. Le verrou global
+    // (`readonly` / `disable`) n'ajoute rien — hacher toute la grille serait illisible.
+    isCellLocked(row, column) && !props.readonly && !props.disable && "q-spreadsheet__cell--locked",
   )
 }
 
@@ -833,12 +961,11 @@ const editorInputMode = computed(() => {
 })
 
 const startEdit = (row: number, column: string, initial?: string) => {
-  if (props.readonly || props.disable) return
   const col = colOf(column)
-  if (col?.editable === false || col?.type === "boolean") return
+  if (isCellLocked(row, column) || 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 +1052,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 +1065,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
@@ -969,17 +1098,14 @@ const setCellValue = (row: number, column: string, old: any, next: any) => {
 }
 
 const clearCell = (row: number, column: string) => {
-  const col = colOf(column)
-  if (col?.editable === false || props.readonly || props.disable) return
+  if (isCellLocked(row, column)) return
   const old = state.value[row]?.[column]
   if (isBlankValue(old) || (Array.isArray(old) && old.length === 0)) return
   setCellValue(row, column, old, null)
 }
 
 const toggleBoolean = (row: number, column: string) => {
-  if (props.readonly || props.disable) return
-  const col = colOf(column)
-  if (col?.editable === false) return
+  if (isCellLocked(row, column)) return
   const old = !!state.value[row]?.[column]
   setCellValue(row, column, old, !old)
 }
@@ -991,7 +1117,7 @@ const clearSelection = () => {
   for (let r = rect.r0; r <= rect.r1; r++) {
     for (let c = rect.c0; c <= rect.c1; c++) {
       const col = cols.value[c]
-      if (!col || col.editable === false || props.readonly || props.disable) continue
+      if (!col || isCellLocked(r, col.name)) continue
       const v = state.value[r]?.[col.name]
       if (!isBlankValue(v) && !(Array.isArray(v) && v.length === 0))
         changed.push({ row: r, column: col.name })
@@ -1136,19 +1262,56 @@ const redo = () => {
 }
 
 // ─── Lignes & colonnes ───
-const blankRow = (): Record<string, any> => {
+const blankRow = (at = state.value.length): Record<string, any> => {
   // `_key` posée dès la création : la ligne est identifiable sans attendre un emit
   const row: Record<string, any> = { [ROW_KEY]: newRowKey() }
   for (const col of cols.value) row[col.name] = col.type === "boolean" ? false : ""
+  // Une ligne neuve naît préremplie par les zones `prefill` qui la visent.
+  // `rowCount` compte la ligne en cours de création (le document l'aura).
+  Object.assign(
+    row,
+    prefillForRow(props.prefill, at, cols.value.map((c) => c.name), {
+      row,
+      rowCount: state.value.length + 1,
+    }),
+  )
   return row
 }
 
+/**
+ * Comble les cellules **vides** d'après `prefill` (sans jamais écraser une valeur
+ * existante) et renvoie le nombre de cellules remplies. Utile après avoir chargé
+ * `rows` : les données déjà présentes ne sont pas touchées à l'initialisation.
+ */
+const applyPrefill = (): number => {
+  const fills = props.prefill
+  if (!fills?.length || props.disable) return 0
+  const names = cols.value.map((c) => c.name)
+  let count = 0
+  const next = state.value.map((row, r) => {
+    const patch = prefillForRow(fills, r, names, { row, rowCount: state.value.length })
+    let out = row
+    for (const [name, value] of Object.entries(patch)) {
+      if (!isBlankValue(row[name])) continue
+      if (out === row) out = { ...row }
+      out[name] = value
+      count++
+    }
+    return out
+  })
+  if (!count) return 0
+  pushHistory()
+  state.value = next
+  emit("update:rows", next)
+  return count
+}
+
 const addRow = (at?: number) => {
   if (props.readonly || props.disable) return
   pushHistory()
   const idx = at ?? state.value.length
   const next = [...state.value]
-  next.splice(idx, 0, blankRow())
+  next.splice(idx, 0, blankRow(idx))
   state.value = next
   emit("update:rows", next)
   emit("structure-change", { rows: next, columns: cols.value, reason: "add-row" })
@@ -1314,7 +1477,7 @@ const pasteClip = async () => {
       const c = startCol + j
       if (r >= state.value.length || c >= cols.value.length) return
       const col = cols.value[c]!
-      if (col.editable === false) return
+      if (isCellLocked(r, col.name)) return
       const old = state.value[r]?.[col.name]
       const next = coerceValue(col, text, old)
       if (next !== old) setCellValue(r, col.name, old, next)
@@ -1409,10 +1572,11 @@ const fillDownKey = () => {
   for (let c = rect.c0; c <= rect.c1; c++) {
     const name = colNameAt(c)
     const col = colOf(name)
-    if (!col || col.editable === false) continue
+    if (!col) continue
     const src = rect.r0 - 1
     const sv = state.value[src]?.[name]
     for (let r = rect.r0; r <= rect.r1; r++) {
+      if (isCellLocked(r, name)) continue
       const old = state.value[r]?.[name]
       if (old !== sv) setCellValue(r, name, old, sv)
     }
@@ -1428,10 +1592,11 @@ const fillRightKey = () => {
     const src = rect.c0 - 1
     const sname = colNameAt(src)
     const col = colOf(sname)
-    if (!col || col.editable === false) continue
+    if (!col) continue
     const sv = state.value[r]?.[sname]
     for (let c = rect.c0; c <= rect.c1; c++) {
       const name = colNameAt(c)
+      if (isCellLocked(r, name)) continue
       const old = state.value[r]?.[name]
       if (old !== sv) setCellValue(r, name, old, sv)
     }
@@ -1547,7 +1712,7 @@ const onKeydown = (e: KeyboardEvent) => {
   // Frappe directe : remplace le contenu (comportement Excel)
   if (e.key.length === 1 && !mod && !e.altKey) {
     const col = colOf(sel.value.column)
-    if (col && col.editable !== false && col.type !== "boolean") {
+    if (col && col.type !== "boolean" && !isCellLocked(sel.value.row, sel.value.column)) {
       e.preventDefault()
       startEdit(sel.value.row, sel.value.column, e.key)
     }
@@ -1637,7 +1802,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),
   )
 })
@@ -1665,8 +1830,7 @@ const multiSelected = (opt: QSpreadsheetCellOption) =>
 const toggleMultiOption = (opt: QSpreadsheetCellOption) => {
   if (!editing.value) return
   const { row, column } = editing.value
-  const col = colOf(column)
-  if (col?.editable === false || props.readonly || props.disable) return
+  if (isCellLocked(row, column)) return
   const old = state.value[row]?.[column]
   const current = multiValues(old)
   const next = multiSelected(opt)
@@ -1690,11 +1854,12 @@ const syncFx = () => {
 watch([sel, state], syncFx)
 
 const fxCanEdit = computed(() => {
-  if (props.readonly || props.disable || !sel.value) return false
-  const col = colOf(sel.value.column)
+  if (!sel.value) return false
+  const { row, column } = sel.value
+  if (isCellLocked(row, column)) return false
+  const col = colOf(column)
   return (
     !!col &&
-    col.editable !== false &&
     col.type !== "boolean" &&
     col.type !== "select" &&
     col.type !== "multiselect"
@@ -2446,7 +2611,7 @@ const insertRowAt = (pos: "above" | "below") => {
       : state.value.length
   const idx = Math.max(0, Math.min(state.value.length, at))
   const next = [...state.value]
-  next.splice(idx, 0, blankRow())
+  next.splice(idx, 0, blankRow(idx))
   state.value = next
   shiftRowKeys(idx, 1)
   emit("update:rows", next)
@@ -2495,7 +2660,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 +2669,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) }),
@@ -2639,7 +2804,7 @@ const applyFill = () => {
       if (rr < 0 || rr >= state.value.length || cc < 0 || cc >= cols.value.length) continue
       const name = colNameAt(cc)
       const col = colOf(name)
-      if (!col || col.editable === false) continue
+      if (!col || isCellLocked(rr, name)) continue
 
       let val: any
       // Série numérique / dates (2 graines) vers le bas ou la droite (Ctrl = copie)
@@ -3372,8 +3537,7 @@ const findMarkClass = (r: number, ci: number) =>
   )
 const findReplaceCurrent = () => {
   const m = findMatches.value[findIdx.value]
-  if (!m || props.readonly || props.disable) return
-  const col = cols.value[m.ci]
+  if (!m || isCellLocked(m.r, m.name)) return
   const raw = state.value[m.r]?.[m.name]
   if (typeof raw !== "string" || !findQuery.value) return
   const next = findCase.value
@@ -3388,6 +3552,7 @@ const findReplaceAll = () => {
   pushHistory()
   const changed: { r: number; name: string; old: string; next: string }[] = []
   for (const m of findMatches.value) {
+    if (isCellLocked(m.r, m.name)) continue
     const raw = state.value[m.r]?.[m.name]
     if (typeof raw !== "string") continue
     const next = findCase.value
@@ -3526,7 +3691,7 @@ const pasteValues = async () => {
       const c = c0 + j
       if (r >= state.value.length || c >= cols.value.length) continue
       const col = cols.value[c]!
-      if (col.editable === false) continue
+      if (isCellLocked(r, col.name)) continue
       const old = state.value[r]?.[col.name]
       const next = coerceLiteral(col, lines[i]![j] ?? "", old)
       if (next !== old) setCellValue(r, col.name, old, next)
@@ -3587,7 +3752,7 @@ const pasteTransposed = async () => {
       const c = c0 + i
       if (r >= state.value.length || c >= cols.value.length) continue
       const col = cols.value[c]!
-      if (col.editable === false) continue
+      if (isCellLocked(r, col.name)) continue
       const old = state.value[r]?.[col.name]
       const next = coerceValue(col, lines[i]![j] ?? "", old)
       if (next !== old) setCellValue(r, col.name, old, next)
@@ -4102,6 +4267,7 @@ defineExpose({
   commitEdit,
   cancelEdit,
   addRow,
+  applyPrefill,
   insertRowAt,
   removeSelectedRows,
   addColumn,
@@ -4592,7 +4758,7 @@ defineExpose({
                 type="button"
                 class="q-spreadsheet__checkbox"
                 :class="{ 'q-spreadsheet__checkbox--on': !!cellValue(ri, col.name) }"
-                :disabled="readonly || disable || col.editable === false"
+                :disabled="isCellLocked(ri, col.name)"
                 aria-label="Toggle"
                 @click.stop="toggleBoolean(ri, col.name)"
               >

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/spreadsheetZones.test.ts

@@ -0,0 +1,239 @@
+// Tests unitaires des **zones** de QSpreadsheet (`lib/spreadsheetZones.ts`) : la traduction de la
+// forme **lisible** (noms de colonnes) vers les rectangles d'index, et le préremplissage.
+import { describe, expect, it } from "bun:test"
+import { inLockRect, lockRect, lockRects, prefillForRow } from "./spreadsheetZones"
+
+/** Colonnes : task(0) · total(1) · status(2) */
+const cols = ["task", "total", "status"]
+const colIndex = (name: string) => cols.indexOf(name)
+
+describe("lockRect", () => {
+  it("une cellule : `{ row, column }`", () => {
+    expect(lockRect({ row: 2, column: "total" }, colIndex)).toEqual({
+      r0: 2,
+      c0: 1,
+      r1: 2,
+      c1: 1,
+    })
+  })
+
+  it("toute une ligne : `{ row }` (colonnes non bornées)", () => {
+    expect(lockRect({ row: 0 }, colIndex)).toEqual({ r0: 0, c0: null, r1: 0, c1: null })
+  })
+
+  it("toute une colonne : `{ column }` (lignes non bornées)", () => {
+    expect(lockRect({ column: "total" }, colIndex)).toEqual({
+      r0: null,
+      c0: 1,
+      r1: null,
+      c1: 1,
+    })
+  })
+
+  it("un bloc : `{ from, to }` (bornes incluses)", () => {
+    expect(
+      lockRect(
+        { from: { row: 0, column: "task" }, to: { row: 2, column: "status" } },
+        colIndex,
+      ),
+    ).toEqual({ r0: 0, c0: 0, r1: 2, c1: 2 })
+  })
+
+  it("un bloc `from`/`to` dans n'importe quel ordre", () => {
+    expect(
+      lockRect(
+        { from: { row: 3, column: "status" }, to: { row: 1, column: "task" } },
+        colIndex,
+      ),
+    ).toEqual({ r0: 1, c0: 0, r1: 3, c1: 2 })
+  })
+
+  it("ignore ce qui ne désigne rien (objet vide, colonne inconnue, from sans to)", () => {
+    expect(lockRect({}, colIndex)).toBeNull()
+    expect(lockRect({ row: 1, column: "nope" }, colIndex)).toBeNull()
+    expect(lockRect({ from: { row: 0, column: "task" } }, colIndex)).toBeNull()
+    expect(lockRect(undefined, colIndex)).toBeNull()
+  })
+})
+
+describe("lockRects", () => {
+  it("résout la liste et ignore les verrous invalides", () => {
+    expect(lockRects([{ row: 0 }, { column: "nope" }, { row: 1, column: "task" }], colIndex)).toEqual(
+      [
+        { r0: 0, c0: null, r1: 0, c1: null },
+        { r0: 1, c0: 0, r1: 1, c1: 0 },
+      ],
+    )
+  })
+
+  it("tolère une entrée non-tableau", () => {
+    expect(lockRects(undefined, colIndex)).toEqual([])
+  })
+})
+
+describe("inLockRect", () => {
+  const rect = { r0: 1, c0: 1, r1: 2, c1: 1 }
+
+  it("borne inclusivement", () => {
+    expect(inLockRect(rect, 1, 1)).toBe(true)
+    expect(inLockRect(rect, 2, 1)).toBe(true)
+    expect(inLockRect(rect, 0, 1)).toBe(false)
+    expect(inLockRect(rect, 3, 1)).toBe(false)
+    expect(inLockRect(rect, 1, 0)).toBe(false)
+    expect(inLockRect(rect, 1, 2)).toBe(false)
+  })
+
+  it("une borne `null` est non bornée", () => {
+    expect(inLockRect({ r0: null, c0: 1, r1: null, c1: 1 }, 999, 1)).toBe(true)
+    expect(inLockRect({ r0: 0, c0: null, r1: 0, c1: null }, 0, 999)).toBe(true)
+  })
+})
+
+describe("prefillForRow", () => {
+  const names = ["task", "total", "status"]
+
+  it("toute la colonne : la valeur est posée sur chaque ligne", () => {
+    const fills = [{ column: "status", value: "todo" }]
+    expect(prefillForRow(fills, 0, names)).toEqual({ status: "todo" })
+    expect(prefillForRow(fills, 7, names)).toEqual({ status: "todo" })
+  })
+
+  it("une cellule : seulement la ligne visée", () => {
+    const fills = [{ row: 2, column: "total", value: 0 }]
+    expect(prefillForRow(fills, 2, names)).toEqual({ total: 0 })
+    expect(prefillForRow(fills, 1, names)).toEqual({})
+  })
+
+  it("toute une ligne : toutes les colonnes", () => {
+    expect(prefillForRow([{ row: 1, value: "—" }], 1, names)).toEqual({
+      task: "—",
+      total: "—",
+      status: "—",
+    })
+  })
+
+  it("un bloc : les colonnes et lignes couvertes", () => {
+    const fills = [
+      { from: { row: 0, column: "total" }, to: { row: 1, column: "status" }, value: false },
+    ]
+    expect(prefillForRow(fills, 0, names)).toEqual({ total: false, status: false })
+    expect(prefillForRow(fills, 1, names)).toEqual({ total: false, status: false })
+    expect(prefillForRow(fills, 2, names)).toEqual({})
+  })
+
+  it("cumule plusieurs zones (la dernière gagne) et ignore l'inconnu", () => {
+    expect(
+      prefillForRow(
+        [
+          { column: "status", value: "todo" },
+          { row: 0, column: "status", value: "urgent" },
+          { column: "nope", value: 1 },
+        ],
+        0,
+        names,
+      ),
+    ).toEqual({ status: "urgent" })
+  })
+
+  it("tolère une entrée vide ou non-tableau", () => {
+    expect(prefillForRow(undefined, 0, names)).toEqual({})
+    expect(prefillForRow([], 0, names)).toEqual({})
+    expect(prefillForRow([{ column: "task", value: 1 }], 0, [])).toEqual({})
+  })
+})
+
+describe("prefillForRow — value fonction (valeurs dynamiques)", () => {
+  const names = ["task", "effectif", "net"]
+
+  it("appelle la fonction avec le contexte (lettre, index, taille du document)", () => {
+    const seen: any[] = []
+    const fills = [
+      {
+        row: 1,
+        column: "net",
+        value: (ctx: any) => {
+          seen.push(ctx)
+          const L = ctx.letterOf("effectif")
+          return `=SUM(${L}1:${L}${ctx.rowCount})`
+        },
+      },
+    ]
+    expect(prefillForRow(fills, 1, names, { rowCount: 4 })).toEqual({ net: "=SUM(B1:B4)" })
+    expect(seen[0]).toMatchObject({
+      rowIndex: 1,
+      column: "net",
+      columnIndex: 2,
+      letter: "C",
+      rowCount: 4,
+    })
+    expect(seen[0].letterOf("effectif")).toBe("B")
+  })
+
+  it("reçoit la ligne ciblée (agrégat calculé, pas une formule)", () => {
+    const fills = [{ row: 0, column: "net", value: (ctx: any) => Number(ctx.row.effectif) * 2 }]
+    expect(prefillForRow(fills, 0, names, { row: { effectif: 21 } })).toEqual({ net: 42 })
+  })
+
+  it("une chaîne de formule constante passe telle quelle", () => {
+    expect(prefillForRow([{ row: 0, column: "net", value: "=B1*2" }], 0, names)).toEqual({
+      net: "=B1*2",
+    })
+  })
+
+  it("une value **fonction** peut renvoyer une formule", () => {
+    const fills = [
+      {
+        row: 0,
+        column: "net",
+        value: (ctx: any) => `=SUM(${ctx.letterOf("effectif")}1:${ctx.letterOf("effectif")}${ctx.rowCount})`,
+      },
+    ]
+    expect(prefillForRow(fills, 0, names, { rowCount: 3 })).toEqual({ net: "=SUM(B1:B3)" })
+  })
+
+  it("value reste littéral (pas de normalisation du préfixe `=`)", () => {
+    expect(prefillForRow([{ row: 0, column: "net", value: "SUM(B1:B2)" }], 0, names)).toEqual({
+      net: "SUM(B1:B2)",
+    })
+  })
+})
+
+describe("prefillForRow — fx (formule prioritaire)", () => {
+  const names = ["task", "effectif", "net"]
+
+  it("fx accepte une formule sans préfixe `=` (normalisée)", () => {
+    expect(prefillForRow([{ row: 0, column: "net", fx: "SUM(B1:B2)" }], 0, names)).toEqual({
+      net: "=SUM(B1:B2)",
+    })
+    expect(prefillForRow([{ row: 0, column: "net", fx: "=B1*2" }], 0, names)).toEqual({
+      net: "=B1*2",
+    })
+  })
+
+  it("fx est prioritaire sur value", () => {
+    expect(
+      prefillForRow([{ row: 0, column: "net", value: 42, fx: "B1*2" }], 0, names),
+    ).toEqual({ net: "=B1*2" })
+  })
+
+  it("fx fonction reçoit le contexte et peut être dynamique", () => {
+    const fills = [
+      {
+        row: 0,
+        column: "net",
+        fx: (ctx: any) => {
+          const L = ctx.letterOf("effectif")
+          return `SUM(${L}1:${L}${ctx.rowCount - 1})`
+        },
+      },
+    ]
+    expect(prefillForRow(fills, 0, names, { rowCount: 3 })).toEqual({ net: "=SUM(B1:B2)" })
+  })
+
+  it("un fx vide retombe sur value ; sinon rien n'est posé", () => {
+    expect(prefillForRow([{ row: 0, column: "net", fx: "  ", value: 7 }], 0, names)).toEqual({
+      net: 7,
+    })
+    expect(prefillForRow([{ row: 0, column: "net" }], 0, names)).toEqual({})
+  })
+})

package/lib/spreadsheetZones.ts

@@ -0,0 +1,253 @@
+// **Zones** de QSpreadsheet (`<q-spreadsheet>`) désignées par des **noms** — servent à deux
+// choses : verrouiller des cellules (`lockedRanges`) et les **préremplir** (`prefill`).
+//
+// On désigne les cellules par **nom de colonne** (la clé dans `rows`), jamais par index :
+//
+//   { row: 2, column: "total" }   → la cellule « total » de la ligne 2
+//   { row: 0 }                    → toute la ligne 0
+//   { column: "total" }           → toute la colonne « total »
+//   { from: {...}, to: {...} }    → un bloc (bornes incluses, dans n'importe quel ordre)
+//
+// `lockRect()` traduit cette forme en rectangle d'**index** (une borne `null` = non bornée) ;
+// `prefillForRow()` en déduit les valeurs à poser dans une ligne neuve. Logique **pure**,
+// testable hors navigateur — comme `spreadsheetValidation.ts`.
+import { colLetter } from "./spreadsheet"
+
+/** Un coin, en clair : ligne (0-based) + **nom** de colonne. */
+export interface QSpreadsheetLockPoint {
+  /** Ligne, 0-based (0 = première ligne de données) */
+  row: number
+  /** Nom de la colonne — la clé utilisée dans `rows` (ex. `"total"`) */
+  column: string
+}
+
+/**
+ * Un verrou, écrit avec des **noms** :
+ * - `{ row: 2, column: "total" }` → une cellule ;
+ * - `{ row: 0 }` → toute la ligne 0 ;
+ * - `{ column: "total" }` → toute la colonne ;
+ * - `{ from, to }` → le bloc entre les deux coins (bornes incluses).
+ */
+export interface QSpreadsheetLock {
+  /** Ligne (0-based). Omise → **toutes** les lignes. */
+  row?: number
+  /** Nom de colonne. Omise → **toutes** les colonnes. */
+  column?: string
+  /** Premier coin d'un **bloc** (avec `to`) — prioritaire sur `row` / `column`. */
+  from?: QSpreadsheetLockPoint
+  /** Coin opposé du bloc (avec `from`). */
+  to?: QSpreadsheetLockPoint
+}
+
+/** Rectangle d'index. Une borne `null` = **non bornée** (toutes les lignes / colonnes). */
+export interface LockRect {
+  r0: number | null
+  c0: number | null
+  r1: number | null
+  c1: number | null
+}
+
+/**
+ * Traduit un verrou lisible en rectangle d'index.
+ * `null` quand il ne désigne rien : objet vide, `from`/`to` incomplets, ou nom de colonne
+ * inconnu (un verrou mal orthographié est **ignoré** plutôt que de tout verrouiller).
+ */
+export function lockRect(
+  lock: QSpreadsheetLock | undefined,
+  columnIndex: (name: string) => number,
+): LockRect | null {
+  if (!lock) return null
+
+  if (lock.from && lock.to) {
+    const a = columnIndex(lock.from.column)
+    const b = columnIndex(lock.to.column)
+    if (a === -1 || b === -1) return null
+    return {
+      r0: Math.min(lock.from.row, lock.to.row),
+      r1: Math.max(lock.from.row, lock.to.row),
+      c0: Math.min(a, b),
+      c1: Math.max(a, b),
+    }
+  }
+
+  const hasRow = typeof lock.row === "number"
+  const hasColumn = typeof lock.column === "string"
+  if (!hasRow && !hasColumn) return null
+
+  let c0: number | null = null
+  let c1: number | null = null
+  if (hasColumn) {
+    const ci = columnIndex(lock.column as string)
+    if (ci === -1) return null
+    c0 = ci
+    c1 = ci
+  }
+
+  const r = hasRow ? (lock.row as number) : null
+  return { r0: r, r1: r, c0, c1 }
+}
+
+/** Traduit une liste de verrous (les entrées non résolvables sont ignorées). */
+export function lockRects(
+  locks: QSpreadsheetLock[] | undefined,
+  columnIndex: (name: string) => number,
+): LockRect[] {
+  if (!Array.isArray(locks)) return []
+  const out: LockRect[] = []
+  for (const lock of locks) {
+    const rect = lockRect(lock, columnIndex)
+    if (rect) out.push(rect)
+  }
+  return out
+}
+
+/** La cellule `(row, col)` tombe-t-elle dans le rectangle ? (bornes `null` = non bornées) */
+export const inLockRect = (rect: LockRect, row: number, col: number): boolean =>
+  (rect.r0 === null || row >= rect.r0) &&
+  (rect.r1 === null || row <= rect.r1) &&
+  (rect.c0 === null || col >= rect.c0) &&
+  (rect.c1 === null || col <= rect.c1)
+
+// ─────────────────────────── Préremplissage ───────────────────────────
+
+/**
+ * Une **formule** de préremplissage : une chaîne (`"SUM(B1:B2)"` ou `"=SUM(B1:B2)"` — le `=`
+ * initial est ajouté s'il manque) ou une **fonction** du contexte qui renvoie cette chaîne.
+ */
+export type QSpreadsheetFillFormula = string | ((ctx: QSpreadsheetFillContext) => string)
+
+/** Zone **préremplie** : mêmes coordonnées qu'un verrou, plus une `value` **et/ou** une `fx`. */
+export interface QSpreadsheetFill extends QSpreadsheetLock {
+  /**
+   * Valeur posée dans les cellules **vides** de la zone. Une **constante** (`0`, `"todo"`, …)
+   * **ou** une **fonction** du contexte — pour une valeur **dynamique** (agrégat calculé…).
+   * Une chaîne commençant par `"="` est stockée comme **formule** et évaluée par le tableur.
+   *
+   * Si `fx` est **aussi** fourni, c'est `fx` qui gagne.
+   */
+  value?: any | ((ctx: QSpreadsheetFillContext) => any)
+  /**
+   * **Formule** de la zone, **prioritaire sur `value`** : une chaîne (`"SUM(B1:B2)"` — le `=`
+   * initial est ajouté s'il manque) ou une fonction qui la renvoie. Écrit explicitement « c'est
+   * une formule », sans se soucier du préfixe :
+   *
+   * ```ts
+   * { row: 2, column: "total", fx: ({ letterOf, rowCount }) =>
+   *     `SUM(${letterOf("effectif")}1:${letterOf("effectif")}${rowCount - 1})` }
+   * ```
+   */
+  fx?: QSpreadsheetFillFormula
+}
+
+/**
+ * Contexte remis à une `value` **fonction**, décrit la cellule remplie et le document
+ * au moment du remplissage. Permet d'écrire des formules dont la référence dépend de la
+ * position ou de la taille des données :
+ *
+ * ```ts
+ * // somme de TOUTE la colonne « effectif » (autant de lignes qu'il y en a)
+ * { row: 3, column: "net", fx: ({ letterOf, rowCount }) =>
+ *     `SUM(${letterOf("effectif")}1:${letterOf("effectif")}${rowCount})` }
+ * ```
+ */
+export interface QSpreadsheetFillContext {
+  /** Index (0-based) de la ligne remplie */
+  rowIndex: number
+  /** La ligne ciblée (référence live sur `rows`) */
+  row: Record<string, any>
+  /** Nom de la colonne remplie */
+  column: string
+  /** Index (0-based) de la colonne remplie */
+  columnIndex: number
+  /** Lettre A1 de la colonne remplie (ex. `"C"`) */
+  letter: string
+  /** Nombre de lignes du document au moment du remplissage */
+  rowCount: number
+  /** Lettre A1 d'une colonne par son **nom** (ex. `letterOf("effectif")` → `"C"`) */
+  letterOf: (column: string) => string
+}
+
+/** Contexte minimal fourni par le composant (ligne ciblée + taille du document). */
+export interface QSpreadsheetFillEnv {
+  /** La ligne ciblée (référence live sur `rows`) */
+  row?: Record<string, any>
+  /** Nombre de lignes du document au moment du remplissage */
+  rowCount?: number
+}
+
+/**
+ * Valeurs à poser dans une ligne d'index `rowIndex`, d'après les zones `prefill` :
+ * chaque zone qui couvre cette ligne fournit sa valeur pour toutes ses colonnes — une `fx`
+ * (formule, **prioritaire**) sinon une `value` ; les deux peuvent être des fonctions appelées
+ * avec le `QSpreadsheetFillContext`. Renvoie `{}` s'il n'y a rien à poser. Pur → testable sans
+ * navigateur.
+ */
+export function prefillForRow(
+  fills: QSpreadsheetFill[] | undefined,
+  rowIndex: number,
+  columnNames: string[],
+  env: QSpreadsheetFillEnv = {},
+): Record<string, any> {
+  if (!Array.isArray(fills) || !fills.length || !columnNames.length) return {}
+
+  const columnIndex = (name: string) => columnNames.indexOf(name)
+  const letterAt = (i: number) => colLetter(i)
+  const letterOf = (name: string) => letterAt(columnIndex(name))
+  const rowCount = env.rowCount ?? 0
+  const out: Record<string, any> = {}
+
+  for (const fill of fills) {
+    const rect = lockRect(fill, columnIndex)
+    if (!rect) continue
+    if (rect.r0 !== null && rowIndex < rect.r0) continue
+    if (rect.r1 !== null && rowIndex > rect.r1) continue
+
+    const from = rect.c0 ?? 0
+    const to = rect.c1 ?? columnNames.length - 1
+    for (let c = from; c <= to; c++) {
+      const name = columnNames[c]
+      if (name === undefined) continue
+
+      const ctx: QSpreadsheetFillContext = {
+        rowIndex,
+        row: env.row ?? {},
+        column: name,
+        columnIndex: c,
+        letter: letterAt(c),
+        rowCount,
+        letterOf,
+      }
+
+      // `fx` (formule) est prioritaire ; `value` ne sert que si aucune formule n'est fournie.
+      const formula = fillFormula(fill, ctx)
+      if (formula !== undefined) {
+        out[name] = formula
+        continue
+      }
+      if (fill.value !== undefined) {
+        out[name] = typeof fill.value === "function" ? fill.value(ctx) : fill.value
+      }
+      // ni `fx` ni `value` → rien à poser
+    }
+  }
+
+  return out
+}
+
+/** Formule résolue d'une zone (normalisée avec un `=` initial), ou `undefined`. */
+function fillFormula(
+  fill: QSpreadsheetFill,
+  ctx: QSpreadsheetFillContext,
+): string | undefined {
+  if (fill.fx === undefined || fill.fx === null) return undefined
+  const raw = typeof fill.fx === "function" ? fill.fx(ctx) : fill.fx
+  return normalizeFormula(raw)
+}
+
+/** `"SUM(B1:B2)"` → `"=SUM(B1:B2)"` ; `""` / non-chaîne → `undefined`. */
+function normalizeFormula(raw: unknown): string | undefined {
+  if (typeof raw !== "string") return undefined
+  const s = raw.trim()
+  if (!s) return undefined
+  return s.startsWith("=") ? s : "=" + s
+}

package/package.json

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

package/styles/main.css

@@ -9493,6 +9493,26 @@ a.q-breadcrumbs__el:hover {
 .q-spreadsheet__cell--readonly {
   cursor: default;
 }
+
+/* Cellule verrouillée (`cellReadonly` / `lockedRanges`) : pas d'édition + affordance discrète.
+   Seule la `background-image` est posée — la `background-color` (formatage conditionnel,
+   `cellBackground`) reste intacte. */
+.q-spreadsheet__cell--locked {
+  cursor: default;
+  background-image: repeating-linear-gradient(
+    135deg,
+    rgb(0 0 0 / 0.05) 0 2px,
+    transparent 2px 6px
+  );
+}
+
+.dark .q-spreadsheet__cell--locked {
+  background-image: repeating-linear-gradient(
+    135deg,
+    rgb(255 255 255 / 0.07) 0 2px,
+    transparent 2px 6px
+  );
+}
 .q-spreadsheet__cell--bool {
   text-align: center;
 }