npm - @jenkin-a/jeditor - Versions diffs - 1.0.1 → 1.0.4 - Mend

@jenkin-a/jeditor 1.0.1 → 1.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/README.en.md CHANGED Viewed

@@ -2,34 +2,281 @@
 Language: English | [中文](README.md)
-Current version: v1.0.1
+Current version: `v1.0.2`
-JEditor is a lightweight rich-text editor built on Tiptap. It uses a plugin-driven toolbar architecture and exposes a simple DOM API (`JEditor.create`). In v1.0.1, two key capabilities are added:
+JEditor is a web rich text editor for document writing, static fragment authoring, and Source HTML editing. It started as a Tiptap-based editor, but the current version is already more than a simple “toolbar + Tiptap wrapper”. It is evolving into a hybrid editing architecture that supports:
-- native HTML bootstrapping from an existing container
-- self-contained UMD / IIFE browser builds for CDN usage
+- visual document editing
+- Source HTML editing
+- HTML preservation and restoration
+- direct CDN usage in the browser
-![Screenshot](Demo/img.png)
+![JEditor Screenshot](Demo/img.png)
+## Goals
+JEditor is not only trying to replicate a traditional rich text editor. Its core goal is harder:
+`Let users edit content like a document while preserving raw HTML as much as possible.`
+That is the main difference between JEditor and conventional editors:
+- most editors focus on structured content only
+- JEditor cares about both structured editing and HTML survivability
 ## Current capabilities
-- ESM build for Vite / Webpack / npm projects
-- self-contained UMD / IIFE builds for direct browser usage
-- native HTML bootstrap from existing container markup
-- `textarea` bootstrap with automatic HTML sync
-- core text formatting:
-  - bold
-  - italic
-  - underline
-  - strike
+The current version already includes:
+- dual-toolbar editing UI
+- native HTML bootstrap from a container
+- `textarea` bootstrap with automatic sync
+- ESM / UMD / IIFE builds
+- direct CDN integration without npm
+- Source toggle button
+- source editor on the left and high-fidelity preview on the right
+- full HTML document preservation
+- fragment HTML preprocess and restore flow
+- Raw HTML Block placeholders
+- core editing features:
   - undo / redo
+  - format painter
   - clear format
-- image plugin:
-  - paste images
-  - base64 insertion
-  - drag-to-resize
-  - reserved `uploadUrl` hook
+  - heading / paragraph
+  - font family / font size
+  - bold / italic / underline / strike
+  - color
+  - blockquote
+  - inline code
+  - code block
+  - lists
+  - link
+  - table
+  - image
+  - callout
+  - fullscreen
+## Architecture overview
+JEditor now follows a hybrid architecture centered around “Source HTML as the single source of truth”:
+```text
+Source HTML
+   ↓
+Parser / Preprocess
+   ↓
+Projection
+   ↓
+Visual Editor (Tiptap)
+   ↓
+restoreRawHTML()
+   ↓
+Output HTML
+```
+You can think of it as three layers:
+1. Source Layer
+   - stores the original HTML
+   - keeps full documents source-authoritative
+   - powers the high-fidelity preview
+2. Projection Layer
+   - preprocesses HTML before `setContent`
+   - sends supported nodes into the schema
+   - wraps unknown nodes as `RawHtmlIsland`
+3. Visual Layer
+   - uses Tiptap for structured editing
+   - all toolbar, plugin, command, and selection logic lives here
+## Three editing states
+### 1. Visual Mode
+This is the default mode. It is used for structured editing such as writing paragraphs, formatting text, inserting tables, callouts, images, and code blocks.
+This layer mainly depends on Tiptap for:
+- selection handling
+- command chains
+- schema
+- history
+- node and mark extensions
+### 2. Source Mode
+Enter it by clicking the `Source` button on the right side of the second toolbar row.
+The current implementation is:
+- left: source editor `textarea`
+- right: high-fidelity iframe preview
+When the content is a full HTML document, JEditor does not force it back through the visual editor. This avoids losing or normalizing:
+- `<!DOCTYPE html>`
+- `<head>`
+- `<style>`
+- `<script>`
+- the original document structure
+### 3. Hybrid / Preservation Flow
+This is currently the most important layer in JEditor.
+For fragment HTML, JEditor preprocesses content before `setContent()`:
+- supported nodes are parsed normally
+- unsupported nodes are wrapped as `raw-html` placeholders
+When exporting, `restoreRawHTML()` turns them back into their original HTML.
+The goal is simple:
+`Unknown HTML may not be editable, but it must not be deleted.`
+## Project structure
+Core source lives under `src`:
+- `src/jeditor.js`
+  - main editor entry
+  - controls mode switching, Source flow, HTML sync, and initialization
+- `src/editor/index.js`
+  - creates the Tiptap editor instance
+- `src/core/plugin-manager.js`
+  - central plugin registry and lifecycle manager
+- `src/core/config.js`
+  - default config and user config merging
+- `src/core/html-preservation.js`
+  - `preprocessHTML`
+  - `restoreRawHTML`
+  - HTML preservation pipeline
+- `src/toolbar/ui.js`
+  - toolbar DOM, popovers, state sync
+- `src/plugins`
+  - all toolbar behaviors and commands
+- `src/extensions`
+  - custom schema / mark / node extensions
+- `src/styles/editor.css`
+  - built-in editor styles
+## HTML preservation
+This is the most important architectural capability in the current version.
+### 1. preprocessHTML
+Runs before `setContent()`.
+Responsibilities:
+- walk through input HTML
+- decide whether a node is supported by the current schema
+- convert unsupported nodes into placeholders
+For example:
+```html
+<section style="display:flex">
+  <article>...</article>
+</section>
+```
+If the current schema cannot fully represent it, JEditor does not drop it. Instead, it converts it into:
+```html
+<raw-html data-raw-html="...encoded html..."></raw-html>
+```
+### 2. RawHtmlIsland
+`RawHtmlIsland` is an indivisible block node.
+Its job is not to edit arbitrary HTML. Its job is to preserve it.
+Visually, it is rendered as a visible block instead of an empty node, for example:
+- Raw HTML Block
+- HTML preserved
+It currently supports:
+- double click to jump back to Source
+- copy raw HTML
+- delete block
+Implementation:
+- `src/extensions/raw-html-island.js`
+### 3. restoreRawHTML
+Runs during `getHTML()`.
+Responsibilities:
+- scan editor output
+- find `raw-html[data-raw-html]`
+- restore the original saved `outerHTML`
+That means even if some nodes cannot be edited visually, they can still be exported back as their original HTML.
+## Schema extension direction
+The first stage of schema extension has already begun:
+- `GenericDiv`
+- `GlobalStyle`
+- `RawHtmlIsland`
+The goal is to gradually support more permissive HTML instead of letting it be removed by a strict schema too early.
+Next steps will include:
+- `GenericSpan`
+- finer inline fallback
+- broader unknown-tag preservation
+## Plugin system
+JEditor uses a plugin-driven toolbar and command architecture.
+A plugin usually contains:
+- `name`
+- `toolbar`
+- `tiptapExtension`
+- `command`
+- `isActive`
+- `renderPopover`
+- `init / destroy`
+This gives JEditor a few advantages:
+- UI and commands stay decoupled
+- toolbar items can be composed by configuration
+- new tools can be added without rewriting the core editor
+Built-in plugin entry:
+- `src/plugins/index.js`
+Plugin manager:
+- `src/core/plugin-manager.js`
+## Install and development
-## Install and develop
 ```bash
 npm install
 npm run dev
@@ -38,57 +285,56 @@ npm run preview
 ```
 Build outputs:
 - `dist/jeditor.es.js`
 - `dist/jeditor.umd.js`
 - `dist/jeditor.iife.js`
 - `dist/jeditor.css`
 ## ESM usage
 ```js
-import 'jeditor/dist/jeditor.css'
+import '@jenkin-a/jeditor/dist/jeditor.css'
 import { JEditor } from '@jenkin-a/jeditor'
-const editor = JEditor.create('#j-editor-container', {
-  placeholder: 'Start creating...',
+const editor = JEditor.create('#editor', {
+  placeholder: 'Start writing...',
 })
 ```
-You can also create an editor from an HTML string:
-```js
-const editor = JEditor.fromHTML('#j-editor-container', '<h2>Hello</h2><p>World</p>')
-```
-If the container already contains HTML, JEditor will parse it automatically:
-```html
-<div id="editor">
-  <h2>Existing HTML</h2>
-  <p>This will be parsed as the initial content.</p>
-</div>
-```
+You can also create from an HTML string:
 ```js
-JEditor.create('#editor')
+const editor = JEditor.fromHTML('#editor', '<h2>Hello</h2><p>World</p>')
 ```
-## CDN / direct browser usage
+## CDN / no-npm usage
 ```html
-<link rel="stylesheet" href="https://unpkg.com/@jenkin-a/jeditor/dist/jeditor.css" />
+<link rel="stylesheet" href="https://unpkg.com/@jenkin-a/jeditor/dist/jeditor.css">
 <script src="https://unpkg.com/feather-icons"></script>
 <script src="https://unpkg.com/@jenkin-a/jeditor/dist/jeditor.iife.js"></script>
 <div id="editor">
-  <h2>Hello JEditor</h2>
-  <p>This HTML is parsed on startup.</p>
+  <h2>Hello, JEditor</h2>
+  <p>The native HTML inside this container will be parsed on startup.</p>
 </div>
 <script>
-  const editor = window.JEditor.create('#editor')
+  const editor = window.JEditor.create('#editor', {
+    placeholder: 'Start writing...',
+  })
 </script>
 ```
-For a local browser-only example, run `npm run build` and open `Demo/cdn.html`.
+To pin a version:
+```html
+<script src="https://unpkg.com/@jenkin-a/jeditor@1.0.2/dist/jeditor.iife.js"></script>
+```
+## API
-## Public API
 ```js
 editor.getHTML()
 editor.getJSON()
@@ -97,25 +343,46 @@ editor.setContent('<p>Hello</p>')
 editor.importHTML('<p>Hello</p>')
 editor.focus()
 editor.destroy()
+editor.toggleSourceMode()
 ```
-## Dependency notes
-The ESM build expects these peer dependencies in your app:
-```bash
-npm install @tiptap/core @tiptap/starter-kit @tiptap/extension-underline @tiptap/extension-image @tiptap/pm
-```
+## Good fit for
+JEditor is a good fit for:
+- enterprise knowledge-base editors
+- SOP / notice / documentation workbenches
+- CMS editors that need Source HTML support
+- admin systems that need both visual editing and HTML editing
+- lightweight browser integrations via CDN
-The CDN / IIFE build is self-contained and does not require extra Tiptap imports.
+## Current boundaries
-## Known limitations
-- Several toolbar buttons are still placeholders; see `src/plugins/placeholders.js`
-- Image upload still defaults to base64; the full `uploadUrl` pipeline is not wired yet
-- Source HTML editing mode is planned for the next major feature cycle
+The current version is already strong, but it is still evolving.
-## Roadmap
-1. v1.0.1: native HTML bootstrap + self-contained CDN / IIFE build
-2. v1.1.x: fill core editing features such as headings, lists, alignment, colors, font controls, links, and code blocks
-3. v1.2.x: Source HTML mode with visual ↔ HTML switching
+Some current boundaries:
+- some UI details still need polishing
+- a few toolbar interactions can be refined further
+- complex unknown inline HTML preservation is not final yet
+- Source Mode and Hybrid Mode will continue to evolve
+## Next direction
+The next development direction is clear:
+1. expand the schema
+   - `GenericSpan`
+   - broader style / attr preservation
+2. improve Raw HTML preservation
+   - finer fallback behavior
+   - better import / export restoration
+3. strengthen Source / Visual collaboration
+   - more stable mode switching
+   - deeper Hybrid editing experience
 ## License
 MIT