fix: docs; feat: add events, split placeholder

rcaferati · rcaferati · commit c0c6214369c7 · 2022-10-13T19:51:44.000-03:00
diff --git a/README.md b/README.md
@@ -4,8 +4,6 @@
 
 `react-native-really-awesome-button` is a performant, extendable, production ready React Native component that renders an animated set of 3D UI buttons.
 
-Run the <a target="_blank" title="Live Demo" href="https://expo.io/@rcaferati/react-native-really-awesome-button">live demo</a> @ expo.io.
-
 | <img width="240" src='https://raw.githubusercontent.com/rcaferati/react-native-really-awesome-button/master/assets/demo-button-blue-new.gif?raw=true' />  | <img width="240" src='https://raw.githubusercontent.com/rcaferati/react-native-really-awesome-button/master/assets/demo-button-rick.gif?raw=true' />  | <img width="240" src='https://raw.githubusercontent.com/rcaferati/react-native-really-awesome-button/master/assets/demo-button-cartman.gif?raw=true' />  |
 |---|---|---|
 
@@ -42,8 +40,8 @@ function Button() {
   return (
     <AwesomeButton
       progress
-      onPress={next => {
-        /** Do Something **/
+      onPress={async (next) => {
+        /** await for something; then: **/
         next();
       }}
     >
@@ -53,12 +51,27 @@ function Button() {
 }
 ```
 
+### Importing a specific theme
+
+```jsx
+  import { ThemedButton } from 'react-native-really-awesome-button';
+
+  function ButtonWithTheme() {
+    return (
+      <>
+        <ThemedButton name="rick" type="primary">Rick's Primary Button</ThemedButton>
+        <ThemedButton name="rick" type="secondary">Rick's Secondary Button</ThemedButton>
+      </>
+    );
+  }
+```
+
 ### Custom Children
 
 ```jsx
 import AwesomeButton from "react-native-really-awesome-button";
 
-function Button() {
+function ButtonWithCustomChildren() {
   return (
     <AwesomeButton>
       <Image source="require('send-icon.png)" />
@@ -68,32 +81,40 @@ function Button() {
 }
 ```
 
-### Importing a specific theme
+### Adding content before and after the button label
+Useful for handling icons or any other inlined content which animates together with the button text.
 
 ```jsx
-  import AwesomeButtonRick from 'react-native-really-awesome-button/src/themes/rick';
+  import { ThemedButton } from 'react-native-really-awesome-button';
+  import { FontAwesome } from "@expo/icons";
 
-  function Button() {
+  function ButtonWithIcon() {
     return (
-     <AwesomeButtonRick type="primary">Rick's Primary Button</AwesomeButtonRick>
-     <AwesomeButtonRick type="secondary">Rick's Secondary Button</AwesomeButtonRick>
+      <ThemedButton
+        name="bruce"
+        type="primary"
+        before={<FontAwesome name="twitter" />}>
+        Rick's Primary Button
+      </ThemedButton>
     );
   }
 ```
 
-### Extra Content placement
-You can use the `Extra Content` prop to render a component inside the button content body. This could be useful to render an image or gradient background
+### Extra content placement
+You can use the `extra` prop to render a component inside the button content body; this should be useful to render an image or gradient background
 
 ```jsx
+import { StyleSheet } from "react-native";
 import AwesomeButton from "react-native-really-awesome-button";
 import LinearGradient from "react-native-linear-gradient";
 
-function Button() {
+function ButtonWithExtraContent() {
   return (
     <AwesomeButton
-      ExtraContent={
+      extra={
         <LinearGradient
           colors={["#4C63D2", "#BC3081", "#F47133", "#FED576"]}
+          style={{ ...StyleSheet.absoluteFillObject }}
         />
       }
     >
@@ -103,53 +124,95 @@ function Button() {
 }
 ```
 
+### Full event control
+Added a set of controlling events on `v2`, giving control of every animation stage like `onPressedIn` and `onPressedOut` which are triggered on the `Animated` callback.
+
+```jsx
+import { StyleSheet } from "react-native";
+import AwesomeButton from "react-native-really-awesome-button";
+import LinearGradient from "react-native-linear-gradient";
+
+function ButtonWithExtraEvents() {
+  return (
+    <>
+      <AwesomeButton
+        onPressIn={handlePressIn}
+        onPressedIn={handlePressedIn}
+        onPressOut={handlePressOut}
+        onPressedOut={handlePressedOut}
+      >
+        Label
+      </AwesomeButton>
+      <AwesomeButton
+        progress
+        onProgressStart={handleOnProgressStart}
+        onProgressEnd={handleOnProgressEnd}
+        onPress={handleOnPress}
+      >
+        Label
+      </AwesomeButton>
+    </>
+  );
+}
+```
+
 ## Props
 
 | Attributes            |     Type      |  Default  | Description                                               |
 | :-------------------- | :-----------: | :-------: | :-------------------------------------------------------- |
 | activityColor         | `String`      | `#FFFFFF` | Button activity indicator color                           |
 | activeOpacity         | `Number`      | `1`       | Button active state opacity                               |
+| animatedPlaceholder   | `Boolean`     | `true`    | When set to `false` removes the placeholder animation loop |
 | backgroundActive      | `String`      | `#C0C0C0` | Button active state background-color                      |
 | backgroundColor       | `String`      | `#C0C0C0` | Button content background-color                           |
 | backgroundDarker      | `String`      | `#9F9F9F` | Button bottom-front-face background-color                 |
-| backgroundShadow      | `String`      | `#C0C0C0` | Button bottom shaddow background-color                    |
+| backgroundShadow      | `String`      | `#C0C0C0` | Button bottom shadow background-color                     |
 | backgroundPlaceholder | `String`      | `#C0C0C0` | Button placeholder background-color                       |
 | backgroundProgress    | `String`      | `#C0C0C0` | Button progress bar background-color                      |
-| borderColor           | `String`      | `null`   | Button border-color                                        |
+| borderColor           | `String`      | `null`    | Button border-color                                        |
 | borderRadius          | `Number`      | `4`       | Button border-radius                                      |
 | borderWidth           | `Number`      | `0`       | Button border-width                                       |
+| dangerouslySetPressableProps | `PressableProps`    | `null`    | Exposes the `PressableProps` of the `Pressable` wrapper; it can overwrite all props except `onPressIn` and `onPressOut` |
+| debouncedPressTime    | `Number`      | `0`       | Configure onPress function debounce time                  |
+| disabled              | `Boolean`     | `true`    | Button disabled state: cancels animation and onPress func |
 | height                | `Number`      | `50`      | Button height                                             |
 | width                 | `Number`      | `null`    | Setting width to `null` mirrors an `auto` behaviour       |
 | paddingHorizontal     | `Number`      | `12`      | Sets the button horizontal padding                        |
 | paddingTop            | `Number`      | `0`       | Sets the button padding top                               |
 | paddingBottom         | `Number`      | `0`       | Sets the button padding bottom                            |
 | stretch               | `Boolean`     | `false`   | When set to `true` together with width set to `null` the button fills it's parent component width |
-| disabled              | `Boolean`     | `true`    | Button disabled state: cancels animation and onPress func |
 | raiseLevel            | `Number`      | `4`       | Button 3D raise level                                     |
-| ExtraContent          | `Node`        | `null`    | Renders a custom component inside the button content body |
-| springRelease         | `Boolean`     | `true`    | Button uses spring on the release animation               |
-| onPress               | `Function`    | `null`    | Button onPress function. It receives a `next` argument when the `progress` prop is set to `true` |
-| progress              | `Boolean`     | `false`   | When set to `true` enables progress animation             |
-| progressLoadingTime   | `Number`      | `3000`    | Number in `ms` for the maximum progress bar animation time |
+| before                | `ReactNode`   | `null`    | Renders a custom component before the button content Text |
+| after                 | `ReactNode`   | `null`    | Renders a custom component after the button content Text  |
+| extra                 | `ReactNode`   | `null`    | Renders a custom component inside the button content body |
+| springRelease         | `Boolean`     | `true`    | Button uses elastic spring on the release animation       |
+| progress              | `Boolean`     | `false`   | When set to `true` enables progress animation             |
+| progressLoadingTime   | `Number`      | `3000`    | Number in `ms` for the maximum progress bar animation time |
 | textColor             | `String`      | `#FFFFFF` | Button default label text color                           |
 | textLineHeight        | `Number`      | `20`      | Button default label text line height                     |
 | textSize              | `Number`      | `16`      | Button default label text font size                       |
 | textFontFamily        | `String`      | `null`    | Button default label text font family                     |
-| style                 | `Style`       | `null`    | Button container custom styles                            |
+| style                 | `Style`       | `null`    | Button container custom styles                            |
+| onPress               | `Function`    | `null`    | Button onPress function. It receives a `next` argument when the `progress` prop is set to `true` |
+| onPressIn             | `Function`    | `null`    | Triggered with the `onPressIn` native event |
+| onPressedIn           | `Function`    | `null`    | Triggered once the press animation has finished |
+| onPressOut            | `Function`    | `null`    | Triggered with the `onPressOut` native event |
+| onPressedOut          | `Function`    | `null`    | Triggered once the release animation has finished |
+| onProgressStart       | `Function`    | `null`    | Triggered before the progress animation has started |
+| onProgressEnd         | `Function`    | `null`    | Triggered after the progress animation has finished |
 
 ## Web version
-Checkout the web version of the Awesome Button UI component at [rcaferati/react-awesome-button](https://github.com/rcaferati/react-awesome-button)
+Checkout the web version of the `Awesome Button UI Component` at [rcaferati/react-awesome-button](https://github.com/rcaferati/react-awesome-button)
 
 [<img src="https://github.com/rcaferati/react-awesome-button/blob/master/assets/public/images/react-awesome-button-customizer.png?raw=true" width="800" />](https://caferati.me/demo/react-awesome-button)
 
 ## About the Author
 
 #### Rafael Caferati
 
-- Checkout my <a href="https://caferati.me" title="Full-Stack Web Developer, UI/UX Javascript Specialist" target="_blank">Full-Stack Web Developer Website</a>
-- Other open source projects @ <a title="Web Software Developer Code Laboratory" target="_blank" href="https://caferati.me/labs">Code Laboratory</a>
-- A scope of my work @ <a title="Web Software Developer Portfolio" target="_blank" href="https://caferati.me/portfolio">Web Developer Portfolio</a>
+- Checkout my <a href="https://caferati.me" title="Full-Stack Web Developer, UI/UX Javascript Specialist" target="_blank">Portfolio Website</a>
+- Connect with me on `LinkedIn` <a href="https://linkedin.com/in/rcaferati" title="Full-Stack Web Developer, UI/UX Javascript Specialist" target="_blank">@rcaferati</a>
 
 ## License
 
-MIT. Copyright (c) 2018 Rafael Caferati.
+MIT. Copyright (c) 2022 Rafael Caferati.
diff --git a/demo/src/components/Example.tsx b/demo/src/components/Example.tsx
@@ -261,23 +261,6 @@ export default function Example({ index }: any) {
               />
             </ThemedButton>
           </Section>
-          {/* <Section title="Linear Gradient Overwrite">
-            <Themed
-              config={theme}
-              backgroundDarker="#EAAC1E"
-              backgroundActive="rgba(0,0,0,0.1)"
-              ExtraContent={
-                <LinearGradient
-                  colors={['#4C63D2', '#BC3081', '#F47133', '#FED576']}
-                  style={styles.gradient}
-                />
-              }
-              style={styles.button}
-              type="primary"
-              size="medium">
-              Gradient Overwrite
-            </ThemedButton>
-          </Section> */}
           <Section title="With auto and stretch">
             <ThemedButton
               config={theme}
diff --git a/demo/src/screens/Social.tsx b/demo/src/screens/Social.tsx
@@ -80,7 +80,7 @@ export default function Social({ navigation }: any) {
           progress
           backgroundProgress="rgba(0,0,0,0.15)"
           onPress={handleTimeout}
-          ExtraContent={
+          extra={
             <LinearGradient
               colors={['#4C63D2', '#BC3081', '#F47133', '#FED576']}
               style={{ ...StyleSheet.absoluteFillObject }}
diff --git a/package.json b/package.json
@@ -60,6 +60,7 @@
     "eslint-config-prettier": "^8.5.0",
     "eslint-plugin-prettier": "^4.0.0",
     "jest": "^28.1.1",
+    "lodash.debounce": "^4.0.8",
     "pod-install": "^0.1.0",
     "prettier": "^2.0.5",
     "react": "17.0.2",
@@ -150,8 +151,5 @@
         }
       ]
     ]
-  },
-  "dependencies": {
-    "lodash.debounce": "^4.0.8"
   }
 }
diff --git a/src/Button.tsx b/src/Button.tsx
diff --git a/src/Placeholder.tsx b/src/Placeholder.tsx

Original file line number	Diff line number	Diff line change
`@@ -60,6 +60,7 @@`
`60`	`60`	`"eslint-config-prettier": "^8.5.0",`
`61`	`61`	`"eslint-plugin-prettier": "^4.0.0",`
`62`	`62`	`"jest": "^28.1.1",`
	`63`	`+ "lodash.debounce": "^4.0.8",`
`63`	`64`	`"pod-install": "^0.1.0",`
`64`	`65`	`"prettier": "^2.0.5",`
`65`	`66`	`"react": "17.0.2",`
`@@ -150,8 +151,5 @@`
`150`	`151`	`}`
`151`	`152`	`]`
`152`	`153`	`]`
`153`		`- },`
`154`		`- "dependencies": {`
`155`		`- "lodash.debounce": "^4.0.8"`
`156`	`154`	`}`
`157`	`155`	`}`