mini-cite 0.2.0

BibTeX-backed inline citations and footnotes for the mini-* family.
Documentation
//! Presentation options for the markup [`crate::process`] emits.

/// Class on the `<sup>` wrapping an inline footnote reference.
const DEFAULT_REFERENCE_CLASS: &str = "footnote-ref";
/// Class on the `<hr>` opening the footnote block.
const DEFAULT_SEPARATOR_CLASS: &str = "footnotes-sep";
/// Class on the `<ol>` holding the footnotes.
const DEFAULT_LIST_CLASS: &str = "footnotes";
/// Class on each footnote `<li>`.
const DEFAULT_ITEM_CLASS: &str = "footnote";
/// Class on the back-link closing each footnote.
const DEFAULT_BACKLINK_CLASS: &str = "footnote-back";
/// The back-link's text: a returning arrow.
const DEFAULT_BACKLINK_LABEL: &str = "↩";

/// Characters that would break out of the `class="…"` attribute they are written into.
const CLASS_DELIMITERS: [char; 3] = ['"', '<', '>'];

/// How the emitted citation markup is labelled and named.
///
/// Structure is fixed — a `<sup>` reference per citation, an `<hr>`, an `<ol>` of
/// `<li>` footnotes, a back-link in each — and so are the `fn-N`/`fnref-N` ids the two
/// halves are wired together with. What this configures is the part a stylesheet
/// addresses: the class on each element, and the back-link's label.
///
/// Defaults follow Pandoc's names (`footnote-ref`, `footnotes`, `footnote-back`), so a
/// stylesheet written against Pandoc's footnote output mostly applies unchanged.
///
/// Setting a class to `""` emits that element with no `class` attribute at all, for
/// callers styling structurally (`li[id^="fn-"]`) rather than by class.
///
/// ```
/// let style = mini_cite::CiteStyle::default()
///     .reference_class("citation-marker")
///     .backlink_label("↑");
/// ```
///
/// # Downstream sanitizing
///
/// These classes only reach the page if whatever renders the Markdown preserves
/// `class`. `ammonia`'s default policy strips it; `mini-docs` allowlists it from
/// 0.5.0 on. Against an older or stricter sanitizer the markup still renders — the
/// ids survive — but the classes are dropped.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CiteStyle {
    pub(crate) reference_class: String,
    pub(crate) separator_class: String,
    pub(crate) list_class: String,
    pub(crate) item_class: String,
    pub(crate) backlink_class: String,
    pub(crate) backlink_label: String,
}

impl Default for CiteStyle {
    fn default() -> Self {
        Self {
            reference_class: DEFAULT_REFERENCE_CLASS.to_string(),
            separator_class: DEFAULT_SEPARATOR_CLASS.to_string(),
            list_class: DEFAULT_LIST_CLASS.to_string(),
            item_class: DEFAULT_ITEM_CLASS.to_string(),
            backlink_class: DEFAULT_BACKLINK_CLASS.to_string(),
            backlink_label: DEFAULT_BACKLINK_LABEL.to_string(),
        }
    }
}

impl CiteStyle {
    /// Sets the class on the `<sup>` wrapping each inline reference.
    #[must_use]
    pub fn reference_class(mut self, class: impl Into<String>) -> Self {
        self.reference_class = checked_class(class.into());
        self
    }

    /// Sets the class on the `<hr>` that opens the footnote block.
    #[must_use]
    pub fn separator_class(mut self, class: impl Into<String>) -> Self {
        self.separator_class = checked_class(class.into());
        self
    }

    /// Sets the class on the `<ol>` holding the footnotes.
    #[must_use]
    pub fn list_class(mut self, class: impl Into<String>) -> Self {
        self.list_class = checked_class(class.into());
        self
    }

    /// Sets the class on each footnote `<li>`.
    #[must_use]
    pub fn item_class(mut self, class: impl Into<String>) -> Self {
        self.item_class = checked_class(class.into());
        self
    }

    /// Sets the class on the back-link closing each footnote.
    #[must_use]
    pub fn backlink_class(mut self, class: impl Into<String>) -> Self {
        self.backlink_class = checked_class(class.into());
        self
    }

    /// Sets the back-link's label — the glyph or word a reader clicks to return to
    /// the citation.
    ///
    /// Written into the document verbatim, so markup here reaches the renderer as
    /// markup and is subject to whatever sanitizing follows. An empty label leaves the
    /// link with nothing to click; give it content, or draw one in CSS through
    /// [`Self::backlink_class`].
    #[must_use]
    pub fn backlink_label(mut self, label: impl Into<String>) -> Self {
        self.backlink_label = label.into();
        self
    }
}

/// Returns `class` unchanged, tripping in debug builds if it could not be written
/// into an attribute intact.
///
/// A class name carrying a quote or an angle bracket does not produce a differently
/// styled page — it produces malformed markup, silently, several layers from here.
/// Nothing sanitizes this on the caller's behalf, so the check belongs at the boundary
/// the value enters through (A4).
fn checked_class(class: String) -> String {
    debug_assert!(
        !class.contains(CLASS_DELIMITERS),
        "class name must not contain a quote or angle bracket: {class:?}"
    );
    class
}

/// Renders a `class` attribute, or nothing at all when `class` is empty.
///
/// The leading space belongs to the attribute rather than to the tag that holds it,
/// so a tag with no class emits no stray whitespace either.
pub(crate) fn class_attr(class: &str) -> String {
    if class.is_empty() {
        return String::new();
    }

    format!(r#" class="{class}""#)
}

#[cfg(test)]
#[path = "../tests/unit/style.rs"]
mod tests;