@ui5/webcomponents-tools 0.0.0-4821618b2 → 0.0.0-49bade48d

package/lib/css-processors/css-processor-themes.mjs

@@ -0,0 +1,226 @@
+import { globby } from "globby";
+import * as esbuild from 'esbuild'
+import * as fs from "fs";
+import * as path from "path";
+import { writeFile, mkdir } from "fs/promises";
+import postcss from "postcss";
+import combineDuplicatedSelectors from "../postcss-combine-duplicated-selectors/index.js"
+import postcssPlugin from "./postcss-plugin.mjs";
+import { writeFileIfChanged, getFileContent } from "./shared.mjs";
+import scopeVariables from "./scope-variables.mjs";
+import { mergeLightDark } from "./merge-light-dark.mjs";
+import { pathToFileURL } from "url";
+
+/**
+ * Auto theme pairs: each entry defines a light theme, its dark counterpart,
+ * and the auto theme name that will be generated by merging them.
+ */
+const AUTO_THEME_PAIRS = [
+    { light: "sap_horizon", dark: "sap_horizon_dark", auto: "sap_horizon_auto" },
+    { light: "sap_horizon_hcw", dark: "sap_horizon_hcb", auto: "sap_horizon_hc_auto" },
+];
+
+const generate = async (argv) => {
+    const CSS_VARIABLES_TARGET = process.env.CSS_VARIABLES_TARGET === "host";
+    const tsMode = process.env.UI5_TS === "true";
+    const extension = tsMode ? ".css.ts" : ".css.js";
+
+    const packageJSON = JSON.parse(fs.readFileSync("./package.json"));
+    const basePackageJSON = (await import("@ui5/webcomponents-base/package.json", { with: { type: "json" } })).default;
+
+    const allInputFiles = await globby([
+        "src/**/parameters-bundle.css",
+    ]);
+
+    // Filter out auto theme placeholders - they will be generated from merging light + dark
+    const autoThemeNames = AUTO_THEME_PAIRS.map(p => p.auto);
+    const inputFiles = allInputFiles.filter(f => !autoThemeNames.some(name => f.includes(`/${name}/`)));
+
+    const restArgs = argv.slice(2);
+
+    const saveFiles = async (distPath, css, suffix = "") => {
+        await mkdir(path.dirname(distPath), { recursive: true });
+        writeFile(distPath.replace(".css", suffix + ".css"), css);
+
+        // JSON
+        const jsonPath = distPath.replace(/dist[\/\\]css/, "dist/generated/assets").replace(".css", suffix + ".css.json");
+        await mkdir(path.dirname(jsonPath), { recursive: true });
+        writeFileIfChanged(jsonPath, JSON.stringify(css));
+
+        // JS/TS
+        const jsPath = distPath.replace(/dist[\/\\]css/, "src/generated/").replace(".css", suffix + extension);
+        const jsContent = getFileContent(packageJSON.name, "\`" + css + "\`");
+        writeFileIfChanged(jsPath, jsContent);
+    }
+
+    const isThemingPackage = (filePath) => filePath.includes("packages/theming") || filePath.includes("packages\\theming");
+
+    const processThemingPackageFile = async (f) => {
+        const selector = ':root';
+        const result = await postcss().process(f.text, { from: undefined });
+
+        const newRule = postcss.rule({ selector });
+
+        result.root.walkRules(selector, rule => {
+            rule.walkDecls(decl => {
+                if (!decl.prop.startsWith('--sapFontUrl')) {
+                    newRule.append(decl.clone());
+                }
+            });
+        });
+
+        return { css: newRule.toString() };
+    };
+
+    const processComponentPackageFile = async (f) => {
+        if (CSS_VARIABLES_TARGET) {
+            const result = await postcss([
+                combineDuplicatedSelectors,
+                postcssPlugin
+            ]).process(f.text, { from: undefined });
+
+            return { css: result.css };
+        }
+
+
+        const combined = await postcss([
+            combineDuplicatedSelectors,
+        ]).process(f.text, { from: undefined });
+
+        return { css: scopeVariables(combined.css, basePackageJSON, f.path) };
+    }
+
+    /**
+     * Generate auto theme CSS by merging light and dark theme outputs.
+     * For the theming package (:root), adds color-scheme and toggle variables.
+     * For component packages (:host), just merges the variables.
+     */
+    const generateAutoThemes = async (processedCSS) => {
+        for (const { light, dark, auto } of AUTO_THEME_PAIRS) {
+            for (const [lightPath, lightCSS] of processedCSS) {
+                // Match paths containing the light theme folder
+                const lightPattern = new RegExp(`[/\\\\]${light}[/\\\\]`);
+                if (!lightPattern.test(lightPath)) continue;
+
+                const darkPath = lightPath.replace(lightPattern, (match) => match.replace(light, dark));
+                const darkCSS = processedCSS.get(darkPath);
+                if (!darkCSS) continue;
+
+                const selector = isThemingPackage(lightPath) ? ":root" : ":host";
+                let autoCSS = mergeLightDark(lightCSS, darkCSS, selector);
+
+                // For the theming package, add color-scheme and toggle setup
+                if (selector === ":root") {
+                    autoCSS = addAutoThemeSetup(autoCSS);
+                }
+
+                const autoPath = lightPath.replace(lightPattern, (match) => match.replace(light, auto));
+                await saveFiles(autoPath, autoCSS);
+            }
+        }
+    };
+
+    let scopingPlugin = {
+        name: 'scoping',
+        setup(build) {
+            build.initialOptions.write = false;
+
+            build.onEnd(async (result) => {
+                const processedCSS = new Map();
+
+                // Process all real theme files
+                await Promise.all(result.outputFiles.map(async f => {
+                    let { css } = isThemingPackage(f.path) ? await processThemingPackageFile(f) : await processComponentPackageFile(f);
+
+                    await saveFiles(f.path, css);
+                    processedCSS.set(f.path, css);
+                }));
+
+                // Generate auto themes by merging light + dark
+                await generateAutoThemes(processedCSS);
+            })
+        },
+    }
+
+    const config = {
+        entryPoints: inputFiles,
+        bundle: true,
+        minify: true,
+        outdir: 'dist/css',
+        outbase: 'src',
+        logLevel: process.env.UI5_VERBOSE === "true" ? "warning" : "error",
+        plugins: [
+            scopingPlugin,
+        ],
+        external: ["*.ttf", "*.woff", "*.woff2"],
+    };
+
+    if (restArgs.includes("-w")) {
+        let ctx = await esbuild.context(config);
+        console.log('watching...')
+        await ctx.watch()
+    } else {
+        await esbuild.build(config);
+    }
+}
+
+/**
+ * Adds auto theme setup CSS: color-scheme declaration and
+ * light/dark toggle variables with @media switching.
+ *
+ * In light mode (default):
+ *   --_ui5-light-scheme is guaranteed-invalid → var() fallbacks resolve to light values
+ *   --_ui5-dark-scheme is valid empty → var() fallbacks are NOT used
+ *
+ * In dark mode (@media prefers-color-scheme: dark):
+ *   --_ui5-light-scheme is valid empty → var() fallbacks are NOT used
+ *   --_ui5-dark-scheme is guaranteed-invalid → var() fallbacks resolve to dark values
+ *
+ * @param {string} mergedCSS - The merged :root CSS from mergeLightDark()
+ * @returns {string} CSS with toggle setup and @media rule appended
+ */
+const addAutoThemeSetup = (mergedCSS) => {
+    const root = postcss.parse(mergedCSS);
+
+    // Add color-scheme and toggle defaults to the :root rule
+    root.walkRules(":root", rule => {
+        rule.prepend(
+            postcss.decl({ prop: "--_ui5-dark-scheme", value: " " }),
+        );
+        rule.prepend(
+            postcss.decl({ prop: "--_ui5-light-scheme", value: "var(--_ui5-f2d95f8)" }),
+        );
+        rule.prepend(
+            postcss.decl({ prop: "color-scheme", value: "light dark" }),
+        );
+    });
+
+    // Add @media rule for dark mode - flips the toggles
+    const mediaRule = postcss.atRule({
+        name: "media",
+        params: "(prefers-color-scheme: dark)",
+    });
+    const darkRoot = postcss.rule({ selector: ":root" });
+    darkRoot.append(
+        postcss.decl({ prop: "--_ui5-light-scheme", value: " " }),
+        postcss.decl({ prop: "--_ui5-dark-scheme", value: "var(--_ui5-f2d95f8)" }),
+        postcss.decl({ prop: "color-scheme", value: "dark" }),
+    );
+    mediaRule.append(darkRoot);
+    root.append(mediaRule);
+
+    return root.toString();
+};
+
+const filePath = process.argv[1];
+
+if (filePath) {
+    const fileUrl = pathToFileURL(filePath).href;
+    if (import.meta.url === fileUrl) {
+        generate(process.argv)
+    }
+}
+
+export default {
+    _ui5mainFn: generate
+}

package/lib/css-processors/merge-light-dark.mjs

@@ -0,0 +1,131 @@
+import postcss from "postcss";
+
+/**
+ * Merges two CSS theme files (light and dark) into a single file using
+ * CSS light-dark() for color values and space toggles for non-color values.
+ *
+ * The space toggle pattern uses --_ui5-dark-scheme / --_ui5-light-scheme,
+ * following the same approach as the compact/cozy density toggles.
+ *
+ * @param {string} lightCSS - The light theme CSS string
+ * @param {string} darkCSS - The dark theme CSS string
+ * @param {string} selector - The selector to match (":root" for theming package, ":host" for component packages)
+ * @returns {string} Merged CSS string with light-dark() and space toggle values
+ */
+const mergeLightDark = (lightCSS, darkCSS, selector = ":root") => {
+	const lightRoot = postcss.parse(lightCSS);
+	const darkRoot = postcss.parse(darkCSS);
+
+	// Extract all custom property declarations from each theme
+	const lightVars = extractVars(lightRoot, selector);
+	const darkVars = extractVars(darkRoot, selector);
+
+	// Build merged declarations
+	const allProps = new Set([...lightVars.keys(), ...darkVars.keys()]);
+	const mergedRule = postcss.rule({ selector });
+
+	for (const prop of allProps) {
+		const lightVal = lightVars.get(prop);
+		const darkVal = darkVars.get(prop);
+
+		if (prop.startsWith("--sapThemeMetaData")) {
+			// Keep light version only for metadata
+			if (lightVal !== undefined) {
+				mergedRule.append(postcss.decl({ prop, value: lightVal }));
+			}
+			continue;
+		}
+
+		if (lightVal !== undefined && darkVal !== undefined) {
+			if (lightVal === darkVal) {
+				// Identical values - output once
+				mergedRule.append(postcss.decl({ prop, value: lightVal }));
+			} else if (isColorValue(lightVal) && isColorValue(darkVal)) {
+				// Different color values - use light-dark()
+				mergedRule.append(postcss.decl({ prop, value: `light-dark(${lightVal}, ${darkVal})` }));
+			} else {
+				// Different non-color values - use space toggle
+				mergedRule.append(postcss.decl({
+					prop,
+					value: `var(--_ui5-light-scheme, ${lightVal}) var(--_ui5-dark-scheme, ${darkVal})`,
+				}));
+			}
+		} else if (lightVal !== undefined) {
+			// Only in light theme - use space toggle with guaranteed-invalid for dark
+			mergedRule.append(postcss.decl({
+				prop,
+				value: `var(--_ui5-light-scheme, ${lightVal}) var(--_ui5-dark-scheme, var(--_ui5-f2d95f8))`,
+			}));
+		} else {
+			// Only in dark theme - use space toggle with guaranteed-invalid for light
+			mergedRule.append(postcss.decl({
+				prop,
+				value: `var(--_ui5-dark-scheme, ${darkVal}) var(--_ui5-light-scheme, var(--_ui5-f2d95f8))`,
+			}));
+		}
+	}
+
+	return mergedRule.toString();
+};
+
+/**
+ * Extract custom property declarations from a parsed CSS root for a given selector.
+ * @param {postcss.Root} root
+ * @param {string} selector
+ * @returns {Map<string, string>}
+ */
+const extractVars = (root, selector) => {
+	const vars = new Map();
+	root.walkRules(rule => {
+		if (rule.selector === selector) {
+			rule.walkDecls(decl => {
+				if (decl.prop.startsWith("--")) {
+					vars.set(decl.prop, decl.value);
+				}
+			});
+		}
+	});
+	return vars;
+};
+
+/**
+ * Heuristic to determine if a CSS value is a color value.
+ * light-dark() only works with <color> values.
+ */
+const isColorValue = (value) => {
+	const v = value.trim().toLowerCase();
+
+	// hex colors
+	if (/^#[0-9a-f]{3,8}$/.test(v)) return true;
+
+	// rgb/rgba/hsl/hsla functions
+	if (/^(rgba?|hsla?|oklch|oklab|lab|lch|color)\s*\(/.test(v)) return true;
+
+	// transparent and common CSS color keywords
+	if (v === "transparent" || v === "currentcolor") return true;
+
+	// Named CSS colors - check for common ones used in SAP themes
+	const namedColors = new Set([
+		"black", "white", "red", "green", "blue", "yellow", "orange", "purple",
+		"pink", "gray", "grey", "brown", "cyan", "magenta", "lime", "navy",
+		"teal", "aqua", "silver", "maroon", "olive", "fuchsia",
+	]);
+	if (namedColors.has(v)) return true;
+
+	// var() references to SAP color variables
+	// Match patterns like var(--sapXxxColor), var(--sapXxx_Background), etc.
+	if (/^var\(--sap\w*(Color|Background|BorderColor|TextColor|IconColor|ForegroundColor|HoverColor|ActiveColor|SelectedColor|Shadow)\w*\)$/.test(value.trim())) return true;
+
+	// Compound values containing color-related var() references
+	// e.g., "0.0625rem solid var(--sapContent_FocusColor)"
+	if (/var\(--sap\w*(Color|BorderColor|TextColor|IconColor|ForegroundColor|SelectedColor)\w*\)/.test(value)) {
+		// If the value also contains dimensional tokens, it's likely a shorthand (border, box-shadow)
+		// These are NOT pure color values - light-dark() won't work
+		if (/\d+(\.\d+)?(rem|px|em|%)/.test(value)) return false;
+		return true;
+	}
+
+	return false;
+};
+
+export { mergeLightDark, isColorValue };

package/lib/css-processors/postcss-plugin.mjs

@@ -0,0 +1,153 @@
+
+import postcss from "postcss";
+
+const hostVariables = new Map();
+
+const SELECTOR = ":host";
+
+const saveVariable = (variable, value, density) => {
+    if (!hostVariables.has(variable)) {
+        hostVariables.set(variable, {});
+    }
+    hostVariables.get(variable)[density] = value;
+}
+
+/**
+ * PostCSS plugin for handling CSS variables across density modes (cozy and compact).
+ *
+ * The plugin scans CSS for `:host` rules that define density-specific custom properties.
+ * Variables declared in a root-level `:host` rule are treated as **cozy** values, while
+ * variables declared inside `@container style(--ui5_content_density: compact)` `:host` rules
+ * are treated as **compact** values.
+ *
+ * All discovered variables are merged into a single root `:host` rule. For variables that
+ * exist in both modes, the plugin generates a value that uses CSS variable fallbacks to
+ * dynamically switch between compact and cozy values based on the active density.
+ *
+ * Variables that exist in only one mode are preserved, with appropriate fallbacks added
+ * when needed.
+ *
+ * Example input:
+ *
+ * ```css
+ * :host {
+ *   --my-variable: cozy-value;
+ *   --cozy-only-variable: cozy-only-value;
+ * }
+ *
+ * @container style(--ui5_content_density: compact) {
+ *   :host {
+ *     --my-variable: compact-value;
+ *     --compact-only-variable: compact-only;
+ *   }
+ * }
+ * ```
+ *
+ * Output:
+ *
+ * ```css
+ * :host {
+ *   --my-variable: var(--_ui5-compact-size, compact-value) var(--_ui5-cozy-size, cozy-value);
+ *   --compact-only-variable: var(--_ui5-compact-size, compact-only) var(--_ui5-cozy-size, initial);
+ *   --cozy-only-variable: cozy-only-value;
+ * }
+ * ```
+ *
+ * This enables seamless runtime switching between density modes using CSS variables alone.
+ */
+
+export default function postcssPlugin() {
+    return {
+        postcssPlugin: 'postcss-content-density-variables',
+        Once(root) {
+            let hasRootHost = false;
+            let hostRule;
+
+            root.walkRules((rule) => {
+                // Only process :host rules
+                if (rule.selector !== SELECTOR) {
+                    return;
+                }
+
+                // Handle root-level :host rules (cozy)
+                if (rule.parent.type === "root") {
+                    if (!hasRootHost) {
+                        hasRootHost = true;
+                        hostRule = rule;
+                    }
+
+                    rule.walkDecls((decl) => {
+                        if (decl.prop.startsWith('--')) {
+                            saveVariable(decl.prop, decl.value, 'cozy');
+                            decl.remove();
+                        }
+                    });
+                }
+
+                // Handle :host rules inside @container (compact)
+                if (rule.parent.type === "atrule") {
+                    if (rule.parent.params.replaceAll("\s", "") === 'style(--ui5_content_density: compact)'.replaceAll("\s", "")) {
+                        rule.walkDecls((decl) => {
+                            if (decl.prop.startsWith('--')) {
+                                saveVariable(decl.prop, decl.value, 'compact');
+                                decl.remove();
+                            }
+                        });
+                    }
+                }
+
+                let current = rule;
+                // Remove up empty rules
+                while (current) {
+                    if (current.nodes.length === 0) {
+                        const parent = current.parent;
+                        current.remove();
+                        current = parent;
+                    }
+
+                    if (current.type === "root") {
+                        break;
+                    }
+                }
+            });
+
+            if (!hasRootHost) {
+                hostRule = postcss.rule({ selector: SELECTOR });
+            }
+
+            // Construct merged variable declarations depending on available modes
+            for (const [variable, variableData] of hostVariables) {
+                if (variableData.cozy && variableData.compact) {
+                    hostRule.append({
+                        prop: variable,
+                        value: `var(--_ui5-compact-size, ${variableData.compact})  var(--_ui5-cozy-size, ${variableData.cozy})`,
+                    });
+                } else if (variableData.compact) {
+
+                    // Use a non-existent variable to always trigger the fallback.
+                    // Because this variable is never defined, the fallback is used
+                    // in all cases.
+
+                    // Using `initial` as a fallback can work only for properties
+                    // that treat it as an invalid value. To avoid this inconsistency,
+                    // we intentionally reference an undefined variable, which is
+                    // always considered invalid and undefined.
+                    hostRule.append({
+                        prop: variable,
+                        value: `var(--_ui5-compact-size, ${variableData.compact}) var(--_ui5-cozy-size, var(--_ui5-f2d95f8))`,
+                    });
+                } else {
+                    hostRule.append({
+                        prop: variable,
+                        value: variableData.cozy,
+                    });
+                }
+            }
+
+            root.prepend(hostRule);
+            hostVariables.clear();
+        }
+    }
+}
+
+postcssPlugin.postcss = true;

package/lib/css-processors/scope-variables.mjs

@@ -0,0 +1,74 @@
+import * as path from "path";
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+/**
+ * Tries to detect an override for a package
+ * @param {*} filePath For example: /my_project/src/themes/overrides/@ui5/webcomponents/my_custom_theme/parameters-bundle.css
+ * @returns
+ */
+const getOverrideVersion = filePath => {
+    if (!filePath) {
+        return;
+    }
+
+	if (!filePath.includes(`overrides${path.sep}`)) {
+		return; // The "overrides/" directory is the marker
+	}
+	const override = filePath.split(`overrides${path.sep}`)[1]; // For example, this will be: @ui5/webcomponents/my_custom_theme/parameters-bundle.css
+	if (!override) {
+		return; // There must be other directories after overrides/, the path can't end with it
+	}
+	const parts = override.split(path.sep);
+	if (parts.length < 3) {
+		return; // There must be at least a directory for the theme that is being overridden (my_custom_theme) and the name of the CSS file after the name of the package that is overridden
+	}
+	const packageName = parts.slice(0, -2).join(path.sep); // After the last 2 parts are removed (my_custom_theme and parameters-bundle.css from the example), the rest is the package
+
+	let overrideVersion;
+	try {
+		overrideVersion = require(`${packageName}${path.sep}package.json`).version;
+	} catch (e) {
+		if (process.env.UI5_VERBOSE === "true") {
+			console.log(`Error requiring package ${packageName}: ${e.message}`);
+		}
+	}
+
+	return overrideVersion;
+}
+
+/**
+ * `packageJSON` should reference the `package.json` of the base package,
+ * as it serves as the starting point for every runtime and carries a unique version.
+ * The `getScopedVarName` function is also defined in the base package
+ * and is consumed by all other packages.
+ *
+ * Runtime (2.19.0)
+ * - base (2.19.0)
+ * - At least one of the following packages: ai / main / fiori / compat (2.19.0)
+ * - Custom package (x.x.x)
+ *
+ * It is not possible to have a runtime with the main package at version 2.19.0
+ * and the base package at a different version (e.g., 2.18.0),
+ * because the main package depends on the base package.
+ * Such a mismatch would create a new runtime.
+ *
+ * Therefore, we can safely assume that the base package version
+ * matches the runtime version and can be reliably used for scoping.
+ *
+ * It is still needed for third-party packages that have not yet migrated to the
+ * component-level variable approach.
+ */
+
+const scopeVariables = (cssText, packageJSON, inputFile) => {
+    const escapeVersion = version => "v" + version?.replaceAll(/[^0-9A-Za-z\-_]/g, "-");
+    const versionStr = escapeVersion(getOverrideVersion(inputFile) || packageJSON.version);
+
+    const expr = /(--_?ui5)([^\,\:\)\s]+)/g;
+
+    return cssText.replaceAll(expr, `$1-${versionStr}$2`);
+}
+
+export default scopeVariables;
+

package/lib/css-processors/shared.mjs

@@ -0,0 +1,47 @@
+import { writeFile, readFile, mkdir } from "fs/promises";
+import * as path from "path";
+import assets from "../../assets-meta.js";
+
+const readOldContent = async (fileName) => {
+    // it seems slower to read the old content, but writing the same content with no real changes
+    // (as in initial build and then watch mode) will cause an unnecessary dev server refresh
+    let oldContent = "";
+    try {
+        oldContent = (await readFile(fileName)).toString();
+    } catch (e) {
+        // file not found
+    }
+    return oldContent;
+}
+
+const writeFileIfChanged = async (fileName, content) => {
+    const oldContent = await readOldContent(fileName);
+    if (content !== oldContent) {
+        if (!oldContent) {
+            await mkdir(path.dirname(fileName), { recursive: true });
+        }
+        return writeFile(fileName, content);
+    }
+}
+
+const DEFAULT_THEME = assets.themes.default;
+const CSS_VARIABLES_TARGET = process.env.CSS_VARIABLES_TARGET === "host";
+
+const getDefaultThemeCode = packageName => {
+    return `import { registerThemePropertiesLoader } from "@ui5/webcomponents-base/dist/asset-registries/Themes.js";
+
+import defaultThemeBase from "@ui5/webcomponents-theming/dist/generated/themes/${DEFAULT_THEME}/parameters-bundle.css.js";
+import defaultTheme from "./${DEFAULT_THEME}/parameters-bundle.css.js";
+
+registerThemePropertiesLoader("@" + "ui5" + "/" + "webcomponents-theming", "${DEFAULT_THEME}", async () => defaultThemeBase);
+registerThemePropertiesLoader(${packageName.split("").map(c => `"${c}"`).join(" + ")}, "${DEFAULT_THEME}", async () => defaultTheme${CSS_VARIABLES_TARGET ? ', "host"' : ''});
+`;
+};
+
+const getFileContent = (packageName, css, includeDefaultTheme) => {
+    const defaultTheme = includeDefaultTheme ? getDefaultThemeCode(packageName) : "";
+    return `${defaultTheme}export default ${css.trim()}`
+}
+
+
+export { writeFileIfChanged, getFileContent }

package/lib/dev-server/custom-hot-update-plugin.js

@@ -0,0 +1,39 @@
+const fs = require("fs");
+
+/**
+ * A change is observed on MacOS since 13.5, where the build generates a large amount
+ * of JSON file that spotlight search has to index, as they are considered new files.
+ *
+ * Starting the vitejs dev server reads all of these files and this triggers the indexing.
+ * The indexing has a side effect of changing some file metadata (can be checked with `mdls <path_to_file>`).
+ * This metadata change is changing the ctime of the file, but not the mtime. This can be checked with `stat -x <path_to_file>
+ *
+ * Essentially only metadata is changed, not content. This should not cause a page refresh,
+ * but chokidar reports this change and vite refreshes the page.
+ * The indexing is running with a 10 second interval, so for roughtly 20 minutes vite is refreshing the page every 10 seconds
+ *
+ * This plugin checks if the file causing the refresh is a generated json file (dist/*.json) and if ctime is changed after mtime
+ * In that case, returing an empty array tells vitejs that a custom update will be made by the plugin,
+ * which is in effect ignoring the page refresh.
+ */
+
+const customHotUpdate = async () => {
+	return {
+		name: 'custom-hot-update',
+		handleHotUpdate(ctx) {
+			// custom check for generated json files
+			if (ctx.file.endsWith(".json")) {
+				const stat = fs.statSync(ctx.file);
+
+				// metadata change only
+				if (stat.ctime > stat.mtime) {
+					// uncomment for debugging
+					// console.log("ignoring hot update for:", ctx.file);
+					return [];
+				}
+			}
+		}
+	}
+};
+
+module.exports = customHotUpdate;