@typeskill/typer
Typeskill, the Operational-Transform Based (React) Native Rich Text Library.
npm install --save @typeskill/typer
Give it a try on Expo
You can also run it locally in seconds
Features & design principles
Design
- Extensively modular architecture: Typeskill handles the logic, you chose the layout;
- No bloated/clumsy
WebView
; this library only relies on (React) Native components; - Fully controlled components;
- Based on the reliable Delta operational transform library from quilljs.
Features
- Support for arbitrary embedded contents;
- Support for arbitrary controllers with the
Bridge
class; - JSON-serializable rich content.
Trying locally
Prerequisite: you must have npm
and expo-cli
globally installed
git clone https://github.com/typeskill/examples/tree/master
cd examples/expo-showcase
npm install
expo start
You can also cd examples/expo-debugger
to understand how the document is represented!
Architecture & example
Introduction
The library exposes two components to render documents:
- The
Typer
component is responsible for editing a document; - The
Print
component is responsible for displaying a document.
Definitions
- A document is a JSON-serializable object describing rich content;
- A document renderer is any controlled component which renders a document—i.e.
Typer
orPrint
; - The master component is referred to as the component containing and controlling the document renderer;
- A document control is any controlled component owned by the master component capable of altering the document—i.e.
Typer
orToolbar
; - An external [document] control is any document control which is not a document renderer—i.e.
Toolbar
or any custom control.
The shape of a Document
A document is an object describing rich content and the current selection. Its op
field is an array of operational transforms implemented with delta library. Its schemaVersion
guarantees retro-compatibility in the future and, if needed, utilities to convert from one version to the other.
To explore the structure in seconds, the easiest way is with the debugger: @typeskill/debugger
.
Controlled components
Document renderers and controls are controlled components, which means you need to define how to store the state from a master component, or through a store architecture such as a Redux. You can study Editor.tsx
, a minimal example master component.
A domain of shared events
Document renderers need an invariant Bridge
instance prop.
The bridge has two responsibilities:
- To convey actions such as insert an image at selection or change text attributes in selection from external controls;
- To notify selection attributes changes to external controls.
A Bridge
instance must be hold by the master component, and can be shared with any external control such as Toolbar
to operate on the document.
Remarks
- The
Bridge
constructor is not exposed. You must consume thebuildBridge
function oruseBridge
hook instead; - To grasp how the bridge is interfaced with the
Toolbar
component, you can read its implementation.
Robustness
This decoupled design has the following advantages:
- the logic can be tested independently from React components;
- the library consumer can integrate the library to fit its graphical and architectural design;
- support for arbitrary content in the future.
Minimal example
Bellow is a simplified snippet from the minimal expo example to show you how the Toolbar
can be interfaced with the Typer
component.
You need a linked react-native-vector-icons
or @expo/vector-icons
if you are on expo to make this example work.
import React from 'react';
import { View } from 'react-native';
import {
Typer,
Toolbar,
DocumentControlAction,
buildVectorIconControlSpec,
useBridge,
useDocument,
} from '@typeskill/typer';
/** NON EXPO **/
import { MaterialCommunityIcons } from 'react-native-vector-icons/MaterialCommunityIcons';
/** EXPO **/
// import { MaterialCommunityIcons } from '@expo/vector-icons'
function buildMaterialControlSpec(actionType, name) {
return buildVectorIconControlSpec(MaterialCommunityIcons, actionType, name);
}
const toolbarLayout = [
buildMaterialControlSpec(
DocumentControlAction.SELECT_TEXT_BOLD,
'format-bold',
),
buildMaterialControlSpec(
DocumentControlAction.SELECT_TEXT_ITALIC,
'format-italic',
),
buildMaterialControlSpec(
DocumentControlAction.SELECT_TEXT_UNDERLINE,
'format-underline',
),
buildMaterialControlSpec(
DocumentControlAction.SELECT_TEXT_STRIKETHROUGH,
'format-strikethrough-variant',
),
];
export function Editor() {
const [document, setDocument] = useDocument();
const bridge = useBridge();
return (
<View style={{ flex: 1 }}>
<Typer
document={document}
onDocumentUpdate={setDocument}
bridge={bridge}
maxMediaBlockHeight={300}
/>
<Toolbar document={document} layout={toolbarLayout} bridge={bridge} />
</View>
);
}
API Contract
You need to comply with this contract to avoid bugs:
- The
Bridge
instance should be instantiated by the master component withbuildBridge
, during mount or withuseBridge
hook; - There should be exactly one
Bridge
instance for one document renderer.
API Reference
Typescript definitions provide an exhaustive and curated documentation reference. The comments are 100% compliant with tsdoc and generated with Microsoft famous API Extractor utility. These definitions follow semantic versioning.
Please note that props
definitions are namespaced. For example, if you are looking at Toolbar
component definitions, you should look for Props
definition inside Toolbar
namespace.
Inspecting and reporting bugs
@typeskill/debugger
is a tool to inspect and reproduce bugs. If you witness a bug, please try a reproduction on the debugger prior to reporting it.
Customizing
Integrating your image picker
Typeskill won't chose a picker on your behalf, as it would break its commitment to modular design.
You can check Editor.tsx
component from the showcase expo example to see how to integrate your image picker.