quadraui 0.6.1

//! Bundled codicon icon font.
//!
//! Every GUI backend paints its built-in chrome glyphs — tree
//! expand/collapse chevrons, tab dirty/close marks, the context-menu
//! submenu arrow, the data-table sort arrow — as codepoints from
//! Microsoft's codicon font, the vector icons VS Code's own chrome uses.
//! TUI paints plain Unicode characters (`▾`/`▸`/`×`/`●`/`▶`/`▼`) in the
//! same places. An app's own [`crate::Icon`] glyphs are a separate path:
//! they need a Nerd Font, which is not this crate's to bundle (it is
//! enormous and GPL-licensed), so the host supplies that font itself.
//!
//! codicon is small (≈150 KiB), narrowly scoped (chrome glyphs, not a
//! general-purpose icon set) and CC-BY-4.0 — licence terms this crate
//! can embed directly. [`FONT_BYTES`] is that font; every GUI backend
//! self-registers it once, unconditionally, via
//! [`crate::Backend::register_font_from_memory`]'s per-backend
//! implementation, so the glyphs in this module paint correctly with no
//! app configuration — see each backend's `codicon`-registration call
//! site (`GtkBackend::new`, `MacBackend::new`, `WinBackend::new`) for
//! where that happens.
//!
//! # Licence
//!
//! <https://github.com/microsoft/vscode-codicons>, Creative Commons
//! Attribution 4.0 International (CC-BY-4.0). Full licence text ships at
//! `quadraui/assets/CODICON_LICENSE`; see the crate-root `README.md`'s
//! "Third-party assets" section for the shipped attribution.
//!
//! # Why these codepoints
//!
//! Every constant below is a codicon Private-Use-Area codepoint, taken
//! from codicon 0.0.46's own `codicon.css` name → codepoint mapping.
//! Nerd Fonts patches codicon's own glyphs into the *same* PUA range
//! (`U+EA60`–`U+EC1E`) rather than a disjoint one, so an app-supplied
//! Nerd Font can legitimately define a codepoint this module also
//! uses. What keeps that from shadowing the app's own glyph is
//! ordering, not code-space separation: every backend's codicon
//! registration call site (`GtkBackend::new`, `MacBackend::new`,
//! `WinBackend::new`) appends `FONT_FAMILY` *last* in its fallback
//! chain — GTK's family list, macOS's cascade list, Windows'
//! `AddMapping` order — so an app-supplied font earlier in that same
//! chain always wins any overlapping codepoint, and codicon only
//! resolves a codepoint nothing else in the chain claimed.

// `--features win` type-checks `win::*` on every host, but the WinAPI
// call sites that register the font and paint the tab close/dirty glyphs
// are `target_os = "windows"`-only, so a non-Windows `win`-only build
// compiles these items with no reader. The `allow(dead_code)` below is
// scoped to exactly that build; every real GUI build still lints them.

/// Raw TTF bytes of the bundled codicon font (codicon 0.0.46-24,
/// upstream: <https://github.com/microsoft/vscode-codicons>). Registered
/// once per process by each GUI backend via
/// [`crate::Backend::register_font_from_memory`]'s own implementation —
/// see this module's doc for why that happens unconditionally.
#[cfg_attr(
    not(any(
        feature = "gtk",
        all(feature = "macos", target_os = "macos"),
        all(feature = "win", target_os = "windows")
    )),
    allow(dead_code)
)]
pub(crate) const FONT_BYTES: &[u8] = include_bytes!("../assets/codicon.ttf");

/// The font family name every backend registers [`FONT_BYTES`] under,
/// and appends to its Nerd-Font-glyph fallback chain (GTK's
/// `with_nerd_font_fallback`, macOS's `CTFont` cascade list, Windows'
/// `IDWriteFontFallback`) so a codicon codepoint resolves regardless of
/// whether — or what — the host app has configured its own Nerd Font
/// fallback to. Matches the family name baked into the font's own
/// `name` table (confirmed via `fc-scan --format '%{family}\n'`), so a
/// backend that resolves by name against the font it just registered
/// needs no translation step.
#[cfg_attr(
    not(any(
        feature = "gtk",
        all(feature = "macos", target_os = "macos"),
        all(feature = "win", target_os = "windows")
    )),
    allow(dead_code)
)]
pub(crate) const FONT_FAMILY: &str = "codicon";

/// Branch row expanded — `codicon-chevron-down`, the GUI counterpart of
/// the plain `▾` [`crate::TreeStyle::chevron_expanded`] default paints on
/// TUI.
pub(crate) const CHEVRON_DOWN: char = '\u{eab4}';

/// Branch row collapsed — `codicon-chevron-right`, the GUI counterpart
/// of the plain `▸` [`crate::TreeStyle::chevron_collapsed`] default paints
/// on TUI.
/// Also used for the context-menu submenu pull-right affordance
/// (`\u{25b6}` on TUI) — codicon has no separate "submenu" glyph, and
/// VS Code's own context menu reuses this exact chevron for both.
pub(crate) const CHEVRON_RIGHT: char = '\u{eab6}';

/// Command-centre back-navigation arrow — `codicon-chevron-left`, the
/// GUI counterpart of the plain `◀` a text-only backend paints in the
/// same place. Sits immediately before [`CHEVRON_RIGHT`] in codicon's
/// own PUA range (`chevron-down`, `chevron-left`, `chevron-right` are
/// consecutive codepoints in codicon 0.0.46's `codicon.css`).
#[cfg_attr(not(all(feature = "macos", target_os = "macos")), allow(dead_code))]
pub(crate) const CHEVRON_LEFT: char = '\u{eab5}';

/// Command-centre search-box magnifier — `codicon-search`, painted
/// small and dim ahead of the search label on GUI backends. TUI's
/// search box has no separate icon glyph, just `[`/`]` brackets around
/// the label.
#[cfg_attr(not(all(feature = "macos", target_os = "macos")), allow(dead_code))]
pub(crate) const SEARCH: char = '\u{ea6d}';

/// Checked context-menu item indicator — `codicon-check` (TUI paints a
/// plain `✓`).
#[cfg_attr(
    not(any(
        feature = "gtk",
        all(feature = "macos", target_os = "macos"),
        all(feature = "win", target_os = "windows")
    )),
    allow(dead_code)
)]
pub(crate) const CHECK: char = '\u{eab2}';

/// Tab close button — `codicon-close` (TUI paints a plain `×`).
#[cfg_attr(
    not(any(
        feature = "gtk",
        all(feature = "macos", target_os = "macos"),
        all(feature = "win", target_os = "windows")
    )),
    allow(dead_code)
)]
pub(crate) const CLOSE: char = '\u{ea76}';

/// Tab dirty indicator (shown instead of the close glyph until
/// hovered) — `codicon-circle-filled` (TUI paints a plain `●`).
#[cfg_attr(
    not(any(
        feature = "gtk",
        all(feature = "macos", target_os = "macos"),
        all(feature = "win", target_os = "windows")
    )),
    allow(dead_code)
)]
pub(crate) const DIRTY: char = '\u{ea71}';

/// Sort-ascending column-header indicator — `codicon-triangle-up`
/// (TUI paints a plain `▲`). Painted by every GUI data table: GTK's
/// own rasteriser (`gtk::data_table`) and the shared
/// `primitives::data_table::native_surface_paint` path macOS and
/// Win-GUI both go through.
pub(crate) const SORT_ASCENDING: char = '\u{eb71}';

/// Sort-descending column-header indicator — `codicon-triangle-down`
/// (TUI paints a plain `▼`). Painted by every GUI data table: GTK's
/// own rasteriser (`gtk::data_table`) and the shared
/// `primitives::data_table::native_surface_paint` path macOS and
/// Win-GUI both go through.
pub(crate) const SORT_DESCENDING: char = '\u{eb6e}';

/// Find/replace "Match Case" toggle — `codicon-case-sensitive` (TUI
/// paints the plain glyph pair `Aa`). Painted by the shared
/// `primitives::find_replace::native_surface_paint` path every pixel
/// backend (GTK, macOS, Win-GUI) goes through.
#[cfg_attr(
    not(any(
        feature = "gtk",
        all(feature = "macos", target_os = "macos"),
        all(feature = "win", target_os = "windows")
    )),
    allow(dead_code)
)]
pub(crate) const CASE_SENSITIVE: char = '\u{eab1}';

/// Find/replace "Match Whole Word" toggle — `codicon-whole-word` (TUI
/// paints the plain glyph pair `ab`). Painted by the shared
/// `primitives::find_replace::native_surface_paint` path every pixel
/// backend (GTK, macOS, Win-GUI) goes through.
#[cfg_attr(
    not(any(
        feature = "gtk",
        all(feature = "macos", target_os = "macos"),
        all(feature = "win", target_os = "windows")
    )),
    allow(dead_code)
)]
pub(crate) const WHOLE_WORD: char = '\u{eb7e}';

/// Find/replace "Use Regular Expression" toggle — `codicon-regex`
/// (TUI paints the plain glyph pair `.*`). Painted by the shared
/// `primitives::find_replace::native_surface_paint` path every pixel
/// backend (GTK, macOS, Win-GUI) goes through.
#[cfg_attr(
    not(any(
        feature = "gtk",
        all(feature = "macos", target_os = "macos"),
        all(feature = "win", target_os = "windows")
    )),
    allow(dead_code)
)]
pub(crate) const REGEX: char = '\u{eb38}';

/// Replace-row "Preserve Case" toggle — `codicon-preserve-case` (TUI
/// paints the plain glyph pair `AB`). Painted by the shared
/// `primitives::find_replace::native_surface_paint` path every pixel
/// backend (GTK, macOS, Win-GUI) goes through.
#[cfg_attr(
    not(any(
        feature = "gtk",
        all(feature = "macos", target_os = "macos"),
        all(feature = "win", target_os = "windows")
    )),
    allow(dead_code)
)]
pub(crate) const PRESERVE_CASE: char = '\u{eb2e}';

#[cfg(test)]
mod tests {
    use super::*;

    /// `FONT_BYTES` must be a real sfnt (TrueType/OpenType) font, not a
    /// corrupted or truncated asset — checked via the sfnt version tag
    /// every TrueType font starts with (`0x00010000`), the same
    /// first-four-bytes check `fc-scan`/FreeType itself uses to decide
    /// whether a file is even worth parsing further.
    #[test]
    fn font_bytes_is_a_real_sfnt_font() {
        assert!(
            FONT_BYTES.len() > 1024,
            "codicon.ttf looks truncated: {} bytes",
            FONT_BYTES.len()
        );
        assert_eq!(
            &FONT_BYTES[0..4],
            &[0x00, 0x01, 0x00, 0x00],
            "codicon.ttf's first four bytes must be the sfnt version tag"
        );
    }

    /// Every glyph constant is a distinct codepoint inside the bundled
    /// font's own PUA coverage (`U+EA60`–`U+ECE7`, the actual `cmap`
    /// range `codicon.ttf` ships — wider than the `codicon.css` name →
    /// codepoint mapping this module's constants are drawn from, since
    /// the font includes glyphs no released `codicon.css` version names
    /// yet) — catches a transposed digit copied from `codicon.css`
    /// resolving to some other PUA glyph (or no glyph at all) instead
    /// of the intended one.
    #[test]
    fn glyph_constants_are_distinct_and_in_codicons_pua_block() {
        let glyphs = [
            CHEVRON_DOWN,
            CHEVRON_RIGHT,
            CHEVRON_LEFT,
            SEARCH,
            CHECK,
            CLOSE,
            DIRTY,
            SORT_ASCENDING,
            SORT_DESCENDING,
            CASE_SENSITIVE,
            WHOLE_WORD,
            REGEX,
            PRESERVE_CASE,
        ];
        for g in glyphs {
            assert!(
                ('\u{ea60}'..='\u{ece7}').contains(&g),
                "{g:?} (U+{:04X}) is outside the bundled font's PUA coverage",
                g as u32
            );
        }
        let mut seen = std::collections::HashSet::new();
        for g in glyphs {
            assert!(seen.insert(g), "duplicate glyph constant: {g:?}");
        }
    }

    /// Falling inside the PUA numeric range (the test above) only rules
    /// out a wildly wrong codepoint — it does not catch a transposed
    /// digit that lands on some *other*, unmapped-but-in-range PUA
    /// codepoint `codicon.ttf` has no glyph for. This checks the actual
    /// `cmap` table: every glyph constant must resolve to a non-`.notdef`
    /// (non-zero) glyph ID, so a future addition that compiles and
    /// passes the range check can still be caught here if it names a
    /// codepoint the font doesn't define.
    #[test]
    fn glyph_constants_have_a_real_glyph_in_the_bundled_fonts_cmap() {
        let glyphs = [
            CHEVRON_DOWN,
            CHEVRON_RIGHT,
            CHEVRON_LEFT,
            SEARCH,
            CHECK,
            CLOSE,
            DIRTY,
            SORT_ASCENDING,
            SORT_DESCENDING,
            CASE_SENSITIVE,
            WHOLE_WORD,
            REGEX,
            PRESERVE_CASE,
        ];
        for g in glyphs {
            let glyph_id = cmap_glyph_id(FONT_BYTES, g as u32)
                .unwrap_or_else(|| panic!("codicon.ttf's cmap table could not be parsed at all"));
            assert_ne!(
                glyph_id, 0,
                "{g:?} (U+{:04X}) falls inside the PUA numeric range but has no glyph \
                 mapped in codicon.ttf's own cmap table — likely a transposed digit \
                 landing on an unmapped codepoint",
                g as u32
            );
        }
    }

    /// Look up a Unicode codepoint's glyph ID in an sfnt's `cmap` table —
    /// just enough of
    /// <https://learn.microsoft.com/en-us/typography/opentype/spec/cmap>
    /// to answer
    /// [`glyph_constants_have_a_real_glyph_in_the_bundled_fonts_cmap`]
    /// without a font-parsing dependency. Supports the two subtable
    /// formats a Unicode `cmap` subtable realistically uses — format 4
    /// (segment mapping, the common case for a BMP-only font) and
    /// format 12 (segmented coverage, used by fonts that map codepoints
    /// outside the BMP; included for robustness even though
    /// `codicon.ttf`'s own PUA range fits inside the BMP). Returns `0`
    /// (the `.notdef` glyph — "not mapped") when the codepoint isn't
    /// covered, matching how cmap readers conventionally report a miss;
    /// returns `None` only when the table itself is missing or
    /// malformed.
    fn cmap_glyph_id(bytes: &[u8], codepoint: u32) -> Option<u32> {
        let num_tables = u16::from_be_bytes(bytes.get(4..6)?.try_into().ok()?) as usize;
        let records_start = 12;
        let mut cmap_offset = None;
        for i in 0..num_tables {
            let rec = records_start + i * 16;
            let tag = bytes.get(rec..rec + 4)?;
            if tag == b"cmap" {
                let offset =
                    u32::from_be_bytes(bytes.get(rec + 8..rec + 12)?.try_into().ok()?) as usize;
                cmap_offset = Some(offset);
                break;
            }
        }
        let cmap = cmap_offset?;
        let num_subtables =
            u16::from_be_bytes(bytes.get(cmap + 2..cmap + 4)?.try_into().ok()?) as usize;
        let mut best_subtable_offset = None;
        for i in 0..num_subtables {
            let rec = cmap + 4 + i * 8;
            let platform_id = u16::from_be_bytes(bytes.get(rec..rec + 2)?.try_into().ok()?);
            let encoding_id = u16::from_be_bytes(bytes.get(rec + 2..rec + 4)?.try_into().ok()?);
            let offset = u32::from_be_bytes(bytes.get(rec + 4..rec + 8)?.try_into().ok()?) as usize;
            // Prefer Windows Unicode full-repertoire (3,10) over Windows
            // Unicode BMP (3,1) — the two encodings an OpenType font's
            // Unicode cmap actually uses.
            let is_better = match (platform_id, encoding_id) {
                (3, 10) => true,
                (3, 1) if best_subtable_offset.is_none() => true,
                _ => false,
            };
            if is_better {
                best_subtable_offset = Some(cmap + offset);
            }
        }
        let sub = best_subtable_offset?;
        let format = u16::from_be_bytes(bytes.get(sub..sub + 2)?.try_into().ok()?);
        match format {
            4 => cmap_format4_glyph_id(bytes, sub, codepoint),
            12 => cmap_format12_glyph_id(bytes, sub, codepoint),
            _ => None,
        }
    }

    /// Format-4 (segment mapping to delta values) `cmap` subtable
    /// lookup — see [`cmap_glyph_id`]'s doc for why this format matters.
    fn cmap_format4_glyph_id(bytes: &[u8], sub: usize, codepoint: u32) -> Option<u32> {
        if codepoint > 0xFFFF {
            return Some(0);
        }
        let c = codepoint as u16;
        let seg_count_x2 =
            u16::from_be_bytes(bytes.get(sub + 6..sub + 8)?.try_into().ok()?) as usize;
        let seg_count = seg_count_x2 / 2;
        let end_codes_start = sub + 14;
        let start_codes_start = end_codes_start + seg_count_x2 + 2; // +2 reservedPad
        let id_deltas_start = start_codes_start + seg_count_x2;
        let id_range_offsets_start = id_deltas_start + seg_count_x2;
        for i in 0..seg_count {
            let end_code = u16::from_be_bytes(
                bytes
                    .get(end_codes_start + i * 2..end_codes_start + i * 2 + 2)?
                    .try_into()
                    .ok()?,
            );
            if c > end_code {
                continue;
            }
            let start_code = u16::from_be_bytes(
                bytes
                    .get(start_codes_start + i * 2..start_codes_start + i * 2 + 2)?
                    .try_into()
                    .ok()?,
            );
            if c < start_code {
                return Some(0);
            }
            let id_delta = i16::from_be_bytes(
                bytes
                    .get(id_deltas_start + i * 2..id_deltas_start + i * 2 + 2)?
                    .try_into()
                    .ok()?,
            );
            let id_range_offset_pos = id_range_offsets_start + i * 2;
            let id_range_offset = u16::from_be_bytes(
                bytes
                    .get(id_range_offset_pos..id_range_offset_pos + 2)?
                    .try_into()
                    .ok()?,
            );
            if id_range_offset == 0 {
                return Some(((c as i32 + id_delta as i32) as u16) as u32);
            }
            let glyph_index_addr =
                id_range_offset_pos + id_range_offset as usize + 2 * (c - start_code) as usize;
            let raw_glyph_id = u16::from_be_bytes(
                bytes
                    .get(glyph_index_addr..glyph_index_addr + 2)?
                    .try_into()
                    .ok()?,
            );
            if raw_glyph_id == 0 {
                return Some(0);
            }
            return Some(((raw_glyph_id as i32 + id_delta as i32) as u16) as u32);
        }
        Some(0)
    }

    /// Format-12 (segmented coverage) `cmap` subtable lookup — see
    /// [`cmap_glyph_id`]'s doc for why this format is also supported.
    fn cmap_format12_glyph_id(bytes: &[u8], sub: usize, codepoint: u32) -> Option<u32> {
        let num_groups =
            u32::from_be_bytes(bytes.get(sub + 12..sub + 16)?.try_into().ok()?) as usize;
        let groups_start = sub + 16;
        for i in 0..num_groups {
            let rec = groups_start + i * 12;
            let start_char = u32::from_be_bytes(bytes.get(rec..rec + 4)?.try_into().ok()?);
            let end_char = u32::from_be_bytes(bytes.get(rec + 4..rec + 8)?.try_into().ok()?);
            if codepoint < start_char || codepoint > end_char {
                continue;
            }
            let start_glyph = u32::from_be_bytes(bytes.get(rec + 8..rec + 12)?.try_into().ok()?);
            return Some(start_glyph + (codepoint - start_char));
        }
        Some(0)
    }

    #[test]
    fn font_family_matches_the_bundled_fonts_own_name_table() {
        // Keeps `FONT_FAMILY` honest against a future font-asset bump:
        // if `codicon.ttf` is ever swapped for a build whose `name`
        // table reports a different family, a registration call keyed
        // on the literal `"codicon"` string would silently stop
        // resolving. No font-parsing dependency is pulled in for this —
        // `sfnt_family_name` below reads just enough of the `name`
        // table (Windows platform, nameID 1) to answer this one
        // question, rather than asserting the constant against its own
        // literal.
        let parsed = sfnt_family_name(FONT_BYTES)
            .expect("codicon.ttf must carry a Windows-platform Font Family (nameID 1) record");
        assert_eq!(
            parsed, FONT_FAMILY,
            "FONT_FAMILY must match the bundled font's own name table"
        );
    }

    /// Read the Windows-platform (platformID 3) Font Family name
    /// (nameID 1) out of an sfnt's `name` table — just enough of
    /// <https://learn.microsoft.com/en-us/typography/opentype/spec/name>
    /// to answer [`font_family_matches_the_bundled_fonts_own_name_table`]
    /// without a font-parsing dependency. Returns `None` if the font has
    /// no `name` table, no matching record, or either is malformed —
    /// every `None` path is deliberately a plain fallback rather than a
    /// panic, since this is test-only parsing of a known-good asset, not
    /// a path any real paint call goes through.
    fn sfnt_family_name(bytes: &[u8]) -> Option<String> {
        let num_tables = u16::from_be_bytes(bytes.get(4..6)?.try_into().ok()?) as usize;
        let records_start = 12;
        let mut name_table_offset = None;
        for i in 0..num_tables {
            let rec = records_start + i * 16;
            let tag = bytes.get(rec..rec + 4)?;
            if tag == b"name" {
                let offset =
                    u32::from_be_bytes(bytes.get(rec + 8..rec + 12)?.try_into().ok()?) as usize;
                name_table_offset = Some(offset);
                break;
            }
        }
        let name_table = name_table_offset?;
        let count = u16::from_be_bytes(bytes.get(name_table + 2..name_table + 4)?.try_into().ok()?)
            as usize;
        let storage_offset =
            u16::from_be_bytes(bytes.get(name_table + 4..name_table + 6)?.try_into().ok()?)
                as usize;
        let records_start = name_table + 6;
        for i in 0..count {
            let rec = records_start + i * 12;
            let platform_id = u16::from_be_bytes(bytes.get(rec..rec + 2)?.try_into().ok()?);
            let name_id = u16::from_be_bytes(bytes.get(rec + 6..rec + 8)?.try_into().ok()?);
            if platform_id != 3 || name_id != 1 {
                continue;
            }
            let length =
                u16::from_be_bytes(bytes.get(rec + 8..rec + 10)?.try_into().ok()?) as usize;
            let str_offset =
                u16::from_be_bytes(bytes.get(rec + 10..rec + 12)?.try_into().ok()?) as usize;
            let start = name_table + storage_offset + str_offset;
            let raw = bytes.get(start..start + length)?;
            // Windows-platform name records are UTF-16BE.
            let units: Vec<u16> = raw
                .chunks_exact(2)
                .map(|c| u16::from_be_bytes([c[0], c[1]]))
                .collect();
            return String::from_utf16(&units).ok();
        }
        None
    }
}