xref: /compose/ui/ui-text/src/androidMain/kotlin/androidx/compose/ui/text/platform/extensions/SpannableExtensions.android.kt

/*
 * Copyright 2020 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package androidx.compose.ui.text.platform.extensions

import android.graphics.Typeface
import android.os.Build
import android.text.Spannable
import android.text.Spanned
import android.text.style.AbsoluteSizeSpan
import android.text.style.BackgroundColorSpan
import android.text.style.ForegroundColorSpan
import android.text.style.LeadingMarginSpan
import android.text.style.LocaleSpan
import android.text.style.MetricAffectingSpan
import android.text.style.RelativeSizeSpan
import android.text.style.ScaleXSpan
import androidx.compose.ui.graphics.Brush
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.ShaderBrush
import androidx.compose.ui.graphics.Shadow
import androidx.compose.ui.graphics.SolidColor
import androidx.compose.ui.graphics.drawscope.DrawStyle
import androidx.compose.ui.graphics.isSpecified
import androidx.compose.ui.graphics.toArgb
import androidx.compose.ui.text.AnnotatedString
import androidx.compose.ui.text.Bullet
import androidx.compose.ui.text.SpanStyle
import androidx.compose.ui.text.TextStyle
import androidx.compose.ui.text.android.InternalPlatformTextApi
import androidx.compose.ui.text.android.style.BaselineShiftSpan
import androidx.compose.ui.text.android.style.FontFeatureSpan
import androidx.compose.ui.text.android.style.LetterSpacingSpanEm
import androidx.compose.ui.text.android.style.LetterSpacingSpanPx
import androidx.compose.ui.text.android.style.LineHeightSpan
import androidx.compose.ui.text.android.style.LineHeightStyleSpan
import androidx.compose.ui.text.android.style.ShadowSpan
import androidx.compose.ui.text.android.style.SkewXSpan
import androidx.compose.ui.text.android.style.TextDecorationSpan
import androidx.compose.ui.text.android.style.TypefaceSpan
import androidx.compose.ui.text.font.FontFamily
import androidx.compose.ui.text.font.FontStyle
import androidx.compose.ui.text.font.FontSynthesis
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.text.intersect
import androidx.compose.ui.text.intl.Locale
import androidx.compose.ui.text.intl.LocaleList
import androidx.compose.ui.text.platform.style.CustomBulletSpan
import androidx.compose.ui.text.platform.style.DrawStyleSpan
import androidx.compose.ui.text.platform.style.ShaderBrushSpan
import androidx.compose.ui.text.style.BaselineShift
import androidx.compose.ui.text.style.LineHeightStyle
import androidx.compose.ui.text.style.TextDecoration
import androidx.compose.ui.text.style.TextGeometricTransform
import androidx.compose.ui.text.style.TextIndent
import androidx.compose.ui.unit.Density
import androidx.compose.ui.unit.TextUnit
import androidx.compose.ui.unit.TextUnitType
import androidx.compose.ui.unit.isUnspecified
import androidx.compose.ui.unit.sp
import androidx.compose.ui.util.fastFilteredMap
import androidx.compose.ui.util.fastForEach
import androidx.compose.ui.util.fastForEachIndexed
import kotlin.math.ceil
import kotlin.math.roundToInt

internal fun Spannable.setSpan(span: Any, start: Int, end: Int) {
    setSpan(span, start, end, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE)
}

@Suppress("DEPRECATION")
internal fun Spannable.setTextIndent(
    textIndent: TextIndent?,
    contextFontSize: Float,
    density: Density
) {
    textIndent?.let { indent ->
        if (indent.firstLine == 0.sp && indent.restLine == 0.sp) return@let
        if (indent.firstLine.isUnspecified || indent.restLine.isUnspecified) return@let
        with(density) {
            val firstLine =
                when (indent.firstLine.type) {
                    TextUnitType.Sp -> indent.firstLine.toPx()
                    TextUnitType.Em -> indent.firstLine.value * contextFontSize
                    else -> 0f
                }
            val restLine =
                when (indent.restLine.type) {
                    TextUnitType.Sp -> indent.restLine.toPx()
                    TextUnitType.Em -> indent.restLine.value * contextFontSize
                    else -> 0f
                }
            setSpan(
                LeadingMarginSpan.Standard(ceil(firstLine).toInt(), ceil(restLine).toInt()),
                0,
                length
            )
        }
    }
}

/**
 * This implementation of the bullet span only draws the bullet. The actual indentation is added
 * already inside the [setTextIndent] call since each bullet is a paragraph. The only exception is
 * when there isn't enough space to put the bullet with its padding, in that case a minimum required
 * space will be added.
 *
 * @param contextFontSize the font size that all text in this paragraph is drawn with
 */
internal fun Spannable.setBulletSpans(
    annotations: List<AnnotatedString.Range<out AnnotatedString.Annotation>>,
    contextFontSize: Float,
    density: Density,
    textIndent: TextIndent?
) {
    val textIndentPx =
        textIndent?.let {
            with(density) {
                when (textIndent.firstLine.type) {
                    TextUnitType.Sp -> textIndent.firstLine.toPx()
                    TextUnitType.Em -> textIndent.firstLine.value * contextFontSize
                    else -> 0f
                }
            }
        } ?: 0f
    annotations.fastForEach {
        (it.item as? Bullet)?.let { bullet ->
            val bulletSize = resolveBulletTextUnitToPx(bullet.size, contextFontSize, density)
            val gapWidthPx = resolveBulletTextUnitToPx(bullet.padding, contextFontSize, density)
            if (!bulletSize.isNaN() && !gapWidthPx.isNaN()) {
                setSpan(
                    CustomBulletSpan(
                        shape = bullet.shape,
                        bulletWidthPx = bulletSize,
                        bulletHeightPx = bulletSize,
                        gapWidthPx = gapWidthPx,
                        density = density,
                        brush = bullet.brush,
                        alpha = bullet.alpha,
                        drawStyle = bullet.drawStyle,
                        textIndentPx = textIndentPx
                    ),
                    it.start,
                    it.end
                )
            }
        }
    }
}

/**
 * Resolves bullet's size or gap size [size] to pixels. If unknown [TextUnitType] is used, returns
 * [Float.NaN] that needs to be handled on caller site.
 */
private fun resolveBulletTextUnitToPx(
    size: TextUnit,
    contextFontSize: Float,
    density: Density
): Float {
    if (size == TextUnit.Unspecified) return contextFontSize
    return when (size.type) {
        TextUnitType.Sp -> {
            // if non-linear font scaling is enabled, this is handled by toPx() conversion already
            with(density) { size.toPx() }
        }
        TextUnitType.Em -> size.value * contextFontSize
        else -> Float.NaN
    }
}

internal fun Spannable.setLineHeight(
    lineHeight: TextUnit,
    contextFontSize: Float,
    density: Density,
    lineHeightStyle: LineHeightStyle
) {
    val resolvedLineHeight = resolveLineHeightInPx(lineHeight, contextFontSize, density)
    if (!resolvedLineHeight.isNaN()) {
        // in order to handle empty lines (including empty text) better, change endIndex so that
        // it won't apply trimLastLineBottom rule
        val endIndex = if (isEmpty() || last() == '\n') length + 1 else length
        setSpan(
            span =
                LineHeightStyleSpan(
                    lineHeight = resolvedLineHeight,
                    startIndex = 0,
                    endIndex = endIndex,
                    trimFirstLineTop = lineHeightStyle.trim.isTrimFirstLineTop(),
                    trimLastLineBottom = lineHeightStyle.trim.isTrimLastLineBottom(),
                    topRatio = lineHeightStyle.alignment.topRatio,
                    preserveMinimumHeight = lineHeightStyle.mode == LineHeightStyle.Mode.Minimum,
                ),
            start = 0,
            end = length
        )
    }
}

@OptIn(InternalPlatformTextApi::class)
internal fun Spannable.setLineHeight(
    lineHeight: TextUnit,
    contextFontSize: Float,
    density: Density
) {
    val resolvedLineHeight = resolveLineHeightInPx(lineHeight, contextFontSize, density)
    if (!resolvedLineHeight.isNaN()) {
        setSpan(span = LineHeightSpan(lineHeight = resolvedLineHeight), start = 0, end = length)
    }
}

private fun resolveLineHeightInPx(
    lineHeight: TextUnit,
    contextFontSize: Float,
    density: Density
): Float {
    return when (lineHeight.type) {
        TextUnitType.Sp -> {
            if (!isNonLinearFontScalingActive(density)) {
                // Non-linear font scaling is not being used, this SP is safe to use directly.
                with(density) { lineHeight.toPx() }
            } else {
                // Determine the intended line height multiplier and use that, since non-linear font
                // scaling may compress the line height if it is much larger than the font size.
                // i.e. preserve the original proportions rather than the absolute converted value.
                val fontSizeSp = with(density) { contextFontSize.toSp() }
                val lineHeightMultiplier = lineHeight.value / fontSizeSp.value
                lineHeightMultiplier * contextFontSize
            }
        }
        TextUnitType.Em -> lineHeight.value * contextFontSize
        else -> Float.NaN
    }
}

// TODO(b/294384826): replace this with the actual platform method once available in core
private fun isNonLinearFontScalingActive(density: Density) = density.fontScale > 1.05

internal fun Spannable.setSpanStyles(
    contextTextStyle: TextStyle,
    annotations: List<AnnotatedString.Range<out AnnotatedString.Annotation>>,
    density: Density,
    resolveTypeface: (FontFamily?, FontWeight, FontStyle, FontSynthesis) -> Typeface,
) {

    setFontAttributes(contextTextStyle, annotations, resolveTypeface)
    var hasLetterSpacing = false
    for (i in annotations.indices) {
        val annotationRange = annotations[i]
        if (annotationRange.item !is SpanStyle) continue
        val start = annotationRange.start
        val end = annotationRange.end

        if (start < 0 || start >= length || end <= start || end > length) continue

        setSpanStyle(annotationRange.item, start, end, density)

        if (annotationRange.item.needsLetterSpacingSpan) {
            hasLetterSpacing = true
        }
    }

    if (hasLetterSpacing) {

        // LetterSpacingSpanPx/LetterSpacingSpanSP has lower priority than normal spans. Because
        // letterSpacing relies on the fontSize on [Paint] to compute Px/Sp from Em. So it must be
        // applied after all spans that changes the fontSize.

        for (i in annotations.indices) {
            val spanStyleRange = annotations[i]
            val style = spanStyleRange.item
            if (style !is SpanStyle) continue
            val start = spanStyleRange.start
            val end = spanStyleRange.end
            if (start < 0 || start >= length || end <= start || end > length) continue

            createLetterSpacingSpan(style.letterSpacing, density)?.let { setSpan(it, start, end) }
        }
    }
}

private fun Spannable.setSpanStyle(style: SpanStyle, start: Int, end: Int, density: Density) {
    // Be aware that SuperscriptSpan needs to be applied before all other spans which
    // affect FontMetrics
    setBaselineShift(style.baselineShift, start, end)

    setColor(style.color, start, end)

    setBrush(style.brush, style.alpha, start, end)

    setTextDecoration(style.textDecoration, start, end)

    setFontSize(style.fontSize, density, start, end)

    setFontFeatureSettings(style.fontFeatureSettings, start, end)

    setGeometricTransform(style.textGeometricTransform, start, end)

    setLocaleList(style.localeList, start, end)

    setBackground(style.background, start, end)

    setShadow(style.shadow, start, end)

    setDrawStyle(style.drawStyle, start, end)
}

/**
 * Set font related [SpanStyle]s to this [Spannable].
 *
 * Different from other styles, font related styles needs to be flattened first and then applied.
 * This is required because on certain API levels the [FontWeight] is not supported by framework,
 * and we have to resolve font settings and create typeface first and then set it directly on
 * TextPaint.
 *
 * Notice that a [contextTextStyle] is also required when we flatten the font related styles. For
 * example: the entire text has the TextStyle(fontFamily = Sans-serif) Hi Hello World [ bold ]
 * FontWeight.Bold is set in range
 * [0, 8). The resolved TypefaceSpan should be TypefaceSpan("Sans-serif", "bold") in range [0, 8). As demonstrated above, the fontFamily information is from [contextTextStyle].
 *
 * @param contextTextStyle the global [TextStyle] for the entire string.
 * @param annotations the [annotations] to be applied, this function will first filter out the font
 *   related [SpanStyle]s and then apply them to this [Spannable].
 * @param resolveTypeface the lambda used to resolve font.
 * @see flattenFontStylesAndApply
 */
private fun Spannable.setFontAttributes(
    contextTextStyle: TextStyle,
    annotations: List<AnnotatedString.Range<out AnnotatedString.Annotation>>,
    resolveTypeface: (FontFamily?, FontWeight, FontStyle, FontSynthesis) -> Typeface,
) {
    @Suppress("UNCHECKED_CAST")
    val fontRelatedSpanStyles =
        annotations.fastFilteredMap({
            it.item is SpanStyle && (it.item.hasFontAttributes() || it.item.fontSynthesis != null)
        }) {
            it as AnnotatedString.Range<SpanStyle>
        }

    // Create a SpanStyle if contextTextStyle has font related attributes, otherwise use
    // null to avoid unnecessary object creation.
    val contextFontSpanStyle =
        if (contextTextStyle.hasFontAttributes()) {
            SpanStyle(
                fontFamily = contextTextStyle.fontFamily,
                fontWeight = contextTextStyle.fontWeight,
                fontStyle = contextTextStyle.fontStyle,
                fontSynthesis = contextTextStyle.fontSynthesis
            )
        } else {
            null
        }

    flattenFontStylesAndApply(contextFontSpanStyle, fontRelatedSpanStyles) { spanStyle, start, end
        ->
        setSpan(
            TypefaceSpan(
                resolveTypeface(
                    spanStyle.fontFamily,
                    spanStyle.fontWeight ?: FontWeight.Normal,
                    spanStyle.fontStyle ?: FontStyle.Normal,
                    spanStyle.fontSynthesis ?: FontSynthesis.All
                )
            ),
            start,
            end,
            Spanned.SPAN_EXCLUSIVE_EXCLUSIVE
        )
    }
}

/**
 * Flatten styles in the [spanStyles], so that overlapping styles are merged, and then apply the
 * [block] on the merged [SpanStyle].
 *
 * @param contextFontSpanStyle the global [SpanStyle]. It act as if every [spanStyles] is applied on
 *   top of it. This parameter is nullable. A null value is exactly the same as a default SpanStyle,
 *   but avoids unnecessary object creation.
 * @param spanStyles the input [SpanStyle] ranges to be flattened.
 * @param block the function to be applied on the merged [SpanStyle].
 */
internal fun flattenFontStylesAndApply(
    contextFontSpanStyle: SpanStyle?,
    spanStyles: List<AnnotatedString.Range<SpanStyle>>,
    block: (SpanStyle, Int, Int) -> Unit
) {
    // quick way out for single SpanStyle or empty list.
    if (spanStyles.size <= 1) {
        if (spanStyles.isNotEmpty()) {
            block(
                contextFontSpanStyle.merge(spanStyles[0].item),
                spanStyles[0].start,
                spanStyles[0].end
            )
        }
        return
    }

    // Sort all span start and end points.
    // S1--S2--E1--S3--E3--E2
    val spanCount = spanStyles.size
    val transitionOffsets = IntArray(spanCount * 2)
    spanStyles.fastForEachIndexed { idx, spanStyle ->
        transitionOffsets[idx] = spanStyle.start
        transitionOffsets[idx + spanCount] = spanStyle.end
    }
    transitionOffsets.sort()

    // S1--S2--E1--S3--E3--E2
    // - Go through all minimum intervals
    // - Find Spans that intersect with the given interval
    // - Merge all spans in order, starting from contextFontSpanStyle
    // - Apply the merged SpanStyle to the minimal interval
    var lastTransitionOffsets = transitionOffsets.first()
    for (transitionOffset in transitionOffsets) {
        // There might be duplicated transition offsets, we skip them here.
        if (transitionOffset == lastTransitionOffsets) {
            continue
        }

        // Check all spans that intersects with this transition range.
        var mergedSpanStyle = contextFontSpanStyle
        spanStyles.fastForEach { spanStyle ->
            // Empty spans do not intersect with anything, skip them.
            if (
                spanStyle.start != spanStyle.end &&
                    intersect(
                        lastTransitionOffsets,
                        transitionOffset,
                        spanStyle.start,
                        spanStyle.end
                    )
            ) {
                mergedSpanStyle = mergedSpanStyle.merge(spanStyle.item)
            }
        }

        mergedSpanStyle?.let { block(it, lastTransitionOffsets, transitionOffset) }

        lastTransitionOffsets = transitionOffset
    }
}

@OptIn(InternalPlatformTextApi::class)
@Suppress("DEPRECATION")
private fun createLetterSpacingSpan(
    letterSpacing: TextUnit,
    density: Density
): MetricAffectingSpan? {
    return when (letterSpacing.type) {
        TextUnitType.Sp -> with(density) { LetterSpacingSpanPx(letterSpacing.toPx()) }
        TextUnitType.Em -> {
            LetterSpacingSpanEm(letterSpacing.value)
        }
        else -> {
            null
        }
    }
}

private val SpanStyle.needsLetterSpacingSpan: Boolean
    get() = letterSpacing.type == TextUnitType.Sp || letterSpacing.type == TextUnitType.Em

@OptIn(InternalPlatformTextApi::class)
private fun Spannable.setShadow(shadow: Shadow?, start: Int, end: Int) {
    shadow?.let {
        setSpan(
            ShadowSpan(
                it.color.toArgb(),
                it.offset.x,
                it.offset.y,
                correctBlurRadius(it.blurRadius)
            ),
            start,
            end
        )
    }
}

@OptIn(InternalPlatformTextApi::class)
private fun Spannable.setDrawStyle(drawStyle: DrawStyle?, start: Int, end: Int) {
    drawStyle?.let { setSpan(DrawStyleSpan(it), start, end) }
}

internal fun Spannable.setBackground(color: Color, start: Int, end: Int) {
    if (color.isSpecified) {
        setSpan(BackgroundColorSpan(color.toArgb()), start, end)
    }
}

internal fun Spannable.setLocaleList(localeList: LocaleList?, start: Int, end: Int) {
    localeList?.let {
        setSpan(
            if (Build.VERSION.SDK_INT >= 24) {
                LocaleListHelperMethods.localeSpan(it)
            } else {
                val locale = if (it.isEmpty()) Locale.current else it[0]
                LocaleSpan(locale.platformLocale)
            },
            start,
            end
        )
    }
}

@OptIn(InternalPlatformTextApi::class)
private fun Spannable.setGeometricTransform(
    textGeometricTransform: TextGeometricTransform?,
    start: Int,
    end: Int
) {
    textGeometricTransform?.let {
        setSpan(ScaleXSpan(it.scaleX), start, end)
        setSpan(SkewXSpan(it.skewX), start, end)
    }
}

@OptIn(InternalPlatformTextApi::class)
private fun Spannable.setFontFeatureSettings(fontFeatureSettings: String?, start: Int, end: Int) {
    fontFeatureSettings?.let { setSpan(FontFeatureSpan(it), start, end) }
}

@Suppress("DEPRECATION")
internal fun Spannable.setFontSize(fontSize: TextUnit, density: Density, start: Int, end: Int) {
    when (fontSize.type) {
        TextUnitType.Sp ->
            with(density) {
                setSpan(
                    AbsoluteSizeSpan(/* size */ fontSize.toPx().roundToInt(), /* dip */ false),
                    start,
                    end
                )
            }
        TextUnitType.Em -> {
            setSpan(RelativeSizeSpan(fontSize.value), start, end)
        }
        else -> {} // Do nothing
    }
}

@OptIn(InternalPlatformTextApi::class)
internal fun Spannable.setTextDecoration(textDecoration: TextDecoration?, start: Int, end: Int) {
    textDecoration?.let {
        val textDecorationSpan =
            TextDecorationSpan(
                isUnderlineText = TextDecoration.Underline in it,
                isStrikethroughText = TextDecoration.LineThrough in it
            )
        setSpan(textDecorationSpan, start, end)
    }
}

internal fun Spannable.setColor(color: Color, start: Int, end: Int) {
    if (color.isSpecified) {
        setSpan(ForegroundColorSpan(color.toArgb()), start, end)
    }
}

@OptIn(InternalPlatformTextApi::class)
private fun Spannable.setBaselineShift(baselineShift: BaselineShift?, start: Int, end: Int) {
    baselineShift?.let { setSpan(BaselineShiftSpan(it.multiplier), start, end) }
}

private fun Spannable.setBrush(brush: Brush?, alpha: Float, start: Int, end: Int) {
    brush?.let {
        when (brush) {
            is SolidColor -> {
                setColor(brush.value, start, end)
            }
            is ShaderBrush -> {
                setSpan(ShaderBrushSpan(brush, alpha), start, end)
            }
        }
    }
}

/**
 * Returns true if there is any font settings on this [TextStyle].
 *
 * @see hasFontAttributes
 */
private fun TextStyle.hasFontAttributes(): Boolean {
    return toSpanStyle().hasFontAttributes() || fontSynthesis != null
}

/** Helper function that merges a nullable [SpanStyle] with another [SpanStyle]. */
private fun SpanStyle?.merge(spanStyle: SpanStyle): SpanStyle {
    if (this == null) return spanStyle
    return this.merge(spanStyle)
}