npm package: @mackral/bible-verses
Description: React Bible verse browsing UI library
Latest version: 1.0.0


# @mackral/bible-verses

A simple, experimental **React 18 Bible verse browsing UI library**, built with modern React patterns (hooks, reducer, and context).

Designed for **React beginners**, **advanced developers**, and **church dev teams** who want an easy way to browse Bible translations, books, chapters, and verses inside a React application.

---

## ✨ Features

- 📖 Browse Bible translations  
- 📚 Select books  
- 🔢 Navigate chapters  
- 📜 Read verses  
- ⚛️ Built with React 18, hooks, `useReducer`, and context  
- 📦 ESM-only, tree-shakeable package  
- 🧩 Modular UI components  

> ⚠️ **Status:** Experimental  
> This package is actively evolving and moving toward a stable release.

---

## 📦 Installation

```bash
npm install @mackral/bible-verses
```

## 🧠 Design Philosophy
- Simple and predictable state management
    - Clear separation of concerns:
    - API client
    - Reducer
    - Controller logic
    - UI components
- Friendly for beginners
- Flexible enough for advanced use cases
This library __does not handle routing__.
Routing-based navigation may be supported in future releases.

## 🎨 Styling
The current version uses utility-style class names (commonly used with Tailwind CSS).
- Styling is **not enforced**
- You can override styles freely
- A **non–Tailwind-dependent version** is planned for later releases

## 🔌 Bible API

This library consumes data from a **Bible API**.

 - API access is abstracted behind an internal client
 - You only need to provide a baseUrl
 - The API is treated generically and can be replaced if compatible

## 🚀 Complete Working Example

This example shows a fully working setup using all exported components.

    import {
      BibleProvider,
      TranslationSelector,
      BookList,
      Chapters,
      Verses
    } from "@mackral/bible-verses";
    
    function BibleApp() {
      return (
        <BibleProvider
          apiConfig={{ baseUrl: "https://your-bible-api.com" }}
          onSelectionChange={(selection) => {
            console.log("Selection changed:", selection);
          }}
        >
          <div style={{ padding: "1rem" }}>
            <h1>Bible Reader</h1>
    
            <TranslationSelector />
    
            <hr />
    
            <BookList />
    
            <hr />
    
            <Chapters />
    
            <hr />
    
            <Verses />
          </div>
        </BibleProvider>
      );
    }
    
    export default BibleApp;


You can drop this component directly into a React 18 app (Vite, CRA, Next.js client-side).

## 🧩 Components

    <BibleProvider />

Wraps your app and provides shared Bible state.

    <BibleProvider
      apiConfig={{ baseUrl }}
      onSelectionChange={(selection) => console.log(selection)}
    >
      {children}
    </BibleProvider>

**Props**
| Prop	 | Description |
| apiConfig	| { baseUrl } for the Bible API |
| onSelectionChange | Callback fired when translation, book, or chapter changes |

    <TranslationSelector />

Dropdown for selecting a Bible translation.

    <BookList />

Displays available books for the selected translation.

    <Chapters />

Shows chapter numbers for the selected book.

    <Verses />

Renders verse content for the selected chapter.

## 🧪 Experimental Notes

Current limitations:

 - No routing support
 - No controlled visibility props
 - Assumes a consistent API response shape

Planned for future releases:

 - Routing-aware navigation
 - Controlled visibility / headless usage
 - Styling-agnostic components
 - Improved extensibility

## 🧱 Namespace Strategy

`@mackral/bible-verses` is part of the @mackral namespace.

More packages under this namespace are planned, making related tools easy to discover.

## 🤝 Contributing

Contributions are welcome — **simple PRs especially** 🙌

**How to contribute**

 1. Fork the repository
 2. Create a feature or fix branch
 3. Keep changes focused and minimal
 4. Open a PR with a clear description

Good first contributions:

 - Bug fixes
 - Documentation improvements
 - Small UI tweaks
 - Minor code cleanup (no major refactors without discussion)

## License
MIT