📋 Async Clipboard API 완벽 가이드: document.execCommand의 종말과 안전한 클립보드 제어

// ❌ 과거 우리가 작성했던 고통스러운 복사 로직
function legacyCopyText(text) {
  const textarea = document.createElement('textarea');
  textarea.value = text;
  textarea.style.position = 'fixed';
  textarea.style.left = '-9999px';
  textarea.style.top = '0';
  document.body.appendChild(textarea);
  
  textarea.focus();
  textarea.select();
  
  try {
    const successful = document.execCommand('copy');
    return successful;
  } catch (err) {
    return false;
  } finally {
    document.body.removeChild(textarea);
  }
}

// navigator.clipboard 인터페이스 핵심 메서드 4가지
navigator.clipboard.writeText(text); // 텍스트 쓰기 (Promise<void>)
navigator.clipboard.readText();      // 텍스트 읽기 (Promise<string>)
navigator.clipboard.write(items);    // ClipboardItem 목록 쓰기 (Promise<void>)
navigator.clipboard.read();         // ClipboardItem 목록 읽기 (Promise<ClipboardItems>)

async function handleCopyCode(codeString) {
  try {
    await navigator.clipboard.writeText(codeString);
    console.log('클립보드 복사 성공!');
  } catch (error) {
    console.error('클립보드 쓰기 실패:', error);
  }
}

async function handlePasteCode() {
  try {
    const text = await navigator.clipboard.readText();
    console.log('읽어온 클립보드 내용:', text);
    return text;
  } catch (error) {
    if (error.name === 'NotAllowedError') {
      console.warn('사용자가 클립보드 접근 권한을 거부했습니다.');
    } else {
      console.error('클립보드 읽기 에러:', error);
    }
    return null;
  }
}

async function copyRichSnippet() {
  const plainText = 'Hello Logic-Phantom! (https://logic-phantom.github.io)';
  const htmlContent = '<strong>Hello Logic-Phantom!</strong> <a href="https://logic-phantom.github.io">공식 블로그</a>';

  // 각 MIME 타입에 맞게 Blob 생성
  const textBlob = new Blob([plainText], { type: 'text/plain' });
  const htmlBlob = new Blob([htmlContent], { type: 'text/html' });

  // 하나의 ClipboardItem 안에 두 가지 표현(representation)을 동시에 담기
  const clipboardItem = new ClipboardItem({
    'text/plain': textBlob,
    'text/html': htmlBlob,
  });

  try {
    await navigator.clipboard.write([clipboardItem]);
    console.log('서식 텍스트와 플레인 텍스트가 동시에 복사되었습니다.');
  } catch (err) {
    console.error('리치 클립보드 쓰기 실패:', err);
  }
}

async function copyCanvasToClipboard(canvasElement) {
  return new Promise((resolve, reject) => {
    canvasElement.toBlob(async (blob) => {
      if (!blob) {
        return reject(new Error('Canvas toBlob 생성 실패'));
      }

      try {
        const item = new ClipboardItem({ [blob.type]: blob });
        await navigator.clipboard.write([item]);
        console.log('PNG 이미지가 성공적으로 클립보드에 복사되었습니다.');
        resolve();
      } catch (err) {
        reject(err);
      }
    }, 'image/png');
  });
}

async function pasteImageFromClipboard(targetImgElement) {
  try {
    const items = await navigator.clipboard.read();

    for (const item of items) {
      // PNG 이미지 타입이 포함되어 있는지 검사
      if (item.types.includes('image/png')) {
        const blob = await item.getType('image/png');
        const objectUrl = URL.createObjectURL(blob);
        
        targetImgElement.src = objectUrl;
        targetImgElement.onload = () => URL.revokeObjectURL(objectUrl);
        console.log('클립보드 이미지 렌더링 완료');
        return;
      }
    }
    console.warn('클립보드에 PNG 이미지가 없습니다.');
  } catch (err) {
    console.error('이미지 읽기 실패:', err);
  }
}

async function checkClipboardPermission() {
  if (!navigator.permissions) return 'unknown';

  try {
    // clipboard-read 또는 clipboard-write
    const permissionStatus = await navigator.permissions.query({
      name: 'clipboard-read',
    });
    
    console.log('현재 클립보드 읽기 권한:', permissionStatus.state); // 'granted' | 'denied' | 'prompt'
    
    permissionStatus.onchange = () => {
      console.log('권한 상태가 변경됨:', permissionStatus.state);
    };
    
    return permissionStatus.state;
  } catch (err) {
    // Firefox 등 일부 브라우저는 아직 clipboard-read 쿼리를 지원하지 않음
    return 'unsupported';
  }
}

/**
 * 환경에 관계없이 텍스트를 안정적으로 복사하는 범용 유틸리티
 * @param {string} text 
 * @returns {Promise<boolean>}
 */
export async function copyTextToClipboard(text) {
  // 1. 최신 Async Clipboard API 우선 시도
  if (navigator.clipboard && window.isSecureContext) {
    try {
      await navigator.clipboard.writeText(text);
      return true;
    } catch (err) {
      console.warn('Async Clipboard API 복사 실패, 폴백 시도:', err);
    }
  }

  // 2. 레거시 execCommand 폴백 시도
  try {
    const textArea = document.createElement('textarea');
    textArea.value = text;
    
    // 화면 깜빡임 및 스크롤 튐 방지 스타일링
    textArea.style.position = 'fixed';
    textArea.style.top = '0';
    textArea.style.left = '-9999px';
    textArea.style.opacity = '0';
    textArea.setAttribute('readonly', '');
    
    document.body.appendChild(textArea);
    
    // iOS 대응 포커스 및 셀렉션
    textArea.focus();
    textArea.select();
    textArea.setSelectionRange(0, 99999);

    const successful = document.execCommand('copy');
    document.body.removeChild(textArea);
    
    return successful;
  } catch (fallbackErr) {
    console.error('모든 복사 방식 실패:', fallbackErr);
    return false;
  }
}

import { useState, useCallback } from 'react';
import { copyTextToClipboard } from './clipboardUtils';

export function useClipboard({ timeout = 2000 } = {}) {
  const [copied, setCopied] = useState(false);
  const [error, setError] = useState(null);

  const copy = useCallback(async (text) => {
    if (!text) return false;

    try {
      const success = await copyTextToClipboard(text);
      if (success) {
        setCopied(true);
        setError(null);
        setTimeout(() => setCopied(false), timeout);
        return true;
      } else {
        throw new Error('클립보드 쓰기 명령이 실패했습니다.');
      }
    } catch (err) {
      setError(err);
      setCopied(false);
      return false;
    }
  }, [timeout]);

  return { copy, copied, error };
}

// 사용 예제 컴포넌트
export function CodeSnippet({ code }) {
  const { copy, copied } = useClipboard({ timeout: 1500 });

  return (
    <div className="code-box">
      <pre><code>{code}</code></pre>
      <button onClick={() => copy(code)} aria-label="코드 복사">
        {copied ? '✅ 복사 완료!' : '📋 복사하기'}
      </button>
    </div>
  );
}

// ❌ Safari에서 100% 에러 발생 (NotAllowedError: The request is not allowed by the user agent)
button.addEventListener('click', async () => {
  const res = await fetch('/api/get-share-link'); // 비동기 API 호출 지연
  const data = await res.json();
  await navigator.clipboard.writeText(data.url); // 거부됨!
});

// ⭕ 해결책: Promise를 ClipboardItem 안에 직접 전달 (Safari 13.1+ 지원)
button.addEventListener('click', () => {
  const textPromise = fetch('/api/get-share-link')
    .then(res => res.json())
    .then(data => new Blob([data.url], { type: 'text/plain' }));

  const item = new ClipboardItem({
    'text/plain': textPromise // Promise<Blob>을 통째로 넘김
  });

  navigator.clipboard.write([item]);
});

<!-- iframe 태그에 반드시 allow 속성 선언 -->
<iframe 
  src="https://widget.example.com" 
  allow="clipboard-write; clipboard-read">
</iframe>