Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

✨ Publish New Docs ✨ #4904

Merged
merged 16 commits into from
Aug 9, 2023
Merged
Show file tree
Hide file tree
Changes from 8 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
38 changes: 15 additions & 23 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -1,33 +1,25 @@
# Website
# Reanimated Documentation

This website is built using [Docusaurus 2](https://v2.docusaurus.io/), a modern static website generator.
👉 [https://docs.swmansion.com/react-native-reanimated/](https://docs.swmansion.com/react-native-reanimated/)

## Installation
## What's in the docs

```console
yarn install
```
The docs come with a [Fundamentals](https://reanimated-beta-docs.swmansion.com/docs/fundamentals/getting-started) section which step-by-step introduction into the world of Reanimated.
kacperkapusciak marked this conversation as resolved.
Show resolved Hide resolved

## Local Development
All sections are sprinkled with interactive examples, playground and code snippets designed to be easily copyable to be run in your projects.
kacperkapusciak marked this conversation as resolved.
Show resolved Hide resolved

```console
yarn start
```
## How can I help?

This command starts a local development server and open up a browser window. Most changes are reflected live without having to restart the server.
Glad you asked! You can help the project in many ways e.g. by:

## Build
- _Reading and sharing_ the docs with friends and co-workers
- _Sending feedback_ in the discussion or issues on GitHub
- _Submitting PRs_ with fixes and improvements to the docs content and styles

```console
yarn build
```
All feedback in all forms ranging from general to tiny fixes is highly appreciated!

This command generates static content into the `build` directory and can be served using any static contents hosting service.
## Meet the docs team

## Deployment

```console
GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
```

If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
- [Aleksandra Niewiadomska-Ptak](https://dribbble.com/aleksandranie): design
- [Tymoteusz Boba](https://twitter.com/IceMeltt): site development
- [Kacper Kapuściak](https://twitter.com/kacperkapusciak): content, interactive examples
7 changes: 2 additions & 5 deletions docs/babel.config.js
Original file line number Diff line number Diff line change
@@ -1,7 +1,4 @@
module.exports = {
presets: [
require.resolve('@docusaurus/core/lib/babel/preset'),
['@babel/preset-env', { targets: { node: 'current' } }],
'@babel/preset-typescript',
],
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
plugins: ['react-native-reanimated/plugin'],
};
7 changes: 7 additions & 0 deletions docs/docs/advanced/_category_.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"label": "Advanced APIs",
"position": 9,
"link": {
"type": "generated-index"
}
}
Original file line number Diff line number Diff line change
@@ -1,16 +1,18 @@
---
id: dispatchCommand
title: dispatchCommand
sidebar_label: dispatchCommand
---
# dispatchCommand

:::info
This page was ported from an old version of the documentation.

As we're rewriting the documentation some of the pages might be a little outdated.
:::

Allows to dispatch command on a native component synchronously from the UI thread.

### Arguments

#### `animatedRef`

The product of [`useAnimatedRef`](../hooks/useAnimatedRef) which is Reanimated's extension of a standard React ref (delivers the view tag on the UI thread).
The product of [`useAnimatedRef`](/docs/core/useAnimatedRef) which is Reanimated's extension of a standard React ref (delivers the view tag on the UI thread).

#### `commandName` [String]

Expand Down
139 changes: 139 additions & 0 deletions docs/docs/advanced/measure.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,139 @@
---
sidebar_position: 1
---

# measure

`measure` lets you synchronously get the dimensions and the position of a view on the screen on the [UI thread](/docs/fundamentals/glossary#ui-thread).
kacperkapusciak marked this conversation as resolved.
Show resolved Hide resolved

## Reference

```jsx
import { measure } from 'react-native-reanimated';

function App() {
const animatedRef = useAnimatedRef();

const handlePress = () => {
runOnUI(() => {
// highlight-next-line
const measurement = measure(animatedRef);
if (measurement === null) {
return;
}
// ...
})();
};

return <Animated.View ref={animatedRef} />;
}
```

<details>
<summary>Type definitions</summary>

```typescript
interface MeasuredDimensions {
x: number;
y: number;
width: number;
height: number;
pageX: number;
pageY: number;
}

function measure<T extends Component>(
animatedRef: AnimatedRef<T>
): MeasuredDimensions | null;
```

</details>

### Arguments

#### `animatedRef`

An [animated ref](/docs/core/useAnimatedRef#returns) connected to the component you'd want to get the measurements from. The animated ref has to be passed either to an [Animated component](/docs/fundamentals/glossary#animated-component) or a React Native built-in component.

### Returns

`measure` returns an object containing these fields:

- `x` a number representing X coordinate relative to the parent component,
- `y` a number representing Y coordinate relative to the parent component,
- `width` a number representing the width of the component,
- `height` a number representing the height of the component,
- `pageX` a number representing X coordinate relative to the screen,
- `pageY` a number representing Y coordinate relative to the screen,

or returns `null` when the measurement couldn't be performed.

## Example

import MeasureBasic from '@site/src/examples/MeasureBasic';
import MeasureBasicSrc from '!!raw-loader!@site/src/examples/MeasureBasic';

<InteractiveExample src={MeasureBasicSrc} component={<MeasureBasic />} />

## Remarks

- `measure` has an implementation only on the [UI thread](/docs/fundamentals/glossary#ui-thread). When using `measure` inside [event handlers](https://react.dev/learn/responding-to-events#adding-event-handlers) it has to be wrapped with [`runOnUI`](/docs/threading/runOnUI) function.
kacperkapusciak marked this conversation as resolved.
Show resolved Hide resolved

- The `useAnimatedStyle` function is first evaluated in the [JavaScript thread](/docs/fundamentals/glossary#javascript-thread) just before the views are attached on the native side. For this reason, in order to safely use the measure within `useAnimatedStyle`, a condition similar to the one below has to be added to the code:
kacperkapusciak marked this conversation as resolved.
Show resolved Hide resolved

<Indent>

```jsx
function App() {
const animatedStyles = useAnimatedStyle(() => {
// highlight-next-line
if (_WORKLET) {
// safely use measure
const measurement = measure(animatedRef);
}
});
}
```

Consecutive runs of `useAnimatedStyle` are executed on the UI thread.

</Indent>

- When you only need the dimensions of the component and you won't use the measurements during the animation consider using [`onLayout`](https://reactnative.dev/docs/view#onlayout) property instead.
kacperkapusciak marked this conversation as resolved.
Show resolved Hide resolved

- Sometimes `measure` returns `null` (e.g. when `ref` still hasn't attached to the view). It's best to add a `null` check after the measurement for additional safety:
kacperkapusciak marked this conversation as resolved.
Show resolved Hide resolved

<Indent>

```jsx
const animatedRef = useAnimatedRef();

const handlePress = () => {
runOnUI(() => {
const measurement = measure(animatedRef);

// highlight-start
if (measurement === null) {
return;
}
// highlight-end
// ...
})();
};
```

</Indent>

- `measure` can be used only on rendered components. For example, trying to `measure` off-screen items in a `FlatList` results in a `null` value.
kacperkapusciak marked this conversation as resolved.
Show resolved Hide resolved

- `measure` isn't available with Remote JS Debugger. We highly recommend using Chrome DevTools (aka `chrome://inspect`) instead for debugging React Native apps,
kacperkapusciak marked this conversation as resolved.
Show resolved Hide resolved

## Platform compatibility

<div className="compatibility">

| Android | iOS | Web |
| ------- | --- | --- |
| ✅ | ✅ | ✅ |

</div>
141 changes: 141 additions & 0 deletions docs/docs/advanced/useAnimatedReaction.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,141 @@
---
sidebar_position: 2
---

# useAnimatedReaction

`useAnimatedReaction` lets you react to a change of a [shared value](/docs/fundamentals/glossary#shared-value). Especially useful when comparing values previously stored in shared value with the current one.
kacperkapusciak marked this conversation as resolved.
Show resolved Hide resolved

## Reference

```javascript
import { useAnimatedReaction } from 'react-native-reanimated';

function App() {
useAnimatedReaction(
() => {
return sv.value;
},
(currentValue, previousValue) => {
if (currentValue !== previousValue) {
// do something ✨
}
}
);

// ...
}
```

<details>
<summary>Type definitions</summary>

```typescript
type DependencyList = ReadonlyArray<any>;

function useAnimatedReaction<T>(
prepare: () => T,
react: (prepareResult: T, preparePreviousResult: T | null) => void,
dependencies?: DependencyList
): void;
```

</details>

### Arguments

#### `prepare`

A function that has to return a value you'd like to react to the changes of. A value returned from this function is used as a first parameter of the `react` argument.
kacperkapusciak marked this conversation as resolved.
Show resolved Hide resolved

```jsx
function App() {
useAnimatedReaction(
// highlight-start
() => {
return Math.floor(sv.value);
},
// highlight-end
(currentValue, previousValue) => {
// ...
}
);
}
```

#### `react`

A function that reacts to the change of a value returned by the `prepare` function. The `react` function comes with 2 parameters: the current value returned from the `prepare` function and the previous value which is initially set to `null`.
kacperkapusciak marked this conversation as resolved.
Show resolved Hide resolved

```jsx
function App() {
useAnimatedReaction(
() => {
return Math.floor(sv.value);
},
// highlight-next-line
(currentValue, previousValue) => {
// ...
// highlight-next-line
}
);
}
```

#### `dependencies` <Optional/>

An optional array of dependencies.

Only relevant when using Reanimated [without the Babel plugin on the Web](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/web-support#web-without-a-babel-plugin).

### Returns

`useAnimatedReaction` returns `undefined`.

## Example

import AnimatedReactionMeasure from '@site/src/examples/AnimatedReactionMeasure';
import AnimatedReactionMeasureSrc from '!!raw-loader!@site/src/examples/AnimatedReactionMeasure';

<InteractiveExample
src={AnimatedReactionMeasureSrc}
component={<AnimatedReactionMeasure />}
/>

## Remarks

- Make sure not to mutate the same shared value in the `result` function that you've used in the `prepare` function as this will cause an infinite loop.
kacperkapusciak marked this conversation as resolved.
Show resolved Hide resolved

<Indent>

```jsx
function App() {
useAnimatedReaction(
() => {
// highlight-next-line
return width.value;
},
(currentValue) => {
// 🚨 An infinite loop!
// highlight-next-line
width.value += currentValue;
}
);
}
```

</Indent>

- Callbacks passed to `prepare` and `result` arguments are automatically [workletized](/docs/fundamentals/glossary#to-workletize) and ran on the [UI thread](/docs/fundamentals/glossary#ui-thread).
kacperkapusciak marked this conversation as resolved.
Show resolved Hide resolved

- You can technically react to any stateful React value using `useAnimatedReaction` but you should most probably use a `useEffect` for that instead.
kacperkapusciak marked this conversation as resolved.
Show resolved Hide resolved

## Platform compatibility

<div className="compatibility">

| Android | iOS | Web |
| ------- | --- | --- |
| ✅ | ✅ | ✅ |

</div>
Original file line number Diff line number Diff line change
@@ -1,9 +1,15 @@
---
id: useEvent
title: useEvent
sidebar_label: useEvent
sidebar_position: 4
---

# useEvent

:::info
This page was ported from an old version of the documentation.

As we're rewriting the documentation some of the pages might be a little outdated.
:::

This is low-level hook returning event handler that will be invoked with native events, which should be used in order to create custom event handler hook like `useAnimatedGestureHandler` or `useAnimatedScrollHandler`.

### Arguments
Expand Down
Loading