@allxsmith/bestax-bulma 5.45.0 → 5.46.0

package/dist/esm/helpers/Theme.js

@@ -6,6 +6,7 @@ import { useBulmaClasses } from './useBulmaClasses.js';
 import { validRadii, validGaps } from './bulmaClassHelpers.js';
 import { warnOnce, isDev } from './devWarnings.js';
 import { useClassPrefix } from './Config.js';
+import { useClientLayoutEffect } from './useClientLayoutEffect.js';
 
 // --- Bulma v1 CSS variables Theme sets (originally generated from
 // CSSVAR_KEYS), in two lists by where Bulma declares them ---
@@ -60,6 +61,21 @@ const bulmaGlobalVars = [
     '--bulma-danger-h',
     '--bulma-danger-s',
     '--bulma-danger-l',
+    // the lightness of each color's label on a solid surface, and of its text
+    // on the page, which Bulma's Sass build picks for contrast with the color
+    // it was built with, so a new trio does not move them
+    '--bulma-primary-invert-l',
+    '--bulma-primary-on-scheme-l',
+    '--bulma-link-invert-l',
+    '--bulma-link-on-scheme-l',
+    '--bulma-info-invert-l',
+    '--bulma-info-on-scheme-l',
+    '--bulma-success-invert-l',
+    '--bulma-success-on-scheme-l',
+    '--bulma-warning-invert-l',
+    '--bulma-warning-on-scheme-l',
+    '--bulma-danger-invert-l',
+    '--bulma-danger-on-scheme-l',
     // shadow (the upstream token .box/.card/.dropdown/.panel derive their own
     // shadow variables from; overriding it from an ancestor is the route that
     // cascades, since those selectors re-declare their derived var on
@@ -810,6 +826,104 @@ const setRootThemeRules = (order, rules) => {
     }
     renderRootThemeRules();
 };
+/** A value given per scheme, rather than as one string. */
+const isSchemeValues = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * The selector of one of Bulma's schemes, as the stylesheet Theme is used
+ * with writes it: `[data-theme=dark], .theme-dark`, or with the class prefix
+ * in both names (`[data-bestax-theme=dark], .bestax-theme-dark`) for a
+ * prefixed build. A prefix that cannot be written into a selector as it
+ * stands gets the plain names, which `colorMode` writes under any prefix.
+ */
+const schemeSelector = (classPrefix, scheme) => {
+    const prefix = /^[A-Za-z_][\w-]*$/.test(classPrefix) ? classPrefix : '';
+    return `[data-${prefix}theme=${scheme}], .${prefix}theme-${scheme}`;
+};
+/**
+ * The `:root` rules for variables given a value per scheme, laid out the
+ * way Bulma lays out its own schemes so each value applies exactly where
+ * Bulma's would: under the visitor's OS preference, unless the page names
+ * the other scheme, and wherever the page names this one, on `<html>` or on
+ * an element inside. A scheme with no value gets no rules, which leaves the
+ * stylesheet's own value there.
+ *
+ * Every selector is as specific as `:root` (the guard is in `:where()`), so
+ * between Themes, and against a plain `:root` rule, the later one still
+ * wins, as it does for every other variable.
+ */
+const schemeRules = (vars, classPrefix) => {
+    const other = { light: 'dark', dark: 'light' };
+    const body = (scheme) => vars
+        .filter(([, values]) => values[scheme])
+        .map(([key, values]) => `${key}: ${values[scheme]};`)
+        .join(' ');
+    const schemes = ['light', 'dark']
+        .map(scheme => [scheme, body(scheme)])
+        .filter(([, declarations]) => declarations);
+    // Bulma's order: both preferences, then both names, the dark one last.
+    return [
+        ...schemes.map(([scheme, declarations]) => `@media (prefers-color-scheme: ${scheme}) { :root:where(:not(` +
+            `${schemeSelector(classPrefix, other[scheme])})) { ${declarations} } }`),
+        ...schemes.map(([scheme, declarations]) => `${schemeSelector(classPrefix, scheme)} { ${declarations} }`),
+    ];
+};
+const schemeAttributes = new Map();
+/** Set a theme attribute on `<html>`, or remove it for `null`. */
+const setSchemeAttribute = (name, value) => {
+    const root = document.documentElement;
+    if (value === null) {
+        root.removeAttribute(name);
+    }
+    else {
+        root.setAttribute(name, value);
+    }
+};
+/**
+ * Write one Theme's value for a theme attribute, `null` removing it, and
+ * make that Theme the attribute's latest writer. Throws, recording nothing,
+ * when `name` cannot be an attribute name.
+ *
+ * A Theme that writes the value it already holds keeps its place and leaves
+ * the page alone. React runs a layout effect again when a `Suspense`
+ * boundary shows its tree again, with nothing changed, and that must not
+ * take the attribute back from a Theme that wrote after it.
+ */
+const writeSchemeAttribute = (order, name, value) => {
+    const held = schemeAttributes.get(name);
+    if (held?.writers.some(writer => writer.order === order && writer.value === value)) {
+        return;
+    }
+    const entry = held ?? {
+        original: document.documentElement.getAttribute(name),
+        writers: [],
+    };
+    setSchemeAttribute(name, value);
+    entry.writers = entry.writers.filter(writer => writer.order !== order);
+    entry.writers.push({ order, value });
+    schemeAttributes.set(name, entry);
+};
+/**
+ * Take one Theme off every theme attribute it wrote, except those named in
+ * `keep`. An attribute it was the latest writer of goes back to the value of
+ * the writer before it, or to what it held before any of them.
+ */
+const releaseSchemeAttributes = (order, keep = []) => {
+    for (const [name, entry] of schemeAttributes) {
+        const index = entry.writers.findIndex(writer => writer.order === order);
+        if (index === -1 || keep.includes(name)) {
+            continue;
+        }
+        const latest = index === entry.writers.length - 1;
+        entry.writers.splice(index, 1);
+        if (entry.writers.length === 0) {
+            schemeAttributes.delete(name);
+            setSchemeAttribute(name, entry.original);
+        }
+        else if (latest) {
+            setSchemeAttribute(name, entry.writers[entry.writers.length - 1].value);
+        }
+    }
+};
 /**
  * Theme component that injects Bulma CSS variables either globally or locally.
  *
@@ -896,7 +1010,9 @@ const Theme = ({ bulmaVars = {}, children, className, isRoot = false, colorMode,
     });
     // Merge bulmaVars and individual props, with props taking precedence
     const mergedVars = useMemo(() => {
-        const vars = { ...bulmaVars };
+        const vars = {
+            ...bulmaVars,
+        };
         for (const [propName, cssVar] of Object.entries(bulmaVarPropMap)) {
             if (bulmaVarProps[propName] !== undefined) {
                 vars[cssVar] = bulmaVarProps[propName];
@@ -910,61 +1026,99 @@ const Theme = ({ bulmaVars = {}, children, className, isRoot = false, colorMode,
         }
         return vars;
     }, [bulmaVars, bulmaVarProps, radiusVar, columnGapVar]);
+    // The variables Theme writes, split by form: a value per scheme, or one
+    // value for every scheme. A key Theme does not take, or an empty value, is
+    // left out. A plain value is written as given, so a number untyped code
+    // passes still works.
+    const { plainVars, perSchemeVars } = useMemo(() => {
+        const plain = [];
+        const perScheme = [];
+        for (const [key, value] of Object.entries(mergedVars)) {
+            if (!value || !bulmaCssVars.includes(key)) {
+                continue;
+            }
+            if (isSchemeValues(value)) {
+                perScheme.push([key, value]);
+            }
+            else {
+                plain.push([key, value]);
+            }
+        }
+        return { plainVars: plain, perSchemeVars: perScheme };
+    }, [mergedVars]);
     // From an effect rather than the render body, so rendering does none of
     // this work, and a server render none at all. In production it returns
     // at its development check before looking at the variables.
     useEffect(() => {
         warnComponentVars(mergedVars);
     }, [mergedVars]);
-    // This Theme's place among root Themes; see `rootThemeRules`.
+    // A scoped Theme writes its variables as an inline style, which has no way
+    // to say which scheme a value is for, so it skips a value given per
+    // scheme. Say so, since nothing on the page does.
+    useEffect(() => {
+        if (isRoot || perSchemeVars.length === 0 || !isDev()) {
+            return;
+        }
+        const keys = perSchemeVars.map(([key]) => key).sort();
+        warnOnce(`Theme:scoped-scheme-values:${keys.join(',')}`, `[bestax-bulma] <Theme>: a scoped Theme writes its variables as an ` +
+            `inline style, which cannot hold a value per scheme, so ` +
+            `${keys.join(', ')} ${keys.length === 1 ? 'is' : 'are'} not set. ` +
+            'Give a single string, set the values on an isRoot Theme, or set ' +
+            'them in your CSS.');
+    }, [isRoot, perSchemeVars]);
+    // This Theme's place among the Themes on the page; see `rootThemeRules`
+    // and `schemeAttributes`.
     const [rootOrder] = useState(() => nextRootOrder++);
-    // The `:root` rules this Theme contributes, or '' when it contributes none.
+    // Bulma names its scheme attribute after the class prefix a stylesheet was
+    // built with (`data-<prefix>theme`), so the prefixed builds read
+    // `data-bestax-theme` and never `data-theme`. Its scheme classes take the
+    // prefix too (`.bestax-theme-dark`).
+    const classPrefix = useClassPrefix();
+    // The `:root` rules this Theme contributes, or '' when it contributes none:
+    // one block for the plain values, then the rules for each value given per
+    // scheme.
     const rootRules = useMemo(() => {
         if (!isRoot) {
             return '';
         }
-        const cssRules = Object.entries(mergedVars)
-            .filter(([key, value]) => bulmaCssVars.includes(key) && value)
-            .map(([key, value]) => `${key}: ${value};`)
-            .join(' ');
-        return cssRules ? `:root { ${cssRules} }` : '';
-    }, [mergedVars, isRoot]);
+        const plain = plainVars.map(([key, value]) => `${key}: ${value};`);
+        return [
+            ...(plain.length > 0 ? [`:root { ${plain.join(' ')} }`] : []),
+            ...schemeRules(perSchemeVars, classPrefix),
+        ].join('\n');
+    }, [plainVars, perSchemeVars, classPrefix, isRoot]);
     // Inject CSS variables globally at :root level, alongside any other root
     // Themes. Clearing `isRoot` or every variable passes '', which withdraws
-    // this Theme's rules.
-    useEffect(() => {
+    // this Theme's rules. A layout effect, so they are in place before the
+    // browser paints what this Theme rendered.
+    useClientLayoutEffect(() => {
         setRootThemeRules(rootOrder, rootRules);
     }, [rootOrder, rootRules]);
     // Withdraw them on unmount. Kept apart from the effect above so a change
     // rewrites the shared element in place rather than removing and recreating
-    // it between the cleanup and the next run.
+    // it between the cleanup and the next run, and passive, so a Theme that a
+    // `Suspense` fallback hides keeps its variables meanwhile: React cleans up
+    // a hidden tree's layout effects, but not its passive ones.
     useEffect(() => () => setRootThemeRules(rootOrder, ''), [rootOrder]);
-    // Bulma names its scheme attribute after the class prefix a stylesheet was
-    // built with (`data-<prefix>theme`), so the prefixed builds read
-    // `data-bestax-theme` and never `data-theme`.
-    const classPrefix = useClassPrefix();
     // Toggle Bulma's light/dark scheme by writing the theme attribute on the
     // document root (<html>). This is always global, even on a scoped Theme.
     // Under a class prefix the prefixed attribute is written as well as
     // `data-theme`, so whichever build is loaded sees it; with no prefix only
     // `data-theme` is. `'system'` removes them so Bulma follows the OS
-    // preference.
-    useEffect(() => {
-        if (colorMode === undefined) {
-            return;
-        }
-        const root = document.documentElement;
-        const names = classPrefix
-            ? ['data-theme', `data-${classPrefix}theme`]
-            : ['data-theme'];
-        const previous = names.map(name => root.getAttribute(name));
+    // preference. Written before the browser paints, and handed back on
+    // unmount, for the reasons the two effects above give; `schemeAttributes`
+    // keeps the two in step.
+    useClientLayoutEffect(() => {
+        const names = colorMode === undefined
+            ? []
+            : classPrefix
+                ? ['data-theme', `data-${classPrefix}theme`]
+                : ['data-theme'];
+        const value = colorMode === undefined || colorMode === 'system' ? null : colorMode;
+        releaseSchemeAttributes(rootOrder, names);
         for (const name of names) {
-            if (colorMode === 'system') {
-                root.removeAttribute(name);
-                continue;
-            }
             try {
-                root.setAttribute(name, colorMode);
+                writeSchemeAttribute(rootOrder, name, value);
             }
             catch {
                 // A class prefix can hold characters an attribute name cannot.
@@ -977,32 +1131,20 @@ const Theme = ({ bulmaVars = {}, children, className, isRoot = false, colorMode,
                     'with that prefix keeps its scheme.');
             }
         }
-        // Restore the previous values when colorMode changes or the component unmounts.
-        return () => {
-            names.forEach((name, i) => {
-                const value = previous[i];
-                if (value === null) {
-                    root.removeAttribute(name);
-                }
-                else {
-                    root.setAttribute(name, value);
-                }
-            });
-        };
-    }, [colorMode, classPrefix]);
+    }, [colorMode, classPrefix, rootOrder]);
+    // Hand the attributes back on unmount.
+    useEffect(() => () => releaseSchemeAttributes(rootOrder), [rootOrder]);
     // For local injection (when isRoot is false), prepare style object for CSS vars
     const style = useMemo(() => {
         if (isRoot) {
             return {};
         }
         const styleObj = {};
-        for (const [key, value] of Object.entries(mergedVars)) {
-            if (bulmaCssVars.includes(key) && value) {
-                styleObj[key] = value;
-            }
+        for (const [key, value] of plainVars) {
+            styleObj[key] = value;
         }
         return styleObj;
-    }, [mergedVars, isRoot]);
+    }, [plainVars, isRoot]);
     // Generate combined class names for the wrapper div
     const combinedClassName = useMemo(() => {
         if (isRoot) {