React component for vim.wasm

react-vim-wasm npm package provides React component for vim.wasm. Vim editor can be easily embedded into your React web application.

Please visit demo to see a live example.

Installation

Install the package via npm package manager. Please note that this component supports React 16.8.0 or later.

npm install --save react react-vim-wasm

Usage

<Vim/> component

import * as React from 'react';
import { useCallback } from 'react';
import { Vim } from 'react-vim-wasm';

const onVimExit = useCallback(s => alert(`Vim exited with status ${s}`), []);
const onFileExport = useCallback((f, buf) => console.log('file exported:', f, buf), []);
const onError = useCallback(e => alert(`Error! ${e.message}`), []);

<Vim
    worker="/path/to/vim-wasm/vim.js"
    onVimExit={onVimExit}
    onFileExport={onFileExport}
    readClipboard={navigator.clipboard && navigator.clipboard.readText}
    onWriteClipboard={navigator.clipboard && navigator.clipboard.writeText}
    onError={onError}
/>

By using this component, all setup is done in the component lifecycle; Prepare <canvas/> and <input/>, load and start Vim editor instance in Web Worker, clean up the worker on Vim ends.

For real example, please read example code.

Properties of <Vim/> are as follows:

| Property Name | Description | Type | Default Value | |--------------------|--------------------------------------------------------------------|---------------------------------|---------------| | worker | File path to worker script vim.js in vim-wasm package. | string | NOT OPTIONAL | | className | Class name added to underlying <canvas/> DOM element. | string | undefined | | style | style attribute value of underlying <canvas/> dom element. | Object | undefined | | id | id attribute value of underlying <canvas/> dom element. | string | undefined | | debug | Enable JavaScript debug logging to console. | boolean | false | | perf | Enable performance tracing and dump result at Vim exiting. | boolean | false | | clipboard | Explicitly enable/disable clipboard register support. | boolean | true | | files | Object that file paths to file contents. | { [fpath: string]: string } | {} | | dirs | Array of new directory paths created before Vim startup. | string[] | [] | | persistentDirs | Array of existing directory paths which are persistent with IDB. | string[] | [] | | cmdArgs | Array of command line arguments passed to vim process. | string[] | [] | | fetchFiles | Mapping from local filesystem paths to remote resources like URLs. | { [fpath: string]: string } | undefined | | onVimCreated | Callback called at creating a VimWasm instance. | (VimWasm) => void | undefined | | onError | Callback called when an error is thrown in worker. | (Error) => void | undefined | | onVimInit | Callback called at initializing Vim worker instance. | () => void | undefined | | onVimExit | Callback called at Vim exiting. | (number) => void | undefined | | onFileExport | Callback called when :export is run. | (string, ArrayBuffer) => void | undefined | | onTitleUpdate | Callback called when window title is updated. | (string) => void | undefined | | readClipboard | Async function to read a clipboard text. | async () => string | undefined | | onWriteClipboard | Async function to write a clipboard text. | async (string) => void | undefined | | drawer | User-defined screen drawer instance (see below section). | ScreenDrawer | undefined |

All properties other than worker are optional. For filetype support, please read these docs also.

useVim() hook

This package provides useVim() React hook function. Thanks to React Hooks architecture, Vim instance management logic can be integrated into your component easily.

import * as React from 'react';
import { useVim } from 'react-vim-wasm';

const YourComponent = props => {
    const [canvasRef, inputRef, vim] = useVim({
        worker: '/path/to/vim-wasm/vim.js',
        // The same as <Vim/> props...
    });

    // Access to `vim` instance if you want

    // Set refs to render screen and handle key inputs
    return <>
        <canvas ref={canvasRef} />
        <input ref={inputRef} />
    </>;
};

useVim() returns 3-elements array.

The first element is a ref to a canvas element to render Vim screen. You must put it to <canvas/> element in your component. This value is set to null if drawer property is set.

The second element is a ref to a input element to catch key input. You must put it to <input/> element in your component. This value is set to null if drawer property is set.

The third element is a VimWasm instance. Some operations (such as calling .cmdline() method) can be done via this instance. Please read vim.wasm document for more details.

checkVimWasmIsAvailable() utility

vim.wasm requires Worker, SharedArrayBuffer and Atomics and some browsers don't meet the requirements.

This package provides checkVimWasmIsAvailable utility function to check browser compatibility. It returns an error message as string when the current browser is incompatible, otherwise undefined.

import { checkVimWasmIsAvailable } from 'react-vim-wasm';

const errmsg = checkVimWasmIsAvailable();
if (errmsg) {
    alert(errmsg);
}

Custom Screen Drawer

User-defined custom renderer can be defined through drawer property of <Vim/> component or useVim() hook.

The drawer property is an instance which implements ScreenDrawer interface defined in vim-wasm/vimwasm.d.ts. Please read this code to know the interface.

By defining your class implementing the interface, your class can render Vim screen instead of <canvas/>.

Note that key down must be handled by your implementation using VimWasm.sendKeydown() method and resize event also must be handled using VimWasm.resize() method.

For a real example, please read DummyDrawer class which is used for testing draw events.

TypeScript Support

This package provides complete TypeScript support. Please read index.d.ts type definitions file put in installed package directory.

Development

Some scripts are defined in package.json.

# Start TypeScript compiler and parcel bundler with watch mode.
# Example site is hosted at http://localhost:1234 and enables hot-reload.
$ npm run watch

# Release build
$ npm run build

# Check lint and formatter
$ npm run lint

# Check lint and formatter with automatic fixes
$ npm run fix

# Deploy to gh-pages
$ npm run gh-pages

# Build and run unit tests
$ npm run watch:test # Watch files and run tests on change
$ npm test           # Single run
$ npm run karma      # Start Karma server

License

This repository is licensed under MIT License.