Botones de copiar al portapapeles que no mienten: estados, tooltips y retroalimentación

Qué hace realmente el botón (y por qué falla)

Un botón de “copiar” es una promesa de UX respaldada por una cadena de condiciones: foco, requisitos de gesto del usuario, APIs del portapapeles del navegador, permisos, reglas de sandbox y, a veces, el propio servicio de portapapeles del sistema operativo. La interfaz vive en la cima de esa pila, lo que significa que debe ser humilde. No puede asumir el éxito. Tiene que confirmarlo.

La mayoría de fallos del portapapeles encajan en uno de estos grupos:

• Sin gesto del usuario: La operación de copia no se desencadena por un click/tap/tecla directo. Los navegadores la rechazan.
• Permisos o política: Las escrituras al portapapeles pueden ser bloqueadas por el navegador, políticas empresariales o configuraciones de sandbox en iframes.
• Problemas de foco y selección: Los fallbacks legacy dependen de seleccionar texto en un input/textarea; la gestión de foco lo rompe.
• Contexto incompatible: No es un contexto seguro (HTTP), o se ejecuta dentro de un iframe restringido sin atributos allow apropiados.
• Condiciones de carrera: Actualizaciones de estado de UI o desmontajes ocurren antes de que la promesa se resuelva; muestras “Copiado” en una escritura cancelada.
• Desajuste de contenido: Copiaste la cadena equivocada (clave enmascarada, texto truncado, espacios extra, formato local incorrecto).
• Particularidades móviles: Comportamientos de selección por pulsación larga, teclados virtuales y restricciones de Safari hacen que “funcionó en escritorio” sea una trampa.

Como SRE, me importa menos la animación del botón y más si tu retroalimentación refleja la realidad ante fallos. Si no puedes detectar el fallo, tu UI no debería afirmar el éxito. Eso no es “ser conservador”; es evitar el tipo de desconfianza del usuario que no recuperas.

Una cita para mantener la honestidad: “La esperanza no es una estrategia.” — Gordon R. Sullivan.

Aquí está la regla: debes tratar la escritura al portapapeles como una operación con latencia y modos de fallo. Merece estados e instrumentación como cualquier llamada de red. Las escrituras al portapapeles son menores, pero el impacto en el usuario es desproporcionadamente grande y ridículo.

Broma #1: Los bugs del portapapeles son como los bugs de DNS: todo el mundo jura que son imposibles hasta que su pager lo demuestra.

El único modelo sensato: una máquina de estados explícita

Deja de pensar “click del botón → copiar → hecho.” Piensa: idle → copying → copied o failed → volver a idle. Eso es una máquina de estados, y las máquinas de estados son cómo mantienes la UI honesta cuando la realidad asincrónica interfiere.

Estados recomendados (verdad mínima viable)

• Idle: El botón invita a la acción. Tooltip: “Copiar”. Icono: portapapeles.
• Copying: Iniciaste una copia, promesa pendiente. Tooltip: “Copiando…” (o sin tooltip). Deshabilita el botón para evitar doble disparo.
• Copied: Éxito confirmado. Tooltip: “Copiado”. Icono: marca de verificación. Restablecer automáticamente tras un TTL corto.
• Failed: Fallo confirmado. Tooltip: “Error al copiar” más una pista. Proporciona fallback: “Selecciona y copia” o “Pulsa Ctrl/Cmd+C”.

Sí, explícitamente pido un estado fallido. Los equipos se lo saltan porque se siente negativo. Los usuarios ya saben que falló porque su pegado está vacío o es incorrecto. La única pregunta es si tu UI les ayuda a recuperarse.

Temporización que se siente rápida sin ser falsa

Las escrituras al portapapeles suelen resolverse rápido, pero no instantáneamente en todas las plataformas. La temporización de tu estado debe cumplir tres objetivos:

1. Prevenir doble copia en los primeros 200–400 ms después del click (deshabilitar o debouncing).
2. Mantener “Copiado” visible el tiempo suficiente para que se perciba (alrededor de 800–1500 ms es típico).
3. Restablecer a idle para que el botón siga siendo útil (2–5 segundos, según contexto).

Ese TTL debe ser consistente en toda la app. Nada socava más la confianza que un “Copiado” que se queda para siempre y otro que desaparece antes de que el usuario parpadee.

No sobreajustes la máquina de estados

Puedes añadir estados de “hover”, “pressed” y “cooldown”. También puedes perderte en ellos. Manténlo simple hasta que tengas una razón real. Como compromiso práctico:

• Idle y hover son visuales, no lógicos (CSS los maneja).
• Copying/Copied/Failed son lógicos (JS/React/Vue los maneja).
• Cooldown es opcional; a menudo sólo deshabilitar durante copying es suficiente.

Cómo decidir qué significa “éxito”

Éxito significa una de las siguientes:

• API moderna: navigator.clipboard.writeText() se resuelve sin lanzar excepción.
• Fallback: Un método legacy de copia devuelve una señal positiva (document.execCommand('copy') devuelve true), y no detectaste inmediatamente desajuste.

Aún así, ten cuidado. Una promesa resuelta no garantiza que el portapapeles del SO contenga exactamente lo que piensas (algunos entornos sanitizan). Pero es la mejor señal disponible, y es mucho mejor que mostrar “Copiado” a ciegas al hacer click.

Cuándo usar un tooltip vs cambiar la etiqueta

Los tooltips son excelentes para “qué pasará si hago click”. Son mediocres para “qué acaba de pasar”, especialmente en móvil donde el hover es imaginario. Mi predeterminación es:

• Escritorio: el icono cambia + tooltip corto (“Copiado”).
• Móvil: el icono cambia + texto inline breve debajo del campo (“Copiado”).
• En cualquier lugar: añade un anuncio con aria-live para que los lectores de pantalla reciban la retroalimentación.

Tooltips vs toasts vs texto inline: elige tu canal de retroalimentación

Tienes tres canales principales de retroalimentación. Cada uno tiene modos de fallo. Elige deliberadamente.

Tooltips: buenos para la intención, aceptables para confirmación, malos para accesibilidad por defecto

Los tooltips son baratos y familiares. También suelen implementarse de forma que:

• No se muestran en dispositivos táctiles.
• No se anuncian a lectores de pantalla.
• Desaparecen cuando el foco se mueve (lo que a menudo desencadena la copia).

Si usas tooltips para confirmación, anclalos al botón y asegúrate de que se muestren en foco además de hover. Mejor: haz que el contenido del tooltip refleje el estado (“Copiar” → “Copiado” → “Copiar”) y gánalo desde tu máquina de estados.

Toasts: geniales para confirmación global, fáciles de sobreusar

Los toasts funcionan cuando la acción de copia tiene significado a nivel del sistema (copiar un token API, cadena de conexión, códigos de recuperación). También generan ruido si los muestras para cada copia pequeña en una tabla.

Guía práctica:

• Usa toasts cuando el usuario probablemente navegará fuera y aún necesitará la confirmación.
• Evita toasts en UIs densas donde los usuarios copian repetidamente (líneas de logs, nombres de métricas, nombres de pods).

Texto inline: aburrido, fiable y sorprendentemente infravalorado

El “Copiado” inline junto al contenido copiado es lo menos ingenioso y lo más dependible. Sobrevive en móvil, sobrevive a cambios de foco y es lo más fácil de hacer accesible con aria-live.

Si tienes espacio, úsalo. Sí, es menos “limpio”. También lo es una interrupción. Escoge estética en consecuencia.

Un híbrido que funciona en productos reales

• El icono del botón cambia (portapapeles → check) durante 1,5s.
• El texto del tooltip cambia a “Copiado” en escritorio.
• Texto inline opcional para diseños móviles o secretos importantes.
• Anuncio para lectores de pantalla usando aria-live="polite".

Microcopy que no gaslight a los usuarios

El microcopy no es decoración. Es respuesta a incidentes para humanos. “Copiado” es una afirmación. Hazla precisa y útil.

Cadenas recomendadas

• Tooltip/etiqueta en idle: “Copiar”
• Copying: “Copiando…” (opcional; también puedes deshabilitar con un spinner)
• Copied: “Copiado”
• Failed: “Error al copiar”
• Pista de fallo (contextual): “Pulsa Ctrl+C” / “Pulsa Cmd+C” / “Selecciona y copia”

Qué evitar

• “¡Copiado!” antes de que la escritura termine. Eso es mentir con entusiasmo.
• Texto demasiado ingenioso. Las personas que copian credenciales no están en un estado de ánimo caprichoso.
• Explicaciones largas dentro de tooltips. Los tooltips no son manuales.
• Fallo silencioso. Si falló, dilo y ofrece un fallback.

Secretos y enmascaramiento: copia lo que el usuario espera

Si la UI muestra “••••••••” pero el botón copia el token real, díselo al usuario. De lo contrario creas una brecha de confianza: los usuarios asumen que copiaste los puntos y pegarán basura. Es un choque común entre seguridad y UX. Resuélvelo con texto explícito:

• Etiqueta del botón: “Copiar token” en lugar de “Copiar”.
• Tras el éxito: “Token copiado” (no solo “Copiado”).
• Opcional: nota corta junto al campo: “Token oculto; al copiar se copia el valor completo.”

Accesibilidad: no hagas invisible el “copiado”

La accesibilidad no es una casilla. Es si tu UI funciona cuando el usuario no puede o no usa hover, un ratón o una atención perfecta. Los botones de portapapeles son una trampa clásica de accesibilidad porque la retroalimentación suele ser puramente visual.

Comportamiento con teclado

• El botón debe ser alcanzable con Tab.
• Enter/Espacio deben disparar la copia.
• El foco debe permanecer estable después de la copia. No robes el foco a menos que tengas una muy buena razón.

Anuncios para lectores de pantalla

Los tooltips no se anuncian de forma fiable. Usa una región con aria-live para anunciar cambios de estado:

• aria-live="polite" para “Copiado”.
• aria-live="assertive" para “Error al copiar” si bloquea el flujo del usuario.

Los cambios de color e icono no bastan

Cambiar el icono de portapapeles a una marca está bien, pero no te fíes solo de eso. Proporciona texto que pueda leerse y anunciarse. También asegúrate del contraste: una marca verde pálida que se pierde sobre fondo blanco es decorativa, no funcional.

Múltiples botones de copia en una lista

Tablas de valores (nombres de pods, IDs, hashes) suelen tener muchos botones de copia. Fallos comunes de accesibilidad:

• Todos los botones tienen nombres accesibles idénticos (“Copiar”), lo que hace la navegación con lector de pantalla dolorosa.
• Los cambios de estado se anuncian sin contexto (“Copiado”), dejando al usuario inseguro sobre qué valor se copió.

Solución: haz la etiqueta contextual (“Copiar nombre de pod”, “Copiar ID de consulta”), y limita el anuncio live a la fila o incluye contexto en el mensaje (“ID de consulta copiado”).

Seguridad y permisos: el portapapeles no es territorio libre

El portapapeles es sensible. Los navegadores lo tratan así. Por eso tu implementación debe respetar requisitos de gesto del usuario y contextos seguros, y por eso ciertos entornos bloquean el acceso al portapapeles por completo.

Restricciones clave con las que debes diseñar

• Contexto seguro: Muchas APIs del portapapeles requieren HTTPS o localhost.
• Gesto del usuario: Debe ser desencadenado por una acción directa (click/tap/tecla).
• Restricciones de iframe: Sandbox y políticas de permisos pueden bloquear escrituras al portapapeles.
• Políticas empresariales: Algunos navegadores administrados restringen el acceso o lo sanitizan.

No filtre secretos al portapapeles casualmente

Si copias secretos (tokens, contraseñas, códigos de recuperación), considera añadir:

• Una advertencia corta: “Copiado al portapapeles (el portapapeles puede ser legible por otras apps).”
• UX opcional de “caducidad de copia” (no mediante borrar el portapapeles —lo que no puedes hacer de forma fiable— sino recordando al usuario).
• Registro de auditoría para acciones de alto riesgo (depende de tu modelo de amenazas).

Broma #2: Si tu revisión de seguridad dice “el portapapeles es un vector de exfiltración de datos,” no están equivocados—solo llegaron temprano a la fiesta.

Hechos e historia útiles en revisiones de diseño

Algo de contexto ayuda cuando discutes “por qué este pequeño botón necesita ingeniería real”. Estos son hechos cortos y concretos que suelen cortar el bikeshedding.

1. El acceso al portapapeles solía ser mayormente hacks web. Los primeros patrones dependían de Flash o textareas ocultas y trucos de selección porque no había una API estándar limpia.
2. document.execCommand('copy') nunca fue una gran API. Es históricamente común, pero es síncrona, delicada y depende de selección/foco que varía por navegador.
3. La API moderna del portapapeles es basada en promesas. Ese cambio importa: puedes modelar “copiando” como una operación async y mostrar progreso/estado honesto.
4. Los navegadores requieren intencionalmente un gesto del usuario para escrituras al portapapeles. Es un límite de seguridad para prevenir manipulaciones silenciosas o robo de datos.
5. HTTPS no es solo cifrado de transporte. Varias características de la plataforma web (incluido el acceso al portapapeles en muchos casos) están condicionadas a contextos seguros.
6. Los tooltips son históricamente centrados en el ratón. Las interfaces táctiles no tienen “hover”, lo que hace que la confirmación solo por tooltip sea poco fiable en una gran franja de dispositivos.
7. El portapapeles en móvil no es uniforme. iOS Safari y webviews embebidos han tenido períodos de comportamiento restringido o inconsistente en comparación con Chrome de escritorio.
8. Los navegadores administrados por empresas pueden cambiar las reglas. Las políticas pueden deshabilitar el acceso al portapapeles, especialmente para copy/paste entre apps o en contextos de escritorio remoto.
9. Los usuarios tratan “Copiado” como un recibo de transacción. En estudios de usabilidad, la retroalimentación de confirmación cambia el comportamiento repetido: la gente deja de verificar manualmente si confía en la UI.

Tres micro-historias corporativas desde las trincheras del portapapeles

Micro-historia 1: El incidente causado por una suposición incorrecta

El producto era una consola administrativa interna usada por ingenieros on-call. La consola tenía un botón “Copiar” junto a una cadena de conexión de base de datos generada. Tenía una animación elegante: al hacer click, el icono giraba a una marca, el tooltip decía “Copiado”. A todos les encantó. Nadie lo cuestionó.

Durante un incidente, un ingeniero copió la cadena de conexión, la pegó en un cliente SQL y obtuvo fallo de autenticación. Intentó de nuevo. Mismo resultado. Escaló al equipo de base de datos con la suposición de que las credenciales estaban mal. El equipo rotó credenciales y de repente múltiples servicios comenzaron a fallar porque los sistemas dependientes no se actualizaron en sincronía.

Tras el polvo, la causa raíz no fue la base de datos. El botón “Copiar” estaba copiando el valor enmascarado que la UI mostraba (con asteriscos), no el secreto real. El ingeniero pegó una cadena llena de asteriscos. La UI todavía dijo “Copiado”, porque la operación de copia en sí tuvo éxito—solo con la carga equivocada.

La solución fue dolorosamente simple: copiar el valor verdadero y cambiar la etiqueta a “Copiar cadena de conexión”. Añadir una nota de una línea: “Valor oculto; copiar copiará la cadena completa.” También añadir una prueba que pegue el contenido copiado y valide que coincide con el valor proporcionado por el backend. No fue sofisticado. Fue honesto.

La lección: la gente no depura tu UI durante un incidente. Asumen que la UI dice la verdad y suben la cadena hasta “arreglar” cosas caras. Si tu UI de portapapeles puede copiar un valor equivocado, necesita guardarraíles o etiquetado explícito.

Micro-historia 2: La optimización que salió mal

Un equipo quiso reducir la latencia percibida. Cambiaron el botón “Copiar” para mostrar “Copiado” inmediatamente al hacer click, y luego realizar la escritura al portapapeles de forma asíncrona. La idea era que la escritura casi siempre tiene éxito, y la retroalimentación instantánea se sentía más ágil. Producto adoró la demo.

Luego embebieron la app en un iframe en un portal usado por múltiples departamentos. En ese portal, el iframe estaba sandboxeado y las escrituras al portapapeles estaban bloqueadas. La escritura fallaba consistentemente, pero la UI siempre mostraba “Copiado”. Los usuarios empezaron a pegar contenido viejo del portapapeles en tickets y hojas de cálculo—IDs incorrectos, hostnames erróneos, a veces secretos obsoletos. Caos, pero del tipo silencioso: lento, distribuido y difícil de trazar.

El equipo vio un aumento de quejas por “mismatched data” pero no pudo reproducir en su entorno de desarrollo. Funcionaba localmente. Funcionaba en staging. Fallaba solo en el portal embebido donde los permisos eran distintos.

La solución fue revertir el cambio de “copiado optimista” e implementar un estado de fallo adecuado. Cuando la escritura fallaba, el tooltip decía “Error al copiar (restringido por el navegador)” y la UI revelaba el valor en un campo seleccionable para copia manual. También añadieron telemetría: conteos de éxito/fallo por contexto de embedding. La optimización “ágil” costó más tiempo del que ahorró.

Lección: la UI optimista está bien cuando el usuario puede recuperarse fácilmente y el impacto es bajo. Las acciones de portapapeles suelen tener alto impacto y poca visibilidad. No finjas certeza.

Micro-historia 3: La práctica aburrida pero correcta que salvó el día

Otra organización tenía una plataforma interna con docenas de botones de copia: nombres de servicio, ARNs, tags de imagen, comandos curl y tokens. El UX era consistente pero poco llamativo: hacer click copia, el icono cambia, aparece un pequeño “Copiado” inline y un mensaje en aria-live anuncia el éxito. También había una ruta “Error al copiar” que ofrecía instrucciones de “Selecciona y copia”.

Lo que la hizo resistente no fueron los visuales. Fue la práctica: trataban la tasa de éxito del portapapeles como una métrica. No una métrica de vanidad—una operativa. Rastreaban intentos de copia, éxitos, fallos y el entorno (familia de navegador, embebido vs top-level, contexto seguro, etc.).

Una semana notaron fallos del portapapeles en un subconjunto de usuarios. Resultó que una actualización del navegador corporativo endureció permisos del portapapeles para apps embebidas en un portal. Como ya tenían el estado “failed” y el fallback, los usuarios no quedaron bloqueados. Y porque tenían telemetría, el equipo de plataforma lo vio en horas y pudo coordinar un cambio de configuración en el portal.

El incidente nunca llegó a ser incidente. Fue un bache, un ticket y un pequeño postmortem. Así es como se ve lo “aburrido pero correcto”: no evitar cada fallo, sino construir el sistema para que los fallos sean detectables y sobrevivibles.

Guía rápida de diagnóstico

Esta es la guía “deja de discutir en Slack y encuentra el cuello de botella”. Úsala cuando usuarios digan “no funciona la copia” o cuando tu telemetría muestre aumento de fallos del portapapeles.

Primero: confirma qué significa “no funciona”

1. ¿Se dispara el evento click? Si no, tienes un problema de wiring de UI (overlay deshabilitado, pointer-events, z-index, manejador de eventos no enlazado).
2. ¿Se intenta la escritura al portapapeles? Si no, tienes lógica que la bloquea (requisito de gesto del usuario violado, promesa no llamada, retorno temprano).
3. ¿Se rechaza la escritura? Si sí, mira permisos, contexto seguro, políticas de iframe.
4. ¿Se copió contenido equivocado? Si sí, revisa enmascaramiento, formateo o cierres de estado obsoletos.

Segundo: identifica el contexto de ejecución

1. Top-level vs iframe: ¿La app está embebida? ¿Tiene atributo sandbox? ¿Están las políticas de permisos configuradas?
2. Contexto seguro: ¿HTTPS vs HTTP? (Localhost es especial; staging no siempre lo es.)
3. Familia de navegador: Safari vs Chrome vs Firefox se comportan distinto, especialmente en móvil.
4. Entorno gestionado por empresa: VDI, escritorio remoto, políticas de Chrome gestionado pueden cambiar el comportamiento.

Tercero: verifica transiciones de estado y afirmaciones de la UI

1. ¿Muestra la UI “Copiado” sólo tras el éxito? Si no, arregla la máquina de estados primero.
2. ¿Se restablece “Copiado”? Un estado “Copiado” pegajoso oculta fallos repetidos.
3. ¿Se manejan los doble clicks? Clicks rápidos pueden competir con la UI y producir confirmaciones falsas.

Cuarto: revisa la observabilidad

1. ¿Registras intentos y resultados de copia? Si no, debuggearás a ciegas.
2. ¿Puedes segmentar por entorno? Embebido vs no embebido, navegador, plataforma, contexto seguro.

Tareas prácticas: comandos, salidas y decisiones (12+)

Estas son tareas reales que puedes ejecutar como parte de una investigación de fiabilidad de UI. Están sesgadas hacia lo que un SRE o ingeniero de plataforma puede hacer rápido: confirmar entorno, reproducir, capturar evidencia y decidir qué cambiar.

Tarea 1: Comprueba si la página se sirve por HTTPS

cr0x@server:~$ curl -I https://app.example.internal
HTTP/2 200
content-type: text/html; charset=utf-8
strict-transport-security: max-age=31536000; includeSubDomains

Qué significa la salida: Estás en un contexto seguro y HSTS está presente. Las APIs del portapapeles son más propensas a permitirse.

Decisión: Si ves HTTP o redirecciones a HTTP, arregla tu ingress/load balancer o las reglas de redirección canónica. No depures el comportamiento del portapapeles en un origen inseguro esperando consistencia.

Tarea 2: Confirma si un portal embebido añade sandbox al iframe

cr0x@server:~$ curl -s https://portal.example.internal/page | grep -n "iframe" | head
42:  <iframe src="https://app.example.internal" sandbox="allow-scripts allow-forms"></iframe>

Qué significa la salida: El iframe está sandboxeado sin permisos explicitos para el portapapeles. Muchas operaciones de portapapeles fallarán.

Decisión: Coordina con el propietario del portal para ajustar sandbox/policy de permisos (o rediseña con un fallback). Tu app no puede anular de forma fiable las restricciones del iframe desde dentro.

Tarea 3: Verifica las cabeceras Content Security Policy y Permissions Policy

cr0x@server:~$ curl -I https://app.example.internal | egrep -i "content-security-policy|permissions-policy"
content-security-policy: default-src 'self'; script-src 'self'
permissions-policy: clipboard-write=(self), clipboard-read=()

Qué significa la salida: La escritura al portapapeles está permitida para self en contexto top-level; la lectura está deshabilitada (a menudo está bien).

Decisión: Si clipboard-write falta o está en none, arregla las cabeceras. Si estás embebido, puede que necesites incluir el origen embebedor, según el diseño de tu política.

Tarea 4: Reproduce en Chromium headless y captura logs de consola

cr0x@server:~$ chromium-browser --headless --disable-gpu --dump-dom https://app.example.internal 2>&1 | tail -n 5
[12345:12345:ERROR:ssl_client_socket_impl.cc(960)] handshake failed; returned -1, SSL error code 1, net_error -202

Qué significa la salida: El entorno no puede negociar TLS (o está usando un certificado no confiable). Depurar el portapapeles no tiene sentido hasta que el acceso básico funcione.

Decisión: Arregla la cadena de certificados/ confianza en el entorno de pruebas, o usa un dominio de staging confiable. No pierdas tiempo en comportamiento de UI cuando el navegador ni siquiera carga la página bien.

Tarea 5: Inspecciona validez del certificado (falla común en staging)

cr0x@server:~$ echo | openssl s_client -connect app.example.internal:443 -servername app.example.internal 2>/dev/null | openssl x509 -noout -issuer -subject -dates
issuer=CN = Example Internal CA
subject=CN = app.example.internal
notBefore=Nov 10 00:00:00 2025 GMT
notAfter=Nov 10 00:00:00 2026 GMT

Qué significa la salida: El certificado está actualmente válido. Los problemas de contexto seguro probablemente no se deban a expiración del certificado.

Decisión: Si las fechas están expiradas/no válidas aún, arregla la rotación de certificados. TLS roto a menudo se traduce en restricciones de “contexto seguro” y fallos de portapapeles confusos.

Tarea 6: Confirma que el backend devuelve el valor completo (evita copiar datos enmascarados)

cr0x@server:~$ curl -s -H "Authorization: Bearer REDACTED" https://app.example.internal/api/token | jq .
{
  "display": "****-****-****",
  "value": "a1b2c3d4-e5f6-7890-abcd-ef0123456789"
}

Qué significa la salida: El backend provee tanto la visualización enmascarada como el valor completo. La UI debe usar value para copiar.

Decisión: Si la API sólo devuelve datos enmascarados, no puedes copiar el secreto real. Cambia el contrato de la API o cambia la UX (p. ej., muestra un paso de revelar antes de copiar).

Tarea 7: Comprueba si un deploy reciente cambió el componente de copia

cr0x@server:~$ git log -n 5 --oneline -- apps/web/src/components/CopyButton.tsx
a3f19c2 copy button: optimistic copied state to reduce perceived latency
b91c2de refactor tooltip positioning for portals
0c7de10 add aria-live region for copy feedback

Qué significa la salida: Hay un cambio de “copiado optimista”. Es un sospechoso principal para falsos positivos.

Decisión: Revertir o hotfix para mostrar “Copiado” sólo después de que la escritura al portapapeles se resuelva. Si mantienes la optimización, debes reconciliar fallos y revertir el estado de la UI cuando fallan.

Tarea 8: Verifica que la acción de copia esté ligada a un gesto del usuario (flujo de auditoría)

cr0x@server:~$ rg -n "writeText|execCommand\\('copy'\\)" apps/web/src | head -n 10
apps/web/src/components/CopyButton.tsx:41: await navigator.clipboard.writeText(text)
apps/web/src/pages/Keys.tsx:88: setTimeout(() => copyKey(keyId), 0)

Qué significa la salida: Un setTimeout envuelve la llamada de copia. Eso puede romper los requisitos de gesto del usuario en algunos navegadores.

Decisión: Elimina la invocación demorada. Dispara la escritura al portapapeles directamente dentro del manejador de click. Si necesitas hacer trabajo antes, hazlo antes de habilitar el botón.

Tarea 9: Valida que la UI no se desmonta antes de que la promesa se resuelva

cr0x@server:~$ rg -n "setCopied\\(|setState\\(|unmount|navigate\\(" apps/web/src/components/CopyButton.tsx
62: setCopied(true)
65: setTimeout(() => setCopied(false), 2000)

Qué significa la salida: Hay un reinicio de estado demorado. Si el componente se desmonta, esto puede lanzar warnings o fallar silenciosamente, dejando UI obsoleta en otro lugar.

Decisión: Asegura que los timers se limpien en el unmount y que las actualizaciones de estado estén protegidas. También evita navegación desencadenada por copia a menos que sea intencionada.

Tarea 10: Confirma que hay telemetría para éxito vs fallo

cr0x@server:~$ rg -n "clipboard|copy_attempt|copy_success|copy_failure" apps/web/src | head -n 20
apps/web/src/telemetry/events.ts:14: export const copyAttempt = ...
apps/web/src/components/CopyButton.tsx:49: telemetry.copyAttempt({ kind: "token" })
apps/web/src/components/CopyButton.tsx:53: telemetry.copySuccess({ kind: "token" })
apps/web/src/components/CopyButton.tsx:57: telemetry.copyFailure({ kind: "token", reason })

Qué significa la salida: Puedes cuantificar la fiabilidad. Bien. Ahora puedes dejar de adivinar.

Decisión: Si falta telemetría, añádela antes de intentar “optimizar”. Si no, estarás “mejorando” algo que no puedes medir.

Tarea 11: Inspecciona la configuración del proxy inverso para cabeceras que afectan embedding y permisos

cr0x@server:~$ sudo nginx -T 2>/dev/null | egrep -n "permissions-policy|content-security-policy|x-frame-options" | head -n 30
120: add_header Permissions-Policy "clipboard-write=(self)" always;
121: add_header X-Frame-Options "SAMEORIGIN" always;

Qué significa la salida: La app prohíbe embedding cross-origin vía X-Frame-Options. Si los usuarios reportan fallos solo en un portal embebido, podrían estar viendo un flujo alternativo o una versión antigua.

Decisión: Alinea tu estrategia de embedding: o soportas embebido intencionalmente (y configuras políticas) o lo bloqueas claramente. El soporte a medias crea fallos extraños y tickets de soporte más extraños.

Tarea 12: Confirma que tu build no está eliminando async/await o polyfills incorrectamente

cr0x@server:~$ jq '.browserslist, .dependencies["core-js"]' apps/web/package.json
[
  ">0.2%",
  "not dead",
  "not op_mini all"
]
"3.39.0"

Qué significa la salida: Tienes un target moderno y core-js disponible. Aun así, el comportamiento del portapapeles es mayormente política de tiempo de ejecución, no transpile.

Decisión: Si apuntas a navegadores muy antiguos, debes implementar fallbacks y probarlos. Si no los soportas, sé explícito en la política de soporte y en la mensajería de la UI.

Tarea 13: Revisa logs de errores cliente alrededor de fallos del portapapeles (colección server-side)

cr0x@server:~$ sudo journalctl -u frontend-logs -S "1 hour ago" | egrep -i "clipboard|notallowederror|securityerror" | tail -n 20
Dec 29 10:22:18 loghost frontend-logs[902]: NotAllowedError: Write permission denied.
Dec 29 10:22:19 loghost frontend-logs[902]: SecurityError: Clipboard API not available.

Qué significa la salida: Estás viendo fallos explícitos de permisos. Esto no es “error del usuario.” Es entorno/política.

Decisión: Implementa mensajería clara de estado fallido y fallback, luego trabaja con seguridad/IT/propietarios del portal para ajustar políticas si procede.

Tarea 14: Verifica que las cadenas copiadas no contengan espacios o líneas ocultas

cr0x@server:~$ printf 'token=%s\n' "abc123 " | cat -A
token=abc123 $

Qué significa la salida: El $ indica un espacio final antes del salto de línea. Si copias/pegas eso en headers de autenticación, puedes obtener fallos enloquecedores.

Decisión: Normaliza el contenido copiado (trim de espacios finales) salvo que el espacio sea semánticamente significativo (raro para IDs, común para bloques de código). Si lo es, advierte a los usuarios y preserva consistentemente.

Errores comunes (síntomas → causa raíz → solución)

1) Síntoma: La UI dice “Copiado” pero el pegado no cambia

Causa raíz: “Copiado” optimista mostrado al hacer click; la escritura al portapapeles falló por permisos/requisito de gesto del usuario.

Solución: Muestra “Copiado” sólo después de que la promesa se resuelva. Añade un estado fallido que ofrezca instrucciones de copia manual. Rastrea telemetría de éxito/fallo.

2) Síntoma: Funciona en la app top-level, falla en el portal embebido

Causa raíz: Sandbox del iframe o Permissions Policy bloquea escrituras al portapapeles.

Solución: Negocia atributos/política del iframe con el propietario del portal, o detecta modo embebido y cambia a un fallback con campo seleccionable. No finjas que se copió.

3) Síntoma: Funciona en escritorio, no en móvil

Causa raíz: Confirmación sólo por tooltip; hover no existe. O fallback basado en selección falla por teclado virtual/foco.

Solución: Usa cambio de icono + retroalimentación inline. Prefiere navigator.clipboard.writeText cuando esté disponible; proporciona un fallback probado en móvil que no dependa de gimnasias de selección complejas.

4) Síntoma: Copia el valor equivocado (enmascarado, truncado, localizado)

Causa raíz: La copia usa el texto renderizado (enmascarado) en lugar del valor subyacente; o copia una cadena formateada de presentación.

Solución: Copia desde el valor canónico en crudo. Si se necesita formateo para bloques de código, hazlo explícito y prueba el pegado de ida y vuelta.

5) Síntoma: El estado “Copiado” se queda pegado para siempre en algunas pantallas

Causa raíz: Timer no reiniciado, desajuste de re-render, o estado obsoleto por bugs de memoización.

Solución: Centraliza la máquina de estados. Limpia timers en unmount. Usa un TTL determinista y mantenlo consistente entre rutas/componentes.

6) Síntoma: Doble click produce estados mixtos o múltiples toasts

Causa raíz: No hay debounce/deshabilitado durante copia; carreras de promesas donde una resolución anterior llega después.

Solución: Deshabilita durante copying, o usa un “id de intento” monotónico y acepta sólo la finalización más reciente.

7) Síntoma: Usuarios de lectores de pantalla no reciben confirmación

Causa raíz: La retroalimentación es solo visual (tooltip/icono). No hay región live ni cambios en el nombre accesible.

Solución: Añade anuncios con aria-live; asegura que el nombre accesible del botón incluya contexto; no confíes en hover.

8) Síntoma: Copia funciona en dev, falla en staging/producción

Causa raíz: Diferencias de contexto seguro, cabeceras CSP/Permissions Policy distintas, o embedding en portal que sólo existe en producción.

Solución: Haz que staging coincida con producción en cabeceras y escenarios de embedding. Añade marcadores de entorno en telemetría para correlacionar fallos.

Listas de verificación / plan paso a paso

Paso a paso: implementar un botón de copia que merezca confianza

1. Define qué copias. Usa un valor canónico en crudo. Si muestras un valor enmascarado, etiqueta la acción de copia específicamente (“Copiar token”).
2. Implementa una máquina de estados. Idle → Copying → (Copied|Failed) → Idle. No se requieren otros estados para lanzar.
3. Vincula la copia a un gesto directo del usuario. No timers retrasados, no copia en background, no “copiar al render”.
4. Usa la API moderna del portapapeles cuando esté disponible. Fallback cuidadoso cuando no lo esté.
5. Deshabilita o debounce durante Copying. Previene dobles disparos y condiciones de carrera.
6. Confirma el éxito antes de afirmarlo. La UI no debe mostrar “Copiado” hasta conocer el éxito.
7. Ofrece camino de recuperación en fallo. Proporciona UI de “seleccionar y copiar” o guía de atajos de teclado.
8. Elige el canal de retroalimentación según contexto. Tooltip para intención en escritorio, inline para fiabilidad en móvil/datos importantes, toast para acciones de alto riesgo.
9. Hazlo accesible. Operabilidad por teclado, nombres accesibles contextuales, anuncios con aria-live.
10. Instrumenta resultados. Emite intentos/éxitos/fallos y segmenta por navegador/embedding/contexto seguro.
11. Prueba en contextos feos. Iframes embebidos, mobile Safari, navegadores gestionados si tienes usuarios empresariales.
12. Estandariza en la app. Un componente, un conjunto de cadenas, una política de temporización. La consistencia es fiabilidad.

Checklist: validación pre-lanzamiento en un entorno similar a producción

• La página carga por HTTPS con cadena de certificados válida.
• Permissions Policy permite explícitamente clipboard-write donde se pretende.
• Modo embebido probado (si aplica) con los atributos reales del portal/iframe.
• Éxito y fallo de copia observados en telemetría.
• Fallback manual verificado (seleccionar texto, guía de atajos).
• Confirmación con lector de pantalla verificada (al menos un lector mayor en una plataforma).
• Comportamiento móvil verificado (al menos iOS Safari y Android Chrome si los soportas).
• Comportamiento de copiado de secretos comunicado explícitamente y coincide con las expectativas del usuario.

Checklist: qué hacer cuando producto pide “copiado instantáneo”

• Pregunta: ¿qué tasa de fallo estamos dispuestos a reportar como éxito?
• Ofrece: muestra inmediatamente “Copiando…” (no “Copiado”), luego “Copiado” al confirmar éxito.
• Requiere: un estado fallido y un camino de recuperación antes de hacer shipping de cualquier confirmación optimista.
• Mide: compara latencia intento→éxito antes y después. Si ya es <50ms, tu “optimización” es teatro.

Preguntas frecuentes

1) ¿Debe “Copiado” ser un tooltip o un toast?

Si es una acción frecuente en una UI densa, usa cambio de icono + tooltip en escritorio y evita toasts. Si es una copia de alto riesgo (token, cadena de conexión), un toast o confirmación inline está justificado.

2) ¿Cuánto debe durar el estado “Copiado”?

Suficiente para percibirse, lo bastante corto para seguir siendo útil: típicamente 1–2 segundos para el indicador “Copiado”, luego restablecer a idle en 2–5 segundos. Estandarízalo.

3) ¿Por qué no podemos copiar siempre al cargar la página (como auto-copiar un enlace de invitación)?

Los navegadores requieren un gesto del usuario para escrituras al portapapeles para prevenir abuso. El auto-copiar sin interacción está bloqueado intencionalmente en muchos entornos.

4) ¿Necesitamos un estado “Copiando…”? El portapapeles es rápido.

Necesitas un estado lógico de copying incluso si no lo muestras. Es cómo deshabilitas el botón, evitas carreras por doble click y evitas afirmar éxito antes de tiempo.

5) ¿Cuál es el mejor fallback cuando la API del portapapeles no está disponible?

Usa un campo seleccionable con el valor y enseña “Pulsa Ctrl+C / Cmd+C” si la copia programática falla. Los hacks de selección pueden funcionar, pero son frágiles—especialmente en móvil y en contextos embebidos.

6) ¿Por qué funciona en Chrome pero no en Safari?

Las políticas y detalles de implementación del portapapeles difieren. Safari y webviews iOS han sido históricamente más estrictos sobre gestos y foco. Prueba en los navegadores que tus usuarios realmente usan, no en los que tu equipo prefiere.

7) ¿Cómo evitamos copiar el valor enmascarado para secretos?

No copies desde el texto renderizado. Copia desde un valor canónico en estado (o recupéralo bajo demanda). Haz la etiqueta del botón explícita (“Copiar token”) para que los usuarios sepan que obtendrán el valor completo.

8) ¿Está bien limpiar el portapapeles después de copiar un secreto?

No de manera fiable. Los navegadores generalmente no permiten borrar o sobrescribir el portapapeles más tarde sin otro gesto del usuario, y el comportamiento del SO varía. Mejor advertir a los usuarios y evitar copiar secretos innecesariamente.

9) Tenemos 30 botones de copia en una tabla. ¿Cómo mantener la UX razonable?

Usa un componente compartido, etiquetas contextuales (“Copiar ID de solicitud”), y evita toasts globales. Considera una confirmación sutil por fila y mantén los anuncios acotados para que los lectores de pantalla no se vuelvan una ruleta.

10) ¿Qué debemos registrar para la telemetría del portapapeles?

Intento, éxito, razón de fallo (nombre/mensaje de excepción sanitizado), entorno (familia de navegador, embebido vs top-level, contexto seguro) y el “tipo” de valor copiado (token vs id vs comando). Nunca registres el contenido copiado.

Conclusión: próximos pasos que realmente se entregan

Si tu botón de copia actualmente dice “Copiado” al hacer click, cámbialo. Hoy. Haz que espere el éxito y dale un estado de fallo con un fallback. Eso por sí solo eliminará toda una clase de dolor invisible para el usuario.

Luego haz las partes aburridas que mantienen los sistemas de producción estables:

• Estandariza una máquina de estados en la app (idle/copying/copied/failed).
• Elige canales de retroalimentación por contexto: tooltip para intención en escritorio, inline para fiabilidad, toast para acciones de alto riesgo.
• Hazlo accesible con etiquetas contextuales y anuncios aria-live.
• Instrumenta resultados de copia para ver fallos por navegador/contexto de embedding antes de que lo haga tu cola de soporte.
• Prueba en los lugares donde vive la realidad: iframes, mobile Safari, navegadores gestionados y casos límite de “contexto seguro”.

Publicar un botón de “copiar al portapapeles” confiable no es glamoroso. Por eso es una ventaja competitiva. La UI que no miente es la UI que los usuarios dejan de pensar—y ese es el mayor cumplido que recibe el software en producción.