@bug-on/m3-expressive 1.0.0 → 1.2.0

package/dist/layout.d.mts

@@ -13,21 +13,21 @@ declare const cardVariants: (props?: ({
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 type MotionDivProps = Omit<HTMLMotionProps<"button">, "children" | "color">;
 interface CardProps extends MotionDivProps, VariantProps<typeof cardVariants> {
-    /** Vô hiệu hóa tương tác và giảm opacity (MD3 disabled state). */
+    /** Disables interaction and reduces opacity (MD3 disabled state). */
     disabled?: boolean;
     /**
-     * Buộc card trở thành interactive dù không có `onClick`.
-     * Hữu ích khi card chứa các element con là interactive.
+     * Forces card to be interactive even without `onClick`.
+     * Useful when card contains child interactive elements.
      */
     interactive?: boolean;
     /**
-     * Nếu có, card render thành thẻ `<a>`. Tự động kích hoạt interactive mode.
-     * Ưu tiên dùng `href` thay vì `onClick` khi điều hướng trang.
+     * If provided, renders card as `<a>` element. Automatically enables interactive mode.
+     * Prefer `href` over `onClick` for page navigation.
      */
     href?: string;
-    /** Target cho thẻ `<a>` (chỉ có hiệu lực khi `href` được cung cấp). */
+    /** Target for `<a>` element (effective only when `href` is provided). */
     target?: React.AnchorHTMLAttributes<HTMLAnchorElement>["target"];
-    /** rel cho thẻ `<a>` (tự động thêm `noreferrer` khi `target="_blank"`). */
+    /** rel for `<a>` element (automatically adds `noreferrer` when `target="_blank"`). */
     rel?: string;
     children?: React.ReactNode;
 }
@@ -219,77 +219,77 @@ type ListItemPosition = "solo" | "leading" | "middle" | "trailing";
 type ListItemLeadingType = "none" | "icon" | "avatar" | "image" | "video" | "checkbox" | "radio" | "custom";
 type ListItemTrailingType = "none" | "icon" | "icon-button" | "text" | "checkbox" | "radio" | "switch" | "custom";
 interface ListProps extends Omit<React.HTMLAttributes<HTMLUListElement>, "onChange"> {
-    /** Variant của danh sách, hỗ trợ 'baseline' và 'expressive'. Default: 'baseline' */
+    /** List variant, supports 'baseline' and 'expressive'. Default: 'baseline' */
     variant?: ListVariant;
-    /** Kiểu hiển thị, hỗ trợ 'standard' (không khoảng cách) và 'segmented' (có gap 2px). Default: 'standard' */
+    /** Display style, supports 'standard' (no gap) and 'segmented' (2px gap). Default: 'standard' */
     listStyle?: ListStyle;
-    /** Chế độ chọn/tương tác của danh sách. Default: 'none' */
+    /** Selection/interaction mode of the list. Default: 'none' */
     selectionMode?: ListSelectionMode;
-    /** Giá trị đang được chọn (dành cho controlled). String cho single, string[] cho multi */
+    /** Currently selected value (for controlled mode). String for single, string[] for multi */
     value?: string | string[];
-    /** Giá trị được chọn mặc định ban đầu (dành cho uncontrolled) */
+    /** Default initial selected value (for uncontrolled mode) */
     defaultValue?: string | string[];
-    /** Callback khi giá trị thay đổi */
+    /** Callback fired when selection changes */
     onChange?: (value: string | string[]) => void;
-    /** Bật chế độ kéo thả sắp xếp danh sách */
+    /** Enable drag-and-drop reordering */
     reorderable?: boolean;
-    /** Mảng chứa dữ liệu các item khi sử dụng reorderable */
+    /** Data items array used with reorderable mode */
     items?: unknown[];
-    /** Callback trả về danh sách sau khi đã được sắp xếp lại */
+    /** Callback returning reordered items */
     onReorder?: (newItems: unknown[]) => void;
-    /** Custom radius góc ngoài (cho leading/trailing list items). Default từ spec MD3 Expressive là 16px */
+    /** Custom outer corner radius (for leading/trailing list items). Default per MD3 Expressive spec is 16px */
     outerRadius?: number;
-    /** Custom radius góc trong (cho các list items kề nhau). Default từ spec MD3 Expressive là 4px */
+    /** Custom inner corner radius (for adjacent list items). Default per MD3 Expressive spec is 4px */
     innerRadius?: number;
     children?: React.ReactNode;
 }
 type SafeHTMLLIAttrs = Omit<React.HTMLAttributes<HTMLLIElement>, "onClick" | "color" | "onDrag" | "onDragStart" | "onDragEnd" | "onDragEnter" | "onDragLeave" | "onDragOver" | "onDrop" | "onAnimationStart" | "onAnimationEnd" | "onAnimationIteration" | "onTransitionEnd">;
 interface ListItemProps extends SafeHTMLLIAttrs {
-    /** Giá trị định danh duy nhất cho ListItem */
+    /** Unique identifier value for the ListItem */
     value: string;
-    /** Tiêu đề chính của item */
+    /** Main headline title of the item */
     headline: React.ReactNode;
-    /** Văn bản hỗ trợ bên dưới tiêu đề */
+    /** Supporting text displayed below the headline */
     supportingText?: React.ReactNode;
-    /** Số dòng hiển thị tối đa của supportingText (1 hoặc 2) để tính chiều cao tương ứng. Default: 1 */
+    /** Max lines for supporting text (1 or 2) to calculate height. Default: 1 */
     supportingTextLines?: 1 | 2;
-    /** Văn bản nhỏ hiển thị phía trên tiêu đề chính */
+    /** Small overline text displayed above the main headline */
     overline?: React.ReactNode;
-    /** Loại thành phần hiển thị ở phần đầu dòng */
+    /** Type of element rendered at the start of the list item */
     leadingType?: ListItemLeadingType;
-    /** Đường dẫn hình ảnh/video nếu leadingType là 'image' hoặc 'video' */
+    /** Source URL for image or video when leadingType is 'image' or 'video' */
     leadingSrc?: string;
-    /** Alt text cho hình ảnh */
+    /** Alt text for image */
     leadingAlt?: string;
-    /** Custom content cho phần leading (sử dụng khi leadingType = 'custom') */
+    /** Custom leading content (used when leadingType = 'custom') */
     leadingContent?: React.ReactNode;
-    /** Loại thành phần hiển thị ở phần cuối dòng */
+    /** Type of element rendered at the end of the list item */
     trailingType?: ListItemTrailingType;
-    /** Văn bản hiển thị ở phần cuối dòng */
+    /** Text displayed at the end of the list item */
     trailingText?: string;
-    /** Custom content hoặc callback cho trailing element */
+    /** Custom content or callback for trailing element */
     trailingContent?: React.ReactNode;
-    /** Vô hiệu hóa tương tác */
+    /** Disable interaction */
     disabled?: boolean;
-    /** Trạng thái được chọn (áp dụng cho single-select / multi-select) */
+    /** Selected state (for single-select / multi-select) */
     selected?: boolean;
-    /** Địa chỉ liên kết nếu render ListItem dưới dạng thẻ Anchor <a> */
+    /** Target URL if rendering ListItem as an anchor <a> tag */
     href?: string;
-    /** Callback khi click vào ListItem */
+    /** Callback when clicking on ListItem */
     onClick?: (event: React.MouseEvent<HTMLElement>) => void;
-    /** Buộc item ở chế độ interactive (có hover/focus overlay, ripple) kể cả khi không truyền onClick/href */
+    /** Force interactive mode (hover/focus overlay, ripple) even without onClick/href */
     interactive?: boolean;
-    /** Bật chế độ chỉ kéo qua handle icon thay vì kéo toàn bộ item */
+    /** Enable drag handle icon drag restriction */
     dragHandle?: boolean;
-    /** Override vị trí của item trong danh sách (solo, leading, middle, trailing) */
+    /** Override position of item in list (solo, leading, middle, trailing) */
     position?: ListItemPosition;
-    /** Index nội bộ của item, được tự động truyền bởi List component */
+    /** Internal item index passed automatically by parent List */
     _listIndex?: number;
 }
 interface ListDividerProps extends React.HTMLAttributes<HTMLLIElement> {
-    /** Thụt lề đầu dòng của divider */
+    /** Indent start of divider */
     inset?: boolean;
-    /** Kiểu thụt lề: 'icon' (thụt lề 56px), 'avatar' (thụt lề 72px) hoặc 'custom' */
+    /** Indent style: 'icon' (56px indent), 'avatar' (72px indent), or 'custom' */
     insetType?: "icon" | "avatar" | "custom";
 }
 

package/dist/layout.d.ts

@@ -13,21 +13,21 @@ declare const cardVariants: (props?: ({
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 type MotionDivProps = Omit<HTMLMotionProps<"button">, "children" | "color">;
 interface CardProps extends MotionDivProps, VariantProps<typeof cardVariants> {
-    /** Vô hiệu hóa tương tác và giảm opacity (MD3 disabled state). */
+    /** Disables interaction and reduces opacity (MD3 disabled state). */
     disabled?: boolean;
     /**
-     * Buộc card trở thành interactive dù không có `onClick`.
-     * Hữu ích khi card chứa các element con là interactive.
+     * Forces card to be interactive even without `onClick`.
+     * Useful when card contains child interactive elements.
      */
     interactive?: boolean;
     /**
-     * Nếu có, card render thành thẻ `<a>`. Tự động kích hoạt interactive mode.
-     * Ưu tiên dùng `href` thay vì `onClick` khi điều hướng trang.
+     * If provided, renders card as `<a>` element. Automatically enables interactive mode.
+     * Prefer `href` over `onClick` for page navigation.
      */
     href?: string;
-    /** Target cho thẻ `<a>` (chỉ có hiệu lực khi `href` được cung cấp). */
+    /** Target for `<a>` element (effective only when `href` is provided). */
     target?: React.AnchorHTMLAttributes<HTMLAnchorElement>["target"];
-    /** rel cho thẻ `<a>` (tự động thêm `noreferrer` khi `target="_blank"`). */
+    /** rel for `<a>` element (automatically adds `noreferrer` when `target="_blank"`). */
     rel?: string;
     children?: React.ReactNode;
 }
@@ -219,77 +219,77 @@ type ListItemPosition = "solo" | "leading" | "middle" | "trailing";
 type ListItemLeadingType = "none" | "icon" | "avatar" | "image" | "video" | "checkbox" | "radio" | "custom";
 type ListItemTrailingType = "none" | "icon" | "icon-button" | "text" | "checkbox" | "radio" | "switch" | "custom";
 interface ListProps extends Omit<React.HTMLAttributes<HTMLUListElement>, "onChange"> {
-    /** Variant của danh sách, hỗ trợ 'baseline' và 'expressive'. Default: 'baseline' */
+    /** List variant, supports 'baseline' and 'expressive'. Default: 'baseline' */
     variant?: ListVariant;
-    /** Kiểu hiển thị, hỗ trợ 'standard' (không khoảng cách) và 'segmented' (có gap 2px). Default: 'standard' */
+    /** Display style, supports 'standard' (no gap) and 'segmented' (2px gap). Default: 'standard' */
     listStyle?: ListStyle;
-    /** Chế độ chọn/tương tác của danh sách. Default: 'none' */
+    /** Selection/interaction mode of the list. Default: 'none' */
     selectionMode?: ListSelectionMode;
-    /** Giá trị đang được chọn (dành cho controlled). String cho single, string[] cho multi */
+    /** Currently selected value (for controlled mode). String for single, string[] for multi */
     value?: string | string[];
-    /** Giá trị được chọn mặc định ban đầu (dành cho uncontrolled) */
+    /** Default initial selected value (for uncontrolled mode) */
     defaultValue?: string | string[];
-    /** Callback khi giá trị thay đổi */
+    /** Callback fired when selection changes */
     onChange?: (value: string | string[]) => void;
-    /** Bật chế độ kéo thả sắp xếp danh sách */
+    /** Enable drag-and-drop reordering */
     reorderable?: boolean;
-    /** Mảng chứa dữ liệu các item khi sử dụng reorderable */
+    /** Data items array used with reorderable mode */
     items?: unknown[];
-    /** Callback trả về danh sách sau khi đã được sắp xếp lại */
+    /** Callback returning reordered items */
     onReorder?: (newItems: unknown[]) => void;
-    /** Custom radius góc ngoài (cho leading/trailing list items). Default từ spec MD3 Expressive là 16px */
+    /** Custom outer corner radius (for leading/trailing list items). Default per MD3 Expressive spec is 16px */
     outerRadius?: number;
-    /** Custom radius góc trong (cho các list items kề nhau). Default từ spec MD3 Expressive là 4px */
+    /** Custom inner corner radius (for adjacent list items). Default per MD3 Expressive spec is 4px */
     innerRadius?: number;
     children?: React.ReactNode;
 }
 type SafeHTMLLIAttrs = Omit<React.HTMLAttributes<HTMLLIElement>, "onClick" | "color" | "onDrag" | "onDragStart" | "onDragEnd" | "onDragEnter" | "onDragLeave" | "onDragOver" | "onDrop" | "onAnimationStart" | "onAnimationEnd" | "onAnimationIteration" | "onTransitionEnd">;
 interface ListItemProps extends SafeHTMLLIAttrs {
-    /** Giá trị định danh duy nhất cho ListItem */
+    /** Unique identifier value for the ListItem */
     value: string;
-    /** Tiêu đề chính của item */
+    /** Main headline title of the item */
     headline: React.ReactNode;
-    /** Văn bản hỗ trợ bên dưới tiêu đề */
+    /** Supporting text displayed below the headline */
     supportingText?: React.ReactNode;
-    /** Số dòng hiển thị tối đa của supportingText (1 hoặc 2) để tính chiều cao tương ứng. Default: 1 */
+    /** Max lines for supporting text (1 or 2) to calculate height. Default: 1 */
     supportingTextLines?: 1 | 2;
-    /** Văn bản nhỏ hiển thị phía trên tiêu đề chính */
+    /** Small overline text displayed above the main headline */
     overline?: React.ReactNode;
-    /** Loại thành phần hiển thị ở phần đầu dòng */
+    /** Type of element rendered at the start of the list item */
     leadingType?: ListItemLeadingType;
-    /** Đường dẫn hình ảnh/video nếu leadingType là 'image' hoặc 'video' */
+    /** Source URL for image or video when leadingType is 'image' or 'video' */
     leadingSrc?: string;
-    /** Alt text cho hình ảnh */
+    /** Alt text for image */
     leadingAlt?: string;
-    /** Custom content cho phần leading (sử dụng khi leadingType = 'custom') */
+    /** Custom leading content (used when leadingType = 'custom') */
     leadingContent?: React.ReactNode;
-    /** Loại thành phần hiển thị ở phần cuối dòng */
+    /** Type of element rendered at the end of the list item */
     trailingType?: ListItemTrailingType;
-    /** Văn bản hiển thị ở phần cuối dòng */
+    /** Text displayed at the end of the list item */
     trailingText?: string;
-    /** Custom content hoặc callback cho trailing element */
+    /** Custom content or callback for trailing element */
     trailingContent?: React.ReactNode;
-    /** Vô hiệu hóa tương tác */
+    /** Disable interaction */
     disabled?: boolean;
-    /** Trạng thái được chọn (áp dụng cho single-select / multi-select) */
+    /** Selected state (for single-select / multi-select) */
     selected?: boolean;
-    /** Địa chỉ liên kết nếu render ListItem dưới dạng thẻ Anchor <a> */
+    /** Target URL if rendering ListItem as an anchor <a> tag */
     href?: string;
-    /** Callback khi click vào ListItem */
+    /** Callback when clicking on ListItem */
     onClick?: (event: React.MouseEvent<HTMLElement>) => void;
-    /** Buộc item ở chế độ interactive (có hover/focus overlay, ripple) kể cả khi không truyền onClick/href */
+    /** Force interactive mode (hover/focus overlay, ripple) even without onClick/href */
     interactive?: boolean;
-    /** Bật chế độ chỉ kéo qua handle icon thay vì kéo toàn bộ item */
+    /** Enable drag handle icon drag restriction */
     dragHandle?: boolean;
-    /** Override vị trí của item trong danh sách (solo, leading, middle, trailing) */
+    /** Override position of item in list (solo, leading, middle, trailing) */
     position?: ListItemPosition;
-    /** Index nội bộ của item, được tự động truyền bởi List component */
+    /** Internal item index passed automatically by parent List */
     _listIndex?: number;
 }
 interface ListDividerProps extends React.HTMLAttributes<HTMLLIElement> {
-    /** Thụt lề đầu dòng của divider */
+    /** Indent start of divider */
     inset?: boolean;
-    /** Kiểu thụt lề: 'icon' (thụt lề 56px), 'avatar' (thụt lề 72px) hoặc 'custom' */
+    /** Indent style: 'icon' (56px indent), 'avatar' (72px indent), or 'custom' */
     insetType?: "icon" | "avatar" | "custom";
 }
 

package/dist/layout.js

@@ -229,19 +229,19 @@ var CardImpl = React18__namespace.forwardRef(
     const baseClass = cn(
       cardVariants({ variant }),
       // Disabled state:
-      // - pointer-events-none → vô hiệu hóa tương tác hoàn toàn
+      // - pointer-events-none → disable interactions completely
       // - opacity-[0.38] → MD3 DisabledContainerOpacity
       disabled && "pointer-events-none opacity-[0.38]",
       className
     );
     const interactiveClass = cn(
-      // Xóa outline default, dùng state overlay & elevation của MD3 để biểu hiện focus
+      // Remove default outline, use MD3 state overlay & elevation for focus
       "focus-visible:outline-none focus:outline-none group",
-      // Layer overlay base pseudo-element
+      // Base pseudo-element overlay layer
       "before:absolute before:inset-0 before:pointer-events-none before:bg-m3-on-surface before:opacity-0 before:transition-opacity before:duration-200",
-      // Interactive states opacities
+      // Interactive state opacities
       "hover:before:opacity-[0.08] focus-visible:before:opacity-[0.10] active:before:opacity-[0.10]",
-      // Outlined interactive card: đổi màu border sang m3-outline khi focus/press/hover
+      // Outlined interactive card: change border color to m3-outline on focus/press/hover
       variant === "outlined" && "hover:border-m3-outline focus-visible:border-m3-outline active:border-m3-outline"
     );
     if (!isInteractive) {
@@ -1396,6 +1396,35 @@ var BUTTON_COLOR_TOKENS = {
     default: "bg-transparent text-m3-primary",
     selected: "bg-transparent text-m3-primary",
     unselected: "bg-transparent text-m3-primary"
+  },
+  // ── MD3 Expressive accent variants ──────────────────────────────────────
+  /**
+   * High-chroma tertiary tone. Use for hero CTAs and expressive moments where
+   * a distinct accent beyond primary is needed (e.g., hero chip, highlight fab).
+   */
+  tertiary: {
+    default: "bg-m3-tertiary text-m3-on-tertiary",
+    selected: "bg-m3-tertiary text-m3-on-tertiary",
+    unselected: "bg-m3-tertiary-container text-m3-on-tertiary-container"
+  },
+  /**
+   * Brand-stable primary fixed. Hue stays consistent across light and dark modes.
+   * Ideal for badges, pill chips, and elements that must carry the brand color
+   * regardless of the active theme.
+   */
+  "primary-fixed": {
+    default: "bg-m3-primary-fixed text-m3-on-primary-fixed",
+    selected: "bg-m3-primary-fixed text-m3-on-primary-fixed",
+    unselected: "bg-m3-primary-fixed text-m3-on-primary-fixed-variant"
+  },
+  /**
+   * Brand-stable tertiary fixed. Use for special-state indicators, achievement
+   * badges, or accent pills that need a fixed tertiary hue across themes.
+   */
+  "tertiary-fixed": {
+    default: "bg-m3-tertiary-fixed text-m3-on-tertiary-fixed",
+    selected: "bg-m3-tertiary-fixed text-m3-on-tertiary-fixed",
+    unselected: "bg-m3-tertiary-fixed text-m3-on-tertiary-fixed-variant"
   }
 };
 var MOTION_PROP_KEYS = [