A Scripture editor React component that works on USJ Scripture data. A utility that converts USX to USJ is also included. It is expected that data conforms to USJ v3.1.
``mermaid --- title: Scripture Data — Editor flow --- graph TB DB[(DB)] <-- USX --> C C[USX-USJ converter] <-- USJ --> A A[USJ-Editor adapter] <-- Editor State --> Editor `
> [!NOTE] > > - Use the component for an editor without commenting features. > - Use the component (DEPRECATED) for an editor with comments (comments appear in the margin).
> [!IMPORTANT] > is deprecated and will be removed in a future release.
`ts import { EditorOptions, Editorial, EditorRef, usxStringToUsj, UsjNodeOptions } from "@eten-tech-foundation/platform-editor"; import { BookChapterControl } from "platform-bible-react";
const emptyUsx = ''; const usx = World English Bible (WEB) The Psalms Blessed is the man who doesn’t walk in the counsel of the wicked, nor stand on the path of sinners, nor sit in the seat of scoffers;
- USJ editor with USX support - Read-only and edit mode - History - undo & redo - Cut, copy, paste, paste as plain text - context menu and keyboard shortcuts - Format block type - change
markers. The current implementation is a proof-of-concept and doesn't have all the markers available yet. - Insert markers - type '\\' (backslash - configurable to another key) for a marker menu. If text is selected first the marker will apply to the selection if possible, e.g. use '\\wj' to "red-letter" selected text. - Add comments to selected text, reply in comment threads, delete comments and threads (deprecated). - To enable comments use the editor component (comments appear in the margin). - To use the editor without comments use the component. - Add and remove different types of annotations. Style the different annotations types with CSS, e.g. style a spelling annotation with a red squiggly underline. - Get and set the cursor location or selection range. - Specify textDirection as "ltr", "rtl", or "auto" ("auto" is unlikely to be useful for minority languages). - Insert note at selection, e.g. footnote, cross-reference. If text is selected it will be used as the quote in a footnote. - BCV linkage - change the book/chapter/verse externally and the cursor moves; move the cursor and it updates the external book/chapter/verse - Nodes supported , , , , , , - Nodes not yet supported
, , , , , , , - Node options: - callback for when a link is clicked - customize possible note callers list - Apply Delta Operation changes to the editor and see Delta Operations when changes are made in the editor. For use with realtime collaborative editing.
Styling
This npm package does not include styling so you need to style the editor component to suit your application. A good place to start is to copy the CSS from this repo:
type via the editor's reference API (see Editorial Ref). This type can then be used to apply custom CSS styles (e.g., a green squiggly underline for a _"grammar"_ type annotation). The CSS classname for an annotation takes the form of .${annotationPrefix}-external-${type}, where type is the string you pass to the setAnnotation() method and annotationPrefix is set by config.theme.typedMark (defaults to _"editor-typed-mark"_). If annotations overlap with each other an additional CSS classname is added where annotationPrefix is set by config.theme.typedMarkOverlap (defaults to _"editor-typed-markOverlap"_).
For example, if an annotation of type _"grammar"_ is overlapping it will have both CSS classnames
editor-typed-mark-external-grammar and editor-typed-markOverlap-external-grammar. If it's not overlapping it still has the first classname. Annotations and comments are the same when considering if it's overlapping.
$3
These follow a similar patter to Annotation Styles. If a comment is overlapping it will have both CSS classnames
editor-typed-mark-internal-comment and editor-typed-markOverlap-internal-comment. If it's not overlapping it still has the first classname. Annotations and comments are the same when considering if it's overlapping. API
$3
`ts /* Props for the Editor component that provides Scripture editing functionality. / export interface EditorProps { /* Initial Scripture data in USJ format. / defaultUsj?: Usj; /* Scripture reference that controls the general cursor location of the Scripture. / scrRef?: SerializedVerseRef; /* Callback function when the Scripture reference has changed. / onScrRefChange?: (scrRef: SerializedVerseRef) => void; /* Callback function when the cursor selection changes. / onSelectionChange?: (selection: SelectionRange | undefined) => void; /* Callback function when USJ Scripture data has changed. / onUsjChange?: (usj: Usj, ops?: DeltaOp[], source?: DeltaSource, insertedNodeKey?: string) => void; /* Callback function when state changes. / onStateChange?: ({ canUndo, canRedo, blockMarker, contextMarker }: StateChangeSnapshot) => void; /* Options to configure the editor. / options?: EditorOptions; /* Logger instance. / logger?: TLogger; } `
$3
`ts /* Forward reference for the editor. / export interface EditorRef { /* Focus the editor. / focus(): void; /* Undo the last action. / undo(): void; /* Redo the last undone action. / redo(): void; /* Cut the selected text. / cut(): void; /* Copy the selected text. / copy(): void; /* Paste text at the current cursor position. / paste(): void; /* Paste text as plain text at the current cursor position. / pastePlainText(): void; /* Get USJ Scripture data. / getUsj(): Usj | undefined; /* Set the USJ Scripture data. / setUsj(usj: Usj): void; /* EXPERIMENTAL: Apply Operational Transform delta update. / applyUpdate(ops: DeltaOp[], source?: DeltaSource): void; /** * EXPERIMENTAL: Replace an embed Operational Transform delta. * * @remarks Embed nodes are treated as atomic units. These include chapter nodes, verse nodes, * milestone nodes, note nodes, and unmatched nodes. * * @param embedNodeKey - The editor key of the embed node to replace. * @param insertEmbedOps - The delta operations that insert the new embed node. */ replaceEmbedUpdate(embedNodeKey: string, insertEmbedOps: DeltaOp[]): void; /** * Get the selection location or range. * @returns the selection location or range, or undefined if there is no selection. The * json-path in the selection assumes no comment Milestone nodes are present in the USJ. */ getSelection(): SelectionRange | undefined; /** * Set the selection location or range. * @param selection - A selection location or range. The json-path in the selection assumes no * comment Milestone nodes are present in the USJ. */ setSelection(selection: SelectionRange): void; /** * Set an ephemeral annotation. * @param selection - An annotation range containing the start and end location. The json-path in * an annotation location assumes no comment Milestone nodes are present in the USJ. * @param type - Type of the annotation. * @param id - ID of the annotation. * @param onClick - Optional onClick handler. * @param onRemove - Optional onRemove handler. */ setAnnotation( selection: AnnotationRange, type: string, id: string, onClick?: TypedMarkOnClick, onRemove?: TypedMarkOnRemove, ): void; /** * Remove an ephemeral annotation. * @param type - Type of the annotation. * @param id - ID of the annotation. */ removeAnnotation(type: string, id: string): void; /* Format the paragraph at the current cursor position with the given block marker. / formatPara(blockMarker: string): void; /* Get the editor element for the given node key, if any. / getElementByKey(nodeKey: string): HTMLElement | undefined; /** * Insert a note at the specified selection, e.g. footnote, cross-reference, endnote. * @param marker - The marker type for the note. * @param caller - Optional note caller to override the default for the given marker. * @param selection - Optional selection range where the note should be inserted. By default it * will use the current selection in the editor. * @throws Will throw an error if the marker is not a valid note marker. */ insertNote(marker: string, caller?: string, selection?: SelectionRange): void; /** * EXPERIMENTAL: Select the note by editor key or at the given index in the editor, if any. * @param noteKeyOrIndex - The note key or index, e.g. index=1 would select the second note in the * editor. */ selectNote(noteKeyOrIndex: string | number): void; /** * EXPERIMENTAL: Get the note operations by editor key or at the given index in the editor, if any. * @param noteKeyOrIndex - The note key or index, e.g. index=1 would get the second note in the * editor. */ getNoteOps(noteKeyOrIndex: string | number): DeltaOp[] | undefined; /* Ref to the end of the toolbar - INTERNAL USE ONLY to dynamically add controls in the toolbar. / toolbarEndRef: RefObject | null; } `
$3
`ts /* Options to configure the editor. / export interface EditorOptions { /* Is the editor readonly or editable. / isReadonly?: boolean; /* Does the editor have external UI controls so disable the built-in toolbar and context menu. / hasExternalUI?: boolean; /* Is the editor enabled for spell checking. / hasSpellCheck?: boolean; /* Text direction: "ltr" | "rtl" | "auto". / textDirection?: TextDirection; /* Key to trigger the marker menu. Defaults to '\'. / markerMenuTrigger?: string; /* Options for some editor nodes. / nodes?: UsjNodeOptions; /* EXPERIMENTAL: View options. Defaults to the formatted view mode which is currently the only functional option. / view?: ViewOptions; /* EXPERIMENTAL: Is the editor being debugged using the TreeView. / debug?: boolean; } `
$3
In
EditorOptions.nodes, you can set the list of possible note callers to what ever you need for the vernacular language being edited. The note callers option defaults to:`ts import { EditorOptions, UsjNodeOptions } from "@eten-tech-foundation/platform-editor";
These are the same as Editorial except where noted below. See Editorial API.
Marginal deprecation and migration
is in maintenance mode. The component continues to ship for backwards compatibility, but it will be removed in a future release. Prefer or an alternative commenting workflow if you can.
If you must continue using
, watch release notes for the removal timeline and plan a migration away from the margin-based commenting experience.
`ts /* Forward reference for the editor. / export interface MarginalRef extends EditorRef { /* Set the comments to accompany USJ Scripture. / setComments?(comments: Comments): void; } `
Demo and Collaborative Web Development Environment
Thanks to CodeSandbox for the instant dev environment: https://codesandbox.io/p/github/eten-tech-foundation/scripture-editors/main
This package is the third tab (
dev:platform:5175).
OR
To run the demo app locally, first follow the Developer Quick Start, but instead of running the last step, instead run:
`sh nx dev platform `
Develop in App
To develop an editor in a target application you can use yalc to link the editor in without having to publish to NPM every time something changes.
1. In this monorepo, publish the editor to
yalc, e.g.: `bash nx devpub platform-editor ` 2. In the target application repo, link from yalc: `bash yalc link @eten-tech-foundation/platform-editor ` 3. In this monorepo, make changes and re-publish the editor (see step 1). 4. When you have finished developing in the target application repo, unlink from yalc: `bash yalc remove @eten-tech-foundation/platform-editor && npm i ``