react-native-platform-components 1.3.0 → 1.4.0

package/src/focusRegistry.ts

@@ -0,0 +1,89 @@
+// 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/icons.ts

@@ -0,0 +1,116 @@
+// 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`.
+ */
+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;
+  /** 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: '',
+  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;
+      return {
+        iconType: 'image',
+        iconName: '',
+        iconUri: resolved.uri,
+        iconScale: resolved.scale > 0 ? resolved.scale : 1,
+        iconTinted: source.tinted === false ? 'false' : 'true',
+      };
+    }
+    default:
+      return NO_ICON;
+  }
+}

package/src/index.tsx

@@ -2,6 +2,12 @@ export * from './DatePicker';
 export * from './SelectionMenu';
 export * from './ContextMenu';
 export * from './SegmentedControl';
+export * from './Button';
+export * from './ButtonGroup';
+export * from './FloatingToolbar';
 export * from './LiquidGlass';
+export * from './TextField';
+export * from './icons';
+export * from './labelStyle';
 export * from './sharedTypes';
 export * from './NativeTheme';

package/src/index.web.tsx

@@ -6,6 +6,8 @@
 import React from 'react';
 import type { ReactNode } from 'react';
 import type { ColorValue, StyleProp, ViewStyle, ViewProps } from 'react-native';
+import type { PlatformIcon } from './icons';
+import type { LabelStyle } from './labelStyle';
 
 // ============================================================================
 // Shared Types (duplicated to avoid importing from files with native deps)
@@ -164,6 +166,90 @@ export const SegmentedControl = (
   _props: SegmentedControlProps
 ): React.ReactElement | null => null;
 
+// ============================================================================
+// Button, ButtonGroup, FloatingToolbar
+// ============================================================================
+
+export type {
+  PlatformIcon,
+  PlatformIconSource,
+  NativeIconFields,
+} from './icons';
+export type { LabelStyle, NativeLabelStyle } from './labelStyle';
+
+export type ButtonVariant =
+  'filled' | 'tonal' | 'outlined' | 'text' | 'elevated';
+export type ButtonSize = 'xsmall' | 'small' | 'medium' | 'large' | 'xlarge';
+export type ButtonShape = 'round' | 'square';
+
+export interface ButtonProps extends ViewProps {
+  label?: string;
+  icon?: PlatformIcon;
+  variant?: ButtonVariant;
+  size?: ButtonSize;
+  shape?: ButtonShape;
+  disabled?: boolean;
+  color?: ColorValue;
+  tintColor?: ColorValue;
+  labelStyle?: LabelStyle;
+  accessibilityLabel?: string;
+  onPress?: () => void;
+  android?: Record<string, unknown>;
+}
+
+export const Button = (_props: ButtonProps): React.ReactElement | null => null;
+
+export type ButtonGroupSelection = 'none' | 'single' | 'multiple';
+export type ButtonGroupOverflow = 'none' | 'menu' | 'wrap';
+
+export interface ButtonGroupButtonProps {
+  label?: string;
+  value: string;
+  disabled?: boolean;
+  icon?: PlatformIcon;
+  accessibilityLabel?: string;
+}
+
+export interface ButtonGroupProps extends ViewProps {
+  buttons: readonly ButtonGroupButtonProps[];
+  variant?: ButtonVariant;
+  size?: ButtonSize;
+  shape?: ButtonShape;
+  connected?: boolean;
+  spacing?: number;
+  selection?: ButtonGroupSelection;
+  selectedValues?: readonly string[];
+  selectionRequired?: boolean;
+  disabled?: boolean;
+  color?: ColorValue;
+  tintColor?: ColorValue;
+  labelStyle?: LabelStyle;
+  onPress?: (value: string, index: number) => void;
+  onSelectionChange?: (values: string[]) => void;
+  android?: Record<string, unknown>;
+}
+
+export const ButtonGroup = (
+  _props: ButtonGroupProps
+): React.ReactElement | null => null;
+
+export type FloatingToolbarIOSEffect = 'regular' | 'clear';
+export type FloatingToolbarAndroidVariant = 'standard' | 'vibrant';
+
+export interface FloatingToolbarProps extends ViewProps {
+  orientation?: 'horizontal' | 'vertical';
+  color?: ColorValue;
+  ios?: Record<string, unknown>;
+  android?: Record<string, unknown>;
+  children?: ReactNode;
+}
+
+export const FloatingToolbar = ({
+  children,
+}: FloatingToolbarProps): React.ReactElement | null => {
+  return <>{children}</>;
+};
+
 // ============================================================================
 // LiquidGlass
 // ============================================================================
@@ -183,6 +269,114 @@ export const LiquidGlass = ({
 
 export const isLiquidGlassSupported = false;
 
+// ============================================================================
+// TextField
+// ============================================================================
+
+export type TextFieldKeyboardType =
+  | 'default'
+  | 'number-pad'
+  | 'decimal-pad'
+  | 'numeric'
+  | 'email-address'
+  | 'phone-pad'
+  | 'url'
+  | 'ascii-capable'
+  | 'numbers-and-punctuation'
+  | 'name-phone-pad'
+  | 'twitter'
+  | 'web-search'
+  | 'visible-password';
+export type TextFieldReturnKeyType =
+  'default' | 'done' | 'go' | 'next' | 'search' | 'send' | 'none' | 'previous';
+export type TextFieldAutoComplete =
+  | 'off'
+  | 'username'
+  | 'password'
+  | 'new-password'
+  | 'one-time-code'
+  | 'email'
+  | 'name'
+  | 'given-name'
+  | 'family-name'
+  | 'tel'
+  | 'street-address'
+  | 'postal-code'
+  | 'country'
+  | 'cc-number'
+  | 'cc-exp'
+  | 'cc-csc'
+  | 'url';
+export type TextFieldAutoCapitalize =
+  'none' | 'sentences' | 'words' | 'characters';
+export type TextFieldClearButtonMode =
+  'never' | 'while-editing' | 'unless-editing' | 'always';
+export type TextFieldIOSChoice = 'default' | 'yes' | 'no';
+export type TextFieldEvent = { nativeEvent: { text: string } };
+export type TextFieldChangeEvent = {
+  nativeEvent: { text: string; eventCount: number };
+};
+
+export interface TextFieldRef {
+  focus(): void;
+  blur(): void;
+  clear(): void;
+  isFocused(): boolean;
+}
+
+export interface TextFieldProps extends Omit<
+  ViewProps,
+  'onFocus' | 'onBlur' | 'children'
+> {
+  value?: string;
+  defaultValue?: string;
+  onChangeText?: (text: string) => void;
+  onChange?: (event: TextFieldChangeEvent) => void;
+  onFocus?: (event: TextFieldEvent) => void;
+  onBlur?: (event: TextFieldEvent) => void;
+  onSubmitEditing?: (event: TextFieldEvent) => void;
+  label?: string;
+  placeholder?: string;
+  supportingText?: string;
+  error?: boolean | string;
+  prefix?: string;
+  suffix?: string;
+  leadingIcon?: PlatformIcon;
+  trailingIcon?: PlatformIcon;
+  onTrailingIconPress?: () => void;
+  clearButtonMode?: TextFieldClearButtonMode;
+  passwordToggle?: boolean;
+  showCharacterCount?: boolean;
+  maxLength?: number;
+  keyboardType?: TextFieldKeyboardType;
+  returnKeyType?: TextFieldReturnKeyType;
+  autoCapitalize?: TextFieldAutoCapitalize;
+  autoCorrect?: boolean;
+  secureTextEntry?: boolean;
+  multiline?: boolean;
+  editable?: boolean;
+  autoFocus?: boolean;
+  selectTextOnFocus?: boolean;
+  autoComplete?: TextFieldAutoComplete;
+  keyboardAppearance?: 'default' | 'light' | 'dark';
+  textStyle?: LabelStyle;
+  accessibilityLabel?: string;
+  ios?: Record<string, unknown>;
+  android?: Record<string, unknown>;
+}
+
+export const TextField = React.forwardRef<TextFieldRef, TextFieldProps>(
+  function TextFieldComponent(_props, ref): React.ReactElement | null {
+    React.useImperativeHandle(ref, () => ({
+      focus: () => {},
+      blur: () => {},
+      clear: () => {},
+      isFocused: () => false,
+    }));
+    return null;
+  }
+);
+
 // ============================================================================
 // Native theme
 // ============================================================================

package/src/labelStyle.ts

@@ -0,0 +1,36 @@
+// labelStyle.ts
+//
+// Label font props shared by SegmentedControl, Button and ButtonGroup.
+import type { TextStyle } from 'react-native';
+
+/**
+ * Font for a control's labels. Each field falls back to the platform default.
+ */
+export interface LabelStyle {
+  fontFamily?: string;
+  fontSize?: number;
+  fontWeight?: TextStyle['fontWeight'];
+  fontStyle?: 'normal' | 'italic';
+}
+
+/** The flat font fields the native specs expect; empty / 0 = default. */
+export type NativeLabelStyle = {
+  fontFamily: string;
+  fontSize: number;
+  fontWeight: string;
+  fontStyle: string;
+};
+
+/** Normalizes a label font for native; `undefined` keeps the platform font. */
+export function normalizeLabelStyle(
+  labelStyle: LabelStyle | undefined
+): NativeLabelStyle | undefined {
+  if (!labelStyle) return undefined;
+  return {
+    fontFamily: labelStyle.fontFamily ?? '',
+    fontSize: labelStyle.fontSize ?? 0,
+    fontWeight:
+      labelStyle.fontWeight === undefined ? '' : String(labelStyle.fontWeight),
+    fontStyle: labelStyle.fontStyle ?? '',
+  };
+}

package/src/reactNativeInternals.d.ts

@@ -0,0 +1,22 @@
+// reactNativeInternals.d.ts
+//
+// React Native's focus registry for text inputs. `Keyboard.dismiss()`, a
+// ScrollView's `keyboardShouldPersistTaps` and `KeyboardAvoidingView` all act
+// on the input registered here, so TextField registers itself like the core
+// TextInput does. The module is a stable internal (it has kept this shape
+// since 0.63), but it is not part of the strict API's type exports, hence this
+// declaration.
+declare module 'react-native/Libraries/Components/TextInput/TextInputState' {
+  type HostInput = object;
+
+  const TextInputState: {
+    currentlyFocusedInput(): HostInput | null | undefined;
+    focusInput(input: HostInput | null | undefined): void;
+    blurInput(input: HostInput | null | undefined): void;
+    registerInput(input: HostInput): void;
+    unregisterInput(input: HostInput): void;
+    isTextInput(input: HostInput): boolean;
+  };
+
+  export default TextInputState;
+}

package/src/sharedTypes.ts

@@ -7,9 +7,15 @@ export type Visible = 'open' | 'closed';
 /** Shared presentation mode for pickers/menus. */
 export type Presentation = 'modal' | 'embedded';
 
-/** Shared Material preference (Android). */
+/** Shared Material preference (Android): the platform widget or the Material one. */
 export type AndroidMaterialMode = 'system' | 'm3';
 
+/**
+ * Shared Material style for the Material-only components (Android):
+ * Material 3, or Material 3 Expressive (the default).
+ */
+export type AndroidMaterialStyle = 'm3' | 'expressive';
+
 /** Common event empty payload type. */
 export type EmptyEvent = Readonly<{}>;