rustial_engine/

style_json.rs

#![cfg(feature = "style-json")]

//! JSON style-spec parsing and resolution for the style runtime.
//!
//! This module adds a declarative style-document layer closer to MapLibre's
//! `style/style.ts`: JSON source and layer definitions are parsed into a
//! lightweight spec and then resolved through a host-provided runtime source
//! registry into an executable [`StyleDocument`](crate::style::StyleDocument).

use crate::style::{
    BackgroundStyleLayer, CircleStyleLayer, FillExtrusionStyleLayer, FillStyleLayer,
    HeatmapStyleLayer, HillshadeStyleLayer, LineStyleLayer, ModelStyleLayer, RasterStyleLayer,
    StyleDocument, StyleError, StyleLayer, StyleLayerMeta, StyleProjection, StyleSource, StyleSourceId,
    StyleSourceKind, StyleValue, SymbolStyleLayer, VectorStyleLayer,
};
use crate::symbols::{
    SymbolAnchor, SymbolIconTextFit, SymbolPlacement, SymbolTextJustify, SymbolTextTransform,
    SymbolWritingMode,
};
use serde::{Deserialize, Serialize};
use serde_json::{Map, Value};
use std::collections::HashMap;
use std::fmt;

/// Errors produced while parsing or resolving a JSON style specification.
#[derive(Debug)]
pub enum StyleSpecError {
    /// Failed to parse JSON.
    Json(serde_json::Error),
    /// A style source required by the JSON spec has no runtime binding.
    MissingRuntimeSource(String),
    /// The runtime binding for a source does not match the declared source kind.
    RuntimeSourceKindMismatch {
        /// Source id being resolved.
        source_id: String,
        /// Declared spec kind.
        declared: StyleSourceKind,
        /// Actual bound runtime kind.
        actual: StyleSourceKind,
    },
    /// A layer references a source but omits the `source` field.
    MissingLayerSource(String),
    /// A JSON field had the wrong shape.
    InvalidField {
        /// Layer or source id for diagnostics.
        id: String,
        /// Field name.
        field: &'static str,
        /// Human-readable expectation.
        expected: &'static str,
    },
    /// The runtime style document rejected the resolved document.
    Runtime(StyleError),
}

impl fmt::Display for StyleSpecError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            StyleSpecError::Json(err) => write!(f, "style JSON parse error: {err}"),
            StyleSpecError::MissingRuntimeSource(id) => {
                write!(f, "missing runtime source binding for style source `{id}`")
            }
            StyleSpecError::RuntimeSourceKindMismatch {
                source_id,
                declared,
                actual,
            } => write!(
                f,
                "runtime source `{source_id}` kind mismatch: declared `{}`, bound `{}`",
                declared.as_str(),
                actual.as_str()
            ),
            StyleSpecError::MissingLayerSource(id) => {
                write!(f, "style layer `{id}` requires a `source` field")
            }
            StyleSpecError::InvalidField { id, field, expected } => {
                write!(f, "invalid field `{field}` in `{id}`, expected {expected}")
            }
            StyleSpecError::Runtime(err) => err.fmt(f),
        }
    }
}

impl std::error::Error for StyleSpecError {}

impl From<serde_json::Error> for StyleSpecError {
    fn from(value: serde_json::Error) -> Self {
        Self::Json(value)
    }
}

impl From<StyleError> for StyleSpecError {
    fn from(value: StyleError) -> Self {
        Self::Runtime(value)
    }
}

/// Declarative JSON style document.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct StyleSpecDocument {
    /// Style-spec version.
    #[serde(default = "default_style_version")]
    pub version: u8,
    /// Optional human-readable style name.
    #[serde(default)]
    pub name: Option<String>,
    /// Declared source definitions.
    #[serde(default)]
    pub sources: HashMap<StyleSourceId, StyleSpecSource>,
    /// Ordered layer definitions.
    #[serde(default)]
    pub layers: Vec<StyleSpecLayer>,
    /// Optional terrain configuration.
    #[serde(default)]
    pub terrain: Option<StyleSpecTerrain>,
    /// Optional top-level projection configuration.
    #[serde(default)]
    pub projection: Option<StyleSpecProjection>,
}

impl StyleSpecDocument {
    /// Parse a JSON style string.
    pub fn from_json(json: &str) -> Result<Self, StyleSpecError> {
        Ok(serde_json::from_str(json)?)
    }

    /// Resolve the declarative style into a runtime [`StyleDocument`].
    pub fn resolve(&self, registry: &StyleSourceRegistry) -> Result<StyleDocument, StyleSpecError> {
        let mut document = StyleDocument::new();

        for (id, source_spec) in &self.sources {
            let runtime = registry
                .source(id)
                .ok_or_else(|| StyleSpecError::MissingRuntimeSource(id.to_string()))?;
            if runtime.kind() != source_spec.source_type.runtime_kind() {
                return Err(StyleSpecError::RuntimeSourceKindMismatch {
                    source_id: id.to_string(),
                    declared: source_spec.source_type.runtime_kind(),
                    actual: runtime.kind(),
                });
            }
            document.add_source(id.clone(), runtime.clone())?;
        }

        if let Some(terrain) = &self.terrain {
            document.set_terrain_source(Some(terrain.source.clone()));
        }

        if let Some(projection) = &self.projection {
            document.set_projection(projection.projection_type.runtime_projection());
        }

        for layer in &self.layers {
            document.add_layer(layer.to_runtime_layer()?)?;
        }

        Ok(document)
    }
}

/// Runtime source registry used while resolving JSON specs.
#[derive(Debug, Clone, Default)]
pub struct StyleSourceRegistry {
    sources: HashMap<StyleSourceId, StyleSource>,
}

impl StyleSourceRegistry {
    /// Create an empty source registry.
    pub fn new() -> Self {
        Self::default()
    }

    /// Register or replace a runtime source binding.
    pub fn set_source(&mut self, id: impl Into<String>, source: StyleSource) {
        self.sources.insert(id.into(), source);
    }

    /// Look up a bound source.
    pub fn source(&self, id: &str) -> Option<&StyleSource> {
        self.sources.get(id)
    }

    /// Resolve a parsed spec document into a runtime style document.
    pub fn resolve_document(&self, spec: &StyleSpecDocument) -> Result<StyleDocument, StyleSpecError> {
        spec.resolve(self)
    }
}

/// Top-level terrain entry in a JSON style spec.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct StyleSpecTerrain {
    /// Source id referenced by the terrain configuration.
    pub source: StyleSourceId,
}

/// Top-level projection entry in a JSON style spec.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct StyleSpecProjection {
    /// Projection type.
    #[serde(rename = "type")]
    pub projection_type: StyleSpecProjectionType,
}

/// Projection kinds accepted by the current JSON style spec.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum StyleSpecProjectionType {
    /// Web Mercator projection.
    #[serde(rename = "mercator")]
    Mercator,
    /// Equirectangular planar projection.
    #[serde(rename = "equirectangular")]
    Equirectangular,
    /// Globe / geocentric projection.
    #[serde(rename = "globe")]
    Globe,
    /// Near-sided vertical perspective projection.
    #[serde(rename = "vertical-perspective")]
    VerticalPerspective,
}

impl StyleSpecProjectionType {
    fn runtime_projection(self) -> StyleProjection {
        match self {
            StyleSpecProjectionType::Mercator => StyleProjection::Mercator,
            StyleSpecProjectionType::Equirectangular => StyleProjection::Equirectangular,
            StyleSpecProjectionType::Globe => StyleProjection::Globe,
            StyleSpecProjectionType::VerticalPerspective => StyleProjection::VerticalPerspective,
        }
    }
}

/// Source kinds accepted by the JSON style spec.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum StyleSpecSourceType {
    /// Raster tile source.
    #[serde(rename = "raster")]
    Raster,
    /// Raster DEM / terrain source.
    #[serde(rename = "raster-dem")]
    RasterDem,
    /// GeoJSON source.
    #[serde(rename = "geojson")]
    GeoJson,
    /// Vector-tile-like source.
    #[serde(rename = "vector")]
    Vector,
    /// Image source.
    #[serde(rename = "image")]
    Image,
    /// Video source.
    #[serde(rename = "video")]
    Video,
    /// Canvas source.
    #[serde(rename = "canvas")]
    Canvas,
    /// Model source.
    #[serde(rename = "model")]
    Model,
}

impl StyleSpecSourceType {
    fn runtime_kind(self) -> StyleSourceKind {
        match self {
            StyleSpecSourceType::Raster => StyleSourceKind::Raster,
            StyleSpecSourceType::RasterDem => StyleSourceKind::Terrain,
            StyleSpecSourceType::GeoJson => StyleSourceKind::GeoJson,
            StyleSpecSourceType::Vector => StyleSourceKind::VectorTile,
            StyleSpecSourceType::Image => StyleSourceKind::Image,
            StyleSpecSourceType::Video => StyleSourceKind::Video,
            StyleSpecSourceType::Canvas => StyleSourceKind::Canvas,
            StyleSpecSourceType::Model => StyleSourceKind::Model,
        }
    }
}

/// Declarative source entry.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct StyleSpecSource {
    /// Source type.
    #[serde(rename = "type")]
    pub source_type: StyleSpecSourceType,
    /// Optional URL.
    #[serde(default)]
    pub url: Option<String>,
    /// Optional tile URL templates.
    #[serde(default)]
    pub tiles: Vec<String>,
    /// Optional arbitrary metadata.
    #[serde(default)]
    pub metadata: HashMap<String, Value>,
}

/// Layer kinds accepted by the JSON style spec.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum StyleSpecLayerType {
    #[serde(rename = "background")]
    /// Background style layer entry.
    Background,
    #[serde(rename = "hillshade")]
    /// Hillshade style layer entry.
    Hillshade,
    #[serde(rename = "raster")]
    /// Raster style layer entry.
    Raster,
    #[serde(rename = "vector")]
    /// Generic vector style layer entry.
    Vector,
    #[serde(rename = "fill")]
    /// Fill style layer entry.
    Fill,
    #[serde(rename = "line")]
    /// Line style layer entry.
    Line,
    #[serde(rename = "circle")]
    /// Circle style layer entry.
    Circle,
    #[serde(rename = "heatmap")]
    /// Heatmap style layer entry.
    Heatmap,
    #[serde(rename = "fill-extrusion")]
    /// Fill-extrusion style layer entry.
    FillExtrusion,
    #[serde(rename = "symbol")]
    /// Symbol style layer entry.
    Symbol,
    #[serde(rename = "model")]
    /// Model style layer entry.
    Model,
}

/// Declarative layer entry.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct StyleSpecLayer {
    /// Style layer id.
    pub id: String,
    /// Layer type.
    #[serde(rename = "type")]
    pub layer_type: StyleSpecLayerType,
    /// Optional source id.
    #[serde(default)]
    pub source: Option<StyleSourceId>,
    /// Optional source-layer id for vector-tile-like sources.
    #[serde(default, rename = "source-layer")]
    pub source_layer: Option<String>,
    /// Optional minimum zoom.
    #[serde(default)]
    pub minzoom: Option<f32>,
    /// Optional maximum zoom.
    #[serde(default)]
    pub maxzoom: Option<f32>,
    /// Layout properties.
    #[serde(default)]
    pub layout: Map<String, Value>,
    /// Paint properties.
    #[serde(default)]
    pub paint: Map<String, Value>,
}

impl StyleSpecLayer {
    fn to_runtime_layer(&self) -> Result<StyleLayer, StyleSpecError> {
        let meta = self.meta()?;
        let layer = match self.layer_type {
            StyleSpecLayerType::Background => {
                let mut layer = BackgroundStyleLayer::new(
                    self.id.clone(),
                    paint_color(&self.paint, "background-color")?
                        .unwrap_or_else(|| [0.0, 0.0, 0.0, 1.0].into()),
                );
                layer.meta = meta;
                StyleLayer::Background(layer)
            }
            StyleSpecLayerType::Hillshade => {
                let mut layer = HillshadeStyleLayer::new(self.id.clone());
                layer.meta = meta;
                if let Some(value) = paint_color(&self.paint, "hillshade-highlight-color")? {
                    layer.highlight_color = value;
                }
                if let Some(value) = paint_color(&self.paint, "hillshade-shadow-color")? {
                    layer.shadow_color = value;
                }
                if let Some(value) = paint_color(&self.paint, "hillshade-accent-color")? {
                    layer.accent_color = value;
                }
                if let Some(value) = paint_f32(&self.paint, "hillshade-illumination-direction")? {
                    layer.illumination_direction_deg = value;
                }
                if let Some(value) = paint_f32(&self.paint, "hillshade-illumination-altitude")? {
                    layer.illumination_altitude_deg = value;
                }
                if let Some(value) = paint_f32(&self.paint, "hillshade-exaggeration")? {
                    layer.exaggeration = value;
                }
                StyleLayer::Hillshade(layer)
            }
            StyleSpecLayerType::Raster => {
                let source = self.required_source()?;
                let mut layer = RasterStyleLayer::new(self.id.clone(), source);
                layer.meta = meta;
                StyleLayer::Raster(layer)
            }
            StyleSpecLayerType::Vector => {
                let source = self.required_source()?;
                let mut layer = VectorStyleLayer::new(self.id.clone(), source);
                layer.meta = meta;
                layer.source_layer = self.source_layer.clone();
                if let Some(value) = paint_color(&self.paint, "fill-color")? {
                    layer.fill_color = value;
                }
                if let Some(value) = paint_color(&self.paint, "line-color")? {
                    layer.stroke_color = value;
                }
                if let Some(value) = paint_f32(&self.paint, "line-width")? {
                    layer.stroke_width = value;
                }
                StyleLayer::Vector(layer)
            }
            StyleSpecLayerType::Fill => {
                let source = self.required_source()?;
                let mut layer = FillStyleLayer::new(self.id.clone(), source);
                layer.meta = meta;
                layer.source_layer = self.source_layer.clone();
                if let Some(value) = paint_color(&self.paint, "fill-color")? {
                    layer.fill_color = value;
                }
                if let Some(value) = paint_color(&self.paint, "fill-outline-color")? {
                    layer.outline_color = value;
                }
                if let Some(value) = paint_f32(&self.paint, "fill-outline-width")? {
                    layer.outline_width = value;
                }
                StyleLayer::Fill(layer)
            }
            StyleSpecLayerType::Line => {
                let source = self.required_source()?;
                let mut layer = LineStyleLayer::new(self.id.clone(), source);
                layer.meta = meta;
                layer.source_layer = self.source_layer.clone();
                if let Some(value) = paint_color(&self.paint, "line-color")? {
                    layer.color = value;
                }
                if let Some(value) = paint_f32(&self.paint, "line-width")? {
                    layer.width = value;
                }
                StyleLayer::Line(layer)
            }
            StyleSpecLayerType::Circle => {
                let source = self.required_source()?;
                let mut layer = CircleStyleLayer::new(self.id.clone(), source);
                layer.meta = meta;
                layer.source_layer = self.source_layer.clone();
                if let Some(value) = paint_color(&self.paint, "circle-color")? {
                    layer.color = value;
                }
                if let Some(value) = paint_f32(&self.paint, "circle-radius")? {
                    layer.radius = value;
                }
                if let Some(value) = paint_color(&self.paint, "circle-stroke-color")? {
                    layer.stroke_color = value;
                }
                if let Some(value) = paint_f32(&self.paint, "circle-stroke-width")? {
                    layer.stroke_width = value;
                }
                StyleLayer::Circle(layer)
            }
            StyleSpecLayerType::Heatmap => {
                let source = self.required_source()?;
                let mut layer = HeatmapStyleLayer::new(self.id.clone(), source);
                layer.meta = meta;
                layer.source_layer = self.source_layer.clone();
                if let Some(value) = paint_color(&self.paint, "heatmap-color")? {
                    layer.color = value;
                }
                if let Some(value) = paint_f32(&self.paint, "heatmap-radius")? {
                    layer.radius = value;
                }
                if let Some(value) = paint_f32(&self.paint, "heatmap-intensity")? {
                    layer.intensity = value;
                }
                StyleLayer::Heatmap(layer)
            }
            StyleSpecLayerType::FillExtrusion => {
                let source = self.required_source()?;
                let mut layer = FillExtrusionStyleLayer::new(self.id.clone(), source);
                layer.meta = meta;
                layer.source_layer = self.source_layer.clone();
                if let Some(value) = paint_color(&self.paint, "fill-extrusion-color")? {
                    layer.color = value;
                }
                if let Some(value) = paint_f32(&self.paint, "fill-extrusion-base")? {
                    layer.base = value;
                }
                if let Some(value) = paint_f32(&self.paint, "fill-extrusion-height")? {
                    layer.height = value;
                }
                StyleLayer::FillExtrusion(layer)
            }
            StyleSpecLayerType::Symbol => {
                let source = self.required_source()?;
                let mut layer = SymbolStyleLayer::new(self.id.clone(), source);
                layer.meta = meta;
                layer.source_layer = self.source_layer.clone();
                if let Some(value) = paint_color(&self.paint, "text-color")?
                    .or_else(|| paint_color(&self.paint, "icon-color").ok().flatten())
                {
                    layer.color = value;
                }
                if let Some(value) = paint_color(&self.paint, "text-halo-color")? {
                    layer.halo_color = value;
                }
                if let Some(value) = paint_f32(&self.layout, "text-size")?
                    .or_else(|| paint_f32(&self.layout, "icon-size").ok().flatten())
                {
                    layer.size = value;
                }
                if let Some(value) = string_value(self.layout.get("text-field"))? {
                    layer.text_field = Some(value);
                }
                if let Some(value) = string_value(self.layout.get("icon-image"))? {
                    layer.icon_image = Some(value);
                }
                if let Some(value) = string_value(self.layout.get("text-font")).or_else(|_| first_string_from_array(self.layout.get("text-font")))? {
                    layer.font_stack = value;
                }
                if let Some(value) = paint_f32(&self.layout, "text-padding")? {
                    layer.padding = value;
                }
                if let Some(value) = bool_value(self.layout.get("text-allow-overlap"))? {
                    layer.text_allow_overlap = Some(value);
                }
                if let Some(value) = bool_value(self.layout.get("icon-allow-overlap"))? {
                    layer.icon_allow_overlap = Some(value);
                }
                if let Some(value) = bool_value(self.layout.get("text-optional"))? {
                    layer.text_optional = Some(value);
                }
                if let Some(value) = bool_value(self.layout.get("icon-optional"))? {
                    layer.icon_optional = Some(value);
                }
                if let Some(value) = bool_value(self.layout.get("text-ignore-placement"))? {
                    layer.text_ignore_placement = Some(value);
                }
                if let Some(value) = bool_value(self.layout.get("icon-ignore-placement"))? {
                    layer.icon_ignore_placement = Some(value);
                }
                if let Some(value) = paint_f32(&self.layout, "text-radial-offset")? {
                    layer.radial_offset = Some(value);
                }
                if let Some(value) = symbol_anchor_offset_array(self.layout.get("text-variable-anchor-offset"))? {
                    layer.variable_anchor_offsets = Some(value);
                }
                if let Some(value) = symbol_anchor(self.layout.get("text-anchor"))? {
                    layer.anchor = value;
                }
                if let Some(value) = symbol_text_justify(self.layout.get("text-justify"))? {
                    layer.justify = value;
                }
                if let Some(value) = symbol_text_transform(self.layout.get("text-transform"))? {
                    layer.transform = value;
                }
                if let Some(value) = paint_f32(&self.layout, "text-max-width")? {
                    layer.max_width = Some(value);
                }
                if let Some(value) = paint_f32(&self.layout, "text-line-height")? {
                    layer.line_height = Some(value);
                }
                if let Some(value) = paint_f32(&self.layout, "text-letter-spacing")? {
                    layer.letter_spacing = Some(value);
                }
                if let Some(value) = symbol_icon_text_fit(self.layout.get("icon-text-fit"))? {
                    layer.icon_text_fit = value;
                }
                if let Some(value) = vec4_value(self.layout.get("icon-text-fit-padding"), "icon-text-fit-padding")? {
                    layer.icon_text_fit_padding = value;
                }
                if let Some(value) = paint_f32(&self.layout, "symbol-sort-key")? {
                    layer.sort_key = Some(value);
                }
                if let Some(value) = symbol_placement(self.layout.get("symbol-placement"))? {
                    layer.placement = value;
                }
                if let Some(value) = paint_f32(&self.layout, "symbol-spacing")? {
                    layer.spacing = value;
                }
                if let Some(value) = paint_f32(&self.layout, "text-max-angle")? {
                    layer.max_angle = value;
                }
                if let Some(value) = bool_value(self.layout.get("text-keep-upright"))? {
                    layer.keep_upright = value;
                }
                if let Some(value) = symbol_anchor_array(self.layout.get("text-variable-anchor"))? {
                    layer.variable_anchors = value;
                }
                if let Some(value) = symbol_writing_mode(self.layout.get("text-writing-mode"))? {
                    layer.writing_mode = value;
                }
                if let Some(value) = vec2_value(self.layout.get("text-offset"))? {
                    layer.offset = value;
                }
                StyleLayer::Symbol(layer)
            }
            StyleSpecLayerType::Model => {
                let source = self.required_source()?;
                let mut layer = ModelStyleLayer::new(self.id.clone(), source);
                layer.meta = meta;
                StyleLayer::Model(layer)
            }
        };
        Ok(layer)
    }

    fn meta(&self) -> Result<StyleLayerMeta, StyleSpecError> {
        let mut meta = StyleLayerMeta::new(self.id.clone());
        meta.min_zoom = self.minzoom;
        meta.max_zoom = self.maxzoom;

        if let Some(value) = self.opacity_value()? {
            meta.opacity = value;
        }

        if let Some(visibility) = self.layout.get("visibility") {
            let visible = match visibility.as_str() {
                Some("visible") | None => true,
                Some("none") => false,
                Some(_) => {
                    return Err(StyleSpecError::InvalidField {
                        id: self.id.clone(),
                        field: "layout.visibility",
                        expected: "`visible` or `none`",
                    })
                }
            };
            meta.visible = visible.into();
        }

        Ok(meta)
    }

    fn opacity_value(&self) -> Result<Option<StyleValue<f32>>, StyleSpecError> {
        let keys = match self.layer_type {
            StyleSpecLayerType::Background => &["background-opacity"][..],
            StyleSpecLayerType::Hillshade => &["hillshade-opacity"],
            StyleSpecLayerType::Raster => &["raster-opacity"],
            StyleSpecLayerType::Vector => &["opacity"],
            StyleSpecLayerType::Fill => &["fill-opacity"],
            StyleSpecLayerType::Line => &["line-opacity"],
            StyleSpecLayerType::Circle => &["circle-opacity"],
            StyleSpecLayerType::Heatmap => &["heatmap-opacity"],
            StyleSpecLayerType::FillExtrusion => &["fill-extrusion-opacity"],
            StyleSpecLayerType::Symbol => &["text-opacity", "icon-opacity"],
            StyleSpecLayerType::Model => &["model-opacity"],
        };

        for key in keys {
            if let Some(value) = self.paint.get(*key) {
                return Ok(Some(f32_value_from_json(&self.id, key, value)?));
            }
        }
        Ok(None)
    }

    fn required_source(&self) -> Result<String, StyleSpecError> {
        self.source
            .clone()
            .ok_or_else(|| StyleSpecError::MissingLayerSource(self.id.clone()))
    }
}

/// Parse a JSON style string.
pub fn parse_style_json(json: &str) -> Result<StyleSpecDocument, StyleSpecError> {
    StyleSpecDocument::from_json(json)
}

fn paint_color(
    map: &Map<String, Value>,
    key: &'static str,
) -> Result<Option<StyleValue<[f32; 4]>>, StyleSpecError> {
    map.get(key)
        .map(|value| color_value_from_json(key, key, value))
        .transpose()
}

fn paint_f32(map: &Map<String, Value>, key: &'static str) -> Result<Option<StyleValue<f32>>, StyleSpecError> {
    map.get(key)
        .map(|value| f32_value_from_json(key, key, value))
        .transpose()
}

fn string_value(value: Option<&Value>) -> Result<Option<StyleValue<String>>, StyleSpecError> {
    value
        .map(|value| string_value_from_json("symbol", "text-field", value))
        .transpose()
}

fn bool_value(value: Option<&Value>) -> Result<Option<StyleValue<bool>>, StyleSpecError> {
    value
        .map(|value| bool_value_from_json("symbol", "allow-overlap", value))
        .transpose()
}

fn first_string_from_array(value: Option<&Value>) -> Result<Option<StyleValue<String>>, StyleSpecError> {
    let Some(value) = value else {
        return Ok(None);
    };
    let Some(array) = value.as_array() else {
        return Err(StyleSpecError::InvalidField {
            id: "symbol".into(),
            field: "text-font",
            expected: "string or string array",
        });
    };
    let Some(first) = array.first() else {
        return Ok(None);
    };
    Ok(Some(string_value_from_json("symbol", "text-font", first)?))
}

fn vec2_value(value: Option<&Value>) -> Result<Option<[f32; 2]>, StyleSpecError> {
    let Some(value) = value else {
        return Ok(None);
    };
    let Some(array) = value.as_array() else {
        return Err(StyleSpecError::InvalidField {
            id: "symbol".into(),
            field: "text-offset",
            expected: "two-element numeric array",
        });
    };
    if array.len() != 2 {
        return Err(StyleSpecError::InvalidField {
            id: "symbol".into(),
            field: "text-offset",
            expected: "two-element numeric array",
        });
    }
    Ok(Some([
        array[0].as_f64().ok_or_else(|| StyleSpecError::InvalidField {
            id: "symbol".into(),
            field: "text-offset",
            expected: "two-element numeric array",
        })? as f32,
        array[1].as_f64().ok_or_else(|| StyleSpecError::InvalidField {
            id: "symbol".into(),
            field: "text-offset",
            expected: "two-element numeric array",
        })? as f32,
    ]))
}

fn symbol_anchor_array(value: Option<&Value>) -> Result<Option<Vec<SymbolAnchor>>, StyleSpecError> {
    let Some(value) = value else {
        return Ok(None);
    };
    let Some(array) = value.as_array() else {
        return Err(StyleSpecError::InvalidField {
            id: "symbol".into(),
            field: "text-variable-anchor",
            expected: "string array",
        });
    };
    let mut anchors = Vec::with_capacity(array.len());
    for value in array {
        let Some(text) = value.as_str() else {
            return Err(StyleSpecError::InvalidField {
                id: "symbol".into(),
                field: "text-variable-anchor",
                expected: "string array",
            });
        };
        anchors.push(parse_symbol_anchor(text)?);
    }
    Ok(Some(anchors))
}

fn symbol_anchor_offset_array(
    value: Option<&Value>,
) -> Result<Option<Vec<(SymbolAnchor, [f32; 2])>>, StyleSpecError> {
    let Some(value) = value else {
        return Ok(None);
    };
    let Some(array) = value.as_array() else {
        return Err(StyleSpecError::InvalidField {
            id: "symbol".into(),
            field: "text-variable-anchor-offset",
            expected: "alternating anchor / [x, y] array",
        });
    };
    if array.len() % 2 != 0 {
        return Err(StyleSpecError::InvalidField {
            id: "symbol".into(),
            field: "text-variable-anchor-offset",
            expected: "alternating anchor / [x, y] array",
        });
    }

    let mut parsed = Vec::with_capacity(array.len() / 2);
    for pair in array.chunks_exact(2) {
        let anchor_text = pair[0].as_str().ok_or_else(|| StyleSpecError::InvalidField {
            id: "symbol".into(),
            field: "text-variable-anchor-offset",
            expected: "anchor string in alternating anchor / [x, y] array",
        })?;
        let anchor = parse_symbol_anchor(anchor_text)?;
        let offset = parse_vec2_array("symbol", "text-variable-anchor-offset", pair[1].as_array().ok_or_else(|| StyleSpecError::InvalidField {
            id: "symbol".into(),
            field: "text-variable-anchor-offset",
            expected: "[x, y] offset array in alternating anchor / [x, y] array",
        })?)?;
        parsed.push((anchor, offset));
    }

    Ok(Some(parsed))
}

fn symbol_writing_mode(value: Option<&Value>) -> Result<Option<SymbolWritingMode>, StyleSpecError> {
    let Some(value) = value else {
        return Ok(None);
    };
    let Some(text) = value.as_str() else {
        return Err(StyleSpecError::InvalidField {
            id: "symbol".into(),
            field: "text-writing-mode",
            expected: "string value",
        });
    };
    Ok(Some(parse_symbol_writing_mode(text)?))
}

fn symbol_placement(value: Option<&Value>) -> Result<Option<SymbolPlacement>, StyleSpecError> {
    let Some(value) = value else {
        return Ok(None);
    };
    let Some(text) = value.as_str() else {
        return Err(StyleSpecError::InvalidField {
            id: "symbol".into(),
            field: "symbol-placement",
            expected: "string value",
        });
    };
    Ok(Some(parse_symbol_placement(text)?))
}

fn symbol_anchor(value: Option<&Value>) -> Result<Option<SymbolAnchor>, StyleSpecError> {
    let Some(value) = value else {
        return Ok(None);
    };
    let Some(text) = value.as_str() else {
        return Err(StyleSpecError::InvalidField {
            id: "symbol".into(),
            field: "text-anchor",
            expected: "string value",
        });
    };
    Ok(Some(parse_symbol_anchor(text)?))
}

fn symbol_text_justify(
    value: Option<&Value>,
) -> Result<Option<StyleValue<SymbolTextJustify>>, StyleSpecError> {
    let Some(value) = value else {
        return Ok(None);
    };
    Ok(Some(match value {
        Value::String(text) => StyleValue::Constant(parse_symbol_text_justify(text)?),
        Value::Object(object) => parse_zoom_stops("symbol", "text-justify", object, |id, field, value| {
            let text = value.as_str().ok_or_else(|| StyleSpecError::InvalidField {
                id: id.to_owned(), field, expected: "string value",
            })?;
            parse_symbol_text_justify(text)
        })?,

        _ => {
            return Err(StyleSpecError::InvalidField {
                id: "symbol".into(),
                field: "text-justify",
                expected: "string value or `{ stops: ... }`",
            })
        }
    }))
}

fn symbol_icon_text_fit(
    value: Option<&Value>,
) -> Result<Option<StyleValue<SymbolIconTextFit>>, StyleSpecError> {
    let Some(value) = value else {
        return Ok(None);
    };
    Ok(Some(match value {
        Value::String(text) => StyleValue::Constant(parse_symbol_icon_text_fit(text)?),
        Value::Object(object) => {
            parse_zoom_stops("symbol", "icon-text-fit", object, |id, field, value| {
                let text = value.as_str().ok_or_else(|| StyleSpecError::InvalidField {
                    id: id.to_owned(), field, expected: "string value",
                })?;
                parse_symbol_icon_text_fit(text)
            })?
        }
        _ => {
            return Err(StyleSpecError::InvalidField {
                id: "symbol".into(),
                field: "icon-text-fit",
                expected: "string value or `{ stops: ... }`",
            })
        }
    }))
}

fn symbol_text_transform(
    value: Option<&Value>,
) -> Result<Option<StyleValue<SymbolTextTransform>>, StyleSpecError> {
    let Some(value) = value else {
        return Ok(None);
    };
    Ok(Some(match value {
        Value::String(text) => StyleValue::Constant(parse_symbol_text_transform(text)?),
        Value::Object(object) => {
            parse_zoom_stops("symbol", "text-transform", object, |id, field, value| {
                let text = value.as_str().ok_or_else(|| StyleSpecError::InvalidField {
                    id: id.to_owned(), field, expected: "string value",
                })?;
                parse_symbol_text_transform(text)
            })?
        }
        _ => {
            return Err(StyleSpecError::InvalidField {
                id: "symbol".into(),
                field: "text-transform",
                expected: "string value or `{ stops: ... }`",
            })
        }
    }))
}

fn parse_symbol_anchor(text: &str) -> Result<SymbolAnchor, StyleSpecError> {
    match text {
        "center" => Ok(SymbolAnchor::Center),
        "top" => Ok(SymbolAnchor::Top),
        "bottom" => Ok(SymbolAnchor::Bottom),
        "left" => Ok(SymbolAnchor::Left),
        "right" => Ok(SymbolAnchor::Right),
        "top-left" => Ok(SymbolAnchor::TopLeft),
        "top-right" => Ok(SymbolAnchor::TopRight),
        "bottom-left" => Ok(SymbolAnchor::BottomLeft),
        "bottom-right" => Ok(SymbolAnchor::BottomRight),
        _ => Err(StyleSpecError::InvalidField {
            id: "symbol".into(),
            field: "text-variable-anchor",
            expected: "known symbol-anchor string",
        }),
    }
}

fn parse_symbol_icon_text_fit(text: &str) -> Result<SymbolIconTextFit, StyleSpecError> {
    match text {
        "none" => Ok(SymbolIconTextFit::None),
        "width" => Ok(SymbolIconTextFit::Width),
        "height" => Ok(SymbolIconTextFit::Height),
        "both" => Ok(SymbolIconTextFit::Both),
        _ => Err(StyleSpecError::InvalidField {
            id: "symbol".into(),
            field: "icon-text-fit",
            expected: "`none`, `width`, `height`, or `both`",
        }),
    }
}

fn parse_symbol_text_transform(text: &str) -> Result<SymbolTextTransform, StyleSpecError> {
    match text {
        "none" => Ok(SymbolTextTransform::None),
        "uppercase" => Ok(SymbolTextTransform::Uppercase),
        "lowercase" => Ok(SymbolTextTransform::Lowercase),
        _ => Err(StyleSpecError::InvalidField {
            id: "symbol".into(),
            field: "text-transform",
            expected: "`none`, `uppercase`, or `lowercase`",
        }),
    }
}

fn parse_symbol_text_justify(text: &str) -> Result<SymbolTextJustify, StyleSpecError> {
    match text {
        "auto" => Ok(SymbolTextJustify::Auto),
        "left" => Ok(SymbolTextJustify::Left),
        "center" => Ok(SymbolTextJustify::Center),
        "right" => Ok(SymbolTextJustify::Right),
        _ => Err(StyleSpecError::InvalidField {
            id: "symbol".into(),
            field: "text-justify",
            expected: "`auto`, `left`, `center`, or `right`",
        }),
    }
}

fn parse_symbol_placement(text: &str) -> Result<SymbolPlacement, StyleSpecError> {
    match text {
        "point" => Ok(SymbolPlacement::Point),
        "line" => Ok(SymbolPlacement::Line),
        _ => Err(StyleSpecError::InvalidField {
            id: "symbol".into(),
            field: "symbol-placement",
            expected: "`point` or `line`",
        }),
    }
}

fn parse_symbol_writing_mode(text: &str) -> Result<SymbolWritingMode, StyleSpecError> {
    match text {
        "horizontal" => Ok(SymbolWritingMode::Horizontal),
        "vertical" => Ok(SymbolWritingMode::Vertical),
        _ => Err(StyleSpecError::InvalidField {
            id: "symbol".into(),
            field: "text-writing-mode",
            expected: "`horizontal` or `vertical`",
        }),
    }
}

fn bool_value_from_json(
    id: &str,
    field: &'static str,
    value: &Value,
) -> Result<StyleValue<bool>, StyleSpecError> {
    match value {
        Value::Bool(value) => Ok(StyleValue::Constant(*value)),
        Value::Object(object) => parse_zoom_stops(id, field, object, parse_bool_constant),
        Value::Array(arr) if is_expression_array(arr) => parse_expression_bool(id, field, arr),
        _ => Err(StyleSpecError::InvalidField {
            id: id.to_owned(),
            field,
            expected: "boolean value, `{ stops: ... }`, or expression array",
        }),
    }
}

fn f32_value_from_json(
    id: &str,
    field: &'static str,
    value: &Value,
) -> Result<StyleValue<f32>, StyleSpecError> {
    match value {
        Value::Number(number) => Ok(StyleValue::Constant(number.as_f64().ok_or_else(|| StyleSpecError::InvalidField {
            id: id.to_owned(),
            field,
            expected: "numeric value",
        })? as f32)),
        Value::Object(object) => parse_zoom_stops(id, field, object, parse_f32_constant),
        Value::Array(arr) if is_expression_array(arr) => parse_expression_f32(id, field, arr),
        _ => Err(StyleSpecError::InvalidField {
            id: id.to_owned(),
            field,
            expected: "numeric value, `{ stops: ... }`, or expression array",
        }),
    }
}

fn string_value_from_json(
    id: &str,
    field: &'static str,
    value: &Value,
) -> Result<StyleValue<String>, StyleSpecError> {
    match value {
        Value::String(text) => Ok(StyleValue::Constant(text.clone())),
        Value::Object(object) => parse_zoom_stops(id, field, object, parse_string_constant),
        Value::Array(arr) if is_expression_array(arr) => parse_expression_string(id, field, arr),
        _ => Err(StyleSpecError::InvalidField {
            id: id.to_owned(),
            field,
            expected: "string value, `{ stops: ... }`, or expression array",
        }),
    }
}

fn color_value_from_json(
    id: &str,
    field: &'static str,
    value: &Value,
) -> Result<StyleValue<[f32; 4]>, StyleSpecError> {
    match value {
        Value::String(text) => Ok(StyleValue::Constant(parse_color_string(id, field, text)?)),
        Value::Array(array) if is_expression_array(array) => parse_expression_color(id, field, array),
        Value::Array(array) => Ok(StyleValue::Constant(parse_color_array(id, field, array)?)),
        Value::Object(object) => parse_zoom_stops(id, field, object, |id, field, value| match value {
            Value::String(text) => parse_color_string(id, field, text),
            Value::Array(array) => parse_color_array(id, field, array),
            _ => Err(StyleSpecError::InvalidField {
                id: id.to_owned(),
                field,
                expected: "color string or RGBA array",
            }),
        }),
        _ => Err(StyleSpecError::InvalidField {
            id: id.to_owned(),
            field,
            expected: "color string, RGBA array, or `{ stops: ... }`",
        }),
    }
}

fn parse_zoom_stops<T>(
    id: &str,
    field: &'static str,
    object: &Map<String, Value>,
    parse_value: impl Fn(&str, &'static str, &Value) -> Result<T, StyleSpecError>,
) -> Result<StyleValue<T>, StyleSpecError> {
    let Some(stops) = object.get("stops").and_then(Value::as_array) else {
        return Err(StyleSpecError::InvalidField {
            id: id.to_owned(),
            field,
            expected: "object with `stops` array",
        });
    };

    let mut parsed = Vec::with_capacity(stops.len());
    for stop in stops {
        let pair = stop.as_array().ok_or_else(|| StyleSpecError::InvalidField {
            id: id.to_owned(),
            field,
            expected: "stop tuple `[zoom, value]`",
        })?;
        if pair.len() != 2 {
            return Err(StyleSpecError::InvalidField {
                id: id.to_owned(),
                field,
                expected: "stop tuple `[zoom, value]`",
            });
        }
        let zoom = pair[0].as_f64().ok_or_else(|| StyleSpecError::InvalidField {
            id: id.to_owned(),
            field,
            expected: "numeric stop zoom",
        })? as f32;
        let value = parse_value(id, field, &pair[1])?;
        parsed.push((zoom, value));
    }
    Ok(StyleValue::ZoomStops(parsed))
}

fn parse_f32_constant(id: &str, field: &'static str, value: &Value) -> Result<f32, StyleSpecError> {
    value.as_f64().map(|v| v as f32).ok_or_else(|| StyleSpecError::InvalidField {
        id: id.to_owned(),
        field,
        expected: "numeric value",
    })
}

fn parse_string_constant(id: &str, field: &'static str, value: &Value) -> Result<String, StyleSpecError> {
    value.as_str().map(ToOwned::to_owned).ok_or_else(|| StyleSpecError::InvalidField {
        id: id.to_owned(),
        field,
        expected: "string value",
    })
}

fn parse_bool_constant(id: &str, field: &'static str, value: &Value) -> Result<bool, StyleSpecError> {
    value.as_bool().ok_or_else(|| StyleSpecError::InvalidField {
        id: id.to_owned(),
        field,
        expected: "boolean value",
    })
}

fn vec4_value(value: Option<&Value>, field: &'static str) -> Result<Option<[f32; 4]>, StyleSpecError> {
    let Some(value) = value else {
        return Ok(None);
    };
    let arr = value.as_array().ok_or_else(|| StyleSpecError::InvalidField {
        id: "symbol".into(),
        field,
        expected: "array of 4 numbers",
    })?;
    if arr.len() != 4 {
        return Err(StyleSpecError::InvalidField {
            id: "symbol".into(),
            field,
            expected: "array of 4 numbers",
        });
    }
    let mut out = [0.0f32; 4];
    for (i, v) in arr.iter().enumerate() {
        out[i] = v.as_f64().ok_or_else(|| StyleSpecError::InvalidField {
            id: "symbol".into(),
            field,
            expected: "numeric array element",
        })? as f32;
    }
    Ok(Some(out))
}

fn parse_vec2_array(id: &str, field: &'static str, arr: &[Value]) -> Result<[f32; 2], StyleSpecError> {
    if arr.len() != 2 {
        return Err(StyleSpecError::InvalidField {
            id: id.to_owned(),
            field,
            expected: "[x, y] array of 2 numbers",
        });
    }
    let x = arr[0].as_f64().ok_or_else(|| StyleSpecError::InvalidField {
        id: id.to_owned(),
        field,
        expected: "numeric value in [x, y] array",
    })? as f32;
    let y = arr[1].as_f64().ok_or_else(|| StyleSpecError::InvalidField {
        id: id.to_owned(),
        field,
        expected: "numeric value in [x, y] array",
    })? as f32;
    Ok([x, y])
}

fn parse_color_array(
    id: &str,
    field: &'static str,
    array: &[Value],
) -> Result<[f32; 4], StyleSpecError> {
    if !(array.len() == 3 || array.len() == 4) {
        return Err(StyleSpecError::InvalidField {
            id: id.to_owned(),
            field,
            expected: "RGB or RGBA array",
        });
    }
    let mut rgba = [0.0, 0.0, 0.0, 1.0];
    for (i, value) in array.iter().enumerate() {
        rgba[i] = value.as_f64().ok_or_else(|| StyleSpecError::InvalidField {
            id: id.to_owned(),
            field,
            expected: "numeric RGB/RGBA components",
        })? as f32;
    }
    Ok(rgba)
}

fn parse_color_string(
    id: &str,
    field: &'static str,
    text: &str,
) -> Result<[f32; 4], StyleSpecError> {
    let hex = text.strip_prefix('#').ok_or_else(|| StyleSpecError::InvalidField {
        id: id.to_owned(),
        field,
        expected: "hex color string like `#RRGGBB` or `#RRGGBBAA`",
    })?;

    let rgba = match hex.len() {
        3 => {
            let r = u8::from_str_radix(&hex[0..1].repeat(2), 16).ok();
            let g = u8::from_str_radix(&hex[1..2].repeat(2), 16).ok();
            let b = u8::from_str_radix(&hex[2..3].repeat(2), 16).ok();
            [r, g, b, Some(255)]
        }
        4 => {
            let r = u8::from_str_radix(&hex[0..1].repeat(2), 16).ok();
            let g = u8::from_str_radix(&hex[1..2].repeat(2), 16).ok();
            let b = u8::from_str_radix(&hex[2..3].repeat(2), 16).ok();
            let a = u8::from_str_radix(&hex[3..4].repeat(2), 16).ok();
            [r, g, b, a]
        }
        6 => {
            let r = u8::from_str_radix(&hex[0..2], 16).ok();
            let g = u8::from_str_radix(&hex[2..4], 16).ok();
            let b = u8::from_str_radix(&hex[4..6], 16).ok();
            [r, g, b, Some(255)]
        }
        8 => {
            let r = u8::from_str_radix(&hex[0..2], 16).ok();
            let g = u8::from_str_radix(&hex[2..4], 16).ok();
            let b = u8::from_str_radix(&hex[4..6], 16).ok();
            let a = u8::from_str_radix(&hex[6..8], 16).ok();
            [r, g, b, a]
        }
        _ => [None, None, None, None],
    };

    match rgba {
        [Some(r), Some(g), Some(b), Some(a)] => Ok([
            r as f32 / 255.0,
            g as f32 / 255.0,
            b as f32 / 255.0,
            a as f32 / 255.0,
        ]),
        _ => Err(StyleSpecError::InvalidField {
            id: id.to_owned(),
            field,
            expected: "hex color string like `#RRGGBB` or `#RRGGBBAA`",
        }),
    }
}

fn default_style_version() -> u8 {
    8
}

// ---------------------------------------------------------------------------
// MapLibre expression JSON parsing
// ---------------------------------------------------------------------------
//
// MapLibre expressions are JSON arrays where the first element is a string
// operator name. This parser converts them into the typed `Expression<T>`
// AST. For example:
//
//   ["get", "height"]          → Expression::GetProperty { key: "height", fallback }
//   ["interpolate", ["linear"], ["zoom"], 0, 1, 20, 10]
//                              → Expression::Interpolate { input: Zoom, stops }
//   ["match", ["get", "type"], "residential", "#00f", "commercial", "#f00", "#888"]
//                              → Expression::Match { input, cases, fallback }
//   ["step", ["zoom"], 1, 5, 2, 10, 3]
//                              → Expression::Step { input: Zoom, default, stops }
//   ["case", cond1, val1, ..., fallback]
//                              → Expression::Case { branches, fallback }

use crate::expression::{BoolExpression, Expression, NumericExpression, StringExpression};

/// Check whether a JSON array looks like a MapLibre expression (starts with a string operator).
fn is_expression_array(arr: &[Value]) -> bool {
    arr.first()
        .and_then(Value::as_str)
        .map(|op| matches!(
            op,
            "get" | "has" | "!" | "all" | "any"
            | "==" | "!=" | ">" | ">=" | "<" | "<="
            | "+" | "-" | "*" | "/" | "%" | "^" | "abs" | "ln" | "sqrt" | "min" | "max"
            | "interpolate" | "step" | "match" | "case" | "coalesce"
            | "zoom" | "pitch"
            | "concat" | "upcase" | "downcase"
            | "feature-state"
            | "to-number" | "to-string" | "to-boolean"
            | "literal"
        ))
        .unwrap_or(false)
}

/// Parse a MapLibre expression array into an `Expression<f32>`.
fn parse_expression_f32(
    id: &str,
    field: &'static str,
    arr: &[Value],
) -> Result<StyleValue<f32>, StyleSpecError> {
    let op = arr[0].as_str().unwrap_or("");
    match op {
        "literal" if arr.len() == 2 => {
            let v = arr[1].as_f64().ok_or_else(|| expr_err(id, field, "literal number"))? as f32;
            Ok(Expression::Constant(v))
        }
        "get" if arr.len() == 2 => {
            let key = arr[1].as_str().ok_or_else(|| expr_err(id, field, "get property key"))?;
            Ok(Expression::GetProperty { key: key.to_owned(), fallback: 0.0 })
        }
        "feature-state" if arr.len() == 2 => {
            let key = arr[1].as_str().ok_or_else(|| expr_err(id, field, "feature-state key"))?;
            Ok(Expression::FeatureState { key: key.to_owned(), fallback: 0.0 })
        }
        "zoom" => Ok(Expression::Interpolate {
            input: Box::new(NumericExpression::Zoom),
            stops: vec![],
        }),
        "interpolate" => parse_interpolate_f32(id, field, arr),
        "step" => parse_step_f32(id, field, arr),
        "case" => parse_case_f32(id, field, arr),
        "coalesce" => {
            let exprs: Result<Vec<_>, _> = arr[1..]
                .iter()
                .map(|v| match v {
                    Value::Number(n) => Ok(Expression::Constant(n.as_f64().unwrap_or(0.0) as f32)),
                    Value::Array(a) if is_expression_array(a) => parse_expression_f32(id, field, a),
                    _ => Err(expr_err(id, field, "coalesce sub-expression")),
                })
                .collect();
            Ok(Expression::Coalesce(exprs?))
        }
        _ => Err(expr_err(id, field, &format!("f32 expression (unsupported operator `{op}`)"))),
    }
}

/// Parse a MapLibre expression array into an `Expression<[f32; 4]>` (color).
fn parse_expression_color(
    id: &str,
    field: &'static str,
    arr: &[Value],
) -> Result<StyleValue<[f32; 4]>, StyleSpecError> {
    let op = arr[0].as_str().unwrap_or("");
    match op {
        "literal" if arr.len() == 2 => {
            if let Some(a) = arr[1].as_array() {
                let c = parse_color_array(id, field, a)?;
                Ok(Expression::Constant(c))
            } else {
                Err(expr_err(id, field, "literal color array"))
            }
        }
        "interpolate" => parse_interpolate_color(id, field, arr),
        "step" => parse_step_color(id, field, arr),
        "match" => parse_match_color(id, field, arr),
        "case" => parse_case_color(id, field, arr),
        _ => Err(expr_err(id, field, &format!("color expression (unsupported operator `{op}`)"))),
    }
}

/// Parse a MapLibre expression array into an `Expression<String>`.
fn parse_expression_string(
    id: &str,
    field: &'static str,
    arr: &[Value],
) -> Result<StyleValue<String>, StyleSpecError> {
    let op = arr[0].as_str().unwrap_or("");
    match op {
        "literal" if arr.len() == 2 => {
            let s = arr[1].as_str().ok_or_else(|| expr_err(id, field, "literal string"))?;
            Ok(Expression::Constant(s.to_owned()))
        }
        "get" if arr.len() == 2 => {
            let key = arr[1].as_str().ok_or_else(|| expr_err(id, field, "get property key"))?;
            Ok(Expression::GetProperty { key: key.to_owned(), fallback: String::new() })
        }
        "feature-state" if arr.len() == 2 => {
            let key = arr[1].as_str().ok_or_else(|| expr_err(id, field, "feature-state key"))?;
            Ok(Expression::FeatureState { key: key.to_owned(), fallback: String::new() })
        }
        "concat" => {
            let exprs: Result<Vec<_>, _> = arr[1..]
                .iter()
                .map(|v| match v {
                    Value::String(s) => Ok(Expression::Constant(s.clone())),
                    Value::Array(a) if is_expression_array(a) => parse_expression_string(id, field, a),
                    _ => Err(expr_err(id, field, "concat sub-expression")),
                })
                .collect();
            Ok(Expression::Coalesce(exprs?))
        }
        _ => Err(expr_err(id, field, &format!("string expression (unsupported operator `{op}`)"))),
    }
}

/// Parse a MapLibre expression array into an `Expression<bool>`.
fn parse_expression_bool(
    id: &str,
    field: &'static str,
    arr: &[Value],
) -> Result<StyleValue<bool>, StyleSpecError> {
    let op = arr[0].as_str().unwrap_or("");
    match op {
        "literal" if arr.len() == 2 => {
            let b = arr[1].as_bool().ok_or_else(|| expr_err(id, field, "literal boolean"))?;
            Ok(Expression::Constant(b))
        }
        "get" if arr.len() == 2 => {
            let key = arr[1].as_str().ok_or_else(|| expr_err(id, field, "get property key"))?;
            Ok(Expression::GetProperty { key: key.to_owned(), fallback: false })
        }
        "feature-state" if arr.len() == 2 => {
            let key = arr[1].as_str().ok_or_else(|| expr_err(id, field, "feature-state key"))?;
            Ok(Expression::FeatureState { key: key.to_owned(), fallback: false })
        }
        "has" if arr.len() == 2 => {
            let key = arr[1].as_str().ok_or_else(|| expr_err(id, field, "has property key"))?;
            Ok(Expression::Case {
                branches: vec![(BoolExpression::Has(key.to_owned()), true)],
                fallback: false,
            })
        }
        _ => Err(expr_err(id, field, &format!("boolean expression (unsupported operator `{op}`)"))),
    }
}

// ---------------------------------------------------------------------------
// Expression sub-parsers
// ---------------------------------------------------------------------------

/// Parse a numeric sub-expression (used as input to interpolate/step).
fn parse_numeric_input(
    id: &str,
    field: &'static str,
    value: &Value,
) -> Result<NumericExpression, StyleSpecError> {
    match value {
        Value::Number(n) => Ok(NumericExpression::Literal(n.as_f64().unwrap_or(0.0))),
        Value::Array(arr) if !arr.is_empty() => {
            let op = arr[0].as_str().unwrap_or("");
            match op {
                "zoom" => Ok(NumericExpression::Zoom),
                "pitch" => Ok(NumericExpression::Pitch),
                "get" if arr.len() == 2 => {
                    let key = arr[1].as_str().ok_or_else(|| expr_err(id, field, "get key"))?;
                    Ok(NumericExpression::GetProperty { key: key.to_owned(), fallback: 0.0 })
                }
                "feature-state" if arr.len() == 2 => {
                    let key = arr[1].as_str().ok_or_else(|| expr_err(id, field, "feature-state key"))?;
                    Ok(NumericExpression::GetState { key: key.to_owned(), fallback: 0.0 })
                }
                "+" if arr.len() == 3 => Ok(NumericExpression::Add(
                    Box::new(parse_numeric_input(id, field, &arr[1])?),
                    Box::new(parse_numeric_input(id, field, &arr[2])?),
                )),
                "-" if arr.len() == 3 => Ok(NumericExpression::Sub(
                    Box::new(parse_numeric_input(id, field, &arr[1])?),
                    Box::new(parse_numeric_input(id, field, &arr[2])?),
                )),
                "*" if arr.len() == 3 => Ok(NumericExpression::Mul(
                    Box::new(parse_numeric_input(id, field, &arr[1])?),
                    Box::new(parse_numeric_input(id, field, &arr[2])?),
                )),
                "/" if arr.len() == 3 => Ok(NumericExpression::Div(
                    Box::new(parse_numeric_input(id, field, &arr[1])?),
                    Box::new(parse_numeric_input(id, field, &arr[2])?),
                )),
                "%" if arr.len() == 3 => Ok(NumericExpression::Mod(
                    Box::new(parse_numeric_input(id, field, &arr[1])?),
                    Box::new(parse_numeric_input(id, field, &arr[2])?),
                )),
                "^" if arr.len() == 3 => Ok(NumericExpression::Pow(
                    Box::new(parse_numeric_input(id, field, &arr[1])?),
                    Box::new(parse_numeric_input(id, field, &arr[2])?),
                )),
                "abs" if arr.len() == 2 => Ok(NumericExpression::Abs(
                    Box::new(parse_numeric_input(id, field, &arr[1])?),
                )),
                "ln" if arr.len() == 2 => Ok(NumericExpression::Ln(
                    Box::new(parse_numeric_input(id, field, &arr[1])?),
                )),
                "sqrt" if arr.len() == 2 => Ok(NumericExpression::Sqrt(
                    Box::new(parse_numeric_input(id, field, &arr[1])?),
                )),
                "min" if arr.len() == 3 => Ok(NumericExpression::Min(
                    Box::new(parse_numeric_input(id, field, &arr[1])?),
                    Box::new(parse_numeric_input(id, field, &arr[2])?),
                )),
                "max" if arr.len() == 3 => Ok(NumericExpression::Max(
                    Box::new(parse_numeric_input(id, field, &arr[1])?),
                    Box::new(parse_numeric_input(id, field, &arr[2])?),
                )),
                _ => Err(expr_err(id, field, &format!("numeric input (unsupported `{op}`)"))),
            }
        }
        _ => Err(expr_err(id, field, "numeric input")),
    }
}

/// Parse a string sub-expression input (used as input to match).
fn parse_string_input(
    id: &str,
    field: &'static str,
    value: &Value,
) -> Result<StringExpression, StyleSpecError> {
    match value {
        Value::String(s) => Ok(StringExpression::Literal(s.clone())),
        Value::Array(arr) if !arr.is_empty() => {
            let op = arr[0].as_str().unwrap_or("");
            match op {
                "get" if arr.len() == 2 => {
                    let key = arr[1].as_str().ok_or_else(|| expr_err(id, field, "get key"))?;
                    Ok(StringExpression::GetProperty { key: key.to_owned(), fallback: String::new() })
                }
                "feature-state" if arr.len() == 2 => {
                    let key = arr[1].as_str().ok_or_else(|| expr_err(id, field, "feature-state key"))?;
                    Ok(StringExpression::GetState { key: key.to_owned(), fallback: String::new() })
                }
                "upcase" if arr.len() == 2 => {
                    Ok(StringExpression::Upcase(Box::new(parse_string_input(id, field, &arr[1])?)))
                }
                "downcase" if arr.len() == 2 => {
                    Ok(StringExpression::Downcase(Box::new(parse_string_input(id, field, &arr[1])?)))
                }
                "concat" if arr.len() >= 3 => {
                    let left = parse_string_input(id, field, &arr[1])?;
                    let right = parse_string_input(id, field, &arr[2])?;
                    Ok(StringExpression::Concat(Box::new(left), Box::new(right)))
                }
                _ => Err(expr_err(id, field, &format!("string input (unsupported `{op}`)"))),
            }
        }
        _ => Err(expr_err(id, field, "string input")),
    }
}

/// Parse a boolean condition expression.
fn parse_bool_condition(
    id: &str,
    field: &'static str,
    value: &Value,
) -> Result<BoolExpression, StyleSpecError> {
    match value {
        Value::Bool(b) => Ok(BoolExpression::Literal(*b)),
        Value::Array(arr) if !arr.is_empty() => {
            let op = arr[0].as_str().unwrap_or("");
            match op {
                "has" if arr.len() == 2 => {
                    let key = arr[1].as_str().ok_or_else(|| expr_err(id, field, "has key"))?;
                    Ok(BoolExpression::Has(key.to_owned()))
                }
                "get" if arr.len() == 2 => {
                    let key = arr[1].as_str().ok_or_else(|| expr_err(id, field, "get key"))?;
                    Ok(BoolExpression::GetProperty { key: key.to_owned(), fallback: false })
                }
                "!" if arr.len() == 2 => {
                    Ok(BoolExpression::Not(Box::new(parse_bool_condition(id, field, &arr[1])?)))
                }
                "all" => {
                    let exprs: Result<Vec<_>, _> = arr[1..]
                        .iter()
                        .map(|v| parse_bool_condition(id, field, v))
                        .collect();
                    Ok(BoolExpression::All(exprs?))
                }
                "any" => {
                    let exprs: Result<Vec<_>, _> = arr[1..]
                        .iter()
                        .map(|v| parse_bool_condition(id, field, v))
                        .collect();
                    Ok(BoolExpression::Any(exprs?))
                }
                "==" if arr.len() == 3 => {
                    // Try numeric comparison first, then string.
                    if let (Ok(a), Ok(b)) = (
                        parse_numeric_input(id, field, &arr[1]),
                        parse_numeric_input(id, field, &arr[2]),
                    ) {
                        Ok(BoolExpression::Eq(a, b))
                    } else if let (Ok(a), Ok(b)) = (
                        parse_string_input(id, field, &arr[1]),
                        parse_string_input(id, field, &arr[2]),
                    ) {
                        Ok(BoolExpression::StrEq(a, b))
                    } else {
                        Err(expr_err(id, field, "== operands"))
                    }
                }
                "!=" if arr.len() == 3 => {
                    let a = parse_numeric_input(id, field, &arr[1])?;
                    let b = parse_numeric_input(id, field, &arr[2])?;
                    Ok(BoolExpression::Neq(a, b))
                }
                ">" if arr.len() == 3 => {
                    let a = parse_numeric_input(id, field, &arr[1])?;
                    let b = parse_numeric_input(id, field, &arr[2])?;
                    Ok(BoolExpression::Gt(a, b))
                }
                ">=" if arr.len() == 3 => {
                    let a = parse_numeric_input(id, field, &arr[1])?;
                    let b = parse_numeric_input(id, field, &arr[2])?;
                    Ok(BoolExpression::Gte(a, b))
                }
                "<" if arr.len() == 3 => {
                    let a = parse_numeric_input(id, field, &arr[1])?;
                    let b = parse_numeric_input(id, field, &arr[2])?;
                    Ok(BoolExpression::Lt(a, b))
                }
                "<=" if arr.len() == 3 => {
                    let a = parse_numeric_input(id, field, &arr[1])?;
                    let b = parse_numeric_input(id, field, &arr[2])?;
                    Ok(BoolExpression::Lte(a, b))
                }
                _ => Err(expr_err(id, field, &format!("boolean condition (unsupported `{op}`)"))),
            }
        }
        _ => Err(expr_err(id, field, "boolean condition")),
    }
}

// ---------------------------------------------------------------------------
// Interpolate / Step / Match / Case parsers (f32)
// ---------------------------------------------------------------------------

/// Parse `["interpolate", ["linear"], input, z0, v0, z1, v1, ...]` for f32.
fn parse_interpolate_f32(
    id: &str,
    field: &'static str,
    arr: &[Value],
) -> Result<StyleValue<f32>, StyleSpecError> {
    // arr[0] = "interpolate", arr[1] = interpolation type, arr[2] = input, arr[3..] = stop pairs
    if arr.len() < 5 || (arr.len() - 3) % 2 != 0 {
        return Err(expr_err(id, field, "interpolate with even stop pairs"));
    }
    let input = parse_numeric_input(id, field, &arr[2])?;
    let mut stops = Vec::with_capacity((arr.len() - 3) / 2);
    for chunk in arr[3..].chunks(2) {
        let z = chunk[0].as_f64().ok_or_else(|| expr_err(id, field, "interpolate stop zoom"))? as f32;
        let v = chunk[1].as_f64().ok_or_else(|| expr_err(id, field, "interpolate stop value"))? as f32;
        stops.push((z, v));
    }
    Ok(Expression::Interpolate { input: Box::new(input), stops })
}

/// Parse `["step", input, default, z0, v0, z1, v1, ...]` for f32.
fn parse_step_f32(
    id: &str,
    field: &'static str,
    arr: &[Value],
) -> Result<StyleValue<f32>, StyleSpecError> {
    if arr.len() < 3 {
        return Err(expr_err(id, field, "step expression"));
    }
    let input = parse_numeric_input(id, field, &arr[1])?;
    let default = arr[2].as_f64().ok_or_else(|| expr_err(id, field, "step default"))? as f32;
    let mut stops = Vec::new();
    for chunk in arr[3..].chunks(2) {
        if chunk.len() == 2 {
            let z = chunk[0].as_f64().ok_or_else(|| expr_err(id, field, "step threshold"))? as f32;
            let v = chunk[1].as_f64().ok_or_else(|| expr_err(id, field, "step value"))? as f32;
            stops.push((z, v));
        }
    }
    Ok(Expression::Step { input: Box::new(input), default, stops })
}

/// Parse `["case", cond1, val1, ..., fallback]` for f32.
fn parse_case_f32(
    id: &str,
    field: &'static str,
    arr: &[Value],
) -> Result<StyleValue<f32>, StyleSpecError> {
    // arr = ["case", cond1, val1, ..., condN, valN, fallback]
    // After "case": (arr.len()-1) interior elements = pairs + 1 fallback → must be odd, i.e. (arr.len()-1) is odd.
    if arr.len() < 4 || (arr.len() - 1) % 2 == 0 {
        return Err(expr_err(id, field, "case expression"));
    }
    // Last element is fallback, preceding pairs are (condition, value).
    let fallback = arr.last().unwrap().as_f64()
        .ok_or_else(|| expr_err(id, field, "case fallback"))? as f32;
    let mut branches = Vec::new();
    for chunk in arr[1..arr.len() - 1].chunks(2) {
        let cond = parse_bool_condition(id, field, &chunk[0])?;
        let val = chunk[1].as_f64().ok_or_else(|| expr_err(id, field, "case value"))? as f32;
        branches.push((cond, val));
    }
    Ok(Expression::Case { branches, fallback })
}

// ---------------------------------------------------------------------------
// Interpolate / Step / Match / Case parsers (color)
// ---------------------------------------------------------------------------

/// Parse `["interpolate", ["linear"], input, z0, c0, z1, c1, ...]` for colors.
fn parse_interpolate_color(
    id: &str,
    field: &'static str,
    arr: &[Value],
) -> Result<StyleValue<[f32; 4]>, StyleSpecError> {
    if arr.len() < 5 || (arr.len() - 3) % 2 != 0 {
        return Err(expr_err(id, field, "interpolate with even stop pairs"));
    }
    let input = parse_numeric_input(id, field, &arr[2])?;
    let mut stops = Vec::with_capacity((arr.len() - 3) / 2);
    for chunk in arr[3..].chunks(2) {
        let z = chunk[0].as_f64().ok_or_else(|| expr_err(id, field, "interpolate stop zoom"))? as f32;
        let c = parse_json_color(id, field, &chunk[1])?;
        stops.push((z, c));
    }
    Ok(Expression::Interpolate { input: Box::new(input), stops })
}

/// Parse `["step", input, default_color, z0, c0, z1, c1, ...]` for colors.
fn parse_step_color(
    id: &str,
    field: &'static str,
    arr: &[Value],
) -> Result<StyleValue<[f32; 4]>, StyleSpecError> {
    if arr.len() < 3 {
        return Err(expr_err(id, field, "step expression"));
    }
    let input = parse_numeric_input(id, field, &arr[1])?;
    let default = parse_json_color(id, field, &arr[2])?;
    let mut stops = Vec::new();
    for chunk in arr[3..].chunks(2) {
        if chunk.len() == 2 {
            let z = chunk[0].as_f64().ok_or_else(|| expr_err(id, field, "step threshold"))? as f32;
            let c = parse_json_color(id, field, &chunk[1])?;
            stops.push((z, c));
        }
    }
    Ok(Expression::Step { input: Box::new(input), default, stops })
}

/// Parse `["match", input, label1, color1, ..., fallback_color]`.
fn parse_match_color(
    id: &str,
    field: &'static str,
    arr: &[Value],
) -> Result<StyleValue<[f32; 4]>, StyleSpecError> {
    if arr.len() < 4 {
        return Err(expr_err(id, field, "match expression"));
    }
    let input = parse_string_input(id, field, &arr[1])?;
    let fallback = parse_json_color(id, field, arr.last().unwrap())?;
    let mut cases = Vec::new();
    // arr[2..last-1] are label/value pairs.
    let pairs = &arr[2..arr.len() - 1];
    for chunk in pairs.chunks(2) {
        if chunk.len() == 2 {
            let label = chunk[0].as_str().ok_or_else(|| expr_err(id, field, "match label"))?;
            let color = parse_json_color(id, field, &chunk[1])?;
            cases.push((label.to_owned(), color));
        }
    }
    Ok(Expression::Match { input: Box::new(input), cases, fallback })
}

/// Parse `["case", cond1, color1, ..., fallback_color]`.
fn parse_case_color(
    id: &str,
    field: &'static str,
    arr: &[Value],
) -> Result<StyleValue<[f32; 4]>, StyleSpecError> {
    // arr = ["case", cond1, val1, ..., condN, valN, fallback] → need at least 4 elements
    if arr.len() < 4 || (arr.len() - 1) % 2 == 0 {
        return Err(expr_err(id, field, "case expression"));
    }
    let fallback = parse_json_color(id, field, arr.last().unwrap())?;
    let mut branches = Vec::new();
    for chunk in arr[1..arr.len() - 1].chunks(2) {
        if chunk.len() == 2 {
            let cond = parse_bool_condition(id, field, &chunk[0])?;
            let color = parse_json_color(id, field, &chunk[1])?;
            branches.push((cond, color));
        }
    }
    Ok(Expression::Case { branches, fallback })
}

// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------

/// Parse a color from a JSON value (string or array).
fn parse_json_color(
    id: &str,
    field: &'static str,
    value: &Value,
) -> Result<[f32; 4], StyleSpecError> {
    match value {
        Value::String(s) => parse_color_string(id, field, s),
        Value::Array(a) => parse_color_array(id, field, a),
        _ => Err(expr_err(id, field, "color value")),
    }
}

/// Build a standardised expression parse error.
fn expr_err(id: &str, field: &'static str, expected: &str) -> StyleSpecError {
    StyleSpecError::InvalidField {
        id: id.to_owned(),
        field,
        expected: Box::leak(format!("expression: {expected}").into_boxed_str()),
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::geometry::{Feature, FeatureCollection, Geometry, Point};
    use crate::models::{ModelInstance, ModelMesh};
    use crate::style::{CanvasSource, GeoJsonSource, ImageSource, ModelSource, VectorTileSource, VideoSource};
    use crate::tile_source::{TileData, TileResponse, TileSource};
    use rustial_math::{GeoCoord, TileId};

    #[derive(Clone, Default)]
    struct StubTileSource;

    impl TileSource for StubTileSource {
        fn request(&self, _id: TileId) {}
        fn poll(&self) -> Vec<(TileId, Result<TileResponse, crate::TileError>)> {
            Vec::new()
        }
    }

    fn sample_features() -> FeatureCollection {
        FeatureCollection {
            features: vec![Feature {
                geometry: Geometry::Point(Point {
                    coord: GeoCoord::from_lat_lon(51.1, 17.0),
                }),
                properties: HashMap::new(),
            }],
        }
    }

    #[test]
    fn parses_and_resolves_style_json() {
        let json = r##"
        {
          "version": 8,
          "projection": { "type": "equirectangular" },
           "terrain": { "source": "dem" },
           "sources": {
             "base": { "type": "raster" },
             "dem": { "type": "raster-dem" },
             "places": { "type": "geojson" },
             "labels": { "type": "vector" },
             "hero": { "type": "model" }
           },
           "layers": [
             { "id": "bg", "type": "background", "paint": { "background-color": "#112233" } },
             { "id": "raster", "type": "raster", "source": "base", "paint": { "raster-opacity": 0.75 } },
             { "id": "fill", "type": "fill", "source": "places", "paint": { "fill-color": "#ff0000" } },
             { "id": "symbol", "type": "symbol", "source": "labels", "layout": { "text-field": "name", "text-size": 18 }, "paint": { "text-color": "#00ff00" } },
             { "id": "model", "type": "model", "source": "hero" }
           ]
        }
        "##;

        let spec = parse_style_json(json).expect("parse spec");
        let mut registry = StyleSourceRegistry::new();
        registry.set_source("base", StyleSource::Raster(crate::style::RasterSource::new(|| Box::new(StubTileSource))));
        registry.set_source("dem", StyleSource::Terrain(crate::style::TerrainSource::new(|| Box::new(crate::terrain::FlatElevationSource::new(4, 4)))));
        registry.set_source("places", StyleSource::GeoJson(GeoJsonSource::new(sample_features())));
        registry.set_source("labels", StyleSource::VectorTile(VectorTileSource::new(sample_features())));
        registry.set_source(
            "hero",
            StyleSource::Model(ModelSource::new(vec![ModelInstance::new(
                GeoCoord::from_lat_lon(0.0, 0.0),
                ModelMesh {
                    positions: vec![[0.0, 0.0, 0.0]],
                    normals: vec![[0.0, 0.0, 1.0]],
                    uvs: vec![[0.0, 0.0]],
                    indices: vec![0],
                },
            )])),
        );

        let document = spec.resolve(&registry).expect("resolve");
        assert_eq!(document.layers().len(), 5);
        assert_eq!(document.terrain_source(), Some("dem"));
        assert_eq!(document.projection(), StyleProjection::Equirectangular);
    }

    #[test]
    fn parses_projection_from_json_without_layers() {
        let json = r##"
        {
          "version": 8,
          "projection": { "type": "globe" },
           "sources": {},
           "layers": []
         }
         "##;

        let spec = parse_style_json(json).expect("parse spec");
        assert!(matches!(
            spec.projection,
            Some(StyleSpecProjection {
                projection_type: StyleSpecProjectionType::Globe
            })
        ));

        let registry = StyleSourceRegistry::new();
        let document = spec.resolve(&registry).expect("resolve");
        assert_eq!(document.projection(), StyleProjection::Globe);
    }

    #[test]
    fn parses_vertical_perspective_projection_from_json() {
        let json = r##"
        {
          "version": 8,
          "projection": { "type": "vertical-perspective" },
          "sources": {},
          "layers": []
        }
        "##;

        let spec = parse_style_json(json).expect("parse spec");
        assert!(matches!(
            spec.projection,
            Some(StyleSpecProjection {
                projection_type: StyleSpecProjectionType::VerticalPerspective
            })
        ));

        let registry = StyleSourceRegistry::new();
        let document = spec.resolve(&registry).expect("resolve");
        assert_eq!(document.projection(), StyleProjection::VerticalPerspective);
    }

    #[test]
    fn parses_zoom_stop_values_from_json() {
        let json = r##"
        {
          "version": 8,
          "sources": { "places": { "type": "geojson" } },
          "layers": [
            {
              "id": "circles",
              "type": "circle",
              "source": "places",
              "paint": {
                "circle-radius": { "stops": [[5, 4], [10, 12]] },
                "circle-color": { "stops": [[5, "#000000"], [10, "#ffffff"]] }
              }
            }
          ]
        }
        "##;

        let spec = parse_style_json(json).expect("parse spec");
        let mut registry = StyleSourceRegistry::new();
        registry.set_source("places", StyleSource::GeoJson(GeoJsonSource::new(sample_features())));
        let document = spec.resolve(&registry).expect("resolve");

        match &document.layers()[0] {
            StyleLayer::Circle(layer) => {
                assert!(matches!(layer.radius, StyleValue::ZoomStops(_)));
                assert!(matches!(layer.color, StyleValue::ZoomStops(_)));
            }
            other => panic!("expected circle layer, got {other:?}"),
        }
    }

    #[test]
    fn parses_symbol_overlap_placement_spacing_max_angle_keep_upright_writing_mode_and_offset() {
        let json = r##"
        {
          "version": 8,
          "sources": { "labels": { "type": "vector" } },
          "layers": [
            {
              "id": "symbol",
              "type": "symbol",
              "source": "labels",
              "layout": {
                "symbol-placement": "line",
                "text-allow-overlap": true,
                "icon-allow-overlap": false,
                "text-optional": true,
                "icon-optional": false,
                "text-ignore-placement": true,
                "icon-ignore-placement": false,
                "text-radial-offset": 2,
                "text-anchor": "top-right",
                "text-justify": "auto",
                "text-transform": "uppercase",
                "text-max-width": 8,
                "text-line-height": 1.5,
                "text-letter-spacing": 0.25,
                "icon-text-fit": "both",
                "icon-text-fit-padding": [1, 2, 3, 4],
                "text-variable-anchor-offset": ["top", [1, 2], "bottom", [3, 4]],
                "symbol-sort-key": 7,
                "symbol-spacing": 320,
                "text-max-angle": 90,
                "text-keep-upright": false,
                "text-field": "name",
                "text-variable-anchor": ["center", "top"],
                "text-writing-mode": "vertical",
                "text-offset": [1, 2]
              }
            }
          ]
        }
        "##;

        let spec = parse_style_json(json).expect("parse spec");
        let mut registry = StyleSourceRegistry::new();
        registry.set_source("labels", StyleSource::VectorTile(VectorTileSource::new(sample_features())));
        let document = spec.resolve(&registry).expect("resolve");

        match &document.layers()[0] {
            StyleLayer::Symbol(layer) => {
                assert_eq!(layer.text_allow_overlap.as_ref().map(StyleValue::evaluate), Some(true));
                assert_eq!(layer.icon_allow_overlap.as_ref().map(StyleValue::evaluate), Some(false));
                assert_eq!(layer.text_optional.as_ref().map(StyleValue::evaluate), Some(true));
                assert_eq!(layer.icon_optional.as_ref().map(StyleValue::evaluate), Some(false));
                assert_eq!(layer.text_ignore_placement.as_ref().map(StyleValue::evaluate), Some(true));
                assert_eq!(layer.icon_ignore_placement.as_ref().map(StyleValue::evaluate), Some(false));
                assert_eq!(layer.radial_offset.as_ref().map(StyleValue::evaluate), Some(2.0));
                assert_eq!(layer.anchor, SymbolAnchor::TopRight);
                assert_eq!(layer.justify.evaluate(), SymbolTextJustify::Auto);
                assert_eq!(layer.transform.evaluate(), SymbolTextTransform::Uppercase);
                assert_eq!(layer.max_width.as_ref().map(StyleValue::evaluate), Some(8.0));
                assert_eq!(layer.line_height.as_ref().map(StyleValue::evaluate), Some(1.5));
                assert_eq!(layer.letter_spacing.as_ref().map(StyleValue::evaluate), Some(0.25));
                assert_eq!(layer.icon_text_fit.evaluate(), SymbolIconTextFit::Both);
                assert_eq!(layer.icon_text_fit_padding, [1.0, 2.0, 3.0, 4.0]);
                assert_eq!(
                    layer.variable_anchor_offsets,
                    Some(vec![
                        (SymbolAnchor::Top, [1.0, 2.0]),
                        (SymbolAnchor::Bottom, [3.0, 4.0]),
                    ])
                );
                assert_eq!(layer.sort_key.as_ref().map(StyleValue::evaluate), Some(7.0));
                assert_eq!(layer.placement, SymbolPlacement::Line);
                assert_eq!(layer.spacing.evaluate(), 320.0);
                assert_eq!(layer.max_angle.evaluate(), 90.0);
                assert!(!layer.keep_upright.evaluate());
                assert_eq!(layer.variable_anchors, vec![SymbolAnchor::Center, SymbolAnchor::Top]);
                assert_eq!(layer.writing_mode, SymbolWritingMode::Vertical);
                assert_eq!(layer.offset, [1.0, 2.0]);
            }
            other => panic!("expected symbol layer, got {other:?}"),
        }
    }

    #[test]
    fn parses_source_layer_for_vector_style_layers() {
        let json = r##"
        {
          "version": 8,
          "sources": { "labels": { "type": "vector" } },
          "layers": [
            {
              "id": "roads",
              "type": "line",
              "source": "labels",
              "source-layer": "transport"
            }
          ]
        }
        "##;

        let spec = parse_style_json(json).expect("parse spec");
        assert_eq!(spec.layers.len(), 1);
        assert_eq!(spec.layers[0].source_layer.as_deref(), Some("transport"));

        let mut registry = StyleSourceRegistry::new();
        let mut source_layers = HashMap::new();
        source_layers.insert(
            "transport".to_string(),
            FeatureCollection {
                features: vec![Feature {
                    geometry: Geometry::Point(Point {
                        coord: GeoCoord::from_lat_lon(1.0, 2.0),
                    }),
                    properties: HashMap::new(),
                }],
            },
        );
        registry.set_source(
            "labels",
            StyleSource::VectorTile(VectorTileSource::from_source_layers(source_layers)),
        );

        let document = spec.resolve(&registry).expect("resolve");
        match &document.layers()[0] {
            StyleLayer::Line(layer) => {
                assert_eq!(layer.source_layer.as_deref(), Some("transport"));
            }
            other => panic!("expected line layer, got {other:?}"),
        }
    }

    // -----------------------------------------------------------------------
    // Expression JSON parsing tests
    // -----------------------------------------------------------------------

    #[test]
    fn f32_expression_interpolate_on_zoom() {
        let json = r##"
        {
          "version": 8,
          "sources": { "s": { "type": "vector" } },
          "layers": [
            {
              "id": "l",
              "type": "line",
              "source": "s",
              "paint": {
                "line-width": ["interpolate", ["linear"], ["zoom"], 0, 1, 20, 10]
              }
            }
          ]
        }
        "##;
        let spec = parse_style_json(json).expect("parse");
        let mut registry = StyleSourceRegistry::new();
        registry.set_source("s", StyleSource::VectorTile(VectorTileSource::new(sample_features())));
        let doc = spec.resolve(&registry).expect("resolve");
        match &doc.layers()[0] {
            StyleLayer::Line(layer) => {
                let ctx = crate::style::StyleEvalContext::new(10.0);
                let width = layer.width.evaluate_with_context(ctx);
                assert!((width - 5.5).abs() < 0.1, "expected ~5.5, got {width}");
            }
            other => panic!("expected line, got {other:?}"),
        }
    }

    #[test]
    fn f32_expression_step_on_zoom() {
        let json = r##"
        {
          "version": 8,
          "sources": { "s": { "type": "vector" } },
          "layers": [
            {
              "id": "l",
              "type": "circle",
              "source": "s",
              "paint": {
                "circle-radius": ["step", ["zoom"], 2, 5, 4, 10, 8]
              }
            }
          ]
        }
        "##;
        let spec = parse_style_json(json).expect("parse");
        let mut registry = StyleSourceRegistry::new();
        registry.set_source("s", StyleSource::VectorTile(VectorTileSource::new(sample_features())));
        let doc = spec.resolve(&registry).expect("resolve");
        match &doc.layers()[0] {
            StyleLayer::Circle(layer) => {
                use crate::expression::ExprEvalContext;
                // Below first stop
                assert!((layer.radius.eval_full(&ExprEvalContext::zoom_only(3.0)) - 2.0).abs() < f32::EPSILON);
                // At first stop
                assert!((layer.radius.eval_full(&ExprEvalContext::zoom_only(5.0)) - 4.0).abs() < f32::EPSILON);
                // Between stops
                assert!((layer.radius.eval_full(&ExprEvalContext::zoom_only(7.0)) - 4.0).abs() < f32::EPSILON);
                // At second stop
                assert!((layer.radius.eval_full(&ExprEvalContext::zoom_only(10.0)) - 8.0).abs() < f32::EPSILON);
                // Above all stops
                assert!((layer.radius.eval_full(&ExprEvalContext::zoom_only(15.0)) - 8.0).abs() < f32::EPSILON);
            }
            other => panic!("expected circle, got {other:?}"),
        }
    }

    #[test]
    fn color_expression_match_on_property() {
        let json = r##"
        {
          "version": 8,
          "sources": { "s": { "type": "vector" } },
          "layers": [
            {
              "id": "l",
              "type": "fill",
              "source": "s",
              "paint": {
                "fill-color": ["match", ["get", "type"], "residential", "#0000ff", "commercial", "#ff0000", "#888888"]
              }
            }
          ]
        }
        "##;
        let spec = parse_style_json(json).expect("parse");
        let mut registry = StyleSourceRegistry::new();
        registry.set_source("s", StyleSource::VectorTile(VectorTileSource::new(sample_features())));
        let doc = spec.resolve(&registry).expect("resolve");
        match &doc.layers()[0] {
            StyleLayer::Fill(layer) => {
                use crate::expression::ExprEvalContext;
                use crate::geometry::PropertyValue;

                let mut props = std::collections::HashMap::new();
                props.insert("type".to_string(), PropertyValue::String("residential".to_string()));
                let ctx = ExprEvalContext::with_feature(10.0, &props);
                let color = layer.fill_color.eval_full(&ctx);
                assert!((color[0] - 0.0).abs() < 0.01);
                assert!((color[2] - 1.0).abs() < 0.01);

                props.insert("type".to_string(), PropertyValue::String("commercial".to_string()));
                let ctx = ExprEvalContext::with_feature(10.0, &props);
                let color = layer.fill_color.eval_full(&ctx);
                assert!((color[0] - 1.0).abs() < 0.01);
                assert!((color[2] - 0.0).abs() < 0.01);

                // fallback
                props.insert("type".to_string(), PropertyValue::String("industrial".to_string()));
                let ctx = ExprEvalContext::with_feature(10.0, &props);
                let color = layer.fill_color.eval_full(&ctx);
                assert!((color[0] - 0.533).abs() < 0.01);
            }
            other => panic!("expected fill, got {other:?}"),
        }
    }

    #[test]
    fn f32_expression_get_property() {
        let json = r##"
        {
          "version": 8,
          "sources": { "s": { "type": "vector" } },
          "layers": [
            {
              "id": "l",
              "type": "fill-extrusion",
              "source": "s",
              "paint": {
                "fill-extrusion-height": ["get", "height"],
                "fill-extrusion-base": ["get", "base"]
              }
            }
          ]
        }
        "##;
        let spec = parse_style_json(json).expect("parse");
        let mut registry = StyleSourceRegistry::new();
        registry.set_source("s", StyleSource::VectorTile(VectorTileSource::new(sample_features())));
        let doc = spec.resolve(&registry).expect("resolve");
        match &doc.layers()[0] {
            StyleLayer::FillExtrusion(layer) => {
                use crate::expression::ExprEvalContext;
                use crate::geometry::PropertyValue;
                let mut props = std::collections::HashMap::new();
                props.insert("height".to_string(), PropertyValue::Number(50.0));
                props.insert("base".to_string(), PropertyValue::Number(10.0));
                let ctx = ExprEvalContext::with_feature(14.0, &props);
                assert!((layer.height.eval_full(&ctx) - 50.0).abs() < f32::EPSILON);
                assert!((layer.base.eval_full(&ctx) - 10.0).abs() < f32::EPSILON);
            }
            other => panic!("expected fill-extrusion, got {other:?}"),
        }
    }

    #[test]
    fn f32_expression_case_with_comparison() {
        let json = r##"
        {
          "version": 8,
          "sources": { "s": { "type": "vector" } },
          "layers": [
            {
              "id": "l",
              "type": "line",
              "source": "s",
              "paint": {
                "line-width": ["case", [">", ["get", "lanes"], 2], 8, 2]
              }
            }
          ]
        }
        "##;
        let spec = parse_style_json(json).expect("parse");
        let mut registry = StyleSourceRegistry::new();
        registry.set_source("s", StyleSource::VectorTile(VectorTileSource::new(sample_features())));
        let doc = spec.resolve(&registry).expect("resolve");
        match &doc.layers()[0] {
            StyleLayer::Line(layer) => {
                use crate::expression::ExprEvalContext;
                use crate::geometry::PropertyValue;

                // lanes = 4 > 2, so width = 8
                let mut props = std::collections::HashMap::new();
                props.insert("lanes".to_string(), PropertyValue::Number(4.0));
                let ctx = ExprEvalContext::with_feature(14.0, &props);
                assert!((layer.width.eval_full(&ctx) - 8.0).abs() < f32::EPSILON);

                // lanes = 1, not > 2, so width = 2 (fallback)
                props.insert("lanes".to_string(), PropertyValue::Number(1.0));
                let ctx = ExprEvalContext::with_feature(14.0, &props);
                assert!((layer.width.eval_full(&ctx) - 2.0).abs() < f32::EPSILON);
            }
            other => panic!("expected line, got {other:?}"),
        }
    }
}