repose_core/

text.rs

use crate::Color;
use std::fmt::Debug;
use std::rc::Rc;
use std::sync::Arc;

/// A range of text measured in byte offsets, matching Compose's `TextRange`.
///
/// When `start == end`, the range is collapsed (cursor position).
/// When `start > end`, the range is reversed (selection direction matters).
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct TextRange {
    pub start: usize,
    pub end: usize,
}

impl TextRange {
    pub const ZERO: TextRange = TextRange { start: 0, end: 0 };

    pub fn new(start: usize, end: usize) -> Self {
        Self { start, end }
    }

    pub fn collapsed(at: usize) -> Self {
        Self { start: at, end: at }
    }

    pub fn min(self) -> usize {
        self.start.min(self.end)
    }

    pub fn max(self) -> usize {
        self.start.max(self.end)
    }

    pub fn is_collapsed(self) -> bool {
        self.start == self.end
    }

    pub fn reversed(self) -> bool {
        self.start > self.end
    }

    pub fn length(self) -> usize {
        self.max() - self.min()
    }

    pub fn intersects(self, other: TextRange) -> bool {
        self.min() < other.max() && other.min() < self.max()
    }

    pub fn contains(self, offset: usize) -> bool {
        self.min() <= offset && offset < self.max()
    }

    pub fn coerce_in(self, min: usize, max: usize) -> Self {
        Self {
            start: self.start.clamp(min, max),
            end: self.end.clamp(min, max),
        }
    }
}

impl From<(usize, usize)> for TextRange {
    fn from((start, end): (usize, usize)) -> Self {
        Self { start, end }
    }
}

/// Snapshot of a text field's editing state including text, selection, and
/// IME composition range. Corresponds to Compose's `TextFieldValue`.
#[derive(Clone, Debug, PartialEq)]
pub struct TextFieldValue {
    /// The annotated text. Plain text is accessible via `text()` or `annotated_string.text`.
    pub annotated_string: AnnotatedString,
    /// Selection range in byte offsets. Collapsed range (start == end) = cursor.
    pub selection: TextRange,
    /// Active IME composition range in byte offsets, or None.
    pub composition: Option<TextRange>,
}

impl TextFieldValue {
    /// Create from plain text (no annotations).
    pub fn new(text: impl Into<String>) -> Self {
        let annotated = AnnotatedString::from(text.into());
        let len = annotated.text.len();
        Self {
            selection: TextRange::collapsed(len),
            annotated_string: annotated,
            composition: None,
        }
    }

    /// Create from an `AnnotatedString` preserving all annotations.
    pub fn from_annotated(annotated: AnnotatedString) -> Self {
        let len = annotated.text.len();
        Self {
            selection: TextRange::collapsed(len),
            annotated_string: annotated,
            composition: None,
        }
    }

    /// Convenience: plain text content (delegates to `annotated_string.text`).
    pub fn text(&self) -> &str {
        &self.annotated_string.text
    }

    pub fn with_selection(mut self, start: usize, end: usize) -> Self {
        let len = self.annotated_string.text.len();
        self.selection = TextRange::new(start.min(len), end.min(len));
        self
    }

    pub fn get_text_before_selection(&self, max_chars: usize) -> AnnotatedString {
        let sel_min = self.selection.min();
        let start = sel_min.saturating_sub(max_chars);
        let text = self.annotated_string.text[start..sel_min].to_string();
        // Preserve spans that intersect the sub-range
        let spans: Vec<TextSpan> = self
            .annotated_string
            .spans
            .iter()
            .filter(|s| s.start >= start && s.end <= sel_min)
            .map(|s| TextSpan {
                start: s.start - start,
                end: s.end - start,
                style: s.style.clone(),
                url: s.url.clone(),
            })
            .collect();
        AnnotatedString::new(text, spans)
    }

    pub fn get_text_after_selection(&self, max_chars: usize) -> AnnotatedString {
        let sel_max = self.selection.max();
        let end = (sel_max + max_chars).min(self.annotated_string.text.len());
        let text = self.annotated_string.text[sel_max..end].to_string();
        let spans: Vec<TextSpan> = self
            .annotated_string
            .spans
            .iter()
            .filter(|s| s.start >= sel_max && s.end <= end)
            .map(|s| TextSpan {
                start: s.start - sel_max,
                end: s.end - sel_max,
                style: s.style.clone(),
                url: s.url.clone(),
            })
            .collect();
        AnnotatedString::new(text, spans)
    }

    pub fn get_selected_text(&self) -> AnnotatedString {
        let r = self.selection.min()..self.selection.max();
        let text = self.annotated_string.text[r.clone()].to_string();
        let spans: Vec<TextSpan> = self
            .annotated_string
            .spans
            .iter()
            .filter(|s| s.start >= r.start && s.end <= r.end)
            .map(|s| TextSpan {
                start: s.start - r.start,
                end: s.end - r.start,
                style: s.style.clone(),
                url: s.url.clone(),
            })
            .collect();
        AnnotatedString::new(text, spans)
    }

    pub fn copy(&self, annotated_string: AnnotatedString) -> Self {
        TextFieldValue {
            annotated_string,
            selection: self.selection,
            composition: self.composition,
        }
    }

    pub fn copy_text(&self, text: String) -> Self {
        TextFieldValue {
            annotated_string: AnnotatedString::from(text),
            selection: self.selection,
            composition: self.composition,
        }
    }
}

/// Result of text layout for `on_text_layout`.
#[derive(Clone, Debug)]
pub struct TextLayoutResult {
    pub line_count: usize,
    pub width_px: f32,
    pub height_px: f32,
    pub first_baseline: f32,
    pub last_baseline: f32,
    pub did_overflow_width: bool,
    pub did_overflow_height: bool,
    pub lines: Vec<TextLineInfo>,
}

/// How text is obfuscated in secure fields.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
pub enum TextObfuscationMode {
    /// Text is visible, no obfuscation.
    Visible,
    /// Reveal the last typed character briefly, then hide.
    RevealLastTyped,
    /// All characters are obfuscated.
    Hidden,
    /// Uses the platform's default obfuscation behavior.
    #[default]
    System,
}

/// Layout information for a single line of text.
#[derive(Clone, Debug)]
pub struct TextLineInfo {
    /// Byte offset of the line start in the text.
    pub start: usize,
    /// Byte offset of the line end (exclusive) in the text.
    pub end: usize,
    /// Top y position in px relative to the text field content area.
    pub top: f32,
    /// Baseline y position in px relative to the text field content area.
    pub baseline: f32,
    /// Bottom y position in px relative to the text field content area.
    pub bottom: f32,
    /// Left x position in px relative to the text field content area.
    pub left: f32,
    /// Right x position in px relative to the text field content area.
    pub right: f32,
    /// Width of this line in px.
    pub width: f32,
}

impl TextLayoutResult {
    pub fn get_line_start(&self, line_index: usize) -> Option<usize> {
        self.lines.get(line_index).map(|l| l.start)
    }

    pub fn get_line_end(&self, line_index: usize) -> Option<usize> {
        self.lines.get(line_index).map(|l| l.end)
    }

    pub fn get_line_end_visible(&self, line_index: usize) -> Option<usize> {
        self.lines.get(line_index).map(|l| l.end)
    }

    pub fn is_line_ellipsized(&self, _line_index: usize) -> bool {
        false
    }

    pub fn get_line_top(&self, line_index: usize) -> Option<f32> {
        self.lines.get(line_index).map(|l| l.top)
    }

    pub fn get_line_baseline(&self, line_index: usize) -> Option<f32> {
        self.lines.get(line_index).map(|l| l.baseline)
    }

    pub fn get_line_bottom(&self, line_index: usize) -> Option<f32> {
        self.lines.get(line_index).map(|l| l.bottom)
    }

    pub fn get_line_left(&self, line_index: usize) -> Option<f32> {
        self.lines.get(line_index).map(|l| l.left)
    }

    pub fn get_line_right(&self, line_index: usize) -> Option<f32> {
        self.lines.get(line_index).map(|l| l.right)
    }

    pub fn get_line_for_offset(&self, offset: usize) -> usize {
        for (i, line) in self.lines.iter().enumerate() {
            if offset >= line.start && offset < line.end {
                return i;
            }
        }
        self.line_count.saturating_sub(1)
    }

    pub fn get_line_for_vertical_position(&self, vertical: f32) -> usize {
        for (i, line) in self.lines.iter().enumerate() {
            if vertical >= line.top && vertical < line.bottom {
                return i;
            }
        }
        self.line_count.saturating_sub(1)
    }

    pub fn get_horizontal_position(&self, offset: usize, _use_primary_direction: bool) -> f32 {
        self.lines
            .iter()
            .find(|l| offset >= l.start && offset <= l.end)
            .map(|l| l.left)
            .unwrap_or(0.0)
    }

    pub fn has_visual_overflow(&self) -> bool {
        self.did_overflow_width || self.did_overflow_height
    }

    pub fn get_bounding_box(&self, offset: usize) -> crate::Rect {
        if self.lines.is_empty() || offset > self.lines.last().unwrap().end {
            return crate::Rect::default();
        }
        let line = self
            .lines
            .iter()
            .find(|l| offset >= l.start && offset < l.end)
            .unwrap_or_else(|| {
                if offset >= self.lines.last().unwrap().end {
                    self.lines.last().unwrap()
                } else {
                    &self.lines[0]
                }
            });
        let _line_idx = self.get_line_for_offset(offset);
        let char_in_line = offset - line.start;
        let pos_in_line = if char_in_line == 0 {
            line.left
        } else {
            let chars = line.end - line.start;
            if chars == 0 {
                line.left
            } else {
                line.left + (line.width * (char_in_line as f32) / (chars as f32))
            }
        };
        crate::Rect {
            x: pos_in_line,
            y: line.top,
            w: if char_in_line < (line.end - line.start) {
                line.width / (line.end - line.start).max(1) as f32
            } else {
                1.0
            },
            h: line.bottom - line.top,
        }
    }

    pub fn get_cursor_rect(&self, offset: usize) -> crate::Rect {
        let line = self
            .lines
            .iter()
            .find(|l| offset >= l.start && offset <= l.end)
            .unwrap_or_else(|| {
                if offset >= self.lines.last().map(|l| l.end).unwrap_or(0) {
                    self.lines.last().unwrap()
                } else {
                    &self.lines[0]
                }
            });
        let char_in_line = offset.saturating_sub(line.start);
        let chars = (line.end - line.start).max(1);
        let x = line.left + (line.width * (char_in_line as f32) / (chars as f32));
        crate::Rect {
            x,
            y: line.top,
            w: 1.0,
            h: line.bottom - line.top,
        }
    }

    pub fn get_offset_for_position(&self, position: (f32, f32)) -> Option<usize> {
        let line_idx = self.get_line_for_vertical_position(position.1);
        let line = self.lines.get(line_idx)?;
        if position.0 <= line.left {
            return Some(line.start);
        }
        if position.0 >= line.right {
            return Some(line.end);
        }
        let fraction = (position.0 - line.left) / line.width.max(1.0);
        let offset_in_line = ((line.end - line.start) as f32 * fraction).round() as usize;
        Some((line.start + offset_in_line).min(line.end))
    }

    pub fn get_word_boundary(&self, _offset: usize) -> super::TextRange {
        // Stub: layout results don't retain the full text, so real word
        // boundaries can't be computed yet.
        super::TextRange::new(0, 0)
    }

    pub fn get_paragraph_direction(&self, _offset: usize) -> u8 {
        0 // LTR
    }

    pub fn get_bidi_run_direction(&self, _offset: usize) -> u8 {
        0 // LTR
    }
}

pub trait OffsetMapping: Debug + Send + Sync + 'static {
    fn original_to_transformed(&self, offset: usize) -> usize;
    fn transformed_to_original(&self, offset: usize) -> usize;
    fn clone_box(&self) -> Box<dyn OffsetMapping>;
}

/// Identity offset mapping: original and transformed offsets are the same.
#[derive(Clone, Copy, Debug)]
pub struct IdentityOffsetMapping;

impl OffsetMapping for IdentityOffsetMapping {
    fn original_to_transformed(&self, offset: usize) -> usize {
        offset
    }
    fn transformed_to_original(&self, offset: usize) -> usize {
        offset
    }
    fn clone_box(&self) -> Box<dyn OffsetMapping> {
        Box::new(*self)
    }
}

/// Transforms display text without changing the underlying value (e.g. password masking).
pub trait VisualTransformation: Debug + Send + Sync + 'static {
    /// Transform the text for display. Takes the original `AnnotatedString` and returns
    /// the transformed `TransformedText` with an offset mapping.
    fn filter(&self, text: &AnnotatedString) -> TransformedText;
}

/// Output of `VisualTransformation::filter`.
pub struct TransformedText {
    pub text: AnnotatedString,
    pub offset_mapping: Box<dyn OffsetMapping>,
}

impl TransformedText {
    pub fn new(text: AnnotatedString, offset_mapping: Box<dyn OffsetMapping>) -> Self {
        TransformedText {
            text,
            offset_mapping,
        }
    }
}

impl Clone for TransformedText {
    fn clone(&self) -> Self {
        Self {
            text: self.text.clone(),
            offset_mapping: self.offset_mapping.clone_box(),
        }
    }
}

impl Debug for TransformedText {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("TransformedText")
            .field("text", &self.text.text)
            .finish()
    }
}

#[derive(Clone, Copy, Debug)]
pub struct IdentityVisualTransformation;

impl VisualTransformation for IdentityVisualTransformation {
    fn filter(&self, text: &AnnotatedString) -> TransformedText {
        TransformedText {
            text: text.clone(),
            offset_mapping: Box::new(IdentityOffsetMapping),
        }
    }
}

/// A `VisualTransformation` that masks all characters with a given character.
/// Matches Compose's `PasswordVisualTransformation`.
#[derive(Clone, Copy, Debug)]
pub struct PasswordVisualTransformation {
    pub mask: char,
}

impl Default for PasswordVisualTransformation {
    fn default() -> Self {
        Self { mask: '\u{2022}' }
    }
}

/// Char-index offset mapping for masked text: the Nth original char maps to
/// the Nth mask char (byte offsets differ when widths differ, e.g. `a\U0001F44D`
/// (5B) masked to `\u{2022}\u{2022}` (6B)). Identity mapping here silently
/// mis-placed carets mid-mask-char for non-BMP input.
#[derive(Clone, Debug)]
pub struct PasswordOffsetMapping {
    original: Vec<usize>,
    transformed: Vec<usize>,
}

impl PasswordOffsetMapping {
    pub fn new(original: &str, mask: char, masked: &str) -> Self {
        let mut o = Vec::with_capacity(original.chars().count() + 1);
        for (i, _) in original.char_indices() {
            o.push(i);
        }
        o.push(original.len());
        let mut t = vec![0usize];
        let n = original.chars().count();
        let mut byte = 0usize;
        for _ in 0..n {
            byte += mask.len_utf8();
            t.push(byte);
        }
        if byte != masked.len() {
            t.clear();
            t.push(0);
            let mut b = 0usize;
            for ch in masked.chars() {
                b += ch.len_utf8();
                t.push(b);
            }
        }
        Self {
            original: o,
            transformed: t,
        }
    }

    fn snap_back(offsets: &[usize], text_len: usize, offset: usize) -> usize {
        let o = offset.min(text_len);
        match offsets.binary_search(&o) {
            Ok(_) => o,
            Err(i) => offsets.get(i.saturating_sub(1)).copied().unwrap_or(0),
        }
    }
    fn index_of(offsets: &[usize], snapped: usize) -> usize {
        match offsets.binary_search(&snapped) {
            Ok(i) => i,
            Err(i) => i.min(offsets.len().saturating_sub(1)),
        }
    }
}

impl OffsetMapping for PasswordOffsetMapping {
    fn original_to_transformed(&self, offset: usize) -> usize {
        let o_text_len = *self.original.last().unwrap_or(&0);
        let snapped = Self::snap_back(&self.original, o_text_len, offset);
        let idx = Self::index_of(&self.original, snapped);
        self.transformed.get(idx).copied().unwrap_or(0)
    }
    fn transformed_to_original(&self, offset: usize) -> usize {
        let t_text_len = *self.transformed.last().unwrap_or(&0);
        let snapped = Self::snap_back(&self.transformed, t_text_len, offset);
        let idx = Self::index_of(&self.transformed, snapped);
        self.original.get(idx).copied().unwrap_or(0)
    }
    fn clone_box(&self) -> Box<dyn OffsetMapping> {
        Box::new(self.clone())
    }
}

impl VisualTransformation for PasswordVisualTransformation {
    fn filter(&self, text: &AnnotatedString) -> TransformedText {
        let masked_text: String = text.text.chars().map(|_| self.mask).collect();
        let mapping = PasswordOffsetMapping::new(&text.text, self.mask, &masked_text);
        TransformedText {
            text: AnnotatedString::new(masked_text, vec![]),
            offset_mapping: Box::new(mapping),
        }
    }
}

/// Convert a byte offset in the original text to the corresponding byte offset
/// in the visually-transformed display text.
pub fn original_offset_to_display(original: &str, display: &str, original_byte: usize) -> usize {
    original_offset_to_display_with_mapping(original, display, original_byte, None)
}

/// Convert a byte offset in the original text to the corresponding byte offset
/// in the visually-transformed display text, using the provided `OffsetMapping` if available.
pub fn original_offset_to_display_with_mapping(
    original: &str,
    display: &str,
    original_byte: usize,
    offset_mapping: Option<&dyn OffsetMapping>,
) -> usize {
    if let Some(om) = offset_mapping {
        om.original_to_transformed(original_byte)
    } else {
        let char_idx = original[..original_byte.min(original.len())]
            .chars()
            .count();
        display
            .char_indices()
            .nth(char_idx)
            .map(|(i, _)| i)
            .unwrap_or(display.len())
    }
}

/// Configures automatic capitalization behavior for the keyboard.
/// Corresponds to Compose's `KeyboardCapitalization`.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
pub enum KeyboardCapitalization {
    #[default]
    Unspecified,
    None,
    Characters,
    Words,
    Sentences,
}

/// Text shadow. Offsets and blur are in [`Dp`](crate::units::Dp),
/// converted to px at the paint boundary.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Shadow {
    pub color: Color,
    /// Horizontal offset in [`Dp`](crate::units::Dp).
    pub offset_x: crate::units::Dp,
    /// Vertical offset in [`Dp`](crate::units::Dp).
    pub offset_y: crate::units::Dp,
    /// Blur radius in [`Dp`](crate::units::Dp).
    pub blur_radius: crate::units::Dp,
}

/// Font synthesis controls whether the font renderer may synthesize
/// bold, italic, or small-caps variants when the font lacks them.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
pub enum FontSynthesis {
    #[default]
    Unspecified,
    None,
    Weight,
    Style,
    SmallCaps,
    All,
}

/// Baseline shift for subscript/superscript.
/// Wraps a multiplier applied against font_size for glyph y-offset.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct BaselineShift(pub f32);

#[allow(non_upper_case_globals)]
impl BaselineShift {
    /// No baseline shift (zero offset).
    pub const Unspecified: BaselineShift = BaselineShift(0.0);
    /// Default superscript offset: shift up by 33.3% of font_size (CSS standard).
    pub const Superscript: BaselineShift = BaselineShift(-0.333);
    /// Default subscript offset: shift down by 20% of font_size (CSS standard).
    pub const Subscript: BaselineShift = BaselineShift(0.2);
}

impl Default for BaselineShift {
    fn default() -> Self {
        BaselineShift::Unspecified
    }
}

/// Hyphenation behavior.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
pub enum Hyphens {
    #[default]
    Unspecified,
    None,
    Auto,
}

/// Line break behavior.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
pub enum LineBreak {
    #[default]
    Unspecified,
    Simple,
    Heading,
    Paragraph,
}

/// First-line and rest-line indent in [`Dp`](crate::units::Dp).
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct TextIndent {
    pub first_line: crate::units::Dp,
    pub rest_lines: crate::units::Dp,
}

impl Default for TextIndent {
    fn default() -> Self {
        Self {
            first_line: crate::units::Dp::ZERO,
            rest_lines: crate::units::Dp::ZERO,
        }
    }
}

/// Path effect applied to a stroked path.
/// Mirrors Compose's `PathEffect`.
#[derive(Clone, Debug, PartialEq)]
pub enum PathEffect {
    /// Replace sharp corners with rounded arcs of the given radius.
    Corner {
        /// Corner radius in em-units.
        radius: f32,
    },
    /// Draw the path as a dashed line.
    Dash {
        /// Interleaved on/off lengths in em-units.
        intervals: Vec<f32>,
        /// Starting phase offset in em-units.
        phase: f32,
    },
}

/// Draw style for text (fill or stroke).
#[derive(Clone, Debug, PartialEq, Default)]
pub enum DrawStyle {
    #[default]
    Fill,
    Stroke {
        /// Stroke width in em-units (fraction of font size). 0.05 = 5% of em.
        width: f32,
        /// Line cap style for stroke endpoints.
        cap: crate::StrokeCap,
        /// Line join style for stroke segment joins.
        join: crate::StrokeJoin,
        /// Miter limit for miter joins.
        miter: f32,
        /// Optional path effect (dash, corner rounding, etc.).
        path_effect: Option<PathEffect>,
    },
    /// Fill plus an outline in the same color. Renders the fill first,
    /// then the stroke on top (same layout; stroke width in em-units).
    /// Faux-bold for fonts without a bold face: single layout pass,
    /// no extra view needed.
    FillAndStroke {
        /// Stroke width in em-units (fraction of font size). 0.05 = 5% of em.
        width: f32,
        /// Line cap style for stroke endpoints.
        cap: crate::StrokeCap,
        /// Line join style for stroke segment joins.
        join: crate::StrokeJoin,
        /// Miter limit for miter joins.
        miter: f32,
        /// Optional path effect (dash, corner rounding, etc.).
        path_effect: Option<PathEffect>,
    },
}

impl DrawStyle {
    /// Create a `Stroke` variant with default cap, join, miter, and no path effect.
    pub const fn stroke(width: f32) -> Self {
        Self::Stroke {
            width,
            cap: crate::StrokeCap::Butt,
            join: crate::StrokeJoin::Miter,
            miter: 4.0,
            path_effect: None,
        }
    }

    /// Create a `FillAndStroke` variant with default cap, join, miter,
    /// and no path effect.
    pub const fn fill_and_stroke(width: f32) -> Self {
        Self::FillAndStroke {
            width,
            cap: crate::StrokeCap::Butt,
            join: crate::StrokeJoin::Miter,
            miter: 4.0,
            path_effect: None,
        }
    }

    /// Outline parameters when this style draws a stroke, else `None`.
    pub const fn stroke_params(
        &self,
    ) -> Option<(
        f32,
        crate::StrokeCap,
        crate::StrokeJoin,
        f32,
        &Option<PathEffect>,
    )> {
        match self {
            Self::Stroke {
                width,
                cap,
                join,
                miter,
                path_effect,
            }
            | Self::FillAndStroke {
                width,
                cap,
                join,
                miter,
                path_effect,
            } => Some((*width, *cap, *join, *miter, path_effect)),
            Self::Fill => None,
        }
    }

    /// Whether this style draws the glyph fill.
    pub const fn draws_fill(&self) -> bool {
        !matches!(self, Self::Stroke { .. })
    }
}

/// Style configuration for text displayed in a text field.
/// Corresponds to Compose's `TextStyle` (font sizes are `TextUnit` Sp there).
#[derive(Clone, Debug)]
pub struct TextStyle {
    /// Font size in [`Sp`](crate::units::Sp). `Sp::ZERO` = use default (16sp for TextField).
    pub font_size: crate::units::Sp,
    /// Text color. None = use theme default.
    pub color: Option<Color>,
    /// Font weight. None = NORMAL.
    pub font_weight: Option<u16>,
    /// Font family. None = use default (sans-serif).
    pub font_family: Option<&'static str>,
    /// Font style. None = Normal.
    pub font_style: Option<u8>,
    /// Text alignment. Unspecified = inherit.
    pub text_align: crate::TextAlign,
    /// Letter spacing in [`Sp`](crate::units::Sp). `Sp::ZERO` = no extra spacing.
    pub letter_spacing: crate::units::Sp,
    /// Line height in [`Sp`](crate::units::Sp). `Sp::ZERO` = default (font_size).
    pub line_height: crate::units::Sp,
    /// Text background color. None = transparent.
    pub background: Option<Color>,
    /// Text decoration (underline, strikethrough). None = no decoration.
    pub text_decoration: Option<crate::TextDecoration>,
    /// Text shadow. None = no shadow.
    pub shadow: Option<Shadow>,
    /// Text direction. None = inherit from thread-local default (usually LTR).
    pub text_direction: Option<crate::TextDirection>,
    /// Font synthesis policy (synthesize missing bold/italic/small-caps).
    pub font_synthesis: FontSynthesis,
    /// Baseline shift (superscript/subscript).
    pub baseline_shift: BaselineShift,
    /// Hyphenation behavior.
    pub hyphens: Hyphens,
    /// Line break behavior.
    pub line_break: LineBreak,
    /// First-line and rest-line indent in dp.
    pub text_indent: Option<TextIndent>,
    /// Draw style (fill or stroke).
    pub draw_style: DrawStyle,
    /// Text opacity (0.0-1.0). 0.0 = use default (fully opaque).
    pub alpha: f32,
    /// Locale hint for text shaping. Empty = use default.
    pub locale_list: Option<String>,
    /// OpenType font feature settings (e.g. "liga", "kern").
    pub font_feature_settings: Option<String>,
    /// OpenType font variation settings (e.g. "wght 700, opsz 24").
    pub font_variation_settings: Option<String>,
}

impl Default for TextStyle {
    fn default() -> Self {
        Self {
            font_size: crate::units::Sp::ZERO,
            color: None,
            font_weight: None,
            font_family: Some("sans-serif"),
            font_style: None,
            text_align: crate::TextAlign::Unspecified,
            letter_spacing: crate::units::Sp::ZERO,
            line_height: crate::units::Sp::ZERO,
            background: None,
            text_decoration: None,
            shadow: None,
            text_direction: None,
            font_synthesis: FontSynthesis::Unspecified,
            baseline_shift: BaselineShift::Unspecified,
            hyphens: Hyphens::Unspecified,
            line_break: LineBreak::Unspecified,
            text_indent: None,
            draw_style: DrawStyle::Fill,
            alpha: 0.0,
            locale_list: None,
            font_feature_settings: None,
            font_variation_settings: None,
        }
    }
}

/// Hints the platform about the type of keyboard to show.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
pub enum KeyboardType {
    #[default]
    Unspecified,
    Text,
    Ascii,
    Number,
    Phone,
    Uri,
    Email,
    Password,
    NumberPassword,
    Decimal,
    PasswordVisible,
    PostalAddress,
    PersonName,
    EmailSubject,
    ShortMessage,
    LongMessage,
    Filter,
    Phonetic,
    DateTime,
    Date,
    Time,
    NumberSigned,
    DecimalSigned,
    DecimalPassword,
    NumberPasswordSigned,
    DecimalPasswordSigned,
}

/// The action button on the IME (soft keyboard).
#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
pub enum ImeAction {
    #[default]
    Unspecified,
    None,
    Default,
    Go,
    Search,
    Send,
    Previous,
    Next,
    Done,
}

/// High-level IME purpose for the platform's soft keyboard.
///
/// Unlike [`KeyboardType`], which enumerates the many Compose-style keyboard
/// layouts, this is the small set of intents platforms can actually react (for NativeA) to
/// (password fields, e-mail addresses, URLs, phone numbers, plain text).
/// On the web it also selects the `inputmode` attribute for mobile browsers.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
pub enum ImePurposeHint {
    #[default]
    Normal,
    Password,
    Email,
    Url,
    Phone,
    Number,
}

impl KeyboardType {
    /// Map this keyboard type to the coarser platform IME purpose.
    pub fn ime_purpose_hint(self) -> ImePurposeHint {
        use KeyboardType::*;
        match self {
            Password
            | NumberPassword
            | DecimalPassword
            | NumberPasswordSigned
            | DecimalPasswordSigned => ImePurposeHint::Password,
            Email | EmailSubject => ImePurposeHint::Email,
            Uri => ImePurposeHint::Url,
            Phone => ImePurposeHint::Phone,
            Number | NumberSigned | Decimal | DecimalSigned => ImePurposeHint::Number,
            _ => ImePurposeHint::Normal,
        }
    }
}

/// Scope provided to `KeyboardActions` callbacks, allowing fallback to the
/// platform's default IME action behavior. Corresponds to Compose's `KeyboardActionScope`.
pub trait KeyboardActionScope {
    fn default_keyboard_action(&self, action: ImeAction);
}

/// Callbacks for IME action button presses on the soft keyboard.
/// Corresponds to Compose's legacy `KeyboardActions`.
#[derive(Clone, Default)]
pub struct KeyboardActions {
    pub on_done: Option<Rc<dyn Fn(&dyn KeyboardActionScope)>>,
    pub on_go: Option<Rc<dyn Fn(&dyn KeyboardActionScope)>>,
    pub on_next: Option<Rc<dyn Fn(&dyn KeyboardActionScope)>>,
    pub on_previous: Option<Rc<dyn Fn(&dyn KeyboardActionScope)>>,
    pub on_search: Option<Rc<dyn Fn(&dyn KeyboardActionScope)>>,
    pub on_send: Option<Rc<dyn Fn(&dyn KeyboardActionScope)>>,
}

impl KeyboardActions {
    pub fn on_any(f: impl Fn(ImeAction, &dyn KeyboardActionScope) + 'static) -> Self {
        let f = Rc::new(f);
        KeyboardActions {
            on_done: Some({
                let f = f.clone();
                Rc::new(move |scope| f(ImeAction::Done, scope))
            }),
            on_go: Some({
                let f = f.clone();
                Rc::new(move |scope| f(ImeAction::Go, scope))
            }),
            on_next: Some({
                let f = f.clone();
                Rc::new(move |scope| f(ImeAction::Next, scope))
            }),
            on_previous: Some({
                let f = f.clone();
                Rc::new(move |scope| f(ImeAction::Previous, scope))
            }),
            on_search: Some({
                let f = f.clone();
                Rc::new(move |scope| f(ImeAction::Search, scope))
            }),
            on_send: Some(Rc::new(move |scope| f(ImeAction::Send, scope))),
        }
    }
}

/// Handles IME action button presses. Single-callback interface used by the
/// new `BasicTextField(state, ...)` API. Corresponds to Compose's `KeyboardActionHandler`.
pub trait KeyboardActionHandler: Debug + 'static {
    fn on_keyboard_action(&self, perform_default: &dyn Fn());
}

/// A simple `KeyboardActionHandler` that only executes the default behavior.
#[derive(Clone, Copy, Debug)]
pub struct DefaultKeyboardActionHandler;

impl KeyboardActionHandler for DefaultKeyboardActionHandler {
    fn on_keyboard_action(&self, perform_default: &dyn Fn()) {
        perform_default();
    }
}

/// Mutable text buffer used as the scope for `InputTransformation` and
/// `OutputTransformation`. Corresponds to Compose's `TextFieldBuffer`.
pub trait TextFieldBuffer {
    fn text(&self) -> &str;
    fn set_text(&mut self, text: &str);
    fn selection(&self) -> TextRange;
    fn set_selection(&mut self, sel: TextRange);
    fn length(&self) -> usize;
    fn replace(&mut self, start: usize, end: usize, text: &str);
    fn insert(&mut self, index: usize, text: &str);
    fn delete(&mut self, start: usize, end: usize);
    fn place_cursor_before_char_at(&mut self, index: usize);
    fn place_cursor_at_end(&mut self);
    fn select_all(&mut self);
    fn revert_all_changes(&mut self);
    fn original_text(&self) -> &str;
    fn original_selection(&self) -> TextRange;
    fn has_selection(&self) -> bool;
}

/// Limits on the number of visible lines in a text field.
/// Corresponds to Compose's `TextFieldLineLimits`.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum TextFieldLineLimits {
    SingleLine,
    MultiLine {
        min_height_in_lines: usize,
        max_height_in_lines: usize,
    },
}

impl TextFieldLineLimits {
    pub fn default() -> Self {
        TextFieldLineLimits::MultiLine {
            min_height_in_lines: 1,
            max_height_in_lines: usize::MAX,
        }
    }
}

/// Wraps the inner text field with custom decorations.
/// Corresponds to Compose's `TextFieldDecorator`.
pub trait TextFieldDecorator: Debug + 'static {
    fn decorate(&self, inner: crate::View) -> crate::View;
}

/// A `TextFieldDecorator` that passes through the inner text field unchanged.
#[derive(Clone, Copy, Debug)]
pub struct DefaultTextFieldDecorator;

impl TextFieldDecorator for DefaultTextFieldDecorator {
    fn decorate(&self, inner: crate::View) -> crate::View {
        inner
    }
}

/// Transforms user input before it is applied to the text field.
/// Corresponds to Compose's `InputTransformation`.
pub trait InputTransformation: Debug + 'static {
    fn keyboard_options(&self) -> Option<KeyboardOptions> {
        None
    }
    fn transform_input(&self, buffer: &mut dyn TextFieldBuffer);
}

/// Transforms text output for display.
/// Corresponds to Compose's `OutputTransformation`.
pub trait OutputTransformation: Debug + 'static {
    fn transform_output(&self, buffer: &mut dyn TextFieldBuffer);
}

/// Internal 1-to-1 codepoint transformation for password obfuscation.
/// Corresponds to Compose's `CodepointTransformation`.
pub struct CodepointTransformation {
    pub transform: Box<dyn Fn(usize, char) -> char>,
}

impl Clone for CodepointTransformation {
    fn clone(&self) -> Self {
        // Cannot clone Box<dyn Fn>; this is for internal use only.
        // In practice, CodepointTransformation is passed as an Option and
        // constructed fresh each time. If clone is needed, wrap the Fn in Rc.
        panic!("CodepointTransformation::clone() is not supported -> use Rc instead");
    }
}

impl CodepointTransformation {
    pub fn new(transform: impl Fn(usize, char) -> char + 'static) -> Self {
        CodepointTransformation {
            transform: Box::new(transform),
        }
    }

    pub fn transform(&self, codepoint_index: usize, codepoint: char) -> char {
        (self.transform)(codepoint_index, codepoint)
    }
}

/// Input transformation settings: keyboard type, capitalization, and IME action.
/// Corresponds to Compose's `KeyboardOptions`.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct KeyboardOptions {
    pub keyboard_type: KeyboardType,
    pub capitalization: KeyboardCapitalization,
    pub ime_action: ImeAction,
    pub auto_correct_enabled: Option<bool>,
    pub show_keyboard_on_focus: Option<bool>,
    pub platform_ime_options: Option<&'static str>,
    pub hint_locales: Option<&'static str>,
}

impl KeyboardOptions {
    pub const DEFAULT: KeyboardOptions = KeyboardOptions {
        keyboard_type: KeyboardType::Text,
        capitalization: KeyboardCapitalization::Unspecified,
        ime_action: ImeAction::Unspecified,
        auto_correct_enabled: None,
        show_keyboard_on_focus: None,
        platform_ime_options: None,
        hint_locales: None,
    };

    pub const SECURE_TEXT_FIELD: KeyboardOptions = KeyboardOptions {
        keyboard_type: KeyboardType::Password,
        capitalization: KeyboardCapitalization::Unspecified,
        ime_action: ImeAction::Unspecified,
        auto_correct_enabled: Some(false),
        show_keyboard_on_focus: None,
        platform_ime_options: None,
        hint_locales: None,
    };

    pub fn fill_unspecified_values_with(&self, other: Option<&KeyboardOptions>) -> KeyboardOptions {
        let other = match other {
            Some(o) => o,
            None => return *self,
        };
        KeyboardOptions {
            keyboard_type: if self.keyboard_type == KeyboardType::Unspecified {
                other.keyboard_type
            } else {
                self.keyboard_type
            },
            capitalization: if self.capitalization == KeyboardCapitalization::Unspecified {
                other.capitalization
            } else {
                self.capitalization
            },
            ime_action: if self.ime_action == ImeAction::Unspecified {
                other.ime_action
            } else {
                self.ime_action
            },
            auto_correct_enabled: self.auto_correct_enabled.or(other.auto_correct_enabled),
            show_keyboard_on_focus: self.show_keyboard_on_focus.or(other.show_keyboard_on_focus),
            platform_ime_options: self.platform_ime_options.or(other.platform_ime_options),
            hint_locales: self.hint_locales.or(other.hint_locales),
        }
    }

    /// Returns a new [KeyboardOptions] that merges this with [other].
    /// [other]'s null or Unspecified values are replaced with this object's values.
    /// Corresponds to Compose's `KeyboardOptions.merge()`.
    pub fn merge(&self, other: Option<&KeyboardOptions>) -> KeyboardOptions {
        other.map_or(*self, |o| o.fill_unspecified_values_with(Some(self)))
    }
}

impl Default for KeyboardOptions {
    fn default() -> Self {
        Self::DEFAULT
    }
}

#[derive(Debug, Clone, PartialEq)]
pub struct SpanStyle {
    pub color: Option<Color>,
    pub font_size: Option<crate::units::Sp>,
    pub font_weight: Option<u16>,
    pub font_family: Option<&'static str>,
    pub font_style: Option<u8>,
    pub text_align: Option<crate::TextAlign>,
    pub letter_spacing: Option<crate::units::Sp>,
    pub line_height: Option<crate::units::Sp>,
    pub background: Option<Color>,
    pub text_decoration: Option<crate::TextDecoration>,
    pub text_direction: Option<crate::TextDirection>,
    pub font_synthesis: Option<FontSynthesis>,
    pub baseline_shift: Option<BaselineShift>,
    pub hyphens: Option<Hyphens>,
    pub line_break: Option<LineBreak>,
    pub text_indent: Option<TextIndent>,
    pub draw_style: Option<DrawStyle>,
    pub alpha: f32,
    /// OpenType font variation settings (e.g. "wght 700, opsz 24").
    pub font_variation_settings: Option<String>,
}

impl SpanStyle {
    pub const fn default() -> Self {
        Self {
            color: None,
            font_size: None,
            font_weight: None,
            font_family: None,
            font_style: None,
            text_align: None,
            letter_spacing: None,
            line_height: None,
            background: None,
            text_decoration: None,
            text_direction: None,
            font_synthesis: None,
            baseline_shift: None,
            hyphens: None,
            line_break: None,
            text_indent: None,
            draw_style: None,
            alpha: 0.0,
            font_variation_settings: None,
        }
    }

    pub fn color(mut self, c: Color) -> Self {
        self.color = Some(c);
        self
    }

    pub fn font_size(mut self, size: crate::units::Sp) -> Self {
        self.font_size = Some(size);
        self
    }

    pub fn text_decoration(mut self, d: TextDecoration) -> Self {
        self.text_decoration = Some(d);
        self
    }

    pub fn font_weight(mut self, w: u16) -> Self {
        self.font_weight = Some(w);
        self
    }

    pub fn font_style(mut self, s: u8) -> Self {
        self.font_style = Some(s);
        self
    }

    pub fn draw_style(mut self, s: DrawStyle) -> Self {
        self.draw_style = Some(s);
        self
    }

    pub fn background(mut self, c: Color) -> Self {
        self.background = Some(c);
        self
    }

    pub fn baseline_shift(mut self, s: BaselineShift) -> Self {
        self.baseline_shift = Some(s);
        self
    }
}

impl Default for SpanStyle {
    fn default() -> Self {
        Self::default()
    }
}

/// A span of text with an associated style.
#[derive(Debug, Clone, PartialEq)]
pub struct TextSpan {
    /// Byte offset start in the original text.
    pub start: usize,
    /// Byte offset end (exclusive) in the original text.
    pub end: usize,
    pub style: SpanStyle,
    /// URL for clickable links.
    pub url: Option<Arc<str>>,
}

/// Text with multiple styled spans.
///
/// Analogous to Compose's `AnnotatedString`.
#[derive(Debug, Clone, PartialEq)]
pub struct AnnotatedString {
    pub text: String,
    pub spans: Arc<[TextSpan]>,
}

impl AnnotatedString {
    pub fn new(text: impl Into<String>, spans: Vec<TextSpan>) -> Self {
        let text = text.into();
        Self {
            text,
            spans: spans.into(),
        }
    }

    pub fn as_str(&self) -> &str {
        &self.text
    }
}

impl From<String> for AnnotatedString {
    fn from(text: String) -> Self {
        Self {
            text,
            spans: Arc::from([]),
        }
    }
}

impl From<&str> for AnnotatedString {
    fn from(text: &str) -> Self {
        Self {
            text: text.to_string(),
            spans: Arc::from([]),
        }
    }
}

/// Builder for constructing an `AnnotatedString`.
#[derive(Default)]
pub struct AnnotatedStringBuilder {
    text: String,
    spans: Vec<TextSpan>,
}

impl AnnotatedStringBuilder {
    pub fn new() -> Self {
        Self::default()
    }

    /// Append plain text (inherits parent style, or default if at top level).
    pub fn push(&mut self, text: &str) -> &mut Self {
        self.text.push_str(text);
        self
    }

    /// Append text with a specific style.
    pub fn push_with_style(&mut self, text: &str, style: SpanStyle) -> &mut Self {
        let start = self.text.len();
        self.text.push_str(text);
        let end = self.text.len();
        if start < end {
            self.spans.push(TextSpan {
                start,
                end,
                style,
                url: None,
            });
        }
        self
    }

    /// Append text in a specific color.
    pub fn push_color(&mut self, text: &str, color: Color) -> &mut Self {
        self.push_with_style(text, SpanStyle::default().color(color))
    }

    /// Append text with a clickable link URL (auto-applies underline + blue color).
    pub fn push_link(&mut self, text: &str, url: impl Into<Arc<str>>) -> &mut Self {
        let start = self.text.len();
        self.text.push_str(text);
        let end = self.text.len();
        if start < end {
            self.spans.push(TextSpan {
                start,
                end,
                style: SpanStyle::default()
                    .color(Color::from_rgba(0x15, 0x76, 0xFF, 255))
                    .text_decoration(TextDecoration::UNDERLINE),
                url: Some(url.into()),
            });
        }
        self
    }

    /// Apply a style to a range of already-appended text.
    pub fn add_style(&mut self, start: usize, end: usize, style: SpanStyle) -> &mut Self {
        if start < end && end <= self.text.len() {
            self.spans.push(TextSpan {
                start,
                end,
                style,
                url: None,
            });
        }
        self
    }

    pub fn build(&mut self) -> AnnotatedString {
        let text = std::mem::take(&mut self.text);
        self.spans.sort_by_key(|s| s.start);
        // Merge overlapping/adjacent spans with same style
        let mut merged: Vec<TextSpan> = Vec::new();
        for span in std::mem::take(&mut self.spans) {
            if let Some(last) = merged.last_mut()
                && last.end == span.start
                && last.style == span.style
            {
                last.end = span.end;
                continue;
            }
            merged.push(span);
        }
        AnnotatedString {
            text,
            spans: merged.into(),
        }
    }
}

/// Horizontal text alignment.
#[derive(Clone, Copy, Debug, Hash, PartialEq, Eq, Default)]
pub enum TextAlign {
    Left,
    Right,
    Center,
    Justify,
    Start,
    End,
    #[default]
    Unspecified,
}

/// Font weight as a numeric value 100-900, matching CSS `font-weight`.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct FontWeight(pub u16);

impl FontWeight {
    pub const THIN: FontWeight = FontWeight(100);
    pub const EXTRA_LIGHT: FontWeight = FontWeight(200);
    pub const LIGHT: FontWeight = FontWeight(300);
    pub const NORMAL: FontWeight = FontWeight(400);
    pub const MEDIUM: FontWeight = FontWeight(500);
    pub const SEMI_BOLD: FontWeight = FontWeight(600);
    pub const BOLD: FontWeight = FontWeight(700);
    pub const EXTRA_BOLD: FontWeight = FontWeight(800);
    pub const BLACK: FontWeight = FontWeight(900);
}

impl Default for FontWeight {
    fn default() -> Self {
        FontWeight::NORMAL
    }
}

/// Font style: normal or italic.
#[derive(Clone, Copy, Debug, Hash, PartialEq, Eq, Default)]
pub enum FontStyle {
    #[default]
    Normal,
    Italic,
}

/// Text decoration state.
#[derive(Clone, Copy, Debug, PartialEq, Default)]
pub struct TextDecoration {
    pub underline: bool,
    pub strikethrough: bool,
    pub color: Option<Color>,
}

impl TextDecoration {
    pub const UNDERLINE: TextDecoration = TextDecoration {
        underline: true,
        strikethrough: false,
        color: None,
    };
    pub const STRIKETHROUGH: TextDecoration = TextDecoration {
        underline: false,
        strikethrough: true,
        color: None,
    };
}

/// Convenience function to build an `AnnotatedString`.
pub fn build_annotated_string(b: impl FnOnce(&mut AnnotatedStringBuilder)) -> AnnotatedString {
    let mut builder = AnnotatedStringBuilder::new();
    b(&mut builder);
    builder.build()
}