@adyen/bento-vue2 1.37.0 → 1.38.0

package/README.md

@@ -40,6 +40,9 @@ Bento Vue contains foundational Vue 2.x (and Vue 3.x) UI components for shipping
         -   [Stylelint](#stylelint)
     -   [Theming](#theming)
         -   [⚠️ `BentoTheme.BENTO` deprecated ⚠️](#️-bentothemebento-deprecated-️)
+        -   [Light and dark themes](#light-and-dark-themes)
+            -   [Setting a default theme](#setting-a-default-theme)
+            -   [Toggling a theme](#toggling-a-theme)
         -   [ADL theme](#adl-theme)
             -   [Set **legacy ADL** theme as default](#set-legacy-adl-theme-as-default)
         -   [Setting themes without the Bento Plugin](#setting-themes-without-the-bento-plugin)
@@ -160,7 +163,8 @@ default value of `withDesignTokensCSSInjection` in the next major version of Ben
 
 We currently export the following styles:
 
--   Bento (default): `@adyen/bento-vue2/styles/bento`
+-   Bento light (default): `@adyen/bento-vue2/styles/bento-light`
+-   Bento dark: `@adyen/bento-vue2/styles/bento-dark`
 -   Legacy i.e. ADL (deprecated): `@adyen/bento-vue2/styles/legacy`
 -   Utility classes: `@adyen/bento-vue2/styles/utility`
 
@@ -168,7 +172,8 @@ NOTE: This way of importing bento styles will be mandatory in Bento 2.X
 
 ##### ⚠️ `bento.css` deprecated ⚠️
 
-The `bento.css` stylesheet is deprecated. It will be removed in v2.0.0. Please use the `bento-light.css` instead.
+The `@adyen/bento-vue2/styles/bento.css` stylesheet is deprecated. It will be removed in v2.0.0. Please use the
+`@adyen/bento-vue2/styles/bento-light.css` instead.
 
 ##### Vue 2
 
@@ -433,11 +438,10 @@ extends: [
 
 ## Theming
 
-Bento components can be themed with both themes provided out-of-the-box and with custom classes applied. At the current
-Bento component support themes. At present, there is only one alternative style provided out of the box: ADL theme (also
-known as Legacy theme).
+Bento components can be themed with both themes provided out-of-the-box and with custom classes applied.
 
-More extensive out-of-the-box theming support is planned and will come soon.
+> Note: It is not recommended to scope themes to individual components or page sections. The component library is
+> designed to be used with a consistent theme applied globally.
 
 ### ⚠️ `BentoTheme.BENTO` deprecated ⚠️
 
@@ -460,6 +464,56 @@ Vue.use(BentoVue, { theme: BentoTheme.BENTO_LIGHT });
 
 The Bento plugin defaults to `BentoTheme.BENTO_LIGHT` if unset.
 
+### Light and dark themes
+
+Starting from version v1.37.0, variables for the dark theme have been introduced, along with the `useBentoTheme`
+composable. This must be used together with the `BentoVue` plugin for theme toggling and configuration to function
+properly.
+
+#### Setting a default theme
+
+To set a default theme at the application level, ensure that the BentoVue plugin is properly integrated.
+
+```typescript
+// set default to light theme
+Vue.use(BentoVue, { theme: BentoTheme.BENTO_LIGHT });
+
+// set default to dark theme
+Vue.use(BentoVue, { theme: BentoTheme.BENTO_DARK });
+
+// set default to follow user preference
+// this is implemented using window.matchMedia(), so the behavior may vary across different browsers and systems
+Vue.use(BentoVue, { theme: BentoTheme.BENTO_SYSTEM });
+```
+
+#### Toggling a theme
+
+In your component logic, import the `useBentoTheme()` composable to manage theme switching.
+
+```html
+<template>
+    <button @click="toggleTheme">Change theme</button>
+</template>
+
+<script setup lang="ts">
+    import { BentoTheme, useBentoTheme } from '@adyen/bento-vue2';
+
+    const { getTheme, setTheme } = useBentoTheme();
+
+    const toggleTheme = () => {
+        if (getTheme() === BentoTheme.BENTO_DARK) {
+            setTheme(BentoTheme.BENTO_LIGHT);
+        } else {
+            setTheme(BentoTheme.BENTO_DARK);
+        }
+    };
+</script>
+```
+
+For enhanced accessibility, consider storing the user's theme preferences in `localStorage`, or respect the system’s
+theme settings by using `BentoTheme.BENTO_SYSTEM`. This ensures that the theme aligns with the user's browser or system
+preferences.
+
 ### ADL theme
 
 #### Set **legacy ADL** theme as default