useClipboard Hook - Guida Utilizzo

📋 Descrizione

useClipboard() è un hook React per copiare testo negli appunti con feedback visivo automatico e gestione dello stato.

File: app/hooks/useClipboard.ts

🎯 Caratteristiche

✅ Hook React nativo - Integrazione perfetta con React components ✅ Stato automatico - Gestisce copied, error automaticamente ✅ Auto-reset - Resetta lo stato dopo timeout configurabile ✅ Clipboard API moderna - HTTPS ready ✅ Fallback automatico - Supporta HTTP e browser vecchi ✅ Error handling - Gestione completa degli errori ✅ TypeScript - Full type safety

🚀 Utilizzo Base

Componente Simple

import { useClipboard } from "@/hooks/utils/useClipboard";

export function CopyButton() {
  const { copy, copied } = useClipboard();

  const handleCopy = async () => {
    await copy("Testo da copiare", "CopyButton");
  };

  return (
    <button onClick={handleCopy}>
      {copied ? "✅ Copiato!" : "📋 Copia"}
    </button>
  );
}

Con Error Handling

import { useClipboard } from "@/hooks/utils/useClipboard";

export function AdvancedCopy() {
  const { copy, copied, error } = useClipboard(3000); // 3 secondi di timeout

  const handleCopy = async () => {
    const success = await copy("Testo", "AdvancedCopy");
    if (!success && error) {
      alert(`Errore: ${error}`);
    }
  };

  return (
    <div>
      <button onClick={handleCopy}>Copia</button>
      {copied && <span>✅ Copiato negli appunti!</span>}
      {error && <span style={{color: 'red'}}>❌ {error}</span>}
    </div>
  );
}

📚 Signature Hook

export function useClipboard(resetTimeMs = 2000) {
  // resetTimeMs: tempo (ms) prima di resettare lo stato 'copied'
  // Default: 2000ms (2 secondi)

  return {
    copy,      // (text: string, context?: string) => Promise<boolean>
    copied,    // boolean - true se il testo è stato copiato
    error      // string | null - messaggio di errore (se presente)
  };
}

Parametri

Parametro	Tipo	Default	Descrizione
resetTimeMs	number	2000	Millisecondi prima di resettare copied a false

Ritorno

Chiave	Tipo	Descrizione
copy(text, context?)	async function	Funzione per copiare testo
copied	boolean	true se ultimo copy è riuscito
error	string | null	Messaggio errore (se presente)

💡 Esempi Pratici

1. Badge con Feedback

export function CopyWithBadge() {
  const { copy, copied } = useClipboard();

  return (
    <button onClick={() => copy("Code123")}>
      📋 {copied ? "✅" : "Copy"}
    </button>
  );
}

2. Multi-Copy

export function MultiCopy() {
  const { copy, copied } = useClipboard(2000);

  return (
    <div>
      <button onClick={() => copy("Fastlabel", "fastlabel")}>
        Fastlabel {copied ? "✅" : ""}
      </button>
      <button onClick={() => copy("Offline", "offline")}>
        Offline {copied ? "✅" : ""}
      </button>
    </div>
  );
}

3. Con Loader

import { useState } from "react";
import { useClipboard } from "@/hooks/utils/useClipboard";

export function CopyWithLoader() {
  const { copy, copied, error } = useClipboard();
  const [loading, setLoading] = useState(false);

  const handleCopy = async () => {
    setLoading(true);
    await copy("Large text...", "loader");
    setLoading(false);
  };

  return (
    <button onClick={handleCopy} disabled={loading}>
      {loading ? "Copiando..." : copied ? "✅ Copiato" : "📋 Copia"}
    </button>
  );
}

4. Uso in Hook (useTopbarCart)

// Nel hook useTopbarCart
const { copy } = useClipboard();

const fastlabel = async () => {
  const fastlabelText = iframeWindow.fastlabel_response;
  const success = await copy(fastlabelText, "useTopbarCart");
  if (success) {
    notifySuccess();
  }
};

🔍 Debug e Logging

L'hook logga automaticamente nel console:

[useClipboard] ✅ Testo copiato negli appunti (Clipboard API)
[useClipboard] ⚠️ Clipboard API error: NotAllowedError
[useClipboard] ✅ Testo copiato negli appunti (legacy method)

🐛 Troubleshooting

"Errore: Impossibile copiare negli appunti"

Cause comuni:

• Mancanza di permessi clipboard (browser chiede primo accesso)
• Ambiente non-HTTPS senza fallback disponibile
• Browser non supportato (molto raro)

Soluzione:

const { copy, error } = useClipboard();

await copy("text");
if (error) {
  console.log(`Fallback usato: ${error}`);
}

Copy non funziona in iframe

Possibili cause:

• CORS policy
• Same-origin requirement

Test:

// Controlla se è iframe
console.log(window !== window.parent);

State non si resetta

Soluzione: Aumenta il timeout

const { copy, copied } = useClipboard(5000); // 5 secondi

📖 Riferimenti Tecnici

• MDN Clipboard API
• MDN execCommand
• React Hooks

---

Versione: 2.0.0 (Hook React) Ultima Aggiornamento: 2025-10-21