From d00f0882fbdd532f8698d2569bd771ca5843d0f5 Mon Sep 17 00:00:00 2001 From: empyrical Date: Wed, 14 Aug 2019 11:29:25 -0700 Subject: [PATCH] Add documentation to TextInput's Flow types (#26054) Summary: The documentation from the Flow types' respective proptypes have been copied over to `TextInput`. ## Changelog [Internal] [Changed] - Added documentation to TextInput's Flow types Pull Request resolved: https://github.com/facebook/react-native/pull/26054 Test Plan: `yarn flow-check-ios` and `yarn flow-check-android` both pass. Differential Revision: D16801435 Pulled By: TheSavior fbshipit-source-id: 7f3d75ba149259d5bbf719375320e2e325188826 --- Libraries/Components/TextInput/TextInput.js | 401 ++++++++++++++++++++ 1 file changed, 401 insertions(+) diff --git a/Libraries/Components/TextInput/TextInput.js b/Libraries/Components/TextInput/TextInput.js index 8e0f0cba5dcf69..94315aa884124b 100644 --- a/Libraries/Components/TextInput/TextInput.js +++ b/Libraries/Components/TextInput/TextInput.js @@ -200,22 +200,128 @@ export type TextContentType = type PasswordRules = string; type IOSProps = $ReadOnly<{| + /** + * If `false`, disables spell-check style (i.e. red underlines). + * The default value is inherited from `autoCorrect`. + * @platform ios + */ spellCheck?: ?boolean, + + /** + * Determines the color of the keyboard. + * @platform ios + */ keyboardAppearance?: ?('default' | 'light' | 'dark'), + + /** + * If `true`, the keyboard disables the return key when there is no text and + * automatically enables it when there is text. The default value is `false`. + * @platform ios + */ enablesReturnKeyAutomatically?: ?boolean, + + /** + * An instance of `DocumentSelectionState`, this is some state that is responsible for + * maintaining selection information for a document. + * + * Some functionality that can be performed with this instance is: + * + * - `blur()` + * - `focus()` + * - `update()` + * + * > You can reference `DocumentSelectionState` in + * > [`vendor/document/selection/DocumentSelectionState.js`](https://github.com/facebook/react-native/blob/master/Libraries/vendor/document/selection/DocumentSelectionState.js) + * + * @platform ios + */ selectionState?: ?DocumentSelectionState, + + /** + * When the clear button should appear on the right side of the text view. + * This property is supported only for single-line TextInput component. + * @platform ios + */ clearButtonMode?: ?('never' | 'while-editing' | 'unless-editing' | 'always'), + + /** + * If `true`, clears the text field automatically when editing begins. + * @platform ios + */ clearTextOnFocus?: ?boolean, + + /** + * Determines the types of data converted to clickable URLs in the text input. + * Only valid if `multiline={true}` and `editable={false}`. + * By default no data types are detected. + * + * You can provide one type or an array of many types. + * + * Possible values for `dataDetectorTypes` are: + * + * - `'phoneNumber'` + * - `'link'` + * - `'address'` + * - `'calendarEvent'` + * - `'none'` + * - `'all'` + * + * @platform ios + */ dataDetectorTypes?: | ?DataDetectorTypesType | $ReadOnlyArray, + + /** + * An optional identifier which links a custom InputAccessoryView to + * this text input. The InputAccessoryView is rendered above the + * keyboard when this text input is focused. + * @platform ios + */ inputAccessoryViewID?: ?string, + + /** + * Give the keyboard and the system information about the + * expected semantic meaning for the content that users enter. + * @platform ios + */ textContentType?: ?TextContentType, + PasswordRules?: ?PasswordRules, + + /** + * If `false`, scrolling of the text view will be disabled. + * The default value is `true`. Does only work with 'multiline={true}'. + * @platform ios + */ scrollEnabled?: ?boolean, |}>; type AndroidProps = $ReadOnly<{| + /** + * Determines which content to suggest on auto complete, e.g.`username`. + * To disable auto complete, use `off`. + * + * *Android Only* + * + * The following values work on Android only: + * + * - `username` + * - `password` + * - `email` + * - `name` + * - `tel` + * - `street-address` + * - `postal-code` + * - `cc-number` + * - `cc-csc` + * - `cc-exp` + * - `cc-exp-month` + * - `cc-exp-year` + * - `off` + * + * @platform android + */ autoCompleteType?: ?( | 'cc-csc' | 'cc-exp' @@ -231,13 +337,62 @@ type AndroidProps = $ReadOnly<{| | 'username' | 'off' ), + + /** + * Sets the return key to the label. Use it instead of `returnKeyType`. + * @platform android + */ returnKeyLabel?: ?string, + + /** + * Sets the number of lines for a `TextInput`. Use it with multiline set to + * `true` to be able to fill the lines. + * @platform android + */ numberOfLines?: ?number, + + /** + * When `false`, if there is a small amount of space available around a text input + * (e.g. landscape orientation on a phone), the OS may choose to have the user edit + * the text inside of a full screen text input mode. When `true`, this feature is + * disabled and users will always edit the text directly inside of the text input. + * Defaults to `false`. + * @platform android + */ disableFullscreenUI?: ?boolean, + + /** + * Set text break strategy on Android API Level 23+, possible values are `simple`, `highQuality`, `balanced` + * The default value is `simple`. + * @platform android + */ textBreakStrategy?: ?('simple' | 'highQuality' | 'balanced'), + + /** + * The color of the `TextInput` underline. + * @platform android + */ underlineColorAndroid?: ?ColorValue, + + /** + * If defined, the provided image resource will be rendered on the left. + * The image resource must be inside `/android/app/src/main/res/drawable` and referenced + * like + * ``` + * + * ``` + * @platform android + */ inlineImageLeft?: ?string, + + /** + * Padding between the inline image, if any, and the text input itself. + * @platform android + */ inlineImagePadding?: ?number, + importantForAutofill?: ?( | 'auto' | 'no' @@ -245,6 +400,12 @@ type AndroidProps = $ReadOnly<{| | 'yes' | 'yesExcludeDescendants' ), + + /** + * When `false`, it will prevent the soft keyboard from showing when the field is focused. + * Defaults to `true`. + * @platform android + */ showSoftInputOnFocus?: ?boolean, |}>; @@ -252,41 +413,281 @@ type Props = $ReadOnly<{| ...$Diff>, ...IOSProps, ...AndroidProps, + + /** + * Can tell `TextInput` to automatically capitalize certain characters. + * + * - `characters`: all characters. + * - `words`: first letter of each word. + * - `sentences`: first letter of each sentence (*default*). + * - `none`: don't auto capitalize anything. + */ autoCapitalize?: ?AutoCapitalize, + + /** + * If `false`, disables auto-correct. The default value is `true`. + */ autoCorrect?: ?boolean, + + /** + * If `true`, focuses the input on `componentDidMount`. + * The default value is `false`. + */ autoFocus?: ?boolean, + + /** + * Specifies whether fonts should scale to respect Text Size accessibility settings. The + * default is `true`. + */ allowFontScaling?: ?boolean, + + /** + * Specifies largest possible scale a font can reach when `allowFontScaling` is enabled. + * Possible values: + * `null/undefined` (default): inherit from the parent node or the global default (0) + * `0`: no max, ignore parent/global default + * `>= 1`: sets the maxFontSizeMultiplier of this node to this value + */ maxFontSizeMultiplier?: ?number, + + /** + * If `false`, text is not editable. The default value is `true`. + */ editable?: ?boolean, + + /** + * Determines which keyboard to open, e.g.`numeric`. + * + * The following values work across platforms: + * + * - `default` + * - `numeric` + * - `number-pad` + * - `decimal-pad` + * - `email-address` + * - `phone-pad` + * + * *iOS Only* + * + * The following values work on iOS only: + * + * - `ascii-capable` + * - `numbers-and-punctuation` + * - `url` + * - `name-phone-pad` + * - `twitter` + * - `web-search` + * + * *Android Only* + * + * The following values work on Android only: + * + * - `visible-password` + */ keyboardType?: ?KeyboardType, + + /** + * Determines how the return key should look. On Android you can also use + * `returnKeyLabel`. + * + * *Cross platform* + * + * The following values work across platforms: + * + * - `done` + * - `go` + * - `next` + * - `search` + * - `send` + * + * *Android Only* + * + * The following values work on Android only: + * + * - `none` + * - `previous` + * + * *iOS Only* + * + * The following values work on iOS only: + * + * - `default` + * - `emergency-call` + * - `google` + * - `join` + * - `route` + * - `yahoo` + */ returnKeyType?: ?ReturnKeyType, + + /** + * Limits the maximum number of characters that can be entered. Use this + * instead of implementing the logic in JS to avoid flicker. + */ maxLength?: ?number, + + /** + * If `true`, the text input can be multiple lines. + * The default value is `false`. + */ multiline?: ?boolean, + + /** + * Callback that is called when the text input is blurred. + */ onBlur?: ?(e: BlurEvent) => mixed, + + /** + * Callback that is called when the text input is focused. + */ onFocus?: ?(e: FocusEvent) => mixed, + + /** + * Callback that is called when the text input's text changes. + */ onChange?: ?(e: ChangeEvent) => mixed, + + /** + * Callback that is called when the text input's text changes. + * Changed text is passed as an argument to the callback handler. + */ onChangeText?: ?(text: string) => mixed, + + /** + * Callback that is called when the text input's content size changes. + * This will be called with + * `{ nativeEvent: { contentSize: { width, height } } }`. + * + * Only called for multiline text inputs. + */ onContentSizeChange?: ?(e: ContentSizeChangeEvent) => mixed, + onTextInput?: ?(e: TextInputEvent) => mixed, + + /** + * Callback that is called when text input ends. + */ onEndEditing?: ?(e: EditingEvent) => mixed, + + /** + * Callback that is called when the text input selection is changed. + * This will be called with + * `{ nativeEvent: { selection: { start, end } } }`. + */ onSelectionChange?: ?(e: SelectionChangeEvent) => mixed, + + /** + * Callback that is called when the text input's submit button is pressed. + * Invalid if `multiline={true}` is specified. + */ onSubmitEditing?: ?(e: EditingEvent) => mixed, + + /** + * Callback that is called when a key is pressed. + * This will be called with `{ nativeEvent: { key: keyValue } }` + * where `keyValue` is `'Enter'` or `'Backspace'` for respective keys and + * the typed-in character otherwise including `' '` for space. + * Fires before `onChange` callbacks. + */ onKeyPress?: ?(e: KeyPressEvent) => mixed, + + /** + * Invoked on content scroll with `{ nativeEvent: { contentOffset: { x, y } } }`. + * May also contain other properties from ScrollEvent but on Android contentSize + * is not provided for performance reasons. + */ onScroll?: ?(e: ScrollEvent) => mixed, + + /** + * The string that will be rendered before text input has been entered. + */ placeholder?: ?Stringish, + + /** + * The text color of the placeholder string. + */ placeholderTextColor?: ?ColorValue, + + /** + * If `true`, the text input obscures the text entered so that sensitive text + * like passwords stay secure. The default value is `false`. Does not work with 'multiline={true}'. + */ secureTextEntry?: ?boolean, + + /** + * The highlight and cursor color of the text input. + */ selectionColor?: ?ColorValue, + + /** + * The start and end of the text input's selection. Set start and end to + * the same value to position the cursor. + */ selection?: ?$ReadOnly<{| start: number, end?: ?number, |}>, + + /** + * The value to show for the text input. `TextInput` is a controlled + * component, which means the native value will be forced to match this + * value prop if provided. For most uses, this works great, but in some + * cases this may cause flickering - one common cause is preventing edits + * by keeping value the same. In addition to simply setting the same value, + * either set `editable={false}`, or set/update `maxLength` to prevent + * unwanted edits without flicker. + */ value?: ?Stringish, + + /** + * Provides an initial value that will change when the user starts typing. + * Useful for simple use-cases where you do not want to deal with listening + * to events and updating the value prop to keep the controlled state in sync. + */ defaultValue?: ?Stringish, + + /** + * If `true`, all text will automatically be selected on focus. + */ selectTextOnFocus?: ?boolean, + + /** + * If `true`, the text field will blur when submitted. + * The default value is true for single-line fields and false for + * multiline fields. Note that for multiline fields, setting `blurOnSubmit` + * to `true` means that pressing return will blur the field and trigger the + * `onSubmitEditing` event instead of inserting a newline into the field. + */ blurOnSubmit?: ?boolean, + + /** + * Note that not all Text styles are supported, an incomplete list of what is not supported includes: + * + * - `borderLeftWidth` + * - `borderTopWidth` + * - `borderRightWidth` + * - `borderBottomWidth` + * - `borderTopLeftRadius` + * - `borderTopRightRadius` + * - `borderBottomRightRadius` + * - `borderBottomLeftRadius` + * + * see [Issue#7070](https://github.com/facebook/react-native/issues/7070) + * for more detail. + * + * [Styles](docs/style.html) + */ style?: ?TextStyleProp, + + /** + * If `true`, caret is hidden. The default value is `false`. + * This property is supported only for single-line TextInput component on iOS. + */ caretHidden?: ?boolean, + + /* + * If `true`, contextMenuHidden is hidden. The default value is `false`. + */ contextMenuHidden?: ?boolean, |}>;