@hzblj/kara-components 0.16.0 → 0.18.0

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

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

@@ -1,25 +1,140 @@
-import {Column, Text as ComposeText, OutlinedTextField, useNativeState} from '@expo/ui/jetpack-compose'
+import {
+  Column,
+  Text as ComposeText,
+  type TextFieldRef as ComposeTextFieldRef,
+  OutlinedTextField,
+  type TextFieldKeyboardActions,
+  type TextFieldKeyboardOptions,
+  type TextFieldKeyboardType,
+  useNativeState,
+} from '@expo/ui/jetpack-compose'
+import {semantics, testID as testIdModifier} from '@expo/ui/jetpack-compose/modifiers'
 import {useSxModifiers} from '@hzblj/kara-sx'
 import {useAppTheme} from '@hzblj/kara-theme'
+import {useImperativeHandle, useMemo, useRef} from 'react'
 import {Glyph} from '../../glyph'
 import {useHostGuard} from '../../host-context'
-import type {TextFieldComponent, TextFieldProps} from './text-field.types'
+import type {TextFieldComponent, TextFieldContentType, TextFieldKeyboard, TextFieldProps} from './text-field.types'
+import {autoCorrectFor, capitalizationFor, ignoreDetachedView} from './text-field-input'
+
+const KEYBOARD = {
+  decimal: 'decimal',
+  default: 'text',
+  email: 'email',
+  number: 'number',
+  phone: 'phone',
+  url: 'uri',
+} as const satisfies Record<TextFieldKeyboard, TextFieldKeyboardType>
+
+/**
+ * A `secure` field asks for the password keyboards: they suggest nothing and learn nothing, and they are what Android's
+ * autofill takes for a password field.
+ */
+const SECURE_KEYBOARD = {
+  ...KEYBOARD,
+  default: 'password',
+  number: 'numberPassword',
+} as const satisfies Record<TextFieldKeyboard, TextFieldKeyboardType>
+
+/** Compose's autofill `ContentType`s, by the hint names `@expo/ui`'s `semantics` modifier maps to them. */
+const AUTOFILL_HINT = {
+  addressCity: 'postal-address-locality',
+  countryName: 'country',
+  creditCardNumber: 'cc-number',
+  emailAddress: 'email',
+  familyName: 'family-name',
+  fullStreetAddress: 'street-address',
+  givenName: 'given-name',
+  name: 'name',
+  newPassword: 'new-password',
+  oneTimeCode: 'one-time-code',
+  password: 'password',
+  postalCode: 'postal-code',
+  streetAddressLine1: 'address-line1',
+  streetAddressLine2: 'address-line2',
+  telephoneNumber: 'tel',
+  username: 'username',
+} as const satisfies Record<TextFieldContentType, string>
 
 export const TextField: TextFieldComponent = ({
+  autoCapitalize,
+  autoCorrect,
+  autoFocus = false,
+  contentType,
   defaultValue = '',
   disabled = false,
   error = false,
+  keyboard = 'default',
   label,
+  maxLength,
   multiline = false,
   onChangeText,
+  onFocusChange,
+  onSubmit,
+  placeholder,
+  ref,
   secure = false,
+  submitLabel,
+  testID,
 }: TextFieldProps) => {
   useHostGuard('TextField')
   const theme = useAppTheme()
   const value = useNativeState(defaultValue)
-  const modifiers = useSxModifiers({wide: true})
+  const field = useRef<ComposeTextFieldRef>(null)
+  const sxModifiers = useSxModifiers({wide: true})
   const invalid = Boolean(error)
   const message = typeof error === 'string' && error ? error : undefined
+  const face = {fontFamily: theme.typography.body.fontFamily, fontWeight: theme.typography.body.fontWeight}
+  const capitalization = capitalizationFor(keyboard, autoCapitalize) ?? 'none'
+  const corrects = !secure && autoCorrectFor(keyboard, autoCorrect)
+  const singleLine = !multiline
+  const submits = singleLine && Boolean(onSubmit)
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      blur: () => field.current?.blur().catch(ignoreDetachedView),
+      // The field reports no text set from code, so the change is reported here.
+      clear: () => {
+        field.current?.clear().catch(ignoreDetachedView)
+        onChangeText?.('')
+      },
+      focus: () => field.current?.focus().catch(ignoreDetachedView),
+    }),
+    [onChangeText]
+  )
+
+  const modifiers = useMemo(
+    () => [
+      ...sxModifiers,
+      ...(testID ? [testIdModifier(testID)] : []),
+      ...(contentType ? [semantics({contentType: AUTOFILL_HINT[contentType]})] : []),
+    ],
+    [contentType, sxModifiers, testID]
+  )
+
+  /**
+   * A multiline field keeps the default action, a return key that starts a new line. A single-line one asked for
+   * `onSubmit` without a `submitLabel` gets `done`: Compose only runs the keyboard action it was given.
+   */
+  const keyboardOptions = useMemo<TextFieldKeyboardOptions>(
+    () => ({
+      autoCorrectEnabled: corrects,
+      capitalization,
+      imeAction: singleLine ? (submitLabel ?? (submits ? 'done' : 'default')) : 'default',
+      keyboardType: (secure ? SECURE_KEYBOARD : KEYBOARD)[keyboard],
+    }),
+    [capitalization, corrects, keyboard, secure, singleLine, submitLabel, submits]
+  )
+
+  // Only the action matching `imeAction` ever fires, so each one is the submit.
+  const keyboardActions = useMemo<TextFieldKeyboardActions | undefined>(
+    () =>
+      submits && onSubmit
+        ? {onDone: onSubmit, onGo: onSubmit, onNext: onSubmit, onSearch: onSubmit, onSend: onSubmit}
+        : undefined,
+    [onSubmit, submits]
+  )
 
   return (
     <Column verticalArrangement={{spacedBy: 4}}>
@@ -32,19 +147,27 @@ export const TextField: TextFieldComponent = ({
         </ComposeText>
       ) : null}
       <OutlinedTextField
+        autoFocus={autoFocus}
         enabled={!disabled}
         isError={invalid}
+        keyboardActions={keyboardActions}
+        keyboardOptions={keyboardOptions}
+        maxLength={maxLength}
         modifiers={modifiers}
+        onFocusChanged={onFocusChange}
         onValueChange={onChangeText}
-        singleLine={!multiline}
-        textStyle={{
-          color: theme.colorString('content.primary'),
-          fontFamily: theme.typography.body.fontFamily,
-          fontWeight: theme.typography.body.fontWeight,
-        }}
+        ref={field}
+        singleLine={singleLine}
+        textStyle={{color: theme.colorString('content.primary'), ...face}}
         value={value}
         visualTransformation={secure ? 'password' : 'none'}
       >
+        {placeholder ? (
+          // No colour of its own: Material's placeholder colour comes down to it, dimmed with the field.
+          <OutlinedTextField.Placeholder>
+            <ComposeText style={face}>{placeholder}</ComposeText>
+          </OutlinedTextField.Placeholder>
+        ) : null}
         {invalid ? (
           <OutlinedTextField.TrailingIcon>
             <Glyph color="content.destructive" name="error" />