npm - @jenkin-a/jeditor - Versions diffs - 1.0.0 → 1.0.3 - Mend

@jenkin-a/jeditor 1.0.0 → 1.0.3

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 (9) hide show

package/Demo/cdn.html ADDED Viewed

@@ -0,0 +1,24 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>JEditor CDN Demo</title>
+    <link rel="stylesheet" href="../dist/jeditor.css">
+    <script src="https://unpkg.com/feather-icons"></script>
+</head>
+<body style="margin:0;background:#f2f2f2;font-family:Arial,sans-serif;">
+    <div style="max-width:1200px;margin:40px auto;padding:0 16px;">
+        <div id="cdn-editor">
+            <h2>CDN bootstrap</h2>
+            <p>This block is parsed from native HTML without Vite.</p>
+            <p>After building, open this file and load <code>../dist/jeditor.iife.js</code>.</p>
+        </div>
+    </div>
+    <script src="../dist/jeditor.iife.js"></script>
+    <script>
+        window.editor = window.JEditor.create('#cdn-editor')
+    </script>
+</body>
+</html>

package/Demo/img.png ADDED Viewed

Binary file

package/README.en.md ADDED Viewed

@@ -0,0 +1,388 @@
+# JEditor
+Language: English | [中文](README.md)
+Current version: `v1.0.2`
+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:
+- visual document editing
+- Source HTML editing
+- HTML preservation and restoration
+- direct CDN usage in the browser
+![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
+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
+  - 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
+```bash
+npm install
+npm run dev
+npm run build
+npm run preview
+```
+Build outputs:
+- `dist/jeditor.es.js`
+- `dist/jeditor.umd.js`
+- `dist/jeditor.iife.js`
+- `dist/jeditor.css`
+## ESM usage
+```js
+import '@jenkin-a/jeditor/dist/jeditor.css'
+import { JEditor } from '@jenkin-a/jeditor'
+const editor = JEditor.create('#editor', {
+  placeholder: 'Start writing...',
+})
+```
+You can also create from an HTML string:
+```js
+const editor = JEditor.fromHTML('#editor', '<h2>Hello</h2><p>World</p>')
+```
+## CDN / no-npm usage
+```html
+<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>The native HTML inside this container will be parsed on startup.</p>
+</div>
+<script>
+  const editor = window.JEditor.create('#editor', {
+    placeholder: 'Start writing...',
+  })
+</script>
+```
+To pin a version:
+```html
+<script src="https://unpkg.com/@jenkin-a/jeditor@1.0.2/dist/jeditor.iife.js"></script>
+```
+## API
+```js
+editor.getHTML()
+editor.getJSON()
+editor.getText()
+editor.setContent('<p>Hello</p>')
+editor.importHTML('<p>Hello</p>')
+editor.focus()
+editor.destroy()
+editor.toggleSourceMode()
+```
+## 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
+## Current boundaries
+The current version is already strong, but it is still evolving.
+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