@automattic/jetpack-ai-client 0.12.1 → 0.12.2

package/CHANGELOG.md

@@ -5,6 +5,10 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.12.2] - 2024-04-22
+### Added
+- AI Client: Add Markdown and HTML conversions. [#36906]
+
 ## [0.12.1] - 2024-04-15
 ### Added
 - AI Client: Add callbacks, initial requesting state and change error handling. [#36869]
@@ -286,6 +290,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Updated package dependencies. [#31659]
 - Updated package dependencies. [#31785]
 
+[0.12.2]: https://github.com/Automattic/jetpack-ai-client/compare/v0.12.1...v0.12.2
 [0.12.1]: https://github.com/Automattic/jetpack-ai-client/compare/v0.12.0...v0.12.1
 [0.12.0]: https://github.com/Automattic/jetpack-ai-client/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/Automattic/jetpack-ai-client/compare/v0.10.1...v0.11.0

package/build/index.d.ts

@@ -12,3 +12,4 @@ export * from './icons/index.js';
 export * from './components/index.js';
 export * from './data-flow/index.js';
 export * from './types.js';
+export * from './libs/index.js';

package/build/index.js

@@ -30,3 +30,7 @@ export * from './data-flow/index.js';
  * Types
  */
 export * from './types.js';
+/*
+ * Libs
+ */
+export * from './libs/index.js';

package/build/libs/index.d.ts

@@ -0,0 +1 @@
+export { MarkdownToHTML, HTMLToMarkdown, renderHTMLFromMarkdown, renderMarkdownFromHTML, } from './markdown/index.js';

package/build/libs/index.js

@@ -0,0 +1 @@
+export { MarkdownToHTML, HTMLToMarkdown, renderHTMLFromMarkdown, renderMarkdownFromHTML, } from './markdown/index.js';

package/build/libs/markdown/html-to-markdown.d.ts

@@ -0,0 +1,23 @@
+/**
+ * External dependencies
+ */
+import TurndownService from 'turndown';
+/**
+ * Types
+ */
+import type { Options, Rule } from 'turndown';
+export default class HTMLToMarkdown {
+    turndownService: TurndownService;
+    constructor(options?: Options, rules?: {
+        [key: string]: Rule;
+    });
+    /**
+     * Renders HTML from Markdown content with specified processing rules.
+     * @param {object} options         - The options to use when rendering the Markdown content
+     * @param {string} options.content - The HTML content to render
+     * @returns {string}                 The rendered Markdown content
+     */
+    render({ content }: {
+        content: string;
+    }): string;
+}

package/build/libs/markdown/html-to-markdown.js

@@ -0,0 +1,31 @@
+/**
+ * External dependencies
+ */
+import TurndownService from 'turndown';
+const defaultTurndownOptions = { emDelimiter: '_', headingStyle: 'atx' };
+const defaultTurndownRules = {
+    strikethrough: {
+        filter: ['del', 's'],
+        replacement: function (content) {
+            return '~~' + content + '~~';
+        },
+    },
+};
+export default class HTMLToMarkdown {
+    turndownService;
+    constructor(options = defaultTurndownOptions, rules = defaultTurndownRules) {
+        this.turndownService = new TurndownService(options);
+        for (const rule in rules) {
+            this.turndownService.addRule(rule, rules[rule]);
+        }
+    }
+    /**
+     * Renders HTML from Markdown content with specified processing rules.
+     * @param {object} options         - The options to use when rendering the Markdown content
+     * @param {string} options.content - The HTML content to render
+     * @returns {string}                 The rendered Markdown content
+     */
+    render({ content }) {
+        return this.turndownService.turndown(content);
+    }
+}

package/build/libs/markdown/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Internal dependencies
+ */
+import HTMLToMarkdown from './html-to-markdown.js';
+import MarkdownToHTML from './markdown-to-html.js';
+/**
+ * Types
+ */
+import type { Fix as HTMLFix } from './markdown-to-html.js';
+declare const renderHTMLFromMarkdown: ({ content, rules, }: {
+    content: string;
+    rules?: Array<HTMLFix> | 'all';
+}) => string;
+declare const renderMarkdownFromHTML: ({ content }: {
+    content: string;
+}) => string;
+export { MarkdownToHTML, HTMLToMarkdown, renderHTMLFromMarkdown, renderMarkdownFromHTML };

package/build/libs/markdown/index.js

@@ -0,0 +1,14 @@
+/**
+ * Internal dependencies
+ */
+import HTMLToMarkdown from './html-to-markdown.js';
+import MarkdownToHTML from './markdown-to-html.js';
+const defaultMarkdownConverter = new MarkdownToHTML();
+const defaultHTMLConverter = new HTMLToMarkdown();
+const renderHTMLFromMarkdown = ({ content, rules = 'all', }) => {
+    return defaultMarkdownConverter.render({ content, rules });
+};
+const renderMarkdownFromHTML = ({ content }) => {
+    return defaultHTMLConverter.render({ content });
+};
+export { MarkdownToHTML, HTMLToMarkdown, renderHTMLFromMarkdown, renderMarkdownFromHTML };

package/build/libs/markdown/markdown-to-html.d.ts

@@ -0,0 +1,24 @@
+/**
+ * External dependencies
+ */
+import MarkdownIt from 'markdown-it';
+/**
+ * Types
+ */
+import type { Options } from 'markdown-it';
+export type Fix = 'list';
+export default class MarkdownToHTML {
+    markdownConverter: MarkdownIt;
+    constructor(options?: Options);
+    /**
+     * Renders HTML from Markdown content with specified processing rules.
+     * @param {object} options         - The options to use when rendering the HTML content
+     * @param {string} options.content - The Markdown content to render
+     * @param {string} options.rules   - The rules to apply to the rendered content
+     * @returns {string}                 The rendered HTML content
+     */
+    render({ content, rules }: {
+        content: string;
+        rules: Array<Fix> | 'all';
+    }): string;
+}

package/build/libs/markdown/markdown-to-html.js

@@ -0,0 +1,33 @@
+/**
+ * External dependencies
+ */
+import MarkdownIt from 'markdown-it';
+const fixes = {
+    list: (content) => {
+        // Fix list indentation
+        return content.replace(/<li>\s+<p>/g, '<li>').replace(/<\/p>\s+<\/li>/g, '</li>');
+    },
+};
+const defaultMarkdownItOptions = {
+    breaks: true,
+};
+export default class MarkdownToHTML {
+    markdownConverter;
+    constructor(options = defaultMarkdownItOptions) {
+        this.markdownConverter = new MarkdownIt(options);
+    }
+    /**
+     * Renders HTML from Markdown content with specified processing rules.
+     * @param {object} options         - The options to use when rendering the HTML content
+     * @param {string} options.content - The Markdown content to render
+     * @param {string} options.rules   - The rules to apply to the rendered content
+     * @returns {string}                 The rendered HTML content
+     */
+    render({ content, rules = 'all' }) {
+        const rendered = this.markdownConverter.render(content);
+        const rulesToApply = rules === 'all' ? Object.keys(fixes) : rules;
+        return rulesToApply.reduce((renderedContent, rule) => {
+            return fixes[rule](renderedContent);
+        }, rendered);
+    }
+}

package/build/types.d.ts

@@ -28,4 +28,14 @@ export type { RecordingState } from './hooks/use-media-recording/index.js';
 export type CancelablePromise<T = void> = Promise<T> & {
     canceled?: boolean;
 };
+export type Block = {
+    attributes?: {
+        [key: string]: unknown;
+    };
+    clientId?: string;
+    innerBlocks?: Block[];
+    isValid?: boolean;
+    name?: string;
+    originalContent?: string;
+};
 export type TranscriptionState = RecordingState | 'validating' | 'processing' | 'error';

package/package.json

@@ -1,7 +1,7 @@
 {
 	"private": false,
 	"name": "@automattic/jetpack-ai-client",
-	"version": "0.12.1",
+	"version": "0.12.2",
 	"description": "A JS client for consuming Jetpack AI services",
 	"homepage": "https://github.com/Automattic/jetpack/tree/HEAD/projects/js-packages/ai-client/#readme",
 	"bugs": {
@@ -26,6 +26,8 @@
 		"@storybook/addon-actions": "8.0.6",
 		"@storybook/blocks": "8.0.6",
 		"@storybook/react": "8.0.6",
+		"@types/markdown-it": "14.0.0",
+		"@types/turndown": "5.0.4",
 		"jest": "^29.6.2",
 		"jest-environment-jsdom": "29.7.0",
 		"typescript": "5.0.4"
@@ -54,7 +56,9 @@
 		"@wordpress/icons": "9.46.0",
 		"classnames": "2.3.2",
 		"debug": "4.3.4",
+		"markdown-it": "14.0.0",
 		"react": "18.2.0",
-		"react-dom": "18.2.0"
+		"react-dom": "18.2.0",
+		"turndown": "7.1.2"
 	}
 }

package/src/index.ts

@@ -35,3 +35,8 @@ export * from './data-flow/index.js';
  * Types
  */
 export * from './types.js';
+
+/*
+ * Libs
+ */
+export * from './libs/index.js';

package/src/libs/index.ts

@@ -0,0 +1,6 @@
+export {
+	MarkdownToHTML,
+	HTMLToMarkdown,
+	renderHTMLFromMarkdown,
+	renderMarkdownFromHTML,
+} from './markdown/index.js';

package/src/libs/markdown/README.md

@@ -0,0 +1,74 @@
+# Markdown converters
+
+Typescript functions and classes to convert Markdown to and from HTML.
+
+## HTML to Markdown
+
+The HTML to Markdown conversion uses the [Turndown](https://github.com/mixmark-io/turndown) library and supports Turndown's options and rules.
+
+Example:
+```typescript
+/**
+ * External dependencies
+ */
+import { renderMarkdownFromHTML } from '@automattic/jetpack-ai-client';
+
+const htmlContent = '<strong>Hello world</strong>';
+const markdownContent = renderMarkdownFromHTML( { content: htmlContent } );
+// **Hello world**
+```
+
+To use custom options and rules:
+```typescript
+/**
+ * External dependencies
+ */
+import { HTMLToMarkdown } from '@automattic/jetpack-ai-client';
+
+const htmlContent = '<strong>Hello world</strong>';
+const options = { headingStyle: 'setext' };
+const rules = {
+	customStrong: {
+		filter: [ 'strong' ],
+		replacement: function( content: string ) {
+				return '***' + content + '***';
+		}
+ 	}
+};
+const renderer = new HTMLToMarkdown( options, rules );
+const markdownContent = renderer.render( { content: htmlContent } );
+// ***Hello world***
+```
+
+## Markdown to HTML
+
+The Markdown to HTML conversion uses the [markdown-it](https://github.com/markdown-it/markdown-it) library and supports markdown-it's options. It also adds access to common fixes.
+
+Example:
+```typescript
+/**
+ * External dependencies
+ */
+import { renderHTMLFromMarkdown } from '@automattic/jetpack-ai-client';
+
+const markdownContent = '**Hello world**';
+const htmlContent = renderHTMLFromMarkdown( { content: markdownContent, rules: 'all' } ); // 'all' is a default value
+// <p><strong>Hello world</strong></p>\n
+```
+
+To use custom options and fixes:
+```typescript
+/**
+ * External dependencies
+ */
+import { MarkdownToHTML } from '@automattic/jetpack-ai-client';
+
+const markdownContent = '**Hello world**';
+const options = { breaks: 'false' };
+const rules = [ 'list' ];
+const renderer = new MarkdownToHTML( options );
+const htmlContent = renderer.render( { content: markdownContent, rules } );
+// <p><strong>Hello world</strong></p>\n
+```
+
+Currently `rules` only supports `'all'` and `['list']`. Further specific fixes can be added when necessary.

package/src/libs/markdown/html-to-markdown.ts

@@ -0,0 +1,42 @@
+/**
+ * External dependencies
+ */
+import TurndownService from 'turndown';
+/**
+ * Types
+ */
+import type { Options, Rule } from 'turndown';
+
+const defaultTurndownOptions: Options = { emDelimiter: '_', headingStyle: 'atx' };
+const defaultTurndownRules: { [ key: string ]: Rule } = {
+	strikethrough: {
+		filter: [ 'del', 's' ],
+		replacement: function ( content: string ) {
+			return '~~' + content + '~~';
+		},
+	},
+};
+
+export default class HTMLToMarkdown {
+	turndownService: TurndownService;
+
+	constructor(
+		options: Options = defaultTurndownOptions,
+		rules: { [ key: string ]: Rule } = defaultTurndownRules
+	) {
+		this.turndownService = new TurndownService( options );
+		for ( const rule in rules ) {
+			this.turndownService.addRule( rule, rules[ rule ] );
+		}
+	}
+
+	/**
+	 * Renders HTML from Markdown content with specified processing rules.
+	 * @param {object} options         - The options to use when rendering the Markdown content
+	 * @param {string} options.content - The HTML content to render
+	 * @returns {string}                 The rendered Markdown content
+	 */
+	render( { content }: { content: string } ): string {
+		return this.turndownService.turndown( content );
+	}
+}

package/src/libs/markdown/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Internal dependencies
+ */
+import HTMLToMarkdown from './html-to-markdown.js';
+import MarkdownToHTML from './markdown-to-html.js';
+/**
+ * Types
+ */
+import type { Fix as HTMLFix } from './markdown-to-html.js';
+
+const defaultMarkdownConverter = new MarkdownToHTML();
+const defaultHTMLConverter = new HTMLToMarkdown();
+
+const renderHTMLFromMarkdown = ( {
+	content,
+	rules = 'all',
+}: {
+	content: string;
+	rules?: Array< HTMLFix > | 'all';
+} ) => {
+	return defaultMarkdownConverter.render( { content, rules } );
+};
+
+const renderMarkdownFromHTML = ( { content }: { content: string } ) => {
+	return defaultHTMLConverter.render( { content } );
+};
+
+export { MarkdownToHTML, HTMLToMarkdown, renderHTMLFromMarkdown, renderMarkdownFromHTML };

package/src/libs/markdown/markdown-to-html.ts

@@ -0,0 +1,48 @@
+/**
+ * External dependencies
+ */
+import MarkdownIt from 'markdown-it';
+/**
+ * Types
+ */
+import type { Options } from 'markdown-it';
+
+export type Fix = 'list';
+type Fixes = {
+	[ key in Fix ]: ( content: string ) => string;
+};
+
+const fixes: Fixes = {
+	list: ( content: string ) => {
+		// Fix list indentation
+		return content.replace( /<li>\s+<p>/g, '<li>' ).replace( /<\/p>\s+<\/li>/g, '</li>' );
+	},
+};
+
+const defaultMarkdownItOptions: Options = {
+	breaks: true,
+};
+
+export default class MarkdownToHTML {
+	markdownConverter: MarkdownIt;
+
+	constructor( options: Options = defaultMarkdownItOptions ) {
+		this.markdownConverter = new MarkdownIt( options );
+	}
+
+	/**
+	 * Renders HTML from Markdown content with specified processing rules.
+	 * @param {object} options         - The options to use when rendering the HTML content
+	 * @param {string} options.content - The Markdown content to render
+	 * @param {string} options.rules   - The rules to apply to the rendered content
+	 * @returns {string}                 The rendered HTML content
+	 */
+	render( { content, rules = 'all' }: { content: string; rules: Array< Fix > | 'all' } ): string {
+		const rendered = this.markdownConverter.render( content );
+		const rulesToApply = rules === 'all' ? Object.keys( fixes ) : rules;
+
+		return rulesToApply.reduce( ( renderedContent, rule ) => {
+			return fixes[ rule ]( renderedContent );
+		}, rendered );
+	}
+}

package/src/types.ts

@@ -93,6 +93,17 @@ export type { RecordingState } from './hooks/use-media-recording/index.js';
  */
 export type CancelablePromise< T = void > = Promise< T > & { canceled?: boolean };
 
+export type Block = {
+	attributes?: {
+		[ key: string ]: unknown;
+	};
+	clientId?: string;
+	innerBlocks?: Block[];
+	isValid?: boolean;
+	name?: string;
+	originalContent?: string;
+};
+
 /*
  * Transcription types
  */