@hzblj/kara-components 0.17.0 → 0.19.0

package/src/atoms/progress/progress.ios.tsx

@@ -7,7 +7,13 @@ import {useMemo} from 'react'
 import {useHostGuard} from '../../host-context'
 import type {ProgressComponent, ProgressProps} from './progress.types'
 
-export const Progress: ProgressComponent = ({accessibilityLabel, circular = false, value}: ProgressProps) => {
+export const Progress: ProgressComponent = ({
+  accessibilityLabel,
+  circular = false,
+  color = 'fill.accent.primary',
+  testID,
+  value,
+}: ProgressProps) => {
   useHostGuard('Progress')
   const theme = useAppTheme()
   const accessibilityModifiers = useAccessibilityModifiers({accessibilityLabel})
@@ -16,16 +22,16 @@ export const Progress: ProgressComponent = ({accessibilityLabel, circular = fals
   const modifiers = useMemo(
     () => [
       ring ? gaugeStyle('circularCapacity') : progressViewStyle(circular ? 'circular' : 'linear'),
-      tint(theme.color('fill.accent.primary')),
+      tint(theme.color(color)),
       ...accessibilityModifiers,
     ],
-    [accessibilityModifiers, circular, ring, theme]
+    [accessibilityModifiers, circular, color, ring, theme]
   )
 
   // SwiftUI's circular `ProgressView` ignores its value on iOS and spins; a ring that fills is a capacity `Gauge`.
   return ring ? (
-    <Gauge modifiers={modifiers} value={value} />
+    <Gauge modifiers={modifiers} testID={testID} value={value} />
   ) : (
-    <ProgressView modifiers={modifiers} value={value ?? null} />
+    <ProgressView modifiers={modifiers} testID={testID} value={value ?? null} />
   )
 }

package/src/atoms/progress/progress.types.ts

@@ -1,14 +1,25 @@
+import type {ColorToken} from '@hzblj/kara-theme'
 import type {ReactNode} from 'react'
 
 /**
- * A progress bar or ring, tinted `fill.accent.primary`: SwiftUI `ProgressView` (a capacity `Gauge` for a ring with a
- * value, which `ProgressView` cannot draw on iOS) / Compose's `LinearProgressIndicator` and `CircularProgressIndicator`.
+ * A progress bar or ring, tinted `fill.accent.primary` unless `color` names another: SwiftUI `ProgressView` (a capacity
+ * `Gauge` for a ring with a value, which `ProgressView` cannot draw on iOS) / Compose's `LinearProgressIndicator` and
+ * `CircularProgressIndicator`.
  */
 export type ProgressProps = {
   /** What is in progress, for VoiceOver and TalkBack: "Uploading". They read how far along it is themselves. */
   accessibilityLabel?: string
   /** A circular indicator instead of a bar. Off by default. */
   circular?: boolean
+  /**
+   * Its colour: `fill.destructive.primary` for storage nearly full, `fill.success.primary` for a goal reached.
+   * `fill.accent.primary` by default. iOS tints the bar or ring with it. Android draws the indicator in it and, for any
+   * colour but the accent, the track in the same colour faded (Material's own track stays under the accent, and an
+   * indeterminate ring has none).
+   */
+  color?: ColorToken
+  /** Test identifier, forwarded to the native view. */
+  testID?: string
   /** Between `0` and `1`. Leave it unset for an indeterminate indicator. */
   value?: number
 }

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

@@ -1,16 +1,60 @@
 import {Host, SegmentedButton, SingleChoiceSegmentedButtonRow, Text} from '@expo/ui/jetpack-compose'
-import {fillMaxWidth, testID as testIdModifier, weight} from '@expo/ui/jetpack-compose/modifiers'
+import {fillMaxWidth, height, testID as testIdModifier, weight} from '@expo/ui/jetpack-compose/modifiers'
+import {iconResourceName} from '@hzblj/expo-native-icons'
 import {haptics} from '@hzblj/expo-rich-haptics'
-import {useAppTheme} from '@hzblj/kara-theme'
+import {DrawableIcon, NativeImage} from '@hzblj/kara-native/jetpack-compose'
+import {spacing as spacingTokens, useAppTheme} from '@hzblj/kara-theme'
 import {useCallback, useMemo} from 'react'
 
 import {useInsideHost} from '../../host-context'
-import type {SegmentedControlComponent, SegmentedControlProps} from './segmented-control.types'
+import {HStack} from '../h-stack'
+import type {SegmentedControlComponent, SegmentedControlProps, SegmentedControlSegment} from './segmented-control.types'
+import {imageUri, segmentOf} from './segments'
 
 const MATCH_HEIGHT_ONLY = {horizontal: false, vertical: true}
 
-/** Every segment the same width, like UIKit's: Material's would size each to its label. */
-const SEGMENT = [weight(1)]
+/** Material's own segment height, which `spacing` only ever adds to. */
+const MATERIAL_HEIGHT = 40
+
+type SegmentLabelProps = {
+  iconSize: number
+  segment: SegmentedControlSegment
+}
+
+/**
+ * What a segment shows: its label, one of the app's icons before it, or an image loaded by kara-native. The icon and a
+ * label the image falls back to take the segment's content colour, so they follow the selection and `disabled`.
+ */
+const SegmentLabel = ({iconSize, segment}: SegmentLabelProps) => {
+  const theme = useAppTheme()
+  const face = theme.typography.subheadlineMedium
+
+  if (segment.image !== undefined) {
+    return (
+      <NativeImage
+        fontFamily={face.fontFamily}
+        fontSize={face.fontSize}
+        fontWeight={String(face.fontWeight)}
+        imageHeight={iconSize}
+        label={segment.label}
+        source={imageUri(segment.image)}
+      />
+    )
+  }
+
+  const label = <Text style={face}>{segment.label}</Text>
+
+  if (segment.icon === undefined) {
+    return label
+  }
+
+  return (
+    <HStack align="center" spacing="s6">
+      <DrawableIcon iconSize={iconSize} resourceName={iconResourceName(segment.icon)} />
+      {label}
+    </HStack>
+  )
+}
 
 /**
  * Material's single-choice segmented buttons, the selected one filled with the accent like a checked `Switch`. Its own
@@ -20,13 +64,28 @@ const SEGMENT = [weight(1)]
  */
 export const SegmentedControl: SegmentedControlComponent = ({
   disabled = false,
+  iconSize = 's20',
   onChange,
   selectedIndex,
+  spacing,
   testID,
   values,
 }: SegmentedControlProps) => {
   const theme = useAppTheme()
   const insideHost = useInsideHost()
+  const segments = useMemo(() => values.map(segmentOf), [values])
+  const iconPoints = spacingTokens[iconSize]
+
+  // Every segment the same width, like UIKit's: Material's would size each to its label. With `spacing`, as tall as
+  // the content and that space, and never shorter than Material's own segment.
+  const segmentModifiers = useMemo(() => {
+    if (spacing === undefined) {
+      return [weight(1)]
+    }
+
+    const content = Math.max(theme.typography.subheadlineMedium.lineHeight, iconPoints)
+    return [weight(1), height(Math.max(MATERIAL_HEIGHT, content + 2 * spacingTokens[spacing]))]
+  }, [iconPoints, spacing, theme])
 
   // 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.
@@ -56,24 +115,24 @@ export const SegmentedControl: SegmentedControlComponent = ({
       }
 
       haptics.selection()
-      onChange?.(index, values[index] ?? '')
+      onChange?.(index, segments[index]?.label ?? '')
     },
-    [onChange, selectedIndex, values]
+    [onChange, segments, selectedIndex]
   )
 
   const row = (
     <SingleChoiceSegmentedButtonRow modifiers={rowModifiers}>
-      {values.map((label, index) => (
+      {segments.map((segment, index) => (
         <SegmentedButton
           colors={colors}
           enabled={!disabled}
           key={index}
-          modifiers={SEGMENT}
+          modifiers={segmentModifiers}
           onClick={() => select(index)}
           selected={index === selectedIndex}
         >
           <SegmentedButton.Label>
-            <Text style={theme.typography.subheadlineMedium}>{label}</Text>
+            <SegmentLabel iconSize={iconPoints} segment={segment} />
           </SegmentedButton.Label>
         </SegmentedButton>
       ))}

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

@@ -1,10 +1,12 @@
 import {RNHostView} from '@expo/ui/swift-ui'
+import {iconResourceName} from '@hzblj/expo-native-icons'
 import {SegmentedControl as NativeSegmentedControl} from '@hzblj/kara-native/swift-ui'
-import {useAppTheme} from '@hzblj/kara-theme'
+import {spacing as spacingTokens, useAppTheme} from '@hzblj/kara-theme'
 import {useCallback, useMemo} from 'react'
 
 import {useInsideHost} from '../../host-context'
 import type {SegmentedControlComponent, SegmentedControlProps} from './segmented-control.types'
+import {imageUri, segmentOf} from './segments'
 
 const MATCH_HEIGHT_ONLY = {horizontal: false, vertical: true}
 
@@ -12,12 +14,16 @@ 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. 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.
+ * (see `useInsideHost`), the host's width and its own height. UIKit plays the control's own feedback. A segment shows a
+ * title or an image, never both, so an icon segment is drawn natively as one image of the icon and the label, in the
+ * label's colour; an image segment is the image alone, loaded and drawn by kara-native at `iconSize`.
  */
 export const SegmentedControl: SegmentedControlComponent = ({
   disabled = false,
+  iconSize = 's20',
   onChange,
   selectedIndex,
+  spacing,
   testID,
   values,
 }: SegmentedControlProps) => {
@@ -25,15 +31,26 @@ export const SegmentedControl: SegmentedControlComponent = ({
   const insideHost = useInsideHost()
   const face = theme.typography.footnoteMedium
 
+  const segments = useMemo(() => values.map(segmentOf), [values])
+
   // The native control speaks in values; a segment's is its index, so two labels may read the same.
-  const options = useMemo(() => values.map((label, index) => ({label, value: String(index)})), [values])
+  const options = useMemo(
+    () =>
+      segments.map((segment, index) => ({
+        icon: segment.icon ? iconResourceName(segment.icon) : undefined,
+        image: imageUri(segment.image),
+        label: segment.label,
+        value: String(index),
+      })),
+    [segments]
+  )
 
   const onValueChange = useCallback(
     (value: string) => {
       const index = Number(value)
-      onChange?.(index, values[index] ?? '')
+      onChange?.(index, segments[index]?.label ?? '')
     },
-    [onChange, values]
+    [onChange, segments]
   )
 
   const control = (
@@ -43,11 +60,13 @@ export const SegmentedControl: SegmentedControlComponent = ({
       disabled={disabled}
       fontFamily={face.fontFamily}
       fontSize={face.fontSize}
+      iconSize={spacingTokens[iconSize]}
       inactiveTextColor={theme.color('content.primary')}
       onValueChange={onValueChange}
       options={options}
       selectedValue={String(selectedIndex)}
       testID={testID}
+      verticalPadding={spacing === undefined ? undefined : spacingTokens[spacing]}
     />
   )
 

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

@@ -1,14 +1,34 @@
+import type {SpaceSize} from '@hzblj/kara-theme'
 import type {ReactNode} from 'react'
+import type {ImageSourcePropType} from 'react-native'
+
+import type {IconName} from '../icon'
+
+/** A segment that shows more than its label. */
+export type SegmentedControlSegment = {
+  /** One of the app's icons, before the label and in the label's colour, the selected segment's or the others'. */
+  icon?: IconName
+  /**
+   * An image in its own colours instead of the label, such as a carrier's logo: a `require()`d file, or `{uri}` for a
+   * URL (raster or SVG). The label stays what screen readers say, and is shown instead if the image cannot be loaded.
+   */
+  image?: ImageSourcePropType
+  /** What the segment says, and what `onChange` reports. */
+  label: string
+}
 
 /**
  * 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. 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.
+ * width it is given; the height is the platform's, or taller with `spacing`. A segment can lead with one of the app's
+ * icons or be an image, a logo, both loaded natively (SDWebImage on iOS, androidsvg on Android, as Footshop does).
  */
 export type SegmentedControlProps = {
   /** Stops the user changing the segment, and dims the control. */
   disabled?: boolean
+  /** The height of the segments' icons and images, a spacing token. `s20` by default. */
+  iconSize?: SpaceSize
   /**
    * Called with the index and label of the segment the user picked, never for a tap on the one already selected.
    * Android plays `selection`; iOS's control plays its own feedback.
@@ -16,10 +36,15 @@ export type SegmentedControlProps = {
   onChange?: (index: number, value: string) => void
   /** The selected segment. Controlled: pass back what `onChange` reports. */
   selectedIndex: number
+  /**
+   * Space above and below the segments' content, a spacing token: a taller control, for bigger icons or an easier
+   * target. Unset keeps the platform's own height, and the control is never shorter than that.
+   */
+  spacing?: SpaceSize
   /** Test identifier, on the whole control. Reach a segment by its label. */
   testID?: string
-  /** The segments' labels, in order. */
-  values: string[]
+  /** The segments, in order: a label, or a segment with an icon or an image. */
+  values: (string | SegmentedControlSegment)[]
 }
 
 export type SegmentedControlComponent = (props: SegmentedControlProps) => ReactNode

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

@@ -0,0 +1,16 @@
+import {Image, type ImageSourcePropType} from 'react-native'
+
+import type {SegmentedControlSegment} from './segmented-control.types'
+
+/** A plain label is a segment with nothing else. */
+export const segmentOf = (value: string | SegmentedControlSegment): SegmentedControlSegment =>
+  typeof value === 'string' ? {label: value} : value
+
+/** What the native loaders take: a `require()`d file's packager or file URL, or the URI itself. */
+export const imageUri = (source: ImageSourcePropType | undefined): string | undefined => {
+  if (source === undefined) {
+    return undefined
+  }
+
+  return Image.resolveAssetSource(Array.isArray(source) ? source[0] : source)?.uri
+}

package/src/atoms/slider/slider.android.tsx

@@ -1,7 +1,8 @@
 import {Slider as ComposeSlider} from '@expo/ui/jetpack-compose'
+import {testID as testIdModifier} from '@expo/ui/jetpack-compose/modifiers'
 import {haptics} from '@hzblj/expo-rich-haptics'
 import {useAppTheme} from '@hzblj/kara-theme'
-import {useCallback, useEffect, useRef} from 'react'
+import {useCallback, useEffect, useMemo, useRef} from 'react'
 
 import {useHostGuard} from '../../host-context'
 import type {SliderComponent, SliderProps} from './slider.types'
@@ -9,14 +10,17 @@ import type {SliderComponent, SliderProps} from './slider.types'
 /**
  * Material's slider. `step` is the increment, as SwiftUI takes it; Compose counts the stops between the two ends
  * instead, so it is converted. A stepped slider ticks at every stop the thumb reaches — Compose's Material slider
- * plays nothing of its own, where iOS 26's slider already does.
+ * plays nothing of its own, where iOS 26's slider already does. `onValueChangeEnd` is Material's
+ * `onValueChangeFinished`, which reports no value: it gets the last one the drag reported.
  */
 export const Slider: SliderComponent = ({
   disabled = false,
   max = 1,
   min = 0,
   onValueChange,
+  onValueChangeEnd,
   step,
+  testID,
   value,
 }: SliderProps) => {
   useHostGuard('Slider')
@@ -27,6 +31,7 @@ export const Slider: SliderComponent = ({
   // Compose reports faster than React re-renders the controlled value.
   const stopOf = useCallback((at: number) => (step ? Math.round((at - min) / step) : 0), [min, step])
   const stop = useRef(stopOf(value))
+  const dragged = useRef<number | undefined>(undefined)
 
   useEffect(() => {
     stop.current = stopOf(value)
@@ -41,11 +46,20 @@ export const Slider: SliderComponent = ({
       }
 
       stop.current = reached
+      dragged.current = next
       onValueChange?.(next)
     },
     [onValueChange, stopOf, steps]
   )
 
+  const onFinished = useCallback(() => {
+    const final = dragged.current ?? value
+    dragged.current = undefined
+    onValueChangeEnd?.(final)
+  }, [onValueChangeEnd, value])
+
+  const modifiers = useMemo(() => (testID ? [testIdModifier(testID)] : undefined), [testID])
+
   return (
     <ComposeSlider
       colors={{
@@ -55,7 +69,9 @@ export const Slider: SliderComponent = ({
       enabled={!disabled}
       max={max}
       min={min}
+      modifiers={modifiers}
       onValueChange={onChange}
+      onValueChangeFinished={onValueChangeEnd ? onFinished : undefined}
       steps={steps}
       value={value}
     />

package/src/atoms/slider/slider.ios.tsx

@@ -1,21 +1,28 @@
 import {Slider as SwiftUISlider} from '@expo/ui/swift-ui'
 import {disabled as disabledModifier, tint} from '@expo/ui/swift-ui/modifiers'
 import {useAppTheme} from '@hzblj/kara-theme'
-import {useMemo} from 'react'
+import {useCallback, useMemo, useRef} from 'react'
 
 import {useHostGuard} from '../../host-context'
 import type {SliderComponent, SliderProps} from './slider.types'
 
+/**
+ * SwiftUI's slider. `onValueChangeEnd` is its `onEditingChanged(false)`, with the last value the drag reported: the
+ * controlled `value` can still be a render behind when the finger lifts.
+ */
 export const Slider: SliderComponent = ({
   disabled = false,
   max = 1,
   min = 0,
   onValueChange,
+  onValueChangeEnd,
   step,
+  testID,
   value,
 }: SliderProps) => {
   useHostGuard('Slider')
   const theme = useAppTheme()
+  const dragged = useRef<number | undefined>(undefined)
 
   const modifiers = useMemo(() => {
     const list = [tint(theme.color('fill.accent.primary'))]
@@ -27,7 +34,36 @@ export const Slider: SliderComponent = ({
     return list
   }, [disabled, theme])
 
+  const onChange = useCallback(
+    (next: number) => {
+      dragged.current = next
+      onValueChange?.(next)
+    },
+    [onValueChange]
+  )
+
+  const onEditingChanged = useCallback(
+    (editing: boolean) => {
+      const final = dragged.current ?? value
+      dragged.current = undefined
+
+      if (!editing) {
+        onValueChangeEnd?.(final)
+      }
+    },
+    [onValueChangeEnd, value]
+  )
+
   return (
-    <SwiftUISlider max={max} min={min} modifiers={modifiers} onValueChange={onValueChange} step={step} value={value} />
+    <SwiftUISlider
+      max={max}
+      min={min}
+      modifiers={modifiers}
+      onEditingChanged={onValueChangeEnd ? onEditingChanged : undefined}
+      onValueChange={onChange}
+      step={step}
+      testID={testID}
+      value={value}
+    />
   )
 }

package/src/atoms/slider/slider.types.ts

@@ -10,8 +10,15 @@ export type SliderProps = {
   min?: number
   /** Called with the new value as the thumb moves. */
   onValueChange?: (value: number) => void
+  /**
+   * Called once with the final value when the user lets go of the slider: where a seek or a volume commits, rather
+   * than at every step of the drag.
+   */
+  onValueChangeEnd?: (value: number) => void
   /** The increment between stops; leave it unset for a continuous slider. On Android every stop plays a `tick`. */
   step?: number
+  /** Test identifier, forwarded to the native view. */
+  testID?: string
   /** Between `min` and `max`. Controlled: pass back what `onValueChange` reports. */
   value: number
 }

package/src/atoms/switch/switch.android.tsx

@@ -1,5 +1,5 @@
 import {Switch as ComposeSwitch, Row, Text} from '@expo/ui/jetpack-compose'
-import {clickable, fillMaxWidth} from '@expo/ui/jetpack-compose/modifiers'
+import {clickable, fillMaxWidth, testID as testIdModifier} from '@expo/ui/jetpack-compose/modifiers'
 import {haptics} from '@hzblj/expo-rich-haptics'
 import {useAppTheme} from '@hzblj/kara-theme'
 import {useCallback, useMemo} from 'react'
@@ -16,7 +16,7 @@ const NOOP = () => undefined
  * `toggleOn`/`toggleOff` — Android 14's constants made for switches — since Compose's Material switch plays nothing
  * of its own. iOS stays silent, as `UISwitch` does.
  */
-export const Switch: SwitchComponent = ({disabled = false, label, onValueChange, value}: SwitchProps) => {
+export const Switch: SwitchComponent = ({disabled = false, label, onValueChange, testID, value}: SwitchProps) => {
   useHostGuard('Switch')
   const theme = useAppTheme()
   const toggle = useCallback(
@@ -30,6 +30,8 @@ export const Switch: SwitchComponent = ({disabled = false, label, onValueChange,
     () => (disabled || !onValueChange ? [fillMaxWidth()] : [fillMaxWidth(), clickable(() => toggle(!value))]),
     [disabled, onValueChange, toggle, value]
   )
+  // On the switch, not the row: the switch is its own toggleable node inside the row, and the one a test reads.
+  const controlModifiers = useMemo(() => (testID ? [testIdModifier(testID)] : undefined), [testID])
   const control = (
     <ComposeSwitch
       colors={{
@@ -38,6 +40,7 @@ export const Switch: SwitchComponent = ({disabled = false, label, onValueChange,
         checkedTrackColor: theme.color('fill.accent.primary'),
       }}
       enabled={!disabled}
+      modifiers={controlModifiers}
       onCheckedChange={onValueChange ? toggle : NOOP}
       value={value}
     />

package/src/atoms/switch/switch.ios.tsx

@@ -6,7 +6,7 @@ import {useMemo} from 'react'
 import {useHostGuard} from '../../host-context'
 import type {SwitchComponent, SwitchProps} from './switch.types'
 
-export const Switch: SwitchComponent = ({disabled = false, label, onValueChange, value}: SwitchProps) => {
+export const Switch: SwitchComponent = ({disabled = false, label, onValueChange, testID, value}: SwitchProps) => {
   useHostGuard('Switch')
   const theme = useAppTheme()
 
@@ -20,5 +20,5 @@ export const Switch: SwitchComponent = ({disabled = false, label, onValueChange,
     return list
   }, [disabled, theme])
 
-  return <Toggle isOn={value} label={label} modifiers={modifiers} onIsOnChange={onValueChange} />
+  return <Toggle isOn={value} label={label} modifiers={modifiers} onIsOnChange={onValueChange} testID={testID} />
 }

package/src/atoms/switch/switch.types.ts

@@ -11,6 +11,8 @@ export type SwitchProps = {
   label?: string
   /** Called with the new value when the user flips it. On Android a flip plays `toggleOn` / `toggleOff`. */
   onValueChange?: (value: boolean) => void
+  /** Test identifier, forwarded to the native switch (on Android the switch itself, not the labelled row). */
+  testID?: string
   /** Whether it is on. Controlled: pass back what `onValueChange` reports. */
   value: boolean
 }

package/src/atoms/text/spans.ts

@@ -4,7 +4,8 @@ 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 =>
+/** The string and number children, joined: the text of a `Text` without spans, however JSX split it. */
+export const textOf = (children: ReactNode): string =>
   Children.toArray(children)
     .map(child => (typeof child === 'string' || typeof child === 'number' ? String(child) : ''))
     .join('')

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

@@ -1,6 +1,6 @@
 import {Text as ComposeText} from '@expo/ui/jetpack-compose'
 import {testID as testIdModifier} from '@expo/ui/jetpack-compose/modifiers'
-import {AnimatedText, type TextAnimation} from '@hzblj/kara-native/jetpack-compose'
+import {AnimatedText, type AnimatedTextOverflow, type TextAnimation} from '@hzblj/kara-native/jetpack-compose'
 import {
   animateConfig,
   type SxAnimateConfig,
@@ -12,8 +12,8 @@ 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'
+import {spansOf, textOf} from './spans'
+import type {TextComponent, TextDecoration, TextProps, TextTransform, TextTruncation} from './text.types'
 
 const DECORATION = {
   none: 'none',
@@ -21,6 +21,12 @@ const DECORATION = {
   underline: 'underline',
 } as const
 
+const OVERFLOW = {
+  head: 'startEllipsis',
+  middle: 'middleEllipsis',
+  tail: 'ellipsis',
+} as const satisfies Record<TextTruncation, AnimatedTextOverflow>
+
 const applyTransform = (children: TextProps['children'], transform: TextTransform | undefined) => {
   if (!transform || typeof children !== 'string') {
     return children
@@ -68,6 +74,7 @@ export const Text: TextComponent = ({
   numberOfLines,
   testID,
   transform,
+  truncation = 'tail',
   variant = 'body',
   ...props
 }: TextProps) => {
@@ -83,11 +90,15 @@ export const Text: TextComponent = ({
   )
   const spans = useMemo(() => spansOf(children, Text), [children])
   const animate = sx.animate === false ? undefined : sx.animate
+  // Compose ellipsizes at the start or in the middle of a single line only, and clips a longer text: that ends at the
+  // tail instead.
+  const overflow = numberOfLines === 1 ? OVERFLOW[truncation] : 'ellipsis'
 
-  // `@expo/ui`'s text takes spans but animates none, and sets no font features: with `animate`, kara's own Compose text
-  // eases each span's colour, and with `monospacedDigit` asks the face for its tabular figures.
-  if (animate !== undefined || monospacedDigit) {
-    const runs = spans ?? [{text: typeof children === 'string' || typeof children === 'number' ? String(children) : ''}]
+  // `@expo/ui`'s text takes spans but animates none, sets no font features and ellipsizes only at the end: with
+  // `animate`, kara's own Compose text eases each span's colour, with `monospacedDigit` asks the face for its tabular
+  // figures, and puts the ellipsis at the start or in the middle of a line.
+  if (animate !== undefined || monospacedDigit || overflow !== 'ellipsis') {
+    const runs = spans ?? [{text: textOf(children)}]
 
     return (
       <AnimatedText
@@ -106,6 +117,7 @@ export const Text: TextComponent = ({
         textAlign={align}
         textColor={theme.colorString(color)}
         textDecoration={decorationOf(decoration)}
+        textOverflow={overflow}
       />
     )
   }
@@ -115,6 +127,7 @@ export const Text: TextComponent = ({
       color={theme.colorString(color)}
       maxLines={numberOfLines}
       modifiers={modifiers}
+      overflow="ellipsis"
       style={{
         fontFamily: style.fontFamily,
         fontSize: style.fontSize,

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

@@ -8,6 +8,7 @@ import {
   multilineTextAlignment,
   strikethrough,
   textCase,
+  truncationMode,
   underline,
 } from '@expo/ui/swift-ui/modifiers'
 import {scaledFont} from '@hzblj/kara-native/swift-ui'
@@ -48,6 +49,7 @@ export const Text: TextComponent = ({
   numberOfLines,
   testID,
   transform,
+  truncation,
   variant = 'body',
   ...props
 }: TextProps) => {
@@ -99,6 +101,10 @@ export const Text: TextComponent = ({
       list.push(lineLimit(numberOfLines))
     }
 
+    if (truncation) {
+      list.push(truncationMode(truncation))
+    }
+
     return [...list, ...transition, ...sxModifiers, ...accessibilityModifiers]
   }, [
     accessibilityModifiers,
@@ -112,6 +118,7 @@ export const Text: TextComponent = ({
     theme,
     transform,
     transition,
+    truncation,
   ])
 
   return (