@astral/ui
@astral/ui - это UI-KIT, на основе которого строятся интерфейсы в Астрал-Софт.
Table of contents
- Storybook
- Introduction
- Playground
- Getting started with Next.js
- Migration guide
- Troubleshooting
- 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
npm --save @astral/ui
global.d.ts
/// <reference types="@astral/ui/declarations" />
next.config
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
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 (
<>
<Head>
<meta
name="viewport"
content="width=device-width, initial-scale=1, shrink-to-fit=no"
/>
<title>Astral.Example</title>
</Head>
<StylesCacheProvider value={stylesCache}>
<ConfigProvider
captureException={monitoringErrorService.captureException}
>
<ThemeProvider theme={theme}>
<NotificationContainer />
<MainLayout>
<Component {...pageProps} />
</MainLayout>
</ThemeProvider>
</ConfigProvider>
</StylesCacheProvider>
</>
);
};
export default App;
Migration guide
3.0.0 -> 4.0.0
Fonts
Подключение шрифтов через объект theme больше не поддерживается.
Шрифты необходимо подключать через сервис для хранения статичных файлов
Инструкция для подключения шрифтов
⚠️ Для подключения шрифтов необходимо настроить Content Security Policy.
2.0.0 -> 3.0.0
ConfigProvider
В ConfigProvider добавлен prop imagesMap:
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
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 (
<ConfigProvider
imagesMap={{
defaultErrorImgSrc: errorImgSrc,
noDataImgSrc,
outdatedReleaseErrorImgSrc,
}}
>
<ThemeProvider>
<Layout />
</ThemeProvider>
</ConfigProvider>
);
};
Typography
Breaking changes:
- Удалены пропсы, которые являлись css правилами (margin, border, mr...)
- Prop
colorпринимает толькоstring. Удалена возможность использовать для color функцию
Актуальные props находятся здесь.
Grid
Grid из @astral/ui v2 был переименован в LegacyGrid, в четвертой версии @astral/ui данный компонент будет удален.
Сигнатуру нового Grid вы можете увидеть в storybook.
Form
Breaking changes:
- Была удалена дефолтная валидация для компонентов:
FormDatePicker,FormMobilePhoneField - Для филдов формы был удален props
rules. Для валидации форм используйте валидацию по схеме с помощью библиотеки @astral/validations
1.0.0 -> 2.0.0
Deps
Теперь пакет @astral/ui аккумулирует и реэкспортит пакеты:
@astral/fonts@astral/illustrations@astral/icons@astral/form@astral/components
Необходимо заменить зависимости:
{
...
"@astral/icons": "^1.19.4",
"@astral/form": "^1.19.4",
"@astral/fonts": "^1.19.4",
"@astral/ui": "^1.19.4",
...
}
На:
{
...
"@astral/ui": "^1.19.4",
...
}
global.d.ts
Заменить файл global.d.ts:
global.d.ts
/// <reference types="@astral/ui/declaration/emotion" />
/// <reference types="@astral/ui/declaration/mui-material" />
/// <reference types="@emotion/react/types/css-prop" />
На:
global.d.ts
/// <reference types="@astral/ui/declarations" />
fonts
Пакет @astral/fonts включен в пакет @astral/ui.
Необходимо заменить импорты:
import UbuntuBoldWoff from '@astral/fonts/UbuntuBold.woff';
import UbuntuBoldWoff2 from '@astral/fonts/UbuntuBold.woff2';
На:
import UbuntuBoldWoff from '@astral/ui/fonts/UbuntuBold.woff';
import UbuntuBoldWoff2 from '@astral/ui/fonts/UbuntuBold.woff2';
И внести соответствующие правки в конфиг сборщика для того, чтобы @astral/ui/fonts обрабатывались как шрифты.
illustrations
Пакет @astral/illustrations включен в пакет @astral/ui.
Необходимо заменить импорты:
import certImgSrc from '@astral/illustrations/cert.svg';
На:
import certImgSrc from '@astral/ui/illustrations/cert.svg';
И внести соответствующие правки в конфиг сборщика для того, чтобы @astral/ui/fonts обрабатывались как шрифты.
@astral/form
Все элементы пакета @astral/form получили префиксы form.
Весь @astral/form теперь экспортируется из @astral/ui.
import { useForm, useFormWatch, useFormController } from '@astral/ui';
@astral/icons
Весь @astral/icons теперь экспортируется из @astral/ui.
import { QuitOutlineMd } from '@astral/ui';
DatePickerProvider
Компонент был удален, используйте ConfigProvider.
Troubleshooting
Медленно выполняются vitest тесты при импорте пакета
Для того чтобы ускорить выполнение vitest тестов, необходимо добавить следующий параметр conditions в vitest.config.ts:
/// <reference types="vitest" />
import react from '@vitejs/plugin-react-swc';
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
Утилита для перехода по ссылке
import { redirectToLink } from '@astral/ui';
// Открытие ссылки в текущей вкладке или фрейме
redirectToLink('/');
// Открытие ссылки в новой вкладке
redirectToLink('/', '_blank')