From 6c696f65168c50fb0fb2952440b237f0c87fee54 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mateusz=20M=C4=99drek?= Date: Wed, 20 Nov 2024 23:22:43 +0100 Subject: [PATCH] chore: prepare docs for v7 --- .eslintrc.js | 1 + .../module/SET_SHOULD_MIMIC_IOS_BEHAVIOR.mdx | 6 + docs/docs/guides/ALTERNATIVES.mdx | 16 +- docs/docs/guides/INSTALLATION.mdx | 16 +- docs/docs/guides/MIGRATION_FROM_2_X_X.mdx | 65 ------ docs/docs/guides/MIGRATION_FROM_V6_TO_V7.mdx | 19 ++ docs/docs/guides/USAGE_MODULE.mdx | 2 - docs/docs/guides/USAGE_VIEW.mdx | 13 -- docs/docs/recipes/BOTTOM_SHEET.mdx | 2 - docs/docs/recipes/CUSTOM_CONFIG.mdx | 4 - docs/docs/recipes/FORM.mdx | 2 - docs/docs/recipes/MODAL.mdx | 11 +- docs/docs/recipes/STICKY_FOOTER.mdx | 12 +- docs/sidebars.js | 2 +- .../USE_SOFT_INPUT_APPLIED_OFFSET_CHANGED.mdx | 24 +++ .../hooks/USE_SOFT_INPUT_HEIGHT_CHANGED.mdx | 24 +++ .../api/hooks/USE_SOFT_INPUT_HIDDEN.mdx | 24 +++ .../api/hooks/USE_SOFT_INPUT_SHOWN.mdx | 24 +++ .../api/hooks/USE_SOFT_INPUT_STATE.mdx | 22 ++ .../ON_SOFT_INPUT_APPLIED_OFFSET_CHANGE.mdx | 28 +++ .../module/ON_SOFT_INPUT_HEIGHT_CHANGE.mdx | 28 +++ .../api/module/ON_SOFT_INPUT_HIDDEN.mdx | 26 +++ .../api/module/ON_SOFT_INPUT_SHOWN.mdx | 26 +++ .../api/module/SET_ADJUST_NOTHING.mdx | 16 ++ .../api/module/SET_ADJUST_PAN.mdx | 16 ++ .../api/module/SET_ADJUST_RESIZE.mdx | 16 ++ .../api/module/SET_ADJUST_UNSPECIFIED.mdx | 16 ++ .../api/module/SET_AVOID_OFFSET.mdx | 26 +++ .../SET_DEFAULT_APP_SOFT_INPUT_MODE.mdx | 16 ++ .../version-7.0.x/api/module/SET_EASING.mdx | 22 ++ .../version-7.0.x/api/module/SET_ENABLED.mdx | 22 ++ .../api/module/SET_HIDE_ANIMATION_DELAY.mdx | 22 ++ .../module/SET_HIDE_ANIMATION_DURATION.mdx | 22 ++ .../module/SET_SHOULD_MIMIC_IOS_BEHAVIOR.mdx | 28 +++ .../api/module/SET_SHOW_ANIMATION_DELAY.mdx | 22 ++ .../module/SET_SHOW_ANIMATION_DURATION.mdx | 22 ++ .../version-7.0.x/api/view/VIEW.mdx | 48 +++++ .../version-7.0.x/guides/ALTERNATIVES.mdx | 12 ++ .../version-7.0.x/guides/INSTALLATION.mdx | 194 ++++++++++++++++++ .../version-7.0.x/guides/JEST_MOCK_USAGE.mdx | 44 ++++ .../guides/MIGRATION_FROM_V6_TO_V7.mdx | 19 ++ .../version-7.0.x/guides/USAGE_MODULE.mdx | 48 +++++ .../version-7.0.x/guides/USAGE_VIEW.mdx | 62 ++++++ .../version-7.0.x/recipes/ANIMATIONS.mdx | 129 ++++++++++++ .../version-7.0.x/recipes/BOTTOM_SHEET.mdx | 105 ++++++++++ .../version-7.0.x/recipes/CUSTOM_CONFIG.mdx | 137 +++++++++++++ .../version-7.0.x/recipes/FORM.mdx | 101 +++++++++ .../version-7.0.x/recipes/MODAL.mdx | 137 +++++++++++++ .../version-7.0.x/recipes/STICKY_FOOTER.mdx | 96 +++++++++ .../version-7.0.x-sidebars.json | 51 +++++ docs/versions.json | 1 + .../src/AvoidSoftInput.ts | 1 + 52 files changed, 1722 insertions(+), 126 deletions(-) delete mode 100644 docs/docs/guides/MIGRATION_FROM_2_X_X.mdx create mode 100644 docs/docs/guides/MIGRATION_FROM_V6_TO_V7.mdx create mode 100644 docs/versioned_docs/version-7.0.x/api/hooks/USE_SOFT_INPUT_APPLIED_OFFSET_CHANGED.mdx create mode 100644 docs/versioned_docs/version-7.0.x/api/hooks/USE_SOFT_INPUT_HEIGHT_CHANGED.mdx create mode 100644 docs/versioned_docs/version-7.0.x/api/hooks/USE_SOFT_INPUT_HIDDEN.mdx create mode 100644 docs/versioned_docs/version-7.0.x/api/hooks/USE_SOFT_INPUT_SHOWN.mdx create mode 100644 docs/versioned_docs/version-7.0.x/api/hooks/USE_SOFT_INPUT_STATE.mdx create mode 100644 docs/versioned_docs/version-7.0.x/api/module/ON_SOFT_INPUT_APPLIED_OFFSET_CHANGE.mdx create mode 100644 docs/versioned_docs/version-7.0.x/api/module/ON_SOFT_INPUT_HEIGHT_CHANGE.mdx create mode 100644 docs/versioned_docs/version-7.0.x/api/module/ON_SOFT_INPUT_HIDDEN.mdx create mode 100644 docs/versioned_docs/version-7.0.x/api/module/ON_SOFT_INPUT_SHOWN.mdx create mode 100644 docs/versioned_docs/version-7.0.x/api/module/SET_ADJUST_NOTHING.mdx create mode 100644 docs/versioned_docs/version-7.0.x/api/module/SET_ADJUST_PAN.mdx create mode 100644 docs/versioned_docs/version-7.0.x/api/module/SET_ADJUST_RESIZE.mdx create mode 100644 docs/versioned_docs/version-7.0.x/api/module/SET_ADJUST_UNSPECIFIED.mdx create mode 100644 docs/versioned_docs/version-7.0.x/api/module/SET_AVOID_OFFSET.mdx create mode 100644 docs/versioned_docs/version-7.0.x/api/module/SET_DEFAULT_APP_SOFT_INPUT_MODE.mdx create mode 100644 docs/versioned_docs/version-7.0.x/api/module/SET_EASING.mdx create mode 100644 docs/versioned_docs/version-7.0.x/api/module/SET_ENABLED.mdx create mode 100644 docs/versioned_docs/version-7.0.x/api/module/SET_HIDE_ANIMATION_DELAY.mdx create mode 100644 docs/versioned_docs/version-7.0.x/api/module/SET_HIDE_ANIMATION_DURATION.mdx create mode 100644 docs/versioned_docs/version-7.0.x/api/module/SET_SHOULD_MIMIC_IOS_BEHAVIOR.mdx create mode 100644 docs/versioned_docs/version-7.0.x/api/module/SET_SHOW_ANIMATION_DELAY.mdx create mode 100644 docs/versioned_docs/version-7.0.x/api/module/SET_SHOW_ANIMATION_DURATION.mdx create mode 100644 docs/versioned_docs/version-7.0.x/api/view/VIEW.mdx create mode 100644 docs/versioned_docs/version-7.0.x/guides/ALTERNATIVES.mdx create mode 100644 docs/versioned_docs/version-7.0.x/guides/INSTALLATION.mdx create mode 100644 docs/versioned_docs/version-7.0.x/guides/JEST_MOCK_USAGE.mdx create mode 100644 docs/versioned_docs/version-7.0.x/guides/MIGRATION_FROM_V6_TO_V7.mdx create mode 100644 docs/versioned_docs/version-7.0.x/guides/USAGE_MODULE.mdx create mode 100644 docs/versioned_docs/version-7.0.x/guides/USAGE_VIEW.mdx create mode 100644 docs/versioned_docs/version-7.0.x/recipes/ANIMATIONS.mdx create mode 100644 docs/versioned_docs/version-7.0.x/recipes/BOTTOM_SHEET.mdx create mode 100644 docs/versioned_docs/version-7.0.x/recipes/CUSTOM_CONFIG.mdx create mode 100644 docs/versioned_docs/version-7.0.x/recipes/FORM.mdx create mode 100644 docs/versioned_docs/version-7.0.x/recipes/MODAL.mdx create mode 100644 docs/versioned_docs/version-7.0.x/recipes/STICKY_FOOTER.mdx create mode 100644 docs/versioned_sidebars/version-7.0.x-sidebars.json diff --git a/.eslintrc.js b/.eslintrc.js index bd75c270..a38dd6a7 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -8,6 +8,7 @@ module.exports = { configFile: path.resolve(__dirname, 'packages', 'example', 'babel.config.js'), }, }, + ignorePatterns: ['**/react-native-avoid-softinput/lib/**/*'], overrides: [ { files: ['**/jest/*'], diff --git a/docs/docs/api/module/SET_SHOULD_MIMIC_IOS_BEHAVIOR.mdx b/docs/docs/api/module/SET_SHOULD_MIMIC_IOS_BEHAVIOR.mdx index def4987f..abda0053 100644 --- a/docs/docs/api/module/SET_SHOULD_MIMIC_IOS_BEHAVIOR.mdx +++ b/docs/docs/api/module/SET_SHOULD_MIMIC_IOS_BEHAVIOR.mdx @@ -5,6 +5,12 @@ sidebar_label: setShouldMimicIOSBehavior keywords: [react-native-avoid-softinput, setShouldMimicIOSBehavior, module] --- +:::warning + +**DEPRECATED** - to provide best possible support for Android 15, install [`react-native-edge-to-edge`](https://github.com/zoontek/react-native-edge-to-edge) + +::: + Use `setShouldMimicIOSBehavior` method, to determine whether keyboard on Android should be handled by the library (like on iOS) or should be managed by OS (via `android:windowSoftInputMode` param). ### Parameters diff --git a/docs/docs/guides/ALTERNATIVES.mdx b/docs/docs/guides/ALTERNATIVES.mdx index 09129b9b..40f6e8fc 100644 --- a/docs/docs/guides/ALTERNATIVES.mdx +++ b/docs/docs/guides/ALTERNATIVES.mdx @@ -2,21 +2,11 @@ id: alternatives title: Alternatives sidebar_label: Alternatives -keywords: [react-native-avoid-softinput, alternatives, react-native-keyboard-manager, react-native-keyboard-controller, react-native-keyboard-aware-scroll-view] +keywords: [react-native-avoid-softinput, alternatives, react-native-keyboard-controller] --- -If, for whatever reason, the library does not satisfy your project's use case, you can check following alternatives (all of them are great and much better than KeyboardAvoidingView): +If, for whatever reason, the library does not satisfy your project's use case, you can check [react-native-keyboard-controller](https://github.com/kirillzyusko/react-native-keyboard-controller) -## [react-native-keyboard-manager](https://github.com/douglasjunior/react-native-keyboard-manager) + `android:windowSoftInputMode="adjustResize"` - -On iOS, you can use react-native-keyboard-manager which under the hood uses well-known [IQKeyboardManager](https://github.com/hackiftekhar/IQKeyboardManager). And for the Android, you might try default `adjustResize` behavior. - -## [react-native-keyboard-controller](https://github.com/kirillzyusko/react-native-keyboard-controller) - -react-native-keyboard-controller has an interesting approach of detecting keyboard appearance on native side and letting you apply detected height to Reanimated or vanilla Animated views. +`react-native-keyboard-controller` has an interesting approach of detecting keyboard appearance on native side and letting you apply detected height to Reanimated or vanilla Animated views. It's written in Kotlin and Swift, it uses WindowInsetsCompat API on Android and it also supports Fabric & TurboModules from [version 1.2.0](https://kirillzyusko.github.io/react-native-keyboard-controller/blog/fabric). Additionally, it has a interactive keyboard support from [version 1.5.0](https://kirillzyusko.github.io/react-native-keyboard-controller/blog/interactive-keyboard). - -## [react-native-keyboard-aware-scroll-view](https://github.com/APSL/react-native-keyboard-aware-scroll-view) - -react-native-keyboard-aware-scroll-view can be used as a drop-in replacement for scroll containers that need to be keyboard aware. It has fully JS implementation, so it can be used in Expo Go apps. diff --git a/docs/docs/guides/INSTALLATION.mdx b/docs/docs/guides/INSTALLATION.mdx index 68d38eb7..1855d512 100644 --- a/docs/docs/guides/INSTALLATION.mdx +++ b/docs/docs/guides/INSTALLATION.mdx @@ -91,9 +91,17 @@ Add plugin inside of your `app.json` or `app.config.js` ### Keyboard handling on Android To make the keyboard handled **only** by `react-native-avoid-softinput` (and not by Android OS), you have to additionally make sure that default keyboard handling on Android is switched off (for iOS nothing to be done 🚀). -To do that, you need to make 2 steps: -#### Modify your Android's project `AndroidManifest.xml` +#### Recommended setup + +To provide best possible support for Android 15, install [`react-native-edge-to-edge`](https://github.com/zoontek/react-native-edge-to-edge) and follow its setup after installation + +
+:warning: Legacy setup + +To setup keyboard handling on Android without `react-native-edge-to-edge`, do the following: + +##### Modify your Android's project `AndroidManifest.xml` - **Expo project after [prebuild](https://docs.expo.dev/workflow/prebuild/) / bare RN project** @@ -127,10 +135,12 @@ To make `react-native-avoid-softinput` responsible for managing the available sp Go to Expo's `app.json`/`app.config.js` and modify [`softwareKeyboardLayoutMode`](https://docs.expo.dev/versions/latest/config/app/#softwarekeyboardlayoutmode), so that it has `resize` value (in a new Expo project it should be the default). -#### Use `AvoidSoftInput.setShouldMimicIOSBehavior(true)` later on in your app's code +##### Use `AvoidSoftInput.setShouldMimicIOSBehavior(true)` later on in your app's code Remember to call `AvoidSoftInput.setShouldMimicIOSBehavior(true)` somewhere in the project's code (either in some root component, if you use the library globally or in specific screen, if you use the library only in some places). +
+ ## 3. Define your use case
diff --git a/docs/docs/guides/MIGRATION_FROM_2_X_X.mdx b/docs/docs/guides/MIGRATION_FROM_2_X_X.mdx deleted file mode 100644 index 4b2d908f..00000000 --- a/docs/docs/guides/MIGRATION_FROM_2_X_X.mdx +++ /dev/null @@ -1,65 +0,0 @@ ---- -id: migration_from_2_x_x -title: Migration from 2.x.x -sidebar_label: Migration from 2.x.x -keywords: [react-native-avoid-softinput, migration] ---- - -## WindowInsetsCompat API (BREAKING CHANGE) - -From version 3.x.x Android implementation starts using [WindowInsetsCompat](https://developer.android.com/reference/androidx/core/view/WindowInsetsCompat) API. This made library's Android implementation more predictible and less hacky. - -As a consequence, from version 3.x.x onwards library to handle padding/translation on Android needs to call new method `setShouldMimicIOSBehavior` instead of `setAdjustNothing` - -If you upgrade to version 3.x.x or newer (and you don't use `setAdjustNothing` or `setDefaultAppSoftInputMode` intentionally to handle sth else then library's correct usage on Android), just replace all `setAdjustNothing` (and `setDefaultAppSoftInputMode`) calls with `setShouldMimicIOSBehavior()`. - -#### Example - -```diff - /** - * If module in your app is always enabled, - * just change `setAdjustNothing` with `setShouldMimicIOSBehavior(true)` - */ - useEffect(() => { -- AvoidSoftInput.setAdjustNothing(); // <---- Set windowSoftInputMode on Android to match iOS behavior -+ AvoidSoftInput.setShouldMimicIOSBehavior(true); // <---- Tell Android that library will handle keyboard insets manually to match iOS behavior - AvoidSoftInput.setEnabled(true); // <---- Enable module - }, []); - - /** - * If you used module only in specific screen with react-navigation, - * change `setAdjustNothing` with `setShouldMimicIOSBehavior(true)` - * and replace `setDefaultAppSoftInputMode` with `setShouldMimicIOSBehavior(false)` - */ - const onFocusEffect = useCallback(() => { -- AvoidSoftInput.setAdjustNothing(); // <---- Set windowSoftInputMode on Android to match iOS behavior -+ AvoidSoftInput.setShouldMimicIOSBehavior(true); // <---- Tell Android that library will handle keyboard insets manually to match iOS behavior - AvoidSoftInput.setEnabled(true); // <---- Enable module - return () => { - AvoidSoftInput.setEnabled(false); -- AvoidSoftInput.setDefaultAppSoftInputMode(); -+ AvoidSoftInput.setShouldMimicIOSBehavior(false); - }; - }, []); - - useFocusEffect(onFocusEffect); -``` - -## Support for Fabric & TurboModules - -From version 3.x.x onwards library supports RN's new architecture in projects with RN version >= 0.70. Autolinking of Fabric & TurboModule library version is handled automatically with projects using `@react-native-community/cli` version >= 9.0.0 ([support was implemented with this commit](https://github.com/react-native-community/cli/commit/86df104250608977130378b9b59d8a9e12d0212a)) - -## Bumping minimal supported React Native and iOS versions (BREAKING CHANGE) - -### Version 4.x.x - -This library follows the React Native releases support policy. -It is supporting **the latest version**, and **the two previous minor series**. - -You may find it working correctly with some older React Native versions, but it'll be a "Use at your own risk" case. - -### Version 3.x.x - -As a result of introducing support for Fabric & TurboModules library bumped its minimal supported RN version (on old architecture) to 0.65 and minimal supported iOS version to 11.0. - -If you use library on older project (RN version \<\= 0.64), you have to upgrade RN to version >= 0.65. diff --git a/docs/docs/guides/MIGRATION_FROM_V6_TO_V7.mdx b/docs/docs/guides/MIGRATION_FROM_V6_TO_V7.mdx new file mode 100644 index 00000000..13c85c74 --- /dev/null +++ b/docs/docs/guides/MIGRATION_FROM_V6_TO_V7.mdx @@ -0,0 +1,19 @@ +--- +id: migration_from_v6_to_v7 +title: Migration from v6 to v7 +sidebar_label: Migration from v6 to v7 +keywords: [react-native-avoid-softinput, migration] +--- + +## Migrate to [`react-native-edge-to-edge`](https://github.com/zoontek/react-native-edge-to-edge) to provide best support for Android 15 "edge to edge" mode + +Since v7, the library supports detection of `react-native-edge-to-edge`. +Follow the [installation page](./INSTALLATION.mdx) for the recommended setup for keyboard handling on Android. +Existing `AvoidSoftInput.setShouldMimicIOSBehavior` function is considered deprecated from v7 and will be removed in future major versions. + +```diff +useEffect(() => { +- AvoidSoftInput.setShouldMimicIOSBehavior(true); // <---- Tell Android that library will handle keyboard insets manually to match iOS behavior + AvoidSoftInput.setEnabled(true); // <---- Enable module +}, []); +``` diff --git a/docs/docs/guides/USAGE_MODULE.mdx b/docs/docs/guides/USAGE_MODULE.mdx index 1ebe0857..04384039 100644 --- a/docs/docs/guides/USAGE_MODULE.mdx +++ b/docs/docs/guides/USAGE_MODULE.mdx @@ -21,12 +21,10 @@ export const FormExample: React.FC = () => { // highlight-start const onFocusEffect = React.useCallback(() => { // This should be run when screen gains focus - enable the module where it's needed - AvoidSoftInput.setShouldMimicIOSBehavior(true); AvoidSoftInput.setEnabled(true); return () => { // This should be run when screen loses focus - disable the module where it's not needed, to make a cleanup AvoidSoftInput.setEnabled(false); - AvoidSoftInput.setShouldMimicIOSBehavior(false); }; }, []); diff --git a/docs/docs/guides/USAGE_VIEW.mdx b/docs/docs/guides/USAGE_VIEW.mdx index 6843b187..a76ae9f0 100644 --- a/docs/docs/guides/USAGE_VIEW.mdx +++ b/docs/docs/guides/USAGE_VIEW.mdx @@ -18,19 +18,6 @@ import { useFocusEffect } from "@react-navigation/native"; export const ModalExample: React.FC = () => { const [ modalVisible, setModalVisible ] = React.useState(false); -// highlight-start - const onFocusEffect = React.useCallback(() => { - // This should be run when screen gains focus - enable the module where it's needed - AvoidSoftInput.setShouldMimicIOSBehavior(true); - return () => { - // This should be run when screen loses focus - disable the module where it's not needed, to make a cleanup - AvoidSoftInput.setShouldMimicIOSBehavior(false); - }; - }, []); - - useFocusEffect(onFocusEffect); // register callback to focus events -// highlight-end - function closeModal() { setModalVisible(false); } diff --git a/docs/docs/recipes/BOTTOM_SHEET.mdx b/docs/docs/recipes/BOTTOM_SHEET.mdx index 5d047bed..2704cc19 100644 --- a/docs/docs/recipes/BOTTOM_SHEET.mdx +++ b/docs/docs/recipes/BOTTOM_SHEET.mdx @@ -37,14 +37,12 @@ export const BottomSheetExample: React.FC = () => { } const onFocusEffect = React.useCallback(() => { - AvoidSoftInput.setShouldMimicIOSBehavior(true); AvoidSoftInput.setEnabled(true); AvoidSoftInput.setAvoidOffset(70); return () => { AvoidSoftInput.setAvoidOffset(0); AvoidSoftInput.setEnabled(false); - AvoidSoftInput.setShouldMimicIOSBehavior(false); }; }, []); diff --git a/docs/docs/recipes/CUSTOM_CONFIG.mdx b/docs/docs/recipes/CUSTOM_CONFIG.mdx index 8809683f..73b5c127 100644 --- a/docs/docs/recipes/CUSTOM_CONFIG.mdx +++ b/docs/docs/recipes/CUSTOM_CONFIG.mdx @@ -20,7 +20,6 @@ import SingleInput from '../components/SingleInput'; export const CustomAnimationConfigModuleExample: React.FC = () => { const onFocusEffect = React.useCallback(() => { - AvoidSoftInput.setShouldMimicIOSBehavior(true); AvoidSoftInput.setEnabled(true); AvoidSoftInput.setEasing('easeOut'); AvoidSoftInput.setHideAnimationDelay(1000); @@ -34,7 +33,6 @@ export const CustomAnimationConfigModuleExample: React.FC = () => { AvoidSoftInput.setShowAnimationDelay(); AvoidSoftInput.setShowAnimationDuration(); AvoidSoftInput.setEnabled(false); - AvoidSoftInput.setShouldMimicIOSBehavior(false); }; }, []); @@ -90,11 +88,9 @@ import SingleInput from '../components/SingleInput'; export const CustomAnimationConfigViewExample: React.FC = () => { const onFocusEffect = React.useCallback(() => { - AvoidSoftInput.setShouldMimicIOSBehavior(true); AvoidSoftInput.setEnabled(true); return () => { AvoidSoftInput.setEnabled(false); - AvoidSoftInput.setShouldMimicIOSBehavior(false); }; }, []); diff --git a/docs/docs/recipes/FORM.mdx b/docs/docs/recipes/FORM.mdx index e620e8b9..1b34e7c1 100644 --- a/docs/docs/recipes/FORM.mdx +++ b/docs/docs/recipes/FORM.mdx @@ -28,11 +28,9 @@ const NOOP = () => {}; export const FormExample: React.FC = () => { const onFocusEffect = React.useCallback(() => { - AvoidSoftInput.setShouldMimicIOSBehavior(true); AvoidSoftInput.setEnabled(true); return () => { AvoidSoftInput.setEnabled(false); - AvoidSoftInput.setShouldMimicIOSBehavior(false); }; }, []); diff --git a/docs/docs/recipes/MODAL.mdx b/docs/docs/recipes/MODAL.mdx index e14c98c4..ea32cd9a 100644 --- a/docs/docs/recipes/MODAL.mdx +++ b/docs/docs/recipes/MODAL.mdx @@ -14,7 +14,7 @@ When the keyboard is visible, the only tasks are to push the input (if needed) a import { useFocusEffect } from '@react-navigation/native'; import * as React from 'react'; import { Image, Modal, ScrollView, StyleSheet, View } from 'react-native'; -import { AvoidSoftInput, AvoidSoftInputView } from 'react-native-avoid-softinput'; +import { AvoidSoftInputView } from 'react-native-avoid-softinput'; import { SafeAreaView } from 'react-native-safe-area-context'; import Button from '../components/Button'; @@ -28,15 +28,6 @@ const icon = require('../../assets/AppIconTransparent.png'); export const ModalExample: React.FC = () => { const [ modalVisible, setModalVisible ] = React.useState(false); - const onFocusEffect = React.useCallback(() => { - AvoidSoftInput.setShouldMimicIOSBehavior(true); - return () => { - AvoidSoftInput.setShouldMimicIOSBehavior(false); - }; - }, []); - - useFocusEffect(onFocusEffect); - function closeModal() { setModalVisible(false); } diff --git a/docs/docs/recipes/STICKY_FOOTER.mdx b/docs/docs/recipes/STICKY_FOOTER.mdx index bd4a06bd..adac327f 100644 --- a/docs/docs/recipes/STICKY_FOOTER.mdx +++ b/docs/docs/recipes/STICKY_FOOTER.mdx @@ -17,7 +17,7 @@ Check [StickyFooterExample](https://github.com/mateusz1913/react-native-avoid-so import { useFocusEffect } from '@react-navigation/native'; import * as React from 'react'; import { ScrollView, StyleSheet, View } from 'react-native'; -import { AvoidSoftInput, useSoftInputHeightChanged } from 'react-native-avoid-softinput'; +import { useSoftInputHeightChanged } from 'react-native-avoid-softinput'; import Animated, { useAnimatedStyle, useSharedValue, withTiming } from 'react-native-reanimated'; import { SafeAreaView } from 'react-native-safe-area-context'; @@ -36,16 +36,6 @@ export const StickyFooterExample: React.FC = () => { }; }); - const onFocusEffect = React.useCallback(() => { - AvoidSoftInput.setShouldMimicIOSBehavior(true); - - return () => { - AvoidSoftInput.setShouldMimicIOSBehavior(false); - }; - }, []); - - useFocusEffect(onFocusEffect); - /** * You can also use `useSoftInputShown` & `useSoftInputHidden` * diff --git a/docs/sidebars.js b/docs/sidebars.js index 19398fa4..a16968d2 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -5,7 +5,7 @@ const sidebars = { docsSidebar: { 'Guides': [ 'guides/installation', - 'guides/migration_from_2_x_x', + 'guides/migration_from_v6_to_v7', 'guides/usage-module', 'guides/usage-view', 'guides/jest-mock-usage', diff --git a/docs/versioned_docs/version-7.0.x/api/hooks/USE_SOFT_INPUT_APPLIED_OFFSET_CHANGED.mdx b/docs/versioned_docs/version-7.0.x/api/hooks/USE_SOFT_INPUT_APPLIED_OFFSET_CHANGED.mdx new file mode 100644 index 00000000..8f511b3f --- /dev/null +++ b/docs/versioned_docs/version-7.0.x/api/hooks/USE_SOFT_INPUT_APPLIED_OFFSET_CHANGED.mdx @@ -0,0 +1,24 @@ +--- +id: use-soft-input-applied-offset-changed +title: useSoftInputAppliedOffsetChanged +sidebar_label: useSoftInputAppliedOffsetChanged +keywords: [react-native-avoid-softinput, useSoftInputAppliedOffsetChanged, react hooks] +--- + +`useSoftInputAppliedOffsetChanged` is a shortcut for using `AvoidSoftInput.onSoftInputAppliedOffsetChange` method inside `useEffect`. + +### Parameters + +| Type | Required | Description | +| ---------------------------------------------------------- | -------- | --------------------------------------------------------------------------------- | +| (\{ appliedOffset \}: \{ appliedOffset: number \}) => void | yes | function called during applying padding or translation with current applied value | + +### Example + +```ts +import { useSoftInputAppliedOffsetChanged } from "react-native-avoid-softinput"; + +useSoftInputAppliedOffsetChanged(({ appliedOffset }) => { + // Do sth +}); +``` diff --git a/docs/versioned_docs/version-7.0.x/api/hooks/USE_SOFT_INPUT_HEIGHT_CHANGED.mdx b/docs/versioned_docs/version-7.0.x/api/hooks/USE_SOFT_INPUT_HEIGHT_CHANGED.mdx new file mode 100644 index 00000000..465cbdf9 --- /dev/null +++ b/docs/versioned_docs/version-7.0.x/api/hooks/USE_SOFT_INPUT_HEIGHT_CHANGED.mdx @@ -0,0 +1,24 @@ +--- +id: use-soft-input-height-changed +title: useSoftInputHeightChanged +sidebar_label: useSoftInputHeightChanged +keywords: [react-native-avoid-softinput, useSoftInputHeightChanged, react hooks] +--- + +`useSoftInputHeightChanged` is a shortcut for using `AvoidSoftInput.onSoftInputHeightChange` method inside `useEffect`. + +### Parameters + +| Type | Required | Description | +| -------------------------------------------------------------- | -------- | --------------------------------------------------------------------------- | +| (\{ softInputHeight \}: \{ softInputHeight: number \}) => void | yes | function called with current soft input height when soft input is displayed | + +### Example + +```ts +import { useSoftInputHeightChanged } from "react-native-avoid-softinput"; + +useSoftInputHeightChanged(({ softInputHeight }) => { + // Do sth +}); +``` diff --git a/docs/versioned_docs/version-7.0.x/api/hooks/USE_SOFT_INPUT_HIDDEN.mdx b/docs/versioned_docs/version-7.0.x/api/hooks/USE_SOFT_INPUT_HIDDEN.mdx new file mode 100644 index 00000000..3e30b34e --- /dev/null +++ b/docs/versioned_docs/version-7.0.x/api/hooks/USE_SOFT_INPUT_HIDDEN.mdx @@ -0,0 +1,24 @@ +--- +id: use-soft-input-hidden +title: useSoftInputHidden +sidebar_label: useSoftInputHidden +keywords: [react-native-avoid-softinput, useSoftInputHidden, react hooks] +--- + +`useSoftInputHidden` is a shortcut for using `AvoidSoftInput.onSoftInputHidden` method inside `useEffect`. + +### Parameters + +| Type | Required | Description | +| ---------- | -------- | ----------------------------------------- | +| () => void | yes | function called when soft input is hidden | + +### Example + +```ts +import { useSoftInputHidden } from "react-native-avoid-softinput"; + +useSoftInputHidden(() => { + // Do sth +}); +``` diff --git a/docs/versioned_docs/version-7.0.x/api/hooks/USE_SOFT_INPUT_SHOWN.mdx b/docs/versioned_docs/version-7.0.x/api/hooks/USE_SOFT_INPUT_SHOWN.mdx new file mode 100644 index 00000000..74ee9e64 --- /dev/null +++ b/docs/versioned_docs/version-7.0.x/api/hooks/USE_SOFT_INPUT_SHOWN.mdx @@ -0,0 +1,24 @@ +--- +id: use-soft-input-shown +title: useSoftInputShown +sidebar_label: useSoftInputShown +keywords: [react-native-avoid-softinput, useSoftInputShown, react hooks] +--- + +`useSoftInputShown` is a shortcut for using `AvoidSoftInput.onSoftInputShown` method inside `useEffect`. + +### Parameters + +| Type | Required | Description | +| -------------------------------------------------------------- | -------- | --------------------------------------------------------------------------- | +| (\{ softInputHeight \}: \{ softInputHeight: number \}) => void | yes | function called with current soft input height when soft input is displayed | + +### Example + +```ts +import { useSoftInputShown } from "react-native-avoid-softinput"; + +useSoftInputShown(({ softInputHeight }) => { + // Do sth +}); +``` diff --git a/docs/versioned_docs/version-7.0.x/api/hooks/USE_SOFT_INPUT_STATE.mdx b/docs/versioned_docs/version-7.0.x/api/hooks/USE_SOFT_INPUT_STATE.mdx new file mode 100644 index 00000000..86d7e917 --- /dev/null +++ b/docs/versioned_docs/version-7.0.x/api/hooks/USE_SOFT_INPUT_STATE.mdx @@ -0,0 +1,22 @@ +--- +id: use-soft-input-state +title: useSoftInputState +sidebar_label: useSoftInputState +keywords: [react-native-avoid-softinput, useSoftInputState, react hooks] +--- + +`useSoftInputState` returns object with properties determining whether soft input is shown and how much screen it covers. + +### Return value + +``` +{ isSoftInputShown: boolean, softInputHeight: number } +``` + +### Example + +```ts +import { useSoftInputState } from "react-native-avoid-softinput"; + +const { isSoftInputShown, softInputHeight } = useSoftInputState(); +``` diff --git a/docs/versioned_docs/version-7.0.x/api/module/ON_SOFT_INPUT_APPLIED_OFFSET_CHANGE.mdx b/docs/versioned_docs/version-7.0.x/api/module/ON_SOFT_INPUT_APPLIED_OFFSET_CHANGE.mdx new file mode 100644 index 00000000..6d875da4 --- /dev/null +++ b/docs/versioned_docs/version-7.0.x/api/module/ON_SOFT_INPUT_APPLIED_OFFSET_CHANGE.mdx @@ -0,0 +1,28 @@ +--- +id: on-soft-input-applied-offset-change +title: onSoftInputAppliedOffsetChange +sidebar_label: onSoftInputAppliedOffsetChange +keywords: [react-native-avoid-softinput, onSoftInputAppliedOffsetChange, module] +--- + +Use `onSoftInputAppliedOffsetChange` method, to e.g. create animation based on current applied offset value. + +### Parameters + +| Type | Required | Description | +| ---------------------------------------------------------- | -------- | --------------------------------------------------------------------------------- | +| (\{ appliedOffset \}: \{ appliedOffset: number \}) => void | yes | function called during applying padding or translation with current applied value | + +### Example + +```ts +import { AvoidSoftInput } from "react-native-avoid-softinput"; + +const unsubscribe = AvoidSoftInput.onSoftInputAppliedOffsetChange( + ({ appliedOffset }) => { + // Do sth + } +); + +// Later invoke unsubscribe.remove() +``` diff --git a/docs/versioned_docs/version-7.0.x/api/module/ON_SOFT_INPUT_HEIGHT_CHANGE.mdx b/docs/versioned_docs/version-7.0.x/api/module/ON_SOFT_INPUT_HEIGHT_CHANGE.mdx new file mode 100644 index 00000000..2007bb17 --- /dev/null +++ b/docs/versioned_docs/version-7.0.x/api/module/ON_SOFT_INPUT_HEIGHT_CHANGE.mdx @@ -0,0 +1,28 @@ +--- +id: on-soft-input-height-change +title: onSoftInputHeightChange +sidebar_label: onSoftInputHeightChange +keywords: [react-native-avoid-softinput, onSoftInputHeightChange, module] +--- + +Use `onSoftInputHeightChange` method, if you want to listen to events when soft input's height changes. + +### Parameters + +| Type | Required | Description | +| -------------------------------------------------------------- | -------- | --------------------------------------------------------------------------- | +| (\{ softInputHeight \}: \{ softInputHeight: number \}) => void | yes | function called with current soft input height when soft input is displayed | + +### Example + +```ts +import { AvoidSoftInput } from "react-native-avoid-softinput"; + +const unsubscribe = AvoidSoftInput.onSoftInputHeightChange( + ({ softInputHeight }) => { + // Do sth + } +); + +// later invoke unsubscribe.remove() +``` diff --git a/docs/versioned_docs/version-7.0.x/api/module/ON_SOFT_INPUT_HIDDEN.mdx b/docs/versioned_docs/version-7.0.x/api/module/ON_SOFT_INPUT_HIDDEN.mdx new file mode 100644 index 00000000..278bd8ae --- /dev/null +++ b/docs/versioned_docs/version-7.0.x/api/module/ON_SOFT_INPUT_HIDDEN.mdx @@ -0,0 +1,26 @@ +--- +id: on-soft-input-hidden +title: onSoftInputHidden +sidebar_label: onSoftInputHidden +keywords: [react-native-avoid-softinput, onSoftInputHidden, module] +--- + +Use `onSoftInputHidden` method, if you want to listen to events when soft input is hidden. + +### Parameters + +| Type | Required | Description | +| ---------- | -------- | ----------------------------------------- | +| () => void | yes | function called when soft input is hidden | + +### Example + +```ts +import { AvoidSoftInput } from "react-native-avoid-softinput"; + +const unsubscribe = AvoidSoftInput.onSoftInputHidden(() => { + // Do sth +}); + +// later invoke unsubscribe.remove() +``` diff --git a/docs/versioned_docs/version-7.0.x/api/module/ON_SOFT_INPUT_SHOWN.mdx b/docs/versioned_docs/version-7.0.x/api/module/ON_SOFT_INPUT_SHOWN.mdx new file mode 100644 index 00000000..2f1e5007 --- /dev/null +++ b/docs/versioned_docs/version-7.0.x/api/module/ON_SOFT_INPUT_SHOWN.mdx @@ -0,0 +1,26 @@ +--- +id: on-soft-input-shown +title: onSoftInputShown +sidebar_label: onSoftInputShown +keywords: [react-native-avoid-softinput, onSoftInputShown, module] +--- + +Use `onSoftInputShown` method, if you want to listen to events when soft input is shown. + +### Parameters + +| Type | Required | Description | +| -------------------------------------------------------------- | -------- | --------------------------------------------------------------------------- | +| (\{ softInputHeight \}: \{ softInputHeight: number \}) => void | yes | function called with current soft input height when soft input is displayed | + +### Example + +```ts +import { AvoidSoftInput } from "react-native-avoid-softinput"; + +const unsubscribe = AvoidSoftInput.onSoftInputShown(({ softInputHeight }) => { + // Do sth +}); + +// later invoke unsubscribe.remove() +``` diff --git a/docs/versioned_docs/version-7.0.x/api/module/SET_ADJUST_NOTHING.mdx b/docs/versioned_docs/version-7.0.x/api/module/SET_ADJUST_NOTHING.mdx new file mode 100644 index 00000000..261d516a --- /dev/null +++ b/docs/versioned_docs/version-7.0.x/api/module/SET_ADJUST_NOTHING.mdx @@ -0,0 +1,16 @@ +--- +id: set-adjust-nothing +title: setAdjustNothing +sidebar_label: setAdjustNothing +keywords: [react-native-avoid-softinput, setAdjustNothing, module] +--- + +Use `setAdjustNothing`, to set `android:windowSoftInputMode` attribute to `adjustNothing` value. + +### Example + +```ts +import { AvoidSoftInput } from "react-native-avoid-softinput"; + +AvoidSoftInput.setAdjustNothing(); +``` diff --git a/docs/versioned_docs/version-7.0.x/api/module/SET_ADJUST_PAN.mdx b/docs/versioned_docs/version-7.0.x/api/module/SET_ADJUST_PAN.mdx new file mode 100644 index 00000000..9aec2265 --- /dev/null +++ b/docs/versioned_docs/version-7.0.x/api/module/SET_ADJUST_PAN.mdx @@ -0,0 +1,16 @@ +--- +id: set-adjust-pan +title: setAdjustPan +sidebar_label: setAdjustPan +keywords: [react-native-avoid-softinput, setAdjustPan, module] +--- + +Use `setAdjustPan`, to set `android:windowSoftInputMode` attribute to `adjustPan` value. + +### Example + +```ts +import { AvoidSoftInput } from "react-native-avoid-softinput"; + +AvoidSoftInput.setAdjustPan(); +``` diff --git a/docs/versioned_docs/version-7.0.x/api/module/SET_ADJUST_RESIZE.mdx b/docs/versioned_docs/version-7.0.x/api/module/SET_ADJUST_RESIZE.mdx new file mode 100644 index 00000000..ac5fb94d --- /dev/null +++ b/docs/versioned_docs/version-7.0.x/api/module/SET_ADJUST_RESIZE.mdx @@ -0,0 +1,16 @@ +--- +id: set-adjust-resize +title: setAdjustResize +sidebar_label: setAdjustResize +keywords: [react-native-avoid-softinput, setAdjustResize, module] +--- + +Use `setAdjustResize`, to set `android:windowSoftInputMode` attribute to `adjustResize` value. + +### Example + +```ts +import { AvoidSoftInput } from "react-native-avoid-softinput"; + +AvoidSoftInput.setAdjustResize(); +``` diff --git a/docs/versioned_docs/version-7.0.x/api/module/SET_ADJUST_UNSPECIFIED.mdx b/docs/versioned_docs/version-7.0.x/api/module/SET_ADJUST_UNSPECIFIED.mdx new file mode 100644 index 00000000..de294e39 --- /dev/null +++ b/docs/versioned_docs/version-7.0.x/api/module/SET_ADJUST_UNSPECIFIED.mdx @@ -0,0 +1,16 @@ +--- +id: set-adjust-unspecified +title: setAdjustUnspecified +sidebar_label: setAdjustUnspecified +keywords: [react-native-avoid-softinput, setAdjustUnspecified, module] +--- + +Use `setAdjustUnspecified`, to set `android:windowSoftInputMode` attribute to `adjustUnspecified` value. + +### Example + +```ts +import { AvoidSoftInput } from "react-native-avoid-softinput"; + +AvoidSoftInput.setAdjustUnspecified(); +``` diff --git a/docs/versioned_docs/version-7.0.x/api/module/SET_AVOID_OFFSET.mdx b/docs/versioned_docs/version-7.0.x/api/module/SET_AVOID_OFFSET.mdx new file mode 100644 index 00000000..78a7d5db --- /dev/null +++ b/docs/versioned_docs/version-7.0.x/api/module/SET_AVOID_OFFSET.mdx @@ -0,0 +1,26 @@ +--- +id: set-avoid-offset +title: setAvoidOffset +sidebar_label: setAvoidOffset +keywords: [react-native-avoid-softinput, setAvoidOffset, module] +--- + +Use `setAvoidOffset` method, if you want to increase/decrease amount of translation/padding applied to react root view/scroll view. + +### Parameters + +| Type | Required | Description | +| ------ | -------- | ------------------------------------------------------ | +| number | yes | additional offset added to react root view/scroll view | + +### Example + +```ts +import { AvoidSoftInput } from "react-native-avoid-softinput"; + +AvoidSoftInput.setAvoidOffset(40); // It will result in applied value 40dp greater than standard one +``` + +:::info +**Value applied to that method is persisted, so if you want to use that in a single use case, remember to clear it (just pass 0 as an argument)** +::: diff --git a/docs/versioned_docs/version-7.0.x/api/module/SET_DEFAULT_APP_SOFT_INPUT_MODE.mdx b/docs/versioned_docs/version-7.0.x/api/module/SET_DEFAULT_APP_SOFT_INPUT_MODE.mdx new file mode 100644 index 00000000..d6eb674a --- /dev/null +++ b/docs/versioned_docs/version-7.0.x/api/module/SET_DEFAULT_APP_SOFT_INPUT_MODE.mdx @@ -0,0 +1,16 @@ +--- +id: set-default-app-soft-input-mode +title: setDefaultAppSoftInputMode +sidebar_label: setDefaultAppSoftInputMode +keywords: [react-native-avoid-softinput, setDefaultAppSoftInputMode, module] +--- + +Use `setDefaultAppSoftInputMode`, to set `android:windowSoftInputMode` to default value declared in Android manifest. + +### Example + +```ts +import { AvoidSoftInput } from "react-native-avoid-softinput"; + +AvoidSoftInput.setDefaultAppSoftInputMode(); +``` diff --git a/docs/versioned_docs/version-7.0.x/api/module/SET_EASING.mdx b/docs/versioned_docs/version-7.0.x/api/module/SET_EASING.mdx new file mode 100644 index 00000000..8c6de96a --- /dev/null +++ b/docs/versioned_docs/version-7.0.x/api/module/SET_EASING.mdx @@ -0,0 +1,22 @@ +--- +id: set-easing +title: setEasing +sidebar_label: setEasing +keywords: [react-native-avoid-softinput, setEasing, module] +--- + +Use `setEasing` method, to customize animation's easing, available values are `easeIn`, `easeInOut`, `easeOut` and `linear`. + +### Parameters + +| Type | Required | Description | +| ------------------------------------------------ | -------- | ------------------ | +| `easeIn` or `easeInOut` or `easeOut` or `linear` | yes | animation's easing | + +### Example + +```ts +import { AvoidSoftInput } from "react-native-avoid-softinput"; + +AvoidSoftInput.setEasing("easeInOut"); // Changes animation's easing to `easeInOut` curve +``` diff --git a/docs/versioned_docs/version-7.0.x/api/module/SET_ENABLED.mdx b/docs/versioned_docs/version-7.0.x/api/module/SET_ENABLED.mdx new file mode 100644 index 00000000..4b520ace --- /dev/null +++ b/docs/versioned_docs/version-7.0.x/api/module/SET_ENABLED.mdx @@ -0,0 +1,22 @@ +--- +id: set-enabled +title: setEnabled +sidebar_label: setEnabled +keywords: [react-native-avoid-softinput, setEnabled, module] +--- + +Use `setEnabled` method, to enable or disable module. + +### Parameters + +| Type | Required | Description | +| ------- | -------- | --------------------------------- | +| boolean | yes | control whether module is enabled | + +### Example + +```ts +import { AvoidSoftInput } from "react-native-avoid-softinput"; + +AvoidSoftInput.setEnabled(true); +``` diff --git a/docs/versioned_docs/version-7.0.x/api/module/SET_HIDE_ANIMATION_DELAY.mdx b/docs/versioned_docs/version-7.0.x/api/module/SET_HIDE_ANIMATION_DELAY.mdx new file mode 100644 index 00000000..19316a08 --- /dev/null +++ b/docs/versioned_docs/version-7.0.x/api/module/SET_HIDE_ANIMATION_DELAY.mdx @@ -0,0 +1,22 @@ +--- +id: set-hide-animation-delay +title: setHideAnimationDelay +sidebar_label: setHideAnimationDelay +keywords: [react-native-avoid-softinput, setHideAnimationDelay, module] +--- + +Use `setHideAnimationDelay` method, to customize delay of hide offset animation with delay value in ms. + +### Parameters + +| Type | Required | Description | +| ------ | -------------------------------------------- | --------------------------- | +| number | no (defaults to 0 on Android and 300 on iOS) | hide offset animation delay | + +### Example + +```ts +import { AvoidSoftInput } from "react-native-avoid-softinput"; + +AvoidSoftInput.setHideAnimationDelay(100); +``` diff --git a/docs/versioned_docs/version-7.0.x/api/module/SET_HIDE_ANIMATION_DURATION.mdx b/docs/versioned_docs/version-7.0.x/api/module/SET_HIDE_ANIMATION_DURATION.mdx new file mode 100644 index 00000000..41006083 --- /dev/null +++ b/docs/versioned_docs/version-7.0.x/api/module/SET_HIDE_ANIMATION_DURATION.mdx @@ -0,0 +1,22 @@ +--- +id: set-hide-animation-duration +title: setHideAnimationDuration +sidebar_label: setHideAnimationDuration +keywords: [react-native-avoid-softinput, setHideAnimationDuration, module] +--- + +Use `setHideAnimationDuration` method, to customize duration of hide offset animation with duration value in ms. + +### Parameters + +| Type | Required | Description | +| ------ | -------------------- | ------------------------------ | +| number | no (defaults to 220) | hide offset animation duration | + +### Example + +```ts +import { AvoidSoftInput } from "react-native-avoid-softinput"; + +AvoidSoftInput.setHideAnimationDuration(300); +``` diff --git a/docs/versioned_docs/version-7.0.x/api/module/SET_SHOULD_MIMIC_IOS_BEHAVIOR.mdx b/docs/versioned_docs/version-7.0.x/api/module/SET_SHOULD_MIMIC_IOS_BEHAVIOR.mdx new file mode 100644 index 00000000..abda0053 --- /dev/null +++ b/docs/versioned_docs/version-7.0.x/api/module/SET_SHOULD_MIMIC_IOS_BEHAVIOR.mdx @@ -0,0 +1,28 @@ +--- +id: set-should-mimic-ios-behavior +title: setShouldMimicIOSBehavior +sidebar_label: setShouldMimicIOSBehavior +keywords: [react-native-avoid-softinput, setShouldMimicIOSBehavior, module] +--- + +:::warning + +**DEPRECATED** - to provide best possible support for Android 15, install [`react-native-edge-to-edge`](https://github.com/zoontek/react-native-edge-to-edge) + +::: + +Use `setShouldMimicIOSBehavior` method, to determine whether keyboard on Android should be handled by the library (like on iOS) or should be managed by OS (via `android:windowSoftInputMode` param). + +### Parameters + +| Type | Required | Description | +| ------- | -------------------- | -------------------------------------------------- | +| boolean | yes | should library handle keyboard handling on Android | + +### Example + +```ts +import { AvoidSoftInput } from "react-native-avoid-softinput"; + +AvoidSoftInput.setShouldMimicIOSBehavior(true); +``` diff --git a/docs/versioned_docs/version-7.0.x/api/module/SET_SHOW_ANIMATION_DELAY.mdx b/docs/versioned_docs/version-7.0.x/api/module/SET_SHOW_ANIMATION_DELAY.mdx new file mode 100644 index 00000000..13b15bea --- /dev/null +++ b/docs/versioned_docs/version-7.0.x/api/module/SET_SHOW_ANIMATION_DELAY.mdx @@ -0,0 +1,22 @@ +--- +id: set-show-animation-delay +title: setShowAnimationDelay +sidebar_label: setShowAnimationDelay +keywords: [react-native-avoid-softinput, setShowAnimationDelay, module] +--- + +Use `setShowAnimationDelay` method, to customize delay of show offset animation with delay value in ms. + +### Parameters + +| Type | Required | Description | +| ------ | ------------------ | --------------------------- | +| number | no (defaults to 0) | show offset animation delay | + +### Example + +```ts +import { AvoidSoftInput } from "react-native-avoid-softinput"; + +AvoidSoftInput.setShowAnimationDelay(200); +``` diff --git a/docs/versioned_docs/version-7.0.x/api/module/SET_SHOW_ANIMATION_DURATION.mdx b/docs/versioned_docs/version-7.0.x/api/module/SET_SHOW_ANIMATION_DURATION.mdx new file mode 100644 index 00000000..6810be82 --- /dev/null +++ b/docs/versioned_docs/version-7.0.x/api/module/SET_SHOW_ANIMATION_DURATION.mdx @@ -0,0 +1,22 @@ +--- +id: set-show-animation-duration +title: setShowAnimationDuration +sidebar_label: setShowAnimationDuration +keywords: [react-native-avoid-softinput, setShowAnimationDuration, module] +--- + +Use `setShowAnimationDuration` method, to customize duration of show offset animation with duration value in ms. + +### Parameters + +| Type | Required | Description | +| ------ | -------------------- | ------------------------------ | +| number | no (defaults to 660) | show offset animation duration | + +### Example + +```ts +import { AvoidSoftInput } from "react-native-avoid-softinput"; + +AvoidSoftInput.setShowAnimationDuration(800); +``` diff --git a/docs/versioned_docs/version-7.0.x/api/view/VIEW.mdx b/docs/versioned_docs/version-7.0.x/api/view/VIEW.mdx new file mode 100644 index 00000000..1a24f222 --- /dev/null +++ b/docs/versioned_docs/version-7.0.x/api/view/VIEW.mdx @@ -0,0 +1,48 @@ +--- +id: view +title: AvoidSoftInputView +sidebar_label: AvoidSoftInputView +keywords: [react-native-avoid-softinput, AvoidSoftInputView, view] +--- + +Wrap your content inside `AvoidSoftInputView`, if your form is rendered inside modal or you don't want to apply padding, or translation to React root view. + +### Props + +Extends `View` props + +| Prop | Type | Default value | +| -------------------------------- | ------------------------------------------------------------ | ------------------- | +| `avoidOffset` | number | 0 | +| `easing` | `easeIn` or `easeInOut` or `easeOut` or `linear` | `linear` | +| `enabled` | boolean | true | +| `hideAnimationDelay` | number | 0 | +| `hideAnimationDuration` | number | 220 | +| `onSoftInputAppliedOffsetChange` | function(e: \{ nativeEvent: \{ appliedOffset: number \}\}) | undefined | +| `onSoftInputHeightChange` | function(e: \{ nativeEvent: \{ softInputHeight: number \}\}) | undefined | +| `onSoftInputHidden` | function(e: \{ nativeEvent: \{ softInputHeight: number \}\}) | undefined | +| `onSoftInputShown` | function(e: \{ nativeEvent: \{ softInputHeight: number \}\}) | undefined | +| `showAnimationDelay` | number | 300/0 (iOS/Android) | +| `showAnimationDuration` | number | 660 | + +### Example + +```tsx +import { AvoidSoftInput } from "react-native-avoid-softinput"; + + + {/** Content that should be pushed above the keyboard */} +; +``` diff --git a/docs/versioned_docs/version-7.0.x/guides/ALTERNATIVES.mdx b/docs/versioned_docs/version-7.0.x/guides/ALTERNATIVES.mdx new file mode 100644 index 00000000..40f6e8fc --- /dev/null +++ b/docs/versioned_docs/version-7.0.x/guides/ALTERNATIVES.mdx @@ -0,0 +1,12 @@ +--- +id: alternatives +title: Alternatives +sidebar_label: Alternatives +keywords: [react-native-avoid-softinput, alternatives, react-native-keyboard-controller] +--- + +If, for whatever reason, the library does not satisfy your project's use case, you can check [react-native-keyboard-controller](https://github.com/kirillzyusko/react-native-keyboard-controller) + +`react-native-keyboard-controller` has an interesting approach of detecting keyboard appearance on native side and letting you apply detected height to Reanimated or vanilla Animated views. +It's written in Kotlin and Swift, it uses WindowInsetsCompat API on Android and it also supports Fabric & TurboModules from [version 1.2.0](https://kirillzyusko.github.io/react-native-keyboard-controller/blog/fabric). +Additionally, it has a interactive keyboard support from [version 1.5.0](https://kirillzyusko.github.io/react-native-keyboard-controller/blog/interactive-keyboard). diff --git a/docs/versioned_docs/version-7.0.x/guides/INSTALLATION.mdx b/docs/versioned_docs/version-7.0.x/guides/INSTALLATION.mdx new file mode 100644 index 00000000..1855d512 --- /dev/null +++ b/docs/versioned_docs/version-7.0.x/guides/INSTALLATION.mdx @@ -0,0 +1,194 @@ +--- +id: installation +title: Getting Started +sidebar_label: Getting Started +slug: /guides +keywords: [react-native-avoid-softinput, installation, setup, keyboard handling, troubleshooting] +--- + +import oneDoesNotSimplyKeyboard from '/img/OneDoesNotSimplyKeyboard.jpg'; + +## 1. Installation & Requirements + +This library follows the React Native releases support policy. +It is supporting **the latest version**, and **the two previous minor series**. +You may find it working correctly with some older React Native versions, but it'll be a "Use at your own risk" case. + +This library supports "New Architecture". + +Library supports Android & iOS, for out-of-tree platforms, `View` component is used as fallback. + +**Install library with your package manager:** + +```sh +yarn add react-native-avoid-softinput +``` + +or + +```sh +npm i --save react-native-avoid-softinput +``` + +**(iOS-only) Install pods:** + +```sh +npx pod-install +``` + +#### Expo + +- ✅ You can use this library with [Development Builds](https://docs.expo.dev/development/introduction/). No config plugin is required. +- ❌ This library can't be used in the "Expo Go" app because it [requires custom native code](https://docs.expo.dev/workflow/customizing/). + +## 2. App's setup + +### Setting Kotlin version + +The library uses Kotlin language to implement Android part. +Depending on the version of React Native or Expo SDK and 3rd party libraries that are used in your project, you might (or might not) need to explicitly specify the version of Kotlin used in the app. + +- **Expo project after [prebuild](https://docs.expo.dev/workflow/prebuild/) / bare RN project** + +Go to `/android/build.gradle` inside your android folder to specify your `kotlinVersion` + +```java +buildscript { + ext { + kotlinVersion = "1.8.0" // <-- add a version here for resolution, version can be newer depending on the React Native version used in the project + } +} +``` + +- **Expo project before [prebuild](https://docs.expo.dev/workflow/prebuild/) / Expo managed project** + +Use `expo-build-properties` plugin to modify `kotlinVersion` value + +```sh +npx expo install expo-build-properties +``` + +Add plugin inside of your `app.json` or `app.config.js` + +```json +{ + "expo": { + "plugins": [ + [ + "expo-build-properties", + { + "android": { + "kotlinVersion": "1.8.0" // <-- add a version here for resolution, version can be newer depending on the Expo SDK version used in the project + } + } + ] + ] + } +} +``` + + +### Keyboard handling on Android + +To make the keyboard handled **only** by `react-native-avoid-softinput` (and not by Android OS), you have to additionally make sure that default keyboard handling on Android is switched off (for iOS nothing to be done 🚀). + +#### Recommended setup + +To provide best possible support for Android 15, install [`react-native-edge-to-edge`](https://github.com/zoontek/react-native-edge-to-edge) and follow its setup after installation + +
+:warning: Legacy setup + +To setup keyboard handling on Android without `react-native-edge-to-edge`, do the following: + +##### Modify your Android's project `AndroidManifest.xml` + +- **Expo project after [prebuild](https://docs.expo.dev/workflow/prebuild/) / bare RN project** + +Go to `/android/app/src/main/AndroidManifest.xml` and search for [`android:windowSoftInputMode`](https://developer.android.com/guide/topics/manifest/activity-element#wsoft) attribute in the `` element. +To make `react-native-avoid-softinput` responsible for managing the available space when keyboard is popped up, that attribute needs to be set to `adjustResize` (in a new RN project it should be the default). + +```xml + + + + + + + + + + + + + + +``` + +- **Expo project before [prebuild](https://docs.expo.dev/workflow/prebuild/) / Expo managed project** + +Go to Expo's `app.json`/`app.config.js` and modify [`softwareKeyboardLayoutMode`](https://docs.expo.dev/versions/latest/config/app/#softwarekeyboardlayoutmode), so that it has `resize` value (in a new Expo project it should be the default). + +##### Use `AvoidSoftInput.setShouldMimicIOSBehavior(true)` later on in your app's code + +Remember to call `AvoidSoftInput.setShouldMimicIOSBehavior(true)` somewhere in the project's code (either in some root component, if you use the library globally or in specific screen, if you use the library only in some places). + +
+ +## 3. Define your use case + +
+ One does not simply handle the keyboard globally in the app with 99 different form layouts +
+ +There're many possible ways to implement a form with some text fields. Depending on the ideas of the UX team and the imagination of the client/product owner, +you may need to implement some complex layouts, that not only have to be accessible, but should behave in a consistent way when the interaction with text fields/keyboard takes place. + +Creating some generic components (like KeyboardAvoidingView) that can magically wrap _any_ form layout in your app **is an anti-pattern**. +Especially, when there are many variables that may change the expected behavior like: + +- whether Android OS default keyboard handling is switched on or off +- whether the form layout is in the scrollable container or not +- are elements like modals/bottomsheets used and are these implemented in the JS layer or use some native primitives +- how complex those inputs are, how many text fields there are +- should some elements in the form be sticky +- etc. + +Instead, you should think how the keyboard interaction with the app should look, what elements should be visible when the keyboard pops up. + +In a basic case where you have a fullscreen scrollable form without a need to have submit button always visible, you might use [`AvoidSoftInput`](./guides/usage-module) module which pushes the whole root view above the keyboard, or detects the nearest scrollable ancestor and tries to scroll to covered text field element. + +In a more advanced case where you have a form inside a modal layout with text field inside, you may use [`AvoidSoftInputView`](./guides/usage-view) component which pushes itself above the keyboard, or detects the nearest scrollable ancestor and tries to scroll to covered text field element. + +In other case you have a task to make a form footer with submit buttons always visible even when the keyboard slides in (effectively making that footer sticky). +Then, you have to think how to make that footer separated from the rest of the text fields that are probably in some scrollable container. +At the end, you'll end up in a need to manually apply padding to the footer container. +Luckily, you might try [`useSoftInputShown`](./api/hooks/use-soft-input-shown), [`useSoftInputHidden`](./api/hooks/use-soft-input-hidden) & [`useSoftInputHeightChanged`](./api/hooks/use-soft-input-height-changed) hooks to detect when the keyboard is displayed and the height value it has. + +The point is, before blindly using the library, you should define what is the expected behavior and which tools you should use to achieve it. +If you don't know, which APIs from the library you should use for your use case, check [the example app](https://github.com/mateusz1913/react-native-avoid-softinput/tree/main/packages/mobile) and try to play with available APIs. + +## Troubleshooting + +### Incorrect `kotlinVersion` + +For more context, check [GH issue 88](https://github.com/mateusz1913/react-native-avoid-softinput/issues/88). + +Sometimes when using this library you may find that your build fails due to incorrect `kotlinVersion` in your native project. +To catch this you **need** to follow [Setting Kotlin version](#setting-kotlin-version) section. + +### Doubled padding on Android when form has many inputs, works as expected on iOS + +For more context, check [GH issue 155](https://github.com/mateusz1913/react-native-avoid-softinput/issues/155). + +The problem may appear if you didn't follow [Keyboard handling on Android](#keyboard-handling-on-android) section and you have e.g. [`adjustPan` behavior](https://developer.android.com/guide/topics/manifest/activity-element#wsoft) set for your app. + +To fix it, follow the section to disable default keyboard handling on Android. + +If, for some reason, you need to keep `adjustPan` behavior for other parts of the app (where library does not need to handle the keyboard), you might check [`AvoidSoftInput.setAdjust(Pan|Resize|Nothing|Unspecified)`](./api/module/set-adjust-pan) functions. diff --git a/docs/versioned_docs/version-7.0.x/guides/JEST_MOCK_USAGE.mdx b/docs/versioned_docs/version-7.0.x/guides/JEST_MOCK_USAGE.mdx new file mode 100644 index 00000000..1e465520 --- /dev/null +++ b/docs/versioned_docs/version-7.0.x/guides/JEST_MOCK_USAGE.mdx @@ -0,0 +1,44 @@ +--- +id: jest-mock-usage +title: Jest mock usage +sidebar_label: Jest mock usage +keywords: [react-native-avoid-softinput, Jest, mock, testing] +--- + +To make testing with Jest easier, library provides mocked implementation that can be integrated in two ways: + +### Using mock in `__mocks__` directory + +1. Create `__mocks__/react-native-avoid-softinput` file. +2. Inside created file paste following lines: + +```js +const mock = require('react-native-avoid-softinput/jest/mock'); + +/** + * If needed, override mock like so: + * + * module.exports = Object.assign(mock, { useSoftInputState: jest.fn(() => ({ isSoftInputShown: true, softInputHeight: 300 })) }); + */ + +module.exports = mock; +``` + +### Using mock in Jest setup file + +1. Create Jest setup file, unless there is already one, and link it in [jest config](https://jestjs.io/docs/configuration#setupfiles-array) +2. Inside Jest setup file add following lines: + +```js +jest.mock('react-native-avoid-softinput', () => { + const mock = require('react-native-avoid-softinput/jest/mock'); + + /** + * If needed, override mock like so: + * + * return Object.assign(mock, { useSoftInputState: jest.fn(() => ({ isSoftInputShown: true, softInputHeight: 300 })) }); + */ + + return mock; +}); +``` diff --git a/docs/versioned_docs/version-7.0.x/guides/MIGRATION_FROM_V6_TO_V7.mdx b/docs/versioned_docs/version-7.0.x/guides/MIGRATION_FROM_V6_TO_V7.mdx new file mode 100644 index 00000000..13c85c74 --- /dev/null +++ b/docs/versioned_docs/version-7.0.x/guides/MIGRATION_FROM_V6_TO_V7.mdx @@ -0,0 +1,19 @@ +--- +id: migration_from_v6_to_v7 +title: Migration from v6 to v7 +sidebar_label: Migration from v6 to v7 +keywords: [react-native-avoid-softinput, migration] +--- + +## Migrate to [`react-native-edge-to-edge`](https://github.com/zoontek/react-native-edge-to-edge) to provide best support for Android 15 "edge to edge" mode + +Since v7, the library supports detection of `react-native-edge-to-edge`. +Follow the [installation page](./INSTALLATION.mdx) for the recommended setup for keyboard handling on Android. +Existing `AvoidSoftInput.setShouldMimicIOSBehavior` function is considered deprecated from v7 and will be removed in future major versions. + +```diff +useEffect(() => { +- AvoidSoftInput.setShouldMimicIOSBehavior(true); // <---- Tell Android that library will handle keyboard insets manually to match iOS behavior + AvoidSoftInput.setEnabled(true); // <---- Enable module +}, []); +``` diff --git a/docs/versioned_docs/version-7.0.x/guides/USAGE_MODULE.mdx b/docs/versioned_docs/version-7.0.x/guides/USAGE_MODULE.mdx new file mode 100644 index 00000000..04384039 --- /dev/null +++ b/docs/versioned_docs/version-7.0.x/guides/USAGE_MODULE.mdx @@ -0,0 +1,48 @@ +--- +id: usage-module +title: Usage - module +sidebar_label: Usage - module +keywords: [react-native-avoid-softinput, module, usage] +--- + +The preferrable usage of the module is to enable it where it's actually needed. + +Depending on the navigation setup you have, check the navigation's library documentation for correct way to run some actions when the screen gains/loses focus. + +The following example assumes `react-navigation` is used as a navigation: + +```ts +import * as React from "react"; +import { Button, ScrollView, TextInput, View } from "react-native"; +import { AvoidSoftInput } from "react-native-avoid-softinput"; +import { useFocusEffect } from "@react-navigation/native"; + +export const FormExample: React.FC = () => { +// highlight-start + const onFocusEffect = React.useCallback(() => { + // This should be run when screen gains focus - enable the module where it's needed + AvoidSoftInput.setEnabled(true); + return () => { + // This should be run when screen loses focus - disable the module where it's not needed, to make a cleanup + AvoidSoftInput.setEnabled(false); + }; + }, []); + + useFocusEffect(onFocusEffect); // register callback to focus events +// highlight-end + + return + + + + + + +