@oix1987/yjd 2.0.0 → 2.1.1

package/README.md

@@ -5,8 +5,8 @@
 🔗 **[yjd.io](https://yjd.io)** · [Live playground](https://yjd.io/demos/) · [Docs](https://yjd.io/site/docs.html)
 
 ```js
-import RichEditor from '@oix1987/yjd';
-new RichEditor('#editor', { placeholder: 'Start writing…' });
+import yjd from '@oix1987/yjd';
+new yjd('#editor', { placeholder: 'Start writing…' });
 ```
 
 ---
@@ -45,7 +45,7 @@ Or via CDN (all-in-one UMD):
 ```html
 <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@oix1987/yjd/lib/styles.min.css">
 <script src="https://cdn.jsdelivr.net/npm/@oix1987/yjd"></script>
-<script> new RichEditor('#editor'); </script>
+<script> new yjd('#editor'); </script>
 ```
 
 ## Quick start (all-in-one)
@@ -53,14 +53,21 @@ Or via CDN (all-in-one UMD):
 The default build registers everything and injects its CSS:
 
 ```js
-import RichEditor from '@oix1987/yjd';
+import yjd from '@oix1987/yjd';   // `RichEditor` is kept as an alias
 
-const editor = new RichEditor('#editor', {
+const editor = new yjd('#editor', {
   placeholder: 'Start writing…',
   onChange: (html) => console.log(html),
 });
 ```
 
+Via `<script>` (UMD) the global is `yjd` (and `window.RichEditor` still works):
+
+```html
+<script src="https://unpkg.com/@oix1987/yjd"></script>
+<script>const editor = new yjd('#editor');</script>
+```
+
 ## Tree-shakeable core
 
 For the smallest bundle, import from `@oix1987/yjd/core` (side-effect-free) and register only what you need. Link the stylesheet once.
@@ -104,12 +111,139 @@ new Editor('#editor', {
 
 **Formats** — `bold` · `italic` · `underline` · `strike` · `subscript` · `superscript` · `color` · `background` · `link` · `heading` · `font-family` · `text-size` · `line-height` · `capitalization` · `text-align` · `list` · `indent-increase` · `indent-decrease` · `image` · `video` · `table` · `emoji` · `tag`
 
-**Modules** — `toolbar` · `history` · `slash-menu` · `block-toolbar` (bubble bar) · `table-toolbar` · `find-replace` · `code-view` · `resize-handles`
+**Modules** — `toolbar` · `history` · `slash-menu` · `mention` · `block-toolbar` (bubble bar) · `table-toolbar` · `find-replace` · `code-view` · `resize-handles`
 
 ## Methods
 
 `getHTML()` · `getText()` · `insertHTML(html)` · `insertText(t)` · `clear()` · `isEmpty()` · `focus()` · `setReadOnly(bool)` · `undo()` · `redo()`
 
+## Integration API
+
+Drop yjd into an existing app — upload images to your storage, tag people, store
+content in whatever format you already use, and progressively enhance `<textarea>`s.
+
+### Export / import (HTML · JSON · Markdown)
+
+```js
+editor.getHTML();      editor.setHTML(html);
+editor.getJSON();      editor.setJSON(json);     // { type: 'doc', content: [...] }
+editor.getMarkdown();  editor.setMarkdown(md);   // mention ids survive round-trips
+```
+
+Also exported standalone: `htmlToMarkdown`, `markdownToHtml`, `domToJson`, `jsonToHtml`.
+
+### Image upload hook
+
+Provide `image.upload` to send files to your server/CDN instead of inlining base64.
+Applies to every insert path — toolbar, paste, and drag-drop. A placeholder shows
+while uploading; the `src` is swapped on success, or the image is removed on failure.
+
+```js
+new yjd('#editor', {
+  image: {
+    upload: async (file) => (await api.upload(file)).url,   // return the URL
+    accept: 'image/png,image/jpeg,image/webp',
+    maxSize: 8 * 1024 * 1024,
+  },
+});
+// events: editor.on('image:upload'|'image:uploaded'|'image:error', cb)
+```
+
+Omit `upload` to keep the base64 fallback.
+
+### File attachments
+
+Like `image`, but for any file. Uploads via `file.upload` and inserts a **file chip**
+(icon + name + size) that serializes to a Markdown link `[name (size)](url)`. Works
+from the toolbar (`file` button), paste, and drag-drop.
+
+```js
+new yjd('#editor', {
+  toolbar1: [{ group: 'insert', items: ['image', 'file'] }],   // add the paperclip
+  file: {
+    upload: async (f) => ({ url: (await api.upload(f)).url, name: f.name }),
+    accept: '.pdf,.zip,.docx',
+    maxSize: 25 * 1024 * 1024,
+  },
+});
+// events: editor.on('file:upload' | 'file:uploaded' | 'file:error', cb)
+```
+
+### Enter-to-submit (comment boxes)
+
+```js
+new yjd('#comment', {
+  submit: {
+    onEnter: (html, editor) => post(html),   // Enter sends; Shift+Enter = newline
+  },
+});
+```
+
+When a mention/slash/emoji popup is open, Enter is left for the popup (it picks the
+item, doesn't submit). Check it yourself with `editor.isMenuOpen()`.
+
+### @mention / #task
+
+```js
+new yjd('#editor', {
+  mention: {
+    trigger: '@',
+    source: async (q) => fetchUsers(q),         // [{ id, name, avatar_url }]
+    renderItem: (u) => `<img src="${u.avatar_url}"> ${u.name}`,
+    triggers: [{ char: '#', source: (q) => fetchTasks(q) }],   // optional extra
+  },
+});
+editor.on('mention:select', (item) => { /* … */ });
+```
+
+Inserts a token that serializes with its id:
+`<span class="mention" data-id="u_123">@Ann</span>` → Markdown `@[Ann](u_123)`.
+If a `source` item has no `avatar_url`, pass `icon` (inline SVG) for special entries
+like “@all”. Menus are portaled to `<body>` but inherit the editor's `--rte-*` theme.
+
+### Toolbar presets
+
+```js
+toolbar: 'full'                    // the default set
+toolbar: 'compact'                 // bold/italic/underline · link · list · image · emoji
+toolbar: { exclude: ['table','video','color'] }   // defaults minus these
+toolbar1: [{ group, items: [...] }]               // or full custom groups
+```
+
+### fromTextarea (two-way + controller)
+
+Enhance an existing form field. Binding is **two-way**: editor edits update
+`textarea.value` (firing native `input`/`change`), and `textarea.value = …` from app
+code updates the editor. The returned editor carries a controller.
+
+```js
+const ed = yjd.fromTextarea('#body', { format: 'markdown' }); // or 'html'
+ed.setValue(md);   // load content
+ed.getValue();     // current content (per format)
+ed.destroy();      // remove editor, restore textarea + last value
+```
+
+### renderStatic
+
+Render stored HTML into a read-only view that matches the editor exactly (sanitized,
+tagged `.yjd-content`) — no editor instance needed. Load the stylesheet on the page.
+
+```js
+import { renderStatic } from '@oix1987/yjd';
+renderStatic(post.body_html, document.querySelector('#post'));
+```
+
+### Events & API notes
+
+- **Events** (via `editor.on(name, cb)` / `editor.off(name, cb)`): `change`,
+  `image:upload` · `image:uploaded` · `image:error`, `file:upload` · `file:uploaded`
+  · `file:error`, `mention:select`, `content:overflow` (when `maxContentSize` exceeded).
+- `editor.editor` is the public contentEditable element (attach your own listeners).
+- **Markdown dialect** — GFM-ish: headings `#`–`######`, `**bold**`, `*italic*`,
+  `~~strike~~`, `` `code` ``, fenced ``` ``` ```, `>` quotes, `-`/`1.` lists,
+  pipe tables, `![alt](src)` images, `[text](url)` links, mentions `@[Name](id)` /
+  `#[Name](id)`, file chips `[name (size)](url)`.
+
 ## Styling
 
 Theme via CSS custom properties:

package/core.js

@@ -61,6 +61,7 @@ export { default as TableToolbar } from './lib/modules/table-toolbar.js';
 export { default as CodeView } from './lib/modules/code-view.js';
 export { default as FindReplace } from './lib/modules/find-replace.js';
 export { default as SlashMenu } from './lib/modules/slash-menu.js';
+export { default as Mention } from './lib/modules/mention.js';
 export { default as ResizeHandles } from './lib/modules/resize-handles.js';
 
 // UI
@@ -75,3 +76,7 @@ export { default as ImagePopup } from './lib/ui/image-popup.js';
 export { default as VideoPopup } from './lib/ui/video-popup.js';
 export { default as TagPopup } from './lib/ui/tag-popup.js';
 export { default as createCustomButton } from './lib/ui/select-button.js';
+
+// Static rendering + serialization helpers
+export { renderStatic } from './lib/static.js';
+export { htmlToMarkdown, markdownToHtml, domToJson, jsonToHtml } from './lib/serialize.js';