test-bentoweb-ui 1.0.74 → 1.0.76

package/README.md

@@ -1,6 +1,48 @@
-# bentoweb-ui
+# Bento UI - Component Library
 
-This template should help get you started developing with Vue 3 in Vite.
+A Vue 3 component library built with Vite, providing responsive and customizable UI components with built-in preview mode functionality for development and testing.
+
+## Project Overview
+
+### Core Features
+
+1. **Responsive Components**: All components are built with mobile-first design and responsive breakpoints
+2. **Preview Mode**: Core feature allowing developers to test desktop/mobile layouts without resizing browser
+3. **Swiper Integration**: Uses modern Swiper Element (Web Component) for carousel functionality
+4. **Flexible Layouts**: Multiple size and grid configurations for different use cases
+5. **Vue 3 Composition API**: Modern Vue 3 features for better performance and developer experience
+
+### Project Structure
+
+```
+bento-ui/
+├── src/
+│   ├── components/         # Vue components
+│   │   ├── BtwSwiperBanner.vue    # Main banner component with preview mode
+│   │   └── ...other components
+│   ├── assets/             # Static assets (images, styles)
+│   ├── composables/        # Vue 3 composables for shared logic
+│   └── utils/              # Helper functions and utilities
+├── public/                 # Public assets
+├── dist/                   # Build output (generated)
+└── package.json           # Dependencies and scripts
+```
+
+### Key Technologies
+
+- **Vue 3**: Progressive JavaScript framework
+- **Vite**: Fast build tool and dev server
+- **Swiper**: Modern touch slider library (using Web Components)
+- **SCSS**: Enhanced CSS with variables and mixins
+- **TypeScript Support**: Optional type safety
+
+### Design Philosophy
+
+1. **Component Reusability**: Components are designed to be flexible and reusable across different projects
+2. **Developer Experience**: Preview mode and clear documentation for easier development
+3. **Performance First**: Optimized for fast loading and smooth interactions
+4. **Responsive by Default**: All components work seamlessly across devices
+5. **Customizable**: Props and slots for extensive customization
 
 ## Recommended IDE Setup
 
@@ -76,6 +118,7 @@ export default {
 |------|------|---------|-------------|
 | BannerImage | Array | required | Array of objects with `src` and `link` properties |
 | size | String | 'l' | Size/layout of the banner. Options: 'm' (interactive style), 'l' (full banner with pagination), 'xl' (two-column layout), 'grid-2' (two square banners), 'grid-6' (3x2 grid of banners) |
+| previewMode | String | '' | Forces the component to display in a specific mode regardless of screen size. Options: '' (normal responsive), 'desktop' (forces desktop view), 'mobile' (forces mobile view) |
 
 The `src` property can be:
 - A path relative to the public directory (e.g., `/images/example.jpg`)
@@ -128,6 +171,102 @@ On mobile devices (screen width < 768px), this layout automatically switches to
 
 <!-- Grid-6 - 3x2 grid of banners -->
 <SwiperBanner :BannerImage="bannerImages" size="grid-6" />
+
+<!-- With Preview Mode - Force mobile view on desktop -->
+<SwiperBanner :BannerImage="bannerImages" size="xl" previewMode="mobile" />
+
+<!-- With Preview Mode - Force desktop view on mobile -->
+<SwiperBanner :BannerImage="bannerImages" size="grid-6" previewMode="desktop" />
+```
+
+### Preview Mode Feature
+
+The preview mode is a core feature of Bento UI components that allows developers to preview how components will appear on different devices without resizing the browser window. This is particularly useful during development and testing.
+
+#### How Preview Mode Works
+
+When `previewMode` is set:
+- **`previewMode="mobile"`**: Forces the component to display its mobile layout regardless of the actual screen size
+- **`previewMode="desktop"`**: Forces the component to display its desktop layout regardless of the actual screen size
+- **`previewMode=""` or not set**: Component uses normal responsive behavior based on actual screen width
+
+The preview mode:
+1. Overrides responsive breakpoints
+2. Applies fixed settings based on the selected mode
+3. Uses CSS classes to control layout visibility
+4. Maintains the appropriate interaction patterns (touch/swipe for mobile, click for desktop)
+
+This feature is implemented across Bento UI components to ensure consistent development and testing experience.
+
+### Development Workflow
+
+#### Local Development
+
+1. **Install dependencies**: `npm install`
+2. **Start dev server**: `npm run dev` - Launches Vite dev server with hot module replacement
+3. **Build for production**: `npm run build` - Creates optimized production build in `dist/`
+4. **Preview production build**: `npm run preview` - Test the production build locally
+
+#### Component Testing Environment
+
+The `src/views/DashboardView.vue` file serves as the primary testing environment for all Bento UI components. This view includes:
+
+- **Preview Mode Controls**: Buttons to toggle between mobile, desktop, and default responsive modes
+- **Live Component Testing**: All components are imported and tested with real data
+- **Interactive Examples**: Form inputs, color pickers, dropdowns, and other interactive elements
+- **Multiple Layout Tests**: Various banner sizes and configurations (grid-6, grid-2, xl, l, m)
+- **Real-world Data**: Sample products, flash sales, and other e-commerce data for testing
+
+Example from DashboardView.vue:
+```vue
+// Preview mode toggle buttons
+<button @click="togglePreviewMode('mobile')">Preview Mode mobile</button>
+<button @click="togglePreviewMode('desktop')">Preview Mode desktop</button>
+<button @click="togglePreviewMode('')">Preview Mode default</button>
+
+// Components with preview mode
+<SwiperBanner :slides="BannerImageXL" size="xl" :previewMode="previewModeMobile" />
+<BtwSpecialCategorySwiper
+  :specialProductsBannerList="featuredProducts"
+  :previewMode="previewModeMobile"
+/>
+```
+
+This centralized testing approach ensures all components work correctly together and maintain consistent behavior across different preview modes.
+
+#### Component Development Guidelines
+
+When creating or modifying components:
+
+1. **Always implement preview mode** for responsive components:
+   ```vue
+   props: {
+     previewMode: {
+       type: String,
+       default: '',
+       validator: (value) => ['', 'desktop', 'mobile'].includes(value),
+     }
+   }
+   ```
+
+2. **Use computed properties** for dynamic configurations based on props
+3. **Follow mobile-first approach** with progressive enhancement for larger screens
+4. **Maintain aspect ratios** for visual consistency across devices
+5. **Document all props** with clear descriptions and examples
+
+#### Testing Components
+
+Use the preview mode to test components in different viewport scenarios:
+
+```vue
+<!-- Test mobile layout on desktop browser -->
+<YourComponent previewMode="mobile" />
+
+<!-- Test desktop layout on mobile device -->
+<YourComponent previewMode="desktop" />
+
+<!-- Normal responsive behavior -->
+<YourComponent />
 ```
 
 ### Swiper Element Attributes