@stackcraftmx/calcita 0.52.0 → 0.54.0

package/dist/upload/chunkedUpload.js

@@ -0,0 +1,261 @@
+import { ApiError } from "../api/ApiError.js";
+import { createLogger } from "../observability/logger.js";
+import { toolkitSettings, translateToolkit } from "../toolkit/toolkitSettings.js";
+import { parseFileSize } from "./fileRules.js";
+import { uploadWithProgress } from "./uploadWithProgress.js";
+const log = createLogger("upload");
+const CHUNK_HEADER = Object.freeze({
+  length: "Upload-Length",
+  offset: "Upload-Offset",
+  name: "Upload-Name",
+  contentType: "Content-Type"
+});
+const UPLOAD_FAILURE = Object.freeze({ rejected: "rejected", noResponse: "noResponse", noTransferId: "noTransferId" });
+const CHUNK_CONTENT_TYPE = "application/offset+octet-stream";
+const HONEST_CEILING = 0.99;
+const SERVER_ERROR_STATUS = 500;
+const OFFLINE_STATUS = 0;
+const DEFAULT_CHUNK_SIZE = 5e6;
+const DEFAULT_CHUNK_RETRY_DELAYS = Object.freeze([500, 1e3, 3e3]);
+class UploadFailure extends Error {
+  /**
+   * @param {string} reason de UPLOAD_FAILURE
+   * @param {Response|null} [response]
+   */
+  constructor(reason, response = null) {
+    super(`La subida no salió: ${reason}`);
+    this.name = "UploadFailure";
+    this.reason = reason;
+    this.response = response;
+  }
+}
+function chunkPiecesOf(fileSize, chunkSize) {
+  const count = Math.max(1, Math.ceil(fileSize / chunkSize));
+  return Array.from({ length: count }, (_, index) => {
+    const offset = index * chunkSize;
+    return { index, offset, end: Math.min(offset + chunkSize, fileSize) };
+  });
+}
+function honestLoadedOf({ confirmedBytes, sendingBytes, totalBytes }) {
+  return Math.min(confirmedBytes + sendingBytes, Math.floor(totalBytes * HONEST_CEILING));
+}
+function storedBytesOf(pieces, serverOffset) {
+  return pieces.filter((piece) => piece.end > piece.offset && piece.end <= serverOffset).reduce((last, piece) => Math.max(last, piece.end), 0);
+}
+function headerTextOf(value) {
+  return String.fromCharCode(...new TextEncoder().encode(String(value)));
+}
+function headerTextsOf(headers) {
+  return Object.fromEntries(Object.entries(headers).map(([name, value]) => [name, headerTextOf(value)]));
+}
+function waitBeforeRetry(milliseconds, signal) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(resolve, milliseconds);
+    signal.addEventListener("abort", () => {
+      clearTimeout(timer);
+      reject(new DOMException("La subida se canceló", "AbortError"));
+    }, { once: true });
+  });
+}
+async function sendWithRetries(sendOnce, retryDelays, signal) {
+  const delays = [...retryDelays ?? []];
+  for (; ; ) {
+    let response = null;
+    try {
+      response = await sendOnce();
+    } catch (failure) {
+      if (failure?.name === "AbortError") {
+        throw failure;
+      }
+    }
+    if (response?.ok) {
+      return response;
+    }
+    const canRetry = response === null || response.status >= SERVER_ERROR_STATUS;
+    if (!canRetry || delays.length === 0) {
+      throw new UploadFailure(response ? UPLOAD_FAILURE.rejected : UPLOAD_FAILURE.noResponse, response);
+    }
+    await waitBeforeRetry(delays.shift(), signal);
+  }
+}
+function defaultPatchUrlOf(url) {
+  return `${url}${url.includes("?") ? "&" : "?"}patch=`;
+}
+async function problemOfResponse(response, toProblem) {
+  let body = null;
+  try {
+    body = JSON.parse(await response.text());
+  } catch {
+  }
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    return null;
+  }
+  if (!toProblem) {
+    return body;
+  }
+  try {
+    const problem = toProblem(body, response);
+    return problem && typeof problem === "object" && !Array.isArray(problem) ? problem : null;
+  } catch (failure) {
+    log.error("toProblem tronó al leer el error de una subida", failure);
+    return null;
+  }
+}
+function startChunkedUpload(options) {
+  const controller = new AbortController();
+  const done = runChunkedUpload(options, controller.signal);
+  return { done, abort: () => controller.abort() };
+}
+async function runChunkedUpload(options, signal) {
+  const {
+    file,
+    fileName,
+    fieldName,
+    metadata = null,
+    url,
+    patchUrl,
+    headers = {},
+    withCredentials = false,
+    chunkSize,
+    retryDelays,
+    transferId = null,
+    onTransferId,
+    onProgress,
+    holdBeforeFull = true,
+    sendRequest
+  } = options;
+  const totalBytes = file.size;
+  const pieces = chunkPiecesOf(totalBytes, chunkSize);
+  const send = (requestUrl, body, method, protocolHeaders, onUploadProgress) => sendRequest(requestUrl, body, {
+    method,
+    headers: headerTextsOf({ ...headers, ...protocolHeaders }),
+    withCredentials,
+    signal,
+    onProgress: onUploadProgress
+  });
+  let shownBytes = 0;
+  let confirmedBytes = 0;
+  const showProgress = (sendingBytes) => {
+    if (signal.aborted) {
+      return;
+    }
+    const loadedBytes = holdBeforeFull ? honestLoadedOf({ confirmedBytes, sendingBytes, totalBytes }) : Math.min(confirmedBytes + sendingBytes, totalBytes);
+    shownBytes = Math.max(shownBytes, loadedBytes);
+    if (totalBytes > 0) {
+      onProgress?.(shownBytes, totalBytes);
+    }
+  };
+  let folio = transferId;
+  if (folio) {
+    const offsetResponse = await sendWithRetries(() => send(`${patchUrl}${encodeURIComponent(folio)}`, null, "HEAD", {}), retryDelays, signal);
+    const serverOffset = Number.parseInt(offsetResponse.headers.get(CHUNK_HEADER.offset) ?? "", 10);
+    confirmedBytes = storedBytesOf(pieces, Number.isNaN(serverOffset) ? 0 : serverOffset);
+  } else {
+    const firstRequest = new FormData();
+    if (metadata && typeof metadata === "object") {
+      firstRequest.append(fieldName, JSON.stringify(metadata));
+    }
+    const transferResponse = await sendWithRetries(() => send(url, firstRequest, "POST", { [CHUNK_HEADER.length]: totalBytes }), retryDelays, signal);
+    folio = (await transferResponse.text()).trim();
+    if (!folio) {
+      throw new UploadFailure(UPLOAD_FAILURE.noTransferId, transferResponse);
+    }
+    onTransferId?.(folio);
+  }
+  showProgress(0);
+  for (const piece of pieces) {
+    const isAlreadyStored = piece.end > piece.offset && piece.end <= confirmedBytes;
+    if (isAlreadyStored) {
+      continue;
+    }
+    const pieceHeaders = {
+      [CHUNK_HEADER.contentType]: CHUNK_CONTENT_TYPE,
+      [CHUNK_HEADER.offset]: piece.offset,
+      [CHUNK_HEADER.length]: totalBytes,
+      [CHUNK_HEADER.name]: fileName
+    };
+    await sendWithRetries(
+      () => send(
+        `${patchUrl}${encodeURIComponent(folio)}`,
+        file.slice(piece.offset, piece.end, CHUNK_CONTENT_TYPE),
+        "PATCH",
+        pieceHeaders,
+        (percent, transfer) => showProgress(transfer.loaded)
+      ),
+      retryDelays,
+      signal
+    );
+    confirmedBytes = piece.end;
+    showProgress(0);
+  }
+  return folio;
+}
+async function apiErrorOfFailure(failure, toProblem) {
+  if (failure?.reason === UPLOAD_FAILURE.noTransferId) {
+    const message = translateToolkit("common", "upload.pond.noTransferId");
+    return new ApiError({ status: failure.response?.status ?? OFFLINE_STATUS, problem: { title: message, detail: message } });
+  }
+  if (failure?.reason === UPLOAD_FAILURE.rejected && failure.response) {
+    return new ApiError({ status: failure.response.status, problem: await problemOfResponse(failure.response, toProblem) });
+  }
+  if (failure?.reason !== UPLOAD_FAILURE.noResponse) {
+    log.error("La subida por trozos falló sin respuesta del servidor", failure);
+  }
+  return new ApiError({ status: OFFLINE_STATUS });
+}
+function createChunkedUpload({
+  url,
+  patchUrl,
+  chunkSize = DEFAULT_CHUNK_SIZE,
+  chunkRetryDelays = DEFAULT_CHUNK_RETRY_DELAYS,
+  headers = {},
+  withCredentials = false,
+  toProblem,
+  sendRequest = uploadWithProgress,
+  fieldName = "file",
+  metadata = null
+}) {
+  const chunkBytes = parseFileSize(chunkSize);
+  const piecesUrl = patchUrl ?? defaultPatchUrlOf(url);
+  return (file, { signal, onUploadProgress } = {}) => new Promise((resolve, reject) => {
+    const running = startChunkedUpload({
+      file,
+      fileName: file.name,
+      fieldName,
+      metadata,
+      url,
+      patchUrl: piecesUrl,
+      withCredentials,
+      chunkSize: chunkBytes,
+      headers: { "Accept-Language": toolkitSettings().language, ...headers },
+      retryDelays: chunkRetryDelays,
+      sendRequest,
+      holdBeforeFull: false,
+      onProgress: (loaded, total) => onUploadProgress?.({ loaded, total })
+    });
+    signal?.addEventListener("abort", () => running.abort(), { once: true });
+    if (signal?.aborted) {
+      running.abort();
+    }
+    running.done.then(
+      (folio) => resolve({ id: folio }),
+      async (failure) => reject(failure?.name === "AbortError" ? failure : await apiErrorOfFailure(failure, toProblem))
+    );
+  });
+}
+export {
+  CHUNK_HEADER,
+  DEFAULT_CHUNK_RETRY_DELAYS,
+  DEFAULT_CHUNK_SIZE,
+  UPLOAD_FAILURE,
+  UploadFailure,
+  chunkPiecesOf,
+  createChunkedUpload,
+  defaultPatchUrlOf,
+  headerTextOf,
+  honestLoadedOf,
+  problemOfResponse,
+  startChunkedUpload,
+  storedBytesOf
+};
+//# sourceMappingURL=chunkedUpload.js.map

package/dist/upload/chunkedUpload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunkedUpload.js","sources":["../../src/upload/chunkedUpload.js"],"sourcesContent":["// Subir UN archivo por trozos, con el protocolo de trozos de FilePond (el que ya esperan los backends que lo usan):\n//   1. POST a url con «Upload-Length» (lo que pesa el archivo): el servidor aparta un lugar y contesta su folio (texto)\n//   2. cada trozo en su PATCH a patchUrl + folio, uno detrás de otro, con Upload-Offset (dónde empieza), Upload-Length y\n//      Upload-Name; el cuerpo es el pedazo del archivo tal cual (application/offset+octet-stream)\n//   3. al reintentar después de un error, HEAD a patchUrl + folio: «Upload-Offset» dice desde dónde seguir\n//\n// Lo usan la zona de FilePond (createPondServer, con chunkUploads) y el cargador mini (createChunkedUpload, la función\n// upload de FileUploadInput y FormFileUploadField).\n//\n// Por qué lo hace Calcita y no FilePond: FilePond cuenta lo que ya SALIÓ del navegador y pinta «100 %» mientras el servidor\n// todavía guarda el último trozo (hay servidores que esperan medio segundo por trozo, a propósito). Aquí la barra es honesta:\n//   - suma lo que el servidor ya confirmó más lo que va en camino del trozo de ahora;\n//   - nunca regresa (un trozo que se reintenta no baja la barra);\n//   - el final depende de la vista (holdBeforeFull): la tarjeta de FilePond no tiene «Procesando», así que se queda en 99 %\n//     hasta que el servidor confirma el último trozo; el cargador mini sí lo tiene: llega a 100 % cuando salió el último\n//     byte y su «Procesando» dice que el servidor está guardando.\n// Los trozos van uno tras otro, nunca juntos: el que tarda es el servidor y mandar dos a la vez no gana nada.\n//\n// Reintentos: solo cuando no hubo respuesta o el servidor falló (5xx), con las esperas de retryDelays. Un 4xx es el servidor\n// diciendo que no: se enseña en seguida, sin hacer esperar a la persona.\n//\n// OJO, distinto de FilePond: con un archivo que mide justo N trozos, FilePond manda al final un PATCH vacío de más (el\n// servidor ya había armado el archivo); aquí no.\n//\n// Cada petición sale por sendRequest, con la misma forma que uploadWithProgress de la casa (url, cuerpo, {method, headers,\n// onProgress, signal, withCredentials}) → Response: así el proyecto la pasa por su propio cliente, o se prueba sin servidor.\n//\n// Funciones del navegador, sin React: function (regla de la casa). Se prueba con node --test (chunkedUpload.test.js) con un\n// servidor de mentira.\nimport {ApiError} from '@/api/ApiError.js';\nimport {createLogger} from '@/observability/logger.js';\nimport {toolkitSettings, translateToolkit} from '@/toolkit/toolkitSettings.js';\nimport {parseFileSize} from '@/upload/fileRules.js';\nimport {uploadWithProgress} from '@/upload/uploadWithProgress.js';\n\nconst log = createLogger('upload');\n\n/** Los headers del protocolo de trozos de FilePond. */\nexport const CHUNK_HEADER = Object.freeze({\n    length: 'Upload-Length',\n    offset: 'Upload-Offset',\n    name: 'Upload-Name',\n    contentType: 'Content-Type',\n});\n\n/** Por qué no se pudo subir: el servidor dijo que no, no contestó, o no dio el folio de la subida. */\nexport const UPLOAD_FAILURE = Object.freeze({rejected: 'rejected', noResponse: 'noResponse', noTransferId: 'noTransferId'});\n\n// el cuerpo de cada trozo: los bytes del archivo tal cual, desde Upload-Offset\nconst CHUNK_CONTENT_TYPE = 'application/offset+octet-stream';\n// la barra se detiene aquí hasta que el servidor confirma el último trozo (FilePond redondea: 99.6 % ya diría «100 %»)\nconst HONEST_CEILING = 0.99;\nconst SERVER_ERROR_STATUS = 500;\n// status de «no hubo respuesta» (los textos del paquete dicen «sin conexión»)\nconst OFFLINE_STATUS = 0;\n/** Los de FilePond: trozos de 5 MB y tres reintentos por trozo. */\nexport const DEFAULT_CHUNK_SIZE = 5_000_000;\nexport const DEFAULT_CHUNK_RETRY_DELAYS = Object.freeze([500, 1000, 3000]);\n\n/** Una subida que no salió: el motivo (UPLOAD_FAILURE) y la respuesta del servidor, si la hubo. */\nexport class UploadFailure extends Error {\n    /**\n     * @param {string} reason de UPLOAD_FAILURE\n     * @param {Response|null} [response]\n     */\n    constructor(reason, response = null) {\n        super(`La subida no salió: ${reason}`);\n        this.name = 'UploadFailure';\n        this.reason = reason;\n        this.response = response;\n    }\n}\n\n/**\n * Los trozos de un archivo: dónde empieza y dónde acaba cada uno. Un archivo vacío es un trozo vacío: el servidor igual\n * necesita saber que el archivo llegó completo.\n *\n * @param {number} fileSize en bytes\n * @param {number} chunkSize en bytes\n * @returns {{index: number, offset: number, end: number}[]}\n */\nexport function chunkPiecesOf(fileSize, chunkSize) {\n    const count = Math.max(1, Math.ceil(fileSize / chunkSize));\n    return Array.from({length: count}, (_, index) => {\n        const offset = index * chunkSize;\n        return {index, offset, end: Math.min(offset + chunkSize, fileSize)};\n    });\n}\n\n/**\n * Lo que la barra puede decir que ya subió: lo que el servidor confirmó más lo que va en camino del trozo de ahora, sin\n * llegar al final hasta que el servidor confirma el último trozo.\n *\n * @param {{confirmedBytes: number, sendingBytes: number, totalBytes: number}} transfer\n * @returns {number} bytes\n */\nexport function honestLoadedOf({confirmedBytes, sendingBytes, totalBytes}) {\n    return Math.min(confirmedBytes + sendingBytes, Math.floor(totalBytes * HONEST_CEILING));\n}\n\n/**\n * Hasta dónde ya está guardado el archivo cuando el servidor dice su Upload-Offset: el final del último trozo COMPLETO antes\n * de ese punto. Un trozo que quedó a medias se vuelve a mandar entero.\n *\n * @param {{offset: number, end: number}[]} pieces\n * @param {number} serverOffset\n * @returns {number}\n */\nexport function storedBytesOf(pieces, serverOffset) {\n    return pieces.filter((piece) => piece.end > piece.offset && piece.end <= serverOffset).reduce((last, piece) => Math.max(last, piece.end), 0);\n}\n\n/**\n * Un texto listo para viajar en un header. Los headers solo llevan bytes: el texto va en UTF-8 byte por byte (lo mismo que\n * FilePond hace con los suyos). Sin esto, un nombre con «–» o con un emoji tumba la petición y uno con acentos llega roto.\n *\n * @param {unknown} value\n * @returns {string}\n */\nexport function headerTextOf(value) {\n    return String.fromCharCode(...new TextEncoder().encode(String(value)));\n}\n\n/**\n * @param {Record<string, unknown>} headers\n * @returns {Record<string, string>}\n */\nfunction headerTextsOf(headers) {\n    return Object.fromEntries(Object.entries(headers).map(([name, value]) => [name, headerTextOf(value)]));\n}\n\n/**\n * Espera antes de reintentar; si la persona cancela mientras tanto, termina en AbortError como lo demás.\n *\n * @param {number} milliseconds\n * @param {AbortSignal} signal\n * @returns {Promise<void>}\n */\nfunction waitBeforeRetry(milliseconds, signal) {\n    return new Promise((resolve, reject) => {\n        const timer = setTimeout(resolve, milliseconds);\n        signal.addEventListener('abort', () => {\n            clearTimeout(timer);\n            reject(new DOMException('La subida se canceló', 'AbortError'));\n        }, {once: true});\n    });\n}\n\n/**\n * Manda una petición y la repite si no hubo respuesta o el servidor falló (5xx), con las esperas de retryDelays. Regresa la\n * respuesta buena; si no la hubo, termina en UploadFailure. Cancelar termina en AbortError.\n *\n * @param {() => Promise<Response>} sendOnce\n * @param {number[]|null|undefined} retryDelays\n * @param {AbortSignal} signal\n * @returns {Promise<Response>}\n */\nasync function sendWithRetries(sendOnce, retryDelays, signal) {\n    const delays = [...(retryDelays ?? [])];\n    for (;;) {\n        let response = null;\n        try {\n            response = await sendOnce();\n        } catch (failure) {\n            // cancelar no es un error de la subida: sube tal cual\n            if (failure?.name === 'AbortError') {\n                throw failure;\n            }\n            // sin respuesta (sin red, el servidor se cayó): se puede reintentar\n        }\n        if (response?.ok) {\n            return response;\n        }\n        const canRetry = response === null || response.status >= SERVER_ERROR_STATUS;\n        if (!canRetry || delays.length === 0) {\n            throw new UploadFailure(response ? UPLOAD_FAILURE.rejected : UPLOAD_FAILURE.noResponse, response);\n        }\n        await waitBeforeRetry(delays.shift(), signal);\n    }\n}\n\n/**\n * @typedef {(url: string, body: FormData|Blob|null, options: {method: string, headers: Record<string, string>, withCredentials: boolean, signal: AbortSignal, onProgress?: (percent: number, transfer: {loaded: number, total: number}) => void}) => Promise<Response>} UploadSendRequest\n *   cómo viaja cada petición: la misma forma que uploadWithProgress de la casa\n */\n\n/**\n * A dónde van los trozos si no se dice: lo que usa FilePond, «?patch=» pegado a url (o «&patch=» si url ya trae «?»).\n *\n * @param {string} url\n * @returns {string}\n */\nexport function defaultPatchUrlOf(url) {\n    return `${url}${url.includes('?') ? '&' : '?'}patch=`;\n}\n\n/**\n * El problema del cuerpo de error: el JSON del servidor, pasado por el adaptador del proyecto (toProblem). Lo que no sea un\n * objeto cuenta como sin problema (se usa el texto genérico del paquete). Un adaptador que truena no tumba el mensaje.\n *\n * @param {Response} response\n * @param {((body: any, response: Response) => any)|undefined} toProblem\n * @returns {Promise<object|null>}\n */\nexport async function problemOfResponse(response, toProblem) {\n    let body = null;\n    try {\n        body = JSON.parse(await response.text());\n    } catch {\n        // la respuesta no era JSON (un 502 del proxy en HTML): va el título genérico de su status\n    }\n    if (!body || typeof body !== 'object' || Array.isArray(body)) {\n        return null;\n    }\n    if (!toProblem) {\n        return body;\n    }\n    try {\n        const problem = toProblem(body, response);\n        return problem && typeof problem === 'object' && !Array.isArray(problem) ? problem : null;\n    } catch (failure) {\n        log.error('toProblem tronó al leer el error de una subida', failure);\n        return null;\n    }\n}\n\n/**\n * Sube un archivo por trozos (ver el encabezado). Regresa la subida en curso: done termina con el folio que dio el servidor\n * y abort la cancela de verdad (la petición de ahora y los reintentos que esperaban).\n *\n * @param {object} options\n * @param {Blob} options.file\n * @param {string} options.fileName el que viaja en Upload-Name\n * @param {string} options.fieldName el campo del primer POST: lleva los metadatos en JSON, como FilePond\n * @param {object|null} [options.metadata]\n * @param {string} options.url a dónde va el POST que pide el folio\n * @param {string} options.patchUrl a dónde va cada trozo: el folio va pegado al final ('/subidas?patch=')\n * @param {Record<string, unknown>} [options.headers] van en las tres peticiones (Authorization, los datos de la pantalla)\n * @param {boolean} [options.withCredentials]\n * @param {number} options.chunkSize en bytes\n * @param {number[]|null} [options.retryDelays] las esperas entre reintentos, en milisegundos; null o [] = sin reintentos\n * @param {string|null} [options.transferId] el folio de un intento anterior: se sigue desde donde se quedó\n * @param {(transferId: string) => void} [options.onTransferId] el folio nuevo, para retomar si algo falla\n * @param {(loaded: number, total: number) => void} [options.onProgress] lo honesto (ver honestLoadedOf), en bytes\n * @param {boolean} [options.holdBeforeFull] true (por omisión): la barra se queda en 99 % hasta que el servidor confirma el\n *     último trozo (una vista sin «Procesando»); false: llega a 100 % cuando salió el último byte\n * @param {UploadSendRequest} options.sendRequest\n * @returns {{done: Promise<string>, abort: () => void}}\n */\nexport function startChunkedUpload(options) {\n    const controller = new AbortController();\n    const done = runChunkedUpload(options, controller.signal);\n    return {done, abort: () => controller.abort()};\n}\n\n/**\n * @param {Parameters<typeof startChunkedUpload>[0]} options\n * @param {AbortSignal} signal\n * @returns {Promise<string>} el folio\n */\nasync function runChunkedUpload(options, signal) {\n    const {file, fileName, fieldName, metadata = null, url, patchUrl, headers = {}, withCredentials = false, chunkSize, retryDelays,\n        transferId = null, onTransferId, onProgress, holdBeforeFull = true, sendRequest} = options;\n    const totalBytes = file.size;\n    const pieces = chunkPiecesOf(totalBytes, chunkSize);\n    const send = (requestUrl, body, method, protocolHeaders, onUploadProgress) => sendRequest(requestUrl, body, {\n        method, headers: headerTextsOf({...headers, ...protocolHeaders}), withCredentials, signal, onProgress: onUploadProgress,\n    });\n\n    // lo que la barra ya enseñó: nunca regresa\n    let shownBytes = 0;\n    let confirmedBytes = 0;\n    const showProgress = (sendingBytes) => {\n        // cancelada, ya no hay avance que contar: la tarjeta se queda en «cancelada»\n        if (signal.aborted) {\n            return;\n        }\n        const loadedBytes = holdBeforeFull\n            ? honestLoadedOf({confirmedBytes, sendingBytes, totalBytes})\n            : Math.min(confirmedBytes + sendingBytes, totalBytes);\n        shownBytes = Math.max(shownBytes, loadedBytes);\n        // un archivo vacío no tiene avance que contar\n        if (totalBytes > 0) {\n            onProgress?.(shownBytes, totalBytes);\n        }\n    };\n\n    // 1. el folio: uno nuevo, o el del intento anterior y hasta dónde llegó\n    let folio = transferId;\n    if (folio) {\n        const offsetResponse = await sendWithRetries(() => send(`${patchUrl}${encodeURIComponent(folio)}`, null, 'HEAD', {}), retryDelays, signal);\n        const serverOffset = Number.parseInt(offsetResponse.headers.get(CHUNK_HEADER.offset) ?? '', 10);\n        confirmedBytes = storedBytesOf(pieces, Number.isNaN(serverOffset) ? 0 : serverOffset);\n    } else {\n        const firstRequest = new FormData();\n        // los metadatos de FilePond van en el campo del archivo, como los manda FilePond\n        if (metadata && typeof metadata === 'object') {\n            firstRequest.append(fieldName, JSON.stringify(metadata));\n        }\n        const transferResponse = await sendWithRetries(() => send(url, firstRequest, 'POST', {[CHUNK_HEADER.length]: totalBytes}), retryDelays, signal);\n        folio = (await transferResponse.text()).trim();\n        if (!folio) {\n            throw new UploadFailure(UPLOAD_FAILURE.noTransferId, transferResponse);\n        }\n        onTransferId?.(folio);\n    }\n    showProgress(0);\n\n    // 2. los trozos que faltan, uno tras otro: el siguiente sale cuando el servidor confirmó el anterior\n    for (const piece of pieces) {\n        const isAlreadyStored = piece.end > piece.offset && piece.end <= confirmedBytes;\n        if (isAlreadyStored) {\n            continue;\n        }\n        const pieceHeaders = {\n            [CHUNK_HEADER.contentType]: CHUNK_CONTENT_TYPE,\n            [CHUNK_HEADER.offset]: piece.offset,\n            [CHUNK_HEADER.length]: totalBytes,\n            [CHUNK_HEADER.name]: fileName,\n        };\n        await sendWithRetries(\n            () => send(`${patchUrl}${encodeURIComponent(folio)}`, file.slice(piece.offset, piece.end, CHUNK_CONTENT_TYPE), 'PATCH', pieceHeaders,\n                (percent, transfer) => showProgress(transfer.loaded)),\n            retryDelays,\n            signal,\n        );\n        confirmedBytes = piece.end;\n        showProgress(0);\n    }\n    return folio;\n}\n\n/**\n * El ApiError de una subida que no salió, para las vistas que leen el error de la casa (el cargador mini enseña el motivo del\n * servidor: el primer error por campo o su detail).\n *\n * @param {unknown} failure\n * @param {((body: any, response: Response) => any)|undefined} toProblem\n * @returns {Promise<ApiError>}\n */\nasync function apiErrorOfFailure(failure, toProblem) {\n    if (failure?.reason === UPLOAD_FAILURE.noTransferId) {\n        const message = translateToolkit('common', 'upload.pond.noTransferId');\n        return new ApiError({status: failure.response?.status ?? OFFLINE_STATUS, problem: {title: message, detail: message}});\n    }\n    if (failure?.reason === UPLOAD_FAILURE.rejected && failure.response) {\n        return new ApiError({status: failure.response.status, problem: await problemOfResponse(failure.response, toProblem)});\n    }\n    if (failure?.reason !== UPLOAD_FAILURE.noResponse) {\n        // no es de la red ni del servidor: un error de programación, que se anota para encontrarlo\n        log.error('La subida por trozos falló sin respuesta del servidor', failure);\n    }\n    return new ApiError({status: OFFLINE_STATUS});\n}\n\n/**\n * La subida por trozos para el cargador mini (upload de FileUploadInput y FormFileUploadField) o para una pantalla propia:\n * regresa esa función upload. Todo va por trozos (un archivo chico va en un solo trozo); si solo los grandes deben ir por\n * trozos, la pantalla elige: upload={(file, options) => (file.size > LIMITE ? porTrozos : subidaNormal)(file, options)}.\n *\n *   const uploadBackup = createChunkedUpload({url: '/upload', patchUrl: '/upload?patch=', chunkSize: '1 MB'});\n *   <FileUploadInput label=\"Respaldo\" value={fileId} onChange={setFileId} upload={uploadBackup} />\n *\n * Al terminar regresa {id: folio} (idOf lo lee por omisión). Con todo enviado la barra llega a 100 % y el renglón dice\n * «Procesando» hasta que el servidor guarda el último trozo. Los errores son ApiError: el renglón enseña el motivo del\n * servidor (con toProblem, también el de un backend que no contesta RFC 9457). Cancelar termina en AbortError.\n *\n * @param {object} options\n * @param {string} options.url a dónde va el POST que pide el folio\n * @param {string} [options.patchUrl] a dónde va cada trozo, con el folio pegado al final; por omisión url + '?patch='\n * @param {number|string} [options.chunkSize] en bytes o con unidades ('1 MB'); por omisión 5 MB, el de FilePond\n * @param {number[]|null} [options.chunkRetryDelays] esperas entre reintentos de un trozo (ms); null o [] = sin reintentos\n * @param {Record<string, string>} [options.headers] van en todas las peticiones, como texto normal (viajan en UTF-8)\n * @param {boolean} [options.withCredentials]\n * @param {(body: any, response: Response) => any} [options.toProblem] el error del backend a la forma RFC 9457\n * @param {UploadSendRequest} [options.sendRequest] cómo viaja cada petición; por omisión uploadWithProgress de la casa\n * @param {string} [options.fieldName] el campo del primer POST; por omisión 'file'\n * @param {object|null} [options.metadata] lo que viaja en ese campo en JSON, como los metadatos de FilePond\n * @returns {(file: File, options?: {signal?: AbortSignal, onUploadProgress?: (transfer: {loaded: number, total: number}) => void}) => Promise<{id: string}>}\n */\nexport function createChunkedUpload({url, patchUrl, chunkSize = DEFAULT_CHUNK_SIZE, chunkRetryDelays = DEFAULT_CHUNK_RETRY_DELAYS, headers = {},\n    withCredentials = false, toProblem, sendRequest = uploadWithProgress, fieldName = 'file', metadata = null}) {\n    const chunkBytes = parseFileSize(chunkSize);\n    const piecesUrl = patchUrl ?? defaultPatchUrlOf(url);\n    return (file, {signal, onUploadProgress} = {}) => new Promise((resolve, reject) => {\n        const running = startChunkedUpload({\n            file, fileName: file.name, fieldName, metadata, url, patchUrl: piecesUrl, withCredentials, chunkSize: chunkBytes,\n            headers: {'Accept-Language': toolkitSettings().language, ...headers}, retryDelays: chunkRetryDelays, sendRequest,\n            holdBeforeFull: false, onProgress: (loaded, total) => onUploadProgress?.({loaded, total}),\n        });\n        signal?.addEventListener('abort', () => running.abort(), {once: true});\n        if (signal?.aborted) {\n            running.abort();\n        }\n        running.done.then(\n            (folio) => resolve({id: folio}),\n            async (failure) => reject(failure?.name === 'AbortError' ? failure : await apiErrorOfFailure(failure, toProblem)),\n        );\n    });\n}\n"],"names":[],"mappings":"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"}

package/dist/upload/uploadWithProgress.js

@@ -1,5 +1,6 @@
 import { toolkitSettings } from "../toolkit/toolkitSettings.js";
 const PERCENT = 100;
+const NULL_BODY_STATUSES = /* @__PURE__ */ new Set([101, 204, 205, 304]);
 function headersOf(rawHeaders) {
   const headers = {};
   for (const line of String(rawHeaders ?? "").trim().split(/[\r\n]+/)) {
@@ -10,14 +11,14 @@ function headersOf(rawHeaders) {
   }
   return headers;
 }
-function uploadWithProgress(url, formData, { headers = {}, onProgress, signal, withCredentials = false } = {}) {
+function uploadWithProgress(url, formData, { method = "POST", headers = {}, onProgress, signal, withCredentials = false } = {}) {
   return new Promise((resolve, reject) => {
     if (signal?.aborted) {
       reject(new DOMException("La subida se canceló", "AbortError"));
       return;
     }
     const request = new XMLHttpRequest();
-    request.open("POST", url);
+    request.open(method, url);
     request.responseType = "blob";
     request.withCredentials = withCredentials;
     signal?.addEventListener("abort", () => request.abort(), { once: true });
@@ -26,12 +27,16 @@ function uploadWithProgress(url, formData, { headers = {}, onProgress, signal, w
       request.setRequestHeader(name, value);
     }
     request.upload.onprogress = (event) => {
+      if (signal?.aborted) {
+        return;
+      }
       if (event.lengthComputable) {
         onProgress?.(Math.round(event.loaded / event.total * PERCENT), { loaded: event.loaded, total: event.total });
       }
     };
     request.onload = () => {
-      resolve(new Response(request.response, { status: request.status, headers: headersOf(request.getAllResponseHeaders()) }));
+      const body = NULL_BODY_STATUSES.has(request.status) ? null : request.response;
+      resolve(new Response(body, { status: request.status, headers: headersOf(request.getAllResponseHeaders()) }));
     };
     request.onerror = () => reject(new TypeError("No hubo respuesta del servidor"));
     request.ontimeout = () => reject(new TypeError("El servidor tardó demasiado en responder"));

package/dist/upload/uploadWithProgress.js.map

@@ -1 +1 @@
-{"version":3,"file":"uploadWithProgress.js","sources":["../../src/upload/uploadWithProgress.js"],"sourcesContent":["// Subir un formulario con archivos (multipart) con el AVANCE real de la subida.\n//\n// fetch no dice cuántos bytes del cuerpo ya viajaron; XMLHttpRequest sí (xhr.upload.onprogress). Es UNA petición normal,\n// el mismo POST de siempre, pero la pantalla puede pintar «Subiendo 47 %».\n//\n// El avance llega a 100 % cuando el CUERPO terminó de viajar; lo que sigue (el servidor procesando y la respuesta\n// bajando) ya no se puede medir aquí: la pantalla cambia a «procesando…» sin porcentaje (uploadMachine lo hace sola).\n//\n// Responde como fetch: un Response (res.ok, res.status, res.headers, res.json(), res.blob()), así quien llama trata el\n// error RFC 9457 igual que con cualquier otra petición. La cancelación también es la de fetch: AbortSignal → AbortError.\n//\n// Funciones del navegador, sin React: function (regla de la casa). Se prueba con node --test (uploadWithProgress.test.js)\n// con un XMLHttpRequest de mentira.\nimport {toolkitSettings} from '@/toolkit/toolkitSettings.js';\n\nconst PERCENT = 100;\n\n/**\n * Los headers de XMLHttpRequest ('k: v\\r\\nk2: v2') como objeto para Response.\n *\n * @param {string|null} rawHeaders\n * @returns {Record<string, string>}\n */\nfunction headersOf(rawHeaders) {\n    const headers = {};\n    for (const line of String(rawHeaders ?? '').trim().split(/[\\r\\n]+/)) {\n        const separatorPosition = line.indexOf(': ');\n        if (separatorPosition > 0) {\n            headers[line.slice(0, separatorPosition)] = line.slice(separatorPosition + 2);\n        }\n    }\n    return headers;\n}\n\n/**\n * @param {string} url\n * @param {FormData} formData los archivos y los campos que pida el backend\n * @param {object} [options]\n * @param {Record<string, string>} [options.headers] p. ej. Authorization; Accept-Language ya va con el idioma activo\n * @param {(percent: number, transfer: {loaded: number, total: number}) => void} [options.onProgress] 0 a 100 de lo que ya\n *     viajó del cuerpo, y los bytes (para la velocidad y lo que falta)\n * @param {AbortSignal} [options.signal]\n * @param {boolean} [options.withCredentials] manda las cookies a otro dominio (sesión de Sanctum en otro subdominio)\n * @returns {Promise<Response>}\n */\nexport function uploadWithProgress(url, formData, {headers = {}, onProgress, signal, withCredentials = false} = {}) {\n    return new Promise((resolve, reject) => {\n        // guard clause: ya venía cancelada\n        if (signal?.aborted) {\n            reject(new DOMException('La subida se canceló', 'AbortError'));\n            return;\n        }\n\n        const request = new XMLHttpRequest();\n        request.open('POST', url);\n        request.responseType = 'blob';\n        request.withCredentials = withCredentials;\n        signal?.addEventListener('abort', () => request.abort(), {once: true});\n\n        // OJO: Content-Type NO se pone a mano: el navegador lo arma con el separador del multipart; puesto a mano, el\n        // servidor no encuentra los archivos\n        const finalHeaders = {'Accept-Language': toolkitSettings().language, ...headers};\n        for (const [name, value] of Object.entries(finalHeaders)) {\n            request.setRequestHeader(name, value);\n        }\n\n        request.upload.onprogress = (event) => {\n            if (event.lengthComputable) {\n                onProgress?.(Math.round((event.loaded / event.total) * PERCENT), {loaded: event.loaded, total: event.total});\n            }\n        };\n        request.onload = () => {\n            resolve(new Response(request.response, {status: request.status, headers: headersOf(request.getAllResponseHeaders())}));\n        };\n        request.onerror = () => reject(new TypeError('No hubo respuesta del servidor'));\n        request.ontimeout = () => reject(new TypeError('El servidor tardó demasiado en responder'));\n        request.onabort = () => reject(new DOMException('La subida se canceló', 'AbortError'));\n        request.send(formData);\n    });\n}\n"],"names":[],"mappings":";AAeA,MAAM,UAAU;AAQhB,SAAS,UAAU,YAAY;AAC3B,QAAM,UAAU,CAAA;AAChB,aAAW,QAAQ,OAAO,cAAc,EAAE,EAAE,KAAI,EAAG,MAAM,SAAS,GAAG;AACjE,UAAM,oBAAoB,KAAK,QAAQ,IAAI;AAC3C,QAAI,oBAAoB,GAAG;AACvB,cAAQ,KAAK,MAAM,GAAG,iBAAiB,CAAC,IAAI,KAAK,MAAM,oBAAoB,CAAC;AAAA,IAChF;AAAA,EACJ;AACA,SAAO;AACX;AAaO,SAAS,mBAAmB,KAAK,UAAU,EAAC,UAAU,CAAA,GAAI,YAAY,QAAQ,kBAAkB,MAAK,IAAI,CAAA,GAAI;AAChH,SAAO,IAAI,QAAQ,CAAC,SAAS,WAAW;AAEpC,QAAI,QAAQ,SAAS;AACjB,aAAO,IAAI,aAAa,wBAAwB,YAAY,CAAC;AAC7D;AAAA,IACJ;AAEA,UAAM,UAAU,IAAI,eAAc;AAClC,YAAQ,KAAK,QAAQ,GAAG;AACxB,YAAQ,eAAe;AACvB,YAAQ,kBAAkB;AAC1B,YAAQ,iBAAiB,SAAS,MAAM,QAAQ,SAAS,EAAC,MAAM,KAAI,CAAC;AAIrE,UAAM,eAAe,EAAC,mBAAmB,gBAAe,EAAG,UAAU,GAAG,QAAO;AAC/E,eAAW,CAAC,MAAM,KAAK,KAAK,OAAO,QAAQ,YAAY,GAAG;AACtD,cAAQ,iBAAiB,MAAM,KAAK;AAAA,IACxC;AAEA,YAAQ,OAAO,aAAa,CAAC,UAAU;AACnC,UAAI,MAAM,kBAAkB;AACxB,qBAAa,KAAK,MAAO,MAAM,SAAS,MAAM,QAAS,OAAO,GAAG,EAAC,QAAQ,MAAM,QAAQ,OAAO,MAAM,MAAK,CAAC;AAAA,MAC/G;AAAA,IACJ;AACA,YAAQ,SAAS,MAAM;AACnB,cAAQ,IAAI,SAAS,QAAQ,UAAU,EAAC,QAAQ,QAAQ,QAAQ,SAAS,UAAU,QAAQ,sBAAqB,CAAE,EAAC,CAAC,CAAC;AAAA,IACzH;AACA,YAAQ,UAAU,MAAM,OAAO,IAAI,UAAU,gCAAgC,CAAC;AAC9E,YAAQ,YAAY,MAAM,OAAO,IAAI,UAAU,0CAA0C,CAAC;AAC1F,YAAQ,UAAU,MAAM,OAAO,IAAI,aAAa,wBAAwB,YAAY,CAAC;AACrF,YAAQ,KAAK,QAAQ;AAAA,EACzB,CAAC;AACL;"}
+{"version":3,"file":"uploadWithProgress.js","sources":["../../src/upload/uploadWithProgress.js"],"sourcesContent":["// Subir un formulario con archivos (multipart) con el AVANCE real de la subida.\n//\n// fetch no dice cuántos bytes del cuerpo ya viajaron; XMLHttpRequest sí (xhr.upload.onprogress). Es UNA petición normal,\n// el mismo POST de siempre, pero la pantalla puede pintar «Subiendo 47 %».\n//\n// El avance llega a 100 % cuando el CUERPO terminó de viajar; lo que sigue (el servidor procesando y la respuesta\n// bajando) ya no se puede medir aquí: la pantalla cambia a «procesando…» sin porcentaje (uploadMachine lo hace sola).\n//\n// Responde como fetch: un Response (res.ok, res.status, res.headers, res.json(), res.blob()), así quien llama trata el\n// error RFC 9457 igual que con cualquier otra petición. La cancelación también es la de fetch: AbortSignal → AbortError.\n//\n// Por omisión es un POST; method cambia el verbo para los protocolos que suben por partes (el PATCH de cada trozo y el HEAD\n// que pregunta hasta dónde llegó, en la subida por trozos de FilePond).\n//\n// Funciones del navegador, sin React: function (regla de la casa). Se prueba con node --test (uploadWithProgress.test.js)\n// con un XMLHttpRequest de mentira.\nimport {toolkitSettings} from '@/toolkit/toolkitSettings.js';\n\nconst PERCENT = 100;\n// las respuestas que por regla no llevan cuerpo: Response truena si se le da uno, aunque venga vacío (un 204 a un PATCH es\n// lo normal en una subida por trozos)\nconst NULL_BODY_STATUSES = new Set([101, 204, 205, 304]);\n\n/**\n * Los headers de XMLHttpRequest ('k: v\\r\\nk2: v2') como objeto para Response.\n *\n * @param {string|null} rawHeaders\n * @returns {Record<string, string>}\n */\nfunction headersOf(rawHeaders) {\n    const headers = {};\n    for (const line of String(rawHeaders ?? '').trim().split(/[\\r\\n]+/)) {\n        const separatorPosition = line.indexOf(': ');\n        if (separatorPosition > 0) {\n            headers[line.slice(0, separatorPosition)] = line.slice(separatorPosition + 2);\n        }\n    }\n    return headers;\n}\n\n/**\n * @param {string} url\n * @param {FormData|Blob|null} formData los archivos y los campos que pida el backend (un trozo del archivo, o nada en un HEAD)\n * @param {object} [options]\n * @param {string} [options.method] por omisión POST\n * @param {Record<string, string>} [options.headers] p. ej. Authorization; Accept-Language ya va con el idioma activo\n * @param {(percent: number, transfer: {loaded: number, total: number}) => void} [options.onProgress] 0 a 100 de lo que ya\n *     viajó del cuerpo, y los bytes (para la velocidad y lo que falta)\n * @param {AbortSignal} [options.signal]\n * @param {boolean} [options.withCredentials] manda las cookies a otro dominio (sesión de Sanctum en otro subdominio)\n * @returns {Promise<Response>}\n */\nexport function uploadWithProgress(url, formData, {method = 'POST', headers = {}, onProgress, signal, withCredentials = false} = {}) {\n    return new Promise((resolve, reject) => {\n        // guard clause: ya venía cancelada\n        if (signal?.aborted) {\n            reject(new DOMException('La subida se canceló', 'AbortError'));\n            return;\n        }\n\n        const request = new XMLHttpRequest();\n        request.open(method, url);\n        request.responseType = 'blob';\n        request.withCredentials = withCredentials;\n        signal?.addEventListener('abort', () => request.abort(), {once: true});\n\n        // OJO: Content-Type NO se pone a mano: el navegador lo arma con el separador del multipart; puesto a mano, el\n        // servidor no encuentra los archivos\n        const finalHeaders = {'Accept-Language': toolkitSettings().language, ...headers};\n        for (const [name, value] of Object.entries(finalHeaders)) {\n            request.setRequestHeader(name, value);\n        }\n\n        request.upload.onprogress = (event) => {\n            // al cancelar, el navegador todavía avisa un último avance: ya no se cuenta (la pantalla volvería a «Subiendo»)\n            if (signal?.aborted) {\n                return;\n            }\n            if (event.lengthComputable) {\n                onProgress?.(Math.round((event.loaded / event.total) * PERCENT), {loaded: event.loaded, total: event.total});\n            }\n        };\n        request.onload = () => {\n            const body = NULL_BODY_STATUSES.has(request.status) ? null : request.response;\n            resolve(new Response(body, {status: request.status, headers: headersOf(request.getAllResponseHeaders())}));\n        };\n        request.onerror = () => reject(new TypeError('No hubo respuesta del servidor'));\n        request.ontimeout = () => reject(new TypeError('El servidor tardó demasiado en responder'));\n        request.onabort = () => reject(new DOMException('La subida se canceló', 'AbortError'));\n        request.send(formData);\n    });\n}\n"],"names":[],"mappings":";AAkBA,MAAM,UAAU;AAGhB,MAAM,qBAAqB,oBAAI,IAAI,CAAC,KAAK,KAAK,KAAK,GAAG,CAAC;AAQvD,SAAS,UAAU,YAAY;AAC3B,QAAM,UAAU,CAAA;AAChB,aAAW,QAAQ,OAAO,cAAc,EAAE,EAAE,KAAI,EAAG,MAAM,SAAS,GAAG;AACjE,UAAM,oBAAoB,KAAK,QAAQ,IAAI;AAC3C,QAAI,oBAAoB,GAAG;AACvB,cAAQ,KAAK,MAAM,GAAG,iBAAiB,CAAC,IAAI,KAAK,MAAM,oBAAoB,CAAC;AAAA,IAChF;AAAA,EACJ;AACA,SAAO;AACX;AAcO,SAAS,mBAAmB,KAAK,UAAU,EAAC,SAAS,QAAQ,UAAU,CAAA,GAAI,YAAY,QAAQ,kBAAkB,MAAK,IAAI,CAAA,GAAI;AACjI,SAAO,IAAI,QAAQ,CAAC,SAAS,WAAW;AAEpC,QAAI,QAAQ,SAAS;AACjB,aAAO,IAAI,aAAa,wBAAwB,YAAY,CAAC;AAC7D;AAAA,IACJ;AAEA,UAAM,UAAU,IAAI,eAAc;AAClC,YAAQ,KAAK,QAAQ,GAAG;AACxB,YAAQ,eAAe;AACvB,YAAQ,kBAAkB;AAC1B,YAAQ,iBAAiB,SAAS,MAAM,QAAQ,SAAS,EAAC,MAAM,KAAI,CAAC;AAIrE,UAAM,eAAe,EAAC,mBAAmB,gBAAe,EAAG,UAAU,GAAG,QAAO;AAC/E,eAAW,CAAC,MAAM,KAAK,KAAK,OAAO,QAAQ,YAAY,GAAG;AACtD,cAAQ,iBAAiB,MAAM,KAAK;AAAA,IACxC;AAEA,YAAQ,OAAO,aAAa,CAAC,UAAU;AAEnC,UAAI,QAAQ,SAAS;AACjB;AAAA,MACJ;AACA,UAAI,MAAM,kBAAkB;AACxB,qBAAa,KAAK,MAAO,MAAM,SAAS,MAAM,QAAS,OAAO,GAAG,EAAC,QAAQ,MAAM,QAAQ,OAAO,MAAM,MAAK,CAAC;AAAA,MAC/G;AAAA,IACJ;AACA,YAAQ,SAAS,MAAM;AACnB,YAAM,OAAO,mBAAmB,IAAI,QAAQ,MAAM,IAAI,OAAO,QAAQ;AACrE,cAAQ,IAAI,SAAS,MAAM,EAAC,QAAQ,QAAQ,QAAQ,SAAS,UAAU,QAAQ,sBAAqB,CAAE,EAAC,CAAC,CAAC;AAAA,IAC7G;AACA,YAAQ,UAAU,MAAM,OAAO,IAAI,UAAU,gCAAgC,CAAC;AAC9E,YAAQ,YAAY,MAAM,OAAO,IAAI,UAAU,0CAA0C,CAAC;AAC1F,YAAQ,UAAU,MAAM,OAAO,IAAI,aAAa,wBAAwB,YAAY,CAAC;AACrF,YAAQ,KAAK,QAAQ;AAAA,EACzB,CAAC;AACL;"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@stackcraftmx/calcita",
-    "version": "0.52.0",
+    "version": "0.54.0",
     "description": "Componentes y utilidades de React con MUI para arrancar proyectos rápido: tabla de servidor, diálogos, avisos, descargas, formularios, formatos y reportes en Excel.",
     "license": "FSL-1.1-MIT",
     "author": "calcifux",