unfoldingword/proskomma-react-hooks

A collection of React Hooks that provide a way to simplify the implementation of Proskomma into your React projects.

Proskomma React Hooks

This project is like placing training wheels on a speed bike (Proskomma).
Explore the docs and code playground »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgments

About The Project

Purpose: A collection of React Hooks that provide a way to simplify the implementation of Proskomma into your React projects.

Problem: Proskomma.js is a very powerful tool but has a fairly steep learning curve to setup and get running.

Scope: This project aims to simplify the implementing of Proskomma.js into our projects and especially the common use cases. It includes bootstrapping, importing and common queries/filters of Proskomma.

This project does not cover the downloading or obtaining of files to import.

Background: We implemented Proskomma.js in a few early projects but found it taking too long to setup and too much specific domain knowledge to make it useful. We kept refactoring our common use cases into this project as custom hooks and have a single place to maintain them.

Architecture and Design Principles: See ARCHITECTURE.md for details on architecture and design principles for this project.

(back to top)

Built With

• React.js
• Proskomma.js
• React Stylguidist

(back to top)

Getting Started

This is an example of how you may give instructions on setting up your project locally. To get a local copy up and running follow these simple example steps.

Prerequisites

Data The source of the data to import into Proskomma are scripture files such as USFM.

Testing files can be generated using Lorem Ipsum USFM.

Real USFM files can be found in multiple places such as:

• Door43 Catalog
• Ebible.org

This is an example of how to list things you need to use the software and how to install them.

• npm

  npm install npm@latest -g

Installation/First Steps

1. Setup a React app using Create React App or React Styleguidist.

npx create-react-app proskomma-react-hooks-app

2. Add it to your React app or component library (inside your project path):

• yarn

yarn add proskomma-react-hooks

• npm

npm i proskomma-react-hooks

3. Bootstrap inside App.jsx with useProskomma.
4. Import: Create a new component for Importing data useImport.
5. Passage: Create a new component for Passage Lookup and use custom hook inside it via usePassage.
6. Search: Create a new component for Search and use custom hook inside it via useSearchForPassages
7. Customize and run your own query useQuery

(back to top)

Usage/Integration

Use this space to show useful examples of how a project can be used. Additional screenshots, code examples and demos work well in this space. You may also link to more resources.

For more examples, please refer to the Styleguidist.

(back to top)

Roadmap

• Return data in useSearchForPassages and useSearchForPassagesByBookCodes just like useSearchForPassagesByBookCode
• Import Serialized JSON for faster importing/resuming of previous Proskomma state
• Enable editing of data through mutations
• Importing of non-USFM sources such as USX
• Rendering to Epub, PDF, HTML, and React via pk-render

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated. Guidelines for external contributions.

You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

If you would like to fork the repo and create a pull request.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Contact

Chris Klapp aka Klappy - [email protected]

Project Link: https://github.com/unfoldingWord/proskomma-react-hooks

(back to top)

Acknowledgments

• Mark Howe
• klappy

(back to top)

proskomma-react-hooks's Issues

Render formatted Scripture to screen using Pk renderer

The current PoC, in Diegesis, can be seen at https://github.com/Proskomma/diegesis/blob/ad625bce427af3886eb9817c61bb69334449fa65/src/pages/Browse/TextBookContent.js#L38

The main steps are

• Run a 'kitchen sink' query to get a description of the whole document (L43)
• Build a config object to pass data into the renderer (L45). Note that this object is also used to store and return state (so it should probably have a different name).
• Instantiate the renderer (L57).
• Give that renderer at least one docSet handler (L58, L60).
• Give that docSet handler at least one document handler (L59). Multiple handlers are useful if, eg, frontmatter is to be processed differently to canonical text.
• Render (L61)
• Do something with the generated state in the config object (L62)

At present it does not handle some USFM features such as character styles, but this could be done, as demonstrated for HTML generation with https://github.com/Proskomma/proskomma-render-pdf

One gotcha is that JSX cannot be generated one tag at a time, instead, some type of stack is required to collect enclosed content and then wrap it with matching tags. (The Diegesis PoC does this. The PDF generator does it in most places but is simply building strings.)

Also note that, in this case, the rendering model is setting the cv reference that is used to scroll to the selected verse.

We discussed making the renderer markup agnostic, ie allowing different containers etc to be specified. This would be cool, but it might be easier to get a hardwired model working with the hook first.

Populate Proskomma using useProskomma via non-USFM sources

@klappy This is almost the first thing that Chaliki does - see https://github.com/Proskomma/chaliki/blob/master/src/App.js

That code (which could definitely be prettier) loads an array of docSets in Proskomma serialized format, and also loads versification files for some of those docSets. In the latest version of Proskomma we could also be loading TSV files, syntax trees and/or key-value entries, and indeed any or all of those could be hiding inside the Proskomma serialized format.

How would we handle this cleanly using hooks?

import serialized JSON

Concept:

• Given a release, such as: https://git.door43.org/unfoldingWord/en_ult/releases/tag/32
• Which has "downloads" (attachments):
  
• The release process could add an attachment containing the PK serialized text (all 66+) of them
• The entire Bible could then be loaded in minimal time

@klappy

Add demo of a DCS import

Create a demo showing how to import a DCS USFM text.

Simplest is to demo using a URL like this:
https://git.door43.org/unfoldingWord/en_ult/raw/branch/master/66-JUD.usfm

And allow the user to edit the code to change the URL to anything they wish. Unless there is something special about importing more than one, a demo showing how to import a single text like the above should suffice.

If the useImport takes a verbose option, be sure to provide metrics on the import process.
@klappy

usePassage crashes on bad reference

When the reference is 3JN 1:1 the code works, but whenever we try changing that value the code crashes.

Error: "Uncaught TypeError: Cannot read properties of undefined (reading 'length')"

If we initialize the reference to "3JN 1:" we get this error: "Uncaught TypeError: Cannot destructure property 'groups' of 'r.match(...)' as it is null."

You can see this yourself at: https://github.com/Proskomma/diegesis-reboot/tree/elias-pinero-browsePassage

Merge branch with useRenderPreview into main branch

Things to note:

• There are at least three branches addressing this hook from three different developers. Thus, some reconciliation may be needed to get the best of each.
• At this point, all of the branches are behind main. Thus the latest changes made and already published in v2.2.1 must be merged into the branch first.

USFM strings permanently in scope in useProskomma?

Discussion on #1 helped me to notice how useProskomma is managing document state. As @klappy says: "Update the documents array and the import will run".

I think this means that all imported documents are in scope, as USFM strings, for the lifetime of the hook? This raises several concerns for me:

1. This mechanism at least doubles the RAM footprint, since each document is stored both as a string and within Proskomma. (In the case of syntax trees that's potentially a very big deal.)
2. In some cases (including the current version of Chaliki) there are no USFM strings, because Chaliki uses the serialized format. In other cases the document content would be USX or TSV or something else.
3. If/when we want to use verse mapping, we need to import VRS files which attach to already-imported documents.

The underlying issue, I think, is that the current hook uses Proskomma as if it's a function that performs transforms on an array of import documents. But Proskomma - like most models - is very, very stateful.

If we replaced Proskomma with PostgreSQL, we wouldn't consider storing all the DBMS content in an array in the view. We'd use a combination of select, insert, update and drop queries to read and write state. I think we should be aiming for something similar for Proskomma.

Improve README

https://github.com/unfoldingWord/readme-template

Resume state of Proskomma via `proskomma-freeze`

Developer should be able to import multiple docsets via single json file using proskomma-freeze.

Add mutations to edit a verse in a document

Developer should be able to mutate/change content in a document. Ie. edit a verse's text and not lose any data along the way.

useProskomma doesn't load documents when there is no text in the usfm file.

When using usfm files with just the verse and chapter numbers and no other text, useProskomma doesn't load the file and the document object is returned empty.

useProskomma.mp4

Paged.js React Hooks

• Create new repo
• Write hooks for paged.js
• inefficient to strip out styles and scripts - needs refactor
• documentation

Improve `useSearch` for more than single term

Developer should be able to search for a term, phrase, tokens, and limit scope to docSet and/or bookCode.

Expose ‘useBookCodeQueue’

After releasing v1.4, I realized that all nested hooks were exposed and documented except for the queueing hook.

Return data in useSearchForPassagesByBookCodes

In useSearchForPassagesByBookCode we get data in return. I think it will be usefull to have this in useSearchForPassagesByBookCodes.

Hook for 'catalog' query?

In Chaliki, at startup, there's a query to find out what's in Proskomma, and to display a summary for the user: https://github.com/Proskomma/chaliki/blob/bf11261b8ad738564bd165f825af2047058299ec/src/Pages/Standard/data/Data.js#L16

Would it be possible to have a hook to do this? We should probably add some more fields to make that hook more widely useful.