@bug-on/m3-expressive 1.0.0 → 1.1.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 (49) hide show
  1. package/CHANGELOG.md +29 -2
  2. package/README.md +20 -18
  3. package/dist/assets/material-symbols-self-hosted.css +27 -26
  4. package/dist/buttons.d.mts +1 -1
  5. package/dist/buttons.d.ts +1 -1
  6. package/dist/buttons.js.map +1 -1
  7. package/dist/buttons.mjs.map +1 -1
  8. package/dist/core.d.mts +44 -44
  9. package/dist/core.d.ts +44 -44
  10. package/dist/core.js.map +1 -1
  11. package/dist/core.mjs.map +1 -1
  12. package/dist/feedback.d.mts +54 -54
  13. package/dist/feedback.d.ts +54 -54
  14. package/dist/feedback.js.map +1 -1
  15. package/dist/feedback.mjs.map +1 -1
  16. package/dist/index.css +3 -0
  17. package/dist/index.d.mts +2 -2
  18. package/dist/index.d.ts +2 -2
  19. package/dist/index.js +8 -8
  20. package/dist/index.js.map +1 -1
  21. package/dist/index.mjs +8 -8
  22. package/dist/index.mjs.map +1 -1
  23. package/dist/layout.d.mts +40 -40
  24. package/dist/layout.d.ts +40 -40
  25. package/dist/layout.js +5 -5
  26. package/dist/layout.js.map +1 -1
  27. package/dist/layout.mjs +5 -5
  28. package/dist/layout.mjs.map +1 -1
  29. package/dist/material-symbols-self-hosted.css +27 -26
  30. package/dist/navigation.js.map +1 -1
  31. package/dist/navigation.mjs.map +1 -1
  32. package/dist/overlays.d.mts +2 -2
  33. package/dist/overlays.d.ts +2 -2
  34. package/dist/overlays.js +2 -2
  35. package/dist/overlays.js.map +1 -1
  36. package/dist/overlays.mjs +2 -2
  37. package/dist/overlays.mjs.map +1 -1
  38. package/dist/pickers.d.mts +241 -243
  39. package/dist/pickers.d.ts +241 -243
  40. package/dist/pickers.js +1 -1
  41. package/dist/pickers.js.map +1 -1
  42. package/dist/pickers.mjs +1 -1
  43. package/dist/pickers.mjs.map +1 -1
  44. package/dist/{side-sheet-modal-BY6VCC8p.d.mts → side-sheet-modal-64FGhDxL.d.mts} +20 -21
  45. package/dist/{side-sheet-modal-CglP6KYA.d.ts → side-sheet-modal-Bd5Qqvp9.d.ts} +20 -21
  46. package/dist/{split-button-trailing-uncheckable-MXj_kyNt.d.mts → split-button-trailing-uncheckable-BRPuTqi1.d.mts} +140 -151
  47. package/dist/{split-button-trailing-uncheckable-C5CLCIKP.d.ts → split-button-trailing-uncheckable-CjOFCoyW.d.ts} +140 -151
  48. package/dist/typography.css +5 -0
  49. package/package.json +4 -4
package/dist/core.d.mts CHANGED
@@ -6,9 +6,9 @@ export { M as MD3ColorStyle, a as MD3Shape, b as MD3Size, P as PolymorphicProps,
6
6
  import { a as Typography, F as FontVariationAxes } from './typography-339RV6v7.mjs';
7
7
 
8
8
  /**
9
- * useMediaQuery — Responsive hook chuẩn SSR-safe
9
+ * useMediaQuery — SSR-safe responsive hook.
10
10
  *
11
- * Tránh hydration mismatch bằng cách khởi tạo với `false`.
11
+ * Prevents hydration mismatch by initializing with `false`.
12
12
  *
13
13
  * @example
14
14
  * ```tsx
@@ -18,20 +18,20 @@ import { a as Typography, F as FontVariationAxes } from './typography-339RV6v7.m
18
18
  declare function useMediaQuery(query: string): boolean;
19
19
 
20
20
  interface RippleOptions {
21
- /** Thời gian hiệu ứng ripple (ms). Mặc định: 600 */
21
+ /** Ripple animation duration (ms). Default: 600 */
22
22
  duration?: number;
23
- /** Màu ripple. Mặc định: 'currentColor' */
23
+ /** Ripple color. Default: 'currentColor' */
24
24
  color?: string;
25
- /** Opacity. Mặc định: 0.12 (chuẩn MD3) */
25
+ /** Opacity. Default: 0.12 (MD3 standard) */
26
26
  opacity?: number;
27
- /** Tắt ripple (ví dụ khi disabled) */
27
+ /** Disable ripple (e.g. when component is disabled) */
28
28
  disabled?: boolean;
29
29
  }
30
30
  /**
31
31
  * useRipple — Material Design 3 Expressive Ripple Effect
32
32
  *
33
- * Hook thuần DOM, không phụ thuộc thư viện animation ngoài.
34
- * Chú ý: Yêu cầu element có `position: relative` và `overflow: hidden`.
33
+ * Pure DOM hook with zero external animation dependencies.
34
+ * Note: Requires element to have `position: relative` and `overflow: hidden`.
35
35
  *
36
36
  * @example
37
37
  * ```tsx
@@ -47,19 +47,19 @@ declare function useRipple$1<T extends HTMLElement = HTMLElement>(options?: Ripp
47
47
  /**
48
48
  * MaterialSymbolsPreconnect
49
49
  *
50
- * Inject preconnect resource hints cho Google Fonts CDN và <head>.
51
- * Đặt component này CÀNG SỚM CÀNG TỐT trong app tree, lý tưởng là
52
- * ngay trong <head> hoặc root layout.
50
+ * Injects preconnect resource hints for Google Fonts CDN into <head>.
51
+ * Place this component AS EARLY AS POSSIBLE in the app tree, ideally
52
+ * directly inside <head> or root layout.
53
53
  *
54
54
  * WHY THIS MATTERS:
55
- * Nếu @import url() nằm trong CSS file, browser phải:
56
- * 1. Parse HTML -> download JS bundle -> execute CSS -> gặp @import -> mới bắt đầu connect Google Fonts
57
- * Preconnect hints cho phép browser bắt đầu TCP handshake + TLS ngay từ bước 1,
58
- * tiết kiệm 100-500ms connection time tùy network.
55
+ * If @import url() is inside a CSS file, browser must:
56
+ * 1. Parse HTML -> download JS bundle -> execute CSS -> hit @import -> start Google Fonts connection
57
+ * Preconnect hints allow browser to establish TCP handshake + TLS connection early at step 1,
58
+ * saving 100-500ms connection latency depending on network.
59
59
  *
60
60
  * USAGE:
61
61
  * ```tsx
62
- * // app/layout.tsx (Next.js) hoặc index.html equivalent
62
+ * // app/layout.tsx (Next.js) or index.html equivalent
63
63
  * import { MaterialSymbolsPreconnect } from '@bug-on/m3-expressive';
64
64
  *
65
65
  * export default function RootLayout({ children }) {
@@ -74,13 +74,13 @@ declare function useRipple$1<T extends HTMLElement = HTMLElement>(options?: Ripp
74
74
  * }
75
75
  * ```
76
76
  *
77
- * NOTE: Chỉ dùng component này với CDN mode.
78
- * Với self-hosted fonts thì không cần preconnect đến external origin.
77
+ * NOTE: Use this component only with CDN mode.
78
+ * Self-hosted fonts do not require preconnecting to external origins.
79
79
  */
80
80
  interface MaterialSymbolsPreconnectProps {
81
81
  /**
82
- * Mảng các biến thể font Material Symbols cần tải.
83
- * Chỉ nên chọn các biến thể mà ứng dụng thực sự sử dụng để tiết kiệm băng thông.
82
+ * Array of Material Symbols font variants to load.
83
+ * Include only variants used by application to minimize bandwidth.
84
84
  * @default ["outlined"]
85
85
  */
86
86
  variants?: Array<"outlined" | "rounded" | "sharp">;
@@ -162,84 +162,84 @@ declare function cn(...inputs: ClassValue[]): string;
162
162
  /**
163
163
  * Props cho component {@link Icon}.
164
164
  *
165
- * Tất cả các trục biến thiên (variable font axes) được map trực tiếp sang `font-variation-settings`.
165
+ * All variable font axes are mapped directly to `font-variation-settings`.
166
166
  */
167
167
  interface IconProps extends React$1.HTMLAttributes<HTMLSpanElement> {
168
168
  /**
169
- * Tên của Material Symbol theo định dạng snake_case.
169
+ * Name of the Material Symbol in snake_case format.
170
170
  * @example "home", "arrow_forward", "settings"
171
171
  * @see https://fonts.google.com/icons
172
172
  */
173
173
  name: string;
174
174
  /**
175
- * Kiểu hình học (Geometric style variant) — tương ứng với font family được tải.
175
+ * Geometric style variant — maps to font family.
176
176
  * @default "outlined"
177
177
  */
178
178
  variant?: "outlined" | "rounded" | "sharp";
179
179
  /**
180
- * Trục FILL. `0` = outlined (viền), `1` = filled (tràn màu).
181
- * Có hiệu ứng spring khi `animateFill` là true.
180
+ * `FILL` axis. `0` = outlined, `1` = filled.
181
+ * Features spring animation when `animateFill` is true.
182
182
  * @default 0
183
183
  */
184
184
  fill?: 0 | 1;
185
185
  /**
186
- * Trục wght — độ dày của nét (stroke weight). Nên khớp với độ dày text xung quanh.
186
+ * `wght` axis — stroke weight. Should match surrounding text weight.
187
187
  * @default 400
188
188
  */
189
189
  weight?: 100 | 200 | 300 | 400 | 500 | 600 | 700;
190
190
  /**
191
- * Trục GRAD — tinh chỉnh độ dày thị giác mà không ảnh hưởng tới layout.
192
- * Dùng mức `-25` trên nền tối để bù trừ hiệu ứng phát sáng (halation).
191
+ * `GRAD` axis — fine-tunes visual weight without affecting layout dimensions.
192
+ * Use `-25` on dark backgrounds to offset light halation effects.
193
193
  * @default 0
194
194
  */
195
195
  grade?: -50 | -25 | 0 | 100 | 200;
196
196
  /**
197
- * Trục opsz — kích thước quang học (optical size) tính bằng dp. Dùng để thiết lập `font-size` nếu không truyền `size`.
198
- * Hãy để giá trị khớp với pixel sẽ render ra để thấy chất lượng tốt nhất.
197
+ * `opsz` axis — optical size in dp. Used to set `font-size` if `size` is not specified.
198
+ * Match rendered pixel size for best quality.
199
199
  * @default 24
200
200
  */
201
201
  opticalSize?: 20 | 24 | 40 | 48;
202
202
  /**
203
- * Ghi đè trực tiếp `font-size` bằng px. Trục `opsz` vẫn sẽ tuân theo thuộc tính `opticalSize`.
203
+ * Direct `font-size` override in px. `opsz` axis still respects `opticalSize`.
204
204
  * @example size={18} opticalSize={20}
205
205
  */
206
206
  size?: number | "inherit";
207
207
  /**
208
- * Kích hoạt hiệu ứng spring mượt mà khi chuyển đổi giá trị FILL (sử dụng cấu hình `SPRING_TRANSITION_FAST`).
209
- * Yêu cầu dependency `motion/react`.
208
+ * Enables smooth spring animation when toggling FILL axis (uses `SPRING_TRANSITION_FAST`).
209
+ * Requires `motion` dependency.
210
210
  * @default false
211
211
  * @example <Icon name="favorite" fill={isLiked ? 1 : 0} animateFill />
212
212
  */
213
213
  animateFill?: boolean;
214
214
  }
215
215
  /**
216
- * Component hiển thị Icon bằng Material Symbols (variable font).
216
+ * Material Symbols (variable font) Icon component.
217
217
  *
218
- * Hãy đảm bảo đã import CSS chứa font trước khi dùng:
218
+ * Make sure to import the icon font CSS before usage:
219
219
  * ```ts
220
- * import '@bug-on/m3-expressive/material-symbols.css';
220
+ * import '@bug-on/m3-expressive/material-symbols-cdn.css';
221
221
  * ```
222
222
  *
223
223
  * @remarks
224
- * - Đặt tên icon dùng snake_case: `"arrow_forward"`, KHÔNG PHẢI `"ArrowForward"`.
225
- * - Thuộc tính `aria-hidden="true"` được tự động thêm vào — bạn cần thêm label đọc bằng giọng nói (accessible labels) ở phần tử cha.
224
+ * - Use snake_case for icon names: `"arrow_forward"`, NOT `"ArrowForward"`.
225
+ * - `aria-hidden="true"` is attached automatically — provide screen reader labels on parent elements.
226
226
  *
227
227
  * @example
228
228
  * ```tsx
229
- * // Icon cơ bản
229
+ * // Basic Icon
230
230
  * <Icon name="home" />
231
231
  *
232
- * // Tùy chỉnh trực quan (filled, nét dày)
232
+ * // Visual customization (filled, heavy weight)
233
233
  * <Icon name="favorite" variant="rounded" fill={1} weight={300} />
234
234
  *
235
- * // Animate khi trạng thái thay đổi
235
+ * // Animated transition on state change
236
236
  * <Icon name="bookmark" fill={saved ? 1 : 0} animateFill />
237
237
  *
238
- * // Đổi kích thước icon cụ thể
238
+ * // Custom size override
239
239
  * <Icon name="close" size={18} opticalSize={20} />
240
240
  *
241
- * // Kết hợp với các component khác
242
- * <Button icon={<Icon name="add" />}>Thêm vào giỏ</Button>
241
+ * // Combination with other components
242
+ * <Button icon={<Icon name="add" />}>Add to cart</Button>
243
243
  * ```
244
244
  *
245
245
  * @see https://fonts.google.com/icons
package/dist/core.d.ts CHANGED
@@ -6,9 +6,9 @@ export { M as MD3ColorStyle, a as MD3Shape, b as MD3Size, P as PolymorphicProps,
6
6
  import { a as Typography, F as FontVariationAxes } from './typography-339RV6v7.js';
7
7
 
8
8
  /**
9
- * useMediaQuery — Responsive hook chuẩn SSR-safe
9
+ * useMediaQuery — SSR-safe responsive hook.
10
10
  *
11
- * Tránh hydration mismatch bằng cách khởi tạo với `false`.
11
+ * Prevents hydration mismatch by initializing with `false`.
12
12
  *
13
13
  * @example
14
14
  * ```tsx
@@ -18,20 +18,20 @@ import { a as Typography, F as FontVariationAxes } from './typography-339RV6v7.j
18
18
  declare function useMediaQuery(query: string): boolean;
19
19
 
20
20
  interface RippleOptions {
21
- /** Thời gian hiệu ứng ripple (ms). Mặc định: 600 */
21
+ /** Ripple animation duration (ms). Default: 600 */
22
22
  duration?: number;
23
- /** Màu ripple. Mặc định: 'currentColor' */
23
+ /** Ripple color. Default: 'currentColor' */
24
24
  color?: string;
25
- /** Opacity. Mặc định: 0.12 (chuẩn MD3) */
25
+ /** Opacity. Default: 0.12 (MD3 standard) */
26
26
  opacity?: number;
27
- /** Tắt ripple (ví dụ khi disabled) */
27
+ /** Disable ripple (e.g. when component is disabled) */
28
28
  disabled?: boolean;
29
29
  }
30
30
  /**
31
31
  * useRipple — Material Design 3 Expressive Ripple Effect
32
32
  *
33
- * Hook thuần DOM, không phụ thuộc thư viện animation ngoài.
34
- * Chú ý: Yêu cầu element có `position: relative` và `overflow: hidden`.
33
+ * Pure DOM hook with zero external animation dependencies.
34
+ * Note: Requires element to have `position: relative` and `overflow: hidden`.
35
35
  *
36
36
  * @example
37
37
  * ```tsx
@@ -47,19 +47,19 @@ declare function useRipple$1<T extends HTMLElement = HTMLElement>(options?: Ripp
47
47
  /**
48
48
  * MaterialSymbolsPreconnect
49
49
  *
50
- * Inject preconnect resource hints cho Google Fonts CDN và <head>.
51
- * Đặt component này CÀNG SỚM CÀNG TỐT trong app tree, lý tưởng là
52
- * ngay trong <head> hoặc root layout.
50
+ * Injects preconnect resource hints for Google Fonts CDN into <head>.
51
+ * Place this component AS EARLY AS POSSIBLE in the app tree, ideally
52
+ * directly inside <head> or root layout.
53
53
  *
54
54
  * WHY THIS MATTERS:
55
- * Nếu @import url() nằm trong CSS file, browser phải:
56
- * 1. Parse HTML -> download JS bundle -> execute CSS -> gặp @import -> mới bắt đầu connect Google Fonts
57
- * Preconnect hints cho phép browser bắt đầu TCP handshake + TLS ngay từ bước 1,
58
- * tiết kiệm 100-500ms connection time tùy network.
55
+ * If @import url() is inside a CSS file, browser must:
56
+ * 1. Parse HTML -> download JS bundle -> execute CSS -> hit @import -> start Google Fonts connection
57
+ * Preconnect hints allow browser to establish TCP handshake + TLS connection early at step 1,
58
+ * saving 100-500ms connection latency depending on network.
59
59
  *
60
60
  * USAGE:
61
61
  * ```tsx
62
- * // app/layout.tsx (Next.js) hoặc index.html equivalent
62
+ * // app/layout.tsx (Next.js) or index.html equivalent
63
63
  * import { MaterialSymbolsPreconnect } from '@bug-on/m3-expressive';
64
64
  *
65
65
  * export default function RootLayout({ children }) {
@@ -74,13 +74,13 @@ declare function useRipple$1<T extends HTMLElement = HTMLElement>(options?: Ripp
74
74
  * }
75
75
  * ```
76
76
  *
77
- * NOTE: Chỉ dùng component này với CDN mode.
78
- * Với self-hosted fonts thì không cần preconnect đến external origin.
77
+ * NOTE: Use this component only with CDN mode.
78
+ * Self-hosted fonts do not require preconnecting to external origins.
79
79
  */
80
80
  interface MaterialSymbolsPreconnectProps {
81
81
  /**
82
- * Mảng các biến thể font Material Symbols cần tải.
83
- * Chỉ nên chọn các biến thể mà ứng dụng thực sự sử dụng để tiết kiệm băng thông.
82
+ * Array of Material Symbols font variants to load.
83
+ * Include only variants used by application to minimize bandwidth.
84
84
  * @default ["outlined"]
85
85
  */
86
86
  variants?: Array<"outlined" | "rounded" | "sharp">;
@@ -162,84 +162,84 @@ declare function cn(...inputs: ClassValue[]): string;
162
162
  /**
163
163
  * Props cho component {@link Icon}.
164
164
  *
165
- * Tất cả các trục biến thiên (variable font axes) được map trực tiếp sang `font-variation-settings`.
165
+ * All variable font axes are mapped directly to `font-variation-settings`.
166
166
  */
167
167
  interface IconProps extends React$1.HTMLAttributes<HTMLSpanElement> {
168
168
  /**
169
- * Tên của Material Symbol theo định dạng snake_case.
169
+ * Name of the Material Symbol in snake_case format.
170
170
  * @example "home", "arrow_forward", "settings"
171
171
  * @see https://fonts.google.com/icons
172
172
  */
173
173
  name: string;
174
174
  /**
175
- * Kiểu hình học (Geometric style variant) — tương ứng với font family được tải.
175
+ * Geometric style variant — maps to font family.
176
176
  * @default "outlined"
177
177
  */
178
178
  variant?: "outlined" | "rounded" | "sharp";
179
179
  /**
180
- * Trục FILL. `0` = outlined (viền), `1` = filled (tràn màu).
181
- * Có hiệu ứng spring khi `animateFill` là true.
180
+ * `FILL` axis. `0` = outlined, `1` = filled.
181
+ * Features spring animation when `animateFill` is true.
182
182
  * @default 0
183
183
  */
184
184
  fill?: 0 | 1;
185
185
  /**
186
- * Trục wght — độ dày của nét (stroke weight). Nên khớp với độ dày text xung quanh.
186
+ * `wght` axis — stroke weight. Should match surrounding text weight.
187
187
  * @default 400
188
188
  */
189
189
  weight?: 100 | 200 | 300 | 400 | 500 | 600 | 700;
190
190
  /**
191
- * Trục GRAD — tinh chỉnh độ dày thị giác mà không ảnh hưởng tới layout.
192
- * Dùng mức `-25` trên nền tối để bù trừ hiệu ứng phát sáng (halation).
191
+ * `GRAD` axis — fine-tunes visual weight without affecting layout dimensions.
192
+ * Use `-25` on dark backgrounds to offset light halation effects.
193
193
  * @default 0
194
194
  */
195
195
  grade?: -50 | -25 | 0 | 100 | 200;
196
196
  /**
197
- * Trục opsz — kích thước quang học (optical size) tính bằng dp. Dùng để thiết lập `font-size` nếu không truyền `size`.
198
- * Hãy để giá trị khớp với pixel sẽ render ra để thấy chất lượng tốt nhất.
197
+ * `opsz` axis — optical size in dp. Used to set `font-size` if `size` is not specified.
198
+ * Match rendered pixel size for best quality.
199
199
  * @default 24
200
200
  */
201
201
  opticalSize?: 20 | 24 | 40 | 48;
202
202
  /**
203
- * Ghi đè trực tiếp `font-size` bằng px. Trục `opsz` vẫn sẽ tuân theo thuộc tính `opticalSize`.
203
+ * Direct `font-size` override in px. `opsz` axis still respects `opticalSize`.
204
204
  * @example size={18} opticalSize={20}
205
205
  */
206
206
  size?: number | "inherit";
207
207
  /**
208
- * Kích hoạt hiệu ứng spring mượt mà khi chuyển đổi giá trị FILL (sử dụng cấu hình `SPRING_TRANSITION_FAST`).
209
- * Yêu cầu dependency `motion/react`.
208
+ * Enables smooth spring animation when toggling FILL axis (uses `SPRING_TRANSITION_FAST`).
209
+ * Requires `motion` dependency.
210
210
  * @default false
211
211
  * @example <Icon name="favorite" fill={isLiked ? 1 : 0} animateFill />
212
212
  */
213
213
  animateFill?: boolean;
214
214
  }
215
215
  /**
216
- * Component hiển thị Icon bằng Material Symbols (variable font).
216
+ * Material Symbols (variable font) Icon component.
217
217
  *
218
- * Hãy đảm bảo đã import CSS chứa font trước khi dùng:
218
+ * Make sure to import the icon font CSS before usage:
219
219
  * ```ts
220
- * import '@bug-on/m3-expressive/material-symbols.css';
220
+ * import '@bug-on/m3-expressive/material-symbols-cdn.css';
221
221
  * ```
222
222
  *
223
223
  * @remarks
224
- * - Đặt tên icon dùng snake_case: `"arrow_forward"`, KHÔNG PHẢI `"ArrowForward"`.
225
- * - Thuộc tính `aria-hidden="true"` được tự động thêm vào — bạn cần thêm label đọc bằng giọng nói (accessible labels) ở phần tử cha.
224
+ * - Use snake_case for icon names: `"arrow_forward"`, NOT `"ArrowForward"`.
225
+ * - `aria-hidden="true"` is attached automatically — provide screen reader labels on parent elements.
226
226
  *
227
227
  * @example
228
228
  * ```tsx
229
- * // Icon cơ bản
229
+ * // Basic Icon
230
230
  * <Icon name="home" />
231
231
  *
232
- * // Tùy chỉnh trực quan (filled, nét dày)
232
+ * // Visual customization (filled, heavy weight)
233
233
  * <Icon name="favorite" variant="rounded" fill={1} weight={300} />
234
234
  *
235
- * // Animate khi trạng thái thay đổi
235
+ * // Animated transition on state change
236
236
  * <Icon name="bookmark" fill={saved ? 1 : 0} animateFill />
237
237
  *
238
- * // Đổi kích thước icon cụ thể
238
+ * // Custom size override
239
239
  * <Icon name="close" size={18} opticalSize={20} />
240
240
  *
241
- * // Kết hợp với các component khác
242
- * <Button icon={<Icon name="add" />}>Thêm vào giỏ</Button>
241
+ * // Combination with other components
242
+ * <Button icon={<Icon name="add" />}>Add to cart</Button>
243
243
  * ```
244
244
  *
245
245
  * @see https://fonts.google.com/icons