@hzblj/kara-components 0.17.0 → 0.18.0

package/src/atoms/list/list.android.tsx

@@ -1,8 +1,11 @@
 import {LazyColumn, PullToRefreshBox} from '@expo/ui/jetpack-compose'
+import {testID as testIdModifier} from '@expo/ui/jetpack-compose/modifiers'
 import {useSxModifiers} from '@hzblj/kara-sx'
-import {Children, Fragment, isValidElement} from 'react'
+import {spacing} from '@hzblj/kara-theme'
+import {Children, Fragment, isValidElement, useMemo} from 'react'
 import {useHostGuard} from '../../host-context'
 import {useRefreshState} from '../../use-refresh-state'
+import {Card} from '../card'
 import {Divider} from '../divider'
 import type {ListComponent, ListProps} from './list.types'
 
@@ -15,12 +18,31 @@ const withSeparators = (children: ListProps['children']) =>
     </Fragment>
   ))
 
-export const List: ListComponent = ({children, onRefresh}: ListProps) => {
+/** The card's inset from the column's edges, as `Form` keeps its cards off the screen's. */
+const INSET = {bottom: spacing.s16, end: spacing.s16, start: spacing.s16, top: spacing.s16}
+
+/**
+ * `plain` is the column as it always was. `insetGrouped` sets the rows in one `Card`, the way `Form` draws a section,
+ * inset by the column's content padding: the card is a single item of the column, so its rows are composed together
+ * rather than as they scroll in. A long list that wants laziness stays `plain`.
+ */
+export const List: ListComponent = ({children, onRefresh, separators = true, testID, variant = 'plain'}: ListProps) => {
   useHostGuard('List')
-  const modifiers = useSxModifiers({wide: true})
+  const sxModifiers = useSxModifiers({wide: true})
+  // On the column, not the refresh box around it: the column is what scrolls.
+  const modifiers = useMemo(
+    () => (testID ? [...sxModifiers, testIdModifier(testID)] : sxModifiers),
+    [sxModifiers, testID]
+  )
   const {isRefreshing, refresh} = useRefreshState(onRefresh)
+  const rows = separators ? withSeparators(children) : children
+  const grouped = variant === 'insetGrouped'
 
-  const column = <LazyColumn modifiers={modifiers}>{withSeparators(children)}</LazyColumn>
+  const column = (
+    <LazyColumn contentPadding={grouped ? INSET : undefined} modifiers={modifiers}>
+      {grouped && Children.toArray(children).length > 0 ? <Card wide>{rows}</Card> : rows}
+    </LazyColumn>
+  )
 
   if (!onRefresh) {
     return column

package/src/atoms/list/list.ios.tsx

@@ -1,18 +1,33 @@
-import {List as SwiftUIList} from '@expo/ui/swift-ui'
-import {type ModifierConfig, refreshable} from '@expo/ui/swift-ui/modifiers'
+import {Group, List as SwiftUIList} from '@expo/ui/swift-ui'
+import {listRowSeparator, listStyle, type ModifierConfig, refreshable} from '@expo/ui/swift-ui/modifiers'
 import {useMemo} from 'react'
 
 import {useHostGuard} from '../../host-context'
 import type {ListComponent, ListProps} from './list.types'
 
-export const List: ListComponent = ({children, onRefresh, testID}: ListProps) => {
+/**
+ * `listRowSeparator` is a row's preference, not the list's: set on the `List` it reaches no row. A `Group` hands a
+ * modifier to each of its children, so the rows go in one, and each of them hides its own separator.
+ */
+const NO_SEPARATORS = [listRowSeparator('hidden')]
+
+export const List: ListComponent = ({
+  children,
+  onRefresh,
+  separators = true,
+  testID,
+  variant = 'insetGrouped',
+}: ListProps) => {
   useHostGuard('List')
 
-  const modifiers = useMemo<ModifierConfig[]>(() => (onRefresh ? [refreshable(onRefresh)] : []), [onRefresh])
+  const modifiers = useMemo<ModifierConfig[]>(
+    () => [listStyle(variant), ...(onRefresh ? [refreshable(onRefresh)] : [])],
+    [onRefresh, variant]
+  )
 
   return (
     <SwiftUIList modifiers={modifiers} testID={testID}>
-      {children}
+      {separators ? children : <Group modifiers={NO_SEPARATORS}>{children}</Group>}
     </SwiftUIList>
   )
 }

package/src/atoms/list/list.types.ts

@@ -1,5 +1,8 @@
 import type {ReactNode} from 'react'
 
+/** How the rows are laid out: in a rounded card inset from the edges, or edge to edge. */
+export type ListVariant = 'insetGrouped' | 'plain'
+
 /**
  * A scrolling list: SwiftUI `List`, Compose `LazyColumn`. It has no height of its own, so it needs one from outside:
  * a `Screen`, or an `Island` with `matchContents={false}` and a height. In an island that sizes itself to its content
@@ -17,8 +20,20 @@ export type ListProps = {
    * until the promise settles, so neither platform needs a `refreshing` flag kept in sync by hand.
    */
   onRefresh?: () => Promise<void>
-  /** Test identifier, forwarded to the native view on iOS. Android ignores it. */
+  /**
+   * Draws a line between rows. On by default. Off, iOS hides SwiftUI's row separators and Android draws no `Divider`,
+   * for rows that carry their own spacing (cards, media).
+   */
+  separators?: boolean
+  /** Test identifier, forwarded to the native view. */
   testID?: string
+  /**
+   * The layout. Each platform's own list by default: `insetGrouped` on iOS, `plain` on Android. `insetGrouped` sets
+   * the rows in a rounded card inset from the edges (SwiftUI's `insetGrouped` list style; on Android a `Card` inside the
+   * column, the way `Form` draws its sections). `plain` runs the rows edge to edge (SwiftUI's `plain` style; Android's
+   * column as it is).
+   */
+  variant?: ListVariant
 }
 
 export type ListComponent = (props: ListProps) => ReactNode

package/src/atoms/progress/progress.android.tsx

@@ -1,19 +1,45 @@
 import {CircularProgressIndicator, LinearProgressIndicator} from '@expo/ui/jetpack-compose'
+import {testID as testIdModifier} from '@expo/ui/jetpack-compose/modifiers'
 import {useAccessibilityModifiers} from '@hzblj/kara-sx'
-import {useAppTheme} from '@hzblj/kara-theme'
+import {useAppTheme, withOpacity} from '@hzblj/kara-theme'
+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) => {
+/**
+ * Material draws the track in the seeded scheme's `secondaryContainer`, a pale accent: under a red or a green bar it
+ * would read as a second colour. Any other colour gets its own faded track instead, the way the accent's is pale; the
+ * accent keeps Material's. An indeterminate ring has no track in Material, so it is left without one.
+ */
+export const Progress: ProgressComponent = ({
+  accessibilityLabel,
+  circular = false,
+  color = 'fill.accent.primary',
+  testID,
+  value,
+}: ProgressProps) => {
   useHostGuard('Progress')
   const theme = useAppTheme()
-  const color = theme.color('fill.accent.primary')
-  const modifiers = useAccessibilityModifiers({accessibilityLabel})
+  const indicator = theme.color(color)
+  // The website reads the default above from the source, so it stays a literal rather than a shared constant.
+  const track = color === 'fill.accent.primary' ? undefined : withOpacity(String(indicator), 'o20')
+  const accessibilityModifiers = useAccessibilityModifiers({accessibilityLabel})
+  const modifiers = useMemo(
+    () => (testID ? [testIdModifier(testID), ...accessibilityModifiers] : accessibilityModifiers),
+    [accessibilityModifiers, testID]
+  )
 
   if (circular) {
-    return <CircularProgressIndicator color={color} modifiers={modifiers} progress={value} />
+    return (
+      <CircularProgressIndicator
+        color={indicator}
+        modifiers={modifiers}
+        progress={value}
+        trackColor={value === undefined ? undefined : track}
+      />
+    )
   }
 
-  return <LinearProgressIndicator color={color} modifiers={modifiers} progress={value} />
+  return <LinearProgressIndicator color={indicator} modifiers={modifiers} progress={value} trackColor={track} />
 }

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/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 (

package/src/atoms/text/text.types.ts

@@ -8,6 +8,9 @@ export type TextDecoration = 'none' | 'strikethrough' | 'underline'
 
 export type TextTransform = 'lowercase' | 'uppercase'
 
+/** Where the ellipsis goes in a text cut short: its start, its middle or its end. */
+export type TextTruncation = 'head' | 'middle' | 'tail'
+
 /**
  * SwiftUI `Text` / Compose `Text` in a theme typography variant. A native atom: outside a host, use `RnText`. It takes
  * the native `sx` surface too: padding, a frame (`wide` lines it up by `align`), a background, and the `ios` bucket's
@@ -34,7 +37,7 @@ export type TextProps = ResponsiveSx &
     color?: ColorToken
     /** An underline or a strikethrough. */
     decoration?: TextDecoration
-    /** The most lines it wraps to. iOS truncates the last with an ellipsis; Android clips it. */
+    /** The most lines it wraps to. A text cut short ends with an ellipsis, where `truncation` puts it. */
     numberOfLines?: number
     /**
      * Sets it in the theme's fixed-width face, at the variant's size and weight: the app's `fonts.mono`, else Menlo on
@@ -51,6 +54,12 @@ export type TextProps = ResponsiveSx &
     testID?: string
     /** Upper- or lower-cases the text. Android applies it only when `children` is a plain string. */
     transform?: TextTransform
+    /**
+     * Where the ellipsis goes in a text cut short. `tail` by default: the end of the last line. `head` keeps the end of
+     * the text and `middle` both of its ends, for a file name, a path or an address. Android puts it at the head or in
+     * the middle of a single line only (`numberOfLines={1}`), as Compose does; a longer text there ends at the tail.
+     */
+    truncation?: TextTruncation
     /** The typography variant. `body` by default. */
     variant?: TextVariant
   }

package/src/atoms/text-field/text-field-input.ts

@@ -0,0 +1,17 @@
+import type {TextFieldAutoCapitalize, TextFieldKeyboard} from './text-field.types'
+
+/** Keyboards for an address, where a capital or a correction the user did not type would only break it. */
+const ADDRESS_KEYBOARDS: ReadonlySet<TextFieldKeyboard> = new Set(['email', 'url'])
+
+/** The capitalisation asked for, else `none` for an address; `undefined` leaves the platform's own. */
+export const capitalizationFor = (
+  keyboard: TextFieldKeyboard,
+  autoCapitalize: TextFieldAutoCapitalize | undefined
+): TextFieldAutoCapitalize | undefined => autoCapitalize ?? (ADDRESS_KEYBOARDS.has(keyboard) ? 'none' : undefined)
+
+/** Autocorrection as asked for, else on for everything but an address. */
+export const autoCorrectFor = (keyboard: TextFieldKeyboard, autoCorrect: boolean | undefined): boolean =>
+  autoCorrect ?? !ADDRESS_KEYBOARDS.has(keyboard)
+
+/** A no-op for a ref call that lands after the native view has gone. */
+export const ignoreDetachedView = () => undefined