oxiforge 0.3.0

// SPDX-License-Identifier: GPL-3.0-only
//! IR model types for the oxiforge YAML language.

use std::{collections::BTreeMap, fmt};

use serde::{
    Deserialize,
    de::{self, Deserializer, Visitor},
};

// ── Value types ──────────────────────────────────────────────────────

/// Color value: hex integer (`0xFF0000`), CSS hex string (`"#F00"`), or named
/// palette.
#[derive(Debug, Clone, PartialEq)]
pub enum Color {
    /// RGB hex value, e.g. `0xFF9500`.
    Hex(u32),
    /// Named palette color, e.g. `"red"`.
    Named(String),
}

impl<'de> Deserialize<'de> for Color {
    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        struct ColorVisitor;
        impl Visitor<'_> for ColorVisitor {
            type Value = Color;
            fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result {
                write!(f, "a color (hex integer, \"#RRGGBB\", or name)")
            }
            fn visit_u64<E: de::Error>(self, v: u64) -> Result<Color, E> {
                Ok(Color::Hex(v as u32))
            }
            fn visit_i64<E: de::Error>(self, v: i64) -> Result<Color, E> {
                Ok(Color::Hex(v as u32))
            }
            fn visit_str<E: de::Error>(self, v: &str) -> Result<Color, E> {
                if let Some(hex) = v.strip_prefix('#') {
                    let expanded = match hex.len() {
                        3 => {
                            let mut s = String::with_capacity(6);
                            for c in hex.chars() {
                                s.push(c);
                                s.push(c);
                            }
                            s
                        }
                        6 => hex.to_string(),
                        _ => return Err(de::Error::custom(format!("invalid CSS hex color: {v}"))),
                    };
                    let val = u32::from_str_radix(&expanded, 16)
                        .map_err(|_| de::Error::custom(format!("invalid hex digits: {v}")))?;
                    Ok(Color::Hex(val))
                } else {
                    Ok(Color::Named(v.to_string()))
                }
            }
        }
        deserializer.deserialize_any(ColorVisitor)
    }
}

/// Dimension: absolute pixels, percentage, or size-to-content.
#[derive(Debug, Clone, PartialEq)]
pub enum Dimension {
    /// Absolute pixel value.
    Pixels(i32),
    /// Percentage (YAML: `"50pct"`).
    Percent(i32),
    /// Size to content (YAML: `"size_content"`).
    SizeContent,
}

impl<'de> Deserialize<'de> for Dimension {
    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        struct DimVisitor;
        impl Visitor<'_> for DimVisitor {
            type Value = Dimension;
            fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result {
                write!(f, "pixels (int), \"Npct\", or \"size_content\"")
            }
            fn visit_i64<E: de::Error>(self, v: i64) -> Result<Dimension, E> {
                Ok(Dimension::Pixels(v as i32))
            }
            fn visit_u64<E: de::Error>(self, v: u64) -> Result<Dimension, E> {
                Ok(Dimension::Pixels(v as i32))
            }
            fn visit_str<E: de::Error>(self, v: &str) -> Result<Dimension, E> {
                if v == "size_content" {
                    Ok(Dimension::SizeContent)
                } else if let Some(n) = v.strip_suffix("pct") {
                    let val: i32 = n.parse().map_err(|_| de::Error::custom(format!("invalid percent: {v}")))?;
                    Ok(Dimension::Percent(val))
                } else {
                    Err(de::Error::custom(format!("invalid dimension: {v}")))
                }
            }
        }
        deserializer.deserialize_any(DimVisitor)
    }
}

/// Opacity: integer 0–255, float 0.0–1.0, or named (`"transp"`, `"cover"`).
#[derive(Debug, Clone, PartialEq)]
pub enum Opacity {
    /// Raw 0–255 value (floats are scaled: 0.5 → 127).
    Value(u8),
    /// Named opacity (`"transp"` = 0, `"cover"` = 255).
    Named(String),
}

impl<'de> Deserialize<'de> for Opacity {
    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        struct OpaVisitor;
        impl Visitor<'_> for OpaVisitor {
            type Value = Opacity;
            fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result {
                write!(f, "opacity (0-255, 0.0-1.0, or \"transp\"/\"cover\")")
            }
            fn visit_i64<E: de::Error>(self, v: i64) -> Result<Opacity, E> {
                Ok(Opacity::Value(v as u8))
            }
            fn visit_u64<E: de::Error>(self, v: u64) -> Result<Opacity, E> {
                Ok(Opacity::Value(v as u8))
            }
            fn visit_f64<E: de::Error>(self, v: f64) -> Result<Opacity, E> {
                Ok(Opacity::Value((v * 255.0) as u8))
            }
            fn visit_str<E: de::Error>(self, v: &str) -> Result<Opacity, E> {
                Ok(Opacity::Named(v.to_string()))
            }
        }
        deserializer.deserialize_any(OpaVisitor)
    }
}

/// Grid track size: pixels, fractional units, or content-sized.
#[derive(Debug, Clone, PartialEq)]
pub enum TrackSize {
    /// Absolute pixel value.
    Pixels(i32),
    /// Fractional unit (YAML: `"1fr"`).
    Fr(i32),
    /// Size to content (YAML: `"content"`).
    Content,
}

impl<'de> Deserialize<'de> for TrackSize {
    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        struct TrackVisitor;
        impl Visitor<'_> for TrackVisitor {
            type Value = TrackSize;
            fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result {
                write!(f, "pixels (int), \"Nfr\", or \"content\"")
            }
            fn visit_i64<E: de::Error>(self, v: i64) -> Result<TrackSize, E> {
                Ok(TrackSize::Pixels(v as i32))
            }
            fn visit_u64<E: de::Error>(self, v: u64) -> Result<TrackSize, E> {
                Ok(TrackSize::Pixels(v as i32))
            }
            fn visit_str<E: de::Error>(self, v: &str) -> Result<TrackSize, E> {
                if v == "content" {
                    Ok(TrackSize::Content)
                } else if let Some(n) = v.strip_suffix("fr") {
                    let val: i32 = n.parse().map_err(|_| de::Error::custom(format!("invalid fr: {v}")))?;
                    Ok(TrackSize::Fr(val))
                } else {
                    Err(de::Error::custom(format!("invalid track size: {v}")))
                }
            }
        }
        deserializer.deserialize_any(TrackVisitor)
    }
}

// ── Enums ────────────────────────────────────────────────────────────

/// Widget alignment relative to parent. Maps to LVGL `lv_align_t`.
#[derive(Debug, Clone, Copy, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum Alignment {
    /// Top-left corner.
    TopLeft,
    /// Top center.
    TopMid,
    /// Top-right corner.
    TopRight,
    /// Left center.
    LeftMid,
    /// Dead center.
    Center,
    /// Right center.
    RightMid,
    /// Bottom-left corner.
    BottomLeft,
    /// Bottom center.
    BottomMid,
    /// Bottom-right corner.
    BottomRight,
    /// Outside top-left.
    OutTopLeft,
    /// Outside top center.
    OutTopMid,
    /// Outside top-right.
    OutTopRight,
    /// Outside bottom-left.
    OutBottomLeft,
    /// Outside bottom center.
    OutBottomMid,
    /// Outside bottom-right.
    OutBottomRight,
    /// Outside left-top.
    OutLeftTop,
    /// Outside left center.
    OutLeftMid,
    /// Outside left-bottom.
    OutLeftBottom,
    /// Outside right-top.
    OutRightTop,
    /// Outside right center.
    OutRightMid,
    /// Outside right-bottom.
    OutRightBottom,
}

/// Flex layout flow direction. Maps to LVGL `lv_flex_flow_t`.
#[derive(Debug, Clone, Copy, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum FlexFlow {
    /// Horizontal left-to-right.
    Row,
    /// Vertical top-to-bottom.
    Column,
    /// Row with wrapping.
    RowWrap,
    /// Column with wrapping.
    ColumnWrap,
    /// Reversed row.
    RowReverse,
    /// Reversed column.
    ColumnReverse,
    /// Reversed row with wrapping.
    RowWrapReverse,
    /// Reversed column with wrapping.
    ColumnWrapReverse,
}

/// Flex alignment. Maps to LVGL `lv_flex_align_t`.
#[derive(Debug, Clone, Copy, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum FlexAlign {
    /// Pack items at start.
    Start,
    /// Pack items at end.
    End,
    /// Center items.
    Center,
    /// Distribute with equal spacing.
    SpaceEvenly,
    /// Distribute with space around each item.
    SpaceAround,
    /// Distribute with space only between items.
    SpaceBetween,
}

/// Grid alignment. Maps to LVGL `lv_grid_align_t`.
#[derive(Debug, Clone, Copy, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum GridAlign {
    /// Align to start.
    Start,
    /// Center.
    Center,
    /// Align to end.
    End,
    /// Stretch to fill.
    Stretch,
    /// Equal spacing.
    SpaceEvenly,
    /// Space around items.
    SpaceAround,
    /// Space between items.
    SpaceBetween,
}

/// Text alignment. Maps to LVGL `lv_text_align_t`.
#[derive(Debug, Clone, Copy, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum TextAlign {
    /// Automatic (LTR/RTL).
    Auto,
    /// Left-aligned.
    Left,
    /// Centered.
    Center,
    /// Right-aligned.
    Right,
}

/// Label long-text mode. Maps to LVGL `lv_label_long_mode_t`.
#[derive(Debug, Clone, Copy, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum LabelLongMode {
    /// Wrap text to next line.
    Wrap,
    /// Expand widget to fit text.
    Expand,
    /// Clip text at widget boundary.
    Clip,
    /// Scroll text circularly.
    ScrollCircular,
}

/// Scale display mode. Maps to LVGL `lv_scale_mode_t`.
#[derive(Debug, Clone, Copy, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum ScaleMode {
    /// Horizontal with ticks on top.
    HorizontalTop,
    /// Horizontal with ticks on bottom.
    HorizontalBottom,
    /// Vertical with ticks on left.
    VerticalLeft,
    /// Vertical with ticks on right.
    VerticalRight,
    /// Round scale, ticks on inner edge.
    RoundInner,
    /// Round scale, ticks on outer edge.
    RoundOuter,
}

/// Scroll direction constraint.
#[derive(Debug, Clone, Copy, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum ScrollDir {
    /// No scrolling.
    None,
    /// Horizontal only.
    Hor,
    /// Vertical only.
    Ver,
    /// Both directions.
    All,
}

/// Scrollbar visibility mode.
#[derive(Debug, Clone, Copy, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum ScrollbarMode {
    /// Never show.
    Off,
    /// Always show.
    On,
    /// Show while scrolling.
    Active,
    /// Show when content overflows.
    Auto,
}

/// Text decoration.
#[derive(Debug, Clone, Copy, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum TextDecor {
    /// No decoration.
    None,
    /// Underline.
    Underline,
    /// Strikethrough.
    Strikethrough,
}

/// Border side(s) to draw.
#[derive(Debug, Clone, Copy, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum BorderSide {
    /// No border.
    None,
    /// Top edge only.
    Top,
    /// Bottom edge only.
    Bottom,
    /// Left edge only.
    Left,
    /// Right edge only.
    Right,
    /// All edges.
    Full,
}

/// Dropdown list expansion direction.
#[derive(Debug, Clone, Copy, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum DdDir {
    /// Expand downward.
    Bottom,
    /// Expand upward.
    Top,
    /// Expand left.
    Left,
    /// Expand right.
    Right,
}

/// Roller infinite/normal mode.
#[derive(Debug, Clone, Copy, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum RollerMode {
    /// Finite list.
    Normal,
    /// Wraps around endlessly.
    Infinite,
}

/// Bar fill mode.
#[derive(Debug, Clone, Copy, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum BarMode {
    /// Fill from minimum to value.
    Normal,
    /// Two-ended range indicator.
    Range,
    /// Symmetrical around center.
    Symmetrical,
}

/// Arc draw mode.
#[derive(Debug, Clone, Copy, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum ArcMode {
    /// Normal (clockwise fill).
    Normal,
    /// Reverse (counter-clockwise fill).
    Reverse,
    /// Symmetrical around start.
    Symmetrical,
}

/// Container layout algorithm.
#[derive(Debug, Clone, Copy, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum LayoutKind {
    /// No automatic layout.
    None,
    /// Flexbox layout.
    Flex,
    /// CSS-grid-style layout.
    Grid,
}

/// Bar orientation override.
#[derive(Debug, Clone, Copy, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum BarOrientation {
    /// Automatic (based on dimensions).
    Auto,
    /// Force horizontal.
    Horizontal,
    /// Force vertical.
    Vertical,
}

/// Slider orientation override.
#[derive(Debug, Clone, Copy, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum SliderOrientation {
    /// Automatic (based on dimensions).
    Auto,
    /// Force horizontal.
    Horizontal,
    /// Force vertical.
    Vertical,
}

/// Keyboard key layout mode.
#[cfg(feature = "widget-keyboard")]
#[derive(Debug, Clone, Copy, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum KeyboardMode {
    /// Lowercase text.
    TextLower,
    /// Uppercase text.
    TextUpper,
    /// Special characters.
    Special,
    /// Numeric keypad.
    Number,
}

/// Chart visualization type.
#[cfg(feature = "widget-chart")]
#[derive(Debug, Clone, Copy, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum ChartType {
    /// No chart drawn.
    None,
    /// Line chart.
    Line,
    /// Smooth curve chart.
    Curve,
    /// Vertical bar chart.
    Bar,
    /// Stacked bar chart.
    Stacked,
    /// X-Y scatter plot.
    Scatter,
}

/// Arc label text direction.
#[cfg(feature = "widget-arc-label")]
#[derive(Debug, Clone, Copy, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum ArcLabelDir {
    /// Text flows clockwise.
    Clockwise,
    /// Text flows counter-clockwise.
    CounterClockwise,
}

/// Spangroup overflow mode.
#[cfg(feature = "widget-spangroup")]
#[derive(Debug, Clone, Copy, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum SpanOverflow {
    /// Clip overflowing text.
    Clip,
    /// Show ellipsis for overflow.
    Ellipsis,
}

/// Spangroup layout mode.
#[cfg(feature = "widget-spangroup")]
#[derive(Debug, Clone, Copy, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum SpanMode {
    /// Fixed height.
    Fixed,
    /// Expand to fit content.
    Expand,
    /// Break lines.
    Break,
}

// ── Style properties ─────────────────────────────────────────────────

/// LVGL style properties shared across widgets, style definitions, parts, and
/// states.
///
/// Each field maps to an `lv_style_set_*` call. All fields are optional;
/// `None` means "don't touch this property."
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct StyleProps {
    /// Overall widget opacity (0–255).
    pub opa: Option<Opacity>,
    /// Background color.
    pub bg_color: Option<Color>,
    /// Background opacity (0–255).
    pub bg_opa: Option<Opacity>,
    /// Named gradient reference (must match a `gradients[].id`).
    pub bg_grad: Option<String>,
    /// Border color.
    pub border_color: Option<Color>,
    /// Border width in pixels.
    pub border_width: Option<i16>,
    /// Border opacity.
    pub border_opa: Option<Opacity>,
    /// Which border side(s) to draw.
    pub border_side: Option<BorderSide>,
    /// Outline color.
    pub outline_color: Option<Color>,
    /// Outline width in pixels.
    pub outline_width: Option<i16>,
    /// Outline opacity.
    pub outline_opa: Option<Opacity>,
    /// Outline padding (gap between outline and widget edge).
    pub outline_pad: Option<i16>,
    /// Shadow color.
    pub shadow_color: Option<Color>,
    /// Shadow blur width.
    pub shadow_width: Option<i16>,
    /// Shadow horizontal offset.
    pub shadow_ofs_x: Option<i16>,
    /// Shadow vertical offset.
    pub shadow_ofs_y: Option<i16>,
    /// Shadow spread.
    pub shadow_spread: Option<i16>,
    /// Shadow opacity.
    pub shadow_opa: Option<Opacity>,
    /// Uniform padding (all sides).
    pub pad_all: Option<i16>,
    /// Top padding.
    pub pad_top: Option<i16>,
    /// Bottom padding.
    pub pad_bottom: Option<i16>,
    /// Left padding.
    pub pad_left: Option<i16>,
    /// Right padding.
    pub pad_right: Option<i16>,
    /// Row gap (flex/grid).
    pub pad_row: Option<i16>,
    /// Column gap (flex/grid).
    pub pad_column: Option<i16>,
    /// Corner radius.
    pub radius: Option<i16>,
    /// Clip child drawing to rounded corners.
    pub clip_corner: Option<bool>,
    /// Horizontal translation offset.
    pub translate_x: Option<i16>,
    /// Vertical translation offset.
    pub translate_y: Option<i16>,
    /// Text color.
    pub text_color: Option<Color>,
    /// Text opacity.
    pub text_opa: Option<Opacity>,
    /// Font name (maps to `Font::` constant).
    pub text_font: Option<String>,
    /// Text alignment.
    pub text_align: Option<TextAlign>,
    /// Text decoration (underline, strikethrough).
    pub text_decor: Option<TextDecor>,
    /// Line color (for Line widget).
    pub line_color: Option<Color>,
    /// Line width.
    pub line_width: Option<i16>,
    /// Line opacity.
    pub line_opa: Option<Opacity>,
    /// Round line endpoints.
    pub line_rounded: Option<bool>,
    /// Arc track/indicator color.
    pub arc_color: Option<Color>,
    /// Arc track/indicator width.
    pub arc_width: Option<i16>,
    /// Arc opacity.
    pub arc_opa: Option<Opacity>,
    /// Round arc endpoints.
    pub arc_rounded: Option<bool>,
    /// Rotation transform (degrees × 10).
    pub transform_angle: Option<i16>,
    /// Zoom transform (256 = 100%).
    pub transform_zoom: Option<u16>,
    /// Background image source — name of an extern `lv_image_dsc_t` symbol
    /// (a compiled-in image descriptor provided by the consuming crate).
    pub bg_image_src: Option<String>,
    /// Background image opacity (0–255).
    pub bg_image_opa: Option<Opacity>,
    /// Background image recolor.
    pub bg_image_recolor: Option<Color>,
    /// Background image recolor opacity (0–255).
    pub bg_image_recolor_opa: Option<Opacity>,
    /// Tile the background image instead of stretching it.
    pub bg_image_tiled: Option<bool>,
    /// Style references (used when StyleProps appears inside a part or state).
    pub styles: Option<StyleRef>,
}

// ── Style references ─────────────────────────────────────────────────

/// Reference to one or more named style definitions.
///
/// YAML accepts either a single string or a list of strings.
#[derive(Debug, Clone, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(untagged)]
pub enum StyleRef {
    /// Single style name.
    Single(String),
    /// Multiple style names.
    Multiple(Vec<String>),
}

impl StyleRef {
    /// Return all referenced style names as a slice of `&str`.
    pub fn names(&self) -> Vec<&str> {
        match self {
            StyleRef::Single(s) => vec![s.as_str()],
            StyleRef::Multiple(v) => v.iter().map(|s| s.as_str()).collect(),
        }
    }
}

// ── Grid cell ────────────────────────────────────────────────────────

/// Grid cell placement for a child widget.
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct GridCell {
    /// Zero-based column index.
    pub column: u16,
    /// Zero-based row index.
    pub row: u16,
    /// Number of columns to span (default 1).
    #[serde(default = "default_span")]
    pub column_span: u16,
    /// Number of rows to span (default 1).
    #[serde(default = "default_span")]
    pub row_span: u16,
    /// Alignment within the column.
    pub column_align: Option<GridAlign>,
    /// Alignment within the row.
    pub row_align: Option<GridAlign>,
}

fn default_span() -> u16 {
    1
}

// ── Event bindings ───────────────────────────────────────────────────

/// LVGL event code for an `on:` binding.
///
/// Maps directly to `oxivgl::enums::EventCode` constants. Use `snake_case`
/// in YAML (e.g. `clicked`, `value_changed`, `long_pressed`).
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum EventCodeKind {
    /// Receive all event types (`EventCode::ALL`).
    All,
    /// Finger/pointer pressed down.
    Pressed,
    /// Finger/pointer released (sent on release whether or not it was a click).
    /// Pairs with `pressed` for press/release input feeding (e.g. driving a
    /// keypad from on-screen buttons).
    Released,
    /// Widget is being pressed (sent continuously).
    Pressing,
    /// Short click — press + release, not sent if scrolled.
    ShortClicked,
    /// First short click within small distance and short time.
    SingleClicked,
    /// Second short click within small distance and short time.
    DoubleClicked,
    /// Third short click within small distance and short time.
    TripleClicked,
    /// Long press detected.
    LongPressed,
    /// Long press repeated.
    LongPressedRepeat,
    /// Short click (press + release). Common alias for `short_clicked`.
    Clicked,
    /// Value changed (sliders, switches, etc.).
    ValueChanged,
    /// Object is being scrolled.
    Scroll,
    /// A draw task has been added (custom draw hooks).
    DrawTaskAdded,
    /// Main drawing phase completed (custom overlay drawing).
    DrawMainEnd,
    /// Widget gained focus.
    Focused,
    /// Widget lost focus.
    Defocused,
    /// Text input ready (Enter pressed on keyboard/textarea).
    Ready,
    /// A key was pressed while the object was focused.
    Key,
}

impl EventCodeKind {
    /// The Rust constant name as it appears in the `oxivgl::enums::EventCode::`
    /// path emitted by codegen.
    pub fn as_event_code_ident(self) -> &'static str {
        match self {
            Self::All => "ALL",
            Self::Pressed => "PRESSED",
            Self::Released => "RELEASED",
            Self::Pressing => "PRESSING",
            Self::ShortClicked => "SHORT_CLICKED",
            Self::SingleClicked => "SINGLE_CLICKED",
            Self::DoubleClicked => "DOUBLE_CLICKED",
            Self::TripleClicked => "TRIPLE_CLICKED",
            Self::LongPressed => "LONG_PRESSED",
            Self::LongPressedRepeat => "LONG_PRESSED_REPEAT",
            Self::Clicked => "CLICKED",
            Self::ValueChanged => "VALUE_CHANGED",
            Self::Scroll => "SCROLL",
            Self::DrawTaskAdded => "DRAW_TASK_ADDED",
            Self::DrawMainEnd => "DRAW_MAIN_END",
            Self::Focused => "FOCUSED",
            Self::Defocused => "DEFOCUSED",
            Self::Ready => "READY",
            Self::Key => "KEY",
        }
    }
}

// ── Common widget properties ─────────────────────────────────────────

/// Properties shared by all widget types (position, size, alignment, flags,
/// styles, layout, children).
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct CommonProps {
    /// Optional widget identifier (used for generated variable name).
    pub id: Option<String>,
    /// Horizontal position (absolute or align offset).
    pub x: Option<Dimension>,
    /// Vertical position (absolute or align offset).
    pub y: Option<Dimension>,
    /// Widget width.
    pub width: Option<Dimension>,
    /// Widget height.
    pub height: Option<Dimension>,
    /// Alignment relative to parent.
    pub align: Option<Alignment>,
    /// Start hidden.
    pub hidden: Option<bool>,
    /// Accept click events.
    pub clickable: Option<bool>,
    /// Toggle-able (checked/unchecked).
    pub checkable: Option<bool>,
    /// Allow scrolling.
    pub scrollable: Option<bool>,
    /// Scroll direction constraint.
    pub scroll_dir: Option<ScrollDir>,
    /// Scrollbar visibility mode.
    pub scrollbar_mode: Option<ScrollbarMode>,
    /// Flex grow factor.
    pub flex_grow: Option<u8>,
    /// Grid cell placement.
    pub grid_cell: Option<GridCell>,
    /// Child widgets (recursive tree).
    pub widgets: Option<Vec<WidgetKind>>,
    /// Named style references.
    pub styles: Option<StyleRef>,
    /// Container layout algorithm.
    pub layout: Option<LayoutKind>,
    /// Flex flow direction.
    pub flex_flow: Option<FlexFlow>,
    /// Flex main-axis alignment.
    pub flex_align_main: Option<FlexAlign>,
    /// Flex cross-axis alignment.
    pub flex_align_cross: Option<FlexAlign>,
    /// Flex track alignment (multi-line).
    pub flex_align_track: Option<FlexAlign>,
    /// Grid column track definitions.
    pub grid_columns: Option<Vec<TrackSize>>,
    /// Grid row track definitions.
    pub grid_rows: Option<Vec<TrackSize>>,
    /// Grid column alignment.
    pub grid_align_column: Option<GridAlign>,
    /// Grid row alignment.
    pub grid_align_row: Option<GridAlign>,
    /// Inline style properties (flattened from YAML).
    #[serde(flatten)]
    pub style: StyleProps,
    /// Style overrides for `DEFAULT` state.
    pub state_default: Option<StyleProps>,
    /// Style overrides for `PRESSED` state.
    pub state_pressed: Option<StyleProps>,
    /// Style overrides for `FOCUSED` state.
    pub state_focused: Option<StyleProps>,
    /// Style overrides for `CHECKED` state.
    pub state_checked: Option<StyleProps>,
    /// Style overrides for `DISABLED` state.
    pub state_disabled: Option<StyleProps>,
    /// Style overrides for `SCROLLED` state.
    pub state_scrolled: Option<StyleProps>,
    /// Style for the indicator part (slider, bar, arc).
    pub part_indicator: Option<StyleProps>,
    /// Style for the knob part (slider, arc).
    pub part_knob: Option<StyleProps>,
    /// Style for items part (dropdown list, roller).
    pub part_items: Option<StyleProps>,
    /// Style for the scrollbar part.
    pub part_scrollbar: Option<StyleProps>,
    /// Style for the selected item part (roller).
    pub part_selected: Option<StyleProps>,
    /// Style for the cursor part (text area).
    pub part_cursor: Option<StyleProps>,
    /// Event bindings: maps event code → an [`EventAction`].
    ///
    /// YAML key: `on`. Each key is a snake_case event code (e.g. `clicked`,
    /// `value_changed`); the value is either a handler function name or a
    /// `{ show_toast: <id>, args: [...] }` declarative toast raise.
    pub on: Option<BTreeMap<EventCodeKind, EventAction>>,
}

/// The action bound to a widget event in an `on:` map.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(untagged)]
pub enum EventAction {
    /// A plain `fn(&oxivgl::event::Event)` handler the consuming crate
    /// provides.
    Handler(String),
    /// Raise a generated toast from the event (via its `post_<id>` helper).
    ShowToast(ShowToastAction),
}

/// A declarative `on: { <event>: { show_toast: <id>, args: [...] } }` binding.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct ShowToastAction {
    /// The toast id to raise (calls the generated `post_<id>` helper).
    pub show_toast: String,
    /// Literal string arguments passed to `post_<id>(...)`, one per toast
    /// param.
    #[serde(default)]
    pub args: Vec<String>,
}

// ── Widget-specific props ────────────────────────────────────────────

/// Generic widget with no type-specific properties (obj, button, switch).
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct WidgetProps {
    /// Common properties.
    #[serde(flatten)]
    pub common: CommonProps,
}

/// Label widget properties.
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct LabelProps {
    /// Common properties.
    #[serde(flatten)]
    pub common: CommonProps,
    /// Static text content.
    pub text: Option<String>,
    /// Bind this label's text to a toast `param` instead of static `text`.
    /// Only valid inside a `toasts:` entry that declares the param; mutually
    /// exclusive with `text`.
    pub bind_text: Option<String>,
    /// Long-text overflow mode.
    pub long_mode: Option<LabelLongMode>,
}

/// Checkbox widget properties.
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct CheckboxProps {
    /// Common properties.
    #[serde(flatten)]
    pub common: CommonProps,
    /// Checkbox label text.
    pub text: Option<String>,
}

/// Slider widget properties.
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct SliderProps {
    /// Common properties.
    #[serde(flatten)]
    pub common: CommonProps,
    /// Minimum value.
    pub min_value: Option<i32>,
    /// Maximum value.
    pub max_value: Option<i32>,
    /// Current value.
    pub value: Option<i32>,
    /// Orientation override.
    pub orientation: Option<SliderOrientation>,
}

/// Arc widget properties.
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct ArcProps {
    /// Common properties.
    #[serde(flatten)]
    pub common: CommonProps,
    /// Minimum range value.
    pub min_value: Option<f32>,
    /// Maximum range value.
    pub max_value: Option<f32>,
    /// Current value.
    pub value: Option<f32>,
    /// Background arc start angle (degrees).
    pub start_angle: Option<u16>,
    /// Background arc end angle (degrees).
    pub end_angle: Option<u16>,
    /// Arc rotation offset (degrees).
    pub rotation: Option<i16>,
    /// Arc draw mode.
    pub mode: Option<ArcMode>,
    /// Whether the user can drag the arc knob.
    pub adjustable: Option<bool>,
}

/// Bar (progress) widget properties.
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct BarProps {
    /// Common properties.
    #[serde(flatten)]
    pub common: CommonProps,
    /// Minimum range value.
    pub min_value: Option<f32>,
    /// Maximum range value.
    pub max_value: Option<f32>,
    /// Current value.
    pub value: Option<f32>,
    /// Bar fill mode.
    pub mode: Option<BarMode>,
    /// Orientation override.
    pub orientation: Option<BarOrientation>,
}

/// Dropdown widget properties.
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct DropdownProps {
    /// Common properties.
    #[serde(flatten)]
    pub common: CommonProps,
    /// List of option strings.
    pub options: Option<Vec<String>>,
    /// Initially selected index.
    pub selected: Option<u32>,
    /// Expansion direction.
    pub dir: Option<DdDir>,
    /// Arrow/icon symbol override.
    pub symbol: Option<String>,
}

/// Roller widget properties.
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct RollerProps {
    /// Common properties.
    #[serde(flatten)]
    pub common: CommonProps,
    /// List of option strings.
    pub options: Option<Vec<String>>,
    /// Initially selected index.
    pub selected: Option<u32>,
    /// Number of visible rows.
    pub visible_row_count: Option<u32>,
    /// Roller mode (normal/infinite).
    pub mode: Option<RollerMode>,
}

/// Scale widget properties.
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct ScaleProps {
    /// Common properties.
    #[serde(flatten)]
    pub common: CommonProps,
    /// Scale display mode.
    pub mode: Option<ScaleMode>,
    /// Total number of tick marks.
    pub total_tick_count: Option<u16>,
    /// Place a major tick every N ticks.
    pub major_tick_every: Option<u16>,
    /// Show numeric labels on major ticks.
    pub label_show: Option<bool>,
    /// Minimum range value.
    pub range_min: Option<i32>,
    /// Maximum range value.
    pub range_max: Option<i32>,
    /// Rotation offset (degrees) for round scales.
    pub rotation: Option<i32>,
    /// Angular sweep (degrees) for round scales.
    pub angle_range: Option<u32>,
    /// Major tick length in pixels.
    pub major_tick_length: Option<i32>,
    /// Minor tick length in pixels.
    pub minor_tick_length: Option<i32>,
}

/// LED indicator widget properties.
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct LedProps {
    /// Common properties.
    #[serde(flatten)]
    pub common: CommonProps,
    /// LED color.
    pub color: Option<Color>,
    /// LED brightness (0–255).
    pub brightness: Option<u8>,
}

/// Image widget properties.
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct ImageProps {
    /// Common properties.
    #[serde(flatten)]
    pub common: CommonProps,
    /// Image source path or symbol.
    pub src: Option<String>,
}

/// Properties for `value_label` — a label that formats f32 with a unit suffix.
#[derive(Debug, Clone, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct ValueLabelProps {
    /// Common properties.
    #[serde(flatten)]
    pub common: CommonProps,
    /// Initial display text.
    pub text: Option<String>,
    /// Unit suffix for `set_value(f32)` formatting (required).
    pub unit: String,
}

/// Line widget properties.
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct LineProps {
    /// Common properties.
    #[serde(flatten)]
    pub common: CommonProps,
    /// Line points as `[x, y]` pairs.
    pub points: Option<Vec<[f32; 2]>>,
}

/// Spinner (loading indicator) widget properties.
#[cfg(feature = "widget-spinner")]
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct SpinnerProps {
    /// Common properties.
    #[serde(flatten)]
    pub common: CommonProps,
    /// Animation cycle time in milliseconds.
    pub anim_time: Option<u32>,
    /// Arc sweep length in degrees.
    pub arc_length: Option<u32>,
}

/// Spinbox (numeric stepper) widget properties.
#[cfg(feature = "widget-spinbox")]
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct SpinboxProps {
    /// Common properties.
    #[serde(flatten)]
    pub common: CommonProps,
    /// Current value.
    pub value: Option<i32>,
    /// Minimum range value.
    pub min_value: Option<i32>,
    /// Maximum range value.
    pub max_value: Option<i32>,
    /// Total digit count.
    pub digit_count: Option<u32>,
    /// Decimal point position (digits after point).
    pub decimal_point: Option<u32>,
    /// Increment/decrement step.
    pub step: Option<u32>,
    /// Wrap around from max to min.
    pub rollover: Option<bool>,
}

/// Textarea (text input) widget properties.
#[cfg(feature = "widget-textarea")]
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct TextareaProps {
    /// Common properties.
    #[serde(flatten)]
    pub common: CommonProps,
    /// Initial text content.
    pub text: Option<String>,
    /// Placeholder text shown when empty.
    pub placeholder: Option<String>,
    /// Replace characters with bullets.
    pub password_mode: Option<bool>,
    /// Single-line mode (no line breaks).
    pub one_line: Option<bool>,
    /// Maximum character count.
    pub max_length: Option<u32>,
}

/// Keyboard widget properties.
#[cfg(feature = "widget-keyboard")]
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct KeyboardProps {
    /// Common properties.
    #[serde(flatten)]
    pub common: CommonProps,
    /// Key layout mode.
    pub mode: Option<KeyboardMode>,
}

/// Chart widget properties.
#[cfg(feature = "widget-chart")]
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct ChartProps {
    /// Common properties.
    #[serde(flatten)]
    pub common: CommonProps,
    /// Chart visualization type.
    pub chart_type: Option<ChartType>,
    /// Number of data points per series.
    pub point_count: Option<u32>,
    /// Horizontal division lines.
    pub div_lines_h: Option<u32>,
    /// Vertical division lines.
    pub div_lines_v: Option<u32>,
}

/// A single tab within a Tabview.
#[cfg(feature = "widget-tabview")]
#[derive(Debug, Clone, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct Tab {
    /// Tab label text (required).
    pub name: String,
    /// Content properties.
    #[serde(flatten)]
    pub common: CommonProps,
}

/// Tabview widget properties.
#[cfg(feature = "widget-tabview")]
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct TabviewProps {
    /// Common properties.
    #[serde(flatten)]
    pub common: CommonProps,
    /// Tab bar position (top/bottom/left/right).
    pub tab_bar_position: Option<DdDir>,
    /// Tab bar size in pixels.
    pub tab_bar_size: Option<i32>,
    /// Tab definitions.
    pub tabs: Option<Vec<Tab>>,
}

/// Canvas color format for the draw buffer.
#[cfg(feature = "widget-canvas")]
#[derive(Debug, Clone, Copy, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum CanvasColorFormat {
    /// 16-bit RGB (5-6-5), no alpha.
    Rgb565,
    /// 32-bit ARGB (8-8-8-8), full alpha.
    Argb8888,
}

/// Imagebutton state-specific image source set.
#[cfg(feature = "widget-imagebutton")]
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct ImagebuttonSrc {
    /// Left image descriptor symbol name.
    pub left: Option<String>,
    /// Middle (stretched) image descriptor symbol name.
    pub mid: Option<String>,
    /// Right image descriptor symbol name.
    pub right: Option<String>,
}

/// Imagebutton widget properties.
#[cfg(feature = "widget-imagebutton")]
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct ImagebuttonProps {
    /// Common properties.
    #[serde(flatten)]
    pub common: CommonProps,
    /// Image sources for Released state.
    pub src_released: Option<ImagebuttonSrc>,
    /// Image sources for Pressed state.
    pub src_pressed: Option<ImagebuttonSrc>,
    /// Image sources for Disabled state.
    pub src_disabled: Option<ImagebuttonSrc>,
}

/// Animated image widget properties.
#[cfg(feature = "widget-animimg")]
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct AnimImgProps {
    /// Common properties.
    #[serde(flatten)]
    pub common: CommonProps,
    /// Frame image descriptor symbol names (C externs).
    pub frames: Option<Vec<String>>,
    /// Animation cycle duration in milliseconds.
    pub duration: Option<u32>,
    /// Number of repeats (0 = infinite).
    pub repeat_count: Option<u32>,
    /// Start animation immediately.
    pub auto_start: Option<bool>,
}

/// Canvas widget properties.
#[cfg(feature = "widget-canvas")]
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct CanvasProps {
    /// Common properties.
    #[serde(flatten)]
    pub common: CommonProps,
    /// Buffer width in pixels.
    pub buf_width: Option<u32>,
    /// Buffer height in pixels.
    pub buf_height: Option<u32>,
    /// Pixel color format (default: argb8888).
    pub color_format: Option<CanvasColorFormat>,
}

/// Arc label (text along a circular arc) widget properties.
#[cfg(feature = "widget-arc-label")]
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct ArcLabelProps {
    /// Common properties.
    #[serde(flatten)]
    pub common: CommonProps,
    /// Text to display along the arc.
    pub text: Option<String>,
    /// Arc radius in pixels.
    pub radius: Option<u32>,
    /// Start angle in degrees (0 = 12 o'clock).
    pub angle_start: Option<f32>,
    /// Angular span in degrees.
    pub angle_size: Option<f32>,
    /// Text flow direction.
    pub dir: Option<ArcLabelDir>,
}

/// Calendar widget properties.
#[cfg(feature = "widget-calendar")]
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct CalendarProps {
    /// Common properties.
    #[serde(flatten)]
    pub common: CommonProps,
    /// Today's year.
    pub today_year: Option<u16>,
    /// Today's month (1–12).
    pub today_month: Option<u8>,
    /// Today's day (1–31).
    pub today_day: Option<u8>,
    /// Displayed month year.
    pub shown_year: Option<u16>,
    /// Displayed month (1–12).
    pub shown_month: Option<u8>,
}

/// A single item in a List widget.
#[cfg(feature = "widget-list")]
#[derive(Debug, Clone, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum ListItem {
    /// Section header text.
    Text(String),
    /// Button with label text (no icon).
    Button(String),
}

/// List widget properties.
#[cfg(feature = "widget-list")]
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct ListProps {
    /// Common properties.
    #[serde(flatten)]
    pub common: CommonProps,
    /// Ordered list items (text headers and buttons).
    pub items: Option<Vec<ListItem>>,
}

/// Table widget properties.
#[cfg(feature = "widget-table")]
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct TableProps {
    /// Common properties.
    #[serde(flatten)]
    pub common: CommonProps,
    /// Number of columns.
    pub columns: Option<u32>,
    /// Per-column widths in pixels.
    pub column_widths: Option<Vec<i32>>,
    /// Row data — each row is a list of cell strings.
    pub rows: Option<Vec<Vec<String>>>,
}

/// A single tile in a Tileview.
#[cfg(feature = "widget-tileview")]
#[derive(Debug, Clone, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct Tile {
    /// Column index.
    pub col: u8,
    /// Row index.
    pub row: u8,
    /// Allowed scroll/swipe directions.
    pub scroll_dir: Option<ScrollDir>,
    /// Content properties.
    #[serde(flatten)]
    pub common: CommonProps,
}

/// Tileview (swipeable tile grid) widget properties.
#[cfg(feature = "widget-tileview")]
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct TileviewProps {
    /// Common properties.
    #[serde(flatten)]
    pub common: CommonProps,
    /// Tile definitions.
    pub tiles: Option<Vec<Tile>>,
}

/// Window widget properties.
#[cfg(feature = "widget-win")]
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct WinProps {
    /// Common properties.
    #[serde(flatten)]
    pub common: CommonProps,
    /// Window title text.
    pub title: Option<String>,
}

/// Message box widget properties.
#[cfg(feature = "widget-msgbox")]
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct MsgboxProps {
    /// Common properties.
    #[serde(flatten)]
    pub common: CommonProps,
    /// Dialog title.
    pub title: Option<String>,
    /// Body text.
    pub text: Option<String>,
    /// Show close button in header.
    pub close_button: Option<bool>,
    /// Footer button labels.
    pub buttons: Option<Vec<String>>,
}

/// A single text span in a Spangroup.
#[cfg(feature = "widget-spangroup")]
#[derive(Debug, Clone, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct SpanDef {
    /// Span text content.
    pub text: String,
    /// Text color override.
    pub text_color: Option<Color>,
    /// Text opacity override (0–255).
    pub text_opa: Option<u8>,
    /// Text decoration override.
    pub text_decor: Option<TextDecor>,
}

/// Spangroup (rich text) widget properties.
#[cfg(feature = "widget-spangroup")]
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct SpangroupProps {
    /// Common properties.
    #[serde(flatten)]
    pub common: CommonProps,
    /// Overflow handling.
    pub overflow: Option<SpanOverflow>,
    /// Layout mode.
    pub span_mode: Option<SpanMode>,
    /// Maximum lines (-1 = unlimited).
    pub max_lines: Option<i32>,
    /// First-line indent in pixels.
    pub indent: Option<i32>,
    /// Span definitions.
    pub spans: Option<Vec<SpanDef>>,
}

/// Buttonmatrix widget properties.
#[cfg(feature = "widget-buttonmatrix")]
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct ButtonmatrixProps {
    /// Common properties.
    #[serde(flatten)]
    pub common: CommonProps,
    /// Button rows — each inner Vec is one row of button labels.
    pub button_rows: Option<Vec<Vec<String>>>,
    /// Radio-button mode (only one checked at a time).
    pub one_checked: Option<bool>,
}

/// Menu header position mode.
#[cfg(feature = "widget-menu")]
#[derive(Debug, Clone, Copy, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum MenuHeaderMode {
    /// Header fixed at top.
    TopFixed,
    /// Header at top, scrolls with content.
    TopUnfixed,
    /// Header fixed at bottom.
    BottomFixed,
}

/// Navigation menu widget properties.
#[cfg(feature = "widget-menu")]
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct MenuProps {
    /// Common properties.
    #[serde(flatten)]
    pub common: CommonProps,
    /// Header position mode.
    pub header_mode: Option<MenuHeaderMode>,
    /// Enable root back button.
    pub root_back_button: Option<bool>,
}

// ── Widget kind (tagged union) ───────────────────────────────────────

/// A widget node in the tree. Each variant is a single-key map in YAML.
#[derive(Debug, Clone, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum WidgetKind {
    /// Generic container object.
    Obj(WidgetProps),
    /// Text label.
    Label(LabelProps),
    /// Push button.
    Button(WidgetProps),
    /// Toggle switch.
    Switch(WidgetProps),
    /// Checkbox with text.
    Checkbox(CheckboxProps),
    /// Slider (value selection).
    Slider(SliderProps),
    /// Circular arc (gauge/progress).
    Arc(ArcProps),
    /// Linear bar (progress).
    Bar(BarProps),
    /// Dropdown selector.
    Dropdown(DropdownProps),
    /// Roller selector.
    Roller(RollerProps),
    /// Scale with tick marks.
    Scale(ScaleProps),
    /// LED indicator.
    Led(LedProps),
    /// Image display.
    Image(ImageProps),
    /// Polyline.
    Line(LineProps),
    /// Label with f32 value + unit suffix.
    ValueLabel(ValueLabelProps),
    /// Loading spinner.
    #[cfg(feature = "widget-spinner")]
    Spinner(SpinnerProps),
    /// Numeric stepper.
    #[cfg(feature = "widget-spinbox")]
    Spinbox(SpinboxProps),
    /// Text input field.
    #[cfg(feature = "widget-textarea")]
    Textarea(TextareaProps),
    /// On-screen keyboard.
    #[cfg(feature = "widget-keyboard")]
    Keyboard(KeyboardProps),
    /// Data chart.
    #[cfg(feature = "widget-chart")]
    Chart(ChartProps),
    /// Tabbed view container.
    #[cfg(feature = "widget-tabview")]
    Tabview(TabviewProps),
    /// Text along a circular arc.
    #[cfg(feature = "widget-arc-label")]
    ArcLabel(ArcLabelProps),
    /// Date picker calendar.
    #[cfg(feature = "widget-calendar")]
    Calendar(CalendarProps),
    /// Scrollable list with text and buttons.
    #[cfg(feature = "widget-list")]
    List(ListProps),
    /// Data table with rows and columns.
    #[cfg(feature = "widget-table")]
    Table(TableProps),
    /// Swipeable tile grid.
    #[cfg(feature = "widget-tileview")]
    Tileview(TileviewProps),
    /// Window with header bar.
    #[cfg(feature = "widget-win")]
    Win(WinProps),
    /// Modal/non-modal dialog.
    #[cfg(feature = "widget-msgbox")]
    Msgbox(MsgboxProps),
    /// Rich text with styled spans.
    #[cfg(feature = "widget-spangroup")]
    Spangroup(SpangroupProps),
    /// Grid of buttons from a map.
    #[cfg(feature = "widget-buttonmatrix")]
    Buttonmatrix(ButtonmatrixProps),
    /// Pixel drawing surface.
    #[cfg(feature = "widget-canvas")]
    Canvas(CanvasProps),
    /// Button with image sources per state.
    #[cfg(feature = "widget-imagebutton")]
    Imagebutton(ImagebuttonProps),
    /// Animated image cycling through frames.
    #[cfg(feature = "widget-animimg")]
    AnimImg(AnimImgProps),
    /// Navigation menu container.
    #[cfg(feature = "widget-menu")]
    Menu(MenuProps),
}

impl WidgetKind {
    /// Access the common properties shared by all widget types.
    pub fn common(&self) -> &CommonProps {
        match self {
            WidgetKind::Obj(p) | WidgetKind::Button(p) | WidgetKind::Switch(p) => &p.common,
            WidgetKind::Label(p) => &p.common,
            WidgetKind::Checkbox(p) => &p.common,
            WidgetKind::Slider(p) => &p.common,
            WidgetKind::Arc(p) => &p.common,
            WidgetKind::Bar(p) => &p.common,
            WidgetKind::Dropdown(p) => &p.common,
            WidgetKind::Roller(p) => &p.common,
            WidgetKind::Scale(p) => &p.common,
            WidgetKind::Led(p) => &p.common,
            WidgetKind::Image(p) => &p.common,
            WidgetKind::Line(p) => &p.common,
            WidgetKind::ValueLabel(p) => &p.common,
            #[cfg(feature = "widget-spinner")]
            WidgetKind::Spinner(p) => &p.common,
            #[cfg(feature = "widget-spinbox")]
            WidgetKind::Spinbox(p) => &p.common,
            #[cfg(feature = "widget-textarea")]
            WidgetKind::Textarea(p) => &p.common,
            #[cfg(feature = "widget-keyboard")]
            WidgetKind::Keyboard(p) => &p.common,
            #[cfg(feature = "widget-chart")]
            WidgetKind::Chart(p) => &p.common,
            #[cfg(feature = "widget-tabview")]
            WidgetKind::Tabview(p) => &p.common,
            #[cfg(feature = "widget-arc-label")]
            WidgetKind::ArcLabel(p) => &p.common,
            #[cfg(feature = "widget-calendar")]
            WidgetKind::Calendar(p) => &p.common,
            #[cfg(feature = "widget-list")]
            WidgetKind::List(p) => &p.common,
            #[cfg(feature = "widget-table")]
            WidgetKind::Table(p) => &p.common,
            #[cfg(feature = "widget-tileview")]
            WidgetKind::Tileview(p) => &p.common,
            #[cfg(feature = "widget-win")]
            WidgetKind::Win(p) => &p.common,
            #[cfg(feature = "widget-msgbox")]
            WidgetKind::Msgbox(p) => &p.common,
            #[cfg(feature = "widget-spangroup")]
            WidgetKind::Spangroup(p) => &p.common,
            #[cfg(feature = "widget-buttonmatrix")]
            WidgetKind::Buttonmatrix(p) => &p.common,
            #[cfg(feature = "widget-canvas")]
            WidgetKind::Canvas(p) => &p.common,
            #[cfg(feature = "widget-imagebutton")]
            WidgetKind::Imagebutton(p) => &p.common,
            #[cfg(feature = "widget-animimg")]
            WidgetKind::AnimImg(p) => &p.common,
            #[cfg(feature = "widget-menu")]
            WidgetKind::Menu(p) => &p.common,
        }
    }

    /// Widget type name as it appears in YAML.
    pub fn type_name(&self) -> &'static str {
        match self {
            WidgetKind::Obj(_) => "obj",
            WidgetKind::Label(_) => "label",
            WidgetKind::Button(_) => "button",
            WidgetKind::Switch(_) => "switch",
            WidgetKind::Checkbox(_) => "checkbox",
            WidgetKind::Slider(_) => "slider",
            WidgetKind::Arc(_) => "arc",
            WidgetKind::Bar(_) => "bar",
            WidgetKind::Dropdown(_) => "dropdown",
            WidgetKind::Roller(_) => "roller",
            WidgetKind::Scale(_) => "scale",
            WidgetKind::Led(_) => "led",
            WidgetKind::Image(_) => "image",
            WidgetKind::Line(_) => "line",
            WidgetKind::ValueLabel(_) => "value_label",
            #[cfg(feature = "widget-spinner")]
            WidgetKind::Spinner(_) => "spinner",
            #[cfg(feature = "widget-spinbox")]
            WidgetKind::Spinbox(_) => "spinbox",
            #[cfg(feature = "widget-textarea")]
            WidgetKind::Textarea(_) => "textarea",
            #[cfg(feature = "widget-keyboard")]
            WidgetKind::Keyboard(_) => "keyboard",
            #[cfg(feature = "widget-chart")]
            WidgetKind::Chart(_) => "chart",
            #[cfg(feature = "widget-tabview")]
            WidgetKind::Tabview(_) => "tabview",
            #[cfg(feature = "widget-arc-label")]
            WidgetKind::ArcLabel(_) => "arc_label",
            #[cfg(feature = "widget-calendar")]
            WidgetKind::Calendar(_) => "calendar",
            #[cfg(feature = "widget-list")]
            WidgetKind::List(_) => "list",
            #[cfg(feature = "widget-table")]
            WidgetKind::Table(_) => "table",
            #[cfg(feature = "widget-tileview")]
            WidgetKind::Tileview(_) => "tileview",
            #[cfg(feature = "widget-win")]
            WidgetKind::Win(_) => "win",
            #[cfg(feature = "widget-msgbox")]
            WidgetKind::Msgbox(_) => "msgbox",
            #[cfg(feature = "widget-spangroup")]
            WidgetKind::Spangroup(_) => "spangroup",
            #[cfg(feature = "widget-buttonmatrix")]
            WidgetKind::Buttonmatrix(_) => "buttonmatrix",
            #[cfg(feature = "widget-canvas")]
            WidgetKind::Canvas(_) => "canvas",
            #[cfg(feature = "widget-imagebutton")]
            WidgetKind::Imagebutton(_) => "imagebutton",
            #[cfg(feature = "widget-animimg")]
            WidgetKind::AnimImg(_) => "anim_img",
            #[cfg(feature = "widget-menu")]
            WidgetKind::Menu(_) => "menu",
        }
    }
}

// ── Style definition ─────────────────────────────────────────────────

/// Named reusable style definition (top-level `style_definitions[]`).
#[derive(Debug, Clone, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct StyleDef {
    /// Unique identifier, referenced by widgets via `styles:`.
    pub id: String,
    /// Style property values.
    #[serde(flatten)]
    pub style: StyleProps,
}

// ── Gradient ─────────────────────────────────────────────────────────

/// Named gradient definition (top-level `gradients[]`).
#[derive(Debug, Clone, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct GradientDef {
    /// Unique identifier, referenced by `bg_grad:`.
    pub id: String,
    /// Direction (`"hor"` or `"ver"`).
    pub dir: String,
    /// Color stops.
    pub stops: Vec<GradientStop>,
}

/// Single gradient color stop.
#[derive(Debug, Clone, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct GradientStop {
    /// Stop color.
    pub color: Color,
    /// Position 0–255.
    pub position: u8,
}

// ── Page ─────────────────────────────────────────────────────────────

/// A page (screen) definition. Each page generates a `create_<id>(screen)`
/// function.
#[derive(Debug, Clone, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct Page {
    /// Unique page identifier (becomes function name suffix).
    pub id: String,
    /// Skip code generation for this page.
    pub skip: Option<bool>,
    /// Name of a user-provided function called from the generated
    /// `View::update`. Signature: `fn(&mut Option<XWidgets>) ->
    /// Result<NavAction, WidgetError>` (or `fn() -> Result<NavAction,
    /// WidgetError>` if the page has no id-tagged widgets). Only effective
    /// when `generate_view: true`.
    pub update_fn: Option<String>,
    /// Name of a user-provided function called from the generated
    /// `View::on_event`. Signature: `fn(&mut Option<XWidgets>, &Event) ->
    /// NavAction` (or `fn(&Event) -> NavAction` if the page has no
    /// id-tagged widgets). Only effective when `generate_view: true`.
    pub on_event_fn: Option<String>,
    /// Declarative keypad/encoder focus group. Lists id-tagged widgets on this
    /// page (in focus order) that join an input `Group`; the generated
    /// `View::input_group` returns it so the navigator routes keys to it. Only
    /// effective when `generate_view: true`. Mutually exclusive with
    /// [`input_group_fn`](Self::input_group_fn).
    pub input_group: Option<InputGroup>,
    /// Name of a user-provided function called from the generated
    /// `View::input_group`. Signature: `fn(&Option<XWidgets>) ->
    /// Option<oxivgl::group::GroupRef>` (or `fn() -> Option<...>` if the page
    /// has no id-tagged widgets). Use when the focus group is built in user
    /// code. Only effective when `generate_view: true`. Mutually exclusive with
    /// [`input_group`](Self::input_group).
    pub input_group_fn: Option<String>,
    /// Optional resource budget asserted (debug builds only) right after the
    /// page's widget tree is created.
    pub budget: Option<BudgetDef>,
    /// Screen-level properties and child widgets.
    #[serde(flatten)]
    pub common: CommonProps,
}

/// Per-view resource budget (the `budget:` key on a page or toast).
///
/// Generates an `oxivgl::diag::assert_budget` call at the end of `create_*()`
/// — a debug-build tripwire that fails CI/HIL when a widget-count regression
/// would otherwise surface as an OOM on a constrained target. No-op in
/// release builds.
#[derive(Debug, Clone, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct BudgetDef {
    /// Maximum allowed object count for the view's subtree.
    #[cfg_attr(feature = "schema", schemars(range(min = 1)))]
    pub max_objects: u32,
    /// Maximum allowed nesting depth (unbounded when omitted).
    #[cfg_attr(feature = "schema", schemars(range(min = 1)))]
    pub max_depth: Option<u16>,
}

/// Declarative input-focus group for a page (the `input_group:` key).
#[derive(Debug, Clone, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct InputGroup {
    /// Widget IDs (defined on this page) added to the focus group, in the
    /// listed order. The first member receives focus when the group is built.
    pub members: Vec<String>,
}

/// A toast (passive global status overlay) definition (a `toasts[]` entry).
///
/// The widget tree builds the toast's content; the navigator wraps it in a
/// styled, input-transparent container on `lv_layer_sys`. Generates a passive
/// `<Id>Toast` View and a `fn <id>_toast() -> NavAction` helper that raises it
/// via [`NavAction::show_toast`](https://docs.rs/oxivgl) with the configured
/// timing.
#[derive(Debug, Clone, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct ToastDef {
    /// Unique identifier (becomes the `<Id>Toast` type and `<id>_toast()` fn).
    pub id: String,
    /// Auto-dismiss timeout in milliseconds. Omitted defaults to 2500 ms.
    /// Mutually exclusive with [`persistent`](Self::persistent).
    pub duration_ms: Option<u32>,
    /// When true the toast stays until explicitly dismissed (no timeout —
    /// the helper passes `None` duration). Mutually exclusive with
    /// [`duration_ms`](Self::duration_ms).
    pub persistent: Option<bool>,
    /// String parameters bound into the toast's widgets via `bind_text:`. Each
    /// becomes an `impl Into<String>` argument of the generated
    /// `<id>_toast(...)` helper, so the toast can show dynamic text.
    pub params: Option<Vec<String>>,
    /// Optional resource budget asserted (debug builds only) right after the
    /// toast's widget tree is created.
    pub budget: Option<BudgetDef>,
    /// Toast content (widget tree + container styling).
    #[serde(flatten)]
    pub common: CommonProps,
}

/// A built-in toast preset (the `toast_presets:` list). Each expands to a
/// parameterized toast — a colored bar with a single `msg` string param.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum ToastPreset {
    /// Neutral/informational (blue).
    Info,
    /// Warning (amber).
    Warn,
    /// Error (red).
    Error,
}

impl ToastPreset {
    /// The generated toast id / helper stem (`info` / `warn` / `error`).
    pub fn id(self) -> &'static str {
        match self {
            Self::Info => "info",
            Self::Warn => "warn",
            Self::Error => "error",
        }
    }

    /// Container background color (hex `0xRRGGBB`).
    pub fn bg(self) -> u32 {
        match self {
            Self::Info => 0x2266cc,
            Self::Warn => 0xcc7a00,
            Self::Error => 0xaa2222,
        }
    }
}

// ── Top-level document ───────────────────────────────────────────────

/// Root document — the entire YAML file deserializes into this.
#[derive(Debug, Clone, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct UiDoc {
    /// The `lvgl:` top-level key.
    pub lvgl: LvglConfig,
}

/// Top-level LVGL configuration block.
#[derive(Debug, Clone, PartialEq, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct LvglConfig {
    /// Default font for all widgets.
    pub default_font: Option<String>,
    /// Display color depth (16 or 32).
    pub color_depth: Option<u8>,
    /// Reusable style definitions.
    pub style_definitions: Option<Vec<StyleDef>>,
    /// Gradient definitions.
    pub gradients: Option<Vec<GradientDef>>,
    /// Theme overrides (reserved, not yet used).
    #[cfg_attr(feature = "schema", schemars(with = "Option<serde_json::Value>"))]
    pub theme: Option<serde_yaml::Value>,
    /// Generate `impl View` wrappers for each page. Opt-in.
    pub generate_view: Option<bool>,
    /// Toast (passive global status overlay) definitions. Each generates a
    /// passive `<Id>Toast` View plus a `fn <id>_toast() -> NavAction` helper.
    pub toasts: Option<Vec<ToastDef>>,
    /// Built-in toast presets to generate (`info` / `warn` / `error`). Each
    /// expands to a parameterized toast with a single `msg` param.
    pub toast_presets: Option<Vec<ToastPreset>>,
    /// Optional app name used to name the root View type alias
    /// (e.g. `app_name: my_ui` → `pub type MyUiRootView = ...`).
    pub app_name: Option<String>,
    /// Page (screen) definitions. Optional — a document may define only
    /// `toasts:` (e.g. a shared toast library).
    #[serde(default)]
    pub pages: Vec<Page>,
    /// SPDX license identifier extracted from leading YAML comment (not a YAML
    /// key).
    #[serde(skip)]
    pub spdx_license: Option<String>,
}

// ── JSON-schema impls for custom-syntax types ────────────────────────
//
// These four types have hand-written `Deserialize` visitors, so their schema
// must be written by hand too — each impl mirrors exactly what its visitor
// accepts. The generated schema (schemas/oxiforge.schema.json) is kept in
// sync by the `schema_sync` drift test.

#[cfg(feature = "schema")]
mod json_schema_impls {
    use std::borrow::Cow;

    use super::*;

    impl schemars::JsonSchema for Color {
        fn schema_name() -> Cow<'static, str> {
            "Color".into()
        }
        fn json_schema(_: &mut schemars::SchemaGenerator) -> schemars::Schema {
            schemars::json_schema!({
                "description": "Color: hex integer (0xRRGGBB), \"#RGB\"/\"#RRGGBB\" string, or palette name",
                "anyOf": [
                    { "type": "integer", "minimum": 0, "maximum": 16777215 },
                    { "type": "string", "pattern": "^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$" },
                    { "type": "string", "description": "Named palette color (e.g. red, blue)" }
                ]
            })
        }
    }

    impl schemars::JsonSchema for Dimension {
        fn schema_name() -> Cow<'static, str> {
            "Dimension".into()
        }
        fn json_schema(_: &mut schemars::SchemaGenerator) -> schemars::Schema {
            schemars::json_schema!({
                "description": "Dimension: pixels (int), \"Npct\", or \"size_content\"",
                "anyOf": [
                    { "type": "integer" },
                    { "type": "string", "pattern": "^-?\\d+pct$" },
                    { "type": "string", "const": "size_content" }
                ]
            })
        }
    }

    impl schemars::JsonSchema for Opacity {
        fn schema_name() -> Cow<'static, str> {
            "Opacity".into()
        }
        fn json_schema(_: &mut schemars::SchemaGenerator) -> schemars::Schema {
            schemars::json_schema!({
                "description": "Opacity: 0-255 integer, 0.0-1.0 float, or \"transp\"/\"cover\"",
                "anyOf": [
                    { "type": "integer", "minimum": 0, "maximum": 255 },
                    { "type": "number", "minimum": 0.0, "maximum": 1.0 },
                    { "type": "string" }
                ]
            })
        }
    }

    impl schemars::JsonSchema for TrackSize {
        fn schema_name() -> Cow<'static, str> {
            "TrackSize".into()
        }
        fn json_schema(_: &mut schemars::SchemaGenerator) -> schemars::Schema {
            schemars::json_schema!({
                "description": "Grid track: pixels (int), \"Nfr\", or \"content\"",
                "anyOf": [
                    { "type": "integer" },
                    { "type": "string", "pattern": "^\\d+fr$" },
                    { "type": "string", "const": "content" }
                ]
            })
        }
    }
}

/// Render the canonical JSON schema for the YAML language as pretty JSON
/// (with trailing newline) — the content of `schemas/oxiforge.schema.json`.
///
/// Derived from [`UiDoc`] via schemars, so it covers exactly what the parser
/// accepts under the enabled widget features. Regenerate with the
/// `gen_schema` bin; the `schema_sync` test fails when the file drifts.
#[cfg(feature = "schema")]
pub fn generated_json_schema() -> String {
    let schema = schemars::schema_for!(UiDoc);
    let mut value = serde_json::to_value(&schema).expect("schema serializes to JSON");

    close_objects(&mut value);

    let obj = value.as_object_mut().expect("schema root is an object");
    obj.insert("$id".into(), "https://github.com/emobotics-dev/oxiforge/schemas/oxiforge.schema.json".into());
    obj.insert("title".into(), "Oxiforge YAML UI Description".into());
    obj.insert(
        "description".into(),
        "Schema for oxiforge YAML UI files that generate Rust code for oxivgl/LVGL UIs".into(),
    );

    let mut s = serde_json::to_string_pretty(&value).expect("schema renders");
    s.push('\n');
    s
}

/// Recursively add `additionalProperties: false` to every object schema that
/// declares `properties` without one — unknown YAML keys then get editor
/// squiggles. schemars inlines `#[serde(flatten)]`, so a closed object still
/// lists every key the parser accepts.
#[cfg(feature = "schema")]
fn close_objects(v: &mut serde_json::Value) {
    match v {
        serde_json::Value::Object(map) => {
            if map.contains_key("properties") && !map.contains_key("additionalProperties") {
                map.insert("additionalProperties".into(), false.into());
            }
            for val in map.values_mut() {
                close_objects(val);
            }
        }
        serde_json::Value::Array(arr) => {
            for val in arr {
                close_objects(val);
            }
        }
        _ => {}
    }
}

// ── Tests ────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn parse_color_hex_int() {
        let c: Color = serde_yaml::from_str("0xFF0000").unwrap();
        assert_eq!(c, Color::Hex(0xFF0000));
    }

    #[test]
    fn parse_color_css_hex6() {
        let c: Color = serde_yaml::from_str("\"#FF0000\"").unwrap();
        assert_eq!(c, Color::Hex(0xFF0000));
    }

    #[test]
    fn parse_color_css_hex3() {
        let c: Color = serde_yaml::from_str("\"#F00\"").unwrap();
        assert_eq!(c, Color::Hex(0xFF0000));
    }

    #[test]
    fn parse_color_named() {
        let c: Color = serde_yaml::from_str("red").unwrap();
        assert_eq!(c, Color::Named("red".into()));
    }

    #[test]
    fn parse_dimension_pixels() {
        let d: Dimension = serde_yaml::from_str("100").unwrap();
        assert_eq!(d, Dimension::Pixels(100));
    }

    #[test]
    fn parse_dimension_percent() {
        let d: Dimension = serde_yaml::from_str("50pct").unwrap();
        assert_eq!(d, Dimension::Percent(50));
    }

    #[test]
    fn parse_dimension_size_content() {
        let d: Dimension = serde_yaml::from_str("size_content").unwrap();
        assert_eq!(d, Dimension::SizeContent);
    }

    #[test]
    fn parse_alignment() {
        let a: Alignment = serde_yaml::from_str("center").unwrap();
        assert_eq!(a, Alignment::Center);
    }

    #[test]
    fn parse_track_size_fr() {
        let t: TrackSize = serde_yaml::from_str("2fr").unwrap();
        assert_eq!(t, TrackSize::Fr(2));
    }

    #[test]
    fn parse_track_size_content() {
        let t: TrackSize = serde_yaml::from_str("content").unwrap();
        assert_eq!(t, TrackSize::Content);
    }

    #[test]
    fn parse_track_size_pixels() {
        let t: TrackSize = serde_yaml::from_str("80").unwrap();
        assert_eq!(t, TrackSize::Pixels(80));
    }

    #[test]
    fn parse_opacity_float() {
        let o: Opacity = serde_yaml::from_str("0.5").unwrap();
        assert_eq!(o, Opacity::Value(127));
    }

    #[test]
    fn parse_opacity_named() {
        let o: Opacity = serde_yaml::from_str("cover").unwrap();
        assert_eq!(o, Opacity::Named("cover".into()));
    }

    #[test]
    fn parse_opacity_int() {
        let o: Opacity = serde_yaml::from_str("128").unwrap();
        assert_eq!(o, Opacity::Value(128));
    }

    #[test]
    fn parse_color_negative_int() {
        // YAML may parse small hex as signed
        let c: Color = serde_yaml::from_str("-1").unwrap();
        assert_eq!(c, Color::Hex(u32::MAX));
    }

    #[test]
    fn parse_dimension_negative() {
        let d: Dimension = serde_yaml::from_str("-5").unwrap();
        assert_eq!(d, Dimension::Pixels(-5));
    }

    #[test]
    fn parse_track_size_fr_large() {
        let t: TrackSize = serde_yaml::from_str("3fr").unwrap();
        assert_eq!(t, TrackSize::Fr(3));
    }

    #[test]
    fn parse_all_widget_kinds_via_doc() {
        // WidgetKind is an externally-tagged enum; test via full doc parse.
        let yaml = r#"
lvgl:
  pages:
    - id: main
      widgets:
        - obj: { id: a }
        - label: { text: hi }
        - button: { id: b }
        - switch: { id: s }
        - checkbox: { text: cb }
        - slider: { value: 50 }
        - arc: { value: 1.0 }
        - bar: { value: 1.0 }
        - dropdown: { selected: 0 }
        - roller: { selected: 0 }
        - scale: { range_min: 0 }
        - led: { brightness: 200 }
        - image: { src: "test.bin" }
        - line: { id: l }
"#;
        let doc: UiDoc = serde_yaml::from_str(yaml).unwrap();
        let widgets = doc.lvgl.pages[0].common.widgets.as_ref().unwrap();
        let names: Vec<&str> = widgets.iter().map(|w| w.type_name()).collect();
        assert_eq!(
            names,
            vec![
                "obj", "label", "button", "switch", "checkbox", "slider", "arc", "bar", "dropdown", "roller", "scale",
                "led", "image", "line"
            ]
        );
    }

    #[test]
    fn parse_style_ref_single() {
        let sr: StyleRef = serde_yaml::from_str("card").unwrap();
        assert_eq!(sr.names(), vec!["card"]);
    }

    #[test]
    fn parse_style_ref_multiple() {
        let sr: StyleRef = serde_yaml::from_str("[card, dark]").unwrap();
        assert_eq!(sr.names(), vec!["card", "dark"]);
    }

    #[test]
    fn parse_grid_cell_defaults() {
        let gc: GridCell = serde_yaml::from_str("column: 0\nrow: 1\n").unwrap();
        assert_eq!(gc.column_span, 1);
        assert_eq!(gc.row_span, 1);
    }
}