@boltz.one/ui

UI kit dùng chung cho Super App Shell và mọi micro app. Mục tiêu: đồng nhất giao diện (theme, typography, antd overrides, components, helpers, icons) giữa core portal và các app con.

Package ship source .tsx (không build sẵn) — consumer (Vite + bundler resolution) tự biên dịch. Đây là pattern thống nhất với @boltz.one/sdk-web.

Cài đặt (trong monorepo)

// package.json của app
{
  "dependencies": {
    "@boltz.one/ui": "workspace:*"
  }
}

react, react-dom, antd, @ant-design/cssinjs, @carbon/icons-react là peerDependencies — app phải tự cài. Lý do: React và antd context phải là singleton xuyên shell + micro app, nếu bị bundle nhiều bản thì theme, message, modal toàn cục sẽ vỡ.

Cấu hình Tailwind (bắt buộc)

UI kit dùng class Tailwind. Consumer phải nạp preset và thêm src của package vào content, nếu không class sẽ bị purge:

// tailwind.config.ts
import type { Config } from 'tailwindcss';
import { uiPreset } from '@boltz.one/ui/tailwind-preset';

export default {
  presets: [uiPreset as Config],
  content: [
    './index.html',
    './src/**/*.{ts,tsx}',
    // đường dẫn tương đối tới @boltz.one/ui (điều chỉnh theo vị trí app)
    '../../core/packages/ui/src/**/*.{ts,tsx}',
  ],
  plugins: [],
} satisfies Config;

Nạp stylesheet nền (Tailwind directives + antd overrides + font IBM Plex Sans):

/* src/styles/globals.css */
@import '@boltz.one/ui/styles/globals.css';
/* override riêng của app đặt bên dưới */

Bọc providers

import { AntdConfigProvider, resolveAntdLocale } from '@boltz.one/ui';
import { useTranslation } from 'react-i18next';

function AppProviders({ children }) {
  const { i18n } = useTranslation();
  return (
    <AntdConfigProvider locale={resolveAntdLocale(i18n.language)}>
      {children}
    </AntdConfigProvider>
  );
}

AntdConfigProvider đã gắn globalTheme mặc định + App context + extractor nạp message/modal/notification vào singleton.

Subpath exports

| Import | Nội dung | |---|---| | @boltz.one/ui | Re-export tiện lợi: theme, providers, components, layout, hooks, utils | | @boltz.one/ui/theme | globalTheme, ANTD_LOCALES, resolveAntdLocale | | @boltz.one/ui/providers | AntdConfigProvider, baseMessage/baseModal/baseNotification, setAntdStatic | | @boltz.one/ui/components | BaseTagStatus, BaseFullScreenSpin | | @boltz.one/ui/layout | SideNav (headless), computeMenuState | | @boltz.one/ui/hooks | useDisclosure | | @boltz.one/ui/utils | formatCurrency, capitalizeText, truncateDisplayValue, cn | | @boltz.one/ui/icons | Icon SVG dùng chung (login/payment) — yêu cầu vite-plugin-svgr | | @boltz.one/ui/styles/globals.css | Stylesheet nền | | @boltz.one/ui/tailwind-preset | Preset Tailwind dùng chung |

./icons và ./styles cố tình không nằm trong entry chính @boltz.one/ui để app không bắt buộc phải có svgr / xử lý CSS chỉ vì import component.

Gọi message/notification ngoài React tree

import { baseNotification } from '@boltz.one/ui/providers';
baseNotification.error({ title: 'Có lỗi xảy ra' });

Nguyên tắc đóng góp

• Component trong components/ phải thuần — không import store/router/i18n của app. Cần điều hướng/ text dịch → nhận qua props (xem SideNav headless).
• Không kéo business logic, không gọi API, không phụ thuộc apps/*.
• Theme là nguồn duy nhất (theme/tokens.ts) — không copy token sang app.