euv_core/vdom/attribute/

impl.rs

use super::*;

/// Implementation of the public read side of an attribute entry.
impl AttributeEntry {
    /// Returns the CSS class names this attribute carries.
    ///
    /// The `class` attribute is the one place where a component's
    /// styling decisions become observable, so it needs a public read
    /// side: a component library's tests have to be able to assert
    /// that a state actually landed on the right class, and an external
    /// crate cannot read the raw attribute value.
    ///
    /// Every shape the attribute can take is reported:
    /// `Css` and `CssRef` contribute the class name they carry, `Text`
    /// and `StaticText` contribute their string split on whitespace,
    /// a `Signal` contributes the class list it currently holds — that
    /// is the shape a reactive `class:` attribute takes — and the
    /// remaining shapes, an event handler, contribute nothing, because
    /// neither is a class list.
    ///
    /// # Returns
    ///
    /// - `Vec<String>` - The class names, in the order they appear.
    pub fn class_names(&self) -> Vec<String> {
        match self.get_value() {
            AttributeValue::Css(css) => vec![css.get_name().clone()],
            AttributeValue::CssRef(css) => vec![css.get_name().clone()],
            AttributeValue::Text(text) => split_class_names(text),
            AttributeValue::StaticText(text) => split_class_names(text),
            AttributeValue::Signal(signal) => split_class_names(&signal.get()),
            _ => Vec::new(),
        }
    }

    /// Returns the attribute's value as text, when it carries one.
    ///
    /// A `Text` or `StaticText` attribute is its own value; a `Css` or
    /// `CssRef` attribute contributes its class name, because that is
    /// the text the browser ends up showing for it. The remaining
    /// shapes — a reactive signal, an event handler — carry no text.
    ///
    /// # Returns
    ///
    /// - `Option<String>` - The value, when the attribute has one.
    pub fn text_value(&self) -> Option<String> {
        match self.get_value() {
            AttributeValue::Text(text) => Some(text.clone()),
            AttributeValue::StaticText(text) => Some((*text).to_string()),
            AttributeValue::Css(css) => Some(css.get_name().clone()),
            AttributeValue::CssRef(css) => Some(css.get_name().clone()),
            _ => None,
        }
    }
}

/// Implementation of injected class tracking for CSS deduplication.
impl InjectedClassesCell {
    /// Returns `true` if the given class name has already been injected into
    /// the DOM.
    ///
    /// # Arguments
    ///
    /// - `&str` - The CSS class name to check.
    ///
    /// # Returns
    ///
    /// - `bool` - Whether the class name has been injected.
    pub(crate) fn is_injected(class_name: &str) -> bool {
        INJECTED_CLASSES
            .read()
            .map(|classes: RwLockReadGuard<'_, HashSet<String>>| classes.contains(class_name))
            .unwrap_or(false)
    }

    /// Marks a class name as injected so future calls to `is_injected`
    /// return `true`.
    ///
    /// A poisoned lock (which only happens if another thread panicked while
    /// holding the write guard) is recovered from rather than propagated:
    /// the set is deduplication bookkeeping, so losing a lock must never
    /// take down the render path.
    ///
    /// # Arguments
    ///
    /// - `&str` - The CSS class name to mark as injected.
    pub(crate) fn mark_injected(class_name: &str) {
        let write_result: Result<
            InjectedClassesWriteGuard<'_>,
            PoisonError<InjectedClassesWriteGuard<'_>>,
        > = INJECTED_CLASSES.write();
        let Ok(mut classes) = write_result else {
            return;
        };
        classes.insert(class_name.to_string());
    }
}

/// Implementation of attribute value factory methods for reactive and merged values.
impl AttributeValue {
    /// Creates a reactive attribute `Self` for conditional attribute values.
    ///
    /// This function replaces the inline `Signal::create(...)` boilerplate
    /// that was previously generated by the `html!` macro for every
    /// attribute value containing an `if` condition.
    ///
    /// The returned `Self::Text` is a snapshot computed on each render of
    /// the enclosing dynamic node: the signals read inside
    /// `compute` during that render register the dynamic node as their
    /// dependent, so any source change re-renders the node and rebuilds
    /// this attribute with the new value. No signal slot or registry
    /// listener is allocated for the snapshot. Direct `Self::Signal`
    /// bindings retain their independent DOM subscription behavior.
    ///
    /// # Arguments
    ///
    /// - `F` - A closure that computes the current attribute value.
    ///   Called once per render of the enclosing dynamic node.
    ///
    /// # Returns
    ///
    /// - `Self` - A `Self::Text` carrying the freshly computed value.
    pub fn reactive<F>(compute: F) -> Self
    where
        F: Fn() -> String + 'static,
    {
        Self::Text(compute())
    }

    /// Merges multiple class attribute values into a single `Self`.
    ///
    /// Each input value is adapted into a `Self` via `IntoReactiveValue`.
    /// `Css` values are injected into the DOM and their names are collected.
    /// All non-empty class names are joined with spaces into a final `Text` attribute.
    /// Signal inputs are read without allocating a new signal for the
    /// merged snapshot. The enclosing dynamic node re-renders on any
    /// constituent signal change (see
    /// [`AttributeValue::reactive`]).
    ///
    /// # Arguments
    ///
    /// - `&[Self]` - The class attribute values to merge.
    ///
    /// # Returns
    ///
    /// - `Self` - A merged attribute value containing space-separated class names.
    pub fn merge_class(values: &[Self]) -> Self {
        Self::Text(Self::join_class_segments(values))
    }

    /// Joins class attribute values into a single space-separated string.
    ///
    /// OPT-20: builds the result in a single `String` (amortized growth,
    /// no intermediate `Vec<String>` + `join(" ")` round-trip), iterating
    /// the input values by reference and cloning only the segments that
    /// survive the filter (skipping `_ => None` arms and empty `Text`
    /// strings), so the per-class render allocation drops from `N + 2`
    /// to `1`.
    ///
    /// OPT-11: both `Css` and `CssRef` arms inject the style on first
    /// reference. Without the `CssRef` arm the ref would fall through
    /// to `_ => None` and silently drop out of the merged class list —
    /// the regression that wiped every multi-class CssRef entry (e.g.
    /// the `c_binding_slider` class next to a parameterized
    /// `c_slider_value("30%")` on the same `<input>`).
    ///
    /// # Arguments
    ///
    /// - `&[Self]` - The class attribute values to merge, in order.
    ///
    /// # Returns
    ///
    /// - `String` - The merged class list, segments separated by a
    ///   single space; empty when no segment survived filtering.
    fn join_class_segments(values: &[Self]) -> String {
        let mut joined: String = String::new();
        for value in values.iter() {
            let segment: Cow<'_, str> = match value {
                Self::Css(css) => {
                    css.inject_style();
                    let name: &str = css.get_name();
                    if name.is_empty() {
                        continue;
                    }
                    Cow::Borrowed(name)
                }
                Self::CssRef(css) => {
                    css.inject_style();
                    let name: &str = css.get_name();
                    if name.is_empty() {
                        continue;
                    }
                    Cow::Borrowed(name)
                }
                Self::Text(text_value) => {
                    if text_value.is_empty() {
                        continue;
                    }
                    Cow::Borrowed(text_value.as_str())
                }
                Self::Signal(signal) => {
                    let current: String = signal.get();
                    if current.is_empty() {
                        continue;
                    }
                    Cow::Owned(current)
                }
                _ => continue,
            };
            if !joined.is_empty() {
                joined.push(' ');
            }
            joined.push_str(segment.as_ref());
        }
        joined
    }

    /// Merges multiple style attribute values into a single `Self`.
    ///
    /// Each input value is expected to be a style string (`Text`) or a reactive
    /// `Signal<String>` producing a style string. All non-empty style strings are
    /// joined with spaces into a final combined style attribute.
    /// Signal inputs are read without allocating a new signal for the
    /// merged snapshot. The enclosing dynamic node re-renders on any
    /// constituent signal change (see
    /// [`AttributeValue::reactive`]).
    ///
    /// # Arguments
    ///
    /// - `&[Self]` - The style attribute values to merge.
    ///
    /// # Returns
    ///
    /// - `Self` - A merged attribute value containing the combined CSS style string.
    pub fn merge_style(values: &[Self]) -> Self {
        Self::Text(Self::join_style_segments(values))
    }

    /// Joins style attribute values into a single space-separated string.
    ///
    /// OPT-20: same single-`String` approach as `join_class_segments`
    /// (amortized growth), specialised to the `Text` + `Signal` cases that
    /// style merging uses. Avoids the intermediate `Vec<String>` plus
    /// `join(" ")` round-trip of the previous implementation, dropping
    /// per-render allocation count from `N + 2` to `1`.
    ///
    /// # Arguments
    ///
    /// - `&[Self]` - The style attribute values to merge, in order.
    ///
    /// # Returns
    ///
    /// - `String` - The merged CSS declarations, segments separated by a
    ///   single space; empty when no segment carried a declaration.
    fn join_style_segments(values: &[Self]) -> String {
        let mut joined: String = String::new();
        for value in values.iter() {
            let segment: Cow<'_, str> = match value {
                Self::Text(text_value) => {
                    if text_value.is_empty() {
                        continue;
                    }
                    Cow::Borrowed(text_value.as_str())
                }
                Self::Signal(signal) => {
                    let current: String = signal.get();
                    if current.is_empty() {
                        continue;
                    }
                    Cow::Owned(current)
                }
                _ => continue,
            };
            if !joined.is_empty() {
                joined.push(' ');
            }
            joined.push_str(segment.as_ref());
        }
        joined
    }

    /// Converts a bool signal into a reactive boolean attribute value.
    ///
    /// Produces `AttributeValue::BoolSignal` directly: the renderer writes
    /// `"true"` / `"false"` and subscribes the source signal to the element
    /// with no intermediate mapping signal (the previous `Signal<String>`
    /// bridge) and no per-render subscription.
    ///
    /// # Arguments
    ///
    /// - `Signal<bool>` - The source boolean signal.
    ///
    /// # Returns
    ///
    /// - `AttributeValue` - A `BoolSignal` wrapping the source signal.
    pub(crate) fn bool_to_attr(source: Signal<bool>) -> AttributeValue {
        AttributeValue::BoolSignal(source)
    }
}

/// Visual equality comparison for attribute values.
///
/// Compares values by their visual output rather than identity. `Signal`
/// values are compared by their current resolved string (borrow-compared
/// via `Signal::with`, no `String` clones); when both signals share the
/// same slab slot, they are always considered **unequal** — the patch walk
/// recognises that case separately and skips the DOM write because the
/// mount-time signal binding already owns the attribute's DOM value (see
/// `patch_attributes`), while the unequal verdict keeps `visual_eq` from
/// masking a value change between VDOM snapshots.
/// `Event` values are always considered equal (re-binding is handled by the
/// handler registry), and `Css` values are compared by class name.
impl PartialEq for AttributeValue {
    /// Compares two attribute values for visual equality.
    ///
    /// # Arguments
    ///
    /// - `&Self` - The first attribute value.
    /// - `&Self` - The second attribute value.
    ///
    /// # Returns
    ///
    /// - `bool` - `true` if the values are visually equal.
    fn eq(&self, other: &Self) -> bool {
        match (self, other) {
            (Self::Text(old_value), Self::Text(new_value)) => old_value == new_value,
            (Self::StaticText(old_value), Self::StaticText(new_value)) => old_value == new_value,
            (Self::Text(old_value), Self::StaticText(new_value)) => old_value == new_value,
            (Self::StaticText(old_value), Self::Text(new_value)) => old_value == new_value,
            (Self::Signal(old_signal), Self::Signal(new_signal)) => {
                if old_signal.get_inner() == new_signal.get_inner() {
                    return false;
                }
                old_signal.with(|old_value: &String| {
                    new_signal.with(|new_value: &String| old_value == new_value)
                })
            }
            (Self::Signal(old_signal), Self::Text(new_value)) => {
                old_signal.with(|old_value: &String| old_value == new_value)
            }
            (Self::Text(old_value), Self::Signal(new_signal)) => {
                new_signal.with(|new_value: &String| old_value == new_value)
            }
            (Self::BoolSignal(old_signal), Self::BoolSignal(new_signal)) => {
                if old_signal.get_inner() == new_signal.get_inner() {
                    return false;
                }
                old_signal.get() == new_signal.get()
            }
            (Self::Event(_), Self::Event(_)) => true,
            (Self::Css(old_class), Self::Css(new_class)) => {
                old_class.get_name() == new_class.get_name()
            }
            (Self::CssRef(old_class), Self::CssRef(new_class)) => {
                old_class.get_name() == new_class.get_name()
            }
            (Self::CssRef(old_class), Self::Css(new_class)) => {
                old_class.get_name() == new_class.get_name()
            }
            (Self::Css(old_class), Self::CssRef(new_class)) => {
                old_class.get_name() == new_class.get_name()
            }
            (Self::Dynamic(old_dynamic), Self::Dynamic(new_dynamic)) => old_dynamic == new_dynamic,
            _ => false,
        }
    }
}

/// Visual equality comparison for attribute entries.
///
/// Two attribute entries are equal when their names match and their values
/// are visually equal as defined by `AttributeValue::eq`.
impl PartialEq for AttributeEntry {
    /// Compares two attribute entries for visual equality.
    ///
    /// # Arguments
    ///
    /// - `&Self` - The first attribute entry.
    /// - `&Self` - The second attribute entry.
    ///
    /// # Returns
    ///
    /// - `bool` - `true` if both names and values match.
    fn eq(&self, other: &Self) -> bool {
        self.get_name() == other.get_name() && self.get_value() == other.get_value()
    }
}

/// Visual equality comparison for CSS classes.
///
/// Two CSS classes are considered equal when their class names match,
/// since the name uniquely identifies the visual style rule.
impl PartialEq for Css {
    /// Compares two CSS classes by name.
    ///
    /// # Arguments
    ///
    /// - `&Self` - The first CSS class.
    /// - `&Self` - The second CSS class.
    ///
    /// # Returns
    ///
    /// - `bool` - `true` if the class names match.
    fn eq(&self, other: &Self) -> bool {
        self.get_name() == other.get_name()
    }
}

/// Implementation of Css construction and style injection.
impl Css {
    /// Parses pseudo-class/pseudo-element rules from a compact serialization string.
    ///
    /// The serialization format is: `:selector { key: value; key: value; }:another { ... }`
    /// This is used by the `class!` macro for fully static class definitions
    /// where pseudo rules can be computed at compile time.
    ///
    /// # Arguments
    ///
    /// - `I` - The serialized pseudo rules string.
    ///
    /// # Returns
    ///
    /// - `Vec<PseudoRule>` - The parsed pseudo rules.
    pub fn parse_pseudo_rules<I>(input: I) -> Vec<PseudoRule>
    where
        I: AsRef<str>,
    {
        let mut remaining: &str = input.as_ref();
        let mut rules: Vec<PseudoRule> = Vec::new();
        while !remaining.is_empty() {
            let selector_end: Option<usize> = remaining.find(CSS_RULE_OPEN);
            let Some(selector_end_index) = selector_end else {
                break;
            };
            let selector: &str = &remaining[..selector_end_index];
            let after_selector: &str = remaining[selector_end_index..]
                .strip_prefix(CSS_RULE_OPEN)
                .unwrap_or_default();
            let style_end: Option<usize> = after_selector.find(CHAR_CSS_RULE_CLOSE);
            let Some(style_end_index) = style_end else {
                break;
            };
            let style: &str = &after_selector[..style_end_index];
            if !selector.is_empty() && !style.is_empty() {
                rules.push(PseudoRule::new(selector.to_string(), style.to_string()));
            }
            remaining = after_selector[style_end_index..]
                .strip_prefix(CHAR_CSS_RULE_CLOSE)
                .unwrap_or_default();
        }
        rules
    }

    /// Parses media query rules from a compact serialization string.
    ///
    /// The serialization format is:
    /// `@media query { key: value; ::selector { key: value; } }@media query2 { ... }`
    /// This is used by the `class!` macro for fully static class definitions
    /// where media rules can be computed at compile time.
    /// Supports nested pseudo-element blocks inside media query blocks.
    ///
    /// # Arguments
    ///
    /// - `S` - The serialized media rules string.
    ///
    /// # Returns
    ///
    /// - `Vec<MediaRule>` - The parsed media rules.
    pub fn parse_media_rules<S>(input: S) -> Vec<MediaRule>
    where
        S: AsRef<str>,
    {
        let input: &str = input.as_ref();
        let mut rules: Vec<MediaRule> = Vec::new();
        let mut remaining: &str = input;
        while !remaining.is_empty() {
            if !remaining.starts_with(CSS_MEDIA_PREFIX) {
                break;
            }
            let after_prefix: &str = remaining.strip_prefix(CSS_MEDIA_PREFIX).unwrap_or_default();
            let query_end: Option<usize> = after_prefix.find(CSS_RULE_OPEN);
            let Some(query_end_index) = query_end else {
                break;
            };
            let query: &str = &after_prefix[..query_end_index];
            let after_query: &str = after_prefix[query_end_index..]
                .strip_prefix(CSS_RULE_OPEN)
                .unwrap_or_default();
            let mut depth: usize = 1;
            let mut close_pos: usize = 0;
            for (index, char_value) in after_query.char_indices() {
                if char_value == '{' {
                    depth += 1;
                } else if char_value == '}' {
                    depth -= 1;
                    if depth == 0 {
                        close_pos = index;
                        break;
                    }
                }
            }
            if close_pos == 0 {
                break;
            }
            let body: &str = &after_query[..close_pos];
            let (style, pseudo_rules): (String, Vec<PseudoRule>) = Self::parse_media_body(body);
            if !query.is_empty() && (!style.is_empty() || !pseudo_rules.is_empty()) {
                rules.push(MediaRule::new(query.to_string(), style, pseudo_rules));
            }
            remaining = after_query[close_pos..]
                .strip_prefix(CHAR_CSS_RULE_CLOSE)
                .unwrap_or_default();
        }
        rules
    }

    /// Parses the body of a media rule, separating top-level style declarations
    /// from nested pseudo-element blocks.
    ///
    /// # Arguments
    ///
    /// - `&str` - The media rule body content (between the outer braces).
    ///
    /// # Returns
    ///
    /// - `(String, Vec<PseudoRule>)` - A tuple of the style string and pseudo rules.
    fn parse_media_body(body: &str) -> (String, Vec<PseudoRule>) {
        let mut style_parts: String = String::new();
        let mut pseudo_rules: Vec<PseudoRule> = Vec::new();
        let mut remaining: &str = body;
        while !remaining.is_empty() {
            let brace_pos: Option<usize> = remaining.find('{');
            match brace_pos {
                Some(pos) => {
                    let before_brace: &str = remaining[..pos].trim();
                    if before_brace.starts_with("::") || before_brace.starts_with(':') {
                        let selector: &str = before_brace;
                        let after_brace: &str = &remaining[pos + 1..];
                        let mut depth: usize = 1;
                        let mut close_pos: usize = 0;
                        for (index, char_value) in after_brace.char_indices() {
                            if char_value == '{' {
                                depth += 1;
                            } else if char_value == '}' {
                                depth -= 1;
                                if depth == 0 {
                                    close_pos = index;
                                    break;
                                }
                            }
                        }
                        if close_pos > 0 {
                            let inner_style: &str = after_brace[..close_pos].trim();
                            if !selector.is_empty() && !inner_style.is_empty() {
                                pseudo_rules.push(PseudoRule::new(
                                    selector.to_string(),
                                    inner_style.to_string(),
                                ));
                            }
                            remaining = after_brace[close_pos + 1..].trim_start();
                            continue;
                        }
                        break;
                    } else {
                        style_parts.push_str(before_brace);
                        style_parts.push(' ');
                        let after_brace: &str = &remaining[pos + 1..];
                        let mut depth: usize = 1;
                        let mut close_pos: usize = 0;
                        for (index, char_value) in after_brace.char_indices() {
                            if char_value == '{' {
                                depth += 1;
                            } else if char_value == '}' {
                                depth -= 1;
                                if depth == 0 {
                                    close_pos = index;
                                    break;
                                }
                            }
                        }
                        if close_pos > 0 {
                            style_parts.push_str(after_brace[..close_pos].trim());
                            style_parts.push(' ');
                            remaining = after_brace[close_pos + 1..].trim_start();
                            continue;
                        }
                        break;
                    }
                }
                None => {
                    style_parts.push_str(remaining.trim());
                    break;
                }
            }
        }
        (style_parts.trim().to_string(), pseudo_rules)
    }

    /// Injects this class's styles into the DOM if not already present.
    ///
    /// Uses a global `HashSet` to track injected class names, avoiding the
    /// expensive `existing_css.contains(css)` full-text search on every call.
    /// Builds the class rule, pseudo-class rules, and media rules as CSS text,
    /// then appends them directly to the `<style>` element via
    /// `append_child` with a new text node — no read-modify-write of the
    /// entire stylesheet content.
    ///
    /// # Panics
    ///
    /// Panics if `window()` or `document()` is unavailable on the current platform.
    pub fn inject_style(&self) {
        let class_name: &String = self.get_name();
        if InjectedClassesCell::is_injected(class_name) {
            return;
        }
        InjectedClassesCell::mark_injected(class_name);
        let raw_name: String = self.get_name().clone();
        let mut escaped_name: String = String::with_capacity(raw_name.len() * 2);
        for ch in raw_name.chars() {
            if ch.is_ascii_alphanumeric() || ch == CHAR_HYPHEN || ch == CHAR_UNDERSCORE {
                escaped_name.push(ch);
            } else {
                escaped_name.push(CHAR_CSS_ESCAPE);
                escaped_name.push(ch);
            }
        }
        let mut css_text: String = format!(
            "{CHAR_CSS_CLASS_PREFIX}{escaped_name}{CSS_RULE_OPEN_FORMAT}{}{CSS_RULE_CLOSE_FORMAT}",
            self.get_style()
        );
        for pseudo_rule in self.get_pseudo_rules() {
            if !pseudo_rule.get_style().is_empty() {
                css_text = format!(
                    "{css_text}{CHAR_CSS_RULE_SEPARATOR}{CHAR_CSS_CLASS_PREFIX}{}{}{CSS_RULE_OPEN_FORMAT}{}{CSS_RULE_CLOSE_FORMAT}",
                    escaped_name,
                    pseudo_rule.get_selector(),
                    pseudo_rule.get_style()
                );
            }
        }
        for media_rule in self.get_media_rules() {
            if !media_rule.get_query().is_empty() {
                let mut media_body: String = format!(
                    "{CHAR_CSS_CLASS_PREFIX}{}{CSS_RULE_OPEN_FORMAT}{}{CSS_RULE_CLOSE_FORMAT}",
                    escaped_name,
                    media_rule.get_style()
                );
                for pseudo_rule in media_rule.get_pseudo_rules() {
                    if !pseudo_rule.get_style().is_empty() {
                        media_body = format!(
                            "{media_body} {CHAR_CSS_CLASS_PREFIX}{}{}{CSS_RULE_OPEN_FORMAT}{}{CSS_RULE_CLOSE_FORMAT}",
                            escaped_name,
                            pseudo_rule.get_selector(),
                            pseudo_rule.get_style()
                        );
                    }
                }
                css_text = format!(
                    "{css_text}{CHAR_CSS_RULE_SEPARATOR}{CSS_MEDIA_PREFIX}{}{CSS_RULE_OPEN_FORMAT}{}{CSS_RULE_CLOSE_FORMAT}",
                    media_rule.get_query(),
                    media_body
                );
            }
        }
        Self::append_css(&css_text);
    }

    /// Appends CSS text directly to the shared `<style>` element.
    ///
    /// Creates a new text node and appends it as a child of the `<style>`
    /// element, avoiding the read-modify-write pattern of reading the entire
    /// `innerText`, concatenating, and setting it back.
    ///
    /// # Arguments
    ///
    /// - `&str` - The CSS text to append.
    ///
    /// The `cfg!` guard matches the one `Scheduler::current_time` already
    /// uses: `window()` reads a wasm-only imported static, so on a non-wasm
    /// target it panics with "cannot access imported statics on non-wasm
    /// targets" rather than returning `None`. That panic short-circuits the
    /// graceful `match window() { None => return }` below, and it fires from
    /// `OnceLock<Css>::get_or_init` — the first time any `c_*()` class
    /// function is called. Every styled view component calls one, so
    /// without this guard none of them can be rendered in a native
    /// `cargo test` process. On wasm the guard is a constant `true` and
    /// this function behaves exactly as before.
    fn append_css(css_text: &str) {
        if !cfg!(target_arch = "wasm32") {
            return;
        }
        let style_id: &str = EUV_CSS_INJECTED_ID;
        let window_value: Window = match window() {
            Some(window_instance) => window_instance,
            None => return,
        };
        let document: Document = match window_value.document() {
            Some(document_instance) => document_instance,
            None => return,
        };
        let style_element: HtmlStyleElement = match document.get_element_by_id(style_id) {
            Some(existing_element) => match existing_element.dyn_into::<HtmlStyleElement>() {
                Ok(element) => element,
                Err(_err) => return,
            },
            None => {
                let created: Element = match document.create_element(STYLE_TAG) {
                    Ok(element) => element,
                    Err(_err) => return,
                };
                let style_element_from_id: HtmlStyleElement =
                    match created.dyn_into::<HtmlStyleElement>() {
                        Ok(element) => element,
                        Err(_err) => return,
                    };
                style_element_from_id.set_id(style_id);
                if let Some(head) = document.head() {
                    let _: Result<Node, JsValue> = head.append_child(&style_element_from_id);
                }
                style_element_from_id
            }
        };
        if !css_text.is_empty() {
            let text_node: Text = document.create_text_node(css_text);
            let _: Result<Node, JsValue> = style_element.append_child(&text_node);
        }
    }

    /// Builds a CSS style string from an array of key-value pairs.
    ///
    /// This function is used by the `html!` macro to convert static `style:`
    /// attributes into a CSS string without allocating intermediate objects.
    ///
    /// # Arguments
    ///
    /// - `&[(K, V)]` - An array of CSS property name-value pairs.
    ///
    /// # Returns
    ///
    /// - `String` - The CSS string (e.g., `"margin: 0 auto; max-width: 800px;"`).
    pub fn style_string<K, V>(props: &[(K, V)]) -> String
    where
        K: AsRef<str>,
        V: AsRef<str>,
    {
        // Single pre-sized `String` instead of per-prop `format!` +
        // intermediate `Vec<String>` + `join` (was N + 2 allocations).
        let total_len: usize = props
            .iter()
            .map(|(key, value): &(K, V)| {
                key.as_ref().len() + CSS_PROP_SEPARATOR.len() + value.as_ref().len() + 2
            })
            .sum();
        let mut out: String = String::with_capacity(total_len);
        for (index, (key, value)) in props.iter().enumerate() {
            if index > 0 {
                out.push_str(CHAR_SPACE);
            }
            out.push_str(key.as_ref());
            out.push_str(CSS_PROP_SEPARATOR);
            out.push_str(value.as_ref());
            out.push(CHAR_CSS_DECL_TERMINATOR);
        }
        out
    }

    /// Builds a stable suffix for a class name from a dynamic parameter value.
    ///
    /// Used by the `class!` macro when a parameter is wrapped in `{}` in the
    /// class body. Wrapping a parameter opts it into value-dependent class
    /// names, so each distinct value can inject its own CSS rule.
    ///
    /// # Arguments
    ///
    /// - `&str` - The dynamic parameter value.
    ///
    /// # Returns
    ///
    /// - `String` - A stable hexadecimal suffix for the class name.
    pub fn param_class_name(value: &str) -> String {
        let mut hash: u64 = CLASS_PARAM_HASH_FNV_OFFSET;
        for byte in value.as_bytes() {
            hash ^= u64::from(*byte);
            hash = hash.wrapping_mul(CLASS_PARAM_HASH_FNV_PRIME);
        }
        format!("{hash:x}")
    }

    /// Builds a CSS style string from owned key-value pairs.
    ///
    /// Used by the `html!` macro for reactive style attributes (with `if`
    /// conditions) where values are computed at runtime.
    ///
    /// # Arguments
    ///
    /// - `&[(String, String)]` - An array of owned CSS property name-value pairs.
    ///
    /// # Returns
    ///
    /// - `String` - The CSS string (e.g., `"margin: 0 auto; max-width: 800px;"`).
    pub fn style_string_owned(props: &[(String, String)]) -> String {
        // Single pre-sized `String` (same shape as `style_string`).
        let total_len: usize = props
            .iter()
            .map(|(key, value): &(String, String)| {
                key.len() + CSS_PROP_SEPARATOR.len() + value.len() + 2
            })
            .sum();
        let mut out: String = String::with_capacity(total_len);
        for (index, (key, value)) in props.iter().enumerate() {
            if index > 0 {
                out.push_str(CHAR_SPACE);
            }
            out.push_str(key);
            out.push_str(CSS_PROP_SEPARATOR);
            out.push_str(value);
            out.push(CHAR_CSS_DECL_TERMINATOR);
        }
        out
    }

    /// Injects CSS text into the shared `<style>` element in the DOM.
    ///
    /// Delegates to [`Css::append_css`] for the actual DOM append.
    /// Unlike the previous implementation, this does not read the existing
    /// stylesheet content or perform a full-text `contains` search.
    ///
    /// # Arguments
    ///
    /// - `S` - The CSS text to inject (e.g., reset styles, keyframes, media queries).
    ///
    /// # Panics
    ///
    /// Panics if `window()` or `document()` is unavailable on the current platform.
    pub fn inject_css<S>(css_text: S)
    where
        S: AsRef<str>,
    {
        let css_text: &str = css_text.as_ref();
        Self::append_css(css_text);
    }
}

/// Displays the CSS class name.
///
/// This enables `format!("{css}")` to produce the class name string,
/// which is required for reactive `if` conditions in `class:` attributes.
impl Display for Css {
    /// Formats the CSS class as its name string.
    ///
    /// # Arguments
    ///
    /// - `&mut Formatter<'_>` - The formatter.
    ///
    /// # Returns
    ///
    /// - `fmt::Result` - The formatting result.
    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
        write!(formatter, "{}", self.get_name())
    }
}