feat: support cross-component sibling and no-pseudo ancestor selectors

Implement two previously unimplemented selector patterns:

- `${Link}:focus-visible + &` (cross-component sibling combinator)
  → stylex.when.siblingBefore(":focus-visible", LinkMarker)
- `${Other} &` (component as ancestor without pseudo)
  → stylex.when.ancestor(":is(*)", OtherMarker)

Both use defineMarker() for the referenced component, reusing the
existing siblingMarkerNames/siblingMarkerParents → crossFileMarkers
pipeline for sidecar generation and JSX marker injection.

Move _unimplemented.selector-componentDescendant (uses CSS class
selectors) to _unsupported and create new implementable test case.

https://claude.ai/code/session_01X1Gxfz4reNWtojK37AJpsT

Author: claude

src/internal/logger.ts

@@ -94,13 +94,15 @@ export type WarningType =
   | "Unsupported selector: unresolved interpolation in descendant component selector"
   | "Unsupported selector: unresolved interpolation in element selector"
   | "Unsupported selector: unresolved interpolation in reverse component selector"
+  | "Unsupported selector: unresolved interpolation in cross-component sibling selector"
   | "Unsupported selector: grouped reverse selector references different components"
   | "Unsupported selector: unknown component selector"
   | "Unsupported css`` mixin: after-base mixin style is not a plain object"
   | "Unsupported css`` mixin: nested contextual conditions in after-base mixin"
   | "Unsupported css`` mixin: cannot infer base default for after-base contextual override (base value is non-literal)"
   | "css`` helper function interpolation references closure variable that cannot be hoisted"
   | "Sibling selector broadened: & + & (adjacent) becomes general sibling (~) in StyleX — interleaved non-matching elements will no longer block the match"
+  | "Sibling selector broadened: + (adjacent) becomes general sibling (~) in StyleX — interleaved non-matching elements will no longer block the match"
   | "Using styled-components components as mixins is not supported; use css`` mixins or strings instead"
   | "styled(ImportedComponent) wraps a component whose file contains internal styled-components — convert the base component's file first to avoid CSS cascade conflicts"
   | "Transient $-prefixed props renamed on exported component — update consumer call sites to use the new prop names"

src/internal/lower-rules/process-rules.ts

@@ -265,7 +265,9 @@ export function processDeclRules(ctx: DeclProcessingState): void {
 
       // Component selector patterns that have special handling below:
       // 1. `${Other}:pseudo &` - ancestor pseudo via descendant combinator (space only)
+      // 1c: `${Other} &` - ancestor without pseudo (no-pseudo reverse)
       // 2. `&:pseudo ${Child}` or just `& ${Child}` - parent styling descendant child
+      // 3. `${Link}:pseudo + &` or `~ &` - cross-component sibling combinator
       // Other component selector patterns (like `${Other} .child`) should bail.
       const selectorTrimmed = selectorForAnalysis.trim();
       const isHandledComponentPattern =
@@ -274,10 +276,14 @@ export function processDeclRules(ctx: DeclProcessingState): void {
           // Pattern 1b: comma-separated reverse selectors where each part matches Pattern 1
           // e.g., `__SC_EXPR_0__:focus-visible &, __SC_EXPR_1__:active &`
           isCommaGroupedReverseSelectorPattern(selectorTrimmed) ||
+          // Pattern 1c: no-pseudo reverse: `${Other} &` (component as ancestor, no pseudo condition)
+          /^__SC_EXPR_\d+__\s+&\s*$/.test(selectorTrimmed) ||
           // Pattern 2: starts with & (forward descendant/pseudo pattern)
           selectorTrimmed.startsWith("&") ||
           // Pattern 3: standalone component selector `${Child} { ... }`
-          /^__SC_EXPR_\d+__\s*\{/.test(selectorTrimmed));
+          /^__SC_EXPR_\d+__\s*\{/.test(selectorTrimmed) ||
+          // Pattern 4: cross-component sibling: `${Link}:pseudo + &` or `~ &`
+          /^__SC_EXPR_\d+__:[a-z][a-z0-9()-]*\s*[+~]\s*&\s*$/.test(selectorTrimmed));
 
       // Use heuristic-based bail checks. We need to allow:
       // - Component selectors that have special handling
@@ -389,10 +395,17 @@ export function processDeclRules(ctx: DeclProcessingState): void {
         !isReverseSelectorPattern &&
         selTrim2.startsWith("__SC_EXPR_") &&
         isCommaGroupedReverseSelectorPattern(selTrim2);
+      // `${Other} &` — no pseudo, component as ancestor. Requires a scoped defineMarker()
+      // since defaultMarker() would match ANY ancestor, not just Other.
+      const isNoPseudoReversePattern =
+        !isReverseSelectorPattern &&
+        !isGroupedReverseSelectorPattern &&
+        selTrim2.startsWith("__SC_EXPR_") &&
+        /^__SC_EXPR_\d+__\s+&\s*$/.test(selTrim2);
       if (
         otherLocal &&
         !isCssHelperPlaceholder &&
-        (isReverseSelectorPattern || isGroupedReverseSelectorPattern)
+        (isReverseSelectorPattern || isGroupedReverseSelectorPattern || isNoPseudoReversePattern)
       ) {
         // For grouped selectors, verify ALL slot IDs resolve to the same component.
         // Without this guard, `${Link}:focus &, ${Button}:active &` would silently
@@ -432,8 +445,12 @@ export function processDeclRules(ctx: DeclProcessingState): void {
           break;
         }
 
-        // Extract all ancestor pseudos (one per comma-separated part)
-        const ancestorPseudos = extractReverseSelectorPseudos(rule.selector);
+        // Extract all ancestor pseudos (one per comma-separated part).
+        // For no-pseudo reverse (`${Other} &`), use `:is(*)` as synthetic always-matching
+        // pseudo so the style is conditional on the marker, not unconditional.
+        const ancestorPseudos = isNoPseudoReversePattern
+          ? [":is(*)"]
+          : extractReverseSelectorPseudos(rule.selector);
         if (ancestorPseudos.length === 0) {
           state.markBail();
           warnings.push({
@@ -453,8 +470,18 @@ export function processDeclRules(ctx: DeclProcessingState): void {
         const overrideStyleKey = `${toStyleKey(decl.localName)}In${jsxParentName}`;
         ancestorSelectorParents.add(parentStyleKey);
 
-        // For cross-file reverse, register a defineMarker for the imported parent
-        const reverseMarkerVarName = crossFileParent ? `${jsxParentName}Marker` : undefined;
+        // Register a defineMarker for the parent:
+        // - Cross-file reverse always needs a marker
+        // - No-pseudo reverse needs a scoped marker (defaultMarker() would be too broad)
+        const needsScopedMarker = isNoPseudoReversePattern || !!crossFileParent;
+        const reverseMarkerVarName = needsScopedMarker ? `${jsxParentName}Marker` : undefined;
+
+        // For no-pseudo reverse with same-file parent, register the marker through
+        // the sibling marker mechanism (feeds into crossFileMarkers → sidecar generation).
+        if (isNoPseudoReversePattern && !crossFileParent && reverseMarkerVarName) {
+          state.siblingMarkerNames.set(parentStyleKey, reverseMarkerVarName);
+          state.siblingMarkerParents.add(parentStyleKey);
+        }
 
         const overrideCountBeforeReverse = relationOverrides.length;
         // Process declarations once, then register into each pseudo bucket
@@ -476,6 +503,18 @@ export function processDeclRules(ctx: DeclProcessingState): void {
           jsxParentName,
         );
 
+        // For same-file no-pseudo reverse, set markerVarName on the override so
+        // finalizeRelationOverrides emits stylex.when.ancestor(":is(*)", Marker).
+        const lastOverride = relationOverrides.at(-1);
+        if (
+          isNoPseudoReversePattern &&
+          !crossFileParent &&
+          lastOverride &&
+          relationOverrides.length > overrideCountBeforeReverse
+        ) {
+          lastOverride.markerVarName = reverseMarkerVarName;
+        }
+
         const result = processDeclarationsIntoBucket(
           rule,
           firstBucket,
@@ -616,6 +655,85 @@ export function processDeclRules(ctx: DeclProcessingState): void {
         continue;
       }
 
+      // Cross-component sibling: `${Link}:focus-visible + &` or `${Link}:active ~ &`
+      // The declaring component reacts when the referenced component is its sibling.
+      // Uses stylex.when.siblingBefore(":pseudo", ReferencedMarker).
+      const crossComponentSiblingMatch = otherLocal
+        ? selTrim2.match(/^__SC_EXPR_\d+__:([a-z][a-z0-9()-]*)\s*([+~])\s*&\s*$/)
+        : null;
+      if (otherLocal && !isCssHelperPlaceholder && crossComponentSiblingMatch) {
+        const siblingPseudo = `:${crossComponentSiblingMatch[1]}`;
+        const combinator = crossComponentSiblingMatch[2] as "+" | "~";
+
+        const referencedDecl = declByLocalName.get(otherLocal);
+        const crossFileRef = !referencedDecl
+          ? state.crossFileSelectorsByLocal.get(otherLocal)
+          : undefined;
+        if (!referencedDecl && !crossFileRef) {
+          state.markBail();
+          warnings.push({
+            severity: "warning",
+            type: "Unsupported selector: unknown component selector",
+            loc: computeSelectorWarningLoc(decl.loc, decl.rawCss, rule.selector),
+          });
+          break;
+        }
+
+        // Emit info warning for `+` since adjacent becomes general sibling
+        if (combinator === "+") {
+          warnings.push({
+            severity: "info",
+            type: "Sibling selector broadened: + (adjacent) becomes general sibling (~) in StyleX — interleaved non-matching elements will no longer block the match",
+            loc: computeSelectorWarningLoc(decl.loc, decl.rawCss, rule.selector),
+          });
+        }
+
+        // Register marker for the referenced component
+        const jsxRefName = crossFileRef?.bridgeComponentLocalName ?? otherLocal;
+        const refStyleKey = referencedDecl ? referencedDecl.styleKey : toStyleKey(jsxRefName);
+        const refMarkerVarName = state.siblingMarkerNames.get(refStyleKey) ?? `${jsxRefName}Marker`;
+        state.siblingMarkerNames.set(refStyleKey, refMarkerVarName);
+        state.siblingMarkerParents.add(refStyleKey);
+        ancestorSelectorParents.add(refStyleKey);
+
+        // Process declarations into a temporary bucket
+        const sibBucket: Record<string, unknown> = {};
+        const sibResult = processDeclarationsIntoBucket(
+          rule,
+          sibBucket,
+          j,
+          decl,
+          resolveThemeValue,
+          resolveThemeValueFromFn,
+          { bailOnUnresolved: true },
+        );
+        if (sibResult === "bail") {
+          state.markBail();
+          warnings.push({
+            severity: "warning",
+            type: "Unsupported selector: unresolved interpolation in cross-component sibling selector",
+            loc: computeSelectorWarningLoc(decl.loc, decl.rawCss, rule.selector),
+          });
+          break;
+        }
+
+        // Build stylex.when.siblingBefore(':pseudo', Marker) per property
+        const makeSiblingKeyExpr = () =>
+          j.callExpression(
+            j.memberExpression(
+              j.memberExpression(j.identifier("stylex"), j.identifier("when")),
+              j.identifier("siblingBefore"),
+            ),
+            [j.literal(siblingPseudo), j.identifier(refMarkerVarName)],
+          );
+
+        for (const [prop, value] of Object.entries(sibBucket)) {
+          const entry = getOrCreateComputedMediaEntry(prop, ctx);
+          entry.entries.push({ keyExpr: makeSiblingKeyExpr(), value });
+        }
+        continue;
+      }
+
       // Selector interpolation that's a MemberExpression (e.g., screenSize.phone)
       // Try to resolve it via the adapter as a media query helper.
       if (!otherLocal && slotExpr && isMemberExpression(slotExpr)) {
@@ -644,7 +762,10 @@ export function processDeclRules(ctx: DeclProcessingState): void {
               // Store the resolved media expression for this rule
               const mediaExpr = parseExpr(selectorResult.expr);
               if (mediaExpr) {
-                resolvedSelectorMedia = { keyExpr: mediaExpr, exprSource: selectorResult.expr };
+                resolvedSelectorMedia = {
+                  keyExpr: mediaExpr,
+                  exprSource: selectorResult.expr,
+                };
                 // Add required imports
                 registerImports(selectorResult.imports, resolverImports);
                 resolved = true;
@@ -936,7 +1057,9 @@ export function processDeclRules(ctx: DeclProcessingState): void {
             (existingVal as Record<string, unknown>)[ps] = value;
           }
         } else {
-          const pseudoMap: Record<string, unknown> = { default: existingVal ?? null };
+          const pseudoMap: Record<string, unknown> = {
+            default: existingVal ?? null,
+          };
           for (const ps of pseudos) {
             pseudoMap[ps] = value;
           }
@@ -1075,7 +1198,9 @@ function processDeclarationsIntoBucket(
  * slot can't be resolved, or `null` if no slots are found.
  */
 function resolveAllSlots(
-  d: { value: { kind: string; parts?: Array<{ kind: string; slotId?: number }> } },
+  d: {
+    value: { kind: string; parts?: Array<{ kind: string; slotId?: number }> };
+  },
   decl: { templateExpressions: unknown[] },
   resolveThemeValue: (expr: unknown) => unknown,
   resolveThemeValueFromFn: (expr: unknown) => unknown,
@@ -1123,7 +1248,12 @@ function resolveAllSlots(
  */
 function buildInterpolatedValue(
   j: DeclProcessingState["state"]["j"],
-  d: { value: { kind: string; parts?: Array<{ kind: string; value?: string; slotId?: number }> } },
+  d: {
+    value: {
+      kind: string;
+      parts?: Array<{ kind: string; value?: string; slotId?: number }>;
+    };
+  },
   resolveSlot: (slotId: number) => unknown,
 ): unknown {
   const parts = d.value.parts ?? [];
@@ -1187,7 +1317,11 @@ function resolveElementSelectorTarget(
   root: DeclProcessingState["state"]["root"],
   j: JSCodeshift,
 ):
-  | { childDecl: StyledDecl; ancestorPseudo: string | null; childPseudo: string | null }
+  | {
+      childDecl: StyledDecl;
+      ancestorPseudo: string | null;
+      childPseudo: string | null;
+    }
   | ElementSelectorBailReason
   | null {
   const parsed = parseElementSelectorPattern(selector);
@@ -1651,7 +1785,11 @@ function tagCrossFileOverride(
 function recoverStandaloneInterpolationsInPseudoBlock(
   rule: DeclProcessingState["decl"]["rules"][number],
   decl: DeclProcessingState["decl"],
-): { when: string; propName: string; cssProps: Record<string, unknown> } | null {
+): {
+  when: string;
+  propName: string;
+  cssProps: Record<string, unknown>;
+} | null {
   const { rawCss, templateExpressions } = decl;
   if (!rawCss) {
     return null;

src/internal/lower-rules/relation-overrides.ts

@@ -36,7 +36,7 @@ export const finalizeRelationOverrides = (args: {
       o.childStyleKey,
       ...(o.childExtraStyleKeys ?? []),
     ]);
-    if (o.crossFile && o.markerVarName) {
+    if (o.markerVarName) {
       overrideToMarker.set(o.overrideStyleKey, o.markerVarName);
     }
   }

…d.selector-componentDescendant.input.tsx …d.selector-componentDescendant.input.tsxtest-cases/_unimplemented.selector-componentDescendant.input.tsx renamed to test-cases/_unsupported.selector-componentDescendant.input.tsx test-cases/_unimplemented.selector-componentDescendant.input.tsx renamed to test-cases/_unsupported.selector-componentDescendant.input.tsx

@@ -0,0 +1,3 @@
+import * as stylex from "@stylexjs/stylex";
+
+export const WrapperMarker = stylex.defineMarker();

test-cases/selector-componentDescendant.input.stylex.ts

@@ -0,0 +1,26 @@
+// Component used as ancestor selector without pseudo
+import styled from "styled-components";
+
+const Wrapper = styled.div`
+  padding: 16px;
+  background: papayawhip;
+`;
+
+const Child = styled.div`
+  color: gray;
+  padding: 8px;
+
+  ${Wrapper} & {
+    color: blue;
+    background: lavender;
+  }
+`;
+
+export const App = () => (
+  <div style={{ display: "flex", flexDirection: "column", gap: 16, padding: 16 }}>
+    <Child>Outside Wrapper (gray)</Child>
+    <Wrapper>
+      <Child>Inside Wrapper (blue, lavender)</Child>
+    </Wrapper>
+  </div>
+);

test-cases/selector-componentDescendant.input.tsx

@@ -0,0 +1,32 @@
+import * as stylex from "@stylexjs/stylex";
+import { WrapperMarker } from "./selector-componentDescendant.input.stylex";
+
+export const App = () => (
+  <div style={{ display: "flex", flexDirection: "column", gap: 16, padding: 16 }}>
+    <div sx={styles.child}>Outside Wrapper (gray)</div>
+    <div sx={[styles.wrapper, WrapperMarker]}>
+      <div sx={[styles.child, styles.childInWrapper]}>Inside Wrapper (blue, lavender)</div>
+    </div>
+  </div>
+);
+
+const styles = stylex.create({
+  wrapper: {
+    padding: 16,
+    backgroundColor: "papayawhip",
+  },
+  child: {
+    color: "gray",
+    padding: 8,
+  },
+  childInWrapper: {
+    color: {
+      default: "gray",
+      [stylex.when.ancestor(":is(*)", WrapperMarker)]: "blue",
+    },
+    backgroundColor: {
+      default: null,
+      [stylex.when.ancestor(":is(*)", WrapperMarker)]: "lavender",
+    },
+  },
+});

test-cases/selector-componentDescendant.output.tsx

@@ -0,0 +1,3 @@
+import * as stylex from "@stylexjs/stylex";
+
+export const LinkMarker = stylex.defineMarker();

test-cases/selector-componentSiblingCombinator.input.stylex.ts

@@ -1,4 +1,4 @@
-// @expected-warning: Unsupported selector: sibling combinator
+// Cross-component sibling combinator: ${Link}:focus-visible + &
 import styled from "styled-components";
 
 const Link = styled.a`

…tor-componentSiblingCombinator.input.tsx …tor-componentSiblingCombinator.input.tsxtest-cases/_unimplemented.selector-componentSiblingCombinator.input.tsx renamed to test-cases/selector-componentSiblingCombinator.input.tsx test-cases/_unimplemented.selector-componentSiblingCombinator.input.tsx renamed to test-cases/selector-componentSiblingCombinator.input.tsx

@@ -0,0 +1,30 @@
+import * as stylex from "@stylexjs/stylex";
+import { LinkMarker } from "./selector-componentSiblingCombinator.input.stylex";
+
+export const App = () => (
+  <div>
+    <a href="#" sx={[styles.link, LinkMarker]}>
+      Link
+    </a>
+    <span sx={styles.badge}>Badge (blue when Link is focused, adjacent sibling)</span>
+  </div>
+);
+
+const styles = stylex.create({
+  link: {
+    display: "flex",
+    padding: 8,
+    backgroundColor: "papayawhip",
+  },
+  // ${Link}:focus-visible + & uses a sibling combinator between the
+  // component and self. This is NOT an ancestor relationship, so
+  // stylex.when.ancestor() would produce incorrect semantics.
+  badge: {
+    paddingBlock: 4,
+    paddingInline: 8,
+    color: {
+      default: "gray",
+      [stylex.when.siblingBefore(":focus-visible", LinkMarker)]: "blue",
+    },
+  },
+});