Refactor RichText core and Replace dangerouslySetInnerHTML with RichText component in samples and documentation

Author: TRomesh

docs/6-rendering-react.md

@@ -7,6 +7,8 @@ In this page you will learn how to create a React component for your content typ
 Open the `src/app/components/Article.tsx` file and add the following
 
 ```tsx
+import { RichText } from '@episerver/cms-sdk/react/richText';
+
 type Props = {
   opti: Infer<typeof ArticleContentType>;
 };
@@ -15,19 +17,60 @@ export default function Article({ opti }: Props) {
   return (
     <main>
       <h1>{opti.heading}</h1>
-      <div dangerouslySetInnerHTML={{ __html: opti.body?.html ?? '' }} />
+      <RichText content={opti.body?.json} />
     </main>
   );
 }
 ```
 
-> [!WARNING]
-> Using [React `dangerouslySetInnerHTML`](https://legacy.reactjs.org/docs/dom-elements.html#dangerouslysetinnerhtml) can introduce XSS risks. In production environments you should sanitize the HTML or use `opti.body?.json` (which gives the content as JSON)
+> [!TIP]
+> Using the `<RichText/>` component is the recommended way to render rich text content. It's safer than `dangerouslySetInnerHTML` as it doesn't rely on HTML parsing, and allows you to customize how elements are rendered with your own React components.
+
+### Customizing Rich Text Elements
+
+You can customize how specific elements are rendered by providing custom components:
+
+```tsx
+import { RichText, type ElementProps } from '@episerver/cms-sdk/react/richText';
+
+// Custom heading renderer
+const CustomHeading = (props: ElementProps) => (
+  <h2 style={{ color: 'blue', fontSize: '1.8rem' }}>{props.children}</h2>
+);
+
+// Custom link renderer
+const CustomLink = (props: ElementProps) => (
+  <a
+    href={props.element.url}
+    style={{ color: 'purple', textDecoration: 'underline' }}
+    target="_blank"
+    rel="noopener noreferrer"
+  >
+    {props.children}
+  </a>
+);
+
+export default function Article({ opti }: Props) {
+  return (
+    <main>
+      <h1>{opti.heading}</h1>
+      <RichText
+        content={opti.body?.json}
+        elements={{
+          'heading-two': CustomHeading,
+          link: CustomLink,
+        }}
+      />
+    </main>
+  );
+}
+```
 
 The entire file should look like this:
 
 ```tsx
 import { contentType, Infer } from '@episerver/cms-sdk';
+import { RichText } from '@episerver/cms-sdk/react/richText';
 
 export const ArticleContentType = contentType({
   key: 'Article',
@@ -50,7 +93,7 @@ export default function Article({ opti }: Props) {
   return (
     <main>
       <h1>{opti.heading}</h1>
-      <div dangerouslySetInnerHTML={{ __html: opti.body?.html ?? '' }} />
+      <RichText content={opti.body?.json} />
     </main>
   );
 }

packages/optimizely-cms-sdk/src/components/richText/index.ts

@@ -9,6 +9,11 @@ export type {
   TextWithMark,
   RendererConfig,
   HtmlComponentConfig,
+  BaseElementRendererProps,
+  BaseLeafRendererProps,
+  BaseElementMap,
+  BaseLeafMap,
+  RichTextPropsBase,
 } from './renderer.js';
 export { isText, isElement } from './renderer.js';
 export type { RenderNode } from './renderer.js';

packages/optimizely-cms-sdk/src/components/richText/renderer.ts

@@ -63,6 +63,86 @@ export type TextWithMark<T extends MarkType> = Text & {
   [K in T]: true;
 };
 
+/**
+ * Props for element renderer components (framework-agnostic)
+ */
+export interface BaseElementRendererProps {
+  element: Element;
+  attributes?: Record<string, unknown>;
+  text?: string; // Enhanced API - direct text access (optional for backward compatibility)
+}
+
+/**
+ * Props for leaf renderer components (framework-agnostic)
+ */
+export interface BaseLeafRendererProps {
+  leaf: Text;
+  attributes?: Record<string, unknown>;
+  text?: string; // Enhanced API - direct text access (optional for backward compatibility)
+}
+
+/**
+ * Generic mapping from element types to renderer components
+ * Can be specialized for each framework: ElementMap<ReactComponent>, ElementMap<VueComponent>, etc.
+ */
+export type BaseElementMap<TRenderer = unknown> = {
+  [K in ElementType]?: TRenderer;
+} & {
+  [key: string]: TRenderer;
+};
+
+/**
+ * Generic mapping from leaf mark types to renderer components
+ * Can be specialized for each framework: LeafMap<ReactComponent>, LeafMap<VueComponent>, etc.
+ */
+export type BaseLeafMap<TRenderer = unknown> = {
+  [K in MarkType]?: TRenderer;
+} & {
+  [key: string]: TRenderer;
+};
+
+/**
+ * Generic props for RichText component (framework-agnostic)
+ * Can be specialized for each framework with specific renderer types
+ */
+export interface RichTextPropsBase<
+  TElementRenderer = unknown,
+  TLeafRenderer = unknown
+> {
+  /**
+   * Slate.js compatible JSON content to render
+   */
+  content?: {
+    type: 'richText';
+    children: Node[];
+  };
+
+  /**
+   * Custom components for rendering elements by type
+   */
+  elements?: BaseElementMap<TElementRenderer>;
+
+  /**
+   * Custom components for rendering text marks
+   */
+  leafs?: BaseLeafMap<TLeafRenderer>;
+
+  /**
+   * Fallback element type when no custom renderer is found
+   */
+  elementFallback?: string;
+
+  /**
+   * Fallback leaf element type when no custom renderer is found
+   */
+  leafFallback?: string;
+
+  /**
+   * Whether to decode HTML entities in text content
+   */
+  decodeHtmlEntities?: boolean;
+}
+
 /**
  * Available element types in the default implementation
  */

packages/optimizely-cms-sdk/src/react/richText/index.ts

@@ -5,18 +5,17 @@ export {
   createHtmlComponent,
   createLeafComponent,
 } from './lib.js';
+
 export type {
-  ElementRendererProps,
-  LeafRendererProps,
+  ElementProps,
+  LeafProps,
+  ElementRenderer,
+  LeafRenderer,
   ElementMap,
   LeafMap,
+  RichTextProps,
 } from './lib.js';
 
-// Class-based renderer (alternative approach)
-export { ReactRichTextRenderer, createReactRenderer } from './renderer.js';
-export type { ReactRendererConfig } from './renderer.js';
-
-// Re-export core types that React users might need
 export type {
   Node,
   Element,

packages/optimizely-cms-sdk/src/react/richText/lib.ts

@@ -3,42 +3,35 @@ import type { PropsWithChildren, JSX } from 'react';
 import {
   defaultElementTypeMap,
   defaultMarkTypeMap,
-} from '../../components/richText/renderer.js';
-import type {
-  Node,
-  Text,
-  Element,
-  ElementType,
-  MarkType,
+  type BaseElementRendererProps,
+  type BaseLeafRendererProps,
+  type BaseElementMap,
+  type BaseLeafMap,
+  type HtmlComponentConfig,
+  type RichTextPropsBase,
 } from '../../components/richText/renderer.js';
 
 /**
- * Props for React element renderer components
+ * React-specific element renderer props (extends shared props with React children)
  */
-export interface ElementRendererProps extends PropsWithChildren {
-  element: Element;
-  attributes?: Record<string, unknown>;
-  text?: string; // Enhanced API - direct text access (optional for backward compatibility)
-}
+export interface ElementRendererProps
+  extends BaseElementRendererProps,
+    PropsWithChildren {}
 
 /**
- * Better named alias for ElementRendererProps - more intuitive and developer-friendly
- * Use this for new code: ({ text, attributes, element }: ElementProps) => JSX.Element
+ * Prop type used for custom Element components
  */
 export type ElementProps = ElementRendererProps;
 
 /**
- * Props for React leaf renderer components
+ * React-specific leaf renderer props (extends shared props with React children)
  */
-export interface LeafRendererProps extends PropsWithChildren {
-  leaf: Text;
-  attributes?: Record<string, unknown>;
-  text?: string; // Enhanced API - direct text access (optional for backward compatibility)
-}
+export interface LeafRendererProps
+  extends BaseLeafRendererProps,
+    PropsWithChildren {}
 
 /**
- * Better named alias for LeafRendererProps - more intuitive and developer-friendly
- * Use this for new code: ({ text, attributes, leaf }: LeafProps) => JSX.Element
+ * Prop type used for custom Leaf components
  */
 export type LeafProps = LeafRendererProps;
 
@@ -47,105 +40,26 @@ export type LeafProps = LeafRendererProps;
  */
 export type ElementRenderer = React.ComponentType<ElementRendererProps>;
 
-/**
- * Better named alias for ElementRenderer - more intuitive and developer-friendly
- * Use this for new code: const MyComponent: ElementComponent = ({ text, attributes }) => JSX.Element
- */
-export type ElementComponent = ElementRenderer;
-
 /**
  * React component for rendering Slate text leaves
  */
 export type LeafRenderer = React.ComponentType<LeafRendererProps>;
 
 /**
- * Better named alias for LeafRenderer - more intuitive and developer-friendly
- * Use this for new code: const MyComponent: LeafComponent = ({ text, attributes }) => JSX.Element
+ * React-specific mapping types (specializes generic types with React components)
  */
-export type LeafComponent = LeafRenderer;
+export type ElementMap = BaseElementMap<ElementRenderer>;
 
 /**
- * Mapping from element types to React renderer components
- * Provides IntelliSense for known element types while allowing custom types
+ * React-specific mapping types (specializes generic types with React components)
  */
-export type ElementMap = {
-  [K in ElementType]?: ElementRenderer;
-} & {
-  [key: string]: ElementRenderer;
-};
+export type LeafMap = BaseLeafMap<LeafRenderer>;
 
 /**
- * Mapping from leaf mark types to React renderer components
- * Provides IntelliSense for known mark types while allowing custom types
+ * React-specific RichText props
  */
-export type LeafMap = {
-  [K in MarkType]?: LeafRenderer;
-} & {
-  [key: string]: LeafRenderer;
-};
-
-/**
- * Props for the main React RichText component
- */
-export interface RichTextProps {
-  /**
-   * Slate.js compatible JSON content to render
-   */
-  content?: {
-    type: 'richText';
-    children: Node[];
-  };
-
-  /**
-   * Custom React components for rendering elements by type
-   */
-  elements?: ElementMap;
-
-  /**
-   * Custom React components for rendering text marks
-   */
-  leafs?: LeafMap;
-
-  /**
-   * Fallback element type when no custom renderer is found
-   */
-  elementFallback?: string;
-
-  /**
-   * Fallback leaf element type when no custom renderer is found
-   */
-  leafFallback?: string;
-
-  /**
-   * Whether to decode HTML entities in text content
-   */
-  decodeHtmlEntities?: boolean;
-}
-
-/**
- * Utility type for Slate.js content arrays
- */
-export type Content = Node[];
-
-/**
- * Configuration for HTML component creation
- */
-export interface HtmlComponentConfig {
-  /**
-   * Whether the element is self-closing (like <img>, <br>)
-   */
-  selfClosing?: boolean;
-
-  /**
-   * Default CSS class to apply
-   */
-  className?: string;
-
-  /**
-   * Additional HTML attributes to apply
-   */
-  attributes?: Record<string, unknown>;
-}
+export interface RichTextProps
+  extends RichTextPropsBase<ElementRenderer, LeafRenderer> {}
 
 /**
  * Converts framework-agnostic attributes to React props