npm package: @g9t3n/react-screenutil
Description: A React/TypeScript implementation inspired by Flutter's flutter_screenutil for responsive design
Author: G9t3n
Latest version: 1.1.4

# react-screenutil

A React/TypeScript implementation inspired by Flutter's `flutter_screenutil` package for creating responsive UIs that adapt seamlessly across different screen sizes.

## 🚀 Features

- 🎨 **Flutter-like syntax** - Use `.w`, `.h`, `.sp`, `.r` on numbers
- 📱 **Automatic scaling** based on design size
- 🔄 **Zero re-renders** option with direct DOM manipulation
- 💪 **Full TypeScript support**
- ⚡ **Lightweight** with no dependencies
- 🌐 **SSR-safe**

## 📦 Installation

```bash
npm install react-screenutil
# or
yarn add react-screenutil
# or
pnpm add react-screenutil
```

## 🎯 Quick Start

### 1. Initialize ScreenUtil

Wrap your app with the provider (optional, for automatic re-renders):

```tsx
import { ScreenUtilProvider } from "react-screenutil";

function App() {
  return (
    <ScreenUtilProvider designWidth={375} designHeight={812}>
      <YourApp />
    </ScreenUtilProvider>
  );
}
```

### 2. Use Responsive Values

```tsx
import "react-screenutil"; // Enable .w, .h, .sp, .r extensions

function MyComponent() {
  return (
    <div
      style={{
        width: `${(300).w}px`,
        height: `${(200).h}px`,
        fontSize: `${(16).sp}px`,
        borderRadius: `${(12).r}px`,
      }}
    >
      Responsive Content
    </div>
  );
}
```

## 📚 API Reference

### Extension Methods

| Method | Description     | Example   |
| ------ | --------------- | --------- |
| `.w`   | Scale width     | `(100).w` |
| `.h`   | Scale height    | `(50).h`  |
| `.sp`  | Scale font size | `(16).sp` |
| `.r`   | Scale radius    | `(8).r`   |

### ScreenUtil Class

```tsx
import { ScreenUtil } from "react-screenutil";

// Initialize
ScreenUtil.init({ designWidth: 375, designHeight: 812 });

// Get dimensions
ScreenUtil.width; // Current screen width
ScreenUtil.height; // Current screen height

// Manual scaling
ScreenUtil.setWidth(100);
ScreenUtil.setHeight(50);
ScreenUtil.setSp(16);
ScreenUtil.setRadius(8);

// Get scale factors
ScreenUtil.scaleWidth;
ScreenUtil.scaleHeight;
```

### React Context (with re-renders)

```tsx
import { useScreenUtil } from "react-screenutil";

function MyComponent() {
  const { width, height } = useScreenUtil();

  return (
    <div>
      Screen: {width} × {height}
    </div>
  );
}
```

### Direct DOM Manipulation (no re-renders)

```tsx
import { ScreenUtil } from "react-screenutil";
import { useEffect, useRef } from "react";

function MyComponent() {
  const textRef = useRef<HTMLParagraphElement>(null);

  useEffect(() => {
    const updateSize = () => {
      if (textRef.current) {
        textRef.current.style.fontSize = `${(16).sp}px`;
      }
    };

    updateSize();
    window.addEventListener("resize", updateSize);
    return () => window.removeEventListener("resize", updateSize);
  }, []);

  return <p ref={textRef}>Responsive text</p>;
}
```

## 💡 Usage Examples

### Responsive Card

```tsx
<div
  style={{
    width: `${(300).w}px`,
    padding: `${(16).w}px`,
    borderRadius: `${(12).r}px`,
    boxShadow: "0 2px 8px rgba(0,0,0,0.1)",
  }}
>
  <h2 style={{ fontSize: `${(20).sp}px` }}>Title</h2>
  <p style={{ fontSize: `${(14).sp}px` }}>Content</p>
</div>
```

### Responsive Grid

```tsx
<div
  style={{
    display: "grid",
    gridTemplateColumns: `repeat(auto-fit, minmax(${(150).w}px, 1fr))`,
    gap: `${(16).w}px`,
  }}
>
  {items.map((item) => (
    <GridItem key={item.id} {...item} />
  ))}
</div>
```

## 🎨 Design Size Recommendations

| Device        | Width | Height | Use Case                 |
| ------------- | ----- | ------ | ------------------------ |
| iPhone 11 Pro | 375   | 812    | Modern iOS (recommended) |
| Android       | 360   | 800    | Android devices          |
| iPad          | 768   | 1024   | Tablets                  |
| Desktop       | 1920  | 1080   | Desktop apps             |

**Tip:** Use mobile-first design sizes (375×812) so elements scale UP on larger screens.

## 🔧 Configuration

```tsx
ScreenUtil.init({
  designWidth: 375, // Your design mockup width
  designHeight: 812, // Your design mockup height
  splitScreenMode: false, // Reserved for future use
});
```

## 📖 How It Works

The utility calculates scale factors based on your design size:

```
scaledValue = designValue × (currentScreenWidth / designWidth)
```

**Example:**

- Design width: 375px
- Current screen: 1366px
- Scale factor: 1366 / 375 = 3.64
- `(100).w` = 100 × 3.64 = **364px**

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📄 License

MIT © [Your Name]

## 🙏 Acknowledgments

Inspired by Flutter's [flutter_screenutil](https://pub.dev/packages/flutter_screenutil) package.