system_fonts/

lib.rs

//! System font discovery and locale-based preset selection.
//!
//! This crate provides a small API for:
//! - Detecting the current system locale
//! - Mapping a locale to a `FontRegion`
//! - Resolving a prioritized list of installed system fonts using `fontdb`
//!
//! The output (`FoundFont`) is designed to be consumed by UI toolkits (e.g. `egui_system_fonts`),
//! where the caller loads the font bytes and registers them into the UI font system.
//!
//! # Quick start
//!
//! Resolve fonts from the current system locale:
//!
//! ```no_run
//! use system_fonts::{find_for_system_locale, FontStyle};
//!
//! let (_locale, region, fonts) = find_for_system_locale(FontStyle::Sans);
//! println!("region={region:?}, fonts={}", fonts.len());
//! ```
//!
//! Force a locale or region policy manually:
//!
//! ```no_run
//! use system_fonts::{find_for_locale, FontStyle};
//!
//! let (region, fonts) = find_for_locale("ko-KR", FontStyle::Sans);
//! println!("region={region:?}, fonts={}", fonts.len());
//! ```
//!
//! # Notes
//! - Font resolution is best-effort: unknown families are skipped.
//! - The internal font database is cached (loaded once per process).
//! - `FoundFont::key` is unique within a single run; do not persist it across runs.
use std::collections::HashSet;
use std::path::PathBuf;
use std::sync::{Arc, OnceLock};

use fontdb::{Database, Family, Query, Source};

/// Font preference used when selecting system fonts.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FontStyle {
    Sans,
    Serif,
}

/// Writing system/locale region used to decide fallback priority.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FontRegion {
    Korean,
    Japanese,
    SimplifiedChinese,
    TraditionalChinese,
    Cyrillic,
    Latin,
    Unknown,
}

/// A preset represents a prioritized group of candidate font families.
#[non_exhaustive]
#[derive(Clone, Debug)]
pub enum FontPreset {
    Latin,
    Korean,
    SimplifiedChinese,
    TraditionalChinese,
    Japanese,
    Cyrillic,
    /// Custom font family names, in priority order.
    Custom(Vec<String>),
}

/// A resolved system font entry usable by UI code.
///
/// `family` is the human-readable family name used for lookup.
/// `key` is a unique identifier suitable as a UI font key within the current process.
/// It is not guaranteed to be stable across machines or across runs.
#[derive(Clone, Debug)]
pub struct FoundFont {
    pub family: String,
    pub key: String,
    pub source: FoundFontSource,
}

/// Font bytes source resolved from the system font database.
///
/// `Path` points to an on-disk font file.
/// `Bytes` contains the font data copied into memory (can be large).
#[derive(Clone, Debug)]
pub enum FoundFontSource {
    Path(PathBuf),
    Bytes(Arc<[u8]>),
}

/// Returns the current system locale string (e.g. "ko-KR", "en-US") if available.
///
/// # Examples
///
/// ```
/// let loc = system_fonts::system_locale();
/// // May be None depending on platform/environment.
/// println!("{loc:?}");
/// ```
pub fn system_locale() -> Option<String> {
    sys_locale::get_locale()
}

/// Converts a locale string into a `FontRegion`.
///
/// Supports common BCP-47 tags as well as "ko_KR.UTF-8"-style strings.
///
/// # Examples
///
/// ```
/// use system_fonts::{region_from_locale, FontRegion};
///
/// assert_eq!(region_from_locale("ko-KR"), FontRegion::Korean);
/// assert_eq!(region_from_locale("ko_KR.UTF-8"), FontRegion::Korean);
/// assert_eq!(region_from_locale("zh-Hant-TW"), FontRegion::TraditionalChinese);
/// assert_eq!(region_from_locale("zh_CN"), FontRegion::SimplifiedChinese);
/// assert_eq!(region_from_locale("ru-RU"), FontRegion::Cyrillic);
/// ```
pub fn region_from_locale(locale: &str) -> FontRegion {
    let mut s = locale.trim().to_ascii_lowercase().replace('_', "-");
    if let Some((head, _)) = s.split_once('.') {
        s = head.to_string();
    }

    if s.contains("-cyrl") {
        return FontRegion::Cyrillic;
    }
    if s.contains("-latn") {
        return FontRegion::Latin;
    }

    if s.starts_with("ko") {
        return FontRegion::Korean;
    }
    if s.starts_with("ja") {
        return FontRegion::Japanese;
    }
    if s.starts_with("zh") {
        if s.contains("hant") || s.contains("-tw") || s.contains("-hk") || s.contains("-mo") {
            return FontRegion::TraditionalChinese;
        }
        return FontRegion::SimplifiedChinese;
    }

    if s.starts_with("ru")
        || s.starts_with("uk")
        || s.starts_with("be")
        || s.starts_with("bg")
        || s.starts_with("mk")
        || s.starts_with("sr")
        || s.starts_with("kk")
        || s.starts_with("ky")
        || s.starts_with("tg")
        || s.starts_with("mn")
    {
        return FontRegion::Cyrillic;
    }

    if s.starts_with("en") || s.starts_with("fr") || s.starts_with("de") {
        return FontRegion::Latin;
    }

    FontRegion::Unknown
}

/// Returns the default preset priority list for a given region.
///
/// The returned presets are ordered from highest to lowest priority.
///
/// # Examples
///
/// ```
/// use system_fonts::{presets_for_region, FontRegion, FontPreset};
///
/// let presets = presets_for_region(FontRegion::Korean);
/// assert!(matches!(presets.first(), Some(FontPreset::Korean)));
/// ```
pub fn presets_for_region(region: FontRegion) -> Vec<FontPreset> {
    match region {
        FontRegion::Korean => vec![
            FontPreset::Korean,
            FontPreset::Japanese,
            FontPreset::SimplifiedChinese,
            FontPreset::TraditionalChinese,
            FontPreset::Latin,
        ],
        FontRegion::Japanese => vec![
            FontPreset::Japanese,
            FontPreset::Korean,
            FontPreset::SimplifiedChinese,
            FontPreset::TraditionalChinese,
            FontPreset::Latin,
        ],
        FontRegion::SimplifiedChinese => vec![
            FontPreset::SimplifiedChinese,
            FontPreset::TraditionalChinese,
            FontPreset::Korean,
            FontPreset::Japanese,
            FontPreset::Latin,
        ],
        FontRegion::TraditionalChinese => vec![
            FontPreset::TraditionalChinese,
            FontPreset::SimplifiedChinese,
            FontPreset::Korean,
            FontPreset::Japanese,
            FontPreset::Latin,
        ],
        FontRegion::Cyrillic => vec![
            FontPreset::Cyrillic,
            FontPreset::Latin,
            FontPreset::Korean,
            FontPreset::SimplifiedChinese,
            FontPreset::TraditionalChinese,
            FontPreset::Japanese,
        ],
        FontRegion::Latin | FontRegion::Unknown => vec![
            FontPreset::Latin,
            FontPreset::Cyrillic,
            FontPreset::Korean,
            FontPreset::SimplifiedChinese,
            FontPreset::TraditionalChinese,
            FontPreset::Japanese,
        ],
    }
}

/// Resolves system fonts from presets and style.
///
/// The returned list is ordered by priority (highest to lowest).
/// For `FontStyle::Serif`, serif candidates are tried first, then sans candidates are appended
/// as a fallback.
///
/// Notes:
/// - Duplicate families are removed (first match wins).
/// - Families not installed on the system are skipped.
///
/// # Examples
///
/// ```no_run
/// use system_fonts::{find_from_presets, FontPreset, FontStyle};
///
/// let presets = [FontPreset::Korean, FontPreset::Latin];
/// let fonts = find_from_presets(presets, FontStyle::Sans);
/// println!("fonts={}", fonts.len());
/// ```
pub fn find_from_presets<I>(presets_in_priority: I, style: FontStyle) -> Vec<FoundFont>
where
    I: IntoIterator<Item = FontPreset>,
{
    let db = font_db();

    let mut targets: Vec<String> = Vec::new();
    for preset in presets_in_priority {
        match style {
            FontStyle::Serif => {
                targets.extend(preset_targets_serif(&preset));
                targets.extend(preset_targets_sans(&preset));
            }
            FontStyle::Sans => {
                targets.extend(preset_targets_sans(&preset));
            }
        }
    }

    let mut seen_family = HashSet::<String>::new();
    let mut out = Vec::<FoundFont>::new();

    for (i, family_name) in targets.into_iter().enumerate() {
        if !seen_family.insert(family_name.clone()) {
            continue;
        }

        if let Some(found) = resolve_one_family(db, &family_name, i) {
            out.push(found);
        }
    }

    out
}

/// Detects a region from the given locale string, then resolves fonts using that region's presets.
///
/// # Examples
///
/// ```no_run
/// use system_fonts::{find_for_locale, FontStyle};
///
/// let (region, fonts) = find_for_locale("ja-JP", FontStyle::Sans);
/// println!("region={region:?}, fonts={}", fonts.len());
/// ```
pub fn find_for_locale(locale: &str, style: FontStyle) -> (FontRegion, Vec<FoundFont>) {
    let region = region_from_locale(locale);
    let presets = presets_for_region(region);
    (region, find_from_presets(presets, style))
}

/// Resolves fonts based on the current system locale.
///
/// If locale is unavailable, falls back to "en-US".
///
/// # Examples
///
/// ```no_run
/// use system_fonts::{find_for_system_locale, FontStyle};
///
/// let (_loc, region, fonts) = find_for_system_locale(FontStyle::Sans);
/// println!("region={region:?}, fonts={}", fonts.len());
/// ```
pub fn find_for_system_locale(style: FontStyle) -> (Option<String>, FontRegion, Vec<FoundFont>) {
    let locale = system_locale();
    let (region, fonts) = match locale.as_deref() {
        Some(loc) if !loc.trim().is_empty() => find_for_locale(loc, style),
        _ => {
            let fallback = "en-US";
            find_for_locale(fallback, style)
        }
    };
    (locale, region, fonts)
}

static FONT_DB: OnceLock<Database> = OnceLock::new();

fn font_db() -> &'static Database {
    FONT_DB.get_or_init(|| {
        let mut db = Database::new();
        db.load_system_fonts();
        db
    })
}

fn resolve_one_family(db: &Database, family_name: &str, uniq: usize) -> Option<FoundFont> {
    let families = [Family::Name(family_name)];
    let query = Query {
        families: &families,
        ..Default::default()
    };

    let id = db.query(&query)?;
    let face = db.face(id)?;

    let source = match &face.source {
        Source::File(path) => FoundFontSource::Path(path.to_path_buf()),
        Source::Binary(bytes) => {
            let v: Vec<u8> = bytes.as_ref().as_ref().to_vec();
            FoundFontSource::Bytes(Arc::from(v.into_boxed_slice()))
        }
        _ => return None,
    };

    let key = format!("system:{}:{}", family_name, uniq);

    Some(FoundFont {
        family: family_name.to_string(),
        key,
        source,
    })
}

fn preset_targets_sans(p: &FontPreset) -> Vec<String> {
    match p {
        FontPreset::Latin => vec![
            "Noto Sans".into(),
            "Segoe UI".into(),
            "Arial".into(),
            "SF Pro Text".into(),
            "Helvetica Neue".into(),
            "DejaVu Sans".into(),
            "Liberation Sans".into(),
            "Roboto".into(),
        ],
        FontPreset::Korean => vec![
            "Noto Sans KR".into(),
            "Noto Sans CJK KR".into(),
            "Malgun Gothic".into(),
            "Apple SD Gothic Neo".into(),
            "NanumGothic".into(),
        ],
        FontPreset::SimplifiedChinese => vec![
            "Noto Sans SC".into(),
            "Noto Sans CJK SC".into(),
            "Microsoft YaHei".into(),
            "PingFang SC".into(),
            "SimHei".into(),
            "SimSun".into(),
        ],
        FontPreset::TraditionalChinese => vec![
            "Noto Sans TC".into(),
            "Noto Sans CJK TC".into(),
            "Microsoft JhengHei".into(),
            "PingFang TC".into(),
        ],
        FontPreset::Japanese => vec![
            "Noto Sans JP".into(),
            "Noto Sans CJK JP".into(),
            "Yu Gothic".into(),
            "Hiragino Sans".into(),
            "Meiryo".into(),
        ],
        FontPreset::Cyrillic => vec![
            "Noto Sans".into(),
            "DejaVu Sans".into(),
            "Segoe UI".into(),
            "Arial".into(),
            "Tahoma".into(),
            "Times New Roman".into(),
        ],
        FontPreset::Custom(list) => list.clone(),
    }
}

fn preset_targets_serif(p: &FontPreset) -> Vec<String> {
    match p {
        FontPreset::Latin => vec![
            "Noto Serif".into(),
            "Times New Roman".into(),
            "Georgia".into(),
            "Liberation Serif".into(),
            "DejaVu Serif".into(),
            "Times".into(),
        ],
        FontPreset::Korean => vec![
            "Noto Serif KR".into(),
            "Noto Serif CJK KR".into(),
            "Batang".into(),
            "AppleMyungjo".into(),
            "NanumMyeongjo".into(),
        ],
        FontPreset::SimplifiedChinese => vec![
            "Noto Serif SC".into(),
            "Noto Serif CJK SC".into(),
            "Songti SC".into(),
            "SimSun".into(),
        ],
        FontPreset::TraditionalChinese => vec![
            "Noto Serif TC".into(),
            "Noto Serif CJK TC".into(),
            "Songti TC".into(),
            "PMingLiU".into(),
        ],
        FontPreset::Japanese => vec![
            "Noto Serif JP".into(),
            "Noto Serif CJK JP".into(),
            "Yu Mincho".into(),
            "Hiragino Mincho ProN".into(),
            "MS Mincho".into(),
        ],
        FontPreset::Cyrillic => vec![
            "Noto Serif".into(),
            "Times New Roman".into(),
            "Georgia".into(),
            "Liberation Serif".into(),
            "DejaVu Serif".into(),
        ],
        FontPreset::Custom(list) => list.clone(),
    }
}