fpts-font-lib

v1.2.7

Published

3 months ago

FPT Securities Font Library with Material-UI Theme

0High
0Medium
0Low

tneilss

fpts font theme material-ui typography

FPT Securities Font Library

Thư viện font và theme tùy chỉnh cho FPT Securities, được xây dựng trên Material-UI.

Cài đặt

npm install fpts-font-lib

Lưu ý: Thư viện này sử dụng peer dependencies, bạn cần cài đặt các dependencies sau:

npm install @mui/material @emotion/react @emotion/styled react react-dom

Setup TypeScript (Quan trọng!)

Để TypeScript nhận diện được các custom theme properties, bạn CHỈ CẦN COPY 1 FILE DUY NHẤT:

Bước 1: Copy file template

Trong thư viện có sẵn file template.fpts-types.d.ts. Copy file này vào thư mục src/ của project và đổi tên thành fpts-types.d.ts:

# Nếu đã cài đặt thư viện qua npm
cp node_modules/fpts-font-lib/template.fpts-types.d.ts src/fpts-types.d.ts

Hoặc tạo file src/fpts-types.d.ts với nội dung:

import "@mui/material/styles";
import type { CustomPaletteExtension, CustomTypographyPropsVariantOverrides, CustomTypographyVariants, CustomTypographyVariantsOptions } from "fpts-font-lib";

declare module "@mui/material/styles" {
  interface BreakpointOverrides {
    laptop: true;
  }

  // Extend Palette với custom colors từ fpts-font-lib
  interface Palette extends CustomPaletteExtension {}
  interface PaletteOptions extends CustomPaletteExtension {}

  // Extend Typography với custom variants từ fpts-font-lib
  interface TypographyVariants extends CustomTypographyVariants {}
  interface TypographyVariantsOptions extends CustomTypographyVariantsOptions {}
}

declare module "@mui/material/Typography" {
  // Extend Typography props với custom variant overrides từ fpts-font-lib
  interface TypographyPropsVariantOverrides extends CustomTypographyPropsVariantOverrides {}
}

declare module "@mui/material/Button" {
  interface ButtonPropsVariantOverrides {
    primary: true;
    secondary: true;
    danger: true;
    ghostPrimary: true;
    ghostSecondary: true;
  }
  interface ButtonPropsSizeOverrides {
    xlarge: true;
    large: true;
    xsmall: true;
  }
}

declare module "@mui/material/TextField" {
  interface TextFieldPropsSizeOverrides {
    xlarge: true;
    large: true;
  }
}

declare module "@mui/material/Chip" {
  interface ChipPropsSizeOverrides {
    large: true;
  }
  interface ChipOwnProps {
    type?: "filter" | "assist" | "input" | "suggestion";
  }
}

declare module "@mui/material/Badge" {
  interface BadgeOwnProps {
    size?: "xsmall" | "small" | "medium" | "large";
    type?: "rounded" | "square";
  }
}

Lợi ích:

✅ Cực kỳ đơn giản: Chỉ cần copy 1 file duy nhất, không cần định nghĩa lại
✅ Sử dụng interface helper: CustomPaletteExtension giúp giảm boilerplate code
✅ Type-safe: TypeScript sẽ nhận diện tất cả custom properties
✅ Dễ maintain: Khi thư viện cập nhật, chỉ cần update lại file này

Tại sao cần file này?

Do giới hạn của TypeScript, module augmentation không thể tự động apply mà cần phải có file declaration trong project consumer. Đây là cách duy nhất để TypeScript nhận diện custom types từ thư viện.

Sử dụng

1. Tạo Theme

import { createTheme, ThemeProvider } from "@mui/material/styles";
import { colorCustom, fontCustom, FONT_FAMILY } from "fpts-font-lib";

const theme = createTheme({
  palette: {
    mode: "light",
    ...colorCustom,
  },
  typography: {
    fontFamily: FONT_FAMILY,
    ...fontCustom,
  },
  breakpoints: {
    values: {
      xs: 0,
      sm: 600,
      md: 900,
      lg: 1200,
      xl: 1536,
      laptop: 1440, // Custom breakpoint
    },
  },
});

function App() {
  return <ThemeProvider theme={theme}>{/* Your app */}</ThemeProvider>;
}

2. Sử dụng Custom Colors

import { Box } from "@mui/material";

function MyComponent() {
  return (
    <Box
      sx={{
        backgroundColor: (theme) => theme.palette.customBase?.baseWhite,
        color: (theme) => theme.palette.customPrimary?.primary50,
      }}>
      Content with custom colors
    </Box>
  );
}

3. Sử dụng Custom Typography

import { Typography } from "@mui/material";

function MyComponent() {
  return (
    <div>
      <Typography variant="heading48-B56">Tiêu đề lớn</Typography>
      <Typography variant="body16-M24">Nội dung văn bản</Typography>
      <Typography variant="sub12-R18">Text phụ</Typography>
    </div>
  );
}

4. Sử dụng Custom Button Variants

import { Button } from "@mui/material";

function MyComponent() {
  return (
    <div>
      <Button variant="primary" size="xlarge">
        Primary Button
      </Button>
      <Button variant="secondary" size="large">
        Secondary Button
      </Button>
      <Button variant="danger">Danger Button</Button>
      <Button variant="ghostPrimary" size="xsmall">
        Ghost Button
      </Button>
    </div>
  );
}

5. Sử dụng Custom TextField Sizes

import { TextField } from "@mui/material";

function MyComponent() {
  return (
    <div>
      <TextField label="XLarge TextField" size="xlarge" variant="outlined" />
      <TextField label="Large TextField" size="large" variant="outlined" />
      <TextField label="Default TextField" variant="outlined" />
    </div>
  );
}

6. Sử dụng Custom Chip Types

import { Chip } from "@mui/material";

function MyComponent() {
  return (
    <div>
      <Chip label="Filter Chip" type="filter" size="large" />
      <Chip label="Assist Chip" type="assist" size="large" />
      <Chip label="Input Chip" type="input" size="large" />
      <Chip label="Suggestion Chip" type="suggestion" size="large" />
    </div>
  );
}

7. Sử dụng Custom Badge

import { Badge, Box } from "@mui/material";

function MyComponent() {
  return (
    <div>
      <Badge badgeContent={4} size="xsmall" type="rounded">
        <Box sx={{ width: 40, height: 40, bgcolor: "grey.300" }} />
      </Badge>
      <Badge badgeContent={4} size="large" type="square">
        <Box sx={{ width: 40, height: 40, bgcolor: "grey.300" }} />
      </Badge>
    </div>
  );
}

8. Sử dụng Custom Breakpoint

import { Box } from "@mui/material";

function MyComponent() {
  return (
    <Box
      sx={{
        backgroundColor: "blue",
        [theme.breakpoints.up("laptop")]: {
          backgroundColor: "purple",
        },
      }}>
      This box changes color on laptop breakpoint (1440px+)
    </Box>
  );
}

API Reference

Exported Types

import type {
  CustomBaseColors,
  CustomPrimaryColors,
  CustomSemanticColors,
  CustomSupportColors,
  CustomAdditionalColors,
  CustomLogoFPTColors,
  CustomPaletteExtension,
  ExtendedPaletteOptions,
} from "fpts-font-lib";

colorCustom

Object chứa tất cả các màu sắc tùy chỉnh:

Custom Base Colors

baseWhite, base10, base15, base20, base25, base30
base40, base45, base50, base55, base60, base70
base80, base90, baseBlack

Custom Primary Colors

primary10, primary20, primary30, primary40
primary50, primary60, primary70, primary80

Custom Semantic Colors

Mỗi màu có 5 shades: lighter, light, default, dark, darker

customRed - Màu đỏ
customGreen - Màu xanh lá
customOrange - Màu cam
customPurple - Màu tím
customBlue - Màu xanh dương
customYellow - Màu vàng
customTeal - Màu xanh ngọc

Custom Support Colors

Màu hỗ trợ với các opacity levels:

primary5001, primary5003, primary5005
greendefault01, greendefault03, greendefault05
reddefault01, reddefault03, reddefault05
orangedefault01, orangedefault03, orangedefault05
purpledefault01, purpledefault03, purpledefault05
bluedefault01, bluedefault03, bluedefault05
yellowdefault01, yellowdefault03, yellowdefault05
primary25

Custom Additional Colors

Màu bổ sung với opacity:

baseWhite03, base2006, base4003, base5003
base6006, base8003, base8006, base8008

Custom Logo FPT Colors

blue - #0066B3
orange - #F36F21
green - #22B24C

fontCustom

Object chứa tất cả các typography variants:

Headings

heading48-B56 - 48px Bold, line-height 56px
heading32-S40 - 32px SemiBold, line-height 48px
heading28-S42 - 28px SemiBold, line-height 1.5
heading24-B36 - 24px Bold, line-height 1.5
heading24-S36 - 24px SemiBold, line-height 1.5
heading20-S30 - 20px SemiBold, line-height 1.5
heading18-B27 - 18px Bold, line-height 1.5
heading18-M27-I - 18px Medium Italic, line-height 1.5

Body

body16-B24 - 16px Bold, line-height 1.5
body16-S24 - 16px SemiBold, line-height 1.5
body16-M24 - 16px Medium, line-height 1.5
body16-R24 - 16px Regular, line-height 1.5
body16-R24-U - 16px Regular Underline, line-height 1.5
body16-M24-I - 16px Medium Italic, line-height 1.5
body14-B21 - 14px Bold, line-height 1.5
body14-S21 - 14px SemiBold, line-height 1.5
body14-M21 - 14px Medium, line-height 1.5
body14-R21 - 14px Regular, line-height 1.5
body14-R21-U - 14px Regular Underline, line-height 1.5
body14-M21-I - 14px Medium Italic, line-height 1.5

Subtitles

sub12-B18 - 12px Bold, line-height 1.5
sub12-S18 - 12px SemiBold, line-height 1.5
sub12-M18 - 12px Medium, line-height 1.5
sub12-R18 - 12px Regular, line-height 1.5
sub12-R18-U - 12px Regular Underline, line-height 1.5
sub12-M18-I - 12px Medium Italic, line-height 1.5
sub10-M15 - 10px Medium, line-height 1.5

Custom Component Variants

Button

Variants: primary, secondary, danger, ghostPrimary, ghostSecondary
Sizes: xlarge, large, medium, small, xsmall

TextField

Sizes: xlarge, large, medium, small

Chip

Sizes: large, medium, small
Types: filter, assist, input, suggestion

Badge

Sizes: xsmall, small, medium, large
Types: rounded, square

Font Assets

import { FONT_FAMILY, fontAssetsPath } from "fpts-font-lib";

// Font family constant
console.log(FONT_FAMILY); // "Manrope Variable, sans-serif"

// Font assets path
console.log(fontAssetsPath); // "./assets/font/"

Example Project

Xem ví dụ đầy đủ trong thư mục example/ của repository.

Development

# Build
npm run build

# Type check
npm run build:tsc

# Backup version hiện tại
npm run backup

# Xem danh sách backups
npm run backups

# Rollback về version cũ
npm run rollback <version>

# Publish an toàn (auto-backup)
npm run safe-publish

🔄 Version Management & Rollback

Thư viện có hệ thống quản lý version và rollback an toàn. Xem chi tiết tại scripts/README.md

Quick Start

# 1. Backup trước khi thay đổi lớn
npm run backup

# 2. Xem các version đã backup
npm run backups

# 3. Rollback về version cũ nếu cần
npm run rollback 1.2.5

# 4. Publish an toàn với auto-backup
npm run safe-publish

Workflow khuyên dùng

Release version mới:

npm run safe-publish  # Auto backup + build + type check + publish
git tag v1.2.6
git push --tags

Khi có lỗi cần rollback:

npm run backups       # Xem các version có sẵn
npm run rollback 1.2.5  # Rollback về version ổn định
npm publish           # Publish lại version cũ (nếu cần)

License

ISC

Author

FPT Securities