Better docs, small improvements, removed extraneous stuff

Author: tjcouch-sil

extensions/.vscode/settings.json

@@ -6,7 +6,7 @@
   "editor.rulers": [100],
   "editor.wordWrapColumn": 100,
 
-  "eslint.validate": ["javascript", "javascriptreact", "html", "typescriptreact"],
+  "eslint.validate": ["html", "javascript", "javascriptreact", "typescript", "typescriptreact"],
 
   "files.associations": {
     ".eslintignore": "ignore",

extensions/src/platform-scripture-editor/src/main.ts

@@ -328,8 +328,10 @@ class ScriptureEditorWebViewFactory extends WebViewFactory<typeof scriptureEdito
             throw new Error(`webViewDefinition.projectId is empty!`);
 
           // Figure out the information needed to make the USJ range to give to the editor:
-          // book, chapter, start jsonPath and offset, and end jsonPath and offset
-          let startVerseRef = { book: '', chapterNum: 0, verseNum: 0 };
+          // book, chapter, start jsonPath and offset, and end jsonPath and offset.
+          // Also need to get the verse to set the scroll group verse to because the editor doesn't
+          // do it automatically right now
+          let startVerseRef = { book: '', chapterNum: 0, verseNum: -1 };
           let startJsonPath = '';
           let endJsonPath = '';
           // Start and end offsets based on the USJ JSONPath location
@@ -391,13 +393,14 @@ class ScriptureEditorWebViewFactory extends WebViewFactory<typeof scriptureEdito
               'Could not get targetScrRef from range! Selection range cannot (yet) span chapters or books',
             );
 
-          // If we don't have at least one of the USJ range properties, need to process the chapter
-          // to find them based on what we have
+          // If we don't have at least one of the USJ range properties or the verse number, need to
+          // process the chapter to find them based on what we have
           if (
             !startJsonPath ||
             !endJsonPath ||
             startJsonPathOffset === undefined ||
-            endJsonPathOffset === undefined
+            endJsonPathOffset === undefined ||
+            startVerseRef.verseNum === -1
           ) {
             // Get the USJ chapter we're on so we can determine the missing USJ range properties
             const pdp = await papi.projectDataProviders.get(
@@ -480,6 +483,15 @@ class ScriptureEditorWebViewFactory extends WebViewFactory<typeof scriptureEdito
                 // will not exist once the editor is updated
                 endJsonPathOffset = 0;
             }
+
+            // If we don't have which verse we're setting the scroll group to, get it
+            if (startVerseRef.verseNum === -1) {
+              const startUsfmLocation = usjRW.usjDocumentLocationToUsfmVerseRefVerseLocation(
+                (startContentLocation ?? usjRW.jsonPathToUsjNodeAndDocumentLocation(startJsonPath))
+                  .documentLocation,
+              );
+              startVerseRef.verseNum = startUsfmLocation.verseRef.verseNum;
+            }
           }
 
           const convertedRange = {

extensions/src/platform-scripture-editor/src/platform-scripture-editor.web-view.tsx

@@ -189,10 +189,10 @@ globalThis.webViewComponent = function PlatformScriptureEditor({
             // and scroll to the new scrRef before setting the range. Set the nextSelectionRange
             // which will set the range after a short wait time in a `useEffect` below
             setScrRefWithScroll(targetScrRef);
-            if (range) nextSelectionRange.current = range;
+            nextSelectionRange.current = range;
           }
           // We're on the right scr ref. Go ahead and set the selection
-          else if (range) editorRef.current?.setSelection(range);
+          else editorRef.current?.setSelection(range);
 
           break;
         }

lib/platform-bible-utils/README.md

@@ -2,9 +2,63 @@
 
 A set of utility functions, types, and classes for use inside Platform.Bible and extensions.
 
-## Development
+## Scripture Location Types Overview
 
-Inspired by https://github.com/jasonsturges/vite-typescript-npm-package
+There are many types exported from this package that describe specific positions in a Scripture project.
+
+The types generally follow this name format:
+
+```
+<scripture_format><location_format?><location_anchor?>Location
+```
+
+- `<scripture_format>` - Which Scripture format the location information is specified against. For example, if the Scripture format is `Usfm`, offsets from the anchor to the specified position are string character index offsets within the USFM representation of the Scripture data.
+- `<location_format?>` - Particulars about the way the anchor is specified. If this is not included, this type is likely a catch-all containing a union of multiple subtypes that all include the same information in different location formats.
+- `<location_anchor?>` - `Book`, `Chapter`, `Verse`, or `Document` - Which kind of more general, well-known position this location is relative to. The more general location "anchor" may be an absolute position: the start of a specified chapter, book, verse; the data in this location type is expected to specify which chapter, book, or verse the location data is relative to. The anchor may also be a specific USJ document, in which case the location type is not expected to specify which document it is relative to. Document-relative positions are only interpretable if you have the document the position is based on; other location types layer over the document-relative types to indicate which document (and therefore which absolute position) the document-relative position is based on. If this is not specified, this type is a union of multiple subtypes that all specify positions in the same Scripture format.
+
+Examples:
+
+- `UsfmVerseLocation` - Locations relative to the start of a specified verse and at an offset in the USFM representation of the Scripture data
+
+  - `<scripture_format>` - `USFM` - the information specifying the position relative to the anchor is an offset based on the USFM representation of the Scripture data
+  - `<location_format>` - None; this is a union type of multiple subtypes that all specify the same data.
+  - `<location_anchor>` - `Verse` - this location specifies a specific verse that its position is relative to
+
+- `UsjLocation` - Location whose JSONPath is specified on a USJ document which contains either the entire book or the entire chapter specified and whose offset information is in the USJ representation of the Scripture data
+
+  - `<scripture_format>` - `USFM` - the information specifying the position relative to the anchor is an offset based on the USFM representation of the Scripture data
+  - `<location_format>` - None; this is a union type of multiple subtypes whose subtypes all specify the same data as one another.
+  - `<location_anchor>` - None; this is a union type of multiple subtypes that all specify either a USJ book or chapter location
+
+- Document-relative locations - various location types that specify a location within some USJ document which is not determinable based on the information in these types
+  - `UsjDocumentLocation` - A JSONPath query to an object, string, or property within a USJ document and additional information that point to a specific location in that USJ document.
+    - Note: The subtypes of this type do not conform to the naming format specified above. They are all different forms of USJ document-relative locations.
+    - JSONPath types - subsets of [JSONPath](https://www.rfc-editor.org/rfc/rfc9535.html) that point to some object, string, or property in a USJ document
+      - `ContentJsonPath` - JSON path to an object or text content string in a USJ document.
+      - `PropertyJsonPath` - JSON path to a property on an object in a USJ document.
+    - Types of USJ document locations - each type is a different format specifying various kinds of locations in a USJ document.
+      - `UsjAttributeKeyLocation`
+      - `UsjAttributeMarkerLocation`
+      - `UsjClosingAttributeMarkerLocation`
+      - `UsjClosingMarkerLocation`
+      - `UsjMarkerLocation`
+      - `UsjTextContentLocation`
+  - `UsjNodeAndDocumentLocation` - An object or string in a USJ document and its location in that document.
+- Absolute locations - various location types that specify a location within a determinable document or relative to a specific point in the Scripture data.
+
+  - `UsfmVerseLocation` - A verse ref and an offset within that verse in USFM space that point to a specific location in USFM.
+    - `UsfmVerseRefVerseLocation` - A particular format for specifying a verse ref and an offset within that verse in USFM space that point to a specific location in USFM.
+    - `SerializedVerseRef` - Just a verse reference. The offset is implied to be 0, meaning this always points to the very beginning of a verse.
+  - `UsjLocation` - A verse ref and a location in USJ space that point to a specific location in USJ. The location in USJ space should be interpreted as starting from either the start of the book or the chapter depending on the type of location used.
+
+    - `UsjBookLocation` - A verse ref and a location in USJ space that point to a specific location in USJ. The location in USJ space should be interpreted as starting from the start of the book specified.
+      - `UsjFlatBookLocation`
+      - `UsjVerseRefBookLocation`
+    - `UsjChapterLocation` - A verse ref and a location in USJ space that point to a specific location in USJ. The location in USJ space should be interpreted as starting from the start of the chapter specified.
+      - `UsjFlatChapterLocation`
+      - `UsjVerseRefChapterLocation`
+
+## Development
 
 When we publish this npm package, then in the root `package.json`, a version can be given to `platform-bible-utils` instead of the existing file link. At that time we will likely need to use `npm link` and `npm unlink` to develop the components ([see here](https://github.com/jasonsturges/vite-typescript-npm-package#development)).
 
@@ -44,3 +98,7 @@ npm run build:basic
 ```
 
 Do not commit changes after running this basic build. Before committing, always run a full build.
+
+## Acknowledgements
+
+Inspired by https://github.com/jasonsturges/vite-typescript-npm-package

lib/platform-bible-utils/dist/index.d.ts

@@ -2800,10 +2800,12 @@ export interface IUsjReaderWriter {
 	 * Convert a JSONPath query into a SerializedVerseRef and offset
 	 *
 	 * @param jsonPathQuery JSONPath search expression that indicates a node within this USJ data. If
-	 *   the expression matches more than one node, then only the first node found is considered.
+	 *   the expression matches more than one node, then only the first node found is considered. Note
+	 *   that this query must yield a {@link MarkerContent} or {@link Usj}; JSONPaths yielding
+	 *   properties on nodes are not currently supported.
 	 * @param bookIdIfNotFound 3-letter ID of the book this USJ document is in (only used if a book ID
 	 *   is not found in the USJ document)
-	 * @returns SerializedVerseRef and offset that represents the location within this USJ data
+	 * @returns SerializedVerseRef and offset that represent the location within this USJ data
 	 *   indicated by `jsonPathQuery`
 	 * @throws If not able to find a book ID in the USJ document and `bookIdIfNotFound` is not
 	 *   provided
@@ -2813,13 +2815,11 @@ export interface IUsjReaderWriter {
 	 * Convert a JSONPath query into a USJ node, JSONPath, and offset
 	 *
 	 * @param jsonPathQuery JSONPath search expression that indicates a node within this USJ data. If
-	 *   the expression matches more than one node, then only the first node found is considered.
-	 * @param bookIdIfNotFound 3-letter ID of the book this USJ document is in (only used if a book ID
-	 *   is not found in the USJ document)
-	 * @returns SerializedVerseRef and offset that represents the location within this USJ data
+	 *   the expression matches more than one node, then only the first node found is considered. Note
+	 *   that this query must yield a {@link MarkerContent} or {@link Usj}; JSONPaths yielding
+	 *   properties on nodes are not currently supported.
+	 * @returns USJ node, JSONPath, and offset that represent the location within this USJ data
 	 *   indicated by `jsonPathQuery`
-	 * @throws If not able to find a book ID in the USJ document and `bookIdIfNotFound` is not
-	 *   provided
 	 */
 	jsonPathToUsjNodeAndDocumentLocation(jsonPathQuery: string): UsjNodeAndDocumentLocation;
 	/** Build a JSONPath query that uniquely identifies the given node with this USJ data. */
@@ -2942,26 +2942,6 @@ export interface IUsjReaderWriter {
 	 *   provided
 	 */
 	usjDocumentLocationToUsfmVerseRefVerseLocation(usjLocation: UsjDocumentLocation, bookIdIfNotFound?: string): UsfmVerseRefVerseLocation;
-	/**
-	 * Transforms a relative USJ document location into an absolute chapter-based USJ location that
-	 * includes which chapter the USJ location is relative to.
-	 *
-	 * Note: this method property transforms book-based USJ document locations to chapter-based USJ
-	 * locations as well.
-	 *
-	 * Note: This may work with peripheral books as well, but these books have `periph` markers
-	 * between `id` and chapters, so this may need to be revised when peripheral books are more fully
-	 * supported
-	 *
-	 * @param usjLocation Location in USJ space relative to the USJ document
-	 * @param bookIdIfNotFound 3-letter ID of the book this USJ document is in (only used if a book ID
-	 *   is not found in the USJ document)
-	 * @returns Location in USJ space relative to the chapter that the USJ document location is in
-	 * @throws If not able to find the location in the USJ document
-	 * @throws If not able to find a book ID in the USJ document and `bookIdIfNotFound` is not
-	 *   provided
-	 */
-	usjDocumentLocationToUsjVerseRefChapterLocation<TDocumentLocation extends UsjDocumentLocation = UsjDocumentLocation>(usjLocation: TDocumentLocation, bookIdIfNotFound?: string): UsjVerseRefChapterLocation<TDocumentLocation>;
 }
 /** Gets the default caller sequence to use to generate callers for textual notes. */
 export declare function getDefaultCallerSequence(): string[];
@@ -4957,20 +4937,6 @@ export declare class UsjReaderWriter implements IUsjReaderWriter {
 	private static jsonPathArrayToJsonPath;
 	/** "Normalize" the JSONPath passed in so we can use it for lookups in {@link FragmentsByJsonPath} */
 	private static normalizeJsonPath;
-	/**
-	 * Move a JSONPath to be relative to a chapter marker JSONPath by removing the chapter path parts
-	 * from the front of the JSONPath and adjusting the content index.
-	 *
-	 * @example Taking JSONPath `$.content[0].content[2].content[5].content[7]['caller']` and moving
-	 * it relative to chapter JSONPath `$.content[0].content[2].content[3]` would return
-	 * `$.content[2].content[7]['caller']`
-	 *
-	 * @param jsonPath JSONPath to move to be relative to the chapter
-	 * @param chapterJsonPath JSONPath to use as the chapter from which to make the other JSONPath
-	 *   relative
-	 * @returns `jsonPath` made relative to the chapter JSONPath
-	 */
-	private static moveJsonPathRelativeToChapter;
 	/**
 	 * Returns a "normalized" JSONPath transformed from the working stack. We can use this JSONPath
 	 * for lookups in {@link FragmentsByJsonPath}
@@ -5091,7 +5057,6 @@ export declare class UsjReaderWriter implements IUsjReaderWriter {
 	 *   JSONPath
 	 */
 	static usjBookLocationToUsjVerseRefBookLocation(usjBookLocation: UsjBookLocation): UsjVerseRefBookLocation;
-	usjDocumentLocationToUsjVerseRefChapterLocation<TDocumentLocation extends UsjDocumentLocation = UsjDocumentLocation>(usjLocation: TDocumentLocation, bookIdIfNotFound?: string): UsjVerseRefChapterLocation<TDocumentLocation>;
 	usfmVerseLocationToUsjNodeAndDocumentLocation(usfmVerseLocation: UsfmVerseLocation): UsjNodeAndDocumentLocation;
 	usfmVerseLocationToUsjDocumentLocation(usfmVerseLocation: UsfmVerseLocation | SerializedVerseRef): UsjDocumentLocation;
 	/**