[MAX UI](https://github.com/max-messenger/max-ui) — библиотека React-компонентов для создания мини-приложений в MAX, сторонних суперприложений, а также standalone-приложений. Готовые компоненты библиотеки умеют подстраиваться под разные платформы и устройства.

Ознакомьтесь с основными принципами устройства интерфейса, навигации и типографики, а также примерами мини-приложений в нашем гайдлайне — его можно скачать в формате .FIG по [ссылке](https://github.com/max-messenger/max-ui/blob/main/MAXUI-Figma.fig)

## Особенности MAX UI

* **Дизайн-система MAX**Библиотека компонентов разработана на основе дизайн-системы MAX, что позволяет мини-приложениям выглядеть гармонично в интерфейсе цифровой платформы.

* **Единообразие на разных платформах**Компоненты библиотеки органично встраиваются в мобильные платформы iOS и Android, а также в экраны устройств разного размера.

* **Современный UI Kit**TypeScript, React 18+, полиморфные компоненты и подробная документация с примерами.

Знаете, как улучшить MAX UI? Мы открыты к предложениям:
* Чтобы сообщить об ошибках в библиотеке, создайте [**issue**](https://github.com/max-messenger/max-ui/issues) в [репозитории MAX UI](https://github.com/max-messenger/max-ui).
* Чтобы предложить идею, создайте **Fork** библиотеки и откройте **pull request**.

## Подключение библиотеки MAX UI

Установите библиотеку одной из команд:

```bash
npm i @maxhub/max-ui
yarn add @maxhub/max-ui
pnpm add @maxhub/max-ui
```

Оберните код вашего приложения в провайдер MAX UI и подключите стили:

```jsx
import { createRoot } from 'react-dom/client';
import { MaxUI } from '@maxhub/max-ui';
import '@maxhub/max-ui/dist/styles.css';
import App from './App.jsx';

const Root = () => (
    
        
    
);

createRoot(document.getElementById('root')).render();
```

Используйте компоненты библиотеки:

```jsx
import { Panel, Grid, Container, Flex, Avatar, Typography } from '@maxhub/max-ui';

const App = () => (
    
        
            
                
                    
                        
                    

                    Иван Иванов
                
            
        
    
);

export default App;
```

---

## Компоненты

Компоненты библиотеки MAX UI мимикрируют под нативные компоненты iOS и Android и умеют поддерживать светлую и тёмную темы оформления. Тема и платформа определяются автоматически в провайдере `MaxUI`, но могут быть переопределены через свойства `platform` (`'ios'` | `'android'`) и `colorScheme` (`'light'` | `'dark'`).

```jsx
import { createRoot } from 'react-dom/client';
import { MaxUI } from '@maxhub/max-ui';
import '@maxhub/max-ui/dist/styles.css';
import App from './App.jsx';

const Root = () => (
    
        
    
);

createRoot(document.getElementById('root')).render();
```

---

## Полиморфные компоненты

Полиморфность компонентов реализована через паттерн `asChild` prop: это позволяет предотвратить ошибки типизации и не увеличивать время TypeScript-процессинга.

В DOM полиморфные компоненты могут быть представлены в виде разных тегов. Например, компонент `Button` — как `button`, `a`, `span` и так далее.

| React-компонент | DOM* |
|---|---|
| `Я — кнопка` | ```  Я — кнопка``` |
| ```  Я — ссылка!``` | ```  Я — ссылка!``` |
| ```  Я — ссылка RRD!``` | ```  Я — ссылка RRD!``` |
| *упрощённое представление компонента |

### Корнер-кейс с asChild

Паттерн `asChild` prop может привести к конфликту свойств, если у одинаковых свойств родительского и дочернего компонентов разные значения. В этом случае свойства `className`, `style` и обработчики событий `on*` (`onClick`, `onChange` и другие) объединяются. В остальных случаях приоритет остаётся у свойств родительского компонента.

| React-компонент | DOM* |
|---|---|
| ```  Кнопка``` | ```  Кнопка``` |
| ```  Кнопка``` | ``  style="color: red; background: green">``  Я — кнопка``` |
| *упрощённое представление компонент  |

---

## Кастомизация компонентов

ℹ️ Библиотека предоставляет API для кастомизации, но не гарантирует отсутствие изменений в следующих мажорных версиях. Любая кастомизация компонентов — ответственность разработчика мини-приложения.

В MAX UI есть два способа кастомизации компонентов — переопределение CSS-переменных и свойство `innerClassNames`.

* Переопределение CSS-переменных Все токены дизайн-системы MAX заданы в CSS-переменных. Вы можете переопределить переменные как для конкретного компонента, так и для всей темы в целом.

* Свойство innerClassNames Многосоставные компоненты, например `Button`, имеют свойство `innerClassNames`. Оно позволяет указать `className` для внутренних элементов.

| React-компонент | DOM* |
|---|---|
| `}>``  Кнопка с иконкой``` | ```  ``    ``  ``  Я — кнопка``` |
| `}``  innerClassNames={{ iconBefore: 'my-custom-icon-class' }}>``  Кнопка с иконкой``` | ```  ``    ``  ``  Я — кнопка``` |
| *\*упрощённое представление компонента* |

ℹ️ Если у вас возникли вопросы, [посмотрите раздел с ответами](https://dev.max.ru/help)