@bug-on/md3-react 0.1.0

package/dist/ui/fab-menu.d.ts

@@ -0,0 +1,204 @@
+/**
+ * @file fab-menu.tsx
+ *
+ * Component FAB Menu theo phong cách MD3 Expressive.
+ *
+ * Cung cấp một Floating Action Button (FAB) dạng toggle để mở một danh sách các hành động có hiệu ứng stagger (xếp tầng).
+ * Tuân thủ mô hình FloatingActionButtonMenu của MD3 với sự hỗ trợ tiếp cận (accessibility) đầy đủ
+ * (điều hướng bàn phím, quản lý focus, các vai trò ARIA).
+ *
+ * @see https://m3.material.io/components/floating-action-button/overview
+ */
+import * as React from "react";
+/**
+ * Định dạng dữ liệu cho từng hành động (item) trong biểu mẫu menu của FAB.
+ *
+ * Nếu bỏ qua thuộc tính `label`, item sẽ render dạng ô vuông chỉ có icon.
+ */
+export interface FABMenuItemData {
+    /** Một ID duy nhất để dùng cho key react và quản lý focus. */
+    id: string;
+    /** Label hiển thị cạnh icon (tuỳ chọn). Không thêm thuộc tính này nếu muốn hiển thị chỉ có icon (icon-only). */
+    label?: string;
+    /** Node của Icon — thường là một component SVG Icon duy nhất. */
+    icon: React.ReactNode;
+    /** Gọi hàm ngay lập tức khi item được kích hoạt (click hoặc nhấn Enter/Phím cách). */
+    onClick: () => void;
+    /**
+     * Khi `true`, vô hiệu hoá item về mặt hình thức lẫn tương tác rẽ nhánh.
+     * Vẫn dùng `aria-disabled` thay vì HTML `disabled` nhằm giữ nó lấy được focus phục vụ cho accessibility.
+     * @default false
+     */
+    disabled?: boolean;
+    /** Thêm CSS classes bổ sung dùng cho wrapper chính của item. */
+    className?: string;
+}
+/**
+ * Các props điều khiển Component chính `FABMenu`.
+ *
+ * @remarks
+ * FABMenu quản lý vòng đời trạng thái mở/đóng menu (open/close), quản lý focus, điều khiển phím,
+ * và điều hướng hiệu ứng chuyển động. Trạng thái `expanded` được truyền từ ngoài (controlled state),
+ * do đó bạn có thể quản lý qua react state, hoặc dùng router hay business logic khác.
+ */
+export interface FABMenuProps {
+    /** FAB Menu có đang mở (mở rộng)/hiển thị hay không. */
+    expanded: boolean;
+    /** Hàm handler kích hoạt khi Toggle FAB được người dùng tương tác, hoặc khi dismiss backdrop. */
+    onToggle: (expanded: boolean) => void;
+    /** Danh sách các action items (Spec MD3 đề nghị 2-6 item là hoàn hảo). */
+    items: FABMenuItemData[];
+    /**
+     * Vai trò màu (color role container) MD3 cho cái nút FAB lẫn các menu items.
+     * @default "primary"
+     */
+    colorVariant?: "primary" | "secondary" | "tertiary";
+    /**
+     * Kích cỡ khởi tạo cho cái ToggleFAB (FAB biến hình thành cục đóng dấu X khi nó expanded).
+     * @default "baseline"
+     */
+    fabSize?: "baseline" | "medium" | "large";
+    /**
+     * Căn lề của danh sách menu items tương quan với cái Toggle FAB.
+     * - `"end"`: Các items dồn hết theo lề phía tay phải (trailing edge, default cực hữu hiệu đối với RTL design).
+     * - `"start"`: Các items dồn hết dọc theo lề trái.
+     * - `"center"`: Các item sẽ được căn ra giữa chiều dọc, căn giữa tâm khối với cái FAB.
+     * @default "end"
+     */
+    alignment?: "start" | "end" | "center";
+    /** Thuộc tính cho CSS component root để đè. */
+    className?: string;
+    /**
+     * Nếu `true`, khi menu đang hiện ra, click chuột ra phía sau (màn xám mờ backdrop) để đóng menu.
+     * @default true
+     */
+    closeOnBackdropClick?: boolean;
+    /**
+     * Nếu `true`, focus sẽ tự động chạy xuống item CUỐI (sát bên trên cái nút FAB) khi menu vừa loé mờ ra.
+     * Nếu `false`, focus sẽ bay lên item ĐẦU TIÊN của danh sách (cao nhất trên màn hình).
+     * @default true
+     */
+    focusLast?: boolean;
+    /** Bắt buộc truyền `aria-label` cho ToggleFAB để đáp ứng Accessibility. */
+    "aria-label"?: string;
+}
+/**
+ * Props thuộc component `ToggleFAB` đứng độc lập.
+ */
+export interface ToggleFABProps {
+    /** Nút có đang trong trạng thái được kích hoạt check (expanded). */
+    expanded: boolean;
+    /** Gọi khi xảy ra sự kiện Toggle nút. */
+    onToggle: (expanded: boolean) => void;
+    /**
+     * Function sinh Icon - nhận về tiến độ `progress` trong khoảng `0` -> `1` (Từ Chưa Expanded -> Đã Expanded)
+     * Dùng cho các hiệu ứng morphing Icon khi animtion render (VD: Từ Cộng thành Đóng).
+     *
+     * @example
+     * ```tsx
+     * icon={(progress) => progress > 0.5 ? <Icon name="close" /> : <Icon name="add" />}
+     * ```
+     */
+    icon: (progress: number) => React.ReactNode;
+    /** Vai trò màu container chuẩn MD3. @default "primary" */
+    colorVariant?: "primary" | "secondary" | "tertiary";
+    /** Kích thước của cục FAB ban đầu (Sau khi nhấn sẽ thu tròn). @default "baseline" */
+    fabSize?: "baseline" | "medium" | "large";
+    /** CSS Class linh tinh bổ sung thêm. */
+    className?: string;
+    /** Thuộc tính đọc thẻ accessibility. Bắt buộc có. */
+    "aria-label"?: string;
+    /** Kiểm soát giá trị của ID để link với menu qua aria-controls. */
+    "aria-controls"?: string;
+    /** Trỏ id component. */
+    id?: string;
+}
+/**
+ * Props thuộc component một món item đơn lẻ `FABMenuItem`.
+ */
+export interface FABMenuItemProps {
+    /** Node của icon hiện. */
+    icon: React.ReactNode;
+    /** Tên nhãn mô tả kế bên icon cho item này. Hoặc ẩn nó đi nếu không mong đợi. */
+    label?: string;
+    /** Hàm bắn ra khi item được kích. */
+    onClick: () => void;
+    /** Vô hiệu hóa hành vi tương tác item mà vẫn cho phép bàn phím tab bấm dính lấy focus. @default false */
+    disabled?: boolean;
+    /** Container tông màu. @default "primary" */
+    colorVariant?: "primary" | "secondary" | "tertiary";
+    /** Custom CSS className. */
+    className?: string;
+    /** Số index liệt kê trong mảng dùng tính render delay (Dành cho animation cấu trúc `custom`). */
+    index?: number;
+    /** Tổng danh sách items có mảng. */
+    totalItems?: number;
+    /** Giá trị logic `tabIndex` dùng điều khiển thao tác phím Tab thủ công. */
+    tabIndex?: number;
+}
+/**
+ * Nút Toggle FAB (Biến hình) có thể được dùng độc lập đứng một mình (standalone) hoặc kết nối để kích hoạt mở cả nùi Menu ở dưới con `FABMenu`.
+ *
+ * Sức ép hiệu ứng kích thước khung nền sẽ chuyển từ vuôn/vát cạnh sang hình tròn hẵn (square → circle), chuyển biến cả màu sắc
+ * khi mà cờ `expanded` chuyển tiếp từ false sang → true.
+ *
+ * @example
+ * ```tsx
+ * const [open, setOpen] = React.useState(false);
+ * <ToggleFAB
+ *   expanded={open}
+ *   onToggle={setOpen}
+ *   colorVariant="primary"
+ *   aria-label="Toggle actions"
+ *   icon={(progress) => progress > 0.5 ? <Icon name="close" /> : <Icon name="add" />}
+ * />
+ * ```
+ */
+export declare const ToggleFAB: React.NamedExoticComponent<ToggleFABProps & React.RefAttributes<HTMLButtonElement>>;
+/**
+ * Một item thực hiện một loại hành động duy nhất trong `FABMenu`.
+ *
+ * Render hình dạng viên thuốc bao quanh icon cùng với label diễn giải.
+ * Khi `label` bỏ trống, nó sẽ render thành một cục thẻ gạch ốp màu vuông vức chứa chữ mỗi cái icon.
+ * Component chứa gợn sóng MD3 Ripple cùng 48dp chuẩn vùng target đụng diện chuẩn WCAG 2.5.5 cho cảm ứng.
+ *
+ * @remarks
+ * Những thành phần khi bị tắt (vô hiệu tương tác) thì chỉ được dùng role `aria-disabled="true"` ở lớp div bề mặt thay vì lấy
+ *  thuộc tính gốc `disabled` của HTML. Nhờ đó, item tuy xám mờ không bấm được phím chuột vẫn sẽ có khả năng focus qua vòng đời tab phím bàn phím
+ * (quy chuẩn chặt chẽ của Material Design 3).
+ */
+export declare function FABMenuItem({ icon, label, onClick, disabled, colorVariant, className, tabIndex, }: FABMenuItemProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * MD3 Expressive FAB Menu.
+ *
+ * Bộ mở rộng Floating Action Button. Khi tương tác bật vào toggle-button (FAB con lai), sẽ trút ra mớ tác vụ menu ở xếp dọc (hoặc lan ra) từ trên đè ngược xuống trên nó.
+ *
+ * Accessibility thực thi chuẩn MD3 toàn phần:
+ *  - thẻ `role="menu"` trang bị cho thẻ hộp div làm luống container
+ *  - trang bị thẻ `role="menuitem"` trên mảng items thành phần con
+ *  - Lifecycle Focus cho trải nghiệm hoàn mỹ: Mở phím bật -> Focus thẳng lên item cao/thấp đầu/cuối cùng menu; Đóng tắt menu -> Focus trả về ngược lại ToggleFAB
+ *  - Tính năng Bàn Phím: Lách Escape nhấn tắt nhắm, Nhấn phím hướng lên-xuống(ArrowUp/Down) để di chuyển, Móc Tab(hoặc là Shift+Tab) nhảy lăng quăng qua các item.
+ *
+ * @example
+ * ```tsx
+ * const [open, setOpen] = React.useState(false);
+ *
+ * const items = [
+ *   { id: 'share', icon: <Icon name="share" />, label: 'Chia sẻ', onClick: () => console.log('Share') },
+ *   { id: 'edit', icon: <Icon name="edit" />, label: 'Chỉnh sửa', onClick: () => console.log('Edit') },
+ *   { id: 'delete', icon: <Icon name="delete" />, label: 'Xóa bớt', disabled: true, onClick: () => {} }
+ * ];
+ *
+ * <FABMenu
+ *   expanded={open}
+ *   onToggle={setOpen}
+ *   aria-label="Các công cụ thao tác nhanh"
+ *   alignment="center"
+ *   colorVariant="tertiary"
+ *   items={items}
+ * />
+ * ```
+ *
+ * @see https://m3.material.io/components/floating-action-button/overview
+ */
+export declare function FABMenu({ expanded, onToggle, items, colorVariant, fabSize, alignment, className, closeOnBackdropClick, focusLast, "aria-label": ariaLabel, }: FABMenuProps): import("react/jsx-runtime").JSX.Element;

package/dist/ui/fab.d.ts

@@ -0,0 +1,162 @@
+/**
+ * @file fab.tsx
+ *
+ * MD3 Expressive Floating Action Button (FAB).
+ *
+ * Supports four sizes, an extended variant with animated label reveal,
+ * shape morphing, a `lowered` elevation variant, and an optional
+ * `FABPosition` container for absolute positioning within a layout.
+ *
+ * @see https://m3.material.io/components/floating-action-button/overview
+ */
+import type { HTMLMotionProps } from "motion/react";
+import * as React from "react";
+type MotionButtonProps = Omit<HTMLMotionProps<"button">, "children" | "color">;
+/**
+ * Tham số Props dùng cho component thao tác nổi `FAB`.
+ *
+ * @remarks
+ * - Đảm bảo rằng đối với loại FAB chỉ show ra mỗi con Icon mà không có nhãn hiển thị (icon-only), bắt buộc phải có thuộc tính `aria-label` nhằm phục vụ (accessibility).
+ * - Ở hình thể mở rộng (khi `extended={true}`), phần nội dung truyền vào `children` chính là chuỗi Text được thể hiện cùng nút, và nó sẽ khiến nút button có label mặc định nên bạn có thể chém bớt tham số `aria-label`.
+ * - Thuộc tính cờ `lowered` (chìm) giúp giáng cấp hiệu ứng tạo bóng Shadow của thẻ, rải mảng cái shadow theo phong thái MD3 "lowered" FAB;
+ *   sử dụng khi nút FAB này vốn bị bọc bên trong bề mặt chìm đè lên component gì khác mà vốn tụi nó đã nhún ở mực sâu (Ví dụ Bottom App Bar) để thiết lập Hierarchy hài hoà.
+ *
+ * @see https://m3.material.io/components/floating-action-button/overview
+ */
+export interface FABProps extends MotionButtonProps {
+    /**
+     * Icon đại diện render — thông thường là truyền thẻ component Icon.
+     * Sẽ được tráo đổi thành Spinner tự động quay khi giá trị `loading={true}`.
+     */
+    icon: React.ReactNode;
+    /**
+     * Kích thước hiển thị FAB. Tuân chuẩn.
+     * - `sm`: Small (40dp) — Được khuyên dùng cho các không gian kín/trong lòng Content.
+     * - `md`: Regular (56dp) — Action thứ yếu hoặc tiêu điểm màn hình. (Phần đông người dùng xài).
+     * - `lg`: Large (96dp) — Trọng tâm thao tác quan trọng lớn nhát.
+     * - `xl`: Extra-large (136dp) — Gây tiếng vang, dạng Spotlight cực bùng nổ của app.
+     * @default "md"
+     */
+    size?: "sm" | "md" | "lg" | "xl";
+    /**
+     * Container vai trò hệ thống tông màu MD3 dùng phết nền.
+     * @default "primary"
+     */
+    colorStyle?: "primary" | "secondary" | "tertiary" | "surface";
+    /**
+     * Kích hoạt khi giá trị được đổi là `true`, sẽ diễn tả Animation bung chữ kèm theo độ dãn hình dài cho cái FAB.
+     * Chiều rộng tự cơi nới để thích ứng chuỗi `children`.
+     * @default false
+     */
+    extended?: boolean;
+    /**
+     * Nơi đón lấy chữ được render cùng khi `extended={true}` bật lên.
+     * Khuyến nghị là Text string thuần.
+     */
+    children?: React.ReactNode;
+    /**
+     * Nhấn `true`, thì rút lại shadow đi một cấp xuống độ nổi nông cạn.
+     * Mảng bám ở Bottom bar hay Top bar Surface để ránh rườm rà.
+     * @default false
+     */
+    lowered?: boolean;
+    /**
+     * Nhấp chuột sang `true`, đổi Icon thành cối xay Spinner chờ kết quả. Đồng loạt chặn click tương tác.
+     * @default false
+     */
+    loading?: boolean;
+    /**
+     * Có 2 chuẩn hình của Loading chờ.
+     * @default "loading-indicator"
+     */
+    loadingVariant?: "loading-indicator" | "circular";
+    /**
+     * Hiện thẻ FAB lên layout không (Kiểm soát bằng motion scale Entrance/Exit).
+     * @default true
+     */
+    visible?: boolean;
+}
+/**
+ * Interface cho component bọc thẻ `FABPosition` — Gắn lớp absolute position nhét cục FAB vào một góc cố định của góc nào đó tại trình duyệt/bề mặt render.
+ *
+ * @see {@link FABPosition}
+ */
+export interface FABPositionProps {
+    /**
+     * Góc để niêm chặt nút FAB.
+     * @default "bottom-right"
+     */
+    position?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
+    /** Kẹp một nùi element. Mong chờ thả Node `<FAB>` vào đây.*/
+    children: React.ReactNode;
+    /** CSS Class hỗ trợ chỉnh override */
+    className?: string;
+}
+/**
+ * Element bao bọc thẻ định vị Absolute cho component `<FAB>`.
+ *
+ * Component dùng để cắm phao Neo cái FAB vào sát ở góc của screen kèm theo một cái offset space theo responsive an toàn mà lại trơn chu nhạy nhẽo.
+ * Nhưng có quy tắc gốc đó là phần tử bao bọc cha mẹ của nó PHẢI có thẻ tag css `position: relative` (hoặc ở cấp tổ tiêm của trang nào đó phải đẻ gốc rễ ra posisition).
+ *
+ * @example
+ * ```tsx
+ * <div className="relative min-h-screen">
+ *   // Cái nút sẽ xà xuống dưới cùng bên lề Trái
+ *   <FABPosition position="bottom-left">
+ *     <FAB icon={<Icon name="edit" />} aria-label="Compose New Mail" />
+ *   </FABPosition>
+ * </div>
+ * ```
+ *
+ * @see {@link FAB}
+ * @see https://m3.material.io/components/floating-action-button/guidelines
+ */
+export declare function FABPosition({ position, children, className, }: FABPositionProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Action nổi chính theo phong cách MD3 Expressive Floating Action Button (FAB).
+ *
+ * Phơi nhiễm các action tạo nhịp điệu kích hoạt cho người sử dụng với đủ bộ trang hoàn trọn kích thước Size (SM->XL),
+ * mang nhiều màu sắc Color role khác biệt, cung cấp một sức nén cho Label để kéo toẹt cái ống dài ra (gọi là Dạng Mở Rộng - Extended) tạo nên hành động sinh động,
+ * Trạng thái load/nhấp hiện xuất cùng animation thu scale thoát cảnh bắt mắt đầy nghệ thuật.
+ *
+ * @remarks
+ * - Chỉ định bắt buộc `aria-label` cho những mẫu icon bị đơn côi trơ trọi (icon-only FABs).
+ * - Trường hợp xài mode Mở Rộng qua việc truyền hàm `extended={true}`, nút FAB này tự ngộ nhận thân thế, lấy `children` dùng làm Aria label luôn hễ như `children` đó đang chứa text string.
+ *   Khi ấy bạn tha hồ cắt bỏ thuộc tính `aria-label` ra.
+ * - Lúc cho biến mất (`visible={false}`), bộ nút tung chiêu lùi về sau làm quả rút bóng thoát Scale-out qua effect spring uyển chuyển.
+ * - Sài kèm `FABPosition` bao đùm nó lại nếu bạn muốn xích nó cố định ngấm chân sâu góc màn hình hiển thị.
+ *
+ * @example
+ * ```tsx
+ * // FAB cơ bản, nhỏ xinh, chỉ hiện icon.
+ * <FAB icon={<Icon name="search" />} aria-label="Nhấn tìm kiếm" size="sm" />
+ *
+ * // Dịch sang dòng Extended có dòng caption chữ dài thòn
+ * const [isOpen, setOpen] = React.useState(false);
+ * <FAB
+ *   icon={<Icon name="edit" />}
+ *   extended={isOpen}
+ *   onClick={() => setOpen(!isOpen)}
+ * >
+ *   Viết tâm thư
+ * </FAB>
+ *
+ * // FAB to lớn nhất dùng trạng thái chờ load Submit lên Server
+ * <FAB
+ *   icon={<Icon name="upload" />}
+ *   size="lg"
+ *   loading={isUploading}
+ *   colorStyle="secondary"
+ *   aria-label="Upload Files lên mây xanh"
+ * />
+ *
+ * // Cố định dưới chân tay phải
+ * <FABPosition position="bottom-right">
+ *   <FAB icon={<Icon name="add" />} aria-label="Dấu Cộng sinh nảy" />
+ * </FABPosition>
+ * ```
+ *
+ * @see https://m3.material.io/components/floating-action-button/overview
+ */
+export declare const FAB: React.NamedExoticComponent<Omit<FABProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;
+export {};

package/dist/ui/icon-button.d.ts

@@ -0,0 +1,131 @@
+/**
+ * @file icon-button.tsx
+ *
+ * MD3 Expressive Icon Button component.
+ *
+ * An icon-only button with shape morphing, ripple effect, loading state,
+ * and toggle variant. Requires `aria-label` for accessibility since there
+ * is no visible text label.
+ *
+ * @see https://m3.material.io/components/icon-buttons/overview
+ */
+import type { HTMLMotionProps } from "motion/react";
+import * as React from "react";
+type MotionButtonProps = Omit<HTMLMotionProps<"button">, "children" | "color">;
+/**
+ * Base props for the Icon Button component.
+ *
+ * @see {@link IconButtonProps} for the full discriminated union.
+ * @see https://m3.material.io/components/icon-buttons/overview
+ */
+export interface BaseIconButtonProps extends MotionButtonProps {
+    /**
+     * Visual color style following MD3 color roles.
+     * @default "standard"
+     */
+    colorStyle?: "standard" | "filled" | "tonal" | "outlined";
+    /**
+     * Button container size.
+     * Sizes: XS=32dp, SM=40dp, MD=56dp, LG=96dp, XL=136dp.
+     * @default "sm"
+     */
+    size?: "xs" | "sm" | "md" | "lg" | "xl";
+    /**
+     * Container shape controlling border-radius morphing.
+     * - `round`: fully circular (CornerFull).
+     * - `square`: rounded square (CornerMedium–CornerExtraLarge per size).
+     * @default "round"
+     */
+    shape?: "round" | "square";
+    /**
+     * When `true`, replaces the icon with an animated loading indicator.
+     * Interaction is blocked and `aria-busy` is set.
+     * @default false
+     */
+    loading?: boolean;
+    /**
+     * Spinner style shown while `loading={true}`.
+     * @default "loading-indicator"
+     */
+    loadingVariant?: "loading-indicator" | "circular";
+    /** Icon content — typically a single SVG icon component. */
+    children: React.ReactNode;
+    /**
+     * Accessible label — **REQUIRED** because icon buttons have no visible text.
+     *
+     * @example "Close", "Add to favourites", "Toggle dark mode"
+     * @see https://m3.material.io/components/icon-buttons/accessibility
+     */
+    "aria-label": string;
+}
+/**
+ * Complete `IconButton` props — discriminated union that enforces
+ * `selected` is only valid with `variant="toggle"`.
+ *
+ * @example
+ * ```tsx
+ * // Standard
+ * <IconButton aria-label="Close" onClick={handleClose}>
+ *   <XIcon />
+ * </IconButton>
+ *
+ * // Toggle
+ * <IconButton
+ *   variant="toggle"
+ *   selected={isLiked}
+ *   aria-label={isLiked ? "Unlike" : "Like"}
+ *   colorStyle="filled"
+ *   onClick={() => setIsLiked(!isLiked)}
+ * >
+ *   <HeartIcon />
+ * </IconButton>
+ * ```
+ *
+ * @see https://m3.material.io/components/icon-buttons/overview
+ */
+export type IconButtonProps = BaseIconButtonProps & ({
+    variant?: "default";
+    selected?: never;
+} | {
+    variant: "toggle";
+    selected: boolean;
+});
+/**
+ * MD3 Expressive Icon Button.
+ *
+ * An icon-only button with spring shape morphing, ripple effect, loading state support,
+ * and an optional toggle variant. Compliant with MD3 Expressive sizing and WCAG 2.5.5
+ * (touch target minimum for XS and SM sizes).
+ *
+ * @remarks
+ * - `aria-label` is **required** — icon buttons have no visible text label.
+ * - `variant="toggle"` requires `selected: boolean`.
+ * - Touch target is automatically extended to 48dp for `xs` and `sm` sizes.
+ *
+ * @example
+ * ```tsx
+ * <IconButton aria-label="Close" onClick={handleClose}>
+ *   <XIcon />
+ * </IconButton>
+ *
+ * <IconButton
+ *   variant="toggle"
+ *   selected={isBookmarked}
+ *   aria-label={isBookmarked ? "Remove bookmark" : "Bookmark"}
+ *   colorStyle="filled"
+ *   onClick={toggleBookmark}
+ * >
+ *   <BookmarkIcon />
+ * </IconButton>
+ * ```
+ *
+ * @see https://m3.material.io/components/icon-buttons/overview
+ */
+export declare const IconButton: React.NamedExoticComponent<(Omit<BaseIconButtonProps & {
+    variant?: "default";
+    selected?: never;
+}, "ref"> | Omit<BaseIconButtonProps & {
+    variant: "toggle";
+    selected: boolean;
+}, "ref">) & React.RefAttributes<HTMLButtonElement>>;
+export {};

package/dist/ui/icon.d.ts

@@ -0,0 +1,88 @@
+import * as React from "react";
+/**
+ * Props cho component {@link Icon}.
+ *
+ * Tất cả các trục biến thiên (variable font axes) được map trực tiếp sang `font-variation-settings`.
+ */
+export interface IconProps extends React.HTMLAttributes<HTMLSpanElement> {
+    /**
+     * Tên của Material Symbol theo định dạng snake_case.
+     * @example "home", "arrow_forward", "settings"
+     * @see https://fonts.google.com/icons
+     */
+    name: string;
+    /**
+     * Kiểu hình học (Geometric style variant) — tương ứng với font family được tải.
+     * @default "outlined"
+     */
+    variant?: "outlined" | "rounded" | "sharp";
+    /**
+     * Trục FILL. `0` = outlined (viền), `1` = filled (tràn màu).
+     * Có hiệu ứng spring khi `animateFill` là true.
+     * @default 0
+     */
+    fill?: 0 | 1;
+    /**
+     * Trục wght — độ dày của nét (stroke weight). Nên khớp với độ dày text xung quanh.
+     * @default 400
+     */
+    weight?: 100 | 200 | 300 | 400 | 500 | 600 | 700;
+    /**
+     * Trục GRAD — tinh chỉnh độ dày thị giác mà không ảnh hưởng tới layout.
+     * Dùng mức `-25` trên nền tối để bù trừ hiệu ứng phát sáng (halation).
+     * @default 0
+     */
+    grade?: -50 | -25 | 0 | 100 | 200;
+    /**
+     * 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`.
+     * Hãy để giá trị khớp với pixel sẽ render ra để thấy chất lượng tốt nhất.
+     * @default 24
+     */
+    opticalSize?: 20 | 24 | 40 | 48;
+    /**
+     * Ghi đè trực tiếp `font-size` bằng px. Trục `opsz` vẫn sẽ tuân theo thuộc tính `opticalSize`.
+     * @example size={18} opticalSize={20}
+     */
+    size?: number | "inherit";
+    /**
+     * 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`).
+     * Yêu cầu dependency `motion/react`.
+     * @default false
+     * @example <Icon name="favorite" fill={isLiked ? 1 : 0} animateFill />
+     */
+    animateFill?: boolean;
+}
+/**
+ * Component hiển thị Icon bằng Material Symbols (variable font).
+ *
+ * Hãy đảm bảo đã import CSS chứa font trước khi dùng:
+ * ```ts
+ * import '@bug-on/md3-react/material-symbols.css';
+ * ```
+ *
+ * @remarks
+ * - Đặt tên icon dùng snake_case: `"arrow_forward"`, KHÔNG PHẢI `"ArrowForward"`.
+ * - 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.
+ *
+ * @example
+ * ```tsx
+ * // Icon cơ bản
+ * <Icon name="home" />
+ *
+ * // Tùy chỉnh trực quan (filled, nét dày)
+ * <Icon name="favorite" variant="rounded" fill={1} weight={300} />
+ *
+ * // Animate khi trạng thái thay đổi
+ * <Icon name="bookmark" fill={saved ? 1 : 0} animateFill />
+ *
+ * // Đổi kích thước icon cụ thể
+ * <Icon name="close" size={18} opticalSize={20} />
+ *
+ * // Kết hợp với các component khác
+ * <Button icon={<Icon name="add" />}>Thêm vào giỏ</Button>
+ * ```
+ *
+ * @see https://fonts.google.com/icons
+ * @see https://m3.material.io/styles/icons/overview
+ */
+export declare const Icon: React.NamedExoticComponent<IconProps & React.RefAttributes<HTMLSpanElement>>;

package/dist/ui/loading-indicator.d.ts

@@ -0,0 +1,42 @@
+import * as React from "react";
+export interface LoadingIndicatorProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "children"> {
+    /**
+     * Visual style variant.
+     * - `uncontained` (default): bare indicator, no container background
+     * - `contained`: indicator inside a circular container
+     *   (MD3 spec: 38dp container / 24dp active indicator)
+     */
+    variant?: "uncontained" | "contained";
+    /**
+     * Indicator size in dp (pixels). Clamped to the MD3 spec range [24dp, 240dp].
+     * Defaults to 48dp.
+     *
+     * Size guidelines:
+     * - Small displays: 24–48dp
+     * - Medium displays: 48–80dp
+     * - Large/XL displays (desktop): up to 240dp
+     *
+     * @default 48
+     */
+    size?: number;
+    /**
+     * Determinate progress value between 0 and 1.
+     * - **Omit** (default) for indeterminate mode: continuous morphing loop.
+     * - **Provide** for determinate mode: Circle→SoftBurst morph + counterclockwise rotation.
+     *
+     * @example `progress={0.7}` shows 70% progress
+     */
+    progress?: number;
+    /**
+     * Active indicator color override. Falls back to MD3 system color tokens.
+     * Supports any valid CSS color value or CSS variable.
+     * @example "#ff5722" | "var(--brand-color)"
+     */
+    color?: string;
+    /**
+     * Required accessible label describing what is loading.
+     * @example "Loading news article"
+     */
+    "aria-label": string;
+}
+export declare const LoadingIndicator: React.ForwardRefExoticComponent<LoadingIndicatorProps & React.RefAttributes<HTMLDivElement>>;

package/dist/ui/navigation-rail.d.ts

@@ -0,0 +1,29 @@
+import * as React from "react";
+export type NavigationRailVariant = "collapsed" | "expanded" | "modal";
+export type NavigationRailLabelVisibility = "labeled" | "auto" | "unlabeled";
+export interface NavigationRailItemProps {
+    selected: boolean;
+    icon: React.ReactNode;
+    label?: React.ReactNode;
+    onClick?: () => void;
+    disabled?: boolean;
+    badge?: React.ReactNode;
+    "aria-label"?: string;
+    className?: string;
+}
+export interface NavigationRailProps {
+    variant?: NavigationRailVariant;
+    labelVisibility?: NavigationRailLabelVisibility;
+    header?: React.ReactNode;
+    fab?: React.ReactNode;
+    footer?: React.ReactNode;
+    narrow?: boolean;
+    open?: boolean;
+    xr?: boolean | "contained" | "spatialized";
+    onClose?: () => void;
+    children: React.ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+}
+export declare const NavigationRailItem: React.NamedExoticComponent<NavigationRailItemProps & React.RefAttributes<HTMLButtonElement>>;
+export declare const NavigationRail: React.NamedExoticComponent<NavigationRailProps & React.RefAttributes<HTMLElement>>;

package/dist/ui/progress-indicator/circular.d.ts

@@ -0,0 +1,3 @@
+import * as React from "react";
+import type { CircularProgressProps } from "./types";
+export declare const CircularProgress: React.ForwardRefExoticComponent<CircularProgressProps & React.RefAttributes<HTMLDivElement>>;

package/dist/ui/progress-indicator/hooks.d.ts

@@ -0,0 +1,3 @@
+import * as React from "react";
+export declare function useContainerWidth(): readonly [(node: HTMLDivElement | null) => void, number];
+export declare function useMergedRef<T>(...refs: (React.Ref<T> | undefined | null)[]): React.RefCallback<T>;