native_theme/model/widgets/

mod.rs

// Per-widget struct pairs and macros

use crate::Rgba;
use crate::model::border::{BorderSpec, ResolvedBorderSpec};
use crate::model::{DialogButtonOrder, FontSpec, ResolvedFontSpec};

/// Helper macro for FIELD_NAMES: emits the TOML key name for an option field.
/// With a rename literal, returns the literal; without, returns `stringify!(field)`.
#[doc(hidden)]
macro_rules! __field_name {
    ($field:ident) => {
        stringify!($field)
    };
    ($field:ident, $rename:literal) => {
        $rename
    };
}
pub(crate) use __field_name;

/// Generates a paired Option-based theme struct and a Resolved struct from a single definition.
///
/// # Usage
///
/// ```ignore
/// define_widget_pair! {
///     /// Doc comment
///     ButtonTheme / ResolvedButtonTheme {
///         option {
///             color: crate::Rgba,
///             size as "size_px": f32,
///         }
///         optional_nested {
///             font: [crate::model::FontSpec, ResolvedFontSpec],
///         }
///     }
/// }
/// ```
///
/// This generates:
/// - `ButtonTheme` with all `option` fields as `Option<T>` and all `optional_nested` fields
///   as `Option<FontSpec>` (the first type in the pair). Derives: Clone, Debug, Default,
///   PartialEq, Serialize, Deserialize. Attributes: skip_serializing_none, serde(default).
///   Fields with `as "name"` get `#[serde(rename = "name")]` on the Option struct only.
/// - `ResolvedButtonTheme` with all `option` fields as plain `T` and all `optional_nested`
///   fields as `ResolvedFontSpec` (the second type in the pair). Derives: Clone, Debug, PartialEq.
///   Resolved structs never get serde renames.
/// - `impl_merge!` invocation for `ButtonTheme` using the `optional_nested` clause for font fields.
macro_rules! define_widget_pair {
    (
        $(#[$attr:meta])*
        $opt_name:ident / $resolved_name:ident {
            $(option {
                $($(#[doc = $opt_doc:expr])* $opt_field:ident $(as $opt_rename:literal)? : $opt_type:ty),* $(,)?
            })?
            $(soft_option {
                $($(#[doc = $so_doc:expr])* $so_field:ident : $so_type:ty),* $(,)?
            })?
            $(optional_nested {
                $($(#[doc = $on_doc:expr])* $on_field:ident : [$on_opt_type:ty, $on_res_type:ty]),* $(,)?
            })?
            $(border_partial {
                $($(#[doc = $bp_doc:expr])* $bp_field:ident : [$bp_opt_type:ty, $bp_res_type:ty]),* $(,)?
            })?
            $(border_optional {
                $($(#[doc = $bo_doc:expr])* $bo_field:ident : [$bo_opt_type:ty, $bo_res_type:ty]),* $(,)?
            })?
        }
    ) => {
        $(#[$attr])*
        #[serde_with::skip_serializing_none]
        #[derive(Clone, Debug, Default, PartialEq, serde::Serialize, serde::Deserialize)]
        #[serde(default)]
        pub struct $opt_name {
            $($($(#[doc = $opt_doc])* $(#[serde(rename = $opt_rename)])? pub $opt_field: Option<$opt_type>,)*)?
            $($($(#[doc = $so_doc])* pub $so_field: Option<$so_type>,)*)?
            $($($(#[doc = $on_doc])* pub $on_field: Option<$on_opt_type>,)*)?
            $($($(#[doc = $bp_doc])* pub $bp_field: Option<$bp_opt_type>,)*)?
            $($($(#[doc = $bo_doc])* pub $bo_field: Option<$bo_opt_type>,)*)?
        }

        $(#[$attr])*
        #[derive(Clone, Debug, PartialEq, serde::Serialize, serde::Deserialize)]
        #[non_exhaustive]
        pub struct $resolved_name {
            $($($(#[doc = $opt_doc])* pub $opt_field: $opt_type,)*)?
            $($($(#[doc = $so_doc])* pub $so_field: Option<$so_type>,)*)?
            $($($(#[doc = $on_doc])* pub $on_field: $on_res_type,)*)?
            $($($(#[doc = $bp_doc])* pub $bp_field: $bp_res_type,)*)?
            $($($(#[doc = $bo_doc])* pub $bo_field: $bo_res_type,)*)?
        }

        impl $opt_name {
            /// All serialized field names for this widget theme, for TOML linting.
            pub const FIELD_NAMES: &[&str] = &[
                $($($crate::model::widgets::__field_name!($opt_field $(, $opt_rename)?),)*)?
                $($(stringify!($so_field),)*)?
                $($(stringify!($on_field),)*)?
                $($(stringify!($bp_field),)*)?
                $($(stringify!($bo_field),)*)?
            ];
        }

        impl_merge!($opt_name {
            $(option { $($opt_field),* })?
            $(soft_option { $($so_field),* })?
            $(optional_nested { $($on_field),* })?
            $(optional_nested { $($bp_field),* })?
            $(optional_nested { $($bo_field),* })?
        });

        #[allow(dead_code)] // LayoutTheme is top-level, not per-variant
        impl $resolved_name {
            /// Extract and validate fields from the Option-based source struct.
            /// Generated by `define_widget_pair!` -- field paths use `stringify!()`.
            pub(crate) fn validate_widget(
                source: &$opt_name,
                prefix: &str,
                _dpi: f32,
                missing: &mut Vec<String>,
            ) -> Self {
                Self {
                    $($(
                        $opt_field: crate::resolve::validate_helpers::require(
                            &source.$opt_field,
                            &format!("{}.{}", prefix, stringify!($opt_field)),
                            missing,
                        ),
                    )*)?
                    $($(
                        $so_field: source.$so_field,
                    )*)?
                    $($(
                        $on_field: <$on_opt_type as crate::resolve::validate_helpers::ValidateNested>::validate_nested(
                            &source.$on_field,
                            &format!("{}.{}", prefix, stringify!($on_field)),
                            _dpi,
                            missing,
                        ),
                    )*)?
                    $($(
                        $bp_field: crate::resolve::validate_helpers::require_border_partial(
                            &source.$bp_field,
                            &format!("{}.{}", prefix, stringify!($bp_field)),
                            missing,
                        ),
                    )*)?
                    $($(
                        $bo_field: crate::resolve::validate_helpers::border_all_optional(
                            &source.$bo_field,
                        ),
                    )*)?
                }
            }
        }
    };
}

// ── §2.2 Window / Application Chrome ────────────────────────────────────────

define_widget_pair! {
    /// Window chrome: background, title bar colors, inactive states, geometry.
    WindowTheme / ResolvedWindowTheme {
        option {
            /// Main window background fill.
            background_color: Rgba,
            /// Active title bar background fill.
            title_bar_background: Rgba,
            /// Title bar background when the window is unfocused.
            inactive_title_bar_background: Rgba,
            /// Title bar text color when the window is unfocused.
            inactive_title_bar_text_color: Rgba,
        }
        optional_nested {
            /// Title bar font specification.
            title_bar_font: [FontSpec, ResolvedFontSpec],
            /// Window border specification.
            border: [BorderSpec, ResolvedBorderSpec],
        }
    }
}

// ── §2.3 Button ──────────────────────────────────────────────────────────────

define_widget_pair! {
    /// Push button: colors, sizing, spacing, geometry.
    ButtonTheme / ResolvedButtonTheme {
        option {
            /// Default button background fill.
            background_color: Rgba,
            /// Primary / accent button background fill.
            primary_background: Rgba,
            /// Primary / accent button text/icon color.
            primary_text_color: Rgba,
            /// Minimum button width in logical pixels.
            min_width as "min_width_px": f32,
            /// Minimum button height in logical pixels.
            min_height as "min_height_px": f32,
            /// Space between icon and label.
            icon_text_gap as "icon_text_gap_px": f32,
            /// Opacity multiplier when the button is disabled (0.0-1.0).
            disabled_opacity: f32,
            /// Button background on hover.
            hover_background: Rgba,
            /// Button text color on hover.
            hover_text_color: Rgba,
            /// Button text color when pressed/active.
            active_text_color: Rgba,
            /// Button text color when disabled.
            disabled_text_color: Rgba,
        }
        soft_option {
            /// Button background when pressed/active.
            active_background: Rgba,
            /// Button background when disabled.
            disabled_background: Rgba,
        }
        optional_nested {
            /// Button label font specification.
            font: [FontSpec, ResolvedFontSpec],
            /// Button border specification.
            border: [BorderSpec, ResolvedBorderSpec],
        }
    }
}

// ── §2.4 Text Input ──────────────────────────────────────────────────────────

define_widget_pair! {
    /// Single-line and multi-line text input fields.
    InputTheme / ResolvedInputTheme {
        option {
            /// Input field background fill.
            background_color: Rgba,
            /// Placeholder text color.
            placeholder_color: Rgba,
            /// Text cursor (caret) color.
            caret_color: Rgba,
            /// Text selection highlight color.
            selection_background: Rgba,
            /// Text color inside the selection highlight.
            selection_text_color: Rgba,
            /// Minimum field height in logical pixels.
            min_height as "min_height_px": f32,
            /// Opacity multiplier when disabled (0.0-1.0).
            disabled_opacity: f32,
            /// Input text color when disabled.
            disabled_text_color: Rgba,
        }
        soft_option {
            /// Border color when the input is hovered.
            hover_border_color: Rgba,
            /// Border color when the input has focus.
            focus_border_color: Rgba,
            /// Input background when disabled.
            disabled_background: Rgba,
        }
        optional_nested {
            /// Input text font specification.
            font: [FontSpec, ResolvedFontSpec],
            /// Input border specification.
            border: [BorderSpec, ResolvedBorderSpec],
        }
    }
}

// ── §2.5 Checkbox / Radio Button ────────────────────────────────────────────

define_widget_pair! {
    /// Checkbox and radio button theme: colors, indicator, label font, border, and interactive states.
    CheckboxTheme / ResolvedCheckboxTheme {
        option {
            /// Checkbox background color.
            background_color: Rgba,
            /// Indicator background when checked.
            checked_background: Rgba,
            /// Indicator (check mark / radio dot) color.
            indicator_color: Rgba,
            /// Indicator (check mark / radio dot) width in logical pixels.
            indicator_width as "indicator_width_px": f32,
            /// Space between indicator and label.
            label_gap as "label_gap_px": f32,
            /// Opacity multiplier when disabled (0.0-1.0).
            disabled_opacity: f32,
            /// Checkbox label text color when disabled.
            disabled_text_color: Rgba,
        }
        soft_option {
            /// Checkbox background on hover.
            hover_background: Rgba,
            /// Checkbox background when disabled.
            disabled_background: Rgba,
            /// Indicator background when unchecked.
            unchecked_background: Rgba,
            /// Border color when unchecked.
            unchecked_border_color: Rgba,
        }
        optional_nested {
            /// Checkbox label font specification.
            font: [FontSpec, ResolvedFontSpec],
            /// Checkbox border specification.
            border: [BorderSpec, ResolvedBorderSpec],
        }
    }
}

// ── §2.6 Menu ────────────────────────────────────────────────────────────────

define_widget_pair! {
    /// Popup and context menu appearance.
    MenuTheme / ResolvedMenuTheme {
        option {
            /// Menu panel background fill.
            background_color: Rgba,
            /// Separator line color between menu items.
            separator_color: Rgba,
            /// Height of a single menu item row.
            row_height as "row_height_px": f32,
            /// Space between a menu item's icon and its label.
            icon_text_gap as "icon_text_gap_px": f32,
            /// Menu item icon size in logical pixels.
            icon_size as "icon_size_px": f32,
            /// Menu item background on hover.
            hover_background: Rgba,
            /// Menu item text color on hover.
            hover_text_color: Rgba,
            /// Disabled menu item text color.
            disabled_text_color: Rgba,
        }
        optional_nested {
            /// Menu item font specification.
            font: [FontSpec, ResolvedFontSpec],
        }
        border_optional {
            /// Menu border specification.
            border: [BorderSpec, ResolvedBorderSpec],
        }
    }
}

// ── §2.7 Tooltip ─────────────────────────────────────────────────────────────

define_widget_pair! {
    /// Tooltip popup appearance.
    TooltipTheme / ResolvedTooltipTheme {
        option {
            /// Tooltip background fill.
            background_color: Rgba,
            /// Maximum tooltip width before wrapping.
            max_width as "max_width_px": f32,
        }
        optional_nested {
            /// Tooltip font specification.
            font: [FontSpec, ResolvedFontSpec],
            /// Tooltip border specification.
            border: [BorderSpec, ResolvedBorderSpec],
        }
    }
}

// ── §2.8 Scrollbar ───────────────────────────────────────────────────────────

define_widget_pair! {
    /// Scrollbar colors and geometry.
    ScrollbarTheme / ResolvedScrollbarTheme {
        option {
            /// Scrollbar track (gutter) color.
            track_color: Rgba,
            /// Scrollbar thumb color.
            thumb_color: Rgba,
            /// Thumb color on hover.
            thumb_hover_color: Rgba,
            /// Scrollbar groove width in logical pixels.
            groove_width as "groove_width_px": f32,
            /// Minimum thumb length in logical pixels.
            min_thumb_length as "min_thumb_length_px": f32,
            /// Width of the thumb rail within the scrollbar.
            thumb_width as "thumb_width_px": f32,
            /// Whether the scrollbar overlays content instead of taking layout space.
            overlay_mode: bool,
        }
        soft_option {
            /// Thumb color when pressed/dragging.
            thumb_active_color: Rgba,
        }
    }
}

// ── §2.9 Slider ──────────────────────────────────────────────────────────────

define_widget_pair! {
    /// Slider control colors and geometry.
    SliderTheme / ResolvedSliderTheme {
        option {
            /// Filled portion of the slider track.
            fill_color: Rgba,
            /// Unfilled track color.
            track_color: Rgba,
            /// Thumb (handle) color.
            thumb_color: Rgba,
            /// Track height in logical pixels.
            track_height as "track_height_px": f32,
            /// Thumb diameter in logical pixels.
            thumb_diameter as "thumb_diameter_px": f32,
            /// Tick mark length in logical pixels.
            tick_mark_length as "tick_mark_length_px": f32,
            /// Opacity multiplier when disabled (0.0-1.0).
            disabled_opacity: f32,
        }
        soft_option {
            /// Thumb color on hover.
            thumb_hover_color: Rgba,
            /// Filled track color when disabled.
            disabled_fill_color: Rgba,
            /// Unfilled track color when disabled.
            disabled_track_color: Rgba,
            /// Thumb color when disabled.
            disabled_thumb_color: Rgba,
        }
    }
}

// ── §2.10 Progress Bar ───────────────────────────────────────────────────────

define_widget_pair! {
    /// Progress bar colors and geometry.
    ProgressBarTheme / ResolvedProgressBarTheme {
        option {
            /// Filled progress bar color.
            fill_color: Rgba,
            /// Background track color.
            track_color: Rgba,
            /// Bar height in logical pixels.
            track_height as "track_height_px": f32,
            /// Minimum bar width in logical pixels.
            min_width as "min_width_px": f32,
        }
        optional_nested {
            /// Progress bar border specification.
            border: [BorderSpec, ResolvedBorderSpec],
        }
    }
}

// ── §2.11 Tab Bar ─────────────────────────────────────────────────────────────

define_widget_pair! {
    /// Tab bar colors and sizing.
    TabTheme / ResolvedTabTheme {
        option {
            /// Inactive tab background.
            background_color: Rgba,
            /// Active (selected) tab background.
            active_background: Rgba,
            /// Active (selected) tab text color.
            active_text_color: Rgba,
            /// Tab bar strip background.
            bar_background: Rgba,
            /// Minimum tab width in logical pixels.
            min_width as "min_width_px": f32,
            /// Minimum tab height in logical pixels.
            min_height as "min_height_px": f32,
            /// Tab text color on hover.
            hover_text_color: Rgba,
        }
        soft_option {
            /// Tab background on hover.
            hover_background: Rgba,
        }
        optional_nested {
            /// Tab font specification.
            font: [FontSpec, ResolvedFontSpec],
        }
        border_optional {
            /// Tab border specification.
            border: [BorderSpec, ResolvedBorderSpec],
        }
    }
}

// ── §2.12 Sidebar ─────────────────────────────────────────────────────────────

define_widget_pair! {
    /// Sidebar panel background, selection, and hover colors.
    SidebarTheme / ResolvedSidebarTheme {
        option {
            /// Sidebar panel background fill.
            background_color: Rgba,
            /// Selected item background color.
            selection_background: Rgba,
            /// Selected item text color.
            selection_text_color: Rgba,
            /// Hovered item background color.
            hover_background: Rgba,
        }
        optional_nested {
            /// Sidebar font specification.
            font: [FontSpec, ResolvedFontSpec],
        }
        border_partial {
            /// Sidebar border specification.
            border: [BorderSpec, ResolvedBorderSpec],
        }
    }
}

// ── §2.13 Toolbar ─────────────────────────────────────────────────────────────

define_widget_pair! {
    /// Toolbar sizing, spacing, and font.
    ToolbarTheme / ResolvedToolbarTheme {
        option {
            /// Toolbar background color.
            background_color: Rgba,
            /// Toolbar height in logical pixels.
            bar_height as "bar_height_px": f32,
            /// Horizontal space between toolbar items.
            item_gap as "item_gap_px": f32,
            /// Toolbar icon size in logical pixels.
            icon_size as "icon_size_px": f32,
        }
        optional_nested {
            /// Toolbar label font specification.
            font: [FontSpec, ResolvedFontSpec],
            /// Toolbar border specification.
            border: [BorderSpec, ResolvedBorderSpec],
        }
    }
}

// ── §2.14 Status Bar ──────────────────────────────────────────────────────────

define_widget_pair! {
    /// Status bar font and background.
    StatusBarTheme / ResolvedStatusBarTheme {
        option {
            /// Status bar background color.
            background_color: Rgba,
        }
        optional_nested {
            /// Status bar font specification.
            font: [FontSpec, ResolvedFontSpec],
        }
        border_partial {
            /// Status bar border specification.
            border: [BorderSpec, ResolvedBorderSpec],
        }
    }
}

// ── §2.15 List / Table ────────────────────────────────────────────────────────

define_widget_pair! {
    /// List and table colors and row geometry.
    ListTheme / ResolvedListTheme {
        option {
            /// List background fill.
            background_color: Rgba,
            /// Alternate row background for striped lists.
            alternate_row_background: Rgba,
            /// Selected row highlight color.
            selection_background: Rgba,
            /// Text color inside a selected row.
            selection_text_color: Rgba,
            /// Column header background fill.
            header_background: Rgba,
            /// Grid line color between rows/columns.
            grid_color: Rgba,
            /// Row height in logical pixels.
            row_height as "row_height_px": f32,
            /// Hovered row background color.
            hover_background: Rgba,
            /// Hovered row text color.
            hover_text_color: Rgba,
            /// Disabled row text color.
            disabled_text_color: Rgba,
        }
        optional_nested {
            /// List item font specification.
            item_font: [FontSpec, ResolvedFontSpec],
            /// Column header font specification.
            header_font: [FontSpec, ResolvedFontSpec],
            /// List border specification.
            border: [BorderSpec, ResolvedBorderSpec],
        }
    }
}

// ── §2.16 Popover / Dropdown ──────────────────────────────────────────────────

define_widget_pair! {
    /// Popover / dropdown panel appearance.
    PopoverTheme / ResolvedPopoverTheme {
        option {
            /// Panel background fill.
            background_color: Rgba,
        }
        optional_nested {
            /// Popover font specification.
            font: [FontSpec, ResolvedFontSpec],
            /// Popover border specification.
            border: [BorderSpec, ResolvedBorderSpec],
        }
    }
}

// ── §2.17 Splitter ────────────────────────────────────────────────────────────

define_widget_pair! {
    /// Splitter handle width and color.
    SplitterTheme / ResolvedSplitterTheme {
        option {
            /// Handle width in logical pixels.
            divider_width as "divider_width_px": f32,
            /// Divider color.
            divider_color: Rgba,
            /// Divider color on hover.
            hover_color: Rgba,
        }
    }
}

// ── §2.18 Separator ───────────────────────────────────────────────────────────

define_widget_pair! {
    /// Separator line color and width.
    SeparatorTheme / ResolvedSeparatorTheme {
        option {
            /// Separator line color.
            line_color: Rgba,
            /// Separator line width in logical pixels.
            line_width as "line_width_px": f32,
        }
    }
}

// ── §2.21 Switch / Toggle ─────────────────────────────────────────────────────

define_widget_pair! {
    /// Toggle switch track, thumb, geometry, and interactive states.
    SwitchTheme / ResolvedSwitchTheme {
        option {
            /// Track background when the switch is on.
            checked_background: Rgba,
            /// Track background when the switch is off.
            unchecked_background: Rgba,
            /// Thumb (knob) color.
            thumb_background: Rgba,
            /// Track width in logical pixels.
            track_width as "track_width_px": f32,
            /// Track height in logical pixels.
            track_height as "track_height_px": f32,
            /// Thumb diameter in logical pixels.
            thumb_diameter as "thumb_diameter_px": f32,
            /// Track corner radius in logical pixels.
            track_radius as "track_radius_px": f32,
            /// Opacity multiplier when disabled (0.0-1.0).
            disabled_opacity: f32,
        }
        soft_option {
            /// Track hover color when checked (on).
            hover_checked_background: Rgba,
            /// Track hover color when unchecked (off).
            hover_unchecked_background: Rgba,
            /// Track color when disabled and checked.
            disabled_checked_background: Rgba,
            /// Track color when disabled and unchecked.
            disabled_unchecked_background: Rgba,
            /// Thumb color when disabled.
            disabled_thumb_color: Rgba,
        }
    }
}

// ── §2.22 Dialog ──────────────────────────────────────────────────────────────

define_widget_pair! {
    /// Dialog sizing, spacing, button order, fonts, border, and background.
    DialogTheme / ResolvedDialogTheme {
        option {
            /// Dialog background color.
            background_color: Rgba,
            /// Minimum dialog width in logical pixels.
            min_width as "min_width_px": f32,
            /// Maximum dialog width in logical pixels.
            max_width as "max_width_px": f32,
            /// Minimum dialog height in logical pixels.
            min_height as "min_height_px": f32,
            /// Maximum dialog height in logical pixels.
            max_height as "max_height_px": f32,
            /// Horizontal space between dialog buttons.
            button_gap as "button_gap_px": f32,
            /// Icon size for dialog type icons (warning, error, etc.).
            icon_size as "icon_size_px": f32,
            /// Platform button order convention (e.g., OK/Cancel vs Cancel/OK).
            button_order: DialogButtonOrder,
        }
        optional_nested {
            /// Dialog title font specification.
            title_font: [FontSpec, ResolvedFontSpec],
            /// Dialog body font specification.
            body_font: [FontSpec, ResolvedFontSpec],
            /// Dialog border specification.
            border: [BorderSpec, ResolvedBorderSpec],
        }
    }
}

// ── §2.23 Spinner / Progress Ring ─────────────────────────────────────────────

define_widget_pair! {
    /// Spinner / indeterminate progress indicator.
    SpinnerTheme / ResolvedSpinnerTheme {
        option {
            /// Spinner arc fill color.
            fill_color: Rgba,
            /// Spinner outer diameter in logical pixels.
            diameter as "diameter_px": f32,
            /// Minimum rendered size in logical pixels.
            min_diameter as "min_diameter_px": f32,
            /// Arc stroke width in logical pixels.
            stroke_width as "stroke_width_px": f32,
        }
    }
}

// ── §2.24 ComboBox / Dropdown Trigger ─────────────────────────────────────────

define_widget_pair! {
    /// ComboBox / dropdown trigger sizing.
    ComboBoxTheme / ResolvedComboBoxTheme {
        option {
            /// ComboBox background color.
            background_color: Rgba,
            /// Minimum trigger height in logical pixels.
            min_height as "min_height_px": f32,
            /// Minimum trigger width in logical pixels.
            min_width as "min_width_px": f32,
            /// Dropdown arrow size in logical pixels.
            arrow_icon_size as "arrow_icon_size_px": f32,
            /// Width of the arrow clickable area.
            arrow_area_width as "arrow_area_width_px": f32,
            /// Opacity multiplier when disabled (0.0-1.0).
            disabled_opacity: f32,
            /// ComboBox text color when disabled.
            disabled_text_color: Rgba,
        }
        soft_option {
            /// ComboBox background on hover.
            hover_background: Rgba,
            /// ComboBox background when disabled.
            disabled_background: Rgba,
        }
        optional_nested {
            /// ComboBox font specification.
            font: [FontSpec, ResolvedFontSpec],
            /// ComboBox border specification.
            border: [BorderSpec, ResolvedBorderSpec],
        }
    }
}

// ── §2.25 Segmented Control ───────────────────────────────────────────────────

define_widget_pair! {
    /// Segmented control sizing (macOS-primary; KDE uses tab bar metrics as proxy).
    SegmentedControlTheme / ResolvedSegmentedControlTheme {
        option {
            /// Segmented control background color.
            background_color: Rgba,
            /// Active segment background.
            active_background: Rgba,
            /// Active segment text color.
            active_text_color: Rgba,
            /// Segment height in logical pixels.
            segment_height as "segment_height_px": f32,
            /// Width of the separator between segments.
            separator_width as "separator_width_px": f32,
            /// Opacity multiplier when disabled (0.0-1.0).
            disabled_opacity: f32,
        }
        soft_option {
            /// Segment background on hover.
            hover_background: Rgba,
        }
        optional_nested {
            /// Segmented control font specification.
            font: [FontSpec, ResolvedFontSpec],
            /// Segmented control border specification.
            border: [BorderSpec, ResolvedBorderSpec],
        }
    }
}

// ── §2.26 Card / Container ────────────────────────────────────────────────────

define_widget_pair! {
    /// Card / container colors and geometry.
    CardTheme / ResolvedCardTheme {
        option {
            /// Card background fill.
            background_color: Rgba,
        }
        border_optional {
            /// Card border specification.
            border: [BorderSpec, ResolvedBorderSpec],
        }
    }
}

// ── §2.27 Expander / Disclosure ───────────────────────────────────────────────

define_widget_pair! {
    /// Expander / disclosure row geometry.
    ExpanderTheme / ResolvedExpanderTheme {
        option {
            /// Collapsed header row height in logical pixels.
            header_height as "header_height_px": f32,
            /// Disclosure arrow size in logical pixels.
            arrow_icon_size as "arrow_icon_size_px": f32,
        }
        soft_option {
            /// Expander header background on hover.
            hover_background: Rgba,
            /// Disclosure arrow/chevron color.
            arrow_color: Rgba,
        }
        optional_nested {
            /// Expander font specification.
            font: [FontSpec, ResolvedFontSpec],
            /// Expander border specification.
            border: [BorderSpec, ResolvedBorderSpec],
        }
    }
}

// ── §2.28 Link ────────────────────────────────────────────────────────────────

define_widget_pair! {
    /// Hyperlink colors and underline setting.
    LinkTheme / ResolvedLinkTheme {
        option {
            /// Visited link text color.
            visited_text_color: Rgba,
            /// Whether links are underlined.
            underline_enabled: bool,
            /// Link background fill (typically transparent).
            background_color: Rgba,
            /// Link background on hover.
            hover_background: Rgba,
            /// Link text color on hover.
            hover_text_color: Rgba,
            /// Link text color when pressed/active.
            active_text_color: Rgba,
            /// Link text color when disabled.
            disabled_text_color: Rgba,
        }
        optional_nested {
            /// Link font specification.
            font: [FontSpec, ResolvedFontSpec],
        }
    }
}

// -- Layout (top-level, not per-variant) ------------------------------------------

define_widget_pair! {
    /// Layout spacing constants shared between light and dark variants.
    ///
    /// Unlike other widget themes, LayoutTheme lives on [`crate::ThemeSpec`] (top-level)
    /// rather than [`crate::ThemeVariant`] because spacing is variant-independent.
    LayoutTheme / ResolvedLayoutTheme {
        option {
            /// Space between adjacent widgets in logical pixels.
            widget_gap as "widget_gap_px": f32,
            /// Padding inside containers in logical pixels.
            container_margin as "container_margin_px": f32,
            /// Padding inside the main window in logical pixels.
            window_margin as "window_margin_px": f32,
            /// Space between major content sections in logical pixels.
            section_gap as "section_gap_px": f32,
        }
    }
}

// --- Per-widget range checks (called from validate()) ---

use crate::resolve::validate_helpers::{
    check_min_max, check_non_negative, check_positive, check_range_f32, check_range_u16,
};

impl ResolvedWindowTheme {
    pub(crate) fn check_ranges(&self, prefix: &str, errors: &mut Vec<String>) {
        check_positive(
            self.title_bar_font.size,
            &format!("{prefix}.title_bar_font.size"),
            errors,
        );
        check_range_u16(
            self.title_bar_font.weight,
            100,
            900,
            &format!("{prefix}.title_bar_font.weight"),
            errors,
        );
    }
}

impl ResolvedButtonTheme {
    pub(crate) fn check_ranges(&self, prefix: &str, errors: &mut Vec<String>) {
        check_non_negative(self.min_width, &format!("{prefix}.min_width"), errors);
        check_non_negative(self.min_height, &format!("{prefix}.min_height"), errors);
        check_non_negative(
            self.icon_text_gap,
            &format!("{prefix}.icon_text_gap"),
            errors,
        );
        check_range_f32(
            self.disabled_opacity,
            0.0,
            1.0,
            &format!("{prefix}.disabled_opacity"),
            errors,
        );
        check_positive(self.font.size, &format!("{prefix}.font.size"), errors);
        check_range_u16(
            self.font.weight,
            100,
            900,
            &format!("{prefix}.font.weight"),
            errors,
        );
    }
}

impl ResolvedInputTheme {
    pub(crate) fn check_ranges(&self, prefix: &str, errors: &mut Vec<String>) {
        check_non_negative(self.min_height, &format!("{prefix}.min_height"), errors);
        check_range_f32(
            self.disabled_opacity,
            0.0,
            1.0,
            &format!("{prefix}.disabled_opacity"),
            errors,
        );
        check_positive(self.font.size, &format!("{prefix}.font.size"), errors);
        check_range_u16(
            self.font.weight,
            100,
            900,
            &format!("{prefix}.font.weight"),
            errors,
        );
    }
}

impl ResolvedCheckboxTheme {
    pub(crate) fn check_ranges(&self, prefix: &str, errors: &mut Vec<String>) {
        check_non_negative(
            self.indicator_width,
            &format!("{prefix}.indicator_width"),
            errors,
        );
        check_non_negative(self.label_gap, &format!("{prefix}.label_gap"), errors);
        check_range_f32(
            self.disabled_opacity,
            0.0,
            1.0,
            &format!("{prefix}.disabled_opacity"),
            errors,
        );
        check_positive(self.font.size, &format!("{prefix}.font.size"), errors);
        check_range_u16(
            self.font.weight,
            100,
            900,
            &format!("{prefix}.font.weight"),
            errors,
        );
    }
}

impl ResolvedMenuTheme {
    pub(crate) fn check_ranges(&self, prefix: &str, errors: &mut Vec<String>) {
        check_non_negative(self.row_height, &format!("{prefix}.row_height"), errors);
        check_non_negative(
            self.icon_text_gap,
            &format!("{prefix}.icon_text_gap"),
            errors,
        );
        check_non_negative(self.icon_size, &format!("{prefix}.icon_size"), errors);
        check_positive(self.font.size, &format!("{prefix}.font.size"), errors);
        check_range_u16(
            self.font.weight,
            100,
            900,
            &format!("{prefix}.font.weight"),
            errors,
        );
    }
}

impl ResolvedTooltipTheme {
    pub(crate) fn check_ranges(&self, prefix: &str, errors: &mut Vec<String>) {
        check_non_negative(self.max_width, &format!("{prefix}.max_width"), errors);
        check_positive(self.font.size, &format!("{prefix}.font.size"), errors);
        check_range_u16(
            self.font.weight,
            100,
            900,
            &format!("{prefix}.font.weight"),
            errors,
        );
    }
}

impl ResolvedScrollbarTheme {
    pub(crate) fn check_ranges(&self, prefix: &str, errors: &mut Vec<String>) {
        check_non_negative(self.groove_width, &format!("{prefix}.groove_width"), errors);
        check_non_negative(
            self.min_thumb_length,
            &format!("{prefix}.min_thumb_length"),
            errors,
        );
        check_non_negative(self.thumb_width, &format!("{prefix}.thumb_width"), errors);
    }
}

impl ResolvedSliderTheme {
    pub(crate) fn check_ranges(&self, prefix: &str, errors: &mut Vec<String>) {
        check_non_negative(self.track_height, &format!("{prefix}.track_height"), errors);
        check_non_negative(
            self.thumb_diameter,
            &format!("{prefix}.thumb_diameter"),
            errors,
        );
        check_non_negative(
            self.tick_mark_length,
            &format!("{prefix}.tick_mark_length"),
            errors,
        );
        check_range_f32(
            self.disabled_opacity,
            0.0,
            1.0,
            &format!("{prefix}.disabled_opacity"),
            errors,
        );
    }
}

impl ResolvedProgressBarTheme {
    pub(crate) fn check_ranges(&self, prefix: &str, errors: &mut Vec<String>) {
        check_non_negative(self.track_height, &format!("{prefix}.track_height"), errors);
        check_non_negative(self.min_width, &format!("{prefix}.min_width"), errors);
    }
}

impl ResolvedTabTheme {
    pub(crate) fn check_ranges(&self, prefix: &str, errors: &mut Vec<String>) {
        check_non_negative(self.min_width, &format!("{prefix}.min_width"), errors);
        check_non_negative(self.min_height, &format!("{prefix}.min_height"), errors);
        check_positive(self.font.size, &format!("{prefix}.font.size"), errors);
        check_range_u16(
            self.font.weight,
            100,
            900,
            &format!("{prefix}.font.weight"),
            errors,
        );
    }
}

impl ResolvedSidebarTheme {
    pub(crate) fn check_ranges(&self, prefix: &str, errors: &mut Vec<String>) {
        check_positive(self.font.size, &format!("{prefix}.font.size"), errors);
        check_range_u16(
            self.font.weight,
            100,
            900,
            &format!("{prefix}.font.weight"),
            errors,
        );
    }
}

impl ResolvedToolbarTheme {
    pub(crate) fn check_ranges(&self, prefix: &str, errors: &mut Vec<String>) {
        check_non_negative(self.bar_height, &format!("{prefix}.bar_height"), errors);
        check_non_negative(self.item_gap, &format!("{prefix}.item_gap"), errors);
        check_non_negative(self.icon_size, &format!("{prefix}.icon_size"), errors);
        check_positive(self.font.size, &format!("{prefix}.font.size"), errors);
        check_range_u16(
            self.font.weight,
            100,
            900,
            &format!("{prefix}.font.weight"),
            errors,
        );
    }
}

impl ResolvedStatusBarTheme {
    pub(crate) fn check_ranges(&self, prefix: &str, errors: &mut Vec<String>) {
        check_positive(self.font.size, &format!("{prefix}.font.size"), errors);
        check_range_u16(
            self.font.weight,
            100,
            900,
            &format!("{prefix}.font.weight"),
            errors,
        );
    }
}

impl ResolvedListTheme {
    pub(crate) fn check_ranges(&self, prefix: &str, errors: &mut Vec<String>) {
        check_non_negative(self.row_height, &format!("{prefix}.row_height"), errors);
        check_positive(
            self.item_font.size,
            &format!("{prefix}.item_font.size"),
            errors,
        );
        check_range_u16(
            self.item_font.weight,
            100,
            900,
            &format!("{prefix}.item_font.weight"),
            errors,
        );
        check_positive(
            self.header_font.size,
            &format!("{prefix}.header_font.size"),
            errors,
        );
        check_range_u16(
            self.header_font.weight,
            100,
            900,
            &format!("{prefix}.header_font.weight"),
            errors,
        );
    }
}

impl ResolvedPopoverTheme {
    pub(crate) fn check_ranges(&self, prefix: &str, errors: &mut Vec<String>) {
        check_positive(self.font.size, &format!("{prefix}.font.size"), errors);
        check_range_u16(
            self.font.weight,
            100,
            900,
            &format!("{prefix}.font.weight"),
            errors,
        );
    }
}

impl ResolvedSplitterTheme {
    pub(crate) fn check_ranges(&self, prefix: &str, errors: &mut Vec<String>) {
        check_non_negative(
            self.divider_width,
            &format!("{prefix}.divider_width"),
            errors,
        );
    }
}

impl ResolvedSeparatorTheme {
    pub(crate) fn check_ranges(&self, prefix: &str, errors: &mut Vec<String>) {
        check_non_negative(self.line_width, &format!("{prefix}.line_width"), errors);
    }
}

impl ResolvedSwitchTheme {
    pub(crate) fn check_ranges(&self, prefix: &str, errors: &mut Vec<String>) {
        check_non_negative(self.track_width, &format!("{prefix}.track_width"), errors);
        check_non_negative(self.track_height, &format!("{prefix}.track_height"), errors);
        check_non_negative(
            self.thumb_diameter,
            &format!("{prefix}.thumb_diameter"),
            errors,
        );
        check_non_negative(self.track_radius, &format!("{prefix}.track_radius"), errors);
        check_range_f32(
            self.disabled_opacity,
            0.0,
            1.0,
            &format!("{prefix}.disabled_opacity"),
            errors,
        );
    }
}

impl ResolvedDialogTheme {
    pub(crate) fn check_ranges(&self, prefix: &str, errors: &mut Vec<String>) {
        check_non_negative(self.min_width, &format!("{prefix}.min_width"), errors);
        check_non_negative(self.max_width, &format!("{prefix}.max_width"), errors);
        check_non_negative(self.min_height, &format!("{prefix}.min_height"), errors);
        check_non_negative(self.max_height, &format!("{prefix}.max_height"), errors);
        check_non_negative(self.button_gap, &format!("{prefix}.button_gap"), errors);
        check_non_negative(self.icon_size, &format!("{prefix}.icon_size"), errors);
        check_positive(
            self.title_font.size,
            &format!("{prefix}.title_font.size"),
            errors,
        );
        check_range_u16(
            self.title_font.weight,
            100,
            900,
            &format!("{prefix}.title_font.weight"),
            errors,
        );
        check_positive(
            self.body_font.size,
            &format!("{prefix}.body_font.size"),
            errors,
        );
        check_range_u16(
            self.body_font.weight,
            100,
            900,
            &format!("{prefix}.body_font.weight"),
            errors,
        );
        check_min_max(
            self.min_width,
            self.max_width,
            &format!("{prefix}.min_width"),
            &format!("{prefix}.max_width"),
            errors,
        );
        check_min_max(
            self.min_height,
            self.max_height,
            &format!("{prefix}.min_height"),
            &format!("{prefix}.max_height"),
            errors,
        );
    }
}

impl ResolvedSpinnerTheme {
    pub(crate) fn check_ranges(&self, prefix: &str, errors: &mut Vec<String>) {
        check_non_negative(self.diameter, &format!("{prefix}.diameter"), errors);
        check_non_negative(self.min_diameter, &format!("{prefix}.min_diameter"), errors);
        check_non_negative(self.stroke_width, &format!("{prefix}.stroke_width"), errors);
    }
}

impl ResolvedLinkTheme {
    pub(crate) fn check_ranges(&self, prefix: &str, errors: &mut Vec<String>) {
        check_positive(self.font.size, &format!("{prefix}.font.size"), errors);
        check_range_u16(
            self.font.weight,
            100,
            900,
            &format!("{prefix}.font.weight"),
            errors,
        );
    }
}

impl ResolvedComboBoxTheme {
    pub(crate) fn check_ranges(&self, prefix: &str, errors: &mut Vec<String>) {
        check_non_negative(self.min_height, &format!("{prefix}.min_height"), errors);
        check_non_negative(self.min_width, &format!("{prefix}.min_width"), errors);
        check_non_negative(
            self.arrow_icon_size,
            &format!("{prefix}.arrow_icon_size"),
            errors,
        );
        check_non_negative(
            self.arrow_area_width,
            &format!("{prefix}.arrow_area_width"),
            errors,
        );
        check_range_f32(
            self.disabled_opacity,
            0.0,
            1.0,
            &format!("{prefix}.disabled_opacity"),
            errors,
        );
        check_positive(self.font.size, &format!("{prefix}.font.size"), errors);
        check_range_u16(
            self.font.weight,
            100,
            900,
            &format!("{prefix}.font.weight"),
            errors,
        );
    }
}

impl ResolvedSegmentedControlTheme {
    pub(crate) fn check_ranges(&self, prefix: &str, errors: &mut Vec<String>) {
        check_non_negative(
            self.segment_height,
            &format!("{prefix}.segment_height"),
            errors,
        );
        check_non_negative(
            self.separator_width,
            &format!("{prefix}.separator_width"),
            errors,
        );
        check_range_f32(
            self.disabled_opacity,
            0.0,
            1.0,
            &format!("{prefix}.disabled_opacity"),
            errors,
        );
        check_positive(self.font.size, &format!("{prefix}.font.size"), errors);
        check_range_u16(
            self.font.weight,
            100,
            900,
            &format!("{prefix}.font.weight"),
            errors,
        );
    }
}

impl ResolvedExpanderTheme {
    pub(crate) fn check_ranges(&self, prefix: &str, errors: &mut Vec<String>) {
        check_non_negative(
            self.header_height,
            &format!("{prefix}.header_height"),
            errors,
        );
        check_non_negative(
            self.arrow_icon_size,
            &format!("{prefix}.arrow_icon_size"),
            errors,
        );
        check_positive(self.font.size, &format!("{prefix}.font.size"), errors);
        check_range_u16(
            self.font.weight,
            100,
            900,
            &format!("{prefix}.font.weight"),
            errors,
        );
    }
}

#[cfg(test)]
#[allow(clippy::unwrap_used, clippy::expect_used, dead_code)]
mod tests {
    use super::*;
    use crate::Rgba;
    use crate::model::border::{BorderSpec, ResolvedBorderSpec};
    use crate::model::font::FontSize;
    use crate::model::{DialogButtonOrder, FontSpec};

    // Define a test widget pair using the macro (validates macro itself still works)
    define_widget_pair! {
        /// Test widget for macro verification.
        TestWidget / ResolvedTestWidget {
            option {
                size: f32,
                label: String,
            }
            optional_nested {
                font: [FontSpec, ResolvedFontSpec],
            }
        }
    }

    // === ResolvedFontSpec tests ===

    #[test]
    fn resolved_font_spec_fields_are_concrete() {
        let rfs = ResolvedFontSpec {
            family: "Inter".into(),
            size: 14.0,
            weight: 400,
            style: crate::model::font::FontStyle::Normal,
            color: crate::Rgba::rgb(0, 0, 0),
        };
        assert_eq!(rfs.family, "Inter");
        assert_eq!(rfs.size, 14.0);
        assert_eq!(rfs.weight, 400);
    }

    // === define_widget_pair! generated struct tests ===

    #[test]
    fn generated_option_struct_has_option_fields() {
        let w = TestWidget::default();
        assert!(w.size.is_none());
        assert!(w.label.is_none());
        assert!(w.font.is_none());
    }

    #[test]
    fn generated_option_struct_is_empty_by_default() {
        assert!(TestWidget::default().is_empty());
    }

    #[test]
    fn generated_option_struct_not_empty_when_size_set() {
        let w = TestWidget {
            size: Some(24.0),
            ..Default::default()
        };
        assert!(!w.is_empty());
    }

    #[test]
    fn generated_option_struct_not_empty_when_font_set() {
        let w = TestWidget {
            font: Some(FontSpec {
                size: Some(FontSize::Px(14.0)),
                ..Default::default()
            }),
            ..Default::default()
        };
        assert!(!w.is_empty());
    }

    #[test]
    fn generated_resolved_struct_has_concrete_fields() {
        let resolved = ResolvedTestWidget {
            size: 24.0,
            label: "Click me".into(),
            font: ResolvedFontSpec {
                family: "Inter".into(),
                size: 14.0,
                weight: 400,
                style: crate::model::font::FontStyle::Normal,
                color: crate::Rgba::rgb(0, 0, 0),
            },
        };
        assert_eq!(resolved.size, 24.0);
        assert_eq!(resolved.label, "Click me");
        assert_eq!(resolved.font.family, "Inter");
    }

    // === merge tests for generated structs ===

    #[test]
    fn generated_merge_option_field_overlay_wins() {
        let mut base = TestWidget {
            size: Some(20.0),
            ..Default::default()
        };
        let overlay = TestWidget {
            size: Some(24.0),
            ..Default::default()
        };
        base.merge(&overlay);
        assert_eq!(base.size, Some(24.0));
    }

    #[test]
    fn generated_merge_option_field_none_preserves_base() {
        let mut base = TestWidget {
            size: Some(20.0),
            ..Default::default()
        };
        let overlay = TestWidget::default();
        base.merge(&overlay);
        assert_eq!(base.size, Some(20.0));
    }

    #[test]
    fn generated_merge_optional_nested_both_some_merges_inner() {
        let mut base = TestWidget {
            font: Some(FontSpec {
                family: Some("Noto Sans".into()),
                size: Some(FontSize::Px(12.0)),
                weight: None,
                ..Default::default()
            }),
            ..Default::default()
        };
        let overlay = TestWidget {
            font: Some(FontSpec {
                family: None,
                size: None,
                weight: Some(700),
                ..Default::default()
            }),
            ..Default::default()
        };
        base.merge(&overlay);
        let font = base.font.as_ref().unwrap();
        assert_eq!(font.family.as_deref(), Some("Noto Sans")); // preserved
        assert_eq!(font.size, Some(FontSize::Px(12.0))); // preserved
        assert_eq!(font.weight, Some(700)); // overlay sets
    }

    #[test]
    fn generated_merge_optional_nested_none_plus_some_clones() {
        let mut base = TestWidget::default();
        let overlay = TestWidget {
            font: Some(FontSpec {
                family: Some("Inter".into()),
                size: Some(FontSize::Px(14.0)),
                weight: Some(400),
                ..Default::default()
            }),
            ..Default::default()
        };
        base.merge(&overlay);
        let font = base.font.as_ref().unwrap();
        assert_eq!(font.family.as_deref(), Some("Inter"));
        assert_eq!(font.size, Some(FontSize::Px(14.0)));
        assert_eq!(font.weight, Some(400));
    }

    #[test]
    fn generated_merge_optional_nested_some_plus_none_preserves_base() {
        let mut base = TestWidget {
            font: Some(FontSpec {
                family: Some("Inter".into()),
                size: Some(FontSize::Px(14.0)),
                weight: Some(400),
                ..Default::default()
            }),
            ..Default::default()
        };
        let overlay = TestWidget::default();
        base.merge(&overlay);
        let font = base.font.as_ref().unwrap();
        assert_eq!(font.family.as_deref(), Some("Inter"));
    }

    #[test]
    fn generated_merge_optional_nested_none_plus_none_stays_none() {
        let mut base = TestWidget::default();
        let overlay = TestWidget::default();
        base.merge(&overlay);
        assert!(base.font.is_none());
    }

    // === impl_merge! optional_nested clause direct tests ===

    // Verify the optional_nested clause directly on a FontSpec-containing struct
    #[derive(Clone, Debug, Default, PartialEq, serde::Serialize, serde::Deserialize)]
    struct WithFont {
        name: Option<String>,
        font: Option<FontSpec>,
    }

    impl_merge!(WithFont {
        option { name }
        optional_nested { font }
    });

    #[test]
    fn impl_merge_optional_nested_none_none_stays_none() {
        let mut base = WithFont::default();
        let overlay = WithFont::default();
        base.merge(&overlay);
        assert!(base.font.is_none());
    }

    #[test]
    fn impl_merge_optional_nested_some_none_preserves_base() {
        let mut base = WithFont {
            font: Some(FontSpec {
                size: Some(FontSize::Px(12.0)),
                ..Default::default()
            }),
            ..Default::default()
        };
        let overlay = WithFont::default();
        base.merge(&overlay);
        assert_eq!(base.font.as_ref().unwrap().size, Some(FontSize::Px(12.0)));
    }

    #[test]
    fn impl_merge_optional_nested_none_some_clones_overlay() {
        let mut base = WithFont::default();
        let overlay = WithFont {
            font: Some(FontSpec {
                family: Some("Inter".into()),
                ..Default::default()
            }),
            ..Default::default()
        };
        base.merge(&overlay);
        assert_eq!(base.font.as_ref().unwrap().family.as_deref(), Some("Inter"));
    }

    #[test]
    fn impl_merge_optional_nested_some_some_merges_inner() {
        let mut base = WithFont {
            font: Some(FontSpec {
                family: Some("Noto".into()),
                size: Some(FontSize::Px(11.0)),
                weight: None,
                ..Default::default()
            }),
            ..Default::default()
        };
        let overlay = WithFont {
            font: Some(FontSpec {
                family: None,
                size: Some(FontSize::Px(14.0)),
                weight: Some(400),
                ..Default::default()
            }),
            ..Default::default()
        };
        base.merge(&overlay);
        let f = base.font.as_ref().unwrap();
        assert_eq!(f.family.as_deref(), Some("Noto")); // preserved
        assert_eq!(f.size, Some(FontSize::Px(14.0))); // overlay wins
        assert_eq!(f.weight, Some(400)); // overlay sets
    }

    #[test]
    fn impl_merge_optional_nested_is_empty_none() {
        let w = WithFont::default();
        assert!(w.is_empty());
    }

    #[test]
    fn impl_merge_optional_nested_is_empty_some_default() {
        // Some(FontSpec::default()) with all-None sub-fields counts as empty (D-2 fix).
        let w = WithFont {
            font: Some(FontSpec::default()),
            ..Default::default()
        };
        assert!(w.is_empty());
    }

    #[test]
    fn impl_merge_optional_nested_is_not_empty_when_populated() {
        let w = WithFont {
            font: Some(FontSpec {
                size: Some(FontSize::Px(14.0)),
                ..Default::default()
            }),
            ..Default::default()
        };
        assert!(!w.is_empty());
    }

    // === ButtonTheme tests ===

    #[test]
    fn button_theme_default_is_empty() {
        assert!(ButtonTheme::default().is_empty());
    }

    #[test]
    fn button_theme_not_empty_when_set() {
        let b = ButtonTheme {
            background_color: Some(Rgba::rgb(200, 200, 200)),
            min_width: Some(64.0),
            ..Default::default()
        };
        assert!(!b.is_empty());
    }

    #[test]
    fn button_theme_merge_font_optional_nested() {
        let mut base = ButtonTheme {
            font: Some(FontSpec {
                family: Some("Noto Sans".into()),
                size: Some(FontSize::Px(11.0)),
                weight: None,
                ..Default::default()
            }),
            ..Default::default()
        };
        let overlay = ButtonTheme {
            font: Some(FontSpec {
                family: None,
                weight: Some(700),
                ..Default::default()
            }),
            ..Default::default()
        };
        base.merge(&overlay);
        let f = base.font.as_ref().unwrap();
        assert_eq!(f.family.as_deref(), Some("Noto Sans")); // preserved
        assert_eq!(f.weight, Some(700)); // overlay
    }

    #[test]
    fn button_theme_toml_round_trip_with_font_and_border() {
        let b = ButtonTheme {
            background_color: Some(Rgba::rgb(200, 200, 200)),
            font: Some(FontSpec {
                family: Some("Inter".into()),
                size: Some(FontSize::Px(14.0)),
                weight: Some(400),
                ..Default::default()
            }),
            border: Some(BorderSpec {
                corner_radius: Some(4.0),
                ..Default::default()
            }),
            ..Default::default()
        };
        let toml_str = toml::to_string(&b).unwrap();
        let b2: ButtonTheme = toml::from_str(&toml_str).unwrap();
        assert_eq!(b, b2);
    }

    // === WindowTheme tests ===

    #[test]
    fn window_theme_has_new_fields() {
        let w = WindowTheme {
            inactive_title_bar_background: Some(Rgba::rgb(180, 180, 180)),
            inactive_title_bar_text_color: Some(Rgba::rgb(120, 120, 120)),
            title_bar_font: Some(FontSpec {
                weight: Some(700),
                ..Default::default()
            }),
            border: Some(BorderSpec {
                corner_radius: Some(4.0),
                shadow_enabled: Some(true),
                ..Default::default()
            }),
            ..Default::default()
        };
        assert!(!w.is_empty());
        assert!(w.inactive_title_bar_background.is_some());
        assert!(w.inactive_title_bar_text_color.is_some());
        assert!(w.title_bar_font.is_some());
        assert!(w.border.is_some());
    }

    #[test]
    fn window_theme_default_is_empty() {
        assert!(WindowTheme::default().is_empty());
    }

    // === DialogTheme tests ===

    #[test]
    fn dialog_theme_button_order_works() {
        let d = DialogTheme {
            button_order: Some(DialogButtonOrder::PrimaryRight),
            min_width: Some(300.0),
            ..Default::default()
        };
        assert_eq!(d.button_order, Some(DialogButtonOrder::PrimaryRight));
        assert_eq!(d.min_width, Some(300.0));
        assert!(!d.is_empty());
    }

    #[test]
    fn dialog_theme_button_order_toml_round_trip() {
        let d = DialogTheme {
            button_order: Some(DialogButtonOrder::PrimaryLeft),
            ..Default::default()
        };
        let toml_str = toml::to_string(&d).unwrap();
        let d2: DialogTheme = toml::from_str(&toml_str).unwrap();
        assert_eq!(d, d2);
    }

    #[test]
    fn dialog_theme_default_is_empty() {
        assert!(DialogTheme::default().is_empty());
    }

    // === SplitterTheme tests ===

    #[test]
    fn splitter_theme_single_field_merge() {
        let mut base = SplitterTheme {
            divider_width: Some(4.0),
            ..Default::default()
        };
        let overlay = SplitterTheme {
            divider_width: Some(6.0),
            ..Default::default()
        };
        base.merge(&overlay);
        assert_eq!(base.divider_width, Some(6.0));
    }

    #[test]
    fn splitter_theme_merge_none_preserves_base() {
        let mut base = SplitterTheme {
            divider_width: Some(4.0),
            ..Default::default()
        };
        let overlay = SplitterTheme::default();
        base.merge(&overlay);
        assert_eq!(base.divider_width, Some(4.0));
    }

    #[test]
    fn splitter_theme_default_is_empty() {
        assert!(SplitterTheme::default().is_empty());
    }

    #[test]
    fn splitter_theme_not_empty_when_set() {
        assert!(
            !SplitterTheme {
                divider_width: Some(4.0),
                ..Default::default()
            }
            .is_empty()
        );
    }

    // === SeparatorTheme tests ===

    #[test]
    fn separator_theme_single_field() {
        let s = SeparatorTheme {
            line_color: Some(Rgba::rgb(200, 200, 200)),
            ..Default::default()
        };
        assert!(!s.is_empty());
    }

    // === All 25 widget theme defaults are empty ===

    #[test]
    fn all_widget_theme_defaults_are_empty() {
        assert!(WindowTheme::default().is_empty());
        assert!(ButtonTheme::default().is_empty());
        assert!(InputTheme::default().is_empty());
        assert!(CheckboxTheme::default().is_empty());
        assert!(MenuTheme::default().is_empty());
        assert!(TooltipTheme::default().is_empty());
        assert!(ScrollbarTheme::default().is_empty());
        assert!(SliderTheme::default().is_empty());
        assert!(ProgressBarTheme::default().is_empty());
        assert!(TabTheme::default().is_empty());
        assert!(SidebarTheme::default().is_empty());
        assert!(ToolbarTheme::default().is_empty());
        assert!(StatusBarTheme::default().is_empty());
        assert!(ListTheme::default().is_empty());
        assert!(PopoverTheme::default().is_empty());
        assert!(SplitterTheme::default().is_empty());
        assert!(SeparatorTheme::default().is_empty());
        assert!(SwitchTheme::default().is_empty());
        assert!(DialogTheme::default().is_empty());
        assert!(SpinnerTheme::default().is_empty());
        assert!(ComboBoxTheme::default().is_empty());
        assert!(SegmentedControlTheme::default().is_empty());
        assert!(CardTheme::default().is_empty());
        assert!(ExpanderTheme::default().is_empty());
        assert!(LinkTheme::default().is_empty());
    }

    // === Representative TOML round-trips ===

    #[test]
    fn input_theme_toml_round_trip() {
        let t = InputTheme {
            background_color: Some(Rgba::rgb(255, 255, 255)),
            font: Some(FontSpec {
                family: Some("Noto Sans".into()),
                ..Default::default()
            }),
            border: Some(BorderSpec {
                color: Some(Rgba::rgb(180, 180, 180)),
                corner_radius: Some(4.0),
                ..Default::default()
            }),
            ..Default::default()
        };
        let toml_str = toml::to_string(&t).unwrap();
        let t2: InputTheme = toml::from_str(&toml_str).unwrap();
        assert_eq!(t, t2);
    }

    #[test]
    fn switch_theme_toml_round_trip() {
        let s = SwitchTheme {
            checked_background: Some(Rgba::rgb(0, 120, 215)),
            track_width: Some(40.0),
            track_height: Some(20.0),
            thumb_diameter: Some(14.0),
            track_radius: Some(10.0),
            ..Default::default()
        };
        let toml_str = toml::to_string(&s).unwrap();
        let s2: SwitchTheme = toml::from_str(&toml_str).unwrap();
        assert_eq!(s, s2);
    }

    #[test]
    fn card_theme_with_border() {
        let c = CardTheme {
            background_color: Some(Rgba::rgb(255, 255, 255)),
            border: Some(BorderSpec {
                corner_radius: Some(8.0),
                shadow_enabled: Some(true),
                ..Default::default()
            }),
        };
        assert!(!c.is_empty());
    }

    #[test]
    fn link_theme_has_underline_enabled_bool_field() {
        let l = LinkTheme {
            visited_text_color: Some(Rgba::rgb(100, 0, 200)),
            underline_enabled: Some(true),
            ..Default::default()
        };
        assert!(!l.is_empty());
        assert_eq!(l.underline_enabled, Some(true));
    }

    #[test]
    fn status_bar_theme_has_font_and_background() {
        let s = StatusBarTheme {
            background_color: Some(Rgba::rgb(240, 240, 240)),
            font: Some(FontSpec {
                size: Some(FontSize::Px(11.0)),
                ..Default::default()
            }),
            ..Default::default()
        };
        assert!(!s.is_empty());
    }

    // === SC4: Dual optional_nested (font + border) test widget ===

    // SC4: Verify define_widget_pair! handles dual optional_nested (font + border)
    define_widget_pair! {
        /// Test widget with both font and border nested sub-structs.
        DualNestedTestWidget / ResolvedDualNestedTestWidget {
            option {
                background: Rgba,
                min_height: f32,
            }
            optional_nested {
                font: [FontSpec, ResolvedFontSpec],
                border: [BorderSpec, ResolvedBorderSpec],
            }
        }
    }

    #[test]
    fn dual_nested_default_is_empty() {
        assert!(DualNestedTestWidget::default().is_empty());
    }

    #[test]
    fn dual_nested_field_names() {
        assert_eq!(DualNestedTestWidget::FIELD_NAMES.len(), 4);
        assert!(DualNestedTestWidget::FIELD_NAMES.contains(&"background"));
        assert!(DualNestedTestWidget::FIELD_NAMES.contains(&"min_height"));
        assert!(DualNestedTestWidget::FIELD_NAMES.contains(&"font"));
        assert!(DualNestedTestWidget::FIELD_NAMES.contains(&"border"));
    }

    #[test]
    fn dual_nested_not_empty_when_font_set() {
        let w = DualNestedTestWidget {
            font: Some(FontSpec {
                family: Some("Inter".into()),
                ..Default::default()
            }),
            ..Default::default()
        };
        assert!(!w.is_empty());
    }

    #[test]
    fn dual_nested_not_empty_when_border_set() {
        let w = DualNestedTestWidget {
            border: Some(BorderSpec {
                color: Some(Rgba::rgb(100, 100, 100)),
                ..Default::default()
            }),
            ..Default::default()
        };
        assert!(!w.is_empty());
    }

    #[test]
    fn dual_nested_merge_both_nested() {
        let mut base = DualNestedTestWidget {
            font: Some(FontSpec {
                family: Some("Noto Sans".into()),
                ..Default::default()
            }),
            ..Default::default()
        };
        let overlay = DualNestedTestWidget {
            border: Some(BorderSpec {
                corner_radius: Some(4.0),
                ..Default::default()
            }),
            ..Default::default()
        };
        base.merge(&overlay);
        assert!(base.font.is_some());
        assert!(base.border.is_some());
        assert_eq!(
            base.font.as_ref().and_then(|f| f.family.as_deref()),
            Some("Noto Sans")
        );
        assert_eq!(
            base.border.as_ref().and_then(|b| b.corner_radius),
            Some(4.0)
        );
    }

    #[test]
    fn dual_nested_merge_inner_font_fields() {
        let mut base = DualNestedTestWidget {
            font: Some(FontSpec {
                family: Some("Noto Sans".into()),
                ..Default::default()
            }),
            ..Default::default()
        };
        let overlay = DualNestedTestWidget {
            font: Some(FontSpec {
                size: Some(FontSize::Px(14.0)),
                ..Default::default()
            }),
            ..Default::default()
        };
        base.merge(&overlay);
        let font = base.font.as_ref().unwrap();
        assert_eq!(font.family.as_deref(), Some("Noto Sans")); // preserved
        assert_eq!(font.size, Some(FontSize::Px(14.0))); // overlay sets
    }

    #[test]
    fn dual_nested_toml_round_trip() {
        let w = DualNestedTestWidget {
            background: Some(Rgba::rgb(240, 240, 240)),
            min_height: Some(32.0),
            font: Some(FontSpec {
                family: Some("Inter".into()),
                size: Some(FontSize::Px(14.0)),
                weight: Some(400),
                ..Default::default()
            }),
            border: Some(BorderSpec {
                color: Some(Rgba::rgb(180, 180, 180)),
                corner_radius: Some(4.0),
                line_width: Some(1.0),
                ..Default::default()
            }),
        };
        let toml_str = toml::to_string(&w).unwrap();
        let w2: DualNestedTestWidget = toml::from_str(&toml_str).unwrap();
        assert_eq!(w, w2);
    }

    // === LayoutTheme tests ===

    // === validate_widget() generation tests ===

    #[test]
    fn button_validate_widget_extracts_all_fields() {
        let button = ButtonTheme {
            background_color: Some(Rgba::rgb(200, 200, 200)),
            primary_background: Some(Rgba::rgb(0, 120, 215)),
            primary_text_color: Some(Rgba::rgb(255, 255, 255)),
            min_width: Some(80.0),
            min_height: Some(32.0),
            icon_text_gap: Some(8.0),
            disabled_opacity: Some(0.4),
            hover_background: Some(Rgba::rgb(210, 210, 210)),
            hover_text_color: Some(Rgba::rgb(0, 0, 0)),
            active_text_color: Some(Rgba::rgb(0, 0, 0)),
            disabled_text_color: Some(Rgba::rgb(128, 128, 128)),
            active_background: Some(Rgba::rgb(180, 180, 180)),
            disabled_background: Some(Rgba::rgb(220, 220, 220)),
            font: Some(FontSpec {
                family: Some("Inter".into()),
                size: Some(FontSize::Px(14.0)),
                weight: Some(400),
                style: Some(crate::model::font::FontStyle::Normal),
                color: Some(Rgba::rgb(0, 0, 0)),
            }),
            border: Some(BorderSpec {
                color: Some(Rgba::rgb(100, 100, 100)),
                corner_radius: Some(4.0),
                corner_radius_lg: Some(8.0),
                line_width: Some(1.0),
                opacity: Some(0.8),
                shadow_enabled: Some(false),
                padding_horizontal: Some(12.0),
                padding_vertical: Some(6.0),
            }),
        };
        let mut missing = Vec::new();
        let resolved = ResolvedButtonTheme::validate_widget(&button, "button", 96.0, &mut missing);
        assert!(missing.is_empty(), "unexpected missing: {missing:?}");
        assert_eq!(resolved.background_color, Rgba::rgb(200, 200, 200));
        assert_eq!(resolved.min_width, 80.0);
        assert_eq!(resolved.font.family, "Inter");
        assert_eq!(resolved.font.size, 14.0);
        assert_eq!(resolved.border.corner_radius, 4.0);
        // soft_option fields pass through as Option
        assert_eq!(resolved.active_background, Some(Rgba::rgb(180, 180, 180)));
        assert_eq!(resolved.disabled_background, Some(Rgba::rgb(220, 220, 220)));
    }

    #[test]
    fn button_validate_widget_records_missing_fields() {
        let button = ButtonTheme::default(); // all None
        let mut missing = Vec::new();
        let _ = ResolvedButtonTheme::validate_widget(&button, "button", 96.0, &mut missing);
        // option fields should be recorded as missing
        assert!(missing.contains(&"button.background_color".to_string()));
        assert!(missing.contains(&"button.min_width".to_string()));
        // font (optional_nested) should be recorded
        assert!(missing.contains(&"button.font".to_string()));
        // border (optional_nested) should be recorded
        assert!(missing.contains(&"button.border".to_string()));
        // soft_option fields should NOT be recorded as missing
        assert!(!missing.iter().any(|m| m.contains("active_background")));
        assert!(!missing.iter().any(|m| m.contains("disabled_background")));
    }

    // === LayoutTheme tests ===

    #[test]
    fn layout_theme_default_is_empty() {
        assert!(LayoutTheme::default().is_empty());
    }

    #[test]
    fn layout_theme_not_empty_when_widget_gap_set() {
        let l = LayoutTheme {
            widget_gap: Some(8.0),
            ..Default::default()
        };
        assert!(!l.is_empty());
    }

    #[test]
    fn layout_theme_field_names() {
        assert_eq!(LayoutTheme::FIELD_NAMES.len(), 4);
        assert!(LayoutTheme::FIELD_NAMES.contains(&"widget_gap_px"));
        assert!(LayoutTheme::FIELD_NAMES.contains(&"container_margin_px"));
        assert!(LayoutTheme::FIELD_NAMES.contains(&"window_margin_px"));
        assert!(LayoutTheme::FIELD_NAMES.contains(&"section_gap_px"));
    }

    #[test]
    fn layout_theme_toml_round_trip() {
        let l = LayoutTheme {
            widget_gap: Some(8.0),
            container_margin: Some(12.0),
            window_margin: Some(16.0),
            section_gap: Some(24.0),
        };
        let toml_str = toml::to_string(&l).unwrap();
        let l2: LayoutTheme = toml::from_str(&toml_str).unwrap();
        assert_eq!(l, l2);
    }

    #[test]
    fn layout_theme_merge() {
        let mut base = LayoutTheme {
            widget_gap: Some(6.0),
            container_margin: Some(10.0),
            ..Default::default()
        };
        let overlay = LayoutTheme {
            widget_gap: Some(8.0),
            section_gap: Some(24.0),
            ..Default::default()
        };
        base.merge(&overlay);
        // overlay widget_gap replaces base
        assert_eq!(base.widget_gap, Some(8.0));
        // base container_margin preserved
        assert_eq!(base.container_margin, Some(10.0));
        // overlay section_gap added
        assert_eq!(base.section_gap, Some(24.0));
        // window_margin stays None
        assert!(base.window_margin.is_none());
    }
}