@dnax/ui 0.0.56 → 0.0.58

package/components/QSpreadsheet.vue

@@ -8,6 +8,7 @@
 // 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,
@@ -17,6 +18,13 @@ import type {
   QSpreadsheetValidationRule,
 } from "../lib/spreadsheetValidation"
 
+export type {
+  QSpreadsheetFill,
+  QSpreadsheetFillContext,
+  QSpreadsheetFillFormula,
+  QSpreadsheetLock,
+  QSpreadsheetLockPoint,
+} from "../lib/spreadsheetZones"
 export type {
   QSpreadsheetCellOption,
   QSpreadsheetOptionAccessor,
@@ -84,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
 }
@@ -92,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
@@ -172,6 +192,7 @@ import {
 } 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,
@@ -207,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) */
@@ -791,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]
@@ -806,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",
   )
 }
 
@@ -880,9 +961,8 @@ 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 = cellOptionsOf(col).find((o) => o.value === raw)
@@ -1018,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)
 }
@@ -1040,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 })
@@ -1185,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" })
@@ -1363,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)
@@ -1458,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)
     }
@@ -1477,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)
     }
@@ -1596,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)
     }
@@ -1714,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)
@@ -1739,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"
@@ -2495,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)
@@ -2688,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)
@@ -3421,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
@@ -3437,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
@@ -3575,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)
@@ -3636,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)
@@ -4151,6 +4267,7 @@ defineExpose({
   commitEdit,
   cancelEdit,
   addRow,
+  applyPrefill,
   insertRowAt,
   removeSelectedRows,
   addColumn,
@@ -4641,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/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.56",
+  "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;
 }