DEV Community: huozhi

Convert HTML to Anything You Want!

huozhi — Sun, 22 Dec 2019 06:47:49 +0000

If you feel it's too long to read, here's the repo: https://github.com/huozhi/html2any

Inspiration

There was a task, to create a FAQ site, which is fully functional to provide user with help information.

Designer: First we have a search bar 🔍, able to retrieve every index page. pages are in rich text.
Dev: Yep, sounds good, not difficult. (I guess markdown can handle all)
Designer: Rich text is required to support videos, gif, inline images, block images blablabla...we hope it could be aligned with our main site, all the theme, animations are same.
Dev: Emmm...this is a new fresh project, can we just use the default video controls?
Designer: The vidos/gif need to be same with main site, the basic controls is not enough for user.
Dev: And where are these contents from?
Designer: Maybe an editor in CMS to publish new pages?
Dev: Hurry?
Designer: Yep! hope be ready soon!

** WHAT THE HELLLLL... **

Looks impossible to finish this work in a such short time with markdown. However it's insane to hard code all static pages within react or other js code. The point is, the RichText component in existing project is not able to easily migrate now, and they still have other logics to handle text collapse / metrics collecting...which we don't really need.

For us, we just want a static page. That's it.

What I can only decouple from existing project are: Video, Image and Gif components. CMS will always provide me with a HTML string for the rich text content. I have to figure out a way to replace the native image/videoes tag with customized react components.

Editor & RichText

While you typing stuff in rich text editor, making them bold / italic, inserting some images, you've already finished once rich text editing. Since these content are not only pure text to display, they need more complicated composing with HTML and CSS, even JavaScript to perform an interaction.

There are kinds of editors:

stateful editor: such as draftjs, slate.They all convert HTML to a middle state, then serialize from state to final HTML
non-stateful editor: doesn't need state, maybe only rely on contenteditable, encapsulate on the top, such as Medium.js

Saving editing content has 2 usual thoughts:

Use stateful editor, sync state to database. Recover from state in database when you display. Feel natural.
Use any editor you like. Communicate by HTML between client and storage.

Saving state may bring potential traps. For example you want to migrate from google closure editor to draftjs. There isn't any state before, the new comer breaks rules. Make you hard to handle the previous way. Migration takes effort and risks.

If you saving HTML string with stateful editor, you have to write your own serializer + deserializer state converter. Draft requires lib like draft-convert, slate has built-in serializer and deserializer with convenient usage.

Went So Far. Anything Related to Our Stuff?

First tasting on slate editor I felt free because of its HTML convert

const rules = [
  {
    deserialize(el, next) {
      if (el.tagName.toLowerCase() == 'p') {
        return {
          kind: 'block',
          type: 'paragraph',
          nodes: next(el.childNodes)
        }
      }
    },
    // Add a serializing function property to our rule...
    serialize(object, children) {
      if (object.kind == 'block' && object.type == 'paragraph') {
        return <p>{children}</p>
      }
    }
  }
]

import { Html } from 'slate'

// Create a new serializer instance with our `rules` from above.
const html = new Html({ rules })

state = {
  state: html.deserialize(htmlString),
}

const htmlString = html.serialize(someState)

Isn't it interesting? Enjoy state and HTML switching after you just defined a de/serialization rule. COOL!

When you reach here, got it? What we need is a thing, without any editor functions, be capable to convert HTML into and from structural state. To help us display complicated state visualization.

LETS DOT IT

Still remember the principle of compiler? The process of consuming code string and output as machine code:

tokenizer: extract special tokens
parse: build tokes to AST
transform: transform AST to dest code

Now the same, our HTML and state are totally like this process. dest code is our final visual form. It could be a component or a HTML string, even a JSON object, whatever.

What we're going to do are following 3 steps:

Tokenize HTML into proper HTML tags
Build a tree, each node is a HTML tag containing its information and children
Traverse this tree with replacing the node into your own

Introduce you html2any

Checkout my final implementation: https://github.com/huozhi/html2any

Run on React Native

Check the presentation on React Native:

A paragraph containing bold fonts and images was converted to the react native form. Here's the screenshot on iOS:

Of course the component nested rules on React Native is much restrict, e.g. Text need sit under View with size specified. Text under Text doesn't inherit styles, which unlike CSS.

Run on Web with React

Click Here!

I made a simple transform rule for web:

br to hr tag
replace gif with a gif player including loading phase
Native video tag change to react video player

Want more? you can design more complicated rule function, then left it to html2any to handle.

Reference and Comparison

Actually we have lots of HTML parser in community. The most familiar ones are parse5 and HTMLparser2. Even cheerio is using HTMLparser2, why create the wheel again?

My reasons are:

html2any is really small enough. It's worth to try if you want to show any content generated from slate or dratjs.
many parsers are in sax form, parsing top to down. Creating a few API to handle the middle processing phase. For usage like ours, we don't need that much. And they do much compatible work for unreachable cases.
The most important reason —— more parsers are for web specially. Their outputs may be DOM tree, that's not our desired dest code. See the examples above right? Our doing is Universal HTML! Render Everywhere! Haha

My slide

Why Positioning a Tooltip Accurately with React So Complicated?

huozhi — Sun, 22 Dec 2019 06:45:43 +0000

Positioning Problem

You might heard lots of sayings of positioned component, such as popup, tooltip, popover, overlay...
they have the common way that you need to position it when you trigger it.

To generalize the problem, thinking deeper, we can encapsulate the components into 2 things: a trigger which you might press or hover in; and a overlay which positioning relatively to the trigger. it might be a tooltip, a popped dialog.

Since I'm using React.js, so I'm going to design it as a react component to solve my positioning problem, and share it as foundation among the overlay-like components. Pure logic, without any styling.

Then I came out the basic idea of the API. The single child component is the trigger, the we pass the overlay component as a prop to OverlayTrigger with the placement position in string literal. It will get rendered with accurate position once hover or focus on the button.

<OverlayTrigger
  placement='top'
  events={['hover', 'focus']}
  overlay={<span>tooltip</span>}
>
  <button>hover to trigger tooltip</button>
</OverlayTrigger>

The result might look like this

How Gonna It Work?

We got the the trigger get mounted on the DOM;
We mount the overlay to DOM when we interact with it (hover or focus)
We position get the position & size by getBoundingClientRect API of above components, and change the position of overlay to close to trigger with specified placement.

pseudo code like the following

function position(overlay, trigger) {
  // after both get mounted, get the positions and sizes
  overlaySize, overlayPos = getSizeAndPosition(overlay)
  triggerSize, triggerPos = getSizeAndPosition(trigger)

  // move overlay near to the trigger
  rePositionOverlay(...)
}

There's might also have a root element which you want to hook your overlay on, by default, it's document.body.
Then you can position it with fixed or absolute layout and the top, left distance.

Sounds easy, with couples line of the code. Then I tried to integrate it with my app...

Hover is Not Equal to Mouse Enter 🤦‍♂️

We had the very basic usage of the tooltip, show up when your hover on some icons, dismiss when you hover out. I looks pretty well when I test with the desktop devices. When I open the surface, Oh flicking....

Can we just disable tooltip when touch screen detected?
No, we can't, if you want to use navigator.maxTouchPoints to detect touch screen, you'll get wrong result on Edge.
Oh, ok, Edge, alright...

Let's try to solve it by browser events. Back to the topic on my previous blog Universal Scrubbing Experience on Web. In a word, if you try to capture hover actions by mouseenter and mouseleave events, that's a trap.

Use PointerEvent on the browsers supported and use MouseEvent on the ones which don't have PointerEvent.

The trigger handlers finally become like this

// if `hover` is specified in trigger `events`
onMouseEnter() {
  // match desktop safari behavior
  // mobile safari won't trigger any mouse event while touching
  if (!window.PointerEvent && !window.TouchEvent) {
    this.showOverlay()
  }
  // ...
}

onPointerEnter(event) {
  // match desktop/mobile browsers which support PointerEvent
  if (event.pointerType === 'mouse') {
    this.showOverlay()
  }
}

Looks like we're done now? But soon I found there's something wrong...

Wait, the Size of Trigger and Tooltip Might Change

If just play with hover you won't have this issue, maybe. But triggers' size do change, positioning only on did mount phase is not enough, did update is required as well.

Then question comes, how do we really know if there's any internal state change happened inside children and overlay components.
If we pass down any prop like onSizeUpdate, that's kind of tricky no one knows the root cause of resizing is class name changing or due to DOM tree updates.

react-bootstrap <OverlayTrigger />

After checking how the popular UI components library solving this problem, like react-bootstrap, ant-design, I found that react-bootstrap pass down a function prop called scheduleUpdate to trigger, that let trigger be able to forcedly enqueue an repositioning task when it's necessary. It's quite convenient, but we need to omit this function prop on trigger when we don't need it or when we spread all props onto it.

That's kind of inconvenient, since there're still few DOM props like onMouseEnter and onClick, been passed to trigger implicitly.

ant-design <align />

Ant design align component use ResizeObserver to track trigger size change. Unfortunately ResizeObserver is not widely supported. When I write this post, https://caniuse.com/#feat=resizeobserver shows that ResizeObserver is only supported on latest tech preview version and mobile safari doesn't support it. Ant design included a polyfill for it to get rid fo resize observer usage.

If we don' care about the bundle size very much, resize observer polyfill could be a choice. However I do care :) ...

Finally I came out a idea, that we use ResizeObserver when it's available, and fallback to MutationObserver on some unsupported browsers. With MutationObserver, the approach is to monitor cache the size and invoke callback when size gets changed.

function createObserver(node, onMeasure) {
  if (window.ResizeObserver) {
    const ro = new ResizeObserver(() => onMeasure())
    ro.observe(node)
    return ro
  } else {
    const cachedSize = {width: 0, height: 0}
    function handleMutate() {
      const {width, height} = node.getBoundingClientRect()
      if (cachedSize.width !== width || cachedSize.height !== height) {
        cachedSize.width = width
        cachedSize.height = height
        onMeasure()
      }
    }
    const mob = new MutationObserver(handleMutate)
    mob.observe(node, mutationObserverOption)
    return mob
  }
}

Now, we keep the API as simple as possible, and make the implementation as small as possible. I think we solve the most annoying issue :)

Repo & Demo

Checkout the source code on https://github.com/huozhi/react-overlay-trigger or use it directly with npm install --save react-overlay-trigger.
I also provide a playground that you can try it with different devices/browsers. https://huozhi.github.io/react-overlay-trigger/

From bundlephobia we can see it's only 2kb after minimized and gzipped. Small enough, and fit for general situations. Whatever you want to pop with your trigger components.

Hope you'll like it, issues & PRs are welcomed!

Universal Scrubbing Experience on Web

huozhi — Sun, 22 Dec 2019 06:36:57 +0000

I was surprised that the first touch device hard to deal with is Edge browser on Windows tablet. I though it was just like chrome. It had been years that the only touch events I had to handle is TouchEvent. Most web applications have simple interactions: just click. If you can click with mouse, you can navigate, trigger popup or submit forms.

Think about it, while you're watching a video on tablet, or with your cell phone, you want to jump further seconds but there is only clicks can be achieved, will you feel disappoint? To protect user experience such as scrubbing the timeline or playhead (indicator) for seeking the position, we need scrub.

Ahhhh...Cross Browser?

Click is across browser, browser doesn't care about your mouse, but screen does care about your finger. Usually in the devices supporting touch events, it has touchstart, touchmove, touchend and touchcancel. But after chrome introducing pointer events, dev noticed that there were still ways to handle similar stuff like mouse events.

just change all mouse events prefix to pointer, you'll get pointerup, pointermove, etc. Also, with the ability to detect is fired by finger, mouse or a pen.

Some of our requirements have different behavior of scrubs on player timeline:

when you do touch scrub, the indicator on timeline move, but mouse doesn't
when you do mouse hover and keep moving, the indicator move as well

Hover vs touch scrubs. Here we gotta detect the type of input. How?

First Failed Try

According to the spec of pointer events on w3c:

You can see a ordered sequence of events firing. For example, when you do click, then following events got fired.

mousemove
pointerover
pointerenter
mouseover
mouseenter
pointerdown
mousedown
Zero or more pointermove and mousemove events, depending on movement of the pointer
pointerup
mouseup
click
pointerout
pointerleave
mouseout
mouseleave

Observing that the corresponding pointer events are fired before mouse events, every event starts with a mouseover. I want to handle all events inside one function so we decided that maintain the continuous pointer type during an finger/mouse interaction.
Since Safari doesn't have pointer events, I decided to use TouchEvent as replacement. The we could just listen to mouse events, every mouse event instance expect first one will be set with a attribute pointerType to tell you the input source.

Actually, the idea that setting event with pointerType is came from Netflix's website. I reversed engineering some compressed js code (not fully mangled) I found the solution.

But finally i realize that won't work, 'cause mouse events are not always fired on touch devices.
Netflix use native controls in Safari if watching a content without login. (I don't know what it will change if you login, but I guess it won't change too much? the code is there). They use a product level solution to resolve this friction.

Smart approach I'd say so, but my product didn't tell me to enable native video controls while user watching on our site. So I tested on different devices/browsers and made a list of status of events support. See:

Browser & Action	PointerEvent	MouseEvent	TouchEvent
chrome + touch	✅	✅	✅
edge + touch	✅	✅	❌
safari + touch	❌	❌	✅
chrome + mouse	✅	✅	❌
edge + mouse	✅	✅	❌
safari + mouse	❌	✅	❌

Is there any way to handle all these stuffs universally?

Cross Browser Scrub Solution

Scrubs have there types:

scrub with finger touch
scrub with mouse drag
mouse over and move on

One behavior may happen on these two composed from three scenarios above , or event only one.
Our approaching is to separate these actions by configurations, make them independent.

What Developer Needs?

Usually we only care about the triggered callbacks, start / move / end are enough. They could be designed as events or handlers.

How to Separate These Actions?

Let's go through the movements:

Hovering elements with mouse: enter, move, leave
Scrubbing through: pointer down / move / pointer up

that's it. Due to different status of events support, we need to handle them in proper way. The handlers may receive event which is instance of PointerEvent, MouseEvent or TouchEvent.

Show Code

If you want to see the details of implementation check huozhi/fpoint. The API is pretty simple and easy to get started. You can also check the demo on different browsers/devices.

Feel free to submit issues or questions on the repo. :)