Add withClamp documentation

docs/docs/animations/withClamp.mdx

@@ -0,0 +1,81 @@
+---
+sidebar_position: 7
+---
+
+# withClamp
+
+`withClamp` is an [animation modifier](/docs/fundamentals/glossary#animation-modifier) that lets you limit the scope of movement of your animation to make it stay within some predefined range.
+Use it with [withSpring](/docs/animations/withSpring) animation.
+
+import { useClampPlayground } from '@site/src/components/InteractivePlayground';
+
+<InteractivePlayground usePlayground={useClampPlayground} />
+
+## Reference
+
+```javascript
+import { withClamp } from 'react-native-reanimated';
+
+function App() {
+  sv.value = withClamp({ min: -1, max: 1 }, withSpring(0));
+  // ...
+}
+```
+
+<details>
+<summary>Type definitions</summary>
+
+```typescript
+type AnimatableValue = number | string | number[];
+
+function withClamp<T extends number | string>(
+  config: {
+    min?: T;
+    max?: T;
+  },
+  clampedAnimation: T
+): T;
+
+enum ReduceMotion {
+  System = 'system',
+  Always = 'always',
+  Never = 'never',
+}
+```
+
+</details>
+
+### Arguments
+
+#### `config`
+
+An object with following properties:
+
+| Name             | Type Description |
+| ---------------- | ---------------- | ------------------------------------------------ |
+| min <Optional /> | `number`         | The lowest value your animation can ever reach   |
+| max <Optional /> | `number`         | The greatest value your animation can ever reach |
+
+#### `animation`
+
+The spring animation you want to clamp.
+
+```typescript
+const clampedStyleWithDelay = useAnimatedStyle(() => {
+  return {
+    width: withClamp({ min: 0, max: 100 }, withSpring(randomWidth.value)),
+  };
+});
+```
+
+### Returns
+
+`withClamp` returns an [animation object](/docs/fundamentals/glossary#animation-object). It can be either assigned directly to a [shared value](/docs/fundamentals/glossary#shared-value) or can be used as a value for a style object returned from [useAnimatedStyle](docs/core/useAnimatedStyle).
+
+<div className="platform-compatibility">
+
+| Android | iOS | Web |
+| ------- | --- | --- |
+| ✅      | ✅  | ✅  |
+
+</div>

docs/package.json

@@ -41,7 +41,7 @@
     "react-draggable": "^4.4.5",
     "react-native": "^0.71.4",
     "react-native-gesture-handler": "^2.13.2",
-    "react-native-reanimated": "^3.6.0-nightly-20231010-4a507b2c4",
+    "react-native-reanimated": "^3.6.0-nightly-20231120-1eb2acaa0",
     "react-native-svg": "^13.14.0",
     "react-native-web": "^0.18.12",
     "source-map": "^0.7.4",

docs/src/components/InteractivePlayground/index.tsx

@@ -5,6 +5,7 @@ import styles from './styles.module.css';
 import BrowserOnly from '@docusaurus/BrowserOnly';
 import CodeBlock from '@theme/CodeBlock';
 
+import useClampPlayground from './useClampPlayground';
 import useSpringPlayground from './useSpringPlayground';
 import useTimingPlayground from './useTimingPlayground';
 import useInterpolateColorPlayground from './useInterpolateColorPlayground';
@@ -23,6 +24,7 @@ import {
 } from '@mui/material';
 
 export {
+  useClampPlayground,
   useSpringPlayground,
   useTimingPlayground,
   useInterpolateColorPlayground,
@@ -99,6 +101,16 @@ interface RangeProps {
   label: string;
 }
 
+interface DoubleRangeProps {
+  min: number;
+  max: number;
+  step?: number;
+  value: [number, number];
+  onChange: [Dispatch<number>, Dispatch<number>];
+  label: string;
+  color?: 'yellow' | 'green';
+}
+
 const RangeStyling = {
   color: 'var(--swm-interactive-slider)', // color of the main path of slider
   '& .MuiSlider-thumb': {
@@ -162,6 +174,58 @@ export function Range({
   );
 }
 
+export function DoubleRange({
+  min,
+  max,
+  value,
+  onChange,
+  label,
+  step = 1,
+  color,
+}: DoubleRangeProps) {
+  return (
+    <>
+      <div className={styles.row}>
+        <label>{label}</label>
+        {[0, 1].map((idx) => {
+          return (
+            <TextField
+              type="number"
+              hiddenLabel
+              size="small"
+              key={`${label}${idx}`}
+              inputProps={{ min: min, max: max, step: step }}
+              sx={TextFieldStyling}
+              value={value[idx]}
+              onChange={(e) => {
+                const newValue = parseFloat(e.target.value);
+                onChange[idx](
+                  newValue > max[idx]
+                    ? max[idx]
+                    : newValue <= min[idx]
+                    ? min[idx]
+                    : newValue
+                );
+              }}
+            />
+          );
+        })}
+      </div>
+      <Slider
+        min={min}
+        max={max}
+        step={step}
+        value={value}
+        sx={RangeStyling}
+        onChange={(e: Event & { target: HTMLInputElement }) => {
+          onChange[0](parseFloat(e.target.value[0]));
+          onChange[1](parseFloat(e.target.value[1]));
+        }}
+      />
+    </>
+  );
+}
+
 interface CheckboxProps {
   value: boolean;
   onChange: Dispatch<boolean>;

docs/src/components/InteractivePlayground/useClampPlayground/Example.tsx

@@ -0,0 +1,169 @@
+import React from 'react';
+import { StyleSheet, View, Text, ViewStyle } from 'react-native';
+import Animated, {
+  useAnimatedStyle,
+  withClamp,
+  withSpring,
+  withRepeat,
+  withSequence,
+  withTiming,
+  withDelay,
+} from 'react-native-reanimated';
+
+const BOX_START = 0;
+const BOX_STOP = 200;
+const BOX_SIZE = 80;
+
+const FRAME_WIDTH = 400;
+const FRAME_HEIGHT = 100;
+const CLAMP_MARKER_HEIGHT = 40;
+
+interface ClampPlaygroundOptions {
+  lowerBound: number;
+  upperBound: number;
+}
+
+interface Props {
+  options: ClampPlaygroundOptions;
+}
+export default function App({ options }: Props) {
+  const config = {
+    damping: 3,
+  };
+
+  const clampedStyle = useAnimatedStyle(() => {
+    return {
+      transform: [
+        {
+          translateX: withClamp(
+            { min: options.lowerBound, max: options.upperBound },
+            withRepeat(
+              withSequence(
+                withDelay(2000, withSpring(BOX_STOP, config)),
+                withTiming(BOX_START, { duration: 0 })
+              ),
+              -1,
+              true
+            )
+          ),
+        },
+      ],
+    };
+  });
+  const defaultStyle = useAnimatedStyle(() => {
+    return {
+      transform: [
+        {
+          translateX: withRepeat(
+            withSequence(
+              withDelay(2000, withSpring(200, config)),
+              withTiming(0, { duration: 0 })
+            ),
+            -1,
+            true
+          ),
+        },
+      ],
+    };
+  });
+
+  function Example({
+    testedStyle,
+    description,
+    showClampMarkers,
+  }: {
+    testedStyle: ViewStyle;
+    description: string;
+    showClampMarkers: boolean;
+  }) {
+    return (
+      <View
+        style={{
+          width: FRAME_WIDTH,
+          height: FRAME_HEIGHT,
+        }}>
+        <View>
+          {showClampMarkers && (
+            <View
+              style={[
+                styles.clampMarker,
+                {
+                  marginTop: (BOX_SIZE - FRAME_HEIGHT) / 2,
+                  borderRightWidth: 2,
+                  width: options.lowerBound,
+                },
+              ]}
+            />
+          )}
+        </View>
+        <Animated.View style={[styles.movingBox, testedStyle]}>
+          <Text style={styles.text}>{description}</Text>
+        </Animated.View>
+        <View>
+          {showClampMarkers && (
+            <View
+              style={[
+                styles.clampMarker,
+                {
+                  borderLeftWidth: 2,
+                  marginTop: -(BOX_SIZE + FRAME_HEIGHT) / 2,
+                  width: FRAME_WIDTH - options.upperBound - BOX_SIZE,
+                  alignSelf: 'flex-end',
+                },
+              ]}
+            />
+          )}
+        </View>
+      </View>
+    );
+  }
+
+  return (
+    <View style={styles.container}>
+      <Example
+        testedStyle={clampedStyle}
+        description="Clamped spring"
+        showClampMarkers={true}
+      />
+      <Example
+        testedStyle={defaultStyle}
+        description="Default spring"
+        showClampMarkers={false}
+      />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    flexDirection: 'column',
+    alignItems: 'center',
+    justifyContent: 'center',
+    padding: CLAMP_MARKER_HEIGHT,
+    paddingBottom: 0,
+  },
+  clampMarker: {
+    position: 'absolute',
+    margin: 0,
+    opacity: 0.5,
+    height: 100,
+    borderColor: '#b58df1',
+    borderStyle: 'dashed',
+  },
+  movingBox: {
+    height: BOX_SIZE,
+    width: BOX_SIZE,
+    borderColor: '#b58df1',
+    borderRadius: 20,
+    borderWidth: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  text: {
+    color: '#b58df1',
+    textTransform: 'uppercase',
+    fontWeight: 'bold',
+    textAlign: 'center',
+  },
+});