feat(transform): fold static JSX past opaque spreads and styled() chains (#3699)

* fix(transform): rewrite JSX elements whose every spread is style-only

A spread the extractor already folded into the element's styles still
counted as a runtime spread, so an element like
`<styled.div {...baseStyle} css={x} />` bailed even though nothing dynamic
was left. Recognize the resolved identifier and member spreads and let the
element rewrite.

`StyleSpread::Open` now carries the span of the spread that produced it, so
a later pass can tell which source spread is opaque rather than only that
one is.

* feat(transform): fold the static half of an element with an opaque spread

`<styled.button {...props} type="button" css={x} />` bailed entirely because
of the spread, so every style source on it was resolved per render. The
factory and the spread now stay — style-prop splitting and DOM filtering
still happen for whatever the spread turns out to hold — while every style
Panda can see collapses into one className.

Requires a bare identifier spread, exactly one opaque spread, no style
source ahead of it, and no explicit className, so the precedence the
factory gives them is reproducible. The class read is optional-chained
because a nullish spread is a legal no-op in JSX.

* feat(transform): fold a same-file styled() chain to its host element

`const Button = styled('button', { base: … })` renders through forwardRef,
which costs a component level per instance even when the class never
changes. When the chain is base-only and rooted in an intrinsic tag, every
`<Button>` folds to `<button className="…">` and the definition is left for
the bundler to drop.

A tag folds only when it resolves to the symbol the chain declared, so a
local binding that shadows the module-level one is untouched — the same
check the imported-tag branch beside it already makes.

Variants, an options argument, a non-local base, `let`/`var`, or a
declaration inside a function all keep the runtime chain.

Author: segunadebayo

.changeset/jsx-partial-fold-opaque-spread.md

@@ -0,0 +1,6 @@
+---
+'@pandacss/compiler': patch
+---
+
+Precompute the static styles of a `styled.*` element that also spreads unknown props. The factory and the spread stay
+so runtime style props still work; everything Panda can see at build time collapses into one `className`.

.changeset/styled-chain-fold.md

@@ -0,0 +1,7 @@
+---
+'@pandacss/compiler': patch
+---
+
+Fold same-file `styled()` chains to their underlying element when the class string is constant, so
+`<Button>` no longer pays for a `forwardRef` component level at runtime. Chains with variants, an
+options argument, or a non-local base keep the existing runtime behaviour.

crates/pandacss_extractor/src/jsx.rs

@@ -4,7 +4,7 @@
 
 use crate::{
     CssSyntaxKind, Diagnostic, ExpressionFacts, ExtractorConfig, ImportSpecifierKind, JsxKind,
-    Literal, MatchCategory, MatchedImport, Matchers, Span, StyleTree, VisitorContext,
+    Literal, MatchCategory, MatchedImport, Matchers, Span, StyleObject, StyleTree, VisitorContext,
     css_template::css_template_to_style_tree,
     jsx_react_runtime,
     matcher::member_display,
@@ -13,6 +13,7 @@ use crate::{
     },
     span_from_oxc,
     style_tree::{jsx_attributes_to_style_tree, project_literal},
+    styled_bindings::{StyledBinding, StyledBindings, collect_styled_bindings},
 };
 use oxc_allocator::Allocator;
 use oxc_ast::ast::{
@@ -196,6 +197,7 @@ pub(crate) fn collect_jsx(
         out: &mut out,
         react_runtime,
         style_source_refs: None,
+        styled_bindings: collect_styled_bindings(program, ctx),
         retain_transform_facts,
     };
     extractor.visit_program(program);
@@ -214,6 +216,7 @@ pub(crate) fn collect_jsx_verbose(
         out: &mut out,
         react_runtime,
         style_source_refs: Some(&mut style_source_refs),
+        styled_bindings: collect_styled_bindings(program, ctx),
         retain_transform_facts: false,
     };
     extractor.visit_program(program);
@@ -287,6 +290,7 @@ pub(crate) struct Extractor<'walk, 'ctx, 'cb> {
     out: &'walk mut Vec<ExtractedJsx>,
     react_runtime: jsx_react_runtime::ReactRuntimeImports,
     style_source_refs: Option<&'walk mut Vec<StyleSourceRef>>,
+    styled_bindings: StyledBindings,
     pub(crate) retain_transform_facts: bool,
 }
 
@@ -298,6 +302,9 @@ pub(crate) struct ResolvedTag<'a> {
     /// `true` when resolved via a matched Panda import; `false` for the
     /// name-only `should_match_tag` fallback.
     pub(crate) panda_owned: bool,
+    /// Set when the tag is a local `styled()` chain the fold may collapse to
+    /// its host element.
+    pub(crate) styled: Option<&'a StyledBinding>,
 }
 
 impl Extractor<'_, '_, '_> {
@@ -329,10 +336,30 @@ impl Extractor<'_, '_, '_> {
                         alias: Cow::Borrowed(&matched.alias),
                         emit_empty: true,
                         panda_owned: true,
+                        styled: None,
                     });
                 }
 
                 let tag_name = id.name.as_str();
+                // A local `styled()` chain stands in for `<styled.{tag}>`, so the
+                // fold reaches it with the machinery host factories already use.
+                // Only when the tag resolves to the symbol we recorded — a local
+                // binding may shadow the module-level chain.
+                if let Some(binding) = self.styled_bindings.get(tag_name)
+                    && binding.symbol_id.is_some()
+                    && let Some(resolver) = self.ctx.resolver
+                    && resolver.symbol_for_identifier(id) == binding.symbol_id
+                {
+                    return Some(ResolvedTag {
+                        category: MatchCategory::Jsx,
+                        name: Cow::Owned(format!("styled.{}", binding.intrinsic)),
+                        alias: Cow::Borrowed(tag_name),
+                        emit_empty: true,
+                        panda_owned: true,
+                        styled: Some(binding),
+                    });
+                }
+
                 let is_configured_component = self.ctx.config.jsx.is_component_tag(tag_name);
                 if !is_configured_component
                     && !self
@@ -349,6 +376,7 @@ impl Extractor<'_, '_, '_> {
                     alias: Cow::Borrowed(tag_name),
                     emit_empty: is_configured_component,
                     panda_owned: false,
+                    styled: None,
                 })
             }
             JSXElementName::MemberExpression(member) => {
@@ -386,6 +414,7 @@ impl Extractor<'_, '_, '_> {
                     alias: Cow::Borrowed(root),
                     emit_empty: is_configured_component,
                     panda_owned: false,
+                    styled: None,
                 });
             }
             return None;
@@ -410,6 +439,7 @@ impl Extractor<'_, '_, '_> {
                         alias: Cow::Borrowed(&matched.alias),
                         emit_empty: true,
                         panda_owned: true,
+                        styled: None,
                     });
                 }
 
@@ -423,6 +453,7 @@ impl Extractor<'_, '_, '_> {
                     alias: Cow::Borrowed(&matched.alias),
                     emit_empty: true,
                     panda_owned: true,
+                    styled: None,
                 })
             }
             ImportSpecifierKind::Namespace => {
@@ -441,6 +472,7 @@ impl Extractor<'_, '_, '_> {
                     alias: Cow::Borrowed(&matched.alias),
                     emit_empty: true,
                     panda_owned: true,
+                    styled: None,
                 })
             }
             ImportSpecifierKind::Default => None,
@@ -484,6 +516,7 @@ impl Extractor<'_, '_, '_> {
                         alias: Cow::Borrowed(&matched.alias),
                         emit_empty: true,
                         panda_owned: true,
+                        styled: None,
                     });
                 }
 
@@ -504,6 +537,7 @@ impl Extractor<'_, '_, '_> {
                     alias: Cow::Borrowed(tag_name),
                     emit_empty: is_configured_component,
                     panda_owned: false,
+                    styled: None,
                 })
             }
             Expression::StringLiteral(s) => {
@@ -517,6 +551,7 @@ impl Extractor<'_, '_, '_> {
                     alias: Cow::Borrowed(tag_name),
                     emit_empty: true,
                     panda_owned: false,
+                    styled: None,
                 })
             }
             Expression::StaticMemberExpression(member) => {
@@ -547,12 +582,18 @@ impl<'a> Visit<'a> for Extractor<'_, '_, '_> {
             let emit_empty = resolved.emit_empty;
             let panda_owned = resolved.panda_owned;
 
+            let styled_base = resolved.styled.map(|binding| binding.base.clone());
+            let styled_intrinsic = resolved.styled.map(|binding| binding.intrinsic.clone());
             let style = jsx_attributes_to_style_tree(
                 &element.attributes,
                 self.ctx.resolver,
                 &self.ctx.config.jsx,
                 &tag_name,
             );
+            let style = match (styled_base, style) {
+                (Some(base), style) => prepend_styled_base(base, style),
+                (None, style) => style,
+            };
             let data = style
                 .as_ref()
                 .and_then(project_literal)
@@ -606,7 +647,8 @@ impl<'a> Visit<'a> for Extractor<'_, '_, '_> {
                 source: if retain {
                     JsxSourceFacts {
                         kind: JsxSourceKind::Element,
-                        factory_intrinsic: factory_intrinsic_from_jsx_name(&element.name),
+                        factory_intrinsic: styled_intrinsic
+                            .or_else(|| factory_intrinsic_from_jsx_name(&element.name)),
                         ..Default::default()
                     }
                 } else {
@@ -688,6 +730,26 @@ fn factory_intrinsic_from_jsx_name(name: &JSXElementName<'_>) -> Option<String>
     }
 }
 
+/// Puts a `styled()` chain's `base` underneath the element's own props, which
+/// is the precedence the runtime factory gives them. `None` when the element's
+/// styles are not a plain object, since only then is the ordering well defined.
+fn prepend_styled_base(
+    base: Vec<(String, StyleTree)>,
+    style: Option<StyleTree>,
+) -> Option<StyleTree> {
+    let own = match style {
+        None => StyleObject::default(),
+        Some(StyleTree::Object(object)) => object,
+        Some(_) => return None,
+    };
+    let mut entries = base;
+    entries.extend(own.entries);
+    Some(StyleTree::Object(StyleObject {
+        entries,
+        spreads: own.spreads,
+    }))
+}
+
 pub(crate) fn factory_intrinsic_from_expression(expression: &Expression<'_>) -> Option<String> {
     match expression.get_inner_expression() {
         Expression::StaticMemberExpression(member) => Some(member.property.name.to_string()),

crates/pandacss_extractor/src/lib.rs

@@ -29,6 +29,7 @@ mod scope;
 mod source;
 mod source_refs;
 mod style_tree;
+mod styled_bindings;
 mod svelte_adapter;
 mod template_styles;
 mod transform_facts;

crates/pandacss_extractor/src/style_tree.rs

@@ -78,8 +78,9 @@ pub enum StyleSpread {
         /// Keys overwritten by a later static entry.
         overridden: Vec<String>,
     },
-    /// Opaque object member or spread. Transform bails; encode skips it.
-    Open,
+    /// Opaque object member or spread. Encode skips it; transform needs the
+    /// span to tell which source spread it came from.
+    Open { span: Span },
     /// Dynamic `...(a || b)` or `...(a ?? b)` with a known fallback. Transform
     /// bails; encode merges the fallback.
     OpenWithFallback { fallback: StyleTree },
@@ -89,7 +90,7 @@ impl StyleSpread {
     /// True for rewrite-critical open spreads.
     #[must_use]
     pub const fn is_open(&self) -> bool {
-        matches!(self, Self::Open | Self::OpenWithFallback { .. })
+        matches!(self, Self::Open { .. } | Self::OpenWithFallback { .. })
     }
 }
 
@@ -181,7 +182,7 @@ fn project_object(obj: &StyleObject) -> Option<Literal> {
                     }
                 }
             }
-            StyleSpread::Open => {}
+            StyleSpread::Open { .. } => {}
         }
     }
 
@@ -196,7 +197,7 @@ fn project_object(obj: &StyleObject) -> Option<Literal> {
             .iter()
             .all(|(_, v)| project_literal(v).is_none())
             && obj.spreads.iter().all(|s| match s {
-                StyleSpread::Open => true,
+                StyleSpread::Open { .. } => true,
                 StyleSpread::Ternary {
                     consequent,
                     alternate,
@@ -415,11 +416,15 @@ fn object_to_style_tree(
         match prop {
             ObjectPropertyKind::ObjectProperty(prop) => {
                 if prop.method || prop.kind != PropertyKind::Init {
-                    spreads.push(StyleSpread::Open);
+                    spreads.push(StyleSpread::Open {
+                        span: span_from_oxc(prop.span),
+                    });
                     continue;
                 }
                 let Some(key) = property_key_to_string(&prop.key, prop.computed, resolver) else {
-                    spreads.push(StyleSpread::Open);
+                    spreads.push(StyleSpread::Open {
+                        span: span_from_oxc(prop.span),
+                    });
                     continue;
                 };
                 mark_spreads_overridden(&mut spreads, &key);
@@ -446,6 +451,8 @@ fn push_style_spread(
     argument: &Expression<'_>,
     resolver: Option<&Resolver<'_, '_>>,
 ) {
+    // Before `get_inner_expression`, so it lines up with `ExpressionFacts::span`.
+    let open_span = span_from_oxc(argument.span());
     let argument = argument.get_inner_expression();
     match argument {
         Expression::ConditionalExpression(c) => {
@@ -509,7 +516,7 @@ fn push_style_spread(
                         Some(fallback) => {
                             spreads.push(StyleSpread::OpenWithFallback { fallback });
                         }
-                        None => spreads.push(StyleSpread::Open),
+                        None => spreads.push(StyleSpread::Open { span: open_span }),
                     }
                 }
             }
@@ -522,7 +529,7 @@ fn push_style_spread(
                 }
                 spreads.extend(inner.spreads);
             }
-            Some(StyleTree::Open) | None => spreads.push(StyleSpread::Open),
+            Some(StyleTree::Open) | None => spreads.push(StyleSpread::Open { span: open_span }),
             Some(StyleTree::OpenWithFallback(inner)) => {
                 spreads.push(StyleSpread::OpenWithFallback { fallback: *inner });
             }
@@ -559,7 +566,7 @@ fn mark_spreads_overridden(spreads: &mut [StyleSpread], key: &str) {
             StyleSpread::Ternary { overridden, .. } | StyleSpread::And { overridden, .. } => {
                 overridden
             }
-            StyleSpread::Open | StyleSpread::OpenWithFallback { .. } => continue,
+            StyleSpread::Open { .. } | StyleSpread::OpenWithFallback { .. } => continue,
         };
         if !overridden.iter().any(|existing| existing == key) {
             overridden.push(key.to_owned());
@@ -694,7 +701,7 @@ fn filter_spread_props(spread: &mut StyleSpread, jsx: &crate::JsxExtractionConfi
         StyleSpread::And { value, .. } | StyleSpread::OpenWithFallback { fallback: value } => {
             filter_object_props(value, jsx, tag_name);
         }
-        StyleSpread::Open => {}
+        StyleSpread::Open { .. } => {}
     }
 }
 
@@ -743,7 +750,7 @@ fn filter_react_runtime_props_in_spread(spread: &mut StyleSpread) {
         StyleSpread::And { value, .. } | StyleSpread::OpenWithFallback { fallback: value } => {
             filter_react_runtime_props_in_tree(value);
         }
-        StyleSpread::Open => {}
+        StyleSpread::Open { .. } => {}
     }
 }