Skip to content

Migrate/audit JSDoc on public APIs (Components) #57382

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
huntie wants to merge 1 commit into from
Closed

Migrate/audit JSDoc on public APIs (Components) #57382

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
268 changes: 88 additions & 180 deletions packages/react-native/Libraries/Components/Button.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,262 +30,170 @@ import * as React from 'react';
/** @build-types emit-as-interface Uniwind compatibility */
export type ButtonProps = Readonly<{
/**
Text to display inside the button. On Android the given title will be
converted to the uppercased form.
* Text to display inside the button. On Android the given title will be
* converted to the uppercased form.
*/
title: string,

/**
Handler to be called when the user taps the button. The first function
argument is an event in form of [GestureResponderEvent](pressevent).
* Handler called when the user taps the button.
*/
onPress?: (event?: GestureResponderEvent) => unknown,

/**
If `true`, doesn't play system sound on touch.

@platform android

@default false
* If `true`, doesn't play system sound on touch.
*
* @platform android
*
* @default `false`
*/
touchSoundDisabled?: ?boolean,

/**
Color of the text (iOS), or background color of the button (Android).

@default {@platform android} '#2196F3'
@default {@platform ios} '#007AFF'
* Color of the text (iOS), or background color of the button (Android).
*
* @default {@platform android} `'#2196F3'`
* @default {@platform ios} `'#007AFF'`
*/
color?: ?ColorValue,

/**
TV preferred focus.

@platform tv

@default false
@deprecated Use `focusable` instead
* TV preferred focus.
*
* @platform tv
*
* @default `false`
* @deprecated Use `focusable` instead
*/
hasTVPreferredFocus?: ?boolean,

/**
Designates the next view to receive focus when the user navigates down. See
the [Android documentation][android:nextFocusDown].

[android:nextFocusDown]:
https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusDown

@platform android, tv
* Designates the next view to receive focus when the user navigates down. See
* the [Android documentation][android:nextFocusDown].
*
* [android:nextFocusDown]:
* https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusDown
*
* @platform android, tv
*/
nextFocusDown?: ?number,

/**
Designates the next view to receive focus when the user navigates forward.
See the [Android documentation][android:nextFocusForward].

[android:nextFocusForward]:
https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusForward

@platform android, tv
* Designates the next view to receive focus when the user navigates forward.
* See the [Android documentation][android:nextFocusForward].
*
* [android:nextFocusForward]:
* https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusForward
*
* @platform android, tv
*/
nextFocusForward?: ?number,

/**
Designates the next view to receive focus when the user navigates left. See
the [Android documentation][android:nextFocusLeft].

[android:nextFocusLeft]:
https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusLeft

@platform android, tv
* Designates the next view to receive focus when the user navigates left. See
* the [Android documentation][android:nextFocusLeft].
*
* [android:nextFocusLeft]:
* https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusLeft
*
* @platform android, tv
*/
nextFocusLeft?: ?number,

/**
Designates the next view to receive focus when the user navigates right. See
the [Android documentation][android:nextFocusRight].

[android:nextFocusRight]:
https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusRight

@platform android, tv
* Designates the next view to receive focus when the user navigates right. See
* the [Android documentation][android:nextFocusRight].
*
* [android:nextFocusRight]:
* https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusRight
*
* @platform android, tv
*/
nextFocusRight?: ?number,

/**
Designates the next view to receive focus when the user navigates up. See
the [Android documentation][android:nextFocusUp].

[android:nextFocusUp]:
https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusUp

@platform android, tv
* Designates the next view to receive focus when the user navigates up. See
* the [Android documentation][android:nextFocusUp].
*
* [android:nextFocusUp]:
* https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusUp
*
* @platform android, tv
*/
nextFocusUp?: ?number,

/**
Text to display for blindness accessibility features.
* Text to display for blindness accessibility features.
*/
accessibilityLabel?: ?string,

/**
* Alias for accessibilityLabel https://reactnative.dev/docs/view#accessibilitylabel
* https://github.com/facebook/react-native/issues/34424
* Alias for `accessibilityLabel`.
*/
'aria-label'?: ?string,
/**
If `true`, disable all interactions for this component.

@default false
/**
* If `true`, disable all interactions for this component.
*
* @default `false`
*/
disabled?: ?boolean,

/**
Used to locate this view in end-to-end tests.
*/
testID?: ?string,

/**
* Accessibility props.
*/
accessible?: ?boolean,
accessibilityActions?: ?ReadonlyArray<AccessibilityActionInfo>,
onAccessibilityAction?: ?(event: AccessibilityActionEvent) => unknown,
accessibilityState?: ?AccessibilityState,

/**
* alias for accessibilityState
*
* see https://reactnative.dev/docs/accessibility#accessibilitystate
* Alias for `accessibilityState`.
*/
'aria-busy'?: ?boolean,
'aria-checked'?: ?boolean | 'mixed',
'aria-disabled'?: ?boolean,
'aria-expanded'?: ?boolean,
'aria-selected'?: ?boolean,

/**
* [Android] Controlling if a view fires accessibility events and if it is reported to accessibility services.
*/
importantForAccessibility?: ?('auto' | 'yes' | 'no' | 'no-hide-descendants'),
accessibilityHint?: ?string,

/**
* A BCP 47 language tag for the screen reader to use when reading text
* content.
*
* @platform ios
*/
accessibilityLanguage?: ?Stringish,
}>;

/**
A basic button component that should render nicely on any platform. Supports a
minimal level of customization.

If this button doesn't look right for your app, you can build your own button
using [TouchableOpacity](touchableopacity) or
[TouchableWithoutFeedback](touchablewithoutfeedback). For inspiration, look at
the [source code for this button component][button:source]. Or, take a look at
the [wide variety of button components built by the community]
[button:examples].

[button:source]:
https://github.com/facebook/react-native/blob/HEAD/Libraries/Components/Button.js

```jsx
<Button
onPress={onPressLearnMore}
title="Learn More"
color="#841584"
accessibilityLabel="Learn more about this purple button"
/>
```

```SnackPlayer name=Button%20Example
import React from 'react';
import { StyleSheet, Button, View, SafeAreaView, Text, Alert } from 'react-native';

const Separator = () => (
<View style={styles.separator} />
);

const App = () => (
<SafeAreaView style={styles.container}>
<View>
<Text style={styles.title}>
The title and onPress handler are required. It is recommended to set accessibilityLabel to help make your app usable by everyone.
</Text>
<Button
title="Press me"
onPress={() => Alert.alert('Simple Button pressed')}
/>
</View>
<Separator />
<View>
<Text style={styles.title}>
Adjust the color in a way that looks standard on each platform. On iOS, the color prop controls the color of the text. On Android, the color adjusts the background color of the button.
</Text>
<Button
title="Press me"
color="#f194ff"
onPress={() => Alert.alert('Button with adjusted color pressed')}
/>
</View>
<Separator />
<View>
<Text style={styles.title}>
All interaction for the component are disabled.
</Text>
<Button
title="Press me"
disabled
onPress={() => Alert.alert('Cannot press this one')}
/>
</View>
<Separator />
<View>
<Text style={styles.title}>
This layout strategy lets the title define the width of the button.
</Text>
<View style={styles.fixToText}>
<Button
title="Left button"
onPress={() => Alert.alert('Left button pressed')}
/>
<Button
title="Right button"
onPress={() => Alert.alert('Right button pressed')}
/>
</View>
</View>
</SafeAreaView>
);

const styles = StyleSheet.create({
container: {
flex: 1,
justifyContent: 'center',
marginHorizontal: 16,
},
title: {
textAlign: 'center',
marginVertical: 8,
},
fixToText: {
flexDirection: 'row',
justifyContent: 'space-between',
},
separator: {
marginVertical: 8,
borderBottomColor: '#737373',
borderBottomWidth: StyleSheet.hairlineWidth,
},
});

export default App;
```
*/

const NativeTouchable:
| typeof TouchableNativeFeedback
| typeof TouchableOpacity =
Platform.OS === 'android' ? TouchableNativeFeedback : TouchableOpacity;

export type ButtonInstance = React.ElementRef<typeof NativeTouchable>;

/**
* A basic button component that should render nicely on any platform. Supports a
* minimal level of customization.
*
* If this button doesn't look right for your app, you can build your own button
* using `Pressable`.
*
* Example:
*
* ```tsx
* <Button
* onPress={onPressLearnMore}
* title="Learn More"
* color="#841584"
* accessibilityLabel="Learn more about this purple button"
* />
* ```
*
* @see https://reactnative.dev/docs/button
*/
const Button: component(
ref?: React.RefSetter<ButtonInstance>,
...props: ButtonProps
Expand Down
Loading
Loading