pharos_native/runtime/

ui.rs

#![allow(clippy::too_many_arguments)]

use std::fs;
use std::path::{Path, PathBuf};

use serde_json::{Map, Value};

#[allow(non_snake_case)]
/// Performs ADD UI PARAM.
///
/// # Parameters
///
/// - `params`: Input consumed by [`crate::runtime::ui::ADD_UI_PARAM`].
/// - `key`: Input consumed by [`crate::runtime::ui::ADD_UI_PARAM`].
/// - `text`: Input consumed by [`crate::runtime::ui::ADD_UI_PARAM`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::ui::ADD_UI_PARAM`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ADD_UI_PARAM(todo!(), "key", "{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ADD_UI_PARAM(params: &mut Map<String, Value>, key: &str, text: &str) -> bool {
    if key.is_empty() {
        return false;
    }
    params.insert(key.to_owned(), Value::String(text.to_owned()));
    true
}

/// Performs UI render param map.
///
/// # Parameters
///
/// - `id`: Input consumed by [`crate::runtime::ui::ui_render_param_map`].
/// - `input_type`: Input consumed by [`crate::runtime::ui::ui_render_param_map`].
/// - `button_type`: Input consumed by [`crate::runtime::ui::ui_render_param_map`].
/// - `name`: Input consumed by [`crate::runtime::ui::ui_render_param_map`].
/// - `label`: Input consumed by [`crate::runtime::ui::ui_render_param_map`].
/// - `label_html`: Input consumed by [`crate::runtime::ui::ui_render_param_map`].
/// - `value`: Input consumed by [`crate::runtime::ui::ui_render_param_map`].
/// - `class_name`: Input consumed by [`crate::runtime::ui::ui_render_param_map`].
/// - `label_class`: Input consumed by [`crate::runtime::ui::ui_render_param_map`].
/// - `attributes_html`: Input consumed by [`crate::runtime::ui::ui_render_param_map`].
/// - `options_html`: Input consumed by [`crate::runtime::ui::ui_render_param_map`].
/// - `help_html`: Input consumed by [`crate::runtime::ui::ui_render_param_map`].
/// - `content_html`: Input consumed by [`crate::runtime::ui::ui_render_param_map`].
/// - `element_type`: Input consumed by [`crate::runtime::ui::ui_render_param_map`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::ui::ui_render_param_map`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_render_param_map(todo!(), todo!(), todo!(), "name", todo!(), todo!(), "value", todo!(), todo!(), todo!(), todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_render_param_map(
    id: &str,
    input_type: Option<&str>,
    button_type: Option<&str>,
    name: &str,
    label: &str,
    label_html: &str,
    value: &str,
    class_name: Option<&str>,
    label_class: Option<&str>,
    attributes_html: &str,
    options_html: &str,
    help_html: &str,
    content_html: &str,
    element_type: &str,
) -> Option<Map<String, Value>> {
    if id.is_empty() || name.is_empty() || label.is_empty() || element_type.is_empty() {
        return None;
    }
    let mut params = Map::new();
    let resolved_class_name = class_name.unwrap_or(if element_type == "button" {
        ""
    } else {
        "form-control"
    });
    let resolved_label_class = label_class.unwrap_or("");
    ADD_UI_PARAM(&mut params, "id", id).then_some(())?;
    ADD_UI_PARAM(&mut params, "input_type", input_type.unwrap_or("text")).then_some(())?;
    ADD_UI_PARAM(&mut params, "button_type", button_type.unwrap_or("button")).then_some(())?;
    ADD_UI_PARAM(&mut params, "name", name).then_some(())?;
    ADD_UI_PARAM(&mut params, "label", label).then_some(())?;
    ADD_UI_PARAM(&mut params, "label_html", label_html).then_some(())?;
    ADD_UI_PARAM(&mut params, "value", value).then_some(())?;
    ADD_UI_PARAM(&mut params, "class_name", resolved_class_name).then_some(())?;
    ADD_UI_PARAM(&mut params, "label_class", resolved_label_class).then_some(())?;
    ADD_UI_PARAM(&mut params, "attributes_html", attributes_html).then_some(())?;
    ADD_UI_PARAM(&mut params, "options_html", options_html).then_some(())?;
    ADD_UI_PARAM(&mut params, "help_html", help_html).then_some(())?;
    ADD_UI_PARAM(&mut params, "content_html", content_html).then_some(())?;
    Some(params)
}

const UI_BUFFER_LIMIT: usize = 2 * 1024 * 1024;
const UI_IDENTIFIER_LIMIT: usize = 128;

/// Performs HTML escape.
fn html_escape(value: &str) -> String {
    value
        .replace('&', "&amp;")
        .replace('<', "&lt;")
        .replace('>', "&gt;")
        .replace('"', "&quot;")
        .replace('\'', "&#39;")
}

/// Appends a bounded slice to a canonical UI buffer.
///
/// # Parameters
///
/// - `buffer`: Input consumed by [`crate::runtime::ui::ui_buffer_append_n`].
/// - `text`: Input consumed by [`crate::runtime::ui::ui_buffer_append_n`].
/// - `length`: Input consumed by [`crate::runtime::ui::ui_buffer_append_n`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::ui::ui_buffer_append_n`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_buffer_append_n(&mut [], "{}", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_buffer_append_n(buffer: &mut String, text: &str, length: usize) -> bool {
    let Some(end) = length.checked_add(0) else {
        return false;
    };
    let Some(fragment) = text.get(..end.min(text.len())) else {
        return false;
    };
    if buffer.len().saturating_add(fragment.len()) > UI_BUFFER_LIMIT {
        return false;
    }
    buffer.push_str(fragment);
    true
}

/// Appends one complete canonical UI fragment to a bounded buffer.
///
/// # Parameters
///
/// - `buffer`: Input consumed by [`crate::runtime::ui::ui_buffer_append`].
/// - `text`: Input consumed by [`crate::runtime::ui::ui_buffer_append`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::ui::ui_buffer_append`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_buffer_append(&mut [], "{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_buffer_append(buffer: &mut String, text: &str) -> bool {
    ui_buffer_append_n(buffer, text, text.len())
}

/// Takes ownership of a canonical UI buffer and leaves it empty.
///
/// # Parameters
///
/// - `buffer`: Input consumed by [`crate::runtime::ui::ui_buffer_take`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::ui::ui_buffer_take`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_buffer_take(&mut []);
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_buffer_take(buffer: &mut String) -> Option<String> {
    (!buffer.is_empty()).then(|| std::mem::take(buffer))
}

/// Validates an identifier used by the canonical UI ledger.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::ui::ui_identifier_valid`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::ui::ui_identifier_valid`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::ui::ui_identifier_valid`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_identifier_valid("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_identifier_valid(value: &str) -> bool {
    !value.is_empty()
        && value.len() <= UI_IDENTIFIER_LIMIT
        && value
            .bytes()
            .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'_' | b'-'))
        && value.as_bytes()[0].is_ascii_alphabetic()
}

/// Restricts input widgets to the HTML types supported by the declarative contract.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::ui::ui_input_type_allowed`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::ui::ui_input_type_allowed`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_input_type_allowed("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_input_type_allowed(value: &str) -> bool {
    matches!(
        value,
        "text"
            | "email"
            | "password"
            | "number"
            | "date"
            | "time"
            | "url"
            | "tel"
            | "search"
            | "hidden"
    )
}

/// Validates an app-relative fragment path and rejects traversal or control bytes.
///
/// # Parameters
///
/// - `relative`: Input consumed by [`crate::runtime::ui::ui_fragment_path_valid`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::ui::ui_fragment_path_valid`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::ui::ui_fragment_path_valid`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_fragment_path_valid(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_fragment_path_valid(relative: &str) -> bool {
    !relative.is_empty()
        && relative.len() <= 512
        && !relative.starts_with('/')
        && !relative.contains("..")
        && !relative.bytes().any(|byte| byte < 0x20 || byte == 0x7f)
}

/// Resolves a validated app-relative UI path while preserving containment.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::ui::ui_path`].
/// - `relative`: Input consumed by [`crate::runtime::ui::ui_path`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::ui::ui_path`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_path(std::path::Path::new("apps/dev_docs"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_path(app_root: &str, relative: &str) -> Option<String> {
    if app_root.is_empty() || !ui_fragment_path_valid(relative) {
        return None;
    }
    let root = Path::new(app_root).canonicalize().ok()?;
    let candidate = root.join(relative);
    let resolved = candidate.canonicalize().ok()?;
    resolved
        .starts_with(&root)
        .then(|| resolved.to_string_lossy().into_owned())
}

/// Identifies shared framework fragments.
///
/// # Parameters
///
/// - `relative`: Input consumed by [`crate::runtime::ui::ui_shared_asset_fragment`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::ui::ui_shared_asset_fragment`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_shared_asset_fragment(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_shared_asset_fragment(relative: &str) -> bool {
    relative.starts_with("templates/shared/") && ui_fragment_path_valid(relative)
}

/// Resolves a shared framework fragment under the app root.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::ui::ui_shared_asset_path`].
/// - `relative`: Input consumed by [`crate::runtime::ui::ui_shared_asset_path`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::ui::ui_shared_asset_path`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_shared_asset_path(std::path::Path::new("apps/dev_docs"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_shared_asset_path(app_root: &str, relative: &str) -> Option<String> {
    ui_shared_asset_fragment(relative)
        .then(|| ui_path(app_root, relative))
        .flatten()
}

/// Appends HTML-escaped attribute text to a canonical buffer.
///
/// # Parameters
///
/// - `buffer`: Input consumed by [`crate::runtime::ui::ui_append_attr_escaped`].
/// - `value`: Input consumed by [`crate::runtime::ui::ui_append_attr_escaped`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::ui::ui_append_attr_escaped`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_append_attr_escaped(&mut [], "value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_append_attr_escaped(buffer: &mut String, value: &str) -> bool {
    ui_buffer_append(buffer, &html_escape(value))
}

/// Builds one optional escaped HTML attribute.
///
/// # Parameters
///
/// - `attribute`: Input consumed by [`crate::runtime::ui::ui_optional_attribute`].
/// - `value`: Input consumed by [`crate::runtime::ui::ui_optional_attribute`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::ui::ui_optional_attribute`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_optional_attribute(todo!(), "value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_optional_attribute(attribute: &str, value: Option<&str>) -> Option<String> {
    if attribute.is_empty() || !ui_identifier_valid(attribute) {
        return None;
    }
    value
        .filter(|text| !text.is_empty())
        .map(|text| format!(" {attribute}=\"{}\"", html_escape(text)))
}

/// Appends a boolean HTML attribute when enabled.
///
/// # Parameters
///
/// - `buffer`: Input consumed by [`crate::runtime::ui::ui_append_boolean_attribute`].
/// - `attribute`: Input consumed by [`crate::runtime::ui::ui_append_boolean_attribute`].
/// - `enabled`: Input consumed by [`crate::runtime::ui::ui_append_boolean_attribute`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::ui::ui_append_boolean_attribute`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_append_boolean_attribute(&mut [], todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_append_boolean_attribute(buffer: &mut String, attribute: &str, enabled: bool) -> bool {
    if !enabled {
        return true;
    }
    if attribute.is_empty() || !ui_identifier_valid(attribute) {
        return false;
    }
    ui_buffer_append(buffer, &format!(" {attribute}"))
}

/// Rejects event literals that could inject markup or script.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::ui::ui_event_literal_allowed`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::ui::ui_event_literal_allowed`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::ui::ui_event_literal_allowed`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_event_literal_allowed("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_event_literal_allowed(value: &str) -> bool {
    !value.is_empty()
        && value.len() <= 256
        && !value
            .chars()
            .any(|ch| ch.is_control() || matches!(ch, '<' | '>' | '"' | '\''))
}

/// Performs value text.
fn value_text(value: Option<&Value>) -> String {
    match value {
        Some(Value::String(text)) => text.clone(),
        Some(Value::Bool(value)) => value.to_string(),
        Some(Value::Number(value)) => value.to_string(),
        Some(Value::Null) | None => String::new(),
        Some(value) => serde_json::to_string(value).unwrap_or_default(),
    }
}

/// Performs resolved value.
fn resolved_value<'a>(value: Option<&'a Value>, params: &'a Value) -> Option<&'a Value> {
    match value {
        Some(Value::String(text)) if text.starts_with("{") && text.ends_with('}') => {
            params.get(&text[1..text.len() - 1])
        }
        other => other,
    }
}

/// Resolves a trusted HTML value from a declaration or page parameters.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::ui::ui_resolved_trusted_html`].
/// - `params`: Input consumed by [`crate::runtime::ui::ui_resolved_trusted_html`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::ui::ui_resolved_trusted_html`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_resolved_trusted_html("value", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_resolved_trusted_html<'a>(value: Option<&'a Value>, params: &'a Value) -> Option<String> {
    resolved_value(value, params)
        .and_then(Value::as_str)
        .map(ToOwned::to_owned)
}

/// Expands bounded parameter placeholders without executing authored code.
///
/// # Parameters
///
/// - `template_text`: Input consumed by [`crate::runtime::ui::ui_render_mutable_params`].
/// - `params`: Input consumed by [`crate::runtime::ui::ui_render_mutable_params`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::ui::ui_render_mutable_params`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::ui::ui_render_mutable_params`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_render_mutable_params(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_render_mutable_params(template_text: &str, params: &Value) -> Option<String> {
    let object = params.as_object()?;
    let mut output = String::with_capacity(template_text.len());
    let mut cursor = 0usize;
    while let Some(offset) = template_text[cursor..].find('{') {
        let open = cursor + offset;
        output.push_str(&template_text[cursor..open]);
        let close = template_text[open + 1..].find('}')? + open + 1;
        let key = &template_text[open + 1..close];
        let value = object
            .get(key)
            .map(|value| value_text(Some(value)))
            .unwrap_or_default();
        output.push_str(&html_escape(&value));
        cursor = close + 1;
    }
    output.push_str(&template_text[cursor..]);
    (output.len() <= UI_BUFFER_LIMIT).then_some(output)
}

/// Loads and renders one validated app fragment.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::ui::ui_render_fragment`].
/// - `relative`: Input consumed by [`crate::runtime::ui::ui_render_fragment`].
/// - `params`: Input consumed by [`crate::runtime::ui::ui_render_fragment`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::ui::ui_render_fragment`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::ui::ui_render_fragment`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_render_fragment(std::path::Path::new("apps/dev_docs"), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_render_fragment(app_root: &str, relative: &str, params: &Value) -> Option<String> {
    let path = if ui_shared_asset_fragment(relative) {
        ui_shared_asset_path(app_root, relative)
    } else {
        ui_path(app_root, relative)
    }?;
    ui_render_mutable_params(&fs::read_to_string(path).ok()?, params)
}

/// Converts one scalar value to its canonical display text.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::ui::ui_scalar_text`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::ui::ui_scalar_text`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_scalar_text("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_scalar_text(value: Option<&Value>) -> String {
    value_text(value)
}

/// Resolves a string value through page parameters.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::ui::ui_resolved_string`].
/// - `params`: Input consumed by [`crate::runtime::ui::ui_resolved_string`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::ui::ui_resolved_string`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_resolved_string("value", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_resolved_string(value: Option<&Value>, params: &Value) -> String {
    value_text(resolved_value(value, params))
}

/// Interpolates `{key}` placeholders in a scalar string.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::ui::ui_interpolated_string`].
/// - `params`: Input consumed by [`crate::runtime::ui::ui_interpolated_string`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::ui::ui_interpolated_string`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_interpolated_string("value", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_interpolated_string(value: Option<&Value>, params: &Value) -> Option<String> {
    ui_render_mutable_params(value?.as_str()?, params)
}

/// Resolves a boolean value through page parameters.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::ui::ui_resolved_bool`].
/// - `params`: Input consumed by [`crate::runtime::ui::ui_resolved_bool`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::ui::ui_resolved_bool`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_resolved_bool("value", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_resolved_bool(value: Option<&Value>, params: &Value) -> bool {
    match resolved_value(value, params) {
        Some(Value::Bool(value)) => *value,
        Some(Value::String(value)) => matches!(value.as_str(), "true" | "1" | "yes" | "on"),
        Some(Value::Number(value)) => value.as_i64().is_some_and(|number| number != 0),
        _ => false,
    }
}

/// Finds fragment value.
fn find_fragment_value<'a>(root: &'a Value, id: &str) -> Option<&'a Value> {
    root.get("elements")
        .and_then(Value::as_array)?
        .iter()
        .find(|item| item.get("id").and_then(Value::as_str) == Some(id))
}

/// Renders choice options from a declarative array.
///
/// # Parameters
///
/// - `options`: Input consumed by [`crate::runtime::ui::ui_render_options`].
/// - `params`: Input consumed by [`crate::runtime::ui::ui_render_options`].
/// - `selected`: Input consumed by [`crate::runtime::ui::ui_render_options`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::ui::ui_render_options`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::ui::ui_render_options`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_render_options(todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_render_options(
    options: Option<&Value>,
    params: &Value,
    selected: &str,
) -> Option<String> {
    let mut output = String::new();
    for option in options?.as_array()? {
        let value = ui_resolved_string(option.get("value"), params);
        let label = ui_resolved_string(option.get("label"), params);
        let selected_attr = if value == selected { " selected" } else { "" };
        if !ui_buffer_append(
            &mut output,
            &format!(
                "<option value=\"{}\"{}>{}</option>",
                html_escape(&value),
                selected_attr,
                html_escape(&label)
            ),
        ) {
            return None;
        }
    }
    Some(output)
}

/// Renders escaped help copy as a fragment.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::ui::ui_render_help`].
/// - `help`: Input consumed by [`crate::runtime::ui::ui_render_help`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::ui::ui_render_help`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_render_help(std::path::Path::new("apps/dev_docs"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_render_help(app_root: &str, help: &str) -> Option<String> {
    if help.is_empty() {
        return Some(String::new());
    }
    let relative = help.strip_prefix("fragment:").unwrap_or(help);
    if relative != help {
        ui_render_fragment(app_root, relative, &Value::Object(Map::new()))
    } else {
        Some(format!(
            "<small class=\"form-text\">{}</small>",
            html_escape(help)
        ))
    }
}

/// Finds a canonical UI declaration by identifier.
///
/// # Parameters
///
/// - `ledger_root`: Input consumed by [`crate::runtime::ui::ui_find_element`].
/// - `canonical_id`: Input consumed by [`crate::runtime::ui::ui_find_element`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::ui::ui_find_element`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_find_element(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_find_element<'a>(ledger_root: &'a Value, canonical_id: &str) -> Option<&'a Value> {
    find_fragment_value(ledger_root, canonical_id)
}

/// Duplicates one scalar display value after parameter resolution.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::ui::ui_scalar_dup`].
/// - `params`: Input consumed by [`crate::runtime::ui::ui_scalar_dup`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::ui::ui_scalar_dup`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_scalar_dup("value", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_scalar_dup(value: Option<&Value>, params: &Value) -> Option<String> {
    Some(ui_resolved_string(value, params))
}

/// Renders a declared fragment with page parameters.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::ui::ui_render_page_params_fragment`].
/// - `field`: Input consumed by [`crate::runtime::ui::ui_render_page_params_fragment`].
/// - `params`: Input consumed by [`crate::runtime::ui::ui_render_page_params_fragment`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::ui::ui_render_page_params_fragment`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_render_page_params_fragment(std::path::Path::new("apps/dev_docs"), "field", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_render_page_params_fragment(
    app_root: &str,
    field: &Value,
    params: &Value,
) -> Option<String> {
    let relative = field
        .get("path")
        .or_else(|| field.get("fragment"))
        .and_then(Value::as_str)?;
    ui_render_fragment(app_root, relative, params)
}

/// Adds a ledger-backed attribute after resolving its value.
///
/// # Parameters
///
/// - `buffer`: Input consumed by [`crate::runtime::ui::ui_append_ledger_attribute`].
/// - `element`: Input consumed by [`crate::runtime::ui::ui_append_ledger_attribute`].
/// - `key`: Input consumed by [`crate::runtime::ui::ui_append_ledger_attribute`].
/// - `attribute`: Input consumed by [`crate::runtime::ui::ui_append_ledger_attribute`].
/// - `params`: Input consumed by [`crate::runtime::ui::ui_append_ledger_attribute`].
/// - `event_policy`: Input consumed by [`crate::runtime::ui::ui_append_ledger_attribute`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::ui::ui_append_ledger_attribute`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_append_ledger_attribute(&mut [], todo!(), "key", todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_append_ledger_attribute(
    buffer: &mut String,
    element: &Value,
    key: &str,
    attribute: &str,
    params: &Value,
    event_policy: bool,
) -> bool {
    let value = ui_resolved_string(element.get(key), params);
    if value.is_empty() {
        return true;
    }
    if event_policy && !ui_event_literal_allowed(&value) {
        return false;
    }
    ui_buffer_append(buffer, &format!(" {attribute}=\"{}\"", html_escape(&value)))
}

/// Validates structured data and HTMX attribute keys.
///
/// # Parameters
///
/// - `group`: Input consumed by [`crate::runtime::ui::ui_structured_key_allowed`].
/// - `key`: Input consumed by [`crate::runtime::ui::ui_structured_key_allowed`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::ui::ui_structured_key_allowed`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_structured_key_allowed(todo!(), "key");
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_structured_key_allowed(group: &str, key: &str) -> bool {
    matches!(group, "data" | "hx") && ui_identifier_valid(key)
}

/// Appends a structured attribute group from a declaration.
///
/// # Parameters
///
/// - `buffer`: Input consumed by [`crate::runtime::ui::ui_append_structured_attributes`].
/// - `element`: Input consumed by [`crate::runtime::ui::ui_append_structured_attributes`].
/// - `group`: Input consumed by [`crate::runtime::ui::ui_append_structured_attributes`].
/// - `params`: Input consumed by [`crate::runtime::ui::ui_append_structured_attributes`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::ui::ui_append_structured_attributes`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::ui::ui_append_structured_attributes`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_append_structured_attributes(&mut [], todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_append_structured_attributes(
    buffer: &mut String,
    element: &Value,
    group: &str,
    params: &Value,
) -> bool {
    let Some(values) = element.get(group).and_then(Value::as_object) else {
        return true;
    };
    for (key, value) in values {
        if !ui_structured_key_allowed(group, key)
            || !ui_append_ledger_attribute(
                buffer,
                &Value::Object(Map::from_iter([(key.clone(), value.clone())])),
                key,
                &format!("{group}-{key}"),
                params,
                group == "hx",
            )
        {
            return false;
        }
    }
    true
}

/// Renders a choice group as safe option or radio markup.
///
/// # Parameters
///
/// - `_app_root`: Input consumed by [`crate::runtime::ui::ui_render_choice_options`].
/// - `element`: Input consumed by [`crate::runtime::ui::ui_render_choice_options`].
/// - `params`: Input consumed by [`crate::runtime::ui::ui_render_choice_options`].
/// - `group_name`: Input consumed by [`crate::runtime::ui::ui_render_choice_options`].
/// - `group_id`: Input consumed by [`crate::runtime::ui::ui_render_choice_options`].
/// - `radio_mode`: Input consumed by [`crate::runtime::ui::ui_render_choice_options`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::ui::ui_render_choice_options`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::ui::ui_render_choice_options`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_render_choice_options(todo!(), todo!(), todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_render_choice_options(
    _app_root: &str,
    element: &Value,
    params: &Value,
    group_name: &str,
    group_id: &str,
    radio_mode: bool,
) -> Option<String> {
    let options = element.get("options")?.as_array()?;
    let selected = ui_resolved_string(element.get("value"), params);
    let mut output = String::new();
    for option in options {
        let value = ui_resolved_string(option.get("value"), params);
        let label = ui_resolved_string(option.get("label"), params);
        if radio_mode {
            output.push_str(&format!(
                "<label><input type=\"radio\" name=\"{}\" value=\"{}\"{}> {}</label>",
                html_escape(group_name),
                html_escape(&value),
                if value == selected { " checked" } else { "" },
                html_escape(&label)
            ));
        } else {
            output.push_str(&format!(
                "<option value=\"{}\"{}>{}</option>",
                html_escape(&value),
                if value == selected { " selected" } else { "" },
                html_escape(&label)
            ));
        }
    }
    (!group_id.is_empty()).then_some(output)
}

/// Renders a button row from a declaration.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::ui::ui_render_button_row`].
/// - `element`: Input consumed by [`crate::runtime::ui::ui_render_button_row`].
/// - `params`: Input consumed by [`crate::runtime::ui::ui_render_button_row`].
/// - `group_id`: Input consumed by [`crate::runtime::ui::ui_render_button_row`].
/// - `class_name`: Input consumed by [`crate::runtime::ui::ui_render_button_row`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::ui::ui_render_button_row`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::ui::ui_render_button_row`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_render_button_row(std::path::Path::new("apps/dev_docs"), todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_render_button_row(
    app_root: &str,
    element: &Value,
    params: &Value,
    group_id: &str,
    class_name: &str,
) -> Option<String> {
    let buttons = element.get("buttons")?.as_array()?;
    let mut output = format!(
        "<div id=\"{}\" class=\"{}\">",
        html_escape(group_id),
        html_escape(class_name)
    );
    for button in buttons {
        let label = ui_resolved_string(button.get("label"), params);
        let path = ui_resolved_string(button.get("path"), params);
        if !ui_event_literal_allowed(&path) {
            return None;
        }
        output.push_str(&format!(
            "<a href=\"{}\">{}</a>",
            html_escape(&path),
            html_escape(&label)
        ));
    }
    output.push_str("</div>");
    let _ = app_root;
    Some(output)
}

/// Renders one complete declaration using the canonical UI contract.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::ui::ui_render_declaration_html`].
/// - `element`: Input consumed by [`crate::runtime::ui::ui_render_declaration_html`].
/// - `params`: Input consumed by [`crate::runtime::ui::ui_render_declaration_html`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::ui::ui_render_declaration_html`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_render_declaration_html(std::path::Path::new("apps/dev_docs"), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_render_declaration_html(
    app_root: &str,
    element: &Value,
    params: &Value,
) -> Option<String> {
    let element_type = element
        .get("element_type")
        .or_else(|| element.get("type"))
        .and_then(Value::as_str)?;
    let id = element.get("id").and_then(Value::as_str)?;
    if !ui_identifier_valid(id) {
        return None;
    }
    if element_type == "button_row" {
        return ui_render_button_row(
            app_root,
            element,
            params,
            id,
            element
                .get("class")
                .and_then(Value::as_str)
                .unwrap_or("ui-button-row"),
        );
    }
    let name = element.get("name").and_then(Value::as_str).unwrap_or(id);
    let label = ui_resolved_string(element.get("label"), params);
    let value = ui_resolved_string(element.get("value"), params);
    let input_type = element
        .get("input_type")
        .and_then(Value::as_str)
        .unwrap_or("text");
    if element_type == "input" && !ui_input_type_allowed(input_type) {
        return None;
    }
    let mut attrs = format!(
        " id=\"{}\" name=\"{}\" type=\"{}\" value=\"{}\"",
        html_escape(id),
        html_escape(name),
        html_escape(input_type),
        html_escape(&value)
    );
    let mut attr_buffer = String::new();
    if !ui_append_structured_attributes(&mut attr_buffer, element, "data", params)
        || !ui_append_structured_attributes(&mut attr_buffer, element, "hx", params)
    {
        return None;
    }
    attrs.push_str(&attr_buffer);
    Some(format!(
        "<label for=\"{}\">{}</label><input{}>",
        html_escape(id),
        html_escape(&label),
        attrs
    ))
}

/// Loads a UI ledger JSON document from an app root.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::ui::ui_load_ledger`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::ui::ui_load_ledger`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::ui::ui_load_ledger`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_load_ledger(std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_load_ledger(app_root: &str) -> Option<Value> {
    let path = PathBuf::from(app_root).join("data/contracts/canonical-ui.json");
    serde_json::from_str(&fs::read_to_string(path).ok()?).ok()
}

/// Computes a validated placeholder identifier.
///
/// # Parameters
///
/// - `name`: Input consumed by [`crate::runtime::ui::ui_placeholder_id`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::ui::ui_placeholder_id`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_placeholder_id("name");
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_placeholder_id(name: &str) -> Option<String> {
    let name = name.trim();
    ui_identifier_valid(name).then(|| name.to_owned())
}

/// Renders a page template after ledger declarations are resolved.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::ui::ui_render_page_file`].
/// - `template_file`: Input consumed by [`crate::runtime::ui::ui_render_page_file`].
/// - `page_params`: Input consumed by [`crate::runtime::ui::ui_render_page_file`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::ui::ui_render_page_file`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::ui::ui_render_page_file`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_render_page_file(std::path::Path::new("apps/dev_docs"), std::path::Path::new("template.html"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_render_page_file(
    app_root: &str,
    template_file: &str,
    page_params: &Value,
) -> Option<String> {
    let template_path = ui_path(app_root, template_file)?;
    let template = fs::read_to_string(template_path).ok()?;
    ui_render_mutable_params(&template, page_params)
}

/// Builds the validated attribute string for one UI declaration.
///
/// # Parameters
///
/// - `element`: Input consumed by [`crate::runtime::ui::ui_declaration_attributes`].
/// - `params`: Input consumed by [`crate::runtime::ui::ui_declaration_attributes`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::ui::ui_declaration_attributes`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::ui::ui_declaration_attributes`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::ui::ui_declaration_attributes(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::ui`] for adjacent helpers that share the same runtime surface.
pub fn ui_declaration_attributes(element: &Value, params: &Value) -> Option<String> {
    let mut output = String::new();
    for (key, attribute, event_policy) in [
        ("placeholder", "placeholder", false),
        ("aria_label", "aria-label", false),
        ("hx_get", "hx-get", true),
        ("hx_post", "hx-post", true),
    ] {
        if !ui_append_ledger_attribute(&mut output, element, key, attribute, params, event_policy) {
            return None;
        }
    }
    if !ui_append_boolean_attribute(
        &mut output,
        "required",
        ui_resolved_bool(element.get("required"), params),
    ) || !ui_append_boolean_attribute(
        &mut output,
        "checked",
        ui_resolved_bool(element.get("checked"), params),
    ) {
        return None;
    }
    Some(output)
}