/* ============================================================================
   Malakwal.pk — the Urdu (Nastaliq) typeface
   ============================================================================

   This file declares ONE font face — Jameel Noori Nastaleeq — and nothing
   else. It is loaded by includes/header.php on every page, because a page
   cannot know in advance whether the article it is about to render is Urdu.

   ----------------------------------------------------------------------------
   WHY THIS IS A SEPARATE FILE, AND A LOCAL @font-face
   ----------------------------------------------------------------------------

   Every other font on this site is served by Google Fonts from
   includes/appearance.php, which emits a <link> to the css2 endpoint. That
   mechanism cannot serve this font: Jameel Noori Nastaleeq is not on Google
   Fonts, and the endpoint answers 400 for it. It is a locally distributed
   Pakistani font, so it is self-hosted here.

   That also means the file must be UPLOADED — it cannot be fetched at build
   time, and nothing in this repository invents a copy of it. See the note in
   assets/fonts/README.md.

   ----------------------------------------------------------------------------
   WHY THE FALLBACK CHAIN IS WRITTEN OUT IN FULL
   ----------------------------------------------------------------------------

   A @font-face whose src file is MISSING is not an error the browser reports.
   It silently contributes no glyphs, and the text renders in whatever the stack
   falls back to. That is the behaviour relied on here: until the .woff2 is
   uploaded, every element asking for "Jameel Noori Nastaleeq" gets the next
   entry in the stack instead, and the page still reads correctly.

   The stack, in order, and why each entry is there:

     'Jameel Noori Nastaleeq'   the face declared below, and the one the site
                                is configured for
     'Noto Nastaliq Urdu'       Google's Nastaliq face. Present on Android and
                                increasingly on desktop; a genuine Nastaliq, so
                                the SHAPE of the script is right even when the
                                letterforms are not Jameel Noori's
     'Nafees Web Naskh'         a common Pakistani system Naskh; a different
                                style but the correct script, which is better
                                than a Latin font showing tofu boxes
     serif                      the last resort. An Arabic-script glyph missing
                                from every named face falls through here rather
                                than rendering as boxes.

   ----------------------------------------------------------------------------
   WHY font-display: swap AND NOT block
   ----------------------------------------------------------------------------

   'block' would hide the text for up to three seconds while the font loads,
   which on a local news page is a blank article. 'swap' shows the fallback
   immediately and re-renders when the real face arrives. A flash of a slightly
   different Nastaliq is a far smaller cost than a flash of nothing.

   ----------------------------------------------------------------------------
   WHY size-adjust IS NOT USED
   ----------------------------------------------------------------------------

   Nastaliq has a much taller line box than a Latin face — the script slopes
   down and to the left, and its descenders and connectors need room. Rather
   than fight that with size-adjust, the line-height for Urdu content is set in
   the News module's own CSS, where it can be tuned per size. Adjusting the face
   itself would shrink the text relative to the English beside it on any page
   that mixes the two.

   ============================================================================ */

@font-face {
    font-family: 'Jameel Noori Nastaleeq';
    font-style: normal;
    font-weight: 400;
    font-display: swap;

    /*
     * woff2 first, then woff, then the raw ttf.
     *
     * Each entry is a separate URL the browser tries in order. A browser that
     * cannot use woff2 falls to woff; one that cannot use either falls to the
     * ttf, which every browser can read but which is two to three times the
     * size. This means the site works with whichever of the three files has
     * been uploaded, and speeds up automatically once the woff2 is there.
     *
     * The ttf entry carries the format hint 'truetype' so a browser that
     * understands the hint does not download a woff2 it cannot parse.
     */
    src:
        url('../fonts/JameelNooriNastaleeq.woff2') format('woff2'),
        url('../fonts/JameelNooriNastaleeq.woff')  format('woff'),
        url('../fonts/JameelNooriNastaleeq.ttf')   format('truetype');

    /*
     * The unicode-range is the Arabic block plus the two joiners Urdu needs.
     *
     * This is not an optimisation for its own sake — it is what keeps the two
     * faces apart. A browser only downloads this file when the page actually
     * contains a character in the range, so an English article costs nothing.
     * It also means mixed text — an Urdu headline quoting a Latin name — uses
     * this face for the Urdu and the site's Latin face for the name, because
     * the Latin characters fall outside the range.
     *
     * \200C and \200D are ZWNJ and ZWJ. They are zero-width and invisible, but
     * they change how a Nastaliq letter joins to its neighbour, so they must be
     * claimed by the face that renders the surrounding text.
     */
    unicode-range:
        U+0600-06FF,
        U+0750-077F,
        U+08A0-08FF,
        U+FB50-FDFF,
        U+FE70-FEFF,
        U+200C-200D;
}

/*
 * ----------------------------------------------------------------------------
 * The utility class
 * ----------------------------------------------------------------------------
 *
 * Applied by the News templates to the container of an Urdu article, and by the
 * admin editor's Urdu body field so an editor sees what he is writing in the
 * face it will be published in.
 *
 * Note the absence of !important, and that this is a plain class rather than an
 * attribute selector. It loses to nothing it should lose to: the site's global
 * `*, *::before, *::after { font-family: var(--font-family) !important }` rule
 * in main.css is the problem, and it is answered by a matching !important on
 * the more specific `.is-urdu` selector in the News stylesheet rather than by
 * a hammer here. See that file for the carve-out.
 *
 * font-family here is a STACK, matching the @font-face fallbacks above, so the
 * name in the CSS and the name in the declaration can never disagree.
 */
.is-urdu,
[lang="ur"] {
    font-family:
        'Jameel Noori Nastaleeq',
        'Noto Nastaliq Urdu',
        'Nafees Web Naskh',
        serif;
}

/*
 * The Latin face, for a run of English inside an Urdu article.
 *
 * An article title in Urdu often contains a Latin proper noun, and Nastaliq's
 * Latin glyphs — where it has any at all — are not good. Marking the run lets
 * the template drop back to the site's own face for those words without
 * switching direction.
 */
.is-latin {
    font-family: var(--font-family, sans-serif);
}
