@zm-editor/react 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,260 @@
+# @zm-editor/react
+
+[Tiptap](https://tiptap.dev) 기반의 Notion 스타일 리치 텍스트 에디터 React 컴포넌트입니다.
+
+[![npm version](https://img.shields.io/npm/v/@zm-editor/react.svg)](https://www.npmjs.com/package/@zm-editor/react)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+[English](./README.md) | **한국어**
+
+## 주요 기능
+
+- **Notion 스타일 UX** - 슬래시 명령어, 버블 메뉴, 드래그 앤 드롭 블록
+- **35+ 슬래시 명령어** - 제목, 목록, 코드 블록, 테이블 등
+- **28+ 커스텀 블록** - 이미지, 임베드, 콜아웃, 다이어그램, API 블록 등
+- **구문 강조** - 26개 이상 언어 지원 (GitHub Dark 테마)
+- **Mermaid 다이어그램** - 플로우차트, 시퀀스 다이어그램, 마인드맵
+- **수학 수식** - KaTeX LaTeX 렌더링
+- **다국어 지원** - 한국어 & 영어 내장
+- **다크 모드** - 완전한 다크 모드 지원
+- **TypeScript** - 완전한 타입 정의 포함
+
+## 설치
+
+```bash
+npm install @zm-editor/core @zm-editor/react
+```
+
+### 필수 의존성
+
+```bash
+npm install react react-dom
+```
+
+### 선택적 의존성
+
+```bash
+# Mermaid 다이어그램 (플로우차트, 시퀀스 다이어그램 등)
+npm install mermaid
+
+# 수학 수식 (LaTeX 렌더링)
+npm install katex
+
+# 파일 첨부의 PDF 미리보기
+npm install pdfjs-dist
+
+# HTML 새니타이징
+npm install dompurify
+```
+
+> **참고:** Mermaid와 KaTeX는 선택 사항입니다. 설치하지 않은 경우, 다이어그램이나 수식 블록 사용 시 설치 안내가 표시됩니다.
+
+## 빠른 시작
+
+```tsx
+'use client'; // Next.js App Router 필수
+
+import { ZmEditor } from '@zm-editor/react';
+
+export default function MyEditor() {
+  return (
+    <ZmEditor
+      initialContent="<p>안녕하세요!</p>"
+      onChange={(editor) => {
+        console.log(editor.getJSON());
+      }}
+    />
+  );
+}
+```
+
+## Next.js 사용법
+
+Next.js App Router에서는 SSR 문제를 피하기 위해 동적 import를 사용하세요:
+
+```tsx
+'use client';
+
+import dynamic from 'next/dynamic';
+
+const ZmEditor = dynamic(
+  () => import('@zm-editor/react').then((mod) => mod.ZmEditor),
+  { ssr: false }
+);
+
+export default function EditorWrapper() {
+  return <ZmEditor />;
+}
+```
+
+## Props
+
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `initialContent` | `string \| JSONContent` | `''` | 초기 에디터 콘텐츠 (HTML 또는 JSON) |
+| `onChange` | `(editor: Editor) => void` | - | 콘텐츠 변경 시 콜백 |
+| `onImageUpload` | `(file: File) => Promise<string>` | - | 커스텀 이미지 업로드 핸들러 |
+| `locale` | `ZmEditorLocale` | `enLocale` | 다국어 설정 |
+| `editable` | `boolean` | `true` | 편집 가능/불가 설정 |
+| `placeholder` | `string` | - | 플레이스홀더 텍스트 |
+| `className` | `string` | - | 추가 CSS 클래스 |
+
+## 슬래시 명령어
+
+`/`를 입력하면 명령어 메뉴가 열립니다:
+
+| 명령어 | 설명 |
+|--------|------|
+| `/text` | 일반 텍스트 |
+| `/h1`, `/h2`, `/h3` | 제목 |
+| `/bullet` | 글머리 기호 목록 |
+| `/number` | 번호 목록 |
+| `/task` | 할 일 목록 (체크리스트) |
+| `/quote` | 인용문 |
+| `/code` | 구문 강조 코드 블록 |
+| `/table` | 테이블 (3x3) |
+| `/image` | 이미지 업로드 |
+| `/file` | 파일 첨부 |
+| `/embed` | 임베드 (YouTube, CodeSandbox, StackBlitz, Replit) |
+| `/callout` | 콜아웃 (info, warning, error, success, tip, note) |
+| `/toggle` | 토글 (접기/펼치기) |
+| `/mermaid` | Mermaid 다이어그램 |
+| `/math` | 수학 수식 (LaTeX) |
+| `/terminal` | 터미널 블록 |
+| `/api` | API 요청/응답 블록 |
+| `/divider` | 구분선 |
+| `/toc` | 목차 |
+| ... | 그 외 15개 이상 |
+
+## 다국어 설정 (i18n)
+
+```tsx
+import { ZmEditor, koLocale, enLocale } from '@zm-editor/react';
+
+// 한국어
+<ZmEditor locale={koLocale} />
+
+// 영어 (기본값)
+<ZmEditor locale={enLocale} />
+
+// 커스텀
+<ZmEditor
+  locale={{
+    ...koLocale,
+    editor: {
+      placeholder: '내용을 입력하세요...',
+    },
+  }}
+/>
+```
+
+## 커스텀 이미지 업로드
+
+```tsx
+<ZmEditor
+  onImageUpload={async (file) => {
+    const formData = new FormData();
+    formData.append('file', file);
+
+    const response = await fetch('/api/upload', {
+      method: 'POST',
+      body: formData,
+    });
+
+    const { url } = await response.json();
+    return url;
+  }}
+/>
+```
+
+## 콘텐츠 내보내기
+
+```tsx
+import { useRef } from 'react';
+import { ZmEditor, type ZmEditorRef } from '@zm-editor/react';
+
+function MyEditor() {
+  const editorRef = useRef<ZmEditorRef>(null);
+
+  const handleExport = () => {
+    const editor = editorRef.current?.editor;
+    if (!editor) return;
+
+    const json = editor.getJSON();  // JSON 형식
+    const html = editor.getHTML();  // HTML 형식
+    const text = editor.getText();  // 텍스트 형식
+  };
+
+  return (
+    <>
+      <ZmEditor ref={editorRef} />
+      <button onClick={handleExport}>내보내기</button>
+    </>
+  );
+}
+```
+
+## 테마 커스터마이징
+
+### 스타일 가져오기
+
+```tsx
+import '@zm-editor/react/styles.css';
+```
+
+### CSS 변수로 커스터마이징
+
+```css
+:root {
+  /* 기본 색상 */
+  --zm-colors-primary: #8b5cf6;
+  --zm-colors-primary-hover: #7c3aed;
+
+  /* 에디터 배경 & 텍스트 */
+  --zm-colors-editor-background: #ffffff;
+  --zm-colors-editor-text: #374151;
+  --zm-colors-editor-border: #e5e7eb;
+}
+
+/* 다크 모드 */
+.dark,
+[data-theme='dark'] {
+  --zm-colors-primary: #a78bfa;
+  --zm-colors-editor-background: #1f2937;
+  --zm-colors-editor-text: #d1d5db;
+}
+```
+
+### 다크 모드 지원
+
+zm-editor는 다음 방식의 다크 모드를 자동 지원합니다:
+- `.dark` 클래스 (Tailwind CSS / next-themes)
+- `[data-theme="dark"]` 속성
+- `@media (prefers-color-scheme: dark)` 시스템 설정
+
+## 브라우저 지원
+
+- Chrome (최신)
+- Firefox (최신)
+- Safari (최신)
+- Edge (최신)
+
+## 요구 사항
+
+- React 18+
+- Node.js 18+
+
+## 관련 패키지
+
+| 패키지 | 설명 |
+|--------|------|
+| [@zm-editor/core](https://www.npmjs.com/package/@zm-editor/core) | 코어 Tiptap 확장 및 유틸리티 |
+
+## 링크
+
+- [GitHub 저장소](https://github.com/hanumoka/zm-editor)
+- [문서](https://github.com/hanumoka/zm-editor#readme)
+
+## 라이선스
+
+[MIT](https://github.com/hanumoka/zm-editor/blob/main/LICENSE)

package/README.md

@@ -0,0 +1,300 @@
+# @zm-editor/react
+
+React components for zm-editor - a Notion-style rich text editor built on [Tiptap](https://tiptap.dev).
+
+[![npm version](https://img.shields.io/npm/v/@zm-editor/react.svg)](https://www.npmjs.com/package/@zm-editor/react)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**English** | [한국어](./README.ko.md)
+
+## Features
+
+- **Notion-like UX** - Slash commands, bubble menu, drag & drop blocks
+- **35+ Slash Commands** - Headings, lists, code blocks, tables, and more
+- **28+ Custom Blocks** - Images, embeds, callouts, diagrams, API blocks, etc.
+- **Syntax Highlighting** - 26+ languages with GitHub Dark theme
+- **Mermaid Diagrams** - Flowcharts, sequence diagrams, mindmaps
+- **Math Equations** - KaTeX LaTeX rendering
+- **i18n Support** - English & Korean built-in
+- **Dark Mode** - Full dark mode support
+- **TypeScript** - Full type definitions included
+
+## Installation
+
+```bash
+npm install @zm-editor/core @zm-editor/react
+```
+
+### Peer Dependencies
+
+```bash
+npm install react react-dom
+```
+
+### Optional Dependencies
+
+```bash
+# For Mermaid diagrams (flowcharts, sequence diagrams, etc.)
+npm install mermaid
+
+# For Math equations (LaTeX rendering)
+npm install katex
+
+# For PDF preview in file attachments
+npm install pdfjs-dist
+
+# For HTML sanitization
+npm install dompurify
+```
+
+> **Note:** Mermaid and KaTeX are optional. If not installed, the editor will display a helpful installation prompt when you try to use diagram or math blocks.
+
+## Quick Start
+
+```tsx
+'use client'; // Required for Next.js App Router
+
+import { ZmEditor } from '@zm-editor/react';
+
+export default function MyEditor() {
+  return (
+    <ZmEditor
+      initialContent="<p>Hello, world!</p>"
+      onChange={(editor) => {
+        console.log(editor.getJSON());
+      }}
+    />
+  );
+}
+```
+
+## Usage with Next.js
+
+For Next.js App Router, use dynamic import to avoid SSR issues:
+
+```tsx
+'use client';
+
+import dynamic from 'next/dynamic';
+
+const ZmEditor = dynamic(
+  () => import('@zm-editor/react').then((mod) => mod.ZmEditor),
+  { ssr: false }
+);
+
+export default function EditorWrapper() {
+  return <ZmEditor />;
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `initialContent` | `string \| JSONContent` | `''` | Initial editor content (HTML or JSON) |
+| `onChange` | `(editor: Editor) => void` | - | Callback when content changes |
+| `onImageUpload` | `(file: File) => Promise<string>` | - | Custom image upload handler |
+| `locale` | `ZmEditorLocale` | `enLocale` | Locale for i18n |
+| `editable` | `boolean` | `true` | Enable/disable editing |
+| `placeholder` | `string` | - | Placeholder text |
+| `className` | `string` | - | Additional CSS class |
+
+## Slash Commands
+
+Type `/` to open the command menu:
+
+| Command | Description |
+|---------|-------------|
+| `/text` | Plain text paragraph |
+| `/h1`, `/h2`, `/h3` | Headings |
+| `/bullet` | Bullet list |
+| `/number` | Numbered list |
+| `/task` | Task list (checklist) |
+| `/quote` | Blockquote |
+| `/code` | Code block with syntax highlighting |
+| `/table` | Table (3x3) |
+| `/image` | Image upload |
+| `/file` | File attachment |
+| `/embed` | Embed (YouTube, CodeSandbox, StackBlitz, Replit) |
+| `/callout` | Callout box (info, warning, error, success, tip, note) |
+| `/toggle` | Toggle (collapsible content) |
+| `/mermaid` | Mermaid diagram |
+| `/math` | Math equation (LaTeX) |
+| `/terminal` | Terminal block |
+| `/api` | API request/response block |
+| `/divider` | Horizontal rule |
+| `/toc` | Table of contents |
+| `/error` | Error/warning/info message |
+| `/os` | OS-specific commands (macOS/Linux/Windows) |
+| `/changelog` | Version changelog |
+| `/env` | Environment variables (with masking) |
+| `/gist` | GitHub Gist embed |
+| `/diff` | Code diff block |
+| `/footnote` | Footnote |
+| `/log` | Log block (debug/info/warn/error) |
+| `/stacktrace` | Stack trace block |
+| `/metadata` | Document metadata |
+| `/graphql` | GraphQL query block |
+| `/openapi` | OpenAPI/Swagger embed |
+| `/diagram` | PlantUML/D2 diagram |
+| `/emoji` | Emoji picker |
+
+## Internationalization (i18n)
+
+```tsx
+import { ZmEditor, koLocale, enLocale } from '@zm-editor/react';
+
+// Korean
+<ZmEditor locale={koLocale} />
+
+// English (default)
+<ZmEditor locale={enLocale} />
+
+// Custom locale
+<ZmEditor
+  locale={{
+    ...enLocale,
+    editor: {
+      placeholder: 'Start writing...',
+    },
+  }}
+/>
+```
+
+## Custom Image Upload
+
+```tsx
+<ZmEditor
+  onImageUpload={async (file) => {
+    const formData = new FormData();
+    formData.append('file', file);
+
+    const response = await fetch('/api/upload', {
+      method: 'POST',
+      body: formData,
+    });
+
+    const { url } = await response.json();
+    return url;
+  }}
+/>
+```
+
+## Export Content
+
+```tsx
+import { useRef } from 'react';
+import { ZmEditor, type ZmEditorRef } from '@zm-editor/react';
+
+function MyEditor() {
+  const editorRef = useRef<ZmEditorRef>(null);
+
+  const handleExport = () => {
+    const editor = editorRef.current?.editor;
+    if (!editor) return;
+
+    const json = editor.getJSON();
+    const html = editor.getHTML();
+    const text = editor.getText();
+  };
+
+  return (
+    <>
+      <ZmEditor ref={editorRef} />
+      <button onClick={handleExport}>Export</button>
+    </>
+  );
+}
+```
+
+## Theming & Customization
+
+zm-editor uses CSS custom properties (variables) for theming, making it easy to customize colors, spacing, and more.
+
+### Import Styles
+
+```tsx
+// Import in your layout or global CSS
+import '@zm-editor/react/styles.css';
+```
+
+### Customize with CSS Variables
+
+Override CSS variables to customize the editor appearance:
+
+```css
+/* In your global CSS */
+:root {
+  /* Primary colors */
+  --zm-colors-primary: #8b5cf6;
+  --zm-colors-primary-hover: #7c3aed;
+
+  /* Editor background & text */
+  --zm-colors-editor-background: #ffffff;
+  --zm-colors-editor-text: #374151;
+  --zm-colors-editor-border: #e5e7eb;
+
+  /* Menu colors */
+  --zm-colors-menu-background: #ffffff;
+  --zm-colors-menu-hover: #f3f4f6;
+  --zm-colors-menu-selected: #eff6ff;
+}
+
+/* Dark mode */
+.dark,
+[data-theme='dark'] {
+  --zm-colors-primary: #a78bfa;
+  --zm-colors-editor-background: #1f2937;
+  --zm-colors-editor-text: #d1d5db;
+  --zm-colors-editor-border: #374151;
+}
+```
+
+### Available CSS Variables
+
+| Category | Variables |
+|----------|-----------|
+| **Editor** | `--zm-colors-editor-background`, `--zm-colors-editor-text`, `--zm-colors-editor-border`, `--zm-colors-heading` |
+| **Menu** | `--zm-colors-menu-background`, `--zm-colors-menu-text`, `--zm-colors-menu-hover`, `--zm-colors-menu-selected` |
+| **Primary** | `--zm-colors-primary`, `--zm-colors-primary-hover`, `--zm-colors-primary-text` |
+| **Code** | `--zm-colors-code-background`, `--zm-colors-codeblock-background`, `--zm-colors-codeblock-text` |
+| **Status** | `--zm-colors-success`, `--zm-colors-warning`, `--zm-colors-error`, `--zm-colors-info` |
+| **Spacing** | `--zm-spacing-xs` (0.25rem), `--zm-spacing-sm` (0.5rem), `--zm-spacing-md` (1rem), `--zm-spacing-lg` (1.5rem) |
+| **Radius** | `--zm-radius-sm` (4px), `--zm-radius-md` (6px), `--zm-radius-lg` (8px) |
+| **Typography** | `--zm-font-family-sans`, `--zm-font-family-mono`, `--zm-font-size-*` |
+
+See `variables.css` for the complete list of available variables.
+
+### Dark Mode Support
+
+zm-editor automatically supports dark mode via:
+- `.dark` class (Tailwind CSS / next-themes)
+- `[data-theme="dark"]` attribute
+- `@media (prefers-color-scheme: dark)` system preference
+
+## Browser Support
+
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
+
+## Requirements
+
+- React 18+
+- Node.js 18+
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [@zm-editor/core](https://www.npmjs.com/package/@zm-editor/core) | Core Tiptap extensions and utilities |
+
+## Links
+
+- [GitHub Repository](https://github.com/hanumoka/zm-editor)
+- [Documentation](https://github.com/hanumoka/zm-editor#readme)
+
+## License
+
+[MIT](https://github.com/hanumoka/zm-editor/blob/main/LICENSE)