@tarekeldeeb/quran-madina-react 0.6.1

package/README.md

@@ -0,0 +1,139 @@
+# @tarekeldeeb/quran-madina-react
+
+A thin React component around the `<quran-madina-html>` custom element. The actual rendering is
+still done by the [`quran-madina-html`](https://www.npmjs.com/package/quran-madina-html) library
+(HTML/CSS, no images) — this just loads it and exposes the tag as a normal React component. The
+**same** wrapper drives **web, iOS and Android** (mobile via a WebView container such as Capacitor;
+see below).
+
+The library is not bundled: the component injects its `<script>` at runtime (the library reads its
+config from its own `<script>` tag, so a plain `import` of it would not work). `react` is a peer
+dependency.
+
+## Install
+
+```bash
+npm install @tarekeldeeb/quran-madina-react react
+```
+
+## Usage
+
+```jsx
+import QuranMadinaHtml from "@tarekeldeeb/quran-madina-react";
+
+export default function App() {
+  return (
+    <div dir="rtl">
+      {/* full page */}
+      <QuranMadinaHtml page={106} font="Hafs" />
+
+      {/* aya range */}
+      <QuranMadinaHtml sura={2} aya="8-10" />
+
+      {/* a word subsequence (1-based, inclusive) */}
+      <QuranMadinaHtml sura={1} aya={1} words="1:2" />
+
+      {/* no header / copy chrome */}
+      <QuranMadinaHtml sura={2} aya="13-14" headless />
+    </div>
+  );
+}
+```
+
+### Props
+
+| Prop        | Type                | Notes |
+|-------------|---------------------|-------|
+| `page`      | number \| string    | Full page 1–604. Mutually exclusive with `sura`/`aya` (page wins). |
+| `sura`      | number \| string    | Sura 1–114, with `aya`. |
+| `aya`       | number \| string    | Aya or range, e.g. `"8-10"`. |
+| `words`     | string              | 1-based word range: `"1:2"`, `"3-10"`, or a single index. |
+| `headless`  | boolean             | Drop the header/copy chrome. |
+| `font`      | string              | `Hafs`, `Uthman`, `Amiri Quran`, `Amiri Quran Colored`, `me_quran`. |
+| `name`      | string              | DB name, default `Madina05`. |
+| `fontSize`  | number \| string    | px, default 16. |
+| `src`       | string              | Library script URL. Default: unpkg latest. |
+| `cdn`       | string              | Base URL for CSS + JSON assets. Default: unpkg package root. |
+
+> **Global config caveat:** `font`, `name`, `fontSize`, `src` and `cdn` configure the single
+> library instance for the whole page. Only the **first** mounted `<QuranMadinaHtml>` sets them;
+> later values are ignored. Put your config on the first instance you render.
+
+## Why `cdn` matters (localhost gotcha)
+
+The library figures out where to fetch its CSS + JSON DB from based on the **page** host: on any
+`localhost` host it assumes the assets live at `../` (that's how this repo's own demo works). A
+React dev server (`localhost:3000`) and a Capacitor app (host is also `localhost`) do **not** have
+the assets at `../`, so without help the DB fetch 404s.
+
+The wrapper fixes this by setting `data-cdn` to the unpkg package root by default, so assets always
+resolve. Override `cdn` if you self-host the assets:
+
+```jsx
+<QuranMadinaHtml page={1} cdn="https://my.cdn.example/quran-madina-html/" />
+```
+
+> `data-cdn` support requires a build of the library that includes it (the release that introduced
+> this feature, or a local `npm run build` of this repo). When loading from a CDN, pin a version
+> that supports it, e.g. `src="https://unpkg.com/quran-madina-html@X.Y.Z"`.
+
+## Mobile: iOS + Android with Capacitor
+
+Capacitor wraps your existing React web build in a native shell with a WebView, so the very same
+component runs on device. Outline:
+
+```bash
+# in your React app
+npm install @capacitor/core @capacitor/cli
+npx cap init "My Quran App" com.example.quran --web-dir=dist   # or build/ for CRA
+npm run build                 # produce the web bundle
+npx cap add ios
+npx cap add android
+npx cap copy
+npx cap open ios              # opens Xcode  → run on simulator/device
+npx cap open android         # opens Android Studio
+```
+
+Notes for mobile:
+
+- Capacitor serves the app from `localhost`, so keep the default `cdn` (unpkg) **or** self-host the
+  assets and point `cdn` at them — see above. Do not rely on the library's `../` default.
+- **Offline support:** bundle the library `dist/quran-madina-html.min.js`, `dist/*.min.css`, the
+  `assets/db/*.json` you use and the `assets/fonts/*.woff2` into your web build, then set `src` to
+  the bundled JS and `cdn` to the base path that contains `dist/` and `assets/`. Everything —
+  including the font — resolves from `cdn`, so no network is needed (requires library >= 0.6,
+  which stores font paths relative).
+- This is the recommended mobile path: it reuses the battle-tested HTML/CSS renderer (fonts,
+  per-line stretch, offsets) instead of reimplementing the layout natively in React Native.
+
+## React Native (native, no WebView)
+
+Not provided here. React Native has no DOM/HTML/CSS, so the custom element cannot run; it would
+require porting the renderer to native `View`/`Text` + `transform: scaleX`. Use the Capacitor path
+above unless you specifically need native (non-WebView) rendering.
+
+## Developing this package
+
+```bash
+cd react
+npm install
+npm test                # vitest (jsdom) — wrapper + loader unit tests
+npm run build           # esbuild → dist/index.mjs + dist/index.cjs, copies dist/index.d.ts
+```
+
+`dist/` is git-ignored and rebuilt automatically on publish (`prepublishOnly`). Source lives in
+`src/`; the public API is hand-typed in `src/index.d.ts`.
+
+## Releasing
+
+This package is released **in lockstep with the core library** by the repo-root command:
+
+```bash
+npm run release         # release-it: builds + publishes quran-madina-html AND this wrapper
+```
+
+The root `release-it` config syncs this `package.json` to the core's new version before the release
+commit, then publishes `@tarekeldeeb/quran-madina-react@<version>` (matching the core) after the
+core lands on npm (see `scripts/sync-wrapper-version.mjs` and `scripts/publish-wrapper.mjs`). So the
+wrapper version always equals the core version. A manual one-off publish is still possible with
+`npm publish --access public` from this folder (scoped packages need `--access public`).

package/dist/index.cjs

@@ -0,0 +1,120 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.js
+var index_exports = {};
+__export(index_exports, {
+  default: () => QuranMadinaHtml,
+  loadQuranMadinaHtml: () => loadQuranMadinaHtml
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/QuranMadinaHtml.jsx
+var import_react = __toESM(require("react"), 1);
+var TAG = "quran-madina-html";
+var DEFAULT_SRC = "https://unpkg.com/quran-madina-html";
+var DEFAULT_CDN = "https://unpkg.com/quran-madina-html/";
+var loaderPromise = null;
+function loadQuranMadinaHtml(opts = {}) {
+  const { src = DEFAULT_SRC, cdn = DEFAULT_CDN, font, name, fontSize } = opts;
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    return Promise.resolve();
+  }
+  if (loaderPromise) return loaderPromise;
+  if (window.customElements && window.customElements.get(TAG)) {
+    loaderPromise = Promise.resolve();
+    return loaderPromise;
+  }
+  loaderPromise = new Promise((resolve, reject) => {
+    const script = document.createElement("script");
+    script.src = src;
+    script.async = true;
+    if (cdn) script.setAttribute("data-cdn", cdn);
+    if (font) script.setAttribute("data-font", font);
+    if (name) script.setAttribute("data-name", name);
+    if (fontSize != null) script.setAttribute("data-font-size", String(fontSize));
+    script.onload = () => resolve();
+    script.onerror = () => {
+      loaderPromise = null;
+      reject(new Error(`Failed to load ${src}`));
+    };
+    document.head.appendChild(script);
+  });
+  return loaderPromise;
+}
+function QuranMadinaHtml({
+  page,
+  sura,
+  aya,
+  words,
+  headless,
+  // loader config (only honored on first mount, see loadQuranMadinaHtml)
+  src,
+  cdn,
+  font,
+  name,
+  fontSize,
+  className,
+  style,
+  ...rest
+}) {
+  const ref = (0, import_react.useRef)(null);
+  const [ready, setReady] = (0, import_react.useState)(
+    typeof window !== "undefined" && !!window.customElements && !!window.customElements.get(TAG)
+  );
+  (0, import_react.useEffect)(() => {
+    let active = true;
+    loadQuranMadinaHtml({ src, cdn, font, name, fontSize }).then(() => active && setReady(true)).catch((err) => console.error("[quran-madina-html]", err));
+    return () => {
+      active = false;
+    };
+  }, [src, cdn, font, name, fontSize]);
+  (0, import_react.useEffect)(() => {
+    const el = ref.current;
+    if (!el) return;
+    const set = (key, value) => {
+      if (value === void 0 || value === null || value === false || value === "") {
+        el.removeAttribute(key);
+      } else {
+        el.setAttribute(key, value === true ? "" : String(value));
+      }
+    };
+    if (page !== void 0 && page !== null && page !== "") {
+      set("page", page);
+      set("sura", null);
+      set("aya", null);
+    } else {
+      set("page", null);
+      set("sura", sura);
+      set("aya", aya);
+    }
+    set("words", words);
+    set("headless", headless);
+  }, [ready, page, sura, aya, words, headless]);
+  return import_react.default.createElement(TAG, { ref, class: className, style, ...rest });
+}

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+import * as React from "react";
+
+export interface QuranMadinaHtmlLoaderOptions {
+  /** URL of the library script (default: https://unpkg.com/quran-madina-html). */
+  src?: string;
+  /** Base URL for the CSS + JSON assets (default: https://unpkg.com/quran-madina-html/). */
+  cdn?: string;
+  /** data-font: "Hafs" | "Uthman" | "Amiri Quran" | "Amiri Quran Colored" | "me_quran". */
+  font?: string;
+  /** data-name (default "Madina05"). */
+  name?: string;
+  /** data-font-size in px (default 16). */
+  fontSize?: number | string;
+}
+
+export interface QuranMadinaHtmlProps
+  extends QuranMadinaHtmlLoaderOptions,
+    React.HTMLAttributes<HTMLElement> {
+  /** Render a full Madina page (1-604). Mutually exclusive with sura/aya. */
+  page?: number | string;
+  /** Sura number (1-114). Use together with `aya`. */
+  sura?: number | string;
+  /** Aya number or range, e.g. "8-10". Use together with `sura`. */
+  aya?: number | string;
+  /** Restrict to a 1-based word range, e.g. "1:2", "3-10", or a single index. */
+  words?: string;
+  /** Drop the header / copy chrome and render only the Quran text. */
+  headless?: boolean;
+}
+
+/** Inject the loader script once; resolves when the custom element is registered. */
+export function loadQuranMadinaHtml(
+  opts?: QuranMadinaHtmlLoaderOptions
+): Promise<void>;
+
+declare const QuranMadinaHtml: React.FC<QuranMadinaHtmlProps>;
+export default QuranMadinaHtml;

package/dist/index.mjs

@@ -0,0 +1,88 @@
+// src/QuranMadinaHtml.jsx
+import React, { useEffect, useRef, useState } from "react";
+var TAG = "quran-madina-html";
+var DEFAULT_SRC = "https://unpkg.com/quran-madina-html";
+var DEFAULT_CDN = "https://unpkg.com/quran-madina-html/";
+var loaderPromise = null;
+function loadQuranMadinaHtml(opts = {}) {
+  const { src = DEFAULT_SRC, cdn = DEFAULT_CDN, font, name, fontSize } = opts;
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    return Promise.resolve();
+  }
+  if (loaderPromise) return loaderPromise;
+  if (window.customElements && window.customElements.get(TAG)) {
+    loaderPromise = Promise.resolve();
+    return loaderPromise;
+  }
+  loaderPromise = new Promise((resolve, reject) => {
+    const script = document.createElement("script");
+    script.src = src;
+    script.async = true;
+    if (cdn) script.setAttribute("data-cdn", cdn);
+    if (font) script.setAttribute("data-font", font);
+    if (name) script.setAttribute("data-name", name);
+    if (fontSize != null) script.setAttribute("data-font-size", String(fontSize));
+    script.onload = () => resolve();
+    script.onerror = () => {
+      loaderPromise = null;
+      reject(new Error(`Failed to load ${src}`));
+    };
+    document.head.appendChild(script);
+  });
+  return loaderPromise;
+}
+function QuranMadinaHtml({
+  page,
+  sura,
+  aya,
+  words,
+  headless,
+  // loader config (only honored on first mount, see loadQuranMadinaHtml)
+  src,
+  cdn,
+  font,
+  name,
+  fontSize,
+  className,
+  style,
+  ...rest
+}) {
+  const ref = useRef(null);
+  const [ready, setReady] = useState(
+    typeof window !== "undefined" && !!window.customElements && !!window.customElements.get(TAG)
+  );
+  useEffect(() => {
+    let active = true;
+    loadQuranMadinaHtml({ src, cdn, font, name, fontSize }).then(() => active && setReady(true)).catch((err) => console.error("[quran-madina-html]", err));
+    return () => {
+      active = false;
+    };
+  }, [src, cdn, font, name, fontSize]);
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    const set = (key, value) => {
+      if (value === void 0 || value === null || value === false || value === "") {
+        el.removeAttribute(key);
+      } else {
+        el.setAttribute(key, value === true ? "" : String(value));
+      }
+    };
+    if (page !== void 0 && page !== null && page !== "") {
+      set("page", page);
+      set("sura", null);
+      set("aya", null);
+    } else {
+      set("page", null);
+      set("sura", sura);
+      set("aya", aya);
+    }
+    set("words", words);
+    set("headless", headless);
+  }, [ready, page, sura, aya, words, headless]);
+  return React.createElement(TAG, { ref, class: className, style, ...rest });
+}
+export {
+  QuranMadinaHtml as default,
+  loadQuranMadinaHtml
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@tarekeldeeb/quran-madina-react",
+  "version": "0.6.1",
+  "description": "React wrapper for the quran-madina-html custom element — render Madina-style Quran pages (no images) in React on web and mobile (via a Capacitor WebView).",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "node build.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.1.0",
+    "esbuild": "^0.24.0",
+    "jsdom": "^25.0.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "vitest": "^2.1.8"
+  },
+  "keywords": [
+    "quran",
+    "madina",
+    "mushaf",
+    "arabic",
+    "react",
+    "quran-madina-html"
+  ],
+  "author": "Tarek Eldeeb",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tarekeldeb/quran-madina-html.git",
+    "directory": "react"
+  },
+  "bugs": {
+    "url": "https://github.com/tarekeldeb/quran-madina-html/issues"
+  },
+  "homepage": "https://github.com/tarekeldeb/quran-madina-html/tree/main/react#readme"
+}