useClipboard Hook - Guida Utilizzo

⚠️ [DEV-166] Documentazione obsoleta. L'API copy(text, context?) descritta in questo file non è più disponibile. Consultare lo Storybook di @elerama/ui → sezione Hooks/useClipboard per la documentazione aggiornata. Vedere README.md per i dettagli della migrazione.

---

📋 Descrizione (storica)

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

if (success) { // Notificare all'iframe che la copia è riuscita notifyClipboardSuccess(); } else { // Mostrare errore all'utente showError("Impossibile copiare negli appunti"); } }

## 🔍 Debug e Logging

La funzione registra automaticamente nel console:

[useTopbarCart] ✅ Testo copiato negli appunti (Clipboard API) [useTopbarCart] ⚠️ Clipboard API error: ... Trying legacy method... [useTopbarCart] ✅ Testo copiato negli appunti (legacy method) [useTopbarCart] ❌ Errore metodo legacy: ...

## 🧩 Componenti che Usano

- `useTopbarCart.ts` - Hook per il carrello della topbar
- `test-iframe.html` - Pagina di test iframe

## 💡 Note Tecniche

### Fallback Legacy (execCommand)

Il fallback utilizza `document.execCommand('copy')` che:
- ✅ Funziona in HTTP (non secure)
- ✅ Funziona in iframe cross-origin (con restrizioni)
- ⚠️ È deprecato ma ampiamente supportato
- ⚠️ Potrebbe non funzionare in alcuni browser ultra-moderni

### Permessi Richiesti

La Clipboard API richiede:
- HTTPS (in ambienti di produzione)
- Permesso dell'utente (mostrato dal browser al primo utilizzo)
- Stesso origin (non cross-domain)

Il fallback **non** richiede permessi espliciti.

## 🐛 Troubleshooting

### Errore: "navigator.clipboard is undefined"
→ La Clipboard API non è disponibile, ma il fallback legacy funzionerà automaticamente

### Errore: "Failed to copy text with legacy method"
→ Il browser potrebbe non supportare `execCommand('copy')`. Verifica che:
- Il testo è valido (non null/undefined)
- Il browser è supportato (IE 9+)
- Non stai operando in un worker thread

### Errore: "Clipboard is not available"
→ Potresti avere CORS issues. Il fallback dovrebbe funzionare comunque.

## 📚 Riferimenti

- [MDN - Clipboard API](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API)
- [MDN - document.execCommand](https://developer.mozilla.org/en-US/docs/Web/API/Document/execCommand)