Merge pull request #151 from episerver/bugfix/CMS-46488-richtext-fallback

CMS-46488 Fix/Improve Richtext fallback Issues

Author: TRomesh

docs/6-rendering-react.md

@@ -66,6 +66,9 @@ export default function Article({ opti }: Props) {
 }
 ```
 
+> [!NOTE]
+> For comprehensive documentation on the RichText component including all props, advanced customization options, fallback handling, and TypeScript support, see the [RichText Component Reference](./6.1-richtext-component-react.md).
+
 The entire file should look like this:
 
 ```tsx

docs/7-richtext-component-react.md renamed to docs/6.1-richtext-component-react.md

@@ -201,119 +201,6 @@ const CodeExample = ({ content }) => (
 );
 ```
 
-### `elementFallback`
-
-**Type:** `string`  
-**Default:** `'div'`
-
-The HTML element to use when an unknown or unsupported element type is encountered. This provides graceful degradation for content with elements not explicitly handled.
-
-#### Example: Custom Element Fallback
-
-```tsx
-// Use span for unknown elements (better for inline contexts)
-<RichText
-  content={content.body?.json}
-  elementFallback="span"
-/>
-
-// Use section for semantic grouping
-<RichText
-  content={content.body?.json}
-  elementFallback="section"
-/>
-```
-
-#### Advanced Fallback with Custom Component
-
-```tsx
-// Create a custom fallback that logs unknown elements
-const CustomFallbackElement = ({ children, element }: ElementProps) => {
-  console.warn('Unknown element type:', element.type);
-
-  return (
-    <div
-      className="unknown-element"
-      data-type={element.type}
-      style={{ border: '1px dashed #ccc', padding: '8px' }}
-    >
-      <small>Unknown element: {element.type}</small>
-      {children}
-    </div>
-  );
-};
-
-<RichText
-  content={content.body?.json}
-  elements={{
-    // Handle known elements...
-    'unknown-element': CustomFallbackElement,
-  }}
-/>;
-```
-
-### `leafFallback`
-
-**Type:** `string`  
-**Default:** `'span'`
-
-The HTML element to use when an unknown text formatting mark is encountered.
-
-#### Example: Custom Leaf Fallback
-
-```tsx
-// Use em for unknown marks
-<RichText
-  content={content.body?.json}
-  leafFallback="em"
-/>
-
-// Use mark element for highlighting unknown formatting
-<RichText
-  content={content.body?.json}
-  leafFallback="mark"
-/>
-```
-
-#### Advanced Fallback with Styling
-
-```tsx
-// Visual indication of unknown formatting
-const CustomFallbackLeaf = ({ children, leaf }: LeafProps) => {
-  const unknownMarks = Object.keys(leaf).filter(
-    (key) =>
-      ![
-        'text',
-        'bold',
-        'italic',
-        'underline',
-        'code',
-        'strikethrough',
-      ].includes(key)
-  );
-
-  return (
-    <span
-      className="unknown-formatting"
-      title={`Unknown formatting: ${unknownMarks.join(', ')}`}
-      style={{ backgroundColor: 'yellow', padding: '0 2px' }}
-    >
-      {children}
-    </span>
-  );
-};
-
-// Apply to all unknown marks
-<RichText
-  content={content.body?.json}
-  leafs={{
-    // Known formatting...
-    bold: ({ children }) => <strong>{children}</strong>,
-    // This would handle any unknown marks
-  }}
-/>;
-```
-
 ## Complete Example
 
 ```tsx
@@ -377,8 +264,6 @@ export default function Article({ content }) {
           code: CustomCode,
         }}
         decodeHtmlEntities={true}
-        elementFallback="div"
-        leafFallback="span"
       />
     </article>
   );
@@ -412,12 +297,140 @@ const leafs: LeafMap = {
 };
 ```
 
+## Fallback Handling for Unknown Elements
+
+The RichText component uses a simple and safe fallback strategy for unknown elements and text marks.
+
+### Default Behavior
+
+**All unknown elements and text marks render as `<span>` elements.**
+
+This ensures:
+
+- Valid HTML in any context (inline or block)
+- No hydration errors in React
+- Safe rendering without breaking layout
+- Can be styled via CSS if needed
+
+### How It Works
+
+- **Known Elements**: Use their default HTML tags (e.g., `heading-one` → `<h1>`, `paragraph` → `<p>`)
+- **Unknown Elements**: Automatically become `<span>` tags
+- **Known Text Marks**: Use their default tags (e.g., `bold` → `<strong>`, `italic` → `<em>`)
+- **Unknown Text Marks**: Automatically become `<span>` tags
+
+### Built-in Element Support
+
+The component includes extensive built-in support for common HTML elements:
+
+**Text semantics:** `span`, `mark`, `strong`, `em`, `u`, `s`, `i`, `b`, `small`, `sub`, `sup`, `ins`, `del`, `kbd`, `abbr`, `cite`, `dfn`, `q`, `time`, `data`, `bdo`, `bdi`, `var`, `samp`
+
+**Interactive:** `a`, `button`, `label`
+
+**Media:** `img`, `svg`, `canvas`
+
+**Forms:** `input`, `select`, `textarea`
+
+**Other:** `br`, `wbr`
+
+### Custom Element Handling
+
+If you encounter unknown HTML tags or elements not supported by the SDK, you can override them using the `elements` or `leafs` props to render custom React components.
+
+> [!NOTE]
+> Unknown elements and text marks are typically introduced when rich text content is created through the **Integration API (REST API)** rather than the CMS editor. When using the Integration API, developers can insert custom HTML elements or formatting that may not be recognized by the SDK's default element mappings. Additionally, some element attributes may not be fully supported when content is created via the Integration API, as the TinyMCE editor processing that normalizes and validates these attributes is bypassed.
+
+```tsx
+import {
+  RichText,
+  ElementProps,
+  LeafProps,
+} from '@optimizely/cms-sdk/react/richText';
+
+// Custom component for unknown block elements
+const UnknownElement = ({ children, element }: ElementProps) => (
+  <div className="unknown-element" data-type={element.type}>
+    {children}
+  </div>
+);
+
+// Custom component for unknown text marks
+const UnknownLeaf = ({ children, leaf }: LeafProps) => (
+  <span className="unknown-leaf" data-marks={Object.keys(leaf).join(',')}>
+    {children}
+  </span>
+);
+
+// Custom component for a specific custom element
+const CustomElement = ({ children, element }: ElementProps) => (
+  <div className="custom-element">{children}</div>
+);
+
+function Article({ content }) {
+  return (
+    <RichText
+      content={content.body?.json}
+      elements={{
+        'unknown-element': UnknownElement, // Handle specific unknown element type
+        'custom-element': CustomElement, // Your custom CMS element
+      }}
+      leafs={{
+        'unknown-leaf': UnknownLeaf, // Handle specific unknown text mark
+        highlight: ({ children }) => (
+          <mark className="highlight">{children}</mark>
+        ),
+      }}
+    />
+  );
+}
+```
+
+#### Example: Handling Custom CMS Elements
+
+```tsx
+// Custom video element not supported by default
+const VideoElement = ({ children, element }: ElementProps) => {
+  const videoData = element as { videoUrl?: string; autoplay?: boolean };
+
+  return (
+    <div className="video-container">
+      <video src={videoData.videoUrl} autoPlay={videoData.autoplay} controls>
+        {children}
+      </video>
+    </div>
+  );
+};
+
+// Custom callout box element
+const CalloutElement = ({ children, element }: ElementProps) => {
+  const calloutData = element as { variant?: string };
+
+  return (
+    <div className={`callout callout-${calloutData.variant || 'info'}`}>
+      {children}
+    </div>
+  );
+};
+
+function Article({ content }) {
+  return (
+    <RichText
+      content={content.body?.json}
+      elements={{
+        'video-embed': VideoElement,
+        'callout-box': CalloutElement,
+      }}
+    />
+  );
+}
+```
+
 ## Best Practices
 
 1. **Performance**: Only override elements/leafs you need to customize
 2. **Accessibility**: Maintain semantic HTML structure in custom components
-3. **Fallbacks**: Always provide sensible fallback values for unknown content
-4. **Type Safety**: Use TypeScript interfaces for better development experience
+3. **Type Safety**: Use TypeScript interfaces for better development experience
+4. **Unknown Elements**: The default `<span>` fallback handles unknown elements safely - no configuration needed
 
 ## Common Use Cases
 

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

@@ -9,10 +9,7 @@ import {
 /**
  * Configuration for rich text renderers
  */
-export interface BaseRendererConfig extends RendererConfig {
-  elementFallback?: string;
-  leafFallback?: string;
-}
+export interface BaseRendererConfig extends RendererConfig {}
 
 /**
  * Base class for rich text renderers that provides common functionality
@@ -28,8 +25,6 @@ export abstract class BaseRichTextRenderer<
   constructor(config: Partial<BaseRendererConfig> = {}) {
     this.config = {
       decodeHtmlEntities: true,
-      elementFallback: 'div',
-      leafFallback: 'span',
       ...config,
     };
   }