@lumir-company/editor 0.4.1 → 0.4.3

package/README.md

@@ -17,6 +17,8 @@
   - [S3 업로드 설정](#1-s3-업로드-권장)
   - [파일명 커스터마이징](#파일명-커스터마이징)
   - [커스텀 업로더](#2-커스텀-업로더)
+- [이미지 삭제](#이미지-삭제)
+- [HTML 미리보기](#html-미리보기)
 - [Props API](#props-api)
 - [사용 예제](#사용-예제)
 - [스타일링](#스타일링)
@@ -29,6 +31,7 @@
 | 특징                    | 설명                                                   |
 | ----------------------- | ------------------------------------------------------ |
 | **이미지 전용**         | 이미지 업로드/드래그앤드롭만 지원 (비디오/오디오 제거) |
+| **HTML 미리보기**       | HTML 파일을 드래그 앤 드롭하여 iframe으로 미리보기     |
 | **S3 연동**             | Presigned URL 기반 S3 업로드 내장                      |
 | **파일명 커스터마이징** | 업로드 파일명 변경 콜백 + UUID 자동 추가 지원          |
 | **로딩 스피너**         | 이미지 업로드 중 자동 스피너 표시                      |
@@ -329,19 +332,290 @@ const imageUrl = await s3Uploader(imageFile);
 
 ---
 
+## 이미지 삭제
+
+에디터에서 이미지가 삭제될 때 S3 등 외부 스토리지에서도 자동으로 삭제하고 싶다면 `onImageDelete` 콜백을 사용하세요.
+
+### 기본 사용
+
+```tsx
+<LumirEditor
+  s3Upload={{
+    apiEndpoint: "/api/s3/presigned",
+    env: "production",
+    path: "images",
+  }}
+  onImageDelete={(imageUrl) => {
+    console.log("이미지 삭제됨:", imageUrl);
+    // S3에서 삭제 로직 구현
+  }}
+/>
+```
+
+### 권장: 지연 삭제 (Undo/Redo 대응)
+
+Undo로 이미지를 복원할 수 있도록 **지연 삭제**를 권장합니다.
+
+```tsx
+"use client";
+
+import { useState, useRef, useCallback } from "react";
+
+function Editor() {
+  const pendingDeletes = useRef(new Map());
+
+  const handleImageDelete = useCallback((imageUrl: string) => {
+    // 이미 예약된 삭제가 있으면 무시
+    if (pendingDeletes.current.has(imageUrl)) return;
+
+    // 5분 후 삭제 예약
+    const timeoutId = setTimeout(async () => {
+      pendingDeletes.current.delete(imageUrl);
+      
+      // S3에서 실제 삭제
+      await fetch(`/api/s3/delete?url=${encodeURIComponent(imageUrl)}`, {
+        method: "DELETE",
+      });
+    }, 5 * 60 * 1000); // 5분
+
+    pendingDeletes.current.set(imageUrl, timeoutId);
+  }, []);
+
+  return (
+    <LumirEditor
+      s3Upload={{ /* ... */ }}
+      onImageDelete={handleImageDelete}
+    />
+  );
+}
+```
+
+### S3 삭제 API 예시
+
+> **참고**: `onImageDelete`는 **프레임워크 독립적**입니다. 아래는 각 환경별 구현 예시입니다.
+
+#### Next.js API Route
+
+**파일**: `app/api/s3/delete/route.ts`
+
+```typescript
+import { NextRequest, NextResponse } from "next/server";
+import { S3Client, DeleteObjectCommand } from "@aws-sdk/client-s3";
+
+const s3 = new S3Client({
+  region: process.env.AWS_REGION!,
+  credentials: {
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+  },
+});
+
+export async function DELETE(req: NextRequest) {
+  const { searchParams } = new URL(req.url);
+  const imageUrl = searchParams.get("url");
+
+  if (!imageUrl) {
+    return NextResponse.json({ error: "url is required" }, { status: 400 });
+  }
+
+  // URL에서 S3 키 추출
+  const key = extractKeyFromUrl(imageUrl);
+
+  await s3.send(
+    new DeleteObjectCommand({
+      Bucket: process.env.AWS_S3_BUCKET!,
+      Key: key,
+    })
+  );
+
+  return NextResponse.json({ success: true });
+}
+
+function extractKeyFromUrl(url: string): string {
+  const urlObj = new URL(url);
+  return decodeURIComponent(urlObj.pathname.slice(1));
+}
+```
+
+**클라이언트 구현**:
+
+```tsx
+const handleImageDelete = (imageUrl: string) => {
+  fetch(`/api/s3/delete?url=${encodeURIComponent(imageUrl)}`, {
+    method: "DELETE",
+  });
+};
+
+<LumirEditor onImageDelete={handleImageDelete} />
+```
+
+#### React + Express
+
+**서버** (`server.js`):
+
+```javascript
+app.delete('/api/images', async (req, res) => {
+  const { imageUrl } = req.body;
+  const key = extractKeyFromS3Url(imageUrl);
+  
+  await s3Client.send(new DeleteObjectCommand({
+    Bucket: process.env.S3_BUCKET,
+    Key: key
+  }));
+  
+  res.json({ success: true });
+});
+```
+
+**클라이언트**:
+
+```tsx
+const handleImageDelete = async (imageUrl: string) => {
+  await fetch('https://api.myapp.com/api/images', {
+    method: 'DELETE',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ imageUrl })
+  });
+};
+
+<LumirEditor onImageDelete={handleImageDelete} />
+```
+
+#### React Native + Firebase Storage
+
+```tsx
+import storage from '@react-native-firebase/storage';
+
+const handleImageDelete = async (imageUrl: string) => {
+  const ref = storage().refFromURL(imageUrl);
+  await ref.delete();
+};
+
+<LumirEditor onImageDelete={handleImageDelete} />
+```
+
+#### Vue + Axios + FastAPI
+
+```typescript
+const handleImageDelete = async (imageUrl: string) => {
+  await axios.delete('https://api.myapp.com/v1/images', {
+    data: { imageUrl }
+  });
+};
+```
+
+### 주의사항
+
+| 항목 | 설명 |
+|------|------|
+| **Undo/Redo** | 지연 삭제로 복원 가능하게 구현 (권장: 5-10분) |
+| **권한 검증** | 프로덕션에서는 인증/인가 필수 |
+| **참조 카운트** | 같은 이미지를 여러 문서에서 사용하는지 확인 |
+| **삭제 로그** | 감사 추적을 위한 삭제 기록 저장 권장 |
+
+---
+
+## HTML 미리보기
+
+LumirEditor는 HTML 파일을 iframe을 사용하여 미리보기할 수 있는 커스텀 블록을 제공합니다. 편집 불가능한 순수 미리보기 기능으로, HTML 문서를 안전하게 표시할 수 있습니다.
+
+### 사용 방법
+
+#### 1. 드래그 앤 드롭
+
+HTML 파일(`.html`, `.htm`)을 에디터에 드래그 앤 드롭하면 자동으로 iframe 미리보기 블록이 삽입됩니다.
+
+```tsx
+<LumirEditor />
+```
+
+- **지원 파일 형식**: `.html`, `.htm`
+- **특징**:
+  - 편집 불가능한 순수 미리보기
+  - 접기/펼치기 기능
+  - 안전한 sandbox 처리 (`allow-same-origin`, JavaScript 실행 비활성화)
+  - 파일명 표시
+
+#### 2. 슬래시 메뉴
+
+에디터에서 `/`를 입력하고 "HTML Preview"를 선택하면 예제 HTML 미리보기 블록이 삽입됩니다.
+
+```
+/ → HTML Preview
+```
+
+### 특징
+
+- **iframe 기반**: HTML 문서를 독립된 iframe에서 안전하게 렌더링
+- **Sandbox 보안**: `sandbox="allow-same-origin"` 속성으로 보안 강화 (JavaScript 실행 의도적 비활성화)
+- **접기/펼치기**: 헤더 클릭으로 미리보기 영역 토글
+- **드래그 리사이즈**: 하단 핸들을 드래그하여 높이 조절 가능 (100px ~ 1200px)
+- **새 창 열기**: HTML 문서를 새 창에서 전체 화면으로 확인
+- **다운로드**: HTML 파일로 다운로드
+- **편집 불가**: 순수 미리보기 전용
+
+### 사용 예제
+
+```tsx
+import { LumirEditor } from "@lumir-company/editor";
+import "@lumir-company/editor/style.css";
+
+function App() {
+  return (
+    <div className="w-full h-[600px]">
+      <LumirEditor
+        onContentChange={(blocks) => {
+          // HTML 미리보기 블록도 일반 블록과 동일하게 처리됨
+          console.log(blocks);
+        }}
+      />
+    </div>
+  );
+}
+```
+
+### 프로그래밍 방식으로 블록 삽입
+
+```tsx
+import { HtmlPreview } from "@lumir-company/editor";
+
+// 에디터 인스턴스에서 직접 블록 삽입
+editor.insertBlocks([
+  {
+    type: "htmlPreview",
+    props: {
+      htmlContent: "<h1>Hello World</h1><p>This is HTML content</p>",
+      fileName: "example.html",
+      height: "400px",
+    },
+  },
+]);
+```
+
+### 주의사항
+
+- HTML 내용은 iframe의 `sandbox="allow-same-origin"` 속성으로 보안이 강화되어 있습니다
+- **JavaScript는 의도적으로 비활성화**되어 있습니다 (보안상 이유)
+- 외부 리소스(CSS, JS, 이미지 등)는 상대 경로가 작동하지 않을 수 있습니다
+- 인라인 CSS 스타일을 권장합니다
+
+---
+
 ## Props API
 
 ### 핵심 Props
 
-| Prop              | 타입                              | 기본값      | 설명               |
-| ----------------- | --------------------------------- | ----------- | ------------------ |
-| `s3Upload`        | `S3UploaderConfig`                | `undefined` | S3 업로드 설정     |
-| `uploadFile`      | `(file: File) => Promise<string>` | `undefined` | 커스텀 업로드 함수 |
-| `onContentChange` | `(blocks) => void`                | `undefined` | 콘텐츠 변경 콜백   |
-| `initialContent`  | `Block[] \| string`               | `undefined` | 초기 콘텐츠        |
-| `editable`        | `boolean`                         | `true`      | 편집 가능 여부     |
-| `theme`           | `"light" \| "dark"`               | `"light"`   | 테마               |
-| `className`       | `string`                          | `""`        | CSS 클래스         |
+| Prop              | 타입                                  | 기본값      | 설명                    |
+| ----------------- | ------------------------------------- | ----------- | ----------------------- |
+| `s3Upload`        | `S3UploaderConfig`                    | `undefined` | S3 업로드 설정          |
+| `uploadFile`      | `(file: File) => Promise<string>`     | `undefined` | 커스텀 업로드 함수      |
+| `onContentChange` | `(blocks) => void`                    | `undefined` | 콘텐츠 변경 콜백        |
+| `onImageDelete`   | `(imageUrl: string) => void`          | `undefined` | 이미지 삭제 시 콜백     |
+| `onError`         | `(error: LumirEditorError) => void`   | `undefined` | 에러 발생 시 콜백       |
+| `initialContent`  | `Block[] \| string`                   | `undefined` | 초기 콘텐츠             |
+| `editable`        | `boolean`                             | `true`      | 편집 가능 여부          |
+| `theme`           | `"light" \| "dark"`                   | `"light"`   | 테마                    |
+| `className`       | `string`                              | `""`        | CSS 클래스              |
 
 ### S3UploaderConfig
 
@@ -369,6 +643,7 @@ interface LumirEditorProps {
   // === 에디터 설정 ===
   initialContent?: DefaultPartialBlock[] | string; // 초기 콘텐츠 (블록 배열 또는 JSON 문자열)
   initialEmptyBlocks?: number; // 초기 빈 블록 개수 (기본: 3)
+  placeholder?: string; // 빈 블록에 표시할 안내 텍스트 (예: "내용을 입력하세요...")
   uploadFile?: (file: File) => Promise<string>; // 커스텀 파일 업로드 함수
   s3Upload?: {
     apiEndpoint: string;
@@ -381,7 +656,9 @@ interface LumirEditorProps {
 
   // === 콜백 ===
   onContentChange?: (blocks: DefaultPartialBlock[]) => void; // 콘텐츠 변경 시 호출
+  onImageDelete?: (imageUrl: string) => void; // 이미지 삭제 시 호출 (S3 삭제 등)
   onSelectionChange?: () => void; // 선택 영역 변경 시 호출
+  onError?: (error: LumirEditorError) => void; // 에러 발생 시 호출
 
   // 기능 설정
   tables?: TableConfig; // 테이블 기능 설정 (splitCells, cellBackgroundColor 등)
@@ -403,6 +680,11 @@ interface LumirEditorProps {
   tableHandles?: boolean; // 테이블 핸들 표시 (기본: true)
   className?: string; // 컨테이너 CSS 클래스
 
+  // === 링크 프리뷰 설정 ===
+  linkPreview?: {
+    apiEndpoint: string; // 링크 메타데이터를 가져올 API 엔드포인트 (예: "/api/link-preview")
+  };
+
   // 미디어 업로드 허용 여부 (기본: 모두 비활성)
   allowVideoUpload?: boolean; // 비디오 업로드 허용 (기본: false)
   allowAudioUpload?: boolean; // 오디오 업로드 허용 (기본: false)
@@ -611,6 +893,56 @@ const url = await uploader(imageFile);
 
 ## 변경 로그
 
+### v0.4.3
+
+- **링크 프리뷰 기능 추가**
+  - `linkPreview` prop으로 링크 미리보기 활성화 (카카오톡 스타일 OG 카드)
+  - URL 붙여넣기 시 자동 링크 프리뷰 블록 생성 (빈 블록이면 교체, 텍스트 있으면 하단 삽입)
+  - 슬래시 메뉴(`/`)에서 Link Preview 항목 추가
+  - 드래그 리사이즈 지원 (좌우 너비, 하단 이미지 높이 조절)
+  - 메타데이터에 이미지 없을 경우 이미지 영역 생략
+  - 에러 카드 클릭 시 링크 이동 지원
+  - `fetchLinkMetadata`, `clearMetadataCache`, `LinkMetadata` 타입 export
+- **링크 툴바 커스텀**
+  - 텍스트 링크를 링크 프리뷰 블록으로 전환하는 버튼 추가 (`replaceBlocks` 사용)
+  - `linkPreview.apiEndpoint` 설정 시에만 전환 버튼 표시
+- **placeholder prop 추가**
+  - `placeholder` prop으로 에디터 빈 블록 안내 텍스트 설정
+- **이미지 삭제 기능 추가**
+  - `onImageDelete` 콜백 prop 추가 - 에디터에서 이미지 삭제 시 호출
+  - S3 등 외부 스토리지에서 이미지 자동 삭제 지원
+  - 지연 삭제 패턴으로 Undo/Redo 대응 가능
+  - 이미지 URL 추출 및 삭제 감지 헬퍼 함수 내장
+- **보안 강화**
+  - URL 이스케이프 처리 추가 (XSS 방지)
+  - LinkButton: `javascript:`, `data:`, `vbscript:`, `file:` 프로토콜 차단
+  - 위험한 URL 입력 시 에러 메시지 표시
+- **링크 삽입 버그 수정**
+  - 플로팅 메뉴 링크 버튼: 텍스트 미선택 시에도 URL 텍스트로 링크 삽입 지원
+  - `editor.focus()` 호출로 선택 상태 복원
+- **README 개선**
+  - 링크 프리뷰 사용 가이드 및 API 라우트 예시 추가
+  - 이미지 삭제 섹션 추가 (지연 삭제 예시 포함)
+  - S3 삭제 API 구현 예시 추가
+  - Props API 문서 업데이트
+
+### v0.4.2
+
+- **코드 구조 리팩토링**
+  - FloatingMenu 컴포넌트 분리 (Icons, 개별 버튼 컴포넌트)
+  - 색상 상수 별도 파일로 분리 (`constants/colors.ts`)
+  - 미사용 기능 제거 (FontSelect, FontSizeControl)
+- **에러 처리 개선**
+  - `LumirEditorError` 커스텀 에러 클래스 추가
+  - `onError` 콜백 prop 추가 - 에러 발생 시 사용자 정의 핸들링 가능
+  - 에러 발생 시 사용자 친화적 토스트 메시지 자동 표시
+- **HTML 미리보기 개선**
+  - sandbox 설정 명확화 (JavaScript 의도적 비활성화)
+  - 드래그 리사이즈, 새 창 열기, 다운로드 기능 문서화
+- **타입 개선**
+  - `LumirErrorCode`, `LumirErrorDetails` 타입 export
+  - `ColorItem` 타입 export
+
 ### v0.4.1
 
 - `preserveExtension` prop 추가 - 확장자 자동 붙이기 제어 (기본: true)