Ripensare l'inserimento dei dati di un'intera app

Le tabelle rendono il prodotto ordinato. Ma poi bisogna riempirle.

Valueize è una piattaforma di financial modeling: personale, ricavi, COGS, opex, capitale circolante, struttura finanziaria. Ognuno di questi moduli è una o più tabelle a griglia — righe di voci, colonne di periodi — che l'utente deve compilare per costruire il modello. Un modello copre in genere 3-4 anni per volta, e ogni anno si può dettagliare mese per mese: le celle da riempire si moltiplicano in fretta.

Il punto è che quei numeri quasi sempre esistono già: sono in un foglio Excel, in un Google Sheet condiviso, in un CSV esportato dal gestionale. Un import da file c'era, ma dava per scontato un foglio pulito e completo — e i piani reali sono fatti a mano, parziali e tutti diversi tra loro. Così, nella pratica, restava l'input manuale: leggere un valore dal proprio foglio e ridigitarlo nella griglia, cella per cella, per ogni tabella. Il lavoro non era 'modellare': era ricopiare.

Input manuale cella per cella, con i dati già pronti dall'altra parte dello schermo.

Il flusso era tecnicamente corretto e praticamente lentissimo. Ogni cella era un input validato, ma la validazione proteggeva il dato singolo, non il tempo dell'utente né la varietà dei fogli da cui i dati arrivavano.

Copi la riga da Excel. La incolli. Fatto.

Un import da file c'era già, ma dava per scontato un foglio pulito e completo. L'utente tipico invece arriva con un piano fatto a mano: parziale, disordinato, diverso da ogni altro — un import perfetto spesso non era nemmeno possibile. Excel, Google Sheets e i CSV però mettono tutti nella clipboard lo stesso formato: righe separate da a-capo, celle separate da tab. Basta un parser per quel formato condiviso, non uno per ogni strumento, e la riga si incolla così com'è, senza riordinare niente prima. Diventa un gesto, non una procedura.

Astrazione, non duplicazione: due contratti generici.

Sotto ci sono due cose, tenute apposta separate. Un parser puro che non sa niente delle tabelle: prende del testo dalla clipboard e restituisce numeri validati. E un provider generico che non sa niente dei numeri: prende una lista di dati e una chiave, e sa incollare, validare, mutare e annullare. Si incastrano con una config minima — ed è per questo che la stessa feature è finita in 31 tabelle diverse senza una riga di codice dedicata.

export function parseExcelData(
  pastedData: string,
  options: ClipboardParseOptions
): ClipboardParseResult {
  const rows = pastedData.split(/\r\n|\r|\n/) // Windows, Mac, Unix
  if (rows.length > 0 && rows[rows.length - 1] === ``) rows.pop()

  const cells = (rows[0] ?? ``).split(`\t`) // Excel/Sheets/CSV → tab-separated
  const parsedData: ClipboardParsedItem[] = []

  cells.forEach((cell, index) => {
    const trimmed = cell.trim()
    const { success, value, error } =
      typeof options.validate === `function`
        ? options.validate(trimmed)
        : VALIDATE_FNS[options.validate](trimmed) // validatore scelto dalla tabella
    parsedData.push({ id: index, originalValue: trimmed, validatedValue: value, error })
  })

  return { clipboardContent: pastedData, data: parsedData, /* ...errors */ }
}

const VALIDATE_FNS = {
  numeric: (input: string) => run(z.string().transform(parseInputValue)
    .refine((v) => !Number.isNaN(Number(v)), `invalid_numeric`), input),

  percentage: (input: string) => run(z.string().transform(parseInputValue)
    .refine((v) => !Number.isNaN(Number(v)), `invalid_numeric`)
    .refine((v) => Number(v) >= 0 && Number(v) <= 100, `invalid_percentage`), input),

  positiveNumeric: (input: string) => run(z.string().transform(parseInputValue)
    .refine((v) => !Number.isNaN(Number(v)), `invalid_numeric`)
    .refine((v) => Number(v) >= 0, `invalid_positive`), input),
}
// la tabella sceglie con una stringa: dataValidationType="percentage"

const cleanInput = (value: string) => {
  const parsed = value
    .replace(currencySymbolsPattern, ``) // €, $, £, ...
    .replace(/[a-zA-Z]/g, ``)
    .replace(/[%]/, ``)
    .replace(/[" "]/g, ``)
    .trim()

  // notazione contabile: (342) → -342
  const hasParentheses = parsed.startsWith(`(`) && parsed.endsWith(`)`)
  return hasParentheses ? `-${parsed.slice(1, -1)}` : parsed
}

const processDecimalPart = (value: string) => {
  let processedValue = value
  if (value.includes(`,`)) {
    const parts = value.split(`,`)
    // 2 cifre dopo la virgola → è un decimale (1234,56 → 1234.56)
    if (parts[1]?.length <= 2) processedValue = value.replace(`,`, `.`)
    // altrimenti è un separatore delle migliaia (1,234 → 1234)
    else processedValue = value.replace(/,/g, ``)
  }
  // più punti: l'ultimo è il decimale, gli altri sono migliaia
  const split = processedValue.split(`.`)
  if (split.length > 1) {
    const decimalPart = split.pop()
    return `${split.join(``)}.${decimalPart}`
  }
  return processedValue
}

// "1.234,56" e "1,234.56" convivono: l'ultimo separatore è il decimale
const handleMixedSeparators = (value: string) => {
  const parts = value.split(/[,.]/)
  if (parts.length >= 2) {
    const decimalPart = parts.pop()
    return `${parts.join(``)}.${decimalPart}`
  }
  return parts.join(``)
}

export const parseInputValue = (value: string) => {
  const parsed = cleanInput(value)
  if (INVALID_NUMERIC_INPUTS.includes(parsed)) return ``      // ".", ",", "..." → scartati
  if (parsed.includes(`,`) && parsed.includes(`.`)) return handleMixedSeparators(parsed)
  return processDecimalPart(parsed)
}

export const TableActionableRowProvider = <DataItem extends object>({
  children,
  currentData,
  mutateDataKey,                       // percorso al campo, es. "value" o "config.rate"
  rowUpdateMutationArgs: { mutationItemFn },
  dataValidationType = `numeric`,      // quale validatore Zod usa il parser
}: {
  currentData: DataItem[]
  mutateDataKey: NestedKeyOf<DataItem>  // solo percorsi validi per DataItem
  dataValidationType?: ClipboardParseValidationType
  rowUpdateMutationArgs: {
    mutationItemFn: (item: DataItem & { itemIndex: number }, extra: {
      rowType: StandardInputType
    }) => Promise<unknown>
  }
}) => { /* ... */ }

// "id" | "config" | "config.rate" | "config.view" ... — niente stringhe a caso
type NestedKeyOf<T> = {
  [K in keyof T & (string | number)]: T[K] extends object
    ? `${K}` | `${K}.${NestedKeyOf<T[K]>}`
    : `${K}`
}[keyof T & (string | number)]

function getPatchedObjectByNestedProps<T extends object, V>(obj: T, path: string, value: V): T {
  const result = { ...obj }
  const keys = path.split(`.`)
  let current = result as Record<string, any>
  for (let i = 0; i < keys.length - 1; i++) {
    current[keys[i]] = { ...current[keys[i]] } // copia il livello annidato
    current = current[keys[i]]
  }
  current[keys[keys.length - 1]] = value
  return result
}

const PASTE_ACTION_TYPES = {
  PASTE_ALL: `PASTE_ALL`,                     // incolla tutto
  PASTE_PRESERVE_EMPTY: `PASTE_PRESERVE_EMPTY`, // vuoto → tieni il valore attuale
  PASTE_SKIP_EMPTY: `PASTE_SKIP_EMPTY`,        // vuoto → salta la cella
} as const

const typePrepareFn = {
  [PASTE_ACTION_TYPES.PASTE_ALL]: (cps) => cps.data,
  [PASTE_ACTION_TYPES.PASTE_PRESERVE_EMPTY]: (cps) => cps.data,
  [PASTE_ACTION_TYPES.PASTE_SKIP_EMPTY]: (cps) =>
    cps.data.filter((item) => item.validatedValue !== ``),
}

// incolli più celle di quante ne restano nella riga dal punto di partenza?
if (clipboardParseResult.data.length > currentData.length - triggerCellIndex) {
  errorCode = PENDING_PASTE_ERROR.LIMIT_OVERFLOW // → dialog "Paste within limit?"
}

// allSettled invece di Promise.all: una cella che fallisce non abbatte le altre
const promises = args.upsertData.map((item, index) =>
  mutationItemFn(item, { rowType })
    .then(() => ({ item, index, success: true }))
    .catch(() => ({ item, index, success: false }))
)

const batchSize = 10
const batched = []
for (let i = 0; i < promises.length; i += batchSize) {
  batched.push(Promise.all(promises.slice(i, i + batchSize)))
}
const results = (await Promise.all(batched)).flat()
// ogni risultato aggiorna il feedback della sua cella (verde/rosso)

const restoreDataCells = fullRowDataBeforePaste.filter(
  (_, i) =>
    i >= contextMenuTriggerCellIndex &&
    i < contextMenuTriggerCellIndex + pastedData.length
)
// rimette lo stato precedente solo su quelle celle: nessuna chiamata
// per il resto della riga, che non è mai stato toccato

Multilingua e multivaluta, verificato su ogni combinazione.

Un parser di numeri finanziari sbaglia in silenzio: 1,234 è milleduecentotrentaquattro per un americano e uno-virgola-due-tre-quattro per un italiano, e leggere male una cifra vuol dire corrompere un bilancio senza che nessuno se ne accorga. Per questo il parser non è coperto da qualche test scelto a mano, ma da una suite che lo fa girare su tutte le lingue supportate incrociate con tutte le valute ammesse, più i casi limite che rompono i parser ingenui: separatori misti, parentesi contabili, simboli attaccati al numero, input spazzatura.

it(`Should return number without currency`, () => {
  ALLOWED_CURRENCIES.forEach((currency) => {
    numbers.forEach((number) => {
      const formatted = formatNumber(number.input, { currency, style: `currency` })
      // qualunque valuta la scriva, il parser deve ricavarne il numero pulito
      expect(parseInputValue(formatted)).toBe(Number(number.expected).toFixed(number.precision))
    })
  })
})

it(`Should return formatted number for all supported locales`, () => {
  SUPPORTED_LOCALES.forEach((locale) => {
    numbers.forEach((number) => {
      const formatted = formatNumber(number.input, { language: locale })
      expect(parseInputValue(formatted)).toBe(Number(number.expected).toFixed(number.precision))
    })
  })
})

expect(parseInputValue(`1,234.56`)).toBe(`1234.56`)   // migliaia US + decimale
expect(parseInputValue(`1234,56`)).toBe(`1234.56`)    // decimale IT
expect(parseInputValue(`1.234,567.89`)).toBe(`1234567.89`) // separatori misti
expect(parseInputValue(`(342,56)`)).toBe(`-342.56`)   // parentesi = negativo
expect(parseInputValue(`$1234.56`)).toBe(`1234.56`)   // simbolo attaccato
expect(parseInputValue(`1 234.56`)).toBe(`1234.56`)   // spazio come separatore

// input che NON è un numero non deve diventare 0 di nascosto
INVALID_NUMERIC_INPUTS.forEach((input) => expect(parseInputValue(input)).toBe(``))

Cosa poteva andare storto (e come l'abbiamo evitato).

La virgola che corrompe un bilancio. L'ambiguità tra separatore delle migliaia e decimale non è un dettaglio estetico: interpretare 1,234 come 1234 invece di 1,234 significa gonfiare un numero di mille volte, in silenzio, dentro un modello finanziario. La difesa non è indovinare la lingua dell'utente, ma una regola deterministica — due cifre dopo il separatore sono decimali, tre o più sono migliaia — e una suite di test che la verifica su ogni lingua e ogni valuta prima che una modifica al parser arrivi in produzione.

Il paste parallelo che restituiva la cella sbagliata. La prima versione mandava tutte le mutation in un unico Promise.all. Al refetch, sulle selezioni grandi, la prima cella spesso non mostrava il valore incollato — anche se la richiesta POST era corretta. Il commento nel codice lo documenta ancora. La soluzione è stata passare a allSettled a gruppi di dieci: gli errori restano isolati alla loro cella e non si perdono aggiornamenti, tenendo reattiva anche una griglia grande.

Cosa è cambiato davvero.