@abumalick/arabic-symbols

Render Islamic honorific abbreviations (عز وجل, ﷺ, رحمه الله, …) as proper single-glyph honorific symbols, using the KFGQPC Arabic Symbols 01 font.

Framework-agnostic core (no DOM) + a ready-made HTML helper + the font and CSS.

Why

Content often writes honorifics as short abbreviations in parentheses — (زج) for عز وجل, (سبح) for سبحانه وتعالى, and so on. This package turns those tokens into the calligraphic honorific glyph, rendered from the KFGQPC symbols font at its native Private-Use-Area codepoints (U+F062–U+F076). Because the glyphs live in the PUA, a missing font degrades to a harmless placeholder — never a wrong letter — and no font modification is required.

Install

pnpm add @abumalick/arabic-symbols

Usage

import { symbolsToHtml, tokenizeSymbols, SYMBOLS } from "@abumalick/arabic-symbols";
import "@abumalick/arabic-symbols/style.css"; // registers @font-face + .arabic-symbol

// HTML string helper (does NOT escape surrounding text — feed it trusted HTML):
symbolsToHtml("من فضل الله (زج) العظيم");
// => 'من فضل الله <span class="arabic-symbol"></span> العظيم'

// Restrict to a specific alias set (alias -> symbol key):
symbolsToHtml("الله (زج)", { aliases: { "زج": "azzaWaJalla" } });

// Aliases can be ANY string (e.g. Latin letters for a French/AZERTY workflow),
// and the delimiter is configurable per product via `wrap` (default ["(", ")"]):
symbolsToHtml("Allah [A] great", {
  aliases: { A: "azzaWaJalla", Z: "subhanahuWaTaala" },
  wrap: ["[", "]"], // author content as [A], [Z]
});

// Framework-agnostic tokens (render however you like — Svelte, Vue, RN, …):
tokenizeSymbols("الله (زج)");
// => [{ type: "text", value: "الله " },
//     { type: "symbol", char: "", key: "azzaWaJalla", phrase: "عز وجل", match: "(زج)" }]

API

• SYMBOLS — the canonical honorific data (readonly array of ArabicSymbol).
• symbolChar(key) — the PUA character for a honorific key (throws if unknown).
• symbolByAlias(alias) — resolve an abbreviation to its ArabicSymbol.
• tokenizeSymbols(text, opts?) — segment text into text/symbol tokens.
• replaceSymbols(text, render, opts?) — replace matched tokens with a custom string.
• symbolsToHtml(text, opts?) — replace matched tokens with <span class="arabic-symbol">…</span>.

Options (opts):

• aliases — an alias -> key map. When provided, only those aliases are matched; otherwise all built-in aliases are used. Aliases can be any string (Arabic tokens like زج, or Latin letters like A for non-Arabic keyboards).
• wrap — the [open, close] delimiter pair around an alias. Defaults to ["(", ")"] (matches (زج)). Set it per product to change the authoring convention, e.g. ["[", "]"] matches [A]. Both delimiters are literal strings (regex-escaped).

Symbols

| key | codepoint | phrase | default aliases | |---|---|---|---| | azzaWaJalla | U+F062 | عز وجل | زج, عزوجل | | subhanahuWaTaala | U+F063 | سبحانه وتعالى | سبح | | jallaJalaluhu | U+F064 | جل جلاله | جج | | jallaWaAla | U+F065 | جل وعلا | جع | | tabarakaWaTaala | U+F066 | تبارك وتعالى | تب | | sallallahuAlayhiWaSallam | U+F067 | صلى الله عليه وسلم | صلعم | | radiyallahuAnhu / Anha / Anhum / Anhuma / Anhunna | U+F068–F06C | رضي الله عنه … | رضه, رضها, رضهم, رضهما, رضهن | | alayhiSalatuWasSalam | U+F06D | عليه الصلاة والسلام | عصس | | alayhiSalam / alayhimSalam / alayhimaSalam | U+F06E, F070, F071 | عليه/عليهم/عليهما السلام | عس, عهم, عهما | | rahimahullah / rahimahallah / rahimahumaAllah / rahimahumullah / rahimahunnaAllah | U+F072–F076 | رحمه الله … | رح, رحها, رحهما, رحهم, رحهن |

To verify the glyph↔phrase readings yourself: node scripts/glyph-sheet.mjs then open scripts/glyphs.html in a browser.

License

SPDX: MIT AND LicenseRef-KFGQPC-Fonts

• Package code: MIT — see LICENSE.
• Bundled font (font/): "KFGQPC Arabic Symbols 01", property of the King Fahd Glorious Qur'an Printing Complex, redistributed unmodified under its own license — see LICENSES/LicenseRef-KFGQPC-Fonts.txt, font/LICENSE, and NOTICE. The KFGQPC terms permit free redistribution as-is but prohibit modifying the font.