@astral/ui

``@astral/ui` - это UI-KIT, на основе которого строятся интерфейсы в Астрал-Софт.

Table of contents

- Storybook
- Introduction
- Playground
- Getting started with Next.js
- Migration guide
- Troubleshooting
- Медленно выполняются vitest тесты при импорте пакета
- utils

Storybook

Storybook содержит документацию компонентов `@astral/ui`.

Introduction

`@astral/ui` - это единая точка входа для всех основных составных частей UI-KIT.

`@astral/ui` экспортирует:
- основу для построения интерфейсов: react-компоненты, хуки, utils,
- обертки компонентов для интеграции с react-hook-form,
- иконки, доступные в дизайн-системе.

Playground

Доступен Codesandbox для проверки функционала.

Getting started with Next.js

Example

Пример использования и интеграции `@astral/ui` находится здесь.

Installation

`shell
npm --save @astral/ui
`

global.d.ts

`ts
///

`

next.config

`js
const nextConfig = {
...
transpilePackages: [
'@astral/ui'
],
webpack(config) {
config.module.rules.push({
test: /\.(woff|woff2)$/i,
issuer: { and: [/\.(js|ts)x?$/] },
type: 'asset/resource',
});

return config;
},
...
};

module.exports = nextConfig;
`

_app.tsx

`tsx
import { AppProps } from 'next/app';
import Head from 'next/head';
import * as monitoringErrorService from '@sentry/nextjs';
import {
type BrandPalette,
ConfigProvider,
NotificationContainer,
StylesCacheProvider,
ThemeProvider,
createTheme,
} from '@astral/ui';
import { createStylesCache as createStylesServerCache } from '@astral/ui/server';

import { MainLayout } from '@example/modules/LayoutModule';

const brandPalette: BrandPalette = {
primary: {
900: '#5D3FD4',
800: '#6746EB',
700: '#8566FF',
600: '#9075FF',
500: '#9D85FF',
400: '#B29EFF',
300: '#C2B2FF',
200: '#E0D9FF',
100: '#EFEBFF',
},
secondary: {
800: '#5653FF',
},
brand: {
800: '#6746EB',
background: '#FAFBFC',
},
};

export const theme = createTheme({ palette: brandPalette });

const stylesCache = createStylesServerCache({ key: 'next' });

export const App = ({ Component, pageProps }: AppProps) => {
return (
<>

name="viewport"
content="width=device-width, initial-scale=1, shrink-to-fit=no"
/>



captureException={monitoringErrorService.captureException}
>









);
};

export default App;
`

Migration guide

3.0.0 -> 4.0.0

$3

Подключение шрифтов через объект theme больше не поддерживается.

Шрифты необходимо подключать через сервис для хранения статичных файлов

Инструкция для подключения шрифтов

⚠️ Для подключения шрифтов необходимо настроить Content Security Policy.

2.0.0 -> 3.0.0

$3

В ConfigProvider добавлен prop `imagesMap`:
`ts
type ImagesMap = {
/**
* изображение при отсутствии данных (используется в DataGrid)
*/
noDataImgSrc: string;
/**
* изображение при ошибке (используется в ContentState)
*/
defaultErrorImgSrc: string;
/**
* изображение при ошибке при обновлении продукта (используется в ContentState/ErrorBoundary)
*/
outdatedReleaseErrorImgSrc: string;
};
`

Данный prop содержит ссылки на img, которые используются в компонентах ui-kit.

Breaking changes:
- Компонент DataGrid теперь не инкапсулирует инлайновую svg для отображения NoData статуса. Для того, чтобы изображение появилось необходимо в ConfigProvider указать prop `imagesMap.noDataImgSrc`
- Компонент ContentState больше не требует required prop `errorState.imgSrc`. Ссылка на изображение берется из ConfigProvider
- Компонент ErrorBoundary перехватывает ошибку устаревших билдов и корректно её обрабатывает, для того, чтобы отобразилось изображение, необходимо в ConfigProvider указать prop `images.outdatedReleaseErrorImgSrc`
`tsx
import noDataImgSrc from '@astral/ui/illustrations/no-data.svg';
import outdatedReleaseErrorImgSrc from '@astral/ui/illustrations/outdated-release.svg';

/ cspell:disable-next-line /
import errorImgSrc from 'static/erorr-inmg.png';

const App = () => {
return (
imagesMap={{
defaultErrorImgSrc: errorImgSrc,
noDataImgSrc,
outdatedReleaseErrorImgSrc,
}}
>




);
};
`

$3

Breaking changes:
- Удалены пропсы, которые являлись css правилами (margin, border, mr...)
- Prop `color` принимает только `string`. Удалена возможность использовать для color функцию

Актуальные props находятся здесь.

$3

Grid из @astral/ui v2 был переименован в LegacyGrid, в четвертой версии @astral/ui данный компонент будет удален.

Сигнатуру нового Grid вы можете увидеть в storybook.

$3

Breaking changes:
- Была удалена дефолтная валидация для компонентов: `FormDatePicker`, `FormMobilePhoneField`
- Для филдов формы был удален props `rules`. Для валидации форм используйте валидацию по схеме с помощью библиотеки @astral/validations

1.0.0 -> 2.0.0

$3


Теперь пакет `@astral/ui` аккумулирует и реэкспортит пакеты:
- `@astral/fonts`
- `@astral/illustrations`
- `@astral/icons`
- `@astral/form`
- `@astral/components`

Необходимо заменить зависимости:
`json
{
...
"@astral/icons": "^1.19.4",
"@astral/form": "^1.19.4",
"@astral/fonts": "^1.19.4",
"@astral/ui": "^1.19.4",
...
}
`

На:
`json
{
...
"@astral/ui": "^1.19.4",
...
}
`

$3

Заменить файл `global.d.ts`:

`global.d.ts`
`ts
///
///
///
`

На:

`global.d.ts`
`ts
///
`

$3


Пакет `@astral/fonts` включен в пакет `@astral/ui`.

Необходимо заменить импорты:
`ts
import UbuntuBoldWoff from '@astral/fonts/UbuntuBold.woff';
import UbuntuBoldWoff2 from '@astral/fonts/UbuntuBold.woff2';
`

На:
`ts
import UbuntuBoldWoff from '@astral/ui/fonts/UbuntuBold.woff';
import UbuntuBoldWoff2 from '@astral/ui/fonts/UbuntuBold.woff2';
`

И внести соответствующие правки в конфиг сборщика для того, чтобы @astral/ui/fonts обрабатывались как шрифты.

$3


Пакет `@astral/illustrations` включен в пакет `@astral/ui`.

Необходимо заменить импорты:
`ts
import certImgSrc from '@astral/illustrations/cert.svg';
`

На:
`ts
import certImgSrc from '@astral/ui/illustrations/cert.svg';
`

И внести соответствующие правки в конфиг сборщика для того, чтобы @astral/ui/fonts обрабатывались как шрифты.

$3


Все элементы пакета `@astral/form` получили префиксы form.
Весь `@astral/form` теперь экспортируется из `@astral/ui`.

`ts
import { useForm, useFormWatch, useFormController } from '@astral/ui';
`

$3


Весь `@astral/icons` теперь экспортируется из `@astral/ui`.

`ts
import { QuitOutlineMd } from '@astral/ui';
`

$3

Компонент был удален, используйте ConfigProvider.

Troubleshooting

Медленно выполняются vitest тесты при импорте пакета

Для того чтобы ускорить выполнение vitest тестов, необходимо добавить следующий параметр conditions в vitest.config.ts:

`ts
///

import react from '@vitejs/plugin-react';
import { defineConfig } from 'vitest/config';
import tsconfigPaths from 'vite-tsconfig-paths';

export default defineConfig({
plugins: [react(), tsconfigPaths()],
resolve: {
conditions: ['vitest'],
},
test: {
environment: 'happy-dom',
},
});
`

В пакете есть специальное свойство exports.vitest, оптимизирующее парсинг пакета для vitest.
Исходна проблема: vitest плохо работает с barrel files.




utils

Table of contents

- redirectToLink




redirectToLink

Утилита для перехода по ссылке

`ts
import { redirectToLink } from '@astral/ui';

// Открытие ссылки в текущей вкладке или фрейме
redirectToLink('/');

// Открытие ссылки в новой вкладке
redirectToLink('/', '_blank')

``