@hzblj/kara-components 0.13.2 → 0.14.1

package/src/atoms/date-picker/date-picker.android.tsx

@@ -1,7 +1,10 @@
 import {DateTimePicker} from '@expo/ui/community/datetime-picker'
+import {RNHostView} from '@expo/ui/jetpack-compose'
 import {useAppTheme} from '@hzblj/kara-theme'
 import {useCallback, useState} from 'react'
 
+import {useInsideHost} from '../../host-context'
+import {Box} from '../box'
 import {Pressable} from '../pressable'
 import {RnText} from '../rn-text'
 import type {DatePickerComponent, DatePickerMode, DatePickerProps} from './date-picker.types'
@@ -21,6 +24,8 @@ const formatted = (value: Date, mode: DatePickerMode): string => {
 /**
  * The value as a field that opens Material's date picker dialog on a tap. Android's picker *is* a dialog — mounted, it
  * opens — so it is mounted only while open, and unmounted on confirm or dismiss, as the component asks its caller to.
+ * Both are React Native views; inside a `Screen` or `Island` `RNHostView` carries them into that host, sized to the
+ * field (see `useInsideHost`).
  */
 export const DatePicker: DatePickerComponent = ({
   max,
@@ -31,6 +36,7 @@ export const DatePicker: DatePickerComponent = ({
   value,
 }: DatePickerProps) => {
   const theme = useAppTheme()
+  const insideHost = useInsideHost()
   const [open, setOpen] = useState(false)
 
   const show = useCallback(() => setOpen(true), [])
@@ -44,7 +50,7 @@ export const DatePicker: DatePickerComponent = ({
     [onValueChange]
   )
 
-  return (
+  const field = (
     <>
       <Pressable
         alignSelf="flex-start"
@@ -71,4 +77,12 @@ export const DatePicker: DatePickerComponent = ({
       ) : null}
     </>
   )
+
+  return insideHost ? (
+    <RNHostView matchContents>
+      <Box>{field}</Box>
+    </RNHostView>
+  ) : (
+    field
+  )
 }

package/src/atoms/date-picker/date-picker.ios.tsx

@@ -3,6 +3,7 @@ import {datePickerStyle, labelsHidden, tint} from '@expo/ui/swift-ui/modifiers'
 import {useAppTheme} from '@hzblj/kara-theme'
 import {useMemo} from 'react'
 
+import {useInsideHost} from '../../host-context'
 import type {DatePickerComponent, DatePickerMode, DatePickerProps} from './date-picker.types'
 
 const COMPONENTS = {
@@ -15,7 +16,8 @@ const COMPONENTS = {
  * The system's compact date picker: the value in a pill, and a tap on it opens the calendar popover UIKit owns. Its own
  * host, sized to the pill on both axes — a host that took the width it was given would lay the pill out against the
  * far edge of it, or past its container's — so it drops into a row the way a `Text` does. The label is the caller's,
- * beside it; the calendar is in the accent.
+ * beside it; the calendar is in the accent. Inside a `Screen` or `Island` it renders into that host instead (see
+ * `useInsideHost`).
  */
 export const DatePicker: DatePickerComponent = ({
   max,
@@ -26,22 +28,31 @@ export const DatePicker: DatePickerComponent = ({
   value,
 }: DatePickerProps) => {
   const theme = useAppTheme()
+  const insideHost = useInsideHost()
 
   const modifiers = useMemo(
     () => [datePickerStyle('compact'), labelsHidden(), tint(theme.color('fill.accent.primary'))],
     [theme]
   )
 
+  const picker = (
+    <SwiftUIDatePicker
+      displayedComponents={[...COMPONENTS[mode]]}
+      modifiers={modifiers}
+      onDateChange={onValueChange}
+      range={min || max ? {end: max, start: min} : undefined}
+      selection={value}
+      testID={testID}
+    />
+  )
+
+  if (insideHost) {
+    return picker
+  }
+
   return (
     <Host colorScheme={theme.dark ? 'dark' : 'light'} matchContents>
-      <SwiftUIDatePicker
-        displayedComponents={[...COMPONENTS[mode]]}
-        modifiers={modifiers}
-        onDateChange={onValueChange}
-        range={min || max ? {end: max, start: min} : undefined}
-        selection={value}
-        testID={testID}
-      />
+      {picker}
     </Host>
   )
 }

package/src/atoms/date-picker/date-picker.types.ts

@@ -5,7 +5,7 @@ export type DatePickerMode = 'date' | 'datetime' | 'time'
 /**
  * A date or time picker: SwiftUI's compact `DatePicker` on iOS, a field that opens Material's picker dialog on a tap
  * on Android. The React Native tier: it brings its own host and sizes itself to the value, so it sits in a row beside
- * its label like a `Text`.
+ * its label like a `Text`. Inside a `Screen` or `Island` it joins that host instead, beside a native `Text` label.
  */
 export type DatePickerProps = {
   /** The latest date that can be picked. Android ignores it in `time` mode. */

package/src/atoms/picker/picker.android.tsx

@@ -12,7 +12,7 @@ import {useAppTheme} from '@hzblj/kara-theme'
 import {useEffect, useMemo, useState} from 'react'
 
 import {Glyph} from '../../glyph'
-import {HostBoundary} from '../../host-context'
+import {HostBoundary, useInsideHost} from '../../host-context'
 import type {PickerComponent, PickerProps} from './picker.types'
 
 const MATCH_HEIGHT_ONLY = {horizontal: false, vertical: true}
@@ -20,9 +20,12 @@ const MATCH_HEIGHT_ONLY = {horizontal: false, vertical: true}
 /**
  * Material's exposed dropdown: a read-only outlined field the width of its container, opening a menu of the options
  * under it. Its own host, themed like an `Island`, so it drops into React Native layout like the iOS picker does.
+ * Inside a `Screen` or `Island` it renders into that host instead (see `useInsideHost`): a host of its own there
+ * would leave the outer one no width, and the native views beside it would disappear.
  */
 export const Picker: PickerComponent = ({disabled = false, onValueChange, options, testID, value}: PickerProps) => {
   const theme = useAppTheme()
+  const insideHost = useInsideHost()
   const [expanded, setExpanded] = useState(false)
   const selectedLabel = options.find(option => option.value === value)?.label ?? ''
   const label = useNativeState(selectedLabel)
@@ -37,52 +40,58 @@ export const Picker: PickerComponent = ({disabled = false, onValueChange, option
     label.set(selectedLabel)
   }, [label, selectedLabel])
 
-  return (
-    <Host colorScheme={theme.dark ? 'dark' : 'light'} matchContents={MATCH_HEIGHT_ONLY} seedColor={theme.materialSeed}>
-      <HostBoundary>
-        <ExposedDropdownMenuBox expanded={expanded} onExpandedChange={disabled ? undefined : setExpanded}>
-          <OutlinedTextField
-            enabled={!disabled}
-            modifiers={fieldModifiers}
-            readOnly
-            singleLine
-            textStyle={{
-              color: theme.colorString('content.primary'),
-              fontFamily: theme.typography.body.fontFamily,
-              fontWeight: theme.typography.body.fontWeight,
+  const menu = (
+    <ExposedDropdownMenuBox expanded={expanded} onExpandedChange={disabled ? undefined : setExpanded}>
+      <OutlinedTextField
+        enabled={!disabled}
+        modifiers={fieldModifiers}
+        readOnly
+        singleLine
+        textStyle={{
+          color: theme.colorString('content.primary'),
+          fontFamily: theme.typography.body.fontFamily,
+          fontWeight: theme.typography.body.fontWeight,
+        }}
+        value={label}
+      >
+        <OutlinedTextField.TrailingIcon>
+          <Glyph color="content.secondary" name="chevronDown" size="s20" />
+        </OutlinedTextField.TrailingIcon>
+      </OutlinedTextField>
+      <ExposedDropdownMenu
+        containerColor={theme.color('surface.primary')}
+        expanded={expanded}
+        onDismissRequest={() => setExpanded(false)}
+      >
+        {options.map(option => (
+          <DropdownMenuItem
+            key={option.value}
+            onClick={() => {
+              setExpanded(false)
+              onValueChange?.(option.value)
             }}
-            value={label}
           >
-            <OutlinedTextField.TrailingIcon>
-              <Glyph color="content.secondary" name="chevronDown" size="s20" />
-            </OutlinedTextField.TrailingIcon>
-          </OutlinedTextField>
-          <ExposedDropdownMenu
-            containerColor={theme.color('surface.primary')}
-            expanded={expanded}
-            onDismissRequest={() => setExpanded(false)}
-          >
-            {options.map(option => (
-              <DropdownMenuItem
-                key={option.value}
-                onClick={() => {
-                  setExpanded(false)
-                  onValueChange?.(option.value)
-                }}
+            <DropdownMenuItem.Text>
+              <ComposeText
+                color={theme.colorString(option.value === value ? 'content.accent' : 'content.primary')}
+                style={theme.typography.body}
               >
-                <DropdownMenuItem.Text>
-                  <ComposeText
-                    color={theme.colorString(option.value === value ? 'content.accent' : 'content.primary')}
-                    style={theme.typography.body}
-                  >
-                    {option.label}
-                  </ComposeText>
-                </DropdownMenuItem.Text>
-              </DropdownMenuItem>
-            ))}
-          </ExposedDropdownMenu>
-        </ExposedDropdownMenuBox>
-      </HostBoundary>
+                {option.label}
+              </ComposeText>
+            </DropdownMenuItem.Text>
+          </DropdownMenuItem>
+        ))}
+      </ExposedDropdownMenu>
+    </ExposedDropdownMenuBox>
+  )
+
+  if (insideHost) {
+    return menu
+  }
+
+  return (
+    <Host colorScheme={theme.dark ? 'dark' : 'light'} matchContents={MATCH_HEIGHT_ONLY} seedColor={theme.materialSeed}>
+      <HostBoundary>{menu}</HostBoundary>
     </Host>
   )
 }

package/src/atoms/picker/picker.ios.tsx

@@ -1,23 +1,44 @@
 import {Picker as NativePicker} from '@expo/ui/community/picker'
+import {Picker as SwiftUIPicker, Text as SwiftUIText} from '@expo/ui/swift-ui'
+import {disabled as disabledModifier, foregroundStyle, pickerStyle, tag} from '@expo/ui/swift-ui/modifiers'
 import {useAppTheme} from '@hzblj/kara-theme'
-import {useCallback} from 'react'
+import {useCallback, useMemo} from 'react'
 
+import {useInsideHost} from '../../host-context'
 import type {PickerComponent, PickerProps} from './picker.types'
 
+/**
+ * A SwiftUI wheel. On its own it is `@expo/ui`'s community picker, which brings a host of its own. Inside a `Screen` or
+ * `Island` it is the same wheel rendered into that host instead (see `useInsideHost`): a host nested in the island's
+ * stack is given no height there, and the wheel spills over the views around it.
+ */
 export const Picker: PickerComponent = ({disabled = false, onValueChange, options, testID, value}: PickerProps) => {
   const theme = useAppTheme()
+  const insideHost = useInsideHost()
+  const color = theme.colorString('content.primary')
 
   const onChange = useCallback((next: string | number | null) => onValueChange?.(String(next)), [onValueChange])
+  const wheelModifiers = useMemo(
+    () => [pickerStyle('wheel'), ...(disabled ? [disabledModifier(true)] : [])],
+    [disabled]
+  )
+
+  if (insideHost) {
+    return (
+      <SwiftUIPicker modifiers={wheelModifiers} onSelectionChange={onChange} selection={value} testID={testID}>
+        {options.map(option => (
+          <SwiftUIText key={option.value} modifiers={[tag(option.value), foregroundStyle(color)]}>
+            {option.label}
+          </SwiftUIText>
+        ))}
+      </SwiftUIPicker>
+    )
+  }
 
   return (
     <NativePicker enabled={!disabled} onValueChange={onChange} selectedValue={value} testID={testID}>
       {options.map(option => (
-        <NativePicker.Item
-          color={theme.colorString('content.primary')}
-          key={option.value}
-          label={option.label}
-          value={option.value}
-        />
+        <NativePicker.Item color={color} key={option.value} label={option.label} value={option.value} />
       ))}
     </NativePicker>
   )

package/src/atoms/picker/picker.types.ts

@@ -10,7 +10,8 @@ export type PickerOption = {
 
 /**
  * A single choice from a list: a SwiftUI wheel picker on iOS, Material's exposed dropdown on Android. It brings its
- * own host, so it renders outside `Screen` and `Island` as well.
+ * own host, so it renders outside `Screen` and `Island` as well. Inside one it renders into that host instead, so it
+ * can share a stack with other native views.
  */
 export type PickerProps = {
   /** Stops the user changing the selection, and dims the picker. */
@@ -19,7 +20,10 @@ export type PickerProps = {
   onValueChange?: (value: string) => void
   /** The choices, in order. */
   options: PickerOption[]
-  /** Android: the dropdown field's test tag. iOS: `@expo/ui`'s wheel picker drops it. */
+  /**
+   * Android: the dropdown field's test tag. iOS: the wheel's, inside a `Screen` or `Island` only; on its own,
+   * `@expo/ui`'s wheel picker drops it.
+   */
   testID?: string
   /** The selected option's `value`. Controlled: pass back what `onValueChange` reports. */
   value: string

package/src/atoms/segmented-control/segmented-control.android.tsx

@@ -4,6 +4,7 @@ import {haptics} from '@hzblj/expo-rich-haptics'
 import {useAppTheme} from '@hzblj/kara-theme'
 import {useCallback, useMemo} from 'react'
 
+import {useInsideHost} from '../../host-context'
 import type {SegmentedControlComponent, SegmentedControlProps} from './segmented-control.types'
 
 const MATCH_HEIGHT_ONLY = {horizontal: false, vertical: true}
@@ -13,8 +14,9 @@ const SEGMENT = [weight(1)]
 
 /**
  * Material's single-choice segmented buttons, the selected one filled with the accent like a checked `Switch`. Its own
- * host, themed like an `Island`, so it drops into React Native layout the way the iOS control does. Material plays
- * nothing on a new segment, so this plays `selection`.
+ * host, themed like an `Island`, so it drops into React Native layout the way the iOS control does. Inside a `Screen`
+ * or `Island` it renders into that host instead (see `useInsideHost`). Material plays nothing on a new segment, so this
+ * plays `selection`.
  */
 export const SegmentedControl: SegmentedControlComponent = ({
   disabled = false,
@@ -24,6 +26,7 @@ export const SegmentedControl: SegmentedControlComponent = ({
   values,
 }: SegmentedControlProps) => {
   const theme = useAppTheme()
+  const insideHost = useInsideHost()
 
   // Every segment keeps the same outline, the selected one too: an accent border would run its fill out over the line
   // the others draw inside, and make it look taller than its neighbours.
@@ -58,24 +61,32 @@ export const SegmentedControl: SegmentedControlComponent = ({
     [onChange, selectedIndex, values]
   )
 
+  const row = (
+    <SingleChoiceSegmentedButtonRow modifiers={rowModifiers}>
+      {values.map((label, index) => (
+        <SegmentedButton
+          colors={colors}
+          enabled={!disabled}
+          key={index}
+          modifiers={SEGMENT}
+          onClick={() => select(index)}
+          selected={index === selectedIndex}
+        >
+          <SegmentedButton.Label>
+            <Text style={theme.typography.subheadlineMedium}>{label}</Text>
+          </SegmentedButton.Label>
+        </SegmentedButton>
+      ))}
+    </SingleChoiceSegmentedButtonRow>
+  )
+
+  if (insideHost) {
+    return row
+  }
+
   return (
     <Host colorScheme={theme.dark ? 'dark' : 'light'} matchContents={MATCH_HEIGHT_ONLY} seedColor={theme.materialSeed}>
-      <SingleChoiceSegmentedButtonRow modifiers={rowModifiers}>
-        {values.map((label, index) => (
-          <SegmentedButton
-            colors={colors}
-            enabled={!disabled}
-            key={index}
-            modifiers={SEGMENT}
-            onClick={() => select(index)}
-            selected={index === selectedIndex}
-          >
-            <SegmentedButton.Label>
-              <Text style={theme.typography.subheadlineMedium}>{label}</Text>
-            </SegmentedButton.Label>
-          </SegmentedButton>
-        ))}
-      </SingleChoiceSegmentedButtonRow>
+      {row}
     </Host>
   )
 }

package/src/atoms/segmented-control/segmented-control.ios.tsx

@@ -1,13 +1,18 @@
+import {RNHostView} from '@expo/ui/swift-ui'
 import {SegmentedControl as NativeSegmentedControl} from '@hzblj/kara-native/swift-ui'
 import {useAppTheme} from '@hzblj/kara-theme'
 import {useCallback, useMemo} from 'react'
 
+import {useInsideHost} from '../../host-context'
 import type {SegmentedControlComponent, SegmentedControlProps} from './segmented-control.types'
 
+const MATCH_HEIGHT_ONLY = {horizontal: false, vertical: true}
+
 /**
  * kara's own `UISegmentedControl`, with the pill in the accent and white text on it — the system control tints only the
  * pill, and SwiftUI's segmented picker not even that. A plain `UIView` in React Native layout: it needs no host, takes
- * the width it is given and UIKit's height. UIKit plays the control's own feedback.
+ * the width it is given and UIKit's height. Inside a `Screen` or `Island` it is carried into that host by `RNHostView`
+ * (see `useInsideHost`), the host's width and its own height. UIKit plays the control's own feedback.
  */
 export const SegmentedControl: SegmentedControlComponent = ({
   disabled = false,
@@ -17,6 +22,7 @@ export const SegmentedControl: SegmentedControlComponent = ({
   values,
 }: SegmentedControlProps) => {
   const theme = useAppTheme()
+  const insideHost = useInsideHost()
   const face = theme.typography.footnoteMedium
 
   // The native control speaks in values; a segment's is its index, so two labels may read the same.
@@ -30,7 +36,7 @@ export const SegmentedControl: SegmentedControlComponent = ({
     [onChange, values]
   )
 
-  return (
+  const control = (
     <NativeSegmentedControl
       activePillColor={theme.color('fill.accent.primary')}
       activeTextColor={theme.color('content.on.accent')}
@@ -44,4 +50,6 @@ export const SegmentedControl: SegmentedControlComponent = ({
       testID={testID}
     />
   )
+
+  return insideHost ? <RNHostView matchContents={MATCH_HEIGHT_ONLY}>{control}</RNHostView> : control
 }

package/src/atoms/segmented-control/segmented-control.types.ts

@@ -3,7 +3,8 @@ import type {ReactNode} from 'react'
 /**
  * A row of mutually exclusive segments, the selected one in the accent: kara's own `UISegmentedControl` on iOS,
  * Material's single-choice segmented buttons on Android. It needs no `Screen` or `Island`: iOS is a plain view, Android
- * brings its own host. It takes the width it is given; the height is the platform's.
+ * brings its own host. Inside one it joins that host, so it can share a stack with other native views. It takes the
+ * width it is given; the height is the platform's.
  */
 export type SegmentedControlProps = {
   /** Stops the user changing the segment, and dims the control. */

package/src/atoms/text/spans.ts

@@ -0,0 +1,45 @@
+import type {ColorToken} from '@hzblj/kara-theme'
+import {Children, isValidElement, type ReactNode} from 'react'
+
+/** A run of the text: a string child, or a nested `Text` with a colour of its own. */
+export type TextSpan = {color?: ColorToken; text: string}
+
+const textOf = (children: ReactNode): string =>
+  Children.toArray(children)
+    .map(child => (typeof child === 'string' || typeof child === 'number' ? String(child) : ''))
+    .join('')
+
+/**
+ * The children as runs when any of them is a nested `Text` (`type`, the platform's own component), `null` when they
+ * are only text. A span keeps its `color`; anything else it sets is the outer text's.
+ */
+export const spansOf = (children: ReactNode, type: unknown): TextSpan[] | null => {
+  const items = Children.toArray(children)
+
+  if (!items.some(child => isValidElement(child) && child.type === type)) {
+    return null
+  }
+
+  return items.flatMap<TextSpan>(child => {
+    if (typeof child === 'string' || typeof child === 'number') {
+      return [{text: String(child)}]
+    }
+    if (isValidElement<{children?: ReactNode; color?: ColorToken}>(child) && child.type === type) {
+      return [{color: child.props.color, text: textOf(child.props.children)}]
+    }
+    return []
+  })
+}
+
+/** The colours and the text folded into one number, for SwiftUI's `.animation(_:value:)`. A 32-bit FNV-1a hash. */
+export const spansKey = (color: ColorToken, spans: readonly TextSpan[] | null, text: string): number => {
+  let hash = 0x811c9dc5
+  const value = spans ? spans.map(span => `${span.color ?? ''}:${span.text}`).join('|') : text
+
+  for (const character of `${color}|${value}`) {
+    hash ^= character.charCodeAt(0)
+    hash = Math.imul(hash, 0x01000193)
+  }
+
+  return hash >>> 0
+}

package/src/atoms/text/text.android.tsx

@@ -1,10 +1,18 @@
 import {Text as ComposeText} from '@expo/ui/jetpack-compose'
 import {testID as testIdModifier} from '@expo/ui/jetpack-compose/modifiers'
-import {splitAccessibility, useAccessibilityModifiers, useSxModifiers} from '@hzblj/kara-sx'
-import {useAppTheme} from '@hzblj/kara-theme'
+import {AnimatedText, type TextAnimation} from '@hzblj/kara-native/jetpack-compose'
+import {
+  animateConfig,
+  type SxAnimateConfig,
+  splitAccessibility,
+  useAccessibilityModifiers,
+  useSxModifiers,
+} from '@hzblj/kara-sx'
+import {duration, easing, springPhysics, useAppTheme} from '@hzblj/kara-theme'
 import {useMemo} from 'react'
 
 import {useHostGuard} from '../../host-context'
+import {spansOf} from './spans'
 import type {TextComponent, TextDecoration, TextProps, TextTransform} from './text.types'
 
 const DECORATION = {
@@ -24,6 +32,32 @@ const applyTransform = (children: TextProps['children'], transform: TextTransfor
 const decorationOf = (decoration: TextDecoration | undefined) =>
   decoration === undefined ? undefined : DECORATION[decoration]
 
+const transformed = (text: string, transform: TextTransform | undefined) =>
+  transform === 'uppercase' ? text.toUpperCase() : transform === 'lowercase' ? text.toLowerCase() : text
+
+/**
+ * `animate` for the spans' colours, as `@hzblj/kara-sx` animates the rest on Compose: a spring token's physics, and
+ * `smoothOut` as a no-bounce spring over its duration; the other curves as tweens along their béziers.
+ */
+const textAnimation = (config: SxAnimateConfig): TextAnimation => {
+  if (config.spring) {
+    const {dampingRatio, stiffness} = springPhysics(config.spring)
+
+    return {dampingRatio, stiffness, type: 'spring'}
+  }
+
+  const milliseconds = duration[config.duration ?? 'fast']
+  const curve = config.easing ?? 'smoothOut'
+
+  if (curve === 'smoothOut') {
+    const omega = (2 * Math.PI * 1000) / milliseconds
+
+    return {dampingRatio: 1, stiffness: omega * omega, type: 'spring'}
+  }
+
+  return {delayMillis: config.delay, durationMillis: milliseconds, easing: easing[curve], type: 'tween'}
+}
+
 export const Text: TextComponent = ({
   align,
   children,
@@ -45,6 +79,32 @@ export const Text: TextComponent = ({
     () => [...sxModifiers, ...(testID ? [testIdModifier(testID)] : []), ...accessibilityModifiers],
     [accessibilityModifiers, sxModifiers, testID]
   )
+  const spans = useMemo(() => spansOf(children, Text), [children])
+  const animate = sx.animate
+
+  // `@expo/ui`'s text takes spans but animates none: with `animate`, kara's own Compose text eases each span's colour.
+  if (animate !== undefined && animate !== false) {
+    const runs = spans ?? [{text: typeof children === 'string' || typeof children === 'number' ? String(children) : ''}]
+
+    return (
+      <AnimatedText
+        animation={textAnimation(animateConfig(animate))}
+        fontFamily={style.fontFamily}
+        fontSize={style.fontSize}
+        fontWeight={style.fontWeight}
+        lineHeight={style.lineHeight}
+        maxLines={numberOfLines}
+        modifiers={modifiers}
+        spans={runs.map(span => ({
+          color: span.color ? theme.colorString(span.color) : undefined,
+          text: transformed(span.text, transform),
+        }))}
+        textAlign={align}
+        textColor={theme.colorString(color)}
+        textDecoration={decorationOf(decoration)}
+      />
+    )
+  }
 
   return (
     <ComposeText
@@ -60,7 +120,13 @@ export const Text: TextComponent = ({
         textDecoration: decorationOf(decoration),
       }}
     >
-      {applyTransform(children, transform)}
+      {spans
+        ? spans.map((span, index) => (
+            <ComposeText color={span.color ? theme.colorString(span.color) : undefined} key={index}>
+              {transformed(span.text, transform)}
+            </ComposeText>
+          ))
+        : applyTransform(children, transform)}
     </ComposeText>
   )
 }

package/src/atoms/text/text.ios.tsx

@@ -10,11 +10,18 @@ import {
   underline,
 } from '@expo/ui/swift-ui/modifiers'
 import {scaledFont} from '@hzblj/kara-native/swift-ui'
-import {type FrameAlignment, splitAccessibility, useAccessibilityModifiers, useSxModifiers} from '@hzblj/kara-sx'
+import {
+  type FrameAlignment,
+  splitAccessibility,
+  textColorTransition,
+  useAccessibilityModifiers,
+  useSxModifiers,
+} from '@hzblj/kara-sx'
 import {useAppTheme} from '@hzblj/kara-theme'
 import {useMemo} from 'react'
 
 import {useHostGuard} from '../../host-context'
+import {spansKey, spansOf} from './spans'
 import type {TextAlign, TextComponent, TextProps} from './text.types'
 
 const ALIGNMENT = {
@@ -48,6 +55,13 @@ export const Text: TextComponent = ({
   const [accessibility, sx] = splitAccessibility(props)
   const sxModifiers = useSxModifiers(sx, FRAME_ALIGNMENT[align ?? 'left'])
   const accessibilityModifiers = useAccessibilityModifiers(accessibility)
+  const spans = useMemo(() => spansOf(children, Text), [children])
+  const animate = sx.animate
+  // With `animate`, SwiftUI interpolates the text when a colour changes: the text's own or a span's.
+  const transition = useMemo(
+    () => textColorTransition(animate, spansKey(color, spans, typeof children === 'string' ? children : '')),
+    [animate, children, color, spans]
+  )
 
   const modifiers = useMemo(() => {
     const list: ModifierConfig[] = [
@@ -78,12 +92,30 @@ export const Text: TextComponent = ({
       list.push(lineLimit(numberOfLines))
     }
 
-    return [...list, ...sxModifiers, ...accessibilityModifiers]
-  }, [accessibilityModifiers, align, color, decoration, numberOfLines, style, sxModifiers, theme, transform])
+    return [...list, ...transition, ...sxModifiers, ...accessibilityModifiers]
+  }, [
+    accessibilityModifiers,
+    align,
+    color,
+    decoration,
+    numberOfLines,
+    style,
+    sxModifiers,
+    theme,
+    transform,
+    transition,
+  ])
 
   return (
     <SwiftUIText modifiers={modifiers} testID={testID}>
-      {children}
+      {spans
+        ? spans.map((span, index) => (
+            // Concatenated into one SwiftUI `Text`: a span takes its colour, the font and the rest are the outer text's.
+            <SwiftUIText key={index} modifiers={span.color ? [foregroundStyle(theme.color(span.color))] : undefined}>
+              {span.text}
+            </SwiftUIText>
+          ))
+        : children}
     </SwiftUIText>
   )
 }