npm package: @navegarti/rn-design-system
Description: Components and functions to help navegar projects
Author: Lucas Rodrigues Paixão
Latest version: 0.8.6

# @navegarti/rn-design-system

A comprehensive React Native design system with reusable components, utilities, hooks, and API integration tools for building scalable mobile applications.

## 📦 Installation

### Using Yarn

```sh
yarn add @navegarti/rn-design-system
```

### Using npm

```sh
npm install @navegarti/rn-design-system
```

### Prerequisites

Ensure your project has the required peer dependencies:

```sh
yarn add react react-native react-native-svg @emotion/react @emotion/native
```

## 🚀 Quick Start

### Basic Import

Import components from the main entry point:

```typescript
import { Button, Input, Text, Flex, Padding } from '@navegarti/rn-design-system';
import { View } from 'react-native';

export default function App() {
  return (
    <Padding padding={16}>
      <Flex>
        <Text.Title>Welcome to Design System</Text.Title>
        <Button.Rounded onPress={() => console.log('Pressed')}>
          <Button.Text>Press Me</Button.Text>
        </Button.Rounded>
      </Flex>
    </Padding>
  );
}
```

### Specific Entry Points

Import from specialized sub-packages for tree-shaking:

```typescript
// Components only
import { Button, Input, Select } from '@navegarti/rn-design-system/components';

// Utilities
import { priceFormatter, getAge, camelCase } from '@navegarti/rn-design-system/utils';

// Hooks
import { useNetworkStatus, useAppIsActive } from '@navegarti/rn-design-system/hooks';

// API layer
import { AxiosAdapter, apiRequest } from '@navegarti/rn-design-system/api';

// Form utilities
import { formValidators, tanstackForm } from '@navegarti/rn-design-system/form';
```

---

## 🎨 Components

### Form Components

#### Input
Customizable text input for user data entry:

```typescript
import { Input } from '@navegarti/rn-design-system';
import { useState } from 'react';

export function LoginForm() {
  const [email, setEmail] = useState('');

  return (
    <Input.Default
      placeholder="Enter your email"
      value={email}
      onChangeText={setEmail}
      keyboardType="email-address"
    />
  );
}
```

#### Select
Dropdown menu for selecting from multiple options:

```typescript
import { Select } from '@navegarti/rn-design-system';
import { useState } from 'react';

export function CountrySelector() {
  const [country, setCountry] = useState('');

  return (
    <Select
      placeholder="Select a country"
      value={country}
      onValueChange={setCountry}
      items={[
        { label: 'Brazil', value: 'BR' },
        { label: 'USA', value: 'US' },
        { label: 'Canada', value: 'CA' },
      ]}
    />
  );
}
```

#### Checkbox
Binary choice selection:

```typescript
import { Checkbox, Text } from '@navegarti/rn-design-system';
import { useState } from 'react';

export function TermsAcceptance() {
  const [agreed, setAgreed] = useState(false);

  return (
    <>
      <Checkbox
        value={agreed}
        onValueChange={setAgreed}
      />
      <Text>I agree to the terms and conditions</Text>
    </>
  );
}
```

#### Radio
Single selection from multiple options:

```typescript
import { Radio, Text } from '@navegarti/rn-design-system';
import { useState } from 'react';

export function PaymentMethod() {
  const [method, setMethod] = useState('credit-card');

  return (
    <>
      <Radio
        value="credit-card"
        selected={method === 'credit-card'}
        onPress={() => setMethod('credit-card')}
      />
      <Text>Credit Card</Text>

      <Radio
        value="debit-card"
        selected={method === 'debit-card'}
        onPress={() => setMethod('debit-card')}
      />
      <Text>Debit Card</Text>
    </>
  );
}
```

#### OTPInput
One-Time Password input for authentication:

```typescript
import { OTPInput } from '@navegarti/rn-design-system';
import { useState } from 'react';

export function TwoFactorAuth() {
  const [otp, setOtp] = useState('');

  return (
    <OTPInput
      value={otp}
      onChangeText={setOtp}
      length={6}
    />
  );
}
```

#### Switch
Toggle boolean values:

```typescript
import { Switch, Text, Flex } from '@navegarti/rn-design-system';
import { useState } from 'react';

export function DarkModeToggle() {
  const [darkMode, setDarkMode] = useState(false);

  return (
    <Flex direction="row" align="center">
      <Text>Dark Mode</Text>
      <Switch
        value={darkMode}
        onValueChange={setDarkMode}
      />
    </Flex>
  );
}
```

### Action Components

#### Button
Highly customizable button component with multiple variants:

```typescript
import { Button } from '@navegarti/rn-design-system';

export function ButtonVariants() {
  return (
    <>
      {/* Default button */}
      <Button onPress={() => {}}>
        <Button.Text>Default</Button.Text>
      </Button>

      {/* Rounded button */}
      <Button.Rounded onPress={() => {}}>
        <Button.Text>Rounded</Button.Text>
      </Button.Rounded>

      {/* Pill-shaped button */}
      <Button.Pill onPress={() => {}}>
        <Button.Text>Pill</Button.Text>
      </Button.Pill>

      {/* Outline button */}
      <Button.Outline onPress={() => {}}>
        <Button.Text>Outline</Button.Text>
      </Button.Outline>

      {/* Square button */}
      <Button.Square onPress={() => {}}>
        <Button.Text>Square</Button.Text>
      </Button.Square>
    </>
  );
}
```

#### FAB
Floating Action Button for primary actions:

```typescript
import { FAB } from '@navegarti/rn-design-system';

export function CreateFunction() {
  return (
    <FAB
      onPress={() => console.log('Create new item')}
      icon={{ name: 'plus' }}
    />
  );
}
```

### Display Components

#### Text
Typography component with predefined styles:

```typescript
import { Text } from '@navegarti/rn-design-system';

export function Typography() {
  return (
    <>
      <Text.Title>Page Title</Text.Title>
      <Text.Subtitle>Subtitle</Text.Subtitle>
      <Text.Body>Regular body text</Text.Body>
      <Text.Caption>Small caption text</Text.Caption>
    </>
  );
}
```

#### Skeleton
Loading placeholder for content:

```typescript
import { Skeleton, Flex } from '@navegarti/rn-design-system';

export function LoadingPlaceholder() {
  return (
    <Flex gap={8}>
      <Skeleton width="100%" height={20} />
      <Skeleton width="100%" height={40} />
      <Skeleton width="80%" height={20} />
    </Flex>
  );
}
```

#### Carousel
Image carousel/gallery component:

```typescript
import { Carousel } from '@navegarti/rn-design-system';

export function ImageGallery() {
  const images = [
    { uri: 'https://example.com/image1.jpg' },
    { uri: 'https://example.com/image2.jpg' },
    { uri: 'https://example.com/image3.jpg' },
  ];

  return <Carousel items={images} />;
}
```

### Layout Components

#### Flex
Flexible layout using Flexbox:

```typescript
import { Flex, Text, Button } from '@navegarti/rn-design-system';

export function FlexLayout() {
  return (
    <Flex
      direction="column"
      justify="space-between"
      align="center"
      gap={16}
    >
      <Text>Flexible Layout</Text>
      <Button><Button.Text>Action</Button.Text></Button>
    </Flex>
  );
}
```

#### Padding
Add internal spacing:

```typescript
import { Padding, Text } from '@navegarti/rn-design-system';

export function PaddedContent() {
  return (
    <Padding padding={16}>
      <Text>Content with padding</Text>
    </Padding>
  );
}
```

#### Margin
Add external spacing:

```typescript
import { Margin, Text } from '@navegarti/rn-design-system';

export function MarginalContent() {
  return (
    <Margin margin={16}>
      <Text>Content with margin</Text>
    </Margin>
  );
}
```

#### FormLabel
Label for form inputs:

```typescript
import { FormLabel, Input } from '@navegarti/rn-design-system';

export function LabeledInput() {
  return (
    <>
      <FormLabel label="Email Address" />
      <Input.Default placeholder="Enter email" />
    </>
  );
}
```

---

## 🪝 Hooks

### useNetworkStatus
Monitor device network connectivity:

```typescript
import { useNetworkStatus } from '@navegarti/rn-design-system/hooks';
import { Text } from 'react-native';

export function NetworkMonitor() {
  const { isConnected } = useNetworkStatus();

  return <Text>{isConnected ? 'Online' : 'Offline'}</Text>;
}
```

### useAppIsActive
Detect when app comes to foreground/background:

```typescript
import { useAppIsActive } from '@navegarti/rn-design-system/hooks';

export function AppLifecycleMonitor() {
  const isActive = useAppIsActive();

  React.useEffect(() => {
    if (isActive) {
      console.log('App is active');
    }
  }, [isActive]);

  return null;
}
```

### useAppSecurity
Check device security status:

```typescript
import { useAppSecurity } from '@navegarti/rn-design-system/hooks';

export function SecurityChecker() {
  const { isDeviceSecure } = useAppSecurity();

  return null;
}
```

### useStatusBar
Control status bar appearance:

```typescript
import { useStatusBar } from '@navegarti/rn-design-system/hooks';

export function MyScreen() {
  useStatusBar({ barStyle: 'dark-content' });

  return null;
}
```

---

## 🔧 Utilities

### Text Formatting

```typescript
import {
  priceFormatter,
  capitalizeWord,
  removeTextAccents,
  userFullnameInitialsExtractor,
} from '@navegarti/rn-design-system/utils';

// Price formatting
const price = priceFormatter(1299.50); // R$ 1.299,50

// Capitalize
const capitalized = capitalizeWord('hello'); // Hello

// Remove accents
const clean = removeTextAccents('São Paulo'); // Sao Paulo

// Extract initials
const initials = userFullnameInitialsExtractor('John Doe'); // JD
```

### Data Manipulation

```typescript
import {
  camelCase,
  camelCaseJSONKeys,
  sortBy,
  uniqBy,
  getAge,
  getOnlyNumbers,
  isArray,
  isObject,
} from '@navegarti/rn-design-system/utils';

// Camel case conversion
const camel = camelCase('hello-world'); // helloWorld

// Sort array of objects
const users = [{ name: 'Bob' }, { name: 'Alice' }];
const sorted = sortBy(users, 'name'); // Alphabetical order

// Get unique items
const unique = uniqBy(users, 'name');

// Age calculation
const age = getAge('1990-01-01');

// Extract numbers
const numbers = getOnlyNumbers('(11) 9999-8888'); // 119999888
```

### Date Formatting

```typescript
import {
  formatDate,
  formatTime,
  formatDateTime,
} from '@navegarti/rn-design-system/utils';

const date = new Date();
const formatted = formatDate(date); // DD/MM/YYYY
const time = formatTime(date); // HH:MM:SS
const combined = formatDateTime(date); // DD/MM/YYYY HH:MM:SS
```

### Input Masks

```typescript
import { Masks } from '@navegarti/rn-design-system/utils';

// CPF mask
const cpfMask = Masks.cpf('12345678901'); // 123.456.789-01

// Phone mask
const phoneMask = Masks.phone('1199998888'); // (11) 99999-888

// Currency mask
const currencyMask = Masks.currency('1299'); // R$ 12,99
```

---

## 📡 API Integration

### Basic Setup

```typescript
import { AxiosAdapter } from '@navegarti/rn-design-system/api';

const api = new AxiosAdapter({
  baseURL: 'https://api.example.com',
  timeout: 10000,
  retryAttempts: 3,
});
```

### Making Requests

```typescript
// GET request
const posts = await api.get<Post[]>('/posts');
if (posts.success && posts.data) {
  console.log('Posts:', posts.data);
}

// POST request
const newPost: Post = { title: 'New Post', body: 'Content' };
const response = await api.post('/posts', newPost);

// PUT request
const updated = await api.put('/posts/1', { title: 'Updated' });

// DELETE request
const deleted = await api.delete('/posts/1');
```

### Error Handling

```typescript
const response = await api.get('/posts');

if (!response.success) {
  switch (response.statusCode) {
    case 401:
      console.log('Unauthorized');
      break;
    case 404:
      console.log('Not found');
      break;
    case 500:
      console.log('Server error');
      break;
    default:
      console.log('Error:', response.error);
  }
}
```

### Authentication

```typescript
import { apiRequest } from '@navegarti/rn-design-system/api';

// Add token
apiRequest.addToken('your-jwt-token');

// Make authenticated request
const profile = await apiRequest.get('/profile');

// Remove token when logging out
apiRequest.removeToken();
```

---

## 📋 Form Validation

### Using Zod Validators

```typescript
import { formValidators } from '@navegarti/rn-design-system/form';

const emailValidator = formValidators.email;
const passwordValidator = formValidators.password;

const email = 'user@example.com';
const result = emailValidator.safeParse(email);

if (result.success) {
  console.log('Valid email');
} else {
  console.log('Invalid email:', result.error.errors);
}
```

### TanStack Form Integration

```typescript
import { tanstackForm } from '@navegarti/rn-design-system/form';
import { useForm } from '@tanstack/react-form';

const form = useForm({
  defaultValues: {
    firstName: '',
    lastName: '',
  },
  onSubmit: async (values) => {
    console.log('Form submitted:', values);
  },
});
```

---

## 📚 Examples

For interactive examples, check out the [example](./example) folder:

```bash
# Navigate to example
cd example

# Install dependencies
yarn install

# Run on iOS
yarn ios

# Run on Android
yarn android
```

Available examples:
- **api-examples.tsx**: Complete API integration patterns
- **API-EXAMPLES-README.md**: Detailed API documentation

---

## 🧪 Testing

Run unit tests:

```bash
yarn test
```

---

## 📖 Documentation

- [API Examples](./example/API-EXAMPLES-README.md) - Detailed API usage

---

## 🔐 Security

For security-related hooks and utilities, ensure your app requires:
- Permission checks via `react-native-permissions`

---

## 🛠️ Troubleshooting

### Module Not Found

```bash
# Clean install
yarn clean
yarn install
yarn prepare
```

### TypeScript Errors

Ensure `tsconfig.json` includes:
```json
{
  "compilerOptions": {
    "moduleResolution": "node",
    "skipLibCheck": true,
    "esModuleInterop": true
  }
}
```

### Peer Dependency Issues

Install missing dependencies:
```bash
yarn add react react-native react-native-svg @emotion/react @emotion/native
```

---

Made with ❤️ by Navegar Team | Built with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)