feat: migrate Header tool to the Editor.js v3 SDK

.gitignore

@@ -1,5 +1,30 @@
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+
+# Swap the comments on the following lines if you don't wish to use zero-installs
+# Documentation here: https://yarnpkg.com/features/zero-installs
+#!.yarn/cache
+#.pnp.*
+
+# IDE
+.idea/*
+
 node_modules/*
-npm-debug.log
-.idea/
+dist/*
+
+# tests
+coverage/
+reports/
+
+# stryker temp files
+.stryker-tmp
+*.tsbuildinfo
+
 .DS_Store
-dist
+
+# ENV
+**/.env

README.md

@@ -1,58 +1,18 @@
 # Heading Tool
 
-![Version of EditorJS that the plugin is compatible with](https://badgen.net/badge/Editor.js/v2.0/blue)
-
-Provides Headings Blocks for the [Editor.js](https://ifmo.su/editor).
+Provides Heading blocks for [Editor.js](https://editorjs.io) v3.
 
 ## Installation
 
-Get the package
-
-```shell
-yarn add @editorjs/header
-```
-
-Include module at your application
-
 ```javascript
-import Header from '@editorjs/header';
-```
-
-Optionally, you can load this tool from CDN [JsDelivr CDN](https://cdn.jsdelivr.net/npm/@editorjs/header@latest)
-
-## Usage
-
-Add a new Tool to the `tools` property of the Editor.js initial config.
+import { Header } from '@editorjs/header';
 
-```javascript
 var editor = EditorJS({
   ...
-
   tools: {
     ...
     header: Header,
   },
-
-  ...
-});
-```
-
-## Shortcut
-
-You can insert this Block by a useful shortcut. Set it up with the `tools[].shortcut` property of the Editor's initial config.
-
-```javascript
-var editor = EditorJS({
-  ...
-
-  tools: {
-    ...
-    header: {
-      class: Header,
-      shortcut: 'CMD+SHIFT+H',
-    },
-  },
-
   ...
 });
 ```
@@ -61,51 +21,47 @@ var editor = EditorJS({
 
 All properties are optional.
 
-| Field        | Type       | Description                 |
-| ------------ | ---------- | --------------------------- |
-| placeholder  | `string`   | header's placeholder string |
-| levels       | `number[]` | enabled heading levels      |
-| defaultLevel | `number`   | default heading level       |
+| Field        | Type     | Description            |
+| ------------ | -------- | ----------------------- |
+| placeholder  | `string` | header's placeholder string |
+| defaultLevel | `number` | default heading level (1–6), used when no level is set on the block |
 
 ```javascript
 var editor = EditorJS({
   ...
-
   tools: {
     ...
     header: {
       class: Header,
       config: {
         placeholder: 'Enter a header',
-        levels: [2, 3, 4],
         defaultLevel: 3
       }
     }
   }
-
   ...
 });
 ```
 
-## Tool's settings
-
-![An image showing the header block tool](https://capella.pics/634ad545-08d7-4cb7-8409-f01289e0e5e1.jpg)
-
-You can select one of six levels for heading.
-
 ## Output data
 
-| Field | Type     | Description                                      |
-| ----- | -------- | ------------------------------------------------ |
-| text  | `string` | header's text                                    |
-| level | `number` | level of header: 1 for H1, 2 for H2 ... 6 for H6 |
+| Field | Type                | Description                                      |
+| ----- | ------------------- | ------------------------------------------------ |
+| text  | `TextNodeSerialized` | header's text, with inline formatting fragments   |
+| level | `number`             | level of header: 1 for H1, 2 for H2 ... 6 for H6  |
 
 ```json
 {
   "type": "header",
   "data": {
-    "text": "Why Telegram is the best messenger",
+    "text": { "value": "Why Telegram is the best messenger", "fragments": [] },
     "level": 2
   }
 }
 ```
+
+## TODO
+
+This package depends on `@editorjs/model`, `@editorjs/sdk`, and `@editorjs/dom-adapters` via `workspace:^`, and is meant to be developed, built, and tested only inside the [`document-model`](https://github.com/editor-js/document-model) workspace (as a git submodule under `packages/tools/header`) — it isn't installable or buildable standalone right now. `yarn install` in this repo alone will fail with a "Workspace not found" error.
+
+Publishing `@editorjs/header` to npm will happen through `document-model`'s own release pipeline once the submodule is wired in, not through this repository's own CI.

eslint.config.mjs

@@ -0,0 +1,37 @@
+import CodeX from 'eslint-config-codex';
+
+export default [
+  ...CodeX,
+
+  {
+    ignores: ['vite.config.ts', 'postcss.config.js', 'src/__mocks__/*'],
+  },
+
+  {
+    languageOptions: {
+      parserOptions: {
+        project: './tsconfig.eslint.json',
+        tsconfigRootDir: import.meta.dirname,
+        sourceType: 'module',
+      },
+    },
+    rules: {
+      'n/no-unpublished-import': ['error', {
+        allowModules: ['eslint-config-codex'],
+        ignoreTypeImport: true,
+      }],
+      'n/no-missing-import': ['error', {
+        allowModules: ['@editorjs/model', '@editorjs/sdk', '@editorjs/dom-adapters'],
+      }],
+    },
+  },
+
+  {
+    files: ['**/*.spec.ts'],
+    rules: {
+      'n/no-unpublished-import': ['error', {
+        allowModules: ['@jest/globals'],
+      }],
+    },
+  },
+];

jest.config.ts

@@ -0,0 +1,19 @@
+import type { JestConfigWithTsJest } from 'ts-jest';
+
+export default {
+  preset: 'ts-jest',
+  testEnvironment: 'jsdom',
+  testMatch: ['<rootDir>/src/**/*.spec.ts'],
+  extensionsToTreatAsEsm: ['.ts'],
+  moduleNameMapper: {
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+    '\\.pcss$': '<rootDir>/src/__mocks__/styleMock.cjs',
+  },
+  coverageReporters: ['lcov', 'json-summary', 'text-summary'],
+  transform: {
+    '^.+\\.tsx?$': [
+      'ts-jest',
+      { useESM: true },
+    ],
+  },
+} as JestConfigWithTsJest;

package.json

@@ -1,6 +1,11 @@
 {
   "name": "@editorjs/header",
-  "version": "2.8.8",
+  "version": "3.0.0",
+  "packageManager": "yarn@4.0.1",
+  "type": "module",
+  "main": "./dist/header.cjs",
+  "module": "./dist/header.js",
+  "types": "./dist/index.d.ts",
   "keywords": [
     "codex editor",
     "header",
@@ -11,35 +16,48 @@
   "description": "Heading Tool for Editor.js",
   "license": "MIT",
   "repository": "https://github.com/editor-js/header",
-  "files": [
-    "dist"
-  ],
-  "main": "./dist/header.umd.js",
-  "module": "./dist/header.mjs",
-  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/header.mjs",
-      "require": "./dist/header.umd.js",
-      "types": "./dist/index.d.ts"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/header.js",
+      "require": "./dist/header.cjs",
+      "default": "./dist/header.js"
     }
   },
+  "files": [
+    "dist"
+  ],
   "scripts": {
-    "dev": "vite",
-    "build": "vite build"
-  },
-  "author": {
-    "name": "CodeX",
-    "email": "team@codex.so"
+    "build": "yarn clear && vite build",
+    "dev": "vite build --watch",
+    "test": "node --experimental-vm-modules $(yarn bin jest)",
+    "test:coverage": "yarn test --coverage=true",
+    "lint": "eslint ./src",
+    "lint:ci": "yarn lint --max-warnings 0",
+    "lint:fix": "yarn lint --fix",
+    "clear": "rm -rf ./dist && rm -f tsconfig.tsbuildinfo"
   },
   "devDependencies": {
-    "typescript": "^5.4.5",
-    "vite": "^4.5.0",
-    "vite-plugin-css-injected-by-js": "^3.3.0",
-    "vite-plugin-dts": "^3.9.1"
+    "@jest/globals": "^29.7.0",
+    "@types/jest": "^29.5.1",
+    "@types/node": "^22.10.2",
+    "eslint": "^9.24.0",
+    "eslint-config-codex": "^2.0.3",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "postcss-apply": "^0.12.0",
+    "postcss-preset-env": "^10.1.5",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.5.4",
+    "vite": "^8.0.8",
+    "vite-plugin-css-injected-by-js": "^3.5.2",
+    "vite-plugin-dts": "^3.7.3"
   },
   "dependencies": {
-    "@codexteam/icons": "^0.0.5",
-    "@editorjs/editorjs": "^2.29.1"
+    "@codexteam/icons": "^0.3.3",
+    "@editorjs/dom-adapters": "workspace:^",
+    "@editorjs/editorjs": "^2.30.8",
+    "@editorjs/model": "workspace:^",
+    "@editorjs/sdk": "workspace:^"
   }
 }

postcss.config.js

@@ -0,0 +1,9 @@
+/**
+ * PostCSS configuration
+ */
+export default {
+  plugins: {
+    'postcss-preset-env': {},
+    'postcss-apply': {},
+  },
+};

src/__mocks__/styleMock.cjs

@@ -0,0 +1,3 @@
+module.exports = new Proxy({}, {
+  get: (_target, prop) => prop,
+});

src/index.module.pcss

@@ -0,0 +1,6 @@
+.header {
+  outline: none;
+  white-space: pre-wrap;
+  margin: 0;
+  min-height: 1em;
+}