Sass configuration refactor

.gitignore

@@ -6,3 +6,4 @@ dist-ssr
 *.log
 .vscode
 .idea
+*.tgz

README.md

@@ -48,65 +48,89 @@ Please note, this package can be used without importing any other Oruga styling
 
 Bulma is a highly customizable CSS framework. From colors to typography, spacing and sizes, forms and layouts, all parts of Bulma can be customized by the user (see [Bulma Customization](https://bulma.io/documentation/customize/concepts/)).
 
-Using the following sample code you **don't need** `import '@oruga-ui/theme-bulma/dist/bulma.css'` but you have to add a custom sass/scss file to customize Bulma and the theme variables. 
-To overwrite Bulma’s Sass variables with your own values, you have to use `@use` and the `with` keyword, which takes a Sass map.
-You have two options for including the theme: include all the styling at once (including full bulma), or include the Oruga theme and Bulma separately.
+To use the examples below start by creating a custom sass/scss file like `main.scss` (you can call it anything) and import it instead of `bulma.css` like this:
 
-```scss
-// Option A: Include all styling (including bulma)
+```js
+import { createApp } from 'vue'
+import App from './App.vue'
+
+import Oruga from '@oruga-ui/oruga-next'
+import { bulmaConfig } from '@oruga-ui/theme-bulma'
+
+import './main.scss'
+
+createApp(App)
+    .use(Oruga, bulmaConfig)
+    .mount('#app')
+```
+
+Inside `main.scss` you need to include Bulma styles and theme styles. You have two options for doing it: **combined** or **separated**. The theme features a combined entrypoint which includes Bulma styles and theme styles. This is best for most customization use cases as it handles some messy variable scope issues. The separated entrypoint only includes theme styles without Bulma. This gives you full control over how you import Bulma and how much of it you import, but you'll have to deal with the messy scope problems mentioned earlier. Unless it's critical you only include part of Bulma the separate method is best avoided.
 
+#### The Combined Method
+
+The combined method is fairly straitforward. Define custom variables and then pass them in using `with()` syntax. You can override any variable in Bulma or the theme which has a `!default` by passing it in this way. 
+
+If you need to add custom color variants with this method you must use the `$theme-bulma-custom-colors` variable.
+
+```scss
 // set your color overrides
 $primary: #8c67ef;
+$red: #f00;
 $link: $primary;
 
 // add new colors to the colors map
-$twitter: #4099FF;
-$custom-colors: ('twitter': $twitter);
+$theme-bulma-custom-colors: ('tertiary': $red);
 
-// Include the Oruga Bulma theme with Bulma included (you can only manipulate any derived variables here)
+// Include the Oruga Bulma theme with Bulma included
 @use '@oruga-ui/theme-bulma/dist/scss/bulma-build' with (
     $family-primary: '"Nunito", sans-serif',
     $primary: $primary,
     $link: $link,
-    $custom-colors: $custom-colors,
+    $theme-bulma-custom-colors: $custom-colors,
 );
 
 // Then add additional custom code here
 // ...
 ```
-**_NOTE:_** Note that only variables within Bulma's [derived-variables.scss](https://github.com/jgthms/bulma/blob/main/sass/utilities/derived-variables.scss) file can be overridden here.
 
-```scss
-// Option B: Include the Oruga theme and Bulma separately
+#### The Separated Method
+When using this method the main thing to be aware of is `$custom-colors`. In the combined method the theme will add Oruga's standard `secondary` color variant for you and you can add additional variants using `$theme-bulma-custom-colors`. Using the separate method you need to do this in your code instead using Bulma's `$custom-colors` var, which will be implicitly passed to the theme behind the scenes. 
 
-// set your color overrides
-$primary: #8c67ef;
-$link: $primary;
-
-// add new colors to the colors map
-$twitter: #4099FF;
-$custom-colors: ('twitter': $twitter);
+```scss
+// Assemble color variables
+$red: #f00;
+$green: #0f0;
+$blue: #00f;
+$black: #000;
+$dark-grey: #6c757d;
+$speed-slower: 1000ms;
+
+// Custom colors is required if you want the secondary variant. Nothing will break if you omit it though.
+$custom-colors: (
+    // Add the standard Oruga secondary variant
+    'secondary': $dark-grey,
+    // If you want to add additional custom colors add them here
+    'tertiary': $red
+);
 
-// 1. Include the Oruga theme first (you can only manipulate any derived variables here)
-@use '@oruga-ui/theme-bulma/dist/scss/bulma' with (
-    $family-primary: '"Nunito", sans-serif',
-    $primary: $primary,
-    $link: $link,
+// Pass any Bulma vars you'd like to override here
+@use "bulma/sass" with (
+    $red: $red,
+    $blue: $blue,
+    $green: $green,
+    $black: $black,
+    $primary: $green,
     $custom-colors: $custom-colors,
 );
 
-// 2. Include any other Bulma module with specific configuration here
-@use "bulma/sass/elements" with (
-    $button-weight: 800
+// Pass any theme vars you'd like to override here
+@use "@oruga-ui/theme-bulma/dist/scss/component-only-build.scss" with (
+    $speed-slower: $speed-slower,
 );
-
-// 3. Include the remaining parts or full Bulma
-@use "bulma/sass";
-
-// Then add additional custom code here
-// ...
 ```
 
+The other thing to be aware of is when you're importing Bulma. `@use "bulma/sass" with (...)` **MUST** come before all other Bulma usage. This is where the messy scope issues come in. If you reference Bulma beforehand, for example to use a Bulma mixin to create a color to pass into Bulma, you're going to get SASS errors.
+
 ### Override default config
 
 In case you want to replace the default style of a component you can override or add new classes changing ``bulmaConfig``; more details about components customization on https://oruga-ui.com/documentation/customisation.html

package.json

@@ -28,7 +28,8 @@
     "build": "vue-tsc --noEmit && vite build",
     "lint": "eslint . --fix --quiet",
     "lint:style": "stylelint **/*.{css,scss} --fix --ignore-path .gitignore",
-    "update": "ncu -u"
+    "update": "ncu -u",
+    "pack:lib": "rm -rf dist && npm run build && echo \"$PWD/$(npm pack)\""
   },
   "peerDependencies": {
     "@oruga-ui/oruga-next": "^0.9.0"

src/assets/scss/_derived-defaults.scss

@@ -0,0 +1,116 @@
+// This file is home to defaulted variables which DO reference bulma
+
+@use "bulma/sass/utilities/initial-variables" as iv;
+@use "bulma/sass/utilities/derived-variables" as dv;
+@use "bulma/sass/utilities/css-variables" as css;
+@use "bulma/sass/form/file" as file;
+
+/* @docs */
+$sizes-map: (
+    "small": dv.$size-small,
+    "normal": dv.$size-normal,
+    "medium": dv.$size-medium,
+    "large": dv.$size-large,
+) !default;
+
+$carousel-arrow-background: css.getVar("scheme-main") !default;
+$carousel-arrow-color: css.getVar("primary") !default;
+$carousel-indicator-background: rgba(css.getVar("scheme-invert"), 0.5) !default;
+$carousel-indicator-border: css.getVar("scheme-main") !default;
+$carousel-indicator-color: css.getVar("primary") !default;
+$carousel-overlay-background: rgba(css.getVar("scheme-invert"), 0.86) !default;
+
+$checkbox-colors: dv.$colors !default;
+$checkbox-border-color: css.getVar("grey") !default;
+$checkbox-border-radius: css.getVar("radius") !default;
+$checkbox-checkmark-color: css.getVar("primary-invert") !default;
+$checkbox-focus-color: hsl(from css.getVar("grey") h s l / 80%) !default;
+$checkbox-active-focus-color: hsl(
+        from css.getVar("checkbox-active-background-color") h s l / 80%
+) !default;
+$checkbox-active-background-color: css.getVar("primary") !default;
+$checkbox-shadow: css.getVar("shadow");
+
+$datepicker-colors: dv.$colors !default;
+$datepicker-header-color: css.getVar("grey") !default;
+$datepicker-today-border: solid 1px rgba(css.getVar("primary"), 0.5) !default;
+$datepicker-item-color: css.getVar("grey-dark") !default;
+$datepicker-item-disabled-color: css.getVar("grey-light") !default;
+$datepicker-item-hover-color: css.getVar("scheme-invert") !default;
+$datepicker-item-hover-background-color: css.getVar("background") !default;
+$datepicker-item-selected-color: css.getVar("primary-invert") !default;
+$datepicker-item-selected-background-color: css.getVar("primary") !default;
+$datepicker-event-background-color: css.getVar("grey-light") !default;
+
+$dropdown-mobile-breakpoint: iv.$desktop !default;
+$dropdown-background-background-color: hsla(
+        #{css.getVar("scheme-h")},
+        #{css.getVar("scheme-s")},
+        #{css.getVar("scheme-invert-l")},
+        0.86
+) !default;
+
+$radio-colors: dv.$colors !default;
+$radio-active-background-color: css.getVar("primary") !default;
+$radio-border-color: css.getVar("grey") !default;
+$radio-shadow: css.getVar("shadow");
+
+$sidebar-colors: dv.$colors !default;
+$sidebar-background-background-color: hsla(
+        #{css.getVar("scheme-h")},
+        #{css.getVar("scheme-s")},
+        #{css.getVar("scheme-invert-l")},
+        0.86
+) !default;
+$sidebar-shadow: css.getVar("shadow");
+
+$skeleton-border-radius: css.getVar("radius") !default;
+
+$slider-colors: dv.$colors !default;
+$slider-radius: css.getVar("radius") !default;
+$slider-background: css.getVar("grey-lighter") !default;
+$slider-color: css.getVar("primary") !default;
+$slider-track-border: 0px solid css.getVar("grey") !default;
+$slider-track-shadow: 0px 0px 0px css.getVar("grey") !default;
+$slider-thumb-background: css.getVar("scheme-main") !default;
+$slider-thumb-radius: css.getVar("radius") !default;
+$slider-thumb-border: 1px solid css.getVar("grey-light") !default;
+$slider-tick-radius: css.getVar("radius") !default;
+$slider-tick-background: css.getVar("grey-light") !default;
+
+$steps-colors: dv.$colors !default;
+$steps-mobile-breakpoint: iv.$tablet !default;
+$steps-marker-background: css.getVar("grey-light") !default;
+$steps-marker-color: css.getVar("scheme-main") !default;
+$steps-marker-border: 0.2em solid css.getVar("white") !default;
+$steps-default-color: css.getVar("grey-lighter") !default;
+$steps-previous-color: css.getVar("scheme-main") !default;
+$steps-previous-background: css.getVar("primary") !default;
+$steps-active-color: css.getVar("primary") !default;
+$steps-active-background: css.getVar("scheme-main") !default;
+$steps-details-background-color: css.getVar("body-background-color") !default;
+
+$switch-colors: dv.$colors !default;
+$switch-background-color: css.getVar("grey-light") !default;
+$switch-active-background-color: css.getVar("primary") !default;
+$switch-shadow: css.getVar("shadow");
+
+$tabs-link-focus-border-bottom-color: css.getVar("tabs-link-hover-border-bottom-color") !default;
+$tabs-link-focus-active-border-bottom-color: css.getVar("tabs-link-active-border-bottom-color") !default;
+$tabs-boxed-link-focus-active-background-color: css.getVar("tabs-boxed-link-active-background-color") !default;
+$tabs-boxed-link-focus-background-color: css.getVar("tabs-boxed-link-hover-background-color") !default;
+$tabs-boxed-link-focus-active-border-bottom-color: css.getVar("tabs-boxed-link-active-border-bottom-color") !default;
+$tabs-boxed-link-focus-border-bottom-color: css.getVar("tabs-boxed-link-hover-border-bottom-color") !default;
+$tabs-toggle-link-focus-active-background-color: css.getVar("tabs-toggle-link-active-background-color") !default;
+$tabs-toggle-link-focus-background-color: css.getVar("tabs-toggle-link-hover-background-color") !default;
+$tabs-toggle-link-focus-active-border-color: css.getVar("tabs-toggle-link-active-border-color") !default;
+$tabs-toggle-link-focus-border-color: css.getVar("tabs-toggle-link-hover-border-color") !default;
+
+$tooltip-colors: dv.$colors !default;
+$tooltip-border-radius: css.getVar("radius") !default;
+$tooltip-bg: css.getVar("scheme-main-bis") !default;
+$tooltip-color: css.getVar("text-body") !default;
+
+$upload-colors: file.$file-colors !default;
+$upload-border-color: css.getVar("grey-light") !default;
+/* @docs */

src/assets/scss/_initial-defaults.scss

@@ -0,0 +1,94 @@
+// This file is home to defaulted variables which DO NOT reference bulma
+
+@use "sass:map";
+
+/* @docs */
+$speed-slow: 150ms !default;
+$speed-slower: 250ms !default;
+
+// oruga defines an extra secondary color
+$secondary: #6c757d !default;
+
+// alternative to focus-shadow-size
+$active-shadow-size: 0 0 0.5em !default;
+
+// renamed with theme-bulma prefix to avoid namespace collision with the @forward below
+$theme-bulma-custom-colors: () !default;
+/* @docs */
+
+// Merge any user-defined custom colors with the custom colors defined by the theme. This will be passes to Bulma as $custom-colors
+// This is the one variable in this file which is not defaulted, but it collects defaulted values so it counts. It's going to be passed into bulma so it has to be here so it comes first
+$theme-bulma-custom-colors-merged: map.merge(
+    // merge our custom-colors with the overridable map
+    ("secondary": $secondary),
+    $theme-bulma-custom-colors
+);
+
+/* @docs */
+$carousel-arrow-icon-spaced: 1.5rem !default;
+$carousel-arrow-top: 50% !default;
+$carousel-indicator-spaced: 0.5rem !default;
+$carousel-overlay-z: 40 !default;
+
+$checkbox-size: 1.25em !default;
+$checkbox-background-color: transparent !default;
+$checkbox-border-width: 2px !default;
+
+$dropdown-content-max-height: 200px !default;
+
+$dropdown-disabled-opacity: 0.5 !default;
+$dropdown-gap: 0px !default;
+$dropdown-z: 40 !default;
+
+// Belongs to field
+$floating-in-height: 3.25em !default;
+
+$icon-spin-duration: 2s !default;
+
+$loading-background-color: rgba(255, 255, 255, 0.5) !default;
+$loading-icon-size: 3em !default;
+$loading-icon-size-full-page: 5em !default;
+$loading-z: 29 !default;
+
+$notification-margin-bottom: 1.5rem !default;
+$notification-notices-padding: 2em !default;
+$notification-notices-z: 1000 !default;
+
+$radio-size: 1.25em !default;
+
+$sidebar-z: 40;
+$sidebar-width: 260px !default;
+$sidebar-height: 260px !default;
+$sidebar-mobile-width: 80px !default;
+
+$skeleton-duration: 1.5s !default;
+$skeleton-margin-top: 0.5rem !default;
+
+$slider-tick-label-size: 0.75rem !default;
+$slider-thumb-shadow: none !default;
+$slider-thumb-to-track-ratio: 2 !default;
+$slider-tick-to-track-ratio: 0.5 !default;
+$slider-tick-width: 3px !default;
+
+$steps-divider-height: 0.2em !default;
+$steps-vertical-padding: 1em 0 !default;
+
+$switch-width: 2.75em !default;
+$switch-padding: 0.2em !default;
+
+$table-sticky-header-height: 300px !default;
+
+$tabs-focused-outline: none !default;
+
+$taginput-height: 2em !default;
+$taginput-tag-size: 0.9em !default;
+
+$tooltip-arrow-size: 5px !default;
+$tooltip-arrow-margin: 2px !default;
+$tooltip-content-multiline-width: 300px !default;
+$tooltip-shadow: 0 1px 2px 1px rgba(0, 1, 0, 0.2) !default;
+$tooltip-z: 38 !default;
+
+$upload-bg: transparent !default;
+$upload-draggable-padding: 0.5rem !default;
+/* @docs */

src/assets/scss/bulma-build.scss

@@ -1,3 +1,16 @@
-@forward "components/utils/all";
-@forward "bulma/sass";
+// This file is the entrypoint for the main css build (bulma.css)
+// It is also the scss entrypoint for users who want to configure Bulma and the theme together
+
+// Theme defaults must be explictly forwarded here, otherwise confusing error messages result from the lack of defaults.
+@forward "initial-defaults";
+@use "initial-defaults" as td;
+
+// the primary bulma forward must come before all usage to prevent issues where usage appears before the with() statement
+@forward "bulma/sass" with (
+    $custom-colors: td.$theme-bulma-custom-colors-merged,
+);
+
+@forward "derived-defaults";
+
+// Theme component scss
 @forward "bulma";

src/assets/scss/component-only-build.scss

@@ -0,0 +1,4 @@
+// This file is the scss entrypoint for users who want to include only theme styles
+
+@forward "initial-defaults";
+@forward "bulma";

src/assets/scss/components/_autocomplete.scss

@@ -1,14 +1,11 @@
 @use "bulma/sass/utilities/css-variables" as css;
 @use "bulma/sass/utilities/mixins" as mixins;
-
-/* @docs */
-$dropdown-content-max-height: 200px !default;
-/* @docs */
+@use "utils/variables" as vars;
 
 .autocomplete {
     @include css.register-vars(
         (
-            "dropdown-content-max-height": #{$dropdown-content-max-height},
+            "dropdown-content-max-height": #{vars.$dropdown-content-max-height},
         )
     );