expo-interface 0.2.0 → 0.3.0

package/src/text-field/index.tsx

@@ -1,9 +1,20 @@
 import type {TextFieldProps} from './types';
-import type {TextStyle} from 'react-native';
+import type {NativeSyntheticEvent, TextInputKeyPressEventData, TextStyle} from 'react-native';
 
+import {useRef} from 'react';
 import {StyleSheet, TextInput} from 'react-native';
 import {fonts, fontWeights, theme, variants} from '../theme';
-import {keyboardTypeFor, useTextValue} from './shared';
+import {InlineTextField} from './inline';
+import {keyboardTypeFor, useAutoFocus, useTextValue} from './shared';
+
+/**
+ * The `row` variant is the form row below; `inline` is the borderless field
+ * for a React Native layout (the same `TextInput`, sized to its room).
+ */
+export function TextField(props: TextFieldProps) {
+  if (props.variant === 'inline') return <InlineTextField {...props}/>;
+  return <RowTextField {...props}/>;
+}
 
 /**
  * On web the field mirrors the native iOS/Android row: a borderless, full-width
@@ -11,11 +22,12 @@ import {keyboardTypeFor, useTextValue} from './shared';
  * typography so it sits flush inside a `FieldGroup.Section`. The browser focus
  * outline is suppressed to match the chromeless iOS `Form` look.
  */
-export function TextField({
+function RowTextField({
   placeholder,
   value,
   onChangeText,
   onSubmit,
+  onKeyPress,
   disabled,
   secureTextEntry,
   keyboardType,
@@ -23,16 +35,21 @@ export function TextField({
   autoCorrect,
   multiline,
   autoFocus,
+  returnKeyType,
+  submitBehavior,
   maxLength,
   accentColor,
   testID,
   style,
 }: TextFieldProps) {
+  const input = useRef<TextInput>(null);
   const [current, setValue] = useTextValue(value, onChangeText);
   const cursor = accentColor ?? (theme.tint as string);
+  useAutoFocus(input, autoFocus);
 
   return (
     <TextInput
+      ref={input}
       value={current}
       onChangeText={setValue}
       placeholder={placeholder}
@@ -43,11 +60,14 @@ export function TextField({
       autoCapitalize={autoCapitalize}
       autoCorrect={autoCorrect}
       multiline={multiline}
-      autoFocus={autoFocus}
       maxLength={maxLength}
       cursorColor={cursor}
       selectionColor={cursor}
+      returnKeyType={returnKeyType}
+      submitBehavior={submitBehavior}
       onSubmitEditing={onSubmit ? event => onSubmit(event.nativeEvent.text) : undefined}
+      onKeyPress={onKeyPress ? (event: NativeSyntheticEvent<TextInputKeyPressEventData & {shiftKey?: boolean}>) =>
+        onKeyPress(event.nativeEvent.key, event.nativeEvent.shiftKey === true) : undefined}
       aria-label={placeholder}
       testID={testID}
       style={[styles.input, disabled && styles.disabled, style]}

package/src/text-field/inline.tsx

@@ -0,0 +1,87 @@
+import type {NativeSyntheticEvent, TextInputKeyPressEventData} from 'react-native';
+import type {TextFieldProps} from './types';
+import {useRef} from 'react';
+import {StyleSheet, TextInput} from 'react-native';
+import {fonts, fontWeights, spacing, useColor} from '../theme';
+import {keyboardTypeFor, useAutoFocus, useTextValue} from './shared';
+
+/**
+ * The `inline` variant: a borderless React Native `TextInput` on every
+ * platform, for a field that sits inside a React Native layout (a search
+ * row in a toolbar, a prompt in a bar) where the native form control would
+ * need a host of its own. It grows to the room it is given, focuses on
+ * mount when asked (and makes sure the keyboard came on Android), and steps
+ * with the keyboard's action key (`returnKeyType` with `submitBehavior`).
+ */
+export function InlineTextField({
+  placeholder,
+  value,
+  onChangeText,
+  onSubmit,
+  onKeyPress,
+  disabled,
+  secureTextEntry,
+  keyboardType,
+  autoCapitalize,
+  autoCorrect,
+  multiline,
+  autoFocus,
+  returnKeyType,
+  submitBehavior,
+  maxLength,
+  accentColor,
+  testID,
+  style,
+}: TextFieldProps) {
+  const input = useRef<TextInput>(null);
+  const [current, setValue] = useTextValue(value, onChangeText);
+  const label = useColor('label');
+  const placeholderColor = useColor('tertiaryLabel');
+  const tint = useColor('tint');
+  const cursor = accentColor ?? tint;
+  useAutoFocus(input, autoFocus);
+
+  return (
+    <TextInput
+      ref={input}
+      value={current}
+      onChangeText={setValue}
+      placeholder={placeholder}
+      placeholderTextColor={placeholderColor}
+      editable={!disabled}
+      secureTextEntry={secureTextEntry}
+      keyboardType={keyboardTypeFor(keyboardType)}
+      autoCapitalize={autoCapitalize}
+      autoCorrect={autoCorrect}
+      multiline={multiline}
+      maxLength={maxLength}
+      cursorColor={cursor}
+      selectionColor={cursor}
+      returnKeyType={returnKeyType}
+      submitBehavior={submitBehavior}
+      onSubmitEditing={onSubmit ? event => onSubmit(event.nativeEvent.text) : undefined}
+      onKeyPress={onKeyPress ? (event: NativeSyntheticEvent<TextInputKeyPressEventData & {shiftKey?: boolean}>) =>
+        onKeyPress(event.nativeEvent.key, event.nativeEvent.shiftKey === true) : undefined}
+      aria-label={placeholder}
+      testID={testID}
+      style={[styles.input, {color: label}, disabled && styles.disabled, style]}
+    />
+  );
+}
+
+const styles = StyleSheet.create({
+  input: {
+    flexGrow: 1,
+    flexShrink: 1,
+    minWidth: 0,
+    margin: 0,
+    paddingVertical: spacing.one,
+    paddingHorizontal: spacing.two,
+    fontSize: 14,
+    fontFamily: fonts?.sans,
+    fontWeight: fontWeights.normal,
+  },
+  disabled: {
+    opacity: 0.4,
+  },
+});

package/src/text-field/shared.ts

@@ -1,6 +1,9 @@
-import type {TextFieldKeyboard} from './types';
+import type {RefObject} from 'react';
+import type {TextInput} from 'react-native';
 import type {ObservableState} from '@expo/ui';
+import type {TextFieldKeyboard} from './types';
 import {useCallback, useEffect, useState} from 'react';
+import {Keyboard, Platform} from 'react-native';
 
 /**
  * Keyboard variants understood by both React Native's `keyboardType` prop and
@@ -14,6 +17,9 @@ type AppleKeyboardType =
   | 'decimal-pad'
   | 'url';
 
+/** How long after the mount the keyboard is looked for (`focusField`). */
+export const FOCUS_RETRY_MS = 150;
+
 /**
  * Bridges controlled and uncontrolled usage on web, mirroring `useDateValue`.
  * When `value` is provided the component is controlled; otherwise it falls back
@@ -83,3 +89,36 @@ export function keyboardTypeFor(type: TextFieldKeyboard | undefined): AppleKeybo
       return 'default';
   }
 }
+
+/**
+ * Focuses a React Native `TextInput` that just mounted, and makes sure its
+ * keyboard came: on Android the first focus asks for the keyboard before the
+ * field is laid out and served by the input method ("Ignoring
+ * showSoftInput() as view is not served"), which leaves a caret in the field
+ * and no keyboard; and a second `focus()` on a focused field is a no-op in
+ * React Native. So a moment later, if the keyboard is still down, the field
+ * is blurred and focused again, a fresh request the input method takes.
+ * Returns the effect's cleanup.
+ */
+export function focusField(input: RefObject<TextInput | null>): () => void {
+  input.current?.focus();
+  if (Platform.OS !== 'android') return () => undefined;
+  const again = setTimeout(() => {
+    const field = input.current;
+    if (!field || Keyboard.isVisible()) return;
+    field.blur();
+    field.focus();
+  }, FOCUS_RETRY_MS);
+  return () => clearTimeout(again);
+}
+
+/**
+ * Focuses the field once it is mounted when `autoFocus` is set (see
+ * `focusField`), for the React Native based fields (web, `inline`).
+ */
+export function useAutoFocus(input: RefObject<TextInput | null>, autoFocus: boolean | undefined): void {
+  useEffect(() => {
+    if (!autoFocus) return;
+    return focusField(input);
+  }, [autoFocus, input]);
+}

package/src/text-field/types.ts

@@ -12,6 +12,25 @@ export type TextFieldKeyboard =
 /** Automatic capitalization behaviour while typing. */
 export type TextFieldCapitalize = 'none' | 'sentences' | 'words' | 'characters';
 
+/** What the keyboard's action key says, and reports through `onSubmit`. */
+export type TextFieldReturnKey = 'done' | 'go' | 'next' | 'search' | 'send';
+
+/**
+ * What happens to the focus when the action key is pressed. `blurAndSubmit`
+ * closes the keyboard; `submit` keeps the field focused so the next press
+ * submits again (an inline search stepping through its matches).
+ */
+export type TextFieldSubmitBehavior = 'blurAndSubmit' | 'submit';
+
+/**
+ * How the field is drawn. `row` is the native form row (SwiftUI `TextField`,
+ * a Compose `TextField` stripped of its container) meant for a
+ * `FieldGroup.Section`; `inline` is a borderless React Native `TextInput` on
+ * every platform, for a field that sits inside a React Native layout (a
+ * search row in a toolbar) where the native control would need a host.
+ */
+export type TextFieldVariant = 'row' | 'inline';
+
 /**
  * Cross-platform single/multi-line text input with a conformed iOS-style
  * appearance — a borderless field whose placeholder doubles as the row label,
@@ -30,6 +49,12 @@ export interface TextFieldProps {
   onChangeText?: (text: string) => void;
   /** Called when the user presses the keyboard return key. Receives the text. */
   onSubmit?: (text: string) => void;
+  /**
+   * Called on a key press with the key's name (`Enter`, `Escape`, `a`) and
+   * whether Shift was held, for keyboard handling the platform does not
+   * cover. `inline` variant only.
+   */
+  onKeyPress?: (key: string, shiftKey: boolean) => void;
   /** Disables editing and dims the field. */
   disabled?: boolean;
   /** Masks the input for sensitive values such as passwords. */
@@ -51,14 +76,34 @@ export interface TextFieldProps {
   autoCorrect?: boolean;
   /** Allows multiple lines of input that grow vertically. */
   multiline?: boolean;
-  /** Focuses the field automatically when mounted. */
+  /**
+   * Focuses the field once it is mounted, and makes sure its keyboard came:
+   * on Android the first focus can be asked for before the field is served
+   * by the input method and dropped, so a moment later, if the keyboard is
+   * still down, the field is focused again.
+   */
   autoFocus?: boolean;
+  /**
+   * What the keyboard's action key says. The key reports through `onSubmit`.
+   * @default 'done'
+   */
+  returnKeyType?: TextFieldReturnKey;
+  /**
+   * Whether the action key closes the keyboard.
+   * @default 'blurAndSubmit'
+   */
+  submitBehavior?: TextFieldSubmitBehavior;
+  /**
+   * The field's look.
+   * @default 'row'
+   */
+  variant?: TextFieldVariant;
   /** Maximum number of characters allowed. Truncates natively as the user types. */
   maxLength?: number;
   /** Tint applied to the cursor/selection (web/android) and the field (iOS). */
   accentColor?: string;
   /** Identifier used to locate the component in end-to-end tests. */
   testID?: string;
-  /** Style applied to the text content (web only). */
+  /** Style applied to the text content (web and the `inline` variant). */
   style?: StyleProp<TextStyle>;
 }

package/src/theme.ts

@@ -2,14 +2,18 @@ import './global.css';
 import type {CSSProperties} from 'react';
 import type {ColorValue, TextStyle} from 'react-native';
 
+import {useMemo} from 'react';
 import {DefaultTheme} from 'expo-router';
-import {Platform, PlatformColor, useColorScheme} from 'react-native';
+import {Platform, PlatformColor} from 'react-native';
 import {TypographyVariant, TypographyStyle} from './typography/types';
 import {ACCENT_SEED, onAccent, useAccentSeed} from './accent';
+import {useColorScheme} from './scheme';
 
 export type VariantMap = Record<TypographyVariant, TypographyStyle>;
 export type ColorTokens = keyof typeof colors[keyof typeof colors];
 export type ColorValues = typeof colors[keyof typeof colors];
+/** A resolved palette: one plain color string per token (see `usePalette`). */
+export type Palette = Record<ColorTokens, string>;
 export type ColorNative = ColorValue | (() => ColorValue);
 
 export const VALID_STYLES = [
@@ -378,7 +382,7 @@ export function useNavTheme() {
   if (Platform.OS === 'web') return nav;
   /* eslint-disable react-hooks/rules-of-hooks -- Platform.OS is a runtime constant. */
   const seed = useAccentSeed();
-  const palette = colors[useColorScheme() === 'dark' ? 'dark' : 'light'];
+  const palette = colors[useColorScheme()];
   /* eslint-enable react-hooks/rules-of-hooks */
   return {
     ...nav,
@@ -445,13 +449,30 @@ export function useColor(token: ColorTokens): string {
   if (Platform.OS === 'web') return theme[token] as string;
   /* eslint-disable react-hooks/rules-of-hooks -- Platform.OS is a runtime constant. */
   const seed = useAccentSeed();
-  const scheme = useColorScheme() === 'dark' ? 'dark' : 'light';
+  const scheme = useColorScheme();
   /* eslint-enable react-hooks/rules-of-hooks */
   if (token === 'tint') return seed;
   if (token === 'onTint') return onAccent(seed);
   return colors[scheme][token];
 }
 
+/**
+ * The resolved palette of the current scheme, with the live accent seed as
+ * `tint` and its contrast as `onTint`: plain color strings on every platform,
+ * including web. `useColor` stays the right call for styles (on web it hands
+ * out the CSS variable, which follows the scheme without a re-render);
+ * `usePalette` is for canvases, native views and anything else that cannot
+ * read a variable.
+ */
+export function usePalette(): Palette {
+  const seed = useAccentSeed();
+  const scheme = useColorScheme();
+  return useMemo(
+    () => ({...colors[scheme], tint: seed, onTint: onAccent(seed)}),
+    [scheme, seed],
+  );
+}
+
 export function getPlatformToken(specifics: {
   default: ColorValue;
   android: ColorNative;
@@ -471,10 +492,20 @@ export function getPlatformToken(specifics: {
   }
 }
 
+/**
+ * The palette as `--color-*` custom properties for `+html.tsx`: the light
+ * values on `:root`, the dark ones under the `prefers-color-scheme` media
+ * query, and both again keyed on `data-theme`, which `setColorScheme` (and
+ * the `getThemeBootScript` boot script) set on the root element to force a
+ * scheme regardless of the system's. `tint`/`onTint` are the same in both
+ * schemes, so the forced palettes leave them to the defaults and to
+ * `AccentProvider`.
+ */
 export function getThemeCSS(): string {
   const format = (s: string) => s.replace(/[A-Z]/g, v => `-${v.toLowerCase()}`);
-  const render = (o: ColorValues) => Object.entries(o).map(([k,v]) =>
-    `\t\t${`--color-${format(k)}`}: ${v};`).join('\n');
+  const render = (o: ColorValues, skipAccent = false) => Object.entries(o)
+    .filter(([k]) => !skipAccent || (k !== 'tint' && k !== 'onTint'))
+    .map(([k,v]) => `\t\t${`--color-${format(k)}`}: ${v};`).join('\n');
   return `
     :root {
       color-scheme: light dark;
@@ -485,6 +516,14 @@ export function getThemeCSS(): string {
         ${render(colors.dark)}
       }
     }
+    :root[data-theme="light"] {
+      color-scheme: light;
+      ${render(colors.light, true)}
+    }
+    :root[data-theme="dark"] {
+      color-scheme: dark;
+      ${render(colors.dark, true)}
+    }
   `;
 }