test-bentoweb-ui 1.0.47 → 1.0.51

package/README.md

@@ -1,29 +1,225 @@
-# bentoweb-ui
-
-This template should help get you started developing with Vue 3 in Vite.
-
-## Recommended IDE Setup
-
-[VSCode](https://code.visualstudio.com/) + [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur).
-
-## Customize configuration
-
-See [Vite Configuration Reference](https://vitejs.dev/config/).
-
-## Project Setup
-
-```sh
-npm install
-```
-
-### Compile and Hot-Reload for Development
-
-```sh
-npm run dev
-```
-
-### Compile and Minify for Production
-
-```sh
-npm run build
-```
+# bentoweb-ui
+
+This template should help get you started developing with Vue 3 in Vite.
+
+## Recommended IDE Setup
+
+[VSCode](https://code.visualstudio.com/) + [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur).
+
+## Customize configuration
+
+See [Vite Configuration Reference](https://vitejs.dev/config/).
+
+## Project Setup
+
+```sh
+npm install
+```
+
+### Compile and Hot-Reload for Development
+
+```sh
+npm run dev
+```
+
+### Compile and Minify for Production
+
+```sh
+npm run build
+```
+
+# Bento UI Components
+
+## Swiper Components
+
+The Swiper components have been updated to use the official Swiper Element (WebComponent) instead of the deprecated vue-awesome-swiper.
+
+### SwiperBanner Usage
+
+```vue
+<template>
+  <SwiperBanner :BannerImage="bannerImages" size="xl" />
+</template>
+
+<script>
+import { SwiperBanner } from 'test-bentoweb-ui';
+
+export default {
+  components: {
+    SwiperBanner
+  },
+  data() {
+    return {
+      bannerImages: [
+        {
+          src: '/images/platform-btw.jpg',
+          link: '/platform'
+        },
+        {
+          src: '/images/t-shirt.jpg',
+          link: '/products'
+        },
+        {
+          src: 'https://example.com/external-image.jpg',
+          link: '/external'
+        }
+      ]
+    }
+  }
+}
+</script>
+```
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| 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) |
+
+The `src` property can be:
+- A path relative to the public directory (e.g., `/images/example.jpg`)
+- An absolute URL (e.g., `https://example.com/image.jpg`)
+
+The `link` property can be:
+- A Vue Router path for internal navigation (e.g., `/products`)
+- An external URL (e.g., `https://example.com`) which will open in a new tab
+
+### Banner Configurations
+
+The SwiperBanner component supports multiple layout configurations, all with proper aspect ratios to maintain consistent proportions across different screen sizes:
+
+#### Banner M (size="m")
+Small interactive banner with horizontal scrolling. Shows 1.2 slides on mobile and 2 slides on desktop.
+
+#### Banner L (size="l")
+Full-width banner with pagination bullets. This is the default configuration and was previously called 'xl'.
+
+#### Banner XL (size="xl")
+Two-column layout where the left column takes 60% of the width (16:9 aspect ratio) and the right column has two rows of smaller banners (21:10 aspect ratio). Requires at least 3 banner images.
+
+On mobile devices (screen width < 768px), this layout automatically switches to a regular swiper with pagination for better user experience.
+
+#### Grid-2 (size="grid-2")
+Two equal-width square banners side by side (1:1 aspect ratio). Requires at least 2 banner images. This layout has a maximum width of 900px and is centered on the page to prevent the square images from appearing too large on wide screens.
+
+On mobile devices (screen width < 768px), this layout automatically switches to a regular swiper with pagination for better user experience.
+
+#### Grid-6 (size="grid-6")
+3x2 grid of rectangle banners (16:9 aspect ratio). Requires at least 6 banner images for full display.
+
+On mobile devices (screen width < 768px), this layout automatically switches to a regular swiper with pagination for better user experience.
+
+### Usage Examples
+
+```vue
+<!-- Banner M - Small interactive banner -->
+<SwiperBanner :BannerImage="bannerImages" size="m" />
+
+<!-- Banner L - Full width banner with pagination (default) -->
+<SwiperBanner :BannerImage="bannerImages" size="l" />
+
+<!-- Banner XL - Two column layout -->
+<SwiperBanner :BannerImage="bannerImages" size="xl" />
+
+<!-- Grid-2 - Two square banners -->
+<SwiperBanner :BannerImage="bannerImages" size="grid-2" />
+
+<!-- Grid-6 - 3x2 grid of banners -->
+<SwiperBanner :BannerImage="bannerImages" size="grid-6" />
+```
+
+### Swiper Element Attributes
+
+When using Swiper Element (WebComponent), attributes must be passed as strings rather than bound objects:
+
+```vue
+<!-- Correct -->
+<swiper-container
+  slides-per-view="1"
+  pagination="true"
+  pagination-clickable="true"
+  autoplay-delay="2500"
+  breakpoints='{"768": {"slidesPerView": 2}}'
+>
+</swiper-container>
+
+<!-- Incorrect - will display as [object Object] -->
+<swiper-container
+  :pagination="{ clickable: true }"
+  :autoplay="{ delay: 2500 }"
+>
+</swiper-container>
+```
+
+For complex options like breakpoints, use a JSON string.
+
+### CSS Styling
+
+Swiper Element uses Shadow DOM, so CSS selectors need to use `::part()` to target internal elements. The element name must be included in the selector:
+
+```css
+/* Correct way to target Shadow DOM parts */
+swiper-container.banner-full::part(pagination) {
+  text-align: left;
+  padding-left: 0.9375rem;
+}
+
+swiper-container.banner-full::part(bullet) {
+  background-color: white;
+  width: 0.4375rem;
+  height: 0.4375rem;
+}
+
+swiper-container.banner-full::part(bullet-active) {
+  width: 0.9375rem;
+  border-radius: 0.3125rem;
+}
+
+/* This won't work */
+.banner-full ::part(bullet) {
+  background-color: white;
+}
+```
+
+Available parts include: `container`, `wrapper`, `slide`, `pagination`, `bullet`, `bullet-active`, and more. See the [Swiper Element documentation](https://swiperjs.com/element#parts) for a complete list.
+
+### SwiperInteractive Usage (Removed)
+
+The SwiperInteractive component has been removed. Please use the SwiperBanner component with `size="m"` instead:
+
+```vue
+<template>
+  <SwiperBanner :BannerImage="interactiveImages" size="m" />
+</template>
+
+<script>
+import { SwiperBanner } from 'test-bentoweb-ui';
+
+export default {
+  components: {
+    SwiperBanner
+  },
+  data() {
+    return {
+      interactiveImages: [
+        {
+          src: '/images/platform-btw.jpg',
+          link: '/platform'
+        },
+        {
+          src: '/images/t-shirt.jpg',
+          link: '/products'
+        },
+        {
+          src: '/images/vdo.jpg',
+          link: '/videos'
+        }
+      ]
+    }
+  }
+}
+</script>
+```
+
+The same path handling rules apply as for the standard SwiperBanner usage. Make sure your Vue Router is properly configured to handle these routes.