react-native-responsiveness-tool/README.md

A utility package for scaling UI elements in React Native based on device dimensions and screen density.

# react-native-responsiveness-tool

A utility package for scaling UI elements in React Native based on device dimensions and screen density. This tool helps create responsive UIs across different screen sizes and densities using various scaling techniques, such as width, height, moderate scaling, adaptive scaling, and percentage-based scaling.

## Features

- **Responsive Scaling**: Scales UI elements based on the device's width and height.
- **Moderate Scaling**: Adjusts sizes according to screen dimensions.
- **Adaptive Scaling**: Customizes scaling factors for specific components.
- **Percentage-based Scaling**: Scales elements based on a percentage of the device width or height.
- **Image Scaling**: Scales images according to their width-to-height ratio.

## Installation

Install the package using npm or yarn:

```bash
npm install react-native-responsiveness-tool
# or
yarn add react-native-responsiveness-tool
```

## Usage

### Importing

```javascript
import {
  DEVICE_WIDTH,
  DEVICE_HEIGHT,
  sw,
  sh,
  moderateScale,
  adaptiveScale,
  scaleWidthPercent,
  scaleHeightPercent,
  imageHeightFromWidth,
  setReferenceDimensions,
} from 'react-native-responsiveness-tool';
```

### Scaling Functions

1. **`sw(size: number)`**
   Scales a value based on the device's width.

   ```javascript
   const scaledWidth = sw(100);
   ```

2. **`sh(size: number)`**
   Scales a value based on the device's height.

   ```javascript
   const scaledHeight = sh(100);
   ```

3. **`moderateScale(size: number)`**
   Applies moderate scaling based on screen height.

   ```javascript
   const moderateScaledValue = moderateScale(100);
   ```

4. **`adaptiveScale(size: number, factor: number = 0.5)`**
   Applies adaptive scaling with a customizable factor.

   ```javascript
   const adaptiveScaledValue = adaptiveScale(100, 0.7);
   ```

5. **`scaleWidthPercent(widthPercent: string)`**
   Scales an element's width based on a percentage of the device's width.

   ```javascript
   const scaledWidthPercent = scaleWidthPercent('50');
   ```

6. **`scaleHeightPercent(heightPercent: string)`**
   Scales an element's height based on a percentage of the device's height.

   ```javascript
   const scaledHeightPercent = scaleHeightPercent('50');
   ```

7. **`imageHeightFromWidth(width: number, height: number)`**
   Scales an image's height based on its width-to-height ratio.

   ```javascript
   const imageHeight = imageHeightFromWidth(200, 300);
   ```

### Reference Dimensions

You can set new reference dimensions for scaling by using the `setReferenceDimensions` function:

```javascript
setReferenceDimensions(375, 812); // Default is 360x800
```

### Constants

- **`DEVICE_WIDTH`**: The width of the device in pixels.
- **`DEVICE_HEIGHT`**: The height of the device in pixels.
- **`DEVICE_SCALE`**: The device scale factor, based on the screen's diagonal size.
- **`REFERENCE_WIDTH`**: Default reference width for scaling (360px).
- **`REFERENCE_HEIGHT`**: Default reference height for scaling (800px).
- **`SCALE_FACTOR`**: Default scaling factor used in adaptive scaling (0.5).

## Example

```javascript
import {
  sw,
  sh,
  moderateScale,
  adaptiveScale,
  scaleWidthPercent,
  scaleHeightPercent,
} from 'react-native-responsiveness-tool';

const App = () => {
  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Text style={{ fontSize: moderateScale(16) }}>Hello, World!</Text>
      <Text style={{ fontSize: adaptiveScale(14, 0.8) }}>Responsive Text</Text>
      <Text style={{ width: scaleWidthPercent('50%') }}>Scaled Width</Text>
      <Text style={{ height: scaleHeightPercent('30%') }}>Scaled Height</Text>
    </View>
  );
};

export default App;
```