Skip to content

Commit

Permalink
docs: checkout docs for 1.12.0 (#441)
Browse files Browse the repository at this point in the history 
## 📜 Description

Added `1.12.0` version in dropdown.

## 💡 Motivation and Context

We've added new functionality, changed some existing etc. so we need to
reflect it in documentation.

## 📢 Changelog

<!-- High level overview of important changes -->
<!-- For example: fixed status bar manipulation; added new types
declarations; -->
<!-- If your changes don't affect one of platform/language below - then
remove this platform/language -->

### Docs

- added new version in dropdown;
- created versioned docs (1.12.0);

## 🤔 How Has This Been Tested?

Tested manually on localhost:3000, preview and argos.

## 📸 Screenshots (if appropriate):

<img width="423" alt="image"
src="https://github.com/kirillzyusko/react-native-keyboard-controller/assets/22820318/08929d08-06b7-4226-8ca9-c59c50847a2e">

## 📝 Checklist

- [x] CI successfully passed
- [x] I added new mocks and corresponding unit-tests if library API was
changed
  • Loading branch information
@kirillzyusko
kirillzyusko committed May 11, 2024
1 parent 2060506 commit 4cabd4d
Show file tree
Hide file tree
Showing 40 changed files with 2,175 additions and 0 deletions.
3 changes: 3 additions & 0 deletions docs/docusaurus.config.js
View file
Expand Up @@ -69,6 +69,9 @@ const config = {
"1.11.0": {
label: "1.11.0",
},
"1.12.0": {
label: "1.12.0",
},
},
},
blog: {
Expand Down
8 changes: 8 additions & 0 deletions docs/versioned_docs/version-1.12.0/api/_category_.json
View file
@@ -0,0 +1,8 @@
{
"label": "API Reference",
"position": 4,
"link": {
"type": "generated-index",
"description": "API reference containing information about all public methods and their signatures"
}
}
4 changes: 4 additions & 0 deletions docs/versioned_docs/version-1.12.0/api/components/_category_.json
View file
@@ -0,0 +1,4 @@
{
"label": "📚 Components",
"position": 2
}
131 changes: 131 additions & 0 deletions docs/versioned_docs/version-1.12.0/api/components/keyboard-avoiding-view.mdx
View file
@@ -0,0 +1,131 @@
---
keywords:
[
react-native-keyboard-controller,
KeyboardAvoidingView,
keyboard avoiding view,
avoid keyboard,
android,
]
---

# KeyboardAvoidingView

This component will automatically adjust its height, position, or bottom padding based on the keyboard height to remain visible while the virtual keyboard is displayed.

## Why another `KeyboardAvoidingView` is needed?

This new `KeyboardAvoidingView` maintains the familiar React Native [API](https://reactnative.dev/docs/keyboardavoidingview) but ensures consistent behavior and animations on both `iOS` and `Android` platforms. Unlike the existing solution, which primarily caters to `iOS`, this component eliminates platform discrepancies, providing a unified user experience. By reproducing the same animations and behaviors on both platforms, it simplifies cross-platform development, meets user expectations for consistency, and enhances code maintainability. Ultimately, it addresses the need for a reliable and uniform keyboard interaction solution across different devices.

Below is a visual difference between the implementations (the animation is _**4x**_ times slower for better visual perception).

import KeyboardAvoidingViewComparison from "@site/src/components/KeyboardAvoidingViewComparison";

<KeyboardAvoidingViewComparison />

:::info Found a bug? Help the project and report it!

If you found any bugs or inconsistent behavior comparing to `react-native` implementation - don't hesitate to open an [issue](https://github.com/kirillzyusko/react-native-keyboard-controller/issues/new?assignees=kirillzyusko&labels=bug&template=bug_report.md&title=). It will help the project 🙏

Also if there is any well-known problems in original `react-native` implementation which can not be fixed for a long time and they are present in this implementation as well - also feel free to submit an [issue](https://github.com/kirillzyusko/react-native-keyboard-controller/issues/new?assignees=kirillzyusko&labels=bug&template=bug_report.md&title=). Let's make this world better together 😎

:::

## Example

```tsx
import React from "react";
import {
Text,
TextInput,
TouchableOpacity,
View,
StyleSheet,
} from "react-native";
import { KeyboardAvoidingView } from "react-native-keyboard-controller";

export default function KeyboardAvoidingViewExample() {
return (
<KeyboardAvoidingView
behavior={"padding"}
contentContainerStyle={styles.container}
keyboardVerticalOffset={100}
style={styles.content}
>
<View style={styles.inner}>
<Text style={styles.heading}>Header</Text>
<View>
<TextInput placeholder="Username" style={styles.textInput} />
<TextInput placeholder="Password" style={styles.textInput} />
</View>
<TouchableOpacity style={styles.button}>
<Text style={styles.text}>Submit</Text>
</TouchableOpacity>
</View>
</KeyboardAvoidingView>
);
}

const styles = StyleSheet.create({
container: {
flex: 1,
},
content: {
flex: 1,
maxHeight: 600,
},
heading: {
fontSize: 36,
marginBottom: 48,
fontWeight: "600",
},
inner: {
padding: 24,
flex: 1,
justifyContent: "space-between",
},
textInput: {
height: 45,
borderColor: "#000000",
borderWidth: 1,
borderRadius: 10,
marginBottom: 36,
paddingLeft: 10,
},
button: {
marginTop: 12,
height: 45,
borderRadius: 10,
backgroundColor: "rgb(40, 64, 147)",
justifyContent: "center",
alignItems: "center",
},
text: {
fontWeight: "500",
fontSize: 16,
color: "white",
},
});
```

## Props

### `behavior`

Specify how to react to the presence of the keyboard. Could be one value of:

- `position`
- `padding`
- `height`

### `contentContainerStyle`

The style of the content container (View) when behavior is `position`.

### `enabled`

A boolean prop indicating whether `KeyboardAvoidingView` is enabled or disabled. Default is `true`.

### `keyboardVerticalOffset`

This is the distance between the top of the user screen and the react native view, may be non-zero in some use cases. Default is `0`.
222 changes: 222 additions & 0 deletions docs/versioned_docs/version-1.12.0/api/components/keyboard-aware-scroll-view.mdx
View file
@@ -0,0 +1,222 @@
---
keywords:
[
react-native-keyboard-controller,
KeyboardAwareScrollView,
keyboard aware view,
aware scroll view,
]
---

# KeyboardAwareScrollView

import Lottie from "lottie-react";
import lottie from "@site/src/components/HomepageFeatures/text-inputs.lottie.json";

<div style={{ display: "flex", justifyContent: "center", marginBottom: 20 }}>
<Lottie
className="lottie"
animationData={lottie}
style={{ width: 400, height: 400 }}
loop
/>
</div>

`ScrollView` that effortlessly handles keyboard appearance, automatically scrolls to focused `TextInput` and provides a native-like performance.

## Comparison

Current `react-native` ecosystem has a plenty of solutions that solves the problem of focused inputs being covered by keyboard. Each of them has its own advantages and disadvantages.

Below is a table with the most important functions and their support in various implementations:

| | [react-native-avoid-soft-input](https://mateusz1913.github.io/react-native-avoid-softinput/) | [react-native-keyboard-aware-scroll-view](https://github.com/APSL/react-native-keyboard-aware-scroll-view) | [react-native-keyboard-manager](https://github.com/douglasjunior/react-native-keyboard-manager) | [react-native-keyboard-controller](./keyboard-aware-scroll-view.mdx) |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| Respects keyboard animation | 🟠 <sup><small>1</small></sup> | ❌ | ✅ | ✅ |
| JS implementation | ❌ | ✅ | ❌ | 🟠 <sup><small>2</small></sup> |
| Reacts on focused input layout changes | ❌ | ❌ | 🟠 <sup><small>3</small></sup> | ✅ |
| Reacts on focus changes | ✅ | ✅ | ✅ | ✅ |
| Auto-scroll when user is typing and input in non visible area | ❌ | ❌ | 🟠 <sup><small>3</small></sup> | ✅ |
| Android support | ✅ | ✅ | ❌ | ✅ |
| Maintained | ✅ | ❌ | ✅ | ✅ |
| Support Fabric (new) architecture | ✅ | 🟠 <sup><small>4</small></sup> | ❌ | ✅ |

> <sup>1</sup> <b>only</b> on <b>iOS</b>
<!-- prettier-ignore-start -->
> <sup>2</sup> <code>KeyboardAwareScrollView</code> is implemented in JS, but some hooks
> (<code>useKeyboardHandler</code>/<code>useReanimatedFocusedInput</code>/<code>useFocusedInputHandler</code>)
> exposed from native code
<!-- prettier-ignore-end -->
<!-- prettier-ignore-start -->
> <sup>3</sup> achievable with
> <code>KeyboardManager.reloadLayoutIfNeeded()</code>
> usage in appropriate <code>TextInput</code> callbacks
> (<code>onLayout</code>/<code>onChangeText</code>)
<!-- prettier-ignore-end -->
> <sup>4</sup> since it's JS based solution it supports new architecture, but it
> uses <b>deprecated</b> API.
## Props

### ScrollView Props

Inherits [ScrollView Props](https://reactnative.dev/docs/scrollview#props).

### `bottomOffset`

The distance between keyboard and focused `TextInput` when keyboard is shown. Default is `0`.

### `disableScrollOnKeyboardHide`

Prevents automatic scrolling of the `ScrollView` when the keyboard gets hidden, maintaining the current screen position. Default is `false`.

### `enabled`

A boolean prop indicating whether `KeyboardAwareScrollView` is enabled or disabled. Default is `true`.

## `FlatList`/`FlashList`/`SectionList` integrations

Unlike original [react-native-keyboard-aware-scroll-view](https://github.com/APSL/react-native-keyboard-aware-scroll-view) package I'm not exporting `KeyboardAwareFlatList`, `KeyboardAwareSectionList` and other components.

If you want to integrate it with your custom virtualization list, you can pass `renderScrollComponent` prop like:

```tsx
import { FlatList } from "react-native";
import { KeyboardAwareScrollView } from "react-native-keyboard-controller";

<FlatList
renderScrollComponent={(props) => <KeyboardAwareScrollView {...props} />}
/>;

// or

import { FlashList } from "@shopify/flash-list";

<FlashList
renderScrollComponent={(props) => <KeyboardAwareScrollView {...props} />}
/>;
```

<details>
<summary>Click to see a full code example with integration</summary>

```tsx
import React from "react";
import { View, FlatList, TextInput } from "react-native";
import { KeyboardAwareScrollView } from "react-native-keyboard-controller";

const List = () => {
return (
<View style={{ flex: 1 }}>
<FlatList
data={new Array(10).fill(0).map((_, i) => i)}
keyExtractor={(data) => String(data)}
renderItem={() => {
return (
<View
style={{
width: "100%",
height: 250,
backgroundColor: "#00000066",
justifyContent: "center",
}}
>
<TextInput
style={{
height: 40,
width: "100%",
borderColor: "black",
borderWidth: 2,
}}
/>
</View>
);
}}
renderScrollComponent={(props) => (
<KeyboardAwareScrollView {...props} />
)}
ItemSeparatorComponent={() => <View style={{ height: 5 }} />}
showsVerticalScrollIndicator={false}
/>
</View>
);
};

export default List;
```

</details>

## Example

```tsx
import React from "react";
import {
StyleSheet,
TextInputProps,
TextInput as TextInputRN,
} from "react-native";
import { KeyboardAwareScrollView } from "react-native-keyboard-controller";

const TextInput = (props: TextInputProps) => {
return (
<TextInputRN
placeholderTextColor="#6c6c6c"
style={styles.textInput}
multiline
numberOfLines={2}
testID={props.placeholder}
{...props}
placeholder={`${props.placeholder} (${
props.keyboardType === "default" ? "text" : "numeric"
})`}
/>
);
};

export default function AwareScrollView() {
return (
<KeyboardAwareScrollView
bottomOffset={50}
style={styles.container}
contentContainerStyle={styles.content}
>
{new Array(10).fill(0).map((_, i) => (
<TextInput
key={i}
placeholder={`TextInput#${i}`}
keyboardType={i % 2 === 0 ? "numeric" : "default"}
/>
))}
</KeyboardAwareScrollView>
);
}

const styles = StyleSheet.create({
container: {
paddingHorizontal: 16,
},
content: {
paddingTop: 50,
},
textInput: {
width: "100%",
minHeight: 50,
maxHeight: 200,
marginBottom: 50,
borderColor: "black",
borderWidth: 2,
marginRight: 160,
borderRadius: 10,
color: "black",
paddingHorizontal: 12,
},
});
```

## Known issues

- [react-native-reanimated#5567](https://github.com/software-mansion/react-native-reanimated/issues/5567): Resizing content inside `ScrollView` prevents multiline `TextInput` from growing in Fabric

0 comments on commit 4cabd4d

Please sign in to comment.