@stylix/core 6.1.1 → 6.3.0

package/dist/index.js

@@ -1,13 +1,69 @@
 import { jsx } from 'react/jsx-runtime';
-import React, { createContext, useLayoutEffect, useContext, useRef, useEffect } from 'react';
+import React, { createContext, useRef, useInsertionEffect, useContext, useEffect } from 'react';
 
-function classifyProps(props, knownProps) {
+function flattenRules(ctx) {
+    return Object.values(ctx.rules)
+        .flatMap((val) => (val && val.refs > 0 ? val.rules : []))
+        .filter(Boolean);
+}
+/**
+ * Applies rules from given StylixContext to the <style> element.
+ */
+function applyRules(ctx) {
+    if (ctx.styleCollector) {
+        const flattenedRules = flattenRules(ctx);
+        ctx.styleCollector.length = 0;
+        ctx.styleCollector.push(...flattenedRules);
+        return;
+    }
+    if (ctx.ssr)
+        return;
+    const supportsAdoptedStylesheets = 'adoptedStyleSheets' in document;
+    // If there's no style element, and we're in dev mode, create one
+    if (!ctx.styleElement && (ctx.devMode || !supportsAdoptedStylesheets)) {
+        ctx.styleElement = document.createElement('style');
+        ctx.styleElement.className = 'stylix';
+        if (ctx.id)
+            ctx.styleElement.id = `stylix-${ctx.id}`;
+        document.head.appendChild(ctx.styleElement);
+    }
+    if (ctx.styleElement) {
+        // If there's a style element, use it
+        const flattenedRules = flattenRules(ctx);
+        ctx.styleElement.innerHTML = flattenedRules.join('\n');
+    }
+    else {
+        // Still no stylesheet yet, create one
+        if (!ctx.stylesheet) {
+            ctx.stylesheet = new CSSStyleSheet();
+            if (supportsAdoptedStylesheets) {
+                document.adoptedStyleSheets.push(ctx.stylesheet);
+            }
+            else if (ctx.stylesheet.ownerNode) {
+                document.head.appendChild(ctx.stylesheet.ownerNode);
+            }
+        }
+        const stylesheet = ctx.stylesheet;
+        const flattenedRules = flattenRules(ctx);
+        if (stylesheet.replaceSync) {
+            try {
+                stylesheet.replaceSync(flattenedRules.join('\n'));
+            }
+            catch (e) {
+                // Errors are ignored, this just means that a browser doesn't support a certain CSS feature.
+                console.warn(e);
+            }
+        }
+    }
+}
+
+function classifyProps(props, knownStyleProps) {
     const styles = {};
     const other = {};
     for (const prop in props) {
         // If prop is not a valid JSX prop, it must be a CSS selector.
         // If prop has a style prop name and the value is likely a style value, it's a style prop.
-        if (!isValidJSXProp(prop) || isStyleProp(prop, knownProps)) {
+        if (!isValidJSXProp(prop) || isStyleProp(prop, knownStyleProps)) {
             styles[prop] = props[prop];
         }
         else {
@@ -20,10 +76,10 @@ function classifyProps(props, knownProps) {
  * Determines if `value` is a recognized CSS property (can be standard CSS or custom Stylix prop).
  * If it is, the simplified prop name is returned. Otherwise, false is returned.
  */
-function isStyleProp(prop, knownProps) {
+function isStyleProp(prop, knownStyleProps) {
     if (isValidJSXProp(prop)) {
         const simplified = simplifyStylePropName(prop);
-        return simplified in knownProps ? simplified : false;
+        return simplified in knownStyleProps ? simplified : false;
     }
     return false;
 }
@@ -572,37 +628,23 @@ const cleanStyles = {
  * // }
  * ```
  */
-function mapObject(source, map, context = {}) {
+function mapObject(source, mapFn, context) {
     if (typeof source !== 'object')
         return source;
-    const result = Array.isArray(source) ? [] : {};
+    const target = (Array.isArray(source) ? [] : {});
     for (const _key in source) {
         const key = Array.isArray(source) ? +_key : _key;
         const value = source[key];
         const contextClone = { ...context };
-        const mapResult = map(key, value, source, contextClone, (value) => mapObject(value, map, contextClone));
-        if (typeof mapResult === 'undefined')
-            continue;
-        if (Array.isArray(mapResult) && Array.isArray(source)) {
-            result.push(...mapResult);
-            continue;
-        }
-        if (typeof mapResult === 'object' &&
-            !Array.isArray(mapResult) &&
-            typeof source === 'object' &&
-            !Array.isArray(source)) {
-            Object.assign(result, mapResult);
-            continue;
-        }
-        throw new Error(`mapObjectRecursive: return value of map function must be an object, array, or undefined, and must match the type of the source value. Type of source value was ${typeof source}, and type of returned value was ${typeof mapResult}.`);
+        mapFn(key, value, target, contextClone, (value) => mapObject(value, mapFn, contextClone));
     }
-    return result;
+    return target;
 }
 
 const defaultIgnoreUnits = [
     'aspect-ratio',
-    'columns',
     'column-count',
+    'columns',
     'fill-opacity',
     'flex',
     'flex-grow',
@@ -610,15 +652,15 @@ const defaultIgnoreUnits = [
     'font-weight',
     'line-height',
     'opacity',
+    'order',
     'orphans',
     'stroke-opacity',
     'widows',
     'z-index',
     'zoom',
-    'order',
 ];
 /**
- * Adds unit (px, em, etc) to numeric values for any style properties not included in `ignoreProps`..
+ * Adds unit (px, em, etc) to numeric values for any style properties not included in `ignoreProps`.
  */
 const defaultUnits = (unit = 'px', ignoreProps = defaultIgnoreUnits) => {
     return {
@@ -629,11 +671,12 @@ const defaultUnits = (unit = 'px', ignoreProps = defaultIgnoreUnits) => {
         },
     };
 };
-const defaultUnitsMap = (key, value, _object, ctx, mapRecursive) => {
+const defaultUnitsMap = (key, value, target, ctx, mapRecursive) => {
     if (typeof value === 'number' && !ctx.ignoreProps.includes(key)) {
-        return { [key]: String(value) + ctx.unit };
+        target[key] = String(value) + ctx.unit;
+        return;
     }
-    return { [key]: mapRecursive(value) };
+    target[key] = mapRecursive(value);
 };
 const defaultPixelUnits = defaultUnits();
 
@@ -664,6 +707,36 @@ const hoistKeyframes = {
     },
 };
 
+function _hoistLayers(styles, root) {
+    for (const key in styles) {
+        const value = styles[key];
+        if (typeof value === 'string' && key.startsWith('@layer')) {
+            // Add layer rules as-is directly to root object
+            root['@layer'] ||= [];
+            root['@layer'].push(value.replace('@layer', '').trim());
+            if (styles !== root)
+                delete styles[key];
+        }
+        else if (isPlainObject(value)) {
+            // Recursively flatten nested styles
+            _hoistLayers(value, root);
+        }
+    }
+    return styles;
+}
+/**
+ * Hoists @layer declarations to root of styles object.
+ */
+const hoistLayers = {
+    name: 'hoistLayers',
+    type: 'processStyles',
+    plugin(_ctx, styles) {
+        if (styles && typeof styles === 'object' && !Array.isArray(styles))
+            styles['@layer'] = [];
+        return _hoistLayers(styles, styles);
+    },
+};
+
 /**
  * Expands media objects using the media definitions from the Stylix context.
  */
@@ -697,10 +770,21 @@ function processMediaStyles(mediaDef, styleProps, styles) {
             // An object for a style prop is definitely a media object
             for (const mediaKey in styleValue) {
                 result[mediaKey] ||= [];
-                result[mediaKey].push(mediaDef[mediaKey]({
-                    // process recursively
-                    [styleKey]: processMediaStyles(mediaDef, styleProps, styleValue[mediaKey]),
-                }));
+                // mediaKey corresponds to a media definition
+                if (mediaKey in mediaDef) {
+                    result[mediaKey].push(mediaDef[mediaKey]({
+                        // process recursively
+                        [styleKey]: processMediaStyles(mediaDef, styleProps, styleValue[mediaKey]),
+                    }));
+                }
+                // mediaKey does not correspond to a media definition, it must be a @media or @container rule
+                else {
+                    result[mediaKey].push({
+                        [mediaKey]: {
+                            [styleKey]: processMediaStyles(mediaDef, styleProps, styleValue[mediaKey]),
+                        },
+                    });
+                }
             }
             continue;
         }
@@ -724,76 +808,42 @@ function processMediaStyles(mediaDef, styleProps, styles) {
 const mergeArrays = {
     name: 'mergeArrays',
     type: 'processStyles',
-    plugin: (_ctx, styles) => _mergeArrays(styles),
+    plugin: (_ctx, styles) => reduceArrays(styles),
 };
-function _mergeArrays(obj) {
-    if (Array.isArray(obj))
-        return reduceArray(obj);
-    return reduceObjectProperties(obj);
+function reduceArrays(obj) {
+    return _reduceArrays(obj);
 }
-function reduceArray(arr) {
-    arr = arr.flat();
-    let target = arr[0];
-    if (Array.isArray(target)) {
-        target = reduceArray(target);
-    }
-    for (let i = 1; i < arr.length; i++) {
-        let source = arr[i];
-        if (Array.isArray(source)) {
-            source = reduceArray(source);
-        }
-        // ignore falsy values
-        if (typeof source === 'undefined')
-            continue;
-        // if both values are primitives, the source value takes precedence
-        if (typeof target !== 'object' && typeof source !== 'object') {
-            target = source;
-            continue;
-        }
-        // if target is primitive but source is object, replace target with source
-        if (typeof target !== 'object') {
-            target = source;
-            continue;
+function _reduceArrays(obj, target = {}) {
+    if (!obj || typeof obj !== 'object')
+        return obj;
+    if (Array.isArray(obj)) {
+        for (const item of obj) {
+            if (!item || typeof item !== 'object')
+                continue;
+            _reduceArrays(item, target);
         }
-        for (const key in source) {
-            const value = source[key];
-            // if the key does not exist in target, just add it
-            if (!(key in target))
-                target[key] = value;
-            // else, if the target value is an object or array:
-            else if (typeof target[key] === 'object') {
-                // if the source value is an object or array, convert target to array if necessary and push source value
-                if (typeof value === 'object') {
-                    if (!Array.isArray(target[key]))
-                        target[key] = [target[key]];
-                    target[key].push(value);
-                }
-                // else, ignore the source value (it's primitive; object values take precedence)
+        return target;
+    }
+    for (const key in obj) {
+        const value = obj[key];
+        // If target[key] is an object
+        if (target[key] && typeof target[key] === 'object') {
+            // If value is an object, merge them
+            if (value && typeof value === 'object') {
+                _reduceArrays(value, target[key]);
             }
-            // else, target value is primitive, overwrite target value
-            else {
+            // If value is not undefined, replace target[key]
+            else if (value !== undefined) {
                 target[key] = value;
             }
+            // otherwise do nothing, keep target[key] as is
+        }
+        // If target[key] is not an object, process normally
+        else {
+            target[key] = _reduceArrays(value, {});
         }
     }
-    return reduceObjectProperties(target);
-}
-const _reduced = Symbol('reduced');
-function reduceObjectProperties(obj) {
-    if (!obj || isEmpty(obj))
-        return undefined;
-    if (typeof obj !== 'object')
-        return obj;
-    if (obj?.[_reduced]) {
-        return obj;
-    }
-    for (const k in obj) {
-        if (!obj[k] || typeof obj[k] !== 'object')
-            continue;
-        obj[k] = _mergeArrays(obj[k]);
-    }
-    Object.defineProperty(obj, _reduced, { value: true, enumerable: false });
-    return obj;
+    return target;
 }
 
 /**
@@ -823,14 +873,17 @@ const propCasing = {
         return mapObject(styles, propCasingMap, { ctx });
     },
 };
-const propCasingMap = (key, value, _object, context, mapRecursive) => {
-    if (typeof key !== 'string' || key === '&')
-        return { [key]: mapRecursive(value) };
+const propCasingMap = (key, value, target, context, mapRecursive) => {
+    if (typeof key !== 'string' || key === '&') {
+        target[key] = mapRecursive(value);
+        return;
+    }
     const simpleKey = isStyleProp(key, context.ctx.styleProps);
     if (simpleKey) {
-        return { [context.ctx.styleProps[simpleKey]]: mapRecursive(value) };
+        target[context.ctx.styleProps[simpleKey]] = mapRecursive(value);
+        return;
     }
-    return { [key]: mapRecursive(value) };
+    target[key] = mapRecursive(value);
 };
 
 /**
@@ -843,35 +896,45 @@ const replace$$class = {
         return mapObject(styles, replace$$classMap, { ctx });
     },
 };
-const replace$$classMap = (key, value, _object, context, mapRecursive) => {
+const replace$$classMap = (key, value, target, context, mapRecursive) => {
     value =
         typeof value === 'string'
             ? value.replaceAll('$$class', context.ctx.className || '')
             : mapRecursive(value);
     key = typeof key === 'string' ? key.replaceAll('$$class', context.ctx.className || '') : key;
-    return { [key]: value };
+    target[key] = value;
 };
 
 function _customPropsProcess(styles, customProps) {
-    return mapObject(styles, (key, value, source, _ctx, mapRecursive) => {
-        if (!isValidJSXProp(key) || isPlainObject(value))
-            return Array.isArray(source) ? [mapRecursive(value)] : { [key]: mapRecursive(value) };
+    if (typeof styles !== 'object' || styles === null)
+        return styles;
+    return mapObject(styles, (key, value, target, _ctx, mapRecursive) => {
+        if (!isValidJSXProp(key) || isPlainObject(value)) {
+            target[key] = mapRecursive(value);
+            return;
+        }
         const simpleKey = simplifyStylePropName(key);
         const propValue = customProps[simpleKey];
-        if (!propValue)
-            return { [key]: mapRecursive(value) };
-        if (typeof propValue === 'object') {
-            if (value)
-                return mapRecursive(propValue);
-            return undefined;
+        if (propValue && typeof propValue === 'object') {
+            // For object, merge the mapped value into target if original prop value is truthy
+            if (value) {
+                const mappedValue = mapRecursive(propValue);
+                Object.assign(target, mappedValue);
+            }
         }
-        if (typeof propValue === 'string') {
-            return { [propValue]: mapRecursive(value) };
+        else if (typeof propValue === 'string') {
+            // For string, just remap the prop name
+            target[propValue] = mapRecursive(value);
         }
-        if (typeof propValue === 'function') {
-            return mapRecursive(propValue(value));
+        else if (typeof propValue === 'function') {
+            // For function, call it with the original value and merge the result
+            const mappedValue = mapRecursive(propValue(value));
+            Object.assign(target, mappedValue);
+        }
+        else {
+            // Unknown type, just keep original
+            target[key] = mapRecursive(value);
         }
-        return { [key]: mapRecursive(value) };
     });
 }
 const customProps = (customProps) => {
@@ -891,7 +954,7 @@ const customProps = (customProps) => {
         {
             name: 'customPropsProcess',
             type: 'processStyles',
-            before: mergeArrays,
+            before: 'mergeArrays',
             plugin(_ctx, styles) {
                 return _customPropsProcess(styles, customProps);
             },
@@ -923,6 +986,7 @@ const defaultPlugins = [
     mergeArrays,
     propCasing,
     hoistKeyframes,
+    hoistLayers,
     replace$$class,
     defaultPixelUnits,
     cleanStyles,
@@ -945,149 +1009,6 @@ function createStyleCollector() {
     return collector;
 }
 
-const detectSSR = () => !(typeof window !== 'undefined' && window.document?.head?.appendChild);
-function useIsoLayoutEffect(fn, deps, runOnSsr, isSsr = detectSSR()) {
-    if (isSsr) {
-        if (runOnSsr)
-            return fn();
-    }
-    else {
-        // biome-ignore lint/correctness/useHookAtTopLevel: isSsr should never change
-        // biome-ignore lint/correctness/useExhaustiveDependencies: dependencies are passed as-is
-        useLayoutEffect(fn, deps);
-    }
-}
-
-let defaultStyleProps;
-function createStylixContext(userValues = {}) {
-    if (!defaultStyleProps) {
-        defaultStyleProps = {};
-        for (const value of cssProps) {
-            defaultStyleProps[simplifyStylePropName(value)] = value;
-        }
-    }
-    const ctx = {
-        id: userValues.id || '$default',
-        devMode: !!userValues.devMode,
-        styleProps: defaultStyleProps,
-        media: userValues.media,
-        styleElement: userValues.styleElement,
-        plugins: defaultPlugins.flat(),
-        styleCounter: 0,
-        rules: {},
-        ssr: userValues.ssr ?? detectSSR(),
-        cleanupRequest: undefined,
-        requestApply: false,
-        classifyProps(props) {
-            const [styles, other] = classifyProps(props, this.styleProps);
-            return [styles, other];
-        },
-    };
-    if (userValues.plugins?.length) {
-        const flatPlugins = userValues.plugins.flat();
-        for (const i in flatPlugins) {
-            const plugin = flatPlugins[i];
-            let pluginIndex = -1;
-            if (plugin.before && ctx.plugins.includes(plugin.before))
-                pluginIndex = ctx.plugins.indexOf(plugin.before);
-            else if (plugin.after && ctx.plugins.includes(plugin.after))
-                pluginIndex = ctx.plugins.indexOf(plugin.after) + 1;
-            else if (plugin.atIndex !== undefined)
-                pluginIndex = plugin.atIndex;
-            if (pluginIndex === -1)
-                ctx.plugins.push(plugin);
-            else
-                ctx.plugins.splice(pluginIndex, 0, plugin);
-        }
-    }
-    applyPlugins('initialize', null, null, ctx);
-    return ctx;
-}
-// The React context object
-const stylixContext = createContext(undefined);
-let defaultStylixContext;
-/**
- * Gets the current Stylix context.
- */
-function useStylixContext() {
-    const ctx = useContext(stylixContext);
-    if (!ctx) {
-        if (!defaultStylixContext)
-            defaultStylixContext = createStylixContext();
-        return defaultStylixContext;
-    }
-    return ctx;
-}
-function StylixProvider({ id, devMode, plugins, media, styleElement, children, ssr, }) {
-    const ctx = useRef(null);
-    if (!ctx.current)
-        ctx.current = createStylixContext({ id, devMode, plugins, media, styleElement, ssr });
-    ctx.current.styleCollector = useContext(styleCollectorContext);
-    // When the component is unmounted, remove the style element, if any
-    useEffect(() => {
-        return () => {
-            ctx.current?.styleElement?.remove();
-        };
-    }, []);
-    return jsx(stylixContext.Provider, { value: ctx.current, children: children });
-}
-
-function flattenRules(ctx) {
-    return Object.values(ctx.rules)
-        .flatMap((val) => (val && val.refs > 0 ? val.rules : []))
-        .filter(Boolean);
-}
-/**
- * Applies rules from given StylixContext to the <style> element.
- */
-function applyRules(ctx) {
-    if (ctx.styleCollector) {
-        const flattenedRules = flattenRules(ctx);
-        ctx.styleCollector.length = 0;
-        ctx.styleCollector.push(...flattenedRules);
-        return;
-    }
-    if (ctx.ssr)
-        return;
-    const supportsAdoptedStylesheets = 'adoptedStyleSheets' in document;
-    // If there's no style element, and we're in dev mode, create one
-    if (!ctx.styleElement && (ctx.devMode || !supportsAdoptedStylesheets)) {
-        ctx.styleElement = document.createElement('style');
-        ctx.styleElement.className = 'stylix';
-        if (ctx.id)
-            ctx.styleElement.id = `stylix-${ctx.id}`;
-        document.head.appendChild(ctx.styleElement);
-    }
-    if (ctx.styleElement) {
-        // If there's a style element, use it
-        const flattenedRules = flattenRules(ctx);
-        ctx.styleElement.innerHTML = flattenedRules.join('\n');
-    }
-    else {
-        // Still no stylesheet yet, create one
-        if (!ctx.stylesheet) {
-            ctx.stylesheet = new CSSStyleSheet();
-            if (supportsAdoptedStylesheets) {
-                document.adoptedStyleSheets.push(ctx.stylesheet);
-            }
-            else if (ctx.stylesheet.ownerNode) {
-                document.head.appendChild(ctx.stylesheet.ownerNode);
-            }
-        }
-        const stylesheet = ctx.stylesheet;
-        const flattenedRules = flattenRules(ctx);
-        if (stylesheet.replaceSync) {
-            try {
-                stylesheet.replaceSync(flattenedRules.join('\n'));
-            }
-            catch (e) {
-                // Errors are ignored, this just means that a browser doesn't support a certain CSS feature.
-                console.warn(e);
-            }
-        }
-    }
-}
-
 function getParentComponentName() {
     const internals = React.__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED;
     const stack = internals?.ReactDebugCurrentFrame?.getStackAddendum?.()?.split('\n') || [];
@@ -1104,6 +1025,9 @@ function getParentComponentName() {
  * Serialize selector and styles to css rule string
  */
 function serialize(selector, styles) {
+    if (selector.startsWith('@') && Array.isArray(styles)) {
+        return `${selector} ${styles.join(', ')};`;
+    }
     const lines = [];
     for (const key in styles) {
         const value = styles[key];
@@ -1123,6 +1047,11 @@ function stylesToRuleArray(styles, className, context) {
     try {
         const processedStyles = applyPlugins('processStyles', styles, className, context);
         const result = [];
+        // Handle @layer rules first
+        if (processedStyles['@layer']) {
+            result.push(serialize('@layer', processedStyles['@layer']));
+            delete processedStyles['@layer'];
+        }
         for (const key in processedStyles) {
             const value = processedStyles[key];
             result.push(serialize(key, value));
@@ -1159,68 +1088,80 @@ function cleanup(ctx) {
         ctx.cleanupRequest = setTimeout(doCleanup, 100);
     }
 }
-/**
- * Accepts a Stylix CSS object and returns a unique className.
- * The styles are registered with the Stylix context and will be applied to the document.
- * If `global` is false, provided styles will be nested within the generated classname.
- * Returns the className if enabled, or an empty string.
- */
-function useStyles(styles, options = { global: false }) {
-    const stylixCtx = useStylixContext();
-    const prevStylesJson = useRef('');
-    // Preprocess styles with plugins
-    if (styles && !isEmpty(styles))
+function createStyles(config) {
+    const { stylixCtx, global } = config;
+    let styles = config.styles;
+    const priorKey = config.key || '';
+    let stylesKey = '';
+    if (styles && !isEmpty(styles)) {
+        // Preprocess styles with plugins
         styles = applyPlugins('preprocessStyles', styles, null, stylixCtx);
-    let stylesJson = styles && !isEmpty(styles) ? JSON.stringify(styles) : '';
-    if (stylesJson && options.global)
-        stylesJson = `global:${stylesJson}`;
-    const changed = stylesJson !== prevStylesJson.current;
-    prevStylesJson.current = stylesJson;
-    options.debugLabel ||= stylixCtx.devMode ? getParentComponentName() : '';
-    if (stylesJson && !stylixCtx.rules[stylesJson]) {
+        // Generate styles key
+        stylesKey = styles ? (global ? 'global:' : '') + JSON.stringify(styles) : '';
+    }
+    if (stylesKey && !stylixCtx.rules[stylesKey]) {
         stylixCtx.styleCounter++;
-        const className = `stylix-${(stylixCtx.styleCounter).toString(36)}${options.debugLabel ? `-${options.debugLabel}` : ''}`;
+        const debugLabel = config.debugLabel || (stylixCtx.devMode && getParentComponentName()) || '';
+        const className = `stylix-${(stylixCtx.styleCounter).toString(36)}${debugLabel ? `-${debugLabel}` : ''}`;
         // If not global styles, wrap original styles with classname
-        if (!options.global)
+        if (!global)
             styles = { [`.${className}`]: styles };
-        stylixCtx.rules[stylesJson] = {
+        stylixCtx.rules[stylesKey] = {
             className,
             rules: stylesToRuleArray(styles, className, stylixCtx),
             refs: 0,
         };
     }
-    if (changed)
+    const isChanged = stylesKey !== priorKey;
+    const ruleSet = stylesKey ? stylixCtx.rules[stylesKey] : null;
+    if (isChanged) {
+        // Mark styles to be applied
         stylixCtx.requestApply = true;
-    // When json changes, add/remove ref count
-    const ruleSet = stylixCtx.rules[stylesJson];
-    if (stylesJson && changed && ruleSet) {
-        ruleSet.refs++;
+        // When json changes, add/remove ref count
+        const priorRuleSet = priorKey ? stylixCtx.rules[priorKey] : null;
+        if (priorRuleSet)
+            priorRuleSet.refs--;
+        if (ruleSet)
+            ruleSet.refs++;
     }
+    return {
+        className: ruleSet?.className || '',
+        key: stylesKey,
+    };
+}
+/**
+ * Accepts a Stylix CSS object and returns a unique className.
+ * The styles are registered with the Stylix context and will be applied to the document.
+ * If `global` is false, provided styles will be nested within the generated classname.
+ * Returns the className if enabled, or an empty string.
+ */
+function useStyles(styles, options = { global: false }) {
+    const stylixCtx = useStylixContext();
+    const prevStylesKey = useRef('');
+    const s = createStyles({
+        stylixCtx,
+        styles,
+        global: options.global,
+        debugLabel: options.debugLabel,
+        key: prevStylesKey.current,
+    });
+    prevStylesKey.current = s.key;
     // Apply styles if requested.
-    // This runs on every render. We utilize useLayoutEffect so that it runs *after* all the other
+    // This runs on every render. We utilize useInsertionEffect so that it runs *after* all the other
     // renders have completed. stylixCtx.requestApply guards against multiple runs. This reduces the number of calls
     // to applyRules(), but prevents styles potentially being added to the DOM after other components force the
     // browser to compute styles.
-    useIsoLayoutEffect(() => {
+    // biome-ignore lint/correctness/useExhaustiveDependencies: stylixCtx is stable
+    useInsertionEffect(() => {
         if (!stylixCtx.requestApply)
             return;
         stylixCtx.requestApply = false;
         applyRules(stylixCtx);
-    }, undefined, true, stylixCtx.ssr);
-    useIsoLayoutEffect(() => {
-        if (!stylesJson || !changed)
-            return;
         return () => {
-            const ruleSet = stylixCtx.rules[stylesJson];
-            if (!ruleSet)
-                return;
-            ruleSet.refs--;
-            if (ruleSet.refs <= 0)
-                stylixCtx.rules[stylesJson] = undefined;
             cleanup(stylixCtx);
         };
-    }, [stylesJson], false, stylixCtx.ssr);
-    return stylixCtx.rules[stylesJson]?.className || '';
+    }, [s.key]);
+    return s.className;
 }
 function useKeyframes(keyframes) {
     return useStyles({ '@keyframes $$class': keyframes }, { global: true });
@@ -1229,6 +1170,115 @@ function useGlobalStyles(styles, options = { disabled: false }) {
     return useStyles(styles, { ...options, global: true });
 }
 
+const detectSSR = () => !(typeof window !== 'undefined' && window.document?.head?.appendChild);
+
+/**
+ * Default style props mapping. This will be populated on the first call to createStylixContext.
+ */
+let defaultStyleProps;
+function createStylixContext(userValues = {}) {
+    if (!defaultStyleProps) {
+        defaultStyleProps = {};
+        for (const value of cssProps) {
+            defaultStyleProps[simplifyStylePropName(value)] = value;
+        }
+    }
+    const ctx = {
+        id: userValues.id || '$default',
+        devMode: !!userValues.devMode,
+        styleProps: defaultStyleProps,
+        media: userValues.media,
+        styleElement: userValues.styleElement,
+        plugins: defaultPlugins.flat(),
+        styleCounter: 0,
+        rules: {},
+        ssr: userValues.ssr ?? detectSSR(),
+        cleanupRequest: undefined,
+        requestApply: false,
+        classifyProps(props) {
+            const [styles, other] = classifyProps(props, this.styleProps);
+            return [styles, other];
+        },
+        styles(styles, config) {
+            const s = createStyles({
+                stylixCtx: ctx,
+                styles,
+                global: config?.global || false,
+            });
+            applyRules(ctx);
+            return s.className;
+        },
+    };
+    if (userValues.plugins?.length) {
+        const flatPlugins = userValues.plugins.flat();
+        for (const i in flatPlugins) {
+            const plugin = flatPlugins[i];
+            let pluginIndex = -1;
+            if (plugin.before)
+                pluginIndex = ctx.plugins.findIndex((v) => v.name === plugin.before);
+            else if (plugin.after) {
+                pluginIndex = ctx.plugins.findIndex((v) => v.name === plugin.before);
+                if (pluginIndex !== -1)
+                    pluginIndex += 1;
+            }
+            else if (plugin.atIndex !== undefined)
+                pluginIndex = plugin.atIndex;
+            if (pluginIndex === -1)
+                ctx.plugins.push(plugin);
+            else
+                ctx.plugins.splice(pluginIndex, 0, plugin);
+        }
+    }
+    applyPlugins('initialize', null, null, ctx);
+    return ctx;
+}
+/**
+ * The React context object for Stylix.
+ */
+const stylixContext = createContext(undefined);
+/**
+ * Default Stylix context, used when no provider is present.
+ */
+let defaultStylixContext;
+/**
+ * React hook that gets the current Stylix context.
+ */
+function useStylixContext() {
+    const ctx = useContext(stylixContext);
+    if (!ctx) {
+        if (!defaultStylixContext)
+            defaultStylixContext = createStylixContext();
+        return defaultStylixContext;
+    }
+    return ctx;
+}
+/**
+ * StylixProvider component. Provides a Stylix context to its descendent elements.
+ * Can either accept an existing context via the `context` prop, or create a new context
+ * using the other configuration props.
+ */
+function StylixProvider(props) {
+    const { context, id, devMode, plugins, media, styleElement, children, ssr } = props;
+    const ctx = useRef(context);
+    if (!ctx.current)
+        ctx.current = createStylixContext({
+            id,
+            devMode,
+            plugins,
+            media,
+            styleElement,
+            ssr,
+        });
+    ctx.current.styleCollector = useContext(styleCollectorContext);
+    // When the component is unmounted, remove the style element, if any
+    useEffect(() => {
+        return () => {
+            ctx.current?.styleElement?.remove();
+        };
+    }, []);
+    return jsx(stylixContext.Provider, { value: ctx.current, children: children });
+}
+
 function _Stylix(props, ref) {
     const { $el, $render, $css, className: outerClassName, children, ...rest } = props;
     const ctx = useStylixContext();
@@ -1245,7 +1295,7 @@ function _Stylix(props, ref) {
     if (React.isValidElement($el)) {
         const $elProps = {
             ...$el.props,
-            ref,
+            ref: ('ref' in $el && $el.ref) || ref,
             /**
              * `allProps` must override `$el.props` because the latter may contain default prop values provided by defaultProps.
              * The expectation is that for <$ $el={<SomeComponent />} someComponentProp="my value" />,