@yonailab/levit-react 0.0.0-stage → 0.4.0

package/README.md

@@ -1,3 +1,48 @@
-# Temporary Holding Version
+# @yonailab/levit-react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[Levit](https://github.com/azusawa/levit) 에디터의 React 컴포넌트입니다. React 18, 19를 지원합니다.
+
+```bash
+npm install @yonailab/levit @yonailab/levit-react
+```
+
+## 컴포넌트
+
+```tsx
+import { useState } from 'react';
+import { LevitEditor } from '@yonailab/levit-react';
+import { ko, type DocumentData } from '@yonailab/levit';
+import '@yonailab/levit/levit.css';
+
+export function Note() {
+  const [doc, setDoc] = useState<DocumentData>();
+  return <LevitEditor value={doc} onChange={setDoc} placeholder="메모를 입력하세요" messages={ko} />;
+}
+```
+
+- `value`와 `onChange`를 함께 쓰면 제어 컴포넌트, `defaultValue`만 쓰면 비제어 컴포넌트입니다.
+- `onChange`가 돌려준 값을 다시 `value`로 넘겨도 커서는 그대로입니다.
+- 에디터 옵션(`plugins`, `messages`, `uploadImage`, `highlightCode`, `onError` 등)을 그대로 props로 넘깁니다.
+- `bubbleMenu={false}`, `slashMenu={false}`로 메뉴를 끌 수 있습니다.
+- `ref`나 `onReady`로 에디터 인스턴스를 받습니다.
+- `'use client'`가 들어 있어 Next.js App Router에서 바로 쓸 수 있습니다.
+
+## 훅
+
+화면 구성을 직접 하려면 `useLevitEditor`를 씁니다.
+
+```tsx
+import { useLevitEditor } from '@yonailab/levit-react';
+
+function Editor() {
+  const { ref, editor } = useLevitEditor({ placeholder: '입력하세요' });
+  return (
+    <>
+      <button onClick={() => editor?.chain().toggleBold().run()}>굵게</button>
+      <div ref={ref} />
+    </>
+  );
+}
+```
+
+`editor`는 마운트 전에는 `null`입니다. 옵션은 에디터를 만들 때 한 번 읽고, 콜백은 항상 최신 것을 부릅니다.

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+import { type CSSProperties } from 'react';
+import { type DocumentData, type EditorOptions, type LevitEditor as Editor } from '@yonailab/levit';
+export type { Editor };
+/** Editor options, plus whether to add the bubble and slash menus. */
+export interface UseLevitEditorOptions extends Omit<EditorOptions, 'element'> {
+    /** Show the formatting toolbar on selected text. Default: true. */
+    bubbleMenu?: boolean;
+    /** Open the block menu with "/". Default: true. */
+    slashMenu?: boolean;
+    /** Called once the editor exists. */
+    onReady?: (editor: Editor) => void;
+}
+/**
+ * Creates a Levit editor on the element you attach `ref` to. The editor is
+ * made after mount (so this is safe in server rendering) and destroyed on
+ * unmount. Options are read when the editor is made; callbacks always call
+ * the latest version you passed.
+ */
+export declare function useLevitEditor(options?: UseLevitEditorOptions): {
+    ref: (element: HTMLElement | null) => void;
+    editor: Editor | null;
+};
+export interface LevitEditorProps extends Omit<UseLevitEditorOptions, 'initialContent' | 'onChange'> {
+    /** The document, for a controlled editor. Pass back what onChange gives you. */
+    value?: DocumentData;
+    /** The starting document, for an uncontrolled editor. */
+    defaultValue?: DocumentData;
+    /** Called with the document JSON after every change. */
+    onChange?: (value: DocumentData, editor: Editor) => void;
+    className?: string;
+    style?: CSSProperties;
+    id?: string;
+}
+/**
+ * A Levit editor with its menus. Use `defaultValue` for an uncontrolled
+ * editor, or `value` with `onChange` for a controlled one. The ref gives the
+ * editor instance.
+ */
+export declare const LevitEditor: import("react").ForwardRefExoticComponent<LevitEditorProps & import("react").RefAttributes<Editor | null>>;

package/dist/index.js

@@ -0,0 +1,66 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef, useCallback, useEffect, useImperativeHandle, useRef, useState, } from 'react';
+import { createBubbleMenu, createLevitEditor, createSlashMenu, sameContent, } from '@yonailab/levit';
+/**
+ * Creates a Levit editor on the element you attach `ref` to. The editor is
+ * made after mount (so this is safe in server rendering) and destroyed on
+ * unmount. Options are read when the editor is made; callbacks always call
+ * the latest version you passed.
+ */
+export function useLevitEditor(options = {}) {
+    const [element, setElement] = useState(null);
+    const [editor, setEditor] = useState(null);
+    const latest = useRef(options);
+    latest.current = options;
+    useEffect(() => {
+        if (!element)
+            return;
+        const { bubbleMenu = true, slashMenu = true, ...editorOptions } = latest.current;
+        const instance = createLevitEditor(element, {
+            ...editorOptions,
+            onChange: (ed) => latest.current.onChange?.(ed),
+            onSelectionChange: (selection) => latest.current.onSelectionChange?.(selection),
+            onError: (error) => {
+                if (latest.current.onError)
+                    latest.current.onError(error);
+                else
+                    console.error(error);
+            },
+        });
+        const menus = [bubbleMenu && createBubbleMenu(instance), slashMenu && createSlashMenu(instance)];
+        setEditor(instance);
+        latest.current.onReady?.(instance);
+        return () => {
+            for (const menu of menus)
+                if (menu)
+                    menu.destroy();
+            instance.destroy();
+            setEditor(null);
+        };
+    }, [element]);
+    return { ref: setElement, editor };
+}
+/**
+ * A Levit editor with its menus. Use `defaultValue` for an uncontrolled
+ * editor, or `value` with `onChange` for a controlled one. The ref gives the
+ * editor instance.
+ */
+export const LevitEditor = forwardRef(function LevitEditor({ value, defaultValue, onChange, className, style, id, ...options }, ref) {
+    const handleChange = useCallback((ed) => onChange?.(ed.getJSON(), ed), [onChange]);
+    const { ref: elementRef, editor } = useLevitEditor({
+        ...options,
+        initialContent: value ?? defaultValue,
+        onChange: handleChange,
+    });
+    useImperativeHandle(ref, () => editor, [editor]);
+    // A controlled value replaces the content only when it differs, so the
+    // value that comes back from onChange does not reset the caret.
+    useEffect(() => {
+        if (!editor || value === undefined)
+            return;
+        if (!sameContent(value, editor.getJSON()))
+            editor.setJSON(value);
+    }, [editor, value]);
+    return _jsx("div", { ref: elementRef, className: className, style: style, id: id });
+});

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@yonailab/levit-react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "description": "React components for the Levit editor.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "check:package": "node ../levit/scripts/check-package.mjs --wrapper",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build && npm run check:package"
+  },
+  "peerDependencies": {
+    "@yonailab/levit": "^0.4.0",
+    "react": ">=18"
+  },
+  "keywords": [
+    "editor",
+    "wysiwyg",
+    "rich-text",
+    "levit",
+    "react"
+  ],
+  "author": "yonailab",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/azusawa/levit.git",
+    "directory": "packages/react"
+  },
+  "homepage": "https://github.com/azusawa/levit/tree/main/packages/react#readme",
+  "bugs": {
+    "url": "https://github.com/azusawa/levit/issues"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1"
+  }
+}