@tarekeldeeb/quran-madina-react 2.1.0 → 2.1.2

package/LICENSE.md

@@ -0,0 +1 @@
+Code and assets are licensed under ["Waqf" General Public License 2.0](https://github.com/ojuba-org/waqf/tree/master/2.0), 3 Muharram 1435

package/README.md

@@ -2,6 +2,8 @@
 
 [![Socket Badge](https://badge.socket.dev/npm/package/@tarekeldeeb/quran-madina-react)](https://socket.dev/npm/package/@tarekeldeeb/quran-madina-react)
 
+**[Documentation](https://tarekeldeeb.github.io/quran-madina-html/docs/)** · [Live demo](https://tarekeldeeb.github.io/quran-madina-html/demo/index.html)
+
 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
@@ -70,6 +72,7 @@ export default function App() {
 | `fontSize`  | number \| string    | px, default 16. Any size works. |
 | `src`       | string              | Library script URL. Default: unpkg latest. |
 | `cdn`       | string              | Base URL for CSS + JSON assets. Default: unpkg package root. |
+| `bundled`   | boolean \| string   | Load the app's own copy of the library (see Offline below): `true` for `/quran-madina/`, or the URL it is served at. Overrides `src`/`cdn`. |
 
 > **Global config caveat:** `layout`, `fontSize`, `src` and `cdn` configure the single
 > library instance for the whole page. Only the **first** mounted `<QuranMadinaHtml>` sets them;
@@ -114,14 +117,30 @@ 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/v2/` files of the layout you use (its `.json` or shard folder and its `-qmh.woff2` font) 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).
+- **Offline:** see below; the copied files go into the app with the rest of the build.
 - 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.
 
+## Offline
+
+Copy the library, its databases and fonts into your app once, from the app's folder:
+
+```bash
+npx quran-madina-bundle                            # the 1441H layout, into public/quran-madina
+npx quran-madina-bundle --layouts 1441H,IndoPak    # about 4 MB per layout
+```
+
+Then pass `bundled`, and nothing loads from the network:
+
+```jsx
+<QuranMadinaHtml page={106} bundled />
+```
+
+Options: `--out <folder>` (default `public/quran-madina`), `--version <x.y.z>` (default: this
+package's version), `--from <folder>` (a built checkout instead of npm). If the folder is served
+somewhere other than `/quran-madina/`, pass that URL: `bundled="/my-app/quran-madina/"`. Run the
+command again after upgrading.
+
 ## React Native (native, no WebView)
 
 Not provided here. React Native has no DOM/HTML/CSS, so the custom element cannot run; it would

package/bin/bundle.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+// Copies quran-madina-html (script, CSS, databases, fonts) into the app's public/ folder, so
+// <QuranMadinaHtml bundled /> renders offline. Run from the app's folder:
+//
+//   npx quran-madina-bundle                          # the 1441H layout, into public/quran-madina
+//   npx quran-madina-bundle --layouts 1441H,IndoPak
+//   npx quran-madina-bundle --out static/quran-madina --version 2.1.1
+//   npx quran-madina-bundle --from ../quran-madina-html   # a built checkout instead of npm
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { DEFAULT_OUT, LAYOUT_STEMS, readFolder, readTarGz, selectBundle } from "./lib.mjs";
+
+const fail = (message) => {
+  console.error(`quran-madina-bundle: ${message}`);
+  process.exit(1);
+};
+
+// the wrapper is released in step with the library: bundle the same version by default
+const own = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8"));
+
+const args = process.argv.slice(2);
+let layouts = ["1441H"];
+let version = own.version;
+let out = DEFAULT_OUT;
+let from = null;
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  const value = () => {
+    if (arg.includes("=")) return arg.slice(arg.indexOf("=") + 1);
+    if (i + 1 >= args.length) fail(`${arg} needs a value`);
+    return args[++i];
+  };
+  if (arg.startsWith("--layouts")) layouts = value().split(",").map((s) => s.trim()).filter(Boolean);
+  else if (arg.startsWith("--version")) version = value();
+  else if (arg.startsWith("--out")) out = value().replace(/\/+$/, "");
+  else if (arg.startsWith("--from")) from = value();
+  else if (arg === "-h" || arg === "--help") {
+    console.log(`usage: npx quran-madina-bundle [--layouts ${Object.keys(LAYOUT_STEMS).join(",")}] ` +
+      `[--out ${DEFAULT_OUT}] [--version ${own.version} | --from <folder>]`);
+    process.exit(0);
+  } else fail(`unknown option ${arg}`);
+}
+if (!existsSync("package.json")) fail("run this from your app's folder");
+
+let pkg;
+if (from) {
+  if (!existsSync(from)) fail(`no folder ${from}`);
+  console.log(`Reading ${from}`);
+  pkg = readFolder(from);
+} else {
+  const url = `https://registry.npmjs.org/quran-madina-html/-/quran-madina-html-${version}.tgz`;
+  console.log(`Downloading ${url}`);
+  const response = await fetch(url).catch((err) => fail(`download failed: ${err.message}`));
+  if (!response.ok) fail(`download failed: HTTP ${response.status}`);
+  pkg = readTarGz(Buffer.from(await response.arrayBuffer()));
+}
+
+let files;
+try {
+  files = selectBundle(pkg, layouts);
+} catch (err) {
+  fail(err.message);
+}
+rmSync(out, { recursive: true, force: true });
+let bytes = 0;
+for (const [path, data] of files) {
+  const target = join(out, path);
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, data);
+  bytes += data.length;
+}
+const base = `/${out.replace(/^public\/?/, "").replace(/^\/+/, "")}/`.replace(/\/+$/, "/");
+console.log(`Wrote ${files.size} files (${(bytes / 1048576).toFixed(1)} MB) to ${out}/ for ${layouts.join(", ")}.`);
+console.log("");
+console.log(out.startsWith("public/") || out === "public"
+  ? `Then: <QuranMadinaHtml bundled ... />${base === "/quran-madina/" ? "" : `  (or bundled="${base}")`}`
+  : `Serve ${out}/ from your app, then: <QuranMadinaHtml bundled="/<where it is served>/" ... />`);

package/bin/lib.mjs

@@ -0,0 +1,97 @@
+// Pure helpers for `quran-madina-bundle` (bin/bundle.mjs): read the quran-madina-html npm
+// package and pick the files an app needs to render offline. Same rules as the Flutter
+// package's bundler (flutter/lib/src/bundle.dart).
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { gunzipSync } from "node:zlib";
+
+/** The layouts the library ships, by the name `layout` takes, and their database folders. */
+export const LAYOUT_STEMS = { "1441H": "Madina-1441H", "1405H": "Madina-1405H", IndoPak: "IndoPak-15" };
+
+/** Where the bundle goes by default, under the app's public/ folder, and the URL it is served at. */
+export const DEFAULT_OUT = "public/quran-madina";
+export const DEFAULT_BASE = "/quran-madina/";
+
+/** The files of a tar archive, by path. Plain files only (ustar names with prefixes). */
+export function readTar(tar) {
+  const out = new Map();
+  const text = (start, length) => {
+    const raw = tar.subarray(start, start + length);
+    const end = raw.indexOf(0);
+    return Buffer.from(end < 0 ? raw : raw.subarray(0, end)).toString("utf8");
+  };
+  let pos = 0;
+  while (pos + 512 <= tar.length) {
+    if (tar.subarray(pos, pos + 512).every((b) => b === 0)) break; // end of archive
+    const name = text(pos, 100);
+    const sizeText = text(pos + 124, 12).trim();
+    const size = sizeText ? parseInt(sizeText, 8) : 0;
+    const type = tar[pos + 156];
+    const prefix = text(pos + 257, 6).startsWith("ustar") ? text(pos + 345, 155) : "";
+    const path = prefix ? `${prefix}/${name}` : name;
+    const start = pos + 512;
+    if (type === 0 || type === 0x30) out.set(path, Buffer.from(tar.subarray(start, start + size)));
+    pos = start + Math.ceil(size / 512) * 512;
+  }
+  return out;
+}
+
+/** The files of a .tgz (an npm package), by path. */
+export const readTarGz = (bytes) => readTar(gunzipSync(bytes));
+
+const BUNDLE_ROOTS = ["dist/", "assets/img/", "assets/db/v2/"];
+
+/**
+ * The files under `dir` (an unpacked package or a built checkout), laid out like an npm package:
+ * each path starts with `package/`. Only the folders a bundle draws from are read.
+ */
+export function readFolder(dir) {
+  const out = new Map();
+  const walk = (folder) => {
+    for (const entry of readdirSync(folder)) {
+      const full = join(folder, entry);
+      const path = relative(dir, full).split(sep).join("/");
+      if (statSync(full).isDirectory()) {
+        if (BUNDLE_ROOTS.some((root) => root.startsWith(`${path}/`) || path.startsWith(root))) walk(full);
+      } else if (BUNDLE_ROOTS.some((root) => path.startsWith(root))) {
+        out.set(`package/${path}`, readFileSync(full));
+      }
+    }
+  };
+  walk(dir);
+  return out;
+}
+
+/** The stem for a layout name, any case; null if the library has no such layout. */
+export function layoutStem(layout) {
+  const key = Object.keys(LAYOUT_STEMS).find((k) => k.toLowerCase() === String(layout).toLowerCase());
+  return key ? LAYOUT_STEMS[key] : null;
+}
+
+/**
+ * The files of the package (paths under `package/`) an app needs for `layouts`: the script, the
+ * CSS, the images, and each layout's sharded database and font. Result paths are relative to the
+ * bundle folder.
+ */
+export function selectBundle(pkg, layouts) {
+  const files = new Map();
+  for (const [path, data] of pkg) if (path.startsWith("package/")) files.set(path.slice(8), data);
+  const out = new Map();
+  const take = (path) => {
+    if (!files.has(path)) throw new Error(`${path} is missing from the package`);
+    out.set(path, files.get(path));
+  };
+  take("dist/quran-madina-html.min.js");
+  take("dist/quran-madina-html.min.css");
+  for (const path of files.keys()) if (path.startsWith("assets/img/")) take(path);
+  for (const layout of layouts) {
+    const stem = layoutStem(layout);
+    if (!stem) throw new Error(`unknown layout "${layout}" (use ${Object.keys(LAYOUT_STEMS).join(", ")})`);
+    const dir = `assets/db/v2/${stem}/`;
+    for (const path of files.keys()) if (path.startsWith(dir)) take(path);
+    const manifest = files.get(`${dir}manifest.json`);
+    if (!manifest) throw new Error(`${dir}manifest.json is missing from the package`);
+    take(JSON.parse(manifest.toString("utf8")).font_url);
+  }
+  return out;
+}

package/dist/index.cjs

@@ -29,6 +29,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.js
 var index_exports = {};
 __export(index_exports, {
+  BUNDLE_BASE: () => BUNDLE_BASE,
+  bundleUrls: () => bundleUrls,
   default: () => QuranMadinaHtml,
   loadQuranMadinaHtml: () => loadQuranMadinaHtml
 });
@@ -39,9 +41,16 @@ 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 BUNDLE_BASE = "/quran-madina/";
+function bundleUrls(bundled) {
+  let base = bundled === true ? BUNDLE_BASE : String(bundled);
+  if (!base.endsWith("/")) base += "/";
+  return { src: `${base}dist/quran-madina-html.min.js`, cdn: base };
+}
 var loaderPromise = null;
 function loadQuranMadinaHtml(opts = {}) {
-  const { src = DEFAULT_SRC, cdn = DEFAULT_CDN, layout, font, name, fontSize } = opts;
+  const { layout, font, name, fontSize, bundled } = opts;
+  const { src = DEFAULT_SRC, cdn = DEFAULT_CDN } = bundled ? bundleUrls(bundled) : opts;
   if (typeof window === "undefined" || typeof document === "undefined") {
     return Promise.resolve();
   }
@@ -87,6 +96,7 @@ function QuranMadinaHtml({
   font,
   name,
   fontSize,
+  bundled,
   className,
   style,
   ...rest
@@ -97,11 +107,11 @@ function QuranMadinaHtml({
   );
   (0, import_react.useEffect)(() => {
     let active = true;
-    loadQuranMadinaHtml({ src, cdn, layout, font, name, fontSize }).then(() => active && setReady(true)).catch((err) => console.error("[quran-madina-html]", err));
+    loadQuranMadinaHtml({ src, cdn, layout, font, name, fontSize, bundled }).then(() => active && setReady(true)).catch((err) => console.error("[quran-madina-html]", err));
     return () => {
       active = false;
     };
-  }, [src, cdn, layout, font, name, fontSize]);
+  }, [src, cdn, layout, font, name, fontSize, bundled]);
   (0, import_react.useEffect)(() => {
     const el = ref.current;
     if (!el) return;

package/dist/index.d.ts

@@ -16,6 +16,12 @@ export interface QuranMadinaHtmlLoaderOptions {
   name?: string;
   /** data-font-size in px (default 16). Any size works. */
   fontSize?: number | string;
+  /**
+   * Load the app's own copy of the library instead of unpkg, for offline use. Write it with
+   * `npx quran-madina-bundle` (default: public/quran-madina). `true` loads it from
+   * "/quran-madina/"; a string is the URL the bundle folder is served at. Overrides src and cdn.
+   */
+  bundled?: boolean | string;
 }
 
 export interface QuranMadinaHtmlProps
@@ -70,3 +76,9 @@ export function loadQuranMadinaHtml(
 
 declare const QuranMadinaHtml: React.FC<QuranMadinaHtmlProps>;
 export default QuranMadinaHtml;
+
+/** URL the default bundle folder (public/quran-madina) is served at: "/quran-madina/". */
+export declare const BUNDLE_BASE: string;
+
+/** The script URL and asset base for a bundled copy of the library (see `bundled`). */
+export declare function bundleUrls(bundled: true | string): { src: string; cdn: string };

package/dist/index.mjs

@@ -3,9 +3,16 @@ 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 BUNDLE_BASE = "/quran-madina/";
+function bundleUrls(bundled) {
+  let base = bundled === true ? BUNDLE_BASE : String(bundled);
+  if (!base.endsWith("/")) base += "/";
+  return { src: `${base}dist/quran-madina-html.min.js`, cdn: base };
+}
 var loaderPromise = null;
 function loadQuranMadinaHtml(opts = {}) {
-  const { src = DEFAULT_SRC, cdn = DEFAULT_CDN, layout, font, name, fontSize } = opts;
+  const { layout, font, name, fontSize, bundled } = opts;
+  const { src = DEFAULT_SRC, cdn = DEFAULT_CDN } = bundled ? bundleUrls(bundled) : opts;
   if (typeof window === "undefined" || typeof document === "undefined") {
     return Promise.resolve();
   }
@@ -51,6 +58,7 @@ function QuranMadinaHtml({
   font,
   name,
   fontSize,
+  bundled,
   className,
   style,
   ...rest
@@ -61,11 +69,11 @@ function QuranMadinaHtml({
   );
   useEffect(() => {
     let active = true;
-    loadQuranMadinaHtml({ src, cdn, layout, font, name, fontSize }).then(() => active && setReady(true)).catch((err) => console.error("[quran-madina-html]", err));
+    loadQuranMadinaHtml({ src, cdn, layout, font, name, fontSize, bundled }).then(() => active && setReady(true)).catch((err) => console.error("[quran-madina-html]", err));
     return () => {
       active = false;
     };
-  }, [src, cdn, layout, font, name, fontSize]);
+  }, [src, cdn, layout, font, name, fontSize, bundled]);
   useEffect(() => {
     const el = ref.current;
     if (!el) return;
@@ -97,6 +105,8 @@ function QuranMadinaHtml({
   return React.createElement(TAG, { ref, class: className, style, ...rest });
 }
 export {
+  BUNDLE_BASE,
+  bundleUrls,
   QuranMadinaHtml as default,
   loadQuranMadinaHtml
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tarekeldeeb/quran-madina-react",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "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",
@@ -15,7 +15,9 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "bin",
+    "README.md",
+    "LICENSE.md"
   ],
   "sideEffects": false,
   "scripts": {
@@ -45,7 +47,7 @@
     "quran-madina-html"
   ],
   "author": "Tarek Eldeeb",
-  "license": "ISC",
+  "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/tarekeldeeb/quran-madina-html.git",
@@ -54,5 +56,8 @@
   "bugs": {
     "url": "https://github.com/tarekeldeeb/quran-madina-html/issues"
   },
-  "homepage": "https://github.com/tarekeldeeb/quran-madina-html/tree/main/react#readme"
+  "homepage": "https://github.com/tarekeldeeb/quran-madina-html/tree/main/react#readme",
+  "bin": {
+    "quran-madina-bundle": "bin/bundle.mjs"
+  }
 }