npm package: @qtpy/route-guard
Description: `RouteGuard` — это React-компонент, предназначенный для условного рендеринга дочерних элементов в зависимости от того, соответствует ли текущий маршрут заданному набору допустимых маршрутов. Он использует хук `useMatch` из библиотеки `react-router` для пр
Author: QtPy
Latest version: 0.0.4

# Документация по компоненту RouteGuard

`RouteGuard` — это React-компонент, предназначенный для условного рендеринга дочерних элементов в зависимости от того, соответствует ли текущий маршрут заданному набору допустимых маршрутов. Он использует хук `useMatch` из библиотеки `react-router` для проверки соответствия маршрутов и поддерживает опциональную инверсию логики соответствия. Кроме того, предоставляет callback-функцию для уведомления об изменении статуса соответствия маршрута.

## Содержание
- [Свойства](#свойства)
- [Использование](#использование)
  - [Базовое использование](#базовое-использование)
  - [Инвертированная логика](#инвертированная-логика)
  - [С обработчиком событий](#с-обработчиком-событий)
- [Типы](#типы)
- [Примечания](#примечания)


## Свойства

Компонент `RouteGuard` принимает следующие свойства (props):

| Свойство          | Тип                                      | По умолчанию | Описание                                                                 |
|-------------------|------------------------------------------|--------------|--------------------------------------------------------------------------|
| `isValidRoutes`   | `Array<string>`                         | Обязательное | Массив шаблонов маршрутов для проверки соответствия текущему URL (использует `useMatch`). |
| `children`        | `React.ReactNode`                       | Обязательное | Контент, который рендерится условно в зависимости от соответствия маршрута. |
| `isInverted`      | `boolean`                               | `false`      | Если `true`, рендерит дочерние элементы, когда текущий маршрут *не* соответствует ни одному из допустимых маршрутов. |
| `onListener`        | `(isShow: boolean, route: string \| null) => void` | Опционально | Callback-функция, вызываемая при изменении статуса соответствия или маршрута. |

## Использование

### Базовое использование

Рендеринг дочерних элементов только при совпадении текущего маршрута с одним из указанных допустимых маршрутов:

```jsx
import RouteGuard from '@qtpy/route-guard';

function App() {
  return (
    <RouteGuard isValidRoutes={['/home', '/dashboard']}>
      <div>Контент виден только на /home или /dashboard</div>
    </RouteGuard>
  );
}
```

### Инвертированная логика

Используйте `isInverted`, чтобы рендерить дочерние элементы, когда текущий маршрут *не* соответствует ни одному из допустимых маршрутов:

```jsx
import RouteGuard from '@qtpy/route-guard';

function App() {
  return (
    <RouteGuard isValidRoutes={['/login', '/register']} isInverted>
      <div>Контент виден на всех маршрутах, кроме /login и /register</div>
    </RouteGuard>
  );
}
```

### С обработчиком событий

Используйте callback-функцию `onListener` для обработки изменений статуса соответствия маршрута:

```jsx
import RouteGuard from '@qtpy/route-guard';

function App() {
  const handleRouteChange = (isShow, route) => {
    console.log(`Соответствие маршрута: ${isShow}, Совпавший маршрут: ${route}`);
  };

  return (
    <RouteGuard isValidRoutes={['/home', '/dashboard']} onListener={handleRouteChange}>
      <div>Контент виден только на /home или /dashboard</div>
    </RouteGuard>
  );
}
```

## Типы

Компонент `RouteGuard` использует следующий TypeScript-интерфейс для своих свойств:

```typescript
interface IProps extends PropsWithChildren {
  isValidRoutes: Array<string>;
  isInverted?: boolean;
  onListener?: (isShow: boolean, route: string | null) => void;
}
```

- `PropsWithChildren` гарантирует, что свойство `children` типизировано как `React.ReactNode`.
- `isValidRoutes` — массив строк, представляющих шаблоны маршрутов, совместимые с `useMatch` из `react-router`.
- `isInverted` — опциональный булевый параметр для инверсии логики соответствия.
- `onListener` — опциональная callback-функция, которая получает статус соответствия (`isShow`) и совпавший маршрут (или `null`).

## Примечания

- **Производительность**: Компонент обёрнут в `React.memo` для предотвращения ненужных повторных рендеров при неизменных свойствах.
- **Соответствие маршрутов**: Хук `useMatch` из `react-router-dom` используется для проверки, соответствует ли текущий URL одному из маршрутов в `isValidRoutes`. Используется первый найденный совпадающий маршрут, а callback-функция `onListener` получает совпавший маршрут или `null`, если совпадений нет.
- **useEffect**: Callback-функция `onListener` вызывается при изменении статуса соответствия или совпавшего маршрута благодаря хуку `useEffect`.
- **Контекст маршрутизации**: Убедитесь, что `RouteGuard` используется в контексте `react-router` (например, внутри `<BrowserRouter>` или `<Router>`).
- **Шаблоны маршрутов**: Массив `isValidRoutes` поддерживает шаблоны маршрутов `react-router`, такие как `/user/:id` для динамических маршрутов.