Skip to content

Commit 253e521

Browse files
hckhanhhckhanh
authored
Enhance README and initialize documentation foundation (#46)
* Initialize documentation directory Added `.gitignore`, `README.md`, and initial support files under the `docs` directory. Configured Biome for linting and formatting, and included a `bun.lock` file to manage dependencies. This sets up the foundation for project documentation. * Update README and expand API documentation Revised the README file to improve clarity, consistency, and grammar. Added new sections in the API documentation covering installation, usage examples, and Vietnamese language rules. Updated dependencies and included `vn-number` for better integration. * Add dynamic `ReadVnNumber` component and update docs Introduced `ReadVnNumber` component for interactive Vietnamese number reading example. Replaced tab-based code samples with dynamic input field for better user engagement. Adjusted Biome configuration and updated class ordering in layout for consistency.
1 parent 014b6b1 commit 253e521

30 files changed

+4725
-102
lines changed

‎README.md‎

Lines changed: 142 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# vn-number 🇻🇳
1+
# vn-number
22

3-
🛠 A bunch of utility functions that work with number in 🇻🇳 Vietnamese language
3+
A bunch of utility functions that work with numbers in Vietnamese language.
44

55
[![Publish](https://github.com/hckhanh/vn-number/actions/workflows/publish.yml/badge.svg)](https://github.com/hckhanh/vn-number/actions/workflows/publish.yml)
66
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=hckhanh_vn-number&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=hckhanh_vn-number)
@@ -14,45 +14,167 @@
1414
- Built-in support for Edge runtime
1515
- Typesafe with TypeScript
1616
- Fully documented
17+
- Works with `number`, `string`, and `bigint` types
18+
- Handles very large numbers (up to quintillions)
1719

18-
## Functions
20+
## Installation
1921

20-
### Read Vietnamese number
22+
```bash
23+
npm install vn-number
24+
```
25+
26+
```bash
27+
deno add jsr:@hckhanh/vn-number
28+
```
29+
30+
## Quick Start
31+
32+
### Read Vietnamese Numbers
33+
34+
Convert numbers to Vietnamese text:
35+
36+
```ts
37+
import { readVnNumber } from 'vn-number'
38+
39+
readVnNumber(1250000)
40+
// Output: "một triệu hai trăm năm mươi nghìn"
41+
42+
readVnNumber(15)
43+
// Output: "mười lăm"
44+
45+
readVnNumber(21)
46+
// Output: "hai mươi mốt"
47+
```
48+
49+
### Format Numbers in Vietnamese Style
50+
51+
Format numbers with Vietnamese thousand separators (dots):
52+
53+
```ts
54+
import { formatVnNumber } from 'vn-number'
55+
56+
formatVnNumber(1250000)
57+
// Output: "1.250.000"
58+
59+
formatVnNumber(BigInt('9999999999999999'))
60+
// Output: "9.999.999.999.999.999"
61+
```
62+
63+
### Format Vietnamese Currency (VND)
64+
65+
Format numbers as Vietnamese Dong currency:
66+
67+
```ts
68+
import { formatVnCurrency } from 'vn-number'
69+
70+
formatVnCurrency(1250000)
71+
// Output: "1.250.000 ₫"
72+
73+
formatVnCurrency(null, 'Không giới hạn')
74+
// Output: "Không giới hạn"
75+
```
76+
77+
### Format Percentages
78+
79+
Format numbers as Vietnamese-style percentages:
2180

2281
```ts
23-
import { readVnNumber } from '@hckhanh/vn-number'
82+
import { formatVnPercent } from 'vn-number'
83+
84+
formatVnPercent(0.991)
85+
// Output: "99,1%"
2486

25-
const result = readVnNumber(1250000)
26-
console.log(result) // một triệu hai trăm năm mươi nghìn
87+
formatVnPercent(0.5)
88+
// Output: "50%"
2789
```
2890

29-
### Format number in Vietnamese format
91+
## Documentation
92+
93+
For detailed documentation, examples, and API reference, visit:
94+
95+
**[https://vn-number.khanh.id](https://vn-number.khanh.id)**
96+
97+
## Common Use Cases
98+
99+
### E-commerce
30100

31101
```ts
32-
import { formatVnNumber } from '@hckhanh/vn-number'
102+
import { formatVnCurrency, readVnNumber } from 'vn-number'
103+
104+
const price = 1500000
105+
106+
console.log(formatVnCurrency(price))
107+
// Output: "1.500.000 ₫"
33108

34-
const result = formatVnNumber(1250000)
35-
console.log(result) // 1.250.000
109+
console.log(readVnNumber(price))
110+
// Output: "một triệu năm trăm nghìn"
36111
```
37112

38-
### Format VN currency (VND - ₫)
113+
### Banking and Financial Documents
39114

40115
```ts
41-
import { formatVnCurrency } from '@hckhanh/vn-number'
116+
import { readVnNumber, formatVnCurrency } from 'vn-number'
42117

43-
const result = formatVnCurrency(1250000)
44-
console.log(result) // 1.250.000 ₫
118+
const amount = 2450000
119+
120+
console.log(`Số tiền: ${formatVnCurrency(amount)}`)
121+
// Output: "Số tiền: 2.450.000 ₫"
122+
123+
console.log(`Bằng chữ: ${readVnNumber(amount)} đồng`)
124+
// Output: "Bằng chữ: hai triệu bốn trăm năm mươi nghìn đồng"
45125
```
46126

47-
### Format percentage in Vietnamese format
127+
### Data Visualization
48128

49129
```ts
50-
import { formatVnPercent } from '@hckhanh/vn-number'
130+
import { formatVnNumber, formatVnPercent } from 'vn-number'
131+
132+
const totalUsers = 1234567
133+
const growthRate = 0.157
51134

52-
const result = formatVnPercent(0.991)
53-
console.log(result) // 99,1%
135+
console.log(`Tổng người dùng: ${formatVnNumber(totalUsers)}`)
136+
// Output: "Tổng người dùng: 1.234.567"
137+
138+
console.log(`Tăng trưởng: ${formatVnPercent(growthRate)}`)
139+
// Output: "Tăng trưởng: 15,7%"
54140
```
55141

142+
## Vietnamese Language Rules
143+
144+
The `readVnNumber` function follows Vietnamese language conventions:
145+
146+
- **"lăm" rule**: 15 → "mười lăm", 25 → "hai mươi lăm"
147+
- **"mốt" rule**: 21 → "hai mươi mốt", 31 → "ba mươi mốt"
148+
- **"lẻ" rule**: 101 → "một trăm lẻ một", 305 → "ba trăm lẻ năm"
149+
- **Zero handling**: 1001 → "một nghìn không trăm lẻ một"
150+
151+
## API Functions
152+
153+
| Function | Description | Example |
154+
|----------|-------------|---------|
155+
| `readVnNumber(number)` | Convert number to Vietnamese text | `readVnNumber(1250000)` → `"một triệu hai trăm năm mươi nghìn"` |
156+
| `formatVnNumber(number, fallback?)` | Format number in Vietnamese style | `formatVnNumber(1250000)` → `"1.250.000"` |
157+
| `formatVnCurrency(money, fallback?)` | Format as VND currency | `formatVnCurrency(1250000)` → `"1.250.000 ₫"` |
158+
| `formatVnPercent(value, fallback?)` | Format as percentage | `formatVnPercent(0.991)` → `"99,1%"` |
159+
160+
## Browser and Runtime Compatibility
161+
162+
- ✅ Node.js 14+
163+
- ✅ Bun
164+
- ✅ Deno
165+
- ✅ Modern browsers (Chrome, Firefox, Safari, Edge)
166+
- ✅ React Native
167+
- ✅ Electron
168+
- ✅ Edge Runtime (Vercel, Cloudflare Workers, etc.)
169+
170+
## Contributing
171+
172+
Contributions are welcome! Please feel free to submit a Pull Request.
173+
174+
## License
175+
176+
MIT © [Khánh Hoàng](https://www.khanh.id)
177+
56178
## Release Notes
57179

58-
You can go to [the Releases](https://github.com/hckhanh/vn-number/releases) page to see the release notes.
180+
See [Releases](https://github.com/hckhanh/vn-number/releases) for changelog and release notes.

‎docs/.gitignore‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# deps
2+
/node_modules
3+
4+
# generated content
5+
.source
6+
7+
# test & build
8+
/coverage
9+
/.next/
10+
/out/
11+
/build
12+
*.tsbuildinfo
13+
14+
# misc
15+
.DS_Store
16+
*.pem
17+
/.pnp
18+
.pnp.js
19+
npm-debug.log*
20+
yarn-debug.log*
21+
yarn-error.log*
22+
23+
# others
24+
.env*.local
25+
.vercel
26+
next-env.d.ts

‎docs/README.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# web
2+
3+
This is a Next.js application generated with
4+
[Create Fumadocs](https://github.com/fuma-nama/fumadocs).
5+
6+
Run development server:
7+
8+
```bash
9+
npm run dev
10+
# or
11+
pnpm dev
12+
# or
13+
yarn dev
14+
```
15+
16+
Open http://localhost:3000 with your browser to see the result.
17+
18+
## Explore
19+
20+
In the project, you can see:
21+
22+
- `lib/source.ts`: Code for content source adapter, [`loader()`](https://fumadocs.dev/docs/headless/source-api) provides the interface to access your content.
23+
- `lib/layout.shared.tsx`: Shared options for layouts, optional but preferred to keep.
24+
25+
| Route | Description |
26+
| ------------------------- | ------------------------------------------------------ |
27+
| `app/(home)` | The route group for your landing page and other pages. |
28+
| `app/docs` | The documentation layout and pages. |
29+
| `app/api/search/route.ts` | The Route Handler for search. |
30+
31+
### Fumadocs MDX
32+
33+
A `source.config.ts` config file has been included, you can customise different options like frontmatter schema.
34+
35+
Read the [Introduction](https://fumadocs.dev/docs/mdx) for further details.
36+
37+
## Learn More
38+
39+
To learn more about Next.js and Fumadocs, take a look at the following
40+
resources:
41+
42+
- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js
43+
features and API.
44+
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
45+
- [Fumadocs](https://fumadocs.dev) - learn about Fumadocs

‎docs/biome.json‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
{
2+
"$schema": "../node_modules/@biomejs/biome/configuration_schema.json",
3+
"extends": "//",
4+
"root": false,
5+
"files": {
6+
"ignoreUnknown": true,
7+
"includes": ["**", "!node_modules", "!.next", "!dist", "!build", "!.source"]
8+
},
9+
"linter": {
10+
"enabled": true,
11+
"rules": {
12+
"recommended": true,
13+
"style": {
14+
"useConsistentCurlyBraces": {
15+
"level": "warn",
16+
"fix": "safe"
17+
}
18+
},
19+
"security": {
20+
"noDangerouslySetInnerHtml": "off"
21+
},
22+
"nursery": {
23+
"useSortedClasses": {
24+
"level": "warn",
25+
"fix": "safe"
26+
}
27+
}
28+
},
29+
"domains": {
30+
"next": "recommended",
31+
"react": "recommended"
32+
}
33+
},
34+
"assist": {
35+
"actions": {
36+
"source": {
37+
"useSortedAttributes": "on"
38+
}
39+
}
40+
},
41+
"css": {
42+
"parser": {
43+
"tailwindDirectives": true
44+
}
45+
},
46+
"javascript": {
47+
"formatter": {
48+
"jsxQuoteStyle": "single"
49+
}
50+
}
51+
}

0 commit comments

Comments
 (0)