@contember/react-richtext-renderer 1.3.0-alpha.9

package/dist/types/types/structure/RootEditorNode.d.ts

@@ -0,0 +1,8 @@
+import type { RichTextElement } from './RichTextElement';
+import type { RichTextLeaf } from './RichTextLeaf';
+import { RichTextChild } from './RichTextChild';
+export interface RootEditorNode<CustomElements extends RichTextElement = never, CustomLeaves extends RichTextLeaf = RichTextLeaf> {
+    formatVersion: number;
+    children: readonly RichTextChild<CustomElements, CustomLeaves>[];
+}
+//# sourceMappingURL=RootEditorNode.d.ts.map

package/dist/types/types/structure/RootEditorNode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RootEditorNode.d.ts","sourceRoot":"","sources":["../../../../src/types/structure/RootEditorNode.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAE/C,MAAM,WAAW,cAAc,CAC9B,cAAc,SAAS,eAAe,GAAG,KAAK,EAC9C,YAAY,SAAS,YAAY,GAAG,YAAY;IAEhD,aAAa,EAAE,MAAM,CAAA;IACrB,QAAQ,EAAE,SAAS,aAAa,CAAC,cAAc,EAAE,YAAY,CAAC,EAAE,CAAA;CAChE"}

package/dist/types/types/structure/index.d.ts

@@ -0,0 +1,5 @@
+export * from './RichTextChild';
+export * from './RichTextElement';
+export * from './RichTextLeaf';
+export * from './RootEditorNode';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/types/structure/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/types/structure/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAA;AAC/B,cAAc,mBAAmB,CAAA;AACjC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@contember/react-richtext-renderer",
+  "license": "Apache-2.0",
+  "version": "1.3.0-alpha.9",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/production/index.js",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/index.d.ts",
+        "development": "./dist/development/index.js",
+        "production": "./dist/production/index.js",
+        "default": "./dist/production/index.js"
+      },
+      "require": {
+        "types": "./dist/types/index.d.ts",
+        "development": "./dist/development/index.cjs",
+        "production": "./dist/production/index.cjs",
+        "default": "./dist/production/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist/",
+    "src/"
+  ],
+  "typings": "./dist/types/index.d.ts",
+  "scripts": {
+    "build": "yarn build:js:dev && yarn build:js:prod",
+    "build:js:dev": "vite build --mode development",
+    "build:js:prod": "vite build --mode production",
+    "ae:build": "api-extractor run --local",
+    "ae:test": "api-extractor run",
+    "test": "vitest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/contember/interface.git",
+    "directory": "packages/react-richtext-renderer"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^14.1.2",
+    "@testing-library/react-hooks": "^8.0.1"
+  },
+  "peerDependencies": {
+    "react": "^17 || ^18"
+  },
+  "stableVersion": "0.0.0"
+}

package/readme.md

@@ -0,0 +1,106 @@
+# Contember Rich Text renderer
+
+This package provides a React renderer for Contember Rich Text format.
+
+## Installation
+
+```bash
+yarn add @contember/react-richtext-renderer
+```
+
+## Usage for blocks
+
+```tsx
+import { RichTextBlocksRenderer } from '@contember/react-richtext-renderer'
+
+const App = () => {
+	const blocks = [] // blocks from Contember API
+
+	return (
+		<RichTextBlocksRenderer
+			blocks={blocks}
+			sourceField={'content'}
+			referencesField={'references'}
+			referenceDiscriminationField={'type'}
+		/>
+	)
+}
+```
+
+## Usage for standalone rich text field
+
+```tsx
+import { RichTextFieldRenderer } from '@contember/react-richtext-renderer'
+
+const App = () => {
+	const value = {} // value from Contember API
+
+	return (
+		<RichTextFieldRenderer
+			source={value}
+		/>
+	)
+}
+```
+
+## Custom elements
+
+```tsx
+import { RichTextBlocksRenderer } from '@contember/react-richtext-renderer'
+
+const App = () => {
+	// ...    
+	return (
+		<RichTextBlocksRenderer
+			// ...
+			renderElement={it => {
+				if (it.element.type === 'blockquote') {
+					return <blockquote>{it.children}</blockquote>
+				}
+				return it.fallback
+			}}
+		/>
+	)
+}
+```
+
+## Custom leafs
+
+```tsx
+import { RichTextBlocksRenderer } from '@contember/react-richtext-renderer'
+
+const App = () => {
+	// ...    
+	return (
+		<RichTextBlocksRenderer
+			// ...
+			renderLeaf={it => {
+				if (it.leaf.isSup) {
+					return <sup>{it.fallback}</sup>
+				}
+				return it.fallback
+			}}
+		/>
+	)
+}
+```
+
+Make sure to use `it.fallback` instead of `it.children` in `renderLeaf` callback, to render already applied leafs as well.
+
+## Custom references
+
+```tsx
+import { RichTextBlocksRenderer } from '@contember/react-richtext-renderer'
+
+const App = () => {
+	// ...    
+	return (
+		<RichTextBlocksRenderer
+			// ...
+			referenceRenderers={{
+				image: ({ reference }) => <img src={reference.url} />,
+			}}
+		/>
+	)
+}
+```

package/src/RichTextRendererError.ts

@@ -0,0 +1 @@
+export class RichTextRendererError extends Error {}

package/src/components/RichText.tsx

@@ -0,0 +1,52 @@
+import { createElement } from 'react'
+import { renderChildren } from '../internal/renderChildren'
+import type { RichTextBlock } from '../types'
+import { RichTextElement, RichTextLeaf, RichTextRenderingOptions } from '../types'
+
+export type RichTextProps<
+	CustomElements extends RichTextElement = never,
+	CustomLeaves extends RichTextLeaf = RichTextLeaf,
+> =
+	& {
+		blocks: RichTextBlock<CustomElements, CustomLeaves>[]
+	}
+	& RichTextRenderingOptions<CustomElements, CustomLeaves>
+
+/**
+ * Accepts normalized decoded RichText blocks and renders them using the provided renderers.
+ * To use decoders, use `RichTextBlocksRenderer` or `RichTextFieldRenderer` instead.
+ *
+ * @group Content rendering
+ */
+export const RichText = <
+	CustomElements extends RichTextElement = never,
+	CustomLeaves extends RichTextLeaf = RichTextLeaf,
+>({
+	blocks,
+	renderElement,
+	renderLeaf,
+	renderBlock = ({ children }) => <>{children}</>,
+	attributeNamePrefix,
+	referenceRenderers,
+	undefinedReferenceHandler,
+}: RichTextProps<CustomElements, CustomLeaves>) => {
+	return (
+		<>
+			{blocks.map((block, i) => (
+				createElement(
+					renderBlock, {
+						block,
+						key: block.id ?? i,
+					}, renderChildren(block.content.children, {
+						referenceRenderers,
+						renderBlock,
+						renderLeaf,
+						renderElement,
+						attributeNamePrefix,
+						undefinedReferenceHandler,
+					}, block),
+				)
+			))}
+		</>
+	)
+}

package/src/components/RichTextBlocksRenderer.tsx

@@ -0,0 +1,40 @@
+import { RichTextBlockSource, RichTextElement, RichTextLeaf, RichTextRenderingOptions } from '../types'
+import { RichText } from './RichText'
+import { useRichTextBlocksSource } from '../hooks'
+
+export type { RichTextBlockSource }
+
+export type RichTextBlocksRendererProps<CustomElements extends RichTextElement = never, CustomLeaves extends RichTextLeaf = RichTextLeaf> =
+	& RichTextBlockSource<CustomElements, CustomLeaves>
+	& RichTextRenderingOptions<CustomElements, CustomLeaves>
+
+/**
+ * Accepts raw RichText blocks and renders them using the provided renderers.
+ *
+ * @group Content rendering
+ */
+export const RichTextBlocksRenderer = <
+	CustomElements extends RichTextElement = never,
+	CustomLeaves extends RichTextLeaf = RichTextLeaf,
+>({
+	renderElement,
+	renderLeaf,
+	renderBlock = ({ children }) => <>{children}</>,
+	attributeNamePrefix,
+	referenceRenderers,
+	undefinedReferenceHandler,
+	...props
+}: RichTextBlocksRendererProps<CustomElements, CustomLeaves>) => {
+	const blocks = useRichTextBlocksSource<CustomElements, CustomLeaves>(props)
+	return (
+		<RichText<CustomElements, CustomLeaves>
+			blocks={blocks}
+			renderElement={renderElement}
+			renderLeaf={renderLeaf}
+			renderBlock={renderBlock}
+			referenceRenderers={referenceRenderers}
+			undefinedReferenceHandler={undefinedReferenceHandler}
+			attributeNamePrefix={attributeNamePrefix}
+		/>
+	)
+}

package/src/components/RichTextFieldRenderer.tsx

@@ -0,0 +1,42 @@
+import { RichText } from './RichText'
+import { RichTextElement, RichTextFieldSource, RichTextLeaf, RichTextRenderingOptions } from '../types'
+import { useRichTextFieldSource } from '../hooks'
+
+export type { RichTextFieldSource }
+
+export type RichTextFieldRendererProps<
+	CustomElements extends RichTextElement = never,
+	CustomLeaves extends RichTextLeaf = RichTextLeaf,
+> =
+	& RichTextFieldSource<CustomElements, CustomLeaves>
+	& RichTextRenderingOptions<CustomElements, CustomLeaves>
+
+/**
+ * Accepts raw RichText field source and renders them using the provided renderers.
+ *
+ * @group Content rendering
+ */
+export const RichTextFieldRenderer = <
+	CustomElements extends RichTextElement = never,
+	CustomLeaves extends RichTextLeaf = RichTextLeaf,
+>({
+	renderLeaf,
+	renderBlock,
+	renderElement,
+	attributeNamePrefix,
+	undefinedReferenceHandler,
+	...source
+}: RichTextFieldRendererProps<CustomElements, CustomLeaves>) => {
+	const blocks = useRichTextFieldSource(source)
+
+	return (
+		<RichText<CustomElements, CustomLeaves>
+			blocks={blocks}
+			renderElement={renderElement}
+			renderLeaf={renderLeaf}
+			renderBlock={renderBlock}
+			attributeNamePrefix={attributeNamePrefix}
+			undefinedReferenceHandler={undefinedReferenceHandler}
+		/>
+	)
+}

package/src/components/RichTextRenderer.tsx

@@ -0,0 +1,31 @@
+import { memo, ReactElement } from 'react'
+import type { RichTextElement } from '../types/structure/RichTextElement'
+import type { RichTextLeaf } from '../types/structure/RichTextLeaf'
+import { RichTextFieldRenderer, RichTextFieldRendererProps } from './RichTextFieldRenderer'
+import { RichTextBlocksRenderer, RichTextBlocksRendererProps } from './RichTextBlocksRenderer'
+
+
+export type RichTextRendererProps<
+	CustomElements extends RichTextElement = never,
+	CustomLeaves extends RichTextLeaf = RichTextLeaf,
+> =
+	| RichTextFieldRendererProps<CustomElements, CustomLeaves>
+	| RichTextBlocksRendererProps<CustomElements, CustomLeaves>
+
+/**
+ * @deprecated Use `RichTextBlocksRenderer` or `RichTextFieldRenderer` instead, or directly use `RichText`.
+ * @group Content rendering
+ */
+export const RichTextRenderer = memo(function RichTextRenderer<
+	CustomElements extends RichTextElement = never,
+	CustomLeaves extends RichTextLeaf = RichTextLeaf,
+>(props: RichTextRendererProps<CustomElements, CustomLeaves>) {
+
+	if ('source' in props) {
+		return <RichTextFieldRenderer<CustomElements, CustomLeaves> {...props} />
+	}
+
+	return <RichTextBlocksRenderer<CustomElements, CustomLeaves> {...props} />
+}) as <CustomElements extends RichTextElement = never, CustomLeaves extends RichTextLeaf = RichTextLeaf>(
+	props: RichTextRendererProps<CustomElements, CustomLeaves>,
+) => ReactElement

package/src/components/index.ts

@@ -0,0 +1,4 @@
+export * from './RichText'
+export * from './RichTextFieldRenderer'
+export * from './RichTextBlocksRenderer'
+export * from './RichTextRenderer'

package/src/hooks/index.ts

@@ -0,0 +1,2 @@
+export * from './useRichTextFieldSource'
+export * from './useRichTextBlocksSource'

package/src/hooks/useRichTextBlocksSource.ts

@@ -0,0 +1,75 @@
+import { RichTextBlock, RichTextBlockSource, RichTextElement, RichTextLeaf, RichTextReference, RootEditorNode } from '../types'
+import { defaultDeserialize } from '../internal/defaultDeserialize'
+import { useMemo } from 'react'
+import { RichTextRendererError } from '../RichTextRendererError'
+
+export const useRichTextBlocksSource = <CustomElements extends RichTextElement, CustomLeaves extends RichTextLeaf>({
+	deserialize = defaultDeserialize,
+	blocks,
+	referencesField = 'references',
+	sourceField = 'source',
+	referenceDiscriminationField = 'type',
+}: RichTextBlockSource<CustomElements, CustomLeaves>) => {
+	return useMemo((): RichTextBlock<CustomElements, CustomLeaves>[] => {
+		const sourceFieldResolved = sourceField ?? 'source'
+		const referencesFieldResolved = referencesField ?? 'references'
+		const referenceDiscriminationFieldResolved = referenceDiscriminationField ?? 'type'
+
+		return blocks.map(block => {
+			if (!(sourceField in block)) {
+				throw new RichTextRendererError(
+					`Found a block without a '${sourceFieldResolved}' field. ` +
+					(sourceField === undefined
+						? `The 'sourceField' prop has not been supplied, and so '${sourceFieldResolved}' was used as a default.`
+						: `That is what the 'sourceField' prop has been set to, and so either this is a typo, ` +
+						`or the data supplied is invalid.`),
+				)
+			}
+			const source = block[sourceFieldResolved]
+			if (typeof source !== 'string' && (typeof source !== 'object' || source === null)) {
+				throw new RichTextRendererError(`Found a block whose source is not a string or an object.`)
+			}
+
+			if (referencesField !== undefined && !(referencesFieldResolved in block)) {
+				throw new RichTextRendererError(
+					`The 'referencesField' prop is set to '${referencesFieldResolved}' but a block without such field ` +
+					`has been encountered. Unless this is just a typo, ` +
+					`if you do not wish to use references, avoid supplying the 'referencesField' prop.`,
+				)
+			}
+			const references = block[referencesFieldResolved]
+
+			let normalizedReferences: Record<string, RichTextReference> | undefined = undefined
+			if (references) {
+				if (typeof Object(references)[Symbol.iterator] !== 'function') {
+					throw new RichTextRendererError(`The set of references must be an iterable!`)
+				}
+
+				normalizedReferences = Object.fromEntries(Array.from(references as Iterable<RichTextReference>).map(reference => {
+					if (!('id' in reference)) {
+						throw new RichTextRendererError(`Found a reference without an id field.`)
+					}
+					if (!(referenceDiscriminationFieldResolved in reference) || typeof reference[referenceDiscriminationFieldResolved] !== 'string') {
+						throw new RichTextRendererError(
+							`Found a reference without a '${referenceDiscriminationFieldResolved}' field. ` +
+							(referenceDiscriminationField === undefined
+								? `The 'referenceDiscriminationField' prop has not been supplied, ` +
+								`and so '${referenceDiscriminationFieldResolved}' was used as a default.`
+								: `That is what the 'referenceDiscriminationField' prop has been set to, ` +
+								`and so either this is a typo, or the data supplied is invalid.`),
+						)
+					}
+					return [reference.id, {
+						...reference,
+						type: reference[referenceDiscriminationFieldResolved] as string,
+					}]
+				}))
+			}
+			return {
+				id: typeof block.id === 'string' ? block.id : undefined,
+				content: typeof source === 'string' ? deserialize(source) : source as RootEditorNode<CustomElements, CustomLeaves>,
+				references: normalizedReferences,
+			}
+		})
+	}, [blocks, deserialize, referenceDiscriminationField, referencesField, sourceField])
+}

package/src/hooks/useRichTextFieldSource.ts

@@ -0,0 +1,26 @@
+import { RichTextBlock, RichTextElement, RichTextFieldSource, RichTextLeaf } from '../types'
+import { useMemo } from 'react'
+import { defaultDeserialize } from '../internal/defaultDeserialize'
+
+export const useRichTextFieldSource = <CustomElements extends RichTextElement, CustomLeaves extends RichTextLeaf>({
+	source,
+	deserialize = defaultDeserialize,
+}: RichTextFieldSource<CustomElements, CustomLeaves>): RichTextBlock<CustomElements, CustomLeaves>[] => {
+	return useMemo(() => {
+		return [
+			{
+				content: source
+					? (typeof source === 'string' ? deserialize(source) : source)
+					: {
+						formatVersion: 0,
+						children: [],
+					},
+				id: undefined,
+				referencesField: undefined,
+				referenceDiscriminationField: undefined,
+				referenceRenderers: {},
+				references: undefined,
+			},
+		]
+	}, [deserialize, source])
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './components'
+export * from './hooks'
+export * from './types'
+
+export * from './RichTextRendererError'
+

package/src/internal/components/ElementRenderer.tsx

@@ -0,0 +1,48 @@
+import type { ReactElement } from 'react'
+import { createElement } from 'react'
+import type { BuiltinElements } from '../../types/builtin/BuiltinElements'
+import { renderChildren } from '../renderChildren'
+import { RenderElementFallback } from './RenderElementFallback'
+import { useReferenceMetadata } from '../useReferenceMetadata'
+import type { RichTextElement } from '../../types/structure/RichTextElement'
+import type { RichTextLeaf } from '../../types/structure/RichTextLeaf'
+import { RichTextBlock } from '../../types/RichTextBlock'
+import { RichTextRenderingOptions } from '../../types/RichTextRenderingOptions'
+
+
+export interface ElementRendererProps<
+	CustomElements extends RichTextElement = never,
+	CustomLeaves extends RichTextLeaf = RichTextLeaf,
+> {
+	element: CustomElements | BuiltinElements<CustomElements, CustomLeaves>
+	children: ReactElement
+	options: RichTextRenderingOptions<CustomElements, CustomLeaves>
+	block: RichTextBlock<CustomElements, CustomLeaves>
+}
+
+export function ElementRenderer<
+	CustomElements extends RichTextElement = never,
+	CustomLeaves extends RichTextLeaf = RichTextLeaf,
+>({ element, children, options, block }: ElementRendererProps<CustomElements, CustomLeaves>) {
+	const referenceMetadata = useReferenceMetadata<CustomElements, CustomLeaves>(element, options, block)
+
+	const fallback = (
+		<RenderElementFallback<CustomElements, CustomLeaves> element={element as BuiltinElements<CustomElements, CustomLeaves>} options={options} block={block}>
+			{children}
+		</RenderElementFallback>
+	)
+
+	return options.renderElement
+		? createElement(options.renderElement, {
+			...referenceMetadata,
+			formatVersion: block.content.formatVersion,
+			block,
+			options,
+			element,
+			fallback,
+			children,
+			renderChildren: (children, opts = options) => renderChildren(children, opts, block),
+			renderChildrenOptions: options,
+		})
+		: fallback
+}

package/src/internal/components/LeafRenderer.tsx

@@ -0,0 +1,36 @@
+import { createElement } from 'react'
+import type { BuiltinLeaves } from '../../types/builtin/BuiltinLeaves'
+import { RenderLeafFallback } from './RenderLeafFallback'
+import type { RichTextLeaf } from '../../types/structure/RichTextLeaf'
+import { RichTextElement } from '../../types/structure/RichTextElement'
+import { RichTextRenderingOptions } from '../../types/RichTextRenderingOptions'
+import { RichTextBlock } from '../../types/RichTextBlock'
+
+export interface LeafRendererProps<CustomElements extends RichTextElement = never, CustomLeaves extends RichTextLeaf = RichTextLeaf> {
+	options: RichTextRenderingOptions<CustomElements, CustomLeaves>
+	block: RichTextBlock<CustomElements, CustomLeaves>
+	leaf: CustomLeaves & BuiltinLeaves
+}
+
+export function LeafRenderer<
+	CustomElements extends RichTextElement = never,
+	CustomLeaves extends RichTextLeaf = RichTextLeaf,
+>({
+	leaf,
+	options: { renderLeaf },
+	block: { content: { formatVersion } },
+}: LeafRendererProps<CustomElements, CustomLeaves>) {
+	const fallback = <RenderLeafFallback leaf={leaf} />
+
+	return renderLeaf
+		? createElement(
+				renderLeaf,
+				{
+					formatVersion,
+					leaf,
+					fallback,
+					children: leaf.text,
+				},
+		  )
+		: fallback
+}