@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

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