@bug-on/md3-react 0.1.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +62 -165
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -2,76 +2,67 @@
2
2
 
3
3
  > ⚠️ **Work in progress** — Material Design 3 Expressive React Component Library
4
4
 
5
- Thư viện UI React với đầy đủ animation, accessible (a11y), hỗ trợ Next.js App Router.
5
+ A high-performance React UI component library built following the [Material Design 3 Expressive](https://m3.material.io/) design language. It brings smooth animations, robust accessibility (a11y), and first-class support for SSR and Next.js App Router.
6
6
 
7
- ## Installation
7
+ To function correctly with full access to Design Tokens (colors, typography, shape, elevation) and CSS utilities, the ecosystem is built across 3 core packages:
8
+ - `@bug-on/md3-react` (Component logic & UI)
9
+ - `@bug-on/md3-tailwind` (TailwindCSS v4 plugin providing the system's utilities)
10
+ - `@bug-on/md3-tokens` (Core CSS variables & Design tokens)
11
+
12
+ ---
13
+
14
+ ## 📦 Installation
15
+
16
+ Install the React component package alongside its required core packages:
8
17
 
9
18
  ```bash
10
- npm install @bug-on/md3-react
11
- # hoặc
12
- pnpm add @bug-on/md3-react
19
+ npm install @bug-on/md3-react @bug-on/md3-tailwind @bug-on/md3-tokens
20
+ # or
21
+ pnpm add @bug-on/md3-react @bug-on/md3-tailwind @bug-on/md3-tokens
13
22
  ```
14
23
 
15
- ## Peer Dependencies
16
-
24
+ Additionally, ensure you have the required **Peer Dependencies** installed in your project:
17
25
  ```bash
18
26
  npm install react react-dom
19
- # Optional (cho animated components):
27
+ # Optional (Required only if you intend to use animated components like Fab, Tabs, Dialog...):
20
28
  npm install motion
21
29
  ```
22
30
 
23
- ## Setup với TailwindCSS v4
24
-
25
- ```css
26
- /* globals.css */
27
- @import "@bug-on/md3-tailwind";
28
- ```
31
+ ---
29
32
 
30
- ## Usage
33
+ ## 🛠️ Setup & Configuration
31
34
 
32
- ```tsx
33
- import { Button, useRipple } from '@bug-on/md3-react';
35
+ This library relies strictly on **Tailwind CSS v4**. You must configure both the library's plugin and token system into your Tailwind and global CSS layers.
34
36
 
35
- export default function Page() {
36
- return (
37
- <Button colorStyle="filled" size="md">
38
- Get Started
39
- </Button>
40
- );
41
- }
42
- ```
43
-
44
- ## Components
45
-
46
- | Component | Description |
47
- |--------------|--------------------------------------------|
48
- | `Button` | MD3 Expressive button, 5 variants, 5 sizes |
49
- | `ButtonGroup`| Group toggle buttons |
50
- | `Card` | MD3 Card container |
51
- | `CodeBlock` | Syntax-highlighted code block |
52
- | `Icon` | Material Symbols variable font icon |
37
+ Add the following to your root CSS file (often `globals.css` or `index.css`):
53
38
 
54
- ## Icons
39
+ ```css
40
+ /* 1. Import Tailwind CSS core */
41
+ @import "tailwindcss";
55
42
 
56
- `<Icon />` renders [Material Symbols](https://fonts.google.com/icons) using a CSS variable font — zero SVG overhead, all 4 axes controllable as props.
43
+ /* 2. Inject the MD3 Ecosystem Plugin */
44
+ @plugin "@bug-on/md3-tailwind";
57
45
 
58
- ### 1. Load the font
46
+ /* 3. Import Core CSS Tokens (Color, Shape, Typography, Elevation) */
47
+ @import "@bug-on/md3-tokens/index.css";
59
48
 
60
- There are two ways to load the font depending on your use case.
49
+ /* 4. Import specific typography classes explicitly for the React components */
50
+ @import "@bug-on/md3-react/typography.css";
51
+ ```
61
52
 
62
- #### Option A: CDN Mode (Default & easiest)
53
+ ### Setup Icons (Font Symbol)
54
+ The library provides an `<Icon />` component using the variable `Material Symbols Outlined` font. Ensure you load the font stylesheet at the root of your application:
63
55
 
64
56
  ```tsx
65
- // 1. Import CDN CSS (In your main app entry, e.g. layout.tsx / main.tsx)
57
+ // app/layout.tsx or src/main.tsx
66
58
  import '@bug-on/md3-react/material-symbols-cdn.css';
67
-
68
- // 2. Add Preconnect to <head> as early as possible for best performance
69
59
  import { MaterialSymbolsPreconnect } from '@bug-on/md3-react';
70
60
 
71
61
  export default function RootLayout({ children }) {
72
62
  return (
73
63
  <html>
74
64
  <head>
65
+ {/* Preconnect resources for significantly faster icon rendering */}
75
66
  <MaterialSymbolsPreconnect />
76
67
  </head>
77
68
  <body>{children}</body>
@@ -79,137 +70,43 @@ export default function RootLayout({ children }) {
79
70
  );
80
71
  }
81
72
  ```
73
+ *(If you need offline support, use the self-hosted alternative by importing `@bug-on/md3-react/material-symbols-self-hosted.css`)*
82
74
 
83
- #### Option B: Self-Hosted Mode (Production / GDPR)
75
+ ---
84
76
 
85
- ```tsx
86
- // 1. Download font from: https://github.com/google/material-design-icons/tree/master/variablefont
87
- // 2. Place it in your public/fonts/ directory
88
- // 3. Import Self-hosted CSS
89
- import '@bug-on/md3-react/material-symbols-self-hosted.css';
90
-
91
- // Note: MaterialSymbolsPreconnect is NOT needed for self-hosting
92
- ```
77
+ ## 🚀 Usage
93
78
 
94
- > **Why `font-display: block`?**
95
- > We specifically use `block` instead of `swap` for icon fonts to prevent layout shift. If `swap` is used, the browser renders the raw text (like "arrow_forward") until the font loads, which looks broken.
96
-
97
- ### 2. Basic usage
79
+ Once the setup is complete, you are ready to use the components!
98
80
 
99
81
  ```tsx
100
- import { Icon } from '@bug-on/md3-react';
82
+ import { Button, Icon } from '@bug-on/md3-react';
101
83
 
102
- <Icon name="home" />
103
- <Icon name="arrow_forward" />
104
- <Icon name="settings" variant="rounded" />
105
- ```
106
-
107
- > **Note:** Icon names use `snake_case` ligatures — `"arrow_forward"`, not `"ArrowForward"`.
108
-
109
- ### 3. Props
110
-
111
- | Prop | Type | Default | Description |
112
- |------|------|---------|-------------|
113
- | `name` | `string` | *required* | Material Symbol name (snake_case) |
114
- | `variant` | `'outlined' \| 'rounded' \| 'sharp'` | `'outlined'` | Font family variant |
115
- | `fill` | `0 \| 1` | `0` | FILL axis — 0=outlined, 1=filled |
116
- | `weight` | `100..700` | `400` | wght axis — stroke weight |
117
- | `grade` | `-50 \| -25 \| 0 \| 100 \| 200` | `0` | GRAD axis — fine weight adjustment |
118
- | `opticalSize` | `20 \| 24 \| 40 \| 48` | `24` | opsz axis + font-size |
119
- | `size` | `number` | — | Explicit font-size override (px) |
120
- | `animateFill` | `boolean` | `false` | Spring-animate FILL transitions |
121
- | `className` | `string` | — | Additional Tailwind/CSS classes |
122
-
123
- ### 4. Variable font axes
124
-
125
- ```tsx
126
- // Heavier weight — matches Bold typography
127
- <Icon name="star" weight={700} />
128
-
129
- // Filled, optimised for 48dp display
130
- <Icon name="favorite" fill={1} opticalSize={48} />
131
-
132
- // Dark background compensation (grade reduces visual weight)
133
- <Icon name="home" grade={-25} className="text-white" />
134
- ```
135
-
136
- ### 5. Animated fill
137
-
138
- ```tsx
139
- const [isLiked, setIsLiked] = useState(false);
140
-
141
- <Icon
142
- name="favorite"
143
- fill={isLiked ? 1 : 0}
144
- animateFill
145
- className="text-red-500"
146
- />
147
- ```
148
-
149
- When `animateFill` is true, the icon uses `motion/react` (`m.span`) to spring-animate the `font-variation-settings` transition — same critically-damped spring as button shape morphing.
150
-
151
- ### 6. As icon prop for other components
152
-
153
- ```tsx
154
- <Button icon={<Icon name="add" />}>New item</Button>
155
- <Button icon={<Icon name="send" fill={1} />} iconPosition="trailing">Send</Button>
156
-
157
- <IconButton aria-label="Close" onClick={handleClose}>
158
- <Icon name="close" />
159
- </IconButton>
160
- ```
161
-
162
- ### 7. Tailwind utility classes
163
-
164
- The `@bug-on/md3-tailwind` plugin adds icon utility classes for CSS-only control:
165
-
166
- ```html
167
- <!-- Variant -->
168
- <span class="md-icon icon-rounded">home</span>
169
-
170
- <!-- Fill -->
171
- <span class="md-icon icon-fill-1">favorite</span>
172
-
173
- <!-- Weight -->
174
- <span class="md-icon icon-weight-300">star</span>
175
-
176
- <!-- Grade (named aliases) -->
177
- <span class="md-icon icon-grade-low">settings</span> <!-- -25 -->
178
- <span class="md-icon icon-grade-high">star</span> <!-- 200 -->
179
-
180
- <!-- Size (sets font-size + opsz axis together) -->
181
- <span class="md-icon icon-size-48">home</span>
182
- ```
183
-
184
- ### 8. Production optimisation — Font subsetting
185
-
186
- The full Material Symbols font is ~295 KB. For production, subset to only the icons you use:
187
-
188
- ```css
189
- /* In your CSS, replace the CDN import with a subsetted URL */
190
- @import url('https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&icon_names=arrow_forward,close,home,settings&display=block');
84
+ export default function Page() {
85
+ return (
86
+ <div className="p-8 bg-m3-surface min-h-screen">
87
+ <Button colorStyle="filled" size="md" icon={<Icon name="add" />}>
88
+ Get Started
89
+ </Button>
90
+ </div>
91
+ );
92
+ }
191
93
  ```
192
94
 
193
- Each icon adds ~1.7 KB. See [Google Fonts subsetting docs](https://developers.google.com/fonts/docs/material_symbols#use_the_icon_font_from_google_fonts).
194
-
195
- ### 9. Self-hosting
196
-
197
- For offline/production use, see the self-hosting guide inside `material-symbols-self-hosted.css` (comments include `@font-face` declarations for all three variants).
95
+ ---
198
96
 
199
- ## Hooks
97
+ ## 🧩 Components Available
200
98
 
201
- | Hook | Description |
202
- |------------------|---------------------------------------------|
203
- | `useRipple` | MD3 Ripple effect (thuần DOM, no-lib) |
204
- | `useMediaQuery` | SSR-safe responsive media query hook |
205
-
206
- ## Accessibility
207
-
208
- Tất cả components tuân thủ **WAI-ARIA** guidelines:
209
- - Đầy đủ `aria-*` attributes
210
- - Focus visible rõ ràng
211
- - Keyboard navigation
212
-
213
- ## License
99
+ | Component | Description |
100
+ |--------------|--------------------------------------------|
101
+ | `Button` | MD3 Expressive button, 5 variants, 5 sizes |
102
+ | `IconButton` | Icon toggle buttons |
103
+ | `Fab` | Floating Action Button |
104
+ | `Tabs` | MD3 Tabs (Scrollable, Animating indicator) |
105
+ | `Card` | MD3 Card container |
106
+ | `Dialog` | Fully Accessible Modal/Dialog component |
107
+ | `Menu` | Dropdown menus |
108
+ | `CodeBlock` | Syntax-highlighted code block |
109
+ | `Icon` | Material Symbols variable font icon |
214
110
 
111
+ ## ⚖️ License
215
112
  MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bug-on/md3-react",
3
- "version": "0.1.0",
3
+ "version": "1.0.0",
4
4
  "description": "Material Design 3 Expressive React components",
5
5
  "author": "Bug Ổn",
6
6
  "license": "MIT",
@@ -56,7 +56,7 @@
56
56
  "class-variance-authority": "^0.7.1",
57
57
  "clsx": "^2.1.1",
58
58
  "tailwind-merge": "^3.3.1",
59
- "@bug-on/md3-tokens": "0.1.0"
59
+ "@bug-on/md3-tokens": "1.0.0"
60
60
  },
61
61
  "devDependencies": {
62
62
  "@testing-library/jest-dom": "^6.9.1",