unified

Project: unified-doc/unified-doc-react

Package: unified-doc-react@3.1.1

  1. Dependents: 0
  2. react wrapper for unified-doc
  1. unified 181
  2. markdown 154
  3. unist 132
  4. html 124
  5. hast 74
  6. file 34
  7. parse 24
  8. content 20
  9. text 19
  10. react 14
  11. compile 14
  12. document 10
  13. doc 8
  14. highlight 7
  15. nlp 6
  16. search 6
  17. export 4
  18. mark 4
  19. annotate 4

unified-doc-react

react wrapper for unified-doc.


Install

npm install unified-doc-react

Use

DocComponent

For quick and simple rendering of a document, use the React component:

import React from 'react';
import { DocComponent } from 'unified-doc-react';

const options = {
  content: '> some **strong** content',
  filename: 'doc.md',
  marks: [
    { id: 'a', start: 0, end: 5 },
    { id: 'a', start: 10, end: 12 },
  ],
};

function MyDoc() {
  return (
    <DocComponent
      className="my-doc"
      options={options}
    />
  );
}

DocProvider and useDoc

For building advanced and interactive document applications, wrap your component with a DocProvider. Components under the DocProvider have access to the doc instance via the useDoc hook.

// App.js
import React from 'react';
import { DocProvider } from 'unified-doc-react';

import MyDoc from './MyDoc';

const options = {
  content: '> some **strong** content',
  filename: 'doc.md',
};

function MyApp() {
  return (
    <DocProvider options={options}>
      <MyDoc />
    </DocProvider>
  );
}

// MyDoc.js
import React, { useState } from 'react';
import { saveFile } from 'unified-doc-dom';
import { useDoc } from 'unified-doc-react';

function MyDoc() {
  const doc = useDoc();
  const [query, setQuery] = useState('');
  const [results, setResults] = useState([]);

  function clearSearch() {
    setQuery('');
    setResults([]);
  }

  function handleSearch(e) {
    const query = e.target.value;
    const results = doc.search(query);
    setQuery(query);
    setResults(results);
  }

  return (
    <div>
      <h1>{doc.file().name}</h1>
      <h2>Search</h2>
      <input value={query} onChange={handleSearch} />
      {results.map((result, i) => {
        const [left, matched, right] = result.snippet;
        return (
          <div key={i}>
            {left}
            <strong>{matched}</strong>
            {right}
          </div>
        );
      })}
      <button onClick={clearSearch}>
        Clear search
      </button>
      <h2>Contents</h2>
      <div>{doc.compile().result}</div>
      <button onClick={() => saveFile(doc.file())}>
        Download original
      </button>
      <button onClick={() => saveFile(doc.file('.html'))}>
        Download HTML
      </button>
      <button onClick={() => saveFile(doc.file('.txt'))}>
        Download text
      </button>
      <h2>Text Contents</h2>
      <pre>{doc.textContent()}</pre>
    </div>
  );
}

Use with unified-doc-dom

unified-doc-react can be used seamlessly with methods in unified-doc-dom to build interactive document applications.

import React, { useEffect, useRef, useState } from 'react';
import { fromFile, highlight, registerMarks, selectText } from 'unified-doc-dom';
import { DocComponent } from 'unified-doc-react';
import { v4 as uuidv4 } from 'uuid';

// import optional highlight styles
import 'unified-doc-dom/css/highlight.css';

function MyDoc() {
  const docRef = useRef();
  const [fileData, setFileData] = useState();
  const [marks, setMarks] = useState([]);

  function addMark(newMark) {
    setMarks(oldMarks => [...oldMarks, { ...newMark, id: uuidv4() }]);
  }

  // enable and capture selected text as marks
  useEffect(() => {
    // cleanup function conveniently returned
    return selectText(docRef.current, { callback: addMark });
  }, []);

  // register marks with callbacks
  useEffect(() => {
    const callbacks = {
      onClick: (event, mark) => console.log('clicked', event, mark),
      onMouseEnter: (event, mark) => console.log('mouseenter', event, mark),
      onMouseOut: (event, mark) => console.log('mouseout', event, mark),
    }
    // cleanup function conveniently returned
    return registerMarks(docRef.current, marks, callbacks);
  }, [marks]);

  // highlight applied marks given its ID
  function highlightLastMark() {
    highlight(docRef.current, marks[marks.length - 1].id);
  }

  // read file data from a JS file
  async function uploadFile(e) {
    const fileData = await fromFile(e.target.files[0]);
    setFileData(fileData);
  }

  let docContent;
  if (!fileData) {
    docContent = <input type="file" onChange={uploadFile}></input>;
  } else {
    const options = {
      content: fileData.content,
      filename: fileData.name,
      marks,
    };
    docContent = <DocComponent options={options} />;
  }

  return (
    <div>
      <button onClick={highlightLastMark}>
        Highlight last mark
      </button>
      <div ref={docRef}>
        {docContent}
      </div>
    </div>
  );
}

API

The term doc used below refers to a unified-doc instance. Please refer to unified-doc for detailed documentation of doc API methods.

DocComponent(props)

Interface

function DocComponent(props: Props): React.ReactElement;

A simple React component that wraps around a doc instance.

interface Props {
  /** options for `doc` instance */
  options: Options;
  /** optional `className` to attach to rendered `docElement` */
  className?: string;
  /** a reference to the rendered `docElement` */
  ref?: React.Ref<HTMLDivElement>;
}

DocProvider(props)

Interface

function DocProvider(props: ProviderProps): React.ReactElement;

Use the DocProvider to expose the doc instance in a React context. Components under DocProvider can access the doc instance via the useDoc hook.

interface ProviderProps {
  /** any React node */
  children: React.ReactNode;
  /** options for `doc` instance */
  options: Options;
}

useDoc()

Interface

export function useDoc(): DocInstance;

Access the doc instance in any components under the DocProvider.

options

Provide options to configure unified-doc.

Please refer to unified-doc for detailed documentation of options.

Development

This project is:

# install dependencies
npm run bootstrap

# build package with microbundle
npm run build

# clean package (rm dist + node_modules)
npm run clean

# watch/rebuild package with microbundle
npm run dev

# lint package with xo + prettier + tsc
npm run lint

# update semantic version with changelog
npm run release

# test package with jest in --watch mode (make sure to run the 'dev' script)
npm run test

# test package in a single run
npm run test:run