-
Notifications
You must be signed in to change notification settings - Fork 1
Development design for MVP
Prepared by Albeit Technology LLC, for unfoldingWord
This document describes the software changes needed to improve the USFM Editor component from its current (0.6.0) release to minimum viable product (MVP). In the MVP, the component will meet the requirements for use in its flagship consumer, the Autographa Bible translation application.
Released as 0.7.0-SNAPSHOT.1
The basic editor component will support only programmatic (API) commands for applying tags and chapter-verse structure. High level components will add GUI elements such as the toolbar and pagination. Exact implementation is to be determined by the implementor, but higher-order components are a promising approach here.
The component should provide a mechanism such as CSS to allow overrides of its default visual styling. Using plain CSS with careful class definitions instead of Material-UI allows more fine-grained control to the application.
The component should be usable in a read-only snippet mode to display (not edit) scripture fragments.
The editor should allow programmatic access to the identification headers of a document (though these will not be displayed or editable by the user through this component).
Book major title (\mt) tags should be partially supported. Multiple levels and lines need not be supported. WYSIWYG editing is not required.
The editor should not allow the user to reorder verses or specify lettered sub-verses, but must allow joined verses (that is, verse ranges).
To create a verse range, the user may select an existing verse number (or a verse range) marker and choose "join with previous verse", and the editor will concatenate their contents and replace the verse number with a verse range (or expand the range if it is already a range).
User may click on an existing verse range marker and choose "unjoin verses" and the editor will split out the individual verses as their own nodes. The contents will not be redistributed among the verses but will remain in the first of the split verses.
An API will be available to specify the chapter/verse structure of the document. The editor will add or remove chapters and verses from the document as needed to match the requested structure. New verses will be added after any existing text content, and the preexisting content of any removed verses will be concatenated into the previous verse.
The user interface should allow for adding and removing chapters and verses at the end of the document. The interface for this will be consistent with the joined verses UX, appearing as a context menu on the number markers.
The GUI for this feature must be disableable programmatically, as it will not be used for Autographa.
An automated test suite should be created for component testing.
The frameworks, libraries, and approaches recommended by React are preferred. Prefer small, fast component tests in the spirit of unit testing.
Test cases should be created for the following purposes:
- Test error-prone features
- Demonstrate that text is preserved in input/output
- Demonstrate that tags, including unsupported tags, are preserved in input/output, but not necessarily stable in structure
The editor should not depend on the application to split USFM documents into chapters. The editor API should deal in whole book USFM documents.
A pagination component will wrap the basic editor and present only one chapter at a time for editing. Selection of the active chapter should be allowed programmatically.
A GUI is also required for chapter selection, and will fire commands at the chapter paging component. This selector will typically be shown above the editor, like another toolbar. However, this selector UI must be programmatically hideable for use in applications (such as Autographa) which provide their own chapter selection UI.
To allow for syncing with other application panels, the editor must publish cursor-entered-verse events and accept go-to-verse-number commands.
A toolbar fixed at the top of the screen will be added to support user commands. Text formatting buttons (currently in a hovering context menu) will appear here. The toolbar will fire commands to the basic editor component.
The styling commands available on the toolbar should be separate from other implementation details, such as in a separate file of toolbutton definitions. Each toolbutton definition record should specify the icon, text, and action(s) to call on the basic editor.
Since the component is expected to be displayed at a fixed size in applications such as Autographa, the document panel should scroll scripture content within the editor. This capability should be implemented as a higher-level component, rather than by the basic editor.
To prevent large formatting mistakes, selection of scripture text will be constrained from crossing verse boundaries.
Usage documentation should be expanded to include per-component Styleguidist pages or similar.
Code style rules should be specified in a configuration file for ESLint or similar. Consider adding a linter to the commit checks on GitHub Actions.
Plans are changing, stay tuned....
Footnotes and cross references (collectively called "notes" here) must be supported. Tool buttons will create these elements. If scripture text is selected at the time of creation, the quoted text should be added to the new \fq or \xq tag within the new note. When a note is inserted, or when its "caller" character is subsequently clicked, a note editor box will be brought into focus (either by scrolling to the element, or, preferably, causing it to peek into view) to edit the note contents.
The following tags must be supported while in the note editor:
- Footnote origin reference (\fr)
- Footnote text (\ft)
- Footnote translation quotation (\fq)
- Footnote alternate translation (\fqa..\fqa*)
- Cross ref origin reference (\xo)
- Cross ref text (\xt)
- Cross ref quotation (\xq)
The list of supported formatting tags will be expanded to include the following poetry and special text styles:
- Poetry line (\q#)
- Paragraph (\p)
- Name of Deity (\nd ..\nd*)
- Words of Jesus (\wj .. \wj*)
Character format tags should be defined in an extensible way so new tags can be added without modifying editor logic. The table will likely be implemented as JSON containing USFM tag id, HTML rendering, CSS rules, and possibly special implementation functions for each tag.
At time of release, the editor should be current with the following:
The Slate library should be updated to the current version in the Slate v0.50+ (a.k.a. 0.5x) architecture. The architecture is not expected to change from 0.50+ soon, but if and when that happens, migrating will be a significant task and is beyond the scope of this work.
The editor should function under current versions of Chrome, Safari, and Firefox.