@unified-doc/react-unified-doc v0.1.9

react-unified-doc

React unified-doc renderer for content.

Contents

• Install
• Description
• Props
• Use
• Docs

Install

yarn add @unified-doc/react-unified-doc

Description

react-unified-doc provides a React wrapper around the unified-doc project to render content. It uses the unified ecosystem to parse, transform and render content through rehype plugins. Supported source content (text, markdown, html) is parsed into a hast tree which is then marked up with React into a safely sanitized HTML document. This document is non-opinionated and maintains high fidelity with the source content, and supports easy customizations with standard web technologies.

Annotating documents is easily accomplished by declaratively specifying the annotations prop. The annotation algorithm is a pure semantic addition to the document converting matching text nodes into <mark /> tags, and leaves the rest of the document unchanged. An annotation is an object containing the following information:

• id: unique ID to identify the annotation. Useful for assigning unique ID to the rendered DOM element.
• startOffset, endOffset: positional string offsets relative to the source content.
• classNames, style: ways to customize the annotated nodes.
• label: render label above the annotated node.
• any other data that is useful for working with annotation callbacks.

Various annotation callbacks (click, hover, tooltips), and text-selection callbacks allow for building interactive applications involving rendering and annotating documents.

react-unified-doc is a part of the unified ecosystem, which allows it to benefit from many plugins. It accepts rehype plugins via the rehypePlugins prop to enrich documents with additional features.

Props

For a more detailed overview, please refer to the formal props documentation.

interface Props {
	/** Source content represented as a string */
	content: string;
	/** Supported content type ('html', 'markdown', 'text') */
	contentType?: ContentType;
	/** An array of annotations to apply to the content */
	annotations?: Annotation[];
	/** Provide optional CSS to style the document */
	className?: string;
	/** Valid rehype plugins can be applied after annotations.  `annotations` and `onSelectText` prop may misbehave depending on how the plugins mutate the rendered content relative to the source content. */
	rehypePlugins?: Plugin[];
	/** HTML Sanitize schema (see https://github.com/syntax-tree/hast-util-sanitize#schema) */
	sanitizeSchema?: { [key: string]: any };
	/** Renders annotation tooltips when hovering on the annotation */
	getAnnotationTooltip?: (annotation: Annotation) => string;
	/** Callback to capture annotation object and mouse click event */
	onAnnotationClick?: AnnotationCallback;
	/** Callback to capture annotation object and mouse enter event */
	onAnnotationMouseEnter?: AnnotationCallback;
	/** Callback to capture annotation object and mouse leave event */
	onAnnotationMouseLeave?: AnnotationCallback;
	/** Callback to capture selected text and mouse up event.  The `SelectedText` extends the `Annotation` object, and can be used to updated the `annotations` prop in a controlled manner.  Note that the this callback may not behave correctly if plugins modify the text content of the document since the callback is applied in relation to the source content. */
	onSelectText?: (selectedText: SelectedText, e?: MouseEvent) => void;
}

Use

import Document from '@unified-doc/react-unified-doc';
import toc from 'rehype-toc';

// include optional CSS for default annotation marks and tippy tooltips
import '@unified-doc/react-unified-doc/src/index.css';
import 'tippy.js/dist/tippy.css';

const content = '<blockquote>Blockquote with <b>bold</b> content.</blockquote>';
const annotations = [
	{ id: 'a1', startOffset: 0, endOffset: 30, label: 'annotation', tooltip: 'cool!' },
];

import './my-document.css';

function MyDocument() {
	return (
		<Document
			annotations={annotations}
			className="custom-doc-classname"
			content={content}
			contentType="html"
			getAnnotationTooltip={annotation => annotation.tooltip}
			rehypePlugins={[toc]}
			onAnnotationClick={annotation => console.log(annotation.id, ' clicked')}
			onAnnotationMouseEnter={annotation => console.log(annotation.id, ' hovered')}
			onSelectText={annotation => console.log(annotation.value, ' selected')}
		/>
	);
}

Docs

View the official docs and examples at https://unified-doc.netlify.com/react-unified-doc/readme.

You can also run the docs locally:

git clone git@github.com:chrisrzhou/unified-doc

cd unified-doc
yarn && yarn docs

export default ({ children }) => children