Text Handling and Typography

/**
 * Configuration object to define the styling of text content.
 */
@Immutable
data class TextStyle(
    val color: Color = Color.Unspecified,
    val fontSize: TextUnit = TextUnit.Unspecified,
    val fontWeight: FontWeight? = null,
    val fontStyle: FontStyle? = null,
    val fontSynthesis: FontSynthesis? = null,
    val fontFamily: FontFamily? = null,
    val fontFeatureSettings: String? = null,
    val letterSpacing: TextUnit = TextUnit.Unspecified,
    val baselineShift: BaselineShift? = null,
    val textGeometricTransform: TextGeometricTransform? = null,
    val localeList: LocaleList? = null,
    val background: Color = Color.Unspecified,
    val textDecoration: TextDecoration? = null,
    val shadow: Shadow? = null,
    val textAlign: TextAlign? = null,
    val textDirection: TextDirection? = null,
    val lineHeight: TextUnit = TextUnit.Unspecified,
    val textIndent: TextIndent? = null,
    val platformStyle: PlatformTextStyle? = null,
    val lineHeightStyle: LineHeightStyle? = null,
    val lineBreak: LineBreak? = null,
    val hyphens: Hyphens? = null
) {
    /**
     * Returns a new text style that is a combination of this style and the given other style.
     */
    fun merge(other: TextStyle? = null): TextStyle
    
    /**
     * Plus operator overload that applies a merge.
     */
    operator fun plus(other: TextStyle): TextStyle
    
    /**
     * Returns a copy of this TextStyle with the given values replaced.
     */
    fun copy(
        color: Color = this.color,
        fontSize: TextUnit = this.fontSize,
        fontWeight: FontWeight? = this.fontWeight,
        fontStyle: FontStyle? = this.fontStyle,
        fontSynthesis: FontSynthesis? = this.fontSynthesis,
        fontFamily: FontFamily? = this.fontFamily,
        fontFeatureSettings: String? = this.fontFeatureSettings,
        letterSpacing: TextUnit = this.letterSpacing,
        baselineShift: BaselineShift? = this.baselineShift,
        textGeometricTransform: TextGeometricTransform? = this.textGeometricTransform,
        localeList: LocaleList? = this.localeList,
        background: Color = this.background,
        textDecoration: TextDecoration? = this.textDecoration,
        shadow: Shadow? = this.shadow,
        textAlign: TextAlign? = this.textAlign,
        textDirection: TextDirection? = this.textDirection,
        lineHeight: TextUnit = this.lineHeight,
        textIndent: TextIndent? = this.textIndent,
        platformStyle: PlatformTextStyle? = this.platformStyle,
        lineHeightStyle: LineHeightStyle? = this.lineHeightStyle,
        lineBreak: LineBreak? = this.lineBreak,
        hyphens: Hyphens? = this.hyphens
    ): TextStyle
    
    companion object {
        /**
         * Constant for default text style.
         */
        val Default: TextStyle
    }
}

/**
 * Font weight values from thin to black.
 */
@Immutable
class FontWeight private constructor(val weight: Int) : Comparable<FontWeight> {
    override fun compareTo(other: FontWeight): Int
    
    companion object {
        val Thin: FontWeight        // 100
        val ExtraLight: FontWeight  // 200
        val Light: FontWeight       // 300
        val Normal: FontWeight      // 400
        val Medium: FontWeight      // 500
        val SemiBold: FontWeight    // 600
        val Bold: FontWeight        // 700
        val ExtraBold: FontWeight   // 800
        val Black: FontWeight       // 900
        
        /**
         * Create a FontWeight with a specific weight value.
         */
        fun W100: FontWeight
        fun W200: FontWeight
        fun W300: FontWeight
        fun W400: FontWeight
        fun W500: FontWeight
        fun W600: FontWeight
        fun W700: FontWeight
        fun W800: FontWeight
        fun W900: FontWeight
    }
}

/**
 * Font style enumeration for normal and italic text.
 */
enum class FontStyle(val value: Int) {
    Normal(0), Italic(1)
}

/**
 * Font synthesis options for generating synthetic font variants.
 */
@Immutable
class FontSynthesis private constructor(val value: Int) {
    companion object {
        val None: FontSynthesis
        val All: FontSynthesis
        val Weight: FontSynthesis
        val Style: FontSynthesis
    }
}

// Basic text styling
val titleStyle = TextStyle(
    fontSize = 24.sp,
    fontWeight = FontWeight.Bold,
    color = Color.Black,
    letterSpacing = 0.5.sp
)

val bodyStyle = TextStyle(
    fontSize = 16.sp,
    fontWeight = FontWeight.Normal,
    lineHeight = 24.sp,
    color = Color.DarkGray
)

// Merging styles
val emphasisStyle = bodyStyle.copy(
    fontWeight = FontWeight.SemiBold,
    fontStyle = FontStyle.Italic
)

// Using styles in Text composables
Text(
    text = "Hello, World!",
    style = titleStyle
)

Text(
    text = "This is body text with custom styling.",
    style = bodyStyle.merge(
        TextStyle(textDecoration = TextDecoration.Underline)
    )
)

/**
 * The base class of font families.
 */
abstract class FontFamily(
    val canLoadSynchronously: Boolean
) {
    companion object {
        /**
         * The platform default font.
         */
        val Default: SystemFontFamily
        
        /**
         * Generic serif font family.
         */
        val Serif: GenericFontFamily
        
        /**
         * Generic sans-serif font family.
         */
        val SansSerif: GenericFontFamily
        
        /**
         * Generic monospace font family.
         */
        val Monospace: GenericFontFamily
        
        /**
         * Generic cursive font family.
         */
        val Cursive: GenericFontFamily
    }
}

/**
 * Defines a font family with explicitly defined fonts.
 */
class FontFamily private constructor(
    val fonts: List<Font>
) : FontFamily(false) {
    constructor(vararg fonts: Font) : this(fonts.toList())
    constructor(font: Font) : this(listOf(font))
}

/**
 * Base class for font definitions.
 */
abstract class Font {
    /**
     * The weight of the font.
     */
    abstract val weight: FontWeight
    
    /**
     * The style of the font.
     */
    abstract val style: FontStyle
    
    /**
     * Load result for font loading.
     */
    sealed class LoadResult {
        class Success(val typeface: Any) : LoadResult()
        class Failure(val exception: Exception) : LoadResult()
    }
}

/**
 * Create a font from a resource.
 */
expect fun Font(
    resId: Int,
    weight: FontWeight = FontWeight.Normal,
    style: FontStyle = FontStyle.Normal
): Font

/**
 * Create a font from a file path.
 */
expect fun Font(
    path: String,
    weight: FontWeight = FontWeight.Normal,
    style: FontStyle = FontStyle.Normal
): Font

/**
 * Create a font from byte array.
 */
expect fun Font(
    data: ByteArray,
    weight: FontWeight = FontWeight.Normal,
    style: FontStyle = FontStyle.Normal
): Font

/**
 * Font loading with suspending functions.
 */
@Composable
fun rememberFontFamily(vararg fonts: Font): State<FontFamily?>

// Using system font families
val titleFamily = FontFamily.Serif
val bodyFamily = FontFamily.SansSerif
val codeFamily = FontFamily.Monospace

// Creating custom font family (platform-specific)
val customFontFamily = FontFamily(
    Font(R.font.my_regular_font, FontWeight.Normal),
    Font(R.font.my_bold_font, FontWeight.Bold),
    Font(R.font.my_italic_font, FontWeight.Normal, FontStyle.Italic)
)

// Using fonts in text styles
val customTextStyle = TextStyle(
    fontFamily = customFontFamily,
    fontSize = 18.sp,
    fontWeight = FontWeight.Bold
)

// Loading fonts asynchronously
@Composable
fun CustomText() {
    val fontFamily by rememberFontFamily(
        Font("path/to/font.ttf", FontWeight.Normal)
    )
    
    fontFamily?.let { family ->
        Text(
            text = "Custom font text",
            style = TextStyle(fontFamily = family)
        )
    }
}

/**
 * Text alignment within its container.
 */
enum class TextAlign {
    Left, Right, Center, Justify, Start, End
}

/**
 * Text direction for bidirectional text support.
 */
enum class TextDirection {
    Ltr, Rtl, Content, ContentOrLtr, ContentOrRtl
}

/**
 * Text overflow handling strategies.
 */
enum class TextOverflow {
    Clip, Ellipsis, Visible
}

/**
 * Text decoration options.
 */
@Immutable
class TextDecoration private constructor(val mask: Int) {
    operator fun plus(decoration: TextDecoration): TextDecoration
    operator fun contains(other: TextDecoration): Boolean
    
    companion object {
        val None: TextDecoration
        val Underline: TextDecoration
        val LineThrough: TextDecoration
        
        /**
         * Combine multiple text decorations.
         */
        fun combine(decorations: List<TextDecoration>): TextDecoration
    }
}

/**
 * Text shadow configuration.
 */
@Immutable
data class Shadow(
    val color: Color = Color.Black,
    val offset: Offset = Offset.Zero,
    val blurRadius: Float = 0.0f
) {
    companion object {
        val None: Shadow
    }
}

/**
 * Text indentation configuration.
 */
@Immutable
data class TextIndent(
    val firstLine: TextUnit = 0.sp,
    val restLine: TextUnit = 0.sp
) {
    companion object {
        val None: TextIndent
    }
}

/**
 * Baseline shift for subscript and superscript text.
 */
@Immutable
class BaselineShift private constructor(val multiplier: Float) {
    companion object {
        val None: BaselineShift
        val Subscript: BaselineShift
        val Superscript: BaselineShift
    }
}

/**
 * Text geometric transformations.
 */
@Immutable
data class TextGeometricTransform(
    val scaleX: Float = 1.0f,
    val skewX: Float = 0.0f
) {
    companion object {
        val None: TextGeometricTransform
    }
}

// Text alignment examples
Text(
    text = "Left aligned text",
    style = TextStyle(textAlign = TextAlign.Left),
    modifier = Modifier.fillMaxWidth()
)

Text(
    text = "Centered text",
    style = TextStyle(textAlign = TextAlign.Center),
    modifier = Modifier.fillMaxWidth()
)

// Text with decorations
Text(
    text = "Underlined text",
    style = TextStyle(
        textDecoration = TextDecoration.Underline,
        color = Color.Blue
    )
)

// Text with shadow
Text(
    text = "Shadow text",
    style = TextStyle(
        shadow = Shadow(
            color = Color.Gray,
            offset = Offset(2.0f, 2.0f),
            blurRadius = 4.0f
        ),
        fontSize = 20.sp
    )
)

// Subscript and superscript
Text(
    text = buildAnnotatedString {
        append("H")
        withStyle(
            style = SpanStyle(
                baselineShift = BaselineShift.Subscript,
                fontSize = 12.sp
            )
        ) {
            append("2")
        }
        append("O")
    }
)

/**
 * Value holder for TextField that contains text, cursor position, and selection range.
 */
@Immutable
class TextFieldValue(
    val text: String,
    val selection: TextRange = TextRange.Zero,
    val composition: TextRange? = null
) {
    /**
     * Returns a copy of this TextFieldValue with the given values replaced.
     */
    fun copy(
        text: String = this.text,
        selection: TextRange = this.selection,
        composition: TextRange? = this.composition
    ): TextFieldValue
    
    companion object {
        /**
         * Default TextFieldValue with empty text.
         */
        val Saver: Saver<TextFieldValue, Any>
    }
}

/**
 * Text range for selection and composition.
 */
@Immutable
data class TextRange(
    val start: Int,
    val end: Int
) {
    /**
     * The minimum offset of the range.
     */
    val min: Int
    
    /**
     * The maximum offset of the range.
     */
    val max: Int
    
    /**
     * The length of the range.
     */
    val length: Int
    
    /**
     * Whether this range represents a collapsed selection.
     */
    val collapsed: Boolean
    
    /**
     * Whether this range represents a reversed selection.
     */
    val reversed: Boolean
    
    companion object {
        val Zero: TextRange
    }
}

/**
 * Keyboard types for different input contexts.
 */
enum class KeyboardType {
    Text, Ascii, Number, Phone, Uri, Email, Password, NumberPassword
}

/**
 * Input method editor (IME) actions.
 */
enum class ImeAction {
    Default, None, Go, Search, Send, Previous, Next, Done
}

/**
 * Capitalization strategies for text input.
 */
enum class KeyboardCapitalization {
    None, Characters, Words, Sentences
}

/**
 * Keyboard options for configuring text input behavior.
 */
@Immutable
data class KeyboardOptions(
    val capitalization: KeyboardCapitalization = KeyboardCapitalization.None,
    val autoCorrect: Boolean = true,
    val keyboardType: KeyboardType = KeyboardType.Text,
    val imeAction: ImeAction = ImeAction.Default
) {
    companion object {
        val Default: KeyboardOptions
    }
}

/**
 * Visual transformation for text input display.
 */
fun interface VisualTransformation {
    /**
     * Transform the text for display.
     */
    fun filter(text: AnnotatedString): TransformedText
    
    companion object {
        /**
         * No transformation applied.
         */
        val None: VisualTransformation
    }
}

/**
 * Password visual transformation that masks input.
 */
class PasswordVisualTransformation(
    val mask: Char = '\u2022'
) : VisualTransformation {
    override fun filter(text: AnnotatedString): TransformedText
}

/**
 * Result of visual transformation.
 */
class TransformedText(
    val text: AnnotatedString,
    val offsetMapping: OffsetMapping
)

/**
 * Maps character offsets between original and transformed text.
 */
interface OffsetMapping {
    /**
     * Convert offset from original to transformed text.
     */
    fun originalToTransformed(offset: Int): Int
    
    /**
     * Convert offset from transformed to original text.
     */
    fun transformedToOriginal(offset: Int): Int
    
    companion object {
        /**
         * Identity mapping (no transformation).
         */
        val Identity: OffsetMapping
    }
}

// Basic text field state
var textState by remember { mutableStateOf(TextFieldValue("")) }

TextField(
    value = textState,
    onValueChange = { textState = it },
    label = { Text("Enter text") }
)

// Password field with visual transformation
var passwordState by remember { mutableStateOf("") }

TextField(
    value = passwordState,
    onValueChange = { passwordState = it },
    label = { Text("Password") },
    visualTransformation = PasswordVisualTransformation(),
    keyboardOptions = KeyboardOptions(
        keyboardType = KeyboardType.Password,
        imeAction = ImeAction.Done
    )
)

// Number input field
var numberState by remember { mutableStateOf("") }

TextField(
    value = numberState,
    onValueChange = { numberState = it },
    label = { Text("Enter number") },
    keyboardOptions = KeyboardOptions(
        keyboardType = KeyboardType.Number,
        imeAction = ImeAction.Next
    )
)

// Email input with auto-correction disabled
var emailState by remember { mutableStateOf("") }

TextField(
    value = emailState,
    onValueChange = { emailState = it },
    label = { Text("Email address") },
    keyboardOptions = KeyboardOptions(
        keyboardType = KeyboardType.Email,
        autoCorrect = false,
        capitalization = KeyboardCapitalization.None
    )
)

/**
 * Text with multiple styles and annotations.
 */
@Immutable
class AnnotatedString(
    val text: String,
    val spanStyles: List<Range<SpanStyle>> = emptyList(),
    val paragraphStyles: List<Range<ParagraphStyle>> = emptyList(),
    val annotations: List<Range<out Any>> = emptyList()
) : CharSequence {
    
    override val length: Int
    override fun get(index: Int): Char
    override fun subSequence(startIndex: Int, endIndex: Int): AnnotatedString
    
    /**
     * Return a substring of this AnnotatedString.
     */
    fun substring(startIndex: Int, endIndex: Int = length): AnnotatedString
    
    /**
     * Plus operator for concatenating AnnotatedStrings.
     */
    operator fun plus(other: AnnotatedString): AnnotatedString
    
    /**
     * Returns a list of annotations attached to this AnnotatedString.
     */
    fun <T : Any> getStringAnnotations(tag: String, start: Int, end: Int): List<Range<T>>
    
    /**
     * Range class for associating data with text ranges.
     */
    @Immutable
    data class Range<T>(
        val item: T,
        val start: Int,
        val end: Int,
        val tag: String = ""
    )
    
    companion object {
        val Saver: Saver<AnnotatedString, Any>
    }
}

/**
 * Styling information that can be applied to a span of text.
 */
@Immutable
data class SpanStyle(
    val color: Color = Color.Unspecified,
    val fontSize: TextUnit = TextUnit.Unspecified,
    val fontWeight: FontWeight? = null,
    val fontStyle: FontStyle? = null,
    val fontSynthesis: FontSynthesis? = null,
    val fontFamily: FontFamily? = null,
    val fontFeatureSettings: String? = null,
    val letterSpacing: TextUnit = TextUnit.Unspecified,
    val baselineShift: BaselineShift? = null,
    val textGeometricTransform: TextGeometricTransform? = null,
    val localeList: LocaleList? = null,
    val background: Color = Color.Unspecified,
    val textDecoration: TextDecoration? = null,
    val shadow: Shadow? = null,
    val platformStyle: PlatformSpanStyle? = null
) {
    /**
     * Returns a new span style that is a combination of this style and the given other style.
     */
    fun merge(other: SpanStyle? = null): SpanStyle
    
    /**
     * Plus operator overload that applies a merge.
     */
    operator fun plus(other: SpanStyle): SpanStyle
}

/**
 * Styling information for paragraphs.
 */
@Immutable
data class ParagraphStyle(
    val textAlign: TextAlign? = null,
    val textDirection: TextDirection? = null,
    val lineHeight: TextUnit = TextUnit.Unspecified,
    val textIndent: TextIndent? = null,
    val platformStyle: PlatformParagraphStyle? = null,
    val lineHeightStyle: LineHeightStyle? = null,
    val lineBreak: LineBreak? = null,
    val hyphens: Hyphens? = null
) {
    /**
     * Returns a new paragraph style that is a combination of this style and the given other style.
     */
    fun merge(other: ParagraphStyle? = null): ParagraphStyle
    
    /**
     * Plus operator overload that applies a merge.
     */
    operator fun plus(other: ParagraphStyle): ParagraphStyle
}

/**
 * Builder for creating AnnotatedStrings with styled content.
 */
class AnnotatedString.Builder(capacity: Int = 16) {
    /**
     * Current length of the built string.
     */
    val length: Int
    
    /**
     * Append text to the builder.
     */
    fun append(text: String)
    fun append(text: Char)
    fun append(text: AnnotatedString)
    
    /**
     * Apply a SpanStyle to the given range.
     */
    fun addStyle(style: SpanStyle, start: Int, end: Int)
    
    /**
     * Apply a ParagraphStyle to the given range.
     */
    fun addStyle(style: ParagraphStyle, start: Int, end: Int)
    
    /**
     * Add an annotation to the given range.
     */
    fun addStringAnnotation(tag: String, annotation: String, start: Int, end: Int)
    
    /**
     * Apply styles within a scope.
     */
    inline fun withStyle(style: SpanStyle, action: AnnotatedString.Builder.() -> Unit): Int
    inline fun withStyle(style: ParagraphStyle, action: AnnotatedString.Builder.() -> Unit): Int
    
    /**
     * Build the final AnnotatedString.
     */
    fun toAnnotatedString(): AnnotatedString
}

/**
 * DSL for building AnnotatedString.
 */
inline fun buildAnnotatedString(
    builder: AnnotatedString.Builder.() -> Unit
): AnnotatedString

// Creating rich text with annotations
val richText = buildAnnotatedString {
    append("Visit our ")
    
    // Add clickable link
    pushStringAnnotation(tag = "URL", annotation = "https://example.com")
    withStyle(style = SpanStyle(color = Color.Blue, textDecoration = TextDecoration.Underline)) {
        append("website")
    }
    pop()
    
    append(" for more information.\n\n")
    
    // Add emphasized text
    withStyle(style = SpanStyle(fontWeight = FontWeight.Bold, fontSize = 18.sp)) {
        append("Important Notice")
    }
    
    append("\nThis text contains ")
    
    // Add styled span
    withStyle(style = SpanStyle(
        color = Color.Red,
        fontStyle = FontStyle.Italic,
        background = Color.Yellow.copy(alpha = 0.3f)
    )) {
        append("highlighted content")
    }
    
    append(" within the paragraph.")
}

// Using the rich text in a Text composable
ClickableText(
    text = richText,
    onClick = { offset ->
        richText.getStringAnnotations(tag = "URL", start = offset, end = offset)
            .firstOrNull()?.let { annotation ->
                // Handle URL click
                println("Clicked URL: ${annotation.item}")
            }
    }
)

// Multi-styled paragraph
val styledText = buildAnnotatedString {
    withStyle(style = ParagraphStyle(textAlign = TextAlign.Center)) {
        withStyle(style = SpanStyle(fontSize = 24.sp, fontWeight = FontWeight.Bold)) {
            append("Centered Title")
        }
    }
    
    append("\n\n")
    
    withStyle(style = ParagraphStyle(textAlign = TextAlign.Justify, lineHeight = 20.sp)) {
        append("This is a justified paragraph with custom line height. ")
        
        withStyle(style = SpanStyle(fontWeight = FontWeight.SemiBold)) {
            append("Bold text")
        }
        
        append(" mixed with ")
        
        withStyle(style = SpanStyle(fontStyle = FontStyle.Italic)) {
            append("italic text")
        }
        
        append(" in the same paragraph.")
    }
}