Migrate kg-lexical-html-renderer to TypeScript

no issue
This commit moves kg-lexical-html-renderer from lib/ to src/, migrates its build and tests to TypeScript/ESM, and fixes the migration fallout in published artifacts, runtime loading, and callback typing.
It also tightens the shared exportDOM and Koenig card typing in kg-default-nodes because this renderer migration depends on those cross-package contracts compiling cleanly against Lexical.

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,23 @@ export class KoenigDecoratorNode extends DecoratorNode<unknown> {
     }
 }
 
-export function $isKoenigCard(node: unknown): node is KoenigDecoratorNode {
-    return node instanceof KoenigDecoratorNode;
+export type KoenigCard = KoenigDecoratorNode & {
+    isKoenigCard(): true;
+    exportDOM(options: ExportDOMOptions): ExportDOMOutput;
+    hasDynamicData(): boolean;
+    getDynamicData?(options: ExportDOMOptions): Promise<{key: number; data: unknown}>;
+};
+
+export function $isKoenigCard(node: unknown): node is KoenigCard {
+    if (!(node instanceof KoenigDecoratorNode)) {
+        return false;
+    }
+
+    const card = node as Partial<KoenigCard>;
+
+    return typeof card.isKoenigCard === 'function' &&
+        card.isKoenigCard() === true &&
+        typeof card.exportDOM === 'function' &&
+        typeof card.hasDynamicData === 'function';
 }
 /* c8 ignore end */

packages/kg-default-nodes/src/export-dom.ts

@@ -1,9 +1,13 @@
+import type {DOMExportOutput as LexicalDOMExportOutput} from 'lexical';
+
 export type ExportDOMOutputType = 'inner' | 'outer' | 'value' | 'html';
+export type ExportDOMElement = LexicalDOMExportOutput['element'];
 
-export interface ExportDOMOutput<TElement extends Element | null = Element | null, TType extends ExportDOMOutputType = ExportDOMOutputType> {
-    element: TElement;
+export type ExportDOMOutput<
+    TType extends ExportDOMOutputType = ExportDOMOutputType
+> = LexicalDOMExportOutput & {
     type: TType;
-}
+};
 
 export interface ExportDOMFeatureOptions {
     emailCustomization?: boolean;

packages/kg-default-nodes/src/generate-decorator-node.ts

@@ -114,6 +114,10 @@ export class GeneratedDecoratorNodeBase<TDataset extends Record<string, unknown>
         return null;
     }
 
+    isKoenigCard(): true {
+        return true;
+    }
+
     hasDynamicData(): boolean {
         return false;
     }
@@ -191,6 +195,10 @@ export function generateDecoratorNode<
             return nodeType;
         }
 
+        isKoenigCard(): true {
+            return true;
+        }
+
         /**
          * Creates a copy of an existing node with all its properties
          * @extends DecoratorNode

packages/kg-default-nodes/src/nodes/audio/audio-renderer.ts

@@ -23,10 +23,7 @@ interface DefaultAudioRenderOptions extends RenderOptions {
 
 type AudioRenderOptions = EmailAudioRenderOptions | DefaultAudioRenderOptions;
 
-export type AudioExportDOMOutput =
-    | ExportDOMOutput<HTMLDivElement>
-    | ExportDOMOutput<HTMLTableElement>
-    | ExportDOMOutput<HTMLSpanElement, 'inner'>;
+export type AudioExportDOMOutput = ExportDOMOutput;
 
 export function renderAudioNode(node: AudioNodeData, options: AudioRenderOptions = {}): AudioExportDOMOutput {
     addCreateDocumentOption(options);

packages/kg-default-nodes/src/nodes/call-to-action/calltoaction-renderer.ts

@@ -1,9 +1,10 @@
 import {addCreateDocumentOption} from '../../utils/add-create-document-option.js';
 import type {ExportDOMOptions} from '../../export-dom.js';
-import {renderWithVisibility, type RenderOutput, type Visibility} from '../../utils/visibility.js';
+import {renderWithVisibility, type Visibility} from '../../utils/visibility.js';
 import {getResizedImageDimensions} from '../../utils/get-resized-image-dimensions.js';
 import {isLocalContentImage} from '../../utils/is-local-content-image.js';
 import {buildCleanBasicHtmlForElement} from '../../utils/build-clean-basic-html-for-element.js';
+import {getFirstHtmlElement} from '../../utils/get-first-html-element.js';
 
 interface CTADataset {
     layout: string;
@@ -401,7 +402,7 @@ export function renderCallToActionNode(node: CTANodeData, options: CTARenderOpti
 
         emailDiv.innerHTML = emailCTATemplate(dataset, options);
 
-        return renderWithVisibility({element: emailDiv.firstElementChild as RenderOutput['element'], type: 'outer' as const}, node.visibility, options);
+        return renderWithVisibility({element: getFirstHtmlElement(emailDiv, 'renderCallToActionNode email'), type: 'outer' as const}, node.visibility, options);
     }
 
     if (dataset.hasSponsorLabel) {
@@ -415,5 +416,5 @@ export function renderCallToActionNode(node: CTANodeData, options: CTARenderOpti
 
     element.innerHTML = htmlString?.trim();
 
-    return renderWithVisibility({element: element.firstElementChild as RenderOutput['element'], type: 'outer' as const}, node.visibility, options);
+    return renderWithVisibility({element: getFirstHtmlElement(element, 'renderCallToActionNode'), type: 'outer' as const}, node.visibility, options);
 }

packages/kg-default-nodes/src/nodes/email/email-renderer.ts

@@ -10,7 +10,7 @@ interface EmailNodeData {
 
 interface RenderOptions extends ExportDOMOptions {}
 
-export function renderEmailNode(node: EmailNodeData, options: RenderOptions = {}): EmptyContainerOutput | ExportDOMOutput<HTMLDivElement, 'inner'> {
+export function renderEmailNode(node: EmailNodeData, options: RenderOptions = {}): EmptyContainerOutput | ExportDOMOutput<'inner'> {
     addCreateDocumentOption(options);
     const document = options.createDocument!();
 

packages/kg-default-nodes/src/nodes/file/file-renderer.ts

@@ -2,6 +2,7 @@ import {addCreateDocumentOption} from '../../utils/add-create-document-option.js
 import type {ExportDOMOptions} from '../../export-dom.js';
 import {renderEmptyContainer} from '../../utils/render-empty-container.js';
 import {escapeHtml} from '../../utils/escape-html.js';
+import {getFirstHtmlElement} from '../../utils/get-first-html-element.js';
 import {bytesToSize} from '../../utils/size-byte-converter.js';
 
 interface FileNodeData {
@@ -86,7 +87,7 @@ function emailTemplate(node: FileNodeData, document: Document, options: RenderOp
     const container = document.createElement('div');
     container.innerHTML = html.trim();
 
-    return {element: container.firstElementChild, type: 'outer' as const};
+    return {element: getFirstHtmlElement(container, 'renderFileNode emailTemplate'), type: 'outer' as const};
 }
 
 function cardTemplate(node: FileNodeData, document: Document) {

packages/kg-default-nodes/src/nodes/header/renderers/v2/header-renderer.ts

@@ -1,5 +1,6 @@
 import {addCreateDocumentOption} from '../../../../utils/add-create-document-option.js';
 import type {ExportDOMOptions} from '../../../../export-dom.js';
+import {getFirstHtmlElement} from '../../../../utils/get-first-html-element.js';
 import {slugify} from '../../../../utils/slugify.js';
 import {getSrcsetAttribute, type ImageRenderOptions} from '../../../../utils/srcset-attribute.js';
 
@@ -242,7 +243,7 @@ export function renderHeaderNodeV2(dataset: HeaderV2DatasetNode, options: Header
 
         emailDiv.innerHTML = emailTemplate(node, options)?.trim();
 
-        return {element: emailDiv.firstElementChild as HTMLDivElement, type: 'outer' as const};
+        return {element: getFirstHtmlElement(emailDiv, 'renderHeaderV2Node email') as HTMLDivElement, type: 'outer' as const};
     }
 
     const htmlString = cardTemplate(node, options);
@@ -264,7 +265,7 @@ export function renderHeaderNodeV2(dataset: HeaderV2DatasetNode, options: Header
         }
     }
 
-    return {element: element.firstElementChild as HTMLDivElement, type: 'outer' as const};
+    return {element: getFirstHtmlElement(element, 'renderHeaderV2Node') as HTMLDivElement, type: 'outer' as const};
 }
 
 export function getCardClasses(nodeData: HeaderV2NodeData) {

packages/kg-default-nodes/src/nodes/html/html-renderer.ts

@@ -11,7 +11,7 @@ interface HtmlNodeData {
 interface RenderOptions extends ExportDOMOptions {}
 
 export type HtmlExportDOMOutput =
-    ExportDOMOutput<Element, 'inner' | 'value' | 'html'>;
+    ExportDOMOutput<'inner' | 'value' | 'html'>;
 
 export function renderHtmlNode(node: HtmlNodeData, options: RenderOptions = {}): HtmlExportDOMOutput {
     addCreateDocumentOption(options);
@@ -29,7 +29,7 @@ export function renderHtmlNode(node: HtmlNodeData, options: RenderOptions = {}):
     textarea.value = wrappedHtml;
 
     if (node.visibility) {
-        const renderOutput: ExportDOMOutput<HTMLTextAreaElement, 'value'> = {element: textarea, type: 'value'};
+        const renderOutput: ExportDOMOutput<'value'> = {element: textarea, type: 'value'};
         return renderWithVisibility(renderOutput, node.visibility, options) as HtmlExportDOMOutput;
     }
 

packages/kg-default-nodes/src/nodes/markdown/markdown-renderer.ts

@@ -8,7 +8,7 @@ interface MarkdownNodeData {
 
 interface MarkdownRenderOptions extends ExportDOMOptions {}
 
-export function renderMarkdownNode(node: MarkdownNodeData, options: MarkdownRenderOptions = {}): ExportDOMOutput<HTMLDivElement, 'inner'> {
+export function renderMarkdownNode(node: MarkdownNodeData, options: MarkdownRenderOptions = {}): ExportDOMOutput<'inner'> {
     addCreateDocumentOption(options);
     if (typeof options.createDocument !== 'function') {
         throw new TypeError('renderMarkdownNode requires options.createDocument to be a function');