@bustle/mobiledoc-vdom-renderer
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.0 • Public • Published

    mobiledoc-vdom-renderer

    Build Status

    This package renders Mobiledoc documents through calls to a createElement function, often referred to as h (for hyperscript) or provided as a global if you are using JSX. This allows embedding Mobiledoc content “natively” as virtual DOM in frameworks like React, preact, or hyperapp.

    Alternatively, you can skip the “virtual” step and build DOM directly with a micro-renderer such as ultradom or even convert mobiledocs to arbitrary ASTs by adopting createElement’s standard (type: (properties: object) => Node, properties: object, ...children: Node[]) => Node signature for your builder.

    Installation

    npm install mobiledoc-vdom-renderer --save

    or

    yarn add mobiledoc-vdom-renderer

    Usage

    /* @jsx h */
    import Renderer from 'mobiledoc-vdom-renderer'
    
    // render: (mobiledoc: Mobiledoc) => Node[]
    const render = Renderer({ createElement: h })
    
    // Instant <Mobiledoc/> Component
    export default function Mobiledoc({ mobiledoc }) {
      return <div>{render(mobiledoc)}</div>
    }

    API

    import Renderer, { upgradeMobiledoc } from 'mobiledoc-vdom-renderer'

    Renderer (default export)

    Renderer: (options: RendererOptions) => RenderFunction

    Creates a render function ((mobiledoc: Mobiledoc) => Node[]) from the supplied options

    • options required

      {
        createElement: CreateElement,
        getCardComponent?: ComponentGetter,
        getAtomComponent?: ComponentGetter,
        getMarkupComponent?: ComponentGetter = getMarkupComponentDefault
      }
      • createElement required
        createElement: (
          type: string | Component,
          properties?: object,
          ...children: Node[]
        ) => Node
        Any compatible function such as React.createElement or hyperscript h
      • getCardComponent
        getCardComponent: (type: string) => string | Component
        Function which returns a string (tag name) or component ((properties: { payload: object }) => Node) for the given card type (required if rendering a mobiledoc with cards)
      • getAtomComponent
        getAtomComponent: (type: string) => string | Component
        Function which returns a string (tag name) or component ((properties: { payload: object }) => Node) for the given atom type (required if rendering a mobiledoc with atoms)
      • getMarkupComponent
        getMarkupComponent: (tagName: string) => string | Component = getMarkupComponentDefault
        Function which returns a string (tag name) or component ((attributes: object) => Node) to override rendering for the given tag name (for instance, to mix in HTML attributes or render a custom component instead)
        import { getMarkupComponentDefault } from 'mobiledoc-vdom-renderer'
        getMarkupComponent’s default behavior is exported as getMarkupComponentDefault, which passes through valid tag names but throws an error for tags not on Mobiledoc’s markup section or markup whitelists; passing through all tag names instead (as in tagName => tagName) allows (non-standard) mobiledocs containing arbitrary tags to be rendered

    upgradeMobiledoc

    upgradeMobiledoc: (mobiledoc: Mobiledoc | Mobiledoc02x) => Mobiledoc

    Upgrades a mobiledoc from any released version to the latest specification (0.3.1)

    Type definitions

    import { Mobiledoc, MobiledocTypes } from 'mobiledoc-vdom-renderer'

    This package includes complete Typescript definitions describing the Mobiledoc format, which may be imported directly for use with any mobiledoc-related code.

    Contributing

    Contributions—including pull requests, bug reports, documentation, and suggestions—are welcome!

    The code is written in Typescript in a pure functional style. Opinionated “best practices,” including functional programming, are strictly enforced by linters—it’ll help to use a code editor which supports both as-you-type linting and type-checking.

    Test-driven development

    • Installation

    git clone https://github.com/bustle/mobiledoc-vdom-renderer.git
    cd mobiledoc-vdom-renderer/
    npm install

    More for Mobiledoc

    Renderers

    Editors

    Utilities

    Install

    npm i @bustle/mobiledoc-vdom-renderer

    DownloadsWeekly Downloads

    28

    Version

    1.0.0

    License

    ISC

    Unpacked Size

    78.6 kB

    Total Files

    81

    Last publish

    Collaborators

    • eggplantkiller
    • tholman
    • teety
    • tylerlove
    • zeejab
    • anujpan
    • gdub
    • bustle-deploy
    • redterror
    • wabyad
    • sarahganis
    • cg3ntry