feat: restructure sass configuration

[whiplashwebb]

Fixes #150

The Problem

Theme Bulma works just fine until you try to configure the SCSS. This will work fine:

@use '@oruga-ui/theme-bulma/dist/scss/bulma-build';

but if you add a config value like this

@use '@oruga-ui/theme-bulma/dist/scss/bulma-build' with (
    $red: #f00,
    $table-sticky-header-height: 299px,
);

you'll get an error [sass] This module was already loaded, so it can't be configured using "with". $red is a Bulma variable and $table-sticky-header-height is a Theme Bulma variable. Either will cause the error. Interestingly if you only pass $primary the error will not occur.

Confusing, huh? The error complains about the order of the code, but the order of the code isn't changing, we're only passing config values. How can this even be possible? The answer appears to be hoisting. I can't find any sass documentation for this but it seems that when you have a defaulted sass variable like $example: #f00 !default; which is referenced by with (...) syntax, the file which contains $example is hoisted to the top of the pile of sass files being processed. This isn't always a problem but if the hoisted file references Bulma with an @use statement that @use can be shifted to an invalid position relative to other code. Typically this breaks src/assets/scss/components/utils/_variables.scss where the theme configures Bulma to pass secondary/custom color.

This problem is compounded by the fact that Theme Bulma needs to support two use cases: using Bulma as part of the theme or separate from it. The two code pathways can break differently in some situations.

The Solution

The solution is reorganizing Theme Bulma code to ensure that the primary bulma @use with (...) statement always comes first.

• All !default variables have been collected in two files mirroring the internal structure of Bulma.
  • _initial-defaults.scss collects all variables which do not reference Bulma. These variables have been placed before the main Bulma @use.
  • _derrived-defaults.scss collects all variables which do reference Bulma. These variables have been placed after the main Bulma @use.
• The primary Bulma @use has been moved to bulma-build.scss so its order can be easily controlled.
• src/assets/scss/components/utils/_variables.scss has been rewritten. Its purpose is the same, allowing you to pull Bulma variables into any theme component that needs them, but it is now hardened against hoisting errors and able to provide ALL variables from Bulma and the theme rather than just Bulma's derived variables. This is important because...
• All component files have been refactored to reference variables via _variables.scss. This provides a consistent pathway to variables where order can be preserved, even when the theme is being used separately from Bulma. References to Bulma mixins etc have been preserved as-is, they never error.
• component-only-build.scss has been added as the entrypoint for the separate bulma use-case. bulma.scss is unchanged but is now intended to be used internally as an entrypoint for component sass.
• Readme has been updated to reflect the changes and covers both theme use-cases.

I also made some secondary fixes to the theme development environment to make dev and testing easier.

• The main sass entrypoint has been moved from src/plugin/theme.ts to the new build.ts. This solves an issue where the style import in theme.ts was creating duplicate css based on the default values for color etc, making it impossible to see the changes made in the scss files.
• Added main-combined.scss and main-separated.scss to represent the two use cases so we can easily test either one. Combined is the default.
• Added pack:lib npm command and gitignore for the packed tarball. Very handy if you want to test in an external codebase.

[whiplashwebb]

@mlmoravek have another look at this PR when you get a sec. I refactored how the component defaults work to use the structure you proposed. I think this works a lot better now. I've created oruga-ui/oruga#1172 to update the docs scripting to handle the changes and tested it with new and old code. Everything appears to be working well.