react-native-platform-components 1.3.0 → 1.5.0

package/src/TextFieldNativeComponent.ts

@@ -0,0 +1,324 @@
+// TextFieldNativeComponent.ts
+import type * as React from 'react';
+import type { ColorValue, HostComponent, ViewProps } from 'react-native';
+import { codegenNativeCommands, codegenNativeComponent } from 'react-native';
+import type { BubblingEventHandler, Double, Int32 } from './codegenTypes';
+
+/**
+ * Icon fields, pre-resolved on the JS side (see icons.ts).
+ */
+export type TextFieldIconProps = Readonly<{
+  iconType: string; // '' | 'sfSymbol' | 'drawable' | 'image'
+  iconName: string; // SF Symbol (iOS) or drawable resource name (Android)
+  iconRequest: string;
+  iconUri: string; // Resolved image URI when iconType === 'image'
+  iconScale: Double; // Resolved image scale when iconType === 'image'
+  iconTinted: string; // 'true' | 'false' — draw the image as a tinted template
+}>;
+
+/**
+ * Text font. Empty strings / 0 mean "platform default".
+ */
+export type TextFieldTextStyleProps = Readonly<{
+  fontFamily?: string;
+  fontSize?: Double;
+  fontWeight?: string; // 'normal' | 'bold' | '100'..'900'
+  fontStyle?: string; // 'normal' | 'italic'
+}>;
+
+/**
+ * Fired on every edit. `eventCount` is the native edit counter that JS hands
+ * back with `setText`, so a stale controlled value can't overwrite what the
+ * user typed since.
+ */
+export type TextFieldChangeEvent = Readonly<{
+  text: string;
+  eventCount: Int32;
+}>;
+
+/** Focus, blur and submit carry the text at that moment. */
+export type TextFieldTextEvent = Readonly<{
+  text: string;
+}>;
+
+/** The cursor or selection, as UTF-16 offsets into the text. */
+export type TextFieldSelectionEvent = Readonly<{
+  start: Int32;
+  end: Int32;
+}>;
+
+/** A press on a keyboard toolbar button (iOS). */
+export type TextFieldToolbarPressEvent = Readonly<{
+  itemId: string;
+}>;
+
+/**
+ * A keyboard toolbar item (iOS). Icons are pre-resolved on the JS side (see
+ * icons.ts); empty strings mean "none".
+ */
+export type TextFieldToolbarItem = Readonly<{
+  kind: string; // 'button' | 'done' | 'flexibleSpace'
+  itemId: string;
+  title: string;
+  systemItem: string; // '' | UIBarButtonItem.SystemItem name
+  iconType: string; // '' | 'sfSymbol' | 'image'
+  iconName: string;
+  iconRequest: string;
+  iconUri: string;
+  iconScale: Double;
+  iconTinted: string; // 'true' | 'false'
+  prominent: string; // 'true' | 'false'
+  accessibilityLabel: string;
+  testID: string;
+}>;
+
+/**
+ * iOS-specific configuration. Every field is '' for the platform default.
+ */
+export type TextFieldIOSProps = Readonly<{
+  /** 'default' | 'complete' | 'limited' | 'none' (iOS 18) */
+  writingTools?: string;
+  /** 'default' | 'yes' | 'no' (iOS 17) */
+  inlinePrediction?: string;
+  /** 'default' | 'yes' | 'no' */
+  smartQuotes?: string;
+  /** 'default' | 'yes' | 'no' */
+  smartDashes?: string;
+  /** 'default' | 'yes' | 'no' */
+  smartInsertDelete?: string;
+  /** 'default' | 'yes' | 'no' (iOS 18) */
+  mathExpressionCompletion?: string;
+  /** 'roundedRect' | 'none' | 'line' | 'bezel' */
+  borderStyle?: string;
+  /** 'above' | 'leading': where the label sits */
+  labelPlacement?: string;
+  /** Width of a leading label column in points; 0 = default */
+  labelWidth?: Double;
+  /** UITextInputPasswordRules descriptor; '' = none */
+  passwordRules?: string;
+}>;
+
+/**
+ * Android-specific configuration.
+ */
+export type TextFieldAndroidProps = Readonly<{
+  /** 'm3' | 'system' (AndroidMaterialMode) */
+  material?: string;
+  /** 'outlined' | 'filled' | 'plain' */
+  variant?: string;
+  /** 'standard' | 'dense' */
+  density?: string;
+}>;
+
+export interface TextFieldNativeProps extends ViewProps {
+  /**
+   * Text applied when the native view is created. Later updates go through
+   * the `setText` command so they can be checked against `eventCount`.
+   */
+  initialText?: string;
+
+  /** Floating label (Android) / caption above the field (iOS). */
+  label?: string;
+
+  /** Placeholder shown while the field is empty. */
+  placeholder?: string;
+
+  /** Helper text below the field. */
+  supportingText?: string;
+
+  /** 'none' | 'error' */
+  errorState?: string;
+
+  /** Error message shown instead of the supporting text. */
+  errorText?: string;
+
+  /** Text shown before the input, inside the field. */
+  prefix?: string;
+
+  /** Text shown after the input, inside the field. */
+  suffix?: string;
+
+  /** Icon at the start of the field. */
+  leadingIcon?: TextFieldIconProps;
+
+  /** Icon at the end of the field; pressing it fires onTrailingIconPress. */
+  trailingIcon?: TextFieldIconProps;
+
+  /** 'never' | 'while-editing' | 'unless-editing' | 'always' */
+  clearButtonMode?: string;
+
+  /** 'shown' | 'hidden': a button that toggles secure text entry. */
+  passwordToggle?: string;
+
+  /** 'shown' | 'hidden': the character counter. */
+  characterCount?: string;
+
+  /** Maximum number of UTF-16 characters; 0 = unlimited. */
+  maxLength?: Int32;
+
+  /** React Native keyboardType value. */
+  keyboardType?: string;
+
+  /** React Native returnKeyType value. */
+  returnKeyType?: string;
+
+  /** 'none' | 'sentences' | 'words' | 'characters' */
+  autoCapitalize?: string;
+
+  /** 'enabled' | 'disabled' */
+  autoCorrect?: string;
+
+  /** 'secure' | 'plain' */
+  secureTextEntry?: string;
+
+  /** 'single' | 'multiline' */
+  lines?: string;
+
+  /**
+   * What the return key does: 'submit' | 'blurAndSubmit' | 'newline',
+   * resolved on the JS side ('newline' only for multi-line fields).
+   */
+  submitBehavior?: string;
+
+  /** iOS: the keyboard toolbar (inputAccessoryView); empty = none. */
+  keyboardToolbarItems?: ReadonlyArray<TextFieldToolbarItem>;
+
+  /** 'enabled' | 'disabled' */
+  interactivity?: string;
+
+  /** 'focus' | 'none': focus the field when it mounts. */
+  autoFocus?: string;
+
+  /** 'select' | 'keep': select all text on focus. */
+  selectTextOnFocus?: string;
+
+  /** React Native autoComplete value; '' = platform default. */
+  autoComplete?: string;
+
+  /** 'default' | 'light' | 'dark' (iOS keyboard appearance) */
+  keyboardAppearance?: string;
+
+  /** Font of the input text. */
+  textStyle?: TextFieldTextStyleProps;
+
+  /**
+   * Screen-reader label, applied to the native field rather than the host
+   * view. Empty means "use the label".
+   */
+  spokenLabel?: string;
+
+  /** E2E identifier of the leading icon. */
+  leadingIconTestID?: string;
+
+  /** Screen-reader label of the leading icon. */
+  leadingIconSpokenLabel?: string;
+
+  /** E2E identifier of the trailing icon. */
+  trailingIconTestID?: string;
+
+  /** Screen-reader label of the trailing icon. */
+  trailingIconSpokenLabel?: string;
+
+  /** Focused outline, focused label and cursor color. */
+  activeColor?: ColorValue;
+
+  /** Unfocused outline (underline for the filled variant) color. */
+  outlineColor?: ColorValue;
+
+  /** Error outline, label and message color. */
+  errorColor?: ColorValue;
+
+  /** Background of the field's box. */
+  containerColor?: ColorValue;
+
+  /** Input text color. */
+  textColor?: ColorValue;
+
+  /** Placeholder color. */
+  placeholderTextColor?: ColorValue;
+
+  /** Largest font scale the text may reach; 0 = no cap. */
+  maxFontSizeMultiplier?: Double;
+
+  /** '' (natural) | 'left' | 'center' | 'right' */
+  textAlign?: string;
+
+  /** Multi-line: minimum and maximum visible lines; 0 = unset. */
+  minLines?: Int32;
+  maxLines?: Int32;
+
+  /** 'none' | 'button': a non-editable field that fires onFieldPress. */
+  pressMode?: string;
+
+  ios?: TextFieldIOSProps;
+  android?: TextFieldAndroidProps;
+
+  /** Fired on every user edit. */
+  onFieldChange?: BubblingEventHandler<TextFieldChangeEvent>;
+
+  /** Fired when the field gains focus. */
+  onFieldFocus?: BubblingEventHandler<TextFieldTextEvent>;
+
+  /** Fired when the field loses focus. */
+  onFieldBlur?: BubblingEventHandler<TextFieldTextEvent>;
+
+  /** Fired when the return key submits (see submitBehavior). */
+  onFieldSubmit?: BubblingEventHandler<TextFieldTextEvent>;
+
+  /** Fired when the cursor moves or the selection changes. */
+  onFieldSelectionChange?: BubblingEventHandler<TextFieldSelectionEvent>;
+
+  /** iOS: fired when a keyboard toolbar button (other than Done) is pressed. */
+  onKeyboardToolbarPress?: BubblingEventHandler<TextFieldToolbarPressEvent>;
+
+  /** Fired when the trailing icon is pressed. */
+  onTrailingIconPress?: BubblingEventHandler<Readonly<{}>>;
+
+  /** Fired when a field with pressMode 'button' is pressed. */
+  onFieldPress?: BubblingEventHandler<Readonly<{}>>;
+}
+
+type NativeTextFieldComponent = HostComponent<TextFieldNativeProps>;
+
+// `React.ElementRef` rather than `React.ComponentRef`: the codegen shipped with
+// React Native 0.81 (and the 0.76 Android floor) only accepts the former.
+interface NativeCommands {
+  /** Focuses the field and shows the keyboard. */
+  focus: (viewRef: React.ElementRef<NativeTextFieldComponent>) => void;
+
+  /** Removes focus and hides the keyboard. */
+  blur: (viewRef: React.ElementRef<NativeTextFieldComponent>) => void;
+
+  /** Clears the text; fires onFieldChange like a user edit. */
+  clear: (viewRef: React.ElementRef<NativeTextFieldComponent>) => void;
+
+  /**
+   * Replaces the text, unless the user has edited since `eventCount` was
+   * reported, in which case the update is dropped and the next edit event
+   * brings JS back in sync.
+   */
+  setText: (
+    viewRef: React.ElementRef<NativeTextFieldComponent>,
+    eventCount: Int32,
+    text: string
+  ) => void;
+
+  /**
+   * Selects `start`..`end` (UTF-16 offsets, clamped to the text), unless the
+   * user has edited since `eventCount` was reported, as for `setText`.
+   */
+  setSelection: (
+    viewRef: React.ElementRef<NativeTextFieldComponent>,
+    eventCount: Int32,
+    start: Int32,
+    end: Int32
+  ) => void;
+}
+
+export const Commands: NativeCommands = codegenNativeCommands<NativeCommands>({
+  supportedCommands: ['focus', 'blur', 'clear', 'setText', 'setSelection'],
+});
+
+export default codegenNativeComponent<TextFieldNativeProps>(
+  'PCTextField'
+) as NativeTextFieldComponent;

package/src/focusRegistry.ts

@@ -0,0 +1,90 @@
+/// <reference path="./reactNativeInternals.d.ts" />
+// focusRegistry.ts
+//
+// TextField's link to React Native's focused-input bookkeeping. The core
+// TextInput registers its host node with `TextInputState`, and that registry is
+// what `Keyboard.dismiss()`, a ScrollView's `keyboardShouldPersistTaps` and
+// `keyboardDismissMode`, and `KeyboardAvoidingView` act on. Registering the
+// same way makes a TextField behave like a TextInput for all of them.
+//
+// `TextInputState` is a stable internal (it has kept this shape since 0.63),
+// but React Native's Babel preset adds a dev-time warning to every static
+// `import` or `require` of a deep path. A dynamic `import()` is resolved by
+// Metro the same way and carries no warning; it settles in a microtask at
+// startup, so a node registered before then is kept and registered once the
+// module arrives. If a future release drops the path, the registry is simply
+// absent and the field falls back to the public `TextInput.State` calls for
+// focus and blur, keeping `Keyboard.dismiss()` working.
+import { TextInput } from 'react-native';
+
+type HostNode = object;
+
+type Registry = {
+  currentlyFocusedInput(): HostNode | null | undefined;
+  focusInput(input: HostNode | null | undefined): void;
+  blurInput(input: HostNode | null | undefined): void;
+  registerInput(input: HostNode): void;
+  unregisterInput(input: HostNode): void;
+  isTextInput(input: HostNode): boolean;
+};
+
+let registry: Registry | undefined;
+const pendingRegistrations = new Set<HostNode>();
+
+// A stable internal without a public counterpart; see reactNativeInternals.d.ts.
+
+import('react-native/Libraries/Components/TextInput/TextInputState')
+  .then((module) => {
+    registry = module.default;
+    pendingRegistrations.forEach((node) => registry?.registerInput(node));
+    pendingRegistrations.clear();
+  })
+  .catch(() => {
+    // Not available: focus and blur still go through TextInput.State below.
+  });
+
+export const focusRegistry = {
+  /** Called when the field mounts. */
+  register(node: HostNode): void {
+    if (registry) {
+      registry.registerInput(node);
+    } else {
+      pendingRegistrations.add(node);
+    }
+  },
+
+  /** Called when the field unmounts; drops the focus if the field held it. */
+  unregister(node: HostNode): void {
+    pendingRegistrations.delete(node);
+    if (registry) {
+      registry.unregisterInput(node);
+      if (registry.currentlyFocusedInput() === node) {
+        registry.blurInput(node);
+      }
+    } else if (TextInput.State.currentlyFocusedInput() === node) {
+      TextInput.State.blurTextInput(node as never);
+    }
+  },
+
+  /** The field gained focus natively. */
+  focused(node: HostNode | null): void {
+    if (node == null) return;
+    if (registry) {
+      registry.focusInput(node);
+    } else {
+      // Also re-sends the focus command, which the focused field ignores
+      TextInput.State.focusTextInput(node as never);
+    }
+  },
+
+  /** The field lost focus natively. */
+  blurred(node: HostNode | null): void {
+    if (node == null) return;
+    if (registry) {
+      registry.blurInput(node);
+    } else {
+      // Also re-sends the blur command, which the unfocused field ignores
+      TextInput.State.blurTextInput(node as never);
+    }
+  },
+};

package/src/haptics.ts

@@ -0,0 +1,31 @@
+// haptics.ts
+//
+// The `haptics` prop shared by the interactive components.
+
+/**
+ * Haptic feedback a control plays when the user acts on it: a press, a
+ * selection change or a menu pick. Unset plays nothing beyond what the
+ * platform control does itself.
+ *
+ * | Value       | iOS                                        | Android (`HapticFeedbackConstants`)    |
+ * | ----------- | ------------------------------------------ | -------------------------------------- |
+ * | `selection` | `UISelectionFeedbackGenerator`             | `SEGMENT_TICK` (API 34+), else `CLOCK_TICK` |
+ * | `light`     | `UIImpactFeedbackGenerator` `.light`       | `CONTEXT_CLICK`                        |
+ * | `medium`    | `UIImpactFeedbackGenerator` `.medium`      | `VIRTUAL_KEY`                          |
+ * | `heavy`     | `UIImpactFeedbackGenerator` `.heavy`       | `LONG_PRESS`                           |
+ * | `success`   | `UINotificationFeedbackGenerator` `.success` | `CONFIRM` (API 30+), else `VIRTUAL_KEY` |
+ * | `warning`   | `UINotificationFeedbackGenerator` `.warning` | `REJECT` (API 30+), else `LONG_PRESS` |
+ * | `error`     | `UINotificationFeedbackGenerator` `.error` | `REJECT` (API 30+), else `LONG_PRESS`  |
+ * | `none`      | Nothing                                    | Nothing, and turns off the view's own haptic (`isHapticFeedbackEnabled`) |
+ *
+ * Both platforms follow the system haptics setting. Web ignores the prop.
+ */
+export type Haptics =
+  | 'selection'
+  | 'light'
+  | 'medium'
+  | 'heavy'
+  | 'success'
+  | 'warning'
+  | 'error'
+  | 'none';

package/src/icons.ts

@@ -0,0 +1,143 @@
+// icons.ts
+//
+// Icon props shared by SegmentedControl, Button and ButtonGroup. Icons are
+// resolved on the JS side so native only deals with flat strings.
+import {
+  Image,
+  Platform,
+  type ImageRequireSource,
+  type ImageURISource,
+} from 'react-native';
+
+/**
+ * A single icon source.
+ *
+ * - `string`: shorthand for an SF Symbol name on iOS and a drawable resource
+ *   name on Android.
+ * - `{ type: 'sfSymbol' }`: an SF Symbol. iOS only; ignored on Android.
+ * - `{ type: 'drawable' }`: a drawable from the app's `res/drawable`.
+ *   Android only; ignored on iOS.
+ * - `{ type: 'image' }`: an image asset (`require('./icon.png')`) or a
+ *   `{ uri }` source. Works on both platforms. Images are drawn as tinted
+ *   templates unless `tinted` is `false`. Native loaders forward `headers`,
+ *   `method` and `body`. `cache` controls the decoded in-memory image cache:
+ *   `reload` bypasses it, `only-if-cached` never fetches, and `default` /
+ *   `force-cache` reuse a matching cached request. HTTP redirects carrying
+ *   custom request options are not followed.
+ */
+export type PlatformIconSource =
+  | string
+  | { type: 'sfSymbol'; name: string }
+  | { type: 'drawable'; name: string }
+  | {
+      type: 'image';
+      source: ImageRequireSource | ImageURISource;
+      tinted?: boolean;
+    };
+
+/**
+ * An icon: a single source used on both platforms, or a per-platform pair so
+ * callers don't need to branch on `Platform.OS`.
+ */
+export type PlatformIcon =
+  | PlatformIconSource
+  | {
+      ios?: PlatformIconSource;
+      android?: PlatformIconSource;
+    };
+
+/** The flat icon fields the native specs expect. */
+export type NativeIconFields = {
+  /** '' | 'sfSymbol' | 'drawable' | 'image' */
+  iconType: string;
+  /** SF Symbol (iOS) or drawable resource name (Android) */
+  iconName: string;
+  /** Resolved image URI when iconType === 'image' */
+  iconUri: string;
+  /** Serialized HTTP request options; empty for ordinary image assets. */
+  iconRequest: string;
+  /** Resolved image scale when iconType === 'image' */
+  iconScale: number;
+  /** 'true' | 'false': draw the image as a tinted template */
+  iconTinted: string;
+};
+
+export const NO_ICON: NativeIconFields = {
+  iconType: '',
+  iconName: '',
+  iconUri: '',
+  iconRequest: '',
+  iconScale: 1,
+  iconTinted: 'true',
+};
+
+function pickIconSource(
+  icon: PlatformIcon | undefined
+): PlatformIconSource | undefined {
+  if (icon === undefined || typeof icon === 'string' || 'type' in icon) {
+    return icon;
+  }
+  return Platform.OS === 'ios' ? icon.ios : icon.android;
+}
+
+/**
+ * Flattens the public icon shape into the strings native expects, dropping
+ * sources that don't apply to the current platform.
+ */
+export function resolveIcon(icon: PlatformIcon | undefined): NativeIconFields {
+  const source = pickIconSource(icon);
+  if (source === undefined) return NO_ICON;
+
+  if (typeof source === 'string') {
+    if (source.length === 0) return NO_ICON;
+    return {
+      ...NO_ICON,
+      iconType: Platform.OS === 'ios' ? 'sfSymbol' : 'drawable',
+      iconName: source,
+    };
+  }
+
+  switch (source.type) {
+    case 'sfSymbol':
+      return Platform.OS === 'ios'
+        ? { ...NO_ICON, iconType: 'sfSymbol', iconName: source.name }
+        : NO_ICON;
+    case 'drawable':
+      return Platform.OS === 'android'
+        ? { ...NO_ICON, iconType: 'drawable', iconName: source.name }
+        : NO_ICON;
+    case 'image': {
+      const resolved = Image.resolveAssetSource(source.source);
+      if (!resolved?.uri) return NO_ICON;
+      const request =
+        typeof source.source === 'object' ? source.source : undefined;
+      const headers = request?.headers
+        ? Object.fromEntries(
+            Object.entries(request.headers).sort(([a], [b]) =>
+              a.localeCompare(b)
+            )
+          )
+        : undefined;
+      const requestOptions = {
+        headers,
+        method: request?.method,
+        body: request?.body,
+        cache: request?.cache,
+      };
+      return {
+        iconType: 'image',
+        iconName: '',
+        iconUri: resolved.uri,
+        iconRequest: Object.values(requestOptions).some(
+          (value) => value !== undefined
+        )
+          ? JSON.stringify(requestOptions)
+          : '',
+        iconScale: resolved.scale > 0 ? resolved.scale : 1,
+        iconTinted: source.tinted === false ? 'false' : 'true',
+      };
+    }
+    default:
+      return NO_ICON;
+  }
+}

package/src/index.tsx

@@ -2,6 +2,19 @@ export * from './DatePicker';
 export * from './SelectionMenu';
 export * from './ContextMenu';
 export * from './SegmentedControl';
+export * from './TabBar';
+export * from './FloatingActionButton';
+export * from './NavigationRail';
+export * from './Button';
+export * from './ButtonGroup';
+export * from './SplitButton';
+export * from './FloatingToolbar';
 export * from './LiquidGlass';
+export * from './LiquidGlassContainer';
+export * from './TextField';
+export * from './icons';
+export * from './labelStyle';
 export * from './sharedTypes';
+export * from './haptics';
 export * from './NativeTheme';
+export * from './PlatformComponentsProvider';