@bug-on/m3-expressive 1.2.4 → 1.2.5

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @bug-on/m3-expressive
 
+## 1.2.5
+
+### Patch Changes
+
+- 97fb801: Add Select component Expose Menus, fix UI menu, readme
+- Updated dependencies [97fb801]
+  - @bug-on/m3-tailwind@1.2.1
+  - @bug-on/m3-tokens@1.2.1
+
 ## 1.2.4
 
 ### Patch Changes

package/README.md

@@ -1,73 +1,78 @@
 # @bug-on/m3-expressive
 
-> ⚠️ **Work in progress** — Material Design 3 Expressive React Component Library.
+[![npm version](https://img.shields.io/npm/v/@bug-on/m3-expressive.svg)](https://www.npmjs.com/package/@bug-on/m3-expressive)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Tailwind CSS v4](https://img.shields.io/badge/Tailwind_CSS-v4-38bdf8.svg)](https://tailwindcss.com/)
 
-High-performance React component library designed following the [Material Design 3 Expressive](https://m3.material.io/) design system. Featuring smooth motion, robust accessibility (a11y) support, and seamless compatibility with SSR and Next.js App Router.
+A high-performance, accessible React component library built strictly following the [Material Design 3 Expressive](https://m3.material.io/) design system specifications. Features fluid spring motion, flexible shape morphing, dynamic Material You color generation, SSR support, and native compatibility with Next.js 16 (App Router) and Tailwind CSS v4.
 
 ---
 
-## 📖 Documentation & Demos
-For component API guides, customization options, and interactive component previews, please visit:  
-👉 **[Official Documentation & Demos (GitHub Repository)](https://github.com/nguyentruongton/bug-on-md3-expressive)**
+## 📖 Documentation & Interactive Demos
+
+For detailed API references, interactive component playgrounds, and customization guides, visit:  
+👉 **[Official Documentation & Live Demos](https://bug-on-md3.vercel.app)**  
+👉 **[GitHub Repository](https://github.com/nguyentruongton/bug-on-md3-expressive)**
 
 ---
 
 ## 📦 Installation
 
-Install the React component package alongside core ecosystem packages:
-
 ```bash
-npm install @bug-on/m3-expressive @bug-on/m3-tailwind @bug-on/m3-tokens
+pnpm add @bug-on/m3-expressive motion
 # or
-pnpm add @bug-on/m3-expressive @bug-on/m3-tailwind @bug-on/m3-tokens
+npm install @bug-on/m3-expressive motion
 ```
 
-### Essential Peer Dependencies
-Ensure the following peer dependencies are installed in your project:
-```bash
-npm install react react-dom
-# Required for animated components (Fab, Tabs, Dialog, etc.):
-npm install motion
-```
+### Peer Dependencies
+
+Ensure your project includes the following peer dependencies:
+
+| Package | Version Requirement | Description |
+| :--- | :--- | :--- |
+| `react` | `>=18.0.0 || ^19.0.0` | Core React framework |
+| `react-dom` | `>=18.0.0 || ^19.0.0` | DOM renderer for React |
+| `motion` | `>=11.0.0` | Animation engine (FAB, Tabs, Dialogs, Sheets, etc.) |
+| `tailwindcss` | `>=4.0.0` | Utility CSS framework (CSS-first architecture) |
 
 ---
 
 ## 🛠️ Configuration & Setup (Tailwind CSS v4)
 
 > [!WARNING]
-> The library only supports **Tailwind CSS v4** (peer dependency `tailwindcss: ">=4.0.0"`). **Tailwind CSS v3 is no longer supported**.
+> This library requires **Tailwind CSS v4** (CSS-first configuration). Tailwind CSS v3 is not supported.
 
-This system is designed around the CSS-first architecture of **Tailwind CSS v4**. Setup is extremely simple and requires no JS/TS configuration files. Just import the stylesheets directly into your application's main CSS entry point (e.g., `globals.css` or `index.css`):
+Import the required stylesheets into your application's main CSS entry point (e.g. `globals.css` or `app/globals.css`):
 
 ```css
-/* 1. Import core Tailwind CSS v4 */
+/* 1. Core Tailwind CSS v4 */
 @import "tailwindcss";
 
-/* 2. Register core Design Tokens + Tailwind Theme + Resets (Zero Config) */
+/* 2. MD3 Expressive Tokens & Theme Resets */
 @import "@bug-on/m3-expressive/index.css";
 
-/* 3. (Optional) Integrate MD3 advanced utility classes (elevations, transitions, icons) */
+/* 3. (Optional) Extended MD3 Tailwind Utilities (Elevations, Transitions) */
 @import "@bug-on/m3-tailwind";
 
-/* 4. (Optional) Integrate specialized Typography CSS for React Components */
+/* 4. (Optional) Expressive Typography Preset Classes */
 @import "@bug-on/m3-expressive/typography.css";
 ```
 
-> **Zero Config:** Once `@bug-on/m3-expressive/index.css` is imported, basic MD3 utility classes (`bg-m3-primary`, `text-m3-on-surface`, `rounded-m3-xl`, etc.) work immediately. For the full set of utilities like depth shadows (`elevation-3`), icon axis control (`icon-fill-1`), or physics-based transitions (`transition-m3-fast-spatial`), import `@bug-on/m3-tailwind` as well. Do NOT use JS plugins in Tailwind v4.
+### Icon Font Setup (Material Symbols Outlined)
+
+The `<Icon />` component uses **Material Symbols Outlined**. You can choose CDN font delivery or self-hosted assets:
 
-### Icons Configuration (Material Symbols)
-The library includes a built-in `<Icon />` component using the `Material Symbols Outlined` font. Import the icon stylesheet at your application root (e.g., `layout.tsx` or `main.tsx`):
+#### Option A: Google Fonts CDN (Recommended for Web)
 
 ```tsx
 // app/layout.tsx or src/main.tsx
-import '@bug-on/m3-expressive/material-symbols-cdn.css';
-import { MaterialSymbolsPreconnect } from '@bug-on/m3-expressive';
+import "@bug-on/m3-expressive/material-symbols-cdn.css";
+import { MaterialSymbolsPreconnect } from "@bug-on/m3-expressive";
 
-export default function RootLayout({ children }) {
+export default function RootLayout({ children }: { children: React.ReactNode }) {
   return (
-    <html>
+    <html lang="en">
       <head>
-        {/* Preconnect helper to accelerate font loading */}
         <MaterialSymbolsPreconnect />
       </head>
       <body>{children}</body>
@@ -76,7 +81,9 @@ export default function RootLayout({ children }) {
 }
 ```
 
-For offline support or self-hosted font deployments:
+#### Option B: Offline / Self-Hosted Assets
+
+For air-gapped environments or offline font delivery, install `@bug-on/m3-fonts`:
 
 ```bash
 pnpm add @bug-on/m3-fonts
@@ -87,26 +94,106 @@ pnpm add @bug-on/m3-fonts
 @import "@bug-on/m3-fonts/typography.css";
 ```
 
-`@bug-on/m3-expressive/material-symbols-self-hosted.css` remains active for backward compatibility, but is deprecated and will be removed in the next major version.
+---
+
+## 🧩 Subpath Exports Guide
+
+To keep bundle sizes lean, `@bug-on/m3-expressive` offers dedicated subpath entrypoints:
+
+| Subpath Import | Module Contents |
+| :--- | :--- |
+| `@bug-on/m3-expressive/core` | `MD3ThemeProvider`, `createMd3ExpressiveTheme`, `generateM3Theme`, `applyTheme` |
+| `@bug-on/m3-expressive/buttons` | `Button`, `IconButton`, `FAB`, `ExtendedFAB`, `FABMenu`, `SplitButton`, `ButtonGroup`, `ButtonDistribute` |
+| `@bug-on/m3-expressive/forms` | `TextField`, `Checkbox`, `RadioButton`, `Switch`, `Slider`, `RangeSlider`, `Select`, `Search` |
+| `@bug-on/m3-expressive/navigation` | `NavigationBar`, `NavigationRail`, `NavigationDrawer`, `Tabs`, `Tab`, `TabsList`, `TabsContent`, `App Bar`, `Toolbar` |
+| `@bug-on/m3-expressive/overlays` | `Dialog`, `SideSheet`, `BottomSheet`, `Tooltip` |
+| `@bug-on/m3-expressive/feedback` | `Snackbar`, `SnackbarProvider`, `useSnackbar`, `ProgressIndicator`, `LoadingIndicator`, `Badge`, `BadgedBox` |
+| `@bug-on/m3-expressive/layout` | `Card`, `Divider`, `List`, `ListItem`, `ListDivider`, `ScrollArea`, `CodeBlock`, `TableOfContents` |
+| `@bug-on/m3-expressive/pickers` | `DatePicker`, `TimePicker` |
+| `@bug-on/m3-expressive/shapes` | `ShapeMedia`, `ShapeEngine`, `MD3Shape` utilities |
 
 ---
 
-## 🚀 Basic Usage
+## 🚀 Quick Code Example
 
 ```tsx
-import { Button, Icon } from '@bug-on/m3-expressive';
+import { MD3ThemeProvider } from "@bug-on/m3-expressive/core";
+import { Button } from "@bug-on/m3-expressive/buttons";
+import { TextField } from "@bug-on/m3-expressive/forms";
+import { Icon } from "@bug-on/m3-expressive";
 
-export default function Page() {
+export default function LoginCard() {
   return (
-    <div className="p-8 bg-m3-surface min-h-screen flex items-center justify-center">
-      <Button colorStyle="filled" size="md" icon={<Icon name="add" />}>
-        Get Started
-      </Button>
-    </div>
+    <MD3ThemeProvider sourceColor="#00639b" defaultMode="system">
+      <div className="p-6 bg-m3-surface text-m3-on-surface rounded-m3-extra-large shadow-m3-elevation-2 max-w-sm space-y-4">
+        <h2 className="text-m3-title-large font-bold">Welcome Back</h2>
+        
+        <TextField
+          label="Email Address"
+          variant="outlined"
+          leadingIcon={<Icon name="mail" />}
+        />
+        
+        <Button
+          colorStyle="filled"
+          size="md"
+          icon={<Icon name="arrow_forward" />}
+        >
+          Sign In
+        </Button>
+      </div>
+    </MD3ThemeProvider>
   );
 }
 ```
 
+---
+
+## 🎨 Component Inventory
+
+### 🔘 Buttons & Actions
+- **`Button`**: Filled, Elevated, Tonal, Outlined, Text variants.
+- **`IconButton`**: Standard, Filled, Tonal, Outlined, with toggle state support.
+- **`FAB` / `ExtendedFAB`**: Small, Medium, Large, Extended with label & animated icons.
+- **`FABMenu`**: Speed-dial style Floating Action Button expandable menu.
+- **`SplitButton`**: Combined primary button action with dropdown trigger.
+- **`ButtonGroup` / `ButtonDistribute`**: Grouped segmented buttons with shared shape states.
+
+### 📝 Forms & Inputs
+- **`TextField`**: Outlined and Filled variants with leading/trailing icons, error state, and helper text.
+- **`Checkbox`**: Standard and TriState indeterminate checkbox with animated checkmark.
+- **`RadioButton`**: Standard Material Design 3 single select options.
+- **`Switch`**: Toggle switch with optional inline icons.
+- **`Slider` / `RangeSlider`**: Continuous and discrete sliders with value tooltips and step indicators.
+- **`Select` / `Menu`**: Expressive dropdown select and popover menus.
+- **`Search`**: Search bar and full-screen Search View overlays.
+
+### 🧭 Navigation & Toolbars
+- **`NavigationBar`**: Bottom navigation bar with animated active indicators.
+- **`NavigationRail`**: Vertical navigation bar for wide displays and desktop screens.
+- **`NavigationDrawer`**: Standard docked and modal drawer components.
+- **`Tabs` / `Tab` / `TabsList` / `TabsContent`**: Primary and Secondary tabs with sliding indicator.
+- **`SmallAppBar` / `MediumFlexibleAppBar` / `LargeFlexibleAppBar` / `BottomAppBar`**: Collapsible & flexible app bars.
+- **`DockedToolbar`**: Expressive floating/docked action toolbar.
+
+### 🖼️ Overlays & Feedback
+- **`Dialog`**: Expressive alert and full-screen dialogs powered by Framer Motion.
+- **`SideSheet` / `BottomSheet`**: Modal and non-modal contextual sheets.
+- **`Tooltip`**: Plain and Rich tooltips with carets and call-to-action buttons.
+- **`Snackbar` / `SnackbarProvider` / `useSnackbar`**: Toast notification queue system.
+- **`ProgressIndicator`**: Circular and Linear progress bars (determinate, indeterminate, wavy).
+- **`LoadingIndicator`**: Expressive loading animation.
+- **`Badge` / `BadgedBox`**: Dot and numerical status badges.
+
+### 📐 Layout, Surfaces & Shapes
+- **`Card`**: Elevated, Filled, Outlined card surfaces.
+- **`Divider`**: Full-bleed and inset divider lines.
+- **`List` / `ListItem` / `ListDivider`**: Single and multi-line list items with avatar/icon slots.
+- **`ScrollArea`**: Styled scrollable container.
+- **`ShapeMedia`**: Morphing media frame supporting MD3 expressive shapes (Full, Extra Large, Large, Medium, Small).
+
+---
+
 ## ⚖️ License
-MIT
 
+[MIT](./LICENSE)

package/dist/buttons.d.mts

@@ -1,4 +1,4 @@
-export { B as BUTTON_COLOR_TOKENS, a as BUTTON_SIZE_TOKENS, b as BaseButtonProps, c as Button, d as ButtonDistribute, e as ButtonDistributeProps, f as ButtonGroup, g as ButtonGroupOrientation, h as ButtonGroupProps, i as ButtonGroupVariant, j as ButtonProps, D as DistributeMode, E as ElevatedSplitButtonLeading, k as ElevatedSplitButtonTrailing, l as ElevatedSplitButtonTrailingUncheckable, m as ExtendedFAB, n as ExtendedFABProps, F as FAB, o as FABMenu, p as FABMenuItem, q as FABMenuItemData, r as FABMenuItemProps, s as FABMenuProps, t as FABPosition, u as FABPositionProps, v as FABProps, w as FilledSplitButtonLeading, x as FilledSplitButtonTrailing, y as FilledSplitButtonTrailingUncheckable, O as OutlinedSplitButtonLeading, z as OutlinedSplitButtonTrailing, A as OutlinedSplitButtonTrailingUncheckable, S as SplitButtonLayout, C as SplitButtonLayoutProps, G as SplitButtonLeading, H as SplitButtonLeadingProps, I as SplitButtonSize, V as SplitButtonSizeTokens, J as SplitButtonTrailing, K as SplitButtonTrailingProps, L as SplitButtonTrailingUncheckable, M as SplitButtonTrailingUncheckableProps, N as SplitButtonVariant, T as ToggleFAB, P as ToggleFABProps, Q as TonalSplitButtonLeading, R as TonalSplitButtonTrailing, U as TonalSplitButtonTrailingUncheckable } from './split-button-trailing-uncheckable-BTWfIN2k.mjs';
+export { B as BUTTON_COLOR_TOKENS, a as BUTTON_SIZE_TOKENS, b as BaseButtonProps, c as Button, d as ButtonDistribute, e as ButtonDistributeProps, f as ButtonGroup, g as ButtonGroupOrientation, h as ButtonGroupProps, i as ButtonGroupVariant, j as ButtonProps, D as DistributeMode, E as ElevatedSplitButtonLeading, k as ElevatedSplitButtonTrailing, l as ElevatedSplitButtonTrailingUncheckable, m as ExtendedFAB, n as ExtendedFABProps, F as FAB, o as FABMenu, p as FABMenuItem, q as FABMenuItemData, r as FABMenuItemProps, s as FABMenuProps, t as FABPosition, u as FABPositionProps, v as FABProps, w as FilledSplitButtonLeading, x as FilledSplitButtonTrailing, y as FilledSplitButtonTrailingUncheckable, O as OutlinedSplitButtonLeading, z as OutlinedSplitButtonTrailing, A as OutlinedSplitButtonTrailingUncheckable, S as SplitButtonLayout, C as SplitButtonLayoutProps, G as SplitButtonLeading, H as SplitButtonLeadingProps, I as SplitButtonSize, V as SplitButtonSizeTokens, J as SplitButtonTrailing, K as SplitButtonTrailingProps, L as SplitButtonTrailingUncheckable, M as SplitButtonTrailingUncheckableProps, N as SplitButtonVariant, T as ToggleFAB, P as ToggleFABProps, Q as TonalSplitButtonLeading, R as TonalSplitButtonTrailing, U as TonalSplitButtonTrailingUncheckable } from './split-button-trailing-uncheckable-DPJL3bO6.mjs';
 import { Transition } from 'motion/react';
 import { b as MD3Size } from './md3-Dty-Qcad.mjs';
 export { B as BaseIconButtonProps, I as IconButton, a as IconButtonProps } from './icon-button-CSsDmuQC.mjs';

package/dist/buttons.d.ts

@@ -1,4 +1,4 @@
-export { B as BUTTON_COLOR_TOKENS, a as BUTTON_SIZE_TOKENS, b as BaseButtonProps, c as Button, d as ButtonDistribute, e as ButtonDistributeProps, f as ButtonGroup, g as ButtonGroupOrientation, h as ButtonGroupProps, i as ButtonGroupVariant, j as ButtonProps, D as DistributeMode, E as ElevatedSplitButtonLeading, k as ElevatedSplitButtonTrailing, l as ElevatedSplitButtonTrailingUncheckable, m as ExtendedFAB, n as ExtendedFABProps, F as FAB, o as FABMenu, p as FABMenuItem, q as FABMenuItemData, r as FABMenuItemProps, s as FABMenuProps, t as FABPosition, u as FABPositionProps, v as FABProps, w as FilledSplitButtonLeading, x as FilledSplitButtonTrailing, y as FilledSplitButtonTrailingUncheckable, O as OutlinedSplitButtonLeading, z as OutlinedSplitButtonTrailing, A as OutlinedSplitButtonTrailingUncheckable, S as SplitButtonLayout, C as SplitButtonLayoutProps, G as SplitButtonLeading, H as SplitButtonLeadingProps, I as SplitButtonSize, V as SplitButtonSizeTokens, J as SplitButtonTrailing, K as SplitButtonTrailingProps, L as SplitButtonTrailingUncheckable, M as SplitButtonTrailingUncheckableProps, N as SplitButtonVariant, T as ToggleFAB, P as ToggleFABProps, Q as TonalSplitButtonLeading, R as TonalSplitButtonTrailing, U as TonalSplitButtonTrailingUncheckable } from './split-button-trailing-uncheckable-DtxrcLxH.js';
+export { B as BUTTON_COLOR_TOKENS, a as BUTTON_SIZE_TOKENS, b as BaseButtonProps, c as Button, d as ButtonDistribute, e as ButtonDistributeProps, f as ButtonGroup, g as ButtonGroupOrientation, h as ButtonGroupProps, i as ButtonGroupVariant, j as ButtonProps, D as DistributeMode, E as ElevatedSplitButtonLeading, k as ElevatedSplitButtonTrailing, l as ElevatedSplitButtonTrailingUncheckable, m as ExtendedFAB, n as ExtendedFABProps, F as FAB, o as FABMenu, p as FABMenuItem, q as FABMenuItemData, r as FABMenuItemProps, s as FABMenuProps, t as FABPosition, u as FABPositionProps, v as FABProps, w as FilledSplitButtonLeading, x as FilledSplitButtonTrailing, y as FilledSplitButtonTrailingUncheckable, O as OutlinedSplitButtonLeading, z as OutlinedSplitButtonTrailing, A as OutlinedSplitButtonTrailingUncheckable, S as SplitButtonLayout, C as SplitButtonLayoutProps, G as SplitButtonLeading, H as SplitButtonLeadingProps, I as SplitButtonSize, V as SplitButtonSizeTokens, J as SplitButtonTrailing, K as SplitButtonTrailingProps, L as SplitButtonTrailingUncheckable, M as SplitButtonTrailingUncheckableProps, N as SplitButtonVariant, T as ToggleFAB, P as ToggleFABProps, Q as TonalSplitButtonLeading, R as TonalSplitButtonTrailing, U as TonalSplitButtonTrailingUncheckable } from './split-button-trailing-uncheckable--BhNTEJw.js';
 import { Transition } from 'motion/react';
 import { b as MD3Size } from './md3-Dty-Qcad.js';
 export { B as BaseIconButtonProps, I as IconButton, a as IconButtonProps } from './icon-button-CSsDmuQC.js';

package/dist/buttons.js

@@ -1100,6 +1100,7 @@ function TouchTarget() {
 }
 var BUTTON_SHAPE_MORPH_SPRING = FAST_SPATIAL_SPRING;
 var BUTTON_RADIUS_SPRING = FAST_EFFECTS_SPRING;
+var ROUND_SHAPE_RADIUS = 9999;
 var BUTTON_SIZE_TOKENS = {
   xs: {
     height: "2rem",
@@ -1118,7 +1119,7 @@ var BUTTON_SIZE_TOKENS = {
     // 12dp
     pressedShapeRadius: m3Tokens.cornerRadius.small,
     // 8dp
-    roundShapeRadius: 16
+    roundShapeRadius: ROUND_SHAPE_RADIUS
   },
   sm: {
     height: "2.5rem",
@@ -1137,7 +1138,7 @@ var BUTTON_SIZE_TOKENS = {
     // 12dp
     pressedShapeRadius: m3Tokens.cornerRadius.small,
     // 8dp
-    roundShapeRadius: 20
+    roundShapeRadius: ROUND_SHAPE_RADIUS
   },
   md: {
     height: "3.5rem",
@@ -1156,7 +1157,7 @@ var BUTTON_SIZE_TOKENS = {
     // 16dp
     pressedShapeRadius: m3Tokens.cornerRadius.medium,
     // 12dp
-    roundShapeRadius: 28
+    roundShapeRadius: ROUND_SHAPE_RADIUS
   },
   lg: {
     height: "6rem",
@@ -1175,7 +1176,7 @@ var BUTTON_SIZE_TOKENS = {
     // 28dp
     pressedShapeRadius: m3Tokens.cornerRadius.large,
     // 16dp
-    roundShapeRadius: 48
+    roundShapeRadius: ROUND_SHAPE_RADIUS
   },
   xl: {
     height: "8.5rem",
@@ -1194,7 +1195,7 @@ var BUTTON_SIZE_TOKENS = {
     // 28dp
     pressedShapeRadius: m3Tokens.cornerRadius.large,
     // 16dp
-    roundShapeRadius: 68
+    roundShapeRadius: ROUND_SHAPE_RADIUS
   }
 };
 var BUTTON_TYPOGRAPHY_TOKENS = {
@@ -1546,7 +1547,6 @@ var ButtonComponent = React16__namespace.forwardRef(
       react.m.button,
       __spreadProps(__spreadValues({
         ref,
-        layout: true,
         type: "button",
         "aria-pressed": isToggle ? isSelected : void 0,
         "aria-label": computedAriaLabel,