rpdfium-doc 7676.6.2

// Derived from PDFium's cpdf_formfield.cpp
// Original: Copyright 2014 The PDFium Authors
// Licensed under BSD-3-Clause / Apache-2.0
// See pdfium-upstream/LICENSE for the original license.

//! Form field types — Text, Button, Choice, Signature field parsing.
//!
//! Parses AcroForm field dictionaries (ISO 32000-2 section 12.7) into
//! typed structs for read-only inspection.

use std::collections::HashMap;

use rpdfium_core::{Name, PdfSource};
use rpdfium_parser::{Object, ObjectId, ObjectStore};

use crate::aaction::{AdditionalActions, parse_additional_actions};
use crate::error::DocError;
use crate::form_control::{FormControl, HighlightingMode, TextPosition};
use crate::icon_fit::{IconFit, parse_icon_fit};

/// The type of an interactive form field.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum FormFieldType {
    /// A text input field (`/FT Tx`).
    Text,
    /// A button field — checkbox, radio, or push button (`/FT Btn`).
    Button,
    /// A choice field — combo box or list box (`/FT Ch`).
    Choice,
    /// A digital signature field (`/FT Sig`).
    Signature,
}

/// A single option in a choice field.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ChoiceOption {
    /// The export value sent when the form is submitted.
    pub export_value: String,
    /// The display value shown to the user.
    pub display_value: String,
}

/// A typed value that can be set on a form field.
#[derive(Debug, Clone, PartialEq)]
pub enum FieldValue {
    /// A text string value (for Text fields).
    String(String),
    /// A boolean value (for Button/checkbox fields — true = checked).
    Bool(bool),
    /// A single choice index (for Choice fields — combo box / list box).
    Choice(usize),
    /// Multiple selected indices (for multi-select Choice fields).
    Indices(Vec<usize>),
}

/// Form field flag bits (`/Ff`).
///
/// ISO 32000-1:2008, Tables 8.70 (common), 8.75 (button), 8.77 (text), 8.79
/// (choice). Multiple groups share bit positions because the meaning depends
/// on the field type (e.g. bit 23 is both DoNotSpellCheck for text and
/// DoNotSpellCheck for choice).
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct FormFieldFlags(u32);

impl FormFieldFlags {
    /// Create flags from a raw integer value.
    pub fn from_bits(bits: u32) -> Self {
        Self(bits)
    }

    /// Return the raw bit value.
    pub fn bits(self) -> u32 {
        self.0
    }

    // --- Common to all field types (Table 8.70) ---

    /// Bit 1: Field is read-only.
    pub fn is_read_only(self) -> bool {
        self.0 & (1 << 0) != 0
    }

    /// Bit 2: Field must have a value before the document is submitted.
    pub fn is_required(self) -> bool {
        self.0 & (1 << 1) != 0
    }

    /// Bit 3: Field value must not be exported.
    pub fn is_no_export(self) -> bool {
        self.0 & (1 << 2) != 0
    }

    // --- Button field flags (Table 8.75) ---

    /// Bit 15: Radio button — at least one must be selected at all times.
    pub fn is_no_toggle_to_off(self) -> bool {
        self.0 & (1 << 14) != 0
    }

    /// Bit 16: Field is a set of radio buttons (not a checkbox).
    pub fn is_radio(self) -> bool {
        self.0 & (1 << 15) != 0
    }

    /// Bit 17: Field is a pushbutton (not a checkbox or radio button).
    pub fn is_push_button(self) -> bool {
        self.0 & (1 << 16) != 0
    }

    /// Bit 26: Radio buttons with the same value turn on/off together.
    /// (Button fields. Note: same bit as `is_rich_text` for text fields.)
    pub fn is_radios_in_unison(self) -> bool {
        self.0 & (1 << 25) != 0
    }

    // --- Text field flags (Table 8.77) ---

    /// Bit 13: Text field allows multiple lines.
    pub fn is_multiline(self) -> bool {
        self.0 & (1 << 12) != 0
    }

    /// Bit 14: Text field is a password (display as bullets).
    pub fn is_password(self) -> bool {
        self.0 & (1 << 13) != 0
    }

    /// Bit 21: Text field value is a file-select path.
    pub fn is_file_select(self) -> bool {
        self.0 & (1 << 20) != 0
    }

    /// Bit 23: Text/choice field should not be spell-checked.
    pub fn is_do_not_spell_check(self) -> bool {
        self.0 & (1 << 22) != 0
    }

    /// Bit 24: Text field should not scroll horizontally.
    pub fn is_do_not_scroll(self) -> bool {
        self.0 & (1 << 23) != 0
    }

    /// Bit 25: Text field uses comb formatting (requires `/MaxLen`).
    pub fn is_comb(self) -> bool {
        self.0 & (1 << 24) != 0
    }

    /// Bit 26: Text field contains rich text (RV entry).
    /// (Text fields. Note: same bit as `is_radios_in_unison` for button fields.)
    pub fn is_rich_text(self) -> bool {
        self.0 & (1 << 25) != 0
    }

    // --- Choice field flags (Table 8.79) ---

    /// Bit 18: Choice field is a combo box (editable dropdown).
    pub fn is_combo(self) -> bool {
        self.0 & (1 << 17) != 0
    }

    /// Bit 19: Combo box choice field is editable by the user.
    pub fn is_combo_editable(self) -> bool {
        self.0 & (1 << 18) != 0
    }

    /// Bit 20: List box items should be sorted alphabetically.
    pub fn is_sort(self) -> bool {
        self.0 & (1 << 19) != 0
    }

    /// Bit 22: List box allows multiple simultaneous selections.
    pub fn is_multi_select(self) -> bool {
        self.0 & (1 << 21) != 0
    }

    /// Bit 27: Choice field commits the value immediately on selection change.
    pub fn is_commit_on_sel_change(self) -> bool {
        self.0 & (1 << 26) != 0
    }

    /// Set or clear the read-only flag (bit 1).
    pub fn set_read_only(&mut self, v: bool) {
        if v {
            self.0 |= 1 << 0;
        } else {
            self.0 &= !(1 << 0);
        }
    }

    /// Set or clear the required flag (bit 2).
    pub fn set_required(&mut self, v: bool) {
        if v {
            self.0 |= 1 << 1;
        } else {
            self.0 &= !(1 << 1);
        }
    }

    /// Set or clear the no-export flag (bit 3).
    pub fn set_no_export(&mut self, v: bool) {
        if v {
            self.0 |= 1 << 2;
        } else {
            self.0 &= !(1 << 2);
        }
    }
}

/// A parsed interactive form field.
#[derive(Debug, Clone)]
pub struct FormField {
    /// Fully qualified field name (parent.child format).
    pub name: String,
    /// Field type.
    pub field_type: FormFieldType,
    /// Current value (`/V`).
    pub value: Option<String>,
    /// Default value (`/DV`).
    pub default_value: Option<String>,
    /// Field flags (`/Ff`).
    pub flags: FormFieldFlags,
    /// Tooltip (`/TU`).
    pub tooltip: Option<String>,
    /// Alternate field name for display (`/TU`, same as tooltip — upstream uses this).
    pub alternate_name: Option<String>,
    /// Mapping name for export (`/TM`).
    pub mapping_name: Option<String>,
    /// For text fields: maximum length (`/MaxLen`).
    pub max_len: Option<u32>,
    /// For choice fields: options (`/Opt`).
    pub options: Vec<ChoiceOption>,
    /// For button fields: checked/appearance state (`/AS`).
    pub appearance_state: Option<String>,
    /// Child fields (for hierarchical fields).
    pub children: Vec<FormField>,
    /// Widget controls associated with this field.
    pub controls: Vec<FormControl>,
    /// Whether the field value has been modified since parsing.
    pub dirty: bool,
    /// Selected indices for choice fields (`/I`).
    pub selected_indices: Vec<usize>,
    /// Additional actions for the field (`/AA`).
    pub additional_actions: Option<AdditionalActions>,
}

impl FormField {
    /// Parse a form field from a PDF dictionary.
    ///
    /// `parent_ft` is the inherited `/FT` value from the parent field (if any).
    /// `parent_name` is the accumulated fully-qualified name prefix.
    pub(crate) fn from_dict<S: PdfSource>(
        dict: &HashMap<Name, Object>,
        store: &ObjectStore<S>,
        parent_ft: Option<&str>,
        parent_name: &str,
    ) -> Option<Self> {
        // /T — partial field name
        let partial_name = dict
            .get(&Name::t())
            .and_then(|o| store.deep_resolve(o).ok())
            .and_then(|o| o.as_string().map(|s| s.to_string_lossy()));

        // Build fully qualified name.
        //
        // Prefer the full name resolved by walking the /Parent chain in the object
        // store (mirrors PDFium's GetFullNameForDict). Fall back to the accumulated
        // parent_name passed down by the in-memory tree walker.
        let name = if let Some(store_name) = resolve_full_field_name_from_store(dict, store) {
            // The store-based walk already produced a dotted full name.
            store_name
        } else {
            // No /Parent reference in the store: use the tree-walker's accumulated name.
            match (&partial_name, parent_name.is_empty()) {
                (Some(pn), true) => pn.clone(),
                (Some(pn), false) => format!("{parent_name}.{pn}"),
                (None, _) => parent_name.to_string(),
            }
        };

        // /FT — field type, inheritable through the /Parent chain (ISO 32000-2 §12.7.3).
        //
        // First check the dict directly; if absent, walk the /Parent chain via the
        // object store (mirrors PDFium's GetFieldAttrRecursive). Finally fall back to
        // the parent_ft propagated by the in-memory tree walker.
        let ft_obj = get_field_attr_inherited(dict, &Name::ft(), store);
        let ft_str = ft_obj
            .as_ref()
            .and_then(|o| store.deep_resolve(o).ok())
            .and_then(|o| o.as_name().map(|n| n.as_str().into_owned()));
        let ft_ref = ft_str.as_deref().or(parent_ft);

        let field_type = match ft_ref {
            Some("Tx") => FormFieldType::Text,
            Some("Btn") => FormFieldType::Button,
            Some("Ch") => FormFieldType::Choice,
            Some("Sig") => FormFieldType::Signature,
            _ => {
                // No field type and no parent type — skip (non-terminal node
                // handled by tree walker which recurses into /Kids)
                return None;
            }
        };

        // /V — value (string or name), inheritable through /Parent chain.
        let value = extract_inherited_string_or_name(dict, &Name::v(), store);

        // /DV — default value, inheritable through /Parent chain.
        let default_value = extract_inherited_string_or_name(dict, &Name::dv(), store);

        // /Ff — field flags, inheritable through /Parent chain.
        let ff_obj = get_field_attr_inherited(dict, &Name::ff(), store);
        let flags = FormFieldFlags::from_bits(
            ff_obj
                .as_ref()
                .and_then(|o| store.deep_resolve(o).ok())
                .and_then(|o| o.as_i64())
                .unwrap_or(0) as u32,
        );

        // /TU — tooltip / alternate name
        let tooltip = dict
            .get(&Name::tu())
            .and_then(|o| store.deep_resolve(o).ok())
            .and_then(|o| o.as_string().map(|s| s.to_string_lossy()));

        // Alternate name is same as tooltip (upstream GetAlternateName reads /TU)
        let alternate_name = tooltip.clone();

        // /TM — mapping name for export
        let mapping_name = dict
            .get(&Name::tm())
            .and_then(|o| store.deep_resolve(o).ok())
            .and_then(|o| o.as_string().map(|s| s.to_string_lossy()));

        // /MaxLen
        let max_len = dict
            .get(&Name::max_len())
            .and_then(|o| store.deep_resolve(o).ok())
            .and_then(|o| o.as_i64())
            .map(|v| v as u32);

        // /Opt — choice field options
        let options = parse_options(dict, store);

        // /AS — appearance state
        let appearance_state = dict
            .get(&Name::as_name())
            .and_then(|o| store.deep_resolve(o).ok())
            .and_then(|o| o.as_name().map(|n| n.as_str().into_owned()));

        // /I — selected indices for choice fields
        let selected_indices = parse_selected_indices(dict, store);

        // Parse widget controls from /Kids that have /Subtype /Widget but no /FT
        let controls = parse_widget_controls(dict, store, &name);

        // /AA — additional actions
        let additional_actions = dict
            .get(&Name::aa())
            .and_then(|o| parse_additional_actions(o, store).ok());

        Some(FormField {
            name,
            field_type,
            value,
            default_value,
            flags,
            tooltip,
            alternate_name,
            mapping_name,
            max_len,
            options,
            appearance_state,
            children: Vec::new(),
            controls,
            dirty: false,
            selected_indices,
            additional_actions,
        })
    }

    /// Set the field's value with type and constraint validation.
    ///
    /// Returns an error if:
    /// - The value type does not match the field type (e.g. `Bool` on a `Text` field).
    /// - A text value exceeds `/MaxLen`.
    /// - A choice index is out of range.
    pub fn set_value(&mut self, value: FieldValue) -> Result<(), DocError> {
        match (&self.field_type, &value) {
            (FormFieldType::Text, FieldValue::String(s)) => {
                if let Some(max) = self.max_len {
                    if s.len() > max as usize {
                        return Err(DocError::ValueTooLong { len: s.len(), max });
                    }
                }
                self.value = Some(s.clone());
            }
            (FormFieldType::Button, FieldValue::Bool(checked)) => {
                self.appearance_state = Some(if *checked {
                    "Yes".to_string()
                } else {
                    "Off".to_string()
                });
                self.value = Some(self.appearance_state.as_ref().unwrap().clone());
            }
            (FormFieldType::Choice, FieldValue::Choice(idx)) => {
                if *idx >= self.options.len() {
                    return Err(DocError::InvalidChoiceIndex {
                        index: *idx,
                        count: self.options.len(),
                    });
                }
                self.value = Some(self.options[*idx].export_value.clone());
            }
            (FormFieldType::Choice, FieldValue::String(s)) => {
                // Allow setting a choice field by raw string value (e.g. from FDF import)
                self.value = Some(s.clone());
            }
            (FormFieldType::Choice, FieldValue::Indices(indices)) => {
                for &idx in indices {
                    if idx >= self.options.len() {
                        return Err(DocError::InvalidChoiceIndex {
                            index: idx,
                            count: self.options.len(),
                        });
                    }
                }
                // Store as comma-separated export values
                let vals: Vec<&str> = indices
                    .iter()
                    .map(|&i| self.options[i].export_value.as_str())
                    .collect();
                self.value = Some(vals.join(","));
            }
            (field_type, val) => {
                let expected = match field_type {
                    FormFieldType::Text => "String",
                    FormFieldType::Button => "Bool",
                    FormFieldType::Choice => "Choice or Indices",
                    FormFieldType::Signature => "Signature (read-only)",
                };
                let got = match val {
                    FieldValue::String(_) => "String",
                    FieldValue::Bool(_) => "Bool",
                    FieldValue::Choice(_) => "Choice",
                    FieldValue::Indices(_) => "Indices",
                };
                return Err(DocError::TypeMismatch {
                    expected: expected.to_string(),
                    got: got.to_string(),
                });
            }
        }
        self.dirty = true;
        Ok(())
    }

    /// Returns the widget controls associated with this field.
    pub fn controls(&self) -> &[FormControl] {
        &self.controls
    }

    /// Returns `true` if the field has been modified and its appearance stream
    /// needs regeneration.
    pub fn needs_appearance(&self) -> bool {
        self.dirty
    }

    /// Reset the field to its default value (`/DV`), or clear if none.
    pub fn reset_to_default(&mut self) {
        self.value = self.default_value.clone();
        self.dirty = true;
    }

    // --- Selection APIs for Choice fields ---

    /// Returns the number of currently selected items.
    ///
    /// Corresponds to upstream `CPDF_FormField::CountSelectedItems()`.
    pub fn selected_item_count(&self) -> usize {
        self.selected_indices.len()
    }

    /// Upstream-aligned alias for [`selected_item_count()`](Self::selected_item_count).
    ///
    /// Corresponds to upstream `CPDF_FormField::CountSelectedItems()`.
    #[inline]
    pub fn count_selected_items(&self) -> usize {
        self.selected_item_count()
    }

    /// Returns `true` if the option at the given index is selected.
    pub fn is_item_selected(&self, index: usize) -> bool {
        self.selected_indices.contains(&index)
    }

    /// Returns the selected option index at position `sel_index` within the selection list.
    ///
    /// Corresponds to upstream `CPDF_FormField::GetSelectedIndex()`.
    pub fn selected_index(&self, sel_index: usize) -> Option<usize> {
        self.selected_indices.get(sel_index).copied()
    }

    /// Upstream-aligned alias for [`selected_index()`](Self::selected_index).
    ///
    /// Corresponds to upstream `CPDF_FormField::GetSelectedIndex()`.
    #[inline]
    pub fn get_selected_index(&self, sel_index: usize) -> Option<usize> {
        self.selected_index(sel_index)
    }

    /// Clear the selection for a choice field.
    ///
    /// Clears the in-memory selected indices list. To persist the change to a
    /// PDF file, use `EditableForm::clear_field_selection` in rpdfium-edit.
    pub fn clear_selection(&mut self) -> Result<(), DocError> {
        self.selected_indices.clear();
        Ok(())
    }

    /// Set or clear the read-only flag for this field.
    ///
    /// Updates the in-memory flags. To persist the change to a PDF file,
    /// use `EditableForm::set_field_read_only` in rpdfium-edit.
    pub fn set_read_only(&mut self, v: bool) {
        self.flags.set_read_only(v);
    }

    /// Set or clear the required flag for this field.
    ///
    /// Updates the in-memory flags. To persist the change to a PDF file,
    /// use `EditableForm::set_field_required` in rpdfium-edit.
    pub fn set_required(&mut self, v: bool) {
        self.flags.set_required(v);
    }

    /// Set or clear the no-export flag for this field.
    ///
    /// Updates the in-memory flags. To persist the change to a PDF file,
    /// use `EditableForm::set_field_no_export` in rpdfium-edit.
    pub fn set_no_export(&mut self, v: bool) {
        self.flags.set_no_export(v);
    }

    /// Returns the additional actions for this field, if any.
    pub fn additional_actions(&self) -> Option<&AdditionalActions> {
        self.additional_actions.as_ref()
    }

    /// ADR-019 alias for [`additional_actions()`](Self::additional_actions).
    ///
    /// Corresponds to `CPDF_FormField::GetAdditionalAction()` in PDFium.
    #[inline]
    pub fn get_additional_actions(&self) -> Option<&AdditionalActions> {
        self.additional_actions()
    }

    // --- Choice option accessor methods ---

    /// Returns the number of options for choice fields.
    ///
    /// Corresponds to upstream `CPDF_FormField::CountOptions()`.
    pub fn option_count(&self) -> usize {
        self.options.len()
    }

    /// Upstream-aligned alias for [`option_count()`](Self::option_count).
    ///
    /// Corresponds to upstream `CPDF_FormField::CountOptions()`.
    #[inline]
    pub fn count_options(&self) -> usize {
        self.option_count()
    }

    /// Returns the display label of the option at `index`, or `None` if out of bounds.
    ///
    /// Corresponds to upstream `CPDF_FormField::GetOptionLabel(index)`.
    pub fn option_label(&self, index: usize) -> Option<&str> {
        self.options.get(index).map(|o| o.display_value.as_str())
    }

    /// Upstream-aligned alias for [`option_label()`](Self::option_label).
    ///
    /// Corresponds to upstream `CPDF_FormField::GetOptionLabel(index)`.
    #[inline]
    pub fn get_option_label(&self, index: usize) -> Option<&str> {
        self.option_label(index)
    }

    /// Returns the export value of the option at `index`, or `None` if out of bounds.
    ///
    /// Corresponds to upstream `CPDF_FormField::GetOptionValue(index)`.
    pub fn option_value(&self, index: usize) -> Option<&str> {
        self.options.get(index).map(|o| o.export_value.as_str())
    }

    /// Upstream-aligned alias for [`option_value()`](Self::option_value).
    ///
    /// Corresponds to upstream `CPDF_FormField::GetOptionValue(index)`.
    #[inline]
    pub fn get_option_value(&self, index: usize) -> Option<&str> {
        self.option_value(index)
    }

    // --- Control accessor methods ---

    /// Returns the number of widget controls for this field.
    ///
    /// Corresponds to upstream `CPDF_FormField::CountControls()`.
    pub fn control_count(&self) -> usize {
        self.controls.len()
    }

    /// Upstream-aligned alias for [`control_count()`](Self::control_count).
    ///
    /// Corresponds to upstream `CPDF_FormField::CountControls()`.
    #[inline]
    pub fn count_controls(&self) -> usize {
        self.control_count()
    }

    /// Returns the control at `index`, or `None` if out of bounds.
    ///
    /// Corresponds to upstream `CPDF_FormField::GetControl(index)`.
    pub fn control_at(&self, index: usize) -> Option<&FormControl> {
        self.controls.get(index)
    }

    /// Upstream-aligned alias for [`control_at()`](Self::control_at).
    ///
    /// Corresponds to upstream `CPDF_FormField::GetControl(index)`.
    #[inline]
    pub fn get_control(&self, index: usize) -> Option<&FormControl> {
        self.control_at(index)
    }
}

/// Maximum depth for parent chain traversal (mirrors PDFium's kGetFieldMaxRecursion = 32).
const MAX_FIELD_ATTR_DEPTH: usize = 32;

/// Walk the parent chain stored in the object store to find an inherited field attribute.
///
/// Equivalent to PDFium's `GetFieldAttrRecursive()` / `GetFieldAttrForDict()`.
/// Looks up `name` first in `start_dict`, then walks `/Parent` references up to
/// `MAX_FIELD_ATTR_DEPTH` levels. Returns a clone of the first found value, or `None`.
///
/// Cycle detection: tracks the last visited `ObjectId`; a parent that references
/// itself terminates the walk.
fn get_field_attr_inherited<S: PdfSource>(
    start_dict: &HashMap<Name, Object>,
    name: &Name,
    store: &ObjectStore<S>,
) -> Option<Object> {
    // Try the starting dict first.
    if let Some(val) = start_dict.get(name) {
        return Some(val.clone());
    }

    // Walk parent chain iteratively.
    let mut current_id: Option<ObjectId> = None;
    let mut parent_ref = start_dict
        .get(&Name::parent())
        .and_then(|v| v.as_reference());

    for _ in 0..MAX_FIELD_ATTR_DEPTH {
        let parent_id = parent_ref?;

        // Cycle detection: stop if we revisit the same object.
        if current_id == Some(parent_id) {
            break;
        }
        current_id = Some(parent_id);

        let parent_obj = store.resolve(parent_id).ok()?;
        let parent_dict = parent_obj.as_dict()?;

        if let Some(val) = parent_dict.get(name) {
            return Some(val.clone());
        }

        parent_ref = parent_dict
            .get(&Name::parent())
            .and_then(|v| v.as_reference());
    }

    None
}

/// Build the fully qualified field name by collecting `/T` partial names from
/// the parent chain stored in the object store.
///
/// Equivalent to PDFium's `CPDF_FormField::GetFullNameForDict()`.
///
/// This supplements the `parent_name` argument already accumulated by the
/// tree walker: if the field dict has a `/Parent` reference pointing into the
/// object store, we walk that chain to collect any additional `/T` components
/// that the in-memory stack traversal may not have visited.
fn resolve_full_field_name_from_store<S: PdfSource>(
    start_dict: &HashMap<Name, Object>,
    store: &ObjectStore<S>,
) -> Option<String> {
    // Only bother if the dict actually has a /Parent reference.
    start_dict.get(&Name::parent())?.as_reference()?;

    let mut parts: Vec<String> = Vec::new();

    // Collect /T at the current level.
    if let Some(t_obj) = start_dict.get(&Name::t()) {
        if let Ok(resolved) = store.deep_resolve(t_obj) {
            if let Some(s) = resolved.as_string() {
                parts.push(s.to_string_lossy());
            }
        }
    }

    // Walk parent chain collecting /T entries.
    let mut parent_ref = start_dict
        .get(&Name::parent())
        .and_then(|v| v.as_reference());
    let mut current_id: Option<ObjectId> = None;

    for _ in 0..MAX_FIELD_ATTR_DEPTH {
        let pid = match parent_ref {
            Some(id) => id,
            None => break,
        };
        if current_id == Some(pid) {
            break;
        }
        current_id = Some(pid);

        let pobj = match store.resolve(pid).ok() {
            Some(o) => o,
            None => break,
        };
        let pdict = match pobj.as_dict() {
            Some(d) => d,
            None => break,
        };

        if let Some(t_obj) = pdict.get(&Name::t()) {
            if let Ok(resolved) = store.deep_resolve(t_obj) {
                if let Some(s) = resolved.as_string() {
                    parts.push(s.to_string_lossy());
                }
            }
        }

        parent_ref = pdict.get(&Name::parent()).and_then(|v| v.as_reference());
    }

    if parts.is_empty() {
        return None;
    }

    parts.reverse();
    Some(parts.join("."))
}

/// Extract a string or name value from a dictionary key, walking the `/Parent` chain
/// if the key is absent from `dict`.
///
/// Equivalent to calling `GetFieldAttrForDict` then interpreting the result as text.
fn extract_inherited_string_or_name<S: PdfSource>(
    dict: &HashMap<Name, Object>,
    key: &Name,
    store: &ObjectStore<S>,
) -> Option<String> {
    let obj = get_field_attr_inherited(dict, key, store)?;
    let resolved = store.deep_resolve(&obj).ok()?;
    if let Some(s) = resolved.as_string() {
        Some(s.to_string_lossy())
    } else {
        resolved.as_name().map(|n| n.as_str().into_owned())
    }
}

/// Parse `/Opt` array into `ChoiceOption` items.
///
/// Each element can be either:
/// - A string (export_value == display_value)
/// - A 2-element array [export_value, display_value]
fn parse_options<S: PdfSource>(
    dict: &HashMap<Name, Object>,
    store: &ObjectStore<S>,
) -> Vec<ChoiceOption> {
    let opt_obj = match dict.get(&Name::opt()) {
        Some(o) => o,
        None => return Vec::new(),
    };
    let resolved = match store.deep_resolve(opt_obj).ok() {
        Some(o) => o,
        None => return Vec::new(),
    };
    let arr = match resolved.as_array() {
        Some(a) => a,
        None => return Vec::new(),
    };

    let mut options = Vec::with_capacity(arr.len());
    for item in arr {
        let resolved_item = match store.deep_resolve(item).ok() {
            Some(o) => o,
            None => continue,
        };

        if let Some(sub_arr) = resolved_item.as_array() {
            // [export_value, display_value]
            if sub_arr.len() >= 2 {
                let export = store
                    .deep_resolve(&sub_arr[0])
                    .ok()
                    .and_then(|o| o.as_string().map(|s| s.to_string_lossy()))
                    .unwrap_or_default();
                let display = store
                    .deep_resolve(&sub_arr[1])
                    .ok()
                    .and_then(|o| o.as_string().map(|s| s.to_string_lossy()))
                    .unwrap_or_default();
                options.push(ChoiceOption {
                    export_value: export,
                    display_value: display,
                });
            }
        } else if let Some(s) = resolved_item.as_string() {
            let val = s.to_string_lossy();
            options.push(ChoiceOption {
                export_value: val.clone(),
                display_value: val,
            });
        }
    }
    options
}

/// Parse `/I` (selected indices) array from a choice field dictionary.
fn parse_selected_indices<S: PdfSource>(
    dict: &HashMap<Name, Object>,
    store: &ObjectStore<S>,
) -> Vec<usize> {
    let i_obj = match dict.get(&Name::i()) {
        Some(o) => o,
        None => return Vec::new(),
    };
    let resolved = match store.deep_resolve(i_obj).ok() {
        Some(o) => o,
        None => return Vec::new(),
    };
    let arr = match resolved.as_array() {
        Some(a) => a,
        None => return Vec::new(),
    };

    arr.iter()
        .filter_map(|item| item.as_i64().map(|n| n as usize))
        .collect()
}

/// Parse widget controls from /Kids that are widget annotations (have /Subtype /Widget
/// but no /FT of their own).
fn parse_widget_controls<S: PdfSource>(
    dict: &HashMap<Name, Object>,
    store: &ObjectStore<S>,
    field_name: &str,
) -> Vec<FormControl> {
    let kids_obj = match dict.get(&Name::kids()) {
        Some(o) => o,
        None => return Vec::new(),
    };
    let kids_resolved = match store.deep_resolve(kids_obj).ok() {
        Some(o) => o,
        None => return Vec::new(),
    };
    let kids_arr = match kids_resolved.as_array() {
        Some(a) => a,
        None => return Vec::new(),
    };

    let mut controls = Vec::new();
    for kid in kids_arr {
        let resolved = match store.deep_resolve(kid).ok() {
            Some(o) => o,
            None => continue,
        };
        let kid_dict = match resolved.as_dict() {
            Some(d) => d,
            None => continue,
        };

        // Check if it's a Widget (has /Subtype /Widget) without its own /FT
        let is_widget = kid_dict
            .get(&Name::subtype())
            .and_then(|o| store.deep_resolve(o).ok())
            .and_then(|o| o.as_name().map(|n| n.as_str().into_owned()))
            .is_some_and(|s| s == "Widget");
        let has_ft = kid_dict.get(&Name::ft()).is_some();

        if is_widget && !has_ft {
            let rect = parse_rect(kid_dict, store);
            let appearance_state = kid_dict
                .get(&Name::as_name())
                .and_then(|o| store.deep_resolve(o).ok())
                .and_then(|o| o.as_name().map(|n| n.as_str().into_owned()));

            // /H — highlighting mode
            let highlighting_mode = kid_dict
                .get(&Name::h())
                .and_then(|o| store.deep_resolve(o).ok())
                .and_then(|o| {
                    o.as_name()
                        .map(|n| HighlightingMode::from_name(&n.as_str()))
                })
                .unwrap_or_default();

            // /DA — default appearance
            let default_appearance = kid_dict
                .get(&Name::da())
                .and_then(|o| store.deep_resolve(o).ok())
                .and_then(|o| o.as_string().map(|s| s.to_string_lossy()));

            // Parse /MK fields
            let mk = parse_mk_fields(kid_dict, store);

            controls.push(FormControl {
                field_name: field_name.to_string(),
                rect,
                appearance_state,
                page_index: None,
                highlighting_mode,
                rotation: mk.rotation,
                border_color: mk.border_color,
                background_color: mk.background_color,
                caption: mk.caption,
                rollover_caption: mk.rollover_caption,
                alt_caption: mk.alt_caption,
                default_appearance,
                normal_icon: mk.normal_icon,
                rollover_icon: mk.rollover_icon,
                down_icon: mk.down_icon,
                icon_fit: mk.icon_fit,
                text_position: mk.text_position,
            });
        }
    }
    controls
}

/// Parsed fields from an MK (appearance characteristics) dictionary.
#[derive(Default)]
struct MkFields {
    rotation: u32,
    border_color: Option<Vec<f32>>,
    background_color: Option<Vec<f32>>,
    caption: Option<String>,
    rollover_caption: Option<String>,
    alt_caption: Option<String>,
    normal_icon: Option<ObjectId>,
    rollover_icon: Option<ObjectId>,
    down_icon: Option<ObjectId>,
    icon_fit: Option<IconFit>,
    text_position: TextPosition,
}

/// Parse MK dictionary fields from a widget annotation dictionary.
fn parse_mk_fields<S: PdfSource>(dict: &HashMap<Name, Object>, store: &ObjectStore<S>) -> MkFields {
    let mk_obj = match dict.get(&Name::mk()) {
        Some(o) => o,
        None => return MkFields::default(),
    };
    let resolved = match store.deep_resolve(mk_obj).ok() {
        Some(o) => o,
        None => return MkFields::default(),
    };
    let mk_dict = match resolved.as_dict() {
        Some(d) => d,
        None => return MkFields::default(),
    };

    let rotation = mk_dict
        .get(&Name::r())
        .and_then(|o| o.as_i64())
        .unwrap_or(0) as u32;

    let border_color = parse_color_array(mk_dict, &Name::bc(), store);
    let background_color = parse_color_array(mk_dict, &Name::bg_color(), store);

    let caption = mk_dict
        .get(&Name::ca_display())
        .and_then(|o| store.deep_resolve(o).ok())
        .and_then(|o| o.as_string().map(|s| s.to_string_lossy()));

    let rollover_caption = mk_dict
        .get(&Name::rc())
        .and_then(|o| store.deep_resolve(o).ok())
        .and_then(|o| o.as_string().map(|s| s.to_string_lossy()));

    let alt_caption = mk_dict
        .get(&Name::ac())
        .and_then(|o| store.deep_resolve(o).ok())
        .and_then(|o| o.as_string().map(|s| s.to_string_lossy()));

    let normal_icon = mk_dict.get(&Name::i()).and_then(|o| o.as_reference());
    let rollover_icon = mk_dict.get(&Name::ri()).and_then(|o| o.as_reference());
    let down_icon = mk_dict.get(&Name::ix()).and_then(|o| o.as_reference());

    let text_position = mk_dict
        .get(&Name::tp())
        .and_then(|o| o.as_i64())
        .map(|v| TextPosition::from_value(v as u32))
        .unwrap_or_default();

    let icon_fit = parse_icon_fit(mk_dict, store);

    MkFields {
        rotation,
        border_color,
        background_color,
        caption,
        rollover_caption,
        alt_caption,
        normal_icon,
        rollover_icon,
        down_icon,
        icon_fit,
        text_position,
    }
}

/// Parse a color array from a dictionary (e.g., `/BC`, `/BG` in MK dict).
fn parse_color_array<S: PdfSource>(
    dict: &HashMap<Name, Object>,
    key: &Name,
    store: &ObjectStore<S>,
) -> Option<Vec<f32>> {
    let obj = dict.get(key)?;
    let resolved = store.deep_resolve(obj).ok()?;
    let arr = resolved.as_array()?;
    let colors: Vec<f32> = arr
        .iter()
        .filter_map(|o| o.as_f64().map(|v| v as f32))
        .collect();
    if colors.is_empty() {
        None
    } else {
        Some(colors)
    }
}

/// Parse a `/Rect` array from a dictionary.
fn parse_rect<S: PdfSource>(
    dict: &HashMap<Name, Object>,
    store: &ObjectStore<S>,
) -> rpdfium_core::Rect {
    let default = rpdfium_core::Rect {
        left: 0.0,
        bottom: 0.0,
        right: 0.0,
        top: 0.0,
    };
    let rect_obj = match dict.get(&Name::rect()) {
        Some(o) => o,
        None => return default,
    };
    let resolved = match store.deep_resolve(rect_obj).ok() {
        Some(o) => o,
        None => return default,
    };
    let arr = match resolved.as_array() {
        Some(a) if a.len() >= 4 => a,
        _ => return default,
    };

    let get_f64 = |idx: usize| -> f64 { arr[idx].as_f64().unwrap_or(0.0) };

    rpdfium_core::Rect {
        left: get_f64(0),
        bottom: get_f64(1),
        right: get_f64(2),
        top: get_f64(3),
    }
}

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

    fn build_store() -> ObjectStore<Vec<u8>> {
        let pdf = build_minimal_pdf();
        ObjectStore::open(pdf, rpdfium_core::ParsingMode::Lenient).unwrap()
    }

    fn build_minimal_pdf() -> Vec<u8> {
        let mut pdf = Vec::new();
        pdf.extend_from_slice(b"%PDF-1.4\n");
        let obj1_offset = pdf.len();
        pdf.extend_from_slice(b"1 0 obj\n<< /Type /Catalog /Pages 2 0 R >>\nendobj\n");
        let obj2_offset = pdf.len();
        pdf.extend_from_slice(b"2 0 obj\n<< /Type /Pages /Kids [] /Count 0 >>\nendobj\n");
        let xref_offset = pdf.len();
        pdf.extend_from_slice(b"xref\n0 3\n");
        pdf.extend_from_slice(b"0000000000 65535 f \r\n");
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj1_offset).as_bytes());
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj2_offset).as_bytes());
        pdf.extend_from_slice(b"trailer\n<< /Size 3 /Root 1 0 R >>\n");
        pdf.extend_from_slice(format!("startxref\n{}\n%%EOF", xref_offset).as_bytes());
        pdf
    }

    fn str_obj(s: &str) -> Object {
        Object::String(PdfString::from_bytes(s.as_bytes().to_vec()))
    }

    #[test]
    fn test_parse_text_field() {
        let store = build_store();
        let mut dict = HashMap::new();
        dict.insert(Name::ft(), Object::Name(Name::from("Tx")));
        dict.insert(Name::t(), str_obj("username"));
        dict.insert(Name::v(), str_obj("john"));
        dict.insert(Name::max_len(), Object::Integer(50));
        dict.insert(Name::tu(), str_obj("Enter your name"));

        let field = FormField::from_dict(&dict, &store, None, "").unwrap();
        assert_eq!(field.field_type, FormFieldType::Text);
        assert_eq!(field.name, "username");
        assert_eq!(field.value.as_deref(), Some("john"));
        assert_eq!(field.max_len, Some(50));
        assert_eq!(field.tooltip.as_deref(), Some("Enter your name"));
    }

    #[test]
    fn test_parse_button_field_checkbox() {
        let store = build_store();
        let mut dict = HashMap::new();
        dict.insert(Name::ft(), Object::Name(Name::from("Btn")));
        dict.insert(Name::t(), str_obj("agree"));
        dict.insert(Name::as_name(), Object::Name(Name::from("Yes")));
        dict.insert(Name::ff(), Object::Integer(0));

        let field = FormField::from_dict(&dict, &store, None, "").unwrap();
        assert_eq!(field.field_type, FormFieldType::Button);
        assert_eq!(field.name, "agree");
        assert_eq!(field.appearance_state.as_deref(), Some("Yes"));
        assert_eq!(field.flags.bits(), 0);
    }

    #[test]
    fn test_parse_choice_field_with_options() {
        let store = build_store();
        let mut dict = HashMap::new();
        dict.insert(Name::ft(), Object::Name(Name::from("Ch")));
        dict.insert(Name::t(), str_obj("color"));

        // Options: simple strings
        let opts = Object::Array(vec![str_obj("Red"), str_obj("Green"), str_obj("Blue")]);
        dict.insert(Name::opt(), opts);

        let field = FormField::from_dict(&dict, &store, None, "").unwrap();
        assert_eq!(field.field_type, FormFieldType::Choice);
        assert_eq!(field.options.len(), 3);
        assert_eq!(field.options[0].export_value, "Red");
        assert_eq!(field.options[0].display_value, "Red");
        assert_eq!(field.options[2].export_value, "Blue");
    }

    #[test]
    fn test_parse_choice_field_with_export_display_pairs() {
        let store = build_store();
        let mut dict = HashMap::new();
        dict.insert(Name::ft(), Object::Name(Name::from("Ch")));
        dict.insert(Name::t(), str_obj("country"));

        // Options: [export_value, display_value] pairs
        let opts = Object::Array(vec![Object::Array(vec![
            str_obj("US"),
            str_obj("United States"),
        ])]);
        dict.insert(Name::opt(), opts);

        let field = FormField::from_dict(&dict, &store, None, "").unwrap();
        assert_eq!(field.options.len(), 1);
        assert_eq!(field.options[0].export_value, "US");
        assert_eq!(field.options[0].display_value, "United States");
    }

    #[test]
    fn test_hierarchical_field_name() {
        let store = build_store();
        let mut dict = HashMap::new();
        dict.insert(Name::ft(), Object::Name(Name::from("Tx")));
        dict.insert(Name::t(), str_obj("city"));

        let field = FormField::from_dict(&dict, &store, None, "address").unwrap();
        assert_eq!(field.name, "address.city");
    }

    #[test]
    fn test_inherit_ft_from_parent() {
        let store = build_store();
        let mut dict = HashMap::new();
        // No /FT on this field — inherits from parent
        dict.insert(Name::t(), str_obj("line1"));
        dict.insert(Name::v(), str_obj("123 Main St"));

        let field = FormField::from_dict(&dict, &store, Some("Tx"), "address").unwrap();
        assert_eq!(field.field_type, FormFieldType::Text);
        assert_eq!(field.name, "address.line1");
        assert_eq!(field.value.as_deref(), Some("123 Main St"));
    }

    #[test]
    fn test_field_flags_parsing() {
        let store = build_store();
        let mut dict = HashMap::new();
        dict.insert(Name::ft(), Object::Name(Name::from("Tx")));
        dict.insert(Name::t(), str_obj("notes"));
        dict.insert(Name::ff(), Object::Integer(4096)); // Multiline flag

        let field = FormField::from_dict(&dict, &store, None, "").unwrap();
        assert_eq!(field.flags.bits(), 4096);
    }

    #[test]
    fn test_no_ft_returns_none() {
        let store = build_store();
        let mut dict = HashMap::new();
        dict.insert(Name::t(), str_obj("orphan"));

        let result = FormField::from_dict(&dict, &store, None, "");
        assert!(result.is_none());
    }

    // ---- Mutation tests ----

    fn make_field(ft: FormFieldType) -> FormField {
        FormField {
            name: "test".to_string(),
            field_type: ft,
            value: None,
            default_value: Some("default_val".to_string()),
            flags: FormFieldFlags::from_bits(0),
            tooltip: None,
            alternate_name: None,
            mapping_name: None,
            max_len: None,
            options: Vec::new(),
            appearance_state: None,
            children: Vec::new(),
            controls: Vec::new(),
            dirty: false,
            selected_indices: Vec::new(),
            additional_actions: None,
        }
    }

    #[test]
    fn test_set_value_text_field() {
        let mut field = make_field(FormFieldType::Text);
        field.max_len = Some(10);
        field
            .set_value(FieldValue::String("hello".to_string()))
            .unwrap();
        assert_eq!(field.value.as_deref(), Some("hello"));
        assert!(field.dirty);
    }

    #[test]
    fn test_set_value_text_field_too_long() {
        let mut field = make_field(FormFieldType::Text);
        field.max_len = Some(3);
        let result = field.set_value(FieldValue::String("toolong".to_string()));
        assert!(result.is_err());
        assert!(!field.dirty);
    }

    #[test]
    fn test_set_value_button_checked() {
        let mut field = make_field(FormFieldType::Button);
        field.set_value(FieldValue::Bool(true)).unwrap();
        assert_eq!(field.appearance_state.as_deref(), Some("Yes"));
        assert_eq!(field.value.as_deref(), Some("Yes"));
        assert!(field.dirty);
    }

    #[test]
    fn test_set_value_button_unchecked() {
        let mut field = make_field(FormFieldType::Button);
        field.set_value(FieldValue::Bool(false)).unwrap();
        assert_eq!(field.appearance_state.as_deref(), Some("Off"));
    }

    #[test]
    fn test_set_value_choice_by_index() {
        let mut field = make_field(FormFieldType::Choice);
        field.options = vec![
            ChoiceOption {
                export_value: "R".into(),
                display_value: "Red".into(),
            },
            ChoiceOption {
                export_value: "G".into(),
                display_value: "Green".into(),
            },
            ChoiceOption {
                export_value: "B".into(),
                display_value: "Blue".into(),
            },
        ];
        field.set_value(FieldValue::Choice(1)).unwrap();
        assert_eq!(field.value.as_deref(), Some("G"));
    }

    #[test]
    fn test_set_value_choice_out_of_bounds() {
        let mut field = make_field(FormFieldType::Choice);
        field.options = vec![ChoiceOption {
            export_value: "R".into(),
            display_value: "Red".into(),
        }];
        let result = field.set_value(FieldValue::Choice(5));
        assert!(result.is_err());
    }

    #[test]
    fn test_set_value_type_mismatch() {
        let mut field = make_field(FormFieldType::Text);
        let result = field.set_value(FieldValue::Bool(true));
        assert!(result.is_err());
        assert!(!field.dirty);
    }

    #[test]
    fn test_reset_to_default() {
        let mut field = make_field(FormFieldType::Text);
        field.value = Some("modified".to_string());
        field.reset_to_default();
        assert_eq!(field.value.as_deref(), Some("default_val"));
        assert!(field.dirty);
    }

    #[test]
    fn test_needs_appearance_after_set() {
        let mut field = make_field(FormFieldType::Text);
        assert!(!field.needs_appearance());
        field
            .set_value(FieldValue::String("x".to_string()))
            .unwrap();
        assert!(field.needs_appearance());
    }

    // ---- FormControl tests ----

    #[test]
    fn test_controls_accessor_empty() {
        let field = make_field(FormFieldType::Text);
        assert!(field.controls().is_empty());
    }

    #[test]
    fn test_widget_kids_parsed_as_controls() {
        let store = build_store();

        // Build a field with /Kids that are widgets (have /Subtype /Widget, no /FT)
        let mut widget_dict = HashMap::new();
        widget_dict.insert(Name::subtype(), Object::Name(Name::from("Widget")));
        widget_dict.insert(
            Name::rect(),
            Object::Array(vec![
                Object::Real(10.0),
                Object::Real(20.0),
                Object::Real(110.0),
                Object::Real(40.0),
            ]),
        );
        widget_dict.insert(Name::as_name(), Object::Name(Name::from("Yes")));

        let mut field_dict = HashMap::new();
        field_dict.insert(Name::ft(), Object::Name(Name::from("Btn")));
        field_dict.insert(Name::t(), str_obj("checkbox"));
        field_dict.insert(
            Name::kids(),
            Object::Array(vec![Object::Dictionary(widget_dict)]),
        );

        let field = FormField::from_dict(&field_dict, &store, None, "").unwrap();
        assert_eq!(field.controls().len(), 1);
        assert_eq!(field.controls()[0].field_name, "checkbox");
        assert_eq!(field.controls()[0].rect.left, 10.0);
        assert_eq!(field.controls()[0].rect.right, 110.0);
        assert_eq!(field.controls()[0].appearance_state.as_deref(), Some("Yes"));
    }

    // ---- Flag helper tests ----

    #[test]
    fn test_flag_helpers_default() {
        let field = make_field(FormFieldType::Text);
        assert!(!field.flags.is_read_only());
        assert!(!field.flags.is_required());
        assert!(!field.flags.is_no_export());
        assert!(!field.flags.is_multiline());
        assert!(!field.flags.is_password());
    }

    #[test]
    fn test_flag_read_only() {
        let mut field = make_field(FormFieldType::Text);
        field.flags = FormFieldFlags::from_bits(1 << 0);
        assert!(field.flags.is_read_only());
    }

    #[test]
    fn test_flag_required() {
        let mut field = make_field(FormFieldType::Text);
        field.flags = FormFieldFlags::from_bits(1 << 1);
        assert!(field.flags.is_required());
    }

    #[test]
    fn test_flag_no_export() {
        let mut field = make_field(FormFieldType::Text);
        field.flags = FormFieldFlags::from_bits(1 << 2);
        assert!(field.flags.is_no_export());
    }

    #[test]
    fn test_flag_multiline() {
        let mut field = make_field(FormFieldType::Text);
        field.flags = FormFieldFlags::from_bits(1 << 12);
        assert!(field.flags.is_multiline());
    }

    #[test]
    fn test_flag_password() {
        let mut field = make_field(FormFieldType::Text);
        field.flags = FormFieldFlags::from_bits(1 << 13);
        assert!(field.flags.is_password());
    }

    #[test]
    fn test_flag_no_toggle_to_off() {
        let mut field = make_field(FormFieldType::Button);
        field.flags = FormFieldFlags::from_bits(1 << 14);
        assert!(field.flags.is_no_toggle_to_off());
    }

    #[test]
    fn test_flag_radio() {
        let mut field = make_field(FormFieldType::Button);
        field.flags = FormFieldFlags::from_bits(1 << 15);
        assert!(field.flags.is_radio());
    }

    #[test]
    fn test_flag_push_button() {
        let mut field = make_field(FormFieldType::Button);
        field.flags = FormFieldFlags::from_bits(1 << 16);
        assert!(field.flags.is_push_button());
    }

    #[test]
    fn test_flag_combo() {
        let mut field = make_field(FormFieldType::Choice);
        field.flags = FormFieldFlags::from_bits(1 << 17);
        assert!(field.flags.is_combo());
    }

    #[test]
    fn test_flag_combo_editable() {
        let mut field = make_field(FormFieldType::Choice);
        field.flags = FormFieldFlags::from_bits(1 << 18);
        assert!(field.flags.is_combo_editable());
    }

    #[test]
    fn test_flag_sort() {
        let mut field = make_field(FormFieldType::Choice);
        field.flags = FormFieldFlags::from_bits(1 << 19);
        assert!(field.flags.is_sort());
    }

    #[test]
    fn test_flag_file_select() {
        let mut field = make_field(FormFieldType::Text);
        field.flags = FormFieldFlags::from_bits(1 << 20);
        assert!(field.flags.is_file_select());
    }

    #[test]
    fn test_flag_multi_select() {
        let mut field = make_field(FormFieldType::Choice);
        field.flags = FormFieldFlags::from_bits(1 << 21);
        assert!(field.flags.is_multi_select());
    }

    #[test]
    fn test_flag_do_not_spell_check() {
        let mut field = make_field(FormFieldType::Text);
        field.flags = FormFieldFlags::from_bits(1 << 22);
        assert!(field.flags.is_do_not_spell_check());
    }

    #[test]
    fn test_flag_do_not_scroll() {
        let mut field = make_field(FormFieldType::Text);
        field.flags = FormFieldFlags::from_bits(1 << 23);
        assert!(field.flags.is_do_not_scroll());
    }

    #[test]
    fn test_flag_comb() {
        let mut field = make_field(FormFieldType::Text);
        field.flags = FormFieldFlags::from_bits(1 << 24);
        assert!(field.flags.is_comb());
    }

    #[test]
    fn test_flag_rich_text_and_radios_in_unison() {
        // kTextRichText and kButtonRadiosInUnison share bit 25.
        let mut field = make_field(FormFieldType::Text);
        field.flags = FormFieldFlags::from_bits(1 << 25);
        assert!(field.flags.is_rich_text());
        assert!(field.flags.is_radios_in_unison());
    }

    #[test]
    fn test_flag_commit_on_sel_change() {
        let mut field = make_field(FormFieldType::Choice);
        field.flags = FormFieldFlags::from_bits(1 << 26);
        assert!(field.flags.is_commit_on_sel_change());
    }

    // ---- Selection API tests ----

    #[test]
    fn test_selected_indices_empty() {
        let field = make_field(FormFieldType::Choice);
        assert_eq!(field.selected_item_count(), 0);
        assert!(!field.is_item_selected(0));
        assert!(field.selected_index(0).is_none());
    }

    #[test]
    fn test_selected_indices_populated() {
        let mut field = make_field(FormFieldType::Choice);
        field.selected_indices = vec![1, 3];
        assert_eq!(field.selected_item_count(), 2);
        assert!(!field.is_item_selected(0));
        assert!(field.is_item_selected(1));
        assert!(!field.is_item_selected(2));
        assert!(field.is_item_selected(3));
        assert_eq!(field.selected_index(0), Some(1));
        assert_eq!(field.selected_index(1), Some(3));
        assert!(field.selected_index(2).is_none());
    }

    // ---- Alternate/mapping name tests ----

    #[test]
    fn test_alternate_name_from_tooltip() {
        let store = build_store();
        let mut dict = HashMap::new();
        dict.insert(Name::ft(), Object::Name(Name::from("Tx")));
        dict.insert(Name::t(), str_obj("field1"));
        dict.insert(Name::tu(), str_obj("Enter your name"));
        let field = FormField::from_dict(&dict, &store, None, "").unwrap();
        assert_eq!(field.alternate_name.as_deref(), Some("Enter your name"));
        assert_eq!(field.tooltip.as_deref(), Some("Enter your name"));
    }

    #[test]
    fn test_mapping_name_parsed() {
        let store = build_store();
        let mut dict = HashMap::new();
        dict.insert(Name::ft(), Object::Name(Name::from("Tx")));
        dict.insert(Name::t(), str_obj("field1"));
        dict.insert(Name::tm(), str_obj("export_field1"));
        let field = FormField::from_dict(&dict, &store, None, "").unwrap();
        assert_eq!(field.mapping_name.as_deref(), Some("export_field1"));
    }

    // ---- Selected indices parsing test ----

    #[test]
    fn test_selected_indices_parsed_from_dict() {
        let store = build_store();
        let mut dict = HashMap::new();
        dict.insert(Name::ft(), Object::Name(Name::from("Ch")));
        dict.insert(Name::t(), str_obj("colors"));
        let opts = Object::Array(vec![str_obj("Red"), str_obj("Green"), str_obj("Blue")]);
        dict.insert(Name::opt(), opts);
        dict.insert(
            Name::i(),
            Object::Array(vec![Object::Integer(0), Object::Integer(2)]),
        );
        let field = FormField::from_dict(&dict, &store, None, "").unwrap();
        assert_eq!(field.selected_indices, vec![0, 2]);
        assert!(field.is_item_selected(0));
        assert!(!field.is_item_selected(1));
        assert!(field.is_item_selected(2));
    }

    #[test]
    fn test_kids_with_ft_not_treated_as_controls() {
        let store = build_store();

        // A kid with /FT is a child field, not a widget control
        let mut child_dict = HashMap::new();
        child_dict.insert(Name::subtype(), Object::Name(Name::from("Widget")));
        child_dict.insert(Name::ft(), Object::Name(Name::from("Tx")));
        child_dict.insert(Name::t(), str_obj("child"));

        let mut field_dict = HashMap::new();
        field_dict.insert(Name::ft(), Object::Name(Name::from("Tx")));
        field_dict.insert(Name::t(), str_obj("parent"));
        field_dict.insert(
            Name::kids(),
            Object::Array(vec![Object::Dictionary(child_dict)]),
        );

        let field = FormField::from_dict(&field_dict, &store, None, "").unwrap();
        // Widget kids with /FT are child fields, not controls
        assert!(field.controls().is_empty());
    }

    // ---- clear_selection test ----

    #[test]
    fn test_clear_selection_clears_indices() {
        let mut field = make_field(FormFieldType::Choice);
        field.selected_indices = vec![0, 2];
        let result = field.clear_selection();
        assert!(result.is_ok());
        // In-memory selection cleared
        assert!(field.selected_indices.is_empty());
    }

    // ---- additional_actions accessor test ----

    #[test]
    fn test_additional_actions_none_by_default() {
        let field = make_field(FormFieldType::Text);
        assert!(field.additional_actions().is_none());
    }

    // ---- count_options / get_option_label / get_option_value ----

    #[test]
    fn test_option_count_returns_options_length() {
        let store = build_store();
        let mut dict = HashMap::new();
        dict.insert(Name::ft(), Object::Name(Name::from("Ch")));
        dict.insert(Name::t(), str_obj("colors"));
        dict.insert(
            Name::opt(),
            Object::Array(vec![str_obj("Red"), str_obj("Green"), str_obj("Blue")]),
        );
        let field = FormField::from_dict(&dict, &store, None, "").unwrap();
        assert_eq!(field.option_count(), 3);
    }

    #[test]
    fn test_get_option_label_returns_display_value() {
        let store = build_store();
        let mut dict = HashMap::new();
        dict.insert(Name::ft(), Object::Name(Name::from("Ch")));
        dict.insert(Name::t(), str_obj("sizes"));
        // Two-element array subarray: [export_value, display_value]
        dict.insert(
            Name::opt(),
            Object::Array(vec![
                Object::Array(vec![str_obj("sm"), str_obj("Small")]),
                Object::Array(vec![str_obj("lg"), str_obj("Large")]),
            ]),
        );
        let field = FormField::from_dict(&dict, &store, None, "").unwrap();
        assert_eq!(field.get_option_label(0), Some("Small"));
        assert_eq!(field.get_option_label(1), Some("Large"));
        assert_eq!(field.get_option_label(2), None);
    }

    #[test]
    fn test_get_option_value_returns_export_value() {
        let store = build_store();
        let mut dict = HashMap::new();
        dict.insert(Name::ft(), Object::Name(Name::from("Ch")));
        dict.insert(Name::t(), str_obj("sizes"));
        dict.insert(
            Name::opt(),
            Object::Array(vec![
                Object::Array(vec![str_obj("sm"), str_obj("Small")]),
                Object::Array(vec![str_obj("lg"), str_obj("Large")]),
            ]),
        );
        let field = FormField::from_dict(&dict, &store, None, "").unwrap();
        assert_eq!(field.get_option_value(0), Some("sm"));
        assert_eq!(field.get_option_value(1), Some("lg"));
        assert_eq!(field.get_option_value(99), None);
    }

    // ---- count_controls / get_control ----

    #[test]
    fn test_control_count_returns_controls_length() {
        let mut field = make_field(FormFieldType::Choice);
        assert_eq!(field.control_count(), 0);
        use crate::form_control::{FormControl, HighlightingMode, TextPosition};
        use rpdfium_core::Rect;
        field.controls.push(FormControl {
            field_name: "test".to_string(),
            rect: Rect::new(0.0, 0.0, 100.0, 20.0),
            appearance_state: None,
            page_index: None,
            highlighting_mode: HighlightingMode::Invert,
            rotation: 0,
            border_color: None,
            background_color: None,
            caption: None,
            rollover_caption: None,
            alt_caption: None,
            default_appearance: None,
            normal_icon: None,
            rollover_icon: None,
            down_icon: None,
            icon_fit: None,
            text_position: TextPosition::CaptionOnly,
        });
        assert_eq!(field.control_count(), 1);
    }

    #[test]
    fn test_get_control_returns_correct_control() {
        let mut field = make_field(FormFieldType::Text);
        use crate::form_control::{FormControl, HighlightingMode, TextPosition};
        use rpdfium_core::Rect;
        let ctrl = FormControl {
            field_name: "f".to_string(),
            rect: Rect::new(10.0, 10.0, 110.0, 30.0),
            appearance_state: None,
            page_index: Some(0),
            highlighting_mode: HighlightingMode::None,
            rotation: 0,
            border_color: None,
            background_color: None,
            caption: None,
            rollover_caption: None,
            alt_caption: None,
            default_appearance: None,
            normal_icon: None,
            rollover_icon: None,
            down_icon: None,
            icon_fit: None,
            text_position: TextPosition::CaptionOnly,
        };
        field.controls.push(ctrl);
        assert!(field.get_control(0).is_some());
        assert_eq!(field.get_control(0).unwrap().page_index, Some(0));
        assert!(field.get_control(1).is_none());
    }

    // -----------------------------------------------------------------------
    // Upstream: TEST(CPDFFormFieldTest, IsItemSelected)
    //
    // Multi-select choice field with /V (values) and /I (selected indices)
    // in various combinations. Tests the conflict resolution logic.
    // -----------------------------------------------------------------------

    /// Upstream: TEST(CPDFFormFieldTest, IsItemSelected)
    ///
    /// Exercises `is_item_selected()` across 18 sub-cases with different
    /// combinations of /V (values), /I (selected indices), and conflicts.
    ///
    /// In rpdfium, `FormField::from_dict` currently populates `selected_indices`
    /// from /I only. The full /V vs /I conflict resolution logic (which
    /// `UseSelectedIndicesObject` mediates in upstream) is tested here using
    /// direct in-memory construction to validate `is_item_selected()`.
    #[test]
    fn test_cpdf_form_field_is_item_selected() {
        // Build a choice field with 5 options
        let options = vec![
            ChoiceOption {
                export_value: "Alpha".into(),
                display_value: "Alpha".into(),
            },
            ChoiceOption {
                export_value: "Beta".into(),
                display_value: "Beta".into(),
            },
            ChoiceOption {
                export_value: "Gamma".into(),
                display_value: "Gamma".into(),
            },
            ChoiceOption {
                export_value: "Delta".into(),
                display_value: "Delta".into(),
            },
            ChoiceOption {
                export_value: "Epsilon".into(),
                display_value: "Epsilon".into(),
            },
        ];

        let make_choice_field = |selected: Vec<usize>| -> FormField {
            FormField {
                name: "multi".to_string(),
                field_type: FormFieldType::Choice,
                value: None,
                default_value: None,
                flags: FormFieldFlags::from_bits(1 << 21), // MultiSelect
                tooltip: None,
                alternate_name: None,
                mapping_name: None,
                max_len: None,
                options: options.clone(),
                appearance_state: None,
                children: Vec::new(),
                controls: Vec::new(),
                dirty: false,
                selected_indices: selected,
                additional_actions: None,
            }
        };

        // Case 1: No selections
        {
            let field = make_choice_field(vec![]);
            for i in 0..5 {
                assert!(!field.is_item_selected(i));
            }
            // Out of range
            assert!(!field.is_item_selected(5));
        }

        // Case 2: Single selection
        {
            let field = make_choice_field(vec![2]); // Gamma
            assert!(!field.is_item_selected(0));
            assert!(!field.is_item_selected(1));
            assert!(field.is_item_selected(2));
            assert!(!field.is_item_selected(3));
            assert!(!field.is_item_selected(4));
        }

        // Case 3: Multiple selections
        {
            let field = make_choice_field(vec![0, 2, 3]);
            assert!(field.is_item_selected(0));
            assert!(!field.is_item_selected(1));
            assert!(field.is_item_selected(2));
            assert!(field.is_item_selected(3));
            assert!(!field.is_item_selected(4));
        }

        // Case 4: Selections with some out-of-range indices
        {
            let field = make_choice_field(vec![0, 2, 3, 12, 42]);
            assert!(field.is_item_selected(0));
            assert!(!field.is_item_selected(1));
            assert!(field.is_item_selected(2));
            assert!(field.is_item_selected(3));
            assert!(!field.is_item_selected(4));
            // Out-of-range indices are stored but don't match valid options
            assert!(!field.is_item_selected(5));
            // But is_item_selected just does contains(), so 12 and 42 return true
            assert!(field.is_item_selected(12));
            assert!(field.is_item_selected(42));
        }

        // Case 5: selected_item_count
        {
            let field = make_choice_field(vec![1, 4]);
            assert_eq!(field.selected_item_count(), 2);
            assert_eq!(field.count_selected_items(), 2);
        }

        // Case 6: selected_index
        {
            let field = make_choice_field(vec![1, 4]);
            assert_eq!(field.selected_index(0), Some(1));
            assert_eq!(field.selected_index(1), Some(4));
            assert_eq!(field.selected_index(2), None);
        }
    }
}