@lumir-company/editor 0.3.3 → 0.4.0

package/README.md

@@ -5,93 +5,78 @@
 [![npm version](https://img.shields.io/npm/v/@lumir-company/editor.svg)](https://www.npmjs.com/package/@lumir-company/editor)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+> 이미지 업로드에 최적화된 경량 에디터. S3 업로드, 파일명 커스터마이징, 로딩 스피너 내장.
+
+---
+
 ## 📋 목차
 
-- [✨ 핵심 특징](#-핵심-특징)
-- [📦 설치](#-설치)
-- [🚀 빠른 시작](#-빠른-시작)
-- [📚 Props 레퍼런스](#-props-레퍼런스)
-- [🖼️ 이미지 업로드](#️-이미지-업로드)
-- [🛠️ 유틸리티 API](#️-유틸리티-api)
-- [📖 타입 정의](#-타입-정의)
-- [💡 사용 예제](#-사용-예제)
-- [🎨 스타일링 가이드](#-스타일링-가이드)
-- [⚠️ 주의사항 및 트러블슈팅](#️-주의사항-및-트러블슈팅)
-- [📄 라이선스](#-라이선스)
+- [특징](#-특징)
+- [빠른 시작](#-빠른-시작)
+- [이미지 업로드](#-이미지-업로드)
+  - [S3 업로드 설정](#1-s3-업로드-권장)
+  - [파일명 커스터마이징](#-파일명-커스터마이징)
+  - [커스텀 업로더](#2-커스텀-업로더)
+- [Props API](#-props-api)
+- [사용 예제](#-사용-예제)
+- [스타일링](#-스타일링)
+- [트러블슈팅](#-트러블슈팅)
 
 ---
 
-## ✨ 핵심 특징
+## ✨ 특징
 
-| 특징                     | 설명                                                        |
-| ------------------------ | ----------------------------------------------------------- |
-| 🖼️ **이미지 전용**       | 이미지 업로드/드래그앤드롭만 지원 (비디오/오디오/파일 제거) |
-| ☁️ **S3 연동**           | Presigned URL 기반 S3 업로드 내장                           |
-| 🎯 **커스텀 업로더**     | 자체 업로드 로직 적용 가능                                  |
-| ⏳ **로딩 스피너**       | 이미지 업로드 중 자동 스피너 표시                           |
-| 🚀 **애니메이션 최적화** | 기본 애니메이션 비활성화로 성능 향상                        |
-| 📝 **TypeScript**        | 완전한 타입 안전성                                          |
-| 🎨 **테마 지원**         | 라이트/다크 테마 및 커스텀 테마 지원                        |
-| 📱 **반응형**            | 모바일/데스크톱 최적화                                      |
+| 특징                       | 설명                                                   |
+| -------------------------- | ------------------------------------------------------ |
+| 🖼️ **이미지 전용**         | 이미지 업로드/드래그앤드롭만 지원 (비디오/오디오 제거) |
+| ☁️ **S3 연동**             | Presigned URL 기반 S3 업로드 내장                      |
+| 🏷️ **파일명 커스터마이징** | 업로드 파일명 변경 콜백 + UUID 자동 추가 지원          |
+| ⏳ **로딩 스피너**         | 이미지 업로드 중 자동 스피너 표시                      |
+| 🚀 **성능 최적화**         | 애니메이션 비활성화로 빠른 렌더링                      |
+| 📝 **TypeScript**          | 완전한 타입 안전성                                     |
+| 🎨 **테마 지원**           | 라이트/다크 테마 및 커스텀 테마                        |
 
 ### 지원 이미지 형식
 
 ```
-PNG, JPEG/JPG, GIF (애니메이션 포함), WebP, BMP, SVG
+PNG, JPEG/JPG, GIF, WebP, BMP, SVG
 ```
 
 ---
 
-## 📦 설치
+## 🚀 빠른 시작
+
+### 1. 설치
 
 ```bash
-# npm
 npm install @lumir-company/editor
-
-# yarn
+# 또는
 yarn add @lumir-company/editor
-
-# pnpm
-pnpm add @lumir-company/editor
 ```
 
-### Peer Dependencies
-
-```json
-{
-  "react": ">=18.0.0",
-  "react-dom": ">=18.0.0"
-}
-```
-
----
-
-## 🚀 빠른 시작
-
-### 1단계: CSS 임포트 (필수)
-
-```tsx
-import "@lumir-company/editor/style.css";
-```
+**필수 Peer Dependencies:**
 
-> ⚠️ **중요**: CSS를 임포트하지 않으면 에디터가 정상적으로 렌더링되지 않습니다.
+- `react` >= 18.0.0
+- `react-dom` >= 18.0.0
 
-### 2단계: 기본 사용
+### 2. 기본 사용
 
 ```tsx
 import { LumirEditor } from "@lumir-company/editor";
-import "@lumir-company/editor/style.css";
+import "@lumir-company/editor/style.css"; // 필수!
 
 export default function App() {
   return (
-    <div className="w-full h-[400px]">
+    <div className="w-full h-[500px]">
       <LumirEditor onContentChange={(blocks) => console.log(blocks)} />
     </div>
   );
 }
 ```
 
-### 3단계: Next.js에서 사용 (SSR 비활성화 필수)
+> ⚠️ **중요**: `style.css`를 임포트하지 않으면 에디터가 정상 작동하지 않습니다.
+
+### 3. Next.js에서 사용
 
 ```tsx
 "use client";
@@ -99,6 +84,7 @@ export default function App() {
 import dynamic from "next/dynamic";
 import "@lumir-company/editor/style.css";
 
+// SSR 비활성화 필수
 const LumirEditor = dynamic(
   () =>
     import("@lumir-company/editor").then((m) => ({ default: m.LumirEditor })),
@@ -107,10 +93,8 @@ const LumirEditor = dynamic(
 
 export default function EditorPage() {
   return (
-    <div className="w-full h-[500px]">
-      <LumirEditor
-        onContentChange={(blocks) => console.log("Content:", blocks)}
-      />
+    <div className="h-[500px]">
+      <LumirEditor />
     </div>
   );
 }
@@ -118,108 +102,148 @@ export default function EditorPage() {
 
 ---
 
-## 📚 Props 레퍼런스
-
-### 에디터 옵션 (Editor Options)
-
-| Prop                 | 타입                                      | 기본값                      | 설명                                     |
-| -------------------- | ----------------------------------------- | --------------------------- | ---------------------------------------- |
-| `initialContent`     | `DefaultPartialBlock[] \| string`         | `undefined`                 | 초기 콘텐츠 (블록 배열 또는 JSON 문자열) |
-| `initialEmptyBlocks` | `number`                                  | `3`                         | 초기 빈 블록 개수                        |
-| `placeholder`        | `string`                                  | `undefined`                 | 첫 번째 블록의 placeholder 텍스트        |
-| `uploadFile`         | `(file: File) => Promise<string>`         | `undefined`                 | 커스텀 파일 업로드 함수                  |
-| `s3Upload`           | `S3UploaderConfig`                        | `undefined`                 | S3 업로드 설정                           |
-| `tables`             | `TableConfig`                             | `{...}`                     | 테이블 기능 설정                         |
-| `heading`            | `{ levels?: (1\|2\|3\|4\|5\|6)[] }`       | `{ levels: [1,2,3,4,5,6] }` | 헤딩 레벨 설정                           |
-| `defaultStyles`      | `boolean`                                 | `true`                      | 기본 스타일 활성화                       |
-| `disableExtensions`  | `string[]`                                | `[]`                        | 비활성화할 확장 기능 목록                |
-| `tabBehavior`        | `"prefer-navigate-ui" \| "prefer-indent"` | `"prefer-navigate-ui"`      | 탭 키 동작                               |
-| `trailingBlock`      | `boolean`                                 | `true`                      | 마지막에 빈 블록 자동 추가               |
-| `allowVideoUpload`   | `boolean`                                 | `false`                     | 비디오 업로드 허용 (기본 비활성)         |
-| `allowAudioUpload`   | `boolean`                                 | `false`                     | 오디오 업로드 허용 (기본 비활성)         |
-| `allowFileUpload`    | `boolean`                                 | `false`                     | 일반 파일 업로드 허용 (기본 비활성)      |
-
-### 뷰 옵션 (View Options)
-
-| Prop                | 타입                               | 기본값    | 설명                                                 |
-| ------------------- | ---------------------------------- | --------- | ---------------------------------------------------- |
-| `editable`          | `boolean`                          | `true`    | 편집 가능 여부                                       |
-| `theme`             | `"light" \| "dark" \| ThemeObject` | `"light"` | 에디터 테마                                          |
-| `formattingToolbar` | `boolean`                          | `true`    | 서식 툴바 표시                                       |
-| `linkToolbar`       | `boolean`                          | `true`    | 링크 툴바 표시                                       |
-| `sideMenu`          | `boolean`                          | `true`    | 사이드 메뉴 표시                                     |
-| `sideMenuAddButton` | `boolean`                          | `false`   | 사이드 메뉴 + 버튼 표시 (false시 드래그 핸들만 표시) |
-| `emojiPicker`       | `boolean`                          | `true`    | 이모지 선택기 표시                                   |
-| `filePanel`         | `boolean`                          | `true`    | 파일 패널 표시                                       |
-| `tableHandles`      | `boolean`                          | `true`    | 테이블 핸들 표시                                     |
-| `className`         | `string`                           | `""`      | 컨테이너 CSS 클래스                                  |
-
-### 콜백 (Callbacks)
-
-| Prop                | 타입                                      | 설명                   |
-| ------------------- | ----------------------------------------- | ---------------------- |
-| `onContentChange`   | `(blocks: DefaultPartialBlock[]) => void` | 콘텐츠 변경 시 호출    |
-| `onSelectionChange` | `() => void`                              | 선택 영역 변경 시 호출 |
+## 🖼️ 이미지 업로드
 
-### S3UploaderConfig
+### 1. S3 업로드 (권장)
+
+Presigned URL을 사용한 안전한 S3 업로드 방식입니다.
 
 ```tsx
-interface S3UploaderConfig {
-  apiEndpoint: string; // Presigned URL API 엔드포인트 (필수)
-  env: "development" | "production"; // 환경 (필수)
-  path: string; // S3 경로 (필수)
-}
+<LumirEditor
+  s3Upload={{
+    apiEndpoint: "/api/s3/presigned",
+    env: "production",
+    path: "blog/images",
+  }}
+/>
 ```
 
-### TableConfig
+#### S3 파일 저장 경로
 
-```tsx
-interface TableConfig {
-  splitCells?: boolean; // 셀 분할 (기본: true)
-  cellBackgroundColor?: boolean; // 셀 배경색 (기본: true)
-  cellTextColor?: boolean; // 셀 텍스트 색상 (기본: true)
-  headers?: boolean; // 헤더 행 (기본: true)
+```
+{env}/{path}/{filename}
+
+예시:
+production/blog/images/my-photo.png
+```
+
+#### API 엔드포인트 응답 형식
+
+서버는 다음 형식으로 응답해야 합니다:
+
+```json
+{
+  "presignedUrl": "https://s3.amazonaws.com/bucket/upload-url",
+  "publicUrl": "https://cdn.example.com/production/blog/images/my-photo.png"
 }
 ```
 
 ---
 
-## 🖼️ 이미지 업로드
+### 📝 파일명 커스터마이징
 
-### 방법 1: S3 업로드 (권장)
+여러 이미지를 동시에 업로드할 때 파일명 중복을 방지하고 관리하기 쉽게 만드는 기능입니다.
 
-Presigned URL을 사용한 안전한 S3 업로드 방식입니다.
+#### 옵션 1: UUID 자동 추가
 
 ```tsx
 <LumirEditor
   s3Upload={{
     apiEndpoint: "/api/s3/presigned",
-    env: "development",
-    path: "blog/images",
+    env: "production",
+    path: "uploads",
+    appendUUID: true, // 파일명 뒤에 UUID 자동 추가
   }}
-  onContentChange={(blocks) => console.log(blocks)}
 />
 ```
 
-**S3 파일 저장 경로 구조:**
+**결과:**
 
 ```
-{env}/{path}/{filename}
-예: development/blog/images/my-image.png
+원본: photo.png
+업로드: photo_550e8400-e29b-41d4-a716-446655440000.png
 ```
 
-**API 엔드포인트 응답 예시:**
+#### 옵션 2: 파일명 변환 콜백
 
-```json
-{
-  "presignedUrl": "https://s3.amazonaws.com/bucket/...",
-  "publicUrl": "https://cdn.example.com/development/blog/images/my-image.png"
+```tsx
+<LumirEditor
+  s3Upload={{
+    apiEndpoint: "/api/s3/presigned",
+    env: "production",
+    path: "uploads",
+    fileNameTransform: (originalName, file) => {
+      // 예: 사용자 ID 추가
+      const userId = getCurrentUserId();
+      return `${userId}_${originalName}`;
+    },
+  }}
+/>
+```
+
+**결과:**
+
+```
+원본: photo.png
+업로드: user123_photo.png
+```
+
+#### 옵션 3: 조합 사용 (권장)
+
+```tsx
+<LumirEditor
+  s3Upload={{
+    apiEndpoint: "/api/s3/presigned",
+    env: "production",
+    path: "uploads",
+    fileNameTransform: (originalName) => `user123_${originalName}`,
+    appendUUID: true, // 변환 후 UUID 추가
+  }}
+/>
+```
+
+**결과:**
+
+```
+원본: photo.png
+1. fileNameTransform 적용: user123_photo.png
+2. appendUUID 적용: user123_photo_550e8400-e29b-41d4.png
+```
+
+#### 실전 예제: 타임스탬프 + UUID
+
+```tsx
+function MyEditor() {
+  return (
+    <LumirEditor
+      s3Upload={{
+        apiEndpoint: "/api/s3/presigned",
+        env: "production",
+        path: "uploads",
+        fileNameTransform: (originalName, file) => {
+          const timestamp = new Date().toISOString().split("T")[0]; // 2024-01-15
+          const ext = originalName.split(".").pop();
+          const nameWithoutExt = originalName.replace(`.${ext}`, "");
+          return `${timestamp}_${nameWithoutExt}.${ext}`;
+        },
+        appendUUID: true,
+      }}
+    />
+  );
 }
 ```
 
-### 방법 2: 커스텀 업로더
+**결과:**
+
+```
+2024-01-15_photo_550e8400-e29b-41d4.png
+```
+
+---
+
+### 2. 커스텀 업로더
 
-자체 업로드 로직을 사용할 때 활용합니다.
+자체 업로드 로직을 사용할 때:
 
 ```tsx
 <LumirEditor
@@ -232,24 +256,22 @@ Presigned URL을 사용한 안전한 S3 업로드 방식입니다.
       body: formData,
     });
 
-    const data = await response.json();
-    return data.url; // 업로드된 이미지의 URL 반환
+    const { url } = await response.json();
+    return url; // 업로드된 이미지 URL 반환
   }}
 />
 ```
 
-### 방법 3: createS3Uploader 헬퍼 함수
-
-S3 업로더를 직접 생성하여 사용할 수 있습니다.
+### 3. 헬퍼 함수 사용
 
 ```tsx
-import { LumirEditor, createS3Uploader } from "@lumir-company/editor";
+import { createS3Uploader } from "@lumir-company/editor";
 
-// S3 업로더 생성
 const s3Uploader = createS3Uploader({
   apiEndpoint: "/api/s3/presigned",
   env: "production",
-  path: "uploads/images",
+  path: "images",
+  appendUUID: true,
 });
 
 // 에디터에 적용
@@ -262,204 +284,90 @@ const imageUrl = await s3Uploader(imageFile);
 ### 업로드 우선순위
 
 1. `uploadFile` prop이 있으면 우선 사용
-2. `uploadFile`이 없고 `s3Upload`가 있으면 S3 업로드 사용
+2. `uploadFile` 없고 `s3Upload`가 있으면 S3 업로드 사용
 3. 둘 다 없으면 업로드 실패
 
 ---
 
-## 🛠️ 유틸리티 API
-
-### ContentUtils
-
-콘텐츠 관리 유틸리티 클래스입니다.
-
-```tsx
-import { ContentUtils } from "@lumir-company/editor";
-
-// JSON 문자열 유효성 검증
-const isValid = ContentUtils.isValidJSONString('[{"type":"paragraph"}]');
-// true
-
-// JSON 문자열을 블록 배열로 파싱
-const blocks = ContentUtils.parseJSONContent(jsonString);
-// DefaultPartialBlock[] | null
-
-// 기본 빈 블록 생성
-const emptyBlock = ContentUtils.createDefaultBlock();
-// { type: "paragraph", props: {...}, content: [...], children: [] }
-
-// 콘텐츠 유효성 검증 및 기본값 설정
-const validatedContent = ContentUtils.validateContent(content, 3);
-// 빈 콘텐츠면 3개의 빈 블록 반환
-```
-
-### EditorConfig
+## 📚 Props API
 
-에디터 설정 유틸리티 클래스입니다.
+### 핵심 Props
 
-```tsx
-import { EditorConfig } from "@lumir-company/editor";
-
-// 테이블 기본 설정 가져오기
-const tableConfig = EditorConfig.getDefaultTableConfig({
-  splitCells: true,
-  headers: false,
-});
+| 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 클래스         |
 
-// 헤딩 기본 설정 가져오기
-const headingConfig = EditorConfig.getDefaultHeadingConfig({
-  levels: [1, 2, 3],
-});
-
-// 비활성화 확장 목록 생성
-const disabledExt = EditorConfig.getDisabledExtensions(
-  ["codeBlock"], // 사용자 정의 비활성 확장
-  false, // allowVideo
-  false, // allowAudio
-  false // allowFile
-);
-// ["codeBlock", "video", "audio", "file"]
-```
-
-### cn (className 유틸리티)
-
-조건부 className 결합 유틸리티입니다.
+### S3UploaderConfig
 
 ```tsx
-import { cn } from "@lumir-company/editor";
-
-<LumirEditor
-  className={cn(
-    "min-h-[400px] rounded-lg",
-    isFullscreen && "fixed inset-0 z-50",
-    isDarkMode && "dark-theme"
-  )}
-/>;
+interface S3UploaderConfig {
+  // 필수
+  apiEndpoint: string; // Presigned URL API 엔드포인트
+  env: "development" | "production";
+  path: string; // S3 저장 경로
+
+  // 선택 (파일명 커스터마이징)
+  fileNameTransform?: (originalName: string, file: File) => string;
+  appendUUID?: boolean; // true: 파일명 뒤에 UUID 추가
+}
 ```
 
----
-
-## 📖 타입 정의
-
-### 주요 타입 import
-
-```tsx
-import type {
-  // 에디터 Props
-  LumirEditorProps,
-
-  // 에디터 인스턴스 타입
-  EditorType,
-
-  // 블록 관련 타입
-  DefaultPartialBlock,
-  DefaultBlockSchema,
-  DefaultInlineContentSchema,
-  DefaultStyleSchema,
-  PartialBlock,
-  BlockNoteEditor,
-} from "@lumir-company/editor";
-
-import type { S3UploaderConfig } from "@lumir-company/editor";
-```
+### 전체 Props
 
-### LumirEditorProps 전체 인터페이스
+<details>
+<summary>전체 Props 보기</summary>
 
 ```tsx
 interface LumirEditorProps {
-  // === Editor Options ===
-  initialContent?: DefaultPartialBlock[] | string;
-  initialEmptyBlocks?: number;
-  placeholder?: string;
-  uploadFile?: (file: File) => Promise<string>;
-  s3Upload?: {
-    apiEndpoint: string;
-    env: "development" | "production";
-    path: string;
-  };
-  allowVideoUpload?: boolean;
-  allowAudioUpload?: boolean;
-  allowFileUpload?: boolean;
-  tables?: {
-    splitCells?: boolean;
-    cellBackgroundColor?: boolean;
-    cellTextColor?: boolean;
-    headers?: boolean;
-  };
-  heading?: { levels?: (1 | 2 | 3 | 4 | 5 | 6)[] };
-  defaultStyles?: boolean;
-  disableExtensions?: string[];
-  tabBehavior?: "prefer-navigate-ui" | "prefer-indent";
-  trailingBlock?: boolean;
-
-  // === View Options ===
-  editable?: boolean;
-  theme?:
-    | "light"
-    | "dark"
-    | Partial<Record<string, unknown>>
-    | {
-        light: Partial<Record<string, unknown>>;
-        dark: Partial<Record<string, unknown>>;
-      };
-  formattingToolbar?: boolean;
-  linkToolbar?: boolean;
-  sideMenu?: boolean;
-  sideMenuAddButton?: boolean;
-  emojiPicker?: boolean;
-  filePanel?: boolean;
-  tableHandles?: boolean;
-  onSelectionChange?: () => void;
-  className?: string;
-
-  // === Callbacks ===
-  onContentChange?: (content: DefaultPartialBlock[]) => void;
+  // === 에디터 설정 ===
+  initialContent?: DefaultPartialBlock[] | string; // 초기 콘텐츠 (블록 배열 또는 JSON 문자열)
+  initialEmptyBlocks?: number; // 초기 빈 블록 개수 (기본: 3)
+  uploadFile?: (file: File) => Promise<string>; // 커스텀 파일 업로드 함수
+  s3Upload?: S3UploaderConfig; // S3 업로드 설정 (apiEndpoint, env, path 등)
+
+  // === 콜백 ===
+  onContentChange?: (blocks: DefaultPartialBlock[]) => void; // 콘텐츠 변경 시 호출
+  onSelectionChange?: () => void; // 선택 영역 변경 시 호출
+
+  // 기능 설정
+  tables?: TableConfig; // 테이블 기능 설정 (splitCells, cellBackgroundColor 등)
+  heading?: { levels?: (1 | 2 | 3 | 4 | 5 | 6)[] }; // 헤딩 레벨 설정 (기본: [1,2,3,4,5,6])
+  defaultStyles?: boolean; // 기본 스타일 활성화 (기본: true)
+  disableExtensions?: string[]; // 비활성화할 확장 기능 목록
+  tabBehavior?: "prefer-navigate-ui" | "prefer-indent"; // 탭 키 동작 (기본: "prefer-navigate-ui")
+  trailingBlock?: boolean; // 마지막에 빈 블록 자동 추가 (기본: true)
+
+  // === UI 설정 ===
+  editable?: boolean; // 편집 가능 여부 (기본: true)
+  theme?: "light" | "dark" | ThemeObject; // 에디터 테마 (기본: "light")
+  formattingToolbar?: boolean; // 서식 툴바 표시 (기본: true)
+  linkToolbar?: boolean; // 링크 툴바 표시 (기본: true)
+  sideMenu?: boolean; // 사이드 메뉴 표시 (기본: true)
+  sideMenuAddButton?: boolean; // 사이드 메뉴 + 버튼 표시 (기본: false, 드래그 핸들만 표시)
+  emojiPicker?: boolean; // 이모지 선택기 표시 (기본: true)
+  filePanel?: boolean; // 파일 패널 표시 (기본: true)
+  tableHandles?: boolean; // 테이블 핸들 표시 (기본: true)
+  className?: string; // 컨테이너 CSS 클래스
+
+  // 미디어 업로드 허용 여부 (기본: 모두 비활성)
+  allowVideoUpload?: boolean; // 비디오 업로드 허용 (기본: false)
+  allowAudioUpload?: boolean; // 오디오 업로드 허용 (기본: false)
+  allowFileUpload?: boolean; // 일반 파일 업로드 허용 (기본: false)
 }
 ```
 
+</details>
+
 ---
 
 ## 💡 사용 예제
 
-### 기본 에디터
-
-```tsx
-import { LumirEditor } from "@lumir-company/editor";
-import "@lumir-company/editor/style.css";
-
-function BasicEditor() {
-  return (
-    <div className="h-[400px]">
-      <LumirEditor />
-    </div>
-  );
-}
-```
-
-### 초기 콘텐츠 설정
-
-```tsx
-// 방법 1: 블록 배열
-<LumirEditor
-  initialContent={[
-    {
-      type: "heading",
-      props: { level: 1 },
-      content: [{ type: "text", text: "제목입니다", styles: {} }],
-    },
-    {
-      type: "paragraph",
-      content: [{ type: "text", text: "본문 내용...", styles: {} }],
-    },
-  ]}
-/>
-
-// 방법 2: JSON 문자열
-<LumirEditor
-  initialContent='[{"type":"paragraph","content":[{"type":"text","text":"Hello World","styles":{}}]}]'
-/>
-```
-
 ### 읽기 전용 모드
 
 ```tsx
@@ -477,46 +385,6 @@ function BasicEditor() {
 <LumirEditor theme="dark" className="bg-gray-900 rounded-lg" />
 ```
 
-### S3 이미지 업로드
-
-```tsx
-<LumirEditor
-  s3Upload={{
-    apiEndpoint: "/api/s3/presigned",
-    env: process.env.NODE_ENV as "development" | "production",
-    path: "articles/images",
-  }}
-  onContentChange={(blocks) => {
-    // 저장 로직
-    saveToDatabase(JSON.stringify(blocks));
-  }}
-/>
-```
-
-### 반응형 디자인
-
-```tsx
-<div className="w-full h-64 md:h-96 lg:h-[600px]">
-  <LumirEditor className="h-full rounded-md md:rounded-lg shadow-sm md:shadow-md" />
-</div>
-```
-
-### 테이블 설정 커스터마이징
-
-```tsx
-<LumirEditor
-  tables={{
-    splitCells: true,
-    cellBackgroundColor: true,
-    cellTextColor: false, // 셀 텍스트 색상 비활성
-    headers: true,
-  }}
-  heading={{
-    levels: [1, 2, 3], // H4-H6 비활성
-  }}
-/>
-```
-
 ### 콘텐츠 저장 및 불러오기
 
 ```tsx
@@ -524,72 +392,31 @@ import { useState, useEffect } from "react";
 import { LumirEditor, ContentUtils } from "@lumir-company/editor";
 
 function EditorWithSave() {
-  const [content, setContent] = useState<string>("");
+  const [content, setContent] = useState("");
 
-  // 저장된 콘텐츠 불러오기
+  // 불러오기
   useEffect(() => {
-    const saved = localStorage.getItem("editor-content");
+    const saved = localStorage.getItem("content");
     if (saved && ContentUtils.isValidJSONString(saved)) {
       setContent(saved);
     }
   }, []);
 
-  // 콘텐츠 저장
-  const handleContentChange = (blocks) => {
-    const jsonContent = JSON.stringify(blocks);
-    localStorage.setItem("editor-content", jsonContent);
+  // 저장
+  const handleChange = (blocks) => {
+    const json = JSON.stringify(blocks);
+    localStorage.setItem("content", json);
   };
 
   return (
-    <LumirEditor
-      initialContent={content}
-      onContentChange={handleContentChange}
-    />
+    <LumirEditor initialContent={content} onContentChange={handleChange} />
   );
 }
 ```
 
 ---
 
-## 🎨 스타일링 가이드
-
-### 기본 CSS 구조
-
-```css
-/* 메인 컨테이너 - 슬래시 메뉴 오버플로우 허용 */
-.lumirEditor {
-  width: 100%;
-  height: 100%;
-  min-width: 200px;
-  overflow: visible; /* 슬래시 메뉴가 컨테이너를 넘어 표시되도록 */
-  background-color: #ffffff;
-}
-
-/* 에디터 내부 콘텐츠 영역 스크롤 */
-.lumirEditor .bn-container {
-  overflow: auto;
-  max-height: 100%;
-}
-
-/* 슬래시 메뉴 z-index 보장 */
-.bn-suggestion-menu,
-.bn-slash-menu,
-.mantine-Menu-dropdown,
-.mantine-Popover-dropdown {
-  z-index: 9999 !important;
-}
-
-/* 에디터 내용 영역 */
-.lumirEditor .bn-editor {
-  font-family: "Pretendard", "Noto Sans KR", -apple-system, sans-serif;
-  padding: 5px 10px 0 25px;
-}
-
-/* 문단 블록 */
-.lumirEditor [data-content-type="paragraph"] {
-  font-size: 14px;
-}
-```
+## 🎨 스타일링
 
 ### Tailwind CSS와 함께 사용
 
@@ -605,14 +432,14 @@ import { LumirEditor, cn } from "@lumir-company/editor";
 />;
 ```
 
-### 커스텀 스타일 적용
+### 커스텀 스타일
 
 ```css
 /* globals.css */
 .my-editor .bn-editor {
-  padding-left: 30px;
-  padding-right: 20px;
+  padding: 20px 30px;
   font-size: 16px;
+  line-height: 1.6;
 }
 
 .my-editor [data-content-type="heading"] {
@@ -627,37 +454,37 @@ import { LumirEditor, cn } from "@lumir-company/editor";
 
 ---
 
-## ⚠️ 주의사항 및 트러블슈팅
+## ⚠️ 트러블슈팅
 
 ### 필수 체크리스트
 
-| 항목                 | 체크                                        |
-| -------------------- | ------------------------------------------- |
-| CSS 임포트           | `import "@lumir-company/editor/style.css";` |
-| 컨테이너 높이 설정   | 부모 요소에 높이 지정 필수                  |
-| Next.js SSR 비활성화 | `dynamic(..., { ssr: false })` 사용         |
-| React 버전           | 18.0.0 이상 필요                            |
+- [ ] CSS 임포트: `import "@lumir-company/editor/style.css"`
+- [ ] 컨테이너 높이 설정: 부모 요소에 높이 지정 필수
+- [ ] Next.js: `dynamic(..., { ssr: false })` 사용
+- [ ] React 버전: 18.0.0 이상
 
-### 일반적인 문제 해결
+### 자주 발생하는 문제
 
-#### 1. 에디터가 렌더링되지 않음
+#### 1. 에디터가 보이지 않음
 
 ```tsx
-// ❌ 잘못된 사용
+// ❌ 잘못됨
 <LumirEditor />;
 
-// ✅ 올바른 사용 - CSS 임포트 필요
+// ✅ 올바름
 import "@lumir-company/editor/style.css";
-<LumirEditor />;
+<div className="h-[400px]">
+  <LumirEditor />
+</div>;
 ```
 
-#### 2. Next.js에서 hydration 오류
+#### 2. Next.js Hydration 오류
 
 ```tsx
-// ❌ 잘못된 사용
+// ❌ 잘못됨
 import { LumirEditor } from "@lumir-company/editor";
 
-// ✅ 올바른 사용 - dynamic import 사용
+// ✅ 올바름
 const LumirEditor = dynamic(
   () =>
     import("@lumir-company/editor").then((m) => ({ default: m.LumirEditor })),
@@ -665,78 +492,85 @@ const LumirEditor = dynamic(
 );
 ```
 
-#### 3. 높이가 0으로 표시됨
+#### 3. 이미지 업로드 실패
 
 ```tsx
-// ❌ 잘못된 사용
-<LumirEditor />
-
-// ✅ 올바른 사용 - 부모 요소에 높이 설정
-<div className="h-[400px]">
-  <LumirEditor />
-</div>
+// uploadFile 또는 s3Upload 중 하나는 반드시 설정!
+<LumirEditor
+  s3Upload={{
+    apiEndpoint: "/api/s3/presigned",
+    env: "development",
+    path: "images",
+  }}
+/>
 ```
 
-#### 4. 이미지 업로드 실패
+#### 4. 여러 이미지 업로드 시 중복 문제
 
 ```tsx
-// uploadFile 또는 s3Upload 중 하나 반드시 설정
+// ✅ 해결: appendUUID 사용
 <LumirEditor
-  uploadFile={async (file) => {
-    // 업로드 로직
-    return imageUrl;
-  }}
-  // 또는
   s3Upload={{
     apiEndpoint: "/api/s3/presigned",
-    env: "development",
+    env: "production",
     path: "images",
+    appendUUID: true, // 고유한 파일명 보장
   }}
 />
 ```
 
-### 성능 최적화 팁
+---
 
-1. **애니메이션 기본 비활성**: 이미 `animations: false`로 설정되어 성능 최적화됨
-2. **큰 콘텐츠 처리**: 초기 콘텐츠가 클 경우 lazy loading 고려
-3. **이미지 최적화**: 업로드 전 클라이언트에서 이미지 리사이징 권장
+## 🛠️ 유틸리티 API
 
----
+### ContentUtils
 
-## 🏗️ 프로젝트 구조
-
-```
-@lumir-company/editor/
-├── dist/                    # 빌드 출력
-│   ├── index.js            # CommonJS 빌드
-│   ├── index.mjs           # ESM 빌드
-│   ├── index.d.ts          # TypeScript 타입 정의
-│   └── style.css           # 스타일시트
-├── src/
-│   ├── components/
-│   │   └── LumirEditor.tsx # 메인 에디터 컴포넌트
-│   ├── types/
-│   │   ├── editor.ts       # 에디터 타입 정의
-│   │   └── index.ts        # 타입 export
-│   ├── utils/
-│   │   ├── cn.ts           # className 유틸리티
-│   │   └── s3-uploader.ts  # S3 업로더
-│   ├── index.ts            # 메인 export
-│   └── style.css           # 소스 스타일
-└── examples/
-    └── tailwind-integration.md  # Tailwind 통합 가이드
+```tsx
+import { ContentUtils } from "@lumir-company/editor";
+
+// JSON 검증
+ContentUtils.isValidJSONString('[{"type":"paragraph"}]'); // true
+
+// JSON 파싱
+const blocks = ContentUtils.parseJSONContent(jsonString);
+
+// 기본 블록 생성
+const emptyBlock = ContentUtils.createDefaultBlock();
 ```
 
----
+### createS3Uploader
 
-## 📄 라이선스
+```tsx
+import { createS3Uploader } from "@lumir-company/editor";
 
-MIT License
+const uploader = createS3Uploader({
+  apiEndpoint: "/api/s3/presigned",
+  env: "production",
+  path: "uploads",
+  appendUUID: true,
+});
 
----
+// 직접 사용
+const url = await uploader(imageFile);
+```
 
 ## 🔗 관련 링크
 
-- [GitHub Repository](https://github.com/lumir-company/editor)
 - [npm Package](https://www.npmjs.com/package/@lumir-company/editor)
 - [BlockNote Documentation](https://www.blocknotejs.org/)
+
+---
+
+## 📝 변경 로그
+
+### v0.4.0
+
+- ✨ 파일명 변환 콜백 (`fileNameTransform`) 추가
+- ✨ UUID 자동 추가 옵션 (`appendUUID`) 추가
+- 🐛 여러 이미지 동시 업로드 시 중복 문제 해결
+- 📝 문서 대폭 개선
+
+### v0.3.3
+
+- 🐛 에디터 재생성 방지 최적화
+- 📝 타입 정의 개선