Breaking: Replace eventHandlers by overrides

Author: thomasthiebaud

README.md

@@ -1,5 +1,11 @@
 # htmlstring-to-react
 
+## Why ?
+
+This module provide an easy way to parse a string containing html elements to an array of React elements. It tries to focus to security (using [DOMPurify](https://github.com/cure53/DOMPurify)) and keeping the bundle as small as possible
+
+It is heavily inspired by [html2react](https://github.com/Deschtex/html2react) and [html-react-parser](https://github.com/remarkablemark/html-react-parser)
+
 ## How to install ?
 
     npm install htmlstring-to-react
@@ -13,30 +19,37 @@
     import { parse } from 'htmlstring-to-react'
     parse('<em key="1"><b key="2">It\' is working</b></em>')
 
-### Add an event handler
+### Add an override
 
-Add an evant handler on all `b` elements
+You can use css selectors to override an element
 
     import { parse } from 'htmlstring-to-react'
     parse('<b key="1">It</b> is <b key="2">working</b>', {
-      eventHandlers: {
-        b: {
-          onClick: () => console.log('click'),
-        },
+      overrides: {
+        b: (props, textContent) => <b onClick={console.log('Click')}>{textContent}</b>
       },
     })
 
-Each key in `eventHandlers` can be a valid css selector.
+All valid css selectors works
 
     import { parse } from 'htmlstring-to-react'
     parse('<b key="1">It</b> is <b key="2" class="active">working</b>', {
-      eventHandlers: {
-        'b.active': {
-          onClick: () => console.log('click'),
-        },
+      overrides: {
+        'b.active': (props, textContent) => <b onClick={console.log('Click')}>{textContent}</b>
       },
     })
 
+**IMPORTANT** Overrides do not support nested elements in the current stage, so this code
+
+    import { parse } from 'htmlstring-to-react'
+    parse('<b key="1"><b key="2">It is working</b></b>', {
+      overrides: {
+        b: (props, textContent) => <b onClick={console.log('Click')}>{textContent}</b>
+      },
+    })
+
+will drop the inner `b` but keep the textContent
+
 ### Change dom parsing configuration
 
 By default, we are sanitizing the html input using `DOMPurify` module. You can override the configuration we are using

src/config.ts

@@ -1,4 +1,4 @@
-import { SelectorsToEventHandlers } from './event'
+import { SelectorsToElement } from './override'
 
 function isObject(item: any) {
   return (item && typeof item === 'object' && !Array.isArray(item))
@@ -63,7 +63,7 @@ export interface DOMConfig {
  */
 export interface Config {
   dom?: DOMConfig
-  eventHandlers?: SelectorsToEventHandlers
+  overrides?: SelectorsToElement
 }
 
 /**

src/event.ts

@@ -1,6 +1,6 @@
 import { Config, getConfig } from './config'
 import * as dom from './dom'
-import { addEventHandlers } from './event'
+import { override } from './override'
 import { render } from './react'
 
 export function parse(html: string, userOptions?: Config): React.ReactNode[] {
@@ -11,8 +11,8 @@ export function parse(html: string, userOptions?: Config): React.ReactNode[] {
   const options = getConfig(userOptions)
   const document = dom.parse(html, options)
 
-  if (options.eventHandlers) {
-    addEventHandlers(document, options.eventHandlers)
+  if (options.overrides) {
+    override(document, options.overrides)
   }
 
   return render(document.childNodes)

src/index.ts

@@ -0,0 +1,25 @@
+/**
+ * An internal representation of an element that can include a React element to use as an override
+ */
+export interface EnrichedElement extends Element {
+  override?: (props: any, textContent?: string) => React.ReactElement<any>
+}
+
+/**
+ * A map between a css selector and a React element
+ */
+export interface SelectorsToElement {
+  [keyof: string]: (props?: any, textContent?: string) => React.ReactElement<any>
+}
+
+export function override(document: DocumentFragment, selectorsToElement: SelectorsToElement) {
+  Object.keys(selectorsToElement).forEach((selector) => {
+    const reactElement = selectorsToElement[selector]
+
+    const elements = document.querySelectorAll(selector)
+    for (let i = 0; i < elements.length; i ++) {
+      const element = elements.item(i) as EnrichedElement
+      element.override = reactElement
+    }
+  })
+}

src/override.ts

@@ -1,7 +1,7 @@
 import * as React from 'react'
 
 import { getAttributes, NodeType } from './dom'
-import { EnrichedElement, EventHandlers } from './event'
+import { EnrichedElement } from './override'
 
 export interface Attributes { [keyof: string]: string | React.EventHandler<any> }
 
@@ -53,16 +53,9 @@ const reactAttributesMap: { [keyof: string]: string } = {
   usemap: 'useMap',
 }
 
-function transformAttributes(attributesMap: NamedNodeMap, eventHandlers: EventHandlers): Attributes {
+function transformAttributes(attributesMap: NamedNodeMap): Attributes {
   const attributes = getAttributes(attributesMap)
   const transformedAttributes: Attributes = {}
-
-  if (eventHandlers) {
-    Object.keys(eventHandlers).forEach((eventHandler) => {
-      transformedAttributes[eventHandler] = eventHandlers[eventHandler]
-    })
-  }
-
   Object.keys(attributes).forEach((key) => {
     if (reactAttributesMap[key]) {
       transformedAttributes[reactAttributesMap[key]] = attributes[key]
@@ -79,6 +72,11 @@ function renderTextNode(node: Node & ChildNode) {
 
 function renderElementNode(node: Node & ChildNode) {
   const element = transform(node as EnrichedElement)
+
+  if (element.override) {
+    return React.cloneElement(element.override(element.attributes, node.textContent))
+  }
+
   if (element.childNodes) {
     return React.createElement(element.nodeName, element.attributes, render(element.childNodes))
   }
@@ -87,11 +85,12 @@ function renderElementNode(node: Node & ChildNode) {
 
 function transform(element: EnrichedElement) {
   return {
-    attributes: transformAttributes(element.attributes, element.eventHandlers),
+    attributes: transformAttributes(element.attributes),
     childNodes: element.childNodes,
     nodeName: element.nodeName.toLowerCase(),
     nodeType: element.nodeType,
     nodeValue: element.nodeValue,
+    override: element.override,
   }
 }
 

src/react.ts

@@ -25,47 +25,59 @@ describe('Public API', () => {
       expect(wrapper.find('b')).toHaveLength(1)
     })
 
-    it('should accept event handlers', () => {
+    it('should override using a React element', () => {
       const spy = jest.fn()
       const elements = htmlStringToReact.parse('<em key="1"><b key="2">It\' is working</b></em>', {
-        eventHandlers: {
-          b: {
-            onClick: spy,
-          },
+        overrides: {
+          b: (props, textContent) => React.createElement('b', { onClick: spy, key: props.key }, textContent),
         },
       })
       const wrapper = shallow(React.createElement('div', null, elements))
       expect(wrapper.text()).toEqual('It\' is working')
       expect(wrapper.find('em')).toHaveLength(1)
       expect(wrapper.find('b')).toHaveLength(1)
+      expect(wrapper.find('b').key()).toEqual('2')
       expect(wrapper.find('b').simulate('click'))
       expect(spy).toHaveBeenCalled()
     })
 
-    it('should ignore incorrect event handlers', () => {
+    it('should override all elements that match the selector', () => {
       const spy = jest.fn()
-      const elements = htmlStringToReact.parse('<em key="1"><b key="2">It\' is working</b></em>', {
-        eventHandlers: {
-          b: {
-            onclick: spy,
-          },
+      const elements = htmlStringToReact.parse('<b key="1">It</b> is <b key="2">working</b>', {
+        overrides: {
+          b: (props, textContent) => React.createElement('b', { onClick: spy }, textContent),
         },
       })
       const wrapper = shallow(React.createElement('div', null, elements))
-      expect(wrapper.text()).toEqual('It\' is working')
-      expect(wrapper.find('em')).toHaveLength(1)
+      expect(wrapper.text()).toEqual('It is working')
+      expect(wrapper.find('b')).toHaveLength(2)
+      expect(wrapper.find('b').at(0).key()).toBeUndefined()
+      expect(wrapper.find('b').at(1).key()).toBeUndefined()
+      expect(wrapper.find('b').at(0).simulate('click'))
+      expect(wrapper.find('b').at(1).simulate('click'))
+      expect(spy).toHaveBeenCalledTimes(2)
+    })
+
+    it('should get textContent even on nested elements', () => {
+      const spy = jest.fn()
+      const elements = htmlStringToReact.parse('<b key="1"><b key="2">It is working</b></b>', {
+        overrides: {
+          b: (props, textContent) => React.createElement('b', { onClick: spy }, textContent),
+        },
+      })
+      const wrapper = shallow(React.createElement('div', null, elements))
+      expect(wrapper.text()).toEqual('It is working')
       expect(wrapper.find('b')).toHaveLength(1)
-      expect(wrapper.find('b').simulate('click'))
-      expect(spy).toHaveBeenCalledTimes(0)
+      expect(wrapper.find('b').at(0).key()).toBeUndefined()
+      expect(wrapper.find('b').at(0).simulate('click'))
+      expect(spy).toHaveBeenCalledTimes(1)
     })
 
     it('should ignore incorrect selectors', () => {
       const spy = jest.fn()
       const elements = htmlStringToReact.parse('<em key="1"><b key="2">It\' is working</b></em>', {
-        eventHandlers: {
-          span: {
-            onClick: spy,
-          },
+        overrides: {
+          span: () => null,
         },
       })
       const wrapper = shallow(React.createElement('div', null, elements))