[docs] Buttons

packages/docs-gesture-handler/docs/components/buttons.mdx

@@ -11,111 +11,153 @@ import GifGallery from '@site/components/GifGallery';
   <img src={useBaseUrl('gifs/samplebutton.gif')} width="280" />
 </GifGallery>
 
-Gesture handler library provides native components that can act as buttons. These can be treated as a replacement to `TouchableHighlight` or `TouchableOpacity` from RN core. Gesture handler's buttons recognize touches in native which makes the recognition process deterministic, allows for rendering ripples on Android in highly performant way (`TouchableNativeFeedback` requires that touch event does a roundtrip to JS before we can update ripple effect, which makes ripples lag a bit on older phones), and provides native and platform default interaction for buttons that are placed in a scrollable container (in which case the interaction is slightly delayed to prevent button from highlighting when you fling).
+The Gesture Handler library offers native components that function as buttons, serving as alternatives to `TouchableHighlight` or `TouchableOpacity` from the core React Native framework. These buttons process touch recognition natively, which ensures a deterministic response. This capability significantly enhances performance; for example, it allows for immediate ripple effects on Android, unlike `TouchableNativeFeedback`, which requires a touch event roundtrip to JavaScript that can cause delays, especially noticeable on older devices. Additionally, these components handle default platform interactions natively, particularly in scrollable containers where interactions are smartly delayed to prevent unintended highlighting during a fling.
 
-Currently Gesture handler library exposes three components that render native touchable elements under the hood:
+Gesture Handler library exposes components that render native touchable elements under the hood:
 
-- [`BaseButton`](/docs/components/buttons/#basebutton)
-- [`RectButton`](/docs/components/buttons/#rectbutton)
-- [`BorderlessButton`](/docs/components/buttons/#borderlessbutton)
+- [`RawButton`](#rawbutton)
+- [`BaseButton`](#basebutton)
+- [`RectButton`](#rectbutton)
+- [`BorderlessButton`](#borderlessbutton)
 
-On top of that all the buttons are wrapped with `NativeViewGestureHandler` and therefore allow for all the [common gesture handler properties](/docs/gestures/use-native-gesture#properties-common-to-all-gestures) and `NativeViewGestureHandler`'s [extra properties](/docs/gestures/use-native-gesture#properties-specific-to-nativegesture) to be applied to them.
+On top of that all the buttons are wrapped with [`Native`](/docs/gestures/use-native-gesture) gesture and therefore allow for all its [properties](/docs/gestures/use-native-gesture#config) to be applied to them.
 
-**IMPORTANT**: In order to make buttons accessible, you have to wrap your children in a `View` with `accessible` and `accessibilityRole="button"` props.
-Example:
+## RawButton
 
-```javascript
-// Not accessible:
-const NotAccessibleButton = () => (
-  <RectButton onPress={this._onPress}>
-    <Text>Foo</Text>
-  </RectButton>
-);
-// Accessible:
-const AccessibleButton = () => (
-  <RectButton onPress={this._onPress}>
-    <View accessible accessibilityRole="button">
-      <Text>Bar</Text>
-    </View>
-  </RectButton>
-);
+The most basic button component does not provide any feedback and lacks props such as `onPress`. It serves as a foundation for other button components and is ideal if you wish to implement your own custom interactions for when the button is pressed.
+
+## BaseButton
+
+Can be used as a base class if you'd like to implement some custom interaction for when the button is pressed.
+
+### onPress
+
+```ts
+onPress?: (pointerInside: boolean) => void;
 ```
 
-It is applicable for both iOS and Android platform. On iOS, you won't be able to even select the button, on Android you won't be able to click it in accessibility mode.
+Triggered when the button gets pressed (analogous to `onPress` in `TouchableHighlight` from RN core).
 
-## `BaseButton`
 
-Can be used as a base class if you'd like to implement some custom interaction for when the button is pressed.
+### onLongPress
 
-Below is a list of properties specific to `BaseButton` component:
+```ts
+onLongPress?: () => void;
+```
 
-### `onActiveStateChange`
+Triggered when the button gets pressed for at least [`delayLongPress`](#delaylongpress) milliseconds.
 
-function that gets triggered when button changes from inactive to active and vice versa. It passes active state as a boolean variable as a first parameter for that method.
 
-### `onPress`
+### onActiveStateChange
 
-function that gets triggered when the button gets pressed (analogous to `onPress` in `TouchableHighlight` from RN core).
+```ts
+onActiveStateChange?: (active: boolean) => void;
+```
 
-### `onLongPress`
+Triggered when the button transitions between active and inactive states. It passes the current active state as a boolean variable to the method as the first parameter.
 
-function that gets triggered when the button gets pressed for at least `delayLongPress` milliseconds.
 
-### `rippleColor` (**Android only**)
+### rippleColor (**Android only**)
 
-defines color of native [ripple](https://developer.android.com/reference/android/graphics/drawable/RippleDrawable) animation used since API level 21.
+```ts
+rippleColor?: number | ColorValue | null;
+```
 
-### `exclusive`
+Defines [color](https://reactnative.dev/docs/colors) of native [ripple](https://developer.android.com/reference/android/graphics/drawable/RippleDrawable) animation.
 
-defines if more than one button could be pressed simultaneously. By default set `true`.
+### exclusive
 
-### `delayLongPress`
+```ts
+exclusive?: boolean;
+```
 
-defines the delay, in milliseconds, after which the `onLongPress` callback gets called. By default set to 600.
+Defines if more than one button could be pressed simultaneously. By default set to `true`.
 
-## `RectButton`
+### delayLongPress
 
-This type of button component should be used when you deal with rectangular elements or blocks of content that can be pressed, for example table rows or buttons with text and icons. This component provides a platform specific interaction, rendering a rectangular ripple on Android or highlighting the background on iOS and on older versions of Android. In addition to the props of [`BaseButton`](/docs/components/buttons#basebutton), it accepts the following:
+```ts
+delayLongPress?: number;
+```
 
-Below is a list of properties specific to `RectButton` component:
+Defines the delay, in milliseconds, after which the [`onLongPress`](#onlongpress) callback gets called. By default set to `600`.
 
-### `underlayColor`
+### borderless (**Android only**)
 
-this is the background color that will be dimmed when button is in active state.
+```ts
+borderless?: boolean;
+```
 
-### `activeOpacity` (**iOS only**)
+set this to `false` if you want the ripple animation to render only within view bounds.
 
-opacity applied to the underlay when button is in active state.
+## RectButton
 
-## `BorderlessButton`
+This type of button component is ideal for use with rectangular elements or content blocks that can be pressed, such as table rows or buttons featuring text and icons. It ensures platform-specific interactions, such as rendering a rectangular ripple on Android or highlighting the background on iOS and older Android versions. In addition to the props offered by [`BaseButton`](#basebutton), it accepts the following:
+
+### underlayColor
+
+```ts
+underlayColor?: string;
+```
+
+Background color that will be dimmed when button is in active state.
+
+### activeOpacity (**iOS only**)
+
+```ts
+activeOpacity?: number;
+```
+
+Opacity applied to the underlay when button is in active state.
+
+## BorderlessButton
 
 This type of button component should be used with simple icon-only or text-only buttons. The interaction will be different depending on platform: on Android a borderless ripple will be rendered (it means that the ripple will animate into a circle that can span outside of the view bounds), whereas on iOS the button will be dimmed (similar to how `TouchableOpacity` works). In addition to the props of [`BaseButton`](/docs/components/buttons#basebutton), it accepts the following:
 
-Below is a list of properties specific to `BorderlessButton` component:
+### activeOpacity (**iOS only**)
 
-### `borderless` (**Android only**)
+```ts
+activeOpacity?: number;
+```
 
-set this to `false` if you want the ripple animation to render only within view bounds.
+Opacity applied to the button when it is in an active state.
 
-### `activeOpacity` (**iOS only**)
+## Accessibility
 
-opacity applied to the button when it is in an active state.
+To guarantee that buttons are fully accessible, you must wrap your children in a `View` marked as `accessible` and include the `accessibilityRole="button"` prop. This requirement applies to both iOS and Android platforms. Without these adjustments, the button won't be selectable on iOS, and on Android, it won't be clickable in accessibility mode.
+
+```tsx
+// Not accessible:
+const NotAccessibleButton = () => (
+  <RectButton onPress={this._onPress}>
+    <Text>Foo</Text>
+  </RectButton>
+);
+
+// Accessible:
+const AccessibleButton = () => (
+  <RectButton onPress={this._onPress}>
+    <View accessible accessibilityRole="button">
+      <Text>Bar</Text>
+    </View>
+  </RectButton>
+);
+```
 
 ## Design patterns
 
-Components listed here were not designed to behave and look in the same way on both platforms but rather to be used for handling similar behaviour on iOS and Android taking into consideration their's design concepts.
+Components listed here were not designed to behave and look in the same way on both platforms but rather to be used for handling similar behaviour on iOS and Android taking into consideration theirs design concepts.
 
 If you wish to get specific information about platforms design patterns, visit [official Apple docs](https://developer.apple.com/design/human-interface-guidelines/components/menus-and-actions/buttons) and [Material.io guideline](https://material.io/components/buttons#text-button), which widely describe how to implement coherent design.
 
 This library allows to use native components with native feedback in adequate situations.
 
-If you do not wish to implement custom design approach, `RectButton` and `BorderlessButton` seem to be absolutely enough and there's no need to use anything else. In all the remaining cases you can always rely on `BaseButton` which is a superclass for the other button classes and can be used as a generic `Touchable` replacement that can be customized to your needs.
+If you do not wish to implement custom design approach, [`RectButton`](#rectbutton) and [`BorderlessButton`](#borderlessbutton) seem to be absolutely enough and there's no need to use anything else. In all the remaining cases you can always rely on [`BaseButton`](#basebutton) which is a superclass for the other button classes and can be used as a generic `Touchable` replacement that can be customized to your needs.
 
 Below we list some of the common usecases for button components to be used along with the type of button that should be used according to the platform specific design guidelines.
 
 ### Lists and action buttons
 
-If you have a list with clickable items or have an action button that need to display as a separate UI block (vs being inlined in a text) you should use `RectButton`. It changes opacity on click and additionally supports a ripple effect on Android.
+If you have a list with clickable items or have an action button that need to display as a separate UI block (vs being inlined in a text) you should use [`RectButton`](#rectbutton). It changes opacity on click and additionally supports a [ripple effect](#ripplecolor-android-only) on Android.
 
 <GifGallery>
   <img src={useBaseUrl('gifs/androidsettings.gif')} width="280" />
@@ -138,41 +180,3 @@ It should be used if you wish to handle non-crucial actions and supportive behav
   <img src={useBaseUrl('gifs/androidmail.gif')} width="280" />
   <img src={useBaseUrl('gifs/iosmail.gif')} width="280" />
 </GifGallery>
-
-### `PureNativeButton`
-
-Use a `PureNativeButton` for accessing the native Component used for build more complex buttons listed above.
-It's normally is not recommended to use, but it might be useful if we want to wrap it using Animated or Reanimated.
-
-```javascript
-import {
-  createNativeWrapper,
-  PureNativeButton,
-} from 'react-native-gesture-handler';
-import Animated from 'react-native-reanimated';
-const { event, Value, createAnimatedComponent } = Animated;
-
-const AnimatedRawButton = createNativeWrapper(
-  createAnimatedComponent(PureNativeButton),
-  {
-    shouldCancelWhenOutside: false,
-    shouldActivateOnStart: false,
-  }
-);
-
-export default class App extends React.Component {
-  constructor(props) {
-    super(props);
-    const state = new Value();
-    this._onGestureEvent = event([
-      {
-        nativeEvent: { state },
-      },
-    ]);
-  }
-
-  render() {
-    return <AnimatedRawButton onHandlerStateChange={this._onGestureEvent} />;
-  }
-}
-```

packages/docs-gesture-handler/docs/guides/upgrading-to-3.mdx

@@ -248,7 +248,7 @@ code2={
 
 The implementation of buttons has been updated, resolving most button-related issues. They have also been internally rewritten to utilize the new hook API. The original button components are still accessible but have been renamed with the prefix `Legacy`, e.g., `RectButton` is now available as `LegacyRectButton`.
 
-Although the legacy JS implementation of the buttons is still available, they also use the new host component internally.
+Although the legacy JS implementation of the buttons is still available, they also use the new host component internally. Because of that, `PureNativeButton` is no longer available in Gesture Handler 3.
 
 <details>
 <summary>Legacy buttons</summary>
@@ -259,6 +259,7 @@ Although the legacy JS implementation of the buttons is still available, they al
 | `BaseButton`          | `LegacyBaseButton`          |
 | `RectButton`          | `LegacyRectButton`          |
 | `BorderlessButton`    | `LegacyBorderlessButton`    |
+| `PureNativeButton`    | *Not available in Gesture Handler 3*    |
 
 </details>
 

skills/gesture-handler-3-migration/SKILL.md

@@ -35,13 +35,15 @@ The exception to thait is `Gesture.ForceTouch` which DOES NOT have a counterpart
 #### Callback changes
 
 In Gesture Handler 3 some of the callbacks were renamed, namely:
+
 - `onStart` -> `onActivate`
 - `onEnd` -> `onDeactivate`
 - `onTouchesCancelled` -> `onTouchesCancel`
 
 In the hooks API `onChange` is no longer available. Instead the `*change*` properties were moved to the event available inside `onUpdate`.
 
 All callbacks of a gesture are now using the same type:
+
 - `usePanGesture()` -> `PanGestureEvent`
 - `useTapGesture()` -> `TapGestureEvent`
 - `useLongPressGesture()` -> `LongPressGestureEvent`
@@ -53,6 +55,7 @@ All callbacks of a gesture are now using the same type:
 - `useManualGesture()` -> `ManualGestureEvent`
 
 The exception to this is touch events:
+
 - `onTouchesDown`
 - `onTouchesUp`
 - `onTouchesMove`
@@ -65,12 +68,14 @@ Where each callback receives `GestureTouchEvent` regardless of the hook used.
 In Gesture Handler 3, `stateManager` is no longer passed to `TouchEvent` callbacks. Instead, you should use the global `GestureStateManager`.
 
 `GestureStateManager` provides methods for imperative state management:
+
 - .begin(handlerTag: number)
 - .activate(handlerTag: number)
 - .deactivate(handlerTag: number) (.end() in the old API)
 - .fail(handlerTag: number)
 
 `handlerTag` can be obtained in two ways:
+
 1. From the gesture object returned by the hook (`gesture.handlerTag`)
 2. From the event inside callback (`event.handlerTag`)
 
@@ -83,13 +88,15 @@ Callback definitions CANNOT reference the gesture that's being defined. In this
 `Gesture.Simultaneous(gesture1, gesture2);` becomes `useSimultaneousGestures(pan1, pan2);`
 
 All relations from the old API and their counterparts in the new one:
+
 - `Gesture.Race()` -> `useCompetingGestures()`
 - `Gesture.Simultaneous()` -> `useSimultaneousGestures()`
 - `Gesture.Exclusive()` -> `useExclusiveGestures()`
 
 #### Cross components relations properties
 
 Properties used to define cross-components interactions were renamed:
+
 - `.simultaneousWithExternalGesture` -> `simultaneousWith:`
 - `.requireExternalGestureToFail` -> `requireToFail:`
 - `.blocksExternalGesture` -> `block:`
@@ -160,6 +167,8 @@ Don't suggest replacing buttons from Gesture Handler with components from React
 
 The implementation of buttons has been updated, resolving most button-related issues. They have also been internally rewritten to utilize the new hook API. The legacy JS implementations of button components are still accessible but have been renamed with the prefix `Legacy`, e.g., `RectButton` is now available as `LegacyRectButton`. Those still use the new native component under the hood.
 
+`PureNativeButton` has been removed. If encountered, inform the user that it has been removed and let them decide how to handle that case. They can achieve similar funcionality with other buttons.
+
 Other components have also been internally rewritten using the new hook API but are exported under their original names, so no changes are necessary on your part. However, if you need to use the previous implementation for any reason, the legacy components are also available and are prefixed with `Legacy`, e.g., `ScrollView` is now available as `LegacyScrollView`.
 
 ### Replaced types