@pdejs/core NPM

About PDEJS

PDEJS is inspired by Preact's reconciler implements. We made the implements working standalone for constucting plugins of Editor.js through declarative ui programming.

Why using Preact's reconciler

We first tried to incorporate React philosophy into the data management in the Editor.js block. React is a UI library includes a simple architecture concerned with the View of MVC model. In applications such as block editors that read and write a lot of data, an approach like React is useful because managing data through DOM manipulation is very labor intensive. Therefore, we used React's mechanisms such as reconciliation and hooks to make data management simple and explicit to improve the development experience.

However, React implementation is complex, even for a reconciler or hooks implementation. Even if the exact same code could be run standalone, it would require time spent understanding the code, making ongoing maintenance impractical. Therefore, we decide to utilze Preact for incorporating the React philosophy without relying on React.

Preact is a library known as a lightweight alternative of React. However, we consider that the superiority of the Preact is not that it is a lighter library than React, but it rewrites React with a minimum amount of code to make it more readable. Hence, we worked on cloning the implements from Preact's reconciler and adjusted for Editor.js plugin development.

Getting started

Required Node.js v16 or later.

With TypeScript(recommended)

Install packages.

npm i @editorjs/editorjs @pdejs/core

npm i --save-dev typescript

Add tsconfig.json.

{
  "compilerOptions": {
    "target": "es2016",
    "lib": ["ESNext", "DOM", "DOM.Iterable"],
    "module": "commonjs",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "jsx": "react"
  }
}

Write your first plugin like shown below.

/* @jsx h */
import {
  h,
  useMount,
  useWatch,
  useState,
  PDJSX,
  createPlugin,
} from '@pdejs/core';

const Plugin = () => {
  const toolbox: PDJSX.ToolAttributes['static_get_toolbox'] = {
    title: 'Simple',
    icon: '⚔️',
  };
  const save: PDJSX.ToolAttributes['save'] = (blockContent) => {
    return blockContent.innerText;
  };

  const [inputValue, setInputValue] = useState('');
  const [submitValue, setSubmitValue] = useState('');
  const handleFormSubmit = (event: Event) => {
    event.preventDefault();
    setSubmitValue(inputValue);
  };
  const handleInputChange = (event: Event) => {
    if (event.target instanceof HTMLInputElement) {
      setInputValue(event.target.value);
    }
  };

  useMount(() => {
    console.log('[@pdejs/simple] is ready to work!');
  });
  useWatch(() => {
    console.log(`[@pdejs/simple] submitted : `, submitValue);
  }, [submitValue]);

  return (
    <tool save={save} static_get_toolbox={toolbox}>
      <div>
        <form onSubmit={handleFormSubmit}>
          <label>
            type something→
            <input onChange={handleInputChange} value={inputValue} />
          </label>
          <button>submit</button>
        </form>
        <div>
          <span>submitted: </span>
          <span>{submitValue}</span>
        </div>
      </div>
    </tool>
  );
};

export const Simple = createPlugin(<Plugin />);

Create files for completing to setup. We recommend to use vite for hosting locally.

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Example - Simple</title>
  </head>
  <body>
    <div id="canvas"></div>
    <button id="save">save</button>
    <script type="module" src="/main.ts"></script>
  </body>
</html>

/* @jsx h */
import { Simple } from './plugin';
import EditorJS from '@editorjs/editorjs';

import './style.css';

const canvasElm = document.querySelector<HTMLDivElement>('#canvas');
const saveElm = document.querySelector<HTMLButtonElement>('#save');

if (!canvasElm) {
  throw new Error('Could not find the element#canvas');
}

const editor = new EditorJS({
  holder: canvasElm,
  tools: {
    simple: {
      class: Simple,
    },
  },
  onReady: () => {
    console.log('Editor.js is ready to work!');
  },
  onChange: (_, event) => {
    console.log("Now I know that Editor's content changed!", event);
  },
  autofocus: true,
  placeholder: "Let's write an awesome story!",
});

saveElm?.addEventListener('click', () => {
  editor
    .save()
    .then((outputData) => {
      console.log('saved: ', outputData);
    })
    .catch((error) => {
      console.log('save failded: ', error);
    });
});

It works :tada:

image

See the source for more information.

With JavaScript

Install packages.

npm i @editorjs/editorjs @pdejs/core

npm i --save-dev @babel/core @babel/cli @babel/plugin-transform-react-jsx @babel/preset-env

Add .babelrc.

{
  "presets": [["@babel/preset-env"]],
  "plugins": ["@babel/plugin-transform-react-jsx"]
}

Other steps are almostly the same way of the With TypeScript.

If you do not want to use `@jsx h`

Modify compilerOptions.jsxFactory in tsconfig.json or add @babel/plugin-transform-react-jsx for modifying pragma as follows.

tsconfig.json (with tsc)

{
  "compilerOptions": {
    "jsxFactory": "h"
  }
}

.babelrc (with @babel-transform-react-jsx)

{
  "plugins": [["transform-react-jsx", { "pragma": "h" }]]
}

APIs

List up the available APIs.

Core Functions

`h(type, config, children)`

Function for parsing JSX to object.

`createPlugin(element)`

Adapter function for Editor.js. It receives PDEJS's JSXElement as an argument and returns Editor.js plugin class.

JSXElement

See types for more information of JSXElement props.

`<tool>`

JSXElement for Editor.js Tools API.

Prop	Description	Required	Data Format	Related Docs
`children`	is children of PDEJS Element.	:ballot_box_with_check:	Array	https://preactjs.com/guide/v10/api-reference/#h--createelement
`save`	extracts Block data from the UI.	:ballot_box_with_check:	Function	https://editorjs.io/tools-api#save
`validate`	validates Block data after saving.		Function	https://editorjs.io/tools-api#validate
`renderSettings`	is object for the settings UI.		Object	https://editorjs.io/tools-api#rendersettings
`destroy`	clears Tools stuff(cache, variables, events).		Function	https://editorjs.io/tools-api#destroy
`onPaste`	handles content pasted.		Function	https://editorjs.io/tools-api#onpaste
`merge`	specifies how to merge two similar Blocks.		Function	https://editorjs.io/tools-api#merge
`static_get_pasteConfig`	allows your Tool to substitute pasted contents.		Object	https://editorjs.io/tools-api#pasteconfig
`static_get_sanitize`	allows to clean unwanted HTMLElement or attributes.		Object	https://editorjs.io/tools-api#sanitize
`static_get_toolbox`	decides icon and title. REQUIRED if Tools should be added to the toolbox.		Object	https://editorjs.io/tools-api#toolbox
`static_get_shortcut`	registers a shortcut command.		String	https://editorjs.io/tools-api#shortcut
`static_get_conversionConfig`	decides that Tool can be converted into/form anothor Tool.		Object	https://editorjs.io/tools-api#conversionconfig
`static_get_enableLineBreaks`	handles Enter keydowns if it's set true.		Boolean	https://editorjs.io/tools-api#enablelinebreaks
`static_get_isReadOnlySupported`	is a flag for supporting the read-only mode.		Boolean	https://editorjs.io/tools-api#isreadonlysupported

`<inlineTool>`

JSXElement for Editor.js Inline Tools API.

Prop	Description	Required	Data Format	Related Docs
`children`	is children of PDEJS Element.	:ballot_box_with_check:	Array	https://preactjs.com/guide/v10/api-reference/#h--createelement
`surround`	works with selected range.	:ballot_box_with_check:	Function	https://editorjs.io/inline-tools-api-1#surround
`checkState`	gets Tool's activated state by selected range.	:ballot_box_with_check:	Function	https://editorjs.io/inline-tools-api-1#checkstate
`renderActions`	create additional element.		Function	https://editorjs.io/inline-tools-api-1#renderactions
`clear`	clears Tools stuff.		Function	https://editorjs.io/inline-tools-api-1#clear
`get_shortcut`	sets a shortcut.		String	https://editorjs.io/inline-tools-api-1#shortcut
`static_get_isInline`	specifies Tool as Inline Toolbar Tool.	:ballot_box_with_check:	Boolean(true)	https://editorjs.io/inline-tools-api-1#isinline
`static_sanitize`	sanitizer rules.		Function	https://editorjs.io/inline-tools-api-1#sanitize
`static_title`	decides Tool's title.		Function	https://editorjs.io/inline-tools-api-1#title

`<blockTune>`

JSXElement for Editor.js Block Tunes API

Prop	Description	Required	Data Format	Related Docs
`children`	is children of PDEJS Element.	:ballot_box_with_check:	Array	https://preactjs.com/guide/v10/api-reference/#h--createelement
`save`	saves Tune's state.		Function	https://editorjs.io/block-tunes-api#save
`wrap`	wraps Block's content element.		Function	https://editorjs.io/block-tunes-api#wrap
`static_get_isTune`	specifies Tool as Block Tune.		Boolean(true)	https://editorjs.io/block-tunes-api#static-get-istune
`static_prepare`	makes any preparations required for Tune.		Function	https://editorjs.io/block-tunes-api#prepare
`static_reset`	resets the value of `static_prepare`.		Function	https://editorjs.io/block-tunes-api#reset

Hook

`useReducer(reducer, initialState, initilizer)`

Update state by provided reducer.

`useState(initialState)`

Returns state and state updater.

`useMount(callback)`

Execute callback when mounting DOM.

`useWatch(callback, deps)`

Execute callback when deps are changed.

`useConstructor()`

UNSTABLE HOOK

Be able to get the value of Editor.js plugin class constructor.

Roadmap

Add types for custom JSX elements
Add a parser for JSX and syntax of Editor.js tools
- Prototyping(Add a simple parser)
- Styles API support
- Access params of constructor as props
Add unit & integration testing
Add implements of diff or reconcile
Add functions for transforming JSX nodes to plugin class syntax
A11y support

Contributing

git clone https://github.com/cam-inc/pde.js.git && cd pde.js && npm run preflight

License

Apache-2.0 License

Inspired

https://github.com/preactjs/preact

change-case

@infinitebrahmanuniverse/nolb-_pd @everything-registry/sub-chunk-709 @zalastax/nolb-_pd

0.0.2

2 years ago

About PDEJS

Why using Preact's reconciler

Getting started

With TypeScript(recommended)

With JavaScript

If you do not want to use @jsx h

APIs

Core Functions

h(type, config, children)

createPlugin(element)

JSXElement

<tool>

<inlineTool>

<blockTune>