react-smart-copy

Contexto

Los botones de copiar aparecen en casi todos los productos: claves de API, identificadores, correos, enlaces de invitación y ejemplos de código. Suelen escribirse como una sola llamada al portapapeles con un mensaje de "Copiado", y se reescriben en cada base de código.

Esa llamada oculta casi todo el comportamiento real. Los navegadores rechazan escrituras fuera de HTTPS, las bloquean si cambia el foco, solo admiten algunos formatos y reportan fallos de forma inconsistente. La interfaz debe explicar todo eso a quien pulsó el botón.

Problema

Las implementaciones habituales fallan de formas que el usuario no ve y que los equipos rara vez prueban. El objetivo era una biblioteca que trate la copia como comportamiento de producto con estados definidos, no como una función utilitaria.

• Fallos como un contexto inseguro o un permiso denegado suelen no hacer nada en silencio.
• Una copia tarda unos milisegundos, así que un texto de estado ingenuo muestra "Copiando…" durante un fotograma y cambia el tamaño del botón.
• Los botones ocultos con display: none al pasar el cursor no se alcanzan con el teclado.
• El resultado rara vez se anuncia a usuarios de lectores de pantalla.
• El renderizado en servidor puede no coincidir cuando un componente lee el portapapeles durante el render.

Enfoque

La biblioteca se construye por capas. Un núcleo independiente del framework contiene una máquina de estados de copia, validación de contenido, un adaptador del portapapeles del navegador y la clasificación de errores. La capa de React añade hooks y un componente compuesto CopyField sobre ese núcleo.

Cada estado es explícito y observable: idle, copying, copied y error. Dos estados separan la lógica de la presentación: el estado real cambia al instante para lógica y pruebas, mientras que el estado visible solo muestra "Copiando…" cuando la copia es lenta y lo mantiene lo suficiente para evitar parpadeos.

• Copia texto, HTML enriquecido con texto plano obligatorio, imágenes PNG, JSON y varios formatos a la vez.
• Pega texto, HTML y capturas con usePaste, y el pegado con teclado no pide permisos.
• CopyGroup coordina filas para que solo una muestre "Copiado" a la vez.
• Un punto de entrada de captura copia un SVG o una parte de la interfaz como PNG.
• Los adaptadores personalizados permiten que entornos como Electron aporten su propio portapapeles.

Decisiones de accesibilidad

Las reglas de accesibilidad forman parte de los componentes, no de una documentación que el equipo deba recordar. El control siempre es un botón real y su nombre accesible se mantiene estable mientras el resultado se anuncia por separado.

• Los controles se alcanzan con Tab y se activan con Enter o Espacio.
• Las acciones reveladas permanecen en el DOM y en el orden de tabulación; se ocultan con opacidad, nunca con display: none.
• El foco de teclado fija la aparición; un clic de ratón no.
• El botón nunca se deshabilita mientras copia, así el foco de teclado no se pierde.
• La región en vivo se monta antes de su primer mensaje, para no perder el primer anuncio.
• Las animaciones respetan prefers-reduced-motion.

Errores, SSR y tamaño

Cada fallo es un error tipado y clasificado, como unsupported, insecure-context, permission-denied, not-focused, unsupported-format o too-large, e indica si un reintento puede ayudar. Nada falla en silencio.

La entrada de React incluye "use client" y nunca accede a window durante el render, así que el servidor y el primer render del cliente coinciden en Next.js. El paquete no tiene dependencias en tiempo de ejecución, y el README indica unos 3,2 kB para useCopy y 5,4 kB para todas las funciones de copia, minificados y comprimidos con Brotli.