@qld-gov-au/qgds-bootstrap5 2.0.4 → 2.0.5

package/.esbuild/helpers/scssOverrideTheme.js

@@ -0,0 +1,40 @@
+import fs from "fs";
+import path from "path";
+
+/**
+ * Creates a temporary main.<themeVar>.scss file with the theme scss import injected after qld-variables import.
+ * Only creates/updates the file if content has changed or file doesn't exist.
+ * Returns the path to the temp file, or null if not created.
+ */
+export function createOverrideThemeScssEntry({ cssDir, mainScss, themeVar }) {
+  const themeFile = path.join(cssDir, `themes/${themeVar}.scss`);
+  const tempEntry = path.join(cssDir, `main.${themeVar}.scss`);
+
+  // Copy main.scss and inject Theme after qld-variables import
+  let mainContent = fs.readFileSync(mainScss, "utf8");
+  if (fs.existsSync(themeFile)) {
+    mainContent = `@import './themes/${themeVar}.scss';` + mainContent;
+  } else {
+    console.warn(
+      `[SCSS Theme] Warning: Theme variables file not found at ${themeFile}`,
+    );
+  }
+
+  // Only write file if it doesn't exist or content has changed
+  let shouldWrite = true;
+  if (fs.existsSync(tempEntry)) {
+    const existingContent = fs.readFileSync(tempEntry, "utf8");
+    shouldWrite = existingContent !== mainContent;
+  }
+
+  if (shouldWrite) {
+    fs.writeFileSync(tempEntry, mainContent);
+    console.log(`[SCSS Theme] Created/updated temp entry: ${tempEntry}`);
+  } else {
+    console.log(
+      `[SCSS Theme] No changes detected, reusing existing: ${tempEntry}`,
+    );
+  }
+
+  return tempEntry;
+}

package/.esbuild/plugins/qgds-plugin-handlebar-partial-builder.js

@@ -35,6 +35,10 @@ export default function QGDSupdateHandlebarsPartialsPlugin() {
             build.onStart(async () => {
 
                 const files = getAllFiles(COMPONENTS_DIR);
+                // Sort files alphabetically to ensure deterministic ordering
+                // This prevents TurboSnap cache invalidation in Chromatic builds
+                // caused by non-deterministic filesystem readdir ordering
+                files.sort();
                 //console.log(files);
                 const fileNames = new Map();
                 let duplicateFound = false;

package/.storybook/dynamicThemeDecorator.js

@@ -0,0 +1,155 @@
+const loadedThemes = new Map();
+const themeStyleElements = new Map();
+let currentTheme = "masterbrand";
+
+// Dynamic theme modules import for lazy loading
+// Automatically generate theme modules based on available theme files
+const themeModules = (() => {
+  const modules = {
+    customized: () => import("../src/css/main.scss"),
+  };
+
+  // Get all theme files in the themes directory
+  const themeContext = import.meta.glob("../src/css/main.*.scss", {
+    eager: false,
+  });
+
+  for (const [path, moduleImporter] of Object.entries(themeContext)) {
+    // Extract theme name from path (e.g., "../src/css/themes/main.test.scss" -> "test")
+    const match = path.match(/(?:main\.)?(\w+)\.scss$/);
+    if (match) {
+      const themeName = match[1];
+      // Only include main.*.scss files or individual theme files if no main.*.scss exists
+      if (path.includes(`main.${themeName}.scss`)) {
+        modules[themeName] = moduleImporter;
+      } else if (
+        !Object.keys(themeContext).some((p) =>
+          p.includes(`main.${themeName}.scss`),
+        )
+      ) {
+        // If no main.*.scss file exists for this theme, use the individual theme file
+        modules[themeName] = moduleImporter;
+      }
+    }
+  }
+
+  return modules;
+})();
+
+function mapStyleElementsByTheme(callback) {
+  // Handle both dev mode (style elements) and production mode (link elements)
+  const styleElements = document.querySelectorAll('style[type="text/css"]');
+  const linkElements = document.querySelectorAll('link[rel="stylesheet"]');
+
+  styleElements.forEach((element) => {
+    callback(element);
+  });
+
+  linkElements.forEach((element) => {
+    callback(element);
+  });
+}
+
+const unloadTheme = (themeName) => {
+  // Cache current theme's style elements before removing
+  // Remove existing style elements for current theme
+  const currentStyleElements = [];
+  const themeNotExist = themeName && !themeStyleElements.has(themeName);
+  mapStyleElementsByTheme((element) => {
+    if (themeNotExist) {
+      currentStyleElements.push(element.cloneNode(true));
+    }
+    element.remove();
+  });
+
+  if (currentStyleElements.length > 0) {
+    themeStyleElements.set(themeName, currentStyleElements);
+  }
+};
+
+const loadTheme = async (themeName) => {
+  // Unload current theme if it's different
+  if (currentTheme && currentTheme !== themeName) {
+    unloadTheme(currentTheme);
+  }
+
+  // If theme style elements are cached, restore them
+  if (themeStyleElements.has(themeName)) {
+    const cachedElements = themeStyleElements.get(themeName);
+    cachedElements.forEach((element) => {
+      document.head.appendChild(element.cloneNode(true));
+    });
+    currentTheme = themeName;
+    return;
+  }
+
+  // If theme is already loaded, no need to reload
+  if (loadedThemes.has(themeName)) {
+    currentTheme = themeName;
+    return;
+  }
+
+  const themeModuleImporter = themeModules[themeName];
+  if (themeModuleImporter) {
+    try {
+      // Import the theme module to trigger SCSS loading
+      await themeModuleImporter();
+
+      // Cache the newly created style elements
+      const newStyleElements = [];
+
+      mapStyleElementsByTheme((element) => {
+        newStyleElements.push(element.cloneNode(true));
+      });
+      if (newStyleElements.length > 0) {
+        themeStyleElements.set(themeName, newStyleElements);
+      }
+
+      // Store references
+      loadedThemes.set(themeName, true);
+      currentTheme = themeName;
+    } catch (error) {
+      console.warn(`Failed to load theme: ${themeName}`, error);
+    }
+  }
+};
+
+export const withDynamicTheme = (Story, context) => {
+  const { globals } = context;
+  const themeName = globals.themeName || "customized";
+
+  loadTheme(themeName);
+
+  return Story();
+};
+
+export const dynamicThemeGlobalTypes = {
+  themeName: {
+    name: "Theme Palette",
+    description: "Theme palette selector",
+    defaultValue: "masterbrand",
+    toolbar: {
+      icon: "switchalt",
+      items: (() => {
+        // Dynamically generate toolbar items from available themes
+        const items = [];
+
+        // Add items for all discovered themes
+        Object.keys(themeModules).forEach((themeName) => {
+          if (themeName !== "customized") {
+            const capitalizedName =
+              themeName.charAt(0).toUpperCase() + themeName.slice(1);
+            items.push({
+              value: themeName,
+              title: `${capitalizedName} theme`,
+            });
+          }
+        });
+        items.push({ value: "customized", title: "Customized theme" });
+        return items;
+      })(),
+      showName: true,
+      dynamicTitle: true,
+    },
+  },
+};

package/.storybook/main.js

@@ -46,6 +46,12 @@ const config = {
 
   viteFinal: async (config, { configType }) => {
     config.root = "./dist";
+    
+    // Define environment variables for the browser
+    config.define = {
+      ...config.define,
+      'import.meta.env.ENABLE_DYNAMIC_THEME': JSON.stringify(process.env.ENABLE_DYNAMIC_THEME === 'true')
+    };
     // config.plugins.push({
     //     name: "html-transform",
     //     transform(src, id) {

package/.storybook/preview.js

@@ -1,14 +1,32 @@
 import "../node_modules/bootstrap/dist/js/bootstrap.bundle.min.js";
 import "../src/js/qld.bootstrap.js";
-import "../src/css/main.scss";
+import "../src/css/main.masterbrand.scss";
 import { withThemeByClassName } from "@storybook/addon-themes";
+import {
+  withDynamicTheme,
+  dynamicThemeGlobalTypes,
+} from "./dynamicThemeDecorator.js";
+
+// Check if dynamic theme should be enabled via environment variable
+const ENABLE_DYNAMIC_THEME = import.meta.env.ENABLE_DYNAMIC_THEME;
 import { allBackgrounds } from "./modes.js";
 import { INITIAL_VIEWPORTS } from "@storybook/addon-viewport";
 import init from "../src/js/handlebars.init.js";
 import Handlebars from "handlebars";
 
+// NOTE: TurboSnap Performance Warning
+// The handlebars.init.js import above loads handlebars.partials.js which is
+// auto-generated during build. Changes to this file trigger TurboSnap to
+// rebuild all stories. To prevent false positives:
+// 1. The generator plugin ensures deterministic file ordering
+// 2. The generated file is excluded from linting
+// See: .esbuild/plugins/qgds-plugin-handlebar-partial-builder.js
+
 /** @type { import('@storybook/html-vite').Preview } */
 const preview = {
+  globalTypes: {
+    ...(ENABLE_DYNAMIC_THEME ? dynamicThemeGlobalTypes : {}),
+  },
   parameters: {
     //actions: { argTypesRegex: "^on[A-Z].*" },
     chromatic: {
@@ -95,6 +113,7 @@ const preview = {
   },
 
   decorators: [
+    ...(ENABLE_DYNAMIC_THEME ? [withDynamicTheme] : []),
     // data-bs-theme="dark" won't be used
     withThemeByClassName({
       themes: {

package/README.md

@@ -87,25 +87,33 @@ mvn install
    ```
 
 4. Build the Design System CSS, Components and templates
+    
+    ```bash
+    npm run build
+    ```
+
+5. Build the same command as above, but with `:theme` following by args `${ThemePaletteName}`
+   This will generate a separate altertive CSS export named as `qld.${ThemePaletteName}.bootstrap.css`
+    
+    ```bash
+    npm run build:theme ${ThemePaletteName}
+    
+    npm run build:theme -- --theme=${ThemePaletteA} --theme=${ThemePaletteB}
+    ```
+
+6.  Start Watch and Storybook for component development
+        
+    ```bash
+    npm run dev-storybook
+    ```
+     Alt:
+     ```bash
+     npm run watch
+     npm run storybook
+     ```
+
+7. Lint
 
-   ```bash
-   npm run build
-   ```
-
-5. Start Watch and Storybook for component development
-
-   ```bash
-   npm run dev-storybook
-   ```
-
-   Alt:
-
-   ```bash
-   npm run watch
-   npm run storybook
-   ```
-
-6. Lint
    ```bash
    npm run lint
    ```

package/dist/README.md

@@ -87,25 +87,33 @@ mvn install
    ```
 
 4. Build the Design System CSS, Components and templates
+    
+    ```bash
+    npm run build
+    ```
+
+5. Build the same command as above, but with `:theme` following by args `${ThemePaletteName}`
+   This will generate a separate altertive CSS export named as `qld.${ThemePaletteName}.bootstrap.css`
+    
+    ```bash
+    npm run build:theme ${ThemePaletteName}
+    
+    npm run build:theme -- --theme=${ThemePaletteA} --theme=${ThemePaletteB}
+    ```
+
+6.  Start Watch and Storybook for component development
+        
+    ```bash
+    npm run dev-storybook
+    ```
+     Alt:
+     ```bash
+     npm run watch
+     npm run storybook
+     ```
+
+7. Lint
 
-   ```bash
-   npm run build
-   ```
-
-5. Start Watch and Storybook for component development
-
-   ```bash
-   npm run dev-storybook
-   ```
-
-   Alt:
-
-   ```bash
-   npm run watch
-   npm run storybook
-   ```
-
-6. Lint
    ```bash
    npm run lint
    ```

package/dist/assets/components/bs5/head/head.hbs

@@ -1,5 +1,5 @@
 
-<!-- VERSION_DETAILS={"project_id":"@qld-gov-au/qgds-bootstrap5","version":"2.0.4","branch":"HEAD","tag":"v2.0.4","commit":"0b896ac48e7daadbef3fdbd2caccc437be120856","majorVersion":"v2"} -->
+<!-- VERSION_DETAILS={"project_id":"@qld-gov-au/qgds-bootstrap5","version":"2.0.5","branch":"HEAD","tag":"v2.0.5","commit":"7972857bf46e8fa3db8ca361447711262fffc21e","majorVersion":"v2"} -->
 
 {{! Select environment, used verbatium if not using predefind key
 cdn := PROD|STAGING|BETA|TEST|DEV|???