refactor: finalize exports

src/helpers/unstable_htmlAsRichText.ts

@@ -0,0 +1,121 @@
+import { Element } from "hast";
+import rehypeParse from "rehype-parse";
+import { unified } from "unified";
+
+import { RTPartialInlineNode } from "../lib/RichTextFieldBuilder";
+import { RehypeRichTextConfig, rehypeRichText } from "../lib/rehypeRichText";
+
+import {
+	RTInlineNode,
+	RTNode,
+	RichTextField,
+	RichTextNodeTypes,
+} from "../types/value/richText";
+
+// Used for TSDocs only.
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type { HTMLRichTextMapSerializer, asHTML } from "./asHTML";
+
+/**
+ * A shorthand definition for {@link RichTextHTMLMapSerializer} rich text node
+ * types.
+ *
+ * @remarks
+ * The `label` rich text node type is not available as is. Use an object
+ * containing your label name to convert to label nodes instead. For example:
+ * `u: { label: "underline" }`
+ * @remarks
+ * The `span` rich text node type is not available as it is not relevant in the
+ * context of going from HTML to Prismic rich text.
+ */
+export type RichTextHTMLMapSerializerShorthand =
+	| Exclude<RichTextNodeTypes, "label" | "span">
+	| { label: string };
+
+/**
+ * The payload provided to a {@link RichTextHTMLMapSerializerFunction}.
+ */
+type RichTextHTMLMapSerializerFunctionPayload = {
+	/**
+	 * The hast {@link Element} node to serialize.
+	 */
+	node: Element;
+
+	/**
+	 * Additional context information to help with the serialization.
+	 */
+	context: {
+		/**
+		 * The list type of the last list node encountered if any.
+		 */
+		listType?: "group-list-item" | "group-o-list-item";
+	};
+};
+
+/**
+ * Serializes a hast {@link Element} node to a
+ * {@link RichTextHTMLMapSerializerShorthand} or a rich text node.
+ *
+ * @remarks
+ * Serializing to a rich text node directly is not recommended and is only
+ * available as an escape hatch. Prefer returning a
+ * {@link RichTextHTMLMapSerializerShorthand} instead.
+ */
+export type RichTextHTMLMapSerializerFunction = (
+	payload: RichTextHTMLMapSerializerFunctionPayload,
+) =>
+	| RichTextHTMLMapSerializerShorthand
+	| RTNode
+	| RTInlineNode
+	| RTPartialInlineNode
+	| undefined;
+
+/**
+ * Serializes a hast {@link Element} node matching the given HTML tag name or CSS
+ * selector to a Prismic rich text node.
+ *
+ * @remarks
+ * This serializer is used to serialize HTML to Prismic rich text. When
+ * serializing Prismic rich text to HTML with {@link asHTML}, use the
+ * {@link HTMLRichTextMapSerializer} type instead.
+ */
+export type RichTextHTMLMapSerializer = Record<
+	string,
+	RichTextHTMLMapSerializerShorthand | RichTextHTMLMapSerializerFunction
+>;
+
+/**
+ * Configuration that determines the output of {@link htmlAsRichText}.
+ */
+export type HTMLAsRichTextConfig = RehypeRichTextConfig;
+
+/**
+ * The return type of {@link htmlAsRichText}.
+ */
+type HTMLAsRichTextReturnType = {
+	result: RichTextField;
+	warnings: string[];
+};
+
+/**
+ * Converts an HTML string to a rich text field.
+ *
+ * @param html - An HTML string.
+ * @param config - Configuration that determines the output the function.
+ *
+ * @returns `html` as rich text.
+ *
+ * @experimental Names and implementations may change in the future.
+ * `unstable_htmlAsRichText()` does not follow SemVer.
+ */
+export const unstable_htmlAsRichText = (
+	html: string,
+	config?: HTMLAsRichTextConfig,
+): HTMLAsRichTextReturnType => {
+	const { result, messages } = unified()
+		.use(rehypeParse, { emitParseErrors: true, missingDoctype: 0 })
+		.use(rehypeRichText, config)
+		.processSync(html);
+
+	return { result, warnings: messages.map((message) => message.toString()) };
+};

src/richtext/unstable_markdownAsRichText.ts → src/helpers/unstable_markdownAsRichText.ts

@@ -2,9 +2,9 @@ import remarkParse from "remark-parse";
 import remarkRehype from "remark-rehype";
 import { unified } from "unified";
 
-import { RichTextField } from "../types/value/richText";
+import { RehypeRichTextConfig, rehypeRichText } from "../lib/rehypeRichText";
 
-import { RehypeRichTextConfig, rehypeRichText } from "./utils/rehypeRichText";
+import { RichTextField } from "../types/value/richText";
 
 // Used for TSDocs only.
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
@@ -18,7 +18,7 @@ export type MarkdownAsRichTextConfig = RehypeRichTextConfig;
 /**
  * The return type of {@link markdownAsRichText}.
  */
-export type MarkdownAsRichTextReturnType = {
+type MarkdownAsRichTextReturnType = {
 	result: RichTextField;
 	warnings: string[];
 };

src/index.ts

@@ -80,6 +80,8 @@ export { mapSliceZone, unstable_mapSliceZone };
 
 // Conversion helper.
 export { documentToLinkField } from "./helpers/documentToLinkField";
+export { unstable_htmlAsRichText } from "./helpers/unstable_htmlAsRichText";
+export { unstable_markdownAsRichText } from "./helpers/unstable_markdownAsRichText";
 
 export type { LinkResolverFunction } from "./helpers/asLink";
 export type { AsLinkAttrsConfig } from "./helpers/asLinkAttrs";
@@ -101,10 +103,13 @@ export type {
 };
 export type { HTMLRichTextSerializer } from "./helpers/asHTML";
 
+export type { RichTextHTMLMapSerializer } from "./helpers/unstable_htmlAsRichText";
+
 //=============================================================================
 // Errors - Custom errors for Prismic APIs.
 //=============================================================================
 
+// Client Errors
 export { PrismicError } from "./errors/PrismicError";
 export { ForbiddenError } from "./errors/ForbiddenError";
 export { NotFoundError } from "./errors/NotFoundError";
@@ -114,6 +119,10 @@ export { PreviewTokenExpiredError } from "./errors/PreviewTokenExpired";
 export { ParsingError } from "./errors/ParsingError";
 export { RepositoryNotFoundError } from "./errors/RepositoryNotFoundError";
 
+// Rich Text Errors
+export { PrismicRichTextError } from "./errors/PrismicRichTextError";
+export { PrismicRichTextSerializerError } from "./errors/PrismicRichTextSerializerError";
+
 //=============================================================================
 // Types - Types representing Prismic content, models, and API payloads.
 //=============================================================================

src/richtext/utils/RichTextFieldBuilder.ts → src/lib/RichTextFieldBuilder.ts

@@ -4,7 +4,7 @@ import {
 	RTNode,
 	RTTextNode,
 	RichTextField,
-} from "../../types/value/richText";
+} from "../types/value/richText";
 
 import { PrismicRichTextError } from "../errors/PrismicRichTextError";
 

src/richtext/utils/hastSerializerHelpers.ts → src/lib/hastSerializerHelpers.ts

@@ -1,13 +1,9 @@
 import { Element } from "hast";
 import { toHtml } from "hast-util-to-html";
 
-import { OEmbedType } from "../../types/value/embed";
-import { LinkType } from "../../types/value/link";
-import {
-	RTEmbedNode,
-	RTImageNode,
-	RTLinkNode,
-} from "../../types/value/richText";
+import { OEmbedType } from "../types/value/embed";
+import { LinkType } from "../types/value/link";
+import { RTEmbedNode, RTImageNode, RTLinkNode } from "../types/value/richText";
 
 import { PrismicRichTextSerializerError } from "../errors/PrismicRichTextSerializerError";
 

src/richtext/utils/hastToRichText.ts → src/lib/hastToRichText.ts

@@ -11,14 +11,15 @@ import {
 	RTTextNode,
 	RichTextField,
 	RichTextNodeType,
-} from "../../types/value/richText";
+} from "../types/value/richText";
+
+import { PrismicRichTextSerializerError } from "../errors/PrismicRichTextSerializerError";
+
 import {
 	RichTextHTMLMapSerializer,
 	RichTextHTMLMapSerializerFunction,
 	RichTextHTMLMapSerializerShorthand,
-} from "../types";
-
-import { PrismicRichTextSerializerError } from "../errors/PrismicRichTextSerializerError";
+} from "../helpers/unstable_htmlAsRichText";
 
 import { RichTextFieldBuilder } from "./RichTextFieldBuilder";
 import {

src/richtext/utils/rehypeRichText.ts → src/lib/rehypeRichText.ts

@@ -6,11 +6,10 @@ import { remove } from "unist-util-remove";
 import { SKIP, visit } from "unist-util-visit";
 import { VFile } from "vfile";
 
-import { CustomTypeModelRichTextField } from "../../types/model/richText";
-import { RichTextField } from "../../types/value/richText";
-
-import { filterRichTextField } from "../filterRichTextField";
+import { CustomTypeModelRichTextField } from "../types/model/richText";
+import { RichTextField } from "../types/value/richText";
 
+import { filterRichTextField } from "./filterRichTextField";
 import { HASTToRichTextConfig, hastToRichText } from "./hastToRichText";
 
 /**

src/richtext/index.ts

@@ -4,19 +4,12 @@ export { asText } from "./asText";
 export { serialize } from "./serialize";
 export { wrapMapSerializer } from "./wrapMapSerializer";
 export { composeSerializers } from "./composeSerializers";
-export { filterRichTextField } from "./filterRichTextField";
+export { filterRichTextField } from "../lib/filterRichTextField";
 
 export { RichTextNodeType as Element } from "../types/value/richText";
 
-export { unstable_htmlAsRichText } from "./unstable_htmlAsRichText";
-export { unstable_markdownAsRichText } from "./unstable_markdownAsRichText";
-
-export { PrismicRichTextError } from "./errors/PrismicRichTextError";
-export { PrismicRichTextSerializerError } from "./errors/PrismicRichTextSerializerError";
-
 export type {
 	RichTextFunctionSerializer,
 	RichTextMapSerializer,
 	RichTextMapSerializerFunction,
-	RichTextHTMLMapSerializer,
 } from "./types";

src/richtext/types.ts

@@ -1,5 +1,3 @@
-import { Element } from "hast";
-
 import {
 	RTAnyNode,
 	RTEmNode,
@@ -11,12 +9,10 @@ import {
 	RTHeading5Node,
 	RTHeading6Node,
 	RTImageNode,
-	RTInlineNode,
 	RTLabelNode,
 	RTLinkNode,
 	RTListItemNode,
 	RTListNode,
-	RTNode,
 	RTOListItemNode,
 	RTOListNode,
 	RTParagraphNode,
@@ -27,8 +23,6 @@ import {
 	RichTextNodeTypes,
 } from "../types/value/richText";
 
-import { RTPartialInlineNode } from "./utils/RichTextFieldBuilder";
-
 // Serializers
 
 /**
@@ -158,68 +152,3 @@ export const RichTextReversedNodeType = {
 	[RichTextNodeType.list]: "list",
 	[RichTextNodeType.oList]: "oList",
 } as const;
-
-// hast serializers
-
-/**
- * A shorthand definition for {@link RichTextHTMLMapSerializer} rich text node
- * types.
- *
- * @remarks
- * The `label` rich text node type is not available as is. Use an object
- * containing your label name to convert to label nodes instead. For example:
- * `u: { label: "underline" }`
- * @remarks
- * The `span` rich text node type is not available as it is not relevant in the
- * context of going from HTML to Prismic rich text.
- */
-export type RichTextHTMLMapSerializerShorthand =
-	| Exclude<RichTextNodeTypes, "label" | "span">
-	| { label: string };
-
-/**
- * The payload provided to a {@link RichTextHTMLMapSerializerFunction}.
- */
-type RichTextHTMLMapSerializerFunctionPayload = {
-	/**
-	 * The hast {@link Element} node to serialize.
-	 */
-	node: Element;
-
-	/**
-	 * Additional context information to help with the serialization.
-	 */
-	context: {
-		/**
-		 * The list type of the last list node encountered if any.
-		 */
-		listType?: "group-list-item" | "group-o-list-item";
-	};
-};
-
-/**
- * Serializes a hast {@link Element} node to a
- * {@link RichTextHTMLMapSerializerShorthand} or a rich text node.
- *
- * @remarks
- * Serializing to a rich text node directly is not recommended and is only
- * available as an escape hatch. Prefer returning a
- * {@link RichTextHTMLMapSerializerShorthand} instead.
- */
-export type RichTextHTMLMapSerializerFunction = (
-	payload: RichTextHTMLMapSerializerFunctionPayload,
-) =>
-	| RichTextHTMLMapSerializerShorthand
-	| RTNode
-	| RTInlineNode
-	| RTPartialInlineNode
-	| undefined;
-
-/**
- * Serializes a hast {@link Element} node matching the given HTML tag name or CSS
- * selector to a Prismic rich text node.
- */
-export type RichTextHTMLMapSerializer = Record<
-	string,
-	RichTextHTMLMapSerializerShorthand | RichTextHTMLMapSerializerFunction
->;