@ihsanabuhanifah/react-math-editor 1.0.0 → 1.1.0

package/README.md

@@ -1,71 +1,79 @@
 # @ihsanabuhanifah/react-math-editor
 
-Komponen Rich Text Editor & Math Viewer modern untuk React. Ditenagai oleh **Tiptap** dan **KaTeX**, dirancang untuk mengetik soal, materi ujian, formula matematika LaTeX, tabel responsif, dan sintaks kode secara visual dan instan.
+[![npm version](https://img.shields.io/npm/v/@ihsanabuhanifah/react-math-editor.svg?color=blue)](https://www.npmjs.com/package/@ihsanabuhanifah/react-math-editor)
+[![npm downloads](https://img.shields.io/npm/dm/@ihsanabuhanifah/react-math-editor.svg)](https://www.npmjs.com/package/@ihsanabuhanifah/react-math-editor)
+[![license](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/ihsanabuhanifah)
+[![React](https://img.shields.io/badge/React-18%20%7C%2019-61dafb.svg)](https://react.dev)
 
-[![npm version](https://img.shields.io/badge/npm-v1.0.0-blue.svg)](https://www.npmjs.com/)
-[![license](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+A modern, lightweight Rich Text Editor and Math Viewer component for React. Powered by **Tiptap**, **KaTeX**, and **highlight.js**.
+
+Designed specifically for educational platforms, exam builders (CBT), question banks, technical documentation, and math blogging.
 
 ---
 
-## ✨ Fitur Utama
+## ✨ Features
 
-- 📐 **Formula Matematika LaTeX Interaktif:** Dialog penulisan rumus dengan pratinjau instan (*live KaTeX preview*) dan klik langsung untuk mengedit rumus yang sudah ada.
-- 📘 **Kamus Rumus LaTeX:** Cheat sheet terintegrasi lengkap dengan berbagai kategori (Aljabar, Trigonometri, Kalkulus, Matriks, Logika).
-- 📊 **Tabel Responsif:** Sisipkan tabel, tambah/hapus baris & kolom secara visual.
-- 📋 **Auto-convert Markdown Table:** Copy-paste tabel teks markdown dari AI (ChatGPT, DeepSeek, Claude) langsung otomatis diubah menjadi tabel HTML.
-- 💻 **Blok Kode & Highlighting:** Syntax highlighting otomatis untuk berbagai bahasa pemrograman menggunakan `highlight.js`.
-- 🖼️ **Upload Gambar Fleksibel:** Integrasikan dengan backend apa pun (AWS S3, Cloudflare R2, Supabase, Laravel, Express) via callback `onUploadImage`.
-- 🎨 **Styles Mandiri:** File CSS terisolasi (`style.css`), tidak memerlukan konfigurasi Tailwind eksternal.
-- 👁️ **RenderMathHTML Viewer:** Komponen terpisah untuk menampilkan output konten dengan perenderan KaTeX dan tabel responsif.
+- 🧠 **SmartContentEditor Included:** Advanced editor supporting resizable & alignable images (25%, 50%, 75%, 100%), document attachments, YouTube video embeds, and AI paste modal.
+- 📐 **Interactive LaTeX Math Formulas:** Popup dialog with live KaTeX preview. Click any formula chip inside the editor to edit it seamlessly.
+- 📘 **Built-in Formula Cheat Sheet:** Comprehensive LaTeX dictionary covering Algebra, Trigonometry, Calculus, Matrices, and Logic.
+- 📊 **Rich Table Support:** Insert tables (3x3), visually add/remove rows and columns, delete tables.
+- 📋 **Auto-convert Markdown Tables:** Copy-paste markdown tables from AI assistants (ChatGPT, Claude, DeepSeek) and they automatically convert into interactive HTML tables.
+- 🤖 **Smart AI Paste:** Dedicated modal & paste listener that formats markdown from AI into clean visual Tiptap nodes.
+- 🎥 **YouTube & Attachment Embeds:** Embed responsive 16:9 YouTube videos and downloadable document attachments.
+- 💻 **Syntax Highlighted Code Blocks:** Pre-configured code blocks with syntax highlighting using `highlight.js`.
+- 🖼️ **Vendor-Agnostic Uploads:** Async callback props (`onUploadImage`, `onUploadFile`) connect to any storage backend.
+- 🎨 **Self-Contained Styling:** Bundled standalone CSS (`style.css`), no TailwindCSS setup required on the consumer application.
+- 👁️ **RenderMathHTML Viewer:** Companion lightweight component to safely render and display saved HTML content.
 
 ---
 
-## 📦 Instalasi
-
-Install paket ini melalui package manager favorit Anda:
+## 📦 Installation
 
 ```bash
 npm install @ihsanabuhanifah/react-math-editor
-# atau
+```
+```bash
 yarn add @ihsanabuhanifah/react-math-editor
-# atau
+```
+```bash
 pnpm add @ihsanabuhanifah/react-math-editor
 ```
 
-Pastikan juga `react` dan `react-dom` versi 18 atau 19 sudah terpasang di project Anda.
+> **Peer Dependencies:** Ensure `react` and `react-dom` (>= 18.0.0) are installed in your project.
 
 ---
 
-## 🚀 Panduan Penggunaan
+## 🚀 Quick Start
 
-### 1. Menggunakan Editor (`TextEditor`)
+### 1. The Editor (`TextEditor`)
 
 ```tsx
 import React, { useState } from "react";
 import { TextEditor } from "@ihsanabuhanifah/react-math-editor";
-import "@ihsanabuhanifah/react-math-editor/dist/style.css"; // Wajib diimport sekali
+import "@ihsanabuhanifah/react-math-editor/dist/style.css"; // Import CSS once
 
-export function FormInputSoal() {
-  const [content, setContent] = useState("<p>Tentukan nilai dari $x^2 + 5x + 6 = 0$!</p>");
+export function QuestionForm() {
+  const [content, setContent] = useState("<p>Solve for $x$: $x^2 - 5x + 6 = 0$</p>");
 
   return (
-    <div style={{ maxWidth: 800, margin: "0 auto" }}>
+    <div style={{ maxWidth: 800, margin: "20px auto" }}>
+      <h2>Create Question</h2>
       <TextEditor
         value={content}
         onChange={(html) => setContent(html)}
-        placeholder="Ketik soal, rumus matematika, atau sisipkan tabel..."
-        minHeight={200}
-        // Handler upload gambar ke server Anda:
-        onUploadImage={async (file) => {
+        placeholder="Type questions, insert LaTeX math formulas, or paste tables..."
+        minHeight={220}
+        onUploadImage={async (file: File) => {
+          // Upload to your backend server / S3
           const formData = new FormData();
-          formData.append("image", file);
+          formData.append("file", file);
 
-          const res = await fetch("/api/upload", {
+          const response = await fetch("/api/upload", {
             method: "POST",
             body: formData,
           });
-          const data = await res.json();
-          return data.url; // Harus mengembalikan string URL gambar
+          const result = await response.json();
+          return result.url; // Must return the image URL string
         }}
       />
     </div>
@@ -75,19 +83,19 @@ export function FormInputSoal() {
 
 ---
 
-### 2. Menampilkan Hasil Konten (`RenderMathHTML`)
+### 2. The Content Viewer (`RenderMathHTML`)
 
-Komponen ini digunakan di halaman preview, ujian siswa, artikel, atau detail soal:
+Use `RenderMathHTML` wherever you need to display the formatted content to students or readers (e.g., exam page, preview card, blog post):
 
 ```tsx
 import React from "react";
 import { RenderMathHTML } from "@ihsanabuhanifah/react-math-editor";
 import "@ihsanabuhanifah/react-math-editor/dist/style.css";
 
-export function DetailSoal({ soalHtml }: { soalHtml: string }) {
+export function QuestionCard({ htmlContent }: { htmlContent: string }) {
   return (
-    <div className="card-soal">
-      <RenderMathHTML html={soalHtml} />
+    <div className="card">
+      <RenderMathHTML html={htmlContent} />
     </div>
   );
 }
@@ -95,82 +103,49 @@ export function DetailSoal({ soalHtml }: { soalHtml: string }) {
 
 ---
 
-## 🛠️ API & Props Reference
+## ⚙️ API & Props Reference
 
 ### `<TextEditor />`
 
-| Prop | Tipe | Default | Deskripsi |
+| Prop | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `value` | `string` | `""` | Konten HTML input awal |
-| `onChange` | `(html: string) => void` | `undefined` | Callback saat isi editor berubah |
-| `placeholder` | `string` | `"Tulis konten..."` | Teks placeholder saat editor kosong |
-| `disabled` | `boolean` | `false` | Menonaktifkan interaksi editor |
-| `readOnly` | `boolean` | `false` | Sembunyikan toolbar dan jadikan read-only |
-| `minHeight` | `number \| string` | `140` | Tinggi minimum area ketik (px atau css string) |
-| `maxHeight` | `number \| string` | `600` | Tinggi maksimum sebelum scroll |
-| `onUploadImage` | `(file: File) => Promise<string>` | `undefined` | Fungsi async pengunggah gambar |
-| `toolbarExtra` | `React.ReactNode` | `undefined` | Slot tombol tambahan di kanan toolbar |
-| `className` | `string` | `""` | Kelas CSS tambahan pada container |
+| `value` | `string` | `""` | Initial HTML string content |
+| `onChange` | `(html: string) => void` | `undefined` | Callback fired on content change with updated HTML |
+| `placeholder` | `string` | `"Tulis konten..."` | Placeholder text when editor is empty |
+| `disabled` | `boolean` | `false` | Disables user interaction |
+| `readOnly` | `boolean` | `false` | Read-only mode without toolbar |
+| `minHeight` | `number \| string` | `140` | Minimum height for editing area (px or CSS string) |
+| `maxHeight` | `number \| string` | `600` | Maximum height before scrolling |
+| `onUploadImage` | `(file: File) => Promise<string>` | `undefined` | Async handler to upload images; returns the URL |
+| `toolbarExtra` | `React.ReactNode` | `undefined` | Slot for custom action buttons in the toolbar |
+| `className` | `string` | `""` | Additional CSS class names for outer container |
 
 ### `<RenderMathHTML />`
 
-| Prop | Tipe | Default | Deskripsi |
+| Prop | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `html` | `string` | `""` | String HTML yang akan dirender |
-| `className` | `string` | `""` | Kelas CSS kustom untuk container |
-| `style` | `React.CSSProperties` | `undefined` | Objek inline style container |
-| `resolveImageUrl` | `(url: string) => Promise<string> \| string` | `undefined` | Resolver opsional untuk URL gambar presigned/private |
+| `html` | `string` | `""` | HTML string containing text, math, or tables to render |
+| `className` | `string` | `""` | Additional CSS class for viewer container |
+| `style` | `React.CSSProperties` | `undefined` | Inline styling for viewer container |
+| `resolveImageUrl` | `(url: string) => Promise<string> \| string` | `undefined` | Optional resolver for private / signed image URLs |
 
 ---
 
-## 🌐 Cara Publikasi ke GitHub & NPM
-
-### A. Publish ke NPM Registry
-1. Masuk ke folder library:
-   ```bash
-   cd packages/react-math-editor
-   ```
-2. Build bundle produksi:
-   ```bash
-   npm run build
-   ```
-3. Login ke akun NPM Anda (jika belum):
-   ```bash
-   npm login
-   ```
-4. Publikasikan paket:
-   ```bash
-   npm publish --access public
-   ```
-
-### B. Simpan di GitHub Repository
-Anda bisa membuat repository baru di GitHub (misal `https://github.com/username/react-math-editor`):
-```bash
-cd packages/react-math-editor
-git init
-git add .
-git commit -m "feat: initial release of react-math-editor"
-git branch -M main
-git remote add origin https://github.com/username/react-math-editor.git
-git push -u origin main
-```
+## 💡 Framework Support
 
-Setelah dipush ke GitHub, Anda bahkan bisa langsung menginstallnya di project lain tanpa harus publish ke NPM:
-```bash
-npm install git+https://github.com/username/react-math-editor.git
-```
+### Next.js (App Router / Pages Router)
+Because KaTeX and Tiptap interact with the browser DOM, wrap `TextEditor` with `'use client'` or dynamic import if using Server Components:
 
-### C. Testing Lokal Tanpa Publish (`npm pack`)
-Jalankan di folder library:
-```bash
-npm pack
-```
-Perintah ini akan menghasilkan file seperti `luvie-react-math-editor-1.0.0.tgz`. Di aplikasi lain, cukup jalankan:
-```bash
-npm install /path/ke/luvie-react-math-editor-1.0.0.tgz
+```tsx
+'use client';
+import { TextEditor } from "@ihsanabuhanifah/react-math-editor";
+import "@ihsanabuhanifah/react-math-editor/dist/style.css";
 ```
 
+### Vite / Create React App / Remix
+Works directly out of the box. Simply import the component and the stylesheet.
+
 ---
 
-## 📄 Lisensi
-[MIT License](LICENSE) © 2026
+## 📄 License
+MIT © [Ihsan Abu Hanifah](https://github.com/ihsanabuhanifah)

package/dist/components/SmartContentEditor.d.ts

@@ -0,0 +1,27 @@
+import { default as React } from 'react';
+
+export declare let lastActiveSmartEditor: any;
+export declare function setLastActiveSmartEditor(ed: any): void;
+export declare function getLastActiveSmartEditor(): any;
+export declare function parseYouTubeEmbedUrl(url: string): string | null;
+export declare function convertAiMarkdownToTipTapHtml(markdown: string): string;
+export interface SmartContentEditorProps {
+    value: string;
+    handleChange?: (html: string) => void;
+    onChange?: (html: string) => void;
+    readOnly?: boolean;
+    minHeight?: number;
+    placeholder?: string;
+    onUploadImage?: (file: File) => Promise<string>;
+    onUploadFile?: (file: File) => Promise<{
+        url: string;
+        name: string;
+        size?: string | number;
+    }>;
+    showMathGraph?: boolean;
+    onPreview?: () => void;
+    error?: string;
+    className?: string;
+}
+export declare function SmartContentEditor({ value, handleChange, onChange, readOnly, minHeight, placeholder, onUploadImage, onUploadFile, showMathGraph, onPreview, error, className, }: SmartContentEditorProps): React.JSX.Element;
+export default SmartContentEditor;