[RNKC-078] - versioned docs (#86)

## 📜 Description

In light of the next upcoming release (`1.4.0`) we need to have
versioned docs, since new release will bring new API methods.

## 💡 Motivation and Context

New `1.4.0` will introduce new hook, so we will need to explicitly show,
that older version doesn't have this API.

To support it we need to have a support for versioned docs. In this PR
I'm adding basic support for it.

## 📢 Changelog

### Docs
- cut current version of docs as `1.0.0`;
- added dropdown for version selection;

## 🤔 How Has This Been Tested?

Tested locally.

## 📸 Screenshots (if appropriate):


## 📝 Checklist

- [x] CI successfully passed

docs/docusaurus.config.js

@@ -39,6 +39,11 @@ const config = {
           // Remove this to remove the "edit this page" links.
           editUrl:
             'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
+          versions: {
+            '1.0.0': {
+              label: '1.0.0-1.3.0',
+            },
+          },
         },
         blog: {
           showReadingTime: true,
@@ -80,6 +85,11 @@ const config = {
             position: 'left',
           },
           { to: '/blog', label: 'Blog', position: 'left' },
+          {
+            type: 'docsVersionDropdown',
+            position: 'left',
+            dropdownActiveClassDisabled: true,
+          },
           {
             href: 'https://github.com/kirillzyusko/react-native-keyboard-controller/tree/main/example',
             label: 'Example App',

docs/versioned_docs/version-1.0.0/api/_category_.json

@@ -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"
+  }
+}

docs/versioned_docs/version-1.0.0/api/hooks/_category_.json

@@ -0,0 +1,3 @@
+{
+  "label": "Hooks"
+}

docs/versioned_docs/version-1.0.0/api/hooks/use-keyboard-animation.md

@@ -0,0 +1,47 @@
+# useKeyboardAnimation
+
+`useKeyboardAnimation` is a hook which gives access to two animated values:
+- `height` - value which changes between **0** and **keyboardHeight**;
+- `progress` - value which changes between **0** (keyboard closed) and **1** (keyboard opened).
+
+## Example
+
+```tsx
+import { useKeyboardAnimation } from "react-native-keyboard-controller";
+
+const { height, progress } = useKeyboardAnimation();
+```
+
+Also have a look on [example](https://github.com/kirillzyusko/react-native-keyboard-controller/tree/main/example) app for more comprehensive usage.
+
+## Using with class component
+
+```tsx
+import {
+  KeyboardController,
+  KeyboardContext,
+  AndroidSoftInputModes,
+} from "react-native-keyboard-controller";
+
+class KeyboardAnimation extends React.PureComponent {
+  // 1. use context value
+  static contextType = KeyboardContext;
+
+  componentDidMount() {
+    // 2. set input mode for android to `adjustResize`
+    // (can be omitted if you already have `adjustResize` in `AndroidManifest.xml`)
+    KeyboardController.setInputMode(AndroidSoftInputModes.SOFT_INPUT_ADJUST_RESIZE);
+  }
+
+  componentWillUnmount() {
+    // 2. return to default input mode (for Android)
+    // in order not to break other part of your app
+    KeyboardController.setDefaultMode();
+  }
+
+  render() {
+    // 3. consume animated values 😊
+    const { animated } = this.context;
+  }
+}
+```

docs/versioned_docs/version-1.0.0/api/hooks/use-reanimated-keyboard-animation.md

@@ -0,0 +1,47 @@
+# useReanimatedKeyboardAnimation
+
+`useReanimatedKeyboardAnimation` is a hook which gives access to two reanimated values:
+- `height` - value which changes between **0** and **keyboardHeight**;
+- `progress` - value which changes between **0** (keyboard closed) and **1** (keyboard opened).
+
+## Example
+
+```tsx
+import { useReanimatedKeyboardAnimation } from "react-native-keyboard-controller";
+
+const { height, progress } = useReanimatedKeyboardAnimation();
+```
+
+Also have a look on [example](https://github.com/kirillzyusko/react-native-keyboard-controller/tree/main/example) app for more comprehensive usage.
+
+## Using with class component
+
+```tsx
+import {
+  KeyboardController,
+  KeyboardContext,
+  AndroidSoftInputModes,
+} from "react-native-keyboard-controller";
+
+class KeyboardAnimation extends React.PureComponent {
+  // 1. use context value
+  static contextType = KeyboardContext;
+
+  componentDidMount() {
+    // 2. set input mode for android to `adjustResize`
+    // (can be omitted if you already have `adjustResize` in `AndroidManifest.xml`)
+    KeyboardController.setInputMode(AndroidSoftInputModes.SOFT_INPUT_ADJUST_RESIZE);
+  }
+
+  componentWillUnmount() {
+    // 2. return to default input mode (for Android)
+    // in order not to break other part of your app
+    KeyboardController.setDefaultMode();
+  }
+
+  render() {
+    // 3. consume reanimated values 😊
+    const { reanimated } = this.context;
+  }
+}
+```

docs/versioned_docs/version-1.0.0/api/keyboard-controller-view.md

@@ -0,0 +1,13 @@
+# KeyboardControllerView
+
+A plain react-native `View` with some additional methods and props. Used internally in [KeyboardProvider](./keyboard-provider.md)
+
+## Props
+
+#### `onKeyboardMove`
+
+A callback function which is fired every time, when keyboard changes its position on the screen.
+
+#### `statusBarTranslucent`
+
+A boolean prop to indicate whether `StatusBar` should be translucent on `Android` or not.

docs/versioned_docs/version-1.0.0/api/keyboard-controller.md

@@ -0,0 +1,24 @@
+# KeyboardController
+
+`KeyboardController` is an object which has two functions:
+- `setInputMode` - used to change `windowSoftInputMode` in runtime;
+- `setDefaultMode` - used to restore default `windowSoftInputMode` (which is declared in `AndroidManifest.xml`);
+
+## Example
+
+```ts
+import {
+  KeyboardController,
+  AndroidSoftInputModes,
+} from "react-native-keyboard-controller";
+
+export const useResizeMode = () => {
+  useEffect(() => {
+    KeyboardController.setInputMode(
+      AndroidSoftInputModes.SOFT_INPUT_ADJUST_RESIZE
+    );
+
+    return () => KeyboardController.setDefaultMode();
+  }, []);
+};
+```

docs/versioned_docs/version-1.0.0/api/keyboard-events.md

@@ -0,0 +1,26 @@
+# KeyboardEvents
+
+This library exposes 4 events which are available on all platforms:
+
+- keyboardWillShow
+- keyboardWillHide
+- keyboardDidShow
+- keyboardDidHide
+
+## Example
+
+```ts
+import { KeyboardEvents } from "react-native-keyboard-controller";
+
+useEffect(() => {
+  const show = KeyboardEvents.addListener("keyboardWillShow", (e) => {
+    // place your code here
+  });
+
+  return () => {
+    show.remove();
+  };
+}, []);
+```
+
+Also have a look on [example](https://github.com/kirillzyusko/react-native-keyboard-controller/tree/main/example) app for more comprehensive usage.

docs/versioned_docs/version-1.0.0/api/keyboard-provider.md

@@ -0,0 +1,27 @@
+# KeyboardProvider
+
+`KeyboardProvider` should wrap your app. Underhood it works with `KeyboardControllerView` to receive events during keyboard movements, maps these events to `Animated`/`Reanimated` values and store them in `context`.
+
+## Props
+
+#### `statusBarTranslucent`
+
+A boolean prop to indicate whether `StatusBar` should be translucent on `Android` or not.
+
+:::caution Important defaults
+By default this library stretches to full screen (`edge-to-edge` mode) and status bar becomes translucent. But the library tries to use standard RN app behavior and automatically applies padding from top to look like a standard RN app. If you use `translucent` prop for `StatusBar` component - it will not work anymore. You'll need to specify it on provider level. For more info [see](https://github.com/kirillzyusko/react-native-keyboard-controller/pull/30) this PR.
+:::
+
+## Example
+
+```tsx
+import { KeyboardProvider } from "react-native-keyboard-controller";
+
+const App = () => {
+  return (
+    <KeyboardProvider>
+      {/* other components in your tree */}
+    </KeyboardProvider>
+  );
+}
+```

docs/versioned_docs/version-1.0.0/guides/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Guides",
+  "position": 2,
+  "link": {
+    "type": "generated-index",
+    "description": "Most useful topics to start quickly."
+  }
+}

docs/versioned_docs/version-1.0.0/guides/building-own-hook.md

@@ -0,0 +1,37 @@
+---
+sidebar_position: 2
+---
+
+# Building own hook
+
+Default hooks may not perfectly fit in your app, because it changes/restores `softInputMode` on mount/unmount of the component where it's used. Though in deep stacks sometimes it may be important to have different `softInputMode` per screen, but by default `react-navigation` keeps previous screens mounted, so if you are using default `useKeyboardAnimation` hook, then all following screens will have `softInputMode=adjustResize`.
+
+To prevent such behavior you can write own hook based on primitives from this library. The implementation may look like:
+
+```ts
+import { useContext, useCallback } from "react";
+import { useFocusEffect } from "@react-navigation/native";
+import {
+  KeyboardContext,
+  KeyboardController,
+  AndroidSoftInputModes
+} from "react-native-keyboard-controller";
+
+function useKeyboardAnimation() {
+  useFocusEffect(
+    useCallback(() => {
+      KeyboardController.setInputMode(
+        AndroidSoftInputModes.SOFT_INPUT_ADJUST_RESIZE
+      );
+
+      return () => KeyboardController.setDefaultMode();
+    }, [])
+  );
+
+  const context = useContext(KeyboardContext);
+
+  return context.animated;
+}
+```
+
+In this case when screen becomes invisible hook will restore default `softInputMode`, and `softInputMode` will be set to `adjustResize` only on the screen where it's used.

docs/versioned_docs/version-1.0.0/guides/compatibility.md

@@ -0,0 +1,32 @@
+---
+sidebar_position: 3
+---
+
+# Compatibility
+
+## React Native
+
+Starting from `1.2.0` this library adds support for a new architecture called `Fabric`. Since a new architecture is still in adoption stage and it changes some APIs over time - it's highly recommended to use versions which are compatible and were intensively tested against specific `react-native` versions.
+
+Below you can find a table with supported versions:
+
+|library version|react-native version|
+|-------|--------------------|
+|1.3.0+ |	0.70.0+            |
+|1.2.0+ |	0.69.0+            |
+
+:::info
+
+For `Paper` (old) architecture there is no any restrictions. If you found an incompatibility - 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 to the project 🙏
+
+:::
+
+## Third-party libraries compatibility
+
+Since this library uses `WindowInsetsCompat` API on Android it may conflict with other libraries if they are using deprecated API (if they are changing `window` flags directly).
+
+For example `react-native-screens` [were](https://github.com/software-mansion/react-native-screens/pull/1451) using old API, so if you are using `StatusBar` management from `react-native-screens` you'll need to use at least `3.14+` version. Otherwise it will **break** keyboard animations.
+
+`StatusBar` component from `react-native` is also using deprecated API. In order to allow better compatibility - `react-native-keyboard-controller` [monkey-patches](https://github.com/kirillzyusko/react-native-keyboard-controller/pull/30) this component (hopefully soon they will change an approach and will rewrite this component to new API).
+
+If you know other 3rd party libraries that may be using deprecated API, please open an [issue](https://github.com/kirillzyusko/react-native-keyboard-controller/issues/new?assignees=kirillzyusko&labels=bug&template=bug_report.md&title=) and we'll try to fix it.

docs/versioned_docs/version-1.0.0/guides/first-animation.md

@@ -0,0 +1,82 @@
+---
+sidebar_position: 1
+---
+
+# First animation
+
+To build your first animation you will need to use two hooks: [useKeyboardAnimation](../api/hooks/use-keyboard-animation.md) or [useReanimatedKeyboardAnimation](../api/hooks/use-reanimated-keyboard-animation.md).
+
+Both of them return an object with two properties: `progress` and `height` (depends on the hook used, values will be `Animated.Value` or `Reanimated.SharedValue`).
+
+:::info
+`useKeyboardAnimation` returns Animated values with enabled **Native Driver** (`useNativeDriver: true`). Thus some properties can not be animated, such as `height`, `backgroundColor`, etc.
+:::
+
+:::caution
+`useReanimatedKeyboardAnimation` works only with `ShareValues`, i.e. it is not compatible with Reanimated v1 API.
+:::
+
+## Example
+
+To see how to use these hooks let's consider example below (for more comprehensive usage you may find an [example](https://github.com/kirillzyusko/react-native-keyboard-controller/tree/main/example) app useful):
+
+```tsx
+import React from 'react';
+import { Animated, StyleSheet, TextInput, View } from 'react-native';
+import { useKeyboardAnimation } from 'react-native-keyboard-controller';
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'flex-end',
+  },
+  box: {
+    width: 60,
+    height: 60,
+    marginVertical: 20,
+  },
+  row: {
+    flexDirection: 'row',
+  },
+});
+
+export default function KeyboardAnimation() {
+  // 1. we need to use hook to get an access to animated values
+  const { height, progress } = useKeyboardAnimation();
+
+  const scale = progress.interpolate({
+    inputRange: [0, 1],
+    outputRange: [1, 2],
+  });
+
+  return (
+    <View style={styles.container}>
+      <View style={styles.row}>
+        <Animated.View
+          style={{
+            width: 50,
+            height: 50,
+            backgroundColor: '#17fc03',
+            borderRadius: 15,
+            // 2. we can apply any transformations we want
+            transform: [{ translateY: height }, { scale }],
+          }}
+        />
+      </View>
+      <TextInput
+        style={{
+          width: '100%',
+          marginTop: 50,
+          height: 50,
+          backgroundColor: 'yellow',
+        }}
+      />
+    </View>
+  );
+}
+```
+
+:::info
+If you are going to use these Animated values in class components (i.e. without hooks) - you can easily [do](../api/hooks/use-keyboard-animation.md) it. Check out [source](https://github.com/kirillzyusko/react-native-keyboard-controller/blob/cf27eb00877db34b860a04cf52a026110e44b4b3/src/animated.tsx#L46-L51) code - this hook simply changes `softInputMode` and consumes `Context`. Also you may read [architecture](../recipes/architecture.md) deep dive to understand more about how this library works.
+:::