Skip to content

rhysd/react-vim-wasm

Repository files navigation

React component for vim.wasm

npm version Build Status

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.