Migrate kg-lexical-html-renderer to TypeScript

- Move lib/ to src/, update tsconfig rootDir
- Update tsconfig.json: NodeNext module, verbatimModuleSyntax, declarationMap
- Add "type": "module" to package.json
- Convert source from CJS to ESM (require -> import, module.exports -> export)
- Add .js extensions to all relative imports
- Rename test files .js to .ts with type annotations
- Switch test runner to tsx
- Replace .eslintrc.js with eslint.config.js (flat config)

Author: kevinansfield

packages/kg-default-nodes/src/KoenigDecoratorNode.ts

@@ -1,5 +1,6 @@
 /* c8 ignore start */
 import {DecoratorNode} from 'lexical';
+import type {ExportDOMOptions, ExportDOMOutput} from './export-dom.js';
 
 export class KoenigDecoratorNode extends DecoratorNode<unknown> {
     static transform() {
@@ -11,7 +12,19 @@ export class KoenigDecoratorNode extends DecoratorNode<unknown> {
     }
 }
 
-export function $isKoenigCard(node: unknown): node is KoenigDecoratorNode {
+// A Ghost card at runtime is a KoenigDecoratorNode plus a custom exportDOM
+// signature and optional dynamic-data hooks. We can't declare these on the
+// class itself — Lexical's DecoratorNode.exportDOM has an incompatible
+// signature and the override (see generate-decorator-node.ts) relies on a
+// localised @ts-expect-error. This intersection type is what $isKoenigCard
+// narrows to so consumers get the card-shaped surface.
+export type KoenigCard = KoenigDecoratorNode & {
+    exportDOM(options: ExportDOMOptions): ExportDOMOutput<Element>;
+    hasDynamicData?(): boolean;
+    getDynamicData?(options: ExportDOMOptions): Promise<{key: number; data: unknown}>;
+};
+
+export function $isKoenigCard(node: unknown): node is KoenigCard {
     return node instanceof KoenigDecoratorNode;
 }
 /* c8 ignore end */

packages/kg-lexical-html-renderer/eslint.config.mjs

@@ -1,52 +1,33 @@
-import {fixupPluginRules} from '@eslint/compat';
 import eslint from '@eslint/js';
+import {defineConfig} from 'eslint/config';
 import ghostPlugin from 'eslint-plugin-ghost';
-import globals from 'globals';
 import tseslint from 'typescript-eslint';
 
-const ghost = fixupPluginRules(ghostPlugin);
-
-export default tseslint.config(
-    {ignores: ['build/**', 'cjs/**', 'es/**']},
+export default defineConfig([
+    {ignores: ['build/**']},
     {
-        files: ['lib/**/*.ts'],
+        files: ['**/*.ts'],
         extends: [
             eslint.configs.recommended,
             tseslint.configs.recommended
         ],
-        plugins: {ghost},
         languageOptions: {
-            globals: globals.node
+            parserOptions: {ecmaVersion: 2022, sourceType: 'module'}
         },
+        plugins: {ghost: ghostPlugin},
         rules: {
             ...ghostPlugin.configs.ts.rules,
-            'ghost/filenames/match-exported-class': 'off',
-            '@typescript-eslint/no-unused-expressions': 'off',
-            '@typescript-eslint/no-require-imports': 'off'
+            '@typescript-eslint/no-explicit-any': 'error'
         }
     },
     {
-        files: ['test/**/*.js'],
-        extends: [
-            eslint.configs.recommended
-        ],
-        plugins: {ghost},
-        languageOptions: {
-            globals: {
-                ...globals.node,
-                ...globals.mocha,
-                should: true,
-                sinon: true
-            }
-        },
+        files: ['test/**/*.ts'],
         rules: {
-            ...ghostPlugin.configs.node.rules,
-            'no-unused-vars': ['error', {caughtErrors: 'none'}],
-            'ghost/filenames/match-exported-class': 'off',
-            'ghost/filenames/match-exported': 'off',
-            'ghost/filenames/match-regex': 'off',
-            ...ghostPlugin.configs.test.rules,
+            ...ghostPlugin.configs['ts-test'].rules,
+            'ghost/mocha/no-global-tests': 'off',
+            'ghost/mocha/handle-done-callback': 'off',
+            'ghost/mocha/no-mocha-arrows': 'off',
             'ghost/mocha/max-top-level-suites': 'off'
         }
     }
-);
+]);

packages/kg-lexical-html-renderer/lib/index.ts

@@ -4,17 +4,25 @@
   "repository": "https://github.com/TryGhost/Koenig/tree/main/packages/kg-lexical-html-renderer",
   "author": "Ghost Foundation",
   "license": "MIT",
-  "main": "build/index.js",
-  "types": "build/index.d.ts",
+  "main": "build/cjs/index.js",
+  "module": "build/esm/index.js",
+  "types": "build/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/esm/index.d.ts",
+      "import": "./build/esm/index.js",
+      "require": "./build/cjs/index.js"
+    }
+  },
   "scripts": {
     "dev": "tsc --watch --preserveWatchOutput --sourceMap",
-    "build": "tsc",
-    "prepare": "tsc",
-    "pretest": "yarn build",
+    "build": "tsc && tsc -p tsconfig.cjs.json && echo '{\"type\":\"module\"}' > build/esm/package.json",
+    "prepare": "tsc && tsc -p tsconfig.cjs.json && echo '{\"type\":\"module\"}' > build/esm/package.json",
+    "pretest": "tsc && tsc -p tsconfig.cjs.json && echo '{\"type\":\"module\"}' > build/esm/package.json && tsc -p tsconfig.test.json",
     "test": "yarn test:unit && yarn test:types",
-    "test:unit": "NODE_ENV=testing c8 --lib --check-coverage --reporter text --reporter cobertura mocha './test/**/*.test.js'",
+    "test:unit": "NODE_ENV=testing c8 --src src --all --check-coverage --reporter text --reporter cobertura mocha --require tsx './test/**/*.test.ts'",
     "test:types": "tsc --noEmit",
-    "lint": "eslint . --cache",
+    "lint": "eslint",
     "posttest": "yarn lint"
   },
   "files": [
@@ -26,12 +34,20 @@
     "access": "public"
   },
   "devDependencies": {
+    "@eslint/js": "9.39.4",
+    "@types/jsdom": "21.1.7",
+    "@types/mocha": "10.0.10",
+    "@types/should": "13.0.0",
+    "@types/sinon": "21.0.0",
     "c8": "11.0.0",
     "jsdom": "29.0.2",
     "mocha": "11.7.5",
     "prettier": "3.8.2",
     "should": "13.2.3",
-    "sinon": "21.1.2"
+    "sinon": "21.1.2",
+    "tsx": "4.21.0",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.57.0"
   },
   "dependencies": {
     "@lexical/clipboard": "0.13.1",

packages/kg-lexical-html-renderer/lib/transformers/index.ts

@@ -1,41 +1,35 @@
-import {SerializedEditorState, LexicalEditor, LexicalNode, Klass} from 'lexical';
 import {createHeadlessEditor} from '@lexical/headless';
 import {ListItemNode, ListNode} from '@lexical/list';
 import {HeadingNode, QuoteNode} from '@lexical/rich-text';
 import {LinkNode} from '@lexical/link';
-import $convertToHtmlString from './convert-to-html-string';
-import getDynamicDataNodes from './get-dynamic-data-nodes';
-
-// TODO: Using import causes circular definitions for kg-default-nodes
-
-const {registerRemoveAtLinkNodesTransform} = require('@tryghost/kg-default-transforms');
+import {JSDOM} from 'jsdom';
+import $convertToHtmlString from './convert-to-html-string.js';
+import getDynamicDataNodes from './get-dynamic-data-nodes.js';
+import {registerRemoveAtLinkNodesTransform} from '@tryghost/kg-default-transforms';
+import type {SerializedEditorState, LexicalEditor, LexicalNode, Klass} from 'lexical';
+import type {ExportDOMDom} from '@tryghost/kg-default-nodes';
+import type {RendererOptions} from './types.js';
 
 interface RenderOptions {
     target?: 'html' | 'email' | 'plaintext';
-    dom?: import('jsdom').JSDOM;
+    dom?: ExportDOMDom;
     // TODO: we should define some standard here once we move to more cards with dynamic data
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    renderData?: Map<number, any>;
+    renderData?: Map<number, unknown>;
 }
 
 function defaultOnError() {
     // do nothing
 }
 
 export default class LexicalHTMLRenderer {
-    dom: import('jsdom').JSDOM;
+    dom: ExportDOMDom;
     nodes: Klass<LexicalNode>[];
     onError: (error: Error) => void;
 
-    constructor({dom, nodes, onError}: {dom?: import('jsdom').JSDOM, nodes?: Klass<LexicalNode>[], onError?: () => void} = {}) {
-        if (!dom) {
-            const jsdom = require('jsdom');
-            const {JSDOM} = jsdom;
-
-            this.dom = new JSDOM();
-        } else {
-            this.dom = dom;
-        }
+    constructor({dom, nodes, onError}: {dom?: ExportDOMDom, nodes?: Klass<LexicalNode>[], onError?: () => void} = {}) {
+        // JSDOM default is a Node-side convenience. Consumers in browser
+        // environments can pass any {window: {document}}-shaped object.
+        this.dom = dom ?? new JSDOM();
 
         this.nodes = nodes || [];
         this.onError = onError || defaultOnError;
@@ -46,7 +40,7 @@ export default class LexicalHTMLRenderer {
             target: 'html',
             dom: this.dom
         };
-        const options = Object.assign({}, defaultOptions, userOptions);
+        const options: RendererOptions = Object.assign({}, defaultOptions, userOptions) as RendererOptions;
 
         const DEFAULT_NODES: Array<Klass<LexicalNode>> = [
             HeadingNode,

packages/kg-lexical-html-renderer/package.json

@@ -1,9 +1,10 @@
-import {ElementNode, LexicalNode} from 'lexical';
 import {$getRoot, $isElementNode, $isLineBreakNode, $isParagraphNode, $isTextNode} from 'lexical';
 import {$isLinkNode} from '@lexical/link';
-import {$isKoenigCard, RendererOptions} from '@tryghost/kg-default-nodes';
-import TextContent from './utils/TextContent';
-import elementTransformers from './transformers';
+import {$isKoenigCard} from '@tryghost/kg-default-nodes';
+import TextContent from './utils/TextContent.js';
+import elementTransformers from './transformers/index.js';
+import type {ElementNode, LexicalNode} from 'lexical';
+import type {RendererOptions} from './types.js';
 
 export default function $convertToHtmlString(options: RendererOptions = {}): string {
     const output: string[] = [];
@@ -31,15 +32,13 @@ export default function $convertToHtmlString(options: RendererOptions = {}): str
 
 function exportTopLevelElementOrDecorator(node: LexicalNode, options: RendererOptions): string | null {
     if ($isKoenigCard(node)) {
-        // NOTE: kg-default-nodes appends type in rare cases to make use of this functionality... with moving to typescript,
-        //  we should change this implementation because it's confusing, or we should override the DOMExportOutput type
         const {element, type} = node.exportDOM(options);
 
         switch (type) {
         case 'inner':
             return element.innerHTML;
         case 'value':
-            if ('value' in element) {
+            if ('value' in element && typeof element.value === 'string') {
                 return element.value;
             }
 

packages/kg-lexical-html-renderer/src/LexicalHTMLRenderer.ts

@@ -1,10 +1,10 @@
 import {$getRoot} from 'lexical';
-import {$isKoenigCard, KoenigDecoratorNode} from '@tryghost/kg-default-nodes';
-
+import {$isKoenigCard} from '@tryghost/kg-default-nodes';
+import type {KoenigCard} from '@tryghost/kg-default-nodes';
 import type {EditorState} from 'lexical';
 
-export default function getDynamicDataNodes(editorState: EditorState): KoenigDecoratorNode[] {
-    const dynamicNodes: KoenigDecoratorNode[] = [];
+export default function getDynamicDataNodes(editorState: EditorState): KoenigCard[] {
+    const dynamicNodes: KoenigCard[] = [];
 
     editorState.read(() => {
         const root = $getRoot();

packages/kg-lexical-html-renderer/src/convert-to-html-string.ts

@@ -0,0 +1,5 @@
+/* c8 ignore start */
+import LexicalHTMLRenderer from './LexicalHTMLRenderer.js';
+
+export {LexicalHTMLRenderer};
+/* c8 ignore stop */