harito-ui
Version:
A modern, transparent UI library for React.
311 lines (233 loc) • 10.4 kB
Markdown
# Harito UI
## Chú ý chạy khi CI/CD
```bash
npm run build
```
trước khi CI/CD để đảm bảo rằng các tệp tĩnh đã được tạo ra thành công và public được lên NPM.
## Để hiểu rõ project
- `docs/ProjectStructure.md`: Giải thích cấu trúc thư mục và vai trò của các file quan trọng trong dự án Harito UI Web.
- `docs/GuideUse.md`: Hướng dẫn sử dụng thư viện Harito UI trong các dự án React.
---
## GuideUse
### HaritoUI Library Usage Guide
This guide provides comprehensive instructions on how to integrate and effectively use the HaritoUI library in your React projects. HaritoUI is designed to be a modern, accessible, and highly customizable UI component library, offering sensible defaults while allowing for extensive overrides.
#### 1. Introduction to HaritoUI
HaritoUI is a React component library built with TypeScript, focusing on reusability, performance, and a clean design. It provides a set of pre-built UI components, a flexible theming system, and integrated services for common web functionalities like analytics and SEO.
#### 2. Installation
To use HaritoUI in your project, install it via npm or yarn:
```bash
npm install harito-ui
# or
yarn add harito-ui
```
### Peer Dependencies
Harito UI requires several peer dependencies to be installed in your host project. Your project must use compatible versions.
**Install the required peer dependencies using npm:**
```bash
npm install react@^19.1.0 react-dom@^19.1.0 /material@^5.15.20 @emotion/react@^11.11.4 /styled@^11.11.5
```
**Or using yarn:**
```bash
yarn add react@^19.1.0 react-dom@^19.1.0 /material@^5.15.20 @emotion/react@^11.11.4 /styled@^11.11.5
```
#### 3. Global Configuration
HaritoUI uses a centralized configuration system that allows you to define global settings for your application, including tracking IDs, SEO defaults, and footer content. This system provides sensible defaults, which you can easily override.
##### 3.1. Initializing Configuration
At the entry point of your application (e.g., `src/main.tsx` or `src/index.tsx`), you must initialize the configuration **before** rendering your React application.
```typescript
// src/index.tsx (or src/main.tsx)
import React from "react";
import { createRoot } from "react-dom/client";
import App from "./App";
import { ThemeProvider } from "./contexts/ThemeContext.tsx";
import { HelmetProvider } from "react-helmet-async";
import { initialize } from "./config"; // Import the initialize function
import "./styles/globals.css";
// Initialize the app configuration
// You can override any default settings here.
initialize({
seo: {
title: "My Awesome Project", // Override default title
description: "This is a custom description for my project.",
},
tracking: {
googleAnalyticsId: "G-YOUR_GA_ID", // Replace with your actual GA ID
googleAdsenseId: "ca-pub-YOUR_ADSENSE_ID", // Replace with your actual AdSense ID
vercelAnalytics: true, // Enable/disable Vercel Analytics
},
footer: {
companyName: "My Company Inc.", // Override default company name
socialLinks: [
// Add or override social links
{ platform: "github", url: "https://github.com/my-company" },
],
},
});
const container = document.getElementById("root");
if (container) {
const root = createRoot(container);
root.render(
<React.StrictMode>
<HelmetProvider>
<ThemeProvider>
<App />
</ThemeProvider>
</HelmetProvider>
</React.StrictMode>
);
} else {
console.error("Root container not found");
}
```
##### 3.2. Accessing Configuration
Any component within your application can access the current configuration using the `getConfig()` function:
```typescript
// Example: Accessing footer config in Footer.tsx
import { getConfig } from "../../config";
const Footer: React.FC = () => {
const config = getConfig().footer;
// ... use config.companyName, config.socialLinks, etc.
};
```
#### 4. Asset Management (SVG Logo & Flags)
HaritoUI encourages the use of SVG for scalable assets like logos and flags. These are managed directly within the `src/assets` directory and imported as React components or URLs.
##### 4.1. Logo
Your main logo should be placed at `src/assets/logo/logo.svg`. It is then exposed as a React component via `src/assets/logo/index.tsx`.
```typescript
// src/assets/logo/index.tsx
import React from 'react';
import LogoSvg from './logo.svg?react'; // Vite-specific import for SVG as React component
interface LogoProps extends React.SVGProps<SVGSVGElement> {
size?: number;
}
const Logo: React.FC<LogoProps> = ({ size = 32, ...props }) => {
return <LogoSvg width={size} height={size} {...props} />;
};
export default Logo;
```
You can then use this `Logo` component in your `Header` or anywhere else:
```typescript
// In MainLayout.tsx
import Logo from "../assets/logo";
// ... inside Header props
logo={{
node: <Logo size={40} />,
alt: "Your Company Logo",
link: "/",
}}
```
##### 4.2. Favicon
The favicon is automatically managed by `MainLayout` using the `logo.svg` file. It imports the SVG as a URL and sets it via `react-helmet-async`. Ensure your `logo.svg` is suitable for use as a favicon.
```typescript
// In MainLayout.tsx
import favicon from "../assets/logo/logo.svg"; // Favicon URL from your logo SVG
// ... inside Helmet
<Helmet>
{/* ... other meta tags */}
<link rel="icon" type="image/svg+xml" href={favicon} />
</Helmet>
```
##### 4.3. Flags
Flag SVGs are located in `src/assets/flags/` and exported via `src/assets/flags/index.ts` using Vite's `?react` suffix, allowing them to be used as React components.
```typescript
// src/assets/flags/index.ts
export { default as UkCir } from "./uk-cir.svg?react";
export { default as VietnamCir } from "./vietnam-cir.svg?react";
// ... other flags
```
You can then pass these components to the `Header`'s `languageSelector`:
```typescript
// In MainLayout.tsx
import { UkCir, VietnamCir, FranceCir } from "../assets/flags";
// ... inside Header props
languageSelector={[
{ code: "en", label: "English", flag: <UkCir /> },
{ code: "vi", label: "Tiếng Việt", flag: <VietnamCir /> },
{ code: "fr", label: "Français", flag: <FranceCir /> },
]}
```
#### 5. SEO and Head Management
HaritoUI leverages `react-helmet-async` through its `MainLayout` component to provide dynamic SEO capabilities for your Single Page Application (SPA).
##### 5.1. Default SEO
Default `title`, `description`, and `keywords` are defined in `src/config/default.ts`.
##### 5.2. Page-Specific SEO
You can override these defaults for specific pages by passing `title`, `description`, and `keywords` props to the `MainLayout` component:
```typescript
// In App.tsx (or any page component)
import MainLayout from "./layouts/MainLayout";
const App: React.FC = () => {
return (
<MainLayout
title="My Custom Page Title"
description="This is a unique description for this specific page."
keywords="custom, page, keywords"
>
{/* Page content goes here */}
</MainLayout>
);
};
```
#### 6. Tracking & Analytics Services
HaritoUI includes a centralized `tracking` service (`src/services/tracking.ts`) that integrates with Google Analytics, Google AdSense, Vercel Analytics, and fetches detailed IP information.
##### 6.1. Configuration
Tracking IDs and settings are configured in `src/config/default.ts` and can be overridden during `initialize()`:
```typescript
// In src/config/default.ts
export const defaultConfig = {
tracking: {
googleAnalyticsId: "G-XXXXXXXXXX",
googleAdsenseId: "ca-pub-XXXXXXXXXXXXXXXX",
vercelAnalytics: true,
},
// ...
};
```
##### 6.2. IP Information to Google Analytics
The `tracking` service automatically fetches IP information (ISP, Organization) using `ip-api.com` and sends it to Google Analytics as custom dimensions.
**Important:** To view this data in Google Analytics, you must configure Custom Dimensions in your GA4 property:
1. Go to **Admin** -> **Custom definitions**.
2. Create new **Custom dimensions** with the following settings:
- **Scope:** Event
- **Event parameter:** `ip_address` (for IP address)
- **Event parameter:** `isp` (for Internet Service Provider)
- **Event parameter:** `organization` (for Organization/Company)
This allows you to analyze user demographics beyond just city/country, providing insights into the types of networks or organizations accessing your site.
#### 7. Using Components
HaritoUI components are organized into `basic`, `composite`, and `page-level` categories.
```typescript
// Example: Importing a basic component
import ThemedButton from "./components/basic/ThemedButton";
// Example: Importing a composite component
import ThemedCard from "./components/composite/ThemedCard";
// Example: Importing a page-level component
import Header from "./components/page-level/Header";
```
Refer to the `src/components` directory for a full list of available components and their respective props.
#### 8. Sample Application Structure
A typical application using HaritoUI would follow this structure:
```
src/
├── App.tsx // Your main application content, wrapped by MainLayout
├── index.tsx // Entry point, initializes config and renders App
├── assets/
│ ├── flags/ // SVG flag components
│ │ └── index.ts
│ └── logo/ // SVG logo component
│ └── index.tsx
│ └── logo.svg
├── components/ // Reusable UI components
│ ├── basic/
│ ├── composite/
│ └── page-level/
├── config/ // Global configuration
│ ├── default.ts // Default settings
│ └── index.ts // Configuration manager (initialize, getConfig)
├── contexts/ // React Contexts (e.g., ThemeContext)
├── layouts/ // Reusable page layouts
│ └── MainLayout.tsx // Main layout with Header, Footer, SEO, Favicon
├── services/ // Utility services (e.g., tracking)
│ └── tracking.ts
└── styles/
└── globals.css // Global CSS variables and styles
```
By following this guide, you can effectively integrate and customize HaritoUI to build robust and modern React applications.